/**
 * Stripe payment gateway adapter — payment-gateway-adapters (wave-10 leaf 5).
 *
 * Stripe (https://stripe.com/) global payment platform.
 * Generates a Stripe Payment Link for invoice collection.
 *
 * STUB — FAIL-CLOSED: not yet implemented. generatePaymentLink THROWS so no
 * route can serve a real-looking mock URL to a paying customer. Replace the
 * internals with the real Stripe API call (commented below) when credentials
 * are available; remove the throw only together with that implementation.
 * Spec contract (2026-05-31-payment-gateway-adapters.md §"only built gateways"):
 * a stub adapter must not be reachable in production — this throw enforces it.
 *
 * ACCEPTED-RISK (S9-i2-004): No inbound webhook verification or settlement path
 * exists while this adapter is a stub. Before production use, add signed webhook
 * routes, provider re-fetch confirmation, and idempotent recordInvoicePayment.
 *
 * Stripe API docs: https://stripe.com/docs/api/payment_links
 * Required config: secretKey (sk_live_... or sk_test_...)
 */

export interface StripeConfig {
  secretKey: string // Stripe secret key — NEVER log, NEVER store plaintext
}

export interface PaymentLinkResult {
  url: string
  expiresAt: string | null
}

/**
 * Create a Stripe Payment Link for an invoice.
 *
 * STUB — FAIL-CLOSED: throws until the real Stripe API call replaces it.
 */
export async function generatePaymentLink(
  config: StripeConfig,
  invoice: {
    id: string
    invoiceNumber: string | null
    amount: string
    currency: string
    customerName: string
    description?: string
  },
): Promise<PaymentLinkResult> {
  console.info('[stripe] Generating payment link (stub)', {
    invoiceId: invoice.id,
    invoiceNumber: invoice.invoiceNumber,
    amount: invoice.amount,
    currency: invoice.currency,
    // Never log secretKey
  })

  /*
   * Real Stripe API call (using Stripe SDK or raw fetch):
   *
   * // Step 1: create a price for this invoice
   * const priceRes = await fetch('https://api.stripe.com/v1/prices', {
   *   method: 'POST',
   *   headers: {
   *     'Authorization': `Bearer ${config.secretKey}`,
   *     'Content-Type': 'application/x-www-form-urlencoded',
   *   },
   *   body: new URLSearchParams({
   *     currency: invoice.currency.toLowerCase(),
   *     unit_amount: String(Math.round(parseFloat(invoice.amount) * 100)),
   *     'product_data[name]': invoice.description ?? `Invoice ${invoice.invoiceNumber ?? invoice.id}`,
   *   }),
   * })
   * const price = await priceRes.json()
   *
   * // Step 2: create the payment link
   * const linkRes = await fetch('https://api.stripe.com/v1/payment_links', {
   *   method: 'POST',
   *   headers: {
   *     'Authorization': `Bearer ${config.secretKey}`,
   *     'Content-Type': 'application/x-www-form-urlencoded',
   *   },
   *   body: new URLSearchParams({
   *     'line_items[0][price]': price.id,
   *     'line_items[0][quantity]': '1',
   *     'metadata[invoice_id]': invoice.id,
   *   }),
   * })
   * const link = await linkRes.json()
   * return { url: link.url, expiresAt: null }
   */

  // FAIL-CLOSED: the Stripe adapter is a stub with no real API call. Returning a
  // mock `buy.stripe.com/mock/...` URL would hand a paying customer a plausible
  // but fake payment link. Throw instead — both live routes (invoices/payment-link
  // and portal/invoices) wrap this in try/catch and surface a 502, never the mock.
  throw new Error(
    'Stripe payment gateway is not configured for production. ' +
      'No live Stripe integration is implemented; refusing to issue a mock payment link.',
  )
}