@fantastic.dev/better-stripe 0.23.0 → 0.23.2

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

@@ -0,0 +1,157 @@
+// @vitest-environment edge-runtime
+import { expect, it, vi } from "vitest";
+import { historical, scope } from "./payoutAdoptionTestHelpers.js";
+
+it.each([
+  ["usd", "failed", 0],
+  ["jpy", "canceled", 25],
+  ["kwd", "failed", 25],
+] as const)(
+  "adopts and replays returned %s principal with %s status and %i fee",
+  async (currency, status, fee) => {
+    const s = await historical(currency);
+    const payout = await s.provider.payouts.retrieve();
+    if (!payout) throw new Error("Missing fixture payout");
+    vi.useFakeTimers();
+    try {
+      vi.setSystemTime(Date.now() + 2000);
+      const returnedAt = Math.floor(Date.now() / 1000);
+      payout.status = status;
+      payout.failure_balance_transaction = "txn_return";
+      s.setTransactions([
+        {
+          id: "txn_return",
+          source: "po_one",
+          amount: 1000,
+          fee,
+          net: 1000 - fee,
+          currency,
+          created: returnedAt,
+          available_on: returnedAt,
+          status: "available",
+          type: status === "failed" ? "payout_failure" : "payout_cancel",
+          exchange_rate: null,
+        },
+        ...s.transactions(),
+      ]);
+      const expected = {
+        status: "adopted",
+        oldestHeldAt: returnedAt * 1000,
+        claims: [
+          { status: "returned", amount: 1000, currency, providerFee: fee },
+        ],
+      };
+      expect(await s.adopt()).toMatchObject(expected);
+      expect(await s.adopt()).toMatchObject(expected);
+      expect(
+        await s.t.run((ctx) => ctx.db.query("payoutReleaseClaims").collect()),
+      ).toHaveLength(1);
+      expect(
+        await s.t.run((ctx) =>
+          ctx.db.query("payoutSourceAllocations").collect(),
+        ),
+      ).toMatchObject([
+        { paidAmount: 0, reservedAmount: 0 },
+        { paidAmount: 0, reservedAmount: 0 },
+      ]);
+      expect(s.provider.payouts.create).not.toHaveBeenCalled();
+
+      // Add later source funding; the returned principal is payable once, net of its fee.
+      s.amounts.push(300);
+      vi.setSystemTime(Date.now() + 10000);
+      const created = Math.floor(Date.now() / 1000);
+      await s.t.run(async (ctx) => {
+        await ctx.db.insert("transfers", {
+          stripeTransferId: "tr_2",
+          destinationAccountId: scope.accountId,
+          sourceChargeId: "ch_2",
+          amount: 300,
+          currency,
+          status: "paid",
+          role: "store",
+        });
+        const policy = await ctx.db.query("payoutPolicies").first();
+        if (!policy) throw new Error("Missing fixture policy");
+        await ctx.db.patch("payoutPolicies", policy._id, {
+          mode: "custom",
+          thresholds: [{ currency, amount: 1 }],
+        });
+      });
+      s.setTransactions([
+        ...s.transactions(),
+        {
+          id: "txn_2",
+          source: "py_2",
+          amount: 300,
+          fee: 0,
+          net: 300,
+          currency,
+          created,
+          available_on: created,
+          status: "available",
+          type: "payment",
+          exchange_rate: null,
+        },
+      ]);
+      expect(await s.run()).toMatchObject({
+        status: "updated",
+        claim: { status: "paid", amount: 1300 - fee, currency },
+      });
+      expect(await s.run()).toMatchObject({
+        status: "updated",
+        claim: { status: "paid", amount: 1300 - fee, currency },
+      });
+      expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  },
+);
+
+it.each(["pending", "wrong_currency", "wrong_principal"] as const)(
+  "holds or rejects %s returns without importing partial history",
+  async (kind) => {
+    const s = await historical();
+    const payout = await s.provider.payouts.retrieve();
+    if (!payout) throw new Error("Missing fixture payout");
+    payout.status = "failed";
+    payout.failure_balance_transaction = "txn_return";
+    const now = Math.floor(Date.now() / 1000);
+    const amount = kind === "wrong_principal" ? 999 : 1000;
+    s.setTransactions([
+      {
+        id: "txn_return",
+        source: "po_one",
+        amount,
+        fee: 0,
+        net: amount,
+        currency: kind === "wrong_currency" ? "eur" : "usd",
+        created: now,
+        available_on: now,
+        status: kind === "pending" ? "pending" : "available",
+        type: "payout_failure",
+        exchange_rate: null,
+      },
+      ...s.transactions(),
+    ]);
+    if (kind === "wrong_principal")
+      await expect(s.adopt()).rejects.toThrow(
+        "Payout transaction receipt identity or principal does not match.",
+      );
+    else
+      expect(await s.adopt()).toMatchObject({
+        status: "held",
+        reason:
+          kind === "pending"
+            ? "return_pending"
+            : "currency_allocation_required",
+      });
+    expect(
+      await s.t.run((ctx) => ctx.db.query("payoutReleaseClaims").collect()),
+    ).toEqual([]);
+    expect(
+      await s.t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
+    ).toEqual([]);
+    expect(s.provider.payouts.create).not.toHaveBeenCalled();
+  },
+);

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()),
+  };
+}