@fantastic.dev/better-stripe 0.23.1 → 0.23.2

package/dist/component/schema.d.ts

@@ -1,4 +1,25 @@
 declare const _default: import("convex/server").SchemaDefinition<{
+    payoutSyncClaims: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        acceptedAt?: number | undefined;
+        acceptedFingerprint?: string | undefined;
+        acceptedGeneration?: number | undefined;
+        accountId: string;
+        generation: number;
+        startedAt: number;
+        status: "accepted" | "pending" | "unknown";
+        stripePayoutId: string;
+    }, {
+        stripePayoutId: import("convex/values").VString<string, "required">;
+        accountId: import("convex/values").VString<string, "required">;
+        generation: import("convex/values").VFloat64<number, "required">;
+        status: import("convex/values").VUnion<"accepted" | "pending" | "unknown", [import("convex/values").VLiteral<"pending", "required">, import("convex/values").VLiteral<"accepted", "required">, import("convex/values").VLiteral<"unknown", "required">], "required", never>;
+        startedAt: import("convex/values").VFloat64<number, "required">;
+        acceptedGeneration: import("convex/values").VFloat64<number | undefined, "optional">;
+        acceptedAt: import("convex/values").VFloat64<number | undefined, "optional">;
+        acceptedFingerprint: import("convex/values").VString<string | undefined, "optional">;
+    }, "required", "acceptedAt" | "acceptedFingerprint" | "acceptedGeneration" | "accountId" | "generation" | "startedAt" | "status" | "stripePayoutId">, {
+        by_stripe_payout_id: ["stripePayoutId", "_creationTime"];
+    }, {}, {}>;
     payoutFeeBalances: import("convex/server").TableDefinition<import("convex/values").VObject<{
         accountId: string;
         amount: number;

package/dist/component/schema.js

@@ -1,3 +1,4 @@
+import { claimsTable as payoutSyncClaimsTable } from "./payoutSync/schema.js";
 import { feeBalancesTable as payoutFeeBalancesTable, claimsTable as payoutReleaseClaimsTable, sourcesTable as payoutSourceAllocationsTable, } from "./payoutRelease/schema.js";
 import { policiesTable, operationsTable } from "./payoutPolicy/schema.js";
 import { currencyTotalsTable } from "./earnings/schema.js";
@@ -10,6 +11,7 @@ import { accountsTable } from "./core/schema";
 import { pricesTable, productsTable } from "./products/schema";
 import { webhookEventsTable } from "./webhooks/schema";
 export default defineSchema({
+    payoutSyncClaims: payoutSyncClaimsTable,
     payoutFeeBalances: payoutFeeBalancesTable,
     payoutReleaseClaims: payoutReleaseClaimsTable,
     payoutSourceAllocations: payoutSourceAllocationsTable,

package/dist/component/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,IAAI,sBAAsB,EAC1C,WAAW,IAAI,wBAAwB,EACvC,YAAY,IAAI,4BAA4B,GAC7C,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EACL,WAAW,EACX,aAAa,EACb,WAAW,EACX,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,aAAa,EACb,YAAY,EACZ,sBAAsB,EACtB,YAAY,EACZ,wBAAwB,EACxB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,eAAe,YAAY,CAAC;IAC1B,iBAAiB,EAAE,sBAAsB;IACzC,mBAAmB,EAAE,wBAAwB;IAC7C,uBAAuB,EAAE,4BAA4B;IACrD,cAAc,EAAE,aAAa;IAC7B,sBAAsB,EAAE,eAAe;IACvC,cAAc,EAAE,mBAAmB;IACnC,cAAc,EAAE,WAAW;IAC3B,gBAAgB,EAAE,aAAa;IAC/B,cAAc,EAAE,WAAW;IAC3B,oBAAoB,EAAE,iBAAiB;IACvC,qBAAqB,EAAE,gBAAgB;IACvC,eAAe,EAAE,oBAAoB;IACrC,mBAAmB,EAAE,wBAAwB;IAC7C,OAAO;IACP,QAAQ,EAAE,aAAa;IAEvB,WAAW;IACX,QAAQ,EAAE,aAAa;IACvB,MAAM,EAAE,WAAW;IAEnB,UAAU;IACV,aAAa,EAAE,kBAAkB;IACjC,gBAAgB,EAAE,qBAAqB;IACvC,QAAQ,EAAE,aAAa;IAEvB,UAAU;IACV,QAAQ,EAAE,aAAa;IACvB,OAAO,EAAE,YAAY;IACrB,iBAAiB,EAAE,sBAAsB;IACzC,OAAO,EAAE,YAAY;IACrB,QAAQ,EAAE,aAAa;IACvB,SAAS,EAAE,cAAc;IACzB,mBAAmB,EAAE,wBAAwB;IAE7C,WAAW;IACX,aAAa,EAAE,kBAAkB;CAClC,CAAC,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,IAAI,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EACL,gBAAgB,IAAI,sBAAsB,EAC1C,WAAW,IAAI,wBAAwB,EACvC,YAAY,IAAI,4BAA4B,GAC7C,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EACL,WAAW,EACX,aAAa,EACb,WAAW,EACX,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,aAAa,EACb,YAAY,EACZ,sBAAsB,EACtB,YAAY,EACZ,wBAAwB,EACxB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,eAAe,YAAY,CAAC;IAC1B,gBAAgB,EAAE,qBAAqB;IACvC,iBAAiB,EAAE,sBAAsB;IACzC,mBAAmB,EAAE,wBAAwB;IAC7C,uBAAuB,EAAE,4BAA4B;IACrD,cAAc,EAAE,aAAa;IAC7B,sBAAsB,EAAE,eAAe;IACvC,cAAc,EAAE,mBAAmB;IACnC,cAAc,EAAE,WAAW;IAC3B,gBAAgB,EAAE,aAAa;IAC/B,cAAc,EAAE,WAAW;IAC3B,oBAAoB,EAAE,iBAAiB;IACvC,qBAAqB,EAAE,gBAAgB;IACvC,eAAe,EAAE,oBAAoB;IACrC,mBAAmB,EAAE,wBAAwB;IAC7C,OAAO;IACP,QAAQ,EAAE,aAAa;IAEvB,WAAW;IACX,QAAQ,EAAE,aAAa;IACvB,MAAM,EAAE,WAAW;IAEnB,UAAU;IACV,aAAa,EAAE,kBAAkB;IACjC,gBAAgB,EAAE,qBAAqB;IACvC,QAAQ,EAAE,aAAa;IAEvB,UAAU;IACV,QAAQ,EAAE,aAAa;IACvB,OAAO,EAAE,YAAY;IACrB,iBAAiB,EAAE,sBAAsB;IACzC,OAAO,EAAE,YAAY;IACrB,QAAQ,EAAE,aAAa;IACvB,SAAS,EAAE,cAAc;IACzB,mBAAmB,EAAE,wBAAwB;IAE7C,WAAW;IACX,aAAa,EAAE,kBAAkB;CAClC,CAAC,CAAC"}

package/docs/read-contracts.md

@@ -126,14 +126,49 @@ accounts and direct callers to the new methods. Their historical scans remain
 subject to Convex read limits; migrate busy accounts to the maintained summaries.
 Full referred-sale history uses `paginateTransfersByAccount`, not the preview.
 
+## Current payout observations
+
+Call `betterStripe.syncPayoutFromStripe(ctx, { stripePayoutId, scope })` from an
+authorized server action. Use `scope: { type: "connected", accountId }` for the
+recipient's connected account or explicitly use `scope: { type: "platform" }`
+for a platform payout. Resolve scope from trusted host configuration and recipient
+ownership. Never accept an arbitrary account or platform mode from the browser.
+The method reads Stripe and updates the existing component payout record; it
+never creates, cancels or releases a bank payout.
+
+The operation works for Stripe-managed automatic and manually triggered payouts.
+It retrieves the current payout under that account's Stripe request scope and
+validates the payout identity, original amount and currency, status, arrival date,
+method and failure details. It does not require a mature balance transaction or a
+manual execution claim. A current status observation does not establish funding
+maturity, payout eligibility or a policy minimum.
+
+A durable claim assigns each read a per-payout generation. Only the newest
+claimed generation can commit. A delayed older response returns `superseded`
+without changing the financial row. A successful result returns `accepted`, its
+generation, `changed` and the stored payout. Identical observations preserve the
+financial row and exact currency totals. Retrying the same committed generation
+also preserves its acceptance timestamp. A later current provider observation
+can legitimately change paid to failed; no terminal-status ranking is applied.
+
+Provider errors or invalid snapshots throw and leave the last accepted financial
+observation intact. The latest incomplete claim becomes unknown when that marker
+can be saved. A lost mutation response may leave a pending or already accepted
+claim. Retry the operation to obtain a new generation and read Stripe again.
+Never substitute the webhook event body when the current provider read fails.
+The claim table holds reconciliation metadata, not a second money ledger.
+
+This method does not yet replace the existing signed webhook dispatcher. The
+prepared generation must be integrated into the shared host callback transaction.
+Until that wiring is adopted, legacy webhook deliveries still apply
+event-body snapshots and can regress on distinct out-of-order events. Do not call
+this method and then blindly apply an old event-body upsert afterward.
+
 ## Payout failures
 
 Component payout rows and live `RecipientPayoutRow` snapshots expose optional
-`failureCode` and `failureMessage`. Signed payout events write the provider's
-current snapshot to the existing payout identity. A later snapshot with absent
-or null provider failure fields clears stored details. Legacy rows remain valid.
-Ordinary event replay is deduplicated. This is snapshot reconciliation and does
-not guarantee convergence for globally out-of-order events.
+`failureCode` and `failureMessage`. A later accepted snapshot with absent or null
+provider failure fields clears stored details. Legacy rows remain valid.
 
 Host apps should translate known codes into safe recovery instructions and a
 settings link. Do not log or blindly render raw provider messages. Authorize

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fantastic.dev/better-stripe",
-  "version": "0.23.1",
+  "version": "0.23.2",
   "description": "A Convex component for Stripe V2 Accounts API integration.",
   "keywords": [
     "stripe",

package/src/client/connect/payoutSync.test.ts

@@ -0,0 +1,313 @@
+// @vitest-environment edge-runtime
+import { expect, it, vi } from "vitest";
+import type Stripe from "stripe";
+import { makeFunctionReference } from "convex/server";
+import type { RunCtx } from "../helpers.js";
+import {
+  component,
+  setup,
+  operation,
+  type Scope,
+} from "./payoutSyncTestHelpers.js";
+const symbol = Symbol.for("toReferencePath");
+it("persists the current automatic payout under the connected scope without requiring mature funding", async () => {
+  const s = await setup();
+  expect(await s.run()).toMatchObject({ status: "accepted", changed: true });
+  expect(s.retrieve).toHaveBeenCalledWith(
+    "po_one",
+    {},
+    { stripeAccount: "acct_owner" },
+  );
+  expect(await s.row()).toMatchObject({
+    stripePayoutId: "po_one",
+    accountId: "acct_owner",
+    amount: 500,
+    currency: "jpy",
+    status: "paid",
+    arrivalDate: "1970-01-01T00:03:20.000Z",
+  });
+  expect(await s.run()).toMatchObject({ status: "accepted", changed: false });
+  expect(
+    await s.t.run((ctx) => ctx.db.query("payouts").collect()),
+  ).toHaveLength(1);
+  expect(
+    await s.t.run((ctx) => ctx.db.query("currencyTotals").unique()),
+  ).toMatchObject({
+    accountId: "acct_owner",
+    currency: "jpy",
+    paidOut: 500,
+    count: 1,
+  });
+});
+it("allows a later authoritative paid-to-failed transition and clears obsolete failure details", async () => {
+  const s = await setup();
+  await s.run();
+  s.set({
+    status: "failed",
+    failure_code: "account_closed",
+    failure_message: "Bank account closed",
+  });
+  await s.run();
+  expect(await s.row()).toMatchObject({
+    status: "failed",
+    failureCode: "account_closed",
+  });
+  expect(
+    await s.t.run((ctx) => ctx.db.query("currencyTotals").unique()),
+  ).toMatchObject({ paidOut: 0, count: 1 });
+  s.set({ status: "pending", failure_code: null, failure_message: null });
+  await s.run();
+  expect((await s.row())?.failureCode).toBeUndefined();
+  expect((await s.row())?.failureMessage).toBeUndefined();
+});
+it("keeps platform scope explicit and ignores provider metadata as account authority", async () => {
+  const s = await setup({ type: "platform" });
+  s.set({ automatic: false });
+  await s.run();
+  expect(s.retrieve).toHaveBeenCalledWith("po_one", {}, {});
+  expect(await s.row()).toMatchObject({
+    accountId: "platform",
+    currency: "jpy",
+  });
+});
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((done) => {
+    resolve = done;
+  });
+  return { promise, resolve };
+}
+it("supersedes a delayed old pending read after a newer paid observation commits", async () => {
+  const s = await setup();
+  const old = { ...s.read(), status: "pending" as const };
+  const response = deferred<Stripe.Payout>();
+  s.retrieve.mockImplementationOnce(() => response.promise);
+  const first = s.run();
+  await vi.waitFor(() => expect(s.retrieve).toHaveBeenCalledTimes(1));
+  expect(await s.run()).toMatchObject({ status: "accepted", generation: 2 });
+  response.resolve(old);
+  expect(await first).toMatchObject({ status: "superseded", generation: 1 });
+  expect(await s.row()).toMatchObject({ status: "paid" });
+  expect(
+    await s.t.run((ctx) => ctx.db.query("payoutSyncClaims").unique()),
+  ).toMatchObject({ status: "accepted", generation: 2, acceptedGeneration: 2 });
+});
+it("a newer failed read holds its generation instead of accepting an older in-flight snapshot", async () => {
+  const s = await setup();
+  await s.run();
+  const response = deferred<Stripe.Payout>();
+  s.retrieve.mockImplementationOnce(() => response.promise);
+  const first = s.run();
+  await vi.waitFor(() => expect(s.retrieve).toHaveBeenCalledTimes(2));
+  s.retrieve.mockRejectedValueOnce(new Error("Provider unavailable"));
+  await expect(s.run()).rejects.toThrow("Provider unavailable");
+  response.resolve({ ...s.read(), status: "pending" });
+  expect(await first).toMatchObject({ status: "superseded" });
+  expect(await s.row()).toMatchObject({ status: "paid" });
+  expect(
+    await s.t.run((ctx) => ctx.db.query("payoutSyncClaims").unique()),
+  ).toMatchObject({ status: "unknown", generation: 3, acceptedGeneration: 1 });
+  expect(await s.run()).toMatchObject({
+    status: "accepted",
+    generation: 4,
+    changed: false,
+  });
+});
+it.each(["begin", "finish"] as const)(
+  "recovers a lost %s response through a fresh durable generation",
+  async (stage) => {
+    const s = await setup();
+    let isLost = false;
+    const ctx = {
+      ...s.ctx,
+      runMutation: async (ref: Record<symbol, string>, args: never) => {
+        const saved = await s.mutate(ref, args);
+        if (!isLost && ref[symbol].endsWith(`/payoutSync/mutations/${stage}`)) {
+          isLost = true;
+          throw new Error("Lost component response");
+        }
+        return saved;
+      },
+    } as unknown as RunCtx;
+    const sync = await operation();
+    await expect(
+      sync(s.provider, component, ctx, {
+        stripePayoutId: "po_one",
+        scope: s.scope,
+      }),
+    ).rejects.toThrow("Lost component response");
+    expect(
+      await s.t.run((ctx) => ctx.db.query("payoutSyncClaims").unique()),
+    ).toMatchObject({
+      generation: 1,
+      status: stage === "finish" ? "accepted" : "pending",
+    });
+    expect(await s.run()).toMatchObject({
+      status: "accepted",
+      generation: 2,
+      changed: stage === "begin",
+    });
+    expect(
+      await s.t.run((ctx) => ctx.db.query("payouts").collect()),
+    ).toHaveLength(1);
+    expect(
+      await s.t.run((ctx) => ctx.db.query("currencyTotals").unique()),
+    ).toMatchObject({ paidOut: 500, count: 1 });
+  },
+);
+it("rejects a foreign existing payout before requesting provider state", async () => {
+  const s = await setup();
+  await s.t.mutation(
+    makeFunctionReference<"mutation">("connect/mutations:upsertPayout"),
+    {
+      stripePayoutId: "po_one",
+      accountId: "acct_foreign",
+      amount: 500,
+      currency: "jpy",
+      status: "paid",
+    },
+  );
+  await expect(s.run()).rejects.toThrow(
+    "Existing payout account does not match.",
+  );
+  expect(s.retrieve).not.toHaveBeenCalled();
+  expect(await s.row()).toMatchObject({ accountId: "acct_foreign" });
+});
+it("rejects changing a payout's durable account even if no financial row was saved", async () => {
+  const s = await setup();
+  s.retrieve.mockRejectedValueOnce(new Error("Unavailable"));
+  await expect(s.run()).rejects.toThrow("Unavailable");
+  s.retrieve.mockClear();
+  const sync = await operation();
+  await expect(
+    sync(s.provider, component, s.ctx, {
+      stripePayoutId: "po_one",
+      scope: { type: "connected", accountId: "acct_foreign" },
+    }),
+  ).rejects.toThrow("Payout synchronization account does not match.");
+  expect(s.retrieve).not.toHaveBeenCalled();
+  expect(await s.row()).toBeNull();
+});
+it.each([{ amount: 501 }, { currency: "kwd" }])(
+  "rejects changed original money %j without changing summaries",
+  async (patch) => {
+    const s = await setup();
+    await s.run();
+    s.set(patch);
+    await expect(s.run()).rejects.toThrow(
+      "Existing payout original money does not match.",
+    );
+    expect(await s.row()).toMatchObject({ amount: 500, currency: "jpy" });
+    expect(
+      await s.t.run((ctx) => ctx.db.query("currencyTotals").unique()),
+    ).toMatchObject({ paidOut: 500, count: 1 });
+  },
+);
+it.each([0, -1, 0.5, Number.MAX_SAFE_INTEGER + 1, NaN])(
+  "rejects invalid provider amount %s without a financial record",
+  async (amount) => {
+    const s = await setup();
+    s.set({ amount });
+    await expect(s.run()).rejects.toThrow(
+      "Invalid payout synchronization money or method.",
+    );
+    expect(await s.row()).toBeNull();
+    expect(
+      await s.t.run((ctx) => ctx.db.query("payoutSyncClaims").unique()),
+    ).toMatchObject({ status: "unknown" });
+  },
+);
+it("rejects an unavailable provider response and preserves retryability", async () => {
+  const s = await setup();
+  s.retrieve.mockResolvedValueOnce(null as unknown as Stripe.Payout);
+  await expect(s.run()).rejects.toThrow(
+    "Provider payout response is unavailable.",
+  );
+  expect(await s.row()).toBeNull();
+  expect(await s.run()).toMatchObject({ status: "accepted", generation: 2 });
+});
+it("rejects a foreign provider payout ID", async () => {
+  const s = await setup();
+  s.set({ id: "po_foreign" });
+  await expect(s.run()).rejects.toThrow(
+    "Provider payout identity does not match.",
+  );
+  expect(await s.row()).toBeNull();
+});
+it.each([NaN, -1, 8640000000001])(
+  "rejects invalid arrival seconds %s",
+  async (arrival_date) => {
+    const s = await setup();
+    s.set({ arrival_date });
+    await expect(s.run()).rejects.toThrow(
+      "Invalid provider payout arrival date.",
+    );
+    expect(await s.row()).toBeNull();
+  },
+);
+it.each(["jpy", "kwd"])(
+  "preserves exact safe original %s units at the maximum integer",
+  async (currency) => {
+    const s = await setup();
+    s.set({ currency, amount: Number.MAX_SAFE_INTEGER });
+    await s.run();
+    expect(await s.row()).toMatchObject({
+      currency,
+      amount: Number.MAX_SAFE_INTEGER,
+    });
+    expect(
+      await s.t.run((ctx) => ctx.db.query("currencyTotals").unique()),
+    ).toMatchObject({ currency, paidOut: Number.MAX_SAFE_INTEGER });
+  },
+);
+it("does not reinterpret a connected account named platform as platform authority", async () => {
+  const s = await setup({ type: "connected", accountId: "platform" });
+  await expect(s.run()).rejects.toThrow(
+    "Payout synchronization scope must be explicit.",
+  );
+  expect(s.retrieve).not.toHaveBeenCalled();
+  expect(await s.row()).toBeNull();
+});
+it("deduplicates equivalent provider metadata order without a financial update", async () => {
+  const s = await setup();
+  s.set({ metadata: { b: "two", a: "one" } });
+  await s.run();
+  s.set({ metadata: { a: "one", b: "two" } });
+  expect(await s.run()).toMatchObject({ status: "accepted", changed: false });
+});
+it("publishes authoritative synchronization through the actual BetterStripe client", async () => {
+  const s = await setup();
+  const { BetterStripe } = await import("../index.js");
+  const spy = vi
+    .spyOn(
+      BetterStripe.prototype as unknown as { stripe: () => Stripe },
+      "stripe",
+    )
+    .mockReturnValue(s.provider);
+  try {
+    const client = new BetterStripe(component) as InstanceType<
+      typeof BetterStripe
+    > & {
+      syncPayoutFromStripe: (
+        ctx: RunCtx,
+        opts: { stripePayoutId: string; scope: Scope },
+      ) => Promise<unknown>;
+    };
+    expect(
+      client.syncPayoutFromStripe,
+      "public authoritative payout method is missing",
+    ).toBeTypeOf("function");
+    expect(
+      await client.syncPayoutFromStripe(s.ctx, {
+        stripePayoutId: "po_one",
+        scope: s.scope,
+      }),
+    ).toMatchObject({ status: "accepted" });
+    expect(await s.row()).toMatchObject({
+      accountId: "acct_owner",
+      status: "paid",
+    });
+  } finally {
+    spy.mockRestore();
+  }
+});

package/src/client/connect/payoutSync.ts

@@ -0,0 +1,93 @@
+import type Stripe from "stripe";
+import type { Infer } from "convex/values";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import { validateIdentity } from "../../component/payoutSync/helpers.js";
+import type { result } from "../../component/payoutSync/validators.js";
+import {
+  payoutAccount,
+  payoutSnapshot,
+  type PayoutSyncScope,
+} from "./payoutSyncValidation.js";
+export type PayoutSyncOptions = {
+  stripePayoutId: string;
+  scope: PayoutSyncScope;
+};
+export type PayoutSyncResult = Infer<typeof result>;
+export type PreparedPayoutSync = Awaited<ReturnType<typeof preparePayoutSync>>;
+async function markUnknown(
+  component: Component,
+  ctx: RunCtx,
+  observation: {
+    stripePayoutId: string;
+    accountId: string;
+    generation: number;
+  },
+) {
+  await runMutationOrThrow(
+    ctx,
+    componentRef(component, "payoutSync/mutations/markUnknown"),
+    observation,
+  );
+}
+/** Package-internal preparation for transactional host webhook dispatch. No financial record write. */
+export async function preparePayoutSync(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  opts: PayoutSyncOptions,
+) {
+  const identity = {
+    stripePayoutId: opts.stripePayoutId,
+    accountId: payoutAccount(opts.scope),
+  };
+  validateIdentity(identity);
+  if (!ctx.runMutation)
+    throw new Error("Payout synchronization requires runMutation.");
+  const generation = (await runMutationOrThrow(
+    ctx,
+    componentRef(component, "payoutSync/mutations/begin"),
+    identity,
+  )) as number;
+  try {
+    const payout = await stripe.payouts.retrieve(
+      identity.stripePayoutId,
+      {},
+      identity.accountId === "platform"
+        ? {}
+        : { stripeAccount: identity.accountId },
+    );
+    return {
+      ...identity,
+      generation,
+      payout: payoutSnapshot(payout, identity),
+    };
+  } catch (error) {
+    await markUnknown(component, ctx, { ...identity, generation });
+    throw error;
+  }
+}
+/** Host must authorize scope. This only reads Stripe and synchronizes the existing financial record. */
+export async function syncPayoutFromStripe(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  opts: PayoutSyncOptions,
+): Promise<PayoutSyncResult> {
+  const observation = await preparePayoutSync(stripe, component, ctx, opts);
+  try {
+    return (await runMutationOrThrow(
+      ctx,
+      componentRef(component, "payoutSync/mutations/finish"),
+      observation,
+    )) as PayoutSyncResult;
+  } catch (error) {
+    await markUnknown(component, ctx, {
+      stripePayoutId: observation.stripePayoutId,
+      accountId: observation.accountId,
+      generation: observation.generation,
+    });
+    throw error;
+  }
+}

package/src/client/connect/payoutSyncTestHelpers.ts

@@ -0,0 +1,82 @@
+// @vitest-environment edge-runtime
+import { convexTest } from "convex-test";
+import { makeFunctionReference } from "convex/server";
+import { expect, vi } from "vitest";
+import type Stripe from "stripe";
+import type { Component, RunCtx } from "../helpers.js";
+import schema from "../../component/schema.js";
+const modules = import.meta.glob("../../component/**/*.*s");
+const symbol = Symbol.for("toReferencePath");
+export const component = {
+  payoutPolicy: {
+    queries: { get: { [symbol]: "betterStripe/payoutPolicy/queries/get" } },
+  },
+} as unknown as Component;
+export type Scope =
+  { type: "connected"; accountId: string } | { type: "platform" };
+type Sync = (
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  opts: { stripePayoutId: string; scope: Scope },
+) => Promise<unknown>;
+export async function operation() {
+  const path = "./payoutSync.js";
+  const mod = (await import(path).catch(() => ({}))) as {
+    syncPayoutFromStripe?: Sync;
+  };
+  expect(
+    mod.syncPayoutFromStripe,
+    "authoritative payout synchronization is missing",
+  ).toBeTypeOf("function");
+  return mod.syncPayoutFromStripe!;
+}
+export async function setup(
+  scope: Scope = { type: "connected", accountId: "acct_owner" },
+) {
+  const t = convexTest(schema, modules);
+  const path = (ref: Record<symbol, string>) =>
+    ref[symbol].replace("betterStripe/", "").replace(/\/(\w+)$/, ":$1");
+  const mutate = (ref: Record<symbol, string>, args: never) =>
+    t.mutation(makeFunctionReference<"mutation">(path(ref)), args);
+  const ctx = {
+    runQuery: (ref: Record<symbol, string>, args: never) =>
+      t.query(makeFunctionReference<"query">(path(ref)), args),
+    runMutation: mutate,
+  } as unknown as RunCtx;
+  let payout = {
+    id: "po_one",
+    amount: 500,
+    currency: "jpy",
+    status: "paid",
+    arrival_date: 200,
+    created: 100,
+    automatic: true,
+    method: "standard",
+    type: "bank_account",
+    source_type: "card",
+    destination: "ba_one",
+    balance_transaction: "txn_pending",
+    failure_code: null,
+    failure_message: null,
+    metadata: { accountId: "acct_metadata_is_not_authority" },
+  } as unknown as Stripe.Payout;
+  const retrieve = vi.fn(async () => ({ ...payout }));
+  const provider = { payouts: { retrieve } } as unknown as Stripe;
+  const sync = await operation();
+  return {
+    t,
+    ctx,
+    mutate,
+    retrieve,
+    provider,
+    scope,
+    set: (patch: Partial<Stripe.Payout>) => {
+      payout = { ...payout, ...patch };
+    },
+    read: () => ({ ...payout }),
+    run: () =>
+      sync(provider, component, ctx, { stripePayoutId: "po_one", scope }),
+    row: () => t.run((ctx) => ctx.db.query("payouts").unique()),
+  };
+}

package/src/client/connect/payoutSyncValidation.ts

@@ -0,0 +1,74 @@
+import type Stripe from "stripe";
+import type { Infer } from "convex/values";
+import type { snapshot } from "../../component/payoutSync/validators.js";
+import {
+  validateIdentity,
+  validateSnapshot,
+} from "../../component/payoutSync/helpers.js";
+export type PayoutSyncScope =
+  { type: "connected"; accountId: string } | { type: "platform" };
+export function payoutAccount(scope: PayoutSyncScope) {
+  if (scope?.type === "platform" && Object.keys(scope).length === 1)
+    return "platform";
+  if (
+    scope?.type === "connected" &&
+    Object.keys(scope).length === 2 &&
+    typeof scope.accountId === "string" &&
+    /^acct_[A-Za-z0-9_]+$/.test(scope.accountId)
+  )
+    return scope.accountId;
+  throw new Error("Payout synchronization scope must be explicit.");
+}
+/** Status observations do not establish funding maturity or payout eligibility. */
+export function payoutSnapshot(
+  p: Stripe.Payout,
+  args: { stripePayoutId: string; accountId: string },
+): Infer<typeof snapshot> {
+  validateIdentity(args);
+  if (!p || typeof p !== "object")
+    throw new Error("Provider payout response is unavailable.");
+  if (p.id !== args.stripePayoutId)
+    throw new Error("Provider payout identity does not match.");
+  if (
+    (p.status !== "pending" &&
+      p.status !== "paid" &&
+      p.status !== "failed" &&
+      p.status !== "canceled" &&
+      p.status !== "in_transit") ||
+    typeof p.automatic !== "boolean" ||
+    !["standard", "instant"].includes(p.method)
+  )
+    throw new Error("Provider payout status or method is unsupported.");
+  if (
+    !Number.isSafeInteger(p.arrival_date) ||
+    p.arrival_date < 0 ||
+    !Number.isSafeInteger(p.arrival_date * 1000) ||
+    p.arrival_date * 1000 > 8640000000000000
+  )
+    throw new Error("Invalid provider payout arrival date.");
+  if (
+    (p.failure_code != null && typeof p.failure_code !== "string") ||
+    (p.failure_message != null && typeof p.failure_message !== "string")
+  )
+    throw new Error("Invalid provider payout failure detail.");
+  const metadata = p.metadata ?? {};
+  if (
+    typeof metadata !== "object" ||
+    Array.isArray(metadata) ||
+    Object.values(metadata).some((v) => typeof v !== "string")
+  )
+    throw new Error("Invalid provider payout metadata.");
+  const result: Infer<typeof snapshot> = {
+    ...args,
+    amount: p.amount,
+    currency: p.currency,
+    status: p.status,
+    arrivalDate: new Date(p.arrival_date * 1000).toISOString(),
+    method: p.method,
+    failureCode: p.failure_code ?? undefined,
+    failureMessage: p.failure_message ?? undefined,
+    metadata,
+  };
+  validateSnapshot(result);
+  return result;
+}