@zarel-ai/sdk 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zarel AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,412 @@
+# @zarel-ai/sdk
+
+TypeScript SDK for the [Zarel](https://zarel.ia) API.
+
+## Installation
+
+```bash
+npm install @zarel-ai/sdk
+```
+
+## Quick Start
+
+`@zarel-ai/sdk` exposes a single `Zarel` client with two explicit plane
+namespaces — `client.runtime.*` (records, tools, conversation, flows, traces,
+…) and `client.contract.*` (spec, entities, roles, authorization,
+capabilities, schemas, processModel, runtime config, …). Each plane targets its own host and accepts an
+independent JWT.
+
+```typescript
+import { Zarel } from '@zarel-ai/sdk';
+
+const zarel = new Zarel({
+  tenant: 'fintech_credit',
+  runtimeToken: process.env.ZAREL_RUNTIME_TOKEN!,    // JWT class: tenant
+  contractToken: process.env.ZAREL_CONTRACT_TOKEN!,  // JWT class: contract
+});
+
+// ── runtime plane (https://fintech_credit.zarel.ia/v1) ────────────
+const reply = await zarel.runtime.conversation.send({ message: 'List pending tickets' });
+const tickets = await zarel.runtime.records.list('tickets');
+await zarel.runtime.actions.dispatch('cancel_booking', { record_id: 42 });
+
+// ── contract plane (https://fintech_credit.admin.zarel.ia/v1) ─────
+const diff = await zarel.contract.spec.diff(yamlSource);
+await zarel.contract.entities.create({ name: 'orders' /* ... */ });
+await zarel.contract.actions.patch('replace_component', { enforcement: 'advisory' });
+```
+
+Either token can be omitted if you only need one plane; touching the
+other plane throws `ZarelAuthError` with a code identifying which token
+is missing (`runtime_token_missing` / `contract_token_missing`). See
+[Error Handling](#error-handling).
+
+Tenant provisioning lives in `@zarel-ai/sdk-platform`; this SDK
+operates against a tenant that already exists.
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `tenant` | `string` | — | Tenant slug; derives `runtimeBaseUrl` and `contractBaseUrl` when those are not set |
+| `runtimeToken` | `string \| (() => string \| Promise<string>)` | — | Runtime-plane credential (`token_class: tenant`). A static JWT **or** a provider resolved before each request (auth-callback / refresh) |
+| `contractToken` | `string \| (() => string \| Promise<string>)` | — | Contract-plane credential (`token_class: contract`); same string-or-provider shape |
+| `transportManaged` | `boolean` | `false` | Transport-managed (no-token) mode for **both** planes: the SDK omits the `Authorization` header and skips the token-presence guard, leaving auth to a credential-injecting transport (e.g. a BFF proxy). Opt-in — direct consumers keep the token-required guard |
+| `runtimeBaseUrl` | `string` | `https://{tenant}.zarel.ia/v1` | Override the runtime host |
+| `contractBaseUrl` | `string` | `https://{tenant}.admin.zarel.ia/v1` | Override the contract host |
+| `timeout` | `number` | `30000` | Request timeout (ms) — applied to both planes |
+| `maxRetries` | `number` | `3` | Max retries on 5xx / network errors |
+| `retryDelay` | `number` | `500` | Base retry delay (ms, exponential backoff) |
+| `apiVersion` | `string` | — | When set, sends `X-Zarel-Api-Version: <value>` on every request (both planes). Forward-looking — no backend reads it yet |
+| `interceptors` | `Interceptors` | — | Per-attempt request/response/error hooks (both planes). See [Interceptors](#interceptors) |
+| `fetch` | `typeof fetch` | `globalThis.fetch` | Custom fetch implementation |
+
+Every request also carries a built-in `User-Agent: @zarel-ai/sdk/<version>`
+header (effective in Node; browsers drop it — `User-Agent` is a forbidden
+`fetch` header).
+
+When `tenant` is omitted and no explicit `runtimeBaseUrl` is given, the
+runtime plane falls back to `https://api.zarel.ia/v1`.
+
+## Plane Surface
+
+### `client.runtime.*`
+
+| Resource | Methods |
+|----------|---------|
+| `runtime.conversation` | `send`, `clearSession`; nested `sessions.{list, get, create, delete}`, `sessions.actions.{list}` |
+| `runtime.tools` | `list`, `mcp.list`, `call`, `userCatalog` |
+| `runtime.records` | `list`, `get`, `create`, `update`, `delete`, `bulk` |
+| `runtime.actions` | `dispatch` (ADR-0085) |
+| `runtime.stateMachine` | `listInstances`, `getInstance`, `listEvents`, `getEvent`, `listTransitionRequests`, `listPendingTransitions`, `getTransitionRequest`, `createTransitionRequest`, `resolveTransitionRequest`, `replay` |
+| `runtime.flows` | `instances.{list, get}` (`list` accepts an optional `{flow}` filter), `callbacks.{resolve}` |
+| `runtime.mcp` | `call(message)` — POST one MCP JSON-RPC message to `/runtime/mcp`, returns the typed `McpJsonRpcResponse` |
+| `runtime.events` | `subscriptions.{list, create, delete}`, `deliveries.{list}` |
+| `runtime.roles.assignments` | `list`, `create`, `delete` |
+| `runtime.entities` | `recompute` (rewrites `runtime.records`; entity *authoring* is `contract.entities`) |
+| `llm` | `services.{list, get}`, `credentials.{list, get, put, delete}` |
+| `embeddings` | `credentials.{list, get, put, delete}` (per provider; write-only on the secret) |
+| `runtime.imports` | `snapshot` |
+| `runtime.traces` | `get`, `list`, `replay`, `bundle` |
+| `runtime.audit` | `list(log, params?)` — paginated, filterable listing of a privacy-preserving audit row-table (`log` ∈ `binding_violations` \| `topic_refusals`); returns a `PagePromise` (`await` → one page, `for await` → auto-paginate). `evidence(log, { from?, to? })` — download a signed tamper-evidence bundle (`.tar.gz`) for an event hash-chain (`log` ∈ `state_machine` \| `flows`) for offline `zarel verify`; optional inclusive `seq` range bounds a large log (over-cap → HTTP 413) (ADR-0108) |
+| `runtime.receipts` | `list(params?)` — the AUTHENTICATED caller's OWN governance receipts, normalized over the three audit signals (`refusal` \| `binding_violation` \| `validation_violation`); always scoped server-side to the token actor (no `view_traces`), returns a `PagePromise` (`await` → one page, `for await` → auto-paginate). Filter by `signal` / `trace_id` / `from` / `to`. Each receipt carries only a non-reversible proof (hash + masked value), never the raw value (Desk Spec 3) |
+| `runtime.system` | `health`, `metrics`, `apiKeys.{list, create, delete}` |
+| `runtime.authorizations` | `effective` — self-scoped effective-authorizations introspection (ADR-0102 §6, S3b) |
+
+### `client.contract.*`
+
+| Resource | Methods |
+|----------|---------|
+| `contract.spec` | `publish`, `diff`, `apply`, `snapshot.{get, localeCoverage, semanticDiff}`, `dryRun.{submit, get, cancel}` |
+| `contract.entities` | `list`, `get`, `create`, `put`, `patch`, `delete`; `fields(name).{list, get, create, put, patch, delete}`; `fields(name).transitions(field).{list, get, create, put, patch, delete}` |
+| `contract.roles` | `list`, `get`, `create`, `put`, `update`, `delete` (`put` = wholesale replace, `update` = partial patch) |
+| `contract.flows` | `list`, `get`, `create`, `update`, `patch`, `delete`; `steps(name).{list, get, create, put, patch, delete}`; `onCompletion(name).{list, get, create, put, patch, delete}` — flow *definitions* (the `contract.flows` plane; runs live on `runtime.flows.instances`) |
+| `contract.authorization` | `list(role)`, `get(role, onPath)`, `create(role, grant)`, `put(role, onPath, actions)`, `patch(role, onPath, actions)`, `del(role, onPath)` — the WHOLE authorization surface, addressed by `(role, on-path)` regardless of family. `ceiling.get()` — read-only owner/plan-envelope introspection (ADR-0102 §6) |
+| `contract.skills` | `list`, `get`, `create`, `put`, `patch`, `delete` (some verbs may surface server-side `501 ENDPOINT_PLANNED`) |
+| `contract.actions` | `list`, `get`, `create`, `put`, `patch`, `delete` (DELETE may surface 501) |
+| `contract.assistant` | `createSession`, `conversationSend`, `getChangeset`, `applyChangeset`, `discardChangeset` — conversational authoring (conversation stages into one changeset; `applyChangeset({base_hash})` is the sole mutation, one version bump). On staleness `applyChangeset` throws `ZarelAPIError` with `code:'contract_hash_mismatch'` and `details.{reseeded_changeset_id, base_hash}` |
+| `contract.batch` | `execute` (Microsoft Graph-style envelope) |
+| `contract.capabilities` | `list`, `get`, `create`, `put`, `patch`, `delete` |
+| `contract.constraints` | same |
+| `contract.schemas` | same |
+| `contract.metadata` | `get`, `put`, `patch` (composite singleton) |
+| `contract.events.rules` | CRUD on `/contract/events/rules*` |
+| `contract.processModel` | `get`/`put`/`patch` (the process-model document) + `phases.{list,get,create,put,patch,delete}` |
+| `contract.quotas` | **no resource, by design.** The per-role bounds (`max_chained_actions_per_turn`, `composite_write.*`) have no admin route — they are declared by publishing the contract, so there is nothing for the SDK to call |
+| `contract.{llm,embeddings,treatment,rails,channels,mcpServers,profiles,timezone}` | ADR-0138 contract roots (admin host). Distinct from the runtime-plane `client.runtime.*`. Singletons: `llm`, `rails`, `embeddings`, `timezone` (`get`/`put` only), `events.delivery`, `assistant` (`get`/`put`/`patch` + `vocabulary` collection). Collections: `mcpServers` (+ `allowedTools(ns)`), `profiles`, `channels` (+ `credentials`) |
+
+_The namespace hierarchy is a structural bijection with the contract OpenAPI surface, enforced by `tests/contract-hierarchy-alignment.test.ts` (ADR-0066)._
+
+### Working with authorization
+
+A grant is `{ on, actions }` — the same shape the YAML contract declares, so what
+you read here and what you author there are isomorphic. `on` is the **on-path**:
+a config section (`entities`, `channels/credentials`) or an operational
+root (`records/{entity}`, `flows/{flow}`, `llm/services/{name}`).
+
+```typescript
+// Everything a role holds, canonically ordered
+const { grants } = await client.contract.authorization.list('support');
+
+// Create-or-replace one grant (idempotent). An action is a bare string or a
+// single-key attenuation carrying `fields` / `scope` / `when`.
+await client.contract.authorization.put('support', 'records/orders', [
+  'read',
+  'list',
+  { update: { fields: ['status'] } },
+]);
+
+// Merge actions into an existing grant — adds or re-attenuates, never drops
+await client.contract.authorization.patch('support', 'records/orders', ['create']);
+
+await client.contract.authorization.del('support', 'records/orders');
+```
+
+`create(role, grant)` is the create-only verb: it returns **409** when a grant on
+that on-path already exists, so it and the idempotent `put` never disagree about
+duplicates.
+
+Writes are bounded by the **plan ceiling** (ADR-0102 §6). Two `403`s are expected
+and worth handling distinctly: `ceiling_exceeded` (the grant is outside the
+tenant's plan envelope) and `owner_role_protected` (the role is platform-seeded
+and immutable to the tenant — this applies to `del` too, not only writes). Read
+the envelope those verdicts derive from with:
+
+```typescript
+const { ownerRoleNames, grants } = await client.contract.authorization.ceiling.get();
+```
+
+Grants are **exact-match, with no parent→child inheritance**: a grant on `runtime`
+never covers `channels` (ADR-0136 §4.1). Address the child explicitly.
+
+## Responses
+
+Methods return the **response payload directly** — the SDK never surfaces the
+wire-level `{ success, data }` envelope. The transport validates the envelope
+and returns its `data`; a `success: false` envelope surfaces as a
+`ZarelAPIError`. This is the single unwrap authority (ADR-0109).
+
+```typescript
+const roles = await zarel.contract.roles.list();   // RoleRecord[]  (not { success, data })
+const order = await zarel.runtime.records.get('orders', 42); // RecordData
+```
+
+A handful of endpoints return a **bare body** (no envelope) or a **flat**
+shape where `success` is a status field rather than a wrapper — e.g.
+`contract.spec.snapshot.get` (the flat contract document), `runtime.conversation.send`
+(`{ success, message, intent_type, … }`), `runtime.tools.*`, and
+`runtime.flows.callbacks.resolve`. The SDK returns those **unchanged**.
+
+The unwrap decision is **spec-derived, not guessed**: the OpenAPI is the single
+source of truth. A codegen step (`gen:sdk-unwrap-map`) reads each operation's
+success response and emits a checked-in per-plane map
+(`src/generated/unwrap-map.ts`) of `{ [operationId]: { unwrap } }`; the transport
+does an O(1) lookup by the `operationId` the resource passes. An operation whose
+2xx response references the canonical envelope is unwrapped to `data`; a flat or
+bare response is returned whole. There is **no runtime key-shape heuristic and no
+manual opt-outs** — both were removed (ADR-0109 amendment). A build-time
+completeness guard ensures every operation is classified, so the decision can
+never silently fall through. Callers never think about this — the return type is
+always the payload.
+
+Response payload types are **generated from `docs/api/*-openapi-v1.yaml`** and
+guarded against drift in CI (ADR-0109): `npm run gen:sdk` regenerates both the
+types (`generated/{runtime,contract}.ts`) and the unwrap map from the same
+response-schema signal, and jest drift-guards byte-diff the checked-in output.
+
+## Pagination
+
+The paginated list calls — `runtime.records.list`, `runtime.traces.list`,
+`runtime.conversation.sessions.list`, and `runtime.audit.list` — return a value that is
+**both awaitable and async-iterable** (the OpenAI/Stripe pattern):
+
+```typescript
+// Await it for the first page — exactly the shape it has always returned:
+const page = await zarel.runtime.records.list('orders', { limit: 50 });
+console.log(page.records, page.total);
+
+// …or iterate it to auto-paginate over every item across all pages:
+for await (const order of zarel.runtime.records.list('orders', { filters: { status: 'open' } })) {
+    process(order);
+}
+for await (const trace of zarel.runtime.traces.list({ outcome: 'refused' })) { /* … */ }
+for await (const session of zarel.runtime.conversation.sessions.list({ status: 'active' })) { /* … */ }
+
+// Audit row-tables (gated by the `view_traces` runtime-system action):
+const violations = await zarel.runtime.audit.list('binding_violations', { entity: 'Account' });
+for await (const refusal of zarel.runtime.audit.list('topic_refusals', { category: 'investment_advice' })) { /* … */ }
+```
+
+`await` is fully backward-compatible — it resolves to the same single-page shape
+as before (`{ records, total }`, `{ traces, next_cursor }`, or
+`ConversationSessionSummary[]`). The first page is fetched lazily (nothing happens until
+you `await` or iterate) and is shared if you do both.
+
+**Page size.** Iteration uses your `limit` as the page size; if you omit it, the
+server's natural page size is used (the SDK does not inject a default, so the
+first request stays identical to a plain `list` call).
+
+**Stopping early & cancellation.** `break` out of the loop and no further page is
+requested. To cancel an in-flight request, pass an `AbortSignal`:
+
+```typescript
+const ac = new AbortController();
+for await (const order of zarel.runtime.records.list('orders', undefined, { signal: ac.signal })) {
+    if (done) { ac.abort(); break; }
+}
+```
+
+**Caveat — `conversation.sessions.list`.** That endpoint's wire shape carries neither a
+`total` nor a cursor, so iteration stops when a page returns fewer items than the
+page size. When the row count is an exact multiple of the page size, one extra
+request returns an empty page and iteration then stops — no items are missed or
+duplicated.
+
+## Error Handling
+
+```typescript
+import { ZarelAPIError, ZarelAuthError, ZarelTimeoutError } from '@zarel-ai/sdk';
+
+try {
+  await zarel.runtime.records.list('tickets');
+} catch (err) {
+  if (err instanceof ZarelAuthError) {
+    // Three discrete codes, distinguishable without parsing messages:
+    //   'runtime_token_missing'  — runtime call without runtimeToken (pre-network)
+    //   'contract_token_missing' — contract call without contractToken (pre-network)
+    //   'unauthorized'           — server returned 401
+    switch (err.code) {
+      case 'runtime_token_missing': /* configure runtimeToken */ break;
+      case 'contract_token_missing': /* configure contractToken */ break;
+      case 'unauthorized': /* refresh / re-mint */ break;
+    }
+  }
+  if (err instanceof ZarelAPIError) {
+    console.error(`API Error ${err.status}: [${err.code}] ${err.message}`);
+  }
+  if (err instanceof ZarelTimeoutError) {
+    console.error('Request timed out');
+  }
+}
+```
+
+## Retries
+
+The SDK automatically retries on `408`, `429`, `500`, `502`, `503`, `504`
+status codes and network errors using exponential backoff with jitter.
+`401` immediately throws `ZarelAuthError` (no retry); `400` / `403` /
+`404` / `501` surface as `ZarelAPIError` without retry.
+
+**`Retry-After`** — when a retryable response (typically `429` / `503`) carries
+a `Retry-After` header, the SDK honours it for that attempt's wait instead of the
+exponential backoff. Both RFC 7231 forms are parsed (delta-seconds and an
+HTTP-date); the wait is clamped to a 60-second ceiling so a huge value can't hang
+the client (it still retries). When the header is absent or unparseable, the
+exponential backoff is unchanged.
+
+## Interceptors
+
+Register per-attempt hooks at client construction (applied to both planes) to
+observe and augment requests without replacing the transport:
+
+```ts
+const client = new Zarel({
+    tenant: 'acme',
+    runtimeToken: token,
+    interceptors: {
+        onRequest: (ctx) => { ctx.headers['X-Trace-Id'] = traceId(); }, // mutate in place
+        onResponse: (ctx) => log.debug(ctx.method, ctx.url, ctx.status, ctx.attempt),
+        onError: (ctx) => log.warn('transport failure', ctx.url, ctx.attempt, ctx.error),
+    },
+});
+```
+
+- Hooks fire **once per network attempt** (retries included); `ctx.attempt` is
+  the 0-based attempt number.
+- **`onRequest`** runs after the transport assembles the per-attempt headers
+  (`Authorization`, `Idempotency-Key`, `User-Agent`, `X-Zarel-Api-Version`), so it
+  sees and may override any of them by mutating `ctx.headers`. A **throw aborts**
+  the request (no network call, no retry) — useful as a pre-flight veto. (Avoid
+  changing `Idempotency-Key` across attempts — it breaks server-side dedup.)
+  Note: `ctx.headers` includes the `Authorization` bearer — don't log it.
+- **`onResponse`** fires for **every** HTTP response (any status: 2xx/4xx/5xx),
+  read-only. **`onError`** fires only when an attempt produced **no** response (a
+  network error or timeout), read-only. The two are mutually exclusive per attempt
+  and a thrown observation hook is swallowed (it never masks the real outcome).
+- Hooks may be `async`; the transport awaits them. Zero runtime dependencies.
+
+## Streaming
+
+`client.runtime.events.stream(...)` opens a typed Server-Sent-Events stream over
+`GET /runtime/events/stream` (runtime plane). It is built on native `fetch` +
+`ReadableStream` (so it carries the `Authorization` header for direct consumers
+and credentials for proxy/cookie consumers — unlike a raw `EventSource`) and adds
+**zero runtime dependencies**.
+
+```ts
+const handle = client.runtime.events.stream(
+    {
+        onEvent: (e) => {
+            if (e.event === 'conversation.turn_created') {
+                // typed via the exported `isConversationTurnCreatedEvent` guard
+                console.log(e.data.payload.session_key, e.data.payload.turn_number);
+            }
+        },
+        onError: (err) => console.error('stream ended', err),  // terminal only
+        onOpen: () => console.log('connected'),                // each (re)connect
+    },
+    { reconnect: true /* default */ },
+);
+
+// later — tears down the request + stops reconnecting (idempotent):
+handle.close();
+```
+
+Events are a typed union: a validated `conversation.turn_created` arm plus a generic
+`{ event: string; data: unknown }` fallback for other named events. Narrow with the
+exported `isConversationTurnCreatedEvent(e)` guard. Malformed or schema-failing frames are
+dropped (never thrown into `onEvent`).
+
+**Reconnection** is built in and default-on: a transient disconnect (network error,
+server EOF, `5xx`, `408`, `429`) reconnects with bounded exponential backoff +
+`Last-Event-ID`, indefinitely until `close()`/abort. A terminal status (`401`/`403`
+and other `4xx`) calls `onError` once and stops. Pass `{ reconnect: false }` for a
+single connection, `{ signal }` to abort via an `AbortSignal`, or `{ lastEventId }`
+to resume from a known position.
+
+### `events.iterate(...)` — async-iterable view
+
+For a pull-style consumer, `client.runtime.events.iterate(...)` returns an
+`AsyncIterableIterator<RuntimeStreamEvent>` over the **same** stream (same auth,
+reconnect, and parsing — it adds no transport of its own):
+
+```ts
+const ac = new AbortController();
+for await (const e of client.runtime.events.iterate({
+    signal: ac.signal,
+    bufferSize: 512,                                  // default 1024; < 1 clamps to 1
+    onDropped: (n) => console.warn(`dropped ${n} (slow consumer)`),
+})) {
+    if (isConversationTurnCreatedEvent(e)) console.log(e.data.payload.turn_number);
+    if (done(e)) break;                               // break tears the stream down
+}
+```
+
+Events are buffered between the stream and your loop in a **bounded FIFO** ring of
+`bufferSize`. If you consume slower than events arrive and the buffer fills, the
+**oldest** event is dropped (loss-tolerant, like the callback stream) and `onDropped`
+is called with the running total — so memory stays bounded regardless of consumer
+speed. A **terminal** stream error (e.g. `401`) is thrown out of the `for await`
+(buffered events drain first); a transient disconnect reconnects silently and never
+ends the loop. `break`/`return`/`throw` and an aborted `signal` all tear the
+underlying stream down. `iterate` does not take `onOpen` (use `stream` for per-connect
+signals); `signal`/`reconnect`/`lastEventId` apply identically.
+
+## MCP transport (`runtime.mcp.call`)
+
+`client.runtime.mcp.call(message)` sends one MCP JSON-RPC message to the tenant's
+stateless MCP "Streamable HTTP" transport (`POST /runtime/mcp`, runtime plane) and
+returns the typed `McpJsonRpcResponse`. It accepts either an `application/json` body
+or a single `text/event-stream` frame (the server chooses) and de-frames both —
+bare JSON-RPC, never the `{success,data}` envelope. A **protocol-level** JSON-RPC
+error is returned in the union (not thrown); **transport** failures throw
+(`ZarelAuthError` on 401, `ZarelAPIError` otherwise). It makes a single attempt
+(no retry — `tools/call` may be a non-idempotent mutation).
+
+```ts
+const res = await client.runtime.mcp.call({ jsonrpc: '2.0', id: 1, method: 'tools/list' });
+if ('error' in res) console.error(res.error.code, res.error.message);
+else console.log(res.result);
+```
+
+This is a thin, zero-dependency one-shot call — for a full MCP client (sessions,
+server-push) use `@modelcontextprotocol/sdk`.
+
+## Requirements
+
+- Node.js 18+ (for native `fetch`)
+- TypeScript 5.0+ (for type-safe usage)
+
+## License
+
+MIT

package/dist/_internal/auth-headers.d.ts

@@ -0,0 +1,19 @@
+import type { TokenInput } from './fetch-client';
+export type RequireTokenCode = 'runtime_token_missing' | 'contract_token_missing';
+/**
+ * The SINGLE auth authority (G3 QI-001) shared by BOTH request paths — the REST
+ * `FetchClient` and the SSE stream client. Given a token (string or provider)
+ * and the transport-managed flag, it resolves the token (honoring the optional
+ * presence guard) and returns the `Authorization` header decision:
+ *
+ *   - transport-managed → `{}` (the credential-injecting transport sets the
+ *     header server-side; the SDK omits it and skips the presence guard);
+ *   - direct, empty token → `{}` (no bearer);
+ *   - direct, present token → `{ Authorization: 'Bearer <token>' }`.
+ *
+ * Centralizing this here means there is exactly one place that builds a Bearer
+ * header — neither the SSE client nor any resource may build its own (the QI-001
+ * structural gate enforces a single `Bearer ` site).
+ */
+export declare function resolveAuthHeaders(token: TokenInput, transportManaged: boolean, requireTokenCode?: RequireTokenCode): Promise<Record<string, string>>;
+//# sourceMappingURL=auth-headers.d.ts.map

package/dist/_internal/auth-headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-headers.d.ts","sourceRoot":"","sources":["../../src/_internal/auth-headers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,MAAM,MAAM,gBAAgB,GAAG,uBAAuB,GAAG,wBAAwB,CAAC;AAElF;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACpC,KAAK,EAAE,UAAU,EACjB,gBAAgB,EAAE,OAAO,EACzB,gBAAgB,CAAC,EAAE,gBAAgB,GACpC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CASjC"}

package/dist/_internal/auth-headers.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAuthHeaders = resolveAuthHeaders;
+const require_token_1 = require("./require-token");
+/**
+ * The SINGLE auth authority (G3 QI-001) shared by BOTH request paths — the REST
+ * `FetchClient` and the SSE stream client. Given a token (string or provider)
+ * and the transport-managed flag, it resolves the token (honoring the optional
+ * presence guard) and returns the `Authorization` header decision:
+ *
+ *   - transport-managed → `{}` (the credential-injecting transport sets the
+ *     header server-side; the SDK omits it and skips the presence guard);
+ *   - direct, empty token → `{}` (no bearer);
+ *   - direct, present token → `{ Authorization: 'Bearer <token>' }`.
+ *
+ * Centralizing this here means there is exactly one place that builds a Bearer
+ * header — neither the SSE client nor any resource may build its own (the QI-001
+ * structural gate enforces a single `Bearer ` site).
+ */
+async function resolveAuthHeaders(token, transportManaged, requireTokenCode) {
+    if (transportManaged) {
+        return {};
+    }
+    const resolved = typeof token === 'function' ? await token() : token;
+    if (requireTokenCode) {
+        (0, require_token_1.requireToken)(resolved, requireTokenCode);
+    }
+    return resolved === '' ? {} : { 'Authorization': `Bearer ${resolved}` };
+}
+//# sourceMappingURL=auth-headers.js.map

package/dist/_internal/auth-headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-headers.js","sourceRoot":"","sources":["../../src/_internal/auth-headers.ts"],"names":[],"mappings":";;AAoBA,gDAaC;AAjCD,mDAA+C;AAK/C;;;;;;;;;;;;;;GAcG;AACI,KAAK,UAAU,kBAAkB,CACpC,KAAiB,EACjB,gBAAyB,EACzB,gBAAmC;IAEnC,IAAI,gBAAgB,EAAE,CAAC;QACnB,OAAO,EAAE,CAAC;IACd,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IACrE,IAAI,gBAAgB,EAAE,CAAC;QACnB,IAAA,4BAAY,EAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,UAAU,QAAQ,EAAE,EAAE,CAAC;AAC5E,CAAC"}

package/dist/_internal/confirmation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Confirmation round-trip transport helpers (ADR-0127 US3) — the single place
+ * the SDK names the header and the single place it parses the challenge.
+ */
+import type { ConfirmationChallenge } from '../types/confirmation';
+/** The retry header. Read server-side from the header only, never the body. */
+export declare const CONFIRMATION_TOKEN_HEADER = "X-Zarel-Confirmation-Token";
+/** `{}` when no token — so a caller can spread this unconditionally. */
+export declare function confirmationHeaders(token?: string): Record<string, string>;
+/**
+ * Parse `error.confirmation` off a 409 body, fail-closed.
+ *
+ * Returns undefined unless the challenge is COMPLETE — at least one named guard
+ * AND a token. A challenge with no token cannot be round-tripped, and one with
+ * no guard has no prompt to show, so surfacing either as a confirmable error
+ * would offer the operator a Confirm button that can only fail. Undefined
+ * degrades the 409 to an ordinary API error, which is the honest outcome.
+ *
+ * A guard missing its `prompt` is kept with a name-derived fallback (the name is
+ * what makes it auditable); a guard missing its `name` is dropped, mirroring
+ * `parseConfirmationGuards` in `@zarel-ai/contract/core`.
+ */
+export declare function parseConfirmationChallenge(raw: unknown): ConfirmationChallenge | undefined;
+//# sourceMappingURL=confirmation.d.ts.map

package/dist/_internal/confirmation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirmation.d.ts","sourceRoot":"","sources":["../../src/_internal/confirmation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAqB,MAAM,uBAAuB,CAAC;AAEtF,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,+BAA+B,CAAC;AAEtE,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE1E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,OAAO,GAAG,qBAAqB,GAAG,SAAS,CAoB1F"}

package/dist/_internal/confirmation.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Confirmation round-trip transport helpers (ADR-0127 US3) — the single place
+ * the SDK names the header and the single place it parses the challenge.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIRMATION_TOKEN_HEADER = void 0;
+exports.confirmationHeaders = confirmationHeaders;
+exports.parseConfirmationChallenge = parseConfirmationChallenge;
+/** The retry header. Read server-side from the header only, never the body. */
+exports.CONFIRMATION_TOKEN_HEADER = 'X-Zarel-Confirmation-Token';
+/** `{}` when no token — so a caller can spread this unconditionally. */
+function confirmationHeaders(token) {
+    return token ? { [exports.CONFIRMATION_TOKEN_HEADER]: token } : {};
+}
+/**
+ * Parse `error.confirmation` off a 409 body, fail-closed.
+ *
+ * Returns undefined unless the challenge is COMPLETE — at least one named guard
+ * AND a token. A challenge with no token cannot be round-tripped, and one with
+ * no guard has no prompt to show, so surfacing either as a confirmable error
+ * would offer the operator a Confirm button that can only fail. Undefined
+ * degrades the 409 to an ordinary API error, which is the honest outcome.
+ *
+ * A guard missing its `prompt` is kept with a name-derived fallback (the name is
+ * what makes it auditable); a guard missing its `name` is dropped, mirroring
+ * `parseConfirmationGuards` in `@zarel-ai/contract/core`.
+ */
+function parseConfirmationChallenge(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const { guards, token, expires_at: expiresAt } = raw;
+    if (typeof token !== 'string' || token.length === 0)
+        return undefined;
+    if (!Array.isArray(guards))
+        return undefined;
+    const parsed = [];
+    for (const entry of guards) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const { name, prompt } = entry;
+        if (typeof name !== 'string' || name.length === 0)
+            continue;
+        parsed.push({ name, prompt: typeof prompt === 'string' ? prompt : `Confirm "${name}"` });
+    }
+    if (parsed.length === 0)
+        return undefined;
+    return {
+        guards: parsed,
+        token,
+        expires_at: typeof expiresAt === 'string' ? expiresAt : '',
+    };
+}
+//# sourceMappingURL=confirmation.js.map

package/dist/_internal/confirmation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirmation.js","sourceRoot":"","sources":["../../src/_internal/confirmation.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAQH,kDAEC;AAeD,gEAoBC;AAzCD,+EAA+E;AAClE,QAAA,yBAAyB,GAAG,4BAA4B,CAAC;AAEtE,wEAAwE;AACxE,SAAgB,mBAAmB,CAAC,KAAc;IAC9C,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,iCAAyB,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/D,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,0BAA0B,CAAC,GAAY;IACnD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC9D,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,GAA8B,CAAC;IAChF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACtE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAE7C,MAAM,MAAM,GAAwB,EAAE,CAAC;IACvC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACzB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QAC1D,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,KAAgC,CAAC;QAC1D,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAC5D,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,IAAI,GAAG,EAAE,CAAC,CAAC;IAC7F,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAE1C,OAAO;QACH,MAAM,EAAE,MAAM;QACd,KAAK;QACL,UAAU,EAAE,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE;KAC7D,CAAC;AACN,CAAC"}

package/dist/_internal/event-iterator.d.ts

@@ -0,0 +1,18 @@
+import type { EventStreamHandle, EventStreamHandlers, EventStreamOptions, RuntimeStreamEvent } from '../types/events-stream';
+/** Opens an underlying stream with the given handlers; returns its teardown handle. */
+export type OpenStream = (handlers: EventStreamHandlers, options: EventStreamOptions) => EventStreamHandle;
+export interface EventIteratorConfig {
+    /** Bounded buffer capacity; clamped to a minimum of 1. */
+    bufferSize?: number;
+    /** Reported with the running total on each overflow drop. */
+    onDropped?: (totalDropped: number) => void;
+    /** Stream options forwarded verbatim to `open` (signal/reconnect/lastEventId). */
+    streamOptions: EventStreamOptions;
+}
+/**
+ * Build an `AsyncIterableIterator<RuntimeStreamEvent>` over `open`. The first
+ * `next()` (or entry into a `for await`) lazily opens the stream; `return()` /
+ * `throw()` / consumer `break` tear it down via the handle's idempotent `close()`.
+ */
+export declare function createEventIterator(open: OpenStream, config: EventIteratorConfig): AsyncIterableIterator<RuntimeStreamEvent>;
+//# sourceMappingURL=event-iterator.d.ts.map

package/dist/_internal/event-iterator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-iterator.d.ts","sourceRoot":"","sources":["../../src/_internal/event-iterator.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACR,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EACrB,MAAM,wBAAwB,CAAC;AAIhC,uFAAuF;AACvF,MAAM,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,mBAAmB,EAAE,OAAO,EAAE,kBAAkB,KAAK,iBAAiB,CAAC;AAE3G,MAAM,WAAW,mBAAmB;IAChC,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,kFAAkF;IAClF,aAAa,EAAE,kBAAkB,CAAC;CACrC;AASD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAC/B,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,mBAAmB,GAC5B,qBAAqB,CAAC,kBAAkB,CAAC,CA4I3C"}