@fantastic.dev/better-stripe 0.13.0 → 0.14.0

package/src/client/costRecovery-invoices.test.ts

@@ -399,3 +399,72 @@ it("never creates a new provider item for an already completed bookkeeping group
   await expect(recovery.attachInvoice(ctx, options)).rejects.toThrow(/sealed/i);
   expect(provider.invoiceItems.create).not.toHaveBeenCalled();
 });
+it("releases an unbound void invoice after a complete item scan without creating an adjustment", async () => {
+  const { ctx, recovery, invoice, items, provider } = await setup();
+  items.push(
+    ...Array.from(
+      { length: 105 },
+      (_, i) => ({ id: `ii_other_${i}`, metadata: {} }) as Stripe.InvoiceItem,
+    ),
+  );
+  invoice.status = "void";
+  const result = await recovery.reconcileInvoice(ctx, options);
+  expect(result).toMatchObject({
+    isDone: true,
+    invoiceItemId: null,
+    invoiceStatus: "void",
+  });
+  await recovery.reconcileInvoice(ctx, options);
+  expect(provider.invoiceItems.create).not.toHaveBeenCalled();
+  expect(await recovery.balance(ctx, scope)).toMatchObject({
+    reservedAmount: 0,
+    collectedAmount: 0,
+    outstanding: 320,
+  });
+});
+it("keeps missing adjustments reserved for unpaid, paid, uncollectible or previously bound invoices", async () => {
+  for (const status of ["draft", "open", "paid", "uncollectible"]) {
+    const { ctx, recovery, invoice } = await setup();
+    invoice.status = status;
+    await expect(
+      recovery.reconcileInvoice(ctx, {
+        ...options,
+        releaseUncollectible: true,
+      }),
+    ).rejects.toThrow(/missing/i);
+    expect(await recovery.balance(ctx, scope)).toMatchObject({
+      reservedAmount: 320,
+      collectedAmount: 0,
+    });
+  }
+  const { ctx, recovery, invoice, items } = await setup();
+  await recovery.attachInvoice(ctx, options);
+  items.length = 0;
+  invoice.status = "void";
+  await expect(recovery.reconcileInvoice(ctx, options)).rejects.toThrow(
+    /bound.*missing/i,
+  );
+});
+it("does not release an unbound void invoice on an incomplete scan or ownership mismatch", async () => {
+  const { ctx, recovery, invoice, provider } = await setup();
+  invoice.status = "void";
+  const originalList = provider.invoiceItems.list.getMockImplementation()!;
+  provider.invoiceItems.list.mockImplementation(() =>
+    (async function* () {
+      yield { id: "ii_unrelated", metadata: {} } as Stripe.InvoiceItem;
+      throw new Error("pagination interrupted");
+    })(),
+  );
+  await expect(recovery.reconcileInvoice(ctx, options)).rejects.toThrow(
+    "pagination interrupted",
+  );
+  provider.invoiceItems.list.mockImplementation(originalList);
+  invoice.customer_account = "acct_other";
+  await expect(recovery.reconcileInvoice(ctx, options)).rejects.toThrow(
+    /ownership/i,
+  );
+  expect(await recovery.balance(ctx, scope)).toMatchObject({
+    reservedAmount: 320,
+    collectedAmount: 0,
+  });
+});

package/src/client/costRecovery-invoices.ts

@@ -6,6 +6,32 @@ const marker = "bsRecoveryGroup";
 const id = (value: string | { id: string } | null) =>
   typeof value === "string" ? value : value?.id;
 
+type InvoiceReceipt = {
+  group: RecoveryGroup;
+  invoiceItemId: string;
+  invoiceStatus: Stripe.Invoice["status"];
+};
+type BindInvoiceItem = (invoiceItemId: string) => Promise<RecoveryGroup>;
+
+/** Attachment always produces an item; reconciliation can release an unbound void invoice. */
+export function attachRecoveryInvoice(
+  stripe: Stripe,
+  group: RecoveryGroup | null,
+  opts: RecoveryInvoiceOptions,
+  bind: BindInvoiceItem,
+  create?: true,
+): Promise<InvoiceReceipt>;
+export function attachRecoveryInvoice(
+  stripe: Stripe,
+  group: RecoveryGroup | null,
+  opts: RecoveryInvoiceOptions,
+  bind: BindInvoiceItem,
+  create: false,
+): Promise<
+  | InvoiceReceipt
+  | (Omit<InvoiceReceipt, "invoiceItemId"> & { invoiceItemId: null })
+>;
+
 /** One immutable item per sealed group. Host serializes provider operations per group. */
 export async function attachRecoveryInvoice(
   stripe: Stripe,
@@ -66,6 +92,12 @@ export async function attachRecoveryInvoice(
       throw new Error(
         "Bound recovery invoice item is missing; reconcile before retrying.",
       );
+    if (
+      !create &&
+      invoice.status === "void" &&
+      ["sealed", "releasing", "released"].includes(group.status)
+    )
+      return { group, invoiceItemId: null, invoiceStatus: invoice.status };
     if (!create)
       throw new Error(
         "Recovery invoice item is missing; no collection can be confirmed.",

package/src/client/costRecovery.ts

@@ -26,6 +26,12 @@ export type RecoveryClaim = RecoveryObservation & {
   reservedAmount: number;
   outstanding: number;
   sign: "positive" | "negative" | "zero";
+  openingCollection?: {
+    operationKey: string;
+    amountDue: number;
+    revision: number;
+    collectedAmount: number;
+  };
 };
 export type RecoveryBalance = RecoveryScope & {
   amountDue: number;
@@ -194,6 +200,16 @@ export class CostRecoveryClient {
       }),
     };
   }
+  /** Import a host-verified opening collection. Never overwrites a live claim. */
+  importClaim(
+    ctx: RunCtx,
+    opts: RecoveryObservation & {
+      operationKey: string;
+      collectedAmount: number;
+    },
+  ) {
+    return this.mutate<RecoveryClaim>(ctx, "mutations/importClaim", opts);
+  }
   recordClaim(ctx: RunCtx, opts: RecoveryObservation) {
     return this.mutate<RecoveryClaim>(ctx, "mutations/record", opts);
   }

package/src/client/errors.ts

@@ -9,6 +9,7 @@ export type BetterStripeErrorCode =
   | "SUBSCRIPTION_UPDATE_FAILED"
   | "REFUND_CREATE_FAILED"
   | "REFUND_UNAUTHORIZED"
+  | "DISPUTE_UPLOAD_FAILED"
   | "DISPUTE_UPDATE_FAILED"
   | "DISPUTE_UNAUTHORIZED"
   | "CHECKOUT_CREATE_FAILED"

package/src/client/index.ts

@@ -94,6 +94,8 @@ 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";
@@ -1403,13 +1405,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 +1413,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/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>
+  );
+}

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

@@ -73,3 +73,76 @@ it("offers the shared example countries in the native onboarding UI", async () =
   );
   expect(screen.getByRole("option", { name: "United Kingdom" })).toBeTruthy();
 });
+
+for (const flow of ["create", "continue"] as const) {
+  for (const transition of ["unmount", "scope", "current"] as const) {
+    it(`${flow} navigates only while current after ${transition}`, async () => {
+      let resolve!: (value: { url: string; onboardingUrl: string }) => void;
+      const response = new Promise<{ url: string; onboardingUrl: string }>(
+        (done) => {
+          resolve = done;
+        },
+      );
+      const navigate = vi.fn();
+      const { result, rerender, unmount } = renderHook(
+        ({ scope }) =>
+          useOnboarding({
+            scopeKey: scope,
+            createAccount: () => response,
+            continueOnboarding: () => response,
+            onNavigate: navigate,
+          }),
+        { initialProps: { scope: "seller-a" } },
+      );
+      let pending!: Promise<unknown>;
+      act(() => {
+        pending = result.current[flow]();
+      });
+      if (transition === "unmount") unmount();
+      if (transition === "scope") rerender({ scope: "seller-b" });
+      await act(async () => {
+        resolve({
+          url: "https://connect.stripe.com/setup",
+          onboardingUrl: "https://connect.stripe.com/setup",
+        });
+        await pending;
+      });
+      expect(navigate).toHaveBeenCalledTimes(transition === "current" ? 1 : 0);
+    });
+  }
+}
+
+for (const flow of ["create", "continue"] as const) {
+  it(`${flow} suppresses the default location assignment after unmount`, async () => {
+    let resolve!: (value: { url: string; onboardingUrl: string }) => void;
+    const response = new Promise<{ url: string; onboardingUrl: string }>(
+      (done) => {
+        resolve = done;
+      },
+    );
+    const assign = vi.fn();
+    const { result, unmount } = renderHook(() =>
+      useOnboarding({
+        scopeKey: "seller",
+        createAccount: () => response,
+        continueOnboarding: () => response,
+      }),
+    );
+    let pending!: Promise<unknown>;
+    act(() => {
+      pending = result.current[flow]();
+    });
+    unmount();
+    vi.stubGlobal("window", { location: { assign } });
+    try {
+      resolve({
+        url: "https://connect.stripe.com/setup",
+        onboardingUrl: "https://connect.stripe.com/setup",
+      });
+      await pending;
+      expect(assign).not.toHaveBeenCalled();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+}