@fantastic.dev/better-stripe 0.23.1 → 0.24.0

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

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

package/src/client/connect/reversalExecution.ts

@@ -0,0 +1,130 @@
+import type Stripe from "stripe";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import { findCommissionReversal } from "./commissionReceipts.js";
+
+export type ClaimedSlice = {
+  stripeTransferId: string;
+  /** Cumulative reversed amount this slice starts from. */
+  from: number;
+  /** Cumulative reversed amount this slice raises the leg to. */
+  to: number;
+  /** The leg's confirmed `reversedAmount` at claim time. */
+  confirmed: number;
+  commissionTracked?: boolean;
+};
+
+export type ReversalClaim = { replay: boolean; slices: ClaimedSlice[] };
+
+/**
+ * Execute the slices an operation claimed via `claimReversalSlices` (BTS-63).
+ * The claim already reserved this money atomically, so all that's left is
+ * moving it: one `bs_rev_<operationId>_<transferId>` reversal per slice, then
+ * confirming the new cumulative total in the ledger. A replayed claim always
+ * re-sends byte-identical params under the same key, which Stripe answers
+ * from its idempotency cache without moving money twice.
+ *
+ * Because Stripe prunes idempotency keys after ~24h (and a crash can land
+ * between the Stripe call and the ledger confirm), a replay first checks the
+ * transfer's live `amount_reversed`: if the slice's money already moved, it
+ * just confirms the ledger instead of re-sending the reversal.
+ *
+ * A slice only executes once every predecessor slice on its leg is confirmed
+ * (`confirmed ≥ from`). Without that gate, a sibling operation landing behind
+ * a transiently-failed claim would execute and confirm PAST the hole; the
+ * failed operation's retry would then see `confirmed ≥ to` and silently skip
+ * — its money would never move while the ledger says it did. Throwing instead
+ * fails this operation's webhook event, and at-least-once delivery retries
+ * both operations until the predecessor fills its hole and each claimed slice
+ * has actually moved. The ledger's `reversedAmount` therefore always covers a
+ * solid, hole-free prefix of the reversed axis — which is exactly what makes
+ * the `confirmed`/`amount_reversed` checks above sound.
+ */
+export async function executeClaimedSlices(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  operationId: string,
+  claim: ReversalClaim,
+): Promise<{ reversals: { stripeTransferId: string; amount: number }[] }> {
+  const reversals: { stripeTransferId: string; amount: number }[] = [];
+  for (const slice of claim.slices) {
+    const receiptAmount = slice.to - slice.from;
+    if (slice.commissionTracked && claim.replay) {
+      const receipt = await findCommissionReversal(
+        stripe,
+        slice.stripeTransferId,
+        operationId,
+        receiptAmount,
+      );
+      if (receipt) {
+        await runMutationOrThrow(
+          ctx,
+          componentRef(component, "connect/mutations/recordTransferReversal"),
+          {
+            stripeTransferId: slice.stripeTransferId,
+            reversedAmount: slice.to,
+            receipt: {
+              stripeReversalId: receipt.id,
+              operationId,
+              amount: receiptAmount,
+            },
+          },
+        );
+        continue;
+      }
+      if (slice.confirmed >= slice.to)
+        throw new Error("Commission reversal requires receipt reconciliation.");
+    }
+    if (slice.confirmed >= slice.to) continue; // executed and recorded already
+
+    if (slice.confirmed < slice.from) {
+      throw new Error(
+        `reversal slice [${slice.from},${slice.to}) on ${slice.stripeTransferId} ` +
+          `blocked: predecessor claim unexecuted (confirmed=${slice.confirmed})`,
+      );
+    }
+
+    if (claim.replay && !slice.commissionTracked) {
+      const transfer = await stripe.transfers.retrieve(slice.stripeTransferId);
+      if ((transfer.amount_reversed ?? 0) >= slice.to) {
+        // The money moved on a previous attempt that died before confirming.
+        await runMutationOrThrow(
+          ctx,
+          componentRef(component, "connect/mutations/recordTransferReversal"),
+          {
+            stripeTransferId: slice.stripeTransferId,
+            reversedAmount: slice.to,
+          },
+        );
+        continue;
+      }
+    }
+
+    const amount = slice.to - slice.from;
+    const receipt = await stripe.transfers.createReversal(
+      slice.stripeTransferId,
+      {
+        amount,
+        ...(slice.commissionTracked
+          ? { metadata: { bsReversalOperation: operationId } }
+          : {}),
+      },
+      { idempotencyKey: `bs_rev_${operationId}_${slice.stripeTransferId}` },
+    );
+    await runMutationOrThrow(
+      ctx,
+      componentRef(component, "connect/mutations/recordTransferReversal"),
+      {
+        stripeTransferId: slice.stripeTransferId,
+        reversedAmount: slice.to,
+        ...(slice.commissionTracked
+          ? { receipt: { stripeReversalId: receipt.id, operationId, amount } }
+          : {}),
+      },
+    );
+    reversals.push({ stripeTransferId: slice.stripeTransferId, amount });
+  }
+  return { reversals };
+}

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

@@ -350,8 +350,8 @@ describe("createSplitTransfers engine (BTS-22)", () => {
       destination: "acct_aff",
     });
     // ledger rows
-    expect(ctx.runMutation).toHaveBeenCalledTimes(3);
-    expect(ctx.runMutation.mock.calls[1][1]).toMatchObject({
+    expect(ctx.runMutation).toHaveBeenCalledTimes(4);
+    expect(ctx.runMutation.mock.calls[2][1]).toMatchObject({
       sourceChargeId: "ch_1",
       destinationAccountId: "acct_store",
       amount: 8000,
@@ -380,7 +380,7 @@ describe("createSplitTransfers engine (BTS-22)", () => {
     });
 
     expect(stripe.transfers.create).toHaveBeenCalledTimes(3);
-    expect(ctx.runMutation).toHaveBeenCalledTimes(4);
+    expect(ctx.runMutation).toHaveBeenCalledTimes(5);
   });
 
   it("skips zero-amount transfers", async () => {