<?php

declare(strict_types=1);

namespace apexl\Io\modules\payment\Dto;

/**
 * Normalised webhook event, parsed + verified by a gateway adapter from
 * the raw HTTP request body.
 *
 * The `type` field uses a Hermes-side vocabulary (matching the outgoing
 * webhook events fan-out by Hermes — see Plan 005 §4h):
 *
 *   payment.succeeded
 *   payment.failed
 *   payment.refunded
 *   subscription.activated
 *   subscription.renewed
 *   subscription.past_due
 *   subscription.cancelled
 *   subscription.plan_changed
 *   payment_method.attached
 *   payment_method.detached
 *   checkout.completed
 *   checkout.expired
 *
 * Adapters MAP gateway-native event names to these — e.g. Stripe's
 * `invoice.payment_succeeded` → `payment.succeeded`. Unknown / irrelevant
 * gateway events MAY be skipped or emitted as `unknown` (consumer can
 * just ignore).
 */
final readonly class WebhookEvent
{
    /**
     * @param array<string, mixed> $payload    full parsed gateway payload (for debug / replay)
     * @param array<string, mixed> $references {gateway_payment_ref, gateway_subscription_ref, gateway_customer_ref, ...} subset relevant to this event
     */
    public function __construct(
        public string $gateway,           // 'stripe', 'paypal', ...
        public string $eventId,           // gateway's stable id — used for idempotency keys
        public string $type,              // normalised event type (see class doc)
        public int    $occurredAt,        // unix seconds
        public array  $payload,
        public array  $references = [],
        public ?string $idempotencyKey = null,
    ) {}
}
