@happyvertical/smrt-commerce 0.51.33 → 0.51.34

package/AGENTS.md

@@ -100,6 +100,23 @@ for usage.
   `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.
+- **Payment rails (#3138).** A runtime has one issuing `provider` and any
+  number of `paymentProviders` (unique names, one inbox namespace each; a
+  provider with `capabilities.issuesInvoices === false` can never issue).
+  `observe()` resolves the provider from the delivery namespace, never the
+  payload. Crypto rails implement the port over `@happyvertical/payments`'
+  `CryptoCheckoutGateway`; never call BTCPay (or any gateway) from here.
+  Settlement is decided by the pure `decideAttempt()` from gateway state and
+  `paymentPolicy` — the gateway's `settled` is authoritative and nothing here
+  counts confirmations. A `BillingPaymentAttempt` (`(provider, checkout_id)`
+  deterministic id) records every state and settles once; grants and payments
+  are keyed by checkout id. Invoice payments close the issuer's invoice out of
+  band in `observe()` (idempotent) before `project()` records the payment, and
+  `settlePaidInvoice` skips (records nothing for) a `paidOutOfBand` invoice
+  the rail latched with `outOfBandRequestedAt`; other out-of-band closes are
+  recorded as `OTHER` payments. Rails never save cards or charge tax: a taxed
+  credit purchase on a rail needs an explicit `automaticTax: false`. Exceptions are flags for operators;
+  nothing reverses or refunds automatically.
 - **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

package/README.md

@@ -373,6 +373,94 @@ const evaluator = await SpendingPolicyEvaluator.create({
   `automaticTax: false` to keep them untaxed), and Stripe customers are
   created idempotently.
 
+### Payment rails: BTC and other crypto (#3138)
+
+A seller runtime can take payments on more than one **rail**. The issuing
+`provider` (Stripe) still issues, taxes, and emails every invoice; extra rails
+in `paymentProviders` let a payer choose, per payment, to pay an invoice or buy
+prepaid credit another way. The crypto rail runs short-lived, fiat-priced
+checkouts through `@happyvertical/payments`' provider-neutral
+`CryptoCheckoutGateway` — BTCPay Server at launch — so another gateway can
+replace BTCPay without changing this package or its consumers.
+
+```ts
+import {
+  BillingRuntime,
+  createBtcPayBillingProvider,
+  createStripeBillingProvider,
+} from '@happyvertical/smrt-commerce';
+
+const btcpay = createBtcPayBillingProvider({
+  baseUrl, apiKey, storeId,        // one BTCPay store per seller entity
+  webhookSecret, metadataSecret,   // from the host's secret store, by name
+  speedPolicy: 'LowMediumSpeed',   // settle after 2 confirmations (BTCPay offers 0/1/2/6)
+  rateSource: 'kraken',
+  minimumAmount: { CAD: 500, USD: 500 },
+});
+const billing = await BillingRuntime.create({
+  db, sellerTenantId, kind: 'provider',
+  provider: createStripeBillingProvider({ stripe, webhookSecret }),
+  paymentProviders: [btcpay],
+  paymentPolicy: { latePaymentPolicy: 'review', refundBasis: 'original_native' },
+  billingRelationships,
+  ledger: { ...ledger, cryptoHoldingsAccountId, fxGainLossAccountId, feesAccountId },
+});
+
+// Prepaid credit or an issued invoice, paid with BTC:
+await billing.createCreditCheckout({ ...purchase, provider: 'btcpay' });
+await billing.createInvoicePayment({ invoiceId, provider: 'btcpay', purchaseId, successUrl, cancelUrl });
+
+// Webhook route for the rail (BTCPay signs with its own header):
+await billing.acceptWebhook(rawBody, '', { provider: 'btcpay', headers: request.headers });
+await billing.processEvents();
+```
+
+- **Settlement is the gateway's.** Credit is granted and invoices are paid
+  only when the gateway reports `settled` under its own confirmation policy;
+  this package never counts confirmations. BTCPay offers 0, 1, 2 or 6
+  confirmations; the default is `LowMediumSpeed` (2 confirmations).
+- **Payment attempts.** Every rail checkout is a `BillingPaymentAttempt`
+  recording the locked fiat price, fiat and native amounts received, rate and
+  rate source, each payment's txid, rail and fee, a timeline of status changes,
+  and what settlement produced. `listPaymentAttempts()` feeds "payment
+  confirming" displays and operator queues; `refreshPaymentAttempts()` is the
+  polling fallback for missed webhooks.
+- **Dunning pauses** for an invoice while a payment for it is confirming
+  (0-conf seen); if the payment then expires or is invalidated the payer's
+  standing is re-applied.
+- **Invoices paid on a rail** are closed at the issuer with
+  `markInvoicePaidOutOfBand` (Stripe `paid_out_of_band`), so Stripe stops
+  collecting; Stripe's own `paid` event then records nothing more.
+  `createInvoicePayment` refuses when the issuing provider cannot do that.
+- **Exceptions never auto-refund.** Underpaid, overpaid, late, manually marked
+  (at the gateway), invalidated-after-settlement, and paid-twice attempts are
+  flagged for an operator (`resolvePaymentAttempt`). Per-seller
+  `paymentPolicy` sets under/overpayment tolerances (basis points), late
+  payments (`review` | `accept`), manually marked checkouts, hold vs convert
+  (`conversionHandler`), and the refund basis.
+- **Ledger.** Receipts are booked at the locked fiat amount into
+  `cryptoHoldingsAccountId` (default `cashAccountId`); money received above
+  the price is booked as customer credit (prepaid-credit liability).
+  `recordManualRefund()` refunds from that excess first, then from purchased
+  credit (or an invoice payment kept as credit because the invoice was paid
+  elsewhere) — capped cumulatively, once per reference; an invoice payment
+  applied to its invoice is reversed at the issuer, not here.
+  `recordCryptoConversion()` posts a conversion with FX gain/loss.
+- **Upgrading.** Additive schema: `_smrt_billing_payment_attempts` (run
+  `smrt db:migrate`). A runtime without `paymentProviders` never reads it.
+- **One live payment per invoice.** The issuer's own `paid` event for an
+  invoice a rail closed out of band records nothing (the rail records it); an
+  out-of-band close made by someone else (wire, cheque) is recorded as an
+  `OTHER`-method payment; a real card payment made while a rail payment
+  confirms is recorded and the rail money is flagged `invoice_already_paid`.
+  An issuer close whose rail payment never settles is flagged
+  `out_of_band_without_settlement`: reopen the invoice at the issuer, then
+  `resolvePaymentAttempt()` it, after which a later out-of-band close is
+  recorded normally.
+- **Entities.** Each legal entity is its own seller runtime with its own
+  store, keys, and ledger. Inter-entity resale is ordinary reseller billing
+  between two sellers, payable on any rail the selling entity offers.
+
 See [`AGENTS.md`](./AGENTS.md#billing-period-close-3060) for invariants and
 known limits.
 

package/dist/__tests__/helpers/crypto-rail.d.ts

@@ -0,0 +1,69 @@
+/**
+ * A crypto payment rail world for #3138: the billing fixture's Stripe
+ * issuing provider plus an in-memory `CryptoCheckoutGateway`, wired into one
+ * seller runtime. Shared by the SQLite suite and the PostgreSQL lane.
+ */
+import { type CreateCryptoCheckoutInput, type CryptoCheckout, type CryptoCheckoutException, type CryptoCheckoutGateway, type CryptoCheckoutPayment, type CryptoCheckoutStatus } from '@happyvertical/payments';
+import type { DatabaseInterface } from '@happyvertical/smrt-core/migrations';
+import type { BillingPaymentPolicy } from '../../billing/payment-attempts.js';
+import type { BillingProvider } from '../../billing/provider.js';
+import { type BillingLedgerAccounts, BillingRuntime } from '../../billing/runtime.js';
+import { type BillingWorld } from './billing-fixture.js';
+export declare const RAIL_METADATA_SECRET = "rail-metadata-secret";
+export declare const RAIL_SIGNATURE = "fake-rail-ok";
+interface FakeCheckout {
+    id: string;
+    orderId: string;
+    amount: number;
+    currency: string;
+    metadata: Record<string, string>;
+    status: CryptoCheckoutStatus;
+    exception: CryptoCheckoutException;
+    amountPaid: number;
+    payments: CryptoCheckoutPayment[];
+    owned: boolean;
+    /** Settlement asset override (default BTC). */
+    asset?: string;
+}
+/** An in-memory gateway: tests move checkouts through their states. */
+export declare class FakeCryptoGateway implements CryptoCheckoutGateway {
+    readonly id = "btcpay";
+    readonly checkouts: Map<string, FakeCheckout>;
+    created: number;
+    private counter;
+    createCheckout(input: CreateCryptoCheckoutInput): Promise<CryptoCheckout>;
+    getCheckout(checkoutId: string): Promise<CryptoCheckout>;
+    listCheckouts(input: {
+        orderId: string;
+    }): Promise<CryptoCheckout[]>;
+    verifyWebhook(rawBody: string, headers: Headers | Record<string, string | undefined>): {
+        eventId: string;
+        checkoutId: string | null;
+        type: string;
+        redelivery: boolean;
+    };
+    /** Move a checkout: `paid` is fiat minor units received. */
+    set(checkoutId: string, status: CryptoCheckoutStatus, options?: {
+        exception?: CryptoCheckoutException;
+        paid?: number;
+        paymentStatus?: CryptoCheckoutPayment['status'];
+    }): void;
+    private view;
+}
+export interface RailWorld extends BillingWorld {
+    gateway: FakeCryptoGateway;
+    rail: BillingProvider;
+    runtime: BillingRuntime;
+    railLedger: BillingLedgerAccounts;
+    /** Provider invoice ids closed as paid out of band. */
+    outOfBand: string[];
+    /** Deliver a signed rail webhook for a checkout and process events. */
+    railEvent(checkoutId: string, eventId?: string): Promise<void>;
+}
+export declare function createRailWorld(db: DatabaseInterface, options?: {
+    paymentPolicy?: Partial<BillingPaymentPolicy>;
+    /** Give Stripe the out-of-band method (default true). */
+    outOfBand?: boolean;
+}): Promise<RailWorld>;
+export {};
+//# sourceMappingURL=crypto-rail.d.ts.map

package/dist/__tests__/helpers/crypto-rail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto-rail.d.ts","sourceRoot":"","sources":["../../../src/__tests__/helpers/crypto-rail.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAE1B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EAE1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAI7E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,KAAK,EACV,eAAe,EAEhB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,KAAK,qBAAqB,EAC1B,cAAc,EACf,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,sBAAsB,CAAC;AAG9B,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAC3D,eAAO,MAAM,cAAc,iBAAiB,CAAC;AAG7C,UAAU,YAAY;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,uBAAuB,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,qBAAa,iBAAkB,YAAW,qBAAqB;IAC7D,QAAQ,CAAC,EAAE,YAAY;IACvB,QAAQ,CAAC,SAAS,4BAAmC;IACrD,OAAO,SAAK;IACZ,OAAO,CAAC,OAAO,CAAK;IAEd,cAAc,CAClB,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,cAAc,CAAC;IAyBpB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAOxD,aAAa,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAM1E,aAAa,CACX,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;;;;;;IAsBvD,4DAA4D;IAC5D,GAAG,CACD,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,oBAAoB,EAC5B,OAAO,GAAE;QACP,SAAS,CAAC,EAAE,uBAAuB,CAAC;QACpC,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,qBAAqB,CAAC,QAAQ,CAAC,CAAC;KAC5C,GACL,IAAI;IA6BP,OAAO,CAAC,IAAI;CAsBb;AAED,MAAM,WAAW,SAAU,SAAQ,YAAY;IAC7C,OAAO,EAAE,iBAAiB,CAAC;IAC3B,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,cAAc,CAAC;IACxB,UAAU,EAAE,qBAAqB,CAAC;IAClC,uDAAuD;IACvD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,uEAAuE;IACvE,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE;AAID,wBAAsB,eAAe,CACnC,EAAE,EAAE,iBAAiB,EACrB,OAAO,GAAE;IACP,aAAa,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC9C,yDAAyD;IACzD,SAAS,CAAC,EAAE,OAAO,CAAC;CAChB,GACL,OAAO,CAAC,SAAS,CAAC,CAmFpB"}

package/dist/__tests__/helpers/fake-stripe.d.ts

@@ -39,6 +39,7 @@ interface FakeInvoice {
     amount_remaining: number;
     metadata: Record<string, string>;
     sent: number;
+    paid_out_of_band?: boolean;
 }
 interface FakeSession {
     id: string;

package/dist/__tests__/helpers/fake-stripe.d.ts.map

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

package/dist/billing/btcpay.d.ts

@@ -0,0 +1,40 @@
+/**
+ * BTCPay Server as a crypto payment rail (#3138): sugar over
+ * {@link createCryptoBillingProvider} with the SDK's BTCPay checkout gateway.
+ * One BTCPay store per seller; keys and secrets come from the host's secret
+ * store, never from this package.
+ */
+import { type BtcpayClientOptions, type BtcpaySpeedPolicy } from '@happyvertical/payments/btcpay';
+import type { BillingProvider } from './provider.js';
+export interface BtcPayBillingProviderOptions {
+    /** Server origin, for example `https://btcpay.example.com`. */
+    baseUrl: string;
+    /** Store-scoped key: `canviewinvoices` + `cancreateinvoice` suffice. */
+    apiKey: string;
+    storeId: string;
+    /** The store webhook's secret. */
+    webhookSecret: string;
+    /** Secret signing the `smrt_*` checkout metadata. */
+    metadataSecret: string;
+    /**
+     * Confirmations before BTCPay settles on-chain: `HighSpeed` 0,
+     * `MediumSpeed` 1, `LowMediumSpeed` 2 (default, the owner's settlement
+     * policy), `LowSpeed` 6.
+     */
+    speedPolicy?: BtcpaySpeedPolicy;
+    /** Default `['BTC-CHAIN']`; add `BTC-LN` once the store has Lightning. */
+    paymentMethods?: string[];
+    expirationMinutes?: number;
+    monitoringMinutes?: number;
+    /** BTCPay's own underpayment tolerance, percent (default 0). */
+    paymentTolerance?: number;
+    /** Label of the store's rate source, recorded on every payment. */
+    rateSource?: string;
+    /** Minimum checkout per currency, minor units. */
+    minimumAmount?: Record<string, number>;
+    /** Provider name (default `btcpay`). */
+    name?: string;
+    fetch?: BtcpayClientOptions['fetch'];
+}
+export declare function createBtcPayBillingProvider(options: BtcPayBillingProviderOptions): BillingProvider;
+//# sourceMappingURL=btcpay.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"btcpay.d.ts","sourceRoot":"","sources":["../../src/billing/btcpay.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EAEvB,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,WAAW,4BAA4B;IAC3C,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;CACtC;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,4BAA4B,GACpC,eAAe,CAsBjB"}

package/dist/billing/credits.d.ts

@@ -1,4 +1,4 @@
-import type { BillingProviderCheckoutSession } from './provider.js';
+import { type BillingProviderCheckoutSession } from './provider.js';
 import type { BillingRuntime } from './runtime.js';
 export declare const CREDIT_PURCHASE_PURPOSE = "credit_purchase";
 export interface CreateCreditCheckoutInput {
@@ -27,6 +27,11 @@ export interface CreateCreditCheckoutInput {
      * automatically charged invoices (#3139).
      */
     savePaymentMethod?: boolean;
+    /**
+     * The payment rail to pay with (a provider name from the runtime's
+     * `provider` or `paymentProviders`; default the issuing provider, #3138).
+     */
+    provider?: string;
 }
 /** 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":"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"}
+{"version":3,"file":"credits.d.ts","sourceRoot":"","sources":["../../src/billing/credits.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,KAAK,8BAA8B,EAEpC,MAAM,eAAe,CAAC;AACvB,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;IAC5B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;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,CAwHzC"}

package/dist/billing/crypto.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A crypto payment rail for the {@link BillingProvider} port (#3138).
+ *
+ * The rail runs short-lived, fiat-priced checkouts through a
+ * `CryptoCheckoutGateway` from `@happyvertical/payments` — BTCPay at launch,
+ * any other implementation of the port later. It never issues invoices: the
+ * runtime's issuing provider (Stripe) does, and this rail pays them or buys
+ * prepaid credit. Settlement is the gateway's decision (its confirmation
+ * policy); this package never counts confirmations.
+ */
+import { type CryptoCheckoutGateway } from '@happyvertical/payments';
+import { type BillingProvider } from './provider.js';
+export interface CryptoBillingProviderOptions {
+    /** A checkout gateway, for example `createBtcpayCheckoutGateway()`. */
+    gateway: CryptoCheckoutGateway;
+    /**
+     * Secret the `smrt_*` checkout metadata is signed with. Rotating it
+     * strands checkouts created before the rotation.
+     */
+    metadataSecret: string;
+    /** Provider name on local rows and in the inbox (default the gateway id). */
+    name?: string;
+    /**
+     * Smallest checkout accepted, per currency, in minor units (fee and dust
+     * economics). A currency without an entry has no minimum.
+     */
+    minimumAmount?: Record<string, number>;
+}
+export declare function createCryptoBillingProvider(options: CryptoBillingProviderOptions): BillingProvider;
+/** Exact decimal string → integer atomic units; rejects excess precision. */
+export declare function decimalToAtomic(value: string, exponent: number): number;
+//# sourceMappingURL=crypto.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/billing/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAEL,KAAK,qBAAqB,EAG3B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAGL,KAAK,eAAe,EAMrB,MAAM,eAAe,CAAC;AASvB,MAAM,WAAW,4BAA4B;IAC3C,uEAAuE;IACvE,OAAO,EAAE,qBAAqB,CAAC;IAC/B;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAKD,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,4BAA4B,GACpC,eAAe,CAqHjB;AAkED,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAYvE"}

package/dist/billing/events.d.ts

@@ -10,7 +10,8 @@
  */
 import { type ForgeProjector } from '@happyvertical/smrt-jobs';
 import { type SavedCard } from './cards.js';
-import type { BillingProviderCheckoutState, BillingProviderEvent, BillingProviderInvoiceState, BillingProviderSubscriptionState } from './provider.js';
+import { type AttemptTarget } from './payment-attempts.js';
+import type { BillingPaymentAttemptState, BillingProviderCheckoutState, BillingProviderEvent, BillingProviderInvoiceState, BillingProviderSubscriptionState } from './provider.js';
 import type { BillingRuntime } from './runtime.js';
 type InvoiceEvent = Extract<BillingProviderEvent, {
     kind: 'invoice';
@@ -24,6 +25,9 @@ type CheckoutEvent = Extract<BillingProviderEvent, {
 type PaymentEvent = Extract<BillingProviderEvent, {
     kind: 'payment';
 }>;
+type AttemptEvent = Extract<BillingProviderEvent, {
+    kind: 'payment_attempt';
+}>;
 type ObservedEvent = {
     event: InvoiceEvent;
     invoice: BillingProviderInvoiceState;
@@ -39,6 +43,11 @@ type ObservedEvent = {
 } | {
     event: PaymentEvent;
     paymentId: string;
+} | {
+    event: AttemptEvent;
+    providerName: string;
+    attempt: BillingPaymentAttemptState;
+    target: AttemptTarget;
 };
 /** 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,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"}
+{"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;AAqBlC,OAAO,EAKL,KAAK,SAAS,EAEf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,KAAK,aAAa,EAInB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACV,0BAA0B,EAE1B,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;AACvE,KAAK,YAAY,GAAG,OAAO,CAAC,oBAAoB,EAAE;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE,CAAC,CAAC;AAE/E,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,GAC1C;IACE,KAAK,EAAE,YAAY,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,0BAA0B,CAAC;IACpC,MAAM,EAAE,aAAa,CAAC;CACvB,CAAC;AAIN,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,CAqG/B"}

package/dist/billing/index.d.ts

@@ -3,12 +3,16 @@
  * card on file, and automatic top-ups (#3139).
  * @packageDocumentation
  */
+export { type BtcPayBillingProviderOptions, createBtcPayBillingProvider, } from './btcpay.js';
 export type { CreateCardSetupCheckoutInput } from './cards.js';
 export type { CreateCreditCheckoutInput } from './credits.js';
+export { type CryptoBillingProviderOptions, createCryptoBillingProvider, } from './crypto.js';
 export { addBillingMonths, billingPeriodContaining, lastEndedBillingPeriod, prorateMinorUnits, type ScheduledBillingPeriod, } from './cycles.js';
+export { type CreateInvoicePaymentInput, INVOICE_PAYMENT_PURPOSE, } from './invoice-payments.js';
 export { type EnqueueBillingJobOptions, enqueueBillingEvents, enqueueBillingPeriodClose, getBillingRuntime, registerBillingRuntime, unregisterBillingRuntime, } from './jobs.js';
+export { type BillingPaymentPolicy, type CryptoConversionInput, type CryptoSettlement, decideAttempt, type ManualRefundInput, type ManualRefundResult, } from './payment-attempts.js';
 export { type BillingPeriod, BillingPeriodCloseError, type ClosePeriodInput, type PeriodCloseGroupResult, type PeriodCloseOutcome, type PeriodCloseResult, previousCalendarMonth, } from './period-close.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 BillingChargeStatus, type BillingCollectionMethod, type BillingInvoiceEventType, type BillingPaymentAttemptException, type BillingPaymentAttemptPayment, type BillingPaymentAttemptState, type BillingPaymentAttemptStatus, type BillingProvider, type BillingProviderCapabilities, 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, BillingProviderUnsupportedError, BillingWebhookVerificationError, providerCapabilities, } 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';

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,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/billing/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,KAAK,4BAA4B,EACjC,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAC/D,YAAY,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EACL,KAAK,4BAA4B,EACjC,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,yBAAyB,EAC9B,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,wBAAwB,EAC7B,oBAAoB,EACpB,yBAAyB,EACzB,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,uBAAuB,CAAC;AAC/B,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,8BAA8B,EACnC,KAAK,4BAA4B,EACjC,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,EAChC,KAAK,eAAe,EACpB,KAAK,2BAA2B,EAChC,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,EAC/B,+BAA+B,EAC/B,oBAAoB,GACrB,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/invoice-payments.d.ts

@@ -0,0 +1,29 @@
+import { type BillingProviderCheckoutSession } from './provider.js';
+import type { BillingRuntime } from './runtime.js';
+export declare const INVOICE_PAYMENT_PURPOSE = "invoice_payment";
+export interface CreateInvoicePaymentInput {
+    invoiceId: string;
+    /** The payment rail (a provider name from `paymentProviders`). */
+    provider: string;
+    /**
+     * Caller-owned id for this attempt; a retry with the same id (and the same
+     * amount due) returns the same checkout.
+     */
+    purchaseId: string;
+    successUrl: string;
+    cancelUrl: string;
+    description?: string;
+}
+export interface InvoicePaymentMetadata {
+    purpose: string;
+    sellerTenantId: string;
+    payerTenantId: string;
+    billingAccountId: string;
+    invoiceId: string;
+    amount: number;
+    currency: string;
+}
+/** Parse checkout metadata written by {@link createInvoicePayment}. */
+export declare function invoicePaymentMetadata(raw: Record<string, string>): InvoicePaymentMetadata | null;
+export declare function createInvoicePayment(runtime: BillingRuntime, input: CreateInvoicePaymentInput): Promise<BillingProviderCheckoutSession>;
+//# sourceMappingURL=invoice-payments.d.ts.map

package/dist/billing/invoice-payments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoice-payments.d.ts","sourceRoot":"","sources":["../../src/billing/invoice-payments.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,KAAK,8BAA8B,EAEpC,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD,eAAO,MAAM,uBAAuB,oBAAoB,CAAC;AAUzD,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,uEAAuE;AACvE,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC1B,sBAAsB,GAAG,IAAI,CAuB/B;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,8BAA8B,CAAC,CA2HzC"}

package/dist/billing/payment-attempts.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Payment-rail attempts (#3138): per-seller policy, settlement of a rail
+ * checkout into credit or an invoice payment, and operator refund and
+ * conversion journals.
+ *
+ * The rail's gateway decides when a checkout is settled (its confirmation
+ * policy); this module never counts confirmations. It records everything the
+ * rail reports on a `BillingPaymentAttempt` and settles at most once, keyed by
+ * the checkout id.
+ */
+import type { DatabaseInterface } from '@happyvertical/smrt-core/migrations';
+import { type BillingPaymentAttempt, type BillingPaymentAttemptFlag, type BillingPaymentAttemptPurpose } from '../models/billing.js';
+import type { BillingPaymentAttemptState } from './provider.js';
+import type { BillingRuntime } from './runtime.js';
+/** Per-seller rules for rail payments. Every default is conservative. */
+export interface BillingPaymentPolicy {
+    /**
+     * Underpayment accepted as payment in full, in basis points of the price
+     * (default 0). The shortfall is not written off in the ledger.
+     */
+    underpaymentToleranceBps: number;
+    /** Overpayment not flagged for an operator, in basis points (default 0). */
+    overpaymentToleranceBps: number;
+    /**
+     * A payment received after the rate lock expired: `review` (default)
+     * flags it and settles nothing; `accept` settles when it covers the price.
+     */
+    latePaymentPolicy: 'review' | 'accept';
+    /** Settle checkouts an operator marked paid at the rail (default false). */
+    acceptManuallyMarked: boolean;
+    /** Hold received crypto (default) or hand it to `conversionHandler`. */
+    cryptoTreatment: 'hold' | 'convert';
+    /**
+     * Called after a settlement when `cryptoTreatment` is `convert`. It runs
+     * inside the event transaction and may run again on retry: enqueue work
+     * (for example a job) rather than calling an exchange directly.
+     */
+    conversionHandler?: (settlement: CryptoSettlement) => void | Promise<void>;
+    /** Refund basis recorded when a refund does not name one. */
+    refundBasis: 'original_native' | 'fiat_at_refund';
+}
+export interface CryptoSettlement {
+    sellerTenantId: string;
+    attemptId: string;
+    paymentId: string;
+    provider: string;
+    amount: number;
+    currency: string;
+    nativeCurrency: string;
+    nativeAmount: number;
+    db: DatabaseInterface;
+}
+export declare function normalizePaymentPolicy(input?: Partial<BillingPaymentPolicy>): BillingPaymentPolicy;
+export type AttemptDecision = {
+    action: 'settle';
+    flag: BillingPaymentAttemptFlag;
+} | {
+    action: 'none';
+    flag: BillingPaymentAttemptFlag;
+};
+/**
+ * What a rail checkout's state means for billing. Pure: the same state and
+ * policy always decide the same way, so `observe()` and `project()` agree.
+ */
+export declare function decideAttempt(state: BillingPaymentAttemptState, policy: BillingPaymentPolicy, expected: {
+    amount: number;
+    currency: string;
+}): AttemptDecision;
+/** The purpose and settlement target an attempt's verified metadata names. */
+export interface AttemptTarget {
+    purpose: BillingPaymentAttemptPurpose;
+    payerTenantId: string;
+    billingAccountId: string;
+    amount: number;
+    currency: string;
+    invoiceId: string;
+    spendingPolicyId: string;
+    grantedByTenantId: string;
+    /**
+     * The issuer reported the invoice paid by its own collection (for example
+     * a card charge whose event has not been applied yet): the rail's money is
+     * kept as customer credit, never allocated to the invoice.
+     */
+    issuerCollected?: boolean;
+}
+/** Read the target from verified metadata; null when not this seller's. */
+export declare function attemptTarget(runtime: BillingRuntime, metadata: Record<string, string>): AttemptTarget | null;
+export interface AttemptOutcome {
+    attempt: BillingPaymentAttempt;
+    /** The attempt left `confirming` without settling. */
+    endedUnsettled: boolean;
+    /** This application settled it. */
+    settled: boolean;
+}
+/**
+ * Record the rail's current state on the attempt and settle it once when the
+ * decision says so. `invoiceHook` applies standing for invoice payments.
+ */
+export declare function applyPaymentAttempt(runtime: BillingRuntime, db: DatabaseInterface, providerName: string, state: BillingPaymentAttemptState, target: AttemptTarget, source: 'webhook' | 'poll'): Promise<AttemptOutcome>;
+export interface ManualRefundInput {
+    /** The settled rail `Payment` refunded. */
+    paymentId: string;
+    /** Fiat value of the refund, minor units of the payment currency. */
+    fiatAmount: number;
+    /** Native amount sent back (satoshis), when known. */
+    nativeAmount?: number;
+    /** Default: the seller's `paymentPolicy.refundBasis`. */
+    basis?: 'original_native' | 'fiat_at_refund';
+    /** The operator's refund reference (for example the refund txid). */
+    reference: string;
+    reason: string;
+}
+export interface ManualRefundResult {
+    journalId: string;
+    creditGrantId: string;
+}
+/**
+ * Record a refund an operator made outside billing. Refunds come from what
+ * the payer is owed: first any overpayment, then — for a credit purchase, or
+ * an invoice payment kept as credit because the invoice was paid elsewhere —
+ * the price. An invoice payment applied to its invoice is not refundable
+ * here (reverse the invoice at the issuer first). Refunds are capped
+ * cumulatively per payment and are idempotent by `reference`.
+ */
+export declare function recordManualRefund(runtime: BillingRuntime, input: ManualRefundInput): Promise<ManualRefundResult>;
+export interface CryptoConversionInput {
+    /** Operator reference (for example the exchange trade id). */
+    reference: string;
+    currency: string;
+    nativeCurrency: string;
+    /** Native amount converted (satoshis). */
+    nativeAmount: number;
+    /** Book value of the converted holdings, minor units of `currency`. */
+    carryingValue: number;
+    /** Cash received, minor units. */
+    proceeds: number;
+    /** Fees paid, minor units (default 0). */
+    fees?: number;
+}
+export declare function recordCryptoConversion(runtime: BillingRuntime, input: CryptoConversionInput): Promise<{
+    journalId: string;
+}>;
+//# sourceMappingURL=payment-attempts.d.ts.map

package/dist/billing/payment-attempts.d.ts.map

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