@axorum/client 0.0.0-stage → 1.0.0

package/dist/key.js

@@ -0,0 +1,71 @@
+/**
+ * A caller-chosen payment key, and the transaction id it stands for.
+ *
+ * @packageDocumentation
+ */
+import { uuidV5 } from "./chart.js";
+import { InvalidPaymentError } from "./errors.js";
+import { TRANSACTION_PREFIX, encodeSuffix } from "./typeid.js";
+/** The longest key accepted, in bytes. */
+export 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 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 function paymentKeyProblem(key) {
+    if (key.length === 0) {
+        return "the payment key is empty; use the identifier your own records keep for this payment, such as an order number";
+    }
+    const bytes = new TextEncoder().encode(key).length;
+    if (bytes > MAX_PAYMENT_KEY_BYTES) {
+        return `the payment key is ${bytes} bytes, over the ${MAX_PAYMENT_KEY_BYTES}-byte limit; use a shorter identifier`;
+    }
+    if (!/^[\x21-\x7e]+$/.test(key)) {
+        return "the payment key holds a space, a control character or non-ASCII; use visible ASCII only";
+    }
+    return undefined;
+}
+/**
+ * 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 function paymentKey(key, issuedAtMs) {
+    const problem = paymentKeyProblem(key);
+    if (problem !== undefined) {
+        throw new InvalidPaymentError(problem);
+    }
+    if (!Number.isFinite(issuedAtMs)) {
+        throw new InvalidPaymentError(`the payment key's issue time is ${issuedAtMs}; pass the milliseconds since the Unix epoch your records keep for it`);
+    }
+    return Object.freeze({ key, issuedAtMs });
+}
+/**
+ * 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 async function keyedTransaction(agentUri, key) {
+    return `${TRANSACTION_PREFIX}_${encodeSuffix(await uuidV5(AUTHORIZE_NAMESPACE, `${agentUri}\u001f${key}`))}`;
+}
+//# sourceMappingURL=key.js.map

package/dist/key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.js","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE/D,0CAA0C;AAC1C,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAEzC;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,sCAAsC,CAAC;AAE1E;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,8GAA8G,CAAC;IACxH,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,IAAI,KAAK,GAAG,qBAAqB,EAAE,CAAC;QAClC,OAAO,sBAAsB,KAAK,oBAAoB,qBAAqB,uCAAuC,CAAC;IACrH,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAChC,OAAO,yFAAyF,CAAC;IACnG,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAsBD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,UAAkB;IACxD,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,mBAAmB,CAC3B,mCAAmC,UAAU,uEAAuE,CACrH,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,QAAgB,EAAE,GAAW;IAClE,OAAO,GAAG,kBAAkB,IAAI,YAAY,CAAC,MAAM,MAAM,CAAC,mBAAmB,EAAE,GAAG,QAAQ,SAAS,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC;AAC/G,CAAC"}

package/dist/payment.d.ts

@@ -0,0 +1,172 @@
+/**
+ * What a one-call `authorize` pays, and the pure plan that turns it into an intent.
+ *
+ * @packageDocumentation
+ */
+import { IdempotencyKey } from "./idempotency.js";
+import type { IntentDraft } from "./intent.js";
+import { type PaymentKey } from "./key.js";
+import type { Amount } from "./types.js";
+/** The longest payee accepted, in UTF-8 bytes. */
+export declare const MAX_PAYEE_BYTES = 256;
+/** What you describe when you create a {@link Payment}. */
+export interface PaymentInit {
+    /** How much, in integer minor units. Must be positive. */
+    amount: Amount;
+    /**
+     * Who is paid, as your policy's approved-counterparty registry names them: a merchant
+     * host such as `api.openai.com`, or an id you imported.
+     */
+    payee: string;
+    /**
+     * A UUID v7 transaction id you already hold (`txn_…`), to re-drive a payment after a
+     * crash; its mint time is the one the id carries. Leave it out and a fresh UUID v7 id
+     * is minted, once, now. An id of any other version carries no mint time: rebuild it
+     * with {@link resumePayment} and the time you persisted, or a keyed payment with
+     * {@link keyedPayment}.
+     */
+    transaction?: string;
+    /**
+     * The agent's stated reason. Defaults to `purchase of <minor> <currency> from <payee>`.
+     *
+     * It is not part of what the transaction id commits to: a re-drive that rewords it
+     * replays the original answer, which carries the **original** justification's hash.
+     * `justificationMatches` tells the two apart.
+     */
+    justification?: string;
+    /** Lowercase-hex SHA-256 digests of evidence the payment references. */
+    evidence?: readonly string[];
+}
+/**
+ * Where a payment's idempotency key came from.
+ *
+ * - `minted`: {@link payment} minted it in this process, so it was never sent before.
+ * - `supplied`: a UUID v7 id you passed to {@link payment}, stamped with the time it
+ *   carries.
+ * - `keyed`: derived from your {@link PaymentKey} ({@link keyedPayment}).
+ * - `resumed`: read back from your records ({@link resumePayment}).
+ *
+ * Every key but a `minted` one may have been sent before, so `authorize` sends it only
+ * while the service's idempotency window still covers it.
+ */
+export type PaymentOrigin = "minted" | "supplied" | "keyed" | "resumed";
+/**
+ * A validated payment with its transaction id already minted.
+ *
+ * Minting at creation, before any I/O, is what makes a re-drive safe: hand the **same**
+ * `Payment` to `authorize` again after an indeterminate failure and a payment that did
+ * commit replays its answer instead of paying twice. A process that may restart persists
+ * {@link Payment.idempotencyKey} (the id and its mint time) and rebuilds the payment
+ * with {@link resumePayment}. Build one with {@link payment}.
+ */
+export interface Payment {
+    readonly amount: Amount;
+    readonly payee: string;
+    /** The transaction id: the idempotency key of every send. */
+    readonly transaction: string;
+    /**
+     * The transaction id and when it was first minted. Every send carries the mint time
+     * as `minted_at_ms`; persist both to resume the payment after a restart.
+     */
+    readonly idempotencyKey: IdempotencyKey;
+    readonly justification: string;
+    readonly evidence: readonly string[];
+    /** Where {@link Payment.idempotencyKey} came from. */
+    readonly origin: PaymentOrigin;
+    /**
+     * The agent URI the transaction id was derived for, when it came from a payment
+     * key ({@link keyedPayment}); `undefined` otherwise.
+     */
+    readonly keyedFor: string | undefined;
+}
+/**
+ * Validates a payment and mints its transaction id.
+ *
+ * ```ts
+ * import { payment } from "@axorum/client";
+ *
+ * const lunch = payment({ amount: { minor: 1_250n, currency: "USD" }, payee: "api.openai.com" });
+ * console.log(lunch.transaction); // txn_…, minted once, now
+ * ```
+ *
+ * @throws {InvalidPaymentError} If the amount is not positive, the payee is empty, too
+ *   long, or carries a control character or surrounding whitespace, or `transaction` is
+ *   not a UUID v7 id.
+ */
+export declare function payment(init: PaymentInit): Payment;
+/**
+ * Rebuilds a payment from the idempotency key you persisted for it, so a process that
+ * restarted re-drives the **same** transaction: if an earlier send committed, its answer
+ * comes back as a replay. The key keeps its original mint time.
+ *
+ * ```ts
+ * import { IdempotencyKey, payment, resumePayment } from "@axorum/client";
+ *
+ * const lunch = payment({ amount: { minor: 1_250n, currency: "USD" }, payee: "api.openai.com" });
+ * const { transaction, mintedAtMs } = lunch.idempotencyKey; // persist both
+ * // … after a restart:
+ * const again = resumePayment(new IdempotencyKey(transaction, mintedAtMs), {
+ *   amount: { minor: 1_250n, currency: "USD" },
+ *   payee: "api.openai.com",
+ * });
+ * ```
+ *
+ * `authorize` sends a resumed payment only while the service's idempotency window
+ * still covers its key; otherwise it fails with `stale_key`, and nothing is sent.
+ *
+ * @throws {InvalidPaymentError} If the payment itself is invalid.
+ */
+export declare function resumePayment(key: IdempotencyKey, init: Omit<PaymentInit, "transaction">): Payment;
+/**
+ * Validates a payment whose transaction id comes from **your** key (an order number, a
+ * job id) rather than a fresh mint, so a process that lost the id can re-drive the
+ * payment from its own records.
+ *
+ * The id is `UUIDv5(AUTHORIZE_NAMESPACE, agent.uri || 0x1F || key)`, the same as the
+ * Rust SDK's `Payment::with_key`: the same agent and key always name the same
+ * transaction. A re-drive replays; a **different** payment under the same key is
+ * refused with `transaction_reused`. The key's issue time becomes the payment's mint
+ * time, so it must be the time persisted with the key.
+ *
+ * `authorize` sends a keyed payment only for the agent it was keyed for. Otherwise it
+ * fails with `keyed_for_another_agent`, and nothing is sent; so does one whose key the
+ * service's idempotency window no longer covers (`stale_key`).
+ *
+ * ```ts
+ * import { keyedPayment, paymentKey } from "@axorum/client";
+ *
+ * const order = await keyedPayment(buyer, paymentKey("order-8812", approvedAtMs), {
+ *   amount: { minor: 1_250n, currency: "USD" },
+ *   payee: "api.openai.com",
+ * });
+ * ```
+ *
+ * @throws {InvalidPaymentError} If the payment itself is invalid (the key was checked
+ *   by {@link paymentKey}).
+ */
+export declare function keyedPayment(agent: {
+    readonly uri: string;
+}, key: PaymentKey, init: Omit<PaymentInit, "transaction">): Promise<Payment>;
+/**
+ * Why `payee` is not acceptable, or `undefined` if it is. Pure.
+ *
+ * The same rules as the Rust SDK's `Payee::new`.
+ */
+export declare function payeeProblem(payee: string): string | undefined;
+/**
+ * The intent a payment proposes, less the policy pin. Pure apart from hashing the
+ * default chart's account ids.
+ *
+ * `purchase(amount, payee)` with the payee bound as text, debiting the default chart's
+ * spend account and crediting its payable account in the amount's currency.
+ */
+export declare function planPayment(agent: string, attestation: string, pay: Payment): Promise<IntentDraft & {
+    transaction: string;
+    minted_at_ms: bigint;
+}>;
+/**
+ * Mints a transaction id from a UUID v7: time-ordered, so ids sort by when their payment
+ * was created.
+ */
+export declare function newPaymentId(): string;
+//# sourceMappingURL=payment.d.ts.map

package/dist/payment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment.d.ts","sourceRoot":"","sources":["../src/payment.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,cAAc,EAAgB,MAAM,kBAAkB,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,UAAU,CAAC;AAE7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,kDAAkD;AAClD,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;AAExE;;;;;;;;GAQG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAalD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,GAAG,OAAO,CAElG;AAiDD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAC/B,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,GACrC,OAAO,CAAC,OAAO,CAAC,CAIlB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAe9D;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,WAAW,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,CAiBtE;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC"}

package/dist/payment.js

@@ -0,0 +1,178 @@
+/**
+ * What a one-call `authorize` pays, and the pure plan that turns it into an intent.
+ *
+ * @packageDocumentation
+ */
+import { DEFAULT_CHART_V1, defaultChartLegs } from "./chart.js";
+import { InvalidPaymentError } from "./errors.js";
+import { IdempotencyKey, mintedAtWire } from "./idempotency.js";
+import { keyedTransaction } from "./key.js";
+import { newTransactionId, v7MintedAtMs } from "./typeid.js";
+/** The longest payee accepted, in UTF-8 bytes. */
+export const MAX_PAYEE_BYTES = 256;
+/**
+ * Validates a payment and mints its transaction id.
+ *
+ * ```ts
+ * import { payment } from "@axorum/client";
+ *
+ * const lunch = payment({ amount: { minor: 1_250n, currency: "USD" }, payee: "api.openai.com" });
+ * console.log(lunch.transaction); // txn_…, minted once, now
+ * ```
+ *
+ * @throws {InvalidPaymentError} If the amount is not positive, the payee is empty, too
+ *   long, or carries a control character or surrounding whitespace, or `transaction` is
+ *   not a UUID v7 id.
+ */
+export function payment(init) {
+    const valid = validated(init);
+    if (init.transaction === undefined) {
+        return build(valid, IdempotencyKey.mint(newPaymentId(), Date.now()), "minted", undefined);
+    }
+    const mintedAtMs = v7MintedAtMs(init.transaction);
+    if (mintedAtMs === undefined) {
+        throw new InvalidPaymentError(`transaction id ${init.transaction} is not a UUID v7, so it carries no mint time; rebuild a keyed ` +
+            "payment with keyedPayment, or pass the id with the mint time you persisted to resumePayment");
+    }
+    return build(valid, new IdempotencyKey(init.transaction, mintedAtMs), "supplied", undefined);
+}
+/**
+ * Rebuilds a payment from the idempotency key you persisted for it, so a process that
+ * restarted re-drives the **same** transaction: if an earlier send committed, its answer
+ * comes back as a replay. The key keeps its original mint time.
+ *
+ * ```ts
+ * import { IdempotencyKey, payment, resumePayment } from "@axorum/client";
+ *
+ * const lunch = payment({ amount: { minor: 1_250n, currency: "USD" }, payee: "api.openai.com" });
+ * const { transaction, mintedAtMs } = lunch.idempotencyKey; // persist both
+ * // … after a restart:
+ * const again = resumePayment(new IdempotencyKey(transaction, mintedAtMs), {
+ *   amount: { minor: 1_250n, currency: "USD" },
+ *   payee: "api.openai.com",
+ * });
+ * ```
+ *
+ * `authorize` sends a resumed payment only while the service's idempotency window
+ * still covers its key; otherwise it fails with `stale_key`, and nothing is sent.
+ *
+ * @throws {InvalidPaymentError} If the payment itself is invalid.
+ */
+export function resumePayment(key, init) {
+    return build(validated(init), new IdempotencyKey(key.transaction, key.mintedAtMs), "resumed", undefined);
+}
+/** A frozen payment from `valid` under `key`. Pure. */
+function build(valid, key, origin, keyedFor) {
+    return Object.freeze({
+        amount: Object.freeze({ ...valid.amount }),
+        payee: valid.payee,
+        transaction: key.transaction,
+        idempotencyKey: key,
+        justification: valid.justification,
+        evidence: Object.freeze([...valid.evidence]),
+        origin,
+        keyedFor,
+    });
+}
+/** `init` checked, with the default justification. Pure. */
+function validated(init) {
+    if (init.amount.minor <= 0n) {
+        throw new InvalidPaymentError(`the amount is ${init.amount.minor} ${init.amount.currency}; a payment moves a positive amount`);
+    }
+    const problem = payeeProblem(init.payee);
+    if (problem !== undefined) {
+        throw new InvalidPaymentError(problem);
+    }
+    return {
+        amount: init.amount,
+        payee: init.payee,
+        justification: init.justification ?? `purchase of ${init.amount.minor} ${init.amount.currency} from ${init.payee}`,
+        evidence: init.evidence ?? [],
+    };
+}
+/**
+ * Validates a payment whose transaction id comes from **your** key (an order number, a
+ * job id) rather than a fresh mint, so a process that lost the id can re-drive the
+ * payment from its own records.
+ *
+ * The id is `UUIDv5(AUTHORIZE_NAMESPACE, agent.uri || 0x1F || key)`, the same as the
+ * Rust SDK's `Payment::with_key`: the same agent and key always name the same
+ * transaction. A re-drive replays; a **different** payment under the same key is
+ * refused with `transaction_reused`. The key's issue time becomes the payment's mint
+ * time, so it must be the time persisted with the key.
+ *
+ * `authorize` sends a keyed payment only for the agent it was keyed for. Otherwise it
+ * fails with `keyed_for_another_agent`, and nothing is sent; so does one whose key the
+ * service's idempotency window no longer covers (`stale_key`).
+ *
+ * ```ts
+ * import { keyedPayment, paymentKey } from "@axorum/client";
+ *
+ * const order = await keyedPayment(buyer, paymentKey("order-8812", approvedAtMs), {
+ *   amount: { minor: 1_250n, currency: "USD" },
+ *   payee: "api.openai.com",
+ * });
+ * ```
+ *
+ * @throws {InvalidPaymentError} If the payment itself is invalid (the key was checked
+ *   by {@link paymentKey}).
+ */
+export async function keyedPayment(agent, key, init) {
+    const valid = validated(init);
+    const transaction = await keyedTransaction(agent.uri, key.key);
+    return build(valid, new IdempotencyKey(transaction, key.issuedAtMs), "keyed", agent.uri);
+}
+/**
+ * Why `payee` is not acceptable, or `undefined` if it is. Pure.
+ *
+ * The same rules as the Rust SDK's `Payee::new`.
+ */
+export function payeeProblem(payee) {
+    if (payee.length === 0) {
+        return "the payee is empty; name who is being paid, as your policy's approved-counterparty registry names them";
+    }
+    const bytes = new TextEncoder().encode(payee).length;
+    if (bytes > MAX_PAYEE_BYTES) {
+        return `the payee is ${bytes} bytes, over the ${MAX_PAYEE_BYTES}-byte limit; use a stable short identifier such as the merchant's host`;
+    }
+    if (/\p{Cc}/u.test(payee)) {
+        return "the payee contains a control character; pass the identifier alone";
+    }
+    if (payee.trim() !== payee) {
+        return "the payee starts or ends with whitespace, so it would never match a registry entry; trim it";
+    }
+    return undefined;
+}
+/**
+ * The intent a payment proposes, less the policy pin. Pure apart from hashing the
+ * default chart's account ids.
+ *
+ * `purchase(amount, payee)` with the payee bound as text, debiting the default chart's
+ * spend account and crediting its payable account in the amount's currency.
+ */
+export async function planPayment(agent, attestation, pay) {
+    return {
+        agent,
+        attestation,
+        transaction: pay.transaction,
+        minted_at_ms: mintedAtWire(pay.idempotencyKey),
+        action: {
+            action: DEFAULT_CHART_V1.action,
+            bindings: {
+                [DEFAULT_CHART_V1.amountParam]: { Amount: pay.amount },
+                [DEFAULT_CHART_V1.payeeParam]: { Text: pay.payee },
+            },
+        },
+        entries: await defaultChartLegs(pay.amount),
+        evidence: [...pay.evidence],
+        justification: pay.justification,
+    };
+}
+/**
+ * Mints a transaction id from a UUID v7: time-ordered, so ids sort by when their payment
+ * was created.
+ */
+export function newPaymentId() {
+    return newTransactionId();
+}
+//# sourceMappingURL=payment.js.map

package/dist/payment.js.map

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

package/dist/refusal.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Reading why an intent was refused (contract 5.0.0).
+ *
+ * @packageDocumentation
+ */
+import type { AgentOutcome, Condition, Figure, Refusal } from "./types.js";
+/**
+ * The refusal codes this version of the contract documents.
+ *
+ * - `forbidden_by_rule`: a forbid rule in the judging policy won and no permit overrode
+ *   it. `rule` names it.
+ * - `not_delegated`: a permit matched and its conditions held, but no delegation to the
+ *   acting agent covers it. `rule` names the highest-priority such permit.
+ * - `denied_by_default`: no rule permitted the action for this actor, so the policy's
+ *   default deny applied. No `rule`.
+ * - `reason_archived`: the refused record has been archived, so a replay cannot carry
+ *   the reason. No `rule`.
+ *
+ * An **open vocabulary**: a newer service may send a code this client has never heard
+ * of. Test with {@link isKnownRefusalCode}, and fall back to `explanation`.
+ */
+export declare const REFUSAL_CODES: readonly ["forbidden_by_rule", "not_delegated", "denied_by_default", "reason_archived"];
+/** A refusal code this version of the contract documents. See {@link REFUSAL_CODES}. */
+export type KnownRefusalCode = (typeof REFUSAL_CODES)[number];
+/** Whether `code` is one this version of the contract documents. */
+export declare function isKnownRefusalCode(code: string): code is KnownRefusalCode;
+/**
+ * What a guard literal tested, named by `Condition.kind` (contract 5.0.0). An open
+ * vocabulary, like {@link REFUSAL_CODES}.
+ */
+export declare const CONDITION_KINDS: readonly ["register_cap", "counterparty_limit", "mandate_cap", "counterparty_list", "chart_of_accounts", "posting_period", "posted_balance", "time_window", "actor", "param"];
+/** A condition kind this version of the contract documents. See {@link CONDITION_KINDS}. */
+export type KnownConditionKind = (typeof CONDITION_KINDS)[number];
+/** Whether `kind` is one this version of the contract documents. */
+export declare function isKnownConditionKind(kind: string): kind is KnownConditionKind;
+/**
+ * What a figure read, named by `Figure.source`: `register` carries `register`, `window`
+ * and `scope`; `mandate` carries `mandate` and `quantity`. An open vocabulary.
+ */
+export declare const FIGURE_SOURCES: readonly ["register", "mandate"];
+/** The comparisons `Figure.op` can name, as the policy wrote them. An open vocabulary. */
+export declare const COMPARISON_OPS: readonly ["eq", "ne", "lt", "le", "gt", "ge", "in"];
+/** The windows `Figure.window.kind` can name. An open vocabulary. */
+export declare const WINDOW_KINDS: readonly ["rolling", "calendar", "unbounded"];
+/** The partitions `Figure.scope` can name. An open vocabulary. */
+export declare const REGISTER_SCOPES: readonly ["per_party", "per_role", "per_counterparty", "per_rail", "global"];
+/** The mandate quantities `Figure.quantity` can name. An open vocabulary. */
+export declare const MANDATE_QUANTITIES: readonly ["spent", "ceiling", "remaining", "projected"];
+/** The modalities `SetAside.modality` can name. An open vocabulary. */
+export declare const MODALITIES: readonly ["permitted", "obligated", "forbidden"];
+/**
+ * The figure a condition compared, or `undefined` when the literal compared no figure
+ * (a list membership, an actor test) or the index is out of range.
+ *
+ * Every amount on a figure is a `bigint` in minor units of `currency`: exact at any
+ * magnitude, including above 2^64. `exponent` is the deployment's declared scale.
+ *
+ * ```ts
+ * const refusal = refusalOf(outcome);
+ * for (const condition of refusal?.conditions ?? []) {
+ *   const figure = figureOf(refusal!, condition);
+ *   if (figure?.headroom !== undefined && figure.headroom > 0n) {
+ *     retryWith(figure.headroom); // the largest amount that clears this condition
+ *   }
+ * }
+ * ```
+ */
+export declare function figureOf(refusal: Refusal, condition: Condition): Figure | undefined;
+/**
+ * The substrate laws a `substrate_rejected` error body can name in `law` (contract
+ * 5.0.0). Present only on a genuine law violation, never on malformed input. An open
+ * vocabulary, like {@link REFUSAL_CODES}.
+ */
+export declare const SUBSTRATE_LAWS: readonly ["conservative", "authorization_conservation", "revenue_cost_matching", "usage_balance_conservation", "period_close_roll_forward"];
+/** A substrate law this version of the contract documents. See {@link SUBSTRATE_LAWS}. */
+export type KnownSubstrateLaw = (typeof SUBSTRATE_LAWS)[number];
+/** Whether `law` is one this version of the contract documents. */
+export declare function isKnownSubstrateLaw(law: string): law is KnownSubstrateLaw;
+/**
+ * What the caller must change, named by `cause` on a `substrate_rejected` error body
+ * (contract 5.0.0). Present only when the refusal broke no law but the intent was
+ * malformed in a way the caller can fix; a body carries `law` or `cause`, never both.
+ * An open vocabulary, like {@link REFUSAL_CODES}.
+ *
+ * @example
+ * ```ts
+ * if (error.body.cause === "unknown_account") {
+ *   // provision the account, or post to one that exists
+ * }
+ * ```
+ */
+export declare const SUBSTRATE_CAUSES: readonly ["unknown_account", "account_revoked", "currency_mismatch", "non_positive_amount", "entry_count", "amount_overflow", "unknown_mandate", "mandate_revoked", "unknown_usage", "usage_not_owned", "unknown_deferral", "unknown_counterparty", "counterparty_mandate_unresolved", "undeclared_action", "missing_param", "unexpected_param", "param_type_mismatch", "period_closed", "undeclared_currency"];
+/** A cause this version of the contract documents. See {@link SUBSTRATE_CAUSES}. */
+export type KnownSubstrateCause = (typeof SUBSTRATE_CAUSES)[number];
+/** Whether `cause` is one this version of the contract documents. */
+export declare function isKnownSubstrateCause(cause: string): cause is KnownSubstrateCause;
+/**
+ * Why `outcome` was refused, or `undefined` if it posted.
+ *
+ * Branch on `code`; for policy-specific reasons, branch on `rule.name`, which you
+ * declared. Show `explanation` to a human: it names the rule and says what to do next.
+ *
+ * `undefined` on a refused outcome means the service predates contract 5.0.0 and sent
+ * no reason; `posted: false` is still the refusal.
+ *
+ * The refusal is **not signed**. The receipt signs the provenance (whose `winning` is
+ * the rule id) and the policy hash; the refusal is derived from those, so a verifier
+ * recomputes it from signed facts rather than trusting these bytes.
+ *
+ * ```ts
+ * const outcome = await axorum.submitPinned(draft);
+ * const refusal = refusalOf(outcome);
+ * if (refusal?.code === "forbidden_by_rule" && refusal.rule?.name === "no_unapproved_vendors") {
+ *   await askForVendorApproval();
+ * } else if (refusal) {
+ *   console.log(refusal.explanation);
+ * }
+ * ```
+ */
+export declare function refusalOf(outcome: AgentOutcome): Refusal | undefined;
+//# sourceMappingURL=refusal.d.ts.map

package/dist/refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.d.ts","sourceRoot":"","sources":["../src/refusal.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE3E;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,yFAKhB,CAAC;AAEX,wFAAwF;AACxF,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,gBAAgB,CAEzE;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,+KAWlB,CAAC;AAEX,4FAA4F;AAC5F,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,kBAAkB,CAE7E;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,kCAAmC,CAAC;AAE/D,0FAA0F;AAC1F,eAAO,MAAM,cAAc,qDAAsD,CAAC;AAElF,qEAAqE;AACrE,eAAO,MAAM,YAAY,+CAAgD,CAAC;AAE1E,kEAAkE;AAClE,eAAO,MAAM,eAAe,8EAMlB,CAAC;AAEX,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,yDAA0D,CAAC;AAE1F,uEAAuE;AACvE,eAAO,MAAM,UAAU,kDAAmD,CAAC;AAE3E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAMnF;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,6IAMjB,CAAC;AAEX,0FAA0F;AAC1F,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,iBAAiB,CAEzE;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,iZAoBnB,CAAC;AAEX,oFAAoF;AACpF,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,qEAAqE;AACrE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,mBAAmB,CAEjF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,GAAG,SAAS,CAEpE"}