@fantastic.dev/better-stripe 0.17.1 → 0.19.0

package/dist/component/payoutPolicy/schema.js

@@ -0,0 +1,54 @@
+import { defineTable } from "convex/server";
+import { v } from "convex/values";
+export const scopeFields = { accountId: v.string(), ownerKey: v.string() };
+export const schedule = v.object({
+    interval: v.union(v.literal("daily"), v.literal("weekly"), v.literal("monthly"), v.literal("manual")),
+    weeklyDays: v.optional(v.array(v.string())),
+    monthlyDays: v.optional(v.array(v.number())),
+});
+export const mode = v.union(v.literal("stripe_managed"), v.literal("custom"));
+export const thresholds = v.array(v.object({ currency: v.string(), amount: v.number() }));
+export const prepareFields = {
+    ...scopeFields,
+    operationKey: v.string(),
+    expectedRevision: v.number(),
+    mode,
+    thresholds,
+    country: v.string(),
+    observedSchedule: schedule,
+    observedAt: v.optional(v.number()),
+};
+export const policyFields = {
+    ...scopeFields,
+    revision: v.number(),
+    mode,
+    thresholds,
+    status: v.union(v.literal("changing"), v.literal("ready")),
+    operationKey: v.string(),
+    country: v.string(),
+    previousSchedule: v.optional(schedule),
+    holdDeadline: v.optional(v.number()),
+};
+export const operationFields = {
+    ...prepareFields,
+    revision: v.number(),
+    previousSchedule: schedule,
+    targetSchedule: schedule,
+    status: v.union(v.literal("pending"), v.literal("complete"), v.literal("canceled")),
+    attempted: v.optional(v.boolean()),
+};
+export const policyDoc = v.object({
+    ...policyFields,
+    _id: v.id("payoutPolicies"),
+    _creationTime: v.number(),
+});
+export const operationDoc = v.object({
+    ...operationFields,
+    _id: v.id("payoutPolicyOperations"),
+    _creationTime: v.number(),
+});
+export const policiesTable = defineTable(policyFields)
+    .index("by_account", ["accountId"])
+    .index("by_deadline", ["holdDeadline"]);
+export const operationsTable = defineTable(operationFields).index("by_operation", ["operationKey"]);
+//# sourceMappingURL=schema.js.map

package/dist/component/payoutPolicy/schema.js.map

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

package/dist/component/schema.d.ts

@@ -1,4 +1,135 @@
 declare const _default: import("convex/server").SchemaDefinition<{
+    payoutPolicies: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        accountId: string;
+        country: string;
+        holdDeadline?: number | undefined;
+        mode: "custom" | "stripe_managed";
+        operationKey: string;
+        ownerKey: string;
+        previousSchedule?: {
+            interval: "daily" | "manual" | "monthly" | "weekly";
+            monthlyDays?: number[] | undefined;
+            weeklyDays?: string[] | undefined;
+        } | undefined;
+        revision: number;
+        status: "changing" | "ready";
+        thresholds: {
+            amount: number;
+            currency: string;
+        }[];
+    }, {
+        accountId: import("convex/values").VString<string, "required">;
+        ownerKey: import("convex/values").VString<string, "required">;
+        revision: import("convex/values").VFloat64<number, "required">;
+        mode: import("convex/values").VUnion<"custom" | "stripe_managed", [import("convex/values").VLiteral<"stripe_managed", "required">, import("convex/values").VLiteral<"custom", "required">], "required", never>;
+        thresholds: import("convex/values").VArray<{
+            amount: number;
+            currency: string;
+        }[], import("convex/values").VObject<{
+            amount: number;
+            currency: string;
+        }, {
+            currency: import("convex/values").VString<string, "required">;
+            amount: import("convex/values").VFloat64<number, "required">;
+        }, "required", "amount" | "currency">, "required">;
+        status: import("convex/values").VUnion<"changing" | "ready", [import("convex/values").VLiteral<"changing", "required">, import("convex/values").VLiteral<"ready", "required">], "required", never>;
+        operationKey: import("convex/values").VString<string, "required">;
+        country: import("convex/values").VString<string, "required">;
+        previousSchedule: import("convex/values").VObject<{
+            interval: "daily" | "manual" | "monthly" | "weekly";
+            monthlyDays?: number[] | undefined;
+            weeklyDays?: string[] | undefined;
+        } | undefined, {
+            interval: import("convex/values").VUnion<"daily" | "manual" | "monthly" | "weekly", [import("convex/values").VLiteral<"daily", "required">, import("convex/values").VLiteral<"weekly", "required">, import("convex/values").VLiteral<"monthly", "required">, import("convex/values").VLiteral<"manual", "required">], "required", never>;
+            weeklyDays: import("convex/values").VArray<string[] | undefined, import("convex/values").VString<string, "required">, "optional">;
+            monthlyDays: import("convex/values").VArray<number[] | undefined, import("convex/values").VFloat64<number, "required">, "optional">;
+        }, "optional", "interval" | "monthlyDays" | "weeklyDays">;
+        holdDeadline: import("convex/values").VFloat64<number | undefined, "optional">;
+    }, "required", "accountId" | "country" | "holdDeadline" | "mode" | "operationKey" | "ownerKey" | "previousSchedule" | "previousSchedule.interval" | "previousSchedule.monthlyDays" | "previousSchedule.weeklyDays" | "revision" | "status" | "thresholds">, {
+        by_account: ["accountId", "_creationTime"];
+        by_deadline: ["holdDeadline", "_creationTime"];
+    }, {}, {}>;
+    payoutPolicyOperations: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        accountId: string;
+        attempted?: boolean | undefined;
+        country: string;
+        expectedRevision: number;
+        mode: "custom" | "stripe_managed";
+        observedAt?: number | undefined;
+        observedSchedule: {
+            interval: "daily" | "manual" | "monthly" | "weekly";
+            monthlyDays?: number[] | undefined;
+            weeklyDays?: string[] | undefined;
+        };
+        operationKey: string;
+        ownerKey: string;
+        previousSchedule: {
+            interval: "daily" | "manual" | "monthly" | "weekly";
+            monthlyDays?: number[] | undefined;
+            weeklyDays?: string[] | undefined;
+        };
+        revision: number;
+        status: "canceled" | "complete" | "pending";
+        targetSchedule: {
+            interval: "daily" | "manual" | "monthly" | "weekly";
+            monthlyDays?: number[] | undefined;
+            weeklyDays?: string[] | undefined;
+        };
+        thresholds: {
+            amount: number;
+            currency: string;
+        }[];
+    }, {
+        accountId: import("convex/values").VString<string, "required">;
+        ownerKey: import("convex/values").VString<string, "required">;
+        operationKey: import("convex/values").VString<string, "required">;
+        expectedRevision: import("convex/values").VFloat64<number, "required">;
+        mode: import("convex/values").VUnion<"custom" | "stripe_managed", [import("convex/values").VLiteral<"stripe_managed", "required">, import("convex/values").VLiteral<"custom", "required">], "required", never>;
+        thresholds: import("convex/values").VArray<{
+            amount: number;
+            currency: string;
+        }[], import("convex/values").VObject<{
+            amount: number;
+            currency: string;
+        }, {
+            currency: import("convex/values").VString<string, "required">;
+            amount: import("convex/values").VFloat64<number, "required">;
+        }, "required", "amount" | "currency">, "required">;
+        country: import("convex/values").VString<string, "required">;
+        observedSchedule: import("convex/values").VObject<{
+            interval: "daily" | "manual" | "monthly" | "weekly";
+            monthlyDays?: number[] | undefined;
+            weeklyDays?: string[] | undefined;
+        }, {
+            interval: import("convex/values").VUnion<"daily" | "manual" | "monthly" | "weekly", [import("convex/values").VLiteral<"daily", "required">, import("convex/values").VLiteral<"weekly", "required">, import("convex/values").VLiteral<"monthly", "required">, import("convex/values").VLiteral<"manual", "required">], "required", never>;
+            weeklyDays: import("convex/values").VArray<string[] | undefined, import("convex/values").VString<string, "required">, "optional">;
+            monthlyDays: import("convex/values").VArray<number[] | undefined, import("convex/values").VFloat64<number, "required">, "optional">;
+        }, "required", "interval" | "monthlyDays" | "weeklyDays">;
+        observedAt: import("convex/values").VFloat64<number | undefined, "optional">;
+        revision: import("convex/values").VFloat64<number, "required">;
+        previousSchedule: import("convex/values").VObject<{
+            interval: "daily" | "manual" | "monthly" | "weekly";
+            monthlyDays?: number[] | undefined;
+            weeklyDays?: string[] | undefined;
+        }, {
+            interval: import("convex/values").VUnion<"daily" | "manual" | "monthly" | "weekly", [import("convex/values").VLiteral<"daily", "required">, import("convex/values").VLiteral<"weekly", "required">, import("convex/values").VLiteral<"monthly", "required">, import("convex/values").VLiteral<"manual", "required">], "required", never>;
+            weeklyDays: import("convex/values").VArray<string[] | undefined, import("convex/values").VString<string, "required">, "optional">;
+            monthlyDays: import("convex/values").VArray<number[] | undefined, import("convex/values").VFloat64<number, "required">, "optional">;
+        }, "required", "interval" | "monthlyDays" | "weeklyDays">;
+        targetSchedule: import("convex/values").VObject<{
+            interval: "daily" | "manual" | "monthly" | "weekly";
+            monthlyDays?: number[] | undefined;
+            weeklyDays?: string[] | undefined;
+        }, {
+            interval: import("convex/values").VUnion<"daily" | "manual" | "monthly" | "weekly", [import("convex/values").VLiteral<"daily", "required">, import("convex/values").VLiteral<"weekly", "required">, import("convex/values").VLiteral<"monthly", "required">, import("convex/values").VLiteral<"manual", "required">], "required", never>;
+            weeklyDays: import("convex/values").VArray<string[] | undefined, import("convex/values").VString<string, "required">, "optional">;
+            monthlyDays: import("convex/values").VArray<number[] | undefined, import("convex/values").VFloat64<number, "required">, "optional">;
+        }, "required", "interval" | "monthlyDays" | "weeklyDays">;
+        status: import("convex/values").VUnion<"canceled" | "complete" | "pending", [import("convex/values").VLiteral<"pending", "required">, import("convex/values").VLiteral<"complete", "required">, import("convex/values").VLiteral<"canceled", "required">], "required", never>;
+        attempted: import("convex/values").VBoolean<boolean | undefined, "optional">;
+    }, "required", "accountId" | "attempted" | "country" | "expectedRevision" | "mode" | "observedAt" | "observedSchedule" | "observedSchedule.interval" | "observedSchedule.monthlyDays" | "observedSchedule.weeklyDays" | "operationKey" | "ownerKey" | "previousSchedule" | "previousSchedule.interval" | "previousSchedule.monthlyDays" | "previousSchedule.weeklyDays" | "revision" | "status" | "targetSchedule" | "targetSchedule.interval" | "targetSchedule.monthlyDays" | "targetSchedule.weeklyDays" | "thresholds">, {
+        by_operation: ["operationKey", "_creationTime"];
+    }, {}, {}>;
     currencyTotals: import("convex/server").TableDefinition<import("convex/values").VObject<{
         accountId: string;
         count: number;

package/dist/component/schema.js

@@ -1,3 +1,4 @@
+import { policiesTable, operationsTable } from "./payoutPolicy/schema.js";
 import { currencyTotalsTable } from "./earnings/schema.js";
 import { claimsTable, balancesTable, groupsTable, reservationsTable, } from "./costRecovery/schema";
 import { allocationsTable, commissionTermsTable, commissionDecisionsTable, } from "./settlement/schema";
@@ -8,6 +9,8 @@ import { accountsTable } from "./core/schema";
 import { pricesTable, productsTable } from "./products/schema";
 import { webhookEventsTable } from "./webhooks/schema";
 export default defineSchema({
+    payoutPolicies: policiesTable,
+    payoutPolicyOperations: operationsTable,
     currencyTotals: currencyTotalsTable,
     recoveryClaims: claimsTable,
     recoveryBalances: balancesTable,

package/dist/component/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EACL,WAAW,EACX,aAAa,EACb,WAAW,EACX,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,aAAa,EACb,YAAY,EACZ,sBAAsB,EACtB,YAAY,EACZ,wBAAwB,EACxB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,eAAe,YAAY,CAAC;IAC1B,cAAc,EAAE,mBAAmB;IACnC,cAAc,EAAE,WAAW;IAC3B,gBAAgB,EAAE,aAAa;IAC/B,cAAc,EAAE,WAAW;IAC3B,oBAAoB,EAAE,iBAAiB;IACvC,qBAAqB,EAAE,gBAAgB;IACvC,eAAe,EAAE,oBAAoB;IACrC,mBAAmB,EAAE,wBAAwB;IAC7C,OAAO;IACP,QAAQ,EAAE,aAAa;IAEvB,WAAW;IACX,QAAQ,EAAE,aAAa;IACvB,MAAM,EAAE,WAAW;IAEnB,UAAU;IACV,aAAa,EAAE,kBAAkB;IACjC,gBAAgB,EAAE,qBAAqB;IACvC,QAAQ,EAAE,aAAa;IAEvB,UAAU;IACV,QAAQ,EAAE,aAAa;IACvB,OAAO,EAAE,YAAY;IACrB,iBAAiB,EAAE,sBAAsB;IACzC,OAAO,EAAE,YAAY;IACrB,QAAQ,EAAE,aAAa;IACvB,SAAS,EAAE,cAAc;IACzB,mBAAmB,EAAE,wBAAwB;IAE7C,WAAW;IACX,aAAa,EAAE,kBAAkB;CAClC,CAAC,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EACL,WAAW,EACX,aAAa,EACb,WAAW,EACX,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,aAAa,EACb,YAAY,EACZ,sBAAsB,EACtB,YAAY,EACZ,wBAAwB,EACxB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,eAAe,YAAY,CAAC;IAC1B,cAAc,EAAE,aAAa;IAC7B,sBAAsB,EAAE,eAAe;IACvC,cAAc,EAAE,mBAAmB;IACnC,cAAc,EAAE,WAAW;IAC3B,gBAAgB,EAAE,aAAa;IAC/B,cAAc,EAAE,WAAW;IAC3B,oBAAoB,EAAE,iBAAiB;IACvC,qBAAqB,EAAE,gBAAgB;IACvC,eAAe,EAAE,oBAAoB;IACrC,mBAAmB,EAAE,wBAAwB;IAC7C,OAAO;IACP,QAAQ,EAAE,aAAa;IAEvB,WAAW;IACX,QAAQ,EAAE,aAAa;IACvB,MAAM,EAAE,WAAW;IAEnB,UAAU;IACV,aAAa,EAAE,kBAAkB;IACjC,gBAAgB,EAAE,qBAAqB;IACvC,QAAQ,EAAE,aAAa;IAEvB,UAAU;IACV,QAAQ,EAAE,aAAa;IACvB,OAAO,EAAE,YAAY;IACrB,iBAAiB,EAAE,sBAAsB;IACzC,OAAO,EAAE,YAAY;IACrB,QAAQ,EAAE,aAAa;IACvB,SAAS,EAAE,cAAc;IACzB,mBAAmB,EAAE,wBAAwB;IAE7C,WAAW;IACX,aAAa,EAAE,kBAAkB;CAClC,CAAC,CAAC"}

package/docs/settlement.md

@@ -156,3 +156,115 @@ It requires a selected retention boundary and migration policy. Applications mus
 not describe a displayed threshold as enforced while Stripe controls automatic
 payouts. A numeric below/exact/above provider-floor demonstration is unavailable
 without a supported provider floor read; surface this capability limitation.
+
+## Recipient-held payout policy controls
+
+`stripe.payoutPolicy` stages versioned, account-wide schedule changes for a
+user-level recipient. The host authenticates `ownerKey`, authorizes the policy,
+and records explicit consent. Thresholds use integer minor units per currency;
+they combine creator and affiliate funds rather than creating category gates.
+The untouched default remains Stripe-managed automatic payouts.
+
+Call `prepare(ctx, { accountId, ownerKey, operationKey, expectedRevision, mode:
+"custom", thresholds: [{ currency: "usd", amount: 1000 }], consent: true })` in
+an authorized action. Revision `-1` means no existing policy. Persisted preparation
+captures the original payout schedule and country holding deadline before any
+provider update. If preparation returns `prepared`, call `apply` with the same
+account, owner and operation key. Replays preserve the immutable request;
+competing operations and stale revisions are rejected. A provider timeout or
+failed confirmation stays pending for reconciliation, rather than being treated
+as a completed schedule change.
+
+These APIs currently require a verified `dashboard: none` account and enabled
+payouts for custom activation. Accounts with Dashboard withdrawal access return
+an explicit control limitation: restricting schedule edits alone cannot prevent
+manual withdrawals. The API never changes dashboard access or loss liability to
+obtain control. Stripe also validates update permissions. Before each subsequent
+payout attempt, `verify` must confirm live manual settings, unchanged country,
+and an unexpired policy; stored `ready` state alone is insufficient.
+
+Initial activation rejects existing nonzero available or pending balances,
+in-flight payouts, and existing manual schedules with `migration_required`.
+The preflight is repeated before an initial schedule update; a delayed activation
+with newly arrived funds is canceled before changing Stripe. This is a bounded
+preflight, not an ownership inference or automatic adoption.
+Already-mixed funds need a reconciled source ledger and explicit adoption before
+custom release can be enabled. Zero-balance activation does not classify later
+unrelated deposits as earnings. Payout claims must use that source ledger and a
+fresh provider balance when the separate release boundary is integrated.
+
+The host must schedule a recurring server job that pages `due(ctx,
+{ cursor: null, numItems: 100 })`, follows its cursor, and calls `expire` for each
+returned account/owner. `expire` reconciles pending operations and restores the
+original automatic schedule when the holding deadline is reached. Unattempted
+expired enables are canceled without changing Stripe. Failed/unknown restores
+remain visible and retryable; alert operators if they cannot complete. Editing
+thresholds never extends the original deadline. Current limits are 10 days for
+Thailand, a conservative 730 days for the US, and 90 days elsewhere; verify
+current provider rules before enabling the feature in production.
+
+For opt-out, prepare a new operation with the latest revision,
+`mode: "stripe_managed"`, and `thresholds: []`, then apply it. Restoration remains
+available after Dashboard control is lost, subject to Stripe permissions. It
+restores only the captured schedule; other balance settings remain untouched.
+
+This is the durable policy/control boundary. Automatic combined payout execution,
+adoption of existing balances, and its UI integration are separate work and are
+not supplied by these schedule APIs. Do not expose a custom minimum as fully
+enforced until those boundaries and the recurring expiry job are installed.
+`verify.providerMinimum` is `null`: the Balance Settings API does not expose a
+numeric payout-floor field, and retained balance reserves are not payout triggers.
+
+Sources: [payout schedules](https://docs.stripe.com/connect/manage-payout-schedule),
+[manual payout holding limits](https://docs.stripe.com/connect/manual-payouts), and
+[Dashboard control limits](https://docs.stripe.com/connect/platform-controls-for-stripe-dashboard-accounts#control-payout-timing).
+
+## Verified recipient funding receipts
+
+Use `stripe.payoutPolicy.transferReceipt(ctx, { accountId, stripeTransferId })`
+in an authorized action to read a transfer's actual recipient funding. The
+reader binds the component ledger to the provider transfer, destination payment,
+original balance transaction and each transfer reversal's recipient refund.
+It verifies account, amount, currency and source identities, and rechecks the
+transfer and ledger before publishing a result. It performs no financial writes.
+
+A `ready` result contains exact signed recipient settlement transactions and
+`totalNet`, `matureNet`, and `pendingCredits`. `sourceCurrency` describes the
+original transfer; `settlementCurrency` describes the actual recipient balance.
+For supported FX receipts, amounts come directly from Stripe's settlement
+transactions; the reader does not calculate exchange-rate conversions. Mixed
+settlement currencies or missing conversion evidence require explicit allocation.
+Transaction `created` and `availableOn` values are Unix seconds; the snapshot's
+`observedAt` is milliseconds.
+
+Positive credits qualify as mature only when their provider status is available
+and their availability date has passed. Pending debits first cancel the matching
+pending original credit; uncovered pending debits reduce mature credit. Other
+positive pending adjustments never qualify early. Signed mature debt is preserved.
+For example, in one settlement currency's minor units:
+
+| Original credit | Reversal/debit | Total net | Mature net | Pending credits |
+| --------------- | -------------- | --------: | ---------: | --------------: |
+| 1000 pending    | 250 pending    |       750 |          0 |             750 |
+| 1000 available  | 250 pending    |       750 |        750 |               0 |
+| 1000 pending    | 1000 pending   |         0 |          0 |               0 |
+| 1000 pending    | 250 available  |       750 |       -250 |            1000 |
+
+This is **received credit, not still-unpaid entitlement**. Previous bank payouts,
+source allocations, recovery liabilities and outstanding reservations must be
+reconciled before any release. Do not pay `matureNet` directly or infer ownership
+from unrelated account-wide available funds. Stripe's balance-transaction
+`payout` filter maps automatic payouts only; application-created manual payouts
+need a maintained allocation ledger.
+
+The default budget is 20 provider requests; `maxRequests` accepts 1–100. Exhausted
+or incomplete history returns `not_ready` without partial financial totals.
+Reserved reversal claims, changing provider/ledger snapshots and unavailable
+receipts also fail closed. Identity mismatches and invalid financial arithmetic
+throw. Larger histories need continued reconciliation rather than treating the
+missing amount as zero or silently truncating it. The original transfer ledger
+remains intact for retries.
+
+Sources: [transfer provenance](https://docs.stripe.com/api/transfers/object),
+[receipt maturity](https://docs.stripe.com/api/balance_transactions/object), and
+[history pagination and payout-filter limits](https://docs.stripe.com/api/balance_transactions/list).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fantastic.dev/better-stripe",
-  "version": "0.17.1",
+  "version": "0.19.0",
   "description": "A Convex component for Stripe V2 Accounts API integration.",
   "keywords": [
     "stripe",

package/src/client/connect/payouts.ts

@@ -53,17 +53,19 @@ export async function getAccountBalance(
   return [...byCurrency.values()];
 }
 
+export type CreatePayoutOptions = {
+  stripeAccountId: string;
+  amount: number;
+  currency?: string;
+  metadata?: Record<string, string>;
+  /** Stripe idempotency key for retry-safe payout creation. */
+  idempotencyKey?: string;
+};
+
 export async function createPayout(
   stripe: Stripe,
   _ctx: RunCtx,
-  opts: {
-    stripeAccountId: string;
-    amount: number;
-    currency?: string;
-    metadata?: Record<string, string>;
-    /** Stripe idempotency key for retry-safe payout creation. */
-    idempotencyKey?: string;
-  },
+  opts: CreatePayoutOptions,
 ) {
   const payout = await stripe.payouts.create(
     {

package/src/client/connect/transferReceipt.pagination.test.ts

@@ -0,0 +1,209 @@
+import type Stripe from "stripe";
+import { expect, it, vi } from "vitest";
+import type { Component, RunCtx } from "../helpers.js";
+import { getTransferFundingReceipt } from "./transferReceipt.js";
+const symbol = Symbol.for("toReferencePath");
+const component = {
+  connect: {
+    queries: {
+      getTransferByStripeId: {
+        [symbol]: "betterStripe/connect/queries/getTransferByStripeId",
+      },
+    },
+  },
+} as unknown as Component;
+const ledger = {
+  stripeTransferId: "tr_1",
+  destinationAccountId: "acct_owner",
+  amount: 1000,
+  currency: "usd",
+  status: "paid",
+};
+const tx = (id: string, amount: number, source = "py_1") => ({
+  id,
+  source,
+  amount,
+  net: amount,
+  fee: 0,
+  currency: "usd",
+  created: 1,
+  available_on: 2,
+  status: "available",
+  type: amount > 0 ? "payment" : "adjustment",
+  exchange_rate: null,
+});
+function setup() {
+  const ctx = {
+    runQuery: vi.fn().mockResolvedValue(ledger),
+  } as unknown as RunCtx;
+  const provider = {
+    transfers: {
+      retrieve: vi.fn().mockResolvedValue({
+        id: "tr_1",
+        destination: "acct_owner",
+        destination_payment: "py_1",
+        source_transaction: null,
+        amount: 1000,
+        amount_reversed: 0,
+        currency: "usd",
+      }),
+      listReversals: vi.fn().mockResolvedValue({ data: [], has_more: false }),
+    },
+    charges: {
+      retrieve: vi.fn().mockResolvedValue({
+        id: "py_1",
+        source_transfer: "tr_1",
+        amount: 1000,
+        currency: "usd",
+        paid: true,
+        status: "succeeded",
+        balance_transaction: "txn_credit",
+      }),
+    },
+    refunds: { retrieve: vi.fn() },
+    balanceTransactions: {
+      list: vi
+        .fn()
+        .mockResolvedValue({ data: [tx("txn_credit", 1000)], has_more: false }),
+    },
+  };
+  return {
+    ctx,
+    provider,
+    run: (extra: object = {}) =>
+      getTransferFundingReceipt(provider as unknown as Stripe, component, ctx, {
+        accountId: "acct_owner",
+        stripeTransferId: "tr_1",
+        ...extra,
+      }),
+  };
+}
+it("reads all 205 source receipts instead of truncating at the first provider page", async () => {
+  const { provider, run } = setup();
+  const rows = [
+    tx("txn_credit", 1000),
+    ...Array.from({ length: 204 }, (_, i) => tx(`txn_fee_${i}`, -1)),
+  ];
+  provider.balanceTransactions.list.mockImplementation(
+    async (args: { starting_after?: string }) => {
+      const start = args.starting_after
+        ? rows.findIndex((t) => t.id === args.starting_after) + 1
+        : 0;
+      return {
+        data: rows.slice(start, start + 100),
+        has_more: start + 100 < rows.length,
+      };
+    },
+  );
+  const result = await run();
+  expect(result).toMatchObject({
+    status: "ready",
+    totalNet: 796,
+    matureNet: 796,
+    pendingCredits: 0,
+  });
+  if (result.status === "ready") expect(result.transactions).toHaveLength(205);
+  expect(provider.balanceTransactions.list).toHaveBeenCalledTimes(3);
+  const limited = await run({ maxRequests: 6 });
+  expect(limited).toMatchObject({
+    status: "not_ready",
+    reason: "history_incomplete",
+  });
+  expect(limited).not.toHaveProperty("totalNet");
+});
+it("does not publish a source snapshot if its authoritative ledger changed during the read", async () => {
+  const { ctx, run } = setup();
+  (ctx.runQuery as ReturnType<typeof vi.fn>)
+    .mockReset()
+    .mockResolvedValueOnce(ledger)
+    .mockResolvedValueOnce({ ...ledger, reversedAmount: 1 });
+  expect(await run()).toMatchObject({
+    status: "not_ready",
+    reason: "ledger_changed",
+  });
+});
+it("propagates genuine provider failures and detects aggregate overflow", async () => {
+  const { provider, run } = setup();
+  provider.charges.retrieve.mockRejectedValueOnce(
+    new Error("provider unavailable"),
+  );
+  await expect(run()).rejects.toThrow("provider unavailable");
+  provider.balanceTransactions.list.mockResolvedValue({
+    data: [
+      tx("txn_credit", 1000),
+      { ...tx("txn_extra", Number.MAX_SAFE_INTEGER), type: "adjustment" },
+    ],
+    has_more: false,
+  });
+  await expect(run()).rejects.toThrow("safe integers");
+});
+it("never uses a pending fee credit to qualify a fully returned mature transfer", async () => {
+  const { ctx, provider, run } = setup();
+  (ctx.runQuery as ReturnType<typeof vi.fn>).mockResolvedValue({
+    ...ledger,
+    reversedAmount: 1000,
+  });
+  provider.transfers.retrieve.mockResolvedValue({
+    id: "tr_1",
+    destination: "acct_owner",
+    destination_payment: "py_1",
+    source_transaction: null,
+    amount: 1000,
+    amount_reversed: 1000,
+    currency: "usd",
+  });
+  provider.transfers.listReversals.mockResolvedValue({
+    data: [
+      {
+        id: "trr_1",
+        transfer: "tr_1",
+        amount: 1000,
+        currency: "usd",
+        destination_payment_refund: "pyr_1",
+      },
+    ],
+    has_more: false,
+  } as never);
+  provider.refunds.retrieve.mockResolvedValue({
+    id: "pyr_1",
+    charge: "py_1",
+    amount: 1000,
+    currency: "usd",
+    status: "succeeded",
+    balance_transaction: "txn_debit",
+  });
+  provider.balanceTransactions.list.mockImplementation(
+    async (args: { source: string }) => ({
+      data:
+        args.source === "py_1"
+          ? [
+              tx("txn_credit", 1000),
+              { ...tx("txn_fee_credit", 100), status: "pending" },
+            ]
+          : [{ ...tx("txn_debit", -1000, "pyr_1"), status: "pending" }],
+      has_more: false,
+    }),
+  );
+  expect(await run()).toMatchObject({
+    status: "ready",
+    totalNet: 100,
+    matureNet: 0,
+    pendingCredits: 100,
+  });
+});
+it("preserves an already available debit while its original credit is pending", async () => {
+  const { provider, run } = setup();
+  provider.balanceTransactions.list.mockResolvedValue({
+    data: [
+      { ...tx("txn_credit", 1000), status: "pending" },
+      tx("txn_fee", -200),
+    ],
+    has_more: false,
+  });
+  expect(await run()).toMatchObject({
+    status: "ready",
+    totalNet: 800,
+    matureNet: -200,
+    pendingCredits: 1000,
+  });
+});