// Provider-agnostic contract — see the approved payment plan
// (spicy-leaping-pizza.md §0/§7). Stripe is the only real implementation
// today (stripeProvider.ts); mockProvider.ts implements the same shape
// for PAYMENT_TEST_MODE so the checkout route never branches on which
// provider is active, only on whether one is configured at all.

export type CreatePaymentIntentInput = {
  amountCents: number;
  currency: string;
  customerEmail: string;
  description: string;
};

export type CreatePaymentIntentResult = {
  clientSecret: string;
  providerReference: string;
};

export type ProviderPaymentUpdate = {
  providerReference: string;
  paymentStatus: "paid" | "failed";
  paidAt: string;
};

export interface PaymentProvider {
  createPaymentIntent(input: CreatePaymentIntentInput): Promise<CreatePaymentIntentResult>;
  // Best-effort, awaited but never fatal to checkout — lets the webhook
  // handler resolve providerReference -> order without the frontend
  // having to persist a second field via an update path that doesn't
  // otherwise exist (see stripeProvider.ts's own comment).
  attachOrderMetadata(providerReference: string, metadata: { orderId: string; orderNumber: string }): Promise<void>;
}
