@axorum/client 0.0.0-stage → 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,245 @@
+/**
+ * The wire contract, given names.
+ *
+ * Every type here is an alias into `src/generated/agent-plane.ts`, which is generated
+ * from the frozen OpenAPI spec. The aliases exist so that a caller writes
+ * `IntentEnvelope` rather than `components["schemas"]["IntentEnvelope"]`; they add no
+ * shape of their own, and they **rename nothing** — `snake_case` on the wire is
+ * `snake_case` here. A second vocabulary would be a second thing to keep in sync, and
+ * the frozen contract is the one that wins.
+ *
+ * @packageDocumentation
+ */
+import type { components } from "./generated/agent-plane.js";
+/**
+ * What an agent submits: identity (`agent` + `attestation`), the accounting view
+ * (`entries`), the deontic view (`action`), the policy pin, external `evidence`, and
+ * the agent's `justification`.
+ *
+ * Build one with {@link pinIntent} from an {@link IntentDraft} rather than by hand —
+ * the `policy` pin is a claim about the *service's* state, not the agent's, and
+ * getting it wrong is a `409`.
+ *
+ * The contract's type with `minted_at_ms` required: every envelope carries the time its transaction id was minted, so the service ages the
+ * key on its own clock; {@link pinIntent} stamps it, and {@link AxorumClient.submitIntent}
+ * refuses an envelope without it.
+ */
+export type IntentEnvelope = components["schemas"]["IntentEnvelope"] & {
+    minted_at_ms: bigint;
+};
+/**
+ * What the ledger answers with — the outcome typology.
+ *
+ * **A refusal lives in here, not in an error.** If the policy in force forbids the
+ * action, this arrives on a `200` with `posted: false` and
+ * `verdict: "ForbiddenRejected"`: the intent reached the commit point, was judged, and
+ * the refusal was *recorded*. That record is the product. Branch on
+ * `posted`/`verdict`, never on a status code.
+ */
+export type AgentOutcome = components["schemas"]["AgentOutcome"];
+/**
+ * The service's idempotency window (contract 5.0.0): how long a committed transaction
+ * id answers a retry with the original outcome.
+ *
+ * Not a document in the contract: the service states it in three response headers on
+ * `GET /api/openapi.json` ({@link IDEMPOTENCY_WINDOW_HEADERS}), and
+ * {@link AxorumClient.idempotencyWindow} reads them into this shape.
+ *
+ * `window_ticks` is the window in server ticks; `window_seconds` its wall-clock length,
+ * rounded down, or `null` when the heartbeat is disabled; `capacity` how many ids the
+ * service holds before it refuses new commits `507`. Every figure is a `bigint`, because
+ * the service may state any count up to `2^64 - 1`. Past the window a resubmission is
+ * refused `409 stale_idempotency_key`. See {@link ensureFresh}.
+ */
+export interface IdempotencyWindow {
+    /** How many committed ids the index holds before it refuses new commits `507`. */
+    readonly capacity: bigint;
+    /** The window's wall-clock length in whole seconds, or `null` when the heartbeat is disabled. */
+    readonly window_seconds: bigint | null;
+    /** The window in server ticks. */
+    readonly window_ticks: bigint;
+}
+/**
+ * Why a refused intent was refused (contract 5.0.0): present on an
+ * {@link AgentOutcome} exactly when `posted` is `false`, absent otherwise.
+ *
+ * A stable `code` (an open vocabulary, see {@link REFUSAL_CODES}), the `rule` behind
+ * it when there is one, and a plain-English `explanation` that says what to do next.
+ * A `forbidden_by_rule` refusal also carries the guard `conditions` that held and the
+ * exact `figures` they compared; any refusal may carry the norms their own exceptions
+ * `set_aside`. Every list is absent when empty. Branch on `code`; for policy-specific
+ * reasons, branch on `rule.name`, which you declared.
+ *
+ * Not signed: the receipt signs the provenance and the policy hash, and the refusal is
+ * derived from them. Read it with {@link refusalOf}.
+ */
+export type Refusal = components["schemas"]["Refusal"];
+/**
+ * The rule that refused an intent: its `id`, and its `name` as declared in the policy
+ * that judged the intent (absent when the service could not read that policy's source).
+ */
+export type RefusingRule = components["schemas"]["RefusingRule"];
+/**
+ * One clause of a refusing forbid's guard and the literal that satisfied it. `kind` is
+ * an open vocabulary (see {@link CONDITION_KINDS}); `figure` indexes
+ * {@link Refusal}`.figures`, read it with {@link figureOf}.
+ */
+export type Condition = components["schemas"]["Condition"];
+/**
+ * One exact comparison a refusing forbid's guard made. `current`, `attempted`,
+ * `compared`, `limit` and `headroom` are **`bigint`** minor units of `currency`, exact
+ * at any magnitude (see {@link Amount}). `headroom` is the largest `attempted` that
+ * would have cleared this comparison; zero or negative means no amount does.
+ *
+ * `current`, `compared` and `headroom` are `undefined` when the service **withheld**
+ * them: the wire omits the key, never `null` or `0`, so `undefined` means "not
+ * disclosed", never zero. Test with `=== undefined` rather than truthiness, which
+ * would also swallow a real `0n`. `attempted`, `limit` and `held` are always present.
+ *
+ * The service discloses them only on the acting party's own `per_party` cell and on
+ * the agent's own mandate (the one charged or, on a refusal, the bound mandate the cap
+ * was evaluated against). It withholds them on a `global` cap, on every other register
+ * scope (a named counterparty keeps its `display_name`), on another party's mandate,
+ * and on a non-spend intent's own mandate.
+ */
+export type Figure = components["schemas"]["Figure"];
+/** The window a register figure accumulates over: `kind`, and `ticks` unless unbounded. */
+export type FigureWindow = components["schemas"]["FigureWindow"];
+/** The counterparty cell a counterparty-scoped register read resolved to. */
+export type FigureCounterparty = components["schemas"]["FigureCounterparty"];
+/** A norm its own `unless` clause set aside for this intent. */
+export type SetAside = components["schemas"]["SetAside"];
+/**
+ * A detached-payload signature envelope — `axorum.evidence.v0` (contract 4.1.0).
+ *
+ * The base64 `payload` carries the **exact** signed bytes (for a receipt: the
+ * compact `axorum.receipt.v0` JSON), so verification needs nothing but this
+ * envelope and the deployment's published key list
+ * (`GET /api/verification-keys.json`) — offline, in any stack:
+ * `crypto.verify(null, message, spkiPem, signature)` in Node, where the signed
+ * message is `"axorum.evidence.v0\n" + kind + "\n" + deployment + "\n" +
+ * sha256(payload)`. See `spec/evidence-signing.md` and the committed JSON
+ * Schemas under `spec/schemas/`.
+ */
+export type Envelope = components["schemas"]["Envelope"];
+/** The five-member deontic verdict. `"ForbiddenRejected"` is the recorded refusal. */
+export type Verdict = components["schemas"]["Verdict"];
+/** A single journal leg: a positive amount posted to one side of one account. */
+export type Entry = components["schemas"]["Entry"];
+/** Whether a journal leg is a debit or a credit. */
+export type Side = components["schemas"]["Side"];
+/**
+ * A monetary amount in integer minor units.
+ *
+ * `minor` is a **`bigint`**: the ledger's minor units are 128-bit integers, and a
+ * JavaScript `number` would truncate large ones silently. Write `{ minor: 50_000n,
+ * currency: "USD" }`.
+ */
+export type Amount = components["schemas"]["Amount"];
+/** A concrete action reference with its argument values bound by parameter name. */
+export type ActionTerm = components["schemas"]["ActionTerm"];
+/** A typed literal in the deontic AST: an externally tagged union, e.g. `{ Int: 3n }`. */
+export type Value = components["schemas"]["Value"];
+/** A live obligation instance — a duty bound to an actor at a tick. */
+export type ObligationInstance = components["schemas"]["ObligationInstance"];
+/** The obligation lifecycle state machine. */
+export type ObligationState = components["schemas"]["ObligationState"];
+/** The obligation state changes recorded by one evaluation. */
+export type ObligationOutcomes = components["schemas"]["ObligationOutcomes"];
+/**
+ * The self-contained audit record accompanying every verdict.
+ *
+ * `semantics` is optional for pre-versioning records. When present, it names the
+ * evaluation law, not the outcome itself; `master_data` is likewise omitted when
+ * the governing policy did not consult replicated reference data.
+ */
+export type Provenance = components["schemas"]["Provenance"];
+/**
+ * The provenance carried by a committed transaction's outcome.
+ *
+ * An externally tagged union with a twist: `Recorded` is an object
+ * (`{ Recorded: {…} }`) but `Archived` is the bare string `"Archived"`. Both forms
+ * occur; narrow with `typeof provenance === "string"`.
+ */
+export type OutcomeProvenance = components["schemas"]["OutcomeProvenance"];
+/** The ERP source-version markers a verdict was decided under. */
+export type MasterDataBasis = components["schemas"]["MasterDataBasis"];
+/**
+ * The evaluation-semantics version carried by stamped provenance.
+ *
+ * The generator types every OpenAPI `integer` as `bigint`, because the same wire
+ * convention protects 128-bit monetary values elsewhere in the contract.
+ */
+export type SemanticsVersion = bigint;
+/** A replicated master-data set a policy can test membership in. */
+export type ReferenceSet = components["schemas"]["ReferenceSet"];
+/** The `GET /api/v1/obligations` response: the duties an actor owes. */
+export type ObligationsResponse = components["schemas"]["ObligationsResponse"];
+/**
+ * The `GET /api/v1/accounts/{id}/balance` response.
+ *
+ * `balance` is a **`bigint`** — 128-bit minor units. See {@link Amount}.
+ */
+export type BalanceResponse = components["schemas"]["BalanceResponse"];
+/** The `GET /api/v1/policies/active` response. `policy` is `null` when none is in force. */
+export type ActivePolicyResponse = components["schemas"]["ActivePolicyResponse"];
+/**
+ * One declared currency: its code, how many decimal digits one minor unit is worth, and a
+ * `warning` when the policy in force refuses some action in it.
+ */
+export type DeclaredCurrency = components["schemas"]["DeclaredCurrency"];
+/**
+ * A declared currency the policy in force refuses some action in: every intent on one of
+ * `actions` in that currency is refused at commit (`422`, `cause: "currency_mismatch"`),
+ * whatever its parameters. An agent cannot change that. Pay in a currency with no warning,
+ * or hand `remedy` to a human operator. `code` is an open vocabulary; `"DSL3002"` today.
+ */
+export type CurrencyWarning = components["schemas"]["CurrencyWarning"];
+/**
+ * The `GET /api/v1/currencies` response: every declared currency, in canonical (sorted)
+ * code order. An empty list means nothing is declared.
+ */
+export type DeclaredCurrencies = components["schemas"]["DeclaredCurrencies"];
+/**
+ * A single **usage move**: a signed delta against one usage balance's counter.
+ *
+ * An intent carries up to three of them — `consume_usage`, `meter_usage`, `bill_usage` —
+ * and the three are judged **together** against the combined post-state, so one intent may
+ * consume, meter, and bill the same amount. A positive `amount` recognizes fresh
+ * consumption/metering/billing; a negative one is a correction that unwinds it.
+ *
+ * `amount.minor` is a **`bigint`**, like every other money figure. See {@link Amount}.
+ */
+export type UsageMove = components["schemas"]["UsageMove"];
+/**
+ * The `GET /api/v1/usages/{id}` response: one usage balance's three running totals.
+ *
+ * Every counter — `consumed`, `metered`, `billed`, and the derived `unmetered`/`unbilled`
+ * headrooms — is a **`bigint`**. It matters more here than anywhere else on the agent
+ * plane: `consumed` takes no ceiling, so a balance can lawfully outgrow `u64`, and a
+ * JavaScript `number` would truncate it silently.
+ *
+ * `text` is the balance narrated in compliance English with exact figures — the sentence to
+ * show a human, rather than a rendering of the counters you assemble yourself.
+ */
+export type UsageBalanceReport = components["schemas"]["UsageBalanceReport"];
+/**
+ * The stored ledger record for one transaction — **opaque in this version of the
+ * contract**, and typed as such.
+ *
+ * The record's own shape is not yet frozen, so the contract declines to publish a
+ * guess at it. What is guaranteed today: a committed transaction's record carries a
+ * `posted` boolean, and a recorded refusal appears with `posted: false`.
+ */
+export type TransactionRecord = components["schemas"]["TransactionRecord"];
+/**
+ * The structured error body every non-2xx agent-plane response carries.
+ *
+ * `error` is a stable `snake_case` code to branch on; `message` is human prose; the
+ * remaining fields are the **load-bearing extras** — `pinned`/`active` (without which
+ * no client could re-pin) and `primary_api_addr` (without which none could tell which
+ * replica holds the primary). This client parses them all and hands them to you on a typed
+ * {@link AxorumError}; it never flattens them away.
+ */
+export type ErrorBody = components["schemas"]["ApiError"];
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,14 @@
+/**
+ * The wire contract, given names.
+ *
+ * Every type here is an alias into `src/generated/agent-plane.ts`, which is generated
+ * from the frozen OpenAPI spec. The aliases exist so that a caller writes
+ * `IntentEnvelope` rather than `components["schemas"]["IntentEnvelope"]`; they add no
+ * shape of their own, and they **rename nothing** — `snake_case` on the wire is
+ * `snake_case` here. A second vocabulary would be a second thing to keep in sync, and
+ * the frozen contract is the one that wins.
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@axorum/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "The official TypeScript client for the Axorum agent plane — submit intents, read ledger state, and recover from a stale policy pin.",
+  "license": "Apache-2.0",
+  "author": "Roland Rodriguez <roland@axorum.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AxorumHQ/axorum.git",
+    "directory": "clients/typescript"
+  },
+  "homepage": "https://github.com/AxorumHQ/axorum/tree/main/clients/typescript#readme",
+  "bugs": "https://github.com/AxorumHQ/axorum/issues",
+  "keywords": [
+    "axorum",
+    "agent",
+    "agent-plane",
+    "ledger",
+    "payments",
+    "policy",
+    "sdk",
+    "client"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "openapi-typescript": "^7.5.2",
+    "typescript": "^5.7.2",
+    "undici": "^7.28.0",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "generate": "node scripts/generate.mjs",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc --project tsconfig.build.json",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit",
+    "test:conformance": "vitest run test/conformance"
+  }
 }