@fantastic.dev/better-stripe 0.11.0 → 0.13.0

package/src/component/costRecovery/mutations.ts

@@ -0,0 +1,115 @@
+import { getGroup, integer } from "./helpers.js";
+import { v } from "convex/values";
+import { mutation } from "../_generated/server.js";
+import { recordClaim, rollbackClaim } from "./claims.js";
+import { reserveGroup, sealGroup } from "./reservations.js";
+import { finishGroup } from "./completion.js";
+import {
+  observationFields,
+  claimDoc,
+  groupDoc,
+  reservationDoc,
+  reserveArgs,
+  rollbackArgs,
+  finishArgs,
+} from "./schema.js";
+export const record = mutation({
+  args: observationFields,
+  returns: claimDoc,
+  handler: async (ctx, args) => {
+    if (args.claimKey.startsWith("rollback:"))
+      throw new Error("Rollback claim keys are reserved.");
+    return recordClaim(ctx, args);
+  },
+});
+export const rollback = mutation({
+  args: rollbackArgs,
+  returns: claimDoc,
+  handler: rollbackClaim,
+});
+export const reserve = mutation({
+  args: reserveArgs,
+  returns: v.object({ reservation: reservationDoc, group: groupDoc }),
+  handler: reserveGroup,
+});
+export const seal = mutation({
+  args: { groupKey: v.string() },
+  returns: groupDoc,
+  handler: sealGroup,
+});
+export const finish = mutation({
+  args: finishArgs,
+  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))!;
+  },
+});

package/src/component/costRecovery/queries.ts

@@ -0,0 +1,88 @@
+import { paginationOptsValidator } from "convex/server";
+import { v } from "convex/values";
+import { query } from "../_generated/server.js";
+import {
+  balanceFields,
+  claimDoc,
+  groupDoc,
+  scopeFields,
+  reservationDoc,
+} from "./schema.js";
+import {
+  readBalance,
+  scopeOnly,
+  validateScope,
+  batchLimit,
+} from "./helpers.js";
+export const balance = query({
+  args: scopeFields,
+  returns: v.object(balanceFields),
+  handler: async (ctx, args) => {
+    validateScope(args);
+    const stored = await readBalance(ctx, args);
+    return {
+      ...scopeOnly(args),
+      amountDue: stored?.amountDue ?? 0,
+      collectedAmount: stored?.collectedAmount ?? 0,
+      reservedAmount: stored?.reservedAmount ?? 0,
+      outstanding: stored?.outstanding ?? 0,
+      ...(stored?.activeGroupKey
+        ? { activeGroupKey: stored.activeGroupKey }
+        : {}),
+    };
+  },
+});
+export const listClaims = query({
+  args: { ...scopeFields, paginationOpts: paginationOptsValidator },
+  returns: v.object({
+    page: v.array(claimDoc),
+    continueCursor: v.string(),
+    isDone: v.boolean(),
+  }),
+  handler: async (ctx, args) => {
+    validateScope(args);
+    batchLimit(args.paginationOpts.numItems);
+    const result = await ctx.db
+      .query("recoveryClaims")
+      .withIndex("by_scope", (q) =>
+        q
+          .eq("accountId", args.accountId)
+          .eq("scopeKey", args.scopeKey)
+          .eq("currency", args.currency),
+      )
+      .order("desc")
+      .paginate(args.paginationOpts);
+    return {
+      page: result.page,
+      continueCursor: result.continueCursor,
+      isDone: result.isDone,
+    };
+  },
+});
+export const group = query({
+  args: { groupKey: v.string() },
+  returns: v.union(groupDoc, v.null()),
+  handler: (ctx, args) =>
+    ctx.db
+      .query("recoveryGroups")
+      .withIndex("by_key", (q) => q.eq("groupKey", args.groupKey))
+      .unique(),
+});
+export const reservation = query({
+  args: { operationKey: v.string() },
+  returns: v.union(reservationDoc, v.null()),
+  handler: (ctx, args) =>
+    ctx.db
+      .query("recoveryReservations")
+      .withIndex("by_key", (q) => q.eq("operationKey", args.operationKey))
+      .unique(),
+});
+export const claim = query({
+  args: { claimKey: v.string() },
+  returns: v.union(claimDoc, v.null()),
+  handler: (ctx, args) =>
+    ctx.db
+      .query("recoveryClaims")
+      .withIndex("by_key", (q) => q.eq("claimKey", args.claimKey))
+      .unique(),
+});

package/src/component/costRecovery/reservations.ts

@@ -0,0 +1,164 @@
+import { v } from "convex/values";
+import type { MutationCtx } from "../_generated/server.js";
+import { reserveArgs } from "./schema.js";
+import {
+  balance,
+  batchLimit,
+  getGroup,
+  groupTarget,
+  integer,
+  sign,
+  validateScope,
+} from "./helpers.js";
+
+import type { Infer } from "convex/values";
+const _reserveArgs = v.object(reserveArgs);
+export async function reserveGroup(
+  ctx: MutationCtx,
+  args: Infer<typeof _reserveArgs>,
+) {
+  validateScope(args);
+  const limit = args.limit ?? 100;
+  batchLimit(limit);
+  [args.maxDebit, args.maxCredit].forEach(integer);
+  if (
+    !args.groupKey.trim() ||
+    !args.operationKey.trim() ||
+    !args.sourceId ||
+    args.maxDebit < 0 ||
+    args.maxCredit < 0
+  )
+    throw new Error("Invalid recovery operation identity or limits.");
+  if (args.sourceGross !== undefined && integer(args.sourceGross) <= 0)
+    throw new Error("Funding gross must be positive.");
+  if (
+    args.sourceProcessingFee !== undefined &&
+    integer(args.sourceProcessingFee) < 0
+  )
+    throw new Error("Funding processing fee must be nonnegative.");
+  if (
+    args.sourceKind === "settlement" &&
+    (!args.sourceGross || args.sourceProcessingFee === undefined)
+  )
+    throw new Error("Settlement recovery requires original funding gross.");
+  let group = await ctx.db
+    .query("recoveryGroups")
+    .withIndex("by_key", (q) => q.eq("groupKey", args.groupKey))
+    .unique();
+  const existing = await ctx.db
+    .query("recoveryReservations")
+    .withIndex("by_key", (q) => q.eq("operationKey", args.operationKey))
+    .unique();
+  if (group)
+    for (const key of [
+      "accountId",
+      "scopeKey",
+      "currency",
+      "sourceKind",
+      "sourceId",
+      "sourceGross",
+      "sourceProcessingFee",
+      "maxDebit",
+      "maxCredit",
+    ] as const)
+      if (group[key] !== args[key])
+        throw new Error("Recovery group identity and limits cannot change.");
+  if (existing) {
+    if (
+      existing.groupKey !== args.groupKey ||
+      existing.limit !== limit ||
+      !group
+    )
+      throw new Error("Recovery operation identity cannot change.");
+    return { reservation: existing, group };
+  }
+  const ledger = await balance(ctx, args);
+  if (ledger.activeGroupKey && ledger.activeGroupKey !== args.groupKey)
+    throw new Error("Another recovery boundary is pending.");
+  if (group && group.status !== "open")
+    throw new Error(
+      "Recovery group is sealed; replay its existing operations.",
+    );
+  if (!group) {
+    const { operationKey: _operationKey, limit: _limit, ...input } = args;
+    const id = await ctx.db.insert("recoveryGroups", {
+      ...input,
+      amount: 0,
+      pendingOperations: 0,
+      status: "open",
+    });
+    group = (await ctx.db.get("recoveryGroups", id))!;
+  }
+  const delta = integer(groupTarget(group, ledger.outstanding) - group.amount);
+  const direction = sign(delta);
+  let remaining = Math.abs(delta),
+    amount = 0;
+  const allocations: {
+    claimId: import("../_generated/dataModel.js").Id<"recoveryClaims">;
+    claimKey: string;
+    amount: number;
+  }[] = [];
+  if (direction !== "zero") {
+    const claims = await ctx.db
+      .query("recoveryClaims")
+      .withIndex("by_sign", (q) =>
+        q
+          .eq("accountId", args.accountId)
+          .eq("scopeKey", args.scopeKey)
+          .eq("currency", args.currency)
+          .eq("sign", direction),
+      )
+      .take(limit);
+    for (const claim of claims) {
+      if (!remaining) break;
+      const take =
+        Math.min(remaining, Math.abs(claim.outstanding)) * (delta < 0 ? -1 : 1);
+      const reservedAmount = integer(claim.reservedAmount + take),
+        outstanding = integer(claim.outstanding - take);
+      await ctx.db.patch("recoveryClaims", claim._id, {
+        reservedAmount,
+        outstanding,
+        sign: sign(outstanding),
+      });
+      allocations.push({
+        claimId: claim._id,
+        claimKey: claim.claimKey,
+        amount: take,
+      });
+      amount = integer(amount + take);
+      remaining -= Math.abs(take);
+    }
+  }
+  const reservationId = await ctx.db.insert("recoveryReservations", {
+    operationKey: args.operationKey,
+    groupKey: args.groupKey,
+    amount,
+    limit,
+    allocations,
+    status: allocations.length ? "reserved" : "empty",
+  });
+  if (allocations.length) {
+    await ctx.db.patch("recoveryBalances", ledger._id, {
+      reservedAmount: integer(ledger.reservedAmount + amount),
+      outstanding: integer(ledger.outstanding - amount),
+      activeGroupKey: group.groupKey,
+    });
+    await ctx.db.patch("recoveryGroups", group._id, {
+      amount: integer(group.amount + amount),
+      pendingOperations: group.pendingOperations + 1,
+    });
+  }
+  return {
+    reservation: (await ctx.db.get("recoveryReservations", reservationId))!,
+    group: (await ctx.db.get("recoveryGroups", group._id))!,
+  };
+}
+export async function sealGroup(ctx: MutationCtx, args: { groupKey: string }) {
+  const group = await getGroup(ctx, args.groupKey);
+  if (group.status !== "open") return group;
+  const ledger = await balance(ctx, group);
+  if (groupTarget(group, ledger.outstanding) !== group.amount)
+    throw new Error("Recovery needs another reservation batch before sealing.");
+  await ctx.db.patch("recoveryGroups", group._id, { status: "sealed" });
+  return (await ctx.db.get("recoveryGroups", group._id))!;
+}

package/src/component/costRecovery/schema.ts

@@ -0,0 +1,135 @@
+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(),
+  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"),
+    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");
   });
 });