<?php

declare(strict_types=1);

namespace apexl\Io\modules\payment\Dto;

/**
 * Snapshot of a subscription's state at the gateway.
 *
 * Returned from create / cancel / change-plan / lookup. Consumers store
 * the ref + status + period dates on their local Subscription row;
 * webhooks update the same fields out-of-band.
 *
 * Status enum follows Stripe's vocabulary (most widely understood):
 *   trialing / active / past_due / cancelled / unpaid / incomplete.
 *
 * Some gateways don't expose every state — adapters map their native
 * states onto this enum + may leave some unused.
 */
final readonly class SubscriptionResult
{
    public function __construct(
        public string  $gatewaySubscriptionRef,
        public string  $status,
        public ?int    $currentPeriodStart = null,
        public ?int    $currentPeriodEnd   = null,
        public ?int    $trialEnd           = null,
        public bool    $cancelAtPeriodEnd  = false,
        public ?int    $cancelledAt        = null,
        public ?string $gatewayPlanRef     = null,
        public ?string $gatewayCustomerRef = null,
    ) {}

    public const string STATUS_TRIALING   = 'trialing';
    public const string STATUS_ACTIVE     = 'active';
    public const string STATUS_PAST_DUE   = 'past_due';
    public const string STATUS_CANCELLED  = 'cancelled';
    public const string STATUS_UNPAID     = 'unpaid';
    public const string STATUS_INCOMPLETE = 'incomplete';
}
