@fantastic.dev/better-stripe 0.13.0 → 0.15.0

package/src/client/index.ts

@@ -1,3 +1,7 @@
+import type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js";
+export type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js";
+import * as intentsImpl from "./billing/intents.js";
+export type * from "./billing/intents.js";
 import { CostRecoveryClient } from "./costRecovery.js";
 export * from "./charge-currency.js";
 export * from "./costRecovery.js";
@@ -88,12 +92,14 @@ import * as transfersImpl from "./connect/transfers.js";
 import * as accountLinksImpl from "./core/accountLinks.js";
 import * as accountsImpl from "./core/accounts.js";
 import * as configImpl from "./core/config.js";
-import { resolveFeeConfig, validatePlatformFee } from "./core/fees.js";
+import * as fees from "./core/fees.js";
 import { validateStatementDescriptorSuffix } from "./core/descriptors.js";
 export { computeFee, computeSplit } from "./core/fees.js";
 export type { FeeBreakdown, SplitResult, SplitTransfer } from "./core/fees.js";
 export { groupSubscriptionsByStore } from "./billing/subscriptions.js";
 export {
+  type DisputeEvidenceUploadOptions,
+  type DisputeEvidenceFileField,
   buildDisputeEvidence,
   disputeEvidenceCountdown,
 } from "./connect/disputes.js";
@@ -202,14 +208,6 @@ export type {
 
 export type BetterStripeComponent = ComponentApi;
 
-/** Deep-copy a platform fee config so stored/returned values can't be mutated. */
-function clonePlatformFee(config: PlatformFeeConfig): PlatformFeeConfig {
-  return {
-    ...config,
-    tiers: config.tiers?.map((tier) => ({ ...tier })),
-  };
-}
-
 // BETTER STRIPE CLIENT
 
 export class BetterStripe {
@@ -228,10 +226,10 @@ export class BetterStripe {
     this._triggers = options?.triggers;
     this._hooks = options?.hooks;
     if (options?.platformFee !== undefined) {
-      validatePlatformFee(options.platformFee);
+      fees.validatePlatformFee(options.platformFee);
       // Store a defensive copy so later mutation of the caller's object can't
       // silently bypass validation or change runtime behavior.
-      this._platformFee = clonePlatformFee(options.platformFee);
+      this._platformFee = fees.clonePlatformFee(options.platformFee);
     }
     if (options?.statementDescriptorSuffix !== undefined) {
       this._statementDescriptorSuffix = validateStatementDescriptorSuffix(
@@ -250,7 +248,7 @@ export class BetterStripe {
 
   /** The configured default platform fee (the platform's take), if any. */
   get platformFee(): PlatformFeeConfig | undefined {
-    return this._platformFee && clonePlatformFee(this._platformFee);
+    return this._platformFee && fees.clonePlatformFee(this._platformFee);
   }
 
   /**
@@ -258,8 +256,8 @@ export class BetterStripe {
    * default. The fee math itself is applied at charge time (M2).
    */
   resolveFee(override?: FeeOverride): PlatformFeeConfig | undefined {
-    const resolved = resolveFeeConfig(this._platformFee, override);
-    return resolved && clonePlatformFee(resolved);
+    const resolved = fees.resolveFeeConfig(this._platformFee, override);
+    return resolved && fees.clonePlatformFee(resolved);
   }
 
   get apiKey(): string {
@@ -655,34 +653,35 @@ export class BetterStripe {
     return pricesImpl.listStripePrices(this.stripe(), ctx, opts);
   }
 
-  // CHECKOUT METHODS
+  /** Card-only one-time checkout. Host authorizes price and authenticated customer. */
+  async createPaymentIntent(
+    ctx: RunCtx,
+    opts: intentsImpl.CreatePaymentIntentOptions,
+  ) {
+    return intentsImpl.createPaymentIntent(
+      this.stripe(),
+      this.component,
+      ctx,
+      opts,
+    );
+  }
 
-  async createCheckoutSession(
+  /** Provision consented card setup; confirmation and authentication happen in Stripe.js. */
+  async createSetupIntent(
     ctx: RunCtx,
-    opts: {
-      idempotencyKey?: string;
-      userId: string;
-      orgId?: string;
-      stripePriceId: string;
-      mode: "payment" | "subscription" | "setup";
-      uiMode?: "embedded" | "redirect" | "custom" | "form";
-      quantity?: number;
-      returnUrl: string;
-      trialDays?: number;
-      accountId?: string;
-      customerEmail?: string;
-      /** Seller/recipient connected account to route funds to (destination charge). */
-      destinationAccountId?: string;
-      /** Multiple recipients (store + affiliate[s]); >1 routes via separate charges & transfers. */
-      split?: SplitRecipient[];
-      /** Per-call platform fee override; falls back to the configured default. */
-      fee?: FeeOverride;
-      /** Charge total (minor units) for one-time payment fee computation. */
-      amount?: number;
-      metadata?: Record<string, string>;
-      sessionOverrides?: Record<string, unknown>;
-    },
+    opts: intentsImpl.CreateSetupIntentOptions,
   ) {
+    return intentsImpl.createSetupIntent(
+      this.stripe(),
+      this.component,
+      ctx,
+      opts,
+    );
+  }
+
+  // CHECKOUT METHODS
+
+  async createCheckoutSession(ctx: RunCtx, opts: CreateCheckoutSessionOptions) {
     const { fee, ...rest } = opts;
     return checkoutImpl.createCheckoutSession(
       this.stripe(),
@@ -1403,13 +1402,6 @@ export class BetterStripe {
     return disputesImpl.listDisputes(this.component, ctx, opts);
   }
 
-  /**
-   * Submit or stage dispute evidence. Stripe's `submit` defaults to TRUE, so
-   * this method stages by default: EVERY call sends an explicit
-   * `submit: false` — evidence-bearing or metadata-only — unless you pass
-   * `submit: true` to submit to the bank (one-shot, outcome-affecting;
-   * BTS-61, BTS-72). See {@link disputesImpl.updateDispute}.
-   */
   async updateDispute(
     ctx: RunCtx,
     opts: {
@@ -1418,23 +1410,29 @@ export class BetterStripe {
       metadata?: Record<string, string>;
       submit?: boolean;
       stripeAccountId?: string;
-      /**
-       * Who is acting on the dispute (BTS-107). A platform admin may act on any
-       * dispute; a seller may act only on a dispute for a sale routed to their
-       * own account. Omit for platform-initiated (unrestricted) actions.
-       */
       actor?: RefundActor;
     },
   ): Promise<{ success: true }> {
     return disputesImpl.updateDispute(this.stripe(), this.component, ctx, opts);
   }
 
+  async uploadDisputeEvidence(
+    ctx: RunCtx,
+    opts: disputesImpl.DisputeEvidenceUploadOptions,
+  ) {
+    return disputesImpl.uploadDisputeEvidence(
+      this.stripe(),
+      this.component,
+      ctx,
+      opts,
+    );
+  }
+
   async closeDispute(
     ctx: RunCtx,
     opts: {
       stripeDisputeId: string;
       stripeAccountId?: string;
-      /** See {@link updateDispute}'s `actor` (BTS-107). Omit for unrestricted. */
       actor?: RefundActor;
     },
   ): Promise<{ success: true }> {

package/src/component/_generated/api.ts

@@ -20,6 +20,7 @@ import type * as core_validators from "../core/validators.js";
 import type * as costRecovery_claims from "../costRecovery/claims.js";
 import type * as costRecovery_completion from "../costRecovery/completion.js";
 import type * as costRecovery_helpers from "../costRecovery/helpers.js";
+import type * as costRecovery_imports from "../costRecovery/imports.js";
 import type * as costRecovery_mutations from "../costRecovery/mutations.js";
 import type * as costRecovery_queries from "../costRecovery/queries.js";
 import type * as costRecovery_reservations from "../costRecovery/reservations.js";
@@ -57,6 +58,7 @@ const fullApi: ApiFromModules<{
   "costRecovery/claims": typeof costRecovery_claims;
   "costRecovery/completion": typeof costRecovery_completion;
   "costRecovery/helpers": typeof costRecovery_helpers;
+  "costRecovery/imports": typeof costRecovery_imports;
   "costRecovery/mutations": typeof costRecovery_mutations;
   "costRecovery/queries": typeof costRecovery_queries;
   "costRecovery/reservations": typeof costRecovery_reservations;

package/src/component/_generated/component.ts

@@ -1707,6 +1707,47 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           },
           Name
         >;
+        importClaim: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            amountDue: number;
+            claimKey: string;
+            collectedAmount: number;
+            currency: string;
+            operationKey: string;
+            revision: number;
+            scopeKey: string;
+            sourceChargeId: string;
+            sourceGross: number;
+            sourceProcessingFee: number;
+          },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            amountDue: number;
+            claimKey: string;
+            collectedAmount: number;
+            currency: string;
+            openingCollection?: {
+              amountDue: number;
+              collectedAmount: number;
+              operationKey: string;
+              revision: number;
+            };
+            outstanding: number;
+            reservedAmount: number;
+            revision: number;
+            scopeKey: string;
+            sign: "positive" | "negative" | "zero";
+            sourceChargeId: string;
+            sourceGross: number;
+            sourceProcessingFee: number;
+          },
+          Name
+        >;
         record: FunctionReference<
           "mutation",
           "internal",
@@ -1729,6 +1770,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             claimKey: string;
             collectedAmount: number;
             currency: string;
+            openingCollection?: {
+              amountDue: number;
+              collectedAmount: number;
+              operationKey: string;
+              revision: number;
+            };
             outstanding: number;
             reservedAmount: number;
             revision: number;
@@ -1816,6 +1863,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             claimKey: string;
             collectedAmount: number;
             currency: string;
+            openingCollection?: {
+              amountDue: number;
+              collectedAmount: number;
+              operationKey: string;
+              revision: number;
+            };
             outstanding: number;
             reservedAmount: number;
             revision: number;
@@ -1892,6 +1945,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             claimKey: string;
             collectedAmount: number;
             currency: string;
+            openingCollection?: {
+              amountDue: number;
+              collectedAmount: number;
+              operationKey: string;
+              revision: number;
+            };
             outstanding: number;
             reservedAmount: number;
             revision: number;
@@ -1965,6 +2024,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               claimKey: string;
               collectedAmount: number;
               currency: string;
+              openingCollection?: {
+                amountDue: number;
+                collectedAmount: number;
+                operationKey: string;
+                revision: number;
+              };
               outstanding: number;
               reservedAmount: number;
               revision: number;

package/src/component/costRecovery/imports.ts

@@ -0,0 +1,74 @@
+import { v, type Infer } from "convex/values";
+import type { MutationCtx } from "../_generated/server.js";
+import { importArgs } from "./schema.js";
+import { recordClaim } from "./claims.js";
+import { adjustTotals, balance, integer, sign } from "./helpers.js";
+const _argsValidator = v.object(importArgs);
+/** The host verifies historical collection; this operation performs no provider IO. */
+export async function importOpeningClaim(
+  ctx: MutationCtx,
+  args: Infer<typeof _argsValidator>,
+) {
+  integer(args.collectedAmount);
+  if (!args.operationKey.trim() || args.claimKey.startsWith("rollback:"))
+    throw new Error("Invalid recovery import identity.");
+  const imported = await ctx.db
+    .query("recoveryClaims")
+    .withIndex("by_import", (q) =>
+      q.eq("openingCollection.operationKey", args.operationKey),
+    )
+    .unique();
+  if (imported && imported.claimKey !== args.claimKey)
+    throw new Error("Recovery import identity cannot change.");
+  const existing = await ctx.db
+    .query("recoveryClaims")
+    .withIndex("by_key", (q) => q.eq("claimKey", args.claimKey))
+    .unique();
+  const openingCollection = {
+    operationKey: args.operationKey,
+    amountDue: args.amountDue,
+    revision: args.revision,
+    collectedAmount: args.collectedAmount,
+  };
+  if (existing) {
+    for (const key of [
+      "accountId",
+      "scopeKey",
+      "currency",
+      "sourceChargeId",
+      "sourceGross",
+      "sourceProcessingFee",
+    ] as const)
+      if (existing[key] !== args[key])
+        throw new Error("Recovery import source identity cannot change.");
+    if (!existing.openingCollection)
+      throw new Error("Cannot import over an existing live recovery claim.");
+    for (const key of [
+      "operationKey",
+      "amountDue",
+      "revision",
+      "collectedAmount",
+    ] as const)
+      if (existing.openingCollection[key] !== openingCollection[key])
+        throw new Error("Recovery opening snapshot cannot change.");
+    return existing;
+  }
+  if ((await balance(ctx, args)).activeGroupKey)
+    throw new Error(
+      "Cannot import while another recovery boundary is pending.",
+    );
+  const { operationKey: _operationKey, collectedAmount, ...observation } = args;
+  const claim = await recordClaim(ctx, observation);
+  const outstanding = integer(claim.amountDue - collectedAmount);
+  await ctx.db.patch("recoveryClaims", claim._id, {
+    collectedAmount,
+    outstanding,
+    sign: sign(outstanding),
+    openingCollection,
+  });
+  await adjustTotals(ctx, args, {
+    collectedAmount,
+    outstanding: -collectedAmount,
+  });
+  return (await ctx.db.get("recoveryClaims", claim._id))!;
+}

package/src/component/costRecovery/mutations.ts

@@ -1,3 +1,4 @@
+import { importOpeningClaim } from "./imports.js";
 import { getGroup, integer } from "./helpers.js";
 import { v } from "convex/values";
 import { mutation } from "../_generated/server.js";
@@ -6,6 +7,7 @@ import { reserveGroup, sealGroup } from "./reservations.js";
 import { finishGroup } from "./completion.js";
 import {
   observationFields,
+  importArgs,
   claimDoc,
   groupDoc,
   reservationDoc,
@@ -113,3 +115,9 @@ export const bindInvoiceFunding = mutation({
     return (await ctx.db.get("recoveryGroups", group._id))!;
   },
 });
+
+export const importClaim = mutation({
+  args: importArgs,
+  returns: claimDoc,
+  handler: importOpeningClaim,
+});

package/src/component/costRecovery/schema.ts

@@ -25,12 +25,24 @@ export const observationFields = {
   amountDue: v.number(),
   revision: v.number(),
 };
+export const openingCollection = v.object({
+  operationKey: v.string(),
+  amountDue: v.number(),
+  revision: v.number(),
+  collectedAmount: v.number(),
+});
+export const importArgs = {
+  ...observationFields,
+  operationKey: v.string(),
+  collectedAmount: v.number(),
+};
 export const claimFields = {
   ...observationFields,
   collectedAmount: v.number(),
   reservedAmount: v.number(),
   outstanding: v.number(),
   sign: signValidator,
+  openingCollection: v.optional(openingCollection),
 };
 export const claimDoc = v.object({
   ...claimFields,
@@ -104,6 +116,7 @@ export const reservationDoc = v.object({
 });
 export const claimsTable = defineTable(claimFields)
   .index("by_key", ["claimKey"])
+  .index("by_import", ["openingCollection.operationKey"])
   .index("by_scope", ["accountId", "scopeKey", "currency"])
   .index("by_sign", ["accountId", "scopeKey", "currency", "sign"]);
 export const balancesTable = defineTable(balanceFields).index("by_scope", [

package/src/react/hooks/useConfirmPayment.test.tsx

@@ -0,0 +1,47 @@
+// @vitest-environment jsdom
+import { renderHook } from "@testing-library/react";
+import { expect, it, vi } from "vitest";
+const f = vi.hoisted(() => ({ confirmSetup: vi.fn(), submit: vi.fn() }));
+vi.mock("@stripe/react-stripe-js", () => ({
+  useStripe: () => ({ confirmSetup: f.confirmSetup }),
+  useElements: () => ({ submit: f.submit }),
+}));
+import { useConfirmPayment } from "./useConfirmPayment.js";
+it("submits Elements and confirms explicit redisplay permission only on succeeded setup", async () => {
+  f.submit.mockResolvedValue({});
+  f.confirmSetup.mockResolvedValue({ setupIntent: { status: "succeeded" } });
+  const { result } = renderHook(useConfirmPayment);
+  expect(
+    await result.current.confirmSetup("https://app.test", "always"),
+  ).toEqual({ success: true });
+  expect(f.submit).toHaveBeenCalled();
+  expect(f.confirmSetup).toHaveBeenCalledWith({
+    elements: expect.anything(),
+    confirmParams: {
+      return_url: "https://app.test",
+      payment_method_data: { allow_redisplay: "always" },
+    },
+    redirect: "if_required",
+  });
+});
+it("does not turn processing or incomplete authentication into saved-card success", async () => {
+  f.submit.mockResolvedValue({});
+  f.confirmSetup.mockResolvedValue({
+    setupIntent: { status: "requires_action" },
+  });
+  const { result } = renderHook(useConfirmPayment);
+  expect(await result.current.confirmSetup()).toEqual({
+    success: false,
+    error: "Card setup is not complete.",
+  });
+});
+it("reports validation errors before confirmation", async () => {
+  f.confirmSetup.mockClear();
+  f.submit.mockResolvedValue({ error: { message: "Invalid card" } });
+  const { result } = renderHook(useConfirmPayment);
+  expect(await result.current.confirmSetup()).toEqual({
+    success: false,
+    error: "Invalid card",
+  });
+  expect(f.confirmSetup).not.toHaveBeenCalled();
+});

package/src/react/hooks/useConfirmPayment.ts

@@ -77,15 +77,27 @@ export function useConfirmPayment() {
    * @param returnUrl - URL to redirect to after 3D Secure. Defaults to current page.
    */
   const confirmSetup = useCallback(
-    async (returnUrl?: string): Promise<StripeConfirmResult> => {
+    async (
+      returnUrl?: string,
+      allowRedisplay?: "always" | "limited" | "unspecified",
+    ): Promise<StripeConfirmResult> => {
       if (!stripe || !elements) {
         return { success: false, error: "Stripe not initialized" };
       }
 
-      const { error } = await stripe.confirmSetup({
+      const validation = await elements.submit();
+      if (validation.error)
+        return {
+          success: false,
+          error: validation.error.message ?? "Check your card details.",
+        };
+      const { error, setupIntent } = await stripe.confirmSetup({
         elements,
         confirmParams: {
           return_url: returnUrl ?? window.location.href,
+          ...(allowRedisplay
+            ? { payment_method_data: { allow_redisplay: allowRedisplay } }
+            : {}),
         },
         redirect: "if_required",
       });
@@ -96,6 +108,8 @@ export function useConfirmPayment() {
           error: error.message ?? "Failed to confirm setup",
         };
       }
+      if (setupIntent?.status !== "succeeded")
+        return { success: false, error: "Card setup is not complete." };
       return { success: true };
     },
     [stripe, elements],

package/src/react/index.ts

@@ -290,3 +290,6 @@ export {
   formatChargeAmount,
   type ChargeCurrencyMetadata,
 } from "../client/charge-currency.js";
+
+export { SaveCard } from "./workflows/SaveCard.js";
+export type { SaveCardProps, SaveCardFormState } from "./workflows/SaveCard.js";

package/src/react/workflows/EvidenceUpload.test.tsx

@@ -0,0 +1,56 @@
+// @vitest-environment jsdom
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+} from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { EvidenceUpload } from "./EvidenceUpload.js";
+afterEach(cleanup);
+it("uploads the selected file once, retains it on failure and retries as a draft", async () => {
+  let reject!: (error: Error) => void;
+  const upload = vi.fn(
+    () =>
+      new Promise<unknown>((_, fail) => {
+        reject = fail;
+      }),
+  );
+  render(<EvidenceUpload scopeKey="seller:dp_1" onUpload={upload} />);
+  const file = new File(["%PDF-1.7"], "proof.pdf", { type: "application/pdf" });
+  fireEvent.change(screen.getByLabelText("Evidence file"), {
+    target: { files: [file] },
+  });
+  fireEvent.click(screen.getByRole("button", { name: "Attach to draft" }));
+  fireEvent.click(screen.getByRole("button", { name: "Uploading…" }));
+  expect(upload).toHaveBeenCalledExactlyOnceWith(file);
+  await act(async () => {
+    reject(new Error("Upload unavailable"));
+  });
+  expect(screen.getByRole("alert").textContent).toBe("Upload unavailable");
+  upload.mockResolvedValue({});
+  fireEvent.click(screen.getByRole("button", { name: "Attach to draft" }));
+  await act(async () => {});
+  expect(upload).toHaveBeenCalledTimes(2);
+  expect(screen.getByRole("status").textContent).toBe(
+    "File attached to draft. Submit evidence separately when ready.",
+  );
+});
+it("forgets another dispute's selected file", () => {
+  const upload = vi.fn();
+  const { rerender } = render(
+    <EvidenceUpload scopeKey="seller:dp_1" onUpload={upload} />,
+  );
+  fireEvent.change(screen.getByLabelText("Evidence file"), {
+    target: { files: [new File(["a"], "a.pdf")] },
+  });
+  rerender(<EvidenceUpload scopeKey="seller:dp_2" onUpload={upload} />);
+  expect(
+    (
+      screen.getByRole("button", {
+        name: "Attach to draft",
+      }) as HTMLButtonElement
+    ).disabled,
+  ).toBe(true);
+});

package/src/react/workflows/EvidenceUpload.tsx

@@ -0,0 +1,71 @@
+"use client";
+import { useId, useState, type ReactNode } from "react";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+
+export type EvidenceUploadProps = {
+  /** Include the authenticated scope and selected dispute. */
+  scopeKey: string;
+  /** Host authorizes the dispute and uploads bytes through BetterStripe server-side. */
+  onUpload: (file: File) => Promise<unknown>;
+  children?: (state: {
+    file: File | undefined;
+    setFile: (file: File | undefined) => void;
+    upload: () => Promise<unknown>;
+    isPending: boolean;
+    error: string | null;
+    isAttached: boolean;
+  }) => ReactNode;
+};
+
+/** Uploading only attaches to the draft. EvidenceForm owns explicit submission. */
+export function EvidenceUpload(props: EvidenceUploadProps) {
+  return <EvidenceUploadBody key={props.scopeKey} {...props} />;
+}
+function EvidenceUploadBody(props: EvidenceUploadProps) {
+  const id = useId();
+  const [file, setFile] = useState<File>();
+  const action = useWorkflowAction(async () => {
+    if (!file) throw new Error("Choose an evidence file first.");
+    await props.onUpload(file);
+    return true;
+  }, props.scopeKey);
+  const state = {
+    file,
+    setFile: (file: File | undefined) => {
+      setFile(file);
+      action.reset();
+    },
+    upload: action.run,
+    isPending: action.isPending,
+    error: action.error,
+    isAttached: action.result === true,
+  };
+  if (props.children) return <>{props.children(state)}</>;
+  return (
+    <section data-better-stripe="evidence-upload" aria-busy={state.isPending}>
+      <label htmlFor={id}>Evidence file</label>
+      <input
+        id={id}
+        type="file"
+        accept="application/pdf,image/jpeg,image/png"
+        disabled={state.isPending}
+        onChange={(event) => state.setFile(event.target.files?.[0])}
+      />
+      <button
+        type="button"
+        disabled={!file || state.isPending}
+        onClick={() => {
+          void state.upload();
+        }}
+      >
+        {state.isPending ? "Uploading…" : "Attach to draft"}
+      </button>
+      {state.error && <p role="alert">{state.error}</p>}
+      {state.isAttached && (
+        <p role="status">
+          File attached to draft. Submit evidence separately when ready.
+        </p>
+      )}
+    </section>
+  );
+}