<?php

declare(strict_types=1);

namespace apexl\Io\modules\payment\Dto;

/**
 * Input to {@see \apexl\Io\modules\payment\Contract\HostedCheckoutInterface::createCheckoutSession()}.
 *
 * The consumer (Hermes / WC plugin / SaaS app) supplies the business
 * details — what's being sold, for how much, on whose behalf, and where
 * to send the shopper afterwards. The adapter translates this into the
 * gateway's native shape.
 *
 * Mode discriminates:
 *   - 'one_off'      → single charge (line items + amounts directly)
 *   - 'subscription' → recurring (plan ref + future-charge auth)
 */
final readonly class CheckoutSessionRequest
{
    /**
     * @param array<int, array{name: string, amount_cents: int, quantity?: int, description?: string}> $lineItems
     * @param array<string, scalar|null> $metadata        opaque dict round-tripped via webhooks back to consumer
     */
    public function __construct(
        public string $mode,
        public string $currency,
        public string $successUrl,
        public string $cancelUrl,
        public ?string $customerEmail = null,
        public ?string $gatewayCustomerRef = null,
        public ?string $gatewayPlanRef = null,
        public array  $lineItems = [],
        public array  $metadata = [],
        public ?string $idempotencyKey = null,
        public ?int   $trialDays = null,
    ) {}

    public const string MODE_ONE_OFF      = 'one_off';
    public const string MODE_SUBSCRIPTION = 'subscription';
}
