rigorix-client 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# rigorix-client (TypeScript)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Protocol-only typed client for the frozen `rigorix.*` JSON-RPC catalog
+([ADR-0001](../../docs/adr/ADR-0001-native-api-catalog.md)). It mirrors the
+catalog `$defs` and speaks JSON-RPC 2.0 over `POST /rpc` (single requests,
+batch arrays, notifications).
+
+Two invariants are enforced in code and CI:
+
+- **Governed flows only** — no raw step-execution surface (ADR-0001 D10); a
+  test fails if one is ever added.
+- **No engine dependency** — execution logic never moves into an SDK (D-1).
+
+## Install
+
+```bash
+npm install rigorix-client@0.2.0
+```
+
+## Usage
+
+```ts
+import { Client, FetchTransport } from "rigorix-client";
+
+const client = new Client(new FetchTransport("https://host/rpc", { authorization: "Bearer …" }));
+
+const plan = await client.plan({ template_name: "attendance" });
+const run = await client.run({ template_name: "attendance" });
+const version = await client.version(); // checks the apiVersion major constraint
+
+await client.notify("rigorix.audit.read", { execution_id: run.execution_id });
+const batch = await client.batchRaw([new BatchCall("rigorix.audit.list", {})]);
+```
+
+## Transport seam
+
+Implement `Transport` (`post(body) => response`), or use the built-in
+`FetchTransport` (global `fetch`, Node 20+) / `MockTransport` (tests).
+
+## Errors
+
+`errors.json` `data.type` maps to a distinct `ApiError.kind`; an unknown type
+falls through to `"unknown"` — never a throw. `JsonRpcError` wraps a JSON-RPC
+`error`; `TransportError`/`ProtocolError`/`VersionMismatchError` cover the rest.
+
+## Catalog binding + drift
+
+`catalog.METHODS` lists every frozen method as `typed` or `server_only`.
+`catalog_drift` reads `schemas/api/catalog.json` and fails if the two diverge —
+the namespace is closed, so no method is silently omitted. Server-only
+exemptions: `audit.head`/`.history`/`.overdue` (enterprise Phase B),
+`auth.verify` (enterprise JWKS), `policy.bundle` (admin control plane).
+
+## Test
+
+```bash
+npm install
+npm test          # tsc + node --test
+```

package/dist/src/auth.d.ts

@@ -0,0 +1,9 @@
+/** Device-flow auth helpers (ADR-0008): conveniences over `rigorix.auth.*`.
+ * The client never invents identity — the attested session is authoritative
+ * (ADR-0001 D5); `approver_id`/`authority` are display-only. */
+import type { Client } from "./client.js";
+import type { AuthLoginParams, AuthLoginResult, AuthStatusResult } from "./types.js";
+/** Begin the OIDC device flow (`rigorix.auth.login`). */
+export declare function beginDeviceFlow(client: Client, params: AuthLoginParams): Promise<AuthLoginResult>;
+/** Report the redacted session status (`rigorix.auth.status`). */
+export declare function sessionStatus(client: Client): Promise<AuthStatusResult>;

package/dist/src/auth.js

@@ -0,0 +1,11 @@
+/** Device-flow auth helpers (ADR-0008): conveniences over `rigorix.auth.*`.
+ * The client never invents identity — the attested session is authoritative
+ * (ADR-0001 D5); `approver_id`/`authority` are display-only. */
+/** Begin the OIDC device flow (`rigorix.auth.login`). */
+export function beginDeviceFlow(client, params) {
+    return client.authLogin(params);
+}
+/** Report the redacted session status (`rigorix.auth.status`). */
+export function sessionStatus(client) {
+    return client.authStatus();
+}

package/dist/src/catalog.d.ts

@@ -0,0 +1,21 @@
+/** The frozen `rigorix.*` catalog as a client-side binding table (ADR-0001 D3).
+ *
+ * Every method in `schemas/api/catalog.json` is either **typed** or
+ * **explicitly server-only**. The `catalog_drift` test fails if the two
+ * diverge — the namespace is closed, so no method is silently omitted. There is
+ * deliberately no raw step-execution method (ADR-0001 D10). */
+export type Binding = {
+    kind: "typed";
+} | {
+    kind: "server_only";
+    reason: string;
+};
+export interface MethodBinding {
+    name: string;
+    binding: Binding;
+}
+export declare const METHODS: MethodBinding[];
+export declare function find(name: string): MethodBinding | undefined;
+export declare function names(): string[];
+/** Ensure the client never exposes a raw step-execution method (ADR-0001 D10). */
+export declare function assertNoRawStepExecution(): void;

package/dist/src/catalog.js

@@ -0,0 +1,64 @@
+/** The frozen `rigorix.*` catalog as a client-side binding table (ADR-0001 D3).
+ *
+ * Every method in `schemas/api/catalog.json` is either **typed** or
+ * **explicitly server-only**. The `catalog_drift` test fails if the two
+ * diverge — the namespace is closed, so no method is silently omitted. There is
+ * deliberately no raw step-execution method (ADR-0001 D10). */
+export const METHODS = [
+    { name: "rigorix.plan", binding: { kind: "typed" } },
+    { name: "rigorix.validatePlan", binding: { kind: "typed" } },
+    { name: "rigorix.run", binding: { kind: "typed" } },
+    { name: "rigorix.execute", binding: { kind: "typed" } },
+    { name: "rigorix.approve", binding: { kind: "typed" } },
+    { name: "rigorix.checkEnforcement", binding: { kind: "typed" } },
+    { name: "rigorix.audit.read", binding: { kind: "typed" } },
+    { name: "rigorix.audit.list", binding: { kind: "typed" } },
+    { name: "rigorix.audit.summary", binding: { kind: "typed" } },
+    {
+        name: "rigorix.audit.head",
+        binding: { kind: "server_only", reason: "enterprise ADR-016 Phase B ledger surface" },
+    },
+    {
+        name: "rigorix.audit.history",
+        binding: { kind: "server_only", reason: "enterprise ADR-016 Phase B ledger surface" },
+    },
+    {
+        name: "rigorix.audit.overdue",
+        binding: { kind: "server_only", reason: "enterprise ADR-016 Phase B ledger surface" },
+    },
+    { name: "rigorix.template.list", binding: { kind: "typed" } },
+    { name: "rigorix.template.get", binding: { kind: "typed" } },
+    { name: "rigorix.template.create", binding: { kind: "typed" } },
+    { name: "rigorix.template.validate", binding: { kind: "typed" } },
+    { name: "rigorix.auth.login", binding: { kind: "typed" } },
+    { name: "rigorix.auth.status", binding: { kind: "typed" } },
+    { name: "rigorix.auth.logout", binding: { kind: "typed" } },
+    {
+        name: "rigorix.auth.verify",
+        binding: { kind: "server_only", reason: "enterprise-side JWKS claim verification" },
+    },
+    {
+        name: "rigorix.policy.bundle",
+        binding: { kind: "server_only", reason: "admin/enterprise control-plane export" },
+    },
+    { name: "rigorix.usageGuide", binding: { kind: "typed" } },
+    { name: "rigorix.system.version", binding: { kind: "typed" } },
+];
+export function find(name) {
+    return METHODS.find((method) => method.name === name);
+}
+export function names() {
+    return METHODS.map((method) => method.name);
+}
+/** Ensure the client never exposes a raw step-execution method (ADR-0001 D10). */
+export function assertNoRawStepExecution() {
+    for (const method of METHODS) {
+        const lower = method.name.toLowerCase();
+        if (lower.includes("step") && method.name !== "rigorix.plan") {
+            throw new Error(`unexpected raw step-execution binding: ${method.name}`);
+        }
+        if (method.name === "rigorix.executeStep") {
+            throw new Error("raw step execution must never be bound");
+        }
+    }
+}

package/dist/src/client.d.ts

@@ -0,0 +1,51 @@
+/** The typed client over a `Transport` (ADR-0001 D1/D3). */
+import { ClientError } from "./error.js";
+import { type RpcResponse } from "./jsonrpc.js";
+import type { Transport } from "./transport.js";
+import type * as types from "./types.js";
+/** The native API major this client targets (catalog.json `apiVersion`). */
+export declare const CLIENT_API_MAJOR = 1;
+/** The full native API version this client was built against. */
+export declare const CLIENT_API_VERSION = "1.0.0";
+/** One raw call in a batch. */
+export declare class BatchCall {
+    readonly method: string;
+    readonly params?: unknown | undefined;
+    constructor(method: string, params?: unknown | undefined);
+}
+/** A typed JSON-RPC client over the frozen `rigorix.*` catalog. */
+export declare class Client {
+    private readonly transport;
+    private nextId;
+    constructor(transport: Transport);
+    private id;
+    /** Call a method and return the raw `result` value. */
+    callRaw(method: string, params?: unknown): Promise<unknown>;
+    /** Call a method with typed params, returning a typed result. */
+    call<P, R>(method: string, params: P): Promise<R>;
+    /** Send a notification (no `id`; no response expected). */
+    notify(method: string, params?: unknown): Promise<void>;
+    /** Send a batch (one JSON array) and return the raw responses. */
+    batchRaw(calls: BatchCall[]): Promise<RpcResponse[]>;
+    plan(params: types.PlanParams): Promise<types.PlanResult>;
+    validatePlan(params: types.ValidatePlanParams): Promise<types.ValidateResult>;
+    run(params: types.RunParams): Promise<types.ExecuteResult>;
+    execute(params: types.ExecuteParams): Promise<types.ExecuteResult>;
+    approve(params: types.ApproveParams): Promise<types.ApproveResult>;
+    checkEnforcement(): Promise<types.CheckEnforcementResult>;
+    auditRead(params: types.AuditReadParams): Promise<types.AuditReadResult>;
+    auditList(params: types.AuditListParams): Promise<types.AuditListResult>;
+    auditSummary(params: types.AuditSummaryParams): Promise<types.AuditSummaryResult>;
+    templateList(params: types.TemplateListParams): Promise<types.TemplateListResult>;
+    templateGet(params: types.TemplateGetParams): Promise<types.TemplateGetResult>;
+    templateCreate(params: types.TemplateCreateParams): Promise<types.TemplateCreateResult>;
+    templateValidate(params: types.TemplateValidateParams): Promise<types.ValidateResult>;
+    authLogin(params: types.AuthLoginParams): Promise<types.AuthLoginResult>;
+    authStatus(): Promise<types.AuthStatusResult>;
+    authLogout(): Promise<types.AuthLogoutResult>;
+    usageGuide(): Promise<types.UsageGuideResult>;
+    version(): Promise<types.VersionResult>;
+    /** Verify the server's `api_version` is compatible with this client's major. */
+    checkVersion(version: types.VersionResult): void;
+}
+export { ClientError };

package/dist/src/client.js

@@ -0,0 +1,122 @@
+/** The typed client over a `Transport` (ADR-0001 D1/D3). */
+import { ClientError, JsonRpcError, ProtocolError, VersionMismatchError, } from "./error.js";
+import { call, decode, decodeBatch, encode, encodeBatch, notification, } from "./jsonrpc.js";
+/** The native API major this client targets (catalog.json `apiVersion`). */
+export const CLIENT_API_MAJOR = 1;
+/** The full native API version this client was built against. */
+export const CLIENT_API_VERSION = "1.0.0";
+/** One raw call in a batch. */
+export class BatchCall {
+    method;
+    params;
+    constructor(method, params) {
+        this.method = method;
+        this.params = params;
+    }
+}
+/** A typed JSON-RPC client over the frozen `rigorix.*` catalog. */
+export class Client {
+    transport;
+    nextId = 1;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    id() {
+        return this.nextId++;
+    }
+    /** Call a method and return the raw `result` value. */
+    async callRaw(method, params) {
+        const body = encode(call(this.id(), method, params));
+        const responseBody = await this.transport.post(body);
+        const response = decode(responseBody);
+        if (response.error)
+            throw new JsonRpcError(response.error);
+        if (response.result === undefined) {
+            throw new ProtocolError("response has neither `result` nor `error`");
+        }
+        return response.result;
+    }
+    /** Call a method with typed params, returning a typed result. */
+    async call(method, params) {
+        return (await this.callRaw(method, params));
+    }
+    /** Send a notification (no `id`; no response expected). */
+    async notify(method, params) {
+        await this.transport.post(encode(notification(method, params)));
+    }
+    /** Send a batch (one JSON array) and return the raw responses. */
+    async batchRaw(calls) {
+        const body = encodeBatch(calls.map((entry) => call(this.id(), entry.method, entry.params)));
+        const responseBody = await this.transport.post(body);
+        return decodeBatch(responseBody);
+    }
+    // ─── Governed flows ──────────────────────────────────────────────────
+    plan(params) {
+        return this.call("rigorix.plan", params);
+    }
+    validatePlan(params) {
+        return this.call("rigorix.validatePlan", params);
+    }
+    run(params) {
+        return this.call("rigorix.run", params);
+    }
+    execute(params) {
+        return this.call("rigorix.execute", params);
+    }
+    approve(params) {
+        return this.call("rigorix.approve", params);
+    }
+    checkEnforcement() {
+        return this.call("rigorix.checkEnforcement", {});
+    }
+    // ─── Audit (read side) ───────────────────────────────────────────────
+    auditRead(params) {
+        return this.call("rigorix.audit.read", params);
+    }
+    auditList(params) {
+        return this.call("rigorix.audit.list", params);
+    }
+    auditSummary(params) {
+        return this.call("rigorix.audit.summary", params);
+    }
+    // ─── Templates ───────────────────────────────────────────────────────
+    templateList(params) {
+        return this.call("rigorix.template.list", params);
+    }
+    templateGet(params) {
+        return this.call("rigorix.template.get", params);
+    }
+    templateCreate(params) {
+        return this.call("rigorix.template.create", params);
+    }
+    templateValidate(params) {
+        return this.call("rigorix.template.validate", params);
+    }
+    // ─── Auth (device flow) ──────────────────────────────────────────────
+    authLogin(params) {
+        return this.call("rigorix.auth.login", params);
+    }
+    authStatus() {
+        return this.call("rigorix.auth.status", {});
+    }
+    authLogout() {
+        return this.call("rigorix.auth.logout", {});
+    }
+    // ─── Self-description / negotiation ──────────────────────────────────
+    usageGuide() {
+        return this.call("rigorix.usageGuide", {});
+    }
+    async version() {
+        const version = await this.call("rigorix.system.version", {});
+        this.checkVersion(version);
+        return version;
+    }
+    /** Verify the server's `api_version` is compatible with this client's major. */
+    checkVersion(version) {
+        const major = Number.parseInt(version.api_version.split(".")[0] ?? "", 10);
+        if (major !== CLIENT_API_MAJOR) {
+            throw new VersionMismatchError(version.api_version, CLIENT_API_MAJOR);
+        }
+    }
+}
+export { ClientError };

package/dist/src/error.d.ts

@@ -0,0 +1,49 @@
+/** Error taxonomy mapping (`schemas/api/errors.json`, ADR-0001 D6).
+ *
+ * `data.type` is the stable machine identifier. Every declared type maps to a
+ * distinct `ApiError.kind`; an unknown type falls through to `"unknown"` —
+ * never a throw. */
+export declare const API_ERROR_TYPES: readonly ["parse_error", "invalid_request", "method_not_found", "invalid_params", "internal_error", "not_authenticated", "insufficient_scope", "denied_by_sequence", "policy_violation", "approval_required", "identity_required", "budget_exhausted", "timeout", "api_error", "not_enabled"];
+export type ApiErrorType = (typeof API_ERROR_TYPES)[number];
+/** The stable `data.type` value for a typed error, or `"unknown"`. */
+export declare class ApiError extends Error {
+    readonly kind: ApiErrorType | "unknown";
+    readonly type: string;
+    readonly code?: number;
+    readonly data?: unknown;
+    constructor(type: string, message: string, code?: number, data?: unknown);
+    /** `data.rule_id`, when present (`denied_by_sequence`). */
+    get ruleId(): string | undefined;
+    /** `data.step`, when present (`denied_by_sequence`). */
+    get step(): string | undefined;
+}
+/** The JSON-RPC `error` object shape. */
+export interface RpcErrorShape {
+    code: number;
+    message: string;
+    data?: {
+        type?: string;
+        [key: string]: unknown;
+    };
+}
+/** Base class for every client-side failure. */
+export declare class ClientError extends Error {
+}
+/** The transport failed (network/IO or non-2xx). */
+export declare class TransportError extends ClientError {
+}
+/** A malformed JSON-RPC response (neither `result` nor `error`). */
+export declare class ProtocolError extends ClientError {
+}
+/** A JSON-RPC `error` object, mapped to the typed taxonomy. */
+export declare class JsonRpcError extends ClientError {
+    readonly rpc: RpcErrorShape;
+    constructor(rpc: RpcErrorShape);
+    get apiError(): ApiError;
+}
+/** The server's `api_version` is incompatible with this client's major. */
+export declare class VersionMismatchError extends ClientError {
+    readonly server: string;
+    readonly clientMajor: number;
+    constructor(server: string, clientMajor: number);
+}

package/dist/src/error.js

@@ -0,0 +1,83 @@
+/** Error taxonomy mapping (`schemas/api/errors.json`, ADR-0001 D6).
+ *
+ * `data.type` is the stable machine identifier. Every declared type maps to a
+ * distinct `ApiError.kind`; an unknown type falls through to `"unknown"` —
+ * never a throw. */
+export const API_ERROR_TYPES = [
+    "parse_error",
+    "invalid_request",
+    "method_not_found",
+    "invalid_params",
+    "internal_error",
+    "not_authenticated",
+    "insufficient_scope",
+    "denied_by_sequence",
+    "policy_violation",
+    "approval_required",
+    "identity_required",
+    "budget_exhausted",
+    "timeout",
+    "api_error",
+    "not_enabled",
+];
+/** The stable `data.type` value for a typed error, or `"unknown"`. */
+export class ApiError extends Error {
+    kind;
+    type;
+    code;
+    data;
+    constructor(type, message, code, data) {
+        super(`${type}: ${message}`);
+        this.name = "ApiError";
+        this.type = type;
+        this.kind = API_ERROR_TYPES.includes(type)
+            ? type
+            : "unknown";
+        this.code = code;
+        this.data = data;
+    }
+    /** `data.rule_id`, when present (`denied_by_sequence`). */
+    get ruleId() {
+        const value = this.data?.rule_id;
+        return typeof value === "string" ? value : undefined;
+    }
+    /** `data.step`, when present (`denied_by_sequence`). */
+    get step() {
+        const value = this.data?.step;
+        return typeof value === "string" ? value : undefined;
+    }
+}
+/** Base class for every client-side failure. */
+export class ClientError extends Error {
+}
+/** The transport failed (network/IO or non-2xx). */
+export class TransportError extends ClientError {
+}
+/** A malformed JSON-RPC response (neither `result` nor `error`). */
+export class ProtocolError extends ClientError {
+}
+/** A JSON-RPC `error` object, mapped to the typed taxonomy. */
+export class JsonRpcError extends ClientError {
+    rpc;
+    constructor(rpc) {
+        super(`json-rpc error ${rpc.code}: ${rpc.message}`);
+        this.rpc = rpc;
+        this.name = "JsonRpcError";
+    }
+    get apiError() {
+        const data = this.rpc.data;
+        const type = typeof data?.type === "string" ? data.type : "unknown";
+        return new ApiError(type, this.rpc.message, this.rpc.code, data);
+    }
+}
+/** The server's `api_version` is incompatible with this client's major. */
+export class VersionMismatchError extends ClientError {
+    server;
+    clientMajor;
+    constructor(server, clientMajor) {
+        super(`server apiVersion ${server} is incompatible with the client constraint (major ${clientMajor})`);
+        this.server = server;
+        this.clientMajor = clientMajor;
+        this.name = "VersionMismatchError";
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,10 @@
+/** rigorix-client (TypeScript) — protocol-only typed client for the frozen
+ * `rigorix.*` JSON-RPC catalog (ADR-0001). Governed flows only; no raw step
+ * execution; no engine dependency. */
+export * from "./auth.js";
+export * from "./catalog.js";
+export * from "./client.js";
+export * from "./error.js";
+export * from "./jsonrpc.js";
+export * from "./transport.js";
+export type * from "./types.js";

package/dist/src/index.js

@@ -0,0 +1,9 @@
+/** rigorix-client (TypeScript) — protocol-only typed client for the frozen
+ * `rigorix.*` JSON-RPC catalog (ADR-0001). Governed flows only; no raw step
+ * execution; no engine dependency. */
+export * from "./auth.js";
+export * from "./catalog.js";
+export * from "./client.js";
+export * from "./error.js";
+export * from "./jsonrpc.js";
+export * from "./transport.js";

package/dist/src/jsonrpc.d.ts

@@ -0,0 +1,23 @@
+/** JSON-RPC 2.0 framing (ADR-0001 D1): single requests, batch arrays, and
+ * notifications (requests with no `id`). */
+import type { RpcErrorShape } from "./error.js";
+export interface RpcRequest {
+    jsonrpc: "2.0";
+    method: string;
+    params?: unknown;
+    id?: number | string;
+}
+export interface RpcResponse {
+    jsonrpc?: string;
+    id?: number | string;
+    result?: unknown;
+    error?: RpcErrorShape;
+}
+/** A request expecting a response. */
+export declare function call(id: number | string, method: string, params?: unknown): RpcRequest;
+/** A notification — no `id`, no response expected. */
+export declare function notification(method: string, params?: unknown): RpcRequest;
+export declare function encode(request: RpcRequest): string;
+export declare function encodeBatch(requests: RpcRequest[]): string;
+export declare function decode<T = RpcResponse>(body: string): T;
+export declare function decodeBatch(body: string): RpcResponse[];

package/dist/src/jsonrpc.js

@@ -0,0 +1,22 @@
+/** JSON-RPC 2.0 framing (ADR-0001 D1): single requests, batch arrays, and
+ * notifications (requests with no `id`). */
+/** A request expecting a response. */
+export function call(id, method, params) {
+    return { jsonrpc: "2.0", method, params, id };
+}
+/** A notification — no `id`, no response expected. */
+export function notification(method, params) {
+    return { jsonrpc: "2.0", method, params };
+}
+export function encode(request) {
+    return JSON.stringify(request);
+}
+export function encodeBatch(requests) {
+    return JSON.stringify(requests);
+}
+export function decode(body) {
+    return JSON.parse(body);
+}
+export function decodeBatch(body) {
+    return JSON.parse(body);
+}

package/dist/src/transport.d.ts

@@ -0,0 +1,19 @@
+/** Transport seam — the crate depends on no HTTP framework. */
+export interface Transport {
+    /** POST a JSON-RPC body and return the raw response body. */
+    post(body: string): Promise<string>;
+}
+/** A `fetch`-based transport (Node 20+ has a global `fetch`). */
+export declare class FetchTransport implements Transport {
+    private readonly url;
+    private readonly headers;
+    constructor(url: string, headers?: Record<string, string>);
+    post(body: string): Promise<string>;
+}
+/** A test transport that records requests and replays queued responses. */
+export declare class MockTransport implements Transport {
+    private readonly responses;
+    readonly requests: string[];
+    constructor(responses?: string[]);
+    post(body: string): Promise<string>;
+}

package/dist/src/transport.js

@@ -0,0 +1,38 @@
+/** Transport seam — the crate depends on no HTTP framework. */
+import { TransportError } from "./error.js";
+/** A `fetch`-based transport (Node 20+ has a global `fetch`). */
+export class FetchTransport {
+    url;
+    headers;
+    constructor(url, headers = {}) {
+        this.url = url;
+        this.headers = headers;
+    }
+    async post(body) {
+        const response = await fetch(this.url, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...this.headers },
+            body,
+        });
+        if (!response.ok) {
+            throw new TransportError(`transport: HTTP ${response.status}`);
+        }
+        return response.text();
+    }
+}
+/** A test transport that records requests and replays queued responses. */
+export class MockTransport {
+    responses;
+    requests = [];
+    constructor(responses = []) {
+        this.responses = responses;
+    }
+    async post(body) {
+        this.requests.push(body);
+        const response = this.responses.shift();
+        if (response === undefined) {
+            throw new TransportError("mock transport: no queued response");
+        }
+        return response;
+    }
+}

package/dist/src/types.d.ts

@@ -0,0 +1,237 @@
+/** Typed request/result interfaces mirroring `schemas/api/catalog.json` `$defs`
+ * (ADR-0001). Field names match the frozen catalog exactly (snake_case). */
+export interface EmptyParams {
+}
+export interface PlanParams {
+    template_name: string;
+}
+export interface PlanResult {
+    template_name: string;
+    description: string;
+    version: string;
+    tags: string[];
+    graph: unknown;
+    constraints?: Constraints | null;
+    enforcement: unknown;
+}
+export interface Constraints {
+    max_tool_calls?: number | null;
+    max_tokens?: number | null;
+    max_duration_secs?: number | null;
+    blocked_tools?: string[];
+    extensions?: Record<string, string>;
+}
+export interface ValidatePlanParams {
+    plan: unknown;
+    identity?: unknown;
+}
+export interface ValidateResult {
+    valid: boolean;
+    warnings: string[];
+    errors: string[];
+    estimated_cost?: CostEstimate | null;
+}
+export interface CostEstimate {
+    estimated_tokens: number;
+    estimated_tool_calls: number;
+    estimated_cost_micro?: number | null;
+}
+export interface RunParams {
+    template_name: string;
+    execution_id?: string;
+    repository?: string;
+    author?: string;
+}
+export interface ExecuteParams {
+    plan?: unknown;
+    template_name?: string;
+    execution_id?: string;
+    repository?: string;
+    author?: string;
+}
+export interface ExecuteResult {
+    execution_id: string;
+    status: string;
+    steps: StepResult[];
+    duration_ms: number;
+    tokens_used?: number | null;
+    audit_uri: string;
+}
+export interface StepResult {
+    step_name: string;
+    success: boolean;
+    error?: string | null;
+    output?: unknown;
+    duration_ms: number;
+}
+export interface ApproveParams {
+    execution_id: string;
+    step_names: string[];
+    approver_id?: string;
+    authority?: string;
+    token_claims_ref?: string;
+}
+export interface ApproveResult {
+    execution_id: string;
+    approved_steps: string[];
+    not_found: string[];
+    still_pending: string[];
+    resumed: boolean;
+    message: string;
+    final_state?: string | null;
+}
+export interface CheckEnforcementResult {
+    active: boolean;
+    preset: string;
+    budget: BudgetStatus;
+    circuit_breakers: CircuitBreaker[];
+}
+export interface BudgetStatus {
+    tool_calls_total: number;
+    tool_calls_remaining: number;
+    tokens_total: number;
+    tokens_remaining: number;
+}
+export interface CircuitBreaker {
+    name: string;
+    is_tripped: boolean;
+    description: string;
+}
+export interface AuditReadParams {
+    execution_id: string;
+    format?: string;
+}
+export interface AuditReadResult {
+    execution_id: string;
+    status: string;
+    template_name?: string | null;
+    started_at: string;
+    completed_at: string;
+    duration_ms: number;
+    steps: StepResult[];
+    tokens_used?: number | null;
+    audit_uri: string;
+}
+export interface AuditListParams {
+    status?: string;
+    since?: string;
+    until?: string;
+    template?: string;
+    limit?: number;
+}
+export interface AuditListResult {
+    total_count: number;
+    audits: AuditListItem[];
+}
+export interface AuditListItem {
+    execution_id: string;
+    status: string;
+    template_name?: string | null;
+    started_at: string;
+    duration_ms: number;
+    audit_uri: string;
+}
+export interface AuditSummaryParams {
+    since?: string;
+    until?: string;
+}
+export interface AuditSummaryResult {
+    since: string;
+    until: string;
+    total_executions: number;
+    success_count: number;
+    failure_count: number;
+    success_rate: number;
+    total_duration_ms: number;
+    total_tokens?: number | null;
+    top_failures: TopFailure[];
+    top_templates: TopTemplate[];
+}
+export interface TopFailure {
+    description: string;
+    count: number;
+    template_name?: string | null;
+}
+export interface TopTemplate {
+    name: string;
+    count: number;
+    avg_duration_ms: number;
+}
+export interface TemplateListParams {
+    limit?: number;
+    search?: string;
+    tags?: string[];
+}
+export interface TemplateListResult {
+    templates: TemplateListItem[];
+}
+export interface TemplateListItem {
+    name: string;
+    description: string;
+    version: string;
+    tags: string[];
+    step_count: number;
+    updated_at: string;
+}
+export interface TemplateGetParams {
+    name: string;
+    format?: string;
+}
+export interface TemplateGetResult {
+    name: string;
+    description: string;
+    version: string;
+    tags: string[];
+    steps: unknown[];
+    constraints?: Constraints | null;
+    metadata?: Record<string, string> | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface TemplateCreateParams {
+    name: string;
+    plan: unknown;
+    overwrite?: boolean;
+}
+export interface TemplateCreateResult {
+    name: string;
+    path: string;
+    status: string;
+}
+export interface TemplateValidateParams {
+    plan: unknown;
+}
+export interface AuthLoginParams {
+    client_id?: string;
+    issuer?: string;
+}
+export interface AuthLoginResult {
+    status: string;
+    verification_uri: string;
+    user_code: string;
+    expires_in: number;
+}
+export interface AuthStatusResult {
+    status: string;
+    claim_summary?: ClaimSummary | null;
+    source: string;
+}
+export interface ClaimSummary {
+    subject: string;
+    issuer: string;
+    authority?: string | null;
+    expires_at?: string | null;
+}
+export interface AuthLogoutResult {
+    status: string;
+}
+export interface UsageGuideResult {
+    guide: string;
+}
+export interface VersionResult {
+    name: string;
+    engine_version: string;
+    api_version: string;
+    schemas: string[];
+    capabilities: string[];
+}

package/dist/src/types.js

@@ -0,0 +1,3 @@
+/** Typed request/result interfaces mirroring `schemas/api/catalog.json` `$defs`
+ * (ADR-0001). Field names match the frozen catalog exactly (snake_case). */
+export {};

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "rigorix-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Protocol-only typed client for the frozen rigorix.* JSON-RPC catalog — governed flows only, no raw step execution, no engine dependency.",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "files": ["dist/src", "README.md"],
+  "license": "Apache-2.0",
+  "author": "Arman Wolkenstein-Jalili and Rigorix contributors",
+  "keywords": ["rigorix", "jsonrpc", "client", "governance", "sdk"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/arman-jalili/rigorix-sdk.git",
+    "directory": "typescript-client"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test dist/test/*.test.js"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}