@fantastic.dev/better-stripe 0.23.1 → 0.24.0

package/src/client/affiliateRecovery.ts

@@ -0,0 +1,173 @@
+import {
+  reconcileAffiliatePayout,
+  completeAffiliatePayout,
+} from "./affiliateRecovery/payoutGate.js";
+import { verifiedLegacyReview } from "./affiliateRecovery/review.js";
+import { runMutationOrThrow } from "./helpers.js";
+import { createPayout } from "./connect/payouts.js";
+import type Stripe from "stripe";
+import type { PaginationOptions } from "convex/server";
+import type { Component, RunCtx } from "./helpers.js";
+import { componentRef } from "./webhooks/helpers.js";
+import { reconcileObligation } from "./affiliateRecovery/engine.js";
+import type {
+  RecoveryObligation,
+  RecoveryOperation,
+} from "./affiliateRecovery/provider.js";
+import type { Doc } from "../component/_generated/dataModel.js";
+export type AffiliateRecoveryObligation = RecoveryObligation;
+export type AffiliateRecoveryOperation = RecoveryOperation;
+export type AffiliateRecoveryBalance = Doc<"affiliateRecoveryBalances">;
+export type AffiliateRecoverySnapshot = {
+  balance: AffiliateRecoveryBalance | null;
+  obligations: {
+    page: RecoveryObligation[];
+    continueCursor: string;
+    isDone: boolean;
+  };
+};
+/** Server API. Host must authorize account ownership and operator retries. */
+export class AffiliateRecoveryClient {
+  constructor(
+    private readonly component: Component,
+    private readonly provider: () => Stripe,
+  ) {}
+  async snapshot(
+    ctx: RunCtx,
+    opts: {
+      affiliateAccountId: string;
+      currency: string;
+      paginationOpts: PaginationOptions;
+    },
+  ): Promise<AffiliateRecoverySnapshot> {
+    return ctx.runQuery(
+      componentRef(
+        this.component,
+        "affiliateRecovery/queries/recoverySnapshot",
+      ),
+      opts,
+    ) as Promise<AffiliateRecoverySnapshot>;
+  }
+  async obligation(
+    ctx: RunCtx,
+    opts: { obligationId: string },
+  ): Promise<RecoveryObligation | null> {
+    return ctx.runQuery(
+      componentRef(this.component, "affiliateRecovery/queries/getObligation"),
+      opts,
+    ) as Promise<RecoveryObligation | null>;
+  }
+  async history(
+    ctx: RunCtx,
+    opts: { obligationId: string; paginationOpts: PaginationOptions },
+  ) {
+    return ctx.runQuery(
+      componentRef(
+        this.component,
+        "affiliateRecovery/queries/operationHistory",
+      ),
+      opts,
+    ) as Promise<{
+      page: RecoveryOperation[];
+      continueCursor: string;
+      isDone: boolean;
+    }>;
+  }
+  async reviewLegacy(
+    ctx: RunCtx,
+    opts: {
+      obligationId: string;
+      reversalIds: string[];
+      restorationTransferIds?: string[];
+      note: string;
+    },
+  ) {
+    const row = await this.obligation(ctx, opts);
+    if (!row) throw new Error("Affiliate obligation not found.");
+    const review = await verifiedLegacyReview(this.provider(), row, opts);
+    await runMutationOrThrow(
+      ctx,
+      componentRef(this.component, "affiliateRecovery/mutations/reviewLegacy"),
+      review,
+    );
+    return this.obligation(ctx, opts);
+  }
+  async retry(ctx: RunCtx, opts: { obligationId: string }) {
+    return reconcileObligation(
+      this.provider(),
+      this.component,
+      ctx,
+      opts.obligationId,
+    );
+  }
+  async reconcilePayouts(
+    ctx: RunCtx,
+    opts: { paginationOpts: PaginationOptions; state: "pending" | "unknown" },
+  ) {
+    const page = (await ctx.runQuery(
+      componentRef(this.component, "affiliatePayouts/queries/pendingPayouts"),
+      opts,
+    )) as {
+      page: Doc<"affiliatePayoutReleases">[];
+      continueCursor: string;
+      isDone: boolean;
+    };
+    for (const row of page.page) {
+      try {
+        // Confirm money already moved even when new debt blocks another attempt.
+        const receipt = await reconcileAffiliatePayout(this.provider(), row);
+        if (receipt) {
+          await completeAffiliatePayout(
+            this.component,
+            ctx,
+            row.operationKey,
+            "submitted",
+            receipt,
+          );
+          continue;
+        }
+        await createPayout(
+          this.provider(),
+          ctx,
+          {
+            stripeAccountId: row.affiliateAccountId,
+            currency: row.currency,
+            amount: row.amount,
+            minimumAmount: row.minimumAmount,
+            idempotencyKey: row.operationKey,
+          },
+          this.component,
+        );
+      } catch {
+        /* The payout gate retains the durable failure/unknown outcome. */
+      }
+    }
+    return page;
+  }
+  /** Run from a host cron for both pending and unknown outcomes. */
+  async reconcilePending(
+    ctx: RunCtx,
+    opts: { paginationOpts: PaginationOptions; state: "pending" | "unknown" },
+  ) {
+    const page = (await ctx.runQuery(
+      componentRef(
+        this.component,
+        "affiliateRecovery/queries/pendingOperations",
+      ),
+      opts,
+    )) as {
+      page: RecoveryOperation[];
+      continueCursor: string;
+      isDone: boolean;
+    };
+    const results = [];
+    for (const op of page.page)
+      results.push(await this.retry(ctx, { obligationId: op.obligationId }));
+    return { ...page, results };
+  }
+}
+export {
+  affiliateSnapshotValidator,
+  affiliateObligationValidator,
+  affiliateOperationValidator,
+} from "./affiliateRecovery/validators.js";

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

@@ -0,0 +1,157 @@
+import { reclaimReversalClaim } from "./transfers.js";
+import type Stripe from "stripe";
+import { describe, expect, it, vi } from "vitest";
+import { findCommissionReversal } from "./commissionReceipts.js";
+import { executeClaimedSlices } from "./reversalExecution.js";
+import type { Component, RunCtx } from "../helpers.js";
+
+const component = new Proxy(
+  {},
+  {
+    get: (_t, p) =>
+      p === Symbol.for("toReferencePath") ? "betterStripe" : component,
+  },
+) as Component;
+const claim = {
+  replay: false,
+  slices: [
+    {
+      stripeTransferId: "tr_1",
+      from: 0,
+      to: 501,
+      confirmed: 0,
+      commissionTracked: true,
+    },
+  ],
+};
+const fixture = () => {
+  const receipts: {
+    id: string;
+    amount: number;
+    metadata: Record<string, string>;
+  }[] = [];
+  const stripe = {
+    transfers: {
+      createReversal: vi.fn(
+        async (
+          _id: string,
+          params: { amount: number; metadata: Record<string, string> },
+        ) => {
+          const receipt = { id: "trr_1", ...params };
+          receipts.push(receipt);
+          return receipt;
+        },
+      ),
+      listReversals: vi.fn(() =>
+        (async function* () {
+          yield* receipts;
+        })(),
+      ),
+      retrieve: vi.fn(),
+    },
+  };
+  const ctx = { runMutation: vi.fn().mockResolvedValue(null) };
+  const run = (replay = false, confirmed = 0) =>
+    executeClaimedSlices(
+      stripe as unknown as Stripe,
+      component,
+      ctx as unknown as RunCtx,
+      "re_1",
+      { ...claim, replay, slices: [{ ...claim.slices[0], confirmed }] },
+    );
+  return { stripe, ctx, receipts, run };
+};
+
+describe("commission reversal receipt reconciliation", () => {
+  it("recovers a provider success after the ledger confirmation crashed, even beyond the idempotency window", async () => {
+    const f = fixture();
+    f.ctx.runMutation.mockRejectedValueOnce(new Error("ledger offline"));
+    await expect(f.run()).rejects.toThrow("ledger offline");
+    expect(f.receipts).toHaveLength(1);
+    await f.run(true);
+    await f.run(true, 501);
+    expect(f.stripe.transfers.createReversal).toHaveBeenCalledTimes(1);
+    expect(f.ctx.runMutation).toHaveBeenLastCalledWith(expect.anything(), {
+      stripeTransferId: "tr_1",
+      reversedAmount: 501,
+      receipt: { stripeReversalId: "trr_1", operationId: "re_1", amount: 501 },
+    });
+  });
+
+  it("does not mistake another operation's aggregate reversal for this receipt", async () => {
+    const f = fixture();
+    f.receipts.push({
+      id: "trr_other",
+      amount: 501,
+      metadata: { bsReversalOperation: "re_other" },
+    });
+    await expect(f.run(true, 501)).rejects.toThrow(
+      "requires receipt reconciliation",
+    );
+    expect(f.stripe.transfers.retrieve).not.toHaveBeenCalled();
+    expect(f.stripe.transfers.createReversal).not.toHaveBeenCalled();
+    expect(f.ctx.runMutation).not.toHaveBeenCalled();
+  });
+
+  it("retries a failed provider attempt with byte-identical parameters and operation identity", async () => {
+    const f = fixture();
+    f.stripe.transfers.createReversal.mockRejectedValueOnce(
+      new Error("network offline"),
+    );
+    await expect(f.run()).rejects.toThrow("network offline");
+    await f.run(true);
+    expect(f.stripe.transfers.createReversal.mock.calls[0]).toEqual(
+      f.stripe.transfers.createReversal.mock.calls[1],
+    );
+    expect(f.receipts).toHaveLength(1);
+  });
+
+  it("rejects a mismatching receipt amount without confirming money", async () => {
+    const f = fixture();
+    f.receipts.push({
+      id: "trr_bad",
+      amount: 500,
+      metadata: { bsReversalOperation: "re_1" },
+    });
+    await expect(f.run(true)).rejects.toThrow("amount mismatch");
+    expect(f.ctx.runMutation).not.toHaveBeenCalled();
+  });
+
+  it("fails explicitly when the bounded receipt search cannot establish success", async () => {
+    const f = fixture();
+    for (let i = 0; i < 1001; i++)
+      f.receipts.push({ id: `trr_${i}`, amount: 1, metadata: {} });
+    await expect(
+      findCommissionReversal(
+        f.stripe as unknown as Stripe,
+        "tr_1",
+        "re_1",
+        501,
+      ),
+    ).rejects.toThrow("lookup limit exceeded");
+  });
+});
+
+it("operator re-execution delegates tracked commissions to the durable recovery engine", async () => {
+  const f = fixture();
+  const runQuery = vi
+    .fn()
+    .mockResolvedValueOnce({
+      operationId: "re_1",
+      sourceChargeId: "ch_1",
+      _creationTime: 0,
+      slices: [{ stripeTransferId: "tr_1", from: 0, to: 501 }],
+      commissionExposure: { kind: "refund" },
+    })
+    .mockResolvedValueOnce({ role: "affiliate", reversedAmount: 0 });
+  await reclaimReversalClaim(
+    f.stripe as unknown as Stripe,
+    component,
+    { ...f.ctx, runQuery } as unknown as RunCtx,
+    { operationId: "re_1" },
+  );
+  expect(f.stripe.transfers.createReversal).not.toHaveBeenCalled();
+  expect(runQuery).toHaveBeenLastCalledWith(expect.anything(), {
+    sourceChargeId: "ch_1",
+  });
+});

package/src/client/connect/commissionReceipts.ts

@@ -0,0 +1,23 @@
+import type Stripe from "stripe";
+
+/** Locate the exact receipt, never infer operation success from an aggregate. */
+export async function findCommissionReversal(
+  stripe: Stripe,
+  stripeTransferId: string,
+  operationId: string,
+  amount: number,
+) {
+  let count = 0;
+  for await (const receipt of stripe.transfers.listReversals(stripeTransferId, {
+    limit: 100,
+  })) {
+    if (++count > 1000)
+      throw new Error("Commission reversal receipt lookup limit exceeded.");
+    if (receipt.metadata?.bsReversalOperation === operationId) {
+      if (receipt.amount !== amount)
+        throw new Error("Commission reversal receipt amount mismatch.");
+      return receipt;
+    }
+  }
+  return null;
+}

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