@shware/purchase 7.1.0 → 7.3.0

package/dist/stripe/mapper.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"mapper.cjs","names":["stripeMinorUnits","CANCELLATION_FEEDBACKS"],"sources":["../../src/stripe/mapper.ts"],"sourcesContent":["import { stripeMinorUnits } from '@shware/utils';\nimport type { Stripe } from 'stripe';\nimport {\n  CANCELLATION_FEEDBACKS,\n  type CancellationDetails,\n  type CancellationFeedback,\n  type SubscriptionStatus,\n} from '../subscription/index';\n\nexport function mapTime<T extends number | null>(\n  stripeTimestampSeconds: T\n): T extends number ? string : null {\n  if (!stripeTimestampSeconds) return null as T extends number ? string : null;\n  return new Date(stripeTimestampSeconds * 1000).toISOString() as T extends number ? string : null;\n}\n\nexport type Price = {\n  id: string;\n  type: Stripe.Price.Type;\n  active: boolean;\n  billing_scheme: Stripe.Price.BillingScheme;\n  currency: Stripe.Price['currency'];\n  unit_amount: number | null;\n  unit_amount_decimal: string | null;\n  recurring: Stripe.Price.Recurring | null;\n};\n\nexport function mapPrice(price: Stripe.Price): Price {\n  return {\n    id: price.id,\n    type: price.type,\n    active: price.active,\n    billing_scheme: price.billing_scheme,\n    currency: price.currency,\n    unit_amount: price.unit_amount,\n    unit_amount_decimal: price.unit_amount_decimal?.toString() ?? null,\n    recurring: price.recurring,\n  };\n}\n\nexport interface LineItem {\n  id: string;\n  currency: string;\n  quantity: number | null;\n  description: string | null;\n  amount_tax: number;\n  amount_total: number;\n  amount_subtotal: number;\n  amount_discount: number;\n  price: Price | null;\n}\n\nexport function mapLineItem(item: Stripe.LineItem): LineItem {\n  return {\n    id: item.price\n      ? typeof item.price.product === 'string'\n        ? item.price.product\n        : item.price.product.id\n      : item.id,\n    currency: item.currency,\n    quantity: item.quantity,\n    description: item.description,\n    amount_tax: item.amount_tax,\n    amount_total: item.amount_total,\n    amount_subtotal: item.amount_subtotal,\n    amount_discount: item.amount_discount,\n    price: item.price ? mapPrice(item.price) : null,\n  };\n}\n\n// Re-exported under our own name so consumers need not reach into stripe's namespace.\n// Open-ended since stripe 22.4: a status the API adds later is not a type error.\nexport type PaymentStatus = Stripe.Checkout.Session.PaymentStatus;\n\n// Declared rather than inferred from mapCheckoutSession: an inferred shape is\n// structural, so a consumer's declaration emit has to spell out payment_status\n// through stripe's internal module path — TS2883 in any package that reaches\n// stripe transitively instead of depending on it (see line_items/price too).\nexport interface CheckoutSession {\n  id: string;\n  url: string | null;\n  coupon: string | undefined;\n  livemode: boolean;\n  expires_at: number;\n  payment_status: PaymentStatus;\n  currency: string | null;\n  amount_total: number | null;\n  line_items: LineItem[] | undefined;\n}\n\nexport function mapCheckoutSession(session: Stripe.Checkout.Session): CheckoutSession {\n  let coupon: string | undefined = undefined;\n  if (Array.isArray(session.discounts) && session.discounts.length !== 0) {\n    const discount = session.discounts[0];\n    if (discount.coupon && typeof discount.coupon === 'object') {\n      coupon = discount.coupon.id;\n    } else if (typeof discount.coupon === 'string') {\n      coupon = discount.coupon;\n    } else {\n      coupon = undefined;\n    }\n  }\n\n  return {\n    id: session.id,\n    url: session.url,\n    coupon,\n    livemode: session.livemode,\n    expires_at: session.expires_at,\n    payment_status: session.payment_status,\n    currency: session.currency,\n    amount_total: session.amount_total,\n    line_items: session.line_items?.data.map(mapLineItem),\n  };\n}\n\nexport function mapInvoice(i: Stripe.Invoice) {\n  return {\n    id: i.id,\n    number: i.number,\n    total: i.total,\n    subtotal: i.subtotal,\n    amount_due: i.amount_due,\n    amount_paid: i.amount_paid,\n    amount_remaining: i.amount_remaining,\n    currency: i.currency,\n    billing_reason: i.billing_reason,\n    hosted_invoice_url: i.hosted_invoice_url,\n    invoice_pdf: i.invoice_pdf,\n    receipt_number: i.receipt_number,\n    status: i.status,\n    created: i.created,\n    period_start: i.period_start,\n    period_end: i.period_end,\n  };\n}\n\nexport function mapPaymentIntent(intent: Stripe.PaymentIntent) {\n  return {\n    id: intent.id,\n    amount: intent.amount,\n    amount_capturable: intent.amount_capturable,\n    amount_received: intent.amount_received,\n    currency: intent.currency,\n    client_secret: intent.client_secret,\n    description: intent.description,\n    status: intent.status,\n    created: intent.created,\n  };\n}\n\nexport function mapCharge(charge: Stripe.Charge) {\n  return {\n    id: charge.id,\n    description: charge.description,\n    currency: charge.currency,\n    amount: charge.amount,\n    amount_captured: charge.amount_captured,\n    amount_refunded: charge.amount_refunded,\n    receipt_email: charge.receipt_email,\n    receipt_number: charge.receipt_number,\n    receipt_url: charge.receipt_url,\n    status: charge.status,\n    created: charge.created,\n    payment_intent:\n      charge.payment_intent && typeof charge.payment_intent === 'object'\n        ? mapPaymentIntent(charge.payment_intent)\n        : undefined,\n  };\n}\n\nexport type ProductPrice = {\n  id: string;\n  type: Stripe.Price.Type;\n  unit_amount: number;\n  currency: Stripe.Price['currency'];\n  product: {\n    id: Stripe.Product['id'];\n    name: Stripe.Product['name'];\n    description: Stripe.Product['description'];\n    livemode: Stripe.Product['livemode'];\n  };\n};\n\nexport function mapSubscriptionStatus(status: Stripe.Subscription.Status): SubscriptionStatus {\n  switch (status) {\n    case 'active':\n      return 'ACTIVE';\n    case 'canceled':\n      return 'CANCELED';\n    case 'incomplete':\n      return 'INCOMPLETE';\n    case 'incomplete_expired':\n      return 'INCOMPLETE_EXPIRED';\n    case 'past_due':\n      return 'PAST_DUE';\n    case 'paused':\n      return 'PAUSED';\n    case 'trialing':\n      return 'TRIALING';\n    case 'unpaid':\n      return 'UNPAID';\n    default: {\n      console.error(`Invalid stripe status: ${String(status)}`);\n      throw new Error(`Invalid stripe status: ${String(status)}`);\n    }\n  }\n}\n\nexport { ZERO_DECIMAL_CURRENCIES } from '@shware/utils';\n\n/** How many Stripe API amount units make one unit of `currency` (1, 100 or 1000). */\nexport function minorUnits(currency: string) {\n  return stripeMinorUnits(currency);\n}\n\nexport function price(value: number, currency: string) {\n  return value / minorUnits(currency);\n}\n\nexport type Money = { amount: number; currency: string };\n\n/** A Stripe amount in minor units (cents, yen, fils) as an amount in `currency` itself. */\nexport function money(value: number, currency: string): Money {\n  return { amount: price(value, currency), currency };\n}\n\nexport interface Item {\n  item_id: string;\n  item_name: string;\n  affiliation?: 'Google Store' | (string & {});\n  coupon?: string;\n  discount?: number;\n  index?: number;\n  item_brand?: string;\n  item_category?: string;\n  item_category2?: string;\n  item_category3?: string;\n  item_category4?: string;\n  item_category5?: string;\n  item_list_id?: string;\n  item_list_name?: string;\n  item_variant?: string;\n  location_id?: string;\n  price?: number;\n  quantity?: number;\n}\n\nexport interface PurchaseProperties {\n  currency: string;\n  value: number;\n  transaction_id: string;\n  coupon?: string;\n  shipping?: number;\n  tax?: number;\n  items?: Item[];\n}\n\nexport interface BeginCheckoutProperties {\n  currency: string;\n  value: number;\n  coupon?: string;\n  items: Item[];\n}\n\n// Google Ads rejects conversion transaction IDs longer than 64 characters.\n// https://support.google.com/google-ads/answer/6386790\nconst GOOGLE_ADS_TRANSACTION_ID_MAX = 64;\n\n/**\n * GA4 purchase events feed Google Ads conversions, whose transaction IDs are\n * capped at 64 characters — but Stripe checkout session ids exceed that:\n * around 2021 they grew from ~32 chars (`cs_live_` + 24 random chars) to ~66\n * (`cs_live_a` + 57), with no announcement. Stripe treats id length/format as\n * opaque and backwards-compatible, guaranteeing only that ids never exceed\n * 255 chars, so they may grow again at any time.\n *\n * Dropping the fixed `cs_live_`/`cs_test_` prefix brings the id under 64\n * while staying reversible: prepend the prefix (livemode tells which) to\n * reconstruct the full session id for Stripe dashboard lookups. The payment\n * intent id (~27 chars) is not a substitute — it only exists on\n * `mode: 'payment'` sessions (subscription-mode sessions carry it on the\n * invoice instead), and its short length is just as unguaranteed as the\n * session id's was.\n *\n * Must stay deterministic: GA4/Google Ads dedupe purchases by\n * transaction_id, and the same session may be tracked from multiple paths.\n */\nfunction toTransactionId(sessionId: string): string {\n  const stripped = sessionId.replace(/^cs_(live|test)_/, '');\n  if (stripped.length > GOOGLE_ADS_TRANSACTION_ID_MAX) {\n    console.warn(\n      `transaction_id still exceeds ${GOOGLE_ADS_TRANSACTION_ID_MAX} chars after stripping ` +\n        `the prefix — Stripe may have lengthened session ids again; truncating: ${sessionId}`\n    );\n  }\n  return stripped.slice(0, GOOGLE_ADS_TRANSACTION_ID_MAX);\n}\n\nexport function getPurchaseProperties(session: CheckoutSession): PurchaseProperties {\n  let value: number;\n  let currency: string;\n  if (!session.amount_total || !session.currency) {\n    value = session.line_items?.reduce((acc, item) => acc + item.amount_total, 0) ?? 0;\n    currency = session.line_items?.[0]?.currency ?? 'usd';\n  } else {\n    value = session.amount_total;\n    currency = session.currency;\n  }\n\n  return {\n    transaction_id: toTransactionId(session.id),\n    value: price(value, currency),\n    currency: currency.toUpperCase(),\n    coupon: session.coupon,\n    items: session.line_items?.map((item, index) => ({\n      index,\n      item_id: item.id,\n      item_name: item.description ?? '',\n      price: price(item.amount_total, item.currency),\n      quantity: item.quantity ?? 1,\n      discount: price(item.amount_discount, item.currency),\n    })),\n  };\n}\n\nexport function getBeginCheckoutProperties(p: ProductPrice): BeginCheckoutProperties {\n  return {\n    currency: p.currency.toUpperCase(),\n    value: price(p.unit_amount, p.currency),\n    items: [\n      {\n        item_id: p.product.id,\n        item_name: p.product.name,\n        price: price(p.unit_amount, p.currency),\n      },\n    ],\n  };\n}\n\n/**\n * Stripe's `cancellation_details` in the shared shape. The object is present on every\n * subscription with all three fields null, so an active one maps to null rather than an empty\n * record. `reason` says who acted: `cancellation_requested` is the customer (or us on their\n * behalf), the payment reasons are Stripe ending it.\n */\nexport function mapCancellationDetails(\n  subscription: Pick<Stripe.Subscription, 'cancellation_details'>\n): CancellationDetails | null {\n  const details = subscription.cancellation_details;\n  if (!details || (!details.reason && !details.feedback && !details.comment)) return null;\n  return {\n    initiator:\n      details.reason === 'payment_failed' || details.reason === 'payment_disputed'\n        ? 'system'\n        : 'user',\n    reason: details.reason ?? null,\n    // Stripe's feedback vocabulary is ours; anything it adds later is reported as \"other\".\n    feedback: details.feedback\n      ? (CANCELLATION_FEEDBACKS as readonly string[]).includes(details.feedback)\n        ? (details.feedback as CancellationFeedback)\n        : 'other'\n      : null,\n    comment: details.comment ?? null,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"mapper.cjs","names":["DISPUTE_STATUSES","stripeMinorUnits","CANCELLATION_FEEDBACKS"],"sources":["../../src/stripe/mapper.ts"],"sourcesContent":["import { stripeMinorUnits } from '@shware/utils';\nimport type { Stripe } from 'stripe';\nimport {\n  CANCELLATION_FEEDBACKS,\n  type CancellationDetails,\n  type CancellationFeedback,\n  DISPUTE_STATUSES,\n  type DisputeStatus,\n  type PaymentType,\n  type RefundStatus,\n  type SubscriptionStatus,\n} from '../subscription/index';\n\nexport function mapTime<T extends number | null>(\n  stripeTimestampSeconds: T\n): T extends number ? string : null {\n  if (!stripeTimestampSeconds) return null as T extends number ? string : null;\n  return new Date(stripeTimestampSeconds * 1000).toISOString() as T extends number ? string : null;\n}\n\nexport type Price = {\n  id: string;\n  type: Stripe.Price.Type;\n  active: boolean;\n  billing_scheme: Stripe.Price.BillingScheme;\n  currency: Stripe.Price['currency'];\n  unit_amount: number | null;\n  unit_amount_decimal: string | null;\n  recurring: Stripe.Price.Recurring | null;\n};\n\nexport function mapPrice(price: Stripe.Price): Price {\n  return {\n    id: price.id,\n    type: price.type,\n    active: price.active,\n    billing_scheme: price.billing_scheme,\n    currency: price.currency,\n    unit_amount: price.unit_amount,\n    unit_amount_decimal: price.unit_amount_decimal?.toString() ?? null,\n    recurring: price.recurring,\n  };\n}\n\nexport interface LineItem {\n  id: string;\n  currency: string;\n  quantity: number | null;\n  description: string | null;\n  amount_tax: number;\n  amount_total: number;\n  amount_subtotal: number;\n  amount_discount: number;\n  price: Price | null;\n}\n\nexport function mapLineItem(item: Stripe.LineItem): LineItem {\n  return {\n    id: item.price\n      ? typeof item.price.product === 'string'\n        ? item.price.product\n        : item.price.product.id\n      : item.id,\n    currency: item.currency,\n    quantity: item.quantity,\n    description: item.description,\n    amount_tax: item.amount_tax,\n    amount_total: item.amount_total,\n    amount_subtotal: item.amount_subtotal,\n    amount_discount: item.amount_discount,\n    price: item.price ? mapPrice(item.price) : null,\n  };\n}\n\n// Re-exported under our own name so consumers need not reach into stripe's namespace.\n// Open-ended since stripe 22.4: a status the API adds later is not a type error.\nexport type PaymentStatus = Stripe.Checkout.Session.PaymentStatus;\n\n// Declared rather than inferred from mapCheckoutSession: an inferred shape is\n// structural, so a consumer's declaration emit has to spell out payment_status\n// through stripe's internal module path — TS2883 in any package that reaches\n// stripe transitively instead of depending on it (see line_items/price too).\nexport interface CheckoutSession {\n  id: string;\n  url: string | null;\n  coupon: string | undefined;\n  livemode: boolean;\n  expires_at: number;\n  payment_status: PaymentStatus;\n  currency: string | null;\n  amount_total: number | null;\n  line_items: LineItem[] | undefined;\n}\n\nexport function mapCheckoutSession(session: Stripe.Checkout.Session): CheckoutSession {\n  let coupon: string | undefined = undefined;\n  if (Array.isArray(session.discounts) && session.discounts.length !== 0) {\n    const discount = session.discounts[0];\n    if (discount.coupon && typeof discount.coupon === 'object') {\n      coupon = discount.coupon.id;\n    } else if (typeof discount.coupon === 'string') {\n      coupon = discount.coupon;\n    } else {\n      coupon = undefined;\n    }\n  }\n\n  return {\n    id: session.id,\n    url: session.url,\n    coupon,\n    livemode: session.livemode,\n    expires_at: session.expires_at,\n    payment_status: session.payment_status,\n    currency: session.currency,\n    amount_total: session.amount_total,\n    line_items: session.line_items?.data.map(mapLineItem),\n  };\n}\n\nexport function mapInvoice(i: Stripe.Invoice) {\n  return {\n    id: i.id,\n    number: i.number,\n    total: i.total,\n    subtotal: i.subtotal,\n    amount_due: i.amount_due,\n    amount_paid: i.amount_paid,\n    amount_remaining: i.amount_remaining,\n    currency: i.currency,\n    billing_reason: i.billing_reason,\n    hosted_invoice_url: i.hosted_invoice_url,\n    invoice_pdf: i.invoice_pdf,\n    receipt_number: i.receipt_number,\n    status: i.status,\n    created: i.created,\n    period_start: i.period_start,\n    period_end: i.period_end,\n  };\n}\n\nexport function mapPaymentIntent(intent: Stripe.PaymentIntent) {\n  return {\n    id: intent.id,\n    amount: intent.amount,\n    amount_capturable: intent.amount_capturable,\n    amount_received: intent.amount_received,\n    currency: intent.currency,\n    client_secret: intent.client_secret,\n    description: intent.description,\n    status: intent.status,\n    created: intent.created,\n  };\n}\n\nexport function mapCharge(charge: Stripe.Charge) {\n  return {\n    id: charge.id,\n    description: charge.description,\n    currency: charge.currency,\n    amount: charge.amount,\n    amount_captured: charge.amount_captured,\n    amount_refunded: charge.amount_refunded,\n    receipt_email: charge.receipt_email,\n    receipt_number: charge.receipt_number,\n    receipt_url: charge.receipt_url,\n    status: charge.status,\n    created: charge.created,\n    payment_intent:\n      charge.payment_intent && typeof charge.payment_intent === 'object'\n        ? mapPaymentIntent(charge.payment_intent)\n        : undefined,\n  };\n}\n\nexport type ProductPrice = {\n  id: string;\n  type: Stripe.Price.Type;\n  unit_amount: number;\n  currency: Stripe.Price['currency'];\n  product: {\n    id: Stripe.Product['id'];\n    name: Stripe.Product['name'];\n    description: Stripe.Product['description'];\n    livemode: Stripe.Product['livemode'];\n  };\n};\n\nexport function mapSubscriptionStatus(status: Stripe.Subscription.Status): SubscriptionStatus {\n  switch (status) {\n    case 'active':\n      return 'ACTIVE';\n    case 'canceled':\n      return 'CANCELED';\n    case 'incomplete':\n      return 'INCOMPLETE';\n    case 'incomplete_expired':\n      return 'INCOMPLETE_EXPIRED';\n    case 'past_due':\n      return 'PAST_DUE';\n    case 'paused':\n      return 'PAUSED';\n    case 'trialing':\n      return 'TRIALING';\n    case 'unpaid':\n      return 'UNPAID';\n    default: {\n      console.error(`Invalid stripe status: ${String(status)}`);\n      throw new Error(`Invalid stripe status: ${String(status)}`);\n    }\n  }\n}\n\n/**\n * What a paid subscription invoice was for, by its `billing_reason`. Only `subscription_cycle` is\n * a renewal: a plan change invoices its proration mid-period (`subscription_update`), and counting\n * that as a renewal would inflate the renewal rate by every upgrade.\n */\nexport function mapPaymentType(\n  invoice: Pick<Stripe.Invoice, 'id' | 'billing_reason'>\n): Exclude<PaymentType, 'ONE_TIME'> {\n  switch (invoice.billing_reason) {\n    // Exactly once per subscription: its first invoice (after a trial, the first paid one is a cycle).\n    case 'subscription_create':\n      return 'SUBSCRIPTION_START';\n    case 'subscription_cycle':\n      return 'SUBSCRIPTION_RENEWAL';\n    case 'subscription_update':\n      return 'SUBSCRIPTION_UPDATE';\n    // An invoice made by hand on the subscription (dashboard or API): off-cycle money, not a renewal.\n    case 'manual':\n      return 'SUBSCRIPTION_UPDATE';\n    default:\n      // subscription_threshold (metered billing) and the rest are not reasons flat-priced\n      // subscriptions produce. Off-cycle is the safe reading: it leaves renewals alone.\n      console.warn(`Invoice ${invoice.id} has billing_reason ${invoice.billing_reason}`);\n      return 'SUBSCRIPTION_UPDATE';\n  }\n}\n\n/** `refund.status` is an untyped string in stripe-node; these are the documented values. */\nconst REFUND_STATUS: Partial<Record<string, RefundStatus>> = {\n  pending: 'PENDING',\n  requires_action: 'PENDING',\n  succeeded: 'SUCCEEDED',\n  failed: 'FAILED',\n  canceled: 'CANCELED',\n};\n\n/** A Stripe refund's status; a refund that has none yet is pending. Throws on an unknown one. */\nexport function mapRefundStatus(refund: Pick<Stripe.Refund, 'id' | 'status'>): RefundStatus {\n  const status = REFUND_STATUS[refund.status ?? 'pending'];\n  if (!status) throw new Error(`Unknown refund status ${refund.status}: ${refund.id}`);\n  return status;\n}\n\n/** A Stripe dispute's status, upper-cased into {@link DISPUTE_STATUSES}. Throws on an unknown one. */\nexport function mapDisputeStatus(dispute: Pick<Stripe.Dispute, 'id' | 'status'>): DisputeStatus {\n  const status = dispute.status.toUpperCase();\n  const known = DISPUTE_STATUSES.find((item) => item === status);\n  if (!known) throw new Error(`Unknown dispute status ${dispute.status}: ${dispute.id}`);\n  return known;\n}\n\nexport { ZERO_DECIMAL_CURRENCIES } from '@shware/utils';\n\n/** How many Stripe API amount units make one unit of `currency` (1, 100 or 1000). */\nexport function minorUnits(currency: string) {\n  return stripeMinorUnits(currency);\n}\n\nexport function price(value: number, currency: string) {\n  return value / minorUnits(currency);\n}\n\nexport type Money = { amount: number; currency: string };\n\n/** A Stripe amount in minor units (cents, yen, fils) as an amount in `currency` itself. */\nexport function money(value: number, currency: string): Money {\n  return { amount: price(value, currency), currency };\n}\n\nexport interface Item {\n  item_id: string;\n  item_name: string;\n  affiliation?: 'Google Store' | (string & {});\n  coupon?: string;\n  discount?: number;\n  index?: number;\n  item_brand?: string;\n  item_category?: string;\n  item_category2?: string;\n  item_category3?: string;\n  item_category4?: string;\n  item_category5?: string;\n  item_list_id?: string;\n  item_list_name?: string;\n  item_variant?: string;\n  location_id?: string;\n  price?: number;\n  quantity?: number;\n}\n\nexport interface PurchaseProperties {\n  currency: string;\n  value: number;\n  transaction_id: string;\n  coupon?: string;\n  shipping?: number;\n  tax?: number;\n  items?: Item[];\n}\n\nexport interface BeginCheckoutProperties {\n  currency: string;\n  value: number;\n  coupon?: string;\n  items: Item[];\n}\n\n// Google Ads rejects conversion transaction IDs longer than 64 characters.\n// https://support.google.com/google-ads/answer/6386790\nconst GOOGLE_ADS_TRANSACTION_ID_MAX = 64;\n\n/**\n * GA4 purchase events feed Google Ads conversions, whose transaction IDs are\n * capped at 64 characters — but Stripe checkout session ids exceed that:\n * around 2021 they grew from ~32 chars (`cs_live_` + 24 random chars) to ~66\n * (`cs_live_a` + 57), with no announcement. Stripe treats id length/format as\n * opaque and backwards-compatible, guaranteeing only that ids never exceed\n * 255 chars, so they may grow again at any time.\n *\n * Dropping the fixed `cs_live_`/`cs_test_` prefix brings the id under 64\n * while staying reversible: prepend the prefix (livemode tells which) to\n * reconstruct the full session id for Stripe dashboard lookups. The payment\n * intent id (~27 chars) is not a substitute — it only exists on\n * `mode: 'payment'` sessions (subscription-mode sessions carry it on the\n * invoice instead), and its short length is just as unguaranteed as the\n * session id's was.\n *\n * Must stay deterministic: GA4/Google Ads dedupe purchases by\n * transaction_id, and the same session may be tracked from multiple paths.\n */\nfunction toTransactionId(sessionId: string): string {\n  const stripped = sessionId.replace(/^cs_(live|test)_/, '');\n  if (stripped.length > GOOGLE_ADS_TRANSACTION_ID_MAX) {\n    console.warn(\n      `transaction_id still exceeds ${GOOGLE_ADS_TRANSACTION_ID_MAX} chars after stripping ` +\n        `the prefix — Stripe may have lengthened session ids again; truncating: ${sessionId}`\n    );\n  }\n  return stripped.slice(0, GOOGLE_ADS_TRANSACTION_ID_MAX);\n}\n\nexport function getPurchaseProperties(session: CheckoutSession): PurchaseProperties {\n  let value: number;\n  let currency: string;\n  if (!session.amount_total || !session.currency) {\n    value = session.line_items?.reduce((acc, item) => acc + item.amount_total, 0) ?? 0;\n    currency = session.line_items?.[0]?.currency ?? 'usd';\n  } else {\n    value = session.amount_total;\n    currency = session.currency;\n  }\n\n  return {\n    transaction_id: toTransactionId(session.id),\n    value: price(value, currency),\n    currency: currency.toUpperCase(),\n    coupon: session.coupon,\n    items: session.line_items?.map((item, index) => ({\n      index,\n      item_id: item.id,\n      item_name: item.description ?? '',\n      price: price(item.amount_total, item.currency),\n      quantity: item.quantity ?? 1,\n      discount: price(item.amount_discount, item.currency),\n    })),\n  };\n}\n\nexport function getBeginCheckoutProperties(p: ProductPrice): BeginCheckoutProperties {\n  return {\n    currency: p.currency.toUpperCase(),\n    value: price(p.unit_amount, p.currency),\n    items: [\n      {\n        item_id: p.product.id,\n        item_name: p.product.name,\n        price: price(p.unit_amount, p.currency),\n      },\n    ],\n  };\n}\n\n/**\n * Stripe's `cancellation_details` in the shared shape. The object is present on every\n * subscription with all three fields null, so an active one maps to null rather than an empty\n * record. `reason` says who acted: `cancellation_requested` is the customer (or us on their\n * behalf), the payment reasons are Stripe ending it.\n */\nexport function mapCancellationDetails(\n  subscription: Pick<Stripe.Subscription, 'cancellation_details'>\n): CancellationDetails | null {\n  const details = subscription.cancellation_details;\n  if (!details || (!details.reason && !details.feedback && !details.comment)) return null;\n  return {\n    initiator:\n      details.reason === 'payment_failed' || details.reason === 'payment_disputed'\n        ? 'system'\n        : 'user',\n    reason: details.reason ?? null,\n    // Stripe's feedback vocabulary is ours; anything it adds later is reported as \"other\".\n    feedback: details.feedback\n      ? (CANCELLATION_FEEDBACKS as readonly string[]).includes(details.feedback)\n        ? (details.feedback as CancellationFeedback)\n        : 'other'\n      : null,\n    comment: details.comment ?? null,\n  };\n}\n"],"mappings":"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"}

package/dist/stripe/mapper.d.cts

@@ -1,4 +1,4 @@
-import { CancellationDetails, SubscriptionStatus } from "../subscription/index.cjs";
+import { CancellationDetails, DisputeStatus, PaymentType, RefundStatus, SubscriptionStatus } from "../subscription/index.cjs";
 import { Stripe } from "stripe";
 import { ZERO_DECIMAL_CURRENCIES } from "@shware/utils";
 //#region src/stripe/mapper.d.ts
@@ -105,6 +105,16 @@ export type ProductPrice = {
   };
 };
 export declare function mapSubscriptionStatus(status: Stripe.Subscription.Status): SubscriptionStatus;
+/**
+ * What a paid subscription invoice was for, by its `billing_reason`. Only `subscription_cycle` is
+ * a renewal: a plan change invoices its proration mid-period (`subscription_update`), and counting
+ * that as a renewal would inflate the renewal rate by every upgrade.
+ */
+export declare function mapPaymentType(invoice: Pick<Stripe.Invoice, 'id' | 'billing_reason'>): Exclude<PaymentType, 'ONE_TIME'>;
+/** A Stripe refund's status; a refund that has none yet is pending. Throws on an unknown one. */
+export declare function mapRefundStatus(refund: Pick<Stripe.Refund, 'id' | 'status'>): RefundStatus;
+/** A Stripe dispute's status, upper-cased into {@link DISPUTE_STATUSES}. Throws on an unknown one. */
+export declare function mapDisputeStatus(dispute: Pick<Stripe.Dispute, 'id' | 'status'>): DisputeStatus;
 /** How many Stripe API amount units make one unit of `currency` (1, 100 or 1000). */
 export declare function minorUnits(currency: string): 1 | 100 | 1000;
 export declare function price(value: number, currency: string): number;

package/dist/stripe/mapper.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"mapper.d.cts","names":[],"sources":["../../src/stripe/mapper.ts"],"mappings":";;;;wBASgB,QAAQ,yBACtB,wBAAwB,IACvB;YAKS;EACV;EACA,MAAM,OAAO,MAAM;EACnB;EACA,gBAAgB,OAAO,MAAM;EAC7B,UAAU,OAAO;EACjB;EACA;EACA,WAAW,OAAO,MAAM;;wBAGV,SAAS,OAAO,OAAO,QAAQ;iBAa9B;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,OAAO;;wBAGO,YAAY,MAAM,OAAO,WAAW;YAoBxC,gBAAgB,OAAO,SAAS,QAAQ;iBAMnC;EACf;EACA;EACA;EACA;EACA;EACA,gBAAgB;EAChB;EACA;EACA,YAAY;;wBAGE,mBAAmB,SAAS,OAAO,SAAS,UAAU;wBA0BtD,WAAW,GAAG,OAAO;EAEjC;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,gBAAc,OAAA,QAAA;EACd;EACA;EACA;EACA,QAAM,OAAA,QAAA;EACN;EACA;EACA;;wBAIY,iBAAiB,QAAQ,OAAO;EAE5C;EACA;EACA;EACA;EACA;EACA;EACA;EACA,QAAM,OAAA,cAAA;EACN;;wBAIY,UAAU,QAAQ,OAAO;EAErC;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,QAAM,OAAA,OAAA;EACN;EACA;;;;;;;;;;;;YAOQ;EACV;EACA,MAAM,OAAO,MAAM;EACnB;EACA,UAAU,OAAO;EACjB;IACE,IAAI,OAAO;IACX,MAAM,OAAO;IACb,aAAa,OAAO;IACpB,UAAU,OAAO;;;wBAIL,sBAAsB,QAAQ,OAAO,aAAa,SAAS;;wBA4B3D,WAAW;wBAIX,MAAM,eAAe;YAIzB;EAAU;EAAgB;;;wBAGtB,MAAM,eAAe,mBAAmB;iBAIvC;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA,QAAQ;;iBAGO;EACf;EACA;EACA;EACA,OAAO;;wBAqCO,sBAAsB,SAAS,kBAAkB;wBA2BjD,2BAA2B,GAAG,eAAe;;;;;;;wBAoB7C,uBACd,cAAc,KAAK,OAAO,wCACzB"}
+{"version":3,"file":"mapper.d.cts","names":[],"sources":["../../src/stripe/mapper.ts"],"mappings":";;;;wBAagB,QAAQ,yBACtB,wBAAwB,IACvB;YAKS;EACV;EACA,MAAM,OAAO,MAAM;EACnB;EACA,gBAAgB,OAAO,MAAM;EAC7B,UAAU,OAAO;EACjB;EACA;EACA,WAAW,OAAO,MAAM;;wBAGV,SAAS,OAAO,OAAO,QAAQ;iBAa9B;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,OAAO;;wBAGO,YAAY,MAAM,OAAO,WAAW;YAoBxC,gBAAgB,OAAO,SAAS,QAAQ;iBAMnC;EACf;EACA;EACA;EACA;EACA;EACA,gBAAgB;EAChB;EACA;EACA,YAAY;;wBAGE,mBAAmB,SAAS,OAAO,SAAS,UAAU;wBA0BtD,WAAW,GAAG,OAAO;EAEjC;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,gBAAc,OAAA,QAAA;EACd;EACA;EACA;EACA,QAAM,OAAA,QAAA;EACN;EACA;EACA;;wBAIY,iBAAiB,QAAQ,OAAO;EAE5C;EACA;EACA;EACA;EACA;EACA;EACA;EACA,QAAM,OAAA,cAAA;EACN;;wBAIY,UAAU,QAAQ,OAAO;EAErC;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,QAAM,OAAA,OAAA;EACN;EACA;;;;;;;;;;;;YAOQ;EACV;EACA,MAAM,OAAO,MAAM;EACnB;EACA,UAAU,OAAO;EACjB;IACE,IAAI,OAAO;IACX,MAAM,OAAO;IACb,aAAa,OAAO;IACpB,UAAU,OAAO;;;wBAIL,sBAAsB,QAAQ,OAAO,aAAa,SAAS;;;;;;wBA8B3D,eACd,SAAS,KAAK,OAAO,oCACpB,QAAQ;;wBA8BK,gBAAgB,QAAQ,KAAK,OAAO,2BAA2B;;wBAO/D,iBAAiB,SAAS,KAAK,OAAO,4BAA4B;;wBAUlE,WAAW;wBAIX,MAAM,eAAe;YAIzB;EAAU;EAAgB;;;wBAGtB,MAAM,eAAe,mBAAmB;iBAIvC;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA,QAAQ;;iBAGO;EACf;EACA;EACA;EACA,OAAO;;wBAqCO,sBAAsB,SAAS,kBAAkB;wBA2BjD,2BAA2B,GAAG,eAAe;;;;;;;wBAoB7C,uBACd,cAAc,KAAK,OAAO,wCACzB"}

package/dist/stripe/mapper.d.mts

@@ -1,4 +1,4 @@
-import { CancellationDetails, SubscriptionStatus } from "../subscription/index.mjs";
+import { CancellationDetails, DisputeStatus, PaymentType, RefundStatus, SubscriptionStatus } from "../subscription/index.mjs";
 import { ZERO_DECIMAL_CURRENCIES } from "@shware/utils";
 import { Stripe } from "stripe";
 //#region src/stripe/mapper.d.ts
@@ -105,6 +105,16 @@ export type ProductPrice = {
   };
 };
 export declare function mapSubscriptionStatus(status: Stripe.Subscription.Status): SubscriptionStatus;
+/**
+ * What a paid subscription invoice was for, by its `billing_reason`. Only `subscription_cycle` is
+ * a renewal: a plan change invoices its proration mid-period (`subscription_update`), and counting
+ * that as a renewal would inflate the renewal rate by every upgrade.
+ */
+export declare function mapPaymentType(invoice: Pick<Stripe.Invoice, 'id' | 'billing_reason'>): Exclude<PaymentType, 'ONE_TIME'>;
+/** A Stripe refund's status; a refund that has none yet is pending. Throws on an unknown one. */
+export declare function mapRefundStatus(refund: Pick<Stripe.Refund, 'id' | 'status'>): RefundStatus;
+/** A Stripe dispute's status, upper-cased into {@link DISPUTE_STATUSES}. Throws on an unknown one. */
+export declare function mapDisputeStatus(dispute: Pick<Stripe.Dispute, 'id' | 'status'>): DisputeStatus;
 /** How many Stripe API amount units make one unit of `currency` (1, 100 or 1000). */
 export declare function minorUnits(currency: string): 1 | 100 | 1000;
 export declare function price(value: number, currency: string): number;

package/dist/stripe/mapper.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"mapper.d.mts","names":[],"sources":["../../src/stripe/mapper.ts"],"mappings":";;;;wBASgB,QAAQ,yBACtB,wBAAwB,IACvB;YAKS;EACV;EACA,MAAM,OAAO,MAAM;EACnB;EACA,gBAAgB,OAAO,MAAM;EAC7B,UAAU,OAAO;EACjB;EACA;EACA,WAAW,OAAO,MAAM;;wBAGV,SAAS,OAAO,OAAO,QAAQ;iBAa9B;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,OAAO;;wBAGO,YAAY,MAAM,OAAO,WAAW;YAoBxC,gBAAgB,OAAO,SAAS,QAAQ;iBAMnC;EACf;EACA;EACA;EACA;EACA;EACA,gBAAgB;EAChB;EACA;EACA,YAAY;;wBAGE,mBAAmB,SAAS,OAAO,SAAS,UAAU;wBA0BtD,WAAW,GAAG,OAAO;EAEjC;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,gBAAc,OAAA,QAAA;EACd;EACA;EACA;EACA,QAAM,OAAA,QAAA;EACN;EACA;EACA;;wBAIY,iBAAiB,QAAQ,OAAO;EAE5C;EACA;EACA;EACA;EACA;EACA;EACA;EACA,QAAM,OAAA,cAAA;EACN;;wBAIY,UAAU,QAAQ,OAAO;EAErC;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,QAAM,OAAA,OAAA;EACN;EACA;;;;;;;;;;;;YAOQ;EACV;EACA,MAAM,OAAO,MAAM;EACnB;EACA,UAAU,OAAO;EACjB;IACE,IAAI,OAAO;IACX,MAAM,OAAO;IACb,aAAa,OAAO;IACpB,UAAU,OAAO;;;wBAIL,sBAAsB,QAAQ,OAAO,aAAa,SAAS;;wBA4B3D,WAAW;wBAIX,MAAM,eAAe;YAIzB;EAAU;EAAgB;;;wBAGtB,MAAM,eAAe,mBAAmB;iBAIvC;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA,QAAQ;;iBAGO;EACf;EACA;EACA;EACA,OAAO;;wBAqCO,sBAAsB,SAAS,kBAAkB;wBA2BjD,2BAA2B,GAAG,eAAe;;;;;;;wBAoB7C,uBACd,cAAc,KAAK,OAAO,wCACzB"}
+{"version":3,"file":"mapper.d.mts","names":[],"sources":["../../src/stripe/mapper.ts"],"mappings":";;;;wBAagB,QAAQ,yBACtB,wBAAwB,IACvB;YAKS;EACV;EACA,MAAM,OAAO,MAAM;EACnB;EACA,gBAAgB,OAAO,MAAM;EAC7B,UAAU,OAAO;EACjB;EACA;EACA,WAAW,OAAO,MAAM;;wBAGV,SAAS,OAAO,OAAO,QAAQ;iBAa9B;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,OAAO;;wBAGO,YAAY,MAAM,OAAO,WAAW;YAoBxC,gBAAgB,OAAO,SAAS,QAAQ;iBAMnC;EACf;EACA;EACA;EACA;EACA;EACA,gBAAgB;EAChB;EACA;EACA,YAAY;;wBAGE,mBAAmB,SAAS,OAAO,SAAS,UAAU;wBA0BtD,WAAW,GAAG,OAAO;EAEjC;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,gBAAc,OAAA,QAAA;EACd;EACA;EACA;EACA,QAAM,OAAA,QAAA;EACN;EACA;EACA;;wBAIY,iBAAiB,QAAQ,OAAO;EAE5C;EACA;EACA;EACA;EACA;EACA;EACA;EACA,QAAM,OAAA,cAAA;EACN;;wBAIY,UAAU,QAAQ,OAAO;EAErC;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,QAAM,OAAA,OAAA;EACN;EACA;;;;;;;;;;;;YAOQ;EACV;EACA,MAAM,OAAO,MAAM;EACnB;EACA,UAAU,OAAO;EACjB;IACE,IAAI,OAAO;IACX,MAAM,OAAO;IACb,aAAa,OAAO;IACpB,UAAU,OAAO;;;wBAIL,sBAAsB,QAAQ,OAAO,aAAa,SAAS;;;;;;wBA8B3D,eACd,SAAS,KAAK,OAAO,oCACpB,QAAQ;;wBA8BK,gBAAgB,QAAQ,KAAK,OAAO,2BAA2B;;wBAO/D,iBAAiB,SAAS,KAAK,OAAO,4BAA4B;;wBAUlE,WAAW;wBAIX,MAAM,eAAe;YAIzB;EAAU;EAAgB;;;wBAGtB,MAAM,eAAe,mBAAmB;iBAIvC;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA,QAAQ;;iBAGO;EACf;EACA;EACA;EACA,OAAO;;wBAqCO,sBAAsB,SAAS,kBAAkB;wBA2BjD,2BAA2B,GAAG,eAAe;;;;;;;wBAoB7C,uBACd,cAAc,KAAK,OAAO,wCACzB"}

package/dist/stripe/mapper.mjs

@@ -1,4 +1,4 @@
-import { CANCELLATION_FEEDBACKS } from "../subscription/index.mjs";
+import { CANCELLATION_FEEDBACKS, DISPUTE_STATUSES } from "../subscription/index.mjs";
 import { ZERO_DECIMAL_CURRENCIES, stripeMinorUnits } from "@shware/utils";
 //#region src/stripe/mapper.ts
 function mapTime(stripeTimestampSeconds) {
@@ -114,6 +114,43 @@ function mapSubscriptionStatus(status) {
 			throw new Error(`Invalid stripe status: ${String(status)}`);
 	}
 }
+/**
+* What a paid subscription invoice was for, by its `billing_reason`. Only `subscription_cycle` is
+* a renewal: a plan change invoices its proration mid-period (`subscription_update`), and counting
+* that as a renewal would inflate the renewal rate by every upgrade.
+*/
+function mapPaymentType(invoice) {
+	switch (invoice.billing_reason) {
+		case "subscription_create": return "SUBSCRIPTION_START";
+		case "subscription_cycle": return "SUBSCRIPTION_RENEWAL";
+		case "subscription_update": return "SUBSCRIPTION_UPDATE";
+		case "manual": return "SUBSCRIPTION_UPDATE";
+		default:
+			console.warn(`Invoice ${invoice.id} has billing_reason ${invoice.billing_reason}`);
+			return "SUBSCRIPTION_UPDATE";
+	}
+}
+/** `refund.status` is an untyped string in stripe-node; these are the documented values. */
+const REFUND_STATUS = {
+	pending: "PENDING",
+	requires_action: "PENDING",
+	succeeded: "SUCCEEDED",
+	failed: "FAILED",
+	canceled: "CANCELED"
+};
+/** A Stripe refund's status; a refund that has none yet is pending. Throws on an unknown one. */
+function mapRefundStatus(refund) {
+	const status = REFUND_STATUS[refund.status ?? "pending"];
+	if (!status) throw new Error(`Unknown refund status ${refund.status}: ${refund.id}`);
+	return status;
+}
+/** A Stripe dispute's status, upper-cased into {@link DISPUTE_STATUSES}. Throws on an unknown one. */
+function mapDisputeStatus(dispute) {
+	const status = dispute.status.toUpperCase();
+	const known = DISPUTE_STATUSES.find((item) => item === status);
+	if (!known) throw new Error(`Unknown dispute status ${dispute.status}: ${dispute.id}`);
+	return known;
+}
 /** How many Stripe API amount units make one unit of `currency` (1, 100 or 1000). */
 function minorUnits(currency) {
 	return stripeMinorUnits(currency);
@@ -206,6 +243,6 @@ function mapCancellationDetails(subscription) {
 	};
 }
 //#endregion
-export { ZERO_DECIMAL_CURRENCIES, getBeginCheckoutProperties, getPurchaseProperties, mapCancellationDetails, mapCharge, mapCheckoutSession, mapInvoice, mapLineItem, mapPaymentIntent, mapPrice, mapSubscriptionStatus, mapTime, minorUnits, money, price };
+export { ZERO_DECIMAL_CURRENCIES, getBeginCheckoutProperties, getPurchaseProperties, mapCancellationDetails, mapCharge, mapCheckoutSession, mapDisputeStatus, mapInvoice, mapLineItem, mapPaymentIntent, mapPaymentType, mapPrice, mapRefundStatus, mapSubscriptionStatus, mapTime, minorUnits, money, price };
 
 //# sourceMappingURL=mapper.mjs.map

package/dist/stripe/mapper.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mapper.mjs","names":[],"sources":["../../src/stripe/mapper.ts"],"sourcesContent":["import { stripeMinorUnits } from '@shware/utils';\nimport type { Stripe } from 'stripe';\nimport {\n  CANCELLATION_FEEDBACKS,\n  type CancellationDetails,\n  type CancellationFeedback,\n  type SubscriptionStatus,\n} from '../subscription/index';\n\nexport function mapTime<T extends number | null>(\n  stripeTimestampSeconds: T\n): T extends number ? string : null {\n  if (!stripeTimestampSeconds) return null as T extends number ? string : null;\n  return new Date(stripeTimestampSeconds * 1000).toISOString() as T extends number ? string : null;\n}\n\nexport type Price = {\n  id: string;\n  type: Stripe.Price.Type;\n  active: boolean;\n  billing_scheme: Stripe.Price.BillingScheme;\n  currency: Stripe.Price['currency'];\n  unit_amount: number | null;\n  unit_amount_decimal: string | null;\n  recurring: Stripe.Price.Recurring | null;\n};\n\nexport function mapPrice(price: Stripe.Price): Price {\n  return {\n    id: price.id,\n    type: price.type,\n    active: price.active,\n    billing_scheme: price.billing_scheme,\n    currency: price.currency,\n    unit_amount: price.unit_amount,\n    unit_amount_decimal: price.unit_amount_decimal?.toString() ?? null,\n    recurring: price.recurring,\n  };\n}\n\nexport interface LineItem {\n  id: string;\n  currency: string;\n  quantity: number | null;\n  description: string | null;\n  amount_tax: number;\n  amount_total: number;\n  amount_subtotal: number;\n  amount_discount: number;\n  price: Price | null;\n}\n\nexport function mapLineItem(item: Stripe.LineItem): LineItem {\n  return {\n    id: item.price\n      ? typeof item.price.product === 'string'\n        ? item.price.product\n        : item.price.product.id\n      : item.id,\n    currency: item.currency,\n    quantity: item.quantity,\n    description: item.description,\n    amount_tax: item.amount_tax,\n    amount_total: item.amount_total,\n    amount_subtotal: item.amount_subtotal,\n    amount_discount: item.amount_discount,\n    price: item.price ? mapPrice(item.price) : null,\n  };\n}\n\n// Re-exported under our own name so consumers need not reach into stripe's namespace.\n// Open-ended since stripe 22.4: a status the API adds later is not a type error.\nexport type PaymentStatus = Stripe.Checkout.Session.PaymentStatus;\n\n// Declared rather than inferred from mapCheckoutSession: an inferred shape is\n// structural, so a consumer's declaration emit has to spell out payment_status\n// through stripe's internal module path — TS2883 in any package that reaches\n// stripe transitively instead of depending on it (see line_items/price too).\nexport interface CheckoutSession {\n  id: string;\n  url: string | null;\n  coupon: string | undefined;\n  livemode: boolean;\n  expires_at: number;\n  payment_status: PaymentStatus;\n  currency: string | null;\n  amount_total: number | null;\n  line_items: LineItem[] | undefined;\n}\n\nexport function mapCheckoutSession(session: Stripe.Checkout.Session): CheckoutSession {\n  let coupon: string | undefined = undefined;\n  if (Array.isArray(session.discounts) && session.discounts.length !== 0) {\n    const discount = session.discounts[0];\n    if (discount.coupon && typeof discount.coupon === 'object') {\n      coupon = discount.coupon.id;\n    } else if (typeof discount.coupon === 'string') {\n      coupon = discount.coupon;\n    } else {\n      coupon = undefined;\n    }\n  }\n\n  return {\n    id: session.id,\n    url: session.url,\n    coupon,\n    livemode: session.livemode,\n    expires_at: session.expires_at,\n    payment_status: session.payment_status,\n    currency: session.currency,\n    amount_total: session.amount_total,\n    line_items: session.line_items?.data.map(mapLineItem),\n  };\n}\n\nexport function mapInvoice(i: Stripe.Invoice) {\n  return {\n    id: i.id,\n    number: i.number,\n    total: i.total,\n    subtotal: i.subtotal,\n    amount_due: i.amount_due,\n    amount_paid: i.amount_paid,\n    amount_remaining: i.amount_remaining,\n    currency: i.currency,\n    billing_reason: i.billing_reason,\n    hosted_invoice_url: i.hosted_invoice_url,\n    invoice_pdf: i.invoice_pdf,\n    receipt_number: i.receipt_number,\n    status: i.status,\n    created: i.created,\n    period_start: i.period_start,\n    period_end: i.period_end,\n  };\n}\n\nexport function mapPaymentIntent(intent: Stripe.PaymentIntent) {\n  return {\n    id: intent.id,\n    amount: intent.amount,\n    amount_capturable: intent.amount_capturable,\n    amount_received: intent.amount_received,\n    currency: intent.currency,\n    client_secret: intent.client_secret,\n    description: intent.description,\n    status: intent.status,\n    created: intent.created,\n  };\n}\n\nexport function mapCharge(charge: Stripe.Charge) {\n  return {\n    id: charge.id,\n    description: charge.description,\n    currency: charge.currency,\n    amount: charge.amount,\n    amount_captured: charge.amount_captured,\n    amount_refunded: charge.amount_refunded,\n    receipt_email: charge.receipt_email,\n    receipt_number: charge.receipt_number,\n    receipt_url: charge.receipt_url,\n    status: charge.status,\n    created: charge.created,\n    payment_intent:\n      charge.payment_intent && typeof charge.payment_intent === 'object'\n        ? mapPaymentIntent(charge.payment_intent)\n        : undefined,\n  };\n}\n\nexport type ProductPrice = {\n  id: string;\n  type: Stripe.Price.Type;\n  unit_amount: number;\n  currency: Stripe.Price['currency'];\n  product: {\n    id: Stripe.Product['id'];\n    name: Stripe.Product['name'];\n    description: Stripe.Product['description'];\n    livemode: Stripe.Product['livemode'];\n  };\n};\n\nexport function mapSubscriptionStatus(status: Stripe.Subscription.Status): SubscriptionStatus {\n  switch (status) {\n    case 'active':\n      return 'ACTIVE';\n    case 'canceled':\n      return 'CANCELED';\n    case 'incomplete':\n      return 'INCOMPLETE';\n    case 'incomplete_expired':\n      return 'INCOMPLETE_EXPIRED';\n    case 'past_due':\n      return 'PAST_DUE';\n    case 'paused':\n      return 'PAUSED';\n    case 'trialing':\n      return 'TRIALING';\n    case 'unpaid':\n      return 'UNPAID';\n    default: {\n      console.error(`Invalid stripe status: ${String(status)}`);\n      throw new Error(`Invalid stripe status: ${String(status)}`);\n    }\n  }\n}\n\nexport { ZERO_DECIMAL_CURRENCIES } from '@shware/utils';\n\n/** How many Stripe API amount units make one unit of `currency` (1, 100 or 1000). */\nexport function minorUnits(currency: string) {\n  return stripeMinorUnits(currency);\n}\n\nexport function price(value: number, currency: string) {\n  return value / minorUnits(currency);\n}\n\nexport type Money = { amount: number; currency: string };\n\n/** A Stripe amount in minor units (cents, yen, fils) as an amount in `currency` itself. */\nexport function money(value: number, currency: string): Money {\n  return { amount: price(value, currency), currency };\n}\n\nexport interface Item {\n  item_id: string;\n  item_name: string;\n  affiliation?: 'Google Store' | (string & {});\n  coupon?: string;\n  discount?: number;\n  index?: number;\n  item_brand?: string;\n  item_category?: string;\n  item_category2?: string;\n  item_category3?: string;\n  item_category4?: string;\n  item_category5?: string;\n  item_list_id?: string;\n  item_list_name?: string;\n  item_variant?: string;\n  location_id?: string;\n  price?: number;\n  quantity?: number;\n}\n\nexport interface PurchaseProperties {\n  currency: string;\n  value: number;\n  transaction_id: string;\n  coupon?: string;\n  shipping?: number;\n  tax?: number;\n  items?: Item[];\n}\n\nexport interface BeginCheckoutProperties {\n  currency: string;\n  value: number;\n  coupon?: string;\n  items: Item[];\n}\n\n// Google Ads rejects conversion transaction IDs longer than 64 characters.\n// https://support.google.com/google-ads/answer/6386790\nconst GOOGLE_ADS_TRANSACTION_ID_MAX = 64;\n\n/**\n * GA4 purchase events feed Google Ads conversions, whose transaction IDs are\n * capped at 64 characters — but Stripe checkout session ids exceed that:\n * around 2021 they grew from ~32 chars (`cs_live_` + 24 random chars) to ~66\n * (`cs_live_a` + 57), with no announcement. Stripe treats id length/format as\n * opaque and backwards-compatible, guaranteeing only that ids never exceed\n * 255 chars, so they may grow again at any time.\n *\n * Dropping the fixed `cs_live_`/`cs_test_` prefix brings the id under 64\n * while staying reversible: prepend the prefix (livemode tells which) to\n * reconstruct the full session id for Stripe dashboard lookups. The payment\n * intent id (~27 chars) is not a substitute — it only exists on\n * `mode: 'payment'` sessions (subscription-mode sessions carry it on the\n * invoice instead), and its short length is just as unguaranteed as the\n * session id's was.\n *\n * Must stay deterministic: GA4/Google Ads dedupe purchases by\n * transaction_id, and the same session may be tracked from multiple paths.\n */\nfunction toTransactionId(sessionId: string): string {\n  const stripped = sessionId.replace(/^cs_(live|test)_/, '');\n  if (stripped.length > GOOGLE_ADS_TRANSACTION_ID_MAX) {\n    console.warn(\n      `transaction_id still exceeds ${GOOGLE_ADS_TRANSACTION_ID_MAX} chars after stripping ` +\n        `the prefix — Stripe may have lengthened session ids again; truncating: ${sessionId}`\n    );\n  }\n  return stripped.slice(0, GOOGLE_ADS_TRANSACTION_ID_MAX);\n}\n\nexport function getPurchaseProperties(session: CheckoutSession): PurchaseProperties {\n  let value: number;\n  let currency: string;\n  if (!session.amount_total || !session.currency) {\n    value = session.line_items?.reduce((acc, item) => acc + item.amount_total, 0) ?? 0;\n    currency = session.line_items?.[0]?.currency ?? 'usd';\n  } else {\n    value = session.amount_total;\n    currency = session.currency;\n  }\n\n  return {\n    transaction_id: toTransactionId(session.id),\n    value: price(value, currency),\n    currency: currency.toUpperCase(),\n    coupon: session.coupon,\n    items: session.line_items?.map((item, index) => ({\n      index,\n      item_id: item.id,\n      item_name: item.description ?? '',\n      price: price(item.amount_total, item.currency),\n      quantity: item.quantity ?? 1,\n      discount: price(item.amount_discount, item.currency),\n    })),\n  };\n}\n\nexport function getBeginCheckoutProperties(p: ProductPrice): BeginCheckoutProperties {\n  return {\n    currency: p.currency.toUpperCase(),\n    value: price(p.unit_amount, p.currency),\n    items: [\n      {\n        item_id: p.product.id,\n        item_name: p.product.name,\n        price: price(p.unit_amount, p.currency),\n      },\n    ],\n  };\n}\n\n/**\n * Stripe's `cancellation_details` in the shared shape. The object is present on every\n * subscription with all three fields null, so an active one maps to null rather than an empty\n * record. `reason` says who acted: `cancellation_requested` is the customer (or us on their\n * behalf), the payment reasons are Stripe ending it.\n */\nexport function mapCancellationDetails(\n  subscription: Pick<Stripe.Subscription, 'cancellation_details'>\n): CancellationDetails | null {\n  const details = subscription.cancellation_details;\n  if (!details || (!details.reason && !details.feedback && !details.comment)) return null;\n  return {\n    initiator:\n      details.reason === 'payment_failed' || details.reason === 'payment_disputed'\n        ? 'system'\n        : 'user',\n    reason: details.reason ?? null,\n    // Stripe's feedback vocabulary is ours; anything it adds later is reported as \"other\".\n    feedback: details.feedback\n      ? (CANCELLATION_FEEDBACKS as readonly string[]).includes(details.feedback)\n        ? (details.feedback as CancellationFeedback)\n        : 'other'\n      : null,\n    comment: details.comment ?? null,\n  };\n}\n"],"mappings":";;;AASA,SAAgB,QACd,wBACkC;CAClC,IAAI,CAAC,wBAAwB,OAAO;CACpC,wBAAO,IAAI,KAAK,yBAAyB,GAAI,EAAA,CAAE,YAAY;AAC7D;AAaA,SAAgB,SAAS,OAA4B;CACnD,OAAO;EACL,IAAI,MAAM;EACV,MAAM,MAAM;EACZ,QAAQ,MAAM;EACd,gBAAgB,MAAM;EACtB,UAAU,MAAM;EAChB,aAAa,MAAM;EACnB,qBAAqB,MAAM,qBAAqB,SAAS,KAAK;EAC9D,WAAW,MAAM;CACnB;AACF;AAcA,SAAgB,YAAY,MAAiC;CAC3D,OAAO;EACL,IAAI,KAAK,QACL,OAAO,KAAK,MAAM,YAAY,WAC5B,KAAK,MAAM,UACX,KAAK,MAAM,QAAQ,KACrB,KAAK;EACT,UAAU,KAAK;EACf,UAAU,KAAK;EACf,aAAa,KAAK;EAClB,YAAY,KAAK;EACjB,cAAc,KAAK;EACnB,iBAAiB,KAAK;EACtB,iBAAiB,KAAK;EACtB,OAAO,KAAK,QAAQ,SAAS,KAAK,KAAK,IAAI;CAC7C;AACF;AAsBA,SAAgB,mBAAmB,SAAmD;CACpF,IAAI,SAA6B,KAAA;CACjC,IAAI,MAAM,QAAQ,QAAQ,SAAS,KAAK,QAAQ,UAAU,WAAW,GAAG;EACtE,MAAM,WAAW,QAAQ,UAAU;EACnC,IAAI,SAAS,UAAU,OAAO,SAAS,WAAW,UAChD,SAAS,SAAS,OAAO;OACpB,IAAI,OAAO,SAAS,WAAW,UACpC,SAAS,SAAS;OAElB,SAAS,KAAA;CAEb;CAEA,OAAO;EACL,IAAI,QAAQ;EACZ,KAAK,QAAQ;EACb;EACA,UAAU,QAAQ;EAClB,YAAY,QAAQ;EACpB,gBAAgB,QAAQ;EACxB,UAAU,QAAQ;EAClB,cAAc,QAAQ;EACtB,YAAY,QAAQ,YAAY,KAAK,IAAI,WAAW;CACtD;AACF;AAEA,SAAgB,WAAW,GAAmB;CAC5C,OAAO;EACL,IAAI,EAAE;EACN,QAAQ,EAAE;EACV,OAAO,EAAE;EACT,UAAU,EAAE;EACZ,YAAY,EAAE;EACd,aAAa,EAAE;EACf,kBAAkB,EAAE;EACpB,UAAU,EAAE;EACZ,gBAAgB,EAAE;EAClB,oBAAoB,EAAE;EACtB,aAAa,EAAE;EACf,gBAAgB,EAAE;EAClB,QAAQ,EAAE;EACV,SAAS,EAAE;EACX,cAAc,EAAE;EAChB,YAAY,EAAE;CAChB;AACF;AAEA,SAAgB,iBAAiB,QAA8B;CAC7D,OAAO;EACL,IAAI,OAAO;EACX,QAAQ,OAAO;EACf,mBAAmB,OAAO;EAC1B,iBAAiB,OAAO;EACxB,UAAU,OAAO;EACjB,eAAe,OAAO;EACtB,aAAa,OAAO;EACpB,QAAQ,OAAO;EACf,SAAS,OAAO;CAClB;AACF;AAEA,SAAgB,UAAU,QAAuB;CAC/C,OAAO;EACL,IAAI,OAAO;EACX,aAAa,OAAO;EACpB,UAAU,OAAO;EACjB,QAAQ,OAAO;EACf,iBAAiB,OAAO;EACxB,iBAAiB,OAAO;EACxB,eAAe,OAAO;EACtB,gBAAgB,OAAO;EACvB,aAAa,OAAO;EACpB,QAAQ,OAAO;EACf,SAAS,OAAO;EAChB,gBACE,OAAO,kBAAkB,OAAO,OAAO,mBAAmB,WACtD,iBAAiB,OAAO,cAAc,IACtC,KAAA;CACR;AACF;AAeA,SAAgB,sBAAsB,QAAwD;CAC5F,QAAQ,QAAR;EACE,KAAK,UACH,OAAO;EACT,KAAK,YACH,OAAO;EACT,KAAK,cACH,OAAO;EACT,KAAK,sBACH,OAAO;EACT,KAAK,YACH,OAAO;EACT,KAAK,UACH,OAAO;EACT,KAAK,YACH,OAAO;EACT,KAAK,UACH,OAAO;EACT;GACE,QAAQ,MAAM,0BAA0B,OAAO,MAAM,GAAG;GACxD,MAAM,IAAI,MAAM,0BAA0B,OAAO,MAAM,GAAG;CAE9D;AACF;;AAKA,SAAgB,WAAW,UAAkB;CAC3C,OAAO,iBAAiB,QAAQ;AAClC;AAEA,SAAgB,MAAM,OAAe,UAAkB;CACrD,OAAO,QAAQ,WAAW,QAAQ;AACpC;;AAKA,SAAgB,MAAM,OAAe,UAAyB;CAC5D,OAAO;EAAE,QAAQ,MAAM,OAAO,QAAQ;EAAG;CAAS;AACpD;AA0CA,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;AAqBtC,SAAS,gBAAgB,WAA2B;CAClD,MAAM,WAAW,UAAU,QAAQ,oBAAoB,EAAE;CACzD,IAAI,SAAS,SAAS,+BACpB,QAAQ,KACN,gCAAgC,8BAA8B,gGACc,WAC9E;CAEF,OAAO,SAAS,MAAM,GAAG,6BAA6B;AACxD;AAEA,SAAgB,sBAAsB,SAA8C;CAClF,IAAI;CACJ,IAAI;CACJ,IAAI,CAAC,QAAQ,gBAAgB,CAAC,QAAQ,UAAU;EAC9C,QAAQ,QAAQ,YAAY,QAAQ,KAAK,SAAS,MAAM,KAAK,cAAc,CAAC,KAAK;EACjF,WAAW,QAAQ,aAAa,EAAE,EAAE,YAAY;CAClD,OAAO;EACL,QAAQ,QAAQ;EAChB,WAAW,QAAQ;CACrB;CAEA,OAAO;EACL,gBAAgB,gBAAgB,QAAQ,EAAE;EAC1C,OAAO,MAAM,OAAO,QAAQ;EAC5B,UAAU,SAAS,YAAY;EAC/B,QAAQ,QAAQ;EAChB,OAAO,QAAQ,YAAY,KAAK,MAAM,WAAW;GAC/C;GACA,SAAS,KAAK;GACd,WAAW,KAAK,eAAe;GAC/B,OAAO,MAAM,KAAK,cAAc,KAAK,QAAQ;GAC7C,UAAU,KAAK,YAAY;GAC3B,UAAU,MAAM,KAAK,iBAAiB,KAAK,QAAQ;EACrD,EAAE;CACJ;AACF;AAEA,SAAgB,2BAA2B,GAA0C;CACnF,OAAO;EACL,UAAU,EAAE,SAAS,YAAY;EACjC,OAAO,MAAM,EAAE,aAAa,EAAE,QAAQ;EACtC,OAAO,CACL;GACE,SAAS,EAAE,QAAQ;GACnB,WAAW,EAAE,QAAQ;GACrB,OAAO,MAAM,EAAE,aAAa,EAAE,QAAQ;EACxC,CACF;CACF;AACF;;;;;;;AAQA,SAAgB,uBACd,cAC4B;CAC5B,MAAM,UAAU,aAAa;CAC7B,IAAI,CAAC,WAAY,CAAC,QAAQ,UAAU,CAAC,QAAQ,YAAY,CAAC,QAAQ,SAAU,OAAO;CACnF,OAAO;EACL,WACE,QAAQ,WAAW,oBAAoB,QAAQ,WAAW,qBACtD,WACA;EACN,QAAQ,QAAQ,UAAU;EAE1B,UAAU,QAAQ,WACb,uBAA6C,SAAS,QAAQ,QAAQ,IACpE,QAAQ,WACT,UACF;EACJ,SAAS,QAAQ,WAAW;CAC9B;AACF"}
+{"version":3,"file":"mapper.mjs","names":[],"sources":["../../src/stripe/mapper.ts"],"sourcesContent":["import { stripeMinorUnits } from '@shware/utils';\nimport type { Stripe } from 'stripe';\nimport {\n  CANCELLATION_FEEDBACKS,\n  type CancellationDetails,\n  type CancellationFeedback,\n  DISPUTE_STATUSES,\n  type DisputeStatus,\n  type PaymentType,\n  type RefundStatus,\n  type SubscriptionStatus,\n} from '../subscription/index';\n\nexport function mapTime<T extends number | null>(\n  stripeTimestampSeconds: T\n): T extends number ? string : null {\n  if (!stripeTimestampSeconds) return null as T extends number ? string : null;\n  return new Date(stripeTimestampSeconds * 1000).toISOString() as T extends number ? string : null;\n}\n\nexport type Price = {\n  id: string;\n  type: Stripe.Price.Type;\n  active: boolean;\n  billing_scheme: Stripe.Price.BillingScheme;\n  currency: Stripe.Price['currency'];\n  unit_amount: number | null;\n  unit_amount_decimal: string | null;\n  recurring: Stripe.Price.Recurring | null;\n};\n\nexport function mapPrice(price: Stripe.Price): Price {\n  return {\n    id: price.id,\n    type: price.type,\n    active: price.active,\n    billing_scheme: price.billing_scheme,\n    currency: price.currency,\n    unit_amount: price.unit_amount,\n    unit_amount_decimal: price.unit_amount_decimal?.toString() ?? null,\n    recurring: price.recurring,\n  };\n}\n\nexport interface LineItem {\n  id: string;\n  currency: string;\n  quantity: number | null;\n  description: string | null;\n  amount_tax: number;\n  amount_total: number;\n  amount_subtotal: number;\n  amount_discount: number;\n  price: Price | null;\n}\n\nexport function mapLineItem(item: Stripe.LineItem): LineItem {\n  return {\n    id: item.price\n      ? typeof item.price.product === 'string'\n        ? item.price.product\n        : item.price.product.id\n      : item.id,\n    currency: item.currency,\n    quantity: item.quantity,\n    description: item.description,\n    amount_tax: item.amount_tax,\n    amount_total: item.amount_total,\n    amount_subtotal: item.amount_subtotal,\n    amount_discount: item.amount_discount,\n    price: item.price ? mapPrice(item.price) : null,\n  };\n}\n\n// Re-exported under our own name so consumers need not reach into stripe's namespace.\n// Open-ended since stripe 22.4: a status the API adds later is not a type error.\nexport type PaymentStatus = Stripe.Checkout.Session.PaymentStatus;\n\n// Declared rather than inferred from mapCheckoutSession: an inferred shape is\n// structural, so a consumer's declaration emit has to spell out payment_status\n// through stripe's internal module path — TS2883 in any package that reaches\n// stripe transitively instead of depending on it (see line_items/price too).\nexport interface CheckoutSession {\n  id: string;\n  url: string | null;\n  coupon: string | undefined;\n  livemode: boolean;\n  expires_at: number;\n  payment_status: PaymentStatus;\n  currency: string | null;\n  amount_total: number | null;\n  line_items: LineItem[] | undefined;\n}\n\nexport function mapCheckoutSession(session: Stripe.Checkout.Session): CheckoutSession {\n  let coupon: string | undefined = undefined;\n  if (Array.isArray(session.discounts) && session.discounts.length !== 0) {\n    const discount = session.discounts[0];\n    if (discount.coupon && typeof discount.coupon === 'object') {\n      coupon = discount.coupon.id;\n    } else if (typeof discount.coupon === 'string') {\n      coupon = discount.coupon;\n    } else {\n      coupon = undefined;\n    }\n  }\n\n  return {\n    id: session.id,\n    url: session.url,\n    coupon,\n    livemode: session.livemode,\n    expires_at: session.expires_at,\n    payment_status: session.payment_status,\n    currency: session.currency,\n    amount_total: session.amount_total,\n    line_items: session.line_items?.data.map(mapLineItem),\n  };\n}\n\nexport function mapInvoice(i: Stripe.Invoice) {\n  return {\n    id: i.id,\n    number: i.number,\n    total: i.total,\n    subtotal: i.subtotal,\n    amount_due: i.amount_due,\n    amount_paid: i.amount_paid,\n    amount_remaining: i.amount_remaining,\n    currency: i.currency,\n    billing_reason: i.billing_reason,\n    hosted_invoice_url: i.hosted_invoice_url,\n    invoice_pdf: i.invoice_pdf,\n    receipt_number: i.receipt_number,\n    status: i.status,\n    created: i.created,\n    period_start: i.period_start,\n    period_end: i.period_end,\n  };\n}\n\nexport function mapPaymentIntent(intent: Stripe.PaymentIntent) {\n  return {\n    id: intent.id,\n    amount: intent.amount,\n    amount_capturable: intent.amount_capturable,\n    amount_received: intent.amount_received,\n    currency: intent.currency,\n    client_secret: intent.client_secret,\n    description: intent.description,\n    status: intent.status,\n    created: intent.created,\n  };\n}\n\nexport function mapCharge(charge: Stripe.Charge) {\n  return {\n    id: charge.id,\n    description: charge.description,\n    currency: charge.currency,\n    amount: charge.amount,\n    amount_captured: charge.amount_captured,\n    amount_refunded: charge.amount_refunded,\n    receipt_email: charge.receipt_email,\n    receipt_number: charge.receipt_number,\n    receipt_url: charge.receipt_url,\n    status: charge.status,\n    created: charge.created,\n    payment_intent:\n      charge.payment_intent && typeof charge.payment_intent === 'object'\n        ? mapPaymentIntent(charge.payment_intent)\n        : undefined,\n  };\n}\n\nexport type ProductPrice = {\n  id: string;\n  type: Stripe.Price.Type;\n  unit_amount: number;\n  currency: Stripe.Price['currency'];\n  product: {\n    id: Stripe.Product['id'];\n    name: Stripe.Product['name'];\n    description: Stripe.Product['description'];\n    livemode: Stripe.Product['livemode'];\n  };\n};\n\nexport function mapSubscriptionStatus(status: Stripe.Subscription.Status): SubscriptionStatus {\n  switch (status) {\n    case 'active':\n      return 'ACTIVE';\n    case 'canceled':\n      return 'CANCELED';\n    case 'incomplete':\n      return 'INCOMPLETE';\n    case 'incomplete_expired':\n      return 'INCOMPLETE_EXPIRED';\n    case 'past_due':\n      return 'PAST_DUE';\n    case 'paused':\n      return 'PAUSED';\n    case 'trialing':\n      return 'TRIALING';\n    case 'unpaid':\n      return 'UNPAID';\n    default: {\n      console.error(`Invalid stripe status: ${String(status)}`);\n      throw new Error(`Invalid stripe status: ${String(status)}`);\n    }\n  }\n}\n\n/**\n * What a paid subscription invoice was for, by its `billing_reason`. Only `subscription_cycle` is\n * a renewal: a plan change invoices its proration mid-period (`subscription_update`), and counting\n * that as a renewal would inflate the renewal rate by every upgrade.\n */\nexport function mapPaymentType(\n  invoice: Pick<Stripe.Invoice, 'id' | 'billing_reason'>\n): Exclude<PaymentType, 'ONE_TIME'> {\n  switch (invoice.billing_reason) {\n    // Exactly once per subscription: its first invoice (after a trial, the first paid one is a cycle).\n    case 'subscription_create':\n      return 'SUBSCRIPTION_START';\n    case 'subscription_cycle':\n      return 'SUBSCRIPTION_RENEWAL';\n    case 'subscription_update':\n      return 'SUBSCRIPTION_UPDATE';\n    // An invoice made by hand on the subscription (dashboard or API): off-cycle money, not a renewal.\n    case 'manual':\n      return 'SUBSCRIPTION_UPDATE';\n    default:\n      // subscription_threshold (metered billing) and the rest are not reasons flat-priced\n      // subscriptions produce. Off-cycle is the safe reading: it leaves renewals alone.\n      console.warn(`Invoice ${invoice.id} has billing_reason ${invoice.billing_reason}`);\n      return 'SUBSCRIPTION_UPDATE';\n  }\n}\n\n/** `refund.status` is an untyped string in stripe-node; these are the documented values. */\nconst REFUND_STATUS: Partial<Record<string, RefundStatus>> = {\n  pending: 'PENDING',\n  requires_action: 'PENDING',\n  succeeded: 'SUCCEEDED',\n  failed: 'FAILED',\n  canceled: 'CANCELED',\n};\n\n/** A Stripe refund's status; a refund that has none yet is pending. Throws on an unknown one. */\nexport function mapRefundStatus(refund: Pick<Stripe.Refund, 'id' | 'status'>): RefundStatus {\n  const status = REFUND_STATUS[refund.status ?? 'pending'];\n  if (!status) throw new Error(`Unknown refund status ${refund.status}: ${refund.id}`);\n  return status;\n}\n\n/** A Stripe dispute's status, upper-cased into {@link DISPUTE_STATUSES}. Throws on an unknown one. */\nexport function mapDisputeStatus(dispute: Pick<Stripe.Dispute, 'id' | 'status'>): DisputeStatus {\n  const status = dispute.status.toUpperCase();\n  const known = DISPUTE_STATUSES.find((item) => item === status);\n  if (!known) throw new Error(`Unknown dispute status ${dispute.status}: ${dispute.id}`);\n  return known;\n}\n\nexport { ZERO_DECIMAL_CURRENCIES } from '@shware/utils';\n\n/** How many Stripe API amount units make one unit of `currency` (1, 100 or 1000). */\nexport function minorUnits(currency: string) {\n  return stripeMinorUnits(currency);\n}\n\nexport function price(value: number, currency: string) {\n  return value / minorUnits(currency);\n}\n\nexport type Money = { amount: number; currency: string };\n\n/** A Stripe amount in minor units (cents, yen, fils) as an amount in `currency` itself. */\nexport function money(value: number, currency: string): Money {\n  return { amount: price(value, currency), currency };\n}\n\nexport interface Item {\n  item_id: string;\n  item_name: string;\n  affiliation?: 'Google Store' | (string & {});\n  coupon?: string;\n  discount?: number;\n  index?: number;\n  item_brand?: string;\n  item_category?: string;\n  item_category2?: string;\n  item_category3?: string;\n  item_category4?: string;\n  item_category5?: string;\n  item_list_id?: string;\n  item_list_name?: string;\n  item_variant?: string;\n  location_id?: string;\n  price?: number;\n  quantity?: number;\n}\n\nexport interface PurchaseProperties {\n  currency: string;\n  value: number;\n  transaction_id: string;\n  coupon?: string;\n  shipping?: number;\n  tax?: number;\n  items?: Item[];\n}\n\nexport interface BeginCheckoutProperties {\n  currency: string;\n  value: number;\n  coupon?: string;\n  items: Item[];\n}\n\n// Google Ads rejects conversion transaction IDs longer than 64 characters.\n// https://support.google.com/google-ads/answer/6386790\nconst GOOGLE_ADS_TRANSACTION_ID_MAX = 64;\n\n/**\n * GA4 purchase events feed Google Ads conversions, whose transaction IDs are\n * capped at 64 characters — but Stripe checkout session ids exceed that:\n * around 2021 they grew from ~32 chars (`cs_live_` + 24 random chars) to ~66\n * (`cs_live_a` + 57), with no announcement. Stripe treats id length/format as\n * opaque and backwards-compatible, guaranteeing only that ids never exceed\n * 255 chars, so they may grow again at any time.\n *\n * Dropping the fixed `cs_live_`/`cs_test_` prefix brings the id under 64\n * while staying reversible: prepend the prefix (livemode tells which) to\n * reconstruct the full session id for Stripe dashboard lookups. The payment\n * intent id (~27 chars) is not a substitute — it only exists on\n * `mode: 'payment'` sessions (subscription-mode sessions carry it on the\n * invoice instead), and its short length is just as unguaranteed as the\n * session id's was.\n *\n * Must stay deterministic: GA4/Google Ads dedupe purchases by\n * transaction_id, and the same session may be tracked from multiple paths.\n */\nfunction toTransactionId(sessionId: string): string {\n  const stripped = sessionId.replace(/^cs_(live|test)_/, '');\n  if (stripped.length > GOOGLE_ADS_TRANSACTION_ID_MAX) {\n    console.warn(\n      `transaction_id still exceeds ${GOOGLE_ADS_TRANSACTION_ID_MAX} chars after stripping ` +\n        `the prefix — Stripe may have lengthened session ids again; truncating: ${sessionId}`\n    );\n  }\n  return stripped.slice(0, GOOGLE_ADS_TRANSACTION_ID_MAX);\n}\n\nexport function getPurchaseProperties(session: CheckoutSession): PurchaseProperties {\n  let value: number;\n  let currency: string;\n  if (!session.amount_total || !session.currency) {\n    value = session.line_items?.reduce((acc, item) => acc + item.amount_total, 0) ?? 0;\n    currency = session.line_items?.[0]?.currency ?? 'usd';\n  } else {\n    value = session.amount_total;\n    currency = session.currency;\n  }\n\n  return {\n    transaction_id: toTransactionId(session.id),\n    value: price(value, currency),\n    currency: currency.toUpperCase(),\n    coupon: session.coupon,\n    items: session.line_items?.map((item, index) => ({\n      index,\n      item_id: item.id,\n      item_name: item.description ?? '',\n      price: price(item.amount_total, item.currency),\n      quantity: item.quantity ?? 1,\n      discount: price(item.amount_discount, item.currency),\n    })),\n  };\n}\n\nexport function getBeginCheckoutProperties(p: ProductPrice): BeginCheckoutProperties {\n  return {\n    currency: p.currency.toUpperCase(),\n    value: price(p.unit_amount, p.currency),\n    items: [\n      {\n        item_id: p.product.id,\n        item_name: p.product.name,\n        price: price(p.unit_amount, p.currency),\n      },\n    ],\n  };\n}\n\n/**\n * Stripe's `cancellation_details` in the shared shape. The object is present on every\n * subscription with all three fields null, so an active one maps to null rather than an empty\n * record. `reason` says who acted: `cancellation_requested` is the customer (or us on their\n * behalf), the payment reasons are Stripe ending it.\n */\nexport function mapCancellationDetails(\n  subscription: Pick<Stripe.Subscription, 'cancellation_details'>\n): CancellationDetails | null {\n  const details = subscription.cancellation_details;\n  if (!details || (!details.reason && !details.feedback && !details.comment)) return null;\n  return {\n    initiator:\n      details.reason === 'payment_failed' || details.reason === 'payment_disputed'\n        ? 'system'\n        : 'user',\n    reason: details.reason ?? null,\n    // Stripe's feedback vocabulary is ours; anything it adds later is reported as \"other\".\n    feedback: details.feedback\n      ? (CANCELLATION_FEEDBACKS as readonly string[]).includes(details.feedback)\n        ? (details.feedback as CancellationFeedback)\n        : 'other'\n      : null,\n    comment: details.comment ?? null,\n  };\n}\n"],"mappings":"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"}

package/dist/subscription/index.cjs

@@ -6,6 +6,76 @@ const PLATFORMS = [
 	"STRIPE"
 ];
 /**
+* What a payment was for, on every platform.
+*
+* - ONE_TIME: a one-time purchase.
+* - SUBSCRIPTION_START: the first paid charge of a subscription.
+* - SUBSCRIPTION_RENEWAL: a charge for a new billing period on the regular cycle.
+* - SUBSCRIPTION_UPDATE: a charge mid-period, outside the cycle: the proration of a plan change, or
+*   a manual invoice on the subscription. Kept apart from renewals so renewal rates stay honest.
+*/
+const PAYMENT_TYPES = [
+	"ONE_TIME",
+	"SUBSCRIPTION_START",
+	"SUBSCRIPTION_RENEWAL",
+	"SUBSCRIPTION_UPDATE"
+];
+/**
+* Where a refund stands, on every platform. Stripe reports all of them; Apple and Google report a
+* refund once it is done (SUCCEEDED), and Apple can take it back (REVERSED, `REFUND_REVERSED`).
+*/
+const REFUND_STATUSES = [
+	"PENDING",
+	"SUCCEEDED",
+	"FAILED",
+	"CANCELED",
+	"REVERSED"
+];
+/**
+* Where a refund may move from the status it has. Notifications arrive out of order and are
+* redelivered, so a status only ever moves forward along these edges:
+* - PENDING settles into anything (Stripe: succeeded / failed / canceled).
+* - SUCCEEDED can still become FAILED (Stripe: the money could not be returned after all) or
+*   REVERSED (Apple: REFUND_REVERSED).
+* - FAILED, CANCELED and REVERSED are final: nothing a platform sends afterwards reopens them.
+* Nothing moves back to PENDING, and a status never "moves" to itself (a redelivery is a no-op).
+*/
+const REFUND_STATUS_TRANSITIONS = {
+	PENDING: [
+		"SUCCEEDED",
+		"FAILED",
+		"CANCELED",
+		"REVERSED"
+	],
+	SUCCEEDED: ["FAILED", "REVERSED"],
+	FAILED: [],
+	CANCELED: [],
+	REVERSED: []
+};
+/**
+* Stripe's dispute statuses, as they are: the `warning_*` ones are inquiries and early fraud
+* warnings that may never become a chargeback, `prevented` is one Stripe blocked before it was
+* filed. Only LOST costs money. Stripe only: Apple and Google absorb chargebacks themselves and
+* report them as refunds.
+*/
+const DISPUTE_STATUSES = [
+	"WARNING_NEEDS_RESPONSE",
+	"WARNING_UNDER_REVIEW",
+	"WARNING_CLOSED",
+	"NEEDS_RESPONSE",
+	"UNDER_REVIEW",
+	"PREVENTED",
+	"WON",
+	"LOST"
+];
+/** A dispute in one of these is over; nothing Stripe sends afterwards reopens it. */
+const CLOSED_DISPUTE_STATUSES = [
+	"WON",
+	"LOST",
+	"WARNING_CLOSED",
+	"PREVENTED"
+];
+/**
 * [Stripe Subscription Status](https://stripe.com/docs/api/subscriptions/object#subscription_object-status)
 * [Stripe Subscription Lifecycle](https://docs.stripe.com/billing/subscriptions/overview)
 *
@@ -59,7 +129,12 @@ const RESUBSCRIBE_INTENTS = [
 exports.AVAILABLE_STATUSES = AVAILABLE_STATUSES;
 exports.CANCELLATION_FEEDBACKS = CANCELLATION_FEEDBACKS;
 exports.CANCELLATION_INITIATORS = CANCELLATION_INITIATORS;
+exports.CLOSED_DISPUTE_STATUSES = CLOSED_DISPUTE_STATUSES;
+exports.DISPUTE_STATUSES = DISPUTE_STATUSES;
+exports.PAYMENT_TYPES = PAYMENT_TYPES;
 exports.PLATFORMS = PLATFORMS;
+exports.REFUND_STATUSES = REFUND_STATUSES;
+exports.REFUND_STATUS_TRANSITIONS = REFUND_STATUS_TRANSITIONS;
 exports.RESUBSCRIBE_INTENTS = RESUBSCRIBE_INTENTS;
 exports.SUBSCRIPTION_STATUSES = SUBSCRIPTION_STATUSES;
 

package/dist/subscription/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../../src/subscription/index.ts"],"sourcesContent":["export const PLATFORMS = ['APPLE', 'GOOGLE', 'STRIPE'] as const;\n\nexport type Platform = (typeof PLATFORMS)[number];\n\n/**\n * [Stripe Subscription Status](https://stripe.com/docs/api/subscriptions/object#subscription_object-status)\n * [Stripe Subscription Lifecycle](https://docs.stripe.com/billing/subscriptions/overview)\n *\n * provision product for customer when Status = TRIALING, ACTIVE, IN_GRACE_PERIOD\n */\nexport const SUBSCRIPTION_STATUSES = [\n  /**\n   * The subscription is currently in a trial period and it’s safe to provision your product for\n   * your customer. The subscription transitions automatically to active when the first payment\n   * is made.\n   *\n   * Google: play(LineItems[0].OfferDetails.OfferId == 'xx')\n   *\n   * Platform: Apple, Google, Stripe\n   * */\n  'TRIALING',\n\n  /**\n   * The subscription is in good standing and the most recent payment is successful. It’s safe to\n   * provision your product for your customer.\n   *\n   * Platform: Apple, Google, Stripe\n   * */\n  'ACTIVE',\n\n  /**\n   * Apple: The subscription enters the billing retry period. If the subtype is GRACE_PERIOD,\n   * continue to provide service through the grace period. If the subtype is empty, the\n   * subscription isn’t in a grace period and you can stop providing the subscription service.\n   *\n   * Google: Subscription is in grace period. The state is only available when the subscription\n   * is an auto renewing plan. In this state, all items are in grace period.\n   *\n   * Platform: Apple, Google\n   * */\n  'IN_GRACE_PERIOD',\n\n  /**\n   * A successful payment needs to be made within 23 hours to activate the subscription. Or the\n   * payment requires action, like customer authentication. Subscriptions can also be incomplete\n   * if there’s a pending payment and the PaymentIntent status would be processing.\n   *\n   * Platform: Stripe\n   * */\n  'INCOMPLETE',\n\n  /**\n   * The initial payment on the subscription failed and no successful payment was made within 23\n   * hours of creating the subscription. These subscriptions don’t bill customers. This status\n   * exists so you can track customers that failed to activate their subscriptions.\n   *\n   * Platform: Stripe\n   * */\n  'INCOMPLETE_EXPIRED',\n\n  /**\n   * Subscription was created but awaiting payment during signup. In this state, all items are\n   * awaiting payment.\n   *\n   * Platform: Google\n   * */\n  'PENDING',\n\n  /**\n   * Pending transaction for subscription is canceled. If this pending purchase was for an\n   * existing subscription, use linkedPurchaseToken to get the current state of that subscription.\n   *\n   * Platform: Google\n   * */\n  'PENDING_PURCHASE_CANCELED',\n\n  /**\n   * Payment on the latest finalized invoice either failed or wasn’t attempted. The subscription\n   * continues to create invoices. Your subscription settings determine the subscription’s next\n   * state. If the invoice is still unpaid after all Smart Retries have been attempted, you can\n   * configure the subscription to move to canceled, unpaid, or leave it as past_due. To move the\n   * subscription to active, pay the most recent invoice before its due date.\n   *\n   * Platform: Stripe\n   * */\n  'PAST_DUE',\n\n  /**\n   * Subscription is on hold (suspended). The state is only available when the subscription is an\n   * auto renewing plan. In this state, all items are on hold. Grace period ends or Active period\n   * ends but not grace period\n   *\n   * Platform: Google\n   * */\n  'ON_HOLD',\n\n  /**\n   * The subscription has been canceled. During cancellation, automatic collection for all unpaid\n   * invoices is disabled (auto_advance=false). This is a terminal state that can’t be updated.\n   *\n   * Platform: Apple, Google, Stripe\n   * */\n  'CANCELED',\n\n  /**\n   * The latest invoice hasn’t been paid but the subscription remains in place. The latest invoice\n   * remains open and invoices continue to be generated but payments aren’t attempted. You should\n   * revoke access to your product when the subscription is unpaid since payments were already\n   * attempted and retried when it was past_due. To move the subscription to active, pay the most\n   * recent invoice before its due date.\n   *\n   * Platform: Stripe\n   * */\n  'UNPAID',\n\n  /**\n   * Google: Subscription is paused. The state is only available when the subscription is an auto\n   * renewing plan. In this state, all items are in paused state.\n   *\n   * Stripe: The subscription has ended its trial period without a default payment method and the\n   * trial_settings.end_behavior.missing_payment_method is set to pause. Invoices will no longer\n   * be created for the subscription. After a default payment method has been attached to the\n   * customer, you can resume the subscription.\n   *\n   * Platform: Google, Stripe\n   * */\n  'PAUSED',\n\n  /**\n   * For example, a user buys a subscription and receives a purchase token A. The\n   * linkedPurchaseToken field will not be set in the API response because the purchase token\n   * belongs to a brand new subscription.\n   *\n   * If the user upgrades their subscription, a new purchase token B will be generated. Since the\n   * upgrade is replacing the subscription from purchase token A, the linkedPurchaseToken field\n   * for token B will be set to point to token A. Notice it points backwards in time to the\n   * original purchase token.\n   *\n   * +---------------------------+  +------------------------+  +------------------------+\n   * | Step 1 first purchase     |  | Step 2 upgrades        |  | Step 3 downgrades      |\n   * | purchaseToken: A          |->| purchaseToken: B       |->| purchaseToken: C       |\n   * | linkedPurchaseToken: null |  | linkedPurchaseToken: A |  | linkedPurchaseToken: B |\n   * +---------------------------+  +------------------------+  +------------------------+\n   *\n   * Platform: Google\n   * */\n  'REPLACED',\n\n  /**\n   * Google: Subscription is expired. All items have expiryTime in the past.\n   *\n   * Platform: Apple, Google\n   * */\n  'EXPIRED',\n] as const;\n\nexport type SubscriptionStatus = (typeof SUBSCRIPTION_STATUSES)[number];\n\n/** statuses where it is safe to provision your product for the customer */\nexport const AVAILABLE_STATUSES = [\n  'ACTIVE',\n  'TRIALING',\n  'IN_GRACE_PERIOD',\n] as const satisfies readonly SubscriptionStatus[];\n\n/** Who stopped the subscription from renewing. */\nexport const CANCELLATION_INITIATORS = [\n  /** The customer: the store's cancel flow, our own cancel dialog, or a declined price increase. */\n  'user',\n  /** The platform: a failed payment, a refund or revocation, a product no longer for sale. */\n  'system',\n  /** Us: a cancellation through the platform's API or console. */\n  'developer',\n] as const;\n\nexport type CancellationInitiator = (typeof CANCELLATION_INITIATORS)[number];\n\n/** What a cancel survey may report, whichever platform asked the question. */\nexport const CANCELLATION_FEEDBACKS = [\n  'customer_service',\n  'low_quality',\n  'missing_features',\n  'switched_service',\n  'too_complex',\n  'too_expensive',\n  'unused',\n  'other',\n] as const;\n\nexport type CancellationFeedback = (typeof CANCELLATION_FEEDBACKS)[number];\n\nexport const RESUBSCRIBE_INTENTS = ['maybe', 'no', 'yes'] as const;\n\nexport type ResubscribeIntent = (typeof RESUBSCRIBE_INTENTS)[number];\n\n/**\n * Why a subscription stopped renewing, in one record shared by every platform. Every key is\n * optional and every value a string, so a platform may add what only it reports without a\n * schema change; the keys below are the ones they have in common. When the subscription was\n * cancelled is not in here: it is a column of its own, `canceledAt`.\n *\n * - `initiator`: see {@link CANCELLATION_INITIATORS}.\n * - `reason`: the platform's own code, kept verbatim for analytics — Stripe's\n *   `cancellation_details.reason`, Google's `cancelSurveyResult.reason`, Apple's notification\n *   subtype or `expirationIntent`.\n * - `feedback`: the customer's survey answer in the shared vocabulary {@link CANCELLATION_FEEDBACKS}.\n * - `comment`: free text the customer typed.\n * - `resubscribeIntent`: whether they said they would come back, when the cancel flow asked.\n */\nexport interface CancellationDetails {\n  [key: string]: string | null | undefined;\n  initiator?: CancellationInitiator | null;\n  reason?: string | null;\n  feedback?: CancellationFeedback | null;\n  comment?: string | null;\n  resubscribeIntent?: ResubscribeIntent | null;\n}\n"],"mappings":";;AAAA,MAAa,YAAY;CAAC;CAAS;CAAU;AAAQ;;;;;;;AAUrD,MAAa,wBAAwB;CAUnC;CAQA;CAYA;CASA;CASA;CAQA;CAQA;CAWA;CASA;CAQA;CAWA;CAaA;CAoBA;CAOA;AACF;;AAKA,MAAa,qBAAqB;CAChC;CACA;CACA;AACF;;AAGA,MAAa,0BAA0B;CAErC;CAEA;CAEA;AACF;;AAKA,MAAa,yBAAyB;CACpC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;AAIA,MAAa,sBAAsB;CAAC;CAAS;CAAM;AAAK"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/subscription/index.ts"],"sourcesContent":["export const PLATFORMS = ['APPLE', 'GOOGLE', 'STRIPE'] as const;\n\nexport type Platform = (typeof PLATFORMS)[number];\n\n/**\n * What a payment was for, on every platform.\n *\n * - ONE_TIME: a one-time purchase.\n * - SUBSCRIPTION_START: the first paid charge of a subscription.\n * - SUBSCRIPTION_RENEWAL: a charge for a new billing period on the regular cycle.\n * - SUBSCRIPTION_UPDATE: a charge mid-period, outside the cycle: the proration of a plan change, or\n *   a manual invoice on the subscription. Kept apart from renewals so renewal rates stay honest.\n */\nexport const PAYMENT_TYPES = [\n  'ONE_TIME',\n  'SUBSCRIPTION_START',\n  'SUBSCRIPTION_RENEWAL',\n  'SUBSCRIPTION_UPDATE',\n] as const;\n\nexport type PaymentType = (typeof PAYMENT_TYPES)[number];\n\n/**\n * Where a refund stands, on every platform. Stripe reports all of them; Apple and Google report a\n * refund once it is done (SUCCEEDED), and Apple can take it back (REVERSED, `REFUND_REVERSED`).\n */\nexport const REFUND_STATUSES = ['PENDING', 'SUCCEEDED', 'FAILED', 'CANCELED', 'REVERSED'] as const;\n\nexport type RefundStatus = (typeof REFUND_STATUSES)[number];\n\n/**\n * Where a refund may move from the status it has. Notifications arrive out of order and are\n * redelivered, so a status only ever moves forward along these edges:\n * - PENDING settles into anything (Stripe: succeeded / failed / canceled).\n * - SUCCEEDED can still become FAILED (Stripe: the money could not be returned after all) or\n *   REVERSED (Apple: REFUND_REVERSED).\n * - FAILED, CANCELED and REVERSED are final: nothing a platform sends afterwards reopens them.\n * Nothing moves back to PENDING, and a status never \"moves\" to itself (a redelivery is a no-op).\n */\nexport const REFUND_STATUS_TRANSITIONS: Readonly<Record<RefundStatus, readonly RefundStatus[]>> = {\n  PENDING: ['SUCCEEDED', 'FAILED', 'CANCELED', 'REVERSED'],\n  SUCCEEDED: ['FAILED', 'REVERSED'],\n  FAILED: [],\n  CANCELED: [],\n  REVERSED: [],\n};\n\n/**\n * Stripe's dispute statuses, as they are: the `warning_*` ones are inquiries and early fraud\n * warnings that may never become a chargeback, `prevented` is one Stripe blocked before it was\n * filed. Only LOST costs money. Stripe only: Apple and Google absorb chargebacks themselves and\n * report them as refunds.\n */\nexport const DISPUTE_STATUSES = [\n  'WARNING_NEEDS_RESPONSE',\n  'WARNING_UNDER_REVIEW',\n  'WARNING_CLOSED',\n  'NEEDS_RESPONSE',\n  'UNDER_REVIEW',\n  'PREVENTED',\n  'WON',\n  'LOST',\n] as const;\n\nexport type DisputeStatus = (typeof DISPUTE_STATUSES)[number];\n\n/** A dispute in one of these is over; nothing Stripe sends afterwards reopens it. */\nexport const CLOSED_DISPUTE_STATUSES: readonly DisputeStatus[] = [\n  'WON',\n  'LOST',\n  'WARNING_CLOSED',\n  'PREVENTED',\n];\n\n/**\n * [Stripe Subscription Status](https://stripe.com/docs/api/subscriptions/object#subscription_object-status)\n * [Stripe Subscription Lifecycle](https://docs.stripe.com/billing/subscriptions/overview)\n *\n * provision product for customer when Status = TRIALING, ACTIVE, IN_GRACE_PERIOD\n */\nexport const SUBSCRIPTION_STATUSES = [\n  /**\n   * The subscription is currently in a trial period and it’s safe to provision your product for\n   * your customer. The subscription transitions automatically to active when the first payment\n   * is made.\n   *\n   * Google: play(LineItems[0].OfferDetails.OfferId == 'xx')\n   *\n   * Platform: Apple, Google, Stripe\n   * */\n  'TRIALING',\n\n  /**\n   * The subscription is in good standing and the most recent payment is successful. It’s safe to\n   * provision your product for your customer.\n   *\n   * Platform: Apple, Google, Stripe\n   * */\n  'ACTIVE',\n\n  /**\n   * Apple: The subscription enters the billing retry period. If the subtype is GRACE_PERIOD,\n   * continue to provide service through the grace period. If the subtype is empty, the\n   * subscription isn’t in a grace period and you can stop providing the subscription service.\n   *\n   * Google: Subscription is in grace period. The state is only available when the subscription\n   * is an auto renewing plan. In this state, all items are in grace period.\n   *\n   * Platform: Apple, Google\n   * */\n  'IN_GRACE_PERIOD',\n\n  /**\n   * A successful payment needs to be made within 23 hours to activate the subscription. Or the\n   * payment requires action, like customer authentication. Subscriptions can also be incomplete\n   * if there’s a pending payment and the PaymentIntent status would be processing.\n   *\n   * Platform: Stripe\n   * */\n  'INCOMPLETE',\n\n  /**\n   * The initial payment on the subscription failed and no successful payment was made within 23\n   * hours of creating the subscription. These subscriptions don’t bill customers. This status\n   * exists so you can track customers that failed to activate their subscriptions.\n   *\n   * Platform: Stripe\n   * */\n  'INCOMPLETE_EXPIRED',\n\n  /**\n   * Subscription was created but awaiting payment during signup. In this state, all items are\n   * awaiting payment.\n   *\n   * Platform: Google\n   * */\n  'PENDING',\n\n  /**\n   * Pending transaction for subscription is canceled. If this pending purchase was for an\n   * existing subscription, use linkedPurchaseToken to get the current state of that subscription.\n   *\n   * Platform: Google\n   * */\n  'PENDING_PURCHASE_CANCELED',\n\n  /**\n   * Payment on the latest finalized invoice either failed or wasn’t attempted. The subscription\n   * continues to create invoices. Your subscription settings determine the subscription’s next\n   * state. If the invoice is still unpaid after all Smart Retries have been attempted, you can\n   * configure the subscription to move to canceled, unpaid, or leave it as past_due. To move the\n   * subscription to active, pay the most recent invoice before its due date.\n   *\n   * Platform: Stripe\n   * */\n  'PAST_DUE',\n\n  /**\n   * Subscription is on hold (suspended). The state is only available when the subscription is an\n   * auto renewing plan. In this state, all items are on hold. Grace period ends or Active period\n   * ends but not grace period\n   *\n   * Platform: Google\n   * */\n  'ON_HOLD',\n\n  /**\n   * The subscription has been canceled. During cancellation, automatic collection for all unpaid\n   * invoices is disabled (auto_advance=false). This is a terminal state that can’t be updated.\n   *\n   * Platform: Apple, Google, Stripe\n   * */\n  'CANCELED',\n\n  /**\n   * The latest invoice hasn’t been paid but the subscription remains in place. The latest invoice\n   * remains open and invoices continue to be generated but payments aren’t attempted. You should\n   * revoke access to your product when the subscription is unpaid since payments were already\n   * attempted and retried when it was past_due. To move the subscription to active, pay the most\n   * recent invoice before its due date.\n   *\n   * Platform: Stripe\n   * */\n  'UNPAID',\n\n  /**\n   * Google: Subscription is paused. The state is only available when the subscription is an auto\n   * renewing plan. In this state, all items are in paused state.\n   *\n   * Stripe: The subscription has ended its trial period without a default payment method and the\n   * trial_settings.end_behavior.missing_payment_method is set to pause. Invoices will no longer\n   * be created for the subscription. After a default payment method has been attached to the\n   * customer, you can resume the subscription.\n   *\n   * Platform: Google, Stripe\n   * */\n  'PAUSED',\n\n  /**\n   * For example, a user buys a subscription and receives a purchase token A. The\n   * linkedPurchaseToken field will not be set in the API response because the purchase token\n   * belongs to a brand new subscription.\n   *\n   * If the user upgrades their subscription, a new purchase token B will be generated. Since the\n   * upgrade is replacing the subscription from purchase token A, the linkedPurchaseToken field\n   * for token B will be set to point to token A. Notice it points backwards in time to the\n   * original purchase token.\n   *\n   * +---------------------------+  +------------------------+  +------------------------+\n   * | Step 1 first purchase     |  | Step 2 upgrades        |  | Step 3 downgrades      |\n   * | purchaseToken: A          |->| purchaseToken: B       |->| purchaseToken: C       |\n   * | linkedPurchaseToken: null |  | linkedPurchaseToken: A |  | linkedPurchaseToken: B |\n   * +---------------------------+  +------------------------+  +------------------------+\n   *\n   * Platform: Google\n   * */\n  'REPLACED',\n\n  /**\n   * Google: Subscription is expired. All items have expiryTime in the past.\n   *\n   * Platform: Apple, Google\n   * */\n  'EXPIRED',\n] as const;\n\nexport type SubscriptionStatus = (typeof SUBSCRIPTION_STATUSES)[number];\n\n/** statuses where it is safe to provision your product for the customer */\nexport const AVAILABLE_STATUSES = [\n  'ACTIVE',\n  'TRIALING',\n  'IN_GRACE_PERIOD',\n] as const satisfies readonly SubscriptionStatus[];\n\n/** Who stopped the subscription from renewing. */\nexport const CANCELLATION_INITIATORS = [\n  /** The customer: the store's cancel flow, our own cancel dialog, or a declined price increase. */\n  'user',\n  /** The platform: a failed payment, a refund or revocation, a product no longer for sale. */\n  'system',\n  /** Us: a cancellation through the platform's API or console. */\n  'developer',\n] as const;\n\nexport type CancellationInitiator = (typeof CANCELLATION_INITIATORS)[number];\n\n/** What a cancel survey may report, whichever platform asked the question. */\nexport const CANCELLATION_FEEDBACKS = [\n  'customer_service',\n  'low_quality',\n  'missing_features',\n  'switched_service',\n  'too_complex',\n  'too_expensive',\n  'unused',\n  'other',\n] as const;\n\nexport type CancellationFeedback = (typeof CANCELLATION_FEEDBACKS)[number];\n\nexport const RESUBSCRIBE_INTENTS = ['maybe', 'no', 'yes'] as const;\n\nexport type ResubscribeIntent = (typeof RESUBSCRIBE_INTENTS)[number];\n\n/**\n * Why a subscription stopped renewing, in one record shared by every platform. Every key is\n * optional and every value a string, so a platform may add what only it reports without a\n * schema change; the keys below are the ones they have in common. When the subscription was\n * cancelled is not in here: it is a column of its own, `canceledAt`.\n *\n * - `initiator`: see {@link CANCELLATION_INITIATORS}.\n * - `reason`: the platform's own code, kept verbatim for analytics — Stripe's\n *   `cancellation_details.reason`, Google's `cancelSurveyResult.reason`, Apple's notification\n *   subtype or `expirationIntent`.\n * - `feedback`: the customer's survey answer in the shared vocabulary {@link CANCELLATION_FEEDBACKS}.\n * - `comment`: free text the customer typed.\n * - `resubscribeIntent`: whether they said they would come back, when the cancel flow asked.\n */\nexport interface CancellationDetails {\n  [key: string]: string | null | undefined;\n  initiator?: CancellationInitiator | null;\n  reason?: string | null;\n  feedback?: CancellationFeedback | null;\n  comment?: string | null;\n  resubscribeIntent?: ResubscribeIntent | null;\n}\n"],"mappings":";;AAAA,MAAa,YAAY;CAAC;CAAS;CAAU;AAAQ;;;;;;;;;;AAarD,MAAa,gBAAgB;CAC3B;CACA;CACA;CACA;AACF;;;;;AAQA,MAAa,kBAAkB;CAAC;CAAW;CAAa;CAAU;CAAY;AAAU;;;;;;;;;;AAaxF,MAAa,4BAAqF;CAChG,SAAS;EAAC;EAAa;EAAU;EAAY;CAAU;CACvD,WAAW,CAAC,UAAU,UAAU;CAChC,QAAQ,CAAC;CACT,UAAU,CAAC;CACX,UAAU,CAAC;AACb;;;;;;;AAQA,MAAa,mBAAmB;CAC9B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAKA,MAAa,0BAAoD;CAC/D;CACA;CACA;CACA;AACF;;;;;;;AAQA,MAAa,wBAAwB;CAUnC;CAQA;CAYA;CASA;CASA;CAQA;CAQA;CAWA;CASA;CAQA;CAWA;CAaA;CAoBA;CAOA;AACF;;AAKA,MAAa,qBAAqB;CAChC;CACA;CACA;AACF;;AAGA,MAAa,0BAA0B;CAErC;CAEA;CAEA;AACF;;AAKA,MAAa,yBAAyB;CACpC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;AAIA,MAAa,sBAAsB;CAAC;CAAS;CAAM;AAAK"}

package/dist/subscription/index.d.cts

@@ -1,6 +1,43 @@
 //#region src/subscription/index.d.ts
 export declare const PLATFORMS: readonly ['APPLE', 'GOOGLE', 'STRIPE'];
 export type Platform = (typeof PLATFORMS)[number];
+/**
+ * What a payment was for, on every platform.
+ *
+ * - ONE_TIME: a one-time purchase.
+ * - SUBSCRIPTION_START: the first paid charge of a subscription.
+ * - SUBSCRIPTION_RENEWAL: a charge for a new billing period on the regular cycle.
+ * - SUBSCRIPTION_UPDATE: a charge mid-period, outside the cycle: the proration of a plan change, or
+ *   a manual invoice on the subscription. Kept apart from renewals so renewal rates stay honest.
+ */
+export declare const PAYMENT_TYPES: readonly ['ONE_TIME', 'SUBSCRIPTION_START', 'SUBSCRIPTION_RENEWAL', 'SUBSCRIPTION_UPDATE'];
+export type PaymentType = (typeof PAYMENT_TYPES)[number];
+/**
+ * Where a refund stands, on every platform. Stripe reports all of them; Apple and Google report a
+ * refund once it is done (SUCCEEDED), and Apple can take it back (REVERSED, `REFUND_REVERSED`).
+ */
+export declare const REFUND_STATUSES: readonly ['PENDING', 'SUCCEEDED', 'FAILED', 'CANCELED', 'REVERSED'];
+export type RefundStatus = (typeof REFUND_STATUSES)[number];
+/**
+ * Where a refund may move from the status it has. Notifications arrive out of order and are
+ * redelivered, so a status only ever moves forward along these edges:
+ * - PENDING settles into anything (Stripe: succeeded / failed / canceled).
+ * - SUCCEEDED can still become FAILED (Stripe: the money could not be returned after all) or
+ *   REVERSED (Apple: REFUND_REVERSED).
+ * - FAILED, CANCELED and REVERSED are final: nothing a platform sends afterwards reopens them.
+ * Nothing moves back to PENDING, and a status never "moves" to itself (a redelivery is a no-op).
+ */
+export declare const REFUND_STATUS_TRANSITIONS: Readonly<Record<RefundStatus, readonly RefundStatus[]>>;
+/**
+ * Stripe's dispute statuses, as they are: the `warning_*` ones are inquiries and early fraud
+ * warnings that may never become a chargeback, `prevented` is one Stripe blocked before it was
+ * filed. Only LOST costs money. Stripe only: Apple and Google absorb chargebacks themselves and
+ * report them as refunds.
+ */
+export declare const DISPUTE_STATUSES: readonly ['WARNING_NEEDS_RESPONSE', 'WARNING_UNDER_REVIEW', 'WARNING_CLOSED', 'NEEDS_RESPONSE', 'UNDER_REVIEW', 'PREVENTED', 'WON', 'LOST'];
+export type DisputeStatus = (typeof DISPUTE_STATUSES)[number];
+/** A dispute in one of these is over; nothing Stripe sends afterwards reopens it. */
+export declare const CLOSED_DISPUTE_STATUSES: readonly DisputeStatus[];
 /**
  * [Stripe Subscription Status](https://stripe.com/docs/api/subscriptions/object#subscription_object-status)
  * [Stripe Subscription Lifecycle](https://docs.stripe.com/billing/subscriptions/overview)

package/dist/subscription/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/subscription/index.ts"],"mappings":";qBAAa;YAED,mBAAmB;;;;;;;qBAQlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAkJD,6BAA6B;;qBAG5B;;qBAOA;;;;;;;YASD,gCAAgC;;qBAG/B;YAWD,+BAA+B;qBAE9B;YAED,4BAA4B;;;;;;;;;;;;;;;iBAgBvB;GACd;EACD,YAAY;EACZ;EACA,WAAW;EACX;EACA,oBAAoB"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/subscription/index.ts"],"mappings":";qBAAa;YAED,mBAAmB;;;;;;;;;;qBAWlB;YAOD,sBAAsB;;;;;qBAMrB;YAED,uBAAuB;;;;;;;;;;qBAWtB,2BAA2B,SAAS,OAAO,uBAAuB;;;;;;;qBAclE;YAWD,wBAAwB;;qBAGvB,kCAAkC;;;;;;;qBAalC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAkJD,6BAA6B;;qBAG5B;;qBAOA;;;;;;;YASD,gCAAgC;;qBAG/B;YAWD,+BAA+B;qBAE9B;YAED,4BAA4B;;;;;;;;;;;;;;;iBAgBvB;GACd;EACD,YAAY;EACZ;EACA,WAAW;EACX;EACA,oBAAoB"}

package/dist/subscription/index.d.mts

@@ -1,6 +1,43 @@
 //#region src/subscription/index.d.ts
 export declare const PLATFORMS: readonly ['APPLE', 'GOOGLE', 'STRIPE'];
 export type Platform = (typeof PLATFORMS)[number];
+/**
+ * What a payment was for, on every platform.
+ *
+ * - ONE_TIME: a one-time purchase.
+ * - SUBSCRIPTION_START: the first paid charge of a subscription.
+ * - SUBSCRIPTION_RENEWAL: a charge for a new billing period on the regular cycle.
+ * - SUBSCRIPTION_UPDATE: a charge mid-period, outside the cycle: the proration of a plan change, or
+ *   a manual invoice on the subscription. Kept apart from renewals so renewal rates stay honest.
+ */
+export declare const PAYMENT_TYPES: readonly ['ONE_TIME', 'SUBSCRIPTION_START', 'SUBSCRIPTION_RENEWAL', 'SUBSCRIPTION_UPDATE'];
+export type PaymentType = (typeof PAYMENT_TYPES)[number];
+/**
+ * Where a refund stands, on every platform. Stripe reports all of them; Apple and Google report a
+ * refund once it is done (SUCCEEDED), and Apple can take it back (REVERSED, `REFUND_REVERSED`).
+ */
+export declare const REFUND_STATUSES: readonly ['PENDING', 'SUCCEEDED', 'FAILED', 'CANCELED', 'REVERSED'];
+export type RefundStatus = (typeof REFUND_STATUSES)[number];
+/**
+ * Where a refund may move from the status it has. Notifications arrive out of order and are
+ * redelivered, so a status only ever moves forward along these edges:
+ * - PENDING settles into anything (Stripe: succeeded / failed / canceled).
+ * - SUCCEEDED can still become FAILED (Stripe: the money could not be returned after all) or
+ *   REVERSED (Apple: REFUND_REVERSED).
+ * - FAILED, CANCELED and REVERSED are final: nothing a platform sends afterwards reopens them.
+ * Nothing moves back to PENDING, and a status never "moves" to itself (a redelivery is a no-op).
+ */
+export declare const REFUND_STATUS_TRANSITIONS: Readonly<Record<RefundStatus, readonly RefundStatus[]>>;
+/**
+ * Stripe's dispute statuses, as they are: the `warning_*` ones are inquiries and early fraud
+ * warnings that may never become a chargeback, `prevented` is one Stripe blocked before it was
+ * filed. Only LOST costs money. Stripe only: Apple and Google absorb chargebacks themselves and
+ * report them as refunds.
+ */
+export declare const DISPUTE_STATUSES: readonly ['WARNING_NEEDS_RESPONSE', 'WARNING_UNDER_REVIEW', 'WARNING_CLOSED', 'NEEDS_RESPONSE', 'UNDER_REVIEW', 'PREVENTED', 'WON', 'LOST'];
+export type DisputeStatus = (typeof DISPUTE_STATUSES)[number];
+/** A dispute in one of these is over; nothing Stripe sends afterwards reopens it. */
+export declare const CLOSED_DISPUTE_STATUSES: readonly DisputeStatus[];
 /**
  * [Stripe Subscription Status](https://stripe.com/docs/api/subscriptions/object#subscription_object-status)
  * [Stripe Subscription Lifecycle](https://docs.stripe.com/billing/subscriptions/overview)

package/dist/subscription/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/subscription/index.ts"],"mappings":";qBAAa;YAED,mBAAmB;;;;;;;qBAQlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAkJD,6BAA6B;;qBAG5B;;qBAOA;;;;;;;YASD,gCAAgC;;qBAG/B;YAWD,+BAA+B;qBAE9B;YAED,4BAA4B;;;;;;;;;;;;;;;iBAgBvB;GACd;EACD,YAAY;EACZ;EACA,WAAW;EACX;EACA,oBAAoB"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/subscription/index.ts"],"mappings":";qBAAa;YAED,mBAAmB;;;;;;;;;;qBAWlB;YAOD,sBAAsB;;;;;qBAMrB;YAED,uBAAuB;;;;;;;;;;qBAWtB,2BAA2B,SAAS,OAAO,uBAAuB;;;;;;;qBAclE;YAWD,wBAAwB;;qBAGvB,kCAAkC;;;;;;;qBAalC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAkJD,6BAA6B;;qBAG5B;;qBAOA;;;;;;;YASD,gCAAgC;;qBAG/B;YAWD,+BAA+B;qBAE9B;YAED,4BAA4B;;;;;;;;;;;;;;;iBAgBvB;GACd;EACD,YAAY;EACZ;EACA,WAAW;EACX;EACA,oBAAoB"}

package/dist/subscription/index.mjs

@@ -5,6 +5,76 @@ const PLATFORMS = [
 	"STRIPE"
 ];
 /**
+* What a payment was for, on every platform.
+*
+* - ONE_TIME: a one-time purchase.
+* - SUBSCRIPTION_START: the first paid charge of a subscription.
+* - SUBSCRIPTION_RENEWAL: a charge for a new billing period on the regular cycle.
+* - SUBSCRIPTION_UPDATE: a charge mid-period, outside the cycle: the proration of a plan change, or
+*   a manual invoice on the subscription. Kept apart from renewals so renewal rates stay honest.
+*/
+const PAYMENT_TYPES = [
+	"ONE_TIME",
+	"SUBSCRIPTION_START",
+	"SUBSCRIPTION_RENEWAL",
+	"SUBSCRIPTION_UPDATE"
+];
+/**
+* Where a refund stands, on every platform. Stripe reports all of them; Apple and Google report a
+* refund once it is done (SUCCEEDED), and Apple can take it back (REVERSED, `REFUND_REVERSED`).
+*/
+const REFUND_STATUSES = [
+	"PENDING",
+	"SUCCEEDED",
+	"FAILED",
+	"CANCELED",
+	"REVERSED"
+];
+/**
+* Where a refund may move from the status it has. Notifications arrive out of order and are
+* redelivered, so a status only ever moves forward along these edges:
+* - PENDING settles into anything (Stripe: succeeded / failed / canceled).
+* - SUCCEEDED can still become FAILED (Stripe: the money could not be returned after all) or
+*   REVERSED (Apple: REFUND_REVERSED).
+* - FAILED, CANCELED and REVERSED are final: nothing a platform sends afterwards reopens them.
+* Nothing moves back to PENDING, and a status never "moves" to itself (a redelivery is a no-op).
+*/
+const REFUND_STATUS_TRANSITIONS = {
+	PENDING: [
+		"SUCCEEDED",
+		"FAILED",
+		"CANCELED",
+		"REVERSED"
+	],
+	SUCCEEDED: ["FAILED", "REVERSED"],
+	FAILED: [],
+	CANCELED: [],
+	REVERSED: []
+};
+/**
+* Stripe's dispute statuses, as they are: the `warning_*` ones are inquiries and early fraud
+* warnings that may never become a chargeback, `prevented` is one Stripe blocked before it was
+* filed. Only LOST costs money. Stripe only: Apple and Google absorb chargebacks themselves and
+* report them as refunds.
+*/
+const DISPUTE_STATUSES = [
+	"WARNING_NEEDS_RESPONSE",
+	"WARNING_UNDER_REVIEW",
+	"WARNING_CLOSED",
+	"NEEDS_RESPONSE",
+	"UNDER_REVIEW",
+	"PREVENTED",
+	"WON",
+	"LOST"
+];
+/** A dispute in one of these is over; nothing Stripe sends afterwards reopens it. */
+const CLOSED_DISPUTE_STATUSES = [
+	"WON",
+	"LOST",
+	"WARNING_CLOSED",
+	"PREVENTED"
+];
+/**
 * [Stripe Subscription Status](https://stripe.com/docs/api/subscriptions/object#subscription_object-status)
 * [Stripe Subscription Lifecycle](https://docs.stripe.com/billing/subscriptions/overview)
 *
@@ -55,6 +125,6 @@ const RESUBSCRIBE_INTENTS = [
 	"yes"
 ];
 //#endregion
-export { AVAILABLE_STATUSES, CANCELLATION_FEEDBACKS, CANCELLATION_INITIATORS, PLATFORMS, RESUBSCRIBE_INTENTS, SUBSCRIPTION_STATUSES };
+export { AVAILABLE_STATUSES, CANCELLATION_FEEDBACKS, CANCELLATION_INITIATORS, CLOSED_DISPUTE_STATUSES, DISPUTE_STATUSES, PAYMENT_TYPES, PLATFORMS, REFUND_STATUSES, REFUND_STATUS_TRANSITIONS, RESUBSCRIBE_INTENTS, SUBSCRIPTION_STATUSES };
 
 //# sourceMappingURL=index.mjs.map