<?php

declare(strict_types=1);

namespace apexl\Io\modules\payment\Dto;

/**
 * Input to {@see \apexl\Io\modules\payment\Contract\SubscriptionGatewayInterface::createSubscription()}.
 *
 * For direct (non-hosted-checkout) subscription creation. Consumers
 * normally drive subscription creation via the hosted-checkout flow
 * (passing `mode = subscription`), which returns a SubscriptionResult
 * directly — this direct API is for vendor-admin "add subscription
 * manually" flows + migrations from external billing systems.
 */
final readonly class SubscriptionRequest
{
    /**
     * @param array<string, scalar|null> $metadata
     */
    public function __construct(
        public string $gatewayCustomerRef,
        public string $gatewayPlanRef,
        public ?string $gatewayPaymentMethodRef = null,
        public ?int    $trialEnd = null,
        public array   $metadata = [],
        public ?string $idempotencyKey = null,
    ) {}
}
