@fantastic.dev/better-stripe 0.23.1 → 0.23.2

package/src/client/index.ts

@@ -1,3 +1,8 @@
+import * as payoutSyncImpl from "./connect/payoutSync.js";
+export type {
+  PayoutSyncOptions,
+  PayoutSyncResult,
+} from "./connect/payoutSync.js";
 import { PayoutPolicyClient } from "./payoutPolicy.js";
 export * from "./payoutPolicy.js";
 import type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js";
@@ -78,10 +83,7 @@ import { v } from "convex/values";
 import Stripe from "stripe";
 
 import type { ComponentApi } from "../component/_generated/component.js";
-import type {
-  DisputeStatus,
-  PayoutStatus,
-} from "../component/connect/validators.js";
+import type { DisputeStatus } from "../component/connect/validators.js";
 import type { SplitRecipient } from "../component/lib/fees.js";
 import * as checkoutImpl from "./billing/checkout.js";
 import * as invoicesImpl from "./billing/invoices.js";
@@ -1300,15 +1302,16 @@ export class BetterStripe extends ReadContractClient {
     return payoutsImpl.getAccountBalance(this.stripe(), opts);
   }
 
-  async getPayout(ctx: RunCtx, opts: { payoutId: string }) {
-    return payoutsImpl.getPayout(this.component, ctx, opts);
-  }
-
-  async listPayouts(
+  async syncPayoutFromStripe(
     ctx: RunCtx,
-    opts?: { stripeAccountId?: string; status?: PayoutStatus; limit?: number },
+    opts: payoutSyncImpl.PayoutSyncOptions,
   ) {
-    return payoutsImpl.listPayouts(this.component, ctx, opts);
+    return payoutSyncImpl.syncPayoutFromStripe(
+      this.stripe(),
+      this.component,
+      ctx,
+      opts,
+    );
   }
 
   // REFUND METHODS

package/src/client/readContracts.ts

@@ -1,3 +1,4 @@
+import * as payoutsImpl from "./connect/payouts.js";
 import type { ComponentApi } from "../component/_generated/component.js";
 import type { PaginationOptions, PaginationResult } from "convex/server";
 import type { Component, RunCtx } from "./helpers.js";
@@ -51,6 +52,17 @@ export class ReadContractClient {
     );
   }
 
+  async getPayout(ctx: RunCtx, opts: { payoutId: string }) {
+    return payoutsImpl.getPayout(this.component, ctx, opts);
+  }
+
+  async listPayouts(
+    ctx: RunCtx,
+    opts?: { stripeAccountId?: string; status?: PayoutStatus; limit?: number },
+  ) {
+    return payoutsImpl.listPayouts(this.component, ctx, opts);
+  }
+
   async getAccountEarningsByCurrency(
     ctx: RunCtx,
     opts: { destinationAccountId: string; previewLimit?: number },

package/src/component/_generated/api.ts

@@ -12,6 +12,7 @@ import type * as billing_mutations from "../billing/mutations.js";
 import type * as billing_queries from "../billing/queries.js";
 import type * as billing_validators from "../billing/validators.js";
 import type * as connect_mutations from "../connect/mutations.js";
+import type * as connect_payoutWrites from "../connect/payoutWrites.js";
 import type * as connect_queries from "../connect/queries.js";
 import type * as connect_validators from "../connect/validators.js";
 import type * as core_mutations from "../core/mutations.js";
@@ -45,6 +46,10 @@ import type * as payoutRelease_helpers from "../payoutRelease/helpers.js";
 import type * as payoutRelease_mutations from "../payoutRelease/mutations.js";
 import type * as payoutRelease_observation from "../payoutRelease/observation.js";
 import type * as payoutRelease_queries from "../payoutRelease/queries.js";
+import type * as payoutSync_helpers from "../payoutSync/helpers.js";
+import type * as payoutSync_mutations from "../payoutSync/mutations.js";
+import type * as payoutSync_queries from "../payoutSync/queries.js";
+import type * as payoutSync_validators from "../payoutSync/validators.js";
 import type * as products_mutations from "../products/mutations.js";
 import type * as products_queries from "../products/queries.js";
 import type * as products_validators from "../products/validators.js";
@@ -67,6 +72,7 @@ const fullApi: ApiFromModules<{
   "billing/queries": typeof billing_queries;
   "billing/validators": typeof billing_validators;
   "connect/mutations": typeof connect_mutations;
+  "connect/payoutWrites": typeof connect_payoutWrites;
   "connect/queries": typeof connect_queries;
   "connect/validators": typeof connect_validators;
   "core/mutations": typeof core_mutations;
@@ -100,6 +106,10 @@ const fullApi: ApiFromModules<{
   "payoutRelease/mutations": typeof payoutRelease_mutations;
   "payoutRelease/observation": typeof payoutRelease_observation;
   "payoutRelease/queries": typeof payoutRelease_queries;
+  "payoutSync/helpers": typeof payoutSync_helpers;
+  "payoutSync/mutations": typeof payoutSync_mutations;
+  "payoutSync/queries": typeof payoutSync_queries;
+  "payoutSync/validators": typeof payoutSync_validators;
   "products/mutations": typeof products_mutations;
   "products/queries": typeof products_queries;
   "products/validators": typeof products_validators;

package/src/component/_generated/component.ts

@@ -3155,6 +3155,88 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         >;
       };
     };
+    payoutSync: {
+      mutations: {
+        begin: FunctionReference<
+          "mutation",
+          "internal",
+          { accountId: string; stripePayoutId: string },
+          number,
+          Name
+        >;
+        finish: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            generation: number;
+            payout: {
+              accountId: string;
+              amount: number;
+              arrivalDate?: string;
+              currency: string;
+              failureCode?: string;
+              failureMessage?: string;
+              metadata?: Record<string, string>;
+              method?: string;
+              status: "pending" | "paid" | "failed" | "canceled" | "in_transit";
+              stripePayoutId: string;
+            };
+            stripePayoutId: string;
+          },
+          | {
+              changed: boolean;
+              generation: number;
+              payout: {
+                _creationTime: number;
+                _id: string;
+                accountId: string;
+                amount: number;
+                arrivalDate?: string;
+                currency: string;
+                failureCode?: string;
+                failureMessage?: string;
+                metadata?: any;
+                method?: string;
+                status:
+                  "pending" | "paid" | "failed" | "canceled" | "in_transit";
+                stripePayoutId: string;
+                totalsRecorded?: true;
+              };
+              status: "accepted";
+            }
+          | { generation: number; status: "superseded" },
+          Name
+        >;
+        markUnknown: FunctionReference<
+          "mutation",
+          "internal",
+          { accountId: string; generation: number; stripePayoutId: string },
+          null,
+          Name
+        >;
+      };
+      queries: {
+        get: FunctionReference<
+          "query",
+          "internal",
+          { accountId: string; stripePayoutId: string },
+          {
+            _creationTime: number;
+            _id: string;
+            acceptedAt?: number;
+            acceptedFingerprint?: string;
+            acceptedGeneration?: number;
+            accountId: string;
+            generation: number;
+            startedAt: number;
+            status: "pending" | "accepted" | "unknown";
+            stripePayoutId: string;
+          } | null,
+          Name
+        >;
+      };
+    };
     products: {
       mutations: {
         upsertPrice: FunctionReference<

package/src/component/connect/mutations.ts

@@ -1,3 +1,4 @@
+import { writePayout } from "./payoutWrites.js";
 import { v } from "convex/values";
 
 import type { Doc, Id } from "../_generated/dataModel";
@@ -8,7 +9,7 @@ import { paymentSeller } from "../lib/paymentSeller";
 import {
   disputeFields,
   paymentStatusValidator,
-  payoutStatusValidator,
+  payoutFields,
   refundFields,
   transferFields,
 } from "./validators";
@@ -113,37 +114,10 @@ export const upsertPayment = mutation({
 // Payout mutations
 
 export const upsertPayout = mutation({
-  args: {
-    stripePayoutId: v.string(),
-    accountId: v.string(),
-    amount: v.number(),
-    currency: v.string(),
-    status: payoutStatusValidator,
-    arrivalDate: v.optional(v.string()),
-    method: v.optional(v.string()),
-    failureCode: v.optional(v.string()),
-    failureMessage: v.optional(v.string()),
-    metadata: v.optional(v.any()),
-  },
+  args: payoutFields,
   returns: v.null(),
   handler: async (ctx, args) => {
-    const existing = await ctx.db
-      .query("payouts")
-      .withIndex("by_stripe_payout_id", (q) =>
-        q.eq("stripePayoutId", args.stripePayoutId),
-      )
-      .first();
-
-    if (existing) {
-      await ctx.db.patch("payouts", existing._id, {
-        ...args,
-        failureCode: args.failureCode,
-        failureMessage: args.failureMessage,
-      });
-    } else {
-      await ctx.db.insert("payouts", args);
-    }
-
+    await writePayout(ctx, args);
     return null;
   },
 });

package/src/component/connect/payoutWrites.ts

@@ -0,0 +1,25 @@
+import type { MutationCtx } from "../_generated/server.js";
+import type { Doc } from "../_generated/dataModel.js";
+type PayoutData = Omit<
+  Doc<"payouts">,
+  "_id" | "_creationTime" | "totalsRecorded"
+>;
+/** The caller's triggered DB maintains the existing exact currency summaries. */
+export async function writePayout(ctx: MutationCtx, args: PayoutData) {
+  const existing = await ctx.db
+    .query("payouts")
+    .withIndex("by_stripe_payout_id", (q) =>
+      q.eq("stripePayoutId", args.stripePayoutId),
+    )
+    .first();
+  const id = existing?._id ?? (await ctx.db.insert("payouts", args));
+  if (existing)
+    await ctx.db.patch("payouts", id, {
+      ...args,
+      failureCode: args.failureCode,
+      failureMessage: args.failureMessage,
+    });
+  const saved = await ctx.db.get("payouts", id);
+  if (!saved) throw new Error("Payout was not found after synchronization.");
+  return saved;
+}

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

@@ -0,0 +1,117 @@
+// @vitest-environment edge-runtime
+import { convexTest } from "convex-test";
+import { makeFunctionReference } from "convex/server";
+import { expect, it, vi } from "vitest";
+import schema from "./schema.js";
+const modules = import.meta.glob("./**/*.*s");
+const scope = { stripePayoutId: "po_one", accountId: "acct_owner" };
+const payout = {
+  ...scope,
+  amount: 500,
+  currency: "jpy",
+  status: "paid" as const,
+  arrivalDate: "1970-01-01T00:03:20.000Z",
+  method: "standard",
+  metadata: {},
+};
+const mutation = (name: string) =>
+  makeFunctionReference<"mutation">(`payoutSync/mutations:${name}`);
+async function setup() {
+  const t = convexTest(schema, modules);
+  const generation = await t.mutation(mutation("begin"), scope);
+  return { t, args: { ...scope, generation, payout } };
+}
+it("replays a committed generation without changing its acceptance time or financial row", async () => {
+  vi.useFakeTimers();
+  try {
+    vi.setSystemTime(1000);
+    const { t, args } = await setup();
+    const first = await t.mutation(mutation("finish"), args);
+    const oldRow = await t.run((ctx) => ctx.db.query("payouts").unique());
+    vi.setSystemTime(2000);
+    expect(await t.mutation(mutation("finish"), args)).toMatchObject({
+      ...first,
+      changed: false,
+    });
+    expect(
+      await t.run((ctx) => ctx.db.query("payoutSyncClaims").unique()),
+    ).toMatchObject({ acceptedAt: 1000 });
+    expect(await t.run((ctx) => ctx.db.query("payouts").unique())).toEqual(
+      oldRow,
+    );
+  } finally {
+    vi.useRealTimers();
+  }
+});
+it("rejects replacing the accepted snapshot under the same generation", async () => {
+  const { t, args } = await setup();
+  await t.mutation(mutation("finish"), args);
+  await expect(
+    t.mutation(mutation("finish"), {
+      ...args,
+      payout: { ...payout, status: "pending" },
+    }),
+  ).rejects.toThrow("An accepted payout observation cannot be replaced.");
+  expect(await t.run((ctx) => ctx.db.query("payouts").unique())).toMatchObject({
+    status: "paid",
+  });
+});
+it("ignores stale completion and stale unknown markers before any financial write", async () => {
+  const { t, args } = await setup();
+  const generation = await t.mutation(mutation("begin"), scope);
+  expect(await t.mutation(mutation("finish"), args)).toMatchObject({
+    status: "superseded",
+  });
+  await t.mutation(mutation("markUnknown"), {
+    ...scope,
+    generation: args.generation,
+  });
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSyncClaims").unique()),
+  ).toMatchObject({ status: "pending", generation });
+  expect(await t.run((ctx) => ctx.db.query("payouts").collect())).toEqual([]);
+  await t.mutation(mutation("finish"), { ...args, generation });
+  await t.mutation(mutation("markUnknown"), { ...scope, generation });
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSyncClaims").unique()),
+  ).toMatchObject({ status: "accepted" });
+});
+it.each([{ stripePayoutId: "po_foreign" }, { accountId: "acct_foreign" }])(
+  "rejects snapshot identity mismatch %j atomically",
+  async (patch) => {
+    const { t, args } = await setup();
+    await expect(
+      t.mutation(mutation("finish"), {
+        ...args,
+        payout: { ...payout, ...patch },
+      }),
+    ).rejects.toThrow(
+      "Payout synchronization snapshot identity does not match.",
+    );
+    expect(await t.run((ctx) => ctx.db.query("payouts").collect())).toEqual([]);
+    expect(
+      await t.run((ctx) => ctx.db.query("currencyTotals").collect()),
+    ).toEqual([]);
+  },
+);
+it("rejects a foreign claim lookup and generation overflow without changing the claim", async () => {
+  const { t } = await setup();
+  await expect(
+    t.query(makeFunctionReference<"query">("payoutSync/queries:get"), {
+      ...scope,
+      accountId: "acct_foreign",
+    }),
+  ).rejects.toThrow("Payout synchronization account does not match.");
+  await t.run(async (ctx) => {
+    const row = await ctx.db.query("payoutSyncClaims").unique();
+    await ctx.db.patch("payoutSyncClaims", row!._id, {
+      generation: Number.MAX_SAFE_INTEGER,
+    });
+  });
+  await expect(t.mutation(mutation("begin"), scope)).rejects.toThrow(
+    "Payout synchronization generation exhausted.",
+  );
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSyncClaims").unique()),
+  ).toMatchObject({ generation: Number.MAX_SAFE_INTEGER });
+});

package/src/component/payoutSync/helpers.ts

@@ -0,0 +1,86 @@
+import type { Infer } from "convex/values";
+import type { MutationCtx, QueryCtx } from "../_generated/server.js";
+import type { Doc } from "../_generated/dataModel.js";
+import { generateIdempotencyKey } from "../lib/idempotency.js";
+import type { snapshot } from "./validators.js";
+export function validateIdentity(args: {
+  stripePayoutId: string;
+  accountId: string;
+}) {
+  if (
+    !/^po_[A-Za-z0-9_]+$/.test(args.stripePayoutId) ||
+    args.stripePayoutId.length > 255 ||
+    (args.accountId !== "platform" &&
+      !/^acct_[A-Za-z0-9_]+$/.test(args.accountId)) ||
+    args.accountId.length > 255
+  )
+    throw new Error("Invalid payout synchronization identity.");
+}
+export async function claimByPayout(
+  ctx: QueryCtx | MutationCtx,
+  args: { stripePayoutId: string; accountId: string },
+) {
+  validateIdentity(args);
+  const claim = await ctx.db
+    .query("payoutSyncClaims")
+    .withIndex("by_stripe_payout_id", (q) =>
+      q.eq("stripePayoutId", args.stripePayoutId),
+    )
+    .unique();
+  if (claim && claim.accountId !== args.accountId)
+    throw new Error("Payout synchronization account does not match.");
+  return claim;
+}
+export async function payoutById(
+  ctx: QueryCtx | MutationCtx,
+  args: { stripePayoutId: string; accountId: string },
+) {
+  const payout = await ctx.db
+    .query("payouts")
+    .withIndex("by_stripe_payout_id", (q) =>
+      q.eq("stripePayoutId", args.stripePayoutId),
+    )
+    .unique();
+  if (payout && payout.accountId !== args.accountId)
+    throw new Error("Existing payout account does not match.");
+  return payout;
+}
+export function validateSnapshot(p: Infer<typeof snapshot>) {
+  validateIdentity(p);
+  if (
+    !Number.isSafeInteger(p.amount) ||
+    p.amount <= 0 ||
+    !/^[a-z]{3}$/.test(p.currency) ||
+    (p.method !== undefined && !["standard", "instant"].includes(p.method))
+  )
+    throw new Error("Invalid payout synchronization money or method.");
+  if (
+    p.arrivalDate !== undefined &&
+    (!Number.isFinite(Date.parse(p.arrivalDate)) ||
+      new Date(p.arrivalDate).toISOString() !== p.arrivalDate)
+  )
+    throw new Error("Invalid payout arrival date.");
+  if (
+    (p.failureCode !== undefined && p.failureCode.length > 255) ||
+    (p.failureMessage !== undefined && p.failureMessage.length > 4096)
+  )
+    throw new Error("Invalid payout failure detail.");
+}
+export async function fingerprint(p: Infer<typeof snapshot> | Doc<"payouts">) {
+  return generateIdempotencyKey("payout-sync", {
+    snapshot: [
+      p.stripePayoutId,
+      p.accountId,
+      p.amount,
+      p.currency,
+      p.status,
+      p.arrivalDate,
+      p.method,
+      p.failureCode,
+      p.failureMessage,
+      Object.entries(p.metadata ?? {}).sort(([a], [b]) =>
+        a < b ? -1 : a > b ? 1 : 0,
+      ),
+    ],
+  });
+}

package/src/component/payoutSync/mutations.ts

@@ -0,0 +1,102 @@
+import { v } from "convex/values";
+import { mutation } from "../earnings/triggers.js";
+import { writePayout } from "../connect/payoutWrites.js";
+import {
+  claimByPayout,
+  payoutById,
+  validateSnapshot,
+  fingerprint,
+} from "./helpers.js";
+import { identity, prepared, result } from "./validators.js";
+export const begin = mutation({
+  args: identity,
+  returns: v.number(),
+  handler: async (ctx, args) => {
+    const claim = await claimByPayout(ctx, args);
+    await payoutById(ctx, args);
+    const generation = (claim?.generation ?? 0) + 1;
+    if (!Number.isSafeInteger(generation))
+      throw new Error("Payout synchronization generation exhausted.");
+    if (claim)
+      await ctx.db.patch("payoutSyncClaims", claim._id, {
+        generation,
+        status: "pending",
+        startedAt: Date.now(),
+      });
+    else
+      await ctx.db.insert("payoutSyncClaims", {
+        ...args,
+        generation,
+        status: "pending",
+        startedAt: Date.now(),
+      });
+    return generation;
+  },
+});
+export const finish = mutation({
+  args: prepared,
+  returns: result,
+  handler: async (ctx, args) => {
+    const claim = await claimByPayout(ctx, args);
+    if (!claim) throw new Error("Payout synchronization claim is missing.");
+    if (claim.generation !== args.generation)
+      return { status: "superseded" as const, generation: args.generation };
+    validateSnapshot(args.payout);
+    if (
+      args.payout.accountId !== args.accountId ||
+      args.payout.stripePayoutId !== args.stripePayoutId
+    )
+      throw new Error(
+        "Payout synchronization snapshot identity does not match.",
+      );
+    const existing = await payoutById(ctx, args);
+    if (
+      existing &&
+      (existing.amount !== args.payout.amount ||
+        existing.currency !== args.payout.currency)
+    )
+      throw new Error("Existing payout original money does not match.");
+    const nextFingerprint = await fingerprint(args.payout);
+    if (
+      claim.status === "accepted" &&
+      claim.acceptedFingerprint !== nextFingerprint
+    )
+      throw new Error("An accepted payout observation cannot be replaced.");
+    const changed =
+      !existing || (await fingerprint(existing)) !== nextFingerprint;
+    if (claim.status === "accepted" && changed)
+      throw new Error(
+        "Accepted payout state changed outside its synchronization.",
+      );
+    if (claim.status === "accepted")
+      return {
+        status: "accepted" as const,
+        generation: args.generation,
+        changed: false,
+        payout: existing!,
+      };
+    const payout = changed ? await writePayout(ctx, args.payout) : existing!;
+    await ctx.db.patch("payoutSyncClaims", claim._id, {
+      status: "accepted",
+      acceptedGeneration: args.generation,
+      acceptedAt: Date.now(),
+      acceptedFingerprint: nextFingerprint,
+    });
+    return {
+      status: "accepted" as const,
+      generation: args.generation,
+      changed,
+      payout,
+    };
+  },
+});
+export const markUnknown = mutation({
+  args: { ...identity, generation: v.number() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const claim = await claimByPayout(ctx, args);
+    if (claim?.generation === args.generation && claim.status === "pending")
+      await ctx.db.patch("payoutSyncClaims", claim._id, { status: "unknown" });
+    return null;
+  },
+});

package/src/component/payoutSync/queries.ts

@@ -0,0 +1,10 @@
+import { v } from "convex/values";
+import { query } from "../_generated/server.js";
+import { claimByPayout } from "./helpers.js";
+import { claimDoc } from "./schema.js";
+import { identity } from "./validators.js";
+export const get = query({
+  args: identity,
+  returns: v.union(claimDoc, v.null()),
+  handler: claimByPayout,
+});

package/src/component/payoutSync/schema.ts

@@ -0,0 +1,25 @@
+import { defineTable } from "convex/server";
+import { v } from "convex/values";
+import { identity } from "./validators.js";
+const fields = {
+  ...identity,
+  generation: v.number(),
+  status: v.union(
+    v.literal("pending"),
+    v.literal("accepted"),
+    v.literal("unknown"),
+  ),
+  startedAt: v.number(),
+  acceptedGeneration: v.optional(v.number()),
+  acceptedAt: v.optional(v.number()),
+  acceptedFingerprint: v.optional(v.string()),
+};
+export const claimDoc = v.object({
+  ...fields,
+  _id: v.id("payoutSyncClaims"),
+  _creationTime: v.number(),
+});
+/** Operational generations only. Financial facts remain in the existing payouts table. */
+export const claimsTable = defineTable(fields).index("by_stripe_payout_id", [
+  "stripePayoutId",
+]);

package/src/component/payoutSync/validators.ts

@@ -0,0 +1,21 @@
+import { v } from "convex/values";
+import { payoutFields, payoutDocValidator } from "../connect/validators.js";
+export const identity = { stripePayoutId: v.string(), accountId: v.string() };
+export const snapshot = v.object({
+  ...payoutFields,
+  metadata: v.optional(v.record(v.string(), v.string())),
+});
+export const prepared = {
+  ...identity,
+  generation: v.number(),
+  payout: snapshot,
+};
+export const result = v.union(
+  v.object({
+    status: v.literal("accepted"),
+    generation: v.number(),
+    changed: v.boolean(),
+    payout: payoutDocValidator,
+  }),
+  v.object({ status: v.literal("superseded"), generation: v.number() }),
+);

package/src/component/schema.ts

@@ -1,3 +1,4 @@
+import { claimsTable as payoutSyncClaimsTable } from "./payoutSync/schema.js";
 import {
   feeBalancesTable as payoutFeeBalancesTable,
   claimsTable as payoutReleaseClaimsTable,
@@ -37,6 +38,7 @@ import { pricesTable, productsTable } from "./products/schema";
 import { webhookEventsTable } from "./webhooks/schema";
 
 export default defineSchema({
+  payoutSyncClaims: payoutSyncClaimsTable,
   payoutFeeBalances: payoutFeeBalancesTable,
   payoutReleaseClaims: payoutReleaseClaimsTable,
   payoutSourceAllocations: payoutSourceAllocationsTable,