@fantastic.dev/better-stripe 0.28.6 → 0.29.0

package/src/component/_generated/api.ts

@@ -63,8 +63,11 @@ import type * as payoutRelease_planning from "../payoutRelease/planning.js";
 import type * as payoutRelease_preview from "../payoutRelease/preview.js";
 import type * as payoutRelease_progress from "../payoutRelease/progress.js";
 import type * as payoutRelease_queries from "../payoutRelease/queries.js";
+import type * as payoutSnapshots_financial from "../payoutSnapshots/financial.js";
+import type * as payoutSnapshots_liabilities from "../payoutSnapshots/liabilities.js";
 import type * as payoutSnapshots_localState from "../payoutSnapshots/localState.js";
 import type * as payoutSnapshots_mutations from "../payoutSnapshots/mutations.js";
+import type * as payoutSnapshots_queries from "../payoutSnapshots/queries.js";
 import type * as payoutSnapshots_revisions from "../payoutSnapshots/revisions.js";
 import type * as payoutSnapshots_scope from "../payoutSnapshots/scope.js";
 import type * as payoutSync_helpers from "../payoutSync/helpers.js";
@@ -149,8 +152,11 @@ const fullApi: ApiFromModules<{
   "payoutRelease/preview": typeof payoutRelease_preview;
   "payoutRelease/progress": typeof payoutRelease_progress;
   "payoutRelease/queries": typeof payoutRelease_queries;
+  "payoutSnapshots/financial": typeof payoutSnapshots_financial;
+  "payoutSnapshots/liabilities": typeof payoutSnapshots_liabilities;
   "payoutSnapshots/localState": typeof payoutSnapshots_localState;
   "payoutSnapshots/mutations": typeof payoutSnapshots_mutations;
+  "payoutSnapshots/queries": typeof payoutSnapshots_queries;
   "payoutSnapshots/revisions": typeof payoutSnapshots_revisions;
   "payoutSnapshots/scope": typeof payoutSnapshots_scope;
   "payoutSync/helpers": typeof payoutSync_helpers;

package/src/component/_generated/component.ts

@@ -2689,6 +2689,13 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           },
           Name
         >;
+        payoutQuote: FunctionReference<
+          "query",
+          "internal",
+          { accountId: string; currency: string; scopeKey: string },
+          { independentLiabilities: number; liabilityRevision: number },
+          Name
+        >;
         reservation: FunctionReference<
           "query",
           "internal",
@@ -3273,6 +3280,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               expectedRevision: number;
               feeRevision?: number;
               historical?: boolean;
+              independentLiabilities?: number;
+              liabilityRevision?: number;
               observations: Array<{
                 currency: string;
                 ledgerFingerprint: string;
@@ -3290,6 +3299,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 requestId: string;
               };
               returnTransactionId?: string;
+              snapshotId?: string;
               status:
                 | "reserved"
                 | "submitted"
@@ -3324,6 +3334,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             expectedRevision: number;
             feeRevision?: number;
             historical?: boolean;
+            independentLiabilities?: number;
+            liabilityRevision?: number;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -3341,6 +3353,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               requestId: string;
             };
             returnTransactionId?: string;
+            snapshotId?: string;
             status:
               | "reserved"
               | "submitted"
@@ -3374,6 +3387,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             expectedRevision: number;
             feeRevision?: number;
             historical?: boolean;
+            independentLiabilities?: number;
+            liabilityRevision?: number;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -3391,6 +3406,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               requestId: string;
             };
             returnTransactionId?: string;
+            snapshotId?: string;
             status:
               | "reserved"
               | "submitted"
@@ -3411,6 +3427,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationId?: string;
             expectedRevision: number;
             independentLiabilities: number;
+            liabilityRevision?: number;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -3423,6 +3440,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             operationKey: string;
             ownerKey: string;
             providerAvailable: number;
+            snapshotId?: string;
           },
           | {
               _creationTime: number;
@@ -3442,6 +3460,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               expectedRevision: number;
               feeRevision?: number;
               historical?: boolean;
+              independentLiabilities?: number;
+              liabilityRevision?: number;
               observations: Array<{
                 currency: string;
                 ledgerFingerprint: string;
@@ -3459,6 +3479,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 requestId: string;
               };
               returnTransactionId?: string;
+              snapshotId?: string;
               status:
                 | "reserved"
                 | "submitted"
@@ -3515,6 +3536,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             expectedRevision: number;
             feeRevision?: number;
             historical?: boolean;
+            independentLiabilities?: number;
+            liabilityRevision?: number;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -3532,6 +3555,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               requestId: string;
             };
             returnTransactionId?: string;
+            snapshotId?: string;
             status:
               | "reserved"
               | "submitted"
@@ -3571,6 +3595,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             expectedRevision: number;
             feeRevision?: number;
             historical?: boolean;
+            independentLiabilities?: number;
+            liabilityRevision?: number;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -3588,6 +3614,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               requestId: string;
             };
             returnTransactionId?: string;
+            snapshotId?: string;
             status:
               | "reserved"
               | "submitted"
@@ -3630,6 +3657,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             expectedRevision: number;
             feeRevision?: number;
             historical?: boolean;
+            independentLiabilities?: number;
+            liabilityRevision?: number;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -3647,6 +3676,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               requestId: string;
             };
             returnTransactionId?: string;
+            snapshotId?: string;
             status:
               | "reserved"
               | "submitted"
@@ -3694,6 +3724,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               expectedRevision: number;
               feeRevision?: number;
               historical?: boolean;
+              independentLiabilities?: number;
+              liabilityRevision?: number;
               observations: Array<{
                 currency: string;
                 ledgerFingerprint: string;
@@ -3711,6 +3743,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 requestId: string;
               };
               returnTransactionId?: string;
+              snapshotId?: string;
               status:
                 | "reserved"
                 | "submitted"
@@ -3731,6 +3764,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             currency: string;
             expectedRevision: number;
             independentLiabilities: number;
+            liabilityRevision?: number;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -3742,6 +3776,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             }>;
             ownerKey: string;
             providerAvailable: number;
+            snapshotId?: string;
           },
           | { amount: 0; reason: string; status: "held" }
           | {
@@ -3799,6 +3834,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 expectedRevision: number;
                 feeRevision?: number;
                 historical?: boolean;
+                independentLiabilities?: number;
+                liabilityRevision?: number;
                 observations: Array<{
                   currency: string;
                   ledgerFingerprint: string;
@@ -3816,6 +3853,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                   requestId: string;
                 };
                 returnTransactionId?: string;
+                snapshotId?: string;
                 status:
                   | "reserved"
                   | "submitted"
@@ -3868,6 +3906,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             accountId: string;
             allocationCount: number;
             allocationCursor?: string;
+            boundOperationKey?: string;
+            boundRiskRevision?: number;
             claimCount: number;
             claimCursor?: string;
             deferredPositiveChanges: boolean;
@@ -3918,6 +3958,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             accountId: string;
             allocationCount: number;
             allocationCursor?: string;
+            boundOperationKey?: string;
+            boundRiskRevision?: number;
             claimCount: number;
             claimCursor?: string;
             deferredPositiveChanges: boolean;
@@ -3968,6 +4010,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             accountId: string;
             allocationCount: number;
             allocationCursor?: string;
+            boundOperationKey?: string;
+            boundRiskRevision?: number;
             claimCount: number;
             claimCursor?: string;
             deferredPositiveChanges: boolean;
@@ -4004,6 +4048,165 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           Name
         >;
       };
+      queries: {
+        claims: FunctionReference<
+          "query",
+          "internal",
+          {
+            accountId: string;
+            operationKey: string;
+            ownerKey: string;
+            paginationOpts: {
+              cursor: string | null;
+              endCursor?: string | null;
+              id?: number;
+              maximumBytesRead?: number;
+              maximumRowsRead?: number;
+              numItems: number;
+            };
+          },
+          {
+            continueCursor: string;
+            isDone: boolean;
+            page: Array<{
+              _creationTime: number;
+              _id: string;
+              accountId: string;
+              allocations: Array<{
+                amount: number;
+                role?: "store" | "affiliate" | "other";
+                stripeTransferId: string;
+              }>;
+              amount: number;
+              attemptedAt?: number;
+              currency: string;
+              debitFee?: number;
+              debitTransactionId?: string;
+              destinationId?: string;
+              expectedRevision: number;
+              feeRevision?: number;
+              historical?: boolean;
+              independentLiabilities?: number;
+              liabilityRevision?: number;
+              observations: Array<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: Array<string>;
+              }>;
+              operationKey: string;
+              ownerKey: string;
+              providerFee?: number;
+              rejection?: {
+                code: "balance_insufficient" | "amount_too_small";
+                requestId: string;
+              };
+              returnTransactionId?: string;
+              snapshotId?: string;
+              status:
+                | "reserved"
+                | "submitted"
+                | "paid"
+                | "returned"
+                | "canceled"
+                | "rejected";
+              stripePayoutId?: string;
+            }>;
+          },
+          Name
+        >;
+        get: FunctionReference<
+          "query",
+          "internal",
+          { accountId: string; operationKey: string; ownerKey: string },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            allocationCount: number;
+            allocationCursor?: string;
+            boundOperationKey?: string;
+            boundRiskRevision?: number;
+            claimCount: number;
+            claimCursor?: string;
+            deferredPositiveChanges: boolean;
+            expectedRevision: number;
+            expiresAt: number;
+            feeCount: number;
+            feeCursor?: string;
+            initialRevision: number;
+            initialRiskRevision: number;
+            observedRevision: number;
+            operationKey: string;
+            ownerKey: string;
+            phase:
+              | "sources"
+              | "allocations"
+              | "fees"
+              | "claims"
+              | "repair"
+              | "check"
+              | "local_ready"
+              | "invalidated"
+              | "discarding";
+            policyMode?: string;
+            policyOperationKey?: string;
+            providerChanged: boolean;
+            readOnly: boolean;
+            reason?: string;
+            riskRevision: number;
+            sourceCount: number;
+            sourceCursor?: string;
+            sourceFence: number;
+            step: number;
+          } | null,
+          Name
+        >;
+        sources: FunctionReference<
+          "query",
+          "internal",
+          {
+            accountId: string;
+            operationKey: string;
+            ownerKey: string;
+            paginationOpts: {
+              cursor: string | null;
+              endCursor?: string | null;
+              id?: number;
+              maximumBytesRead?: number;
+              maximumRowsRead?: number;
+              numItems: number;
+            };
+          },
+          {
+            continueCursor: string;
+            isDone: boolean;
+            page: Array<{
+              _creationTime: number;
+              _id: string;
+              amount: number;
+              currency: string;
+              destinationAccountId: string;
+              metadata?: any;
+              paymentId?: string;
+              reinstatement?: boolean;
+              reversalClaimedAmount?: number;
+              reversalStatus?: "partially_reversed" | "fully_reversed";
+              reversedAmount?: number;
+              role?: "store" | "affiliate" | "other";
+              sourceChargeId?: string;
+              sourceInvoiceId?: string;
+              status: "pending" | "paid" | "failed" | "reversed";
+              stripeTransferId: string;
+              totalsRecorded?: true;
+            }>;
+          },
+          Name
+        >;
+      };
     };
     payoutSync: {
       mutations: {

package/src/component/costRecovery/mutations.ts

@@ -1,7 +1,7 @@
 import { importOpeningClaim } from "./imports.js";
 import { getGroup, integer } from "./helpers.js";
 import { v } from "convex/values";
-import { mutation } from "../_generated/server.js";
+import { mutation } from "../earnings/triggers.js";
 import { recordClaim, rollbackClaim } from "./claims.js";
 import { reserveGroup, sealGroup } from "./reservations.js";
 import { finishGroup } from "./completion.js";

package/src/component/costRecovery/queries.ts

@@ -1,3 +1,4 @@
+import { riskRevision } from "../payoutSnapshots/revisions.js";
 import { paginator } from "convex-helpers/server/pagination";
 import schema from "../schema.js";
 import { paginationOptsValidator } from "convex/server";
@@ -88,3 +89,23 @@ export const claim = query({
       .withIndex("by_key", (q) => q.eq("claimKey", args.claimKey))
       .unique(),
 });
+
+/** Amount and account version come from the same database snapshot. Host authorizes this scope. */
+export const payoutQuote = query({
+  args: scopeFields,
+  returns: v.object({
+    independentLiabilities: v.number(),
+    liabilityRevision: v.number(),
+  }),
+  handler: async (ctx, args) => {
+    validateScope(args);
+    const balance = await readBalance(ctx, args);
+    const amount = (balance?.amountDue ?? 0) - (balance?.collectedAmount ?? 0);
+    if (!Number.isSafeInteger(amount))
+      throw new Error("Invalid payout recovery liability.");
+    return {
+      independentLiabilities: Math.max(0, amount),
+      liabilityRevision: await riskRevision(ctx, args.accountId),
+    };
+  },
+});

package/src/component/payoutRelease/helpers.ts

@@ -72,24 +72,29 @@ export async function checkSnapshot(
   observations: Infer<typeof observation>[],
   fresh: boolean,
   freshCurrency?: string,
+  membership?: Map<string, Doc<"transfers">>,
 ) {
-  const rows = await ctx.db
-    .query("transfers")
-    .withIndex("by_destination_account_id", (q) =>
-      q.eq("destinationAccountId", accountId),
-    )
-    .take(101);
+  const rows = membership
+    ? [...membership.values()]
+    : await ctx.db
+        .query("transfers")
+        .withIndex("by_destination_account_id", (q) =>
+          q.eq("destinationAccountId", accountId),
+        )
+        .take(101);
   if (
-    rows.length > 100 ||
+    (!membership && rows.length > 100) ||
     observations.length !== rows.length ||
     new Set(observations.map((o) => o.stripeTransferId)).size !== rows.length
   )
     throw new Error("Payout source snapshot is incomplete or duplicated.");
   const byId = new Map(rows.map((row) => [row.stripeTransferId, row]));
-  const allocated = await ctx.db
-    .query("payoutSourceAllocations")
-    .withIndex("by_account", (q) => q.eq("accountId", accountId))
-    .take(101);
+  const allocated = membership
+    ? []
+    : await ctx.db
+        .query("payoutSourceAllocations")
+        .withIndex("by_account", (q) => q.eq("accountId", accountId))
+        .take(101);
   if (
     allocated.length > 100 ||
     allocated.some((source) => !byId.has(source.stripeTransferId))
@@ -179,6 +184,9 @@ export function payoutClaimFingerprint(c: Doc<"payoutReleaseClaims">) {
     c.ownerKey,
     c.operationKey,
     c.historical ?? false,
+    c.snapshotId,
+    c.liabilityRevision,
+    c.independentLiabilities,
     c.currency,
     c.amount,
     c.status,

package/src/component/payoutRelease/mutations.ts

@@ -1,3 +1,8 @@
+import {
+  collectedSources,
+  bindCollection,
+  retireCollection,
+} from "../payoutSnapshots/financial.js";
 import {
   reserveRecoveryGuard,
   releaseRecoveryGuard,
@@ -43,6 +48,8 @@ export const claim = mutation({
     providerAvailable: v.number(),
     independentLiabilities: v.number(),
     observations: v.array(observation),
+    snapshotId: v.optional(v.id("payoutSnapshots")),
+    liabilityRevision: v.optional(v.number()),
   },
   returns: v.union(claimDoc, held),
   handler: async (ctx, args) => {
@@ -106,10 +113,17 @@ export const claim = mutation({
       ...(args.destinationId ? { destinationId: args.destinationId } : {}),
       allocations: plan.allocations,
       observations: args.observations,
+      independentLiabilities: args.independentLiabilities,
+      ...(args.snapshotId ? { snapshotId: args.snapshotId } : {}),
+      ...(args.liabilityRevision === undefined
+        ? {}
+        : { liabilityRevision: args.liabilityRevision }),
       feeRevision: fees?.revision ?? 0,
       status: "reserved",
     });
-    return (await ctx.db.get("payoutReleaseClaims", id))!;
+    const claim = (await ctx.db.get("payoutReleaseClaims", id))!;
+    await bindCollection(ctx, claim);
+    return claim;
   },
 });
 export const beginAttempt = mutation({
@@ -130,11 +144,13 @@ export const beginAttempt = mutation({
       claim.observations,
       true,
       claim.currency,
+      await collectedSources(ctx, claim, claim.observations),
     );
     await reserveRecoveryGuard(ctx, claim, claim.amount);
     await ctx.db.patch("payoutReleaseClaims", claim._id, {
       attemptedAt: Date.now(),
     });
+    await retireCollection(ctx, claim);
     return (await ctx.db.get("payoutReleaseClaims", claim._id))!;
   },
 });
@@ -151,6 +167,7 @@ export const cancelUnattempted = mutation({
       throw new Error("An attempted payout claim cannot be canceled.");
     if (claim.status === "canceled") return claim;
     await moveAllocations(ctx, claim, "release");
+    await retireCollection(ctx, claim);
     await releaseRecoveryGuard(ctx, claim);
     await ctx.db.patch("payoutReleaseClaims", claim._id, {
       status: "canceled",

package/src/component/payoutRelease/planning.ts

@@ -1,3 +1,5 @@
+import { collectedSources } from "../payoutSnapshots/financial.js";
+import type { Id } from "../_generated/dataModel.js";
 import type { Infer } from "convex/values";
 import type { MutationCtx, QueryCtx } from "../_generated/server.js";
 import type { policyDoc } from "../payoutPolicy/schema.js";
@@ -14,6 +16,9 @@ export async function readPayoutPlan(
     ownerKey: string;
     currency: string;
     observations: Infer<typeof observation>[];
+    snapshotId?: Id<"payoutSnapshots">;
+    operationKey?: string;
+    liabilityRevision?: number;
     providerAvailable: number;
     independentLiabilities: number;
   },
@@ -27,6 +32,7 @@ export async function readPayoutPlan(
     args.observations,
     true,
     args.currency,
+    await collectedSources(ctx, args, args.observations),
   );
   const sources: PayoutFundingSource[] = [];
   for (const observation of args.observations) {
@@ -46,7 +52,7 @@ export async function readPayoutPlan(
     });
   }
   const fees = await readFees(ctx, args);
-  await assertAllocationTotals(ctx, args, sources);
+  if (!args.snapshotId) await assertAllocationTotals(ctx, args, sources);
   const minimumWaived = waiveApplicationMinimum(policy, Date.now());
   const plan = planRecipientPayout({
     currency: args.currency,

package/src/component/payoutRelease/preview.ts

@@ -14,6 +14,8 @@ export const previewFields = {
   providerAvailable: v.number(),
   independentLiabilities: v.number(),
   observations: v.array(observation),
+  snapshotId: v.optional(v.id("payoutSnapshots")),
+  liabilityRevision: v.optional(v.number()),
 };
 const held = v.object({
   status: v.literal("held"),

package/src/component/payoutRelease/schema.ts

@@ -13,6 +13,9 @@ export const allocation = v.object({
 export const claimFields = {
   ...scopeFields,
   historical: v.optional(v.boolean()),
+  snapshotId: v.optional(v.id("payoutSnapshots")),
+  liabilityRevision: v.optional(v.number()),
+  independentLiabilities: v.optional(v.number()),
   operationKey: v.string(),
   expectedRevision: v.number(),
   currency: v.string(),