@firedrill-tools/stripe 0.1.1

package/firedrill/tools/stripe/behavior.mjs

@@ -0,0 +1,148 @@
+// Synthetic Stripe account (test mode) for Firedrill. Every operation computes from `context.state`: ids come
+// from the `meta/counters` row, timestamps from the virtual clock, card outcomes from a fixed test-card
+// catalogue. Nothing here contacts Stripe or any card network; no e-mail, receipt or hosted page is served.
+import { FORM_ERROR_KEY, requestArguments } from "./lib/form.mjs";
+import { requireFits } from "./lib/size.mjs";
+import { formError, formErrorEnvelope, responseHeaders, stripeError } from "./lib/wire.mjs";
+import { invoiceItemsCreate, invoicesCreate, invoicesFinalize, invoicesList, invoicesPay, invoicesRetrieve, invoicesVoid, subscriptionsCancel, subscriptionsCreate, subscriptionsList, subscriptionsRetrieve, subscriptionsUpdate } from "./ops/billing.mjs";
+import { pricesCreate, pricesList, pricesRetrieve, productsCreate, productsList, productsRetrieve, productsUpdate } from "./ops/catalog.mjs";
+import { dashboardContext } from "./ops/dashboard.mjs";
+import { customersCreate, customersList, customersRetrieve, customersUpdate, paymentMethodsAttach, paymentMethodsDetach, paymentMethodsList } from "./ops/customers.mjs";
+import { balanceRetrieve, chargesList, chargesRetrieve, paymentIntentsCancel, paymentIntentsCapture, paymentIntentsConfirm, paymentIntentsCreate, paymentIntentsList, paymentIntentsRetrieve, refundsCreate, refundsList } from "./ops/payments.mjs";
+
+const handlers = {
+  "balance.retrieve": balanceRetrieve,
+  "dashboard.context": dashboardContext,
+  "customers.create": customersCreate,
+  "customers.retrieve": customersRetrieve,
+  "customers.update": customersUpdate,
+  "customers.list": customersList,
+  "payment_methods.list": paymentMethodsList,
+  "payment_methods.attach": paymentMethodsAttach,
+  "payment_methods.detach": paymentMethodsDetach,
+  "payment_intents.create": paymentIntentsCreate,
+  "payment_intents.retrieve": paymentIntentsRetrieve,
+  "payment_intents.list": paymentIntentsList,
+  "payment_intents.confirm": paymentIntentsConfirm,
+  "payment_intents.capture": paymentIntentsCapture,
+  "payment_intents.cancel": paymentIntentsCancel,
+  "charges.retrieve": chargesRetrieve,
+  "charges.list": chargesList,
+  "refunds.create": refundsCreate,
+  "refunds.list": refundsList,
+  "products.create": productsCreate,
+  "products.retrieve": productsRetrieve,
+  "products.update": productsUpdate,
+  "products.list": productsList,
+  "prices.create": pricesCreate,
+  "prices.retrieve": pricesRetrieve,
+  "prices.list": pricesList,
+  "invoice_items.create": invoiceItemsCreate,
+  "invoices.create": invoicesCreate,
+  "invoices.retrieve": invoicesRetrieve,
+  "invoices.list": invoicesList,
+  "invoices.finalize": invoicesFinalize,
+  "invoices.pay": invoicesPay,
+  "invoices.void": invoicesVoid,
+  "subscriptions.create": subscriptionsCreate,
+  "subscriptions.retrieve": subscriptionsRetrieve,
+  "subscriptions.list": subscriptionsList,
+  "subscriptions.update": subscriptionsUpdate,
+  "subscriptions.cancel": subscriptionsCancel,
+};
+
+/**
+ * Every Stripe operation's response must fit one HTTP response (the framework refuses bodies over 1 MiB with an
+ * opaque 500 after committing). Lists already fill pages by bytes; this bound covers single objects and their
+ * expansions, answering `invalid_request_error` and discarding the operation's writes. `dashboard.context` is a small
+ * fixed-shape app read with no declared errors.
+ */
+function fitResponse(context, value) {
+  // List pages are already filled by bytes in `paginate` (up to PAGE_BYTE_BUDGET); every other value is one object.
+  return value !== null && typeof value === "object" && value.object === "list" ? value : requireFits(context, value, "This object");
+}
+
+const operations = Object.fromEntries(
+  Object.entries(handlers).map(([id, handler]) => [id, id === "dashboard.context" ? handler : (input, context) => fitResponse(context, handler(input, context))]),
+);
+
+// ---------------------------------------------------------------------------------------------
+// HTTP codecs: Stripe REST v1 (form-encoded requests, JSON responses, Stripe error envelope)
+// ---------------------------------------------------------------------------------------------
+
+function idempotencyKey(request) {
+  const values = request.headers["idempotency-key"];
+  const key = values === undefined || values.length === 0 ? undefined : values[values.length - 1];
+  return key === undefined || key.length === 0 ? {} : { idempotencyKey: key };
+}
+
+/**
+ * Path parameters + bracket-encoded query/form arguments; `Idempotency-Key` becomes the framework key.
+ * A request the form decoder cannot map (reserved segment, nesting or array index over the cap) must still answer in
+ * Stripe's envelope, but a throwing `decode` becomes the framework's `HTTP_REQUEST_MAPPING_FAILED`. The decoder's error
+ * therefore travels as the only argument under `FORM_ERROR_KEY`: every route's input schema is closed
+ * (`additionalProperties: false`), so the framework rejects the call before any handler runs, and `encode` renders the
+ * carried error as Stripe's 400 `invalid_request_error`. No idempotency key is forwarded for such a request.
+ */
+function decode(request) {
+  const decoded = requestArguments(request);
+  if (decoded.error !== undefined) return { arguments: { [FORM_ERROR_KEY]: decoded.error } };
+  return { arguments: decoded.value, ...idempotencyKey(request) };
+}
+
+function route(options = {}) {
+  return {
+    decode,
+    encode({ invocation, outcome }) {
+      const headers = responseHeaders(invocation);
+      const carried = outcome.status === "invalid" ? formError(invocation.arguments, FORM_ERROR_KEY) : undefined;
+      if (carried !== undefined) return { headers, body: { kind: "json", value: formErrorEnvelope(carried, invocation.correlationId) } };
+      if (outcome.status !== "ok") return { headers, body: { kind: "json", value: stripeError(outcome, invocation.correlationId) } };
+      const value = options.select === undefined ? outcome.value : options.select(outcome.value, invocation);
+      return { headers, body: { kind: "json", value } };
+    },
+  };
+}
+
+const http = {
+  "retrieve-balance": route(),
+  "create-customer": route(),
+  "retrieve-customer": route(),
+  "update-customer": route(),
+  "list-customers": route(),
+  "list-payment-methods": route(),
+  "list-customer-payment-methods": route({ select: (value, invocation) => ({ ...value, url: `/v1/customers/${invocation.arguments.customer}/payment_methods` }) }),
+  "attach-payment-method": route(),
+  "detach-payment-method": route(),
+  "create-payment-intent": route(),
+  "retrieve-payment-intent": route(),
+  "list-payment-intents": route(),
+  "confirm-payment-intent": route(),
+  "capture-payment-intent": route(),
+  "cancel-payment-intent": route(),
+  "retrieve-charge": route(),
+  "list-charges": route(),
+  "create-refund": route(),
+  "list-refunds": route(),
+  "create-product": route(),
+  "retrieve-product": route(),
+  "update-product": route(),
+  "list-products": route(),
+  "create-price": route(),
+  "retrieve-price": route(),
+  "list-prices": route(),
+  "create-invoice-item": route(),
+  "create-invoice": route(),
+  "retrieve-invoice": route(),
+  "list-invoices": route(),
+  "finalize-invoice": route(),
+  "pay-invoice": route(),
+  "void-invoice": route(),
+  "create-subscription": route(),
+  "retrieve-subscription": route(),
+  "list-subscriptions": route(),
+  "update-subscription": route(),
+  "cancel-subscription": route(),
+};
+
+export default { operations, http };

package/firedrill/tools/stripe/lib/cards.mjs

@@ -0,0 +1,53 @@
+// The synthetic test-card catalogue: Stripe's published test payment method ids and the outcome each one
+// produces when it is confirmed. Constants only; materialised cards live in the `payment_methods` namespace.
+
+const CARDS = Object.freeze({
+  pm_card_visa: { brand: "visa", last4: "4242", funding: "credit", country: "US", outcome: "succeed", fingerprint: "Xt5EWLLDS7FJjR1c" },
+  pm_card_visa_debit: { brand: "visa", last4: "5556", funding: "debit", country: "US", outcome: "succeed", fingerprint: "k9tPmQ2vR4sX7bLn" },
+  pm_card_mastercard: { brand: "mastercard", last4: "4444", funding: "credit", country: "US", outcome: "succeed", fingerprint: "Q7mVdR2sK9pLxT4w" },
+  pm_card_amex: { brand: "amex", last4: "8431", funding: "credit", country: "US", outcome: "succeed", fingerprint: "Bv3NcY6hJ8qWzP1r" },
+  pm_card_chargeDeclined: { brand: "visa", last4: "0002", funding: "credit", country: "US", outcome: "decline_generic", fingerprint: "Dc0LnX4tG7vKrM2s" },
+  pm_card_chargeDeclinedInsufficientFunds: { brand: "visa", last4: "9995", funding: "credit", country: "US", outcome: "decline_insufficient_funds", fingerprint: "If9Pq2Ws5RtY7uB3" },
+  pm_card_authenticationRequired: { brand: "visa", last4: "3155", funding: "credit", country: "US", outcome: "requires_action", fingerprint: "Au3Rq8Zt1Vx6NmC5" },
+});
+
+export const TEST_CARD_IDS = Object.freeze(Object.keys(CARDS));
+
+export function testCard(id) {
+  return typeof id === "string" && Object.hasOwn(CARDS, id) ? CARDS[id] : undefined;
+}
+
+export function isTestCardId(id) {
+  return testCard(id) !== undefined;
+}
+
+/** The `card` block of a PaymentMethod built from a catalogue entry. */
+export function cardDetails(card) {
+  return {
+    brand: card.brand,
+    checks: { address_line1_check: null, address_postal_code_check: null, cvc_check: "pass" },
+    country: card.country,
+    display_brand: card.brand,
+    exp_month: 12,
+    exp_year: 2034,
+    fingerprint: card.fingerprint,
+    funding: card.funding,
+    generated_from: null,
+    last4: card.last4,
+    networks: { available: [card.brand], preferred: null },
+    regulated_status: "unregulated",
+    three_d_secure_usage: { supported: true },
+    wallet: null,
+  };
+}
+
+/** Decline details for the two synthetic decline outcomes; undefined for outcomes that do not decline. */
+export function declineFor(outcome) {
+  if (outcome === "decline_generic") {
+    return { decline_code: "generic_decline", message: "Your card was declined." };
+  }
+  if (outcome === "decline_insufficient_funds") {
+    return { decline_code: "insufficient_funds", message: "Your card has insufficient funds." };
+  }
+  return undefined;
+}

package/firedrill/tools/stripe/lib/form.mjs

@@ -0,0 +1,204 @@
+// Stripe's form encoding: `metadata[order_id]=42`, `items[0][price]=price_x`, `expand[]=customer`,
+// `created[gte]=1700000000`. The framework hands codecs the raw `URLSearchParams` pairs; this module un-flattens
+// them into nested objects/arrays and coerces the integer/boolean parameters this Tool knows. Pure functions only.
+//
+// Tool modules run in the serve process's own JavaScript realm and codecs run inline in its request handler, so the
+// decoder is defensive by construction:
+// - maps are built from `Object.create(null)` and copied out with `Object.fromEntries` (own data properties only), and
+//   the segments `__proto__`, `constructor` and `prototype` are rejected, so no caller key can reach a prototype;
+// - nesting depth and array indices are capped, and the walk is iterative, so no request causes deep recursion, a
+//   sparse array of length 2^32-1, or other work that is not proportional to the request's own size;
+// - it never throws: a request that cannot be mapped yields `{ error: { code, message, param } }`, which the codec
+//   turns into Stripe's 400 `invalid_request_error` envelope (see `behavior.mjs`).
+
+/** Bracket segments allowed after the parameter name (`a[b][c]` has two). This Tool's deepest parameter has four. */
+export const MAX_NESTING_DEPTH = 20;
+/** Largest accepted array index; `expand[]`/`items[]` hold at most `MAX_ARRAY_INDEX + 1` entries. */
+export const MAX_ARRAY_INDEX = 999;
+/** Argument key the codec uses to carry a decoding error past schema validation to `encode`. */
+export const FORM_ERROR_KEY = "firedrill:form_error";
+
+const RESERVED_SEGMENTS = new Set(["__proto__", "constructor", "prototype"]);
+const DISPLAY_LIMIT = 120;
+
+const INTEGER_KEYS = new Set([
+  "amount",
+  "amount_to_capture",
+  "limit",
+  "quantity",
+  "unit_amount",
+  "days_until_due",
+  "trial_period_days",
+  "interval_count",
+  "cancel_at",
+  "billing_cycle_anchor",
+  "start",
+  "end",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+]);
+const INTEGER_OR_OBJECT_KEYS = new Set(["created", "due_date", "current_period_start", "current_period_end"]);
+const INTEGER_OR_STRING_KEYS = new Set(["trial_end"]);
+const BOOLEAN_KEYS = new Set(["confirm", "active", "cancel_at_period_end", "auto_advance", "paid_out_of_band", "off_session", "deleted", "enabled"]);
+const OPAQUE_PARENTS = new Set(["metadata"]);
+
+class FormError {
+  constructor(code, message, param) {
+    this.error = { code, message, param };
+  }
+}
+
+function display(key) {
+  return key.length > DISPLAY_LIMIT ? `${key.slice(0, DISPLAY_LIMIT)}...` : key;
+}
+
+/**
+ * `items[0][price]` → `["items", "0", "price"]`. A key that is not of the form `name[seg]...[seg]` stays one opaque
+ * parameter name (the canonical schema rejects it as unknown). Linear scan; stops as soon as the depth cap is exceeded.
+ */
+function segments(key) {
+  const open = key.indexOf("[");
+  if (open <= 0 || key.indexOf("]") < open) return [key];
+  const parts = [key.slice(0, open)];
+  let position = open;
+  while (position < key.length) {
+    if (key[position] !== "[") return [key];
+    const close = key.indexOf("]", position + 1);
+    if (close === -1) return [key];
+    const segment = key.slice(position + 1, close);
+    if (segment.includes("[")) return [key];
+    if (parts.length > MAX_NESTING_DEPTH) {
+      throw new FormError("parameter_invalid", `Invalid parameter: ${display(key)} is nested more than ${MAX_NESTING_DEPTH} levels deep.`, display(key));
+    }
+    parts.push(segment);
+    position = close + 1;
+  }
+  return parts;
+}
+
+function coerce(parent, key, value) {
+  if (OPAQUE_PARENTS.has(parent)) return value;
+  if (INTEGER_KEYS.has(key) || INTEGER_OR_OBJECT_KEYS.has(key)) {
+    if (/^-?[0-9]{1,15}$/.test(value)) return Number(value);
+    if (/^-?[0-9]{1,15}\.[0-9]{1,15}$/.test(value)) return Number(value);
+    return value;
+  }
+  if (INTEGER_OR_STRING_KEYS.has(key)) return /^[0-9]{1,15}$/.test(value) ? Number(value) : value;
+  if (BOOLEAN_KEYS.has(key)) {
+    if (value === "true") return true;
+    if (value === "false") return false;
+    return value;
+  }
+  return value;
+}
+
+function isMap(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function arrayIndex(key, name, array, segment) {
+  // Leading zeros are not significant (`items[0001]` is index 1, as Stripe reads it); a digit run too long to be a
+  // safe integer is simply over the cap and gets the same "0 to MAX_ARRAY_INDEX" message.
+  const digits = segment === "" ? null : segment.replace(/^0+(?=[0-9])/, "");
+  const index = digits === null ? array.length : digits.length <= 15 ? Number(digits) : Number.POSITIVE_INFINITY;
+  if (index > MAX_ARRAY_INDEX) {
+    throw new FormError(
+      "parameter_invalid",
+      `Invalid array: ${display(key)}. The ${name} parameter accepts at most ${MAX_ARRAY_INDEX + 1} entries, indexed from 0 to ${MAX_ARRAY_INDEX}.`,
+      display(key),
+    );
+  }
+  return index;
+}
+
+/** Iterative write of one `parts → value` pair into a null-prototype tree. */
+function assign(root, key, parts, value) {
+  let target = root;
+  let parentKey = "";
+  let position = 0;
+  while (position < parts.length) {
+    const head = parts[position];
+    if (position === parts.length - 1) {
+      target[head] = coerce(parentKey, head, value);
+      return;
+    }
+    const next = parts[position + 1];
+    if (next === "" || /^[0-9]+$/.test(next)) {
+      if (!Array.isArray(target[head])) target[head] = [];
+      const array = target[head];
+      const index = arrayIndex(key, head, array, next);
+      if (position + 1 === parts.length - 1) {
+        array[index] = coerce(head, head, value);
+        return;
+      }
+      if (next === "" || !isMap(array[index])) array[index] = Object.create(null);
+      target = array[index];
+      parentKey = head;
+      position += 2;
+      continue;
+    }
+    if (!isMap(target[head])) target[head] = Object.create(null);
+    target = target[head];
+    parentKey = head;
+    position += 1;
+  }
+}
+
+/** Null-prototype tree → plain JSON value. Depth is bounded by `MAX_NESTING_DEPTH`, array length by the index cap. */
+function compact(value) {
+  if (Array.isArray(value)) {
+    // Walk the entries the request actually set (`Object.keys` of an array yields its present indices in ascending
+    // order), so a sparse `x[999]=1` costs one step rather than a thousand: the cost stays proportional to the
+    // request's own size however many sparse arrays it builds.
+    const out = [];
+    for (const index of Object.keys(value)) if (value[index] !== undefined) out.push(compact(value[index]));
+    return out;
+  }
+  if (isMap(value)) return Object.fromEntries(Object.keys(value).map((key) => [key, compact(value[key])]));
+  return value;
+}
+
+function unflattenOrThrow(record) {
+  const target = Object.create(null);
+  for (const key of Object.keys(record)) {
+    const values = record[key];
+    const parts = segments(key);
+    const reserved = parts.find((part) => RESERVED_SEGMENTS.has(part));
+    if (reserved !== undefined || parts[0] === FORM_ERROR_KEY) {
+      throw new FormError("parameter_unknown", `Received unknown parameter: ${display(key)}`, display(key));
+    }
+    for (const value of values) assign(target, key, parts, typeof value === "string" ? value : String(value));
+  }
+  return compact(target);
+}
+
+function guarded(run) {
+  try {
+    return { value: run() };
+  } catch (error) {
+    if (error instanceof FormError) return { error: error.error };
+    return { error: { code: "parameter_invalid", message: "Invalid request: the form parameters could not be decoded.", param: undefined } };
+  }
+}
+
+/**
+ * `Record<string, string[]>` (form body or query string) → `{ value }` with nested arguments, or `{ error }` when the
+ * request cannot be mapped. Repeated plain keys keep the last value (Stripe's behaviour for duplicated scalar
+ * parameters); `expand[]`, `ids[]`, `items[0][price]` build arrays. Integer-looking values of known integer parameters
+ * become numbers, `true`/`false` of known boolean parameters become booleans; anything else stays a string for the
+ * canonical schema to judge.
+ */
+export function unflatten(record) {
+  return guarded(() => unflattenOrThrow(record));
+}
+
+/** Path parameters plus query and form arguments merged into one canonical argument object, or `{ error }`. */
+export function requestArguments(request) {
+  return guarded(() => {
+    const query = unflattenOrThrow(request.query);
+    const body = request.body.kind === "form" ? unflattenOrThrow(request.body.value) : {};
+    return { ...query, ...body, ...request.path };
+  });
+}

package/firedrill/tools/stripe/lib/ids.mjs

@@ -0,0 +1,85 @@
+// Deterministic Stripe-style identifiers. Ids are `<prefix>_<6 base-36 sequence chars><8 hash chars>`: the
+// zero-padded, upper-case base-36 object sequence keeps a namespace scan in creation order, the 8-character
+// FNV-1a-derived suffix is a checksum only and is never parsed. Nothing here keeps state or reads a clock.
+
+const B36 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+const B62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+
+/** 32-bit FNV-1a of a string, as an unsigned integer. */
+export function fnv1a(text, seed = 0x811c9dc5) {
+  let hash = seed >>> 0;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash >>> 0;
+}
+
+function encode(number, alphabet, width) {
+  let out = "";
+  let value = number;
+  do {
+    out = alphabet[value % alphabet.length] + out;
+    value = Math.floor(value / alphabet.length);
+  } while (value > 0);
+  return out.padStart(width, alphabet[0]).slice(-width);
+}
+
+/** A deterministic base-62 token of `length` characters derived from `seed`. */
+export function token(seed, length) {
+  let out = "";
+  let round = 0;
+  while (out.length < length) {
+    out += encode(fnv1a(`${seed}#${round}`), B62, 6);
+    round += 1;
+  }
+  return out.slice(0, length);
+}
+
+/** Render the id of the `sequence`-th object with a Stripe prefix (`cus`, `pi`, `ch`, ...). */
+export function renderId(prefix, sequence) {
+  return `${prefix}_${encode(sequence, B36, 6)}${token(`${prefix}_${sequence}`, 8)}`;
+}
+
+/** Sequence number encoded in an id rendered by `renderId`, or undefined for foreign ids. */
+export function sequenceOf(id) {
+  const match = /^[a-z]+_([0-9A-Z]{6})[0-9A-Za-z]{8}$/.exec(id);
+  if (match === null) return undefined;
+  let value = 0;
+  for (const character of match[1]) value = value * 36 + B36.indexOf(character);
+  return value;
+}
+
+const COUNTER_START = 1000;
+
+/** Allocate the next object sequence from the `meta/counters` row (created lazily at 1000). */
+export function nextSequence(context) {
+  const stored = context.state.get("meta", "counters");
+  const next = stored === null || typeof stored.next !== "number" ? COUNTER_START : stored.next;
+  context.state.put("meta", "counters", { next: next + 1 });
+  return next;
+}
+
+export function nextId(context, prefix) {
+  return renderId(prefix, nextSequence(context));
+}
+
+/** Customer invoice prefix: eight upper-case alphanumerics derived from the customer sequence. */
+export function invoicePrefix(sequence) {
+  return token(`invoice_prefix_${sequence}`, 8).toUpperCase();
+}
+
+/** A PaymentIntent client secret: never usable anywhere, deterministic per intent. */
+export function clientSecret(intentId) {
+  return `${intentId}_secret_${token(`secret_${intentId}`, 24)}`;
+}
+
+/** Acquirer reference number shown on refunds' destination details. */
+export function acquirerReference(refundId) {
+  return token(`arn_${refundId}`, 24).replace(/[a-z]/g, (character) => character.toUpperCase());
+}
+
+/** Deterministic 0–99 risk score for a charge outcome. */
+export function riskScore(chargeId) {
+  return fnv1a(`risk_${chargeId}`) % 100;
+}

package/firedrill/tools/stripe/lib/money.mjs

@@ -0,0 +1,35 @@
+// Amounts are integers in minor units; currencies are a fixed lower-case ISO-4217 list. Pure functions only.
+
+export const CURRENCIES = Object.freeze(["usd", "eur", "gbp", "cad", "aud", "chf", "sek", "nok", "dkk", "jpy", "nzd", "sgd"]);
+export const MIN_CHARGE_AMOUNT = 50;
+export const MAX_CHARGE_AMOUNT = 99_999_999;
+
+const SYMBOLS = { usd: "$", eur: "€", gbp: "£", cad: "CA$", aud: "A$", chf: "CHF ", sek: "kr ", nok: "kr ", dkk: "kr ", jpy: "¥", nzd: "NZ$", sgd: "S$" };
+
+export function isCurrency(value) {
+  return typeof value === "string" && CURRENCIES.includes(value.toLowerCase());
+}
+
+export function normalizeCurrency(value) {
+  return value.toLowerCase();
+}
+
+export function isInteger(value) {
+  return typeof value === "number" && Number.isInteger(value);
+}
+
+/** `$12.50` / `€3.00` / `¥500` formatting used in Stripe's error messages. */
+export function formatAmount(amount, currency) {
+  const symbol = SYMBOLS[currency] ?? `${currency.toUpperCase()} `;
+  if (currency === "jpy") return `${symbol}${amount}`;
+  const sign = amount < 0 ? "-" : "";
+  const absolute = Math.abs(amount);
+  const major = Math.floor(absolute / 100);
+  const minor = String(absolute % 100).padStart(2, "0");
+  return `${sign}${symbol}${major}.${minor}`;
+}
+
+/** Legacy `unit_amount_decimal` / `amount_decimal` strings (Stripe renders integers as decimal strings). */
+export function decimalString(amount) {
+  return String(amount);
+}