@fantastic.dev/better-stripe 0.11.0 → 0.12.0

package/src/component/costRecovery/schema.ts

@@ -0,0 +1,127 @@
+import { defineTable } from "convex/server";
+import { v } from "convex/values";
+export const scopeFields = {
+  accountId: v.string(),
+  scopeKey: v.string(),
+  currency: v.string(),
+};
+export const totalsFields = {
+  amountDue: v.number(),
+  collectedAmount: v.number(),
+  reservedAmount: v.number(),
+  outstanding: v.number(),
+};
+export const signValidator = v.union(
+  v.literal("positive"),
+  v.literal("negative"),
+  v.literal("zero"),
+);
+export const observationFields = {
+  ...scopeFields,
+  claimKey: v.string(),
+  sourceChargeId: v.string(),
+  sourceGross: v.number(),
+  sourceProcessingFee: v.number(),
+  amountDue: v.number(),
+  revision: v.number(),
+};
+export const claimFields = {
+  ...observationFields,
+  collectedAmount: v.number(),
+  reservedAmount: v.number(),
+  outstanding: v.number(),
+  sign: signValidator,
+};
+export const claimDoc = v.object({
+  ...claimFields,
+  _id: v.id("recoveryClaims"),
+  _creationTime: v.number(),
+});
+export const balanceFields = {
+  ...scopeFields,
+  ...totalsFields,
+  activeGroupKey: v.optional(v.string()),
+};
+export const groupInput = {
+  ...scopeFields,
+  groupKey: v.string(),
+  sourceKind: v.union(v.literal("settlement"), v.literal("invoice")),
+  sourceId: v.string(),
+  sourceGross: v.optional(v.number()),
+  sourceProcessingFee: v.optional(v.number()),
+  maxDebit: v.number(),
+  maxCredit: v.number(),
+};
+export const groupFields = {
+  ...groupInput,
+  amount: v.number(),
+  pendingOperations: v.number(),
+  status: v.union(
+    v.literal("open"),
+    v.literal("sealed"),
+    v.literal("collecting"),
+    v.literal("releasing"),
+    v.literal("collected"),
+    v.literal("released"),
+  ),
+};
+export const groupDoc = v.object({
+  ...groupFields,
+  _id: v.id("recoveryGroups"),
+  _creationTime: v.number(),
+});
+export const reservationFields = {
+  operationKey: v.string(),
+  groupKey: v.string(),
+  amount: v.number(),
+  limit: v.number(),
+  allocations: v.array(
+    v.object({
+      claimId: v.id("recoveryClaims"),
+      claimKey: v.string(),
+      amount: v.number(),
+    }),
+  ),
+  status: v.union(
+    v.literal("reserved"),
+    v.literal("collected"),
+    v.literal("released"),
+    v.literal("empty"),
+  ),
+};
+export const reservationDoc = v.object({
+  ...reservationFields,
+  _id: v.id("recoveryReservations"),
+  _creationTime: v.number(),
+});
+export const claimsTable = defineTable(claimFields)
+  .index("by_key", ["claimKey"])
+  .index("by_scope", ["accountId", "scopeKey", "currency"])
+  .index("by_sign", ["accountId", "scopeKey", "currency", "sign"]);
+export const balancesTable = defineTable(balanceFields).index("by_scope", [
+  "accountId",
+  "scopeKey",
+  "currency",
+]);
+export const groupsTable = defineTable(groupFields).index("by_key", [
+  "groupKey",
+]);
+export const reservationsTable = defineTable(reservationFields)
+  .index("by_key", ["operationKey"])
+  .index("by_group_status", ["groupKey", "status"]);
+
+export const reserveArgs = {
+  ...groupInput,
+  operationKey: v.string(),
+  limit: v.optional(v.number()),
+};
+export const finishArgs = {
+  groupKey: v.string(),
+  outcome: v.union(v.literal("collect"), v.literal("release")),
+  limit: v.optional(v.number()),
+};
+export const rollbackArgs = {
+  groupKey: v.string(),
+  returnedPrincipal: v.number(),
+  revision: v.number(),
+};

package/src/component/schema.ts

@@ -1,3 +1,9 @@
+import {
+  claimsTable,
+  balancesTable,
+  groupsTable,
+  reservationsTable,
+} from "./costRecovery/schema";
 import {
   allocationsTable,
   commissionTermsTable,
@@ -24,6 +30,10 @@ import { pricesTable, productsTable } from "./products/schema";
 import { webhookEventsTable } from "./webhooks/schema";
 
 export default defineSchema({
+  recoveryClaims: claimsTable,
+  recoveryBalances: balancesTable,
+  recoveryGroups: groupsTable,
+  recoveryReservations: reservationsTable,
   settlementAllocations: allocationsTable,
   commissionTerms: commissionTermsTable,
   commissionDecisions: commissionDecisionsTable,

package/src/react/components/PayoutSchedule.render.test.tsx

@@ -176,3 +176,18 @@ describe("PayoutSchedule", () => {
     expect(BarrelExport).toBe(PayoutSchedule);
   });
 });
+it.each(["ugx", "isk"])(
+  "preserves observed fractional %s balances",
+  (currency) => {
+    const html = renderToStaticMarkup(
+      createElement(PayoutSchedule, {
+        balance: { currency, available: 101, pending: -1 },
+        children: ({ availableLabel, pendingLabel }) =>
+          createElement("p", null, `${availableLabel}|${pendingLabel}`),
+      }),
+    );
+    expect(html).toBe(
+      `<p>${currency.toUpperCase()} 1.01|-${currency.toUpperCase()} 0.01</p>`,
+    );
+  },
+);

package/src/react/components/PriceCard.render.test.tsx

@@ -30,6 +30,43 @@ const basePrice: PriceCardPrice = {
 };
 
 describe("PriceCard", () => {
+  it("accepts a translated custom price label and locale", () => {
+    const html = renderToStaticMarkup(
+      createElement(PriceCard, {
+        price: { ...basePrice, unitAmount: undefined },
+        customPriceLabel: "Preis auf Anfrage",
+        locale: "de-DE",
+      }),
+    );
+    expect(html).toContain("<p>Preis auf Anfrage</p>");
+    expect(
+      renderToStaticMarkup(
+        createElement(PriceCard, {
+          price: { ...basePrice, currency: "eur" },
+          locale: "de-DE",
+        }),
+      ),
+    ).toContain("20,00");
+  });
+  it("shows a zero-decimal charge without dividing by 100", () => {
+    const html = renderToStaticMarkup(
+      createElement(PriceCard, {
+        price: { ...basePrice, currency: "jpy", unitAmount: 500 },
+      }),
+    );
+    expect(html).toContain("<p>¥500/month</p>");
+  });
+
+  it("does not present a custom price as free in render props", () => {
+    const html = renderToStaticMarkup(
+      createElement(PriceCard, {
+        price: { ...basePrice, unitAmount: null },
+        children: ({ formattedPrice }) =>
+          createElement("p", null, formattedPrice),
+      }),
+    );
+    expect(html).toBe("<p>Custom price</p>");
+  });
   it("renders the formatted price inside the default card with role=option", () => {
     const html = renderToStaticMarkup(
       createElement(PriceCard, { price: basePrice }),

package/src/react/components/PriceCard.tsx

@@ -23,6 +23,8 @@ export type PriceCardProps = {
   /** i18n overrides */
   currentPlanLabel?: string;
   selectLabel?: string;
+  customPriceLabel?: string;
+  locale?: string;
   /** Render prop for full customization */
   children?: (props: {
     price: PriceCardPrice;
@@ -45,10 +47,16 @@ export function PriceCard({
   onSelect,
   currentPlanLabel = "Current plan",
   selectLabel = "Select",
+  customPriceLabel = "Custom price",
+  locale = "en-US",
   children,
   className,
 }: PriceCardProps) {
-  const formattedPrice = formatPriceWithInterval(price);
+  const formattedPrice = formatPriceWithInterval(
+    price,
+    locale,
+    customPriceLabel,
+  );
 
   if (children) {
     return (

package/src/react/index.test.ts

@@ -7,6 +7,11 @@ import { describe, expect, it } from "vitest";
 import * as ReactExports from "./index.js";
 
 describe("better-stripe/react barrel export", () => {
+  it("exports shared charge helpers with actual zero-decimal behavior", () => {
+    expect(ReactExports.parseChargeAmount("500", "jpy")).toBe(500);
+    expect(ReactExports.formatChargeAmount(500, "jpy")).toBe("¥500");
+    expect(ReactExports.getChargeCurrencyMetadata("isk")?.apiDecimals).toBe(2);
+  });
   it("exports all documented hook factories", () => {
     const hookFactories = [
       "createUseAccount",

package/src/react/index.ts

@@ -283,3 +283,10 @@ export {
 
 // Complete unstyled workflows
 export * from "./workflows/index.js";
+export {
+  chargeAmountToDecimal,
+  getChargeCurrencyMetadata,
+  parseChargeAmount,
+  formatChargeAmount,
+  type ChargeCurrencyMetadata,
+} from "../client/charge-currency.js";

package/src/react/lib/price-helpers.test.ts

@@ -8,6 +8,10 @@ import {
 } from "./price-helpers.js";
 
 describe("formatPrice", () => {
+  it("keeps fractional compatibility units from observed balances and costs", () => {
+    expect(formatPrice(101, "ugx")).toContain("1.01");
+    expect(formatPrice(-1, "isk")).toBe("-ISK 0.01");
+  });
   it("formats USD cents to dollars", () => {
     expect(formatPrice(2000, "usd")).toBe("$20.00");
   });
@@ -32,6 +36,15 @@ describe("formatPrice", () => {
 });
 
 describe("formatPriceWithInterval", () => {
+  it("supports translated custom prices without fabricating an interval", () => {
+    expect(
+      formatPriceWithInterval(
+        { currency: "usd", type: "recurring", interval: "month", active: true },
+        "en-US",
+        "Contact us",
+      ),
+    ).toBe("Contact us");
+  });
   it("shows amount only for one_time prices", () => {
     const result = formatPriceWithInterval({
       unitAmount: 2900,
@@ -80,7 +93,7 @@ describe("formatPriceWithInterval", () => {
     expect(result).toBe("$50.00 every 3 months");
   });
 
-  it("handles null unitAmount as zero", () => {
+  it("keeps a custom/null amount distinct from a zero price", () => {
     const result = formatPriceWithInterval({
       unitAmount: null,
       currency: "usd",
@@ -89,7 +102,7 @@ describe("formatPriceWithInterval", () => {
       intervalCount: null,
       active: true,
     });
-    expect(result).toBe("$0.00");
+    expect(result).toBe("Custom price");
   });
 });
 

package/src/react/lib/price-helpers.ts

@@ -1,6 +1,11 @@
 /**
  * Price formatting and filtering utilities.
  */
+import {
+  formatChargeAmount,
+  getChargeCurrencyMetadata,
+} from "../../client/charge-currency.js";
+import { renderCurrencyUnits } from "../../client/charge-currency-format.js";
 
 type PriceLike = {
   unitAmount?: number | null;
@@ -12,19 +17,29 @@ type PriceLike = {
 };
 
 /**
- * Format a price amount in cents to a display string.
+ * Legacy display helper for observed ordinary account/charge units.
+ * Preserves fractional ISK/UGX balances; does not validate charge eligibility.
  * e.g. 2000, 'usd' → '$20.00'
  */
 export function formatPrice(
-  amountInCents: number,
+  amount: number,
   currency: string,
   locale = "en-US",
 ): string {
-  return new Intl.NumberFormat(locale, {
-    style: "currency",
-    currency: currency.toUpperCase(),
-    minimumFractionDigits: 2,
-  }).format(amountInCents / 100);
+  const metadata = getChargeCurrencyMetadata(currency);
+  if (!metadata || !Number.isSafeInteger(amount))
+    throw new RangeError("Invalid amount or unsupported currency");
+  const displayDecimals =
+    amount % 10 ** metadata.apiDecimals === 0
+      ? metadata.displayDecimals
+      : metadata.apiDecimals;
+  return renderCurrencyUnits(
+    amount,
+    metadata.currency,
+    metadata.apiDecimals,
+    displayDecimals,
+    locale,
+  );
 }
 
 /**
@@ -34,8 +49,10 @@ export function formatPrice(
 export function formatPriceWithInterval(
   price: PriceLike,
   locale = "en-US",
+  customPriceLabel = "Custom price",
 ): string {
-  const amount = formatPrice(price.unitAmount ?? 0, price.currency, locale);
+  if (price.unitAmount == null) return customPriceLabel;
+  const amount = formatChargeAmount(price.unitAmount, price.currency, locale);
   if (price.type === "one_time" || !price.interval) {
     return amount;
   }

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

@@ -34,7 +34,7 @@ it("loads an itemized estimate only when requested and displays the server total
     nextBillingAt: 1800000000000,
     lines: [
       { id: "plan", description: "Store plan", amount: 2900 },
-      { id: "cost", description: "Refund costs", amount: 800 },
+      { id: "cost", description: "Refund costs", amount: 700 },
     ],
   });
   render(<InvoiceEstimate scopeKey="seller" load={load} />);

package/src/react/workflows/PlanPricingEditor.currency.test.tsx

@@ -0,0 +1,164 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+import type { ComponentProps } from "react";
+import { act, cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, expect, it, vi } from "vitest";
+import { PlanPricingEditor } from "./PlanPricingEditor.js";
+afterEach(cleanup);
+const plan = {
+  id: "plan",
+  name: "Plan",
+  monthlyAmount: 500,
+  feeBasisPoints: 500,
+  affiliateBasisPoints: 4000,
+  version: 1,
+};
+
+it.each([
+  ["usd", 500, "5.00", "12.34", 1234, "decimal"],
+  ["jpy", 500, "500", "600", 600, "numeric"],
+  ["mga", 500, "500", "600", 600, "numeric"],
+  ["isk", 50000, "500", "600", 60000, "numeric"],
+  ["ugx", 50000, "500", "600", 60000, "numeric"],
+  ["huf", 1045, "10.45", "12.34", 1234, "decimal"],
+  ["twd", 1045, "10.45", "12.34", 1234, "decimal"],
+  [
+    "usd",
+    Number.MAX_SAFE_INTEGER,
+    "90071992547409.91",
+    "90071992547409.91",
+    Number.MAX_SAFE_INTEGER,
+    "decimal",
+  ],
+])(
+  "initializes and saves exact %s provider price units",
+  async (currency, monthlyAmount, initial, input, expected, inputMode) => {
+    const onSave = vi.fn().mockResolvedValue(undefined);
+    render(
+      <PlanPricingEditor
+        plan={{ ...plan, currency, monthlyAmount }}
+        onSave={onSave}
+      />,
+    );
+    const field = screen.getByLabelText(
+      `Monthly price (${currency.toUpperCase()})`,
+    );
+    expect(field).toHaveValue(initial);
+    expect(field).toHaveAttribute("inputmode", inputMode);
+    await userEvent.clear(field);
+    await userEvent.type(field, input);
+    await userEvent.click(screen.getByRole("button", { name: "Save pricing" }));
+    expect(onSave).toHaveBeenCalledWith({
+      monthlyAmount: expected,
+      feeBasisPoints: 500,
+      affiliateBasisPoints: 4000,
+      expectedVersion: 1,
+    });
+  },
+);
+
+it.each([
+  ["jpy", "0.5"],
+  ["mga", "1.5"],
+  ["isk", "1.01"],
+  ["ugx", "1.01"],
+  ["usd", "1.005"],
+  ["usd", "90071992547409.92"],
+  ["usd", "0"],
+  ["usd", "1e2"],
+  ["ZZZ", "1"],
+  ["bhd", "1"],
+])(
+  "rejects invalid %s price %s before the callback",
+  async (currency, value) => {
+    const onSave = vi.fn();
+    render(<PlanPricingEditor plan={{ ...plan, currency }} onSave={onSave} />);
+    const field = screen.getByLabelText(
+      `Monthly price (${currency.toUpperCase()})`,
+    );
+    await userEvent.clear(field);
+    await userEvent.type(field, value);
+    await userEvent.click(screen.getByRole("button", { name: "Save pricing" }));
+    expect(screen.getByRole("alert")).toBeTruthy();
+    expect(onSave).not.toHaveBeenCalled();
+  },
+);
+
+it("resets currency-scoped headless fields and ignores a late previous save", async () => {
+  let resolveOld: (() => void) | undefined;
+  const onSave = vi
+    .fn()
+    .mockImplementationOnce(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveOld = resolve;
+        }),
+    )
+    .mockResolvedValue(undefined);
+  const children = (
+    state: Parameters<
+      NonNullable<ComponentProps<typeof PlanPricingEditor>["children"]>
+    >[0],
+  ) => (
+    <>
+      <output>
+        {state.monthlyPrice}|{state.isPending ? "pending" : "idle"}|
+        {state.message ?? ""}
+      </output>
+      <button onClick={() => void state.save()}>Save</button>
+      <button onClick={() => state.setMonthlyPrice("777")}>Edit</button>
+    </>
+  );
+  const { rerender } = render(
+    <PlanPricingEditor plan={{ ...plan, currency: "usd" }} onSave={onSave}>
+      {children}
+    </PlanPricingEditor>,
+  );
+  await userEvent.click(screen.getByRole("button", { name: "Save" }));
+  expect(screen.getByRole("status")).toHaveTextContent("pending");
+  rerender(
+    <PlanPricingEditor plan={{ ...plan, currency: "jpy" }} onSave={onSave}>
+      {children}
+    </PlanPricingEditor>,
+  );
+  expect(screen.getByRole("status")).toHaveTextContent("500|idle|");
+  await act(async () => resolveOld?.());
+  expect(screen.getByRole("status")).toHaveTextContent("500|idle|");
+  await userEvent.click(screen.getByRole("button", { name: "Save" }));
+  expect(onSave).toHaveBeenLastCalledWith({
+    monthlyAmount: 500,
+    feeBasisPoints: 500,
+    affiliateBasisPoints: 4000,
+    expectedVersion: 1,
+  });
+  await userEvent.click(screen.getByRole("button", { name: "Edit" }));
+  rerender(
+    <PlanPricingEditor
+      plan={{ ...plan, currency: "jpy", version: 2, monthlyAmount: 600 }}
+      onSave={onSave}
+    >
+      {children}
+    </PlanPricingEditor>,
+  );
+  expect(screen.getByRole("status")).toHaveTextContent("600|idle|");
+});
+
+it("keeps currency-aware retries on the same plan version", async () => {
+  const onSave = vi
+    .fn()
+    .mockRejectedValueOnce(new Error("Retry"))
+    .mockResolvedValue(undefined);
+  render(
+    <PlanPricingEditor plan={{ ...plan, currency: "jpy" }} onSave={onSave} />,
+  );
+  await userEvent.click(screen.getByRole("button", { name: "Save pricing" }));
+  expect(screen.getByRole("alert")).toHaveTextContent("Retry");
+  await userEvent.click(screen.getByRole("button", { name: "Save pricing" }));
+  expect(onSave).toHaveBeenNthCalledWith(2, {
+    monthlyAmount: 500,
+    feeBasisPoints: 500,
+    affiliateBasisPoints: 4000,
+    expectedVersion: 1,
+  });
+});

package/src/react/workflows/PlanPricingEditor.tsx

@@ -1,10 +1,17 @@
 "use client";
 import { useId, useState, type ReactNode } from "react";
+import {
+  chargeAmountToDecimal,
+  getChargeCurrencyMetadata,
+  parseChargeAmount,
+} from "../../client/charge-currency.js";
 import { useWorkflowAction } from "./useWorkflowAction.js";
 export type PlanPricing = {
   id: string;
   name: string;
   monthlyAmount: number;
+  /** Defaults to USD for existing consumers. Charge/Price currency, not payout units. */
+  currency?: string;
   feeBasisPoints: number | null;
   affiliateBasisPoints?: number | null;
   version: number;
@@ -16,6 +23,8 @@ export type PlanPricingUpdate = {
   expectedVersion: number;
 };
 export type PlanPricingEditorState = {
+  currency: string;
+  inputDecimalPlaces: 0 | 2 | null;
   monthlyPrice: string;
   saleFee: string;
   affiliateShare: string;
@@ -39,24 +48,27 @@ export function PlanPricingEditor({
   children,
 }: PlanPricingEditorProps) {
   const id = useId();
-  const scope = `${plan.id}:${plan.version}`;
+  const currency = (plan.currency ?? "usd").toLowerCase();
+  const metadata = getChargeCurrencyMetadata(currency);
+  const scope = `${plan.id}:${plan.version}:${currency}`;
   const initial = {
     scope,
     affiliateShare: String((plan.affiliateBasisPoints ?? 0) / 100),
-    monthlyPrice: (plan.monthlyAmount / 100).toFixed(2),
+    monthlyPrice: chargeAmountToDecimal(plan.monthlyAmount, currency) ?? "",
     saleFee:
       plan.feeBasisPoints === null ? "" : String(plan.feeBasisPoints / 100),
   };
   const [fields, setFields] = useState(initial);
   if (fields.scope !== scope) setFields(initial);
   const action = useWorkflowAction(async () => {
-    if (!/^\d+(\.\d{1,2})?$/.test(fields.monthlyPrice.trim()))
+    const monthlyAmount = parseChargeAmount(
+      fields.monthlyPrice.trim(),
+      currency,
+    );
+    if (monthlyAmount === null || monthlyAmount <= 0)
       throw new Error(
-        "Enter a positive monthly price with at most two decimal places.",
+        "Enter a positive monthly price in supported currency units.",
       );
-    const monthlyAmount = Math.round(Number(fields.monthlyPrice) * 100);
-    if (!Number.isSafeInteger(monthlyAmount) || monthlyAmount <= 0)
-      throw new Error("Enter a positive monthly price.");
     const feeBasisPoints =
       fields.saleFee.trim() === ""
         ? null
@@ -90,8 +102,10 @@ export function PlanPricingEditor({
       expectedVersion: plan.version,
     });
     return "Pricing saved. Existing subscriptions keep their monthly price.";
-  }, plan.id);
+  }, scope);
   const state: PlanPricingEditorState = {
+    currency,
+    inputDecimalPlaces: metadata?.displayDecimals ?? null,
     ...fields,
     setMonthlyPrice: (monthlyPrice) =>
       setFields((previous) => ({ ...previous, monthlyPrice })),
@@ -114,10 +128,12 @@ export function PlanPricingEditor({
       aria-label={`${plan.name} pricing`}
     >
       <h3>{plan.name}</h3>
-      <label htmlFor={`${id}-monthly`}>Monthly price (USD)</label>
+      <label htmlFor={`${id}-monthly`}>
+        Monthly price ({currency.toUpperCase()})
+      </label>
       <input
         id={`${id}-monthly`}
-        inputMode="decimal"
+        inputMode={state.inputDecimalPlaces === 0 ? "numeric" : "decimal"}
         value={state.monthlyPrice}
         disabled={state.isPending}
         onChange={(event) => state.setMonthlyPrice(event.target.value)}