@happyvertical/smrt-commerce 0.51.29 → 0.51.31

package/AGENTS.md

@@ -31,7 +31,13 @@ for usage.
 - **Port, not provider.** Period close, events, and credit checkout call only
   the `BillingProvider` port (integer minor units). `stripe.ts` adapts
   `@happyvertical/accounting`, which takes currency *major* units; convert with
-  `units.ts` (ISO 4217 exponent) and never hand-roll a Stripe call here.
+  `units.ts` and never hand-roll a Stripe call here. `units.ts` exponents are
+  an explicit ISO 4217 table matching the SDK's, never `Intl` display digits
+  (CLDR differs for IQD, MGA, … and drifts by ICU release). The SDK's
+  `*Minor` fields are already ISO minor units. Capabilities a rail may lack
+  (`chargeSavedPaymentMethod`, `createSetupCheckout`, `getCheckout`,
+  `setDefaultPaymentMethod`, `markInvoiceUncollectible`) are optional port
+  methods: detect them by presence, and keep additions optional (#3139).
   `sendAndReconcile` refuses a provider invoice whose subtotal or total
   disagrees with the local invoice.
 - **Replay safety is identity.** Close, invoice, line, payment, allocation,
@@ -70,20 +76,35 @@ for usage.
   and only `smrt_*` checkout metadata is kept; it is
   HMAC-signed with the webhook secret at creation (empty values are omitted:
   Stripe drops them), so another integration on the same account cannot forge
-  a credit purchase; credit is granted only when the collected total equals
-  it. Rotating the webhook secret strands in-flight checkouts (up to 24 h). `observe()` re-reads provider state, so
-  ordering never depends on delivery order. The standing hook runs inside the
-  event transaction and must be idempotent.
+  a credit purchase or a card setup; credit is granted only when the
+  collected total equals it plus provider tax. Checkout amounts come from the
+  re-read session (`getCheckout()`), never the Stripe event, whose amounts are
+  in Stripe's unit. Rotating the webhook secret strands in-flight checkouts
+  (up to 24 h). `observe()` re-reads provider state, so ordering never depends
+  on delivery order; the only provider writes in `observe()` are idempotent
+  (making a saved card the default). The standing hook runs inside the event
+  transaction and must be idempotent.
+- **Card on file and top-ups (#3139).** A saved card is the payer customer's
+  default `PaymentInstrument` (seller tenant, id from the provider method).
+  `autoChargeInvoices` bills such payers `charge_automatically`, decided at
+  first push; activation follows `paid`, never send. An auto top-up attempt
+  is a `PENDING` `Payment` (`reference` `auto-top-up:<policyId>`, id from the
+  policy and `count()` of its attempts) inserted before the charge, so racing
+  evaluations derive one id and one charge; the charge key is derived from
+  that id. `applyAutoTopUpOutcome()` must run in a transaction and starts with
+  a conditional `UPDATE … WHERE status = 'pending'` row lock, so the hook and
+  the `payment` webhook settle once; the grant is keyed by the charge key.
+  Never settle an attempt outside that function. Taxed accounts are skipped
+  unless `taxedAccounts: 'charge_untaxed'` (no tax on off-session charges,
+  happyvertical/sdk#1283). A provider write-off moves the local invoice to
+  `WRITTEN_OFF` (a later payment is recorded; the status stays).
 - **`Invoice.providerTaxAmount`** is added to line-item tax; it is
   server-managed (not API-writable). `toAccountingInput()` emits major units.
-- **Known limits** (each tracked upstream): provider customer creation is not
-  idempotent (happyvertical/sdk#1268); credit checkouts are untaxed and
-  two-decimal only (sdk#1269); `autoTopUp` cannot charge a saved card
-  (sdk#1270); Stripe line discounts and uncollectible status are worked around
-  as negative lines and event types (sdk#1271). `RetailCharge` has no
-  adjustment ledger. Flat plans are monthly, in arrears; plan changes are not
-  prorated (#3119). The Stripe adapter passes line service periods but
-  the accounting SDK does not send them to Stripe yet (happyvertical/sdk#1274).
+- **Known limits**: write-offs post no bad-debt journal (AR stays until paid
+  or journaled by an operator); discounts still reach Stripe as negative lines (the SDK's
+  line `discount` would change the lines a replayed push reconciles, so it
+  needs its own migration); `RetailCharge` has no adjustment ledger. Flat
+  plans are monthly, in arrears; plan changes are not prorated (#3119).
 
 ## Cross-Package References
 

package/README.md

@@ -153,6 +153,7 @@ minor units.
 
 ```ts
 import { getAccountingProvider } from '@happyvertical/accounting';
+import { SpendingPolicyEvaluator } from '@happyvertical/smrt-subscriptions';
 import {
   BillingRuntime,
   createStripeBillingProvider,
@@ -210,14 +211,36 @@ if (intake.type?.endsWith(':unverified_credit_purchase')) {
 }
 await billing.processEvents(); // or enqueueBillingEvents({ runtime: 'platform' })
 
-// Prepaid credit through provider checkout.
+// Prepaid credit through provider checkout: tax is added on top when the
+// payer's account is taxed; `savePaymentMethod` keeps the card for top-ups.
 const { url } = await billing.createCreditCheckout({
   spendingPolicyId,
   amount: 5000,
   purchaseId: cartId,
+  savePaymentMethod: true,
   successUrl,
   cancelUrl,
 });
+
+// Card on file at signup: a setup checkout that charges nothing. Its
+// completion event makes the card the payer's default and adopts the billing
+// address collected at checkout as the tax location.
+const setup = await billing.createCardSetupCheckout({
+  payerTenantId,
+  currency: 'CAD',
+  setupId: signupId,
+  successUrl,
+  cancelUrl,
+});
+
+// Automatic top-ups: charge the saved card when a balance would run out.
+// Accounts are taxed by default (`automaticTax`), and a taxed account is not
+// topped up (no tax on off-session charges, sdk#1283): set
+// `automaticTax: false` on the account or pass `taxedAccounts: 'charge_untaxed'`.
+const evaluator = await SpendingPolicyEvaluator.create({
+  db,
+  autoTopUp: billing.autoTopUpHook({ amount: () => 2500 }),
+});
 ```
 
 - **What is billed.** A `provider` runtime bills `ClientCharge`s (and their
@@ -284,9 +307,8 @@ const { url } = await billing.createCreditCheckout({
   with its own service period. Stop workers running a pre-#3116 version
   before relying on this: they claim flat plans outside the numbering.
 - **Service periods.** Each flat-plan invoice line carries its billed window
-  as `periodStart`/`periodEnd`, down to the provider port. The Stripe adapter
-  passes them on; `@happyvertical/accounting` does not send them to Stripe yet
-  (happyvertical/sdk#1274).
+  as `periodStart`/`periodEnd`, down to the provider port and on to Stripe's
+  invoice item `period`.
 - **Upgrading to #3116.** Additive schema only: `_smrt_billing_accounts` gains
   `billing_anchor_at` (nullable) and `prorate_flat_plans` (default false), and
   `_smrt_billing_line_sources` gains `chain_sequence` (default 0) and an index
@@ -299,11 +321,57 @@ const { url } = await billing.createCreditCheckout({
 - **Events** are verified, stored in smrt-jobs' durable delivery inbox, and
   applied against current provider state: paid invoices record a payment and
   allocation; failures and overdue notices mark the payer `past_due` and its
-  flat-plan subscriptions `past_due`; payment reinstates them. Dunning is the
-  provider's.
+  flat-plan subscriptions `past_due`; an invoice written off at the provider
+  (`markInvoiceUncollectible(invoiceId)`, or in Stripe) is written off
+  locally and marks the payer `uncollectible` (no bad-debt journal is
+  posted; AR stays until it is paid or an operator journals it); payment
+  reinstates them, including a late payment of the written-off invoice. Dunning is the provider's.
+  Subscribe the webhook endpoint to `invoice.*`, `customer.subscription.*`,
+  `checkout.session.completed`, `checkout.session.async_payment_succeeded`,
+  and `payment_intent.*`.
 - **Prepaid credit** purchases credit a `period: 'balance'` spending policy
   once per checkout session, paid by the policy's tenant or, for a delegated
-  balance, the parent that set it.
+  balance, the parent that set it. Amounts are ISO 4217 minor units in any
+  currency the provider supports. When the payer's account is taxed
+  (`automaticTax`, not tax-exempt; override per call), provider tax is
+  charged on top and collected at checkout with the buyer's address: the
+  credit is the amount bought, the payment is the total collected, and the
+  tax is booked to the tax account. For a payer with a provider customer but
+  no local tax location, the address collected at checkout becomes its tax
+  location. `savePaymentMethod` requires a provider that can re-read the
+  checkout and set a default payment method, and is refused otherwise.
+- **Card on file (#3139).** `createCardSetupCheckout()` (or a credit purchase
+  with `savePaymentMethod`) saves the payer's card without charging it. On
+  completion the card becomes the provider customer's default and the
+  payer's default `PaymentInstrument`. When the checkout collected the billing
+  address (a taxed payer with no tax location), it becomes the payer's tax
+  location.
+- **Automatically charged invoices.** With `autoChargeInvoices: true` on the
+  runtime, a payer with a default card is invoiced `charge_automatically`:
+  the provider charges the card after the invoice is sent, on its own
+  schedule, and retries failures. Activate service on the `current` standing
+  from the `paid` event, not on send; a failure marks the payer `past_due`.
+- **Automatic top-ups.** Taxed accounts (the default: `automaticTax` on, not
+  tax-exempt) are never topped up unless the hook is built with
+  `taxedAccounts: 'charge_untaxed'`, because an off-session charge carries no
+  tax yet (happyvertical/sdk#1283); the skip is silent (no attempt row).
+  `billing.autoTopUpHook()` is the `autoTopUp` hook for
+  `SpendingPolicyEvaluator`: when a balance would run out it charges the
+  payer's saved card off-session (the delegating parent's, for a delegated
+  balance) and credits the balance only when the charge succeeds. A charge
+  still processing is credited from its `payment_intent.succeeded` event; a
+  decline or an authentication requirement credits nothing, closes the
+  attempt, and calls the runtime's `onAutoTopUpFailed` (ask the payer to
+  re-save their card with a setup checkout). One attempt runs per policy at a
+  time, retries of a declined card wait `retryAfterMs` (default one hour),
+  and the credit is granted exactly once however the outcome arrives. An
+  off-session charge carries no tax (happyvertical/sdk#1283), so taxed
+  accounts are not topped up unless the seller passes
+  `taxedAccounts: 'charge_untaxed'`; they buy credit through checkout.
+- **Upgrading to #3139.** Requires `@happyvertical/accounting` 0.92 or later.
+  No schema change. Credit checkouts are now taxed for taxed accounts (pass
+  `automaticTax: false` to keep them untaxed), and Stripe customers are
+  created idempotently.
 
 See [`AGENTS.md`](./AGENTS.md#billing-period-close-3060) for invariants and
 known limits.

package/dist/billing/cards.d.ts

@@ -0,0 +1,64 @@
+import { DatabaseInterface } from '@happyvertical/smrt-core/migrations';
+import { BillingAccount } from '../models/billing.js';
+import { BillingProviderCheckoutSession, BillingProviderCheckoutState } from './provider.js';
+import { BillingRuntime } from './runtime.js';
+export declare const CARD_SETUP_PURPOSE = "card_setup";
+/** Checkout metadata flag: the session saves its payment method. */
+export declare const SAVE_CARD_METADATA = "smrt_save_card";
+/**
+ * Checkout metadata flag: the session collects the billing address, which is
+ * adopted as the payer's tax location when the card is saved.
+ */
+export declare const COLLECT_ADDRESS_METADATA = "smrt_collect_address";
+export interface CreateCardSetupCheckoutInput {
+    payerTenantId: string;
+    /** The currency the saved card will be charged in. */
+    currency: string;
+    successUrl: string;
+    cancelUrl: string;
+    /**
+     * Caller-owned id for this setup attempt. A retried request with the same
+     * id returns the same checkout; a new attempt (for example after a declined
+     * card) needs a new id.
+     */
+    setupId: string;
+    /**
+     * Collect the billing address at checkout and adopt it as the payer's tax
+     * location. Default: when the account is taxed and has no tax location.
+     */
+    collectBillingAddress?: boolean;
+}
+/** Only the payer (or a system/operator context) manages its card. */
+export declare function assertPayerContext(payerTenantId: string): void;
+export declare function createCardSetupCheckout(runtime: BillingRuntime, input: CreateCardSetupCheckoutInput): Promise<BillingProviderCheckoutSession>;
+/**
+ * What a completed checkout saved for one of this seller's accounts: a card
+ * (setup, or a purchase with `savePaymentMethod`) and/or a billing address it
+ * was asked to collect. Validated against the account.
+ */
+export interface SavedCard {
+    account: BillingAccount;
+    providerCustomerId: string;
+    paymentMethodId?: string;
+    billingAddress?: BillingProviderCheckoutState['billingAddress'];
+}
+/** Whether the provider can apply a saved card from a checkout event. */
+export declare function assertCanSaveCards(runtime: BillingRuntime): void;
+/**
+ * The card and/or collected address a completed checkout saved for one of
+ * this seller's accounts, or null when it saved neither. Throws when the
+ * session and its (verified) metadata disagree, so the event dead-letters
+ * visibly.
+ */
+export declare function savedCardFromCheckout(runtime: BillingRuntime, metadata: Record<string, string>, state: BillingProviderCheckoutState, savesCard: boolean): Promise<SavedCard | null>;
+/**
+ * Record a saved card as the customer's default instrument, and adopt a
+ * collected billing address. Idempotent; runs in the event transaction.
+ */
+export declare function recordSavedCard(runtime: BillingRuntime, db: DatabaseInterface, card: SavedCard): Promise<void>;
+/**
+ * Whether the payer's default card is with this runtime's provider customer:
+ * what `autoChargeInvoices` bills and automatic top-ups charge.
+ */
+export declare function defaultCardFor(runtime: BillingRuntime, account: BillingAccount, providerCustomerId: string): Promise<boolean>;
+//# sourceMappingURL=cards.d.ts.map

package/dist/billing/cards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cards.d.ts","sourceRoot":"","sources":["../../src/billing/cards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAU7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EACV,8BAA8B,EAC9B,4BAA4B,EAC7B,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQnD,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAC/C,oEAAoE;AACpE,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AACnD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAE/D,MAAM,WAAW,4BAA4B;IAC3C,aAAa,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAU9D;AAED,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,8BAA8B,CAAC,CA0CzC;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,cAAc,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,4BAA4B,CAAC,gBAAgB,CAAC,CAAC;CACjE;AAED,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAShE;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,KAAK,EAAE,4BAA4B,EACnC,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CA8B3B;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,cAAc,EACvB,EAAE,EAAE,iBAAiB,EACrB,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,IAAI,CAAC,CAYf;AA0CD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,cAAc,EACvB,kBAAkB,EAAE,MAAM,GACzB,OAAO,CAAC,OAAO,CAAC,CAUlB"}

package/dist/billing/credits.d.ts

@@ -15,6 +15,18 @@ export interface CreateCreditCheckoutInput {
     purchaseId: string;
     /** Checkout line description (default `Prepaid credit`). */
     description?: string;
+    /**
+     * Charge provider-calculated tax on top of the credit (#3139). Default:
+     * the payer's account setting (`automaticTax`, off for tax-exempt
+     * customers). The credit granted is always `amount`; tax is booked to the
+     * tax account.
+     */
+    automaticTax?: boolean;
+    /**
+     * Also save the card as the payer's default for automatic top-ups and
+     * automatically charged invoices (#3139).
+     */
+    savePaymentMethod?: boolean;
 }
 /** The checkout metadata a completed purchase is settled from. */
 export interface CreditPurchaseMetadata {

package/dist/billing/credits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credits.d.ts","sourceRoot":"","sources":["../../src/billing/credits.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQnD,eAAO,MAAM,uBAAuB,oBAAoB,CAAC;AAEzD,MAAM,WAAW,yBAAyB;IACxC,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAuBD,uEAAuE;AACvE,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC1B,sBAAsB,GAAG,IAAI,CAwB/B;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,8BAA8B,CAAC,CAgEzC"}
+{"version":3,"file":"credits.d.ts","sourceRoot":"","sources":["../../src/billing/credits.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQnD,eAAO,MAAM,uBAAuB,oBAAoB,CAAC;AAEzD,MAAM,WAAW,yBAAyB;IACxC,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAuBD,uEAAuE;AACvE,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC1B,sBAAsB,GAAG,IAAI,CAwB/B;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,8BAA8B,CAAC,CA4FzC"}

package/dist/billing/events.d.ts

@@ -1,5 +1,6 @@
 import { ForgeProjector } from '@happyvertical/smrt-jobs';
-import { BillingProviderEvent, BillingProviderInvoiceState, BillingProviderSubscriptionState } from './provider.js';
+import { SavedCard } from './cards.js';
+import { BillingProviderCheckoutState, BillingProviderEvent, BillingProviderInvoiceState, BillingProviderSubscriptionState } from './provider.js';
 import { BillingRuntime } from './runtime.js';
 type InvoiceEvent = Extract<BillingProviderEvent, {
     kind: 'invoice';
@@ -10,6 +11,9 @@ type SubscriptionEvent = Extract<BillingProviderEvent, {
 type CheckoutEvent = Extract<BillingProviderEvent, {
     kind: 'checkout_completed';
 }>;
+type PaymentEvent = Extract<BillingProviderEvent, {
+    kind: 'payment';
+}>;
 type ObservedEvent = {
     event: InvoiceEvent;
     invoice: BillingProviderInvoiceState;
@@ -18,6 +22,13 @@ type ObservedEvent = {
     subscription: BillingProviderSubscriptionState;
 } | {
     event: CheckoutEvent;
+    /** The session re-read from the provider, when it can be. */
+    checkout: BillingProviderCheckoutState | null;
+    /** A card the session saved, already the provider default. */
+    card: SavedCard | null;
+} | {
+    event: PaymentEvent;
+    paymentId: string;
 };
 /** Apply up to `limit` queued events for a runtime; returns how many ran. */
 export declare function processBillingEvents(runtime: BillingRuntime, limit: number): Promise<number>;

package/dist/billing/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/billing/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,0BAA0B,CAAC;AAoBlC,OAAO,KAAK,EACV,oBAAoB,EACpB,2BAA2B,EAC3B,gCAAgC,EACjC,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQnD,KAAK,YAAY,GAAG,OAAO,CAAC,oBAAoB,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC;AACvE,KAAK,iBAAiB,GAAG,OAAO,CAC9B,oBAAoB,EACpB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,CACzB,CAAC;AACF,KAAK,aAAa,GAAG,OAAO,CAC1B,oBAAoB,EACpB;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAC/B,CAAC;AAEF,KAAK,aAAa,GACd;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,2BAA2B,CAAA;CAAE,GAC7D;IACE,KAAK,EAAE,iBAAiB,CAAC;IACzB,YAAY,EAAE,gCAAgC,CAAC;CAChD,GACD;IAAE,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC;AAI7B,6EAA6E;AAC7E,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,cAAc,GACtB,cAAc,CAAC,aAAa,CAAC,CA+D/B"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/billing/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,0BAA0B,CAAC;AAoBlC,OAAO,EAKL,KAAK,SAAS,EAEf,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EACV,4BAA4B,EAC5B,oBAAoB,EACpB,2BAA2B,EAC3B,gCAAgC,EACjC,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAInD,KAAK,YAAY,GAAG,OAAO,CAAC,oBAAoB,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC;AACvE,KAAK,iBAAiB,GAAG,OAAO,CAC9B,oBAAoB,EACpB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,CACzB,CAAC;AACF,KAAK,aAAa,GAAG,OAAO,CAC1B,oBAAoB,EACpB;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAC/B,CAAC;AACF,KAAK,YAAY,GAAG,OAAO,CAAC,oBAAoB,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC;AAEvE,KAAK,aAAa,GACd;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,2BAA2B,CAAA;CAAE,GAC7D;IACE,KAAK,EAAE,iBAAiB,CAAC;IACzB,YAAY,EAAE,gCAAgC,CAAC;CAChD,GACD;IACE,KAAK,EAAE,aAAa,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,EAAE,4BAA4B,GAAG,IAAI,CAAC;IAC9C,8DAA8D;IAC9D,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;CACxB,GACD;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAI/C,6EAA6E;AAC7E,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,cAAc,GACtB,cAAc,CAAC,aAAa,CAAC,CAiF/B"}

package/dist/billing/index.d.ts

@@ -1,14 +1,16 @@
 /**
- * Billing-period close, provider events, and prepaid credit purchases
- * (#3060).
+ * Billing-period close, provider events, prepaid credit purchases (#3060),
+ * card on file, and automatic top-ups (#3139).
  * @packageDocumentation
  */
+export type { CreateCardSetupCheckoutInput } from './cards.js';
 export type { CreateCreditCheckoutInput } from './credits.js';
 export { addBillingMonths, billingPeriodContaining, lastEndedBillingPeriod, prorateMinorUnits, type ScheduledBillingPeriod, } from './cycles.js';
 export { type EnqueueBillingJobOptions, enqueueBillingEvents, enqueueBillingPeriodClose, getBillingRuntime, registerBillingRuntime, unregisterBillingRuntime, } from './jobs.js';
 export { type BillingPeriod, BillingPeriodCloseError, type ClosePeriodInput, type PeriodCloseGroupResult, type PeriodCloseOutcome, type PeriodCloseResult, previousCalendarMonth, } from './period-close.js';
-export { type BillingInvoiceEventType, type BillingProvider, type BillingProviderCheckoutInput, type BillingProviderCheckoutSession, type BillingProviderCustomerInput, type BillingProviderEvent, type BillingProviderInvoiceInput, type BillingProviderInvoiceLine, type BillingProviderInvoiceState, type BillingProviderInvoiceStatus, type BillingProviderSubscriptionState, BillingWebhookVerificationError, } from './provider.js';
-export { type BillingLedgerAccounts, BillingRuntime, type BillingRuntimeOptions, type PayerStandingChange, type PayerStandingHook, type SyncedBillingAccount, type UpsertBillingAccountInput, } from './runtime.js';
+export { type BillingChargeStatus, type BillingCollectionMethod, type BillingInvoiceEventType, type BillingProvider, type BillingProviderChargeInput, type BillingProviderChargeResult, type BillingProviderCheckoutInput, type BillingProviderCheckoutSession, type BillingProviderCheckoutState, type BillingProviderCustomerInput, type BillingProviderEvent, type BillingProviderInvoiceInput, type BillingProviderInvoiceLine, type BillingProviderInvoiceState, type BillingProviderInvoiceStatus, type BillingProviderSetupCheckoutInput, type BillingProviderSubscriptionState, BillingWebhookVerificationError, } from './provider.js';
+export { type BillingLedgerAccounts, BillingRuntime, type BillingRuntimeOptions, type EnsureProviderCustomerOptions, type PayerStandingChange, type PayerStandingHook, type SyncedBillingAccount, type UpsertBillingAccountInput, } from './runtime.js';
 export { createStripeBillingProvider, type StripeBillingProviderOptions, } from './stripe.js';
+export type { AutoTopUpFailure, AutoTopUpFailureHook, AutoTopUpHookOptions, } from './top-up.js';
 export { currencyMinorUnitExponent, majorToMinorUnits, minorToMajorUnits, } from './units.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/billing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/billing/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,wBAAwB,EAC7B,oBAAoB,EACpB,yBAAyB,EACzB,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,aAAa,EAClB,uBAAuB,EACvB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,KAAK,4BAA4B,EACjC,KAAK,8BAA8B,EACnC,KAAK,4BAA4B,EACjC,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,EACjC,KAAK,gCAAgC,EACrC,+BAA+B,GAChC,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,qBAAqB,EAC1B,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,GAC/B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,2BAA2B,EAC3B,KAAK,4BAA4B,GAClC,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/billing/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAC/D,YAAY,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,wBAAwB,EAC7B,oBAAoB,EACpB,yBAAyB,EACzB,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,aAAa,EAClB,uBAAuB,EACvB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,EACjC,KAAK,8BAA8B,EACnC,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,EACjC,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,EACjC,KAAK,iCAAiC,EACtC,KAAK,gCAAgC,EACrC,+BAA+B,GAChC,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,qBAAqB,EAC1B,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,EAClC,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,GAC/B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,2BAA2B,EAC3B,KAAK,4BAA4B,GAClC,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/billing/period-close.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"period-close.d.ts","sourceRoot":"","sources":["../../src/billing/period-close.ts"],"names":[],"mappings":"AA4CA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQnD,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,WAAW,EAAE,IAAI,CAAC;IAClB,8DAA8D;IAC9D,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,iDAAiD;IACjD,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,MAAM,kBAAkB,GAC1B,WAAW,GACX,OAAO,GACP,MAAM,GACN,iBAAiB,GACjB,QAAQ,CAAC;AAEb,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,WAAW,EAAE,IAAI,CAAC;IAClB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,sBAAsB,EAAE,CAAC;CAClC;AAED,yEAAyE;AACzE,qBAAa,uBAAwB,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,EAAE,iBAAiB;gBAAzB,MAAM,EAAE,iBAAiB;CAW/C;AAmDD,4DAA4D;AAC5D,wBAAgB,qBAAqB,CAAC,GAAG,OAAa,GAAG,aAAa,CAQrE;AAkCD,wBAAgB,aAAa,CAC3B,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,gBAAgB,GAAG,MAAM,CAAC,EACxD,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAsED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,cAAc,EACvB,KAAK,GAAE,gBAAqB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CAwE5B"}
+{"version":3,"file":"period-close.d.ts","sourceRoot":"","sources":["../../src/billing/period-close.ts"],"names":[],"mappings":"AA6CA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQnD,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,WAAW,EAAE,IAAI,CAAC;IAClB,8DAA8D;IAC9D,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,iDAAiD;IACjD,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,MAAM,kBAAkB,GAC1B,WAAW,GACX,OAAO,GACP,MAAM,GACN,iBAAiB,GACjB,QAAQ,CAAC;AAEb,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,WAAW,EAAE,IAAI,CAAC;IAClB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,sBAAsB,EAAE,CAAC;CAClC;AAED,yEAAyE;AACzE,qBAAa,uBAAwB,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,EAAE,iBAAiB;gBAAzB,MAAM,EAAE,iBAAiB;CAW/C;AAmDD,4DAA4D;AAC5D,wBAAgB,qBAAqB,CAAC,GAAG,OAAa,GAAG,aAAa,CAQrE;AAkCD,wBAAgB,aAAa,CAC3B,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,gBAAgB,GAAG,MAAM,CAAC,EACxD,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAsED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,cAAc,EACvB,KAAK,GAAE,gBAAqB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CAwE5B"}

package/dist/billing/provider.d.ts

@@ -18,6 +18,14 @@ export interface BillingProviderInvoiceLine {
     periodStart?: Date;
     periodEnd?: Date;
 }
+/**
+ * How the provider collects an invoice. `charge_automatically` charges the
+ * payer's saved default payment method after the invoice is sent, on the
+ * provider's own schedule; the outcome arrives as a `paid` or
+ * `payment_failed` event. A provider that cannot pull funds from a saved
+ * method must reject it, never fall back to `send_invoice`.
+ */
+export type BillingCollectionMethod = 'send_invoice' | 'charge_automatically';
 export interface BillingProviderInvoiceInput {
     /** Local invoice id; the provider tags its invoice with it. */
     invoiceId: string;
@@ -33,9 +41,15 @@ export interface BillingProviderInvoiceInput {
     idempotencyKey: string;
     /** Ask the provider to calculate tax from the customer's tax location. */
     automaticTax: boolean;
+    /** Default `send_invoice` (#3139). */
+    collectionMethod?: BillingCollectionMethod;
     memo?: string;
 }
-export type BillingProviderInvoiceStatus = 'draft' | 'open' | 'paid' | 'void';
+/**
+ * `uncollectible` is an open balance the seller wrote off (#3139); it can
+ * still be paid or voided later.
+ */
+export type BillingProviderInvoiceStatus = 'draft' | 'open' | 'paid' | 'void' | 'uncollectible';
 export interface BillingProviderInvoiceState {
     providerInvoiceId: string;
     status: BillingProviderInvoiceStatus;
@@ -70,11 +84,88 @@ export interface BillingProviderCheckoutInput {
     cancelUrl: string;
     /** Opaque values returned verbatim on the completion event. */
     metadata: Record<string, string>;
+    /**
+     * Charge provider-calculated tax on top of `amount` (#3139). The buyer's
+     * tax location is collected at checkout when the customer has none.
+     */
+    automaticTax?: boolean;
+    /**
+     * Also save the payment method for later off-session charges (for example
+     * automatic top-ups). Requires `providerCustomerId`.
+     */
+    savePaymentMethod?: boolean;
 }
 export interface BillingProviderCheckoutSession {
     sessionId: string;
     url: string | null;
 }
+/** A checkout that saves a payment method without charging (#3139). */
+export interface BillingProviderSetupCheckoutInput {
+    /** Stable key reused when retrying the same checkout creation. */
+    idempotencyKey: string;
+    providerCustomerId: string;
+    /** The currency the saved method will be charged in. */
+    currency: string;
+    successUrl: string;
+    cancelUrl: string;
+    /** Collect the billing address (tax location) and save it to the customer. */
+    collectBillingAddress: boolean;
+    /** Opaque values returned verbatim on the completion event. */
+    metadata: Record<string, string>;
+}
+/** A checkout session as the provider reports it now (#3139). */
+export interface BillingProviderCheckoutState {
+    sessionId: string;
+    mode: 'payment' | 'setup' | 'other';
+    /** The session completed (paid, or a payment method was saved). */
+    complete: boolean;
+    /** A payment-mode session collected its money. */
+    paid: boolean;
+    providerCustomerId?: string;
+    /** The payment method the session collected. */
+    paymentMethodId?: string;
+    currency?: string;
+    /** Line amount before discounts and tax, minor units. */
+    amountSubtotal?: number;
+    /** Provider-calculated tax, minor units. */
+    amountTax?: number;
+    /** Amount collected, minor units. */
+    amountTotal?: number;
+    /**
+     * The customer's billing address after a completed session that was asked
+     * to collect one.
+     */
+    billingAddress?: Address;
+}
+/**
+ * The outcome of an off-session charge (#3139). `processing` settles later
+ * through a `payment` event; `requires_action` (the issuer wants the payer
+ * present), `failed`, and `canceled` charged nothing.
+ */
+export type BillingChargeStatus = 'succeeded' | 'processing' | 'requires_action' | 'failed' | 'canceled';
+export interface BillingProviderChargeInput {
+    providerCustomerId: string;
+    /** Positive integer minor units. */
+    amount: number;
+    currency: string;
+    /**
+     * Stable key for this logical charge. Every retry with it returns the
+     * original charge; a new attempt needs a new key.
+     */
+    idempotencyKey: string;
+    description?: string;
+    metadata?: Record<string, string>;
+}
+export interface BillingProviderChargeResult {
+    status: BillingChargeStatus;
+    /** The provider payment id, when one was created. */
+    providerPaymentId?: string;
+    /** Minor units. */
+    amount: number;
+    currency: string;
+    failureCode?: string;
+    failureMessage?: string;
+}
 /** Invoice lifecycle changes this package acts on. */
 export type BillingInvoiceEventType = 'paid' | 'payment_failed' | 'overdue' | 'uncollectible' | 'voided';
 /** A verified provider event, normalized and stripped of customer data. */
@@ -91,14 +182,35 @@ export type BillingProviderEvent = {
     kind: 'checkout_completed';
     eventId: string;
     sessionId: string;
+    /** `payment` (credit purchase) or `setup` (card on file, #3139). */
+    mode?: 'payment' | 'setup';
     /** Only `paid` sessions settle a credit purchase. */
     paid: boolean;
     currency: string;
-    /** Line-item amount before discounts and tax, minor units. */
-    amountSubtotal: number;
+    /**
+     * Line-item amount before discounts and tax, minor units. Omitted by a
+     * provider whose event amounts are not minor units; `observe()` then
+     * re-reads the session with `getCheckout()`.
+     */
+    amountSubtotal?: number;
+    /** Provider-calculated tax, minor units. */
+    amountTax?: number;
     /** Amount actually collected (after discounts, with tax), minor units. */
-    amountTotal: number;
+    amountTotal?: number;
     metadata: Record<string, string>;
+} | {
+    /** An off-session charge made by `chargeSavedPaymentMethod` (#3139). */
+    kind: 'payment';
+    eventId: string;
+    /** The `idempotencyKey` the charge was made with. */
+    chargeKey: string;
+    status: BillingChargeStatus;
+    providerPaymentId: string;
+    providerCustomerId?: string;
+    /** Minor units, when the provider amount converts exactly. */
+    amount?: number;
+    currency?: string;
+    failureCode?: string;
 } | {
     kind: 'ignored';
     eventId: string;
@@ -129,6 +241,20 @@ export interface BillingProvider {
      * anything verified but not actionable is returned as `ignored`.
      */
     verifyWebhook(payload: string, signature: string): Promise<BillingProviderEvent>;
+    /**
+     * Charge the customer's saved default payment method off-session,
+     * idempotently by `input.idempotencyKey`. A decline or an authentication
+     * requirement is a result, not a throw.
+     */
+    chargeSavedPaymentMethod?(input: BillingProviderChargeInput): Promise<BillingProviderChargeResult>;
+    /** Start a checkout that saves a payment method without charging. */
+    createSetupCheckout?(input: BillingProviderSetupCheckoutInput): Promise<BillingProviderCheckoutSession>;
+    /** Re-read a checkout session, with amounts in minor units. */
+    getCheckout?(sessionId: string): Promise<BillingProviderCheckoutState>;
+    /** Make a saved payment method the customer's default. Idempotent. */
+    setDefaultPaymentMethod?(providerCustomerId: string, paymentMethodId: string): Promise<void>;
+    /** Write an open invoice off as uncollectible. Idempotent. */
+    markInvoiceUncollectible?(providerInvoiceId: string): Promise<void>;
 }
 export declare class BillingWebhookVerificationError extends Error {
     constructor(message?: string);

package/dist/billing/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/billing/provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/billing/provider.ts"],"names":[],"mappings":"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"}