@peable.to/shared-types 0.2.0 → 0.3.1-oxy-one.0

package/dist/cjs/billing.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BILLING_SUBSCRIPTION_STATUSES = void 0;
+/** Recurring billing transport. Store/plan references belong to the authenticated app;
+ * they do not identify an Oxy payer or convey entitlements. */
+exports.BILLING_SUBSCRIPTION_STATUSES = ['incomplete', 'incomplete_expired', 'trialing', 'active', 'past_due', 'canceled', 'unpaid', 'paused'];

package/dist/cjs/dispute.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * A dispute — the card network holding a settled payment's money while a
+ * cardholder contests it.
+ *
+ * Published because `payment_intent.disputed` and `payment_intent.dispute_closed`
+ * carry it as their `data.object`. It was route-local at first, with the webhook
+ * carrying the PaymentIntent and the detail reachable only through
+ * `GET /v1/payment_intents/:id/disputes`. That was inconsistent with the reason
+ * those two events exist: `disputed` is a DEADLINE, and a merchant who has to
+ * make a second call to learn when evidence is due is a merchant who can miss it
+ * while their integration is working exactly as documented.
+ *
+ * It is also what the provider does. Stripe's `charge.dispute.created` carries
+ * the dispute, not the charge — the parity was half-applied.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/index.js

@@ -1,15 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MERCHANT_ENVIRONMENTS = exports.verifyWebhook = exports.signWebhook = exports.PAYMENT_INTENT_STATUSES = exports.isValidStatusTransition = exports.isBaseUnitString = exports.UNITS_PER_COIN = void 0;
+exports.BILLING_SUBSCRIPTION_STATUSES = exports.SOCIAL_SOURCE_REF_MAX_LENGTH = exports.SOCIAL_SOURCE_APP_MAX_LENGTH = exports.MERCHANT_ENVIRONMENTS = exports.verifyWebhook = exports.signWebhook = exports.CARD_ONLY_STATUSES = exports.CHAIN_ONLY_STATUSES = exports.PAYMENT_INTENT_RAILS = exports.PAYMENT_INTENT_STATUSES = exports.POST_SETTLEMENT_STATUSES = exports.reachesSettlementFromPayer = exports.canStillBePaid = exports.isValidStatusTransition = exports.isCurrencyCode = exports.decimalsFor = exports.CURRENCY_DECIMALS = exports.CURRENCY_CODES = exports.isBaseUnitString = exports.UNITS_PER_COIN = void 0;
 // @peable.to/shared-types — public API for the Peable Gateway contract.
 var money_1 = require("./money");
 Object.defineProperty(exports, "UNITS_PER_COIN", { enumerable: true, get: function () { return money_1.UNITS_PER_COIN; } });
 Object.defineProperty(exports, "isBaseUnitString", { enumerable: true, get: function () { return money_1.isBaseUnitString; } });
+Object.defineProperty(exports, "CURRENCY_CODES", { enumerable: true, get: function () { return money_1.CURRENCY_CODES; } });
+Object.defineProperty(exports, "CURRENCY_DECIMALS", { enumerable: true, get: function () { return money_1.CURRENCY_DECIMALS; } });
+Object.defineProperty(exports, "decimalsFor", { enumerable: true, get: function () { return money_1.decimalsFor; } });
+Object.defineProperty(exports, "isCurrencyCode", { enumerable: true, get: function () { return money_1.isCurrencyCode; } });
 var paymentIntent_1 = require("./paymentIntent");
 Object.defineProperty(exports, "isValidStatusTransition", { enumerable: true, get: function () { return paymentIntent_1.isValidStatusTransition; } });
+Object.defineProperty(exports, "canStillBePaid", { enumerable: true, get: function () { return paymentIntent_1.canStillBePaid; } });
+Object.defineProperty(exports, "reachesSettlementFromPayer", { enumerable: true, get: function () { return paymentIntent_1.reachesSettlementFromPayer; } });
+Object.defineProperty(exports, "POST_SETTLEMENT_STATUSES", { enumerable: true, get: function () { return paymentIntent_1.POST_SETTLEMENT_STATUSES; } });
 Object.defineProperty(exports, "PAYMENT_INTENT_STATUSES", { enumerable: true, get: function () { return paymentIntent_1.PAYMENT_INTENT_STATUSES; } });
+Object.defineProperty(exports, "PAYMENT_INTENT_RAILS", { enumerable: true, get: function () { return paymentIntent_1.PAYMENT_INTENT_RAILS; } });
+Object.defineProperty(exports, "CHAIN_ONLY_STATUSES", { enumerable: true, get: function () { return paymentIntent_1.CHAIN_ONLY_STATUSES; } });
+Object.defineProperty(exports, "CARD_ONLY_STATUSES", { enumerable: true, get: function () { return paymentIntent_1.CARD_ONLY_STATUSES; } });
 var webhookSigner_1 = require("./webhookSigner");
 Object.defineProperty(exports, "signWebhook", { enumerable: true, get: function () { return webhookSigner_1.signWebhook; } });
 Object.defineProperty(exports, "verifyWebhook", { enumerable: true, get: function () { return webhookSigner_1.verifyWebhook; } });
 var merchant_1 = require("./merchant");
 Object.defineProperty(exports, "MERCHANT_ENVIRONMENTS", { enumerable: true, get: function () { return merchant_1.MERCHANT_ENVIRONMENTS; } });
+var social_1 = require("./social");
+Object.defineProperty(exports, "SOCIAL_SOURCE_APP_MAX_LENGTH", { enumerable: true, get: function () { return social_1.SOCIAL_SOURCE_APP_MAX_LENGTH; } });
+Object.defineProperty(exports, "SOCIAL_SOURCE_REF_MAX_LENGTH", { enumerable: true, get: function () { return social_1.SOCIAL_SOURCE_REF_MAX_LENGTH; } });
+var billing_1 = require("./billing");
+Object.defineProperty(exports, "BILLING_SUBSCRIPTION_STATUSES", { enumerable: true, get: function () { return billing_1.BILLING_SUBSCRIPTION_STATUSES; } });

package/dist/cjs/money.js

@@ -1,20 +1,60 @@
 "use strict";
-// Amount helpers over FairCoin base units (m⊜). One coin is UNITS_PER_COIN
-// base units. Amounts move through the system as bigint conceptually; the
-// PaymentIntent DTO stores them as a base-unit integer string so no float ever
-// touches a monetary value.
+// Amount helpers. Every monetary value moves through this gateway as a
+// canonical integer string in the currency's SMALLEST unit — m⊜ for FairCoin,
+// cents for a fiat currency — so no float ever touches one.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UNITS_PER_COIN = void 0;
+exports.UNITS_PER_COIN = exports.CURRENCY_DECIMALS = exports.CURRENCY_CODES = void 0;
+exports.isCurrencyCode = isCurrencyCode;
+exports.decimalsFor = decimalsFor;
 exports.isBaseUnitString = isBaseUnitString;
+/**
+ * The currencies this gateway can denominate a payment in.
+ *
+ * A closed set, and the database mirrors it as a CHECK
+ * (`db/schema/valueSets.ts`). ADR 0001 D4: the scale of an amount is a property
+ * of its currency and is NOT implied by the field's type, which is why
+ * {@link CURRENCY_DECIMALS} exists and why {@link UNITS_PER_COIN} must never be
+ * used to interpret a fiat amount.
+ */
+exports.CURRENCY_CODES = ['FAIR', 'EUR', 'USD'];
+/** Whether an arbitrary string is a currency this gateway knows. */
+function isCurrencyCode(value) {
+    return exports.CURRENCY_CODES.includes(value);
+}
+/**
+ * How many decimal places each currency's smallest unit represents — i.e. an
+ * amount of `1` means `10^-decimals` of one whole unit.
+ *
+ * FairCoin's 8 is a consensus constant and is pinned against
+ * {@link UNITS_PER_COIN} by this package's own tests, so the two spellings of
+ * one fact cannot drift.
+ */
+exports.CURRENCY_DECIMALS = Object.freeze({
+    FAIR: 8,
+    EUR: 2,
+    USD: 2,
+});
+/** The decimal places of `currency`'s smallest unit. */
+function decimalsFor(currency) {
+    return exports.CURRENCY_DECIMALS[currency];
+}
 // Frozen FairCoin consensus constant (smallest units per FAIR). Mirrors
 // @fairco.in/core's branding.ts; inlined here (rather than imported) to keep
 // @peable.to/shared-types zero-runtime-dep for a clean CJS+ESM publish — must
 // stay a bigint, never converted to number.
+//
+// FAIRCOIN ONLY. A fiat amount has its own scale (`CURRENCY_DECIMALS`), and
+// dividing a EUR amount by this constant is off by six orders of magnitude with
+// nothing failing.
 exports.UNITS_PER_COIN = 100000000n;
 /**
- * True only for a canonical non-negative integer string in base units:
- * one or more decimal digits, no sign, no decimal point, no leading zeros
- * (except the literal "0"). Floats and negatives are rejected.
+ * True only for a canonical non-negative integer string in the currency's
+ * smallest unit: one or more decimal digits, no sign, no decimal point, no
+ * leading zeros (except the literal "0"). Floats and negatives are rejected.
+ *
+ * Currency-agnostic on purpose — the pattern is about the SPELLING of an
+ * amount, not its scale, and the same one is restated as a CHECK in the
+ * database (`BASE_UNIT_STRING_PATTERN`), byte-identical.
  */
 function isBaseUnitString(s) {
     return /^(0|[1-9][0-9]*)$/.test(s);

package/dist/cjs/paymentIntent.js

@@ -1,26 +1,117 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PAYMENT_INTENT_STATUSES = void 0;
+exports.POST_SETTLEMENT_STATUSES = exports.PAYMENT_INTENT_STATUSES = exports.CARD_ONLY_STATUSES = exports.CHAIN_ONLY_STATUSES = exports.PAYMENT_INTENT_RAILS = void 0;
 exports.isValidStatusTransition = isValidStatusTransition;
+exports.canStillBePaid = canStillBePaid;
+exports.reachesSettlementFromPayer = reachesSettlementFromPayer;
+/** {@link PaymentIntentRail} as the tuple the database CHECK reads. */
+exports.PAYMENT_INTENT_RAILS = ['faircoin', 'card'];
+/**
+ * Which statuses belong to which rail (ADR 0001 D5).
+ *
+ * The four chain states describe a transaction on a blockchain and the four
+ * card states describe an authorization at a card acquirer; neither set is
+ * expressible on the other rail. Mapping a card authorization onto `broadcast`
+ * would be cheaper and would be a lie — nothing was broadcast, there is no
+ * transaction, and `payment_intents_broadcast_requires_txid_check` would then
+ * be demanding a txid from a payment that can never have one.
+ *
+ * `db/schema/payments.ts` renders these two sets into CHECK constraints, so the
+ * restriction holds against a write that skipped the application.
+ */
+exports.CHAIN_ONLY_STATUSES = [
+    'awaiting_approval',
+    'approved',
+    'broadcast',
+    'confirming',
+];
+exports.CARD_ONLY_STATUSES = [
+    'requires_action',
+    'processing',
+    'refunded',
+    'partially_refunded',
+];
 /**
  * Legal forward transitions of the PaymentIntent lifecycle. Terminal states
- * (settled/expired/failed/rejected) allow no further transition here — the one
+ * (refunded/expired/failed/rejected) allow no further transition here — the one
  * documented exception, a reorg dropping `settled` back to `confirming`, is
  * modelled by the backend state machine, not this happy-path table.
+ *
+ * ONE table for both rails, deliberately. It answers "is this a legal lifecycle
+ * edge at all"; WHICH rail may reach a given status is the separate, structural
+ * question the two sets above answer, in the database. A rail-parameterised
+ * table would put the same restriction in two places and let them disagree.
+ *
+ * Self-transitions are absent because `applyEvent` short-circuits on
+ * `current === target` before consulting this table — that is the idempotent
+ * re-poll of the settlement watcher, and a second partial refund, which change
+ * an amount without changing a status.
  */
 const ALLOWED = {
-    // `created` supports two paths: the rich wallet flow (→ awaiting_approval →
-    // approved → broadcast) AND the minimal path where the payer pays out-of-band
-    // and reports the txid directly (→ broadcast), or the merchant cancels an
-    // unpaid intent (→ rejected). Both are legal forward transitions.
-    created: ['awaiting_approval', 'broadcast', 'rejected', 'expired'],
+    // `created` supports three paths: the rich wallet flow (→ awaiting_approval →
+    // approved → broadcast), the minimal path where the payer pays out-of-band
+    // and reports the txid directly (→ broadcast), and the card path (→
+    // requires_action for an SCA challenge, → processing, or straight to settled
+    // for a charge that confirms in one call). `failed` is reachable from here
+    // because a card can be declined on first confirmation, having never been
+    // anything else; no FairCoin path uses that edge, since `underpaid` is only
+    // emitted for an intent that already carries a txid.
+    created: [
+        'awaiting_approval',
+        'broadcast',
+        'requires_action',
+        'processing',
+        'settled',
+        'failed',
+        'rejected',
+        'expired',
+    ],
     awaiting_approval: ['approved', 'rejected', 'expired'],
     approved: ['broadcast', 'failed'],
     broadcast: ['confirming', 'failed'],
     confirming: ['settled', 'failed'],
-    settled: [],
+    requires_action: ['processing', 'settled', 'failed', 'expired', 'rejected'],
+    processing: ['settled', 'failed'],
+    /**
+     * A failed ATTEMPT is not a failed payment, on the card rail.
+     *
+     * `payment_intent.payment_failed` means one authorization attempt was
+     * declined; Stripe returns the PaymentIntent to `requires_payment_method` and
+     * the payer can confirm it again with another card. With `failed` terminal,
+     * the later `payment_intent.succeeded` was an ILLEGAL transition — so the
+     * drain recorded a processing failure and retried it forever, the payment
+     * stayed `failed`, and a merchant who had been paid was told their payment
+     * had been declined.
+     *
+     * On the chain rail `failed` means `underpaid`, which IS terminal — coins
+     * arrived and were not enough. Nothing here opens that door: `underpaid` is
+     * emitted only by the settlement watcher, and `LEGAL_SOURCES` in
+     * `services/intentState.ts` keeps every `card_*` event to card statuses and
+     * the chain's `confirmed` to `confirming`. This table answers "is the edge
+     * legal at all"; which rail may walk it is the separate question those two
+     * guards answer.
+     */
+    failed: ['requires_action', 'processing', 'settled'],
+    // Money coming back requires money to have arrived, so both refund states are
+    // reachable only from `settled`.
+    settled: ['refunded', 'partially_refunded'],
+    /**
+     * ...and money coming back can be UNDONE, which is why these edges run both
+     * ways.
+     *
+     * A refund is not final when the provider accepts it: a bank can reject one
+     * days later, and the provider then says so (`refund.failed`). Without a path
+     * back, a payment whose only refund failed would claim `refunded` forever —
+     * the merchant's books saying money went back that is still with them, and no
+     * transition anywhere able to correct it.
+     *
+     * The target is always recomputed from the SUM of succeeded refunds
+     * (`applyRefundToIntent`), never stepped, so these edges describe where that
+     * sum can legally land rather than a sequence anyone walks.
+     */
+    partially_refunded: ['refunded', 'settled'],
+    refunded: ['partially_refunded', 'settled'],
     expired: [],
-    failed: [],
     rejected: [],
 };
 function isValidStatusTransition(from, to) {
@@ -29,3 +120,88 @@ function isValidStatusTransition(from, to) {
 /** Every legal `PaymentIntentStatus`, derived from `ALLOWED`'s keys — the
  * single source of truth consumed by the Gateway's list-route status filter. */
 exports.PAYMENT_INTENT_STATUSES = Object.keys(ALLOWED);
+/**
+ * The statuses a payer can still complete a payment FROM.
+ *
+ * **Twice now this question has been answered by walking the transition table,
+ * and twice the table has moved underneath it.**
+ *
+ * The hosted checkout first asked leaf-ness — "has this status no outgoing
+ * edges" — which meant `settled` while `settled` had none. Adding the refund
+ * transitions (`settled → refunded | partially_refunded`) gave it edges, so a
+ * settled payment stopped looking finished, and the checkout began REUSING a
+ * remembered settled intent instead of minting a fresh one: a payer who had
+ * already paid saw their old receipt forever, with no way to pay the link
+ * again.
+ *
+ * The fix was reachability — "is `settled` still reachable" — and that held
+ * until refunds could be UNDONE. `refunded → settled` (a bank rejecting a
+ * refund days later) makes `settled` reachable from `settled` in two steps, so
+ * reachability answers `true` for a payment that is finished, and the original
+ * bug returns unchanged.
+ *
+ * So the set is stated, not derived. It is exactly the statuses in which the
+ * gateway is still waiting on the PAYER — which is what the question means, in
+ * the payer's own terms, and is the one formulation no edge added elsewhere can
+ * silently change. `paymentIntent.test.ts` pins it against the table: every
+ * member must still be able to reach `settled` without passing through a
+ * post-settlement status, and no non-member may.
+ */
+const PAYABLE_STATUSES = new Set([
+    'created',
+    'awaiting_approval',
+    'approved',
+    'broadcast',
+    'confirming',
+    'requires_action',
+    'processing',
+]);
+/**
+ * Whether a payer can still complete a payment against an intent in this
+ * status.
+ *
+ * `settled` answers `false`: it is where paying ENDS. `partially_refunded`
+ * answers `false` too — money can still move, but not from the payer.
+ */
+function canStillBePaid(status) {
+    return PAYABLE_STATUSES.has(status);
+}
+/**
+ * The statuses a payment reaches only AFTER the payer has finished.
+ *
+ * Exported for the gate below rather than for production use: the property that
+ * makes `PAYABLE_STATUSES` checkable is that a payable status reaches `settled`
+ * without going through one of these.
+ */
+exports.POST_SETTLEMENT_STATUSES = [
+    'settled',
+    'refunded',
+    'partially_refunded',
+];
+/**
+ * Whether `settled` is reachable from `status` without passing through a
+ * post-settlement status. The derivation `canStillBePaid` used to BE, kept as
+ * the thing that checks it rather than as the thing that answers it.
+ */
+function reachesSettlementFromPayer(status) {
+    const blocked = new Set(exports.POST_SETTLEMENT_STATUSES);
+    // A payment that has ALREADY settled is one the payer has finished with,
+    // whatever edges lead out of it. Checked before the walk rather than inside
+    // it, because `partially_refunded → settled` is a direct edge and the walk
+    // would find it in one step — and that edge is a refund being undone, not a
+    // payer paying.
+    if (blocked.has(status))
+        return false;
+    const seen = new Set();
+    const queue = [...ALLOWED[status]];
+    while (queue.length > 0) {
+        const next = queue.shift();
+        if (next === 'settled')
+            return true;
+        if (seen.has(next) || blocked.has(next))
+            continue;
+        seen.add(next);
+        queue.push(...ALLOWED[next]);
+    }
+    return false;
+}

package/dist/cjs/settlement.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/social.js

@@ -3,3 +3,22 @@
 // Gateway backend, the wallet frontend, and (indirectly) the enrichment
 // service's callers. Mirrors the Stripe-parity style of paymentIntent.ts.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SOCIAL_SOURCE_REF_MAX_LENGTH = exports.SOCIAL_SOURCE_APP_MAX_LENGTH = void 0;
+/**
+ * Longest `SocialPaymentSource.app` the gateway accepts. An app slug, not a
+ * label — 32 characters is more than any Oxy app id needs and short enough that
+ * the column can never become a place to put prose.
+ *
+ * Published with the contract because it is what a request is REFUSED for: a
+ * caller that cannot read the bound from the types finds it out with a 422.
+ */
+exports.SOCIAL_SOURCE_APP_MAX_LENGTH = 32;
+/**
+ * Longest `SocialPaymentSource.ref` the gateway accepts.
+ *
+ * The bound is the whole defence here, because the value is opaque: Peable
+ * never parses, resolves or links a `ref`, so nothing downstream would notice
+ * it growing. 128 characters holds any id an app mints (a uuid, a snowflake, a
+ * base64 hash) and refuses a payload.
+ */
+exports.SOCIAL_SOURCE_REF_MAX_LENGTH = 128;

package/dist/esm/billing.js

@@ -0,0 +1,3 @@
+/** Recurring billing transport. Store/plan references belong to the authenticated app;
+ * they do not identify an Oxy payer or convey entitlements. */
+export const BILLING_SUBSCRIPTION_STATUSES = ['incomplete', 'incomplete_expired', 'trialing', 'active', 'past_due', 'canceled', 'unpaid', 'paused'];

package/dist/esm/dispute.js

@@ -0,0 +1,16 @@
+/**
+ * A dispute — the card network holding a settled payment's money while a
+ * cardholder contests it.
+ *
+ * Published because `payment_intent.disputed` and `payment_intent.dispute_closed`
+ * carry it as their `data.object`. It was route-local at first, with the webhook
+ * carrying the PaymentIntent and the detail reachable only through
+ * `GET /v1/payment_intents/:id/disputes`. That was inconsistent with the reason
+ * those two events exist: `disputed` is a DEADLINE, and a merchant who has to
+ * make a second call to learn when evidence is due is a merchant who can miss it
+ * while their integration is working exactly as documented.
+ *
+ * It is also what the provider does. Stripe's `charge.dispute.created` carries
+ * the dispute, not the charge — the parity was half-applied.
+ */
+export {};

package/dist/esm/index.js

@@ -1,5 +1,7 @@
 // @peable.to/shared-types — public API for the Peable Gateway contract.
-export { UNITS_PER_COIN, isBaseUnitString } from './money.js';
-export { isValidStatusTransition, PAYMENT_INTENT_STATUSES, } from './paymentIntent.js';
+export { UNITS_PER_COIN, isBaseUnitString, CURRENCY_CODES, CURRENCY_DECIMALS, decimalsFor, isCurrencyCode, } from './money.js';
+export { isValidStatusTransition, canStillBePaid, reachesSettlementFromPayer, POST_SETTLEMENT_STATUSES, PAYMENT_INTENT_STATUSES, PAYMENT_INTENT_RAILS, CHAIN_ONLY_STATUSES, CARD_ONLY_STATUSES, } from './paymentIntent.js';
 export { signWebhook, verifyWebhook } from './webhookSigner.js';
 export { MERCHANT_ENVIRONMENTS, } from './merchant.js';
+export { SOCIAL_SOURCE_APP_MAX_LENGTH, SOCIAL_SOURCE_REF_MAX_LENGTH, } from './social.js';
+export { BILLING_SUBSCRIPTION_STATUSES, } from './billing.js';

package/dist/esm/money.js

@@ -1,16 +1,54 @@
-// Amount helpers over FairCoin base units (m⊜). One coin is UNITS_PER_COIN
-// base units. Amounts move through the system as bigint conceptually; the
-// PaymentIntent DTO stores them as a base-unit integer string so no float ever
-// touches a monetary value.
+// Amount helpers. Every monetary value moves through this gateway as a
+// canonical integer string in the currency's SMALLEST unit — m⊜ for FairCoin,
+// cents for a fiat currency — so no float ever touches one.
+/**
+ * The currencies this gateway can denominate a payment in.
+ *
+ * A closed set, and the database mirrors it as a CHECK
+ * (`db/schema/valueSets.ts`). ADR 0001 D4: the scale of an amount is a property
+ * of its currency and is NOT implied by the field's type, which is why
+ * {@link CURRENCY_DECIMALS} exists and why {@link UNITS_PER_COIN} must never be
+ * used to interpret a fiat amount.
+ */
+export const CURRENCY_CODES = ['FAIR', 'EUR', 'USD'];
+/** Whether an arbitrary string is a currency this gateway knows. */
+export function isCurrencyCode(value) {
+    return CURRENCY_CODES.includes(value);
+}
+/**
+ * How many decimal places each currency's smallest unit represents — i.e. an
+ * amount of `1` means `10^-decimals` of one whole unit.
+ *
+ * FairCoin's 8 is a consensus constant and is pinned against
+ * {@link UNITS_PER_COIN} by this package's own tests, so the two spellings of
+ * one fact cannot drift.
+ */
+export const CURRENCY_DECIMALS = Object.freeze({
+    FAIR: 8,
+    EUR: 2,
+    USD: 2,
+});
+/** The decimal places of `currency`'s smallest unit. */
+export function decimalsFor(currency) {
+    return CURRENCY_DECIMALS[currency];
+}
 // Frozen FairCoin consensus constant (smallest units per FAIR). Mirrors
 // @fairco.in/core's branding.ts; inlined here (rather than imported) to keep
 // @peable.to/shared-types zero-runtime-dep for a clean CJS+ESM publish — must
 // stay a bigint, never converted to number.
+//
+// FAIRCOIN ONLY. A fiat amount has its own scale (`CURRENCY_DECIMALS`), and
+// dividing a EUR amount by this constant is off by six orders of magnitude with
+// nothing failing.
 export const UNITS_PER_COIN = 100000000n;
 /**
- * True only for a canonical non-negative integer string in base units:
- * one or more decimal digits, no sign, no decimal point, no leading zeros
- * (except the literal "0"). Floats and negatives are rejected.
+ * True only for a canonical non-negative integer string in the currency's
+ * smallest unit: one or more decimal digits, no sign, no decimal point, no
+ * leading zeros (except the literal "0"). Floats and negatives are rejected.
+ *
+ * Currency-agnostic on purpose — the pattern is about the SPELLING of an
+ * amount, not its scale, and the same one is restated as a CHECK in the
+ * database (`BASE_UNIT_STRING_PATTERN`), byte-identical.
  */
 export function isBaseUnitString(s) {
     return /^(0|[1-9][0-9]*)$/.test(s);

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}