@fantastic.dev/better-stripe 0.8.1 → 0.10.0

package/src/client/billing/providerReads.test.ts

@@ -0,0 +1,60 @@
+import type Stripe from "stripe";
+import { expect, it, vi } from "vitest";
+import {
+  getCheckoutSessionFromStripe,
+  getSubscriptionFromStripe,
+  getCouponFromStripe,
+} from "./providerReads.js";
+it("retrieves authoritative expanded provider objects without consulting the component cache", async () => {
+  const raw = {
+    checkout: {
+      sessions: {
+        retrieve: vi
+          .fn()
+          .mockResolvedValue({ id: "cs_1", payment_status: "paid" }),
+      },
+    },
+    subscriptions: {
+      retrieve: vi.fn().mockResolvedValue({ id: "sub_1", status: "active" }),
+    },
+    coupons: {
+      retrieve: vi.fn().mockResolvedValue({ id: "coupon_1", valid: true }),
+    },
+  };
+  const stripe = raw as unknown as Stripe;
+  expect(
+    await getCheckoutSessionFromStripe(stripe, {
+      stripeSessionId: "cs_1",
+      expand: ["subscription", "payment_intent"],
+    }),
+  ).toMatchObject({ payment_status: "paid" });
+  expect(raw.checkout.sessions.retrieve).toHaveBeenCalledWith("cs_1", {
+    expand: ["subscription", "payment_intent"],
+  });
+  await getSubscriptionFromStripe(stripe, {
+    stripeSubscriptionId: "sub_1",
+    expand: ["latest_invoice"],
+  });
+  expect(raw.subscriptions.retrieve).toHaveBeenCalledWith("sub_1", {
+    expand: ["latest_invoice"],
+  });
+  await getCouponFromStripe(stripe, { stripeCouponId: "coupon_1" });
+  expect(raw.coupons.retrieve).toHaveBeenCalledWith("coupon_1", {
+    expand: undefined,
+  });
+});
+
+it("preserves Stripe error identity and codes for server reconciliation", async () => {
+  const failure = Object.assign(new Error("No such Checkout Session"), {
+    code: "resource_missing",
+    statusCode: 404,
+  });
+  const raw = {
+    checkout: { sessions: { retrieve: vi.fn().mockRejectedValue(failure) } },
+  };
+  await expect(
+    getCheckoutSessionFromStripe(raw as unknown as Stripe, {
+      stripeSessionId: "cs_missing",
+    }),
+  ).rejects.toBe(failure);
+});

package/src/client/billing/providerReads.ts

@@ -0,0 +1,30 @@
+import type Stripe from "stripe";
+export type CheckoutSessionReadOptions = {
+  stripeSessionId: string;
+  expand?: string[];
+};
+export type SubscriptionReadOptions = {
+  stripeSubscriptionId: string;
+  expand?: string[];
+};
+export type CouponReadOptions = { stripeCouponId: string; expand?: string[] };
+/** Authoritative Stripe objects for authorized server fulfillment/reconciliation. */
+export function getCheckoutSessionFromStripe(
+  stripe: Stripe,
+  opts: CheckoutSessionReadOptions,
+) {
+  return stripe.checkout.sessions.retrieve(opts.stripeSessionId, {
+    expand: opts.expand,
+  });
+}
+export function getSubscriptionFromStripe(
+  stripe: Stripe,
+  opts: SubscriptionReadOptions,
+) {
+  return stripe.subscriptions.retrieve(opts.stripeSubscriptionId, {
+    expand: opts.expand,
+  });
+}
+export function getCouponFromStripe(stripe: Stripe, opts: CouponReadOptions) {
+  return stripe.coupons.retrieve(opts.stripeCouponId, { expand: opts.expand });
+}

package/src/client/billing/subscriptions.ts

@@ -511,14 +511,7 @@ export async function upsertSubscription(
     accountId?: string;
     userId: string;
     orgId?: string;
-    status:
-      | "active"
-      | "trialing"
-      | "past_due"
-      | "canceled"
-      | "incomplete"
-      | "unpaid"
-      | "paused";
+    status: SubscriptionStatus;
     priceId?: string;
     quantity?: number;
     currentPeriodStart?: string;

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

@@ -0,0 +1,91 @@
+import type Stripe from "stripe";
+import { expect, it, vi } from "vitest";
+import { getPayoutSnapshot } from "./payoutSnapshot.js";
+const payout = (id: string, status = "paid") => ({
+  id,
+  status,
+  amount: 1000,
+  currency: "usd",
+  arrival_date: 0,
+  created: 1,
+});
+it("scopes every read and uses a real cursor for history while completing upcoming pages", async () => {
+  const list = vi.fn(
+    async (
+      args: { status?: string; starting_after?: string },
+      _options: { stripeAccount: string },
+    ) => {
+      void _options;
+      if (args.status === "pending")
+        return args.starting_after
+          ? { data: [payout("po_2", "pending")], has_more: false }
+          : { data: [payout("po_1", "pending")], has_more: true };
+      if (args.status === "in_transit")
+        return { data: [payout("po_1", "pending")], has_more: false };
+      return { data: [payout("po_history")], has_more: true };
+    },
+  );
+  const raw = {
+    balance: {
+      retrieve: vi.fn().mockResolvedValue({
+        available: [{ currency: "usd", amount: 10 }],
+        pending: [{ currency: "eur", amount: 20 }],
+      }),
+    },
+    payouts: { list },
+  };
+  const result = await getPayoutSnapshot(raw as unknown as Stripe, {
+    stripeAccountId: "acct_a",
+    cursor: "po_before",
+  });
+  expect(result).toMatchObject({
+    status: "ready",
+    balances: [
+      { currency: "usd", available: 10, pending: 0 },
+      { currency: "eur", available: 0, pending: 20 },
+    ],
+    nextCursor: "po_history",
+    upcomingComplete: true,
+  });
+  expect(result.upcoming.map((r) => r.id)).toEqual(["po_1", "po_2"]);
+  expect(result.upcoming[0].arrivalDate).toBeNull();
+  expect(list).toHaveBeenCalledWith(
+    expect.objectContaining({ starting_after: "po_before" }),
+    { stripeAccount: "acct_a" },
+  );
+  expect(
+    list.mock.calls.every(
+      (call) =>
+        (call[1] as { stripeAccount: string }).stripeAccount === "acct_a",
+    ),
+  ).toBe(true);
+});
+it("reports bounded upcoming previews and not-ready accounts explicitly", async () => {
+  const raw = {
+    balance: {
+      retrieve: vi.fn().mockResolvedValue({ available: [], pending: [] }),
+    },
+    payouts: {
+      list: vi.fn().mockResolvedValue({
+        data: [payout("po_1", "pending")],
+        has_more: true,
+      }),
+    },
+  };
+  expect(
+    await getPayoutSnapshot(raw as unknown as Stripe, {
+      stripeAccountId: "acct_a",
+      maxUpcomingPages: 1,
+    }),
+  ).toMatchObject({ upcomingComplete: false });
+  raw.balance.retrieve.mockRejectedValue({ code: "account_invalid" });
+  expect(
+    await getPayoutSnapshot(raw as unknown as Stripe, {
+      stripeAccountId: "acct_a",
+    }),
+  ).toMatchObject({
+    status: "not_ready",
+    balances: [],
+    reason: "account_unavailable",
+  });
+});

package/src/client/connect/payoutSnapshot.ts

@@ -0,0 +1,130 @@
+import type Stripe from "stripe";
+import { throwStripeError } from "../errors.js";
+import { getAccountBalance, type AccountBalance } from "./payouts.js";
+export type RecipientPayoutRow = {
+  id: string;
+  amount: number;
+  currency: string;
+  status: string;
+  arrivalDate: number | null;
+  created: number;
+};
+export type RecipientPayoutSnapshot = {
+  balances: AccountBalance[];
+  payouts: RecipientPayoutRow[];
+  upcoming: RecipientPayoutRow[];
+  nextCursor: string | null;
+  status: "ready" | "not_ready";
+  reason?: string;
+  upcomingComplete: boolean;
+};
+export type PayoutSnapshotOptions = {
+  stripeAccountId: string;
+  cursor?: string;
+  limit?: number;
+  maxUpcomingPages?: number;
+};
+const row = (p: Stripe.Payout): RecipientPayoutRow => ({
+  id: p.id,
+  amount: p.amount,
+  currency: p.currency,
+  status: p.status,
+  arrivalDate: p.arrival_date ? p.arrival_date * 1000 : null,
+  created: p.created * 1000,
+});
+/** Account-scoped live balance and cursor history. Upcoming truncation is explicit. */
+export async function getPayoutSnapshot(
+  stripe: Stripe,
+  opts: PayoutSnapshotOptions,
+): Promise<RecipientPayoutSnapshot> {
+  const limit = opts.limit ?? 100,
+    maxPages = opts.maxUpcomingPages ?? 10;
+  if (
+    !opts.stripeAccountId ||
+    !Number.isInteger(limit) ||
+    limit < 1 ||
+    limit > 100 ||
+    !Number.isInteger(maxPages) ||
+    maxPages < 1 ||
+    maxPages > 100
+  )
+    throwStripeError(
+      "INVALID_CONFIGURATION",
+      "Invalid payout account or page bounds.",
+    );
+  const options = { stripeAccount: opts.stripeAccountId };
+  async function upcoming(status: "pending" | "in_transit") {
+    const rows: Stripe.Payout[] = [];
+    let cursor: string | undefined;
+    for (let page = 0; page < maxPages; page++) {
+      const batch = await stripe.payouts.list(
+        { status, limit: 100, starting_after: cursor },
+        options,
+      );
+      rows.push(...batch.data);
+      if (!batch.has_more) return { rows, complete: true };
+      const next = batch.data[batch.data.length - 1]?.id;
+      if (!next || next === cursor)
+        throwStripeError(
+          "STRIPE_API_ERROR",
+          "Stripe payout pagination did not advance.",
+        );
+      cursor = next;
+    }
+    return { rows, complete: false };
+  }
+  try {
+    const [balances, history, pending, transit] = await Promise.all([
+      getAccountBalance(stripe, opts),
+      stripe.payouts.list({ limit, starting_after: opts.cursor }, options),
+      upcoming("pending"),
+      upcoming("in_transit"),
+    ]);
+    const rows = [
+      ...new Map(
+        [...pending.rows, ...transit.rows]
+          .filter((p) => p.status === "pending" || p.status === "in_transit")
+          .map((p) => [p.id, row(p)]),
+      ).values(),
+    ].sort(
+      (a, b) =>
+        (a.arrivalDate ?? Infinity) - (b.arrivalDate ?? Infinity) ||
+        a.created - b.created,
+    );
+    if (history.has_more && !history.data.length)
+      throwStripeError(
+        "STRIPE_API_ERROR",
+        "Stripe payout history did not advance.",
+      );
+    return {
+      status: "ready",
+      balances,
+      payouts: history.data.map(row),
+      upcoming: rows,
+      nextCursor: history.has_more
+        ? history.data[history.data.length - 1]!.id
+        : null,
+      upcomingComplete: pending.complete && transit.complete,
+    };
+  } catch (error) {
+    if (
+      error &&
+      typeof error === "object" &&
+      "code" in error &&
+      ["account_invalid", "resource_missing"].includes(String(error.code))
+    )
+      return {
+        status: "not_ready",
+        reason: "account_unavailable",
+        balances: [],
+        payouts: [],
+        upcoming: [],
+        nextCursor: null,
+        upcomingComplete: true,
+      };
+    throwStripeError(
+      "STRIPE_API_ERROR",
+      "Could not retrieve recipient payout snapshot.",
+    );
+  }
+}

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

@@ -28,7 +28,11 @@ function makeComponent(): Component {
 function plainCtx() {
   return {
     runQuery: vi.fn().mockResolvedValue(null),
-    runMutation: vi.fn().mockResolvedValue(undefined),
+    runMutation: vi.fn(async (ref: Record<symbol, string>, args: unknown) =>
+      ref[TO_REF].endsWith("settlement/mutations/reserveSettlementAllocation")
+        ? args
+        : undefined,
+    ),
   } as unknown as RunCtx & {
     runQuery: ReturnType<typeof vi.fn>;
     runMutation: ReturnType<typeof vi.fn>;
@@ -47,6 +51,8 @@ function makeCtx(transfers: unknown[]) {
   const runMutation = vi.fn(
     async (refObj: Record<symbol, string>, args: Record<string, unknown>) => {
       const path = refObj[TO_REF].replace(/^betterStripe\//, "");
+      if (path === "settlement/mutations/reserveSettlementAllocation")
+        return args;
       if (path !== "connect/mutations/claimReversalSlices") return undefined;
       const legs = transfers as {
         stripeTransferId: string;
@@ -88,7 +94,9 @@ function makeCtx(transfers: unknown[]) {
 let trSeq = 0;
 function makeStripe() {
   return {
+    charges: { retrieve: vi.fn().mockResolvedValue({ created: 1 }) },
     transfers: {
+      list: vi.fn().mockResolvedValue({ data: [], has_more: false }),
       createReversal: vi.fn().mockResolvedValue({ id: "trr_1" }),
       create: vi.fn(async (_params: unknown) => ({ id: `tr_new_${++trSeq}` })),
     },
@@ -342,8 +350,8 @@ describe("createSplitTransfers engine (BTS-22)", () => {
       destination: "acct_aff",
     });
     // ledger rows
-    expect(ctx.runMutation).toHaveBeenCalledTimes(2);
-    expect(ctx.runMutation.mock.calls[0][1]).toMatchObject({
+    expect(ctx.runMutation).toHaveBeenCalledTimes(3);
+    expect(ctx.runMutation.mock.calls[1][1]).toMatchObject({
       sourceChargeId: "ch_1",
       destinationAccountId: "acct_store",
       amount: 8000,
@@ -372,7 +380,7 @@ describe("createSplitTransfers engine (BTS-22)", () => {
     });
 
     expect(stripe.transfers.create).toHaveBeenCalledTimes(3);
-    expect(ctx.runMutation).toHaveBeenCalledTimes(3);
+    expect(ctx.runMutation).toHaveBeenCalledTimes(4);
   });
 
   it("skips zero-amount transfers", async () => {
@@ -403,6 +411,7 @@ describe("createSplitTransfers idempotency (BTS-24)", () => {
         destinationAccountId: "acct_store",
         role: "store",
         amount: 8000,
+        currency: "usd",
       },
     ]);
 
@@ -431,12 +440,14 @@ describe("createSplitTransfers idempotency (BTS-24)", () => {
         destinationAccountId: "acct_store",
         role: "store",
         amount: 8000,
+        currency: "usd",
       },
       {
         stripeTransferId: "tr_aff",
         destinationAccountId: "acct_aff",
         role: "affiliate",
         amount: 1000,
+        currency: "usd",
       },
     ]);
 

package/src/client/connect/transfers.ts

@@ -1,3 +1,5 @@
+import { recoverSettlementTransfers } from "../settlement/reconciliation.js";
+import { executeResolvedTransfers } from "../settlement/execution.js";
 import type Stripe from "stripe";
 
 import type { SplitRecipient } from "../../component/lib/fees.js";
@@ -303,6 +305,7 @@ export async function reverseTransfers(
     throw new Error("reverseTransfers: amount must be a non-negative integer");
   }
 
+  await recoverSettlementTransfers(stripe, component, ctx, opts.sourceChargeId);
   if (opts.operationId) {
     const claim = (await runMutationOrThrow(
       ctx,
@@ -421,6 +424,7 @@ export async function reverseTransfersForRefund(
     return { reversals: [] };
   }
 
+  await recoverSettlementTransfers(stripe, component, ctx, opts.sourceChargeId);
   const claim = (await runMutationOrThrow(
     ctx,
     componentRef(component, "connect/mutations/claimReversalSlices"),
@@ -460,48 +464,15 @@ export async function createSplitTransfers(
 ): Promise<SplitResult> {
   const result = computeSplit(opts.amount, opts.feeConfig, opts.split);
 
-  // Ledger-level idempotency (BTS-24): skip any (charge, destination, role) leg
-  // already recorded, so a webhook retry — even after a partial run — never
-  // double-transfers. Complements the deterministic Stripe idempotency key.
-  const existing = ((await ctx.runQuery(
-    componentRef(component, "connect/queries/listTransfersByCharge"),
-    { sourceChargeId: opts.sourceChargeId },
-  )) ?? []) as LedgerTransfer[];
-  const done = new Set(
-    existing.map((t) => `${t.destinationAccountId}:${t.role ?? ""}`),
-  );
-
-  for (const t of result.transfers) {
-    if (t.amount <= 0) continue;
-    if (done.has(`${t.destinationAccountId}:${t.role}`)) continue;
-    const transfer = await stripe.transfers.create(
-      {
-        amount: t.amount,
-        currency: opts.currency,
-        destination: t.destinationAccountId,
-        source_transaction: opts.sourceChargeId,
-        metadata: { bsRole: t.role, bsSourceCharge: opts.sourceChargeId },
-      },
-      // Deterministic key so a webhook retry can't double-transfer (BTS-24).
-      {
-        idempotencyKey: `bs_split_${opts.sourceChargeId}_${t.destinationAccountId}_${t.role}`,
-      },
-    );
-    await runMutationOrThrow(
-      ctx,
-      componentRef(component, "connect/mutations/upsertTransfer"),
-      {
-        stripeTransferId: transfer.id,
-        sourceChargeId: opts.sourceChargeId,
-        destinationAccountId: t.destinationAccountId,
-        amount: t.amount,
-        currency: opts.currency,
-        role: t.role,
-        status: "paid" as const,
-        paymentId: opts.paymentId,
-      },
-    );
-  }
+  await executeResolvedTransfers(stripe, component, ctx, {
+    sourceChargeId: opts.sourceChargeId,
+    gross: opts.amount,
+    currency: opts.currency,
+    processingFee: 0,
+    platformNet: result.platformRetained,
+    transfers: result.transfers,
+    paymentId: opts.paymentId,
+  });
 
   return result;
 }

package/src/client/core/account-idempotency.test.ts

@@ -0,0 +1,78 @@
+// @vitest-environment edge-runtime
+import type Stripe from "stripe";
+import { convexTest } from "convex-test";
+import { componentsGeneric, defineSchema } from "convex/server";
+import { expect, it, vi } from "vitest";
+import componentSchema from "../../component/schema.js";
+import type { Component, RunCtx } from "../helpers.js";
+import { createAccount, getOrCreateAccount } from "./accounts.js";
+const modules = import.meta.glob("../../component/**/*.*s");
+it("reuses one provider account for concurrent calls and recovers a persistence failure", async () => {
+  const t = convexTest(defineSchema({}), modules);
+  t.registerComponent("betterStripe", componentSchema, modules);
+  const component = componentsGeneric().betterStripe as unknown as Component;
+  const provider = new Map<string, { params: string; id: string }>();
+  let created = 0;
+  const sdk = {
+    v2: {
+      core: {
+        accounts: {
+          create: vi.fn(
+            async (params: unknown, options?: { idempotencyKey?: string }) => {
+              const key = options?.idempotencyKey ?? `unkeyed-${++created}`,
+                existing = provider.get(key),
+                fingerprint = JSON.stringify(params);
+              if (existing && existing.params !== fingerprint)
+                throw new Error("idempotency_error");
+              if (existing) return { id: existing.id };
+              const value = { params: fingerprint, id: `acct_${++created}` };
+              provider.set(key, value);
+              return { id: value.id };
+            },
+          ),
+        },
+      },
+    },
+  };
+  let fail = true;
+  const ctx: RunCtx = {
+    runQuery: t.query as RunCtx["runQuery"],
+    runMutation: (async (
+      ref: Parameters<typeof t.mutation>[0],
+      args: Record<string, unknown>,
+    ) => {
+      if (fail) {
+        fail = false;
+        throw new Error("persistence unavailable");
+      }
+      return t.mutation(ref, args);
+    }) as RunCtx["runMutation"],
+  };
+  const opts = {
+    userId: "buyer",
+    email: "buyer@example.com",
+    idempotencyKey: "account:buyer:v1",
+  };
+  await expect(
+    createAccount(sdk as unknown as Stripe, component, ctx, opts),
+  ).rejects.toThrow("persistence unavailable");
+  const [a, b] = await Promise.all([
+    getOrCreateAccount(sdk as unknown as Stripe, component, ctx, opts),
+    getOrCreateAccount(sdk as unknown as Stripe, component, ctx, opts),
+  ]);
+  expect(a.stripeAccountId).toBe(b.stripeAccountId);
+  expect(provider.size).toBe(1);
+  expect(sdk.v2.core.accounts.create).toHaveBeenCalledWith(expect.anything(), {
+    idempotencyKey: opts.idempotencyKey,
+  });
+  await expect(
+    createAccount(sdk as unknown as Stripe, component, ctx, {
+      ...opts,
+      email: "changed@example.com",
+    }),
+  ).rejects.toThrow("idempotency_error");
+  const row = await t.query(component.core.queries.getAccountByUserId, {
+    userId: "buyer",
+  });
+  expect(row?.stripeAccountId).toBe(a.stripeAccountId);
+});

package/src/client/core/accounts.ts

@@ -1,3 +1,14 @@
+import { idempotencyOptions } from "./idempotency.js";
+export type CreateAccountOptions = {
+  userId: string;
+  email?: string;
+  name?: string;
+  country?: string;
+  orgId?: string;
+  metadata?: Record<string, string>;
+  /** Stable account-provisioning key; use a different key for a different account. */
+  idempotencyKey?: string;
+};
 import type Stripe from "stripe";
 
 import type { Component, RunCtx } from "../helpers.js";
@@ -31,14 +42,7 @@ export async function createAccount(
   stripe: Stripe,
   component: Component,
   ctx: RunCtx,
-  opts: {
-    userId: string;
-    email?: string;
-    name?: string;
-    country?: string;
-    orgId?: string;
-    metadata?: Record<string, string>;
-  },
+  opts: CreateAccountOptions,
 ) {
   const metadata = {
     ...(opts.metadata ?? {}),
@@ -56,7 +60,10 @@ export async function createAccount(
     };
   }
 
-  const account = await stripe.v2.core.accounts.create(createParams);
+  const requestOptions = idempotencyOptions(opts.idempotencyKey);
+  const account = requestOptions
+    ? await stripe.v2.core.accounts.create(createParams, requestOptions)
+    : await stripe.v2.core.accounts.create(createParams);
 
   await runMutationOrThrow(
     ctx,
@@ -191,14 +198,7 @@ export async function getOrCreateAccount(
   stripe: Stripe,
   component: Component,
   ctx: RunCtx,
-  opts: {
-    userId: string;
-    email?: string;
-    name?: string;
-    country?: string;
-    orgId?: string;
-    metadata?: Record<string, string>;
-  },
+  opts: CreateAccountOptions,
 ) {
   const existing = opts.orgId
     ? await ctx.runQuery(
@@ -238,14 +238,7 @@ export async function ensureCustomerAccount(
   stripe: Stripe,
   component: Component,
   ctx: RunCtx,
-  opts: {
-    userId: string;
-    email?: string;
-    name?: string;
-    country?: string;
-    orgId?: string;
-    metadata?: Record<string, string>;
-  },
+  opts: CreateAccountOptions,
 ): Promise<{
   stripeAccountId: string;
   accountId: string | null;

package/src/client/core/idempotency.test.ts

@@ -0,0 +1,10 @@
+import { expect, it } from "vitest";
+import { idempotencyOptions } from "./idempotency.js";
+it("preserves omitted options and validates explicit request identities", () => {
+  expect(idempotencyOptions(undefined)).toBeUndefined();
+  expect(idempotencyOptions("logical-order:123")).toEqual({
+    idempotencyKey: "logical-order:123",
+  });
+  for (const key of ["", "  ", "bad\nkey", "x".repeat(256)])
+    expect(() => idempotencyOptions(key)).toThrow();
+});

package/src/client/core/idempotency.ts

@@ -0,0 +1,11 @@
+import { throwStripeError } from "../errors.js";
+/** Explicit request identity. Omission preserves the SDK's existing behavior. */
+export function idempotencyOptions(key: string | undefined) {
+  if (key === undefined) return undefined;
+  if (!key.trim() || key.length > 255 || /[\r\n]/.test(key))
+    throwStripeError(
+      "INVALID_CONFIGURATION",
+      "Idempotency keys must be nonempty, at most 255 characters, and contain no line breaks.",
+    );
+  return { idempotencyKey: key };
+}