@fantastic.dev/better-stripe 0.24.0 → 0.25.0

package/src/component/payoutSnapshots/revisions.ts

@@ -0,0 +1,247 @@
+import type { Infer } from "convex/values";
+import type { riskKind } from "./schema.js";
+import type { Triggers } from "convex-helpers/server/triggers";
+import type { DataModel, Doc } from "../_generated/dataModel.js";
+import type { MutationCtx, QueryCtx } from "../_generated/server.js";
+import { addSummaryAmounts as add } from "../earnings/arithmetic.js";
+import {
+  transferFingerprint,
+  payoutClaimFingerprint,
+} from "../payoutRelease/helpers.js";
+export async function financialRevision(
+  ctx: QueryCtx | MutationCtx,
+  accountId: string,
+) {
+  const row = await ctx.db
+    .query("payoutFinancialRevisions")
+    .withIndex("by_account", (q) => q.eq("accountId", accountId))
+    .unique();
+  return { revision: row?.revision ?? 0, riskRevision: row?.riskRevision ?? 0 };
+}
+/** Stable fence: ordinary positive funding never writes this row. */
+export async function riskRevision(
+  ctx: QueryCtx | MutationCtx,
+  accountId: string,
+) {
+  const risk = await ctx.db
+    .query("payoutRiskRevisions")
+    .withIndex("by_account", (q) => q.eq("accountId", accountId))
+    .unique();
+  if (risk) return risk.riskRevision;
+  return (await financialRevision(ctx, accountId)).riskRevision;
+}
+async function bump(
+  ctx: MutationCtx,
+  accountId: string,
+  risk: boolean,
+  kind: Infer<typeof riskKind>,
+  key: string,
+  removed = false,
+) {
+  const row = await ctx.db
+    .query("payoutFinancialRevisions")
+    .withIndex("by_account", (q) => q.eq("accountId", accountId))
+    .unique();
+  const fence = await ctx.db
+    .query("payoutRiskRevisions")
+    .withIndex("by_account", (q) => q.eq("accountId", accountId))
+    .unique();
+  if (row && fence && row.riskRevision !== fence.riskRevision)
+    throw new Error("Financial risk revisions disagree.");
+  const next = {
+    revision: add(row?.revision ?? 0, 1),
+    riskRevision: add(
+      fence?.riskRevision ?? row?.riskRevision ?? 0,
+      risk ? 1 : 0,
+    ),
+  };
+  if (row) await ctx.db.patch("payoutFinancialRevisions", row._id, next);
+  else await ctx.db.insert("payoutFinancialRevisions", { accountId, ...next });
+  if (!fence)
+    await ctx.db.insert("payoutRiskRevisions", {
+      accountId,
+      riskRevision: next.riskRevision,
+    });
+  else if (risk)
+    await ctx.db.patch("payoutRiskRevisions", fence._id, {
+      riskRevision: next.riskRevision,
+    });
+  if (risk)
+    await ctx.db.insert("payoutRiskEvents", {
+      accountId,
+      riskRevision: next.riskRevision,
+      kind,
+      key,
+      ...(removed ? { removed: true } : {}),
+    });
+}
+function positiveOnly(
+  old: Doc<"transfers"> | null,
+  next: Doc<"transfers"> | null,
+) {
+  if (!next) return false;
+  if (!old)
+    return (
+      next.amount >= 0 &&
+      (next.reversedAmount ?? 0) === 0 &&
+      (next.reversalClaimedAmount ?? 0) === 0 &&
+      next.status !== "reversed"
+    );
+  const identity = (t: Doc<"transfers">) =>
+    JSON.stringify([
+      t.stripeTransferId,
+      t.destinationAccountId,
+      t.sourceChargeId,
+      t.currency,
+      t.role,
+      t.reinstatement ?? false,
+    ]);
+  return (
+    identity(old) === identity(next) &&
+    next.amount >= old.amount &&
+    (next.reversedAmount ?? 0) <= (old.reversedAmount ?? 0) &&
+    (next.reversalClaimedAmount ?? 0) <= (old.reversalClaimedAmount ?? 0) &&
+    next.status !== "reversed" &&
+    !(old.status === "paid" && next.status !== "paid")
+  );
+}
+function payoutFingerprint(p: Doc<"payouts">) {
+  return JSON.stringify([
+    p.stripePayoutId,
+    p.accountId,
+    p.amount,
+    p.currency,
+    p.status,
+    p.arrivalDate,
+    p.method,
+    p.failureCode,
+    p.failureMessage,
+  ]);
+}
+/** Funding, payout claims and allocations commit with their revision counters. */
+export function registerPayoutRevisions(triggers: Triggers<DataModel>) {
+  triggers.register("transfers", async (ctx, change) => {
+    if (
+      change.oldDoc &&
+      change.newDoc &&
+      transferFingerprint(change.oldDoc) === transferFingerprint(change.newDoc)
+    )
+      return;
+    const accounts = new Set([
+      change.oldDoc?.destinationAccountId,
+      change.newDoc?.destinationAccountId,
+    ]);
+    for (const account of accounts)
+      if (account)
+        await bump(
+          ctx,
+          account,
+          !positiveOnly(change.oldDoc, change.newDoc),
+          "transfer",
+          (change.newDoc ?? change.oldDoc)!.stripeTransferId,
+          change.newDoc === null,
+        );
+  });
+  triggers.register("payouts", async (ctx, change) => {
+    if (
+      change.oldDoc &&
+      change.newDoc &&
+      payoutFingerprint(change.oldDoc) === payoutFingerprint(change.newDoc)
+    )
+      return;
+    for (const account of new Set([
+      change.oldDoc?.accountId,
+      change.newDoc?.accountId,
+    ]))
+      if (account)
+        await bump(
+          ctx,
+          account,
+          true,
+          "provider_payout",
+          (change.newDoc ?? change.oldDoc)!.stripePayoutId,
+          change.newDoc === null,
+        );
+  });
+  triggers.register("payoutSourceAllocations", async (ctx, change) => {
+    const fp = (s: Doc<"payoutSourceAllocations">) =>
+      JSON.stringify([
+        s.accountId,
+        s.ownerKey,
+        s.stripeTransferId,
+        s.currency,
+        s.paidAmount,
+        s.reservedAmount,
+      ]);
+    if (
+      change.oldDoc &&
+      change.newDoc &&
+      fp(change.oldDoc) === fp(change.newDoc)
+    )
+      return;
+    for (const account of new Set([
+      change.oldDoc?.accountId,
+      change.newDoc?.accountId,
+    ]))
+      if (account)
+        await bump(
+          ctx,
+          account,
+          true,
+          "allocation",
+          (change.newDoc ?? change.oldDoc)!.stripeTransferId,
+          change.newDoc === null,
+        );
+  });
+  triggers.register("payoutReleaseClaims", async (ctx, change) => {
+    if (
+      change.oldDoc &&
+      change.newDoc &&
+      payoutClaimFingerprint(change.oldDoc) ===
+        payoutClaimFingerprint(change.newDoc)
+    )
+      return;
+    for (const account of new Set([
+      change.oldDoc?.accountId,
+      change.newDoc?.accountId,
+    ]))
+      if (account)
+        await bump(
+          ctx,
+          account,
+          true,
+          "claim",
+          (change.newDoc ?? change.oldDoc)!.operationKey,
+          change.newDoc === null,
+        );
+  });
+  triggers.register("payoutFeeBalances", async (ctx, change) => {
+    const fp = (s: Doc<"payoutFeeBalances">) =>
+      JSON.stringify([
+        s.accountId,
+        s.ownerKey,
+        s.currency,
+        s.amount,
+        s.revision,
+      ]);
+    if (
+      change.oldDoc &&
+      change.newDoc &&
+      fp(change.oldDoc) === fp(change.newDoc)
+    )
+      return;
+    for (const account of new Set([
+      change.oldDoc?.accountId,
+      change.newDoc?.accountId,
+    ]))
+      if (account)
+        await bump(
+          ctx,
+          account,
+          true,
+          "fee",
+          (change.newDoc ?? change.oldDoc)!.currency,
+          change.newDoc === null,
+        );
+  });
+}

package/src/component/payoutSnapshots/schema.ts

@@ -0,0 +1,125 @@
+import { defineTable } from "convex/server";
+import { v } from "convex/values";
+export const financialRevisionsTable = defineTable({
+  accountId: v.string(),
+  revision: v.number(),
+  riskRevision: v.number(),
+}).index("by_account", ["accountId"]);
+export const riskKind = v.union(
+  v.literal("transfer"),
+  v.literal("provider_payout"),
+  v.literal("allocation"),
+  v.literal("claim"),
+  v.literal("fee"),
+);
+export const riskEventsTable = defineTable({
+  accountId: v.string(),
+  riskRevision: v.number(),
+  kind: riskKind,
+  key: v.string(),
+  removed: v.optional(v.boolean()),
+}).index("by_account_revision", ["accountId", "riskRevision"]);
+export const collectionPhase = v.union(
+  v.literal("sources"),
+  v.literal("allocations"),
+  v.literal("fees"),
+  v.literal("claims"),
+  v.literal("repair"),
+  v.literal("check"),
+  v.literal("local_ready"),
+  v.literal("invalidated"),
+  v.literal("discarding"),
+);
+export const snapshotFields = {
+  readOnly: v.boolean(),
+  accountId: v.string(),
+  ownerKey: v.string(),
+  operationKey: v.string(),
+  expectedRevision: v.number(),
+  policyMode: v.optional(v.string()),
+  policyOperationKey: v.optional(v.string()),
+  phase: collectionPhase,
+  step: v.number(),
+  sourceFence: v.number(),
+  sourceCursor: v.optional(v.string()),
+  allocationCursor: v.optional(v.string()),
+  feeCursor: v.optional(v.string()),
+  claimCursor: v.optional(v.string()),
+  initialRevision: v.number(),
+  initialRiskRevision: v.number(),
+  riskRevision: v.number(),
+  observedRevision: v.number(),
+  sourceCount: v.number(),
+  allocationCount: v.number(),
+  claimCount: v.number(),
+  feeCount: v.number(),
+  deferredPositiveChanges: v.boolean(),
+  providerChanged: v.boolean(),
+  expiresAt: v.number(),
+  reason: v.optional(v.string()),
+};
+export const snapshotDoc = v.object({
+  ...snapshotFields,
+  _id: v.id("payoutSnapshots"),
+  _creationTime: v.number(),
+});
+export const snapshotsTable = defineTable(snapshotFields)
+  .index("by_operation", ["operationKey"])
+  .index("by_read_only", ["readOnly"])
+  .index("by_account_phase", ["accountId", "phase"]);
+export const snapshotSourcesTable = defineTable({
+  snapshotId: v.id("payoutSnapshots"),
+  stripeTransferId: v.string(),
+  ledgerFingerprint: v.string(),
+  sourceCreatedAt: v.number(),
+  currency: v.string(),
+  amount: v.number(),
+  status: v.string(),
+  role: v.optional(v.string()),
+  sourceChargeId: v.optional(v.string()),
+  reversedAmount: v.number(),
+  reversalClaimedAmount: v.number(),
+  reinstatement: v.boolean(),
+  allocationPresent: v.boolean(),
+  allocationCurrency: v.optional(v.string()),
+  paidAmount: v.number(),
+  reservedAmount: v.number(),
+  expectedPaid: v.number(),
+  expectedReserved: v.number(),
+  needsCheck: v.boolean(),
+})
+  .index("by_snapshot", ["snapshotId"])
+  .index("by_snapshot_transfer", ["snapshotId", "stripeTransferId"])
+  .index("by_snapshot_check", ["snapshotId", "needsCheck"]);
+export const snapshotClaimsTable = defineTable({
+  snapshotId: v.id("payoutSnapshots"),
+  operationKey: v.string(),
+  fingerprint: v.string(),
+  currency: v.string(),
+  amount: v.number(),
+  status: v.string(),
+  stripePayoutId: v.optional(v.string()),
+  historical: v.optional(v.boolean()),
+  providerFee: v.optional(v.number()),
+  allocations: v.array(
+    v.object({
+      stripeTransferId: v.string(),
+      amount: v.number(),
+      role: v.optional(v.string()),
+    }),
+  ),
+})
+  .index("by_snapshot", ["snapshotId"])
+  .index("by_snapshot_operation", ["snapshotId", "operationKey"]);
+export const snapshotFeesTable = defineTable({
+  snapshotId: v.id("payoutSnapshots"),
+  currency: v.string(),
+  amount: v.number(),
+  revision: v.number(),
+})
+  .index("by_snapshot", ["snapshotId"])
+  .index("by_snapshot_currency", ["snapshotId", "currency"]);
+export const riskRevisionsTable = defineTable({
+  accountId: v.string(),
+  riskRevision: v.number(),
+}).index("by_account", ["accountId"]);

package/src/component/payoutSnapshots/scope.ts

@@ -0,0 +1,7 @@
+import { v } from "convex/values";
+export { validateIdentity } from "../payoutRelease/helpers.js";
+export const identity = {
+  accountId: v.string(),
+  ownerKey: v.string(),
+  operationKey: v.string(),
+};

package/src/component/payoutWorker/helpers.ts

@@ -0,0 +1,30 @@
+import type { MutationCtx, QueryCtx } from "../_generated/server.js";
+import { validateScope } from "../payoutPolicy/helpers.js";
+export function validate(args: {
+  accountId: string;
+  ownerKey: string;
+  currency: string;
+}) {
+  validateScope(args);
+  if (!/^[a-z]{3}$/.test(args.currency))
+    throw new Error("Invalid worker currency.");
+}
+export async function readJob(
+  ctx: MutationCtx | QueryCtx,
+  args: { accountId: string; ownerKey: string; currency: string },
+) {
+  validate(args);
+  const job = await ctx.db
+    .query("payoutWorkerJobs")
+    .withIndex("by_account_currency", (q) =>
+      q.eq("accountId", args.accountId).eq("currency", args.currency),
+    )
+    .unique();
+  if (job && job.ownerKey !== args.ownerKey)
+    throw new Error("Payout worker owner does not match.");
+  return job;
+}
+export function pageSize(n: number) {
+  if (!Number.isInteger(n) || n < 1 || n > 25)
+    throw new Error("Invalid worker page size.");
+}

package/src/component/payoutWorker/mutations.ts

@@ -0,0 +1,181 @@
+import { v } from "convex/values";
+import { mutation } from "../_generated/server.js";
+import { readPolicy } from "../payoutPolicy/helpers.js";
+import { claimByKey, add } from "../payoutRelease/helpers.js";
+import { balance as recoveryBalance } from "../affiliateRecovery/accounting.js";
+import { readJob, validate } from "./helpers.js";
+import { scope, jobDoc } from "./schema.js";
+const held = v.object({
+  status: v.literal("held"),
+  reason: v.string(),
+  nextAttemptAt: v.optional(v.number()),
+});
+/** A worker lease serializes observations; only the payout claim reserves money. */
+export const begin = mutation({
+  args: { ...scope, cadenceMs: v.number() },
+  returns: v.union(
+    held,
+    v.object({
+      status: v.literal("run"),
+      job: jobDoc,
+      reconcileOnly: v.boolean(),
+    }),
+  ),
+  handler: async (ctx, args) => {
+    validate(args);
+    if (
+      !Number.isSafeInteger(args.cadenceMs) ||
+      args.cadenceMs < 60000 ||
+      args.cadenceMs > 86400000
+    )
+      throw new Error("Worker cadence must be between one minute and one day.");
+    const policy = await readPolicy(ctx, args);
+    let job = await readJob(ctx, args);
+    const now = Date.now();
+    if (job?.leaseUntil && job.leaseUntil > now)
+      return {
+        status: "held" as const,
+        reason: "worker_busy",
+        nextAttemptAt: job.leaseUntil,
+      };
+    if (job && job.nextAttemptAt > now)
+      return {
+        status: "held" as const,
+        reason: "not_due",
+        nextAttemptAt: job.nextAttemptAt,
+      };
+    const claim = job?.operationKey
+      ? await claimByKey(ctx, { ...args, operationKey: job.operationKey })
+      : null;
+    if (claim && claim.currency !== args.currency)
+      throw new Error("Worker payout currency changed.");
+    const unresolved =
+      claim?.status === "reserved" || claim?.status === "submitted";
+    if (
+      !unresolved &&
+      (policy?.mode !== "custom" ||
+        policy.status !== "ready" ||
+        !policy.holdDeadline ||
+        policy.holdDeadline <= now ||
+        !policy.thresholds.some((t) => t.currency === args.currency))
+    ) {
+      if (job)
+        await ctx.db.patch("payoutWorkerJobs", job._id, {
+          operationKey: undefined,
+          hasOperation: false,
+          leaseUntil: undefined,
+          lastReason: "policy_inactive",
+          nextAttemptAt: now + args.cadenceMs,
+        });
+      return { status: "held" as const, reason: "policy_inactive" };
+    }
+    if (!job) {
+      const id = await ctx.db.insert("payoutWorkerJobs", {
+        accountId: args.accountId,
+        ownerKey: args.ownerKey,
+        currency: args.currency,
+        generation: 0,
+        sequence: 0,
+        cadenceMs: args.cadenceMs,
+        nextAttemptAt: now,
+        hasOperation: false,
+      });
+      job = (await ctx.db.get("payoutWorkerJobs", id))!;
+    }
+    if (!unresolved) {
+      const recovery = await recoveryBalance(
+        ctx,
+        args.accountId,
+        args.currency,
+      );
+      if (
+        recovery &&
+        (recovery.outstandingDebt > 0 ||
+          recovery.reservedRecovery > 0 ||
+          recovery.reservedRestoration > 0 ||
+          recovery.activePayoutKey)
+      ) {
+        const nextAttemptAt = now + args.cadenceMs;
+        await ctx.db.patch("payoutWorkerJobs", job._id, {
+          operationKey: undefined,
+          hasOperation: false,
+          leaseUntil: undefined,
+          lastReason: "affiliate_recovery_pending",
+          nextAttemptAt,
+        });
+        return {
+          status: "held" as const,
+          reason: "affiliate_recovery_pending",
+          nextAttemptAt,
+        };
+      }
+    }
+    // A lost response with no claim is safe to resume at the same operation ID.
+    // A retained attempted claim always reconciles, including after opt-out.
+    const retain = job.operationKey && (!claim || unresolved);
+    const sequence = retain ? job.sequence : add(job.sequence, 1);
+    const operationKey = retain
+      ? job.operationKey!
+      : `bs:auto:${job._id}:${sequence}`;
+    await ctx.db.patch("payoutWorkerJobs", job._id, {
+      generation: add(job.generation, 1),
+      sequence,
+      operationKey,
+      hasOperation: true,
+      cadenceMs: args.cadenceMs,
+      leaseUntil: now + 600000,
+      lastAttemptAt: now,
+    });
+    return {
+      status: "run" as const,
+      job: (await ctx.db.get("payoutWorkerJobs", job._id))!,
+      reconcileOnly: unresolved && claim.attemptedAt !== undefined,
+    };
+  },
+});
+export const finish = mutation({
+  args: {
+    ...scope,
+    generation: v.number(),
+    operationKey: v.string(),
+    reason: v.string(),
+  },
+  returns: jobDoc,
+  handler: async (ctx, args) => {
+    const job = await readJob(ctx, args);
+    if (
+      job?.generation === args.generation &&
+      job.completedGeneration === args.generation
+    ) {
+      if (
+        job.completedOperationKey !== args.operationKey ||
+        job.lastReason !== args.reason
+      )
+        throw new Error("Payout worker result cannot be changed.");
+      return job;
+    }
+    if (
+      !job ||
+      job.generation !== args.generation ||
+      job.operationKey !== args.operationKey
+    )
+      throw new Error("Payout worker generation changed.");
+    if (!args.reason || args.reason.length > 120 || /[\r\n]/.test(args.reason))
+      throw new Error("Invalid worker result reason.");
+    const claim = await claimByKey(ctx, args);
+    if (claim && claim.currency !== job.currency)
+      throw new Error("Worker payout currency changed.");
+    const retain =
+      claim?.status === "reserved" || claim?.status === "submitted";
+    await ctx.db.patch("payoutWorkerJobs", job._id, {
+      operationKey: retain ? job.operationKey : undefined,
+      hasOperation: retain,
+      leaseUntil: undefined,
+      nextAttemptAt: Date.now() + job.cadenceMs,
+      lastReason: args.reason,
+      completedGeneration: args.generation,
+      completedOperationKey: args.operationKey,
+    });
+    return (await ctx.db.get("payoutWorkerJobs", job._id))!;
+  },
+});

package/src/component/payoutWorker/queries.ts

@@ -0,0 +1,64 @@
+import { paginationOptsValidator } from "convex/server";
+import { v } from "convex/values";
+import { query } from "../_generated/server.js";
+import { policyDoc } from "../payoutPolicy/schema.js";
+import { readJob, pageSize } from "./helpers.js";
+import { jobDoc, scope } from "./schema.js";
+export const get = query({
+  args: scope,
+  returns: v.union(jobDoc, v.null()),
+  handler: readJob,
+});
+export const policies = query({
+  args: { paginationOpts: paginationOptsValidator },
+  returns: v.object({
+    page: v.array(policyDoc),
+    continueCursor: v.string(),
+    isDone: v.boolean(),
+  }),
+  handler: async (ctx, args) => {
+    pageSize(args.paginationOpts.numItems);
+    const p = await ctx.db
+      .query("payoutPolicies")
+      .withIndex("by_mode_status", (q) =>
+        q.eq("mode", "custom").eq("status", "ready"),
+      )
+      .paginate(args.paginationOpts);
+    return { page: p.page, continueCursor: p.continueCursor, isDone: p.isDone };
+  },
+});
+export const changing = query({
+  args: { paginationOpts: paginationOptsValidator },
+  returns: v.object({
+    page: v.array(policyDoc),
+    continueCursor: v.string(),
+    isDone: v.boolean(),
+  }),
+  handler: async (ctx, args) => {
+    pageSize(args.paginationOpts.numItems);
+    const p = await ctx.db
+      .query("payoutPolicies")
+      .withIndex("by_status", (q) => q.eq("status", "changing"))
+      .paginate(args.paginationOpts);
+    return { page: p.page, continueCursor: p.continueCursor, isDone: p.isDone };
+  },
+});
+/** Includes attempted jobs after opt-out. It is not restricted to custom policies. */
+export const recovering = query({
+  args: { paginationOpts: paginationOptsValidator },
+  returns: v.object({
+    page: v.array(jobDoc),
+    continueCursor: v.string(),
+    isDone: v.boolean(),
+  }),
+  handler: async (ctx, args) => {
+    pageSize(args.paginationOpts.numItems);
+    const p = await ctx.db
+      .query("payoutWorkerJobs")
+      .withIndex("by_operation_pending", (q) =>
+        q.eq("hasOperation", true).lte("nextAttemptAt", Date.now()),
+      )
+      .paginate(args.paginationOpts);
+    return { page: p.page, continueCursor: p.continueCursor, isDone: p.isDone };
+  },
+});

package/src/component/payoutWorker/schema.ts

@@ -0,0 +1,26 @@
+import { defineTable } from "convex/server";
+import { v } from "convex/values";
+import { scopeFields } from "../payoutPolicy/schema.js";
+export const scope = { ...scopeFields, currency: v.string() };
+export const fields = {
+  ...scope,
+  generation: v.number(),
+  sequence: v.number(),
+  cadenceMs: v.number(),
+  nextAttemptAt: v.number(),
+  leaseUntil: v.optional(v.number()),
+  operationKey: v.optional(v.string()),
+  hasOperation: v.boolean(),
+  lastReason: v.optional(v.string()),
+  lastAttemptAt: v.optional(v.number()),
+  completedGeneration: v.optional(v.number()),
+  completedOperationKey: v.optional(v.string()),
+};
+export const jobDoc = v.object({
+  ...fields,
+  _id: v.id("payoutWorkerJobs"),
+  _creationTime: v.number(),
+});
+export const jobsTable = defineTable(fields)
+  .index("by_account_currency", ["accountId", "currency"])
+  .index("by_operation_pending", ["hasOperation", "nextAttemptAt"]);

package/src/component/public.test.ts

@@ -428,7 +428,7 @@ describe("core — clearAllTables", () => {
       accountId: "acct_clear",
       amount: 1000,
       currency: "usd",
-      status: "pending",
+      status: "paid",
     });
 
     await t.mutation(api.connect.mutations.upsertRefund, {
@@ -471,7 +471,7 @@ describe("core — clearAllTables", () => {
     const result = await t.mutation(api.core.mutations.clearAllTables, {});
     const tableCount = Object.keys(schema.tables).length;
 
-    expect(result.cleared).toBe(15);
+    expect(result.cleared).toBe(20);
     expect(result.tables).toHaveLength(tableCount);
 
     for (const tableName of Object.keys(schema.tables) as TableNames[]) {