@fantastic.dev/better-stripe 0.9.0 → 0.10.1

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

package/src/client/customer-preview-thin.test.ts

@@ -0,0 +1,41 @@
+import { componentsGeneric } from "convex/server";
+import { expect, it, vi } from "vitest";
+import { handleV2Event } from "./webhooks/v2.js";
+import type { WebhookContext } from "./webhooks/helpers.js";
+import type { V2ThinEvent } from "./types.js";
+it("syncs a preview customer without requesting merchant, recipient or Connect requirements", async () => {
+  const retrieve = vi.fn().mockResolvedValue({
+    id: "acct_buyer",
+    metadata: { userId: "buyer" },
+    configuration: { customer: { applied: true } },
+    applied_configurations: ["customer"],
+    identity: { country: "us" },
+  });
+  const runMutation = vi.fn();
+  const ctx = {
+    component: componentsGeneric().betterStripe,
+    ctx: { runMutation },
+    stripe: { v2: { core: { accounts: { retrieve } } } },
+    config: { stripeApiVersion: "2026-09-30.preview" },
+  } as unknown as WebhookContext;
+  await handleV2Event(ctx, {
+    id: "evt_preview",
+    type: "v2.core.account[configuration.customer].updated",
+    context: "acct_merchant",
+    related_object: { id: "acct_buyer", type: "v2.core.account" },
+  } as V2ThinEvent);
+  expect(retrieve).toHaveBeenCalledWith(
+    "acct_buyer",
+    { include: ["configuration.customer", "identity"] },
+    { stripeContext: "acct_merchant" },
+  );
+  expect(runMutation).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.objectContaining({
+      userId: "buyer",
+      stripeAccountId: "acct_buyer",
+      appliedConfigurations: ["customer"],
+      onboardingStatus: "complete",
+    }),
+  );
+});

package/src/client/customer-preview-webhooks.test.ts

@@ -0,0 +1,150 @@
+import type Stripe from "stripe";
+import { componentsGeneric, type HttpRouter } from "convex/server";
+import { expect, it, vi } from "vitest";
+import { BetterStripe } from "./index.js";
+import type { Component, RunCtx } from "./helpers.js";
+import {
+  createWebhookEndpoint,
+  setupEventDestination,
+} from "./utils/webhookEndpoints.js";
+const handle = vi.hoisted(() => vi.fn(async () => new Response("ok")));
+vi.mock("./webhooks/handler.js", () => ({ handleWebhookRequest: handle }));
+const version = "2026-09-30.preview";
+const component = componentsGeneric().betterStripe as unknown as Component;
+it("instance routes inherit the selected client version and reject conflicting configuration", async () => {
+  const bs = new BetterStripe(component, {
+    STRIPE_SECRET_KEY: "sk_test_preview_routes",
+    stripeApiVersion: version,
+  });
+  const route = vi.fn();
+  bs.registerRoutes({ route } as unknown as HttpRouter, {
+    webhookSecret: "whsec_fixture",
+  });
+  const handler = route.mock.calls[0][0].handler as {
+    _handler: (ctx: unknown, request: Request) => Promise<Response>;
+  };
+  await handler._handler(
+    {},
+    new Request("https://example.com/stripe/webhook", { method: "POST" }),
+  );
+  expect(handle).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.anything(),
+    component,
+    expect.objectContaining({
+      stripeApiVersion: version,
+      stripeSecretKey: "sk_test_preview_routes",
+      webhookSecret: "whsec_fixture",
+    }),
+  );
+  expect(() =>
+    bs.registerRoutes({ route } as unknown as HttpRouter, {
+      stripeApiVersion: "2026-09-30.endive",
+    }),
+  ).toThrow("match");
+  expect(route).toHaveBeenCalledTimes(1);
+});
+function sdk() {
+  const raw = {
+    webhookEndpoints: {
+      list: vi.fn().mockResolvedValue({ data: [] }),
+      create: vi.fn().mockResolvedValue({
+        id: "we_preview",
+        url: "https://example.com/events",
+        secret: "whsec_fixture",
+      }),
+    },
+    v2: {
+      core: {
+        eventDestinations: {
+          list: vi.fn().mockResolvedValue({ data: [] }),
+          create: vi.fn().mockResolvedValue({
+            id: "ed_preview",
+            enabled_events: [],
+            webhook_endpoint: { signing_secret: "whsec_fixture" },
+          }),
+          update: vi.fn(),
+        },
+      },
+    },
+  };
+  return { raw, stripe: raw as unknown as Stripe };
+}
+it("pins snapshot payloads, leaves thin payloads unversioned, and uses canonical preview scopes", async () => {
+  const { raw, stripe } = sdk(),
+    ctx = {} as RunCtx;
+  await createWebhookEndpoint(stripe, ctx, {
+    url: "https://example.com/events",
+    apiVersion: version,
+  });
+  expect(raw.webhookEndpoints.create).toHaveBeenCalledWith(
+    expect.objectContaining({ api_version: version }),
+  );
+  await setupEventDestination(stripe, ctx, {
+    url: "https://example.com/events",
+    eventPayload: "snapshot",
+    apiVersion: version,
+  });
+  expect(raw.v2.core.eventDestinations.create).toHaveBeenLastCalledWith(
+    expect.objectContaining({
+      snapshot_api_version: version,
+      events_from: ["@self"],
+    }),
+  );
+  await setupEventDestination(stripe, ctx, {
+    url: "https://example.com/events",
+    eventPayload: "thin",
+    apiVersion: version,
+  });
+  const thin = raw.v2.core.eventDestinations.create.mock.calls[1][0];
+  expect(thin).not.toHaveProperty("snapshot_api_version");
+  expect(thin.events_from).toEqual(["@self", "@accounts"]);
+  expect(thin.enabled_events).toEqual([
+    "v2.core.account.created",
+    "v2.core.account[configuration.customer].updated",
+    "v2.core.account[identity].updated",
+  ]);
+});
+it("refuses to reuse a snapshot destination whose immutable version differs", async () => {
+  const { raw, stripe } = sdk();
+  raw.v2.core.eventDestinations.list.mockResolvedValue({
+    data: [
+      {
+        id: "ed_old",
+        event_payload: "snapshot",
+        snapshot_api_version: "2026-09-30.endive",
+        webhook_endpoint: { url: "https://example.com/events" },
+      },
+    ],
+  });
+  await expect(
+    setupEventDestination(stripe, {} as RunCtx, {
+      url: "https://example.com/events",
+      eventPayload: "snapshot",
+      apiVersion: version,
+    }),
+  ).rejects.toThrow("version");
+  expect(raw.v2.core.eventDestinations.update).not.toHaveBeenCalled();
+  expect(raw.v2.core.eventDestinations.create).not.toHaveBeenCalled();
+});
+it("refuses a preview thin destination that cannot deliver managed customer account events", async () => {
+  const { raw, stripe } = sdk();
+  raw.v2.core.eventDestinations.list.mockResolvedValue({
+    data: [
+      {
+        id: "ed_old",
+        event_payload: "thin",
+        events_from: ["@self"],
+        webhook_endpoint: { url: "https://example.com/events" },
+      },
+    ],
+  });
+  await expect(
+    setupEventDestination(stripe, {} as RunCtx, {
+      url: "https://example.com/events",
+      eventPayload: "thin",
+      apiVersion: version,
+    }),
+  ).rejects.toThrow("scope");
+  expect(raw.v2.core.eventDestinations.update).not.toHaveBeenCalled();
+});