@fantastic.dev/better-stripe 0.24.0 → 0.25.1

package/src/component/_generated/component.ts

@@ -3683,6 +3683,161 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         >;
       };
     };
+    payoutSnapshots: {
+      mutations: {
+        advance: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            batchSize?: number;
+            expectedStep: number;
+            operationKey: string;
+            ownerKey: string;
+          },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            allocationCount: number;
+            allocationCursor?: string;
+            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;
+          },
+          Name
+        >;
+        begin: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            expectedRevision: number;
+            operationKey: string;
+            ownerKey: string;
+          },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            allocationCount: number;
+            allocationCursor?: string;
+            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;
+          },
+          Name
+        >;
+        discard: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            batchSize?: number;
+            operationKey: string;
+            ownerKey: string;
+          },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            allocationCount: number;
+            allocationCursor?: string;
+            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
+        >;
+      };
+    };
     payoutSync: {
       mutations: {
         begin: FunctionReference<
@@ -3765,6 +3920,212 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         >;
       };
     };
+    payoutWorker: {
+      mutations: {
+        begin: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            cadenceMs: number;
+            currency: string;
+            ownerKey: string;
+          },
+          | { nextAttemptAt?: number; reason: string; status: "held" }
+          | {
+              job: {
+                _creationTime: number;
+                _id: string;
+                accountId: string;
+                cadenceMs: number;
+                completedGeneration?: number;
+                completedOperationKey?: string;
+                currency: string;
+                generation: number;
+                hasOperation: boolean;
+                lastAttemptAt?: number;
+                lastReason?: string;
+                leaseUntil?: number;
+                nextAttemptAt: number;
+                operationKey?: string;
+                ownerKey: string;
+                sequence: number;
+              };
+              reconcileOnly: boolean;
+              status: "run";
+            },
+          Name
+        >;
+        finish: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            currency: string;
+            generation: number;
+            operationKey: string;
+            ownerKey: string;
+            reason: string;
+          },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            cadenceMs: number;
+            completedGeneration?: number;
+            completedOperationKey?: string;
+            currency: string;
+            generation: number;
+            hasOperation: boolean;
+            lastAttemptAt?: number;
+            lastReason?: string;
+            leaseUntil?: number;
+            nextAttemptAt: number;
+            operationKey?: string;
+            ownerKey: string;
+            sequence: number;
+          },
+          Name
+        >;
+      };
+      queries: {
+        changing: FunctionReference<
+          "query",
+          "internal",
+          {
+            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;
+              country: string;
+              holdDeadline?: number;
+              mode: "stripe_managed" | "custom";
+              operationKey: string;
+              ownerKey: string;
+              previousSchedule?: {
+                interval: "daily" | "weekly" | "monthly" | "manual";
+                monthlyDays?: Array<number>;
+                weeklyDays?: Array<string>;
+              };
+              revision: number;
+              status: "changing" | "ready";
+              thresholds: Array<{ amount: number; currency: string }>;
+            }>;
+          },
+          Name
+        >;
+        get: FunctionReference<
+          "query",
+          "internal",
+          { accountId: string; currency: string; ownerKey: string },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            cadenceMs: number;
+            completedGeneration?: number;
+            completedOperationKey?: string;
+            currency: string;
+            generation: number;
+            hasOperation: boolean;
+            lastAttemptAt?: number;
+            lastReason?: string;
+            leaseUntil?: number;
+            nextAttemptAt: number;
+            operationKey?: string;
+            ownerKey: string;
+            sequence: number;
+          } | null,
+          Name
+        >;
+        policies: FunctionReference<
+          "query",
+          "internal",
+          {
+            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;
+              country: string;
+              holdDeadline?: number;
+              mode: "stripe_managed" | "custom";
+              operationKey: string;
+              ownerKey: string;
+              previousSchedule?: {
+                interval: "daily" | "weekly" | "monthly" | "manual";
+                monthlyDays?: Array<number>;
+                weeklyDays?: Array<string>;
+              };
+              revision: number;
+              status: "changing" | "ready";
+              thresholds: Array<{ amount: number; currency: string }>;
+            }>;
+          },
+          Name
+        >;
+        recovering: FunctionReference<
+          "query",
+          "internal",
+          {
+            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;
+              cadenceMs: number;
+              completedGeneration?: number;
+              completedOperationKey?: string;
+              currency: string;
+              generation: number;
+              hasOperation: boolean;
+              lastAttemptAt?: number;
+              lastReason?: string;
+              leaseUntil?: number;
+              nextAttemptAt: number;
+              operationKey?: string;
+              ownerKey: string;
+              sequence: number;
+            }>;
+          },
+          Name
+        >;
+      };
+    };
     products: {
       mutations: {
         upsertPrice: FunctionReference<

package/src/component/core/mutations.ts

@@ -1,3 +1,4 @@
+import { assertPayoutResetSafe } from "./resetSafety.js";
 import { v } from "convex/values";
 
 import type { TableNames } from "../_generated/dataModel";
@@ -155,6 +156,7 @@ export const clearAllTables = mutation({
     tables: v.array(v.string()),
   }),
   handler: async (ctx) => {
+    await assertPayoutResetSafe(ctx);
     // Derive table names from the schema definition so the clear list can never
     // drift out of sync when new tables are added.
     const tables = Object.keys(schema.tables) as TableNames[];

package/src/component/core/resetSafety.ts

@@ -0,0 +1,67 @@
+import type { MutationCtx } from "../_generated/server.js";
+/** A database reset cannot erase the only restoration or unresolved-payout record. */
+export async function assertPayoutResetSafe(ctx: MutationCtx) {
+  const [bound, custom, changing, reserved, submitted, pending, transit] =
+    await Promise.all([
+      ctx.db
+        .query("payoutSnapshots")
+        .withIndex("by_read_only", (q) => q.eq("readOnly", false))
+        .first(),
+      ctx.db
+        .query("payoutPolicies")
+        .withIndex("by_mode_status", (q) => q.eq("mode", "custom"))
+        .first(),
+      ctx.db
+        .query("payoutPolicies")
+        .withIndex("by_mode_status", (q) =>
+          q.eq("mode", "stripe_managed").eq("status", "changing"),
+        )
+        .first(),
+      ctx.db
+        .query("payoutReleaseClaims")
+        .withIndex("by_status", (q) => q.eq("status", "reserved"))
+        .first(),
+      ctx.db
+        .query("payoutReleaseClaims")
+        .withIndex("by_status", (q) => q.eq("status", "submitted"))
+        .first(),
+      ctx.db
+        .query("payouts")
+        .withIndex("by_status", (q) => q.eq("status", "pending"))
+        .first(),
+      ctx.db
+        .query("payouts")
+        .withIndex("by_status", (q) => q.eq("status", "in_transit"))
+        .first(),
+    ]);
+  if (bound)
+    throw new Error(
+      "A financially bound payout collection must be resolved before reset.",
+    );
+  if (custom || changing)
+    throw new Error(
+      "Restore and verify payout schedules before reset; restoration records cannot be erased.",
+    );
+  if (reserved || submitted)
+    throw new Error(
+      "Resolve payout claims before reset; unresolved reservations cannot be erased.",
+    );
+  if (pending || transit)
+    throw new Error("Verify in-flight provider payouts before reset.");
+  const affiliateOperations = await Promise.all(
+    (["pending", "unknown"] as const).flatMap((state) => [
+      ctx.db
+        .query("affiliatePayoutReleases")
+        .withIndex("by_state", (q) => q.eq("state", state))
+        .first(),
+      ctx.db
+        .query("affiliateRecoveryOperations")
+        .withIndex("by_state", (q) => q.eq("state", state))
+        .first(),
+    ]),
+  );
+  if (affiliateOperations.some(Boolean))
+    throw new Error(
+      "Resolve pending or unknown affiliate operations before reset.",
+    );
+}

package/src/component/earnings/triggers.ts

@@ -1,3 +1,4 @@
+import { registerPayoutRevisions } from "../payoutSnapshots/revisions.js";
 import { Triggers } from "convex-helpers/server/triggers";
 import {
   customCtx,
@@ -93,4 +94,5 @@ triggers.register("payouts", async (ctx, change) => {
       await ctx.innerDb.patch("payouts", change.id, { totalsRecorded: true });
   }
 });
+registerPayoutRevisions(triggers);
 export const mutation = customMutation(rawMutation, customCtx(triggers.wrapDB));

package/src/component/payout-reset-safety.test.ts

@@ -0,0 +1,148 @@
+// @vitest-environment edge-runtime
+import { convexTest } from "convex-test";
+import { makeFunctionReference } from "convex/server";
+import { expect, it } from "vitest";
+import schema from "./schema.js";
+const modules = import.meta.glob("./**/*.*s");
+const reset = makeFunctionReference<"mutation">(
+  "core/mutations:clearAllTables",
+);
+const scope = { accountId: "acct_one", ownerKey: "owner" };
+it.each(["custom", "changing"])(
+  "retains restoration records for %s payout policy",
+  async (kind) => {
+    const t = convexTest(schema, modules);
+    await t.run((ctx) =>
+      ctx.db.insert("payoutPolicies", {
+        ...scope,
+        revision: 0,
+        mode: kind === "custom" ? "custom" : "stripe_managed",
+        status: kind === "changing" ? "changing" : "ready",
+        operationKey: "control",
+        country: "US",
+        thresholds: [],
+        previousSchedule: { interval: "weekly", weeklyDays: ["monday"] },
+        holdDeadline: Date.now() + 86400000,
+      }),
+    );
+    await expect(t.mutation(reset, {})).rejects.toThrow(/payout.*schedule/i);
+    expect(
+      await t.run((ctx) => ctx.db.query("payoutPolicies").collect()),
+    ).toHaveLength(1);
+  },
+);
+it.each(["reserved", "submitted"])(
+  "retains an unresolved %s payout claim",
+  async (status) => {
+    const t = convexTest(schema, modules);
+    await t.run((ctx) =>
+      ctx.db.insert("payoutReleaseClaims", {
+        ...scope,
+        operationKey: "money",
+        expectedRevision: 0,
+        currency: "usd",
+        amount: 1000,
+        status: status as "reserved" | "submitted",
+        allocations: [{ stripeTransferId: "tr_one", amount: 1000 }],
+        observations: [],
+        attemptedAt: Date.now(),
+      }),
+    );
+    await expect(t.mutation(reset, {})).rejects.toThrow(/payout.*claim/i);
+    expect(
+      await t.run((ctx) => ctx.db.query("payoutReleaseClaims").collect()),
+    ).toHaveLength(1);
+  },
+);
+it("retains known in-flight provider payouts", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(
+    makeFunctionReference<"mutation">("connect/mutations:upsertPayout"),
+    {
+      stripePayoutId: "po_one",
+      accountId: scope.accountId,
+      currency: "usd",
+      amount: 1000,
+      status: "pending",
+    },
+  );
+  await expect(t.mutation(reset, {})).rejects.toThrow(/in.flight.*payout/i);
+  expect(await t.run((ctx) => ctx.db.query("payouts").collect())).toHaveLength(
+    1,
+  );
+});
+it("cannot bypass a bound collection through wholesale reset", async () => {
+  const t = convexTest(schema, modules);
+  const h = await t.mutation(
+    makeFunctionReference<"mutation">("payoutSnapshots/mutations:begin"),
+    { ...scope, operationKey: "collection", expectedRevision: -1 },
+  );
+  await t.run((ctx) =>
+    ctx.db.patch("payoutSnapshots", h._id, { readOnly: false }),
+  );
+  await expect(t.mutation(reset, {})).rejects.toThrow(/bound.*collection/i);
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSnapshots").collect()),
+  ).toHaveLength(1);
+});
+it.each(["pending", "unknown"] as const)(
+  "retains %s direct affiliate payout attempts",
+  async (state) => {
+    const t = convexTest(schema, modules);
+    await t.run((ctx) =>
+      ctx.db.insert("affiliatePayoutReleases", {
+        affiliateAccountId: scope.accountId,
+        currency: "usd",
+        operationKey: "direct-affiliate",
+        amount: 1000,
+        minimumAmount: 1,
+        createdAt: Date.now(),
+        state,
+      }),
+    );
+    await expect(t.mutation(reset, {})).rejects.toThrow(
+      /affiliate.*operation/i,
+    );
+    expect(
+      await t.run((ctx) => ctx.db.query("affiliatePayoutReleases").collect()),
+    ).toHaveLength(1);
+  },
+);
+it.each(["pending", "unknown"] as const)(
+  "retains %s affiliate recovery attempts",
+  async (state) => {
+    const t = convexTest(schema, modules);
+    await t.run(async (ctx) => {
+      const obligationId = await ctx.db.insert("affiliateObligations", {
+        sourceChargeId: "ch_one",
+        affiliateAccountId: scope.accountId,
+        currency: "usd",
+        chargeAmount: 1000,
+        originalCommission: 100,
+        refundedPrincipal: 1000,
+        disputedPrincipal: 0,
+        lostPrincipal: 0,
+        finalizedAmount: 100,
+        provisionalAmount: 0,
+        recoveredAmount: 0,
+        needsReconciliation: false,
+      });
+      await ctx.db.insert("affiliateRecoveryOperations", {
+        obligationId,
+        kind: "recovery",
+        amount: 100,
+        state,
+        attempted: true,
+        createdAt: Date.now(),
+      });
+    });
+    await expect(t.mutation(reset, {})).rejects.toThrow(
+      /affiliate.*operation/i,
+    );
+    expect(
+      await t.run((ctx) =>
+        ctx.db.query("affiliateRecoveryOperations").collect(),
+      ),
+    ).toHaveLength(1);
+  },
+);