@fantastic.dev/better-stripe 0.23.2 → 0.25.0

package/src/client/billing/prepared-checkout.test.ts

@@ -0,0 +1,430 @@
+import { expect, it, vi } from "vitest";
+import type Stripe from "stripe";
+import type { Component, RunCtx } from "../helpers.js";
+import type { CreateCheckoutSessionOptions } from "./checkoutOptions.js";
+
+async function contract() {
+  const path = "./preparedCheckout.js";
+  const mod = await import(path).catch(() => ({}));
+  expect(
+    mod.prepareCheckoutSession,
+    "package-owned preparation is missing",
+  ).toBeTypeOf("function");
+  expect(
+    mod.executePreparedCheckoutSession,
+    "package-owned prepared execution is missing",
+  ).toBeTypeOf("function");
+  return mod;
+}
+function fixture() {
+  const create = vi.fn().mockResolvedValue({
+    id: "cs_one",
+    status: "open",
+    client_secret: "secret_one",
+    url: null,
+  });
+  const provider = {
+    checkout: { sessions: { create } },
+    prices: { retrieve: vi.fn().mockResolvedValue({ id: "price_one" }) },
+  } as unknown as Stripe;
+  const runMutation = vi.fn().mockResolvedValue(null);
+  const runQuery = vi.fn().mockResolvedValue(null);
+  const ctx = { runMutation, runQuery } as unknown as RunCtx;
+  const component = {
+    billing: {
+      mutations: {
+        upsertCheckoutSession: {
+          [Symbol.for("toReferencePath")]:
+            "betterStripe/billing/mutations/upsertCheckoutSession",
+        },
+      },
+    },
+  } as unknown as Component;
+  const options: CreateCheckoutSessionOptions = {
+    userId: "buyer_one",
+    stripePriceId: "price_one",
+    mode: "subscription",
+    accountId: "acct_buyer",
+    returnUrl: "https://example.com/return",
+    metadata: { intentId: "intent_one", episodeId: "episode_one" },
+    trialDays: 0,
+    sessionOverrides: {
+      allowed_payment_method_types: ["card"],
+      subscription_data: {
+        metadata: {
+          userId: "buyer_one",
+          intentId: "intent_one",
+          episodeId: "episode_one",
+        },
+      },
+    },
+  };
+  return { create, provider, runMutation, runQuery, ctx, component, options };
+}
+it("prepares the exact serializable provider request without a provider or component write", async () => {
+  const api = await contract();
+  const s = fixture();
+  const prepared = await api.prepareCheckoutSession(
+    s.provider,
+    s.component,
+    s.ctx,
+    s.options,
+  );
+  expect(prepared.request).toMatchObject({
+    mode: "subscription",
+    customer_account: "acct_buyer",
+    line_items: [{ price: "price_one", quantity: 1 }],
+    metadata: {
+      userId: "buyer_one",
+      intentId: "intent_one",
+      episodeId: "episode_one",
+    },
+    subscription_data: {
+      metadata: {
+        userId: "buyer_one",
+        intentId: "intent_one",
+        episodeId: "episode_one",
+      },
+    },
+  });
+  expect(prepared.request.subscription_data.trial_period_days).toBeUndefined();
+  expect(JSON.parse(JSON.stringify(prepared))).toEqual(prepared);
+  expect(s.create).not.toHaveBeenCalled();
+  expect(s.runMutation).not.toHaveBeenCalled();
+});
+it("executes a persisted request unchanged with explicit idempotency and correlated component metadata", async () => {
+  const api = await contract();
+  const s = fixture();
+  const prepared = JSON.parse(
+    JSON.stringify(
+      await api.prepareCheckoutSession(
+        s.provider,
+        s.component,
+        s.ctx,
+        s.options,
+      ),
+    ),
+  );
+  s.options.metadata = { intentId: "changed" };
+  s.options.accountId = "acct_changed";
+  s.options.trialDays = 30;
+  expect(
+    await api.executePreparedCheckoutSession(s.provider, s.component, s.ctx, {
+      prepared,
+      idempotencyKey: "intent-one-checkout",
+    }),
+  ).toEqual({
+    stripeSessionId: "cs_one",
+    clientSecret: "secret_one",
+    url: undefined,
+  });
+  expect(s.create).toHaveBeenCalledWith(prepared.request, {
+    idempotencyKey: "intent-one-checkout",
+  });
+  expect(s.runMutation.mock.calls[0][1]).toMatchObject({
+    userId: "buyer_one",
+    accountId: "acct_buyer",
+    priceId: "price_one",
+    metadata: { intentId: "intent_one", episodeId: "episode_one" },
+  });
+});
+
+it.each([
+  { metadata: { userId: "foreign_buyer" } },
+  { customer_account: "acct_foreign" },
+  { line_items: [{ price: "price_foreign", quantity: 1 }] },
+])(
+  "rejects provider overrides that change owned correlation %j before writes",
+  async (patch) => {
+    const api = await contract();
+    const s = fixture();
+    s.options.sessionOverrides = { ...s.options.sessionOverrides, ...patch };
+    await expect(
+      api.prepareCheckoutSession(s.provider, s.component, s.ctx, s.options),
+    ).rejects.toThrow("Prepared Checkout correlation does not match.");
+    expect(s.create).not.toHaveBeenCalled();
+    expect(s.runMutation).not.toHaveBeenCalled();
+  },
+);
+
+it("exposes preparation and execution on the actual BetterStripe client", async () => {
+  const { BetterStripe } = await import("../index.js");
+  const s = fixture();
+  const client = new BetterStripe(s.component as never, {
+    STRIPE_SECRET_KEY: "sk_test_fake",
+  });
+  expect(client.checkoutRequests?.prepare).toBeTypeOf("function");
+  expect(client.checkoutRequests?.execute).toBeTypeOf("function");
+});
+it.each([undefined, "", "bad\nkey"])(
+  "requires an explicit valid prepared execution key %j",
+  async (key) => {
+    const api = await contract();
+    const s = fixture();
+    const prepared = await api.prepareCheckoutSession(
+      s.provider,
+      s.component,
+      s.ctx,
+      s.options,
+    );
+    await expect(
+      api.executePreparedCheckoutSession(s.provider, s.component, s.ctx, {
+        prepared,
+        idempotencyKey: key,
+      }),
+    ).rejects.toThrow();
+    expect(s.create).not.toHaveBeenCalled();
+  },
+);
+it("does not execute changed prepared parameters or component correlation", async () => {
+  const api = await contract();
+  const s = fixture();
+  const prepared = await api.prepareCheckoutSession(
+    s.provider,
+    s.component,
+    s.ctx,
+    s.options,
+  );
+  for (const changed of [
+    {
+      ...prepared,
+      request: { ...prepared.request, return_url: "https://foreign.example" },
+    },
+    { ...prepared, row: { ...prepared.row, userId: "foreign" } },
+  ]) {
+    await expect(
+      api.executePreparedCheckoutSession(s.provider, s.component, s.ctx, {
+        prepared: changed,
+        idempotencyKey: "same-intent",
+      }),
+    ).rejects.toThrow();
+  }
+  expect(s.create).not.toHaveBeenCalled();
+});
+it("retries the exact provider request after a lost component response", async () => {
+  const api = await contract();
+  const s = fixture();
+  const prepared = await api.prepareCheckoutSession(
+    s.provider,
+    s.component,
+    s.ctx,
+    s.options,
+  );
+  s.runMutation.mockRejectedValueOnce(new Error("Lost component response"));
+  const args = { prepared, idempotencyKey: "same-intent" };
+  await expect(
+    api.executePreparedCheckoutSession(s.provider, s.component, s.ctx, args),
+  ).rejects.toThrow("Lost component response");
+  await api.executePreparedCheckoutSession(
+    s.provider,
+    s.component,
+    s.ctx,
+    args,
+  );
+  expect(s.create.mock.calls).toEqual([
+    [prepared.request, { idempotencyKey: "same-intent" }],
+    [prepared.request, { idempotencyKey: "same-intent" }],
+  ]);
+});
+
+it("freezes fee and descriptor reads before execution even when configuration changes", async () => {
+  const api = await contract();
+  const s = fixture();
+  s.runQuery.mockImplementation(async (ref: Record<symbol, string>) =>
+    ref[Symbol.for("toReferencePath")].endsWith(
+      "core/queries/getAccountByStripeId",
+    )
+      ? { statementDescriptor: "ORIGINAL" }
+      : null,
+  );
+  const opts = {
+    ...s.options,
+    destinationAccountId: "acct_seller",
+    feeConfig: { percent: 10 },
+    defaultStatementDescriptorSuffix: "DEFAULT",
+    sessionOverrides: { allowed_payment_method_types: ["card"] },
+  };
+  const prepared = await api.prepareCheckoutSession(
+    s.provider,
+    s.component,
+    s.ctx,
+    opts,
+  );
+  expect(prepared.request.subscription_data).toMatchObject({
+    application_fee_percent: 10,
+    transfer_data: { destination: "acct_seller" },
+    metadata: { bsStatementDescriptor: "ORIGINAL" },
+  });
+  s.runQuery.mockClear();
+  s.runQuery.mockResolvedValue({ statementDescriptor: "CHANGED" });
+  opts.feeConfig.percent = 40;
+  opts.defaultStatementDescriptorSuffix = "CHANGED";
+  await api.executePreparedCheckoutSession(s.provider, s.component, s.ctx, {
+    prepared,
+    idempotencyKey: "frozen-defaults",
+  });
+  expect(s.create).toHaveBeenCalledWith(prepared.request, {
+    idempotencyKey: "frozen-defaults",
+  });
+  expect(
+    s.runQuery.mock.calls.some(([ref]) =>
+      ref[Symbol.for("toReferencePath")].endsWith(
+        "core/queries/getAccountByStripeId",
+      ),
+    ),
+  ).toBe(false);
+});
+it("rejects nested reserved split instructions injected by overrides", async () => {
+  const api = await contract();
+  const s = fixture();
+  s.options.sessionOverrides = {
+    subscription_data: {
+      metadata: {
+        userId: "buyer_one",
+        intentId: "intent_one",
+        episodeId: "episode_one",
+        bsChargeType: "separate",
+        bsSplit: "forged",
+      },
+    },
+  };
+  await expect(
+    api.prepareCheckoutSession(s.provider, s.component, s.ctx, s.options),
+  ).rejects.toThrow("Prepared Checkout routing metadata does not match.");
+  expect(s.create).not.toHaveBeenCalled();
+});
+it("rejects executing a different key from an explicitly prepared key", async () => {
+  const api = await contract();
+  const s = fixture();
+  s.options.idempotencyKey = "original-key";
+  const prepared = await api.prepareCheckoutSession(
+    s.provider,
+    s.component,
+    s.ctx,
+    s.options,
+  );
+  await expect(
+    api.executePreparedCheckoutSession(s.provider, s.component, s.ctx, {
+      prepared,
+      idempotencyKey: "changed-key",
+    }),
+  ).rejects.toThrow("Prepared Checkout idempotency key does not match.");
+  expect(s.create).not.toHaveBeenCalled();
+});
+
+it("runs the public client contract using resolved fee defaults and the actual provider boundary", async () => {
+  const { BetterStripe } = await import("../index.js");
+  const s = fixture();
+  const client = new BetterStripe(s.component as never, {
+    STRIPE_SECRET_KEY: "sk_test_fake",
+    platformFee: { percent: 10 },
+    statementDescriptorSuffix: "DOJO",
+  });
+  vi.spyOn(
+    client as unknown as { stripe: () => Stripe },
+    "stripe",
+  ).mockReturnValue(s.provider);
+  const prepared = await client.checkoutRequests.prepare(s.ctx, {
+    ...s.options,
+    destinationAccountId: "acct_seller",
+    sessionOverrides: { allowed_payment_method_types: ["card"] },
+  });
+  expect(prepared.request.subscription_data).toMatchObject({
+    application_fee_percent: 10,
+    metadata: { bsStatementDescriptor: "DOJO" },
+  });
+  await client.checkoutRequests.execute(s.ctx, {
+    prepared,
+    idempotencyKey: "public-client-intent",
+  });
+  expect(s.create).toHaveBeenCalledWith(prepared.request, {
+    idempotencyKey: "public-client-intent",
+  });
+});
+
+it.each(["subscription", "payment"] as const)(
+  "preserves generated split routing through prepared %s execution",
+  async (mode) => {
+    const api = await contract();
+    const s = fixture();
+    const opts = {
+      ...s.options,
+      mode,
+      sessionOverrides: { allowed_payment_method_types: ["card"] },
+      split: [
+        {
+          destinationAccountId: "acct_seller",
+          role: "store" as const,
+          percent: 80,
+        },
+        {
+          destinationAccountId: "acct_affiliate",
+          role: "affiliate" as const,
+          percent: 10,
+        },
+      ],
+      feeConfig: { percent: 5 },
+    };
+    const prepared = await api.prepareCheckoutSession(
+      s.provider,
+      s.component,
+      s.ctx,
+      opts,
+    );
+    const nested =
+      mode === "subscription"
+        ? prepared.request.subscription_data
+        : prepared.request.payment_intent_data;
+    expect(nested.metadata).toMatchObject({
+      bsChargeType: "separate",
+      bsSplit: JSON.stringify(prepared.options.split),
+      bsFeeConfig: JSON.stringify(prepared.options.feeConfig),
+    });
+    expect(nested.transfer_data).toBeUndefined();
+    await api.executePreparedCheckoutSession(s.provider, s.component, s.ctx, {
+      prepared,
+      idempotencyKey: "prepared-split",
+    });
+    expect(s.create).toHaveBeenCalledWith(prepared.request, {
+      idempotencyKey: "prepared-split",
+    });
+    expect(s.runMutation.mock.calls[0][1]).toMatchObject({
+      chargeType: "separate",
+      splitRecipients: opts.split,
+    });
+  },
+);
+it("retains the platform-price provider guard during prepared execution", async () => {
+  const api = await contract();
+  const s = fixture();
+  const opts = {
+    ...s.options,
+    destinationAccountId: "acct_seller",
+    sessionOverrides: { allowed_payment_method_types: ["card"] },
+  };
+  const prepared = await api.prepareCheckoutSession(
+    s.provider,
+    s.component,
+    s.ctx,
+    opts,
+  );
+  s.runQuery.mockImplementation(async (ref: Record<symbol, string>) => {
+    const path = ref[Symbol.for("toReferencePath")];
+    if (path.endsWith("products/queries/getPriceByStripeId"))
+      return { stripeProductId: "prod_one" };
+    if (path.endsWith("products/queries/getProductByStripeId"))
+      return { accountId: "acct_seller" };
+    return null;
+  });
+  vi.mocked(s.provider.prices.retrieve).mockRejectedValueOnce({
+    code: "resource_missing",
+  });
+  await expect(
+    api.executePreparedCheckoutSession(s.provider, s.component, s.ctx, {
+      prepared,
+      idempotencyKey: "prepared-price-guard",
+    }),
+  ).rejects.toThrow("unavailable on the platform");
+  expect(s.create).not.toHaveBeenCalled();
+  expect(s.runMutation).not.toHaveBeenCalled();
+});

package/src/client/billing/preparedCheckout.ts

@@ -0,0 +1,143 @@
+import type Stripe from "stripe";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import { idempotencyOptions } from "../core/idempotency.js";
+import { renderCheckoutSession } from "./checkoutRequest.js";
+
+export type PreparedCheckoutSession = Awaited<
+  ReturnType<typeof renderCheckoutSession>
+>;
+function canonical(value: unknown): string {
+  return JSON.stringify(value, (_key, item: unknown) => {
+    if (typeof item === "number" && !Number.isFinite(item))
+      throw new Error("Checkout request must be serializable.");
+    if (["function", "symbol", "bigint"].includes(typeof item))
+      throw new Error("Checkout request must be serializable.");
+    if (item && typeof item === "object" && !Array.isArray(item))
+      return Object.fromEntries(
+        Object.entries(item).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+      );
+    return item;
+  });
+}
+function snapshot<T>(value: T): T {
+  return JSON.parse(canonical(value)) as T;
+}
+function validateCorrelation(prepared: PreparedCheckoutSession) {
+  const { request, row, options } = prepared;
+  const nested =
+    request.mode === "subscription"
+      ? request.subscription_data?.metadata
+      : request.mode === "payment"
+        ? request.payment_intent_data?.metadata
+        : undefined;
+  if (
+    request.mode !== options.mode ||
+    request.customer_account !== options.accountId ||
+    request.customer_email !==
+      (options.accountId ? undefined : options.customerEmail) ||
+    request.line_items?.length !== 1 ||
+    request.line_items[0]?.price !== options.stripePriceId ||
+    canonical(request.metadata) !== canonical(row.metadata) ||
+    (request.mode !== "setup" &&
+      Object.entries(row.metadata).some(
+        ([key, value]) => nested?.[key] !== value,
+      ))
+  )
+    throw new Error("Prepared Checkout correlation does not match.");
+  const generated =
+    request.mode === "subscription"
+      ? prepared.routingMetadata.subscription
+      : prepared.routingMetadata.payment;
+  const reserved = new Set(
+    [...Object.keys(nested ?? {}), ...Object.keys(generated ?? {})].filter(
+      (key) => key.startsWith("bs"),
+    ),
+  );
+  if ([...reserved].some((key) => nested?.[key] !== generated?.[key]))
+    throw new Error("Prepared Checkout routing metadata does not match.");
+}
+/** Read-only preparation. Persist the whole snapshot under host-owned immutable authorization. */
+export async function prepareCheckoutSession(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  opts: Parameters<typeof renderCheckoutSession>[3],
+): Promise<PreparedCheckoutSession> {
+  const prepared = snapshot(
+    await renderCheckoutSession(stripe, component, ctx, snapshot(opts)),
+  );
+  validateCorrelation(prepared);
+  return prepared;
+}
+/** Execute only a trusted server snapshot. Ownership and durable request binding belong to the host. */
+export async function executePreparedCheckoutSession(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  args: { prepared: PreparedCheckoutSession; idempotencyKey: string },
+) {
+  const requestOptions = idempotencyOptions(args.idempotencyKey);
+  if (!requestOptions)
+    throw new Error("Prepared Checkout requires an explicit idempotency key.");
+  const prepared = snapshot(args.prepared);
+  if (prepared.version !== 1)
+    throw new Error("Unsupported prepared Checkout version.");
+  if (
+    prepared.options.idempotencyKey !== undefined &&
+    prepared.options.idempotencyKey !== args.idempotencyKey
+  )
+    throw new Error("Prepared Checkout idempotency key does not match.");
+  validateCorrelation(prepared);
+  const expected = snapshot(
+    await renderCheckoutSession(
+      stripe,
+      component,
+      ctx,
+      prepared.options,
+      prepared.descriptor,
+    ),
+  );
+  if (canonical(prepared) !== canonical(expected))
+    throw new Error(
+      "Prepared Checkout request does not match its bound context.",
+    );
+  return submitPreparedCheckout(
+    stripe,
+    component,
+    ctx,
+    prepared,
+    args.idempotencyKey,
+  );
+}
+/** Shared legacy submission. Its input has already passed the maintained renderer's safeguards. */
+export async function submitPreparedCheckout(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  prepared: PreparedCheckoutSession,
+  key?: string,
+) {
+  const options = idempotencyOptions(key);
+  const session = options
+    ? await stripe.checkout.sessions.create(prepared.request, options)
+    : await stripe.checkout.sessions.create(prepared.request);
+  await runMutationOrThrow(
+    ctx,
+    componentRef(component, "billing/mutations/upsertCheckoutSession"),
+    {
+      ...prepared.row,
+      stripeSessionId: session.id,
+      mode: prepared.request.mode,
+      status: (session.status ?? "open") as "open" | "complete" | "expired",
+      clientSecret: session.client_secret ?? undefined,
+      url: session.url ?? undefined,
+    },
+  );
+  return {
+    stripeSessionId: session.id,
+    clientSecret: session.client_secret ?? undefined,
+    url: session.url ?? undefined,
+  };
+}

package/src/client/checkoutRequests.ts

@@ -0,0 +1,40 @@
+import type Stripe from "stripe";
+import type { Component, RunCtx } from "./helpers.js";
+import type { FeeOverride, PlatformFeeConfig } from "./types.js";
+import type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js";
+import {
+  prepareCheckoutSession,
+  executePreparedCheckoutSession,
+} from "./billing/preparedCheckout.js";
+
+/** Server-only request preparation and execution, without a browser-owned money API. */
+export class CheckoutRequestClient {
+  constructor(
+    private component: Component,
+    private provider: () => Stripe,
+    private resolveFee: (fee?: FeeOverride) => PlatformFeeConfig | undefined,
+    private descriptor?: string,
+  ) {}
+  prepare(ctx: RunCtx, opts: CreateCheckoutSessionOptions) {
+    const { fee, ...rest } = opts;
+    return prepareCheckoutSession(this.provider(), this.component, ctx, {
+      ...rest,
+      feeConfig:
+        opts.destinationAccountId || opts.split?.length
+          ? this.resolveFee(fee)
+          : undefined,
+      defaultStatementDescriptorSuffix: this.descriptor,
+    });
+  }
+  execute(
+    ctx: RunCtx,
+    args: Parameters<typeof executePreparedCheckoutSession>[3],
+  ) {
+    return executePreparedCheckoutSession(
+      this.provider(),
+      this.component,
+      ctx,
+      args,
+    );
+  }
+}