@fantastic.dev/better-stripe 0.23.2 → 0.24.0

package/CHANGELOG.md

@@ -2,11 +2,23 @@
 
 ## Unreleased
 
+- Add original affiliate commission obligations, exact reversal receipts,
+  currency-scoped debt offsets before future transfers, receipt-backed dispute
+  restoration, payout release reservations and paginated audit/migration APIs.
+  Add authenticated example views, reusable React recovery components, scheduled
+  reconciliation and simulated scenario/video evidence. Document actual provider
+  restrictions and sandbox verification limits in the [clawback guide](docs/affiliate-clawbacks.md).
+- Base split refund recovery on cumulative succeeded refunds, excluding pending
+  and failed refunds from finalized obligations. Calculate affiliate dispute
+  exposure from original gross charge principal, with deterministic integer
+  rounding and an original-commission cap.
+
 - Return every original split leg by default from `listTransfersByCharge`,
   excluding reinstatement rows before applying any explicit preview limit.
   Split breakdowns and reversal claims now cover sales with more than 50 legs.
-  Queries and atomic claims fail on Convex resource limits rather than silently
-  truncate financial data. `listTransfersByAccount` remains a preview API;
+  Atomic claims fail explicitly above 1,000 charge-linked transfer rows;
+  queries also fail on Convex resource limits rather than silently truncate
+  financial data. `listTransfersByAccount` remains a preview API;
   earnings hooks use exact server-side aggregates.
 - Update the former roadmap to describe the existing product-level first-charge
   descriptors, first-invoice fee recovery, retry-safe reversal claims, and exact
@@ -14,6 +26,12 @@
 - Remove internal tracker references from public documentation and add a
   regression check that prevents their reintroduction.
 
+## [0.24.0](https://github.com/FantasticDevHQ/better-stripe/compare/v0.23.2...v0.24.0) (2026-10-15)
+
+### Features
+
+- add affiliate commission recovery and future earnings offsets ([#191](https://github.com/FantasticDevHQ/better-stripe/issues/191)) ([49f38ac](https://github.com/FantasticDevHQ/better-stripe/commit/49f38ac78f12415d6a330b4729ade56950ee2ad5))
+
 ## [0.23.2](https://github.com/FantasticDevHQ/better-stripe/compare/v0.23.1...v0.23.2) (2026-10-15)
 
 ### Bug Fixes

package/README.md

@@ -55,7 +55,7 @@ schedule controls alone do not enforce a minimum.
 
 ## Status
 
-**Version**: `0.23.2` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
+**Version**: `0.24.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.
 
@@ -194,7 +194,8 @@ The marketplace economics layer includes platform fees, split transfers, rolling
 - **First subscription charge descriptor** — `createProduct` and `updateProduct` stamp the store's descriptor (or platform fallback) onto store-owned Stripe products. The product descriptor covers the first invoice for direct subscriptions and Checkout subscription mode; the invoice-time descriptor still takes precedence on later invoices. Existing products need `updateProduct` to receive the descriptor, and a later store descriptor change requires refreshing its products. Shared products have one descriptor and should not be reused across stores that need different descriptors.
 - **First-invoice fees** — finalized first invoices bypass the draft update window. At `invoice.paid`, the processor collects the fixed/tiered fee through a partial reversal of the destination transfer. Invoice markers and invoice-tagged reversals prevent duplicate collection, including recovery after a failed marker write. Renewals whose fees were set on the draft invoice are skipped.
 - **Dispute reversal retries** — reversal slices are claimed atomically before any Stripe call. Partial-success retries reuse the recorded amounts and idempotency keys, skip confirmed legs, and reconcile money already moved before a ledger-write failure.
-- **Earnings and split totals** — `useEarnings` reads exact server-side aggregates with bounded drill-down previews. `listTransfersByAccount` remains a preview API; do not sum it for financial totals. `listTransfersByCharge` now returns every original split leg by default, and reversal claims cover all of those legs. An explicit list limit requests a preview. Convex read/write/response limits fail loudly rather than silently truncate financial data.
+- **Affiliate commission recovery** — original commission snapshots, shared refund/dispute exposure, reversal receipts, and a resumable backfill are available. Currency-scoped future-commission offsets, receipt-backed dispute restoration, payout reservations, and reusable recovery views are included. See [affiliate commission clawbacks](docs/affiliate-clawbacks.md).
+- **Earnings and split totals** — `useEarnings` reads exact server-side aggregates with bounded drill-down previews. `listTransfersByAccount` remains a preview API; do not sum it for financial totals. `listTransfersByCharge` now returns every original split leg by default, and reversal claims cover up to 1,000 charge-linked transfer rows, failing explicitly above that bound. An explicit list limit requests a preview. Convex read/write/response limits fail loudly rather than silently truncate financial data.
 
 ## Installation
 
@@ -1085,8 +1086,8 @@ Payouts are **automatic and rolling** (Stripe-managed schedule, via hosted Expre
 
 The platform is merchant of record, so a chargeback lands on the platform's Stripe account even for a seller's sale. The dispute pipeline (all webhook-driven, on `charge.dispute.*`):
 
-1. **Clawback** — when a dispute opens (`charge.dispute.created`), `reverseTransfers` reverses the split/destination transfers funded by the disputed charge, pro-rata to the disputed amount, so recipients bear their share of the loss. Idempotent via the dispute id.
-2. **Reinstatement** — if the dispute is won (`.closed` with `status: "won"`, or `.funds_reinstated`), `reinstateTransfers` re-creates transfers for the amounts clawed back, paying recipients back from the platform balance (Stripe's own reversal is permanent, so winning means paying again).
+1. **Clawback** — a monetary `charge.dispute.created` event uses the disputed charge's original gross amount to calculate affiliate commission exposure. Inquiry/warning, prevented, and already-won payloads do not trigger recovery. Affiliate legs share the original-principal exposure axis with refunds; seller and other legs retain the existing reversal allocation. The dispute ID identifies the operation, and a missing authoritative charge amount causes recovery to retry.
+2. **Reinstatement** — if the dispute is won (`.closed` with `status: "won"`, or `.funds_reinstated`), the existing `reinstateTransfers` path creates new transfers from the platform balance. Affiliate restoration uses exact reversal/offset receipts, preserves independent successful refunds, and cancels unpaid dispute debt. Failed or uncertain restoration remains visible until reconciled. See [recovery limitations](docs/affiliate-clawbacks.md#verification-evidence).
 3. **Auto-cancel** — on dispute open, the disputed subscription (resolved PaymentIntent → invoice → subscription) is canceled by default (`registerRoutes`'s `autoCancelOnDispute`, default `true`; pairs with `cancelDisputeAtPeriodEnd`, default `false` → cancel-at-period-end, matching the Skool model of "cancel now, remove access at cycle end").
 
 Sellers respond to their own disputes without platform staff involvement, via an embedded Stripe Connect session:
@@ -1103,6 +1104,40 @@ export const createDisputeSession = action({
 
 `stripe.reverseTransfers(ctx, { sourceChargeId, percent?, amount? })` is also exposed directly, for manual clawback outside the automatic dispute flow (e.g. a support-initiated partial reversal). The internal engine additionally accepts an `operationId` for a stable Stripe idempotency key (used by the automatic dispute flow); the public method doesn't expose it yet, so a manual call relies on Stripe's default request idempotency.
 
+For commissions tracked by the recovery ledger, generic manual reversal is
+rejected. Use `createRefund` for a real refund or `stripe.affiliateRecovery.retry`
+for a recovery operation, so existing offsets and uncertain receipts remain
+coordinated.
+
+### Affiliate commission accounting
+
+The component stores each original affiliate transfer's commission and currency,
+links available payment/invoice references, and separates finalized obligations,
+provisional dispute exposure, reserved slices, and confirmed reversals. New
+commission reversal operations reconcile exact Stripe receipts after interrupted
+ledger writes. Percentage and fixed commissions use the original allocated
+amount, with deterministic rounding in integer currency units.
+
+Trusted host APIs under `components.betterStripe.settlement` provide
+`queries.listAffiliateObligations` and
+`mutations.migrateAffiliateObligations`. Authorize account ownership before
+exposing snapshots and restrict migration to operators. Existing rows with
+unattributed reversal balances require reconciliation. See the
+[API and migration guide](docs/affiliate-clawbacks.md#migration-and-operator-reconciliation).
+
+Insufficient-balance debt is offset atomically against eligible future commissions
+in the same currency before transfer creation. Dispute wins restore only actual
+reversals/offsets and retain independent refunds. `stripe.affiliateRecovery`
+provides snapshots, history, operator retry and legacy review; the reusable
+`AffiliateRecovery`/`AffiliateRecoveryHistory` views consume those records.
+
+Affiliate payouts require a stable idempotency key and pass an atomic debt and
+reservation gate. An optional `minimumAmount` applies a host-authorized currency
+minimum; it is not a discovered provider floor. Transfer reversal does not recall
+a completed bank payout, Stripe-managed automatic bank payouts remain outside
+this gate, and Global Payouts is unsupported. See the guide for account capability
+checks, maintenance jobs and live sandbox verification requirements.
+
 ### Refunds and Statement Descriptors
 
 `createRefund(ctx, { stripePaymentIntentId?, stripeChargeId?, amount?, reason?, refundApplicationFee?, reverseTransfer?, ... })` issues a Stripe refund with marketplace semantics, both defaulting **on**:
@@ -1110,7 +1145,7 @@ export const createDisputeSession = action({
 - `refundApplicationFee` — return the platform's application fee pro-rata with the refund (destination charges only; Stripe pro-rates partial refunds automatically).
 - `reverseTransfer` — pull the refunded amount back from the destination account (destination charges only; also pro-rated for partials).
 
-Stripe hard-errors if either flag is sent for a charge that doesn't carry an application fee / destination transfer, so `createRefund` resolves the charge first and only sends each flag when the charge can honor it. **Split (separate-charges) sales carry neither** — those go through the same charge, so their clawback is webhook-driven: on `refund.created`/`.updated`, `reverseTransfersForRefund` reverses each recipient's ledger leg pro-rata to Stripe's cumulative `amount_refunded`, converging correctly across multiple partial refunds (and coexisting with a prior dispute clawback on the same charge). A separate `application_fee.refunded` handler keeps the linked payment's `feeCollectedAmount`/`feeRefundedAmount` in sync. The `refunds` table and the linked `payments` row update as the corresponding webhooks arrive; `createRefund` itself returns only the new refund id.
+Stripe hard-errors if either flag is sent for a charge that doesn't carry an application fee / destination transfer, so `createRefund` resolves the charge first and only sends each flag when the charge can honor it. **Split (separate-charges) sales carry neither** — those go through the same charge, so their clawback is webhook-driven: on `refund.created`/`.updated`, `reverseTransfersForRefund` reverses each recipient's ledger leg pro-rata to the cumulative amount of live refunds whose status is `succeeded`. Pending, action-required, failed, and canceled refunds are excluded; `charge.amount_refunded` alone can include pending refunds. Affiliate legs converge on the larger successful-refund or dispute exposure, capped at the original commission, so the same principal is not recovered twice. A separate `application_fee.refunded` handler keeps the linked payment's `feeCollectedAmount`/`feeRefundedAmount` in sync. The `refunds` table and the linked `payments` row update as the corresponding webhooks arrive; `createRefund` itself returns only the new refund id.
 
 Per-store statement descriptors make destination charges recognizable on a buyer's card statement (`PLATFORMPREFIX* SUFFIX`):
 

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

@@ -0,0 +1,18 @@
+import type Stripe from "stripe";
+import type { Component, RunCtx } from "../helpers.js";
+/** Record proportional original commission exposure for a monetary dispute. */
+export declare function reverseTransfersForDispute(stripe: Stripe, component: Component, ctx: RunCtx, opts: {
+    sourceChargeId: string;
+    operationId: string;
+    chargeAmount: number;
+    amount: number;
+    finalized: boolean;
+    disputeState?: "open" | "lost" | "won";
+    refundedPrincipal?: number;
+}): Promise<{
+    reversals: {
+        stripeTransferId: string;
+        amount: number;
+    }[];
+}>;
+//# sourceMappingURL=disputes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"disputes.d.ts","sourceRoot":"","sources":["../../../src/client/affiliateRecovery/disputes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAUvD,+EAA+E;AAC/E,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IACJ,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;IACvC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;;;;;GAqCF"}

package/dist/client/affiliateRecovery/disputes.js

@@ -0,0 +1,33 @@
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import { recoverSettlementTransfers } from "../settlement/reconciliation.js";
+import { executeClaimedSlices, } from "../connect/reversalExecution.js";
+import { reconcileAffiliateCharge } from "./engine.js";
+/** Record proportional original commission exposure for a monetary dispute. */
+export async function reverseTransfersForDispute(stripe, component, ctx, opts) {
+    await recoverSettlementTransfers(stripe, component, ctx, opts.sourceChargeId);
+    const claim = (await runMutationOrThrow(ctx, componentRef(component, "connect/mutations/claimReversalSlices"), {
+        sourceChargeId: opts.sourceChargeId,
+        operationId: opts.operationId,
+        mode: opts.disputeState === "won"
+            ? {
+                kind: "fraction",
+                chargeAmount: opts.chargeAmount,
+                amountRefunded: 0,
+            }
+            : { kind: "amount", amount: opts.amount },
+        commissionExposure: {
+            kind: "dispute",
+            chargeAmount: opts.chargeAmount,
+            principal: opts.amount,
+            finalized: opts.finalized,
+            disputeState: opts.disputeState,
+            refundedPrincipal: opts.refundedPrincipal,
+            disputeId: opts.operationId,
+        },
+    }));
+    const result = await executeClaimedSlices(stripe, component, ctx, opts.operationId, { ...claim, slices: claim.slices.filter((s) => !s.commissionTracked) });
+    await reconcileAffiliateCharge(stripe, component, ctx, opts.sourceChargeId);
+    return result;
+}
+//# sourceMappingURL=disputes.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"disputes.js","sourceRoot":"","sources":["../../../src/client/affiliateRecovery/disputes.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EACL,oBAAoB,GAErB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAEvD,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,MAAc,EACd,SAAoB,EACpB,GAAW,EACX,IAQC;IAED,MAAM,0BAA0B,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;IAC9E,MAAM,KAAK,GAAG,CAAC,MAAM,kBAAkB,CACrC,GAAG,EACH,YAAY,CAAC,SAAS,EAAE,uCAAuC,CAAC,EAChE;QACE,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,IAAI,EACF,IAAI,CAAC,YAAY,KAAK,KAAK;YACzB,CAAC,CAAC;gBACE,IAAI,EAAE,UAAU;gBAChB,YAAY,EAAE,IAAI,CAAC,YAAY;gBAC/B,cAAc,EAAE,CAAC;aAClB;YACH,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE;QAC7C,kBAAkB,EAAE;YAClB,IAAI,EAAE,SAAS;YACf,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,SAAS,EAAE,IAAI,CAAC,MAAM;YACtB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;YACzC,SAAS,EAAE,IAAI,CAAC,WAAW;SAC5B;KACF,CACF,CAAkB,CAAC;IACpB,MAAM,MAAM,GAAG,MAAM,oBAAoB,CACvC,MAAM,EACN,SAAS,EACT,GAAG,EACH,IAAI,CAAC,WAAW,EAChB,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,EAAE,CACvE,CAAC;IACF,MAAM,wBAAwB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;IAC5E,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/client/affiliateRecovery/engine.d.ts

@@ -0,0 +1,29 @@
+import type Stripe from "stripe";
+import type { Component, RunCtx } from "../helpers.js";
+export declare function reconcileObligation(stripe: Stripe, component: Component, ctx: RunCtx, obligationId: string): Promise<{
+    state: string;
+    reason: string;
+    error?: undefined;
+} | {
+    reason?: undefined;
+    state: string;
+    error: string;
+} | {
+    reason?: undefined;
+    error?: undefined;
+    state: string;
+}>;
+export declare function reconcileAffiliateCharge(stripe: Stripe, component: Component, ctx: RunCtx, sourceChargeId: string): Promise<({
+    state: string;
+    reason: string;
+    error?: undefined;
+} | {
+    reason?: undefined;
+    state: string;
+    error: string;
+} | {
+    reason?: undefined;
+    error?: undefined;
+    state: string;
+})[]>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/client/affiliateRecovery/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/client/affiliateRecovery/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAUvD,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM;;;;;;;;;;;;GAiKrB;AACD,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,MAAM,EACX,cAAc,EAAE,MAAM;;;;;;;;;;;;MAcvB"}

package/dist/client/affiliateRecovery/engine.js

@@ -0,0 +1,116 @@
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import { classifyRecoveryError, findReceipt, verifyConnectPath, } from "./provider.js";
+export async function reconcileObligation(stripe, component, ctx, obligationId) {
+    let row = (await ctx.runQuery(componentRef(component, "affiliateRecovery/queries/getObligation"), { obligationId }));
+    if (!row || row.needsReconciliation)
+        return {
+            state: "unsupported",
+            reason: "Original commission provenance requires reconciliation.",
+        };
+    // Finish uncertain recovery before restoring its actual proceeds. Each pass
+    // claims one immutable operation atomically with debt/offset reservations.
+    let lastState = "settled";
+    for (let pass = 0; pass < 2; pass++) {
+        const net = row.recoveredAmount + (row.offsetAmount ?? 0) - (row.restoredAmount ?? 0);
+        const kind = net > row.finalizedAmount + row.provisionalAmount
+            ? "restoration"
+            : "recovery";
+        const op = (await runMutationOrThrow(ctx, componentRef(component, "affiliateRecovery/mutations/reserveOperation"), { obligationId, kind, now: Date.now() }));
+        if (!op) {
+            if ((row.debtAmount ?? 0) > 0)
+                lastState = "offset_required";
+            break;
+        }
+        try {
+            const receiptId = op.attempted
+                ? await findReceipt(stripe, op, row)
+                : null;
+            if (!receiptId && op.attempted && op.kind === "recovery") {
+                const original = await stripe.transfers.retrieve(row.stripeTransferId);
+                if (original.amount_reversed >
+                    (op.providerBaseline ?? row.recoveredAmount)) {
+                    const error = "Provider reversal aggregate changed without an attributable operation receipt; operator receipt review is required.";
+                    await runMutationOrThrow(ctx, componentRef(component, "affiliateRecovery/mutations/completeOperation"), { operationId: op._id, state: "unknown", error });
+                    return { state: "unknown", error };
+                }
+            }
+            let confirmed = receiptId;
+            if (!confirmed) {
+                const started = (await runMutationOrThrow(ctx, componentRef(component, "affiliateRecovery/mutations/beginOperation"), { operationId: op._id }));
+                if (!["pending", "unknown"].includes(started.state)) {
+                    lastState = started.state;
+                    if (started.state === "canceled") {
+                        row = (await ctx.runQuery(componentRef(component, "affiliateRecovery/queries/getObligation"), { obligationId }));
+                        continue;
+                    }
+                    break;
+                }
+                const capability = await verifyConnectPath(stripe, row, op.kind);
+                if (!capability.supported) {
+                    await runMutationOrThrow(ctx, componentRef(component, "affiliateRecovery/mutations/completeOperation"), {
+                        operationId: op._id,
+                        state: op.attempted ? "unknown" : "unsupported",
+                        error: capability.reason,
+                    });
+                    return {
+                        state: op.attempted ? "unknown" : "unsupported",
+                        reason: capability.reason,
+                    };
+                }
+                const metadata = {
+                    bsRecoveryOperation: op._id,
+                    bsOriginalCharge: row.sourceChargeId,
+                };
+                if (op.kind === "recovery") {
+                    const receipt = await stripe.transfers.createReversal(row.stripeTransferId, { amount: op.amount, metadata }, { idempotencyKey: `bs_affiliate_${op._id}` });
+                    if (receipt.amount !== op.amount)
+                        throw new Error("Affiliate provider reversal amount mismatch.");
+                    confirmed = receipt.id;
+                }
+                else {
+                    const receipt = await stripe.transfers.create({
+                        amount: op.amount,
+                        currency: row.currency,
+                        destination: row.affiliateAccountId,
+                        transfer_group: `bs_restore_${row._id}`,
+                        metadata,
+                    }, { idempotencyKey: `bs_affiliate_${op._id}` });
+                    if (receipt.amount !== op.amount || receipt.currency !== row.currency)
+                        throw new Error("Affiliate provider restoration amount mismatch.");
+                    confirmed = receipt.id;
+                }
+            }
+            const confirmedTransferReversed = op.kind === "recovery"
+                ? (await stripe.transfers.retrieve(row.stripeTransferId))
+                    .amount_reversed
+                : undefined;
+            await runMutationOrThrow(ctx, componentRef(component, "affiliateRecovery/mutations/completeOperation"), {
+                operationId: op._id,
+                state: "succeeded",
+                receiptId: confirmed,
+                confirmedTransferReversed,
+            });
+            lastState = "succeeded";
+        }
+        catch (error) {
+            const outcome = classifyRecoveryError(error);
+            // This write deliberately occurs outside the provider/receipt transaction.
+            // Unknown outcomes retain the reservation and block commission release.
+            await runMutationOrThrow(ctx, componentRef(component, "affiliateRecovery/mutations/completeOperation"), { operationId: op._id, ...outcome });
+            return outcome;
+        }
+        row = (await ctx.runQuery(componentRef(component, "affiliateRecovery/queries/getObligation"), { obligationId }));
+    }
+    return { state: lastState };
+}
+export async function reconcileAffiliateCharge(stripe, component, ctx, sourceChargeId) {
+    const rows = (await ctx.runQuery(componentRef(component, "affiliateRecovery/queries/chargeObligations"), { sourceChargeId }));
+    const results = [];
+    for (const row of rows ?? [])
+        if (typeof row._id === "string" &&
+            typeof row.originalCommission === "number")
+            results.push(await reconcileObligation(stripe, component, ctx, row._id));
+    return results;
+}
+//# sourceMappingURL=engine.js.map

package/dist/client/affiliateRecovery/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../../src/client/affiliateRecovery/engine.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EACL,qBAAqB,EACrB,WAAW,EACX,iBAAiB,GAGlB,MAAM,eAAe,CAAC;AACvB,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAc,EACd,SAAoB,EACpB,GAAW,EACX,YAAoB;IAEpB,IAAI,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,QAAQ,CAC3B,YAAY,CAAC,SAAS,EAAE,yCAAyC,CAAC,EAClE,EAAE,YAAY,EAAE,CACjB,CAA8B,CAAC;IAChC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,mBAAmB;QACjC,OAAO;YACL,KAAK,EAAE,aAAa;YACpB,MAAM,EAAE,yDAAyD;SAClE,CAAC;IACJ,4EAA4E;IAC5E,2EAA2E;IAC3E,IAAI,SAAS,GAAG,SAAS,CAAC;IAC1B,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC;QACpC,MAAM,GAAG,GACP,GAAG,CAAC,eAAe,GAAG,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,CAAC,CAAC;QAC5E,MAAM,IAAI,GACR,GAAG,GAAG,GAAG,CAAC,eAAe,GAAG,GAAG,CAAC,iBAAiB;YAC/C,CAAC,CAAC,aAAa;YACf,CAAC,CAAC,UAAU,CAAC;QACjB,MAAM,EAAE,GAAG,CAAC,MAAM,kBAAkB,CAClC,GAAG,EACH,YAAY,CAAC,SAAS,EAAE,8CAA8C,CAAC,EACvE,EAAE,YAAY,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CACxC,CAA6B,CAAC;QAC/B,IAAI,CAAC,EAAE,EAAE,CAAC;YACR,IAAI,CAAC,GAAG,CAAC,UAAU,IAAI,CAAC,CAAC,GAAG,CAAC;gBAAE,SAAS,GAAG,iBAAiB,CAAC;YAC7D,MAAM;QACR,CAAC;QACD,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,EAAE,CAAC,SAAS;gBAC5B,CAAC,CAAC,MAAM,WAAW,CAAC,MAAM,EAAE,EAAE,EAAE,GAAG,CAAC;gBACpC,CAAC,CAAC,IAAI,CAAC;YACT,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,EAAE,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBACzD,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,gBAAiB,CAAC,CAAC;gBACxE,IACE,QAAQ,CAAC,eAAe;oBACxB,CAAC,EAAE,CAAC,gBAAgB,IAAI,GAAG,CAAC,eAAe,CAAC,EAC5C,CAAC;oBACD,MAAM,KAAK,GACT,qHAAqH,CAAC;oBACxH,MAAM,kBAAkB,CACtB,GAAG,EACH,YAAY,CACV,SAAS,EACT,+CAA+C,CAChD,EACD,EAAE,WAAW,EAAE,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CACjD,CAAC;oBACF,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;gBACrC,CAAC;YACH,CAAC;YACD,IAAI,SAAS,GAAG,SAAS,CAAC;YAC1B,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,MAAM,OAAO,GAAG,CAAC,MAAM,kBAAkB,CACvC,GAAG,EACH,YAAY,CAAC,SAAS,EAAE,4CAA4C,CAAC,EACrE,EAAE,WAAW,EAAE,EAAE,CAAC,GAAG,EAAE,CACxB,CAAsB,CAAC;gBACxB,IAAI,CAAC,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBACpD,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC;oBAC1B,IAAI,OAAO,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;wBACjC,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,QAAQ,CACvB,YAAY,CACV,SAAS,EACT,yCAAyC,CAC1C,EACD,EAAE,YAAY,EAAE,CACjB,CAAuB,CAAC;wBACzB,SAAS;oBACX,CAAC;oBACD,MAAM;gBACR,CAAC;gBACD,MAAM,UAAU,GAAG,MAAM,iBAAiB,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;gBACjE,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;oBAC1B,MAAM,kBAAkB,CACtB,GAAG,EACH,YAAY,CACV,SAAS,EACT,+CAA+C,CAChD,EACD;wBACE,WAAW,EAAE,EAAE,CAAC,GAAG;wBACnB,KAAK,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa;wBAC/C,KAAK,EAAE,UAAU,CAAC,MAAM;qBACzB,CACF,CAAC;oBACF,OAAO;wBACL,KAAK,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa;wBAC/C,MAAM,EAAE,UAAU,CAAC,MAAM;qBAC1B,CAAC;gBACJ,CAAC;gBACD,MAAM,QAAQ,GAAG;oBACf,mBAAmB,EAAE,EAAE,CAAC,GAAG;oBAC3B,gBAAgB,EAAE,GAAG,CAAC,cAAc;iBACrC,CAAC;gBACF,IAAI,EAAE,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;oBAC3B,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,cAAc,CACnD,GAAG,CAAC,gBAAiB,EACrB,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,EAC/B,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAC,GAAG,EAAE,EAAE,CAC7C,CAAC;oBACF,IAAI,OAAO,CAAC,MAAM,KAAK,EAAE,CAAC,MAAM;wBAC9B,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;oBAClE,SAAS,GAAG,OAAO,CAAC,EAAE,CAAC;gBACzB,CAAC;qBAAM,CAAC;oBACN,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,MAAM,CAC3C;wBACE,MAAM,EAAE,EAAE,CAAC,MAAM;wBACjB,QAAQ,EAAE,GAAG,CAAC,QAAQ;wBACtB,WAAW,EAAE,GAAG,CAAC,kBAAkB;wBACnC,cAAc,EAAE,cAAc,GAAG,CAAC,GAAG,EAAE;wBACvC,QAAQ;qBACT,EACD,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAC,GAAG,EAAE,EAAE,CAC7C,CAAC;oBACF,IAAI,OAAO,CAAC,MAAM,KAAK,EAAE,CAAC,MAAM,IAAI,OAAO,CAAC,QAAQ,KAAK,GAAG,CAAC,QAAQ;wBACnE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;oBACrE,SAAS,GAAG,OAAO,CAAC,EAAE,CAAC;gBACzB,CAAC;YACH,CAAC;YACD,MAAM,yBAAyB,GAC7B,EAAE,CAAC,IAAI,KAAK,UAAU;gBACpB,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,gBAAiB,CAAC,CAAC;qBACrD,eAAe;gBACpB,CAAC,CAAC,SAAS,CAAC;YAChB,MAAM,kBAAkB,CACtB,GAAG,EACH,YAAY,CACV,SAAS,EACT,+CAA+C,CAChD,EACD;gBACE,WAAW,EAAE,EAAE,CAAC,GAAG;gBACnB,KAAK,EAAE,WAAW;gBAClB,SAAS,EAAE,SAAS;gBACpB,yBAAyB;aAC1B,CACF,CAAC;YACF,SAAS,GAAG,WAAW,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;YAC7C,2EAA2E;YAC3E,wEAAwE;YACxE,MAAM,kBAAkB,CACtB,GAAG,EACH,YAAY,CACV,SAAS,EACT,+CAA+C,CAChD,EACD,EAAE,WAAW,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,OAAO,EAAE,CACpC,CAAC;YACF,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,QAAQ,CACvB,YAAY,CAAC,SAAS,EAAE,yCAAyC,CAAC,EAClE,EAAE,YAAY,EAAE,CACjB,CAAuB,CAAC;IAC3B,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAC9B,CAAC;AACD,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,MAAc,EACd,SAAoB,EACpB,GAAW,EACX,cAAsB;IAEtB,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,QAAQ,CAC9B,YAAY,CAAC,SAAS,EAAE,6CAA6C,CAAC,EACtE,EAAE,cAAc,EAAE,CACnB,CAAgC,CAAC;IAClC,MAAM,OAAO,GAAG,EAAE,CAAC;IACnB,KAAK,MAAM,GAAG,IAAI,IAAI,IAAI,EAAE;QAC1B,IACE,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ;YAC3B,OAAO,GAAG,CAAC,kBAAkB,KAAK,QAAQ;YAE1C,OAAO,CAAC,IAAI,CAAC,MAAM,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7E,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/client/affiliateRecovery/payoutGate.d.ts

@@ -0,0 +1,24 @@
+import type Stripe from "stripe";
+import type { Component, RunCtx } from "../helpers.js";
+import type { Doc } from "../../component/_generated/dataModel.js";
+export declare function reserveAffiliatePayout(component: Component, ctx: RunCtx, opts: {
+    stripeAccountId: string;
+    currency?: string;
+    amount: number;
+    minimumAmount?: number;
+    idempotencyKey?: string;
+}): Promise<{
+    _creationTime: number;
+    _id: import("convex/values").GenericId<"affiliatePayoutReleases">;
+    affiliateAccountId: string;
+    amount: number;
+    createdAt: number;
+    currency: string;
+    minimumAmount: number;
+    operationKey: string;
+    state: "failed" | "pending" | "submitted" | "unknown";
+    stripePayoutId?: string | undefined;
+} | null>;
+export declare function completeAffiliatePayout(component: Component, ctx: RunCtx, operationKey: string, state: "unknown" | "submitted" | "failed", stripePayoutId?: string): Promise<any>;
+export declare function reconcileAffiliatePayout(stripe: Stripe, release: Doc<"affiliatePayoutReleases">): Promise<string | null>;
+//# sourceMappingURL=payoutGate.d.ts.map

package/dist/client/affiliateRecovery/payoutGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payoutGate.d.ts","sourceRoot":"","sources":["../../../src/client/affiliateRecovery/payoutGate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAGvD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,yCAAyC,CAAC;AACnE,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IACJ,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;;;;;;;;;;;UAcF;AACD,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,EACzC,cAAc,CAAC,EAAE,MAAM,gBAOxB;AACD,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,GAAG,CAAC,yBAAyB,CAAC,0BAoBxC"}

package/dist/client/affiliateRecovery/payoutGate.js

@@ -0,0 +1,30 @@
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+export async function reserveAffiliatePayout(component, ctx, opts) {
+    return runMutationOrThrow(ctx, componentRef(component, "affiliatePayouts/mutations/reservePayout"), {
+        affiliateAccountId: opts.stripeAccountId,
+        currency: opts.currency ?? "usd",
+        amount: opts.amount,
+        minimumAmount: opts.minimumAmount ?? 1,
+        operationKey: opts.idempotencyKey,
+        now: Date.now(),
+    });
+}
+export async function completeAffiliatePayout(component, ctx, operationKey, state, stripePayoutId) {
+    return runMutationOrThrow(ctx, componentRef(component, "affiliatePayouts/mutations/finishPayout"), { operationKey, state, stripePayoutId });
+}
+export async function reconcileAffiliatePayout(stripe, release) {
+    let count = 0;
+    for await (const receipt of stripe.payouts.list({ created: { gte: Math.floor(release.createdAt / 1000) }, limit: 100 }, { stripeAccount: release.affiliateAccountId })) {
+        if (++count > 1000)
+            throw new Error("Affiliate payout history requires operator reconciliation.");
+        if (receipt.metadata?.bsAffiliatePayout !== release._id)
+            continue;
+        if (receipt.currency !== release.currency ||
+            receipt.amount !== release.amount)
+            throw new Error("Affiliate payout receipt mismatch.");
+        return receipt.id;
+    }
+    return null;
+}
+//# sourceMappingURL=payoutGate.js.map

package/dist/client/affiliateRecovery/payoutGate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payoutGate.js","sourceRoot":"","sources":["../../../src/client/affiliateRecovery/payoutGate.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,SAAoB,EACpB,GAAW,EACX,IAMC;IAED,OAAO,kBAAkB,CACvB,GAAG,EACH,YAAY,CAAC,SAAS,EAAE,0CAA0C,CAAC,EACnE;QACE,kBAAkB,EAAE,IAAI,CAAC,eAAe;QACxC,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,KAAK;QAChC,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,aAAa,EAAE,IAAI,CAAC,aAAa,IAAI,CAAC;QACtC,YAAY,EAAE,IAAI,CAAC,cAAc;QACjC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE;KAChB,CACgD,CAAC;AACtD,CAAC;AACD,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,SAAoB,EACpB,GAAW,EACX,YAAoB,EACpB,KAAyC,EACzC,cAAuB;IAEvB,OAAO,kBAAkB,CACvB,GAAG,EACH,YAAY,CAAC,SAAS,EAAE,yCAAyC,CAAC,EAClE,EAAE,YAAY,EAAE,KAAK,EAAE,cAAc,EAAE,CACxC,CAAC;AACJ,CAAC;AACD,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,MAAc,EACd,OAAuC;IAEvC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,EAAE,MAAM,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAC7C,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,EACtE,EAAE,aAAa,EAAE,OAAO,CAAC,kBAAkB,EAAE,CAC9C,EAAE,CAAC;QACF,IAAI,EAAE,KAAK,GAAG,IAAI;YAChB,MAAM,IAAI,KAAK,CACb,4DAA4D,CAC7D,CAAC;QACJ,IAAI,OAAO,CAAC,QAAQ,EAAE,iBAAiB,KAAK,OAAO,CAAC,GAAG;YAAE,SAAS;QAClE,IACE,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,QAAQ;YACrC,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM;YAEjC,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACxD,OAAO,OAAO,CAAC,EAAE,CAAC;IACpB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/client/affiliateRecovery/provider.d.ts

@@ -0,0 +1,14 @@
+import type Stripe from "stripe";
+import type { Doc } from "../../component/_generated/dataModel.js";
+export type RecoveryOperation = Doc<"affiliateRecoveryOperations">;
+export type RecoveryObligation = Doc<"affiliateObligations">;
+export declare function findReceipt(stripe: Stripe, op: RecoveryOperation, row: RecoveryObligation): Promise<string | null>;
+export declare function verifyConnectPath(stripe: Stripe, row: RecoveryObligation, kind: RecoveryOperation["kind"]): Promise<{
+    supported: boolean;
+    reason: string;
+}>;
+export declare function classifyRecoveryError(error: unknown): {
+    state: "unknown" | "insufficient_balance" | "unsupported" | "failed";
+    error: string;
+};
+//# sourceMappingURL=provider.d.ts.map

package/dist/client/affiliateRecovery/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/client/affiliateRecovery/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,yCAAyC,CAAC;AACnE,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,6BAA6B,CAAC,CAAC;AACnE,MAAM,MAAM,kBAAkB,GAAG,GAAG,CAAC,sBAAsB,CAAC,CAAC;AAC7D,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,iBAAiB,EACrB,GAAG,EAAE,kBAAkB,0BAwCxB;AACD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,kBAAkB,EACvB,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC;;;GA4ChC;AACD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG;IACrD,KAAK,EAAE,SAAS,GAAG,sBAAsB,GAAG,aAAa,GAAG,QAAQ,CAAC;IACrE,KAAK,EAAE,MAAM,CAAC;CACf,CA2BA"}

package/dist/client/affiliateRecovery/provider.js

@@ -0,0 +1,96 @@
+export async function findReceipt(stripe, op, row) {
+    let count = 0;
+    if (op.kind === "recovery") {
+        if (!row.stripeTransferId)
+            return null;
+        for await (const receipt of stripe.transfers.listReversals(row.stripeTransferId, { limit: 100 })) {
+            if (++count > 1000)
+                throw new Error("Affiliate receipt history exceeds supported bound.");
+            if (receipt.metadata?.bsRecoveryOperation !== op._id)
+                continue;
+            if (receipt.amount !== op.amount)
+                throw new Error("Affiliate reversal receipt amount mismatch.");
+            return receipt.id;
+        }
+    }
+    else {
+        for await (const receipt of stripe.transfers.list({
+            transfer_group: `bs_restore_${row._id}`,
+            limit: 100,
+        })) {
+            if (++count > 1000)
+                throw new Error("Affiliate restoration history exceeds supported bound.");
+            if (receipt.metadata?.bsRecoveryOperation !== op._id)
+                continue;
+            const destination = typeof receipt.destination === "string"
+                ? receipt.destination
+                : receipt.destination?.id;
+            if (receipt.amount !== op.amount ||
+                receipt.currency !== row.currency ||
+                destination !== row.affiliateAccountId)
+                throw new Error("Affiliate restoration receipt identity mismatch.");
+            return receipt.id;
+        }
+    }
+    return null;
+}
+export async function verifyConnectPath(stripe, row, kind) {
+    const account = await stripe.v2.core.accounts.retrieve(row.affiliateAccountId, { include: ["configuration.recipient"] });
+    const capability = account.configuration?.recipient?.capabilities?.stripe_balance
+        ?.stripe_transfers;
+    if (capability?.status !== "active")
+        return {
+            supported: false,
+            reason: "Connect recipient stripe_transfers capability is not active; operator review required.",
+        };
+    if (kind === "recovery") {
+        if (!row.stripeTransferId)
+            return {
+                supported: false,
+                reason: "No original Connect transfer; recover through future commissions.",
+            };
+        const original = await stripe.transfers.retrieve(row.stripeTransferId);
+        const destination = typeof original.destination === "string"
+            ? original.destination
+            : original.destination?.id;
+        if (destination !== row.affiliateAccountId ||
+            original.currency !== row.currency ||
+            original.source_transaction !== row.sourceChargeId ||
+            original.amount !== (row.releasedCommission ?? row.originalCommission))
+            return {
+                supported: false,
+                reason: "Original Connect transfer identity does not match the commission; operator review required.",
+            };
+    }
+    return {
+        supported: true,
+        reason: "Original Connect path verified; reversal remains subject to available balance and provider restrictions.",
+    };
+}
+export function classifyRecoveryError(error) {
+    const value = error;
+    const code = value.code ?? "";
+    const state = ["balance_insufficient", "insufficient_funds"].includes(code)
+        ? "insufficient_balance"
+        : [
+            "account_invalid",
+            "transfers_not_allowed",
+            "resource_missing",
+            "platform_account_required",
+        ].includes(code)
+            ? "unsupported"
+            : [
+                "StripeConnectionError",
+                "StripeAPIError",
+                "StripeRateLimitError",
+            ].includes(value.type ?? "") ||
+                code === "idempotency_key_in_use" ||
+                !value.type
+                ? "unknown"
+                : "failed";
+    return {
+        state,
+        error: (value.message ?? "Affiliate provider outcome requires reconciliation.").slice(0, 500),
+    };
+}
+//# sourceMappingURL=provider.js.map

package/dist/client/affiliateRecovery/provider.js.map

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

package/dist/client/affiliateRecovery/review.d.ts

@@ -0,0 +1,28 @@
+import type Stripe from "stripe";
+import type { RecoveryObligation } from "./provider.js";
+/** Operator-selected provenance is verified against exact provider receipts. */
+export declare function verifiedLegacyReview(stripe: Stripe, row: RecoveryObligation, opts: {
+    reversalIds: string[];
+    restorationTransferIds?: string[];
+    note: string;
+}): Promise<{
+    obligationId: import("convex/values").GenericId<"affiliateObligations">;
+    recoveredAmount: number;
+    restoredAmount: number;
+    receipts: {
+        id: string;
+        amount: number;
+    }[];
+    restorationIds: string[];
+    note: string;
+    exposure: {
+        kind: "dispute" | "refund";
+        chargeAmount: number;
+        principal: number;
+        finalized: boolean;
+        refundedPrincipal: number;
+        disputeId: string;
+        disputeState: "lost" | "open" | "won" | undefined;
+    };
+}>;
+//# sourceMappingURL=review.d.ts.map

package/dist/client/affiliateRecovery/review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.d.ts","sourceRoot":"","sources":["../../../src/client/affiliateRecovery/review.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD,gFAAgF;AAChF,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,kBAAkB,EACvB,IAAI,EAAE;IACJ,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;CACd;;;;;;;;;;;;;;;;;;;GAyGF"}