@fantastic.dev/better-stripe 0.17.0 → 0.18.0

package/src/component/_generated/component.ts

@@ -2194,6 +2194,286 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         >;
       };
     };
+    payoutPolicy: {
+      mutations: {
+        beginAttempt: FunctionReference<
+          "mutation",
+          "internal",
+          { accountId: string; operationKey: string; ownerKey: string },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            attempted?: boolean;
+            country: string;
+            expectedRevision: number;
+            mode: "stripe_managed" | "custom";
+            observedAt?: number;
+            observedSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            operationKey: string;
+            ownerKey: string;
+            previousSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            revision: number;
+            status: "pending" | "complete" | "canceled";
+            targetSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            thresholds: Array<{ amount: number; currency: string }>;
+          },
+          Name
+        >;
+        cancelUnattempted: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            observedSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            operationKey: string;
+            ownerKey: string;
+          },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            attempted?: boolean;
+            country: string;
+            expectedRevision: number;
+            mode: "stripe_managed" | "custom";
+            observedAt?: number;
+            observedSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            operationKey: string;
+            ownerKey: string;
+            previousSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            revision: number;
+            status: "pending" | "complete" | "canceled";
+            targetSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            thresholds: Array<{ amount: number; currency: string }>;
+          },
+          Name
+        >;
+        confirm: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            observedSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            operationKey: string;
+            ownerKey: string;
+          },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            attempted?: boolean;
+            country: string;
+            expectedRevision: number;
+            mode: "stripe_managed" | "custom";
+            observedAt?: number;
+            observedSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            operationKey: string;
+            ownerKey: string;
+            previousSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            revision: number;
+            status: "pending" | "complete" | "canceled";
+            targetSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            thresholds: Array<{ amount: number; currency: string }>;
+          },
+          Name
+        >;
+        prepare: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            country: string;
+            expectedRevision: number;
+            mode: "stripe_managed" | "custom";
+            observedAt?: number;
+            observedSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            operationKey: string;
+            ownerKey: string;
+            thresholds: Array<{ amount: number; currency: string }>;
+          },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            attempted?: boolean;
+            country: string;
+            expectedRevision: number;
+            mode: "stripe_managed" | "custom";
+            observedAt?: number;
+            observedSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            operationKey: string;
+            ownerKey: string;
+            previousSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            revision: number;
+            status: "pending" | "complete" | "canceled";
+            targetSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            thresholds: Array<{ amount: number; currency: string }>;
+          },
+          Name
+        >;
+      };
+      queries: {
+        due: FunctionReference<
+          "query",
+          "internal",
+          {
+            now: number;
+            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; ownerKey: string },
+          {
+            _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 }>;
+          } | null,
+          Name
+        >;
+        operation: FunctionReference<
+          "query",
+          "internal",
+          { accountId: string; operationKey: string; ownerKey: string },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            attempted?: boolean;
+            country: string;
+            expectedRevision: number;
+            mode: "stripe_managed" | "custom";
+            observedAt?: number;
+            observedSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            operationKey: string;
+            ownerKey: string;
+            previousSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            revision: number;
+            status: "pending" | "complete" | "canceled";
+            targetSchedule: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            thresholds: Array<{ amount: number; currency: string }>;
+          } | null,
+          Name
+        >;
+      };
+    };
     products: {
       mutations: {
         upsertPrice: FunctionReference<

package/src/component/connect/queries.ts

@@ -3,6 +3,7 @@ import {
   getAccountPayouts as getAccountPayoutsLegacy,
 } from "../earnings/legacyReads.js";
 import { currencyTotals, previewSize } from "../earnings/reads.js";
+import { addSummaryAmounts } from "../earnings/arithmetic.js";
 import { v } from "convex/values";
 import { paginator } from "convex-helpers/server/pagination";
 import schema from "../schema.js";
@@ -557,7 +558,7 @@ export const getAccountEarningsByCurrency = query({
         currency: r.currency,
         gross: r.gross,
         reversed: r.reversed,
-        net: r.gross - r.reversed,
+        net: addSummaryAmounts(r.gross, -r.reversed),
         transferCount: r.count,
       })),
       transfers,

package/src/component/earnings/arithmetic.ts

@@ -0,0 +1,10 @@
+/** Check exact integer arithmetic before converting back to the public Number representation. */
+export function addSummaryAmounts(left: number, right: number): number {
+  if (!Number.isSafeInteger(left) || !Number.isSafeInteger(right))
+    throw new Error("Currency totals require safe integer amounts");
+  const result = BigInt(left) + BigInt(right);
+  const limit = BigInt(Number.MAX_SAFE_INTEGER);
+  if (result > limit || result < -limit)
+    throw new Error("Currency totals exceed supported safe integer bounds");
+  return Number(result);
+}

package/src/component/earnings/reads.ts

@@ -1,4 +1,5 @@
 import type { QueryCtx } from "../_generated/server.js";
+import { addSummaryAmounts } from "./arithmetic.js";
 export function previewSize(value = 50) {
   if (!Number.isInteger(value) || value < 0 || value > 100)
     throw new Error("Preview size must be an integer from 0 to 100");
@@ -37,5 +38,10 @@ export async function currencyTotals(
     .take(501);
   if (rows.length > 500)
     throw new Error("Account exceeds supported currency count");
+  for (const row of rows) {
+    for (const value of [row.gross, row.reversed, row.paidOut, row.count])
+      addSummaryAmounts(value, 0);
+    addSummaryAmounts(row.gross, -row.reversed);
+  }
   return rows;
 }

package/src/component/earnings/triggers.ts

@@ -4,6 +4,7 @@ import {
   customMutation,
 } from "convex-helpers/server/customFunctions";
 import type { DataModel } from "../_generated/dataModel.js";
+import { addSummaryAmounts } from "./arithmetic.js";
 import {
   mutation as rawMutation,
   type MutationCtx,
@@ -21,7 +22,7 @@ async function adjust(
   ctx: MutationCtx,
   kind: "earnings" | "payouts",
   value: Contribution,
-  sign: number,
+  sign: 1 | -1,
 ) {
   const row = await ctx.db
     .query("currencyTotals")
@@ -33,11 +34,12 @@ async function adjust(
     )
     .unique();
   const totals = {
-    gross: (row?.gross ?? 0) + sign * value.gross,
-    reversed: (row?.reversed ?? 0) + sign * value.reversed,
-    paidOut: (row?.paidOut ?? 0) + sign * value.paidOut,
-    count: (row?.count ?? 0) + sign * value.count,
+    gross: addSummaryAmounts(row?.gross ?? 0, sign * value.gross),
+    reversed: addSummaryAmounts(row?.reversed ?? 0, sign * value.reversed),
+    paidOut: addSummaryAmounts(row?.paidOut ?? 0, sign * value.paidOut),
+    count: addSummaryAmounts(row?.count ?? 0, sign * value.count),
   };
+  addSummaryAmounts(totals.gross, -totals.reversed);
   if (row) {
     if (totals.count === 0) await ctx.db.delete("currencyTotals", row._id);
     else await ctx.db.patch("currencyTotals", row._id, totals);
@@ -72,14 +74,17 @@ triggers.register("transfers", async (ctx, change) => {
 triggers.register("payouts", async (ctx, change) => {
   const contribution = (
     row: NonNullable<typeof change.newDoc>,
-  ): Contribution => ({
-    accountId: row.accountId,
-    currency: row.currency,
-    gross: 0,
-    reversed: 0,
-    paidOut: row.status === "paid" ? row.amount : 0,
-    count: 1,
-  });
+  ): Contribution => {
+    const amount = addSummaryAmounts(row.amount, 0);
+    return {
+      accountId: row.accountId,
+      currency: row.currency,
+      gross: 0,
+      reversed: 0,
+      paidOut: row.status === "paid" ? amount : 0,
+      count: 1,
+    };
+  };
   if (change.oldDoc?.totalsRecorded)
     await adjust(ctx, "payouts", contribution(change.oldDoc), -1);
   if (change.newDoc) {

package/src/component/payout-policy.test.ts

@@ -0,0 +1,248 @@
+// @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 m = (name: string) =>
+  makeFunctionReference<"mutation">(`payoutPolicy/mutations:${name}`);
+const q = (name: string) =>
+  makeFunctionReference<"query">(`payoutPolicy/queries:${name}`);
+const scope = { accountId: "acct_recipient", ownerKey: "user_1" };
+const initial = {
+  ...scope,
+  operationKey: "enable-1",
+  expectedRevision: -1,
+  mode: "custom",
+  thresholds: [{ currency: "usd", amount: 1000 }],
+  country: "US",
+  observedSchedule: { interval: "weekly", weeklyDays: ["friday", "monday"] },
+};
+it("persists restoration and a deadline before provider mutation, then confirms exactly once", async () => {
+  const t = convexTest(schema, modules);
+  const op = await t.mutation(m("prepare"), initial);
+  expect(op.status).toBe("pending");
+  expect(op.targetSchedule).toEqual({ interval: "manual" });
+  expect(op.previousSchedule).toEqual(initial.observedSchedule);
+  let policy = await t.query(q("get"), scope);
+  expect(policy.status).toBe("changing");
+  expect(policy.revision).toBe(0);
+  expect(policy.holdDeadline).toBeGreaterThan(Date.now());
+  await t.mutation(m("confirm"), {
+    ...scope,
+    operationKey: "enable-1",
+    observedSchedule: { interval: "manual" },
+  });
+  policy = await t.query(q("get"), scope);
+  expect(policy.status).toBe("ready");
+  expect(policy.mode).toBe("custom");
+  expect(
+    await t.mutation(m("confirm"), {
+      ...scope,
+      operationKey: "enable-1",
+      observedSchedule: { interval: "manual" },
+    }),
+  ).toEqual(
+    await t.query(q("operation"), { ...scope, operationKey: "enable-1" }),
+  );
+});
+it("preserves the original schedule and deadline across threshold changes and opt-out", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(m("prepare"), initial);
+  await t.mutation(m("confirm"), {
+    ...scope,
+    operationKey: "enable-1",
+    observedSchedule: { interval: "manual" },
+  });
+  const original = await t.query(q("get"), scope);
+  const change = {
+    ...initial,
+    operationKey: "change",
+    expectedRevision: 0,
+    thresholds: [
+      { currency: "eur", amount: 500 },
+      { currency: "usd", amount: 2000 },
+    ],
+    observedSchedule: { interval: "manual" },
+  };
+  await t.mutation(m("prepare"), change);
+  await t.mutation(m("confirm"), {
+    ...scope,
+    operationKey: "change",
+    observedSchedule: { interval: "manual" },
+  });
+  const updated = await t.query(q("get"), scope);
+  expect(updated.previousSchedule).toEqual(original.previousSchedule);
+  expect(updated.holdDeadline).toBe(original.holdDeadline);
+  const off = await t.mutation(m("prepare"), {
+    ...change,
+    operationKey: "off",
+    expectedRevision: 1,
+    mode: "stripe_managed",
+    thresholds: [],
+  });
+  expect(off.targetSchedule).toEqual(initial.observedSchedule);
+  await t.mutation(m("confirm"), {
+    ...scope,
+    operationKey: "off",
+    observedSchedule: initial.observedSchedule,
+  });
+  expect(await t.query(q("get"), scope)).toMatchObject({
+    mode: "stripe_managed",
+    status: "ready",
+    thresholds: [],
+  });
+});
+it("rejects changed replays, ownership changes, stale revisions and competing operations", async () => {
+  const t = convexTest(schema, modules);
+  const op = await t.mutation(m("prepare"), initial);
+  expect(await t.mutation(m("prepare"), initial)).toEqual(op);
+  for (const changed of [
+    { thresholds: [{ currency: "usd", amount: 900 }] },
+    { ownerKey: "other" },
+    { accountId: "acct_other" },
+  ])
+    await expect(
+      t.mutation(m("prepare"), { ...initial, ...changed }),
+    ).rejects.toThrow(/identity|operation/);
+  await expect(
+    t.mutation(m("prepare"), {
+      ...initial,
+      operationKey: "other",
+      expectedRevision: 0,
+    }),
+  ).rejects.toThrow(/pending/);
+  await t.mutation(m("confirm"), {
+    ...scope,
+    operationKey: "enable-1",
+    observedSchedule: { interval: "manual" },
+  });
+  await expect(
+    t.mutation(m("prepare"), { ...initial, operationKey: "other" }),
+  ).rejects.toThrow(/revision/);
+  await expect(
+    t.query(q("get"), { ...scope, ownerKey: "other" }),
+  ).rejects.toThrow(/owner/);
+});
+it("cannot confirm a different provider schedule or hide external drift", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(m("prepare"), initial);
+  await expect(
+    t.mutation(m("confirm"), {
+      ...scope,
+      operationKey: "enable-1",
+      observedSchedule: { interval: "daily" },
+    }),
+  ).rejects.toThrow(/schedule/);
+  await t.mutation(m("confirm"), {
+    ...scope,
+    operationKey: "enable-1",
+    observedSchedule: { interval: "manual" },
+  });
+  await expect(
+    t.mutation(m("prepare"), {
+      ...initial,
+      operationKey: "change",
+      expectedRevision: 0,
+      observedSchedule: { interval: "daily" },
+    }),
+  ).rejects.toThrow(/drift/);
+});
+it.each([0, -1, 1.5, Number.MAX_SAFE_INTEGER + 1])(
+  "rejects invalid custom minor-unit thresholds (%s)",
+  async (amount) => {
+    const t = convexTest(schema, modules);
+    await expect(
+      t.mutation(m("prepare"), {
+        ...initial,
+        thresholds: [{ currency: "usd", amount }],
+      }),
+    ).rejects.toThrow(/threshold/);
+  },
+);
+it("uses country holding limits and never extends a hold by editing thresholds", async () => {
+  for (const [country, days] of [
+    ["TH", 10],
+    ["US", 730],
+    ["GB", 90],
+  ] as const) {
+    const t = convexTest(schema, modules);
+    const before = Date.now();
+    await t.mutation(m("prepare"), { ...initial, country });
+    const policy = await t.query(q("get"), scope);
+    expect(policy.holdDeadline).toBeGreaterThanOrEqual(
+      before + days * 86400000,
+    );
+    expect(policy.holdDeadline).toBeLessThan(
+      Date.now() + days * 86400000 + 1000,
+    );
+  }
+});
+it("returns bounded due policies and retains expired changing operations for reconciliation", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(m("prepare"), initial);
+  const p = await t.query(q("get"), scope);
+  const result = await t.query(q("due"), {
+    now: p.holdDeadline + 1,
+    paginationOpts: { numItems: 1, cursor: null },
+  });
+  expect(result.page).toHaveLength(1);
+  expect(result.page[0].status).toBe("changing");
+});
+it("accepts equivalent retries regardless of object property order", async () => {
+  const t = convexTest(schema, modules);
+  const op = await t.mutation(m("prepare"), initial);
+  expect(
+    await t.mutation(
+      m("prepare"),
+      Object.fromEntries(Object.entries(initial).reverse()),
+    ),
+  ).toEqual(op);
+});
+it("marks attempts durably and only cancels an unattempted provider change", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(m("prepare"), initial);
+  const args = {
+    ...scope,
+    operationKey: "enable-1",
+    observedSchedule: initial.observedSchedule,
+  };
+  expect((await t.mutation(m("cancelUnattempted"), args)).status).toBe(
+    "canceled",
+  );
+  expect(await t.query(q("get"), scope)).toMatchObject({
+    mode: "stripe_managed",
+    status: "ready",
+  });
+  await expect(
+    t.mutation(m("confirm"), {
+      ...scope,
+      operationKey: "enable-1",
+      observedSchedule: { interval: "manual" },
+    }),
+  ).rejects.toThrow(/canceled/);
+  await t.mutation(m("prepare"), {
+    ...initial,
+    operationKey: "second",
+    expectedRevision: 0,
+  });
+  await t.mutation(m("beginAttempt"), { ...scope, operationKey: "second" });
+  await expect(
+    t.mutation(m("cancelUnattempted"), { ...args, operationKey: "second" }),
+  ).rejects.toThrow(/attempt/);
+});
+it("anchors the hold deadline before provider reads and rejects future observations", async () => {
+  const t = convexTest(schema, modules);
+  const observedAt = Date.now() - 60000;
+  await t.mutation(m("prepare"), { ...initial, observedAt });
+  expect((await t.query(q("get"), scope)).holdDeadline).toBe(
+    observedAt + 730 * 86400000,
+  );
+  await expect(
+    t.mutation(m("prepare"), {
+      ...initial,
+      operationKey: "future",
+      observedAt: Date.now() + 60000,
+    }),
+  ).rejects.toThrow(/observation/);
+});