@fantastic.dev/better-stripe 0.7.0 → 0.8.0

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

@@ -0,0 +1,39 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, expect, it, vi } from "vitest";
+import { ReferralLinks } from "./ReferralLinks.js";
+afterEach(cleanup);
+it("copies the complete attributed URL and reports clipboard failure", async () => {
+  const writeText = vi
+    .fn()
+    .mockResolvedValueOnce(undefined)
+    .mockRejectedValueOnce(new Error("Clipboard blocked"));
+  render(
+    <ReferralLinks
+      links={[
+        {
+          id: "store",
+          label: "Independent Store",
+          url: "https://app.test/stores?store=acct_one&ref=avery",
+        },
+      ]}
+      writeText={writeText}
+    />,
+  );
+  await userEvent.click(
+    screen.getByRole("button", {
+      name: "Copy referral link for Independent Store",
+    }),
+  );
+  expect(writeText).toHaveBeenCalledWith(
+    "https://app.test/stores?store=acct_one&ref=avery",
+  );
+  expect(screen.getByRole("status").textContent).toContain("copied");
+  await userEvent.click(
+    screen.getByRole("button", {
+      name: "Copy referral link for Independent Store",
+    }),
+  );
+  expect(screen.getByRole("alert").textContent).toContain("Clipboard blocked");
+});

package/src/react/workflows/ReferralLinks.tsx

@@ -0,0 +1,75 @@
+"use client";
+import type { ReactNode } from "react";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+export type ReferralLink = { id: string; label: string; url: string };
+export function useReferralLinks({
+  scopeKey = "referral-links",
+  writeText = (text: string) => navigator.clipboard.writeText(text),
+}: { scopeKey?: string; writeText?: (text: string) => Promise<void> } = {}) {
+  const action = useWorkflowAction(async (url: string) => {
+    if (!url.trim()) throw new Error("A referral URL is required.");
+    await writeText(url);
+    return url;
+  }, scopeKey);
+  return {
+    copy: action.run,
+    copiedUrl: action.result,
+    error: action.error,
+    isPending: action.isPending,
+  };
+}
+export type ReferralLinksProps = {
+  links: ReferralLink[] | undefined;
+  scopeKey?: string;
+  writeText?: (text: string) => Promise<void>;
+  children?: (
+    state: ReturnType<typeof useReferralLinks> & {
+      links: ReferralLink[];
+      isLoading: boolean;
+    },
+  ) => ReactNode;
+};
+export function ReferralLinks(props: ReferralLinksProps) {
+  const state = useReferralLinks(props);
+  if (props.children)
+    return (
+      <>
+        {props.children({
+          ...state,
+          links: props.links ?? [],
+          isLoading: props.links === undefined,
+        })}
+      </>
+    );
+  return (
+    <section data-better-stripe="referral-links">
+      <h2>Referral links</h2>
+      {state.error && <p role="alert">{state.error}</p>}
+      {state.copiedUrl && <p role="status">Referral link copied</p>}
+      {props.links === undefined ? (
+        <p role="status">Loading referral links…</p>
+      ) : !props.links.length ? (
+        <p>No referral links yet.</p>
+      ) : (
+        <ul>
+          {props.links.map((link) => (
+            <li key={link.id}>
+              <a href={link.url}>{link.label}</a>
+              <p>{link.url}</p>
+              <button
+                type="button"
+                disabled={state.isPending}
+                aria-label={`Copy referral link for ${link.label}`}
+                onClick={() => {
+                  void state.copy(link.url);
+                }}
+              >
+                {state.isPending ? "Copying…" : "Copy link"}
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+    </section>
+  );
+}

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

@@ -0,0 +1,75 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { useRefunds } from "./Refunds.js";
+afterEach(cleanup);
+it("validates a partial amount before Stripe and preserves exact minor units", async () => {
+  const issueRefund = vi.fn().mockResolvedValue({ stripeRefundId: "re_test" });
+  const { result } = renderHook(() =>
+    useRefunds({
+      scopeKey: "seller",
+      issueRefund,
+      paymentIntentId: " pi_test ",
+    }),
+  );
+  await act(async () => {
+    await result.current.submitRefund("partial");
+  });
+  expect(issueRefund).not.toHaveBeenCalled();
+  expect(result.current.error).toContain("positive");
+  act(() => result.current.setRefundAmount("12.34"));
+  await act(async () => {
+    await result.current.submitRefund("partial");
+  });
+  expect(issueRefund).toHaveBeenCalledWith({
+    stripePaymentIntentId: "pi_test",
+    amountCents: 1234,
+    reason: "requested_by_customer",
+  });
+  expect(result.current.refundResult?.stripeRefundId).toBe("re_test");
+});
+it("rejects excess precision and resets fields for another account", async () => {
+  const issueRefund = vi.fn();
+  const { result, rerender } = renderHook(
+    ({ scope }) =>
+      useRefunds({ scopeKey: scope, issueRefund, paymentIntentId: "pi_test" }),
+    { initialProps: { scope: "one" } },
+  );
+  act(() => result.current.setRefundAmount("0.005"));
+  await act(async () => {
+    await result.current.submitRefund("partial");
+  });
+  expect(issueRefund).not.toHaveBeenCalled();
+  rerender({ scope: "two" });
+  expect(result.current.refundAmount).toBe("");
+  expect(result.current.refundResult).toBeNull();
+});
+it("keeps a pending refund labeled as a refund when a reversal is attempted", async () => {
+  let finish!: (value: { stripeRefundId: string }) => void;
+  const reverseTransfers = vi.fn();
+  const { result } = renderHook(() =>
+    useRefunds({
+      scopeKey: "seller",
+      paymentIntentId: "pi_one",
+      sourceChargeId: "ch_one",
+      issueRefund: () =>
+        new Promise((resolve) => {
+          finish = resolve;
+        }),
+      reverseTransfers,
+    }),
+  );
+  let pending!: Promise<unknown>;
+  act(() => {
+    pending = result.current.submitRefund("full");
+  });
+  await act(async () => {
+    await result.current.submitReversal("full");
+  });
+  expect(result.current.busy).toBe("refund");
+  expect(reverseTransfers).not.toHaveBeenCalled();
+  await act(async () => {
+    finish({ stripeRefundId: "re_one" });
+    await pending;
+  });
+});

package/src/react/workflows/Refunds.tsx

@@ -0,0 +1,223 @@
+"use client";
+import { useState, useId, type ReactNode } from "react";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+import { Connect, type ConnectProps } from "./Connect.js";
+export type RefundRequest = {
+  stripePaymentIntentId: string;
+  amountCents?: number;
+  reason: "requested_by_customer";
+};
+export type ReversalRequest = { sourceChargeId: string; amountCents?: number };
+export type RefundResult = { stripeRefundId: string };
+export type ReversalResult = {
+  reversals: { stripeTransferId: string; amount: number }[];
+  summary: { reversalCount: number; totalReversed: number };
+};
+export type RefundActionsProps = {
+  scopeKey: string;
+  paymentIntentId?: string;
+  sourceChargeId?: string;
+  issueRefund: (args: RefundRequest) => Promise<RefundResult>;
+  reverseTransfers?: (args: ReversalRequest) => Promise<ReversalResult>;
+};
+/** Currency input expressed in two decimal minor units. Rejects rounding and scientific notation. */
+export function parseAmountCents(value: string): number | null {
+  if (!/^\d+(?:\.\d{1,2})?$/.test(value.trim())) return null;
+  const [whole, fraction = ""] = value.trim().split(".");
+  const amount = Number(whole) * 100 + Number(fraction.padEnd(2, "0"));
+  return Number.isSafeInteger(amount) && amount > 0 ? amount : null;
+}
+export function useRefunds(props: RefundActionsProps) {
+  const initial = {
+    scope: props.scopeKey,
+    paymentIntentId: props.paymentIntentId ?? "",
+    sourceChargeId: props.sourceChargeId ?? "",
+    refundAmount: "",
+    reversalAmount: "",
+  };
+  const [fields, setFields] = useState(initial);
+  if (fields.scope !== props.scopeKey) setFields(initial);
+  const [operationType, setOperationType] = useState<"refund" | "reversal">(
+    "refund",
+  );
+  const action = useWorkflowAction(
+    async (operation: {
+      type: "refund" | "reversal";
+      kind: "full" | "partial";
+    }) => {
+      setOperationType(operation.type);
+      const id = (
+        operation.type === "refund"
+          ? fields.paymentIntentId
+          : fields.sourceChargeId
+      ).trim();
+      if (!id)
+        throw new Error(
+          operation.type === "refund"
+            ? "Enter a PaymentIntent id before issuing a refund."
+            : "Enter a source charge id before reversing transfers.",
+        );
+      const amount =
+        operation.kind === "partial"
+          ? parseAmountCents(
+              operation.type === "refund"
+                ? fields.refundAmount
+                : fields.reversalAmount,
+            )
+          : undefined;
+      if (amount === null)
+        throw new Error(
+          `Enter a positive partial ${operation.type === "refund" ? "refund" : "reversal"} amount with at most two decimal places.`,
+        );
+      if (operation.type === "refund")
+        return {
+          type: "refund" as const,
+          value: await props.issueRefund({
+            stripePaymentIntentId: id,
+            amountCents: amount,
+            reason: "requested_by_customer",
+          }),
+        };
+      if (!props.reverseTransfers)
+        throw new Error("Transfer reversals are not configured.");
+      return {
+        type: "reversal" as const,
+        value: await props.reverseTransfers({
+          sourceChargeId: id,
+          amountCents: amount,
+        }),
+      };
+    },
+    props.scopeKey,
+  );
+  const set = (
+    name:
+      "paymentIntentId" | "sourceChargeId" | "refundAmount" | "reversalAmount",
+    value: string,
+  ) => setFields((previous) => ({ ...previous, [name]: value }));
+  return {
+    ...fields,
+    setPaymentIntentId: (value: string) => set("paymentIntentId", value),
+    setSourceChargeId: (value: string) => set("sourceChargeId", value),
+    setRefundAmount: (value: string) => set("refundAmount", value),
+    setReversalAmount: (value: string) => set("reversalAmount", value),
+    error: action.error,
+    isPending: action.isPending,
+    busy: action.isPending ? operationType : null,
+    refundResult: action.result?.type === "refund" ? action.result.value : null,
+    reversalResult:
+      action.result?.type === "reversal" ? action.result.value : null,
+    submitRefund: (kind: "full" | "partial") =>
+      action.run({ type: "refund", kind }),
+    submitReversal: (kind: "full" | "partial") =>
+      action.run({ type: "reversal", kind }),
+  };
+}
+export type RefundsRenderProps = ReturnType<typeof useRefunds>;
+export type RefundsProps =
+  | (RefundActionsProps & {
+      presentation?: "headless";
+      children?: (state: RefundsRenderProps) => ReactNode;
+    })
+  | (Omit<ConnectProps, "component"> & { presentation: "embedded" });
+export function Refunds(props: RefundsProps) {
+  return props.presentation === "embedded" ? (
+    <Connect {...props} component="refunds" />
+  ) : (
+    <RefundsBody key={props.scopeKey} {...props} />
+  );
+}
+function RefundsBody(
+  props: RefundActionsProps & {
+    children?: (state: RefundsRenderProps) => ReactNode;
+  },
+) {
+  const state = useRefunds(props);
+  const id = useId();
+  if (props.children) return <>{props.children(state)}</>;
+  return (
+    <section data-better-stripe="refunds" aria-busy={state.isPending}>
+      <h2>Refunds</h2>
+      {state.error && <p role="alert">{state.error}</p>}
+      <label htmlFor={`${id}-payment`}>PaymentIntent ID</label>
+      <input
+        id={`${id}-payment`}
+        value={state.paymentIntentId}
+        onChange={(event) => state.setPaymentIntentId(event.target.value)}
+      />
+      <label htmlFor={`${id}-amount`}>Partial refund amount</label>
+      <input
+        id={`${id}-amount`}
+        type="number"
+        min="0.01"
+        step="0.01"
+        value={state.refundAmount}
+        onChange={(event) => state.setRefundAmount(event.target.value)}
+      />
+      <button
+        type="button"
+        disabled={state.isPending}
+        onClick={() => {
+          void state.submitRefund("full");
+        }}
+      >
+        {state.isPending ? "Processing…" : "Full refund"}
+      </button>
+      <button
+        type="button"
+        disabled={state.isPending}
+        onClick={() => {
+          void state.submitRefund("partial");
+        }}
+      >
+        Partial refund
+      </button>
+      {state.refundResult && (
+        <p role="status">Refund created: {state.refundResult.stripeRefundId}</p>
+      )}
+      {props.reverseTransfers && (
+        <>
+          <h3>Transfer reversals</h3>
+          <label htmlFor={`${id}-charge`}>Source charge ID</label>
+          <input
+            id={`${id}-charge`}
+            value={state.sourceChargeId}
+            onChange={(event) => state.setSourceChargeId(event.target.value)}
+          />
+          <label htmlFor={`${id}-reversal`}>Partial reversal amount</label>
+          <input
+            id={`${id}-reversal`}
+            type="number"
+            min="0.01"
+            step="0.01"
+            value={state.reversalAmount}
+            onChange={(event) => state.setReversalAmount(event.target.value)}
+          />
+          <button
+            type="button"
+            disabled={state.isPending}
+            onClick={() => {
+              void state.submitReversal("full");
+            }}
+          >
+            Reverse all transfers
+          </button>
+          <button
+            type="button"
+            disabled={state.isPending}
+            onClick={() => {
+              void state.submitReversal("partial");
+            }}
+          >
+            Partial reversal
+          </button>
+          {state.reversalResult && (
+            <p role="status">
+              Reversed {state.reversalResult.summary.reversalCount} transfers.
+            </p>
+          )}
+        </>
+      )}
+    </section>
+  );
+}

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

@@ -0,0 +1,25 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { useWebhookSetup } from "./Setup.js";
+afterEach(cleanup);
+it("refreshes destination status after setup and keeps setup errors available for retry", async () => {
+  const load = vi
+    .fn()
+    .mockResolvedValueOnce({ configured: false })
+    .mockResolvedValueOnce({ configured: true });
+  const setup = vi.fn().mockResolvedValue({ id: "we_test" });
+  const { result } = renderHook(() =>
+    useWebhookSetup({ scopeKey: "site", load, setup }),
+  );
+  await waitFor(() =>
+    expect(result.current.status).toEqual({ configured: false }),
+  );
+  await act(async () => {
+    await result.current.configure();
+  });
+  await waitFor(() =>
+    expect(result.current.status).toEqual({ configured: true }),
+  );
+  expect(result.current.result).toEqual({ id: "we_test" });
+});

package/src/react/workflows/Setup.tsx

@@ -0,0 +1,166 @@
+"use client";
+import type { ReactNode } from "react";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+import { useWorkflowResource } from "./useWorkflowResource.js";
+export type WebhookSetupOptions<Status, Result> = {
+  scopeKey: string;
+  load: () => Promise<Status>;
+  setup: () => Promise<Result>;
+};
+export function useWebhookSetup<Status, Result>(
+  props: WebhookSetupOptions<Status, Result>,
+) {
+  const status = useWorkflowResource(props.load, props.scopeKey);
+  const setup = useWorkflowAction(
+    async () => ({ value: await props.setup() }),
+    props.scopeKey,
+  );
+  return {
+    status: status.data,
+    isChecking: status.isLoading,
+    statusError: status.error,
+    checkStatus: status.refresh,
+    result: setup.result?.value,
+    isPending: setup.isPending,
+    error: setup.error,
+    configure: async () => {
+      if (await setup.run()) status.refresh();
+    },
+  };
+}
+export function WebhookSetup<Status, Result>(
+  props: WebhookSetupOptions<Status, Result> & {
+    renderStatus?: (status: Status) => ReactNode;
+    children?: (
+      state: ReturnType<typeof useWebhookSetup<Status, Result>>,
+    ) => ReactNode;
+  },
+) {
+  const state = useWebhookSetup(props);
+  if (props.children) return <>{props.children(state)}</>;
+  return (
+    <section data-better-stripe="webhook-setup">
+      <h2>Webhook destinations</h2>
+      {(state.error || state.statusError) && (
+        <p role="alert">{state.error || state.statusError}</p>
+      )}
+      {state.isChecking ? (
+        <p role="status">Checking destinations…</p>
+      ) : state.status !== undefined && props.renderStatus ? (
+        props.renderStatus(state.status)
+      ) : (
+        <p>Destination status loaded.</p>
+      )}
+      <button
+        type="button"
+        disabled={state.isPending || state.isChecking}
+        onClick={() => {
+          void state.configure();
+        }}
+      >
+        {state.isPending ? "Configuring…" : "Configure webhooks"}
+      </button>
+      <button
+        type="button"
+        disabled={state.isChecking}
+        onClick={state.checkStatus}
+      >
+        Refresh status
+      </button>
+    </section>
+  );
+}
+export type EnvironmentCheck = {
+  id: string;
+  label: string;
+  configured: boolean;
+};
+export function EnvironmentStatus({
+  checks,
+  isLoading = checks === undefined,
+  error,
+  children,
+}: {
+  checks: EnvironmentCheck[] | undefined;
+  isLoading?: boolean;
+  error?: string | null;
+  children?: (state: {
+    checks: EnvironmentCheck[];
+    allConfigured: boolean;
+    isLoading: boolean;
+    error: string | null;
+  }) => ReactNode;
+}) {
+  const state = {
+    checks: checks ?? [],
+    allConfigured:
+      !!checks?.length && checks.every((check) => check.configured),
+    isLoading,
+    error: error ?? null,
+  };
+  if (children) return <>{children(state)}</>;
+  return (
+    <section data-better-stripe="environment-status">
+      <h2>Environment</h2>
+      {error ? (
+        <p role="alert">{error}</p>
+      ) : isLoading ? (
+        <p role="status">Checking configuration…</p>
+      ) : !checks?.length ? (
+        <p>No environment checks configured.</p>
+      ) : (
+        <ul>
+          {checks.map((check) => (
+            <li key={check.id}>
+              {check.label}: {check.configured ? "Set" : "Not set"}
+            </li>
+          ))}
+        </ul>
+      )}
+    </section>
+  );
+}
+export type FixtureProgressState = {
+  cursor: number;
+  total: number;
+  status: string;
+  error?: string;
+};
+export function FixtureProgress({
+  state,
+  children,
+}: {
+  state: FixtureProgressState | null | undefined;
+  children?: (
+    state: FixtureProgressState & { progress: number; message: string },
+  ) => ReactNode;
+}) {
+  if (!state) return <p>No fixture run yet.</p>;
+  const result = {
+    ...state,
+    progress:
+      state.total > 0
+        ? Math.max(0, Math.min(1, state.cursor / state.total))
+        : 0,
+    message:
+      state.status === "running"
+        ? "Fixtures are being created. Stripe events continue to update your data."
+        : state.status === "complete"
+          ? "Fixtures are populated. Stripe statuses can continue updating through webhooks."
+          : "Population stopped. Resume to retry this step.",
+  };
+  if (children) return <>{children(result)}</>;
+  return (
+    <div data-better-stripe="fixture-progress">
+      <progress
+        aria-label="Sandbox fixture progress"
+        value={result.progress}
+        max={1}
+      />
+      <p role="status">
+        {state.cursor} of {state.total} steps complete. {result.message}
+      </p>
+      {state.error && <p role="alert">{state.error}</p>}
+    </div>
+  );
+}

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

@@ -0,0 +1,82 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, expect, it, vi } from "vitest";
+import { Storefront } from "./Storefront.js";
+afterEach(cleanup);
+it("preserves product, store, and referral attribution when selecting a price", async () => {
+  const onSelectPrice = vi.fn();
+  render(
+    <Storefront
+      stores={[
+        {
+          accountId: "acct_one",
+          name: "Independent Store",
+          products: [
+            {
+              stripeProductId: "prod_one",
+              name: "Tee",
+              prices: [
+                {
+                  stripePriceId: "price_one",
+                  unitAmount: 2900,
+                  currency: "usd",
+                  type: "one_time",
+                },
+              ],
+            },
+          ],
+        },
+      ]}
+      referralCode="avery"
+      onSelectPrice={onSelectPrice}
+    />,
+  );
+  await userEvent.click(screen.getByRole("button", { name: "Buy Tee" }));
+  expect(onSelectPrice).toHaveBeenCalledWith(
+    expect.objectContaining({
+      store: expect.objectContaining({ accountId: "acct_one" }),
+      price: expect.objectContaining({ stripePriceId: "price_one" }),
+      referralCode: "avery",
+    }),
+  );
+});
+it("does not offer inactive prices or purchases when the application disables buying", () => {
+  render(
+    <Storefront
+      canPurchase={false}
+      stores={[
+        {
+          accountId: "acct_one",
+          name: "Store",
+          products: [
+            {
+              stripeProductId: "prod_one",
+              name: "Tee",
+              prices: [
+                {
+                  stripePriceId: "price_old",
+                  active: false,
+                  unitAmount: 100,
+                  currency: "usd",
+                  type: "one_time",
+                },
+                {
+                  stripePriceId: "price_one",
+                  unitAmount: 2900,
+                  currency: "usd",
+                  type: "one_time",
+                },
+              ],
+            },
+          ],
+        },
+      ]}
+    />,
+  );
+  expect(
+    (screen.getByRole("button", { name: "Buy Tee" }) as HTMLButtonElement)
+      .disabled,
+  ).toBe(true);
+  expect(screen.getAllByRole("button")).toHaveLength(1);
+});