Domain Layer

interface PaymentGatewayInterface
{
    /**
     * Create or retrieve a customer in the payment provider.
     *
     * @return string The provider's customer ID
     */
    public function ensureCustomer(Tenant $tenant): string;

    /**
     * Create a checkout session for subscription signup.
     */
    public function createCheckoutSession(CreateCheckoutData $data): CheckoutSession;

    /**
     * Create a subscription in the provider.
     *
     * @return array<string, mixed> Provider subscription data
     */
    public function createSubscription(
        string $customerId,
        string $priceId,
        array $options = []
    ): array;

    /**
     * Cancel a subscription.
     *
     * @param bool $immediately If false, cancel at period end
     */
    public function cancelSubscription(
        string $subscriptionId,
        bool $immediately = false
    ): void;

    /**
     * Resume a subscription that was scheduled for cancellation.
     */
    public function resumeSubscription(string $subscriptionId): void;

    /**
     * Update subscription (change plan, quantity).
     *
     * @return array<string, mixed> Updated subscription data
     */
    public function updateSubscription(
        string $subscriptionId,
        array $params
    ): array;

    /**
     * Get the billing portal URL for self-service management.
     */
    public function getBillingPortalUrl(string $customerId, string $returnUrl): string;
}

interface InvitationNotifierInterface
{
    /**
     * Send an invitation notification to the invitee.
     */
    public function sendInvitation(Invitation $invitation, string $plainToken): void;
}

final readonly class CheckoutSession
{
    public function __construct(
        public string $sessionId,
        public string $url,
    ) {}
}

enum PricingType: string
{
    case Flat = 'flat';
    case Seat = 'seat';
    case Usage = 'usage';

    public function supportsQuantity(): bool
    {
        return $this === self::Seat;
    }

    public function requiresUsageData(): bool
    {
        return $this === self::Usage;
    }
}

enum SubscriptionStatus: string
{
    case Active = 'active';
    case Trialing = 'trialing';
    case PastDue = 'past_due';
    case Canceled = 'canceled';
    case Unpaid = 'unpaid';
    case Paused = 'paused';
    case Incomplete = 'incomplete';
    case IncompleteExpired = 'incomplete_expired';

    public function isActive(): bool
    {
        return in_array($this, [self::Active, self::Trialing], true);
    }

    public function canUpgrade(): bool
    {
        return in_array($this, [self::Active, self::Trialing, self::PastDue], true);
    }

    public function canCancel(): bool
    {
        return in_array($this, [self::Active, self::Trialing, self::PastDue], true);
    }
}

final readonly class Money implements \JsonSerializable
{
    private function __construct(
        public int $amount,
        public string $currency,
    ) {}

    // Factory methods
    public static function cents(int $amount, string $currency): self
    {
        return new self($amount, strtoupper($currency));
    }

    public static function zero(string $currency): self
    {
        return new self(0, strtoupper($currency));
    }

    public static function fromMajor(float $amount, string $currency): self
    {
        $minorUnits = CurrencyRegistry::minorUnits($currency);
        $cents = (int) round($amount * (10 ** $minorUnits));
        return new self($cents, strtoupper($currency));
    }

    // Arithmetic with currency guards
    public function add(Money $other): self
    {
        $this->assertSameCurrency($other);
        return new self($this->amount + $other->amount, $this->currency);
    }

    public function subtract(Money $other): self
    {
        $this->assertSameCurrency($other);
        return new self($this->amount - $other->amount, $this->currency);
    }

    public function multiply(int|float $factor): self
    {
        return new self((int) round($this->amount * $factor), $this->currency);
    }

    // Comparison and formatting methods omitted for brevity

    // Serialization (CONTRACTS.md §1.4)
    public function jsonSerialize(): array
    {
        return [
            'amount' => $this->amount,
            'currency' => $this->currency,
        ];
    }

    private function assertSameCurrency(Money $other): void
    {
        if ($this->currency !== $other->currency) {
            throw CurrencyMismatchException::forOperation(
                $this->currency,
                $other->currency
            );
        }
    }
}

final readonly class BillingInterval
{
    public function __construct(
        public IntervalUnit $unit,
        public int $count,
    ) {
        if ($count < 1) {
            throw new InvalidArgumentException('Interval count must be at least 1');
        }
    }

    public function toArray(): array
    {
        return [
            'unit' => $this->unit->value,
            'count' => $this->count,
        ];
    }
}

final readonly class CanAccessFeature
{
    /**
     * Check if access to a feature is allowed.
     *
     * @param EntitlementType $type   The type of entitlement (boolean or quota)
     * @param int|null        $value  The quota limit (null = unlimited)
     * @param int|null        $currentUsage  Current usage count
     */
    public function __invoke(
        EntitlementType $type,
        ?int $value,
        ?int $currentUsage
    ): bool {
        return match ($type) {
            EntitlementType::Boolean => true,
            EntitlementType::Quota => $this->checkQuota($value, $currentUsage),
        };
    }

    private function checkQuota(?int $limit, ?int $usage): bool
    {
        if ($limit === null) {
            return true; // Unlimited
        }
        return ($usage ?? 0) < $limit;
    }
}

final class BillingModeResolver
{
    /**
     * Get the current billing mode from configuration.
     */
    public function current(): BillingMode
    {
        $configuredMode = config('billing.mode');

        if ($configuredMode === null) {
            return BillingMode::default();
        }

        $mode = BillingMode::tryFrom($configuredMode);

        return $mode ?? BillingMode::default();
    }

    /**
     * Get the current billing mode, throwing if unsupported.
     *
     * @throws UnsupportedBillingModeException
     */
    public function currentOrFail(): BillingMode
    {
        $mode = $this->current();

        if (! $mode->isSupported()) {
            throw UnsupportedBillingModeException::forMode($mode);
        }

        return $mode;
    }

    public function isPlatformManaged(): bool
    {
        return $this->current()->isPlatformManaged();
    }
}

final class AlreadySubscribedException extends \DomainException
{
    public function __construct(
        public readonly string $tenantId,
        public readonly string $planId,
        string $message = '',
    ) {
        parent::__construct($message ?: 'Tenant is already subscribed to this plan');
    }

    public static function forPlan(string $tenantId, string $planId): self
    {
        return new self(
            $tenantId,
            $planId,
            "Tenant {$tenantId} is already subscribed to plan {$planId}"
        );
    }
}