@fantastic.dev/better-stripe 0.10.2 → 0.12.0

package/CHANGELOG.md

@@ -14,6 +14,29 @@
 - Remove internal tracker references from public documentation and add a
   regression check that prevents their reintroduction.
 
+## [0.12.0](https://github.com/FantasticDevHQ/better-stripe/compare/v0.11.0...v0.12.0) (2026-10-15)
+
+### Features
+
+- **billing:** add consented balance funding operations ([#149](https://github.com/FantasticDevHQ/better-stripe/issues/149)) ([16434c4](https://github.com/FantasticDevHQ/better-stripe/commit/16434c4eeef343045b4ba66516221232dfa57e06))
+- **billing:** expose complete upcoming invoice previews ([#147](https://github.com/FantasticDevHQ/better-stripe/issues/147)) ([6d81cec](https://github.com/FantasticDevHQ/better-stripe/commit/6d81cec1b458fadbe4aeb69b9611d6ba208d87ce))
+- **recovery:** add durable cost claims and reservations ([#151](https://github.com/FantasticDevHQ/better-stripe/issues/151)) ([a958c3a](https://github.com/FantasticDevHQ/better-stripe/commit/a958c3aa12178de4f22c0c614b0b9e5d7eb37819))
+- **settlement:** expose complete processing cost context ([#150](https://github.com/FantasticDevHQ/better-stripe/issues/150)) ([3933d6b](https://github.com/FantasticDevHQ/better-stripe/commit/3933d6bf3c54181e8f7c27b35e6eb6802fb7c2d8))
+
+### Bug Fixes
+
+- **react:** preserve charge currency units in price cards ([#155](https://github.com/FantasticDevHQ/better-stripe/issues/155)) ([b0967ae](https://github.com/FantasticDevHQ/better-stripe/commit/b0967ae61ac8ae85adc4f2d8f375e2c71ad1464f))
+- **react:** preserve plan pricing currency units ([#156](https://github.com/FantasticDevHQ/better-stripe/issues/156)) ([f65e712](https://github.com/FantasticDevHQ/better-stripe/commit/f65e712a91dd55e6979ccea540627d4c437dfc6c))
+- **release:** keep generated notes public ([#153](https://github.com/FantasticDevHQ/better-stripe/issues/153)) ([d67f21a](https://github.com/FantasticDevHQ/better-stripe/commit/d67f21a6315c0498db7358b6b37669520037fefa))
+- **release:** preserve historical code examples ([#154](https://github.com/FantasticDevHQ/better-stripe/issues/154)) ([1c3c9f0](https://github.com/FantasticDevHQ/better-stripe/commit/1c3c9f0a63e7c5eb77e685dc0bb3963a4e7dc935))
+- **webhooks:** reconcile dedicated payout cancellations ([#152](https://github.com/FantasticDevHQ/better-stripe/issues/152)) ([9dd84e2](https://github.com/FantasticDevHQ/better-stripe/commit/9dd84e22473a35445a0445a82e8fcdf2eb9ace23))
+
+## [0.11.0](https://github.com/FantasticDevHQ/better-stripe/compare/v0.10.2...v0.11.0) (2026-10-14)
+
+### Features
+
+- add retry-safe catalog creation request keys ([#145](https://github.com/FantasticDevHQ/better-stripe/issues/145)) ([45b0d52](https://github.com/FantasticDevHQ/better-stripe/commit/45b0d52dfcb6577cf5df339721ed9eed34a83a1d))
+
 ## [0.10.2](https://github.com/FantasticDevHQ/better-stripe/compare/v0.10.1...v0.10.2) (2026-10-14)
 
 ### Bug Fixes

package/README.md

@@ -38,7 +38,7 @@ See the [customer preview setup and webhook migration guide](docs/accounts-v2-pr
 
 ## Status
 
-**Version**: `0.10.2` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
+**Version**: `0.12.0` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
 
 Used in production by its authors. Webhook pipeline is covered by unit tests and a live E2E harness (`npm run e2e:webhooks`) that fires real Stripe-signed events and asserts the ledger.
 
@@ -335,6 +335,201 @@ Methods named `get<Entity>` take the component document ID (exception: `getInvoi
 | `reactivateSubscription(ctx, { stripeSubscriptionId })`                                                                                                                                                                  | Reactivate a canceled subscription                                                                                                            |
 | `updateSubscriptionQuantity(ctx, { stripeSubscriptionId, quantity })`                                                                                                                                                    | Update subscription seat quantity                                                                                                             |
 
+### Durable recovery claims
+
+`stripe.costRecovery` is a server-only bookkeeping client. It uses the Convex
+component. Its calls do not use Stripe credentials; normal component installation
+configuration still applies. It never moves money. Your host authenticates the
+caller, approves which costs are owed, authorizes the account and recovery scope,
+and verifies provider outcomes before confirming collection. A recovery scope is
+an application-defined liability boundary, such as one store. Amounts are signed
+integer minor units and currencies never mix.
+
+```ts
+const recovery = stripe.costRecovery;
+const scope = {
+  accountId: sellerAccountId,
+  scopeKey: storeId,
+  currency: "usd",
+};
+await recovery.recordClaim(ctx, {
+  ...scope,
+  claimKey: `cost:${chargeId}`,
+  sourceChargeId: chargeId,
+  sourceGross: originalGross,
+  sourceProcessingFee: originalProviderFee,
+  amountDue: approvedCumulativeCost,
+  revision: durableObservationRevision,
+});
+const result = await recovery.reserve(ctx, {
+  ...scope,
+  groupKey: `settlement:${fundingChargeId}`,
+  operationKey: `settlement:${fundingChargeId}:batch:1`,
+  sourceKind: "settlement",
+  sourceId: fundingChargeId,
+  sourceGross: fundingGross,
+  sourceProcessingFee: fundingProviderFee,
+  maxDebit: availableSellerEarnings,
+  maxCredit: approvedCreditBudget,
+});
+```
+
+Claims retain their original charge, account, scope, currency, gross and provider
+fee. Replays of the same revision must have the same amount; lower revisions are
+ignored. The host must assign durable, monotonically increasing observation
+revisions from authoritative reconciliation, not an unordered event arrival
+counter. Use `getClaim(ctx, { claimKey })` to capture the prior revision before
+reading provider state, then propose the next revision. On a conflicting revision,
+retry the full provider reconciliation, rather than incrementing the revision of
+an already-stale snapshot. Later provider observations update cumulative `amountDue`, including
+signed credits, without erasing collected or reserved history. Claim keys beginning
+with `rollback:` are reserved by the package.
+
+Reservations use maintained totals across all claims, so a credit beyond the
+first history page still reduces the recoverable amount. Each call allocates at
+most 100 claims. Repeat with distinct, durable batch operation keys in the same
+group until `seal(ctx, { groupKey })` succeeds. The group's debit/credit budgets
+apply across all batches. A group identifies exactly one external money boundary;
+only one group per account/scope/currency may remain pending. Retry the same batch
+key to recover the same allocation after a timeout or host write failure.
+
+Seal before any provider side effect. New claim observations can require another
+batch before sealing; observations after sealing remain owed or credited for a
+later group. After verifying the provider's final result, call
+`finish(ctx, { groupKey, outcome: "collect" | "release" })`. Completion processes
+at most ten reservations per call, each with at most 100 claims. Repeat while
+`isDone` is false using separate action/job invocations when needed to respect
+Convex transaction limits. Completion is idempotent; a collected group cannot be
+released or reused with another outcome. Do not release an unknown provider
+outcome just because a request timed out. An unpaid invoice must stay reserved
+until its verified payment or cancellation policy resolves it.
+
+For a collected settlement group whose funding sale is later returned, call
+`rollback(ctx, { groupKey, returnedPrincipal, revision })` with the authorized
+cumulative principal. This records a separate, source-linked rollback claim,
+preserves the original costs and collection history, and rounds positive and
+negative amounts symmetrically. Reinstated principal can reduce the rollback
+again with a newer revision. This bookkeeping operation does not refund or
+reverse a transfer. Invoice funding requires a provider-aware adapter; this
+settlement rollback helper does not infer invoice payment allocations.
+
+Use `balance(ctx, scope)` for exact maintained totals and
+`listClaims(ctx, { ...scope, limit, cursor })` for paginated history. `getClaim`, `getGroup` and
+`getReservation` resume durable workflows. Integrate these server callbacks with
+the existing unstyled React `CostRecovery` display. These bookkeeping APIs leave
+consent, provider fee policy and entitlement changes in the host; provider invoice
+reconciliation and the example migration are separate work.
+
+### Refund and dispute processing costs
+
+`getProcessingCostContext(ctx, { paymentIntentId, stripeAccountId? })` reads
+provider costs for an authorized payment, including refunded and disputed
+charges. Authorize both the payment and optional connected-account namespace in
+your host. The client preserves its configured API version and provider errors;
+it does not settle a sale, move money, create debt or decide which costs a seller
+owes. The example's cost adapter uses this method while keeping its billing policy
+in the application.
+
+A `ready` result contains every refund and dispute, source-linked balance
+transactions, signed fee adjustments and provider amounts in integer minor units.
+Dates are milliseconds. `processingFee` is the original charge balance
+transaction's total provider-reported fee, which can include application fees on
+direct charges. Each transaction exposes `feeDetails` so your approved policy can
+distinguish processor, application and other fees. A null breakdown means provider
+details were unavailable; the reported total remains authoritative. Negative fee
+adjustments remain credits. Failed refunds include their failure reversal instead
+of counting their principal as returned.
+
+`principalReturned` caps the combined economic refund/dispute principal at the
+original gross amount. Raw signed provider transactions remain intact, including
+any overlapping debits, and are not a seller debt calculation. A won dispute with
+an unreinstated principal withdrawal is `not_ready`. Pending refunds, missing cost
+transactions or different settlement currencies also return an explicit
+`not_ready` reason instead of estimated or mixed-currency totals. Provider
+pagination errors throw rather than returning partial data. Retry delayed
+provider data; resolve currency conversion through an explicit host policy.
+
+See Stripe's [balance transaction fields](https://docs.stripe.com/api/balance_transactions/object)
+and [refund failure reversals](https://docs.stripe.com/api/refunds/object).
+
+### Optional balance-funded subscriptions
+
+Balance funding requires an eligible connected account and Stripe's Accounts v2
+balance-payment preview. It is separate from non-Connect customer-only Accounts
+v2 eligibility. Keep your normal client on GA; construct a separate client with
+`stripeApiVersion: STRIPE_CUSTOMER_PREVIEW_API_VERSION` for this optional feature.
+`getBalanceFundingCapability()` reports whether that client is explicitly
+configured. It does not claim the account has provider approval; Stripe validates
+eligibility when preparing the payment method.
+
+After authenticating the seller, authorizing the subscription, and recording
+explicit recurring-debit consent in your own database:
+
+```ts
+const preparation = await balanceStripe.prepareBalanceFunding(ctx, {
+  customerAccount: authorizedSellerAccountId,
+  stripeSubscriptionId: authorizedSubscriptionId,
+  consent: true,
+  idempotencyKey: durablePreparationRequestId,
+});
+// Persist this immutable server-side record BEFORE enabling balance payments.
+await savePreparationAndConsent(preparation);
+await balanceStripe.setBalanceFunding(ctx, {
+  preparation,
+  enabled: true,
+  consent: true,
+  idempotencyKey: durableEnableRequestId,
+});
+// Opt-out restores the previous default method and payment-method types.
+await balanceStripe.setBalanceFunding(ctx, {
+  preparation: await loadPersistedPreparation(),
+  enabled: false,
+  idempotencyKey: durableDisableRequestId,
+});
+```
+
+`prepareBalanceFunding` creates/attaches a `stripe_balance` method and captures
+the prior subscription settings without changing them. `setBalanceFunding`
+checks subscription ownership and payment-method ownership, then changes the
+settings or recognizes that the requested state already exists. Null prior
+settings restore inheritance from the customer's settings. External source
+changes cause an error instead of being overwritten. Provider errors are
+preserved. Never accept restoration records or account IDs from an unauthenticated
+browser as authority.
+
+Serialize changes per subscription in the host. Persist the operation identity
+before the provider call, reuse it after a timeout or host write failure, and use
+a new identity for each later enable/disable cycle. The example's durable pending
+operation prevents an opposite change from racing an unfinished operation; retry
+the pending change first. Preserve the preparation through retries. Keys must be
+nonempty, contain no line breaks, and be at most 247 characters because the package
+adds phase suffixes. Stripe's idempotency retention window still applies.
+
+Only eligible processing earnings can fund these subscriptions; top-ups cannot.
+Insufficient available balance in the invoice currency fails payment and does not
+automatically charge a saved card. Handle `invoice.payment_failed` in your host
+and offer an explicit alternate-method recovery flow. These operations neither
+pay an overdue invoice nor change payout schedules. See Stripe's
+[balance-payment eligibility, approval and recovery guidance](https://docs.stripe.com/payments/pay-with-balance).
+
+### Upcoming invoice preview
+
+Authorize the customer account and subscription in your host action, then call
+`stripe.getUpcomingInvoicePreview(ctx, { customerAccount, stripeSubscriptionId })`.
+The method verifies that the subscription belongs to that account and uses your
+configured Stripe API version. It retrieves every invoice line, returns integer
+minor-unit amounts and millisecond timestamps, and preserves Stripe errors,
+including unavailable previews. Failed pagination throws instead of returning a
+partial estimate. `nextBillingAt` uses Stripe's next payment attempt, trial end,
+or earliest subscription-item renewal date, in that order.
+
+Pass the result through an authenticated callback to the React `InvoiceEstimate`
+component. It displays the provider `total` without summing line amounts. Totals
+can include discounts, tax or credits; `amountDue` can differ from `total` because
+of customer balances. Previews are estimates, not payable invoices. Application
+recovery costs and credits remain host-owned policy. See Stripe's
+[invoice preview documentation](https://docs.stripe.com/api/invoices/create_preview).
+
 ### Invoice, Payment Method, and Payout
 
 | Method                                                                               | Description                                                                                |
@@ -344,6 +539,7 @@ Methods named `get<Entity>` take the component document ID (exception: `getInvoi
 | `listInvoices(ctx, { stripeAccountId?, userId?, subscriptionId?, status?, limit? })` | List invoices with optional filters                                                        |
 | `listInvoicesByUser(ctx, { userId })`                                                | List all invoices for a user                                                               |
 | `getInvoiceFromStripe(ctx, { stripeInvoiceId })`                                     | Fetch latest invoice data directly from Stripe                                             |
+| `getUpcomingInvoicePreview(ctx, { customerAccount, stripeSubscriptionId })`          | Preview the next invoice with complete lines, provider totals and millisecond dates        |
 | `listPaymentMethods(ctx, { stripeCustomerId, type? })`                               | List saved payment methods                                                                 |
 | `attachPaymentMethod(ctx, { paymentMethodId, stripeCustomerId })`                    | Attach a payment method to a customer account                                              |
 | `detachPaymentMethod(ctx, { paymentMethodId })`                                      | Detach a payment method                                                                    |
@@ -493,7 +689,8 @@ The component maintains a `webhookEvents` table that tracks every event by its S
 - `customer.subscription.created`, `.updated`, `.deleted`, `.trial_will_end`
 - `invoice.created`, `.finalized`, `.paid`, `.payment_failed`
 - `payment_intent.succeeded`, `.payment_failed`, `.canceled`
-- `payout.created`, `.updated`, `.paid`, `.failed`
+- `payout.created`, `.updated`, `.paid`, `.failed`, `.canceled`
+
 - `refund.created`, `.updated`, `.failed`
 - `application_fee.refunded` -- keeps `feeCollectedAmount`/`feeRefundedAmount` accurate on the linked payment
 - `charge.dispute.created`, `.updated`, `.closed`, `.funds_withdrawn`, `.funds_reinstated`
@@ -502,6 +699,18 @@ The component maintains a `webhookEvents` table that tracks every event by its S
 
 Note: Subscription and invoice events use v1 Billing API event names even when the billing entity is a V2 account referenced via `customer_account`.
 
+Dedicated payout cancellations use the same signed V1 endpoint, payout record
+and connected-account association as other payout events. Generic `onEvent`
+and `events["payout.canceled"]` callbacks run after reconciliation. Cancellation
+does not invoke the paid/completed convenience hook. Normal verified replay is
+deduplicated by the existing event ledger.
+
+When upgrading from 0.11.0 or earlier, add `payout.canceled` to the existing V1
+endpoint's selected events. New endpoints created with the corrected package's
+defaults include it. Updating the library alone does not edit an existing provider
+endpoint or recover already missed events. Consumers must adopt a published
+version containing this correction; a merged source fix is not a package release.
+
 ## Trigger API
 
 The trigger system follows the BetterAuth pattern: define callbacks at client init time, export the `syncWebhook`/`asyncWebhook` pair via `webhookHandlers()`, and pass their function references to `registerRoutes` via `webhooks`.
@@ -1234,9 +1443,16 @@ terms, and recoverable execution through the component's existing transfer ledge
 explicitly bounded upcoming payout data. See [settlement and payout contracts](docs/settlement.md)
 for authorization, recovery, migration, and provider limitations.
 
-Account creation (`createAccount`, `getOrCreateAccount`, `ensureCustomerAccount`)
-and `createCheckoutSession` accept an optional `idempotencyKey`. Use one stable
+Account creation (`createAccount`, `getOrCreateAccount`, `ensureCustomerAccount`),
+`createCheckoutSession`, `createProduct`, and `createPrice` accept an optional `idempotencyKey`. Use one stable
 account-creation key per logical account and a distinct key per checkout order.
+For catalog edits, persist a request key for the logical product or immutable
+price version. Retry identical parameters with the same key after a provider or
+component persistence failure. Use a new key when the price amount or other
+creation parameters change. Creating a new Price does not migrate existing
+subscriptions; they retain their prior price until the host explicitly changes
+them. Never reuse a version key for different parameters.
+
 React `Checkout` preserves its request ID through retries; your server must
 forward that identity as the SDK request option. Persist it in the host order
 for recovery across reloads. Omission retains the previous SDK behavior.

package/dist/client/billing/balanceFunding.d.ts

@@ -0,0 +1,36 @@
+import type Stripe from "stripe";
+import { STRIPE_CUSTOMER_PREVIEW_API_VERSION } from "../apiVersion.js";
+export type BalanceFundingCapability = {
+    configured: boolean;
+    requiredApiVersion: typeof STRIPE_CUSTOMER_PREVIEW_API_VERSION;
+    requiresConnectedAccount: true;
+    eligibility: "provider_validates_on_prepare";
+};
+export declare function getBalanceFundingCapability(version: string): BalanceFundingCapability;
+export type BalanceFundingScope = {
+    customerAccount: string;
+    stripeSubscriptionId: string;
+};
+/** Persist server-side before applying; never accept this record from a browser. */
+export type BalanceFundingPreparation = BalanceFundingScope & {
+    paymentMethodId: string;
+    previousPaymentMethodId: string | null;
+    previousPaymentMethodTypes: string[] | null;
+};
+export type PrepareBalanceFundingOptions = BalanceFundingScope & {
+    consent: true;
+    idempotencyKey: string;
+};
+export type SetBalanceFundingOptions = {
+    preparation: BalanceFundingPreparation;
+    enabled: boolean;
+    consent?: true;
+    idempotencyKey: string;
+};
+/** Capture restoration settings, provision and attach; does not enable billing. */
+export declare function prepareBalanceFunding(stripe: Stripe, version: string, opts: PrepareBalanceFundingOptions): Promise<BalanceFundingPreparation>;
+/** Apply a host-persisted preparation. Host serializes changes per subscription. */
+export declare function setBalanceFunding(stripe: Stripe, version: string, opts: SetBalanceFundingOptions): Promise<{
+    enabled: boolean;
+}>;
+//# sourceMappingURL=balanceFunding.d.ts.map

package/dist/client/billing/balanceFunding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"balanceFunding.d.ts","sourceRoot":"","sources":["../../../src/client/billing/balanceFunding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,EAAE,mCAAmC,EAAE,MAAM,kBAAkB,CAAC;AAIvE,MAAM,MAAM,wBAAwB,GAAG;IACrC,UAAU,EAAE,OAAO,CAAC;IACpB,kBAAkB,EAAE,OAAO,mCAAmC,CAAC;IAC/D,wBAAwB,EAAE,IAAI,CAAC;IAC/B,WAAW,EAAE,+BAA+B,CAAC;CAC9C,CAAC;AACF,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,GACd,wBAAwB,CAO1B;AACD,MAAM,MAAM,mBAAmB,GAAG;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB,EAAE,MAAM,CAAC;CAC9B,CAAC;AACF,oFAAoF;AACpF,MAAM,MAAM,yBAAyB,GAAG,mBAAmB,GAAG;IAC5D,eAAe,EAAE,MAAM,CAAC;IACxB,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,0BAA0B,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAC7C,CAAC;AACF,MAAM,MAAM,4BAA4B,GAAG,mBAAmB,GAAG;IAC/D,OAAO,EAAE,IAAI,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AACF,MAAM,MAAM,wBAAwB,GAAG;IACrC,WAAW,EAAE,yBAAyB,CAAC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AA4BF,mFAAmF;AACnF,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,4BAA4B,GACjC,OAAO,CAAC,yBAAyB,CAAC,CA0CpC;AAQD,oFAAoF;AACpF,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAsD/B"}

package/dist/client/billing/balanceFunding.js

@@ -0,0 +1,107 @@
+import { STRIPE_CUSTOMER_PREVIEW_API_VERSION } from "../apiVersion.js";
+import { idempotencyOptions } from "../core/idempotency.js";
+import { resolveOwnerAccount } from "../utils/owner.js";
+export function getBalanceFundingCapability(version) {
+    return {
+        configured: version === STRIPE_CUSTOMER_PREVIEW_API_VERSION,
+        requiredApiVersion: STRIPE_CUSTOMER_PREVIEW_API_VERSION,
+        requiresConnectedAccount: true,
+        eligibility: "provider_validates_on_prepare",
+    };
+}
+function request(version, key, phase) {
+    if (!getBalanceFundingCapability(version).configured)
+        throw new Error("Balance funding requires explicit Stripe preview API configuration.");
+    if (typeof key !== "string")
+        throw new Error("An explicit idempotency key is required for balance funding.");
+    idempotencyOptions(key);
+    return idempotencyOptions(`${key}:${phase}`);
+}
+async function subscription(stripe, scope) {
+    if (!scope.customerAccount.startsWith("acct_") || !scope.stripeSubscriptionId)
+        throw new Error("A customer account and subscription are required.");
+    const sub = await stripe.subscriptions.retrieve(scope.stripeSubscriptionId);
+    if (resolveOwnerAccount(sub) !== scope.customerAccount)
+        throw new Error("Subscription does not belong to the customer account.");
+    if (!["active", "past_due", "trialing"].includes(sub.status))
+        throw new Error("This subscription cannot change payment sources.");
+    return sub;
+}
+function methodId(sub) {
+    const pm = sub.default_payment_method;
+    return typeof pm === "string" ? pm : (pm?.id ?? null);
+}
+/** Capture restoration settings, provision and attach; does not enable billing. */
+export async function prepareBalanceFunding(stripe, version, opts) {
+    const createOptions = request(version, opts.idempotencyKey, "create");
+    const attachOptions = request(version, opts.idempotencyKey, "attach");
+    if (opts.consent !== true)
+        throw new Error("Explicit consent is required for balance funding.");
+    const sub = await subscription(stripe, opts);
+    const previous = methodId(sub);
+    const types = sub.payment_settings?.payment_method_types ?? null;
+    if (types?.includes("stripe_balance") ||
+        (previous &&
+            (await stripe.paymentMethods.retrieve(previous)).type ===
+                "stripe_balance"))
+        throw new Error("Balance funding is already configured; reuse the persisted restoration record.");
+    const pm = await stripe.paymentMethods.create({ type: "stripe_balance" }, createOptions);
+    if (pm.type !== "stripe_balance")
+        throw new Error("Stripe did not return a balance payment method.");
+    const current = await stripe.paymentMethods.retrieve(pm.id);
+    if (resolveOwnerAccount(current) === null) {
+        await stripe.paymentMethods.attach(pm.id, { customer_account: opts.customerAccount }, attachOptions);
+    }
+    else if (resolveOwnerAccount(current) !== opts.customerAccount) {
+        throw new Error("Balance payment method belongs to a different customer account.");
+    }
+    return {
+        customerAccount: opts.customerAccount,
+        stripeSubscriptionId: opts.stripeSubscriptionId,
+        paymentMethodId: pm.id,
+        previousPaymentMethodId: previous,
+        previousPaymentMethodTypes: types,
+    };
+}
+function sameTypes(a, b) {
+    return a === null || b === null
+        ? a === b
+        : a.length === b.length &&
+            [...a].sort().every((type, i) => type === [...b].sort()[i]);
+}
+/** Apply a host-persisted preparation. Host serializes changes per subscription. */
+export async function setBalanceFunding(stripe, version, opts) {
+    if (typeof opts.enabled !== "boolean")
+        throw new Error("An explicit enabled state is required for balance funding.");
+    const requestOptions = request(version, opts.idempotencyKey, opts.enabled ? "enable" : "disable");
+    if (opts.enabled && opts.consent !== true)
+        throw new Error("Explicit consent is required for balance funding.");
+    const prep = opts.preparation;
+    const sub = await subscription(stripe, prep);
+    const pm = await stripe.paymentMethods.retrieve(prep.paymentMethodId);
+    if (pm.type !== "stripe_balance" ||
+        resolveOwnerAccount(pm) !== prep.customerAccount)
+        throw new Error("Balance payment method does not belong to the customer account.");
+    const original = methodId(sub) === prep.previousPaymentMethodId &&
+        sameTypes(sub.payment_settings?.payment_method_types ?? null, prep.previousPaymentMethodTypes);
+    const balance = methodId(sub) === prep.paymentMethodId &&
+        sameTypes(sub.payment_settings?.payment_method_types ?? null, [
+            "stripe_balance",
+        ]);
+    if (!original && !balance)
+        throw new Error("Subscription payment settings changed; reconcile before applying this restoration record.");
+    if ((opts.enabled && balance) || (!opts.enabled && original))
+        return { enabled: opts.enabled };
+    await stripe.subscriptions.update(sub.id, {
+        default_payment_method: opts.enabled
+            ? prep.paymentMethodId
+            : (prep.previousPaymentMethodId ?? ""),
+        payment_settings: {
+            payment_method_types: opts.enabled
+                ? ["stripe_balance"]
+                : (prep.previousPaymentMethodTypes ?? ""),
+        },
+    }, requestOptions);
+    return { enabled: opts.enabled };
+}
+//# sourceMappingURL=balanceFunding.js.map

package/dist/client/billing/balanceFunding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"balanceFunding.js","sourceRoot":"","sources":["../../../src/client/billing/balanceFunding.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mCAAmC,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAQxD,MAAM,UAAU,2BAA2B,CACzC,OAAe;IAEf,OAAO;QACL,UAAU,EAAE,OAAO,KAAK,mCAAmC;QAC3D,kBAAkB,EAAE,mCAAmC;QACvD,wBAAwB,EAAE,IAAI;QAC9B,WAAW,EAAE,+BAA+B;KAC7C,CAAC;AACJ,CAAC;AAqBD,SAAS,OAAO,CAAC,OAAe,EAAE,GAAW,EAAE,KAAa;IAC1D,IAAI,CAAC,2BAA2B,CAAC,OAAO,CAAC,CAAC,UAAU;QAClD,MAAM,IAAI,KAAK,CACb,qEAAqE,CACtE,CAAC;IACJ,IAAI,OAAO,GAAG,KAAK,QAAQ;QACzB,MAAM,IAAI,KAAK,CACb,8DAA8D,CAC/D,CAAC;IACJ,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACxB,OAAO,kBAAkB,CAAC,GAAG,GAAG,IAAI,KAAK,EAAE,CAAE,CAAC;AAChD,CAAC;AACD,KAAK,UAAU,YAAY,CAAC,MAAc,EAAE,KAA0B;IACpE,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,oBAAoB;QAC3E,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAC5E,IAAI,mBAAmB,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,eAAe;QACpD,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,IAAI,CAAC,CAAC,QAAQ,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC;QAC1D,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,OAAO,GAAG,CAAC;AACb,CAAC;AACD,SAAS,QAAQ,CAAC,GAAwB;IACxC,MAAM,EAAE,GAAG,GAAG,CAAC,sBAAsB,CAAC;IACtC,OAAO,OAAO,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,IAAI,CAAC,CAAC;AACxD,CAAC;AAED,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAc,EACd,OAAe,EACf,IAAkC;IAElC,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IACtE,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IACtE,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI;QACvB,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,MAAM,GAAG,GAAG,MAAM,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAG,GAAG,CAAC,gBAAgB,EAAE,oBAAoB,IAAI,IAAI,CAAC;IACjE,IACE,KAAK,EAAE,QAAQ,CAAC,gBAAgB,CAAC;QACjC,CAAC,QAAQ;YACP,CAAC,MAAM,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI;gBACnD,gBAAgB,CAAC;QAErB,MAAM,IAAI,KAAK,CACb,gFAAgF,CACjF,CAAC;IACJ,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,MAAM,CAC3C,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAC1B,aAAa,CACd,CAAC;IACF,IAAI,EAAE,CAAC,IAAI,KAAK,gBAAgB;QAC9B,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAC5D,IAAI,mBAAmB,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;QAC1C,MAAM,MAAM,CAAC,cAAc,CAAC,MAAM,CAChC,EAAE,CAAC,EAAE,EACL,EAAE,gBAAgB,EAAE,IAAI,CAAC,eAAe,EAAE,EAC1C,aAAa,CACd,CAAC;IACJ,CAAC;SAAM,IAAI,mBAAmB,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,eAAe,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CACb,iEAAiE,CAClE,CAAC;IACJ,CAAC;IACD,OAAO;QACL,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,oBAAoB,EAAE,IAAI,CAAC,oBAAoB;QAC/C,eAAe,EAAE,EAAE,CAAC,EAAE;QACtB,uBAAuB,EAAE,QAAQ;QACjC,0BAA0B,EAAE,KAAK;KAClC,CAAC;AACJ,CAAC;AACD,SAAS,SAAS,CAAC,CAAkB,EAAE,CAAkB;IACvD,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAC7B,CAAC,CAAC,CAAC,KAAK,CAAC;QACT,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;YACnB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AACpE,CAAC;AAED,oFAAoF;AACpF,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAc,EACd,OAAe,EACf,IAA8B;IAE9B,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,SAAS;QACnC,MAAM,IAAI,KAAK,CACb,4DAA4D,CAC7D,CAAC;IACJ,MAAM,cAAc,GAAG,OAAO,CAC5B,OAAO,EACP,IAAI,CAAC,cAAc,EACnB,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CACpC,CAAC;IACF,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI;QACvC,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC;IAC9B,MAAM,GAAG,GAAG,MAAM,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC7C,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IACtE,IACE,EAAE,CAAC,IAAI,KAAK,gBAAgB;QAC5B,mBAAmB,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC,eAAe;QAEhD,MAAM,IAAI,KAAK,CACb,iEAAiE,CAClE,CAAC;IACJ,MAAM,QAAQ,GACZ,QAAQ,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,uBAAuB;QAC9C,SAAS,CACP,GAAG,CAAC,gBAAgB,EAAE,oBAAoB,IAAI,IAAI,EAClD,IAAI,CAAC,0BAA0B,CAChC,CAAC;IACJ,MAAM,OAAO,GACX,QAAQ,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,eAAe;QACtC,SAAS,CAAC,GAAG,CAAC,gBAAgB,EAAE,oBAAoB,IAAI,IAAI,EAAE;YAC5D,gBAAgB;SACjB,CAAC,CAAC;IACL,IAAI,CAAC,QAAQ,IAAI,CAAC,OAAO;QACvB,MAAM,IAAI,KAAK,CACb,2FAA2F,CAC5F,CAAC;IACJ,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,IAAI,QAAQ,CAAC;QAC1D,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IACnC,MAAM,MAAM,CAAC,aAAa,CAAC,MAAM,CAC/B,GAAG,CAAC,EAAE,EACN;QACE,sBAAsB,EAAE,IAAI,CAAC,OAAO;YAClC,CAAC,CAAC,IAAI,CAAC,eAAe;YACtB,CAAC,CAAC,CAAC,IAAI,CAAC,uBAAuB,IAAI,EAAE,CAAC;QACxC,gBAAgB,EAAE;YAChB,oBAAoB,EAAE,IAAI,CAAC,OAAO;gBAChC,CAAC,CAAC,CAAC,gBAAgB,CAAC;gBACpB,CAAC,CAAC,CAAC,IAAI,CAAC,0BAA0B,IAAI,EAAE,CAAC;SAC5C;KACF,EACD,cAAc,CACf,CAAC;IACF,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;AACnC,CAAC"}

package/dist/client/billing/invoicePreview.d.ts

@@ -0,0 +1,28 @@
+import type Stripe from "stripe";
+export type UpcomingInvoicePreviewOptions = {
+    /** Host must authorize this customer account before calling. */
+    customerAccount: string;
+    stripeSubscriptionId: string;
+};
+/** Provider amounts are integer minor units; all dates are milliseconds. */
+export type UpcomingInvoicePreview = {
+    stripeInvoiceId: string;
+    currency: string;
+    total: number;
+    subtotal: number;
+    amountDue: number;
+    nextBillingAt: number;
+    periodStart: number;
+    periodEnd: number;
+    linesComplete: true;
+    lines: {
+        id: string;
+        description: string;
+        amount: number;
+        currency: string;
+        periodStart: number;
+        periodEnd: number;
+    }[];
+};
+export declare function getUpcomingInvoicePreview(stripe: Stripe, opts: UpcomingInvoicePreviewOptions): Promise<UpcomingInvoicePreview>;
+//# sourceMappingURL=invoicePreview.d.ts.map

package/dist/client/billing/invoicePreview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoicePreview.d.ts","sourceRoot":"","sources":["../../../src/client/billing/invoicePreview.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAGjC,MAAM,MAAM,6BAA6B,GAAG;IAC1C,gEAAgE;IAChE,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,sBAAsB,GAAG;IACnC,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,IAAI,CAAC;IACpB,KAAK,EAAE;QACL,EAAE,EAAE,MAAM,CAAC;QACX,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;KACnB,EAAE,CAAC;CACL,CAAC;AAQF,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,6BAA6B,GAClC,OAAO,CAAC,sBAAsB,CAAC,CAsDjC"}

package/dist/client/billing/invoicePreview.js

@@ -0,0 +1,56 @@
+import { resolveOwnerAccount } from "../utils/owner.js";
+function integer(value) {
+    if (!Number.isSafeInteger(value))
+        throw new Error("Invoice preview amounts and dates must be safe integers.");
+    return value;
+}
+export async function getUpcomingInvoicePreview(stripe, opts) {
+    if (!opts.customerAccount.startsWith("acct_") || !opts.stripeSubscriptionId)
+        throw new Error("A customer account and subscription are required.");
+    const subscription = await stripe.subscriptions.retrieve(opts.stripeSubscriptionId);
+    if (resolveOwnerAccount(subscription) !== opts.customerAccount)
+        throw new Error("Subscription does not belong to the customer account.");
+    const preview = await stripe.invoices.createPreview({
+        customer_account: opts.customerAccount,
+        subscription: opts.stripeSubscriptionId,
+    });
+    const lines = [];
+    const append = (line) => {
+        if (line.currency !== preview.currency)
+            throw new Error("Invoice preview line currency does not match the invoice.");
+        lines.push({
+            id: line.id,
+            description: line.description ?? "Subscription",
+            amount: integer(line.amount),
+            currency: line.currency,
+            periodStart: integer(line.period.start * 1000),
+            periodEnd: integer(line.period.end * 1000),
+        });
+    };
+    if (preview.lines.has_more) {
+        for await (const line of stripe.invoices.listLineItems(preview.id, {
+            limit: 100,
+        }))
+            append(line);
+    }
+    else {
+        preview.lines.data.forEach(append);
+    }
+    const renewalDates = subscription.items.data.map((item) => item.current_period_end);
+    const nextBillingAt = preview.next_payment_attempt ??
+        (subscription.status === "trialing" ? subscription.trial_end : null) ??
+        Math.min(...renewalDates);
+    return {
+        stripeInvoiceId: preview.id,
+        currency: preview.currency,
+        total: integer(preview.total),
+        subtotal: integer(preview.subtotal),
+        amountDue: integer(preview.amount_due),
+        nextBillingAt: integer(nextBillingAt * 1000),
+        periodStart: integer(preview.period_start * 1000),
+        periodEnd: integer(preview.period_end * 1000),
+        linesComplete: true,
+        lines,
+    };
+}
+//# sourceMappingURL=invoicePreview.js.map

package/dist/client/billing/invoicePreview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoicePreview.js","sourceRoot":"","sources":["../../../src/client/billing/invoicePreview.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AA6BxD,SAAS,OAAO,CAAC,KAAa;IAC5B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,MAAc,EACd,IAAmC;IAEnC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,oBAAoB;QACzE,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,QAAQ,CACtD,IAAI,CAAC,oBAAoB,CAC1B,CAAC;IACF,IAAI,mBAAmB,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC,eAAe;QAC5D,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC;QAClD,gBAAgB,EAAE,IAAI,CAAC,eAAe;QACtC,YAAY,EAAE,IAAI,CAAC,oBAAoB;KACxC,CAAC,CAAC;IACH,MAAM,KAAK,GAAoC,EAAE,CAAC;IAClD,MAAM,MAAM,GAAG,CAAC,IAA4B,EAAE,EAAE;QAC9C,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO,CAAC,QAAQ;YACpC,MAAM,IAAI,KAAK,CACb,2DAA2D,CAC5D,CAAC;QACJ,KAAK,CAAC,IAAI,CAAC;YACT,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,cAAc;YAC/C,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;YAC5B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,WAAW,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC;YAC9C,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,GAAG,IAAI,CAAC;SAC3C,CAAC,CAAC;IACL,CAAC,CAAC;IACF,IAAI,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC3B,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,EAAE;YACjE,KAAK,EAAE,GAAG;SACX,CAAC;YACA,MAAM,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IACD,MAAM,YAAY,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAC9C,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,kBAAkB,CAClC,CAAC;IACF,MAAM,aAAa,GACjB,OAAO,CAAC,oBAAoB;QAC5B,CAAC,YAAY,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;QACpE,IAAI,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC;IAC5B,OAAO;QACL,eAAe,EAAE,OAAO,CAAC,EAAE;QAC3B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;QAC7B,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;QACnC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC;QACtC,aAAa,EAAE,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;QAC5C,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;QACjD,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;QAC7C,aAAa,EAAE,IAAI;QACnB,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/client/charge-currency-format.d.ts

@@ -0,0 +1,3 @@
+/** Internal exact renderer. Callers establish units and amount eligibility. */
+export declare function renderCurrencyUnits(amount: number, currency: string, apiDecimals: 0 | 2, displayDecimals: 0 | 2, locale: string): string;
+//# sourceMappingURL=charge-currency-format.d.ts.map

package/dist/client/charge-currency-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"charge-currency-format.d.ts","sourceRoot":"","sources":["../../src/client/charge-currency-format.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,CAAC,GAAG,CAAC,EAClB,eAAe,EAAE,CAAC,GAAG,CAAC,EACtB,MAAM,EAAE,MAAM,GACb,MAAM,CAqBR"}

package/dist/client/charge-currency-format.js

@@ -0,0 +1,22 @@
+/** Internal exact renderer. Callers establish units and amount eligibility. */
+export function renderCurrencyUnits(amount, currency, apiDecimals, displayDecimals, locale) {
+    const scale = 10n ** BigInt(apiDecimals);
+    const units = BigInt(Math.abs(amount));
+    const whole = units / scale;
+    const signedWhole = amount < 0 ? (whole === 0n ? -0 : -whole) : whole;
+    const formatter = new Intl.NumberFormat(locale, {
+        style: "currency",
+        currency: currency.toUpperCase(),
+        minimumFractionDigits: displayDecimals,
+        maximumFractionDigits: displayDecimals,
+    });
+    const digits = new Intl.NumberFormat(locale, { useGrouping: false });
+    const fraction = (units % scale).toString().padStart(apiDecimals, "0");
+    return formatter
+        .formatToParts(signedWhole)
+        .map((part) => part.type === "fraction"
+        ? [...fraction].map((digit) => digits.format(Number(digit))).join("")
+        : part.value)
+        .join("");
+}
+//# sourceMappingURL=charge-currency-format.js.map

package/dist/client/charge-currency-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"charge-currency-format.js","sourceRoot":"","sources":["../../src/client/charge-currency-format.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,MAAM,UAAU,mBAAmB,CACjC,MAAc,EACd,QAAgB,EAChB,WAAkB,EAClB,eAAsB,EACtB,MAAc;IAEd,MAAM,KAAK,GAAG,GAAG,IAAI,MAAM,CAAC,WAAW,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;IAC5B,MAAM,WAAW,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACtE,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE;QAC9C,KAAK,EAAE,UAAU;QACjB,QAAQ,EAAE,QAAQ,CAAC,WAAW,EAAE;QAChC,qBAAqB,EAAE,eAAe;QACtC,qBAAqB,EAAE,eAAe;KACvC,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;IACrE,MAAM,QAAQ,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IACvE,OAAO,SAAS;SACb,aAAa,CAAC,WAAW,CAAC;SAC1B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CACZ,IAAI,CAAC,IAAI,KAAK,UAAU;QACtB,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,CAAC,CAAC,IAAI,CAAC,KAAK,CACf;SACA,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC"}

package/dist/client/charge-currency.d.ts

@@ -0,0 +1,14 @@
+export type ChargeCurrencyMetadata = {
+    currency: string;
+    apiDecimals: 0 | 2;
+    displayDecimals: 0 | 2;
+};
+/** Metadata does not establish account/country/payment-method support. */
+export declare function getChargeCurrencyMetadata(currency: string): ChargeCurrencyMetadata | null;
+/** Parse a nonnegative ASCII decimal exactly. Invalid input is never rounded. */
+export declare function parseChargeAmount(value: string, currency: string): number | null;
+/** Exact ASCII decimal for charge inputs; invalid source units stay unavailable. */
+export declare function chargeAmountToDecimal(amount: number, currency: string): string | null;
+/** Format signed integer charge units without floating-point division. */
+export declare function formatChargeAmount(amount: number, currency: string, locale?: string): string;
+//# sourceMappingURL=charge-currency.d.ts.map

package/dist/client/charge-currency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"charge-currency.d.ts","sourceRoot":"","sources":["../../src/client/charge-currency.ts"],"names":[],"mappings":"AAuCA,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC;IACnB,eAAe,EAAE,CAAC,GAAG,CAAC,CAAC;CACxB,CAAC;AAEF,0EAA0E;AAC1E,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,GACf,sBAAsB,GAAG,IAAI,CAU/B;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,IAAI,CASf;AAED,oFAAoF;AACpF,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,IAAI,CAef;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,SAAU,GACf,MAAM,CAiBR"}