@fantastic.dev/better-stripe 0.12.0 → 0.14.0

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,5 @@
+import { importOpeningClaim } from "./imports.js";
+import { getGroup, integer } from "./helpers.js";
 import { v } from "convex/values";
 import { mutation } from "../_generated/server.js";
 import { recordClaim, rollbackClaim } from "./claims.js";
@@ -5,6 +7,7 @@ import { reserveGroup, sealGroup } from "./reservations.js";
 import { finishGroup } from "./completion.js";
 import {
   observationFields,
+  importArgs,
   claimDoc,
   groupDoc,
   reservationDoc,
@@ -41,3 +44,80 @@ export const finish = mutation({
   returns: v.object({ group: groupDoc, isDone: v.boolean() }),
   handler: finishGroup,
 });
+
+export const bindInvoiceItem = mutation({
+  args: { groupKey: v.string(), invoiceItemId: v.string() },
+  returns: groupDoc,
+  handler: async (ctx, args) => {
+    const group = await ctx.db
+      .query("recoveryGroups")
+      .withIndex("by_key", (q) => q.eq("groupKey", args.groupKey))
+      .unique();
+    if (
+      !group ||
+      group.sourceKind !== "invoice" ||
+      group.status === "open" ||
+      group.status === "released" ||
+      group.status === "releasing"
+    )
+      throw new Error("Invoice recovery group must be sealed and active.");
+    if (
+      !args.invoiceItemId ||
+      (group.invoiceItemId && group.invoiceItemId !== args.invoiceItemId)
+    )
+      throw new Error("Recovery invoice item identity cannot change.");
+    await ctx.db.patch("recoveryGroups", group._id, {
+      invoiceItemId: args.invoiceItemId,
+    });
+    return (await ctx.db.get("recoveryGroups", group._id))!;
+  },
+});
+
+export const bindInvoiceFunding = mutation({
+  args: {
+    groupKey: v.string(),
+    sourceChargeId: v.string(),
+    sourceGross: v.number(),
+    sourceProcessingFee: v.number(),
+  },
+  returns: groupDoc,
+  handler: async (ctx, args) => {
+    const group = await getGroup(ctx, args.groupKey);
+    if (group.sourceKind !== "invoice" || group.status !== "collected")
+      throw new Error(
+        "Invoice funding requires a collected invoice recovery group.",
+      );
+    integer(args.sourceGross);
+    integer(args.sourceProcessingFee);
+    if (
+      !args.sourceChargeId ||
+      args.sourceGross <= 0 ||
+      args.sourceProcessingFee < 0
+    )
+      throw new Error("Invalid invoice funding economics.");
+    const funding = {
+      sourceChargeId: args.sourceChargeId,
+      sourceGross: args.sourceGross,
+      sourceProcessingFee: args.sourceProcessingFee,
+    };
+    if (
+      group.invoiceFunding &&
+      Object.keys(funding).some(
+        (key) =>
+          group.invoiceFunding![key as keyof typeof funding] !==
+          funding[key as keyof typeof funding],
+      )
+    )
+      throw new Error("Original invoice funding economics cannot change.");
+    await ctx.db.patch("recoveryGroups", group._id, {
+      invoiceFunding: funding,
+    });
+    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,
@@ -56,6 +68,14 @@ export const groupFields = {
   ...groupInput,
   amount: v.number(),
   pendingOperations: v.number(),
+  invoiceItemId: v.optional(v.string()),
+  invoiceFunding: v.optional(
+    v.object({
+      sourceChargeId: v.string(),
+      sourceGross: v.number(),
+      sourceProcessingFee: v.number(),
+    }),
+  ),
   status: v.union(
     v.literal("open"),
     v.literal("sealed"),
@@ -96,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/Collections.test.tsx

@@ -84,3 +84,39 @@ it("preserves store attribution in referred sales and refund statuses in history
   expect(screen.getByText("failed")).toBeTruthy();
   expect(screen.getByRole("columnheader", { name: "Created" })).toBeTruthy();
 });
+
+it("renders observed refund units and unavailable data without throwing", () => {
+  render(
+    <RefundHistory
+      rows={[
+        {
+          stripeRefundId: "re_jpy",
+          amount: 500,
+          currency: "jpy",
+          status: "succeeded",
+        },
+        {
+          stripeRefundId: "re_ugx",
+          amount: 101,
+          currency: "ugx",
+          status: "pending",
+        },
+        {
+          stripeRefundId: "re_unknown",
+          amount: 100,
+          currency: "zzz",
+          status: "failed",
+        },
+        {
+          stripeRefundId: "re_invalid",
+          amount: -1,
+          currency: "usd",
+          status: "canceled",
+        },
+      ]}
+    />,
+  );
+  expect(screen.getByText("¥500")).toBeTruthy();
+  expect(screen.getByText("UGX 1.01")).toBeTruthy();
+  expect(screen.getAllByText("Amount unavailable")).toHaveLength(2);
+});

package/src/react/workflows/Collections.tsx

@@ -2,6 +2,7 @@
 import type { CollectionProps, WorkflowColumn } from "./Collection.js";
 import { Collection } from "./Collection.js";
 import { formatPrice } from "../lib/price-helpers.js";
+import { formatRefundAmount } from "./refund-preview.js";
 export type ResourceCollectionProps<Row> = Omit<
   CollectionProps<Row>,
   "columns" | "getKey"
@@ -111,7 +112,8 @@ export function RefundHistory(props: ResourceCollectionProps<RefundRow>) {
       id: "amount",
       label: "Amount",
       align: "end",
-      cell: (row) => formatPrice(row.amount, row.currency),
+      cell: (row) =>
+        formatRefundAmount(row.amount, row.currency) ?? "Amount unavailable",
     },
     { id: "status", label: "Status", cell: (row) => row.status },
     {

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

package/src/react/workflows/Onboarding.tsx

@@ -51,10 +51,13 @@ export function useOnboarding(props: OnboardingActions) {
             ? result.url
             : undefined;
       if (!url) throw new Error("Stripe did not return an onboarding URL.");
-      (props.onNavigate ?? ((url) => window.location.assign(url)))(url);
-      return true;
+      return url;
     },
     props.scopeKey,
+    (url) => {
+      if (typeof url === "string")
+        (props.onNavigate ?? ((url) => window.location.assign(url)))(url);
+    },
   );
   const run = action.run;
   return {
@@ -69,9 +72,9 @@ export function useOnboarding(props: OnboardingActions) {
     createError: operation === "create" ? action.error : null,
     linkError: operation === "link" ? action.error : null,
     restartError: operation === "close" ? action.error : null,
-    create: () => run("create"),
-    continue: () => run("link"),
-    close: () => run("close"),
+    create: async () => ((await run("create")) ? true : undefined),
+    continue: async () => ((await run("link")) ? true : undefined),
+    close: async () => ((await run("close")) ? true : undefined),
   };
 }
 export type OnboardingAccount = {