<?php

declare(strict_types=1);

namespace apexl\Io\modules\payment\Contract;

use apexl\Io\modules\payment\Dto\CheckoutSessionRequest;
use apexl\Io\modules\payment\Dto\CheckoutSessionResult;

/**
 * Gateway supports hosted-checkout sessions — consumer redirects shopper
 * to a vendor-or-gateway-hosted URL, shopper completes payment, gateway
 * redirects back with outcome.
 *
 * Used by:
 *   - Hermes's middleman gateway flow (CheckoutSession entity)
 *   - WC plugin's `process_payment()` redirect path
 *   - SaaS apps that don't want to embed card forms themselves
 */
interface HostedCheckoutInterface
{
    /**
     * Create a hosted-checkout session.
     *
     * Returns a result containing the gateway's session ref + the hosted URL
     * to redirect the shopper to. The consumer stores the session ref +
     * waits for the gateway's webhook to confirm payment (or polls the
     * gateway via `lookupCheckoutSession`).
     */
    public function createCheckoutSession(CheckoutSessionRequest $request): CheckoutSessionResult;

    /**
     * Look up an existing session by the gateway's session ref. Used post-
     * redirect to confirm outcome if the webhook is delayed.
     */
    public function lookupCheckoutSession(string $gatewaySessionRef): CheckoutSessionResult;
}
