@fantastic.dev/better-stripe 0.23.2 → 0.25.0

package/src/client/connect/payoutExecutionTestHelpers.ts

@@ -0,0 +1,213 @@
+// @vitest-environment edge-runtime
+import { convexTest } from "convex-test";
+import { makeFunctionReference } from "convex/server";
+import { vi } from "vitest";
+import type Stripe from "stripe";
+import schema from "../../component/schema.js";
+import type { Component, RunCtx } from "../helpers.js";
+import { releaseRecipientPayout } from "./payoutExecution.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 const scope = {
+  accountId: "acct_recipient",
+  ownerKey: "owner",
+  operationKey: "release-1",
+  currency: "usd",
+  independentLiabilities: 0,
+};
+export async function setup(amounts = [600, 400]) {
+  const t = convexTest(schema, modules);
+  await t.run(async (ctx) => {
+    await ctx.db.insert("payoutPolicies", {
+      accountId: scope.accountId,
+      ownerKey: scope.ownerKey,
+      mode: "custom",
+      status: "ready",
+      revision: 0,
+      operationKey: "enable",
+      country: "US",
+      thresholds: [{ currency: "usd", amount: 1000 }],
+      holdDeadline: Date.now() + 86400000,
+    });
+    for (let i = 0; i < amounts.length; i++)
+      await ctx.db.insert("transfers", {
+        stripeTransferId: `tr_${i}`,
+        destinationAccountId: scope.accountId,
+        sourceChargeId: `ch_${i}`,
+        amount: amounts[i],
+        currency: "usd",
+        status: "paid",
+        role: i % 2 ? "affiliate" : "store",
+      });
+  });
+  const path = (ref: Record<symbol, string>) =>
+    ref[symbol].replace("betterStripe/", "").replace(/\/(\w+)$/, ":$1");
+  const ctx = {
+    runQuery: (ref: Record<symbol, string>, args: never) =>
+      t.query(makeFunctionReference<"query">(path(ref)), args),
+    runMutation: (ref: Record<symbol, string>, args: never) =>
+      t.mutation(makeFunctionReference<"mutation">(path(ref)), args),
+  } as unknown as RunCtx;
+  let transactions = amounts.map((amount, i) => ({
+    id: `txn_${i}`,
+    source: `py_${i}`,
+    amount,
+    fee: 0,
+    net: amount,
+    currency: "usd",
+    created: 100,
+    available_on: 200,
+    status: "available",
+    type: "payment",
+    exchange_rate: null,
+  }));
+  let payout: Record<string, unknown> | undefined;
+  const provider = {
+    accounts: {
+      listExternalAccounts: vi.fn(async () => ({
+        data: [
+          {
+            id: "ba_one",
+            object: "bank_account",
+            currency: "usd",
+            default_for_currency: true,
+          },
+        ],
+        has_more: false,
+      })),
+    },
+    transfers: {
+      retrieve: vi.fn(async (id: string) => {
+        const i = Number(id.slice(3));
+        return {
+          id,
+          destination: scope.accountId,
+          destination_payment: `py_${i}`,
+          source_transaction: `ch_${i}`,
+          amount: amounts[i],
+          currency: "usd",
+          amount_reversed: 0,
+        };
+      }),
+      listReversals: vi.fn(async () => ({ data: [], has_more: false })),
+    },
+    charges: {
+      retrieve: vi.fn(async (id: string) => {
+        const i = Number(id.slice(3));
+        return {
+          id,
+          source_transfer: `tr_${i}`,
+          amount: amounts[i],
+          currency: "usd",
+          paid: true,
+          status: "succeeded",
+          balance_transaction: `txn_${i}`,
+        };
+      }),
+    },
+    balanceTransactions: {
+      list: vi.fn(async (params: { source?: string; limit?: number }) => ({
+        data: params.source
+          ? transactions.filter((t) => t.source === params.source)
+          : transactions.slice(0, params.limit),
+        has_more: false,
+      })),
+      retrieve: vi.fn(async (id: string) =>
+        transactions.find((t) => t.id === id),
+      ),
+    },
+    balance: {
+      retrieve: vi.fn(async () => ({
+        available: [
+          {
+            currency: "usd",
+            amount: transactions
+              .filter((t) => t.status === "available")
+              .reduce((a, t) => a + t.net, 0),
+            source_types: {
+              card: transactions
+                .filter((t) => t.status === "available")
+                .reduce((a, t) => a + t.net, 0),
+            },
+          },
+        ],
+        pending: [],
+      })),
+    },
+    payouts: {
+      list: vi.fn(async () => ({
+        data: payout ? [payout] : [],
+        has_more: false,
+      })),
+      retrieve: vi.fn(async () => payout),
+      create: vi.fn(
+        async (params: {
+          amount: number;
+          currency: string;
+          metadata: object;
+        }) => {
+          payout = {
+            id: "po_one",
+            ...params,
+            status: "paid",
+            automatic: false,
+            method: "standard",
+            type: "bank_account",
+            source_type: "card",
+            destination: "ba_one",
+            created: Math.floor(Date.now() / 1000),
+            arrival_date: Math.floor(Date.now() / 1000),
+            balance_transaction: "txn_debit",
+            failure_balance_transaction: null,
+            reversed_by: null,
+          };
+          transactions = [
+            {
+              id: "txn_debit",
+              source: "po_one",
+              amount: -params.amount,
+              fee: 0,
+              net: -params.amount,
+              currency: "usd",
+              created: Math.floor(Date.now() / 1000),
+              available_on: Math.floor(Date.now() / 1000),
+              status: "available",
+              type: "payout",
+              exchange_rate: null,
+            },
+            ...transactions,
+          ];
+          return payout;
+        },
+      ),
+    },
+  };
+  const verify = vi.fn(async () => ({
+    status: "verified" as const,
+    policy: (await t.run((ctx) => ctx.db.query("payoutPolicies").first()))!,
+  }));
+  const run = (extra = {}) =>
+    releaseRecipientPayout(
+      provider as unknown as Stripe,
+      component,
+      ctx,
+      { ...scope, ...extra },
+      verify,
+    );
+  return {
+    t,
+    ctx,
+    provider,
+    verify,
+    run,
+    setTransactions: (rows: typeof transactions) => {
+      transactions = rows;
+    },
+    transactions: () => transactions,
+  };
+}

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

@@ -0,0 +1,145 @@
+// @vitest-environment edge-runtime
+import { afterEach, expect, it, vi } from "vitest";
+import type Stripe from "stripe";
+import { setup, scope, component } from "./payoutExecutionTestHelpers.js";
+import { reconcileRecipientPayout } from "./payoutReconciliation.js";
+import { PayoutWorkerClient } from "./payoutWorker.js";
+import { changeBalance } from "../../component/affiliateRecovery/accounting.js";
+afterEach(() => vi.useRealTimers());
+async function worker(amounts?: number[]) {
+  const s = await setup(amounts);
+  const client = new PayoutWorkerClient(
+    component,
+    (_ctx, opts) => s.run(opts),
+    (_ctx, opts) =>
+      reconcileRecipientPayout(
+        s.provider as unknown as Stripe,
+        component,
+        s.ctx,
+        opts,
+      ),
+  );
+  const run = () => client.run(s.ctx, scope);
+  return { ...s, client, run };
+}
+it("the recurring worker releases combined money once, records its result and waits for the next attempt", async () => {
+  const s = await worker();
+  expect(await s.run()).toMatchObject({
+    status: "completed",
+    job: { lastReason: "paid", hasOperation: false },
+    payout: { claim: { amount: 1000, status: "paid" } },
+  });
+  expect(await s.run()).toMatchObject({ status: "held", reason: "not_due" });
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+  const state = await s.client.get(s.ctx, scope);
+  expect(state?.nextAttemptAt).toBeGreaterThan(Date.now());
+});
+it("the next recurring attempt carries below-minimum balances and pays when new funding qualifies", async () => {
+  vi.useFakeTimers();
+  const amounts = [599, 400];
+  const s = await worker(amounts);
+  expect(await s.run()).toMatchObject({
+    payout: { status: "held", reason: "below_threshold", matureUnpaid: 999 },
+  });
+  vi.advanceTimersByTime(300000);
+  expect(await s.run()).toMatchObject({
+    payout: { reason: "below_threshold" },
+  });
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+  amounts.push(1);
+  await s.t.run((ctx) =>
+    ctx.db.insert("transfers", {
+      stripeTransferId: "tr_2",
+      destinationAccountId: scope.accountId,
+      sourceChargeId: "ch_2",
+      amount: 1,
+      currency: "usd",
+      status: "paid",
+      role: "affiliate",
+    }),
+  );
+  s.setTransactions([
+    ...s.transactions(),
+    {
+      ...s.transactions()[0],
+      id: "txn_2",
+      source: "py_2",
+      amount: 1,
+      net: 1,
+    },
+  ]);
+  vi.advanceTimersByTime(300000);
+  expect(await s.run()).toMatchObject({
+    payout: { claim: { status: "paid", amount: 1000 } },
+  });
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+});
+it("unknown provider outcomes keep the same durable attempt and never blindly recreate", async () => {
+  vi.useFakeTimers();
+  const s = await worker();
+  s.provider.payouts.create.mockRejectedValueOnce(
+    new Error("network outcome unknown"),
+  );
+  await expect(s.run()).rejects.toThrow("network outcome unknown");
+  const first = await s.client.get(s.ctx, scope);
+  expect(first).toMatchObject({
+    hasOperation: true,
+    lastReason: "worker_error",
+  });
+  vi.advanceTimersByTime(300000);
+  expect(await s.run()).toMatchObject({
+    payout: { status: "held", reason: "payout_unidentified" },
+  });
+  expect((await s.client.get(s.ctx, scope))?.operationKey).toBe(
+    first?.operationKey,
+  );
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+});
+it("concurrent recurring workers share the lease instead of canceling each other's unattempted claim", async () => {
+  const s = await worker();
+  const results = await Promise.all([s.run(), s.run()]);
+  expect(results.map((r) => r.status).sort()).toEqual(["completed", "held"]);
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+});
+it("a successful payout with a lost response is recovered after opting out without another create", async () => {
+  vi.useFakeTimers();
+  const s = await worker();
+  const create = s.provider.payouts.create.getMockImplementation()!;
+  s.provider.payouts.create.mockImplementationOnce(async (params) => {
+    await create(params);
+    throw new Error("response lost after provider accepted");
+  });
+  await expect(s.run()).rejects.toThrow(/response lost/);
+  await s.t.run((ctx) =>
+    changeBalance(ctx, scope.accountId, "usd", { outstandingDebt: 100 }),
+  );
+  await s.t.run(async (ctx) => {
+    const policy = await ctx.db.query("payoutPolicies").first();
+    await ctx.db.patch("payoutPolicies", policy!._id, {
+      mode: "stripe_managed",
+      thresholds: [],
+      revision: 1,
+    });
+  });
+  vi.advanceTimersByTime(300000);
+  expect(await s.run()).toMatchObject({
+    payout: { claim: { status: "paid", amount: 1000 } },
+    job: { hasOperation: false },
+  });
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+});
+it("reports affiliate recovery holds before a fresh attempt without creating a payout", async () => {
+  const s = await worker();
+  await s.t.run((ctx) =>
+    changeBalance(ctx, scope.accountId, "usd", { outstandingDebt: 100 }),
+  );
+  expect(await s.run()).toMatchObject({
+    status: "held",
+    reason: "affiliate_recovery_pending",
+  });
+  expect(await s.client.get(s.ctx, scope)).toMatchObject({
+    lastReason: "affiliate_recovery_pending",
+    hasOperation: false,
+  });
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+});

package/src/client/connect/payoutWorker.ts

@@ -0,0 +1,144 @@
+import type { Infer } from "convex/values";
+import type { jobDoc } from "../../component/payoutWorker/schema.js";
+import type { policyDoc } from "../../component/payoutPolicy/schema.js";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import type {
+  PayoutReleaseOptions,
+  PayoutReleaseResult,
+} from "./payoutExecution.js";
+import type {
+  PayoutReconciliationOptions,
+  PayoutReconciliation,
+} from "./payoutReconciliation.js";
+export type PayoutWorkerJob = Infer<typeof jobDoc>;
+export type PayoutWorkerScope = {
+  accountId: string;
+  ownerKey: string;
+  currency: string;
+};
+export type PayoutWorkerOptions = Omit<PayoutReleaseOptions, "operationKey"> & {
+  cadenceMs?: number;
+};
+type PageOptions = { cursor: string | null; numItems: number };
+type Page<T> = { page: T[]; continueCursor: string; isDone: boolean };
+type Held = { status: "held"; reason: string; nextAttemptAt?: number };
+export type PayoutWorkerResult =
+  | Held
+  | { status: "completed"; job: PayoutWorkerJob; payout: PayoutReleaseResult };
+/** Host cron only. No method on this worker represents a customer withdrawal request. */
+export class PayoutWorkerClient {
+  constructor(
+    private readonly component: Component,
+    private readonly release: (
+      ctx: RunCtx,
+      opts: PayoutReleaseOptions,
+    ) => Promise<PayoutReleaseResult>,
+    private readonly reconcile: (
+      ctx: RunCtx,
+      opts: PayoutReconciliationOptions,
+    ) => Promise<PayoutReconciliation>,
+  ) {}
+  get(ctx: RunCtx, scope: PayoutWorkerScope): Promise<PayoutWorkerJob | null> {
+    return ctx.runQuery(
+      componentRef(this.component, "payoutWorker/queries/get"),
+      {
+        accountId: scope.accountId,
+        ownerKey: scope.ownerKey,
+        currency: scope.currency,
+      },
+    );
+  }
+  policies(
+    ctx: RunCtx,
+    paginationOpts: PageOptions,
+  ): Promise<Page<Infer<typeof policyDoc>>> {
+    return ctx.runQuery(
+      componentRef(this.component, "payoutWorker/queries/policies"),
+      { paginationOpts },
+    );
+  }
+  recovering(
+    ctx: RunCtx,
+    paginationOpts: PageOptions,
+  ): Promise<Page<PayoutWorkerJob>> {
+    return ctx.runQuery(
+      componentRef(this.component, "payoutWorker/queries/recovering"),
+      { paginationOpts },
+    );
+  }
+  changing(
+    ctx: RunCtx,
+    paginationOpts: PageOptions,
+  ): Promise<Page<Infer<typeof policyDoc>>> {
+    return ctx.runQuery(
+      componentRef(this.component, "payoutWorker/queries/changing"),
+      { paginationOpts },
+    );
+  }
+  async run(
+    ctx: RunCtx,
+    opts: PayoutWorkerOptions,
+  ): Promise<PayoutWorkerResult> {
+    if (
+      !Number.isSafeInteger(opts.independentLiabilities) ||
+      opts.independentLiabilities < 0 ||
+      (opts.maxPages !== undefined &&
+        (!Number.isInteger(opts.maxPages) ||
+          opts.maxPages < 1 ||
+          opts.maxPages > 100))
+    )
+      throw new Error("Invalid automatic payout liabilities or page budget.");
+    const scope = {
+      accountId: opts.accountId,
+      ownerKey: opts.ownerKey,
+      currency: opts.currency,
+    };
+    const started = (await runMutationOrThrow(
+      ctx,
+      componentRef(this.component, "payoutWorker/mutations/begin"),
+      {
+        ...scope,
+        cadenceMs: opts.cadenceMs ?? 300000,
+      },
+    )) as
+      Held | { status: "run"; job: PayoutWorkerJob; reconcileOnly: boolean };
+    if (started.status === "held") return started;
+    const operationKey = started.job.operationKey!;
+    const finish = (reason: string) =>
+      runMutationOrThrow(
+        ctx,
+        componentRef(this.component, "payoutWorker/mutations/finish"),
+        { ...scope, operationKey, generation: started.job.generation, reason },
+      ) as Promise<PayoutWorkerJob>;
+    let payout: PayoutReleaseResult;
+    try {
+      payout = started.reconcileOnly
+        ? await this.reconcile(ctx, {
+            ...scope,
+            operationKey,
+            maxPages: opts.maxPages,
+          })
+        : await this.release(ctx, {
+            ...scope,
+            operationKey,
+            independentLiabilities: opts.independentLiabilities,
+            maxPages: opts.maxPages,
+          });
+    } catch (error) {
+      try {
+        await finish("worker_error");
+      } catch (completionError) {
+        throw new AggregateError(
+          [error, completionError],
+          "Payout worker outcome requires reconciliation.",
+        );
+      }
+      throw error;
+    }
+    const reason =
+      payout.status === "held" ? payout.reason : payout.claim.status;
+    return { status: "completed", job: await finish(reason), payout };
+  }
+}

package/src/client/connect/payouts.ts

@@ -1,3 +1,9 @@
+import {
+  reserveAffiliatePayout,
+  completeAffiliatePayout,
+  reconcileAffiliatePayout,
+} from "../affiliateRecovery/payoutGate.js";
+import { classifyRecoveryError } from "../affiliateRecovery/provider.js";
 import type Stripe from "stripe";
 
 import type { PayoutStatus } from "../../component/connect/validators.js";
@@ -54,6 +60,8 @@ export async function getAccountBalance(
 }
 
 export type CreatePayoutOptions = {
+  /** Host-authorized minimum in the payout currency. */
+  minimumAmount?: number;
   stripeAccountId: string;
   amount: number;
   currency?: string;
@@ -64,23 +72,75 @@ export type CreatePayoutOptions = {
 
 export async function createPayout(
   stripe: Stripe,
-  _ctx: RunCtx,
+  ctx: RunCtx,
   opts: CreatePayoutOptions,
+  component?: Component,
 ) {
-  const payout = await stripe.payouts.create(
-    {
-      amount: opts.amount,
-      currency: opts.currency ?? "usd",
-      metadata: opts.metadata ?? undefined,
-    },
-    {
-      stripeAccount: opts.stripeAccountId,
-      ...(opts.idempotencyKey !== undefined
-        ? { idempotencyKey: opts.idempotencyKey }
-        : {}),
-    },
-  );
-  return { stripePayoutId: payout.id };
+  const release = component
+    ? await reserveAffiliatePayout(component, ctx, opts)
+    : null;
+  if (release?.state === "submitted")
+    return { stripePayoutId: release.stripePayoutId! };
+  if (release?.state === "failed")
+    throw new Error(
+      "Affiliate payout failed; use a new authorized operation key.",
+    );
+  try {
+    if (release) {
+      const receiptId = await reconcileAffiliatePayout(stripe, release);
+      if (receiptId) {
+        await completeAffiliatePayout(
+          component!,
+          ctx,
+          release.operationKey,
+          "submitted",
+          receiptId,
+        );
+        return { stripePayoutId: receiptId };
+      }
+    }
+    if (release) {
+      if (Date.now() - release.createdAt >= 23 * 60 * 60 * 1000)
+        throw new Error(
+          "Affiliate payout idempotency window expired; reconcile the provider receipt before retrying.",
+        );
+      // Receipt lookup may yield while a refund records new debt.
+      await reserveAffiliatePayout(component!, ctx, opts);
+    }
+    const payout = await stripe.payouts.create(
+      {
+        amount: opts.amount,
+        currency: opts.currency ?? "usd",
+        metadata: release
+          ? { ...opts.metadata, bsAffiliatePayout: release._id }
+          : (opts.metadata ?? undefined),
+      },
+      {
+        stripeAccount: opts.stripeAccountId,
+        ...(opts.idempotencyKey !== undefined
+          ? { idempotencyKey: opts.idempotencyKey }
+          : {}),
+      },
+    );
+    if (release)
+      await completeAffiliatePayout(
+        component!,
+        ctx,
+        release.operationKey,
+        "submitted",
+        payout.id,
+      );
+    return { stripePayoutId: payout.id };
+  } catch (error) {
+    if (release)
+      await completeAffiliatePayout(
+        component!,
+        ctx,
+        release.operationKey,
+        classifyRecoveryError(error).state === "unknown" ? "unknown" : "failed",
+      );
+    throw error;
+  }
 }
 
 export async function getPayout(

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

@@ -0,0 +1,46 @@
+import type Stripe from "stripe";
+import { expect, it } from "vitest";
+import { successfulRefundPrincipal } from "./refundPrincipal.js";
+const provider = (refunds: { amount: number; status: string }[]) =>
+  ({
+    refunds: {
+      list: () =>
+        (async function* () {
+          yield* refunds;
+        })(),
+    },
+  }) as unknown as Stripe;
+it("excludes pending, failed and canceled refunds from the finalized cumulative principal", async () => {
+  expect(
+    await successfulRefundPrincipal(
+      provider([
+        { amount: 100, status: "succeeded" },
+        { amount: 200, status: "pending" },
+        { amount: 300, status: "failed" },
+        { amount: 400, status: "canceled" },
+        { amount: 500, status: "succeeded" },
+        { amount: 600, status: "requires_action" },
+      ]),
+      "ch_1",
+    ),
+  ).toBe(600);
+});
+it("fails closed on invalid money and a refund history beyond the supported bound", async () => {
+  await expect(
+    successfulRefundPrincipal(
+      provider([{ amount: -1, status: "succeeded" }]),
+      "ch_1",
+    ),
+  ).rejects.toThrow("Invalid");
+  await expect(
+    successfulRefundPrincipal(
+      provider(
+        Array.from({ length: 1001 }, () => ({
+          amount: 1,
+          status: "succeeded",
+        })),
+      ),
+      "ch_1",
+    ),
+  ).rejects.toThrow("limit exceeded");
+});

package/src/client/connect/refundPrincipal.ts

@@ -0,0 +1,26 @@
+import type Stripe from "stripe";
+
+/** Charge.amount_refunded also includes pending refunds; only success is final. */
+export async function successfulRefundPrincipal(
+  stripe: Stripe,
+  chargeId: string,
+) {
+  let principal = 0;
+  let count = 0;
+  for await (const refund of stripe.refunds.list({
+    charge: chargeId,
+    limit: 100,
+  })) {
+    if (++count > 1000)
+      throw new Error("Successful refund lookup limit exceeded.");
+    if (refund.status !== "succeeded") continue;
+    if (
+      !Number.isSafeInteger(refund.amount) ||
+      refund.amount < 0 ||
+      !Number.isSafeInteger(principal + refund.amount)
+    )
+      throw new Error("Invalid successful refund principal.");
+    principal += refund.amount;
+  }
+  return principal;
+}