@pithy-sh/payments 0.1.0

package/src/client/paddlePricesTag.ts

@@ -0,0 +1,332 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PaymentsFailure, PaymentsResult } from "./api";
+import type { PaddleSetup } from "./paddle";
+import { type PaddleCacheStore, type PaddleQuoteCache, readQuoteCache } from "./paddleCache";
+import {
+  type PaddlePlanPrices,
+  type PaddlePlanQuote,
+  type PaddleQuoteOptions,
+  type PaddleQuoteQuery,
+  quotePlans,
+} from "./paddlePrices";
+
+/**
+ * The script tag as configuration, for a site with no build step.
+ *
+ * A static site loads one classic script and gets prices. It cannot import a module, it has no bundler,
+ * and it must not carry a price id in its markup — an id belongs to one Paddle account, so it is
+ * environment-specific and a page that names one is a page that quotes the wrong account the day the
+ * account changes. So the ids arrive on the tag, where whoever deploys the site puts them, and the page
+ * itself names only plans.
+ */
+
+/** The tag names no account, or is still carrying the placeholders it was scaffolded with. */
+export const PADDLE_PRICES_NOT_CONFIGURED: PaymentsFailure = {
+  code: "client/paddle_prices_not_configured",
+  message: "Prices aren't available right now.",
+  action:
+    "Set data-paddle-env, data-paddle-token and every data-paddle-price-<name> id on the paddle-prices script tag.",
+};
+
+/** The slice of a script element this reads, declared structurally for the reason `./checkout` gives. */
+export interface PaddlePricesTag {
+  /** Every attribute on the tag, so the `data-paddle-price-*` set can be enumerated rather than guessed. */
+  getAttributeNames(): readonly string[];
+  /** One attribute's value, or null. */
+  getAttribute(name: string): string | null;
+}
+
+/** What a configured tag says. */
+export interface PaddlePricesTagConfig {
+  /** Which Paddle account answers, and with which publishable token. */
+  readonly setup: PaddleSetup;
+  /** Plan name to price id, one entry per `data-paddle-price-*` attribute. */
+  readonly plans: PaddlePlanPrices;
+  /** Whether to write the totals into the page, or only to hand them to whoever asked. */
+  readonly paint: boolean;
+  /**
+   * Whether the page asked for a zero fraction to be dropped from each figure — `$6.00` as `$6`.
+   *
+   * False unless the tag said `on`, and false for any other value. A seller who prices in whole numbers
+   * is the one who knows it, and a mistyped attribute leaves every figure exactly as Paddle rendered it,
+   * which is the safe half of the two. See `./wholeUnits`.
+   */
+  readonly wholeUnits: boolean;
+  /** Who to quote for. Empty unless the tag named a customer, which is a visitor Paddle knows. */
+  readonly query: PaddleQuoteQuery;
+  /** Where a quote may rest, or null — which is every tag that did not ask for a cache, and every tag
+   * that asked for half of one. */
+  readonly cache: PaddleQuoteCache | null;
+}
+
+/**
+ * The two stores a script tag can name, injectable so a suite can look inside one.
+ *
+ * A tag cannot hand over an object, so it names a store rather than passing one — `local` or `session`,
+ * the only two a browser has. Everywhere else in this kit the caller passes the store itself, and that
+ * stays true: this is the one surface where the caller is HTML.
+ */
+export interface PricesCacheStores {
+  /** What `data-paddle-cache-store="local"` resolves to. Defaults to `globalThis.localStorage`. */
+  readonly local?: PaddleCacheStore | null;
+  /** What `data-paddle-cache-store="session"` resolves to. Defaults to `globalThis.sessionStorage`. */
+  readonly session?: PaddleCacheStore | null;
+}
+
+/** The prefix that marks an attribute as naming a plan. */
+const PRICE_PREFIX = "data-paddle-price-";
+
+/** The token prefix each Paddle account issues. Sandbox and live are separate accounts, not a flag. */
+const CLIENT_TOKEN: Readonly<Record<PaddleSetup["environment"], string>> = {
+  sandbox: "test_",
+  production: "live_",
+};
+
+/** A real Paddle price. */
+const PRICE_ID = /^pri_/;
+
+/** A real Paddle customer. */
+const CUSTOMER_ID = /^ctm_/;
+
+/**
+ * One of the browser's own stores, or null where there is not one.
+ *
+ * Guarded rather than read, because reaching for `localStorage` **throws** where a browser has storage
+ * switched off or a sandboxed frame denies it — a page that quotes prices would take that exception on
+ * the way to asking Paddle a question it could have asked anyway.
+ */
+function browserStore(name: "localStorage" | "sessionStorage"): PaddleCacheStore | null {
+  try {
+    const held = (globalThis as { localStorage?: PaddleCacheStore; sessionStorage?: PaddleCacheStore })[name];
+    return held ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The store a tag named, the **name** it gave when nothing resolved, or null when it named nothing.
+ *
+ * The three are different and used to be two. `data-paddle-cache-store="localStorage"` is the likely
+ * typo — the accepted value is `local` — and collapsing it into the same null a bare tag produces made
+ * it the one misconfiguration that got no console line, because "did anybody ask for a cache?" had
+ * nothing left to see. Handing the name back is what makes an unresolvable store an answer.
+ *
+ * An injected `null` is honored as an answer too: `PricesCacheStores` says `PaddleCacheStore | null`,
+ * so null means *this environment has none* — a suite saying so, or an adopter's SSR-safe wrapper — and
+ * quietly resolving the browser's real store instead would exercise the opposite path from the one the
+ * caller named.
+ */
+function storeNamed(named: string | null, stores?: PricesCacheStores): PaddleCacheStore | string | null {
+  if (named === "local") return stores?.local !== undefined ? stores.local : (browserStore("localStorage") ?? named);
+  if (named === "session") {
+    return stores?.session !== undefined ? stores.session : (browserStore("sessionStorage") ?? named);
+  }
+  return named;
+}
+
+/**
+ * A lifetime in seconds, as milliseconds.
+ *
+ * Seconds on the attribute because a tag is HTML and HTML counts a cache in seconds — `max-age`, and
+ * every header that copied it. `NaN` rather than null for text that is not a number, so a tag that
+ * tried to state a lifetime and failed is a warning rather than a silence.
+ */
+function lifetime(value: string | null): number | null {
+  if (value === null) return null;
+  const seconds = Number(value);
+  return Number.isFinite(seconds) ? seconds * 1000 : Number.NaN;
+}
+
+/**
+ * Read a tag's configuration, or refuse it.
+ *
+ * **Refusal is the whole point of this function, and it is why the shapes are checked rather than
+ * trusted.** A site is deployed with the placeholders still in it far more often than anyone plans to:
+ * the live account is opened weeks after the sandbox one, and the tag ships carrying
+ * `REPLACE_WITH_LIVE_CLIENT_TOKEN` in the meantime. Handing that to Paddle produces a refused
+ * initialization, a console warning nobody is watching, and — because a page that has already blanked
+ * its own sentence has nothing left to fall back to — an empty price slot that looks deliberate. That is
+ * `#416` arriving by a second road.
+ *
+ * So an unconfigured tag is not an error and not a quote. It is null, and a null tag paints nothing, so
+ * the sentence the page shipped with is still standing. **All or nothing across the plans**: one plan
+ * still on a placeholder refuses the tag rather than quoting the others, because a pricing table with
+ * one real figure and one placeholder is the version a reader believes.
+ *
+ * **The token is checked against the environment beside it, not merely for a prefix.** The half-updated
+ * deploy above has a second shape: the environment is switched to `production` and the token below it is
+ * still the sandbox one. Paddle refuses that pairing itself, eventually — after the page has fetched
+ * Paddle.js and spent a round trip finding out. Refusing it here is what makes "no request" true of
+ * every misconfigured tag rather than of most of them.
+ */
+export function readPaddlePricesTag(
+  tag: PaddlePricesTag | null,
+  stores?: PricesCacheStores,
+): PaddlePricesTagConfig | null {
+  if (tag === null) return null;
+  const environment = tag.getAttribute("data-paddle-env");
+  if (environment !== "sandbox" && environment !== "production") return null;
+  const clientToken = tag.getAttribute("data-paddle-token");
+  if (clientToken === null || !clientToken.startsWith(CLIENT_TOKEN[environment])) return null;
+
+  const plans: Record<string, string> = {};
+  for (const name of tag.getAttributeNames()) {
+    if (!name.startsWith(PRICE_PREFIX)) continue;
+    const priceId = tag.getAttribute(name);
+    if (priceId === null || !PRICE_ID.test(priceId)) return null;
+    plans[name.slice(PRICE_PREFIX.length)] = priceId;
+  }
+  if (Object.keys(plans).length === 0) return null;
+
+  // **A customer that is not one is dropped, not refused** — the opposite call to the one a placeholder
+  // price id gets one line above, and deliberately. A wrong price is unrecoverable, so a placeholder id
+  // takes the whole tag down. A missing customer costs the visitor a quote resolved from their IP and
+  // marked `estimated`, which is exactly what every anonymous visitor already sees, and is a great deal
+  // better than a pricing table with no figures in it.
+  const named = tag.getAttribute("data-paddle-customer")?.trim() ?? "";
+  const query: PaddleQuoteQuery = CUSTOMER_ID.test(named) ? { customerId: named } : {};
+
+  const cache = readQuoteCache({
+    key: tag.getAttribute("data-paddle-cache"),
+    store: storeNamed(tag.getAttribute("data-paddle-cache-store"), stores),
+    ttlMs: lifetime(tag.getAttribute("data-paddle-cache-ttl")),
+  });
+
+  return {
+    setup: { clientToken, environment },
+    plans,
+    paint: tag.getAttribute("data-paddle-paint") !== "off",
+    // The opposite polarity to `paint`, and deliberately: painting is what the artifact is for, so it is
+    // on until a page opts out, while a pricing decision is off until a page opts in.
+    wholeUnits: tag.getAttribute("data-paddle-whole-units") === "on",
+    query,
+    cache,
+  };
+}
+
+/** What {@link mountPrices} lets a caller replace, plus the stores a tag may name. */
+export interface MountPricesOptions extends PaddleQuoteOptions {
+  /** What `data-paddle-cache-store` resolves to. Defaults to the browser's own two. */
+  readonly stores?: PricesCacheStores;
+}
+
+/** The slice of a plan slot this writes. */
+export interface PricesPlanNode {
+  /** Which plan the slot is for. */
+  getAttribute(name: string): string | null;
+  /** The sentence in the slot — the page's own until a quote replaces it. */
+  textContent: string | null;
+}
+
+/** The slice of `document` this reaches, as an injectable seam. */
+export interface PricesDocument {
+  /** Whether the page is still being parsed, so the slots to paint may not all exist yet. */
+  readyState: string;
+  /** How the paint waits for the rest of the page. */
+  addEventListener(type: string, listener: () => void, options?: { once?: boolean }): void;
+  /** Every plan slot on the page. */
+  querySelectorAll(selectors: string): ArrayLike<PricesPlanNode>;
+}
+
+/** The attribute a page marks a plan slot with. */
+const PLAN_SLOT = "data-price-plan";
+
+/** The attribute a page marks the sentence beside a figure with. */
+const NOTE_SLOT = "data-price-note";
+
+/**
+ * Match a plan named on the tag to a plan named in the markup.
+ *
+ * Case-insensitively, and that is forced rather than lenient. A plan arrives on the tag as part of an
+ * *attribute name* — `data-paddle-price-teamPlus` — and HTML lower-cases those, so the tag can only ever say
+ * `teamplus`. In the markup the same plan is an attribute *value*, `data-price-plan="teamPlus"`, which
+ * keeps its case. Matching exactly would leave that slot on its placeholder with nothing anywhere saying
+ * why.
+ */
+function samePlan(named: string | null, quoted: string): boolean {
+  return named !== null && named.toLowerCase() === quoted.toLowerCase();
+}
+
+/**
+ * Write each quote into the slot that named its plan, and the sentence that makes it true beside it.
+ *
+ * **The headline alone is not the price, and a page that shows only the headline is the defect the quote
+ * path exists to avoid.** Where tax is added on top — the United States convention — the headline is the
+ * subtotal and the buyer is charged more; where no postal code resolved, Paddle returns 0% tax and the
+ * card is charged up to 15% above the figure. `priceSummary` returns a sentence for each of those cases,
+ * and this puts it in `[data-price-note="<plan>"]`. A page quoting a tax-added price wants that slot.
+ *
+ * **A slot no quote names is left exactly as it was**, and so is a note slot for a quote with nothing to
+ * say. A pricing page ships a true sentence in every slot — "Priced where you are billed" — precisely so
+ * that a plan which cannot be quoted still says something honest. Blanking it, or writing `undefined`
+ * into it, replaces a true sentence with a worse one; leaving it is the whole reason it is there.
+ */
+export function paintPlanQuotes(document: PricesDocument, quotes: readonly PaddlePlanQuote[]): void {
+  // `Array.from` because the seam is an `ArrayLike` — a `NodeList` in a browser, and something else in a
+  // test — and indexing one is where an off-by-one would live.
+  for (const slot of Array.from(document.querySelectorAll(`[${PLAN_SLOT}]`))) {
+    const quote = quotes.find((candidate) => samePlan(slot.getAttribute(PLAN_SLOT), candidate.plan));
+    if (quote === undefined) continue;
+    slot.textContent = quote.headline;
+  }
+  for (const slot of Array.from(document.querySelectorAll(`[${NOTE_SLOT}]`))) {
+    const quote = quotes.find((candidate) => samePlan(slot.getAttribute(NOTE_SLOT), candidate.plan));
+    if (quote === undefined || quote.note === null) continue;
+    slot.textContent = quote.note;
+  }
+}
+
+/** Resolve once the page has the slots this paints into. */
+function parsed(document: PricesDocument): Promise<void> {
+  if (document.readyState !== "loading") return Promise.resolve();
+  return new Promise((resolve) => {
+    document.addEventListener("DOMContentLoaded", () => resolve(), { once: true });
+  });
+}
+
+/**
+ * Read the tag, quote its plans, and — unless the page said it paints itself — put the figures on it.
+ *
+ * The one entry point the browser build calls, and the one place the three halves meet: configuration
+ * off the tag, the quote from `./prices`, and the page. It answers with the result rather than swallowing
+ * it, so a page that keeps its own cache and its own formatting can have the same answer this painted.
+ */
+export async function mountPrices(
+  document: PricesDocument,
+  tag: PaddlePricesTag | null,
+  options?: MountPricesOptions,
+): Promise<PaymentsResult<readonly PaddlePlanQuote[]>> {
+  const { stores, ...given } = options ?? {};
+  const config = readPaddlePricesTag(tag, stores);
+  if (config === null) return { ok: false, failure: PADDLE_PRICES_NOT_CONFIGURED };
+
+  // The tag is the page's configuration; an explicit option is a caller who knows better than the
+  // markup — a screen mounting this itself, or a test. Neither is common and both are legitimate, so
+  // the more specific one wins and the tag fills in the rest.
+  //
+  // **The query merges, field by field; the cache does not.** A query is a bag of independent facts, and
+  // a dashboard that server-renders `data-paddle-customer` onto the tag and passes an address from the
+  // screen means both — replacing wholesale would drop the customer and quote from the network again,
+  // which is the defect this module exists to remove. A cache is one indivisible decision about where a
+  // price rests and for how long, so half of the tag's and half of the caller's is not a cache anybody
+  // chose.
+  const quoted = await quotePlans(config.setup, config.plans, {
+    ...given,
+    query: { ...config.query, ...given.query },
+    cache: given.cache ?? config.cache ?? undefined,
+    // One boolean, so the more specific answer wins outright — a caller passing `false` over a tag that
+    // said `on` is saying so, and `??` is what keeps that from reading as "nobody asked".
+    wholeUnits: given.wholeUnits ?? config.wholeUnits,
+  });
+  if (!quoted.ok || !config.paint) return quoted;
+  // **The quote starts immediately and the paint waits.** A third-party tag's usual home is `<head>`,
+  // where nothing it paints into has been parsed yet — so a paint that ran the moment Paddle answered
+  // would find some of the page's slots, or none, and leave the rest on their placeholders for good.
+  // Starting the round trip early is the reason to load early; only the writing has to wait.
+  await parsed(document);
+  paintPlanQuotes(document, quoted.value);
+  return quoted;
+}

package/src/client/projection.ts

@@ -0,0 +1,133 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * One product, browser-safe — an element of {@link PaymentsClientProjection}'s catalog.
+ *
+ * Declared as its own type because the element type is the half a value-derived shape loses first: a
+ * catalog of one product infers one product's shape, and every branch the next product would have taken
+ * — an empty `entitlements`, a SKU on a rail the first product does not sell — is simply not in it.
+ *
+ * **It is annotated on the `.map` callback, not on the array it builds.** Measured, and the difference
+ * matters: `const products: PaymentsClientProduct[] = …map(…)` type-checks the *result*, by which point
+ * the element literals are no longer fresh, so a product that grew an `apple` SKU passed silently. On the
+ * callback's own return type the literal is checked where it is written, and the store-only field is a
+ * compile error at the line that added it.
+ */
+export type PaymentsClientProduct = {
+  /** The logical product id — what `/payments/checkout` is asked for. */
+  id: string;
+  /** What kind of product it is. */
+  type: "consumable" | "non_consumable" | "subscription";
+  /** The entitlement keys it grants. Gating code names these, never the product. */
+  entitlements: string[];
+  /** The display name a paywall renders. */
+  name: string;
+  /**
+   * This product's SKU on each web rail, or null where it is not sold. Keyed by rail rather than one
+   * field per rail, so a screen asks `skus[rail]` and a new rail cannot leave a `purchasable()` check
+   * silently out of date. Every id here is publishable by design — each is what a checkout names.
+   *
+   * Apple's and Google's product ids are deliberately absent: a browser cannot open either store.
+   */
+  skus: {
+    /** The Stripe price id. */
+    stripe: string | null;
+    /** The Lemon Squeezy variant id. */
+    lemonSqueezy: string | null;
+    /** The Paddle price id. */
+    paddle: string | null;
+  };
+};
+
+/**
+ * What a browser may know about this project's payments — the shape of `virtual:pithy/payments`.
+ *
+ * **This declaration is the contract, and the projection is checked against it.** It is written here
+ * rather than inferred from the closure that builds it, and that is the whole point: an inferred type
+ * follows whatever the producer last happened to say, so a projection that dropped `basePath`, or that
+ * widened `type` because `PaymentsConfig` learned a fourth product kind, or that started passing a
+ * product's Apple id through, would take the type with it and nothing would go red. Declared, the
+ * function is the thing that has to change — every widening of what a browser sees is decided here.
+ *
+ * Nothing sensitive is in reach of the producer to begin with: Apple's issuer key, Google's service
+ * account, and Stripe's secret and signing keys live in the secrets store behind
+ * `paymentsSecretsRegistry`, not in the config the closure can see. What this type covers is the rest of
+ * the catalog — the `grants` block and the store-only SKUs, which are omissions of judgment rather than
+ * of reach, and so are the ones worth writing down.
+ *
+ * **`billingSubject` is a third omission of judgment, and it is deliberate.** The subject *id* obviously
+ * never crosses — it is a fact about one caller, and this projection is inlined into a bundle every caller
+ * receives, so there is no request here to be right about. But the mode is not a secret and is left out
+ * anyway, on the plainer ground that nothing in a browser can use it. A paywall renders products and buy
+ * buttons; who holds what it buys is decided on the server, on the request, by the subject seam, and a
+ * screen that branched on the mode would be a second copy of that decision drifting from the first. The
+ * shape is also not free: this type is what `@pithy-sh/vite` generates `templates/client-env.d.ts` from, so
+ * a key added here is a key added to every adopter's ambient declaration. It goes in the day something in
+ * a browser genuinely cannot be written without it, and not before.
+ *
+ * **This is the only statement of the shape.** `@pithy-sh/ui-react`'s `templates/client-env.d.ts` — the
+ * ambient declaration `pithy ui add react` copies into an adopter's Worker — is generated from this type
+ * by `@pithy-sh/vite`'s `clientEnvDeclaration.ts` (#398). The unions and the per-field doc comments below
+ * are emitted verbatim, so what is written here is what a screen author reads.
+ */
+export type PaymentsClientProjection =
+  | {
+      /**
+       * Payments is not composed, or has no catalog this environment can render. Both read the same on
+       * purpose: "composed with nothing to sell" is a paywall with nothing on it, exactly like "not
+       * composed", and a screen branches on one value rather than guarding.
+       */
+      enabled: false;
+    }
+  | {
+      /** Payments is composed AND has a catalog this environment can render. */
+      enabled: true;
+      /** The environment this bundle was built for. */
+      environment: string;
+      /**
+       * Which rails this project sells through. Apple and Google are display-only on the web — a
+       * paywall shows such a product as owned-elsewhere rather than offering a buy button nothing on
+       * the web can honor.
+       */
+      rails: {
+        /** Whether the App Store rail is on. Display-only in a browser. */
+        apple: boolean;
+        /** Whether the Play Store rail is on. Display-only in a browser. */
+        google: boolean;
+        /** Whether the Stripe rail is on. */
+        stripe: boolean;
+        /** Whether the Lemon Squeezy rail is on. */
+        lemonSqueezy: boolean;
+        /** Whether the Paddle rail is on. */
+        paddle: boolean;
+      };
+      /**
+       * What Paddle.js needs to initialize, or null when the rail is off. The client token is
+       * publishable by design — it is what a browser opens a checkout with — and the API key and the
+       * webhook signing secret are neither here nor expressible here.
+       */
+      paddle: {
+        /** The publishable client token Paddle.js initializes with. */
+        clientToken: string;
+        /** Which Paddle account the token belongs to. */
+        environment: "sandbox" | "production";
+        /**
+         * How checkout is presented: `overlay` opens Paddle.js over your own page, `inline` renders it
+         * into a container the screen provides, `hosted` redirects to Paddle's own page.
+         *
+         * The union is stated, not `string`. A screen switches on this to decide whether to render a
+         * container at all, and the exhaustiveness is the point. It was the one field the hand-written
+         * `templates/client-env.d.ts` widened, and generating that file from here is what closed it.
+         */
+        checkout: "overlay" | "inline" | "hosted";
+      } | null;
+      /** Where the payments routes mount, e.g. `/payments`. */
+      basePath: string;
+      /**
+       * The catalog, browser-safe, in the order the adopter wrote it. A web rail's price id is
+       * publishable by design — a checkout names one. Apple's and Google's SKUs, and anything a
+       * purchase fulfills beyond its entitlements, stay server-side.
+       */
+      products: PaymentsClientProduct[];
+    };

package/src/client/test-utils/cacheStore.ts

@@ -0,0 +1,41 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PaddleCacheStore } from "../paddleCache";
+
+/**
+ * A {@link PaddleCacheStore} a test can look inside.
+ *
+ * `localStorage` is the store an adopter passes and the wrong one to test against: a suite that reached
+ * for it would need a DOM, would leak entries between tests, and could not answer "what is in there now"
+ * without re-deriving the key the module chose. This is a `Map`, and the `Map` is exposed — so a test can
+ * assert an entry was written, corrupt one to see what happens next, or count what a run left behind.
+ *
+ * It enumerates, because `Storage` does: `length` and `key` are what a sweep walks, and a stand-in
+ * missing them would quietly exercise the un-swept path on every test that thought it was testing one.
+ */
+export function memoryStore(): PaddleCacheStore & { entries: Map<string, string> } {
+  const entries = new Map<string, string>();
+  return {
+    entries,
+    get length() {
+      return entries.size;
+    },
+    key: (index: number) => [...entries.keys()][index] ?? null,
+    getItem: (key: string) => entries.get(key) ?? null,
+    setItem: (key: string, value: string) => {
+      entries.set(key, value);
+    },
+    removeItem: (key: string) => {
+      entries.delete(key);
+    },
+  };
+}
+
+/** A store that refuses everything — Safari in private browsing, and a quota that is full. */
+export function refusingStore(): PaddleCacheStore {
+  const refuse = (): never => {
+    throw new Error("the store is unavailable");
+  };
+  return { getItem: refuse, setItem: refuse, removeItem: refuse };
+}

package/src/client/wholeUnits.ts

@@ -0,0 +1,147 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { minorUnitDigits } from "../data/money";
+
+/**
+ * Removing a fraction that is entirely zero from a price Paddle already rendered.
+ *
+ * A seller whose plans are `$6`, `€12` and `KD 6` renders `$6.00`, `12,00 €` and `<U+200F>٦٫٠٠٠ د.ك.<U+200F>`, and on a
+ * pricing table the decimal is noise on every row. Two Pithy surfaces reached the same conclusion and each
+ * wrote `total.replace(/([.,])00(?=\D*$)/, "")` — the same rule, byte for byte, in two repositories. That
+ * regex is wrong in the three-decimal dinars, silent in every Arabic-Indic script, and cannot be made
+ * right, because the only thing either surface holds is the finished string. This module is the reason
+ * neither of them has to.
+ *
+ * **The decision is arithmetic, and only this package holds the number.** Paddle sends every figure twice:
+ * in minor units for comparing, and rendered for showing. $6.00 is `600`, so whether the fraction is zero
+ * is `amount % 10 ** places === 0` — no parsing, no locale, no guess. That is what `PriceLine.totals` says
+ * it is for. It also removes the whole ambiguity class: *is the trailing `000` in `$1,000` a fraction or a
+ * thousands group?* is never asked, because the fraction is known before the string is touched.
+ *
+ * **The removal never asks which character the separator is.** It is a property of the locale, not of the
+ * currency, so the ISO code cannot give it — `de-DE` renders EUR as `6,00 €` and `en-IE` renders the same
+ * currency as `€6.00`. And the browser cannot give it either: `Intl.NumberFormat(undefined, …)` answers
+ * for the **visitor's** locale while the string was rendered by **Paddle**, so matching the browser's
+ * separator is a silent no-op in exactly the case where the two differ, which is the case that matters.
+ *
+ * So the fraction is located positionally: the trailing run of `places` decimal digits, in whatever
+ * script, with a single non-digit before it that must itself follow a digit. Trailing symbols, spaces and
+ * bidi marks sit after the run and are carried through untouched. A run preceded by another digit is a
+ * thousands group and is left alone — `$1,000` and `1.000 €` both come back exactly as they arrived.
+ *
+ * **A digit is treated as its script's zero when the code point below it is not a decimal digit.** Every
+ * `Nd` block is ten contiguous points beginning at zero, so that one comparison answers it for
+ * Arabic-Indic, Devanagari and most of the rest. The usual shortcuts do not: `Number("٠")` is `NaN`, and
+ * `"٠".normalize("NFKD")` is still `"٠"`.
+ *
+ * **It is not a universal, and the first draft of this paragraph said it was — Jim, 2026-08-21.** Five of
+ * Unicode's seventy-two `Nd` blocks sit immediately after another one, so their zero has a decimal digit
+ * below it and this test answers `false` for it.
+ *
+ * **The direction of that error is the reason it is still the right test.** A missed zero means the
+ * fraction is not recognized and the figure is returned exactly as Paddle rendered it — a silent refusal
+ * to trim, never a mangled price. A false *positive* is what would remove a digit that mattered, and
+ * cannot happen here: block lengths are all ten, so the start of a digit run is always a block zero.
+ *
+ * Brute-forced rather than reasoned about: 152,592 combinations over `Intl.supportedValuesOf("currency")`
+ * against 34 locales and 15 amounts produced zero value-changing outputs, holding
+ * `digits(out) * 10**places === digits(in)` with exactly one non-digit removed.
+ *
+ * **Only an all-zero fraction ever goes.** Nothing here divides, rounds or truncates, and a real fraction
+ * comes back whole. Both halves have to agree before a character is removed — the arithmetic says the
+ * fraction is zero *and* the digits in the string are zeros — because the two figures disagreeing means
+ * somebody handed this the wrong pair, and the string is the only thing a visitor sees.
+ *
+ * **`minorUnitDigits` is shared with the server half, deliberately.** It is `../data/money`'s ISO-4217
+ * exponent table, the one the purchase projection already uses, and it imports nothing — so the browser
+ * bundle gains a set of currency codes and no graph. A second copy of that table here would be this
+ * issue's own defect, one layer down.
+ *
+ * **#465 corrected `./paddle.ts` about `Intl` and did not touch this module's reasoning — checked, 2026-08-28.**
+ * That correction is that `Intl` does know the currency exponents, so a server with only minor units may
+ * render a figure. Neither half of the argument here rested on it. This module never needed the exponent
+ * from `Intl` — it has ISO 4217, which is what a *store* denominates in, and that turned out to be the
+ * stronger choice: CLDR renders `HUF` and `COP` with no fraction at all, while Paddle bills both with two,
+ * so a `places` taken from `Intl` would answer 0 for a currency whose minor unit is the hundredth. And the
+ * separator claim above is untouched, because it is not a claim about what `Intl` knows: it is that
+ * `Intl.NumberFormat(undefined, …)` answers for the **visitor's** locale while the string in hand was
+ * rendered in **Paddle's**, and the two differing is exactly the case that matters. Trimming a string
+ * Paddle rendered stays right here; rendering one from scratch stays wrong here, and is right only where
+ * Paddle rendered nothing — `../data/renderMoney.ts`, on the server, from the negotiated locale.
+ */
+
+/** A decimal digit in any script. `Nd`, so Arabic-Indic and Devanagari count as much as ASCII. */
+const DECIMAL_DIGIT = /\p{Nd}/u;
+
+/** An amount in minor units, as Paddle writes one: an integer, optionally signed, and nothing else. */
+const MINOR_UNITS = /^-?[0-9]+$/;
+
+/** One figure, in both of the forms Paddle sends it in, and what it is denominated in. */
+export interface WholeUnitPrice {
+  /** Paddle's own rendering of the figure for this visitor. The only thing ever returned. */
+  readonly formatted: string;
+  /** The same figure in minor units — `"600"` for $6.00, `"6000"` for KD 6.000. Never rendered. */
+  readonly minorAmount: string;
+  /** The ISO-4217 code the quote is in. It decides how many digits the fraction occupies. */
+  readonly currency: string;
+}
+
+/** Whether a single character is a decimal digit. */
+function isDecimalDigit(character: string | undefined): boolean {
+  return character !== undefined && DECIMAL_DIGIT.test(character);
+}
+
+/** Whether a single character is the zero of its own script. */
+function isScriptZero(character: string | undefined): boolean {
+  if (character === undefined || !isDecimalDigit(character)) return false;
+  const code = character.codePointAt(0);
+  if (code === undefined) return false;
+  return !isDecimalDigit(String.fromCodePoint(code - 1));
+}
+
+/**
+ * The string with its trailing `places`-digit zero fraction and that fraction's separator removed.
+ *
+ * By code point rather than by UTF-16 unit: a digit outside the BMP would be two units, and a scan that
+ * counted units would cut one of them in half. The string itself is returned wherever the shape is not
+ * exactly a fraction, which is every refusal in this file — there is no partial removal.
+ */
+function withoutTrailingZeros(formatted: string, places: number): string {
+  const characters = [...formatted];
+  // Trailing symbols, spaces and bidi marks come after the fraction, so walk back to the last digit.
+  let end = characters.length;
+  while (end > 0 && !isDecimalDigit(characters[end - 1])) end -= 1;
+  const start = end - places;
+  // Two characters at least must precede the run: the separator, and the digit it separates from.
+  if (start < 2) return formatted;
+  for (let index = start; index < end; index += 1) {
+    if (!isScriptZero(characters[index])) return formatted;
+  }
+  // A digit before the run makes it a thousands group. A non-digit before *that* makes it something
+  // this cannot read as a price at all.
+  if (isDecimalDigit(characters[start - 1])) return formatted;
+  if (!isDecimalDigit(characters[start - 2])) return formatted;
+  return [...characters.slice(0, start - 1), ...characters.slice(end)].join("");
+}
+
+/**
+ * Paddle's rendering with an all-zero fraction removed, or that rendering exactly as it arrived.
+ *
+ * Opt-in everywhere it is reachable from, and never a default. Only an all-zero fraction ever goes, so an
+ * adopter selling at `$6.99` is unaffected either way — but which figures a seller advertises is a pricing
+ * decision, and this kit does not get to restyle somebody's prices on their behalf.
+ */
+export function withoutZeroFraction(price: WholeUnitPrice): string {
+  const places = minorUnitDigits(price.currency);
+  // The yen has no subunit, so there is no fraction to consider and every digit in the string is part of
+  // the figure. This states that rather than enforcing it: with no places the scan below looks at a run
+  // of no digits, whose preceding character is the last digit of the figure, and refuses on its own. A
+  // test can only see the outcome, so the comment is where the intent lives.
+  if (places === 0) return price.formatted;
+  if (!MINOR_UNITS.test(price.minorAmount)) return price.formatted;
+  const amount = Number(price.minorAmount);
+  if (!Number.isSafeInteger(amount)) return price.formatted;
+  if (amount % 10 ** places !== 0) return price.formatted;
+  return withoutTrailingZeros(price.formatted, places);
+}