@dork-labs/cloud-api 0.83.0 → 0.88.0

package/dist/display.js

@@ -0,0 +1,431 @@
+/**
+ * `@dork-labs/cloud-api/display` — one way to render a Cloud amount for a person.
+ *
+ * Every amount on the wire is an exact integer count of micro-units carried as
+ * a string, and a response names its unit in `denomination`: the currency the
+ * micro-units are millionths of, and how many micro-units one credit is. This
+ * module turns an amount and that denomination into text, by the kind of
+ * figure it is:
+ *
+ * - a **position** (what someone has or may still spend) rounds down to whole
+ *   credits, so no page shows credit that cannot be spent;
+ * - a **charge** (what someone spent, was charged or is held for) rounds half
+ *   away from zero to whole credits, and a non-zero amount under half a credit
+ *   reads as less than one credit;
+ * - a **rate** (a price per unit of something) is never rounded;
+ * - **money** rounds to the currency's minor unit, half away from zero, and a
+ *   non-zero amount that rounds to zero reads as less than the smallest unit;
+ * - a **cap** (a money limit) rounds down, so a limit never reads higher than
+ *   the one enforced.
+ *
+ * Rules this module keeps, so two clients can never disagree:
+ *
+ * - **No scale lives here.** The credit scale comes from the served
+ *    denomination on every call. A missing or malformed denomination, or a
+ *    malformed amount, returns `null`: never a guess.
+ * - **No amount becomes a JavaScript number.** Every digit is produced with
+ *    `BigInt`. `Intl.NumberFormat` is asked only for a currency's symbol, where
+ *    the symbol sits, and how many minor-unit digits the currency has. No
+ *    amount is ever handed to `Intl`.
+ * - **No dependencies**, not even the contract's own schemas, so a renderer
+ *    can import this without Zod.
+ *
+ * Numbers are grouped the way `en-US` groups them. Localised formatting is a
+ * separate, later change. The package README lists every rule with worked
+ * examples.
+ *
+ * @packageDocumentation
+ */
+const INTEGER_STRING = /^-?(0|[1-9][0-9]*)$/;
+const POSITIVE_INTEGER_STRING = /^[1-9][0-9]*$/;
+const CURRENCY_CODE = /^[A-Z]{3}$/;
+/** How many decimal digits a micro-unit is below the major unit. */
+const MICRO_DIGITS = 6;
+const MICRO_PER_MAJOR = BigInt(10) ** BigInt(MICRO_DIGITS);
+const ZERO = BigInt(0);
+const ONE = BigInt(1);
+const TWO = BigInt(2);
+const TEN = BigInt(10);
+/**
+ * Floor division: the quotient rounded toward negative infinity.
+ *
+ * @param dividend - Any integer.
+ * @param divisor - A positive integer.
+ */
+export function floorDiv(dividend, divisor) {
+    const quotient = dividend / divisor;
+    return dividend % divisor !== ZERO && dividend < ZERO ? quotient - ONE : quotient;
+}
+/**
+ * The quotient rounded to the nearest integer, a tie going away from zero.
+ *
+ * @param dividend - Any integer.
+ * @param divisor - A positive integer.
+ */
+export function roundHalfAwayFromZero(dividend, divisor) {
+    const magnitude = dividend < ZERO ? -dividend : dividend;
+    let quotient = magnitude / divisor;
+    if ((magnitude % divisor) * TWO >= divisor)
+        quotient += ONE;
+    return dividend < ZERO ? -quotient : quotient;
+}
+/**
+ * Reads an amount string, or `null` when it is not a base-10 integer string.
+ *
+ * @param micro - The amount as it came off the wire.
+ */
+function parseAmount(micro) {
+    if (typeof micro !== 'string' || !INTEGER_STRING.test(micro))
+        return null;
+    return BigInt(micro);
+}
+/**
+ * Reads the served credit scale, or `null` when the denomination is missing or
+ * malformed.
+ *
+ * @param denomination - The response's `denomination`.
+ */
+function parseScale(denomination) {
+    if (typeof denomination !== 'object' || denomination === null)
+        return null;
+    const { microPerCredit } = denomination;
+    if (typeof microPerCredit !== 'string' || !POSITIVE_INTEGER_STRING.test(microPerCredit)) {
+        return null;
+    }
+    if (currencyOf(denomination) === null)
+        return null;
+    return BigInt(microPerCredit);
+}
+const currencyShapes = new Map();
+/**
+ * Learns how a currency is written in `en-US`, without formatting any amount.
+ *
+ * `formatToParts(0)` gives the symbol and which side of the digits it sits on;
+ * `resolvedOptions()` gives the minor-unit digits. Cached per code.
+ *
+ * @param currency - An ISO 4217 code.
+ */
+function shapeOf(currency) {
+    const cached = currencyShapes.get(currency);
+    if (cached !== undefined)
+        return cached;
+    let shape = null;
+    try {
+        const format = new Intl.NumberFormat('en-US', { style: 'currency', currency });
+        const parts = format.formatToParts(0);
+        const numeric = new Set(['integer', 'group', 'decimal', 'fraction']);
+        const first = parts.findIndex((part) => numeric.has(part.type));
+        let last = -1;
+        parts.forEach((part, index) => {
+            if (numeric.has(part.type))
+                last = index;
+        });
+        const minorDigits = format.resolvedOptions().maximumFractionDigits ?? 0;
+        if (first >= 0 && minorDigits >= 0 && minorDigits <= MICRO_DIGITS) {
+            const text = (slice) => slice
+                .filter((part) => part.type !== 'minusSign' && part.type !== 'plusSign')
+                .map((part) => part.value)
+                .join('');
+            shape = {
+                prefix: text(parts.slice(0, first)),
+                suffix: text(parts.slice(last + 1)),
+                minorDigits,
+            };
+        }
+    }
+    catch {
+        shape = null;
+    }
+    currencyShapes.set(currency, shape);
+    return shape;
+}
+/**
+ * Reads the currency of a denomination, or `null` when it is missing, not
+ * three capital letters, or refused by this runtime's `Intl`. A well-formed
+ * code `Intl` does not know is still written, with the code as its symbol.
+ *
+ * @param denomination - A response's `denomination`, or just `{ currency }`.
+ */
+function currencyOf(denomination) {
+    if (typeof denomination !== 'object' || denomination === null)
+        return null;
+    const { currency } = denomination;
+    if (typeof currency !== 'string' || !CURRENCY_CODE.test(currency))
+        return null;
+    return shapeOf(currency);
+}
+/**
+ * Groups the digits of a non-negative integer the way `en-US` does.
+ *
+ * @param value - A non-negative integer.
+ */
+function group(value) {
+    const digits = value.toString();
+    let out = '';
+    for (let index = 0; index < digits.length; index += 1) {
+        if (index > 0 && (digits.length - index) % 3 === 0)
+            out += ',';
+        out += digits[index];
+    }
+    return out;
+}
+/**
+ * Writes `numerator / 10^scaleDigits` exactly, grouped, with at least
+ * `minFraction` decimals and no trailing zero beyond them.
+ *
+ * @param numerator - A non-negative integer.
+ * @param scaleDigits - How many decimal places the numerator is scaled by.
+ * @param minFraction - The fewest decimals to show.
+ */
+function decimal(numerator, scaleDigits, minFraction) {
+    const unit = TEN ** BigInt(scaleDigits);
+    const whole = numerator / unit;
+    let fraction = scaleDigits > 0 ? (numerator % unit).toString().padStart(scaleDigits, '0') : '';
+    while (fraction.length > minFraction && fraction.endsWith('0'))
+        fraction = fraction.slice(0, -1);
+    return fraction.length > 0 ? `${group(whole)}.${fraction}` : group(whole);
+}
+/**
+ * Writes an integer credit count with its sign, never as a negative zero.
+ *
+ * @param value - Whole credits.
+ */
+function signedCredits(value) {
+    return value < ZERO ? `-${group(-value)}` : group(value);
+}
+/**
+ * Writes a count of minor units as money.
+ *
+ * @param minor - The amount in the currency's minor units.
+ * @param shape - How the currency is written.
+ * @param whole - Whether to drop the minor digits (the exact amount is whole).
+ */
+function writeMoney(minor, shape, whole) {
+    const magnitude = minor < ZERO ? -minor : minor;
+    const digits = whole
+        ? group(magnitude / TEN ** BigInt(shape.minorDigits))
+        : decimal(magnitude, shape.minorDigits, shape.minorDigits);
+    const sign = minor < ZERO ? '-' : '';
+    return `${sign}${shape.prefix}${digits}${shape.suffix}`;
+}
+/**
+ * The shared money rule, with the rounding as a parameter.
+ *
+ * @param micro - The amount string.
+ * @param currency - The response's `denomination`, or just `{ currency }`.
+ * @param round - How to turn micro-units into minor units.
+ */
+function money(micro, currency, round) {
+    const amount = parseAmount(micro);
+    const shape = currencyOf(currency);
+    if (amount === null || shape === null)
+        return null;
+    const microPerMinor = TEN ** BigInt(MICRO_DIGITS - shape.minorDigits);
+    const minor = round(amount, microPerMinor);
+    if (minor === ZERO && amount !== ZERO) {
+        const smallest = writeMoney(ONE, shape, shape.minorDigits === 0);
+        return amount < ZERO ? `-<${smallest}` : `<${smallest}`;
+    }
+    // Whole means the EXACT amount is a whole major unit, so a rounded figure
+    // keeps its minor digits and never reads as more exact than it is.
+    return writeMoney(minor, shape, amount % MICRO_PER_MAJOR === ZERO);
+}
+/**
+ * Renders what a person has or may still spend: whole credits, rounded toward
+ * negative infinity, so it never shows credit that cannot be spent.
+ *
+ * @param micro - The amount string, in micro-units.
+ * @param denomination - The response's `denomination`.
+ * @returns The grouped credit count, or `null` for a malformed amount or denomination.
+ */
+export function formatPosition(micro, denomination) {
+    const amount = parseAmount(micro);
+    const scale = parseScale(denomination);
+    if (amount === null || scale === null)
+        return null;
+    return signedCredits(floorDiv(amount, scale));
+}
+/**
+ * Renders what a person spent, was charged or is held for: whole credits,
+ * rounded half away from zero. Zero reads as zero; a non-zero amount that rounds
+ * to zero reads as less than one credit, with a minus sign when negative.
+ *
+ * @param micro - The amount string, in micro-units.
+ * @param denomination - The response's `denomination`.
+ * @returns The grouped credit count, or `null` for a malformed amount or denomination.
+ */
+export function formatCharge(micro, denomination) {
+    const amount = parseAmount(micro);
+    const scale = parseScale(denomination);
+    if (amount === null || scale === null)
+        return null;
+    if (amount === ZERO)
+        return '0';
+    const credits = roundHalfAwayFromZero(amount, scale);
+    if (credits === ZERO)
+        return amount < ZERO ? '-<1' : '<1';
+    return signedCredits(credits);
+}
+/**
+ * Renders a price per unit of something in credits, never rounded: every
+ * significant digit, trailing zeros trimmed.
+ *
+ * A scale with a prime factor other than two or five cannot write every
+ * amount as a finite decimal. Such an amount returns `null` rather than a
+ * rounded figure.
+ *
+ * @param micro - The amount string, in micro-units.
+ * @param denomination - The response's `denomination`.
+ * @returns The exact credit figure, or `null` when it cannot be written exactly or the input is malformed.
+ */
+export function formatRate(micro, denomination) {
+    const amount = parseAmount(micro);
+    const scale = parseScale(denomination);
+    if (amount === null || scale === null)
+        return null;
+    // amount / scale is a finite decimal exactly when, after cancelling, the
+    // denominator has only twos and fives. Find the power of ten that clears it.
+    let digits = 0;
+    let numerator = amount < ZERO ? -amount : amount;
+    let power = ONE;
+    while ((numerator * power) % scale !== ZERO) {
+        digits += 1;
+        power *= TEN;
+        if (digits > scale.toString().length * 4)
+            return null;
+    }
+    numerator = (numerator * power) / scale;
+    const text = decimal(numerator, digits, 0);
+    return amount < ZERO ? `-${text}` : text;
+}
+/**
+ * Renders money: rounded to the currency's minor unit, half away from zero.
+ * An amount that is exactly a whole major unit prints without minor digits;
+ * any other prints with all of them. A non-zero amount that rounds to zero
+ * reads as less than the smallest unit.
+ *
+ * Money needs no credit scale, so a bare `{ currency }` is enough.
+ *
+ * @param micro - The amount string, in micro-units of the currency.
+ * @param currency - The response's `denomination`, or just `{ currency }`.
+ * @returns The money text, or `null` for a malformed amount or currency.
+ */
+export function formatMoney(micro, currency) {
+    return money(micro, currency, roundHalfAwayFromZero);
+}
+/**
+ * Renders a money limit: the money rule, rounded toward negative infinity, so
+ * a limit never reads higher than the one enforced.
+ *
+ * @param micro - The amount string, in micro-units of the currency.
+ * @param currency - The response's `denomination`, or just `{ currency }`.
+ * @returns The money text, or `null` for a malformed amount or currency.
+ */
+export function formatCap(micro, currency) {
+    return money(micro, currency, floorDiv);
+}
+/**
+ * Renders a price in money, never rounded: the exact amount, with at least the
+ * currency's minor digits.
+ *
+ * @param micro - The amount string, in micro-units of the currency.
+ * @param currency - The response's `denomination`, or just `{ currency }`.
+ * @returns The money text, or `null` for a malformed amount or currency.
+ */
+export function formatMoneyRate(micro, currency) {
+    const amount = parseAmount(micro);
+    const shape = currencyOf(currency);
+    if (amount === null || shape === null)
+        return null;
+    const magnitude = amount < ZERO ? -amount : amount;
+    const sign = amount < ZERO ? '-' : '';
+    return `${sign}${shape.prefix}${decimal(magnitude, MICRO_DIGITS, shape.minorDigits)}${shape.suffix}`;
+}
+/**
+ * Renders a credit figure with its money value beside it:
+ * `<credits> credits (<money>)`, with the singular for exactly one credit.
+ *
+ * For a position or a charge the money is worked out from the ROUNDED credit
+ * count times the served scale, never separately from the exact amount, so the
+ * two figures always agree. A charge under one credit reads as less than one
+ * credit, beside less than the money of one credit. A rate is exact on both
+ * sides.
+ *
+ * @param micro - The amount string, in micro-units.
+ * @param denomination - The response's `denomination`.
+ * @param kind - How the credit figure is rounded.
+ * @returns The text, or `null` for a malformed amount or denomination.
+ */
+export function formatCreditsWithMoney(micro, denomination, kind) {
+    const amount = parseAmount(micro);
+    const scale = parseScale(denomination);
+    if (amount === null || scale === null)
+        return null;
+    const label = (credits) => credits === '1' || credits === '-1' ? `${credits} credit` : `${credits} credits`;
+    if (kind === 'rate') {
+        const credits = formatRate(micro, denomination);
+        const price = formatMoneyRate(micro, denomination);
+        if (credits === null || price === null)
+            return null;
+        return `${label(credits)} (${price})`;
+    }
+    let credits;
+    if (kind === 'position') {
+        credits = floorDiv(amount, scale);
+    }
+    else {
+        credits = amount === ZERO ? ZERO : roundHalfAwayFromZero(amount, scale);
+        if (credits === ZERO && amount !== ZERO) {
+            const oneCredit = formatMoney(scale.toString(), denomination);
+            if (oneCredit === null)
+                return null;
+            // One credit may itself be under the smallest money unit, in which case
+            // it already reads as less than that unit and needs no second marker.
+            const under = oneCredit.startsWith('<') ? oneCredit : `<${oneCredit}`;
+            return amount < ZERO ? `-<1 credit (-${under})` : `<1 credit (${under})`;
+        }
+    }
+    const price = formatMoney((credits * scale).toString(), denomination);
+    if (price === null)
+        return null;
+    return `${label(signedCredits(credits))} (${price})`;
+}
+/**
+ * Renders a total the only honest way: the exact sum of the lines, rounded once
+ * by the kind of what it totals. Never the sum of rounded lines, so a total may
+ * differ from its rounded lines by a credit or two, and it is the total that
+ * matches what was charged.
+ *
+ * @param lines - The exact amount strings being totalled.
+ * @param denomination - The response's `denomination` (or `{ currency }` for money and cap).
+ * @param kind - How the total is rounded.
+ * @returns The total's text, or `null` when any line or the denomination is malformed.
+ */
+export function formatTotal(lines, denomination, kind) {
+    let sum = ZERO;
+    for (const line of lines) {
+        const amount = parseAmount(line);
+        if (amount === null)
+            return null;
+        sum += amount;
+    }
+    const total = sum.toString();
+    // The credit kinds read the scale off the denomination and return null
+    // without one, so a bare currency is safe to pass through.
+    const scaled = denomination;
+    switch (kind) {
+        case 'position':
+            return formatPosition(total, scaled);
+        case 'charge':
+            return formatCharge(total, scaled);
+        case 'rate':
+            return formatRate(total, scaled);
+        case 'money':
+            return formatMoney(total, denomination);
+        case 'cap':
+            return formatCap(total, denomination);
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=display.js.map

package/dist/display.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"display.js","sourceRoot":"","sources":["../src/display.ts"],"names":[],"mappings":"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"}

package/dist/primitives.d.ts

@@ -51,6 +51,69 @@ export declare const MicroAmountSchema: z.ZodString;
  * here.
  */
 export declare const PositiveMicroAmountSchema: z.ZodString;
+/**
+ * The metadata key that says what kind of amount a field carries.
+ *
+ * Set with `.meta()` on {@link MoneyMicroSchema} and {@link CreditMicroSchema},
+ * so it reaches the generated JSON Schema as an `amountKind` keyword as well as
+ * the runtime registry (`z.globalRegistry.get(schema)`). A renderer reads it to
+ * decide whether an amount is shown as money or as credits.
+ */
+export declare const AMOUNT_KIND_META: "amountKind";
+/**
+ * The two kinds of amount this contract carries.
+ *
+ * Mechanism, not catalog: it says how an amount is counted, never what anybody
+ * bought.
+ */
+export declare const AmountKindSchema: z.ZodEnum<{
+    money: "money";
+    credit: "credit";
+}>;
+/** What an amount counts. */
+export type AmountKind = z.infer<typeof AmountKindSchema>;
+/**
+ * An amount of money, as an exact integer count of micro-units carried as a
+ * string.
+ *
+ * The same wire shape and the same TypeScript type as {@link MicroAmountSchema};
+ * only the description and the {@link AMOUNT_KIND_META} mark differ. Render it
+ * in the response's `denomination.currency`, never as credits.
+ */
+export declare const MoneyMicroSchema: z.ZodString;
+/**
+ * A strictly positive amount of money: the shape of an amount a purchase is
+ * made of.
+ *
+ * The same wire shape as {@link PositiveMicroAmountSchema}, marked as money.
+ */
+export declare const PositiveMoneyMicroSchema: z.ZodString;
+/**
+ * An amount of credits, as an exact integer count of micro-units carried as a
+ * string.
+ *
+ * The same wire shape and the same TypeScript type as {@link MicroAmountSchema};
+ * only the description and the {@link AMOUNT_KIND_META} mark differ. Divide by
+ * the response's `denomination.microPerCredit` to get credits. The scale is
+ * served, never assumed: this package publishes no value for it.
+ */
+export declare const CreditMicroSchema: z.ZodString;
+/**
+ * The unit a response's amounts are in: which currency the micro-units are
+ * millionths of, and how many of them one credit is.
+ *
+ * Served by the service at runtime on every response that carries an amount.
+ * This package publishes no value for either field, and a client never
+ * hard-codes one. A response without it came from an older service; a client
+ * that receives none shows that it could not read the amount rather than
+ * guessing a unit.
+ */
+export declare const DenominationSchema: z.ZodObject<{
+    currency: z.ZodString;
+    microPerCredit: z.ZodString;
+}, z.core.$strip>;
+/** The unit a response's amounts are in. */
+export type Denomination = z.infer<typeof DenominationSchema>;
 /**
  * A value returned once and never again.
  *

package/dist/primitives.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../src/primitives.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAG,CAAU,CAAC;AAEvC,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,EAAG,KAAc,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAG,eAAwB,CAAC;AAE5D,kEAAkE;AAClE,eAAO,MAAM,yBAAyB,QAAuB,CAAC;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,eAAe,kBAEmC,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,aAGkE,CAAC;AAExF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,aAQ3B,CAAC;AAEJ;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,aAQnC,CAAC;AAEJ;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,aAK3B,CAAC;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,YAAY,aAG6D,CAAC;AAEvF,kEAAkE;AAClE,eAAO,MAAM,gBAAgB;;;iBAa4D,CAAC;AAE1F,uEAAuE;AACvE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,WAAW,EAAE,MAAM;;;kBAS1E;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,UAGyC,CAAC;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,UAMwD,CAAC;AAErF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,EAAG,8BAAuC,CAAC;AAEhF;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAG,cAAuB,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,4FAQzD"}
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../src/primitives.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAG,CAAU,CAAC;AAEvC,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,EAAG,KAAc,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAG,eAAwB,CAAC;AAE5D,kEAAkE;AAClE,eAAO,MAAM,yBAAyB,QAAuB,CAAC;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,eAAe,kBAEmC,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,aAGkE,CAAC;AAExF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,aAQ3B,CAAC;AAEJ;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,aAQnC,CAAC;AAEJ;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAG,YAAqB,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;;EAI1B,CAAC;AAEJ,6BAA6B;AAC7B,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAK1D;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,aAMW,CAAC;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,aASG,CAAC;AAEzC;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,aAMW,CAAC;AAE1C;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB;;;iBAY5B,CAAC;AAEJ,4CAA4C;AAC5C,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,aAK3B,CAAC;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,YAAY,aAG6D,CAAC;AAEvF,kEAAkE;AAClE,eAAO,MAAM,gBAAgB;;;iBAa4D,CAAC;AAE1F,uEAAuE;AACvE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,WAAW,EAAE,MAAM;;;kBAS1E;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,UAGyC,CAAC;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,UAMwD,CAAC;AAErF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,EAAG,8BAAuC,CAAC;AAEhF;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAG,cAAuB,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,4FAQzD"}

package/dist/primitives.js

@@ -44,7 +44,7 @@ export const IdSchema = z
 export const MicroAmountSchema = z
     .string()
     .regex(/^-?(0|[1-9][0-9]*)$/, 'must be a base-10 integer count of micro-units carried as a string')
-    .describe('An exact integer count of micro-units, carried as a string so no value goes through a JavaScript number.');
+    .describe('An exact integer count of micro-units, carried as a string so no value goes through a JavaScript number. A micro-unit is a millionth of the major unit of the currency the response names.');
 /**
  * A strictly positive integer count of micro-units carried as a string.
  *
@@ -62,6 +62,83 @@ export const PositiveMicroAmountSchema = z
     .string()
     .regex(/^[1-9][0-9]*$/, 'must be a positive base-10 integer count of micro-units carried as a string')
     .describe('A strictly positive exact integer count of micro-units, carried as a string so no amount goes through a JavaScript number.');
+/**
+ * The metadata key that says what kind of amount a field carries.
+ *
+ * Set with `.meta()` on {@link MoneyMicroSchema} and {@link CreditMicroSchema},
+ * so it reaches the generated JSON Schema as an `amountKind` keyword as well as
+ * the runtime registry (`z.globalRegistry.get(schema)`). A renderer reads it to
+ * decide whether an amount is shown as money or as credits.
+ */
+export const AMOUNT_KIND_META = 'amountKind';
+/**
+ * The two kinds of amount this contract carries.
+ *
+ * Mechanism, not catalog: it says how an amount is counted, never what anybody
+ * bought.
+ */
+export const AmountKindSchema = z
+    .enum(['money', 'credit'])
+    .describe('What an amount counts: money paid, refunded, offered or capped, or credits held, spent or priced.');
+const INTEGER_STRING = /^-?(0|[1-9][0-9]*)$/;
+const POSITIVE_INTEGER_STRING = /^[1-9][0-9]*$/;
+/**
+ * An amount of money, as an exact integer count of micro-units carried as a
+ * string.
+ *
+ * The same wire shape and the same TypeScript type as {@link MicroAmountSchema};
+ * only the description and the {@link AMOUNT_KIND_META} mark differ. Render it
+ * in the response's `denomination.currency`, never as credits.
+ */
+export const MoneyMicroSchema = z
+    .string()
+    .regex(INTEGER_STRING, 'must be a base-10 integer count of micro-units carried as a string')
+    .describe("An exact integer count of micro-units of the response's currency: money paid, refunded, offered or capped.")
+    .meta({ [AMOUNT_KIND_META]: 'money' });
+/**
+ * A strictly positive amount of money: the shape of an amount a purchase is
+ * made of.
+ *
+ * The same wire shape as {@link PositiveMicroAmountSchema}, marked as money.
+ */
+export const PositiveMoneyMicroSchema = z
+    .string()
+    .regex(POSITIVE_INTEGER_STRING, 'must be a positive base-10 integer count of micro-units carried as a string')
+    .describe('A strictly positive exact integer count of micro-units of money to be paid, in the currency the service names.')
+    .meta({ [AMOUNT_KIND_META]: 'money' });
+/**
+ * An amount of credits, as an exact integer count of micro-units carried as a
+ * string.
+ *
+ * The same wire shape and the same TypeScript type as {@link MicroAmountSchema};
+ * only the description and the {@link AMOUNT_KIND_META} mark differ. Divide by
+ * the response's `denomination.microPerCredit` to get credits. The scale is
+ * served, never assumed: this package publishes no value for it.
+ */
+export const CreditMicroSchema = z
+    .string()
+    .regex(INTEGER_STRING, 'must be a base-10 integer count of micro-units carried as a string')
+    .describe("An exact integer count of micro-units of the response's currency, counted as credits: divide by the response's denomination.microPerCredit to get credits.")
+    .meta({ [AMOUNT_KIND_META]: 'credit' });
+/**
+ * The unit a response's amounts are in: which currency the micro-units are
+ * millionths of, and how many of them one credit is.
+ *
+ * Served by the service at runtime on every response that carries an amount.
+ * This package publishes no value for either field, and a client never
+ * hard-codes one. A response without it came from an older service; a client
+ * that receives none shows that it could not read the amount rather than
+ * guessing a unit.
+ */
+export const DenominationSchema = z
+    .object({
+    currency: z
+        .string()
+        .regex(/^[A-Z]{3}$/, 'must be an ISO 4217 currency code')
+        .describe('An ISO 4217 code. Rendered, never enumerated.'),
+    microPerCredit: PositiveMicroAmountSchema.describe('How many micro-units of currency one credit is. Served by the service; a client never hard-codes it.'),
+})
+    .describe('The unit these amounts are in: the currency their micro-units are millionths of, and how many micro-units one credit is.');
 /**
  * A value returned once and never again.
  *

package/dist/primitives.js.map

@@ -1 +1 @@
-{"version":3,"file":"primitives.js","sourceRoot":"","sources":["../src/primitives.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"primitives.js","sourceRoot":"","sources":["../src/primitives.ts"],"names":[],"mappings":"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"}