@fantastic.dev/better-stripe 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -14,6 +14,30 @@
 - Remove internal tracker references from public documentation and add a
   regression check that prevents their reintroduction.
 
+## [0.14.0](https://github.com/FantasticDevHQ/better-stripe/compare/v0.13.0...v0.14.0) (2026-10-15)
+
+### Features
+
+- bind dispute evidence uploads and guard onboarding navigation ([#167](https://github.com/FantasticDevHQ/better-stripe/issues/167)) ([e52cd5d](https://github.com/FantasticDevHQ/better-stripe/commit/e52cd5dfc34d3c83a00d2f1686d07af5370b1e60))
+- **recovery:** preserve verified opening collections ([#163](https://github.com/FantasticDevHQ/better-stripe/issues/163)) ([e613ac0](https://github.com/FantasticDevHQ/better-stripe/commit/e613ac0d52d1d053b4e3a54dd0394ad1e427c729))
+
+### Bug Fixes
+
+- **recovery:** release unbound void invoice reservations ([#165](https://github.com/FantasticDevHQ/better-stripe/issues/165)) ([a73fd89](https://github.com/FantasticDevHQ/better-stripe/commit/a73fd893370688385fcf9dc2a8dd309d2cbd3ead))
+
+## [0.13.0](https://github.com/FantasticDevHQ/better-stripe/compare/v0.12.0...v0.13.0) (2026-10-15)
+
+### Features
+
+- **recovery:** reconcile seller cost invoice adjustments ([#159](https://github.com/FantasticDevHQ/better-stripe/issues/159)) ([d1ffdbc](https://github.com/FantasticDevHQ/better-stripe/commit/d1ffdbcb224b6c31ae958c576a4bcd6ff4a0a4dd))
+
+### Bug Fixes
+
+- **example:** bind reversal inputs to original charge currency ([#160](https://github.com/FantasticDevHQ/better-stripe/issues/160)) ([6b86926](https://github.com/FantasticDevHQ/better-stripe/commit/6b86926c7d4a173babd2964d4eee086f61c48f63))
+- **example:** reconcile unsettled disputed sources ([#161](https://github.com/FantasticDevHQ/better-stripe/issues/161)) ([9c732bd](https://github.com/FantasticDevHQ/better-stripe/commit/9c732bdc88555210d2172067e6bbf5d2fc513190))
+- **react:** isolate refund preview amounts by currency and status ([#162](https://github.com/FantasticDevHQ/better-stripe/issues/162)) ([601d509](https://github.com/FantasticDevHQ/better-stripe/commit/601d50923dc98f212b29fd4e4e3d856dfffbda44))
+- **react:** preserve original refund currency units ([#157](https://github.com/FantasticDevHQ/better-stripe/issues/157)) ([494827f](https://github.com/FantasticDevHQ/better-stripe/commit/494827f1cb35b0b0ca10b1c6da38a1095bb32500))
+
 ## [0.12.0](https://github.com/FantasticDevHQ/better-stripe/compare/v0.11.0...v0.12.0) (2026-10-15)
 
 ### Features

package/README.md

@@ -38,7 +38,7 @@ See the [customer preview setup and webhook migration guide](docs/accounts-v2-pr
 
 ## Status
 
-**Version**: `0.12.0` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
+**Version**: `0.14.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.
 
@@ -337,9 +337,10 @@ Methods named `get<Entity>` take the component document ID (exception: `getInvoi
 
 ### 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
+`stripe.costRecovery` is a server-only recovery client backed by the Convex
+component. Bookkeeping methods do not use Stripe credentials or move money.
+Invoice methods use the configured Stripe client and must run in an action.
+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
@@ -410,15 +411,99 @@ 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.
+reverse a transfer. For invoice groups, use the verified funding adapter below;
+do not invent 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.
+consent, provider fee policy and entitlement changes in the host.
+
+### Importing opening recovery balances
+
+When moving an existing ledger into the component, your server can call
+`stripe.costRecovery.importClaim(ctx, { ...observation, operationKey, collectedAmount })`.
+The observation includes the authorized account/scope/currency, original charge,
+gross and processing fee, approved cumulative amount due and a durable revision.
+`collectedAmount` is the signed amount already verified as collected before the
+cutover. The component retains that opening snapshot and computes outstanding as
+amount due minus the imported collection. It does not create a Stripe payment.
+
+Quiesce the old ledger's writers and verify its invoice and payout outcomes first.
+An unpaid invoice is a reservation, not a collection; an unknown provider outcome
+must stay held until reconciled. Do not import those amounts as collected or
+silently release them. Authorize source identity and original provider economics
+in the host before invoking this server-only bookkeeping operation.
+
+Use one stable import operation key per claim. A replay returns the current claim
+even after later observations or collections, without resetting its opening
+amount. Changing the opening snapshot or source binding, reusing an operation key
+for another claim, importing over a normal live claim, or introducing a new
+opening balance while the scope has a pending external recovery group is rejected.
+Signed credit collections and currencies stay separate. New observations continue
+through `recordClaim` with newer durable revisions.
+
+### Invoice recovery adjustments
+
+After authorizing the seller, invoice and liability scope, reserve with
+`sourceKind: "invoice"` and `sourceId: invoiceId`. Allocate bounded batches and
+seal the group before calling Stripe. Then attach exactly one signed adjustment
+for the entire group:
+
+```ts
+const receipt = await recovery.attachInvoice(ctx, { ...scope, groupKey });
+// Invoke from your invoice lifecycle reconciliation, and repeat bounded completion
+// until isDone after payment or release.
+const result = await recovery.reconcileInvoice(ctx, {
+  ...scope,
+  groupKey,
+  releaseUncollectible: false,
+});
+```
+
+The invoice must belong to the authorized customer account, use the same currency,
+and be draft before a new item is created. The package stores its stable group
+identity before the provider call, uses that identity as the idempotency key and
+item metadata, and persists the resulting item ID. Every retry scans all items
+on that exact invoice, recovering a successful creation even if the subsequent
+database write failed or the provider idempotency key expired. A bound item that
+has been deleted, changed or duplicated requires reconciliation; the package
+never silently recreates it. Negative adjustments are credits. Items are not
+discountable.
+
+Your host must durably serialize provider operations for each group, including
+attachment and any calls that finish or release it. Never release a reservation
+after a timeout or unknown provider outcome. Draft and open invoices retain their
+reservations, blocking recovery from a second payout. A verified paid invoice
+commits collection; a verified void releases the obligation for a future boundary.
+If an invoice is voided before its adjustment was attached, reconciliation releases
+an unbound sealed group only after scanning every item on that exact invoice.
+The receipt then has `invoiceItemId: null`. A missing previously bound item, or
+an absent adjustment on a paid or unpaid invoice, remains an error and keeps
+reservations held.
+Uncollectible invoices stay reserved unless your explicit host policy passes
+`releaseUncollectible: true`. Do not use that policy while another process might
+retry payment on the original invoice. Subscription cancellation alone does not
+prove its invoices were voided. These methods never attempt card fallback or
+change a payout schedule.
+
+For a collected invoice fully funded by one PaymentIntent, call
+`rollbackInvoice(ctx, { ...scope, groupKey, revision })`. It checks the paid
+invoice, completely paginates its payments, verifies the funding charge and its
+refund/dispute transactions, retains the original funding economics, and records
+a separate proportional rollback claim. Use a durable revision captured before
+provider reconciliation, and retry the full read on revision conflicts. Original
+cost claims remain intact. Multiple payments, partial allocations, mixed customer
+credits and non-PaymentIntent funding return
+`{ status: "not_ready", reason: "invoice_funding_allocation_required" }` without
+changing claims. Provider processing costs can also return their documented
+not-ready reasons. Those cases need a host-approved allocation policy rather than
+guessed amounts. Invoice integration in the example is a separate migration.
+
+Provider methods preserve the configured API version and propagate Stripe errors.
+See Stripe's [invoice item creation](https://docs.stripe.com/api/invoiceitems/create)
+and [invoice item pagination](https://docs.stripe.com/api/invoiceitems/list).
 
 ### Refund and dispute processing costs
 

package/dist/client/connect/disputes.d.ts

@@ -66,6 +66,26 @@ export declare function updateDispute(stripe: Stripe, component: Component, ctx:
 }): Promise<{
     success: true;
 }>;
+/** File fields supported by Stripe dispute evidence. */
+export type DisputeEvidenceFileField = "cancellation_policy" | "customer_communication" | "customer_signature" | "duplicate_charge_documentation" | "receipt" | "refund_policy" | "service_documentation" | "shipping_documentation" | "uncategorized_file";
+export type DisputeEvidenceUploadOptions = {
+    stripeDisputeId: string;
+    /** Derive this on the server from the authenticated session. */
+    actor: RefundActor;
+    field: DisputeEvidenceFileField;
+    file: {
+        data: Uint8Array;
+        name: string;
+        type: "application/pdf" | "image/jpeg" | "image/png";
+    };
+    /** Request account owning the charge, distinct from the seller actor. */
+    stripeAccountId?: string;
+};
+/** Upload and attach to one authorized dispute as a draft. Never submits. */
+export declare function uploadDisputeEvidence(stripe: Stripe, component: Component, ctx: RunCtx, opts: DisputeEvidenceUploadOptions): Promise<{
+    stripeFileId: string;
+    stripeDisputeId: string;
+}>;
 /**
  * Accept a dispute (concede the chargeback). Irreversible.
  *

package/dist/client/connect/disputes.d.ts.map

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

package/dist/client/connect/disputes.js

@@ -82,6 +82,61 @@ export async function updateDispute(stripe, component, ctx, opts) {
         throwStripeError("DISPUTE_UPDATE_FAILED", "Failed to update dispute", err);
     }
 }
+/** Upload and attach to one authorized dispute as a draft. Never submits. */
+export async function uploadDisputeEvidence(stripe, component, ctx, opts) {
+    if (!opts.actor ||
+        !["admin", "seller"].includes(opts.actor.type) ||
+        (opts.actor.type === "seller" &&
+            (typeof opts.actor.accountId !== "string" ||
+                !opts.actor.accountId.trim())))
+        throwStripeError("DISPUTE_UNAUTHORIZED", "Dispute upload requires an authenticated actor");
+    await assertDisputeAuthorized(component, ctx, opts);
+    const fields = [
+        "cancellation_policy",
+        "customer_communication",
+        "customer_signature",
+        "duplicate_charge_documentation",
+        "receipt",
+        "refund_policy",
+        "service_documentation",
+        "shipping_documentation",
+        "uncategorized_file",
+    ];
+    const { data, name, type } = opts.file;
+    const signature = type === "application/pdf"
+        ? [37, 80, 68, 70, 45]
+        : type === "image/jpeg"
+            ? [255, 216, 255]
+            : type === "image/png"
+                ? [137, 80, 78, 71, 13, 10, 26, 10]
+                : [];
+    if (!fields.includes(opts.field) ||
+        !(data instanceof Uint8Array) ||
+        !data.byteLength ||
+        data.byteLength > 5_000_000 ||
+        !name.trim() ||
+        !signature.length ||
+        !signature.every((byte, i) => data[i] === byte))
+        throwStripeError("INVALID_CONFIGURATION", "Invalid dispute evidence: use a nonempty PDF, JPEG or PNG up to 5 MB with a matching MIME type and filename");
+    let stripeFileId;
+    try {
+        const file = await stripe.files.create({ purpose: "dispute_evidence", file: { data, name, type } }, opts.stripeAccountId
+            ? { stripeAccount: opts.stripeAccountId }
+            : undefined);
+        stripeFileId = file.id;
+    }
+    catch (err) {
+        throwStripeError("DISPUTE_UPLOAD_FAILED", "Failed to upload dispute evidence", err);
+    }
+    await updateDispute(stripe, component, ctx, {
+        stripeDisputeId: opts.stripeDisputeId,
+        actor: opts.actor,
+        stripeAccountId: opts.stripeAccountId,
+        evidence: { [opts.field]: stripeFileId },
+        submit: false,
+    });
+    return { stripeFileId, stripeDisputeId: opts.stripeDisputeId };
+}
 /**
  * Accept a dispute (concede the chargeback). Irreversible.
  *

package/dist/client/connect/disputes.js.map

@@ -1 +1 @@
-{"version":3,"file":"disputes.js","sourceRoot":"","sources":["../../../src/client/connect/disputes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"disputes.js","sourceRoot":"","sources":["../../../src/client/connect/disputes.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMhD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAoB,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAIxE,gFAAgF;AAChF,kBAAkB;AAClB,EAAE;AACF,yEAAyE;AACzE,6EAA6E;AAC7E,gFAAgF;AAChF,gFAAgF;AAEhF,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,SAAoB,EACpB,GAAW,EACX,IAAiC;IAEjC,OAAO,CAAC,MAAM,GAAG,CAAC,QAAQ,CACxB,YAAY,CAAC,SAAS,EAAE,sCAAsC,CAAC,EAC/D,IAAI,CACL,CAAkC,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,SAAoB,EACpB,GAAW,EACX,IAA6C;IAO7C,MAAM,OAAO,GAAG,MAAM,oBAAoB,CAAC,SAAS,EAAE,GAAG,EAAE;QACzD,eAAe,EAAE,IAAI,CAAC,eAAe;KACtC,CAAC,CAAC;IACH,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,OAAO;QACL,GAAG,OAAO;QACV,SAAS,EAAE,wBAAwB,CAAC,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC;KACrE,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,SAAoB,EACpB,GAAW,EACX,IAKC;IAED,MAAM,EAAE,eAAe,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC;IAChD,OAAO,CAAC,MAAM,GAAG,CAAC,QAAQ,CACxB,YAAY,CAAC,SAAS,EAAE,8BAA8B,CAAC,EACvD;QACE,GAAG,IAAI;QACP,GAAG,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACzE,CACF,CAA6B,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAc,EACd,SAAoB,EACpB,GAAW,EACX,IAcC;IAED,8EAA8E;IAC9E,6EAA6E;IAC7E,MAAM,uBAAuB,CAAC,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAEpD,0EAA0E;IAC1E,qEAAqE;IACrE,2EAA2E;IAC3E,+CAA+C;IAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,CAAC,MAAM,CAC1B,IAAI,CAAC,eAAe,EACpB;YACE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,MAAM;SACP,EACD,IAAI,CAAC,eAAe;YAClB,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,eAAe,EAAE;YACzC,CAAC,CAAC,SAAS,CACd,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,gBAAgB,CAAC,uBAAuB,EAAE,0BAA0B,EAAE,GAAG,CAAC,CAAC;IAC7E,CAAC;AACH,CAAC;AA2BD,6EAA6E;AAC7E,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAc,EACd,SAAoB,EACpB,GAAW,EACX,IAAkC;IAElC,IACE,CAAC,IAAI,CAAC,KAAK;QACX,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;QAC9C,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ;YAC3B,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,KAAK,QAAQ;gBACvC,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;QAElC,gBAAgB,CACd,sBAAsB,EACtB,gDAAgD,CACjD,CAAC;IACJ,MAAM,uBAAuB,CAAC,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IACpD,MAAM,MAAM,GAA+B;QACzC,qBAAqB;QACrB,wBAAwB;QACxB,oBAAoB;QACpB,gCAAgC;QAChC,SAAS;QACT,eAAe;QACf,uBAAuB;QACvB,wBAAwB;QACxB,oBAAoB;KACrB,CAAC;IACF,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC;IACvC,MAAM,SAAS,GACb,IAAI,KAAK,iBAAiB;QACxB,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;QACtB,CAAC,CAAC,IAAI,KAAK,YAAY;YACrB,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;YACjB,CAAC,CAAC,IAAI,KAAK,WAAW;gBACpB,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;gBACnC,CAAC,CAAC,EAAE,CAAC;IACb,IACE,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;QAC5B,CAAC,CAAC,IAAI,YAAY,UAAU,CAAC;QAC7B,CAAC,IAAI,CAAC,UAAU;QAChB,IAAI,CAAC,UAAU,GAAG,SAAS;QAC3B,CAAC,IAAI,CAAC,IAAI,EAAE;QACZ,CAAC,SAAS,CAAC,MAAM;QACjB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;QAE/C,gBAAgB,CACd,uBAAuB,EACvB,6GAA6G,CAC9G,CAAC;IACJ,IAAI,YAAoB,CAAC;IACzB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,MAAM,CACpC,EAAE,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAC3D,IAAI,CAAC,eAAe;YAClB,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,eAAe,EAAE;YACzC,CAAC,CAAC,SAAS,CACd,CAAC;QACF,YAAY,GAAG,IAAI,CAAC,EAAE,CAAC;IACzB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,gBAAgB,CACd,uBAAuB,EACvB,mCAAmC,EACnC,GAAG,CACJ,CAAC;IACJ,CAAC;IACD,MAAM,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE;QAC1C,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,YAAY,EAAE;QACxC,MAAM,EAAE,KAAK;KACd,CAAC,CAAC;IACH,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,IAAI,CAAC,eAAe,EAAE,CAAC;AACjE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAc,EACd,SAAoB,EACpB,GAAW,EACX,IAKC;IAED,sEAAsE;IACtE,MAAM,uBAAuB,CAAC,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAEpD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,CAAC,KAAK,CACzB,IAAI,CAAC,eAAe,EACpB,EAAE,EACF,IAAI,CAAC,eAAe;YAClB,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,eAAe,EAAE;YACzC,CAAC,CAAC,SAAS,CACd,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,gBAAgB,CAAC,uBAAuB,EAAE,yBAAyB,EAAE,GAAG,CAAC,CAAC;IAC5E,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,KAAK,UAAU,uBAAuB,CACpC,SAAoB,EACpB,GAAW,EACX,IAAsD;IAEtD,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;IACvB,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,CAAC,eAAe;IAE7D,MAAM,OAAO,GAAG,MAAM,oBAAoB,CAAC,SAAS,EAAE,GAAG,EAAE;QACzD,eAAe,EAAE,IAAI,CAAC,eAAe;KACtC,CAAC,CAAC;IACH,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,gBAAgB,CACd,sBAAsB,EACtB,uDAAuD,IAAI,CAAC,eAAe,2BAA2B,CACvG,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,2EAA2E;IAC3E,uEAAuE;IACvE,MAAM,IAAI,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAC3C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,gBAAgB,CACd,sBAAsB,EACtB,0CAA0C,IAAI,CAAC,eAAe,uDAAuD,CACtH,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,QAAQ,CACjC,YAAY,CAAC,SAAS,EAAE,sCAAsC,CAAC,EAC/D,EAAE,qBAAqB,EAAE,IAAI,EAAE,CAChC,CAAkC,CAAC;IACpC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,gBAAgB,CACd,sBAAsB,EACtB,uDAAuD,IAAI,2BAA2B,CACvF,CAAC;IACJ,CAAC;IAED,IACE,CAAC,kBAAkB,CAAC,KAAK,EAAE;QACzB,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;QAClD,eAAe,EAAE,OAAO,CAAC,eAAe;KACzC,CAAC,EACF,CAAC;QACD,gBAAgB,CACd,sBAAsB,EACtB,yCAAyC,KAAK,CAAC,SAAS,gEAAgE,CACzH,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,KASpC;IACC,MAAM,aAAa,GAAG,KAAK,CAAC,qBAAqB,CAAC;IAClD,MAAM,IAAI,GAAG,aAAa,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5E,MAAM,IAAI,GAAG;QACX,KAAK,CAAC,cAAc;QACpB,CAAC,IAAI,IAAI,aAAa;YACpB,CAAC,CAAC,4BAA4B,aAAa,EAAE;YAC7C,CAAC,CAAC,SAAS;KACd;SACE,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,MAAM,CAAC,CAAC;IAChB,OAAO;QACL,GAAG,CAAC,KAAK,CAAC,kBAAkB;YAC1B,CAAC,CAAC,EAAE,mBAAmB,EAAE,KAAK,CAAC,kBAAkB,EAAE;YACnD,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,KAAK,CAAC,cAAc;YACtB,CAAC,CAAC,EAAE,mBAAmB,EAAE,KAAK,CAAC,cAAc,EAAE;YAC/C,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,sBAAsB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CACtC,aAAiC,EACjC,GAAG,GAAS,IAAI,IAAI,EAAE;IAEtB,IAAI,CAAC,aAAa;QAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAClE,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,aAAa,CAAC,CAAC,OAAO,EAAE,CAAC;IAChD,4EAA4E;IAC5E,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACvE,MAAM,MAAM,GAAG,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC;IACrC,OAAO;QACL,KAAK,EAAE,aAAa;QACpB,aAAa,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC;QAC7C,SAAS,EAAE,MAAM,GAAG,CAAC;KACtB,CAAC;AACJ,CAAC"}

package/dist/client/costRecovery-invoices.d.ts

@@ -0,0 +1,44 @@
+import type Stripe from "stripe";
+import type { RecoveryGroup, RecoveryScope } from "./costRecovery.js";
+export type RecoveryInvoiceOptions = RecoveryScope & {
+    groupKey: string;
+};
+type InvoiceReceipt = {
+    group: RecoveryGroup;
+    invoiceItemId: string;
+    invoiceStatus: Stripe.Invoice["status"];
+};
+type BindInvoiceItem = (invoiceItemId: string) => Promise<RecoveryGroup>;
+/** Attachment always produces an item; reconciliation can release an unbound void invoice. */
+export declare function attachRecoveryInvoice(stripe: Stripe, group: RecoveryGroup | null, opts: RecoveryInvoiceOptions, bind: BindInvoiceItem, create?: true): Promise<InvoiceReceipt>;
+export declare function attachRecoveryInvoice(stripe: Stripe, group: RecoveryGroup | null, opts: RecoveryInvoiceOptions, bind: BindInvoiceItem, create: false): Promise<InvoiceReceipt | (Omit<InvoiceReceipt, "invoiceItemId"> & {
+    invoiceItemId: null;
+})>;
+/** Refuse ambiguous cash/credit or multi-payment allocations instead of inventing economics. */
+export declare function readInvoiceFunding(stripe: Stripe, group: RecoveryGroup): Promise<{
+    status: "not_ready";
+    paymentIntentId: string;
+    reason: import("./index.js").ProcessingCostNotReadyReason;
+} | {
+    status: "ready";
+    paymentIntentId: string;
+    chargeId: string;
+    currency: string;
+    gross: number;
+    metadata: Record<string, string>;
+    processingFee: number;
+    refundFeeAdjustment: number;
+    disputeFeeAdjustment: number;
+    netFees: number;
+    refundedPrincipal: number;
+    disputedPrincipal: number;
+    principalReturned: number;
+    refunds: import("./index.js").ProcessingCostRecord[];
+    disputes: import("./index.js").ProcessingCostRecord[];
+    transactions: import("./index.js").ProcessingCostTransaction[];
+} | {
+    status: "not_ready";
+    reason: "invoice_funding_allocation_required";
+}>;
+export {};
+//# sourceMappingURL=costRecovery-invoices.d.ts.map

package/dist/client/costRecovery-invoices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"costRecovery-invoices.d.ts","sourceRoot":"","sources":["../../src/client/costRecovery-invoices.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACtE,MAAM,MAAM,sBAAsB,GAAG,aAAa,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAK1E,KAAK,cAAc,GAAG;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;CACzC,CAAC;AACF,KAAK,eAAe,GAAG,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;AAEzE,8FAA8F;AAC9F,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,GAAG,IAAI,EAC3B,IAAI,EAAE,sBAAsB,EAC5B,IAAI,EAAE,eAAe,EACrB,MAAM,CAAC,EAAE,IAAI,GACZ,OAAO,CAAC,cAAc,CAAC,CAAC;AAC3B,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,GAAG,IAAI,EAC3B,IAAI,EAAE,sBAAsB,EAC5B,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,KAAK,GACZ,OAAO,CACN,cAAc,GACd,CAAC,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC,GAAG;IAAE,aAAa,EAAE,IAAI,CAAA;CAAE,CAAC,CACpE,CAAC;AAmGF,gGAAgG;AAChG,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa;;;;;;;;;;;;;;;;;;;;;;YA8B/D,WAAW;YACX,qCAAqC;GAYlD"}

package/dist/client/costRecovery-invoices.js

@@ -0,0 +1,109 @@
+import { getProcessingCostContext } from "./settlement/processingCosts.js";
+const marker = "bsRecoveryGroup";
+const id = (value) => typeof value === "string" ? value : value?.id;
+/** One immutable item per sealed group. Host serializes provider operations per group. */
+export async function attachRecoveryInvoice(stripe, group, opts, bind, create = true) {
+    if (!group ||
+        group.groupKey !== opts.groupKey ||
+        group.sourceKind !== "invoice" ||
+        group.accountId !== opts.accountId ||
+        group.scopeKey !== opts.scopeKey ||
+        group.currency !== opts.currency)
+        throw new Error("Recovery invoice scope does not match the authorized group.");
+    if (group.status === "open" ||
+        (create && ["released", "releasing"].includes(group.status)))
+        throw new Error("Invoice recovery group must be sealed and active.");
+    const invoice = await stripe.invoices.retrieve(group.sourceId);
+    if (invoice.id !== group.sourceId ||
+        invoice.customer_account !== group.accountId)
+        throw new Error("Recovery invoice ownership does not match.");
+    if (invoice.currency !== group.currency)
+        throw new Error("Recovery invoice currency does not match.");
+    let found;
+    for await (const item of stripe.invoiceItems.list({
+        invoice: invoice.id,
+        limit: 100,
+    })) {
+        if (item.metadata?.[marker] !== group._id)
+            continue;
+        if (found)
+            throw new Error("Duplicate recovery invoice items require reconciliation.");
+        if (id(item.invoice) !== invoice.id ||
+            item.customer_account !== group.accountId ||
+            item.currency !== group.currency ||
+            item.amount !== group.amount ||
+            item.discountable ||
+            (group.invoiceItemId && group.invoiceItemId !== item.id))
+            throw new Error("Recovery invoice item economics or identity do not match.");
+        found = item;
+    }
+    if (!found) {
+        if (group.invoiceItemId)
+            throw new Error("Bound recovery invoice item is missing; reconcile before retrying.");
+        if (!create &&
+            invoice.status === "void" &&
+            ["sealed", "releasing", "released"].includes(group.status))
+            return { group, invoiceItemId: null, invoiceStatus: invoice.status };
+        if (!create)
+            throw new Error("Recovery invoice item is missing; no collection can be confirmed.");
+        if (group.status !== "sealed")
+            throw new Error("New recovery items require a sealed, uncompleted group.");
+        if (invoice.status !== "draft")
+            throw new Error("New recovery items require a draft invoice.");
+        found = await stripe.invoiceItems.create({
+            invoice: invoice.id,
+            customer_account: group.accountId,
+            currency: group.currency,
+            amount: group.amount,
+            discountable: false,
+            description: "Refund and dispute cost adjustment",
+            metadata: { [marker]: group._id },
+        }, { idempotencyKey: `better-stripe:recovery:${group._id}` });
+    }
+    const bound = group.invoiceItemId === found.id ? group : await bind(found.id);
+    return {
+        group: bound,
+        invoiceItemId: found.id,
+        invoiceStatus: invoice.status,
+    };
+}
+/** Refuse ambiguous cash/credit or multi-payment allocations instead of inventing economics. */
+export async function readInvoiceFunding(stripe, group) {
+    const invoice = await stripe.invoices.retrieve(group.sourceId);
+    if (invoice.customer_account !== group.accountId ||
+        invoice.currency !== group.currency ||
+        invoice.status !== "paid")
+        throw new Error("Invoice funding ownership, currency or paid state does not match.");
+    const payments = [];
+    for await (const payment of stripe.invoicePayments.list({
+        invoice: group.sourceId,
+        limit: 100,
+    })) {
+        if (id(payment.invoice) !== group.sourceId ||
+            payment.currency !== group.currency)
+            throw new Error("Invoice payment identity or currency does not match.");
+        if (payment.status === "paid")
+            payments.push(payment);
+    }
+    const payment = payments[0];
+    if (payments.length !== 1 ||
+        payment?.payment.type !== "payment_intent" ||
+        !payment.payment.payment_intent ||
+        payment.amount_paid !== invoice.amount_paid)
+        return {
+            status: "not_ready",
+            reason: "invoice_funding_allocation_required",
+        };
+    const cost = await getProcessingCostContext(stripe, {
+        paymentIntentId: id(payment.payment.payment_intent),
+    });
+    if (cost.status === "not_ready")
+        return cost;
+    if (cost.currency !== group.currency || cost.gross !== invoice.amount_paid)
+        return {
+            status: "not_ready",
+            reason: "invoice_funding_allocation_required",
+        };
+    return cost;
+}
+//# sourceMappingURL=costRecovery-invoices.js.map

package/dist/client/costRecovery-invoices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"costRecovery-invoices.js","sourceRoot":"","sources":["../../src/client/costRecovery-invoices.ts"],"names":[],"mappings":"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"}

package/dist/client/costRecovery.d.ts

@@ -1,3 +1,4 @@
+import type Stripe from "stripe";
 import type { Component, RunCtx } from "./helpers.js";
 export type RecoveryScope = {
     accountId: string;
@@ -19,6 +20,12 @@ export type RecoveryClaim = RecoveryObservation & {
     reservedAmount: number;
     outstanding: number;
     sign: "positive" | "negative" | "zero";
+    openingCollection?: {
+        operationKey: string;
+        amountDue: number;
+        revision: number;
+        collectedAmount: number;
+    };
 };
 export type RecoveryBalance = RecoveryScope & {
     amountDue: number;
@@ -47,6 +54,12 @@ export type RecoveryGroup = RecoveryGroupOptions & {
     _creationTime: number;
     amount: number;
     pendingOperations: number;
+    invoiceItemId?: string;
+    invoiceFunding?: {
+        sourceChargeId: string;
+        sourceGross: number;
+        sourceProcessingFee: number;
+    };
     status: "open" | "sealed" | "collecting" | "releasing" | "collected" | "released";
 };
 export type RecoveryReservation = {
@@ -63,12 +76,56 @@ export type RecoveryReservation = {
     }[];
     status: "reserved" | "collected" | "released" | "empty";
 };
-/** Durable bookkeeping only. Host authorizes policy and verifies provider outcomes. */
+/** Host authorizes policy and scope. Provider methods verify invoice outcomes. */
 export declare class CostRecoveryClient {
     private readonly component;
-    constructor(component: Component);
+    private readonly provider?;
+    constructor(component: Component, provider?: (() => Stripe) | undefined);
     private mutate;
     private query;
+    /** Host authorizes the account, scope and invoice group; call from an action. */
+    attachInvoice(ctx: RunCtx, opts: RecoveryScope & {
+        groupKey: string;
+    }): Promise<{
+        group: RecoveryGroup;
+        invoiceItemId: string;
+        invoiceStatus: Stripe.Invoice["status"];
+    }>;
+    /** Re-read Stripe; keep unpaid items reserved. Repeat until isDone after terminal outcomes. */
+    reconcileInvoice(ctx: RunCtx, opts: RecoveryScope & {
+        groupKey: string;
+        releaseUncollectible?: boolean;
+    }): Promise<{
+        isDone: boolean;
+        group: RecoveryGroup;
+        invoiceItemId: string;
+        invoiceStatus: Stripe.Invoice["status"];
+    } | {
+        isDone: boolean;
+        group: RecoveryGroup;
+        invoiceStatus: Stripe.Invoice["status"];
+        invoiceItemId: null;
+    }>;
+    /** Reconcile a returned funding charge without changing the original cost claims. */
+    rollbackInvoice(ctx: RunCtx, opts: RecoveryScope & {
+        groupKey: string;
+        revision: number;
+    }): Promise<{
+        status: "not_ready";
+        paymentIntentId: string;
+        reason: import("./index.js").ProcessingCostNotReadyReason;
+    } | {
+        status: "ready";
+        claim: RecoveryClaim;
+    } | {
+        status: "not_ready";
+        reason: "invoice_funding_allocation_required";
+    }>;
+    /** Import a host-verified opening collection. Never overwrites a live claim. */
+    importClaim(ctx: RunCtx, opts: RecoveryObservation & {
+        operationKey: string;
+        collectedAmount: number;
+    }): Promise<RecoveryClaim>;
     recordClaim(ctx: RunCtx, opts: RecoveryObservation): Promise<RecoveryClaim>;
     reserve(ctx: RunCtx, opts: RecoveryGroupOptions & {
         operationKey: string;

package/dist/client/costRecovery.d.ts.map

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