@axorum/client 0.0.0-stage → 1.0.0

package/dist/index.js.map

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

package/dist/intent.d.ts

@@ -0,0 +1,163 @@
+/**
+ * An intent with everything but the policy pin.
+ *
+ * @packageDocumentation
+ */
+import type { ActionTerm, Entry, IntentEnvelope, UsageMove } from "./types.js";
+/**
+ * An {@link IntentEnvelope} with everything the agent knows, and **not** the one thing
+ * only the service does: which policy is in force.
+ *
+ * The pin is not the agent's to choose. It is a claim about the *service's* state — "I
+ * believe policy P is in force" — and getting it wrong is a `409`. So it is left off
+ * here, and {@link AxorumClient.submitPinned} stamps it from the service's own answer,
+ * re-stamping it if the policy moves mid-flight.
+ *
+ * A plain object, not a builder: `entries`, `evidence` and `justification` are
+ * optional and default to empty, which is a well-formed thing to *hold* — the ledger,
+ * not this type, is the judge of whether it is a well-formed thing to *submit*.
+ *
+ * ```ts
+ * const draft: IntentDraft = {
+ *   agent: "agent://example.com/agent/clerk_01h455vb4pex5vsknk084sn02q",
+ *   attestation: paseto,
+ *   action: { action: "post", bindings: {} },
+ *   entries: [
+ *     { account: cash,    side: "Debit",  amount: { minor: 1_000n, currency: "USD" } },
+ *     { account: revenue, side: "Credit", amount: { minor: 1_000n, currency: "USD" } },
+ *   ],
+ *   justification: "invoice 4471, approved by the purchase order",
+ * };
+ * ```
+ *
+ * # Usage moves ride the same draft
+ *
+ * A metered spend is one intent, not two. The `consume_usage` / `meter_usage` /
+ * `bill_usage` moves travel on the *same* draft as the journal legs, are judged in the
+ * *same* commit, and are held to the usage-balance conservation law
+ * `0 ≤ billed ≤ metered ≤ consumed`. So an agent that consumes an API call, meters it, and
+ * bills for it does so atomically — and the three moves are validated **together** against
+ * the combined post-state, which is why one intent may lawfully do all three at once:
+ *
+ * ```ts
+ * const metered: IntentDraft = {
+ *   ...draft,
+ *   consume_usage: { usage, amount: { minor: 1_000n, currency: "USD" } },
+ *   meter_usage:   { usage, amount: { minor: 1_000n, currency: "USD" } },
+ *   bill_usage:    { usage, amount: { minor: 1_000n, currency: "USD" } },
+ * };
+ * ```
+ *
+ * A move that would break the chain — metering past consumption, billing past metering, a
+ * correction below zero, a balance the agent's party does not own — is refused, and
+ * **nothing posts**: not the usage moves, and not the journal legs that rode with them.
+ */
+export interface IntentDraft {
+    /** The agent's `agent://` URI. */
+    agent: string;
+    /** The PASETO v4.public capability attestation proving the agent may act. */
+    attestation: string;
+    /** The proposed deontic action and its typed bindings. */
+    action: ActionTerm;
+    /**
+     * The client-minted transaction id (`txn_…`) — the substrate's **idempotency key**.
+     *
+     * Omit it and the client mints one for you, **once**, before its first attempt: every
+     * re-pinned retry then carries the same id, so an attempt that in fact landed replays
+     * its stored outcome instead of posting twice. That is the entire reason the retry
+     * loop is safe.
+     *
+     * Supply your own when you need to correlate the submission with something outside
+     * Axorum, or to deliberately replay a transaction you already submitted. Mint it with
+     * {@link newTransactionId}: a UUID v7 id carries its own mint time. An id that does not
+     * (one you derived or were given) needs {@link IntentDraft.minted_at_ms} too.
+     */
+    transaction?: string;
+    /**
+     * When `transaction` was first issued, in whole milliseconds since the Unix epoch, as
+     * the envelope's `minted_at_ms` carries it: the `mintedAtMs` of an
+     * {@link IdempotencyKey} you persisted, or the issue time of an id that is not a UUID
+     * v7 and so carries none. Leave it out for a UUID v7 id, whose own timestamp is read.
+     * Never the time of a retry: the service ages the key from it.
+     */
+    minted_at_ms?: bigint;
+    /** The accounting journal legs. Debits and credits must balance per currency. */
+    entries?: Entry[];
+    /** Exact distinct obligation IDs to fulfill atomically, at most 64. */
+    fulfills?: string[];
+    /** Lowercase-hex SHA-256 digests of external evidence the agent references. */
+    evidence?: string[];
+    /**
+     * The agent's stated reason. The gateway hashes it onto the ledger; the text itself
+     * stays with you.
+     */
+    justification?: string;
+    /**
+     * The **consume** move this intent carries: the ground-truth event that the agent used a
+     * metered resource, as a signed delta on a usage balance's `consumed` running total.
+     *
+     * `consumed` is the top of the chain and takes no ceiling — consumption is a fact, not a
+     * recognition, so nothing bounds it from above.
+     */
+    consume_usage?: UsageMove;
+    /**
+     * The **meter** move this intent carries: the measurement recognition of consumption, as
+     * a signed delta on a usage balance's `metered` running total.
+     *
+     * Metering past `consumed` is **phantom usage** — measuring more than was used — and the
+     * ledger refuses it.
+     */
+    meter_usage?: UsageMove;
+    /**
+     * The **bill** move this intent carries: the financial recognition of metering, as a
+     * signed delta on a usage balance's `billed` running total.
+     *
+     * Billing past `metered` is billing with no meter basis, and the ledger refuses it.
+     */
+    bill_usage?: UsageMove;
+}
+/**
+ * A draft whose transaction id and mint time are settled — minted if the caller left the
+ * id out.
+ *
+ * Internal, and the reason it exists is the whole idempotency story: the id and its mint
+ * time are settled **once**, before the first attempt, not on each pass through the retry
+ * loop. A loop that re-minted would double-post, and one that re-stamped would age the
+ * key from the wrong time.
+ */
+export type SettledDraft = IntentDraft & {
+    transaction: string;
+    minted_at_ms: bigint;
+};
+/**
+ * Settles a draft's transaction id and mint time: a fresh UUID v7 id minted now when it
+ * has none, else the draft's `minted_at_ms`, else the time its UUID v7 id carries.
+ *
+ * Pure but for the mint. Call it once, at the top of a submission — never inside a
+ * retry loop.
+ *
+ * @throws {ConfigError} If the id is not a UUID v7 and the draft sets no
+ *   `minted_at_ms`: the client never invents a mint time for an id it did not mint. Or
+ *   if it sets `minted_at_ms` with no id to belong to.
+ */
+export declare function settleDraft(draft: IntentDraft): SettledDraft;
+/**
+ * Stamps the policy pin and the id's mint time onto a draft, completing the envelope.
+ *
+ * **A pure function** — which is the whole reason the draft/envelope split is testable
+ * without a service running. Re-pinning the same draft changes the policy and *nothing
+ * else*: above all not the transaction id, which is the idempotency key that makes a
+ * retry safe rather than a double-post.
+ *
+ * If the draft has no transaction id, one is minted here; its mint time is settled as
+ * {@link settleDraft} does, so a re-pin of a settled draft keeps it. Prefer letting
+ * {@link AxorumClient.submitPinned} do the pinning — this is exported for callers who
+ * drive the pin themselves, and for the tests that hold the retry loop to account.
+ *
+ * @param draft - The intent, minus the pin.
+ * @param policy - The policy the agent believes is in force (`pol_…`).
+ * @returns The complete envelope, ready to submit.
+ * @throws {ConfigError} As {@link settleDraft}.
+ */
+export declare function pinIntent(draft: IntentDraft, policy: string): IntentEnvelope;
+//# sourceMappingURL=intent.d.ts.map

package/dist/intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../src/intent.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IAEd,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IAEpB,0DAA0D;IAC1D,MAAM,EAAE,UAAU,CAAC;IAEnB;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,iFAAiF;IACjF,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC;IAElB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,SAAS,CAAC;IAE1B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IAExB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvF;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,CAoB5D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CA2B5E"}

package/dist/intent.js

@@ -0,0 +1,82 @@
+/**
+ * An intent with everything but the policy pin.
+ *
+ * @packageDocumentation
+ */
+import { ConfigError } from "./errors.js";
+import { newTransactionId, v7MintedAtMs } from "./typeid.js";
+/**
+ * Settles a draft's transaction id and mint time: a fresh UUID v7 id minted now when it
+ * has none, else the draft's `minted_at_ms`, else the time its UUID v7 id carries.
+ *
+ * Pure but for the mint. Call it once, at the top of a submission — never inside a
+ * retry loop.
+ *
+ * @throws {ConfigError} If the id is not a UUID v7 and the draft sets no
+ *   `minted_at_ms`: the client never invents a mint time for an id it did not mint. Or
+ *   if it sets `minted_at_ms` with no id to belong to.
+ */
+export function settleDraft(draft) {
+    if (draft.transaction === undefined) {
+        if (draft.minted_at_ms !== undefined) {
+            throw new ConfigError("the draft sets minted_at_ms but no transaction: a mint time belongs to the id it " +
+                "was issued with, so set both, or neither and let the client mint the id");
+        }
+        const nowMs = Date.now();
+        return { ...draft, transaction: newTransactionId(nowMs), minted_at_ms: BigInt(nowMs) };
+    }
+    const idTime = v7MintedAtMs(draft.transaction);
+    const mintedAtMs = draft.minted_at_ms ?? (idTime === undefined ? undefined : BigInt(idTime));
+    if (mintedAtMs === undefined) {
+        throw new ConfigError(`transaction '${draft.transaction}' is not a UUID v7 id, so it carries no mint time: ` +
+            `set the draft's minted_at_ms to when it was first issued`);
+    }
+    return { ...draft, transaction: draft.transaction, minted_at_ms: mintedAtMs };
+}
+/**
+ * Stamps the policy pin and the id's mint time onto a draft, completing the envelope.
+ *
+ * **A pure function** — which is the whole reason the draft/envelope split is testable
+ * without a service running. Re-pinning the same draft changes the policy and *nothing
+ * else*: above all not the transaction id, which is the idempotency key that makes a
+ * retry safe rather than a double-post.
+ *
+ * If the draft has no transaction id, one is minted here; its mint time is settled as
+ * {@link settleDraft} does, so a re-pin of a settled draft keeps it. Prefer letting
+ * {@link AxorumClient.submitPinned} do the pinning — this is exported for callers who
+ * drive the pin themselves, and for the tests that hold the retry loop to account.
+ *
+ * @param draft - The intent, minus the pin.
+ * @param policy - The policy the agent believes is in force (`pol_…`).
+ * @returns The complete envelope, ready to submit.
+ * @throws {ConfigError} As {@link settleDraft}.
+ */
+export function pinIntent(draft, policy) {
+    const settled = settleDraft(draft);
+    const targets = settled.fulfills;
+    if (targets !== undefined && (targets.length > 64 || new Set(targets).size !== targets.length ||
+        targets.some((id) => !/^obl_[0-7][0-9a-hjkmnp-tv-z]{25}$/.test(id)))) {
+        throw new TypeError("fulfills must contain at most 64 distinct obligation IDs");
+    }
+    return {
+        agent: settled.agent,
+        attestation: settled.attestation,
+        transaction: settled.transaction,
+        entries: settled.entries ?? [],
+        action: settled.action,
+        evidence: settled.evidence ?? [],
+        ...(settled.fulfills === undefined ? {} : { fulfills: [...settled.fulfills].sort() }),
+        justification: settled.justification ?? "",
+        policy,
+        minted_at_ms: settled.minted_at_ms,
+        // Spread rather than assign: an intent that carries no usage move omits the key
+        // **entirely**, and the contract is explicit that it is never `null`. A
+        // present-but-`undefined` key would serialize to nothing today, but it is not what the
+        // type says, and `exactOptionalPropertyTypes` is on precisely so the two cannot be
+        // confused.
+        ...(settled.consume_usage === undefined ? {} : { consume_usage: settled.consume_usage }),
+        ...(settled.meter_usage === undefined ? {} : { meter_usage: settled.meter_usage }),
+        ...(settled.bill_usage === undefined ? {} : { bill_usage: settled.bill_usage }),
+    };
+}
+//# sourceMappingURL=intent.js.map

package/dist/intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.js","sourceRoot":"","sources":["../src/intent.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA0I7D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,KAAkB;IAC5C,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACpC,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACrC,MAAM,IAAI,WAAW,CACnB,mFAAmF;gBACjF,yEAAyE,CAC5E,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,OAAO,EAAE,GAAG,KAAK,EAAE,WAAW,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IACzF,CAAC;IACD,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAC/C,MAAM,UAAU,GAAG,KAAK,CAAC,YAAY,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7F,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,WAAW,CACnB,gBAAgB,KAAK,CAAC,WAAW,qDAAqD;YACpF,0DAA0D,CAC7D,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,GAAG,KAAK,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,SAAS,CAAC,KAAkB,EAAE,MAAc;IAC1D,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IACjC,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,EAAE,IAAI,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM;QACzF,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,mCAAmC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzE,MAAM,IAAI,SAAS,CAAC,0DAA0D,CAAC,CAAC;IAClF,CAAC;IACD,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE;QAC9B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE;QAChC,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACrF,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,EAAE;QAC1C,MAAM;QACN,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,gFAAgF;QAChF,wEAAwE;QACxE,uFAAuF;QACvF,mFAAmF;QACnF,YAAY;QACZ,GAAG,CAAC,OAAO,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC;QACxF,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;QAClF,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;KAChF,CAAC;AACJ,CAAC"}

package/dist/json.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Lossless JSON for a ledger — because `JSON.parse` is not one.
+ *
+ * Axorum denominates money in **128-bit integer minor units**, and puts them on the
+ * wire as bare JSON numbers (`{"minor": 50000, "currency": "USD"}`). The frozen
+ * contract names JavaScript explicitly on this point: a parser that decodes numbers
+ * as IEEE-754 doubles — `JSON.parse`, notably — silently loses precision on values
+ * above `Number.MAX_SAFE_INTEGER`. Silently mis-stating a balance is the one thing a
+ * financial-control client must never do, so this client does not use `JSON.parse`.
+ *
+ * The rule is one line, and it is the same in both directions:
+ *
+ * > **Every JSON integer is a `bigint`.** Every JSON number with a fraction or an
+ * > exponent is a `number`.
+ *
+ * So `minor`, `balance`, `anchor`, `deadline` and the `Int`/`Tick` literals all
+ * arrive as `bigint`, and the generated wire types say so. It is one rule to hold in
+ * your head instead of a table of which fields are safe.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Parses JSON, decoding every integer as a `bigint` so a 128-bit money value
+ * survives the trip.
+ *
+ * A drop-in replacement for `JSON.parse` in this client, and a pure function: same
+ * text, same value, no I/O.
+ *
+ * @param text - The JSON document.
+ * @returns The decoded value: objects, arrays, strings, booleans, `null`, `bigint`
+ *   for integers, and `number` for fractional or exponent literals.
+ * @throws {SyntaxError} If `text` is not one well-formed JSON document.
+ */
+export declare function parseJson(text: string): unknown;
+/**
+ * Serializes to JSON, writing a `bigint` as a **bare integer literal** — the wire
+ * form the ledger reads — rather than as a quoted string (`JSON.stringify` refuses
+ * `bigint` outright).
+ *
+ * Mirrors `JSON.stringify` otherwise: `toJSON()` is honoured, `undefined` object
+ * values and function values are dropped, and `undefined` array elements become
+ * `null`.
+ *
+ * @param value - The value to serialize.
+ * @returns The JSON text.
+ * @throws {TypeError} On a circular structure.
+ */
+export declare function stringifyJson(value: unknown): string;
+//# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAsLH;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD"}

package/dist/json.js

@@ -0,0 +1,259 @@
+/**
+ * Lossless JSON for a ledger — because `JSON.parse` is not one.
+ *
+ * Axorum denominates money in **128-bit integer minor units**, and puts them on the
+ * wire as bare JSON numbers (`{"minor": 50000, "currency": "USD"}`). The frozen
+ * contract names JavaScript explicitly on this point: a parser that decodes numbers
+ * as IEEE-754 doubles — `JSON.parse`, notably — silently loses precision on values
+ * above `Number.MAX_SAFE_INTEGER`. Silently mis-stating a balance is the one thing a
+ * financial-control client must never do, so this client does not use `JSON.parse`.
+ *
+ * The rule is one line, and it is the same in both directions:
+ *
+ * > **Every JSON integer is a `bigint`.** Every JSON number with a fraction or an
+ * > exponent is a `number`.
+ *
+ * So `minor`, `balance`, `anchor`, `deadline` and the `Int`/`Tick` literals all
+ * arrive as `bigint`, and the generated wire types say so. It is one rule to hold in
+ * your head instead of a table of which fields are safe.
+ *
+ * @packageDocumentation
+ */
+/** Character codes that end a bare JSON token. */
+const STRUCTURAL = new Set([",", "]", "}", " ", "\t", "\n", "\r"]);
+/** A hand-written recursive-descent JSON reader. See the module docs for why. */
+class JsonReader {
+    text;
+    index = 0;
+    constructor(text) {
+        this.text = text;
+    }
+    /** Reads one complete JSON document, rejecting anything trailing it. */
+    read() {
+        const value = this.readValue();
+        this.skipWhitespace();
+        if (this.index < this.text.length) {
+            this.fail("unexpected trailing content");
+        }
+        return value;
+    }
+    readValue() {
+        this.skipWhitespace();
+        const char = this.text[this.index];
+        switch (char) {
+            case "{":
+                return this.readObject();
+            case "[":
+                return this.readArray();
+            case '"':
+                return this.readString();
+            case "t":
+                return this.readLiteral("true", true);
+            case "f":
+                return this.readLiteral("false", false);
+            case "n":
+                return this.readLiteral("null", null);
+            default:
+                if (char === "-" || (char !== undefined && char >= "0" && char <= "9")) {
+                    return this.readNumber();
+                }
+                return this.fail(char === undefined ? "unexpected end of input" : `unexpected '${char}'`);
+        }
+    }
+    readObject() {
+        this.index += 1; // '{'
+        const object = {};
+        this.skipWhitespace();
+        if (this.text[this.index] === "}") {
+            this.index += 1;
+            return object;
+        }
+        for (;;) {
+            this.skipWhitespace();
+            if (this.text[this.index] !== '"') {
+                this.fail("expected a key");
+            }
+            const key = this.readString();
+            this.skipWhitespace();
+            if (this.text[this.index] !== ":") {
+                this.fail(`expected ':' after key '${key}'`);
+            }
+            this.index += 1;
+            const value = this.readValue();
+            // `defineProperty`, not assignment: a wire body carrying a `__proto__` key must
+            // become an ordinary own property, never a prototype swap. This is what
+            // `JSON.parse` does, and it is not optional for a body an attacker may shape.
+            Object.defineProperty(object, key, {
+                value,
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            });
+            this.skipWhitespace();
+            const next = this.text[this.index];
+            if (next === ",") {
+                this.index += 1;
+                continue;
+            }
+            if (next === "}") {
+                this.index += 1;
+                return object;
+            }
+            this.fail("expected ',' or '}'");
+        }
+    }
+    readArray() {
+        this.index += 1; // '['
+        const array = [];
+        this.skipWhitespace();
+        if (this.text[this.index] === "]") {
+            this.index += 1;
+            return array;
+        }
+        for (;;) {
+            array.push(this.readValue());
+            this.skipWhitespace();
+            const next = this.text[this.index];
+            if (next === ",") {
+                this.index += 1;
+                continue;
+            }
+            if (next === "]") {
+                this.index += 1;
+                return array;
+            }
+            this.fail("expected ',' or ']'");
+        }
+    }
+    readString() {
+        const start = this.index;
+        this.index += 1; // opening quote
+        for (;;) {
+            const char = this.text[this.index];
+            if (char === undefined) {
+                this.fail("unterminated string");
+            }
+            if (char === '"') {
+                this.index += 1;
+                // The span is a valid JSON string literal by construction, so the platform
+                // decoder is both correct and faster than re-implementing escape handling.
+                return JSON.parse(this.text.slice(start, this.index));
+            }
+            // A backslash escapes the next character, including another backslash. Skipping
+            // two keeps `"\\"` from being read as an unterminated string.
+            this.index += char === "\\" ? 2 : 1;
+        }
+    }
+    /**
+     * Reads a JSON number.
+     *
+     * The whole point of this module: a literal with no fraction and no exponent is an
+     * **integer**, and becomes a `bigint` — exactly, at any magnitude. Anything else is
+     * a `number`.
+     */
+    readNumber() {
+        const start = this.index;
+        while (this.index < this.text.length) {
+            const char = this.text[this.index];
+            if (STRUCTURAL.has(char)) {
+                break;
+            }
+            this.index += 1;
+        }
+        const literal = this.text.slice(start, this.index);
+        if (/^-?(?:0|[1-9][0-9]*)$/.test(literal)) {
+            return BigInt(literal);
+        }
+        if (/^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][-+]?[0-9]+)?$/.test(literal)) {
+            return Number(literal);
+        }
+        return this.fail(`'${literal}' is not a number`);
+    }
+    readLiteral(literal, value) {
+        if (this.text.startsWith(literal, this.index)) {
+            this.index += literal.length;
+            return value;
+        }
+        return this.fail(`expected '${literal}'`);
+    }
+    skipWhitespace() {
+        while (this.index < this.text.length) {
+            const char = this.text[this.index];
+            if (char !== " " && char !== "\t" && char !== "\n" && char !== "\r") {
+                return;
+            }
+            this.index += 1;
+        }
+    }
+    fail(reason) {
+        throw new SyntaxError(`${reason} at position ${this.index}`);
+    }
+}
+/**
+ * Parses JSON, decoding every integer as a `bigint` so a 128-bit money value
+ * survives the trip.
+ *
+ * A drop-in replacement for `JSON.parse` in this client, and a pure function: same
+ * text, same value, no I/O.
+ *
+ * @param text - The JSON document.
+ * @returns The decoded value: objects, arrays, strings, booleans, `null`, `bigint`
+ *   for integers, and `number` for fractional or exponent literals.
+ * @throws {SyntaxError} If `text` is not one well-formed JSON document.
+ */
+export function parseJson(text) {
+    return new JsonReader(text).read();
+}
+/**
+ * Serializes to JSON, writing a `bigint` as a **bare integer literal** — the wire
+ * form the ledger reads — rather than as a quoted string (`JSON.stringify` refuses
+ * `bigint` outright).
+ *
+ * Mirrors `JSON.stringify` otherwise: `toJSON()` is honoured, `undefined` object
+ * values and function values are dropped, and `undefined` array elements become
+ * `null`.
+ *
+ * @param value - The value to serialize.
+ * @returns The JSON text.
+ * @throws {TypeError} On a circular structure.
+ */
+export function stringifyJson(value) {
+    return write(value, new Set());
+}
+function write(value, seen) {
+    if (typeof value === "bigint") {
+        // The reason this module exists: a bare integer literal, at full precision.
+        return value.toString();
+    }
+    if (value === null) {
+        return "null";
+    }
+    if (typeof value === "object") {
+        const source = value;
+        if (typeof source.toJSON === "function") {
+            return write(source.toJSON(), seen);
+        }
+        if (seen.has(value)) {
+            throw new TypeError("cannot serialize a circular structure to JSON");
+        }
+        seen.add(value);
+        const json = Array.isArray(value)
+            ? `[${value.map((element) => writeOrNull(element, seen)).join(",")}]`
+            : `{${writeEntries(value, seen).join(",")}}`;
+        seen.delete(value);
+        return json;
+    }
+    // Strings, numbers, and booleans are already spelled correctly by the platform.
+    return JSON.stringify(value) ?? "null";
+}
+/** An array hole or an `undefined` element is `null`, as in `JSON.stringify`. */
+function writeOrNull(value, seen) {
+    return value === undefined || typeof value === "function" ? "null" : write(value, seen);
+}
+/** An `undefined` or function-valued key is omitted, as in `JSON.stringify`. */
+function writeEntries(object, seen) {
+    return Object.entries(object).flatMap(([key, value]) => value === undefined || typeof value === "function"
+        ? []
+        : [`${JSON.stringify(key)}:${write(value, seen)}`]);
+}
+//# sourceMappingURL=json.js.map

package/dist/json.js.map

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

package/dist/key.d.ts

@@ -0,0 +1,64 @@
+/**
+ * A caller-chosen payment key, and the transaction id it stands for.
+ *
+ * @packageDocumentation
+ */
+/** The longest key accepted, in bytes. */
+export declare const MAX_PAYMENT_KEY_BYTES = 255;
+/**
+ * The namespace keyed transaction ids are UUID v5s under. Fixed forever: the Rust SDK
+ * derives the same id from the same key, and `spec/fixtures/authorize-key-v1.json` pins
+ * both.
+ */
+export declare const AUTHORIZE_NAMESPACE = "107dbcd8-d7e9-4ddd-8e42-34da893200e4";
+/**
+ * Why `key` is not an acceptable payment key, or `undefined`. Pure; the same rules
+ * as the Rust SDK's `PaymentKey::new`.
+ *
+ * One to {@link MAX_PAYMENT_KEY_BYTES} bytes of visible ASCII (`!` through `~`): no
+ * space, no control character, nothing a copy through a log or a shell could silently
+ * change.
+ */
+export declare function paymentKeyProblem(key: string): string | undefined;
+/**
+ * A payment key you chose, and when you first issued it.
+ *
+ * The key names the transaction; the issue time takes no part in the id. It tells the
+ * client how old the key is, because the service remembers a transaction id only for
+ * its advertised idempotency window, and a key re-sent after that could be applied as a
+ * new payment. So persist `issuedAtMs` with the key, and pass the same value every time
+ * you rebuild the payment from your records, never the time of the rebuild. A payment
+ * whose key is older than the window is reconciled by looking the transaction up, not
+ * re-driven.
+ *
+ * Build one with {@link paymentKey}.
+ */
+export interface PaymentKey {
+    /** The key: 1 to {@link MAX_PAYMENT_KEY_BYTES} bytes of visible ASCII. */
+    readonly key: string;
+    /** When the key was first issued, in milliseconds since the Unix epoch. */
+    readonly issuedAtMs: number;
+}
+/**
+ * Validates a payment key and the time it was first issued. Pure; the same rules as the
+ * Rust SDK's `PaymentKey::new`.
+ *
+ * ```ts
+ * import { paymentKey } from "@axorum/client";
+ *
+ * // `order.approvedAtMs` is stored with the order, so a restart passes the same value.
+ * const key = paymentKey("order-8812", order.approvedAtMs);
+ * ```
+ *
+ * @throws {InvalidPaymentError} If the key is empty, over
+ *   {@link MAX_PAYMENT_KEY_BYTES} bytes or not visible ASCII, or `issuedAtMs` is not a
+ *   finite number.
+ */
+export declare function paymentKey(key: string, issuedAtMs: number): PaymentKey;
+/**
+ * The transaction id `agentUri` paying under `key` stands for:
+ * `UUIDv5(AUTHORIZE_NAMESPACE, agentUri || 0x1F || key)` as a `txn_` TypeID. Async only
+ * because it hashes with WebCrypto. The key must already be valid.
+ */
+export declare function keyedTransaction(agentUri: string, key: string): Promise<string>;
+//# sourceMappingURL=key.d.ts.map

package/dist/key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,0CAA0C;AAC1C,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,yCAAyC,CAAC;AAE1E;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAYjE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU,CAWtE;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAErF"}