@kaironull/sdk 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+# @kaironull/sdk
+
+Node.js SDK for the [KairoNull](https://kaironull.com) Umbra Trust Protocol —
+capture AI decision events to a hash-chained, RFC3161-anchored evidence
+ledger, and verify records independently.
+
+Zero runtime dependencies. Uses native `fetch` (Node 18+).
+
+## Install
+
+```bash
+npm install @kaironull/sdk
+```
+
+## Quickstart
+
+```ts
+import { KairoNull } from '@kaironull/sdk'
+
+const client = new KairoNull({ apiKey: 'utp_live_...' }) // get a key at kaironull.com/get-access
+
+const result = await client.record({
+  pipelineId: 'credit-decisioning',
+  entryType: 'flag', // 'pass' | 'flag' | 'block' | 'escalate'
+  stageSlug: 'risk-review',
+  summary: 'Application flagged for manual review: DTI ratio 0.61 exceeds threshold',
+  trustScore: 0.42,
+  modelVersion: 'risk-model-v3.2',
+})
+
+console.log(result.entryHash)   // sha256 hex — share this with an auditor
+console.log(result.chainHeight) // position in your org's evidence chain
+```
+
+## Verify a record (no API key needed)
+
+```ts
+import { KairoNull } from '@kaironull/sdk'
+
+const client = new KairoNull() // public methods don't require a key
+const verified = await client.verify('95be8bb5253668bb898da34631cc3c9e...')
+
+if (verified.found) {
+  console.log(verified.record?.summary)
+  console.log('Anchored:', verified.anchor?.anchored)
+}
+```
+
+Anyone can verify a hash — auditors don't need credentials, an account, or
+access to your systems. This is also what powers the public widget at
+[kaironull.com/#verify](https://kaironull.com/#verify).
+
+## Check chain health
+
+```ts
+const status = await client.chainStatus()
+console.log(status.chainHeight, status.healthy)
+```
+
+Same data backing [kaironull.com/status](https://kaironull.com/status).
+
+## Export an evidence bundle
+
+```ts
+const bundle = await client.exportReport({
+  from: '2026-06-01T00:00:00Z',
+  to: '2026-07-01T00:00:00Z',
+})
+// bundle.entries, bundle.anchor — hand this to an auditor or regulator
+```
+
+## Revoke your key
+
+```ts
+await client.revokeKey('key-id-here') // the key used to auth this call is what's revoked
+```
+
+## Error handling
+
+```ts
+import { AuthenticationError, ValidationError, APIError } from '@kaironull/sdk'
+
+try {
+  await client.record({ ... })
+} catch (e) {
+  if (e instanceof ValidationError) {
+    // bad input — fix the call
+  } else if (e instanceof AuthenticationError) {
+    // missing/invalid/revoked key
+  } else if (e instanceof APIError) {
+    // anything else — e.statusCode has the HTTP status
+  }
+}
+```
+
+## Links
+
+- [Full API reference / quickstart](https://kaironull.com/quickstart)
+- [Get an API key](https://kaironull.com/get-access)
+- [Docs](https://kaironull.com/docs)
+- [Python SDK](https://pypi.org/project/kaironull/)
+
+## Status
+
+This SDK covers the full public API surface: `record`, `verify`,
+`chainStatus`, `exportReport`, `revokeKey`. It is a thin wrapper — every
+method maps directly to one REST call, matching the
+[quickstart](https://kaironull.com/quickstart) examples exactly.

package/dist/client.d.ts

@@ -0,0 +1,59 @@
+import type { ChainStatus, ExportReportOptions, RecordInput, RecordResult, RevokedKey, VerifyResult } from './types.js';
+export interface KairoNullOptions {
+    /** Your `utp_live_...` API key. Required for record(), revokeKey(), exportReport(). */
+    apiKey?: string;
+    /** Override the API host. Defaults to https://kaironull.com */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Defaults to 10000. */
+    timeoutMs?: number;
+}
+/**
+ * Client for the KairoNull Umbra Trust Protocol REST API.
+ *
+ * ```ts
+ * const client = new KairoNull({ apiKey: 'utp_live_...' })
+ * const result = await client.record({
+ *   pipelineId: 'credit-decisioning',
+ *   entryType: 'flag',
+ *   stageSlug: 'risk-review',
+ *   summary: 'Application flagged for manual review',
+ *   trustScore: 0.42,
+ * })
+ * ```
+ */
+export declare class KairoNull {
+    private readonly apiKey?;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(options?: KairoNullOptions);
+    private request;
+    private requireApiKey;
+    /**
+     * Record an AI decision event. Requires an API key.
+     * Maps to `POST /api/v1/records`.
+     */
+    record(input: RecordInput): Promise<RecordResult>;
+    /**
+     * Verify a record by its SHA-256 entry hash. Public — no API key required.
+     * Maps to `GET /api/v1/verify/:hash`.
+     */
+    verify(entryHash: string): Promise<VerifyResult>;
+    /**
+     * Get the current state of the evidence chain. Public — no API key required.
+     * Same data that powers https://kaironull.com/status.
+     * Maps to `GET /api/v1/chain/status`.
+     */
+    chainStatus(): Promise<ChainStatus>;
+    /**
+     * Revoke this client's own API key. Requires an API key — the key itself
+     * is the Bearer token and can only revoke itself.
+     * Maps to `DELETE /api/v1/keys/:id`.
+     */
+    revokeKey(keyId: string): Promise<RevokedKey>;
+    /**
+     * Export the full evidence bundle for offline audit or regulator handoff.
+     * Requires an API key. Maps to `GET /api/v1/reports`.
+     */
+    exportReport(options?: ExportReportOptions): Promise<Record<string, unknown>>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,WAAW,EACX,mBAAmB,EAEnB,WAAW,EACX,YAAY,EACZ,UAAU,EACV,YAAY,EACb,MAAM,YAAY,CAAA;AAMnB,MAAM,WAAW,gBAAgB;IAC/B,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;gBAEtB,OAAO,GAAE,gBAAqB;YAU5B,OAAO;IAiDrB,OAAO,CAAC,aAAa;IAcrB;;;OAGG;IACG,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAwCvD;;;OAGG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAuBtD;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC;IA0BzC;;;;OAIG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAkBnD;;;OAGG;IACG,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAQxF"}

package/dist/client.js

@@ -0,0 +1,208 @@
+import { APIError, AuthenticationError, ValidationError } from './errors.js';
+const DEFAULT_BASE_URL = 'https://kaironull.com';
+const HASH_RE = /^[0-9a-f]{64}$/;
+const VALID_ENTRY_TYPES = new Set(['pass', 'flag', 'block', 'escalate']);
+/**
+ * Client for the KairoNull Umbra Trust Protocol REST API.
+ *
+ * ```ts
+ * const client = new KairoNull({ apiKey: 'utp_live_...' })
+ * const result = await client.record({
+ *   pipelineId: 'credit-decisioning',
+ *   entryType: 'flag',
+ *   stageSlug: 'risk-review',
+ *   summary: 'Application flagged for manual review',
+ *   trustScore: 0.42,
+ * })
+ * ```
+ */
+export class KairoNull {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    constructor(options = {}) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+        this.timeoutMs = options.timeoutMs ?? 10_000;
+    }
+    // -------------------------------------------------------------------- //
+    // Internal request helper
+    // -------------------------------------------------------------------- //
+    async request(method, path, opts = {}) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (opts.params) {
+            for (const [k, v] of Object.entries(opts.params))
+                url.searchParams.set(k, v);
+        }
+        const headers = {};
+        if (opts.authToken)
+            headers.Authorization = `Bearer ${opts.authToken}`;
+        if (opts.body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers,
+                body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            throw new APIError(`Network error calling ${url}: ${err.message}`, 0);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        if (res.status === 401 || res.status === 403) {
+            throw new AuthenticationError((await errorMessage(res)) ?? 'Authentication failed');
+        }
+        if (res.status === 400) {
+            throw new ValidationError((await errorMessage(res)) ?? 'Invalid request');
+        }
+        if (res.status === 404) {
+            return isJson(res) ? (await res.json()) : {};
+        }
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new APIError((await errorMessage(res)) ?? `Request to ${path} failed`, res.status, text);
+        }
+        const text = await res.text();
+        return (text ? JSON.parse(text) : {});
+    }
+    requireApiKey() {
+        if (!this.apiKey) {
+            throw new AuthenticationError('This call requires an API key. Pass apiKey when constructing new KairoNull(), ' +
+                'or request one at https://kaironull.com/get-access');
+        }
+        return this.apiKey;
+    }
+    // -------------------------------------------------------------------- //
+    // Public methods
+    // -------------------------------------------------------------------- //
+    /**
+     * Record an AI decision event. Requires an API key.
+     * Maps to `POST /api/v1/records`.
+     */
+    async record(input) {
+        if (!VALID_ENTRY_TYPES.has(input.entryType)) {
+            throw new ValidationError(`entryType must be one of pass, flag, block, escalate — got ${input.entryType}`);
+        }
+        if (input.trustScore !== undefined && (input.trustScore < 0 || input.trustScore > 1)) {
+            throw new ValidationError('trustScore must be between 0 and 1');
+        }
+        const body = {
+            pipeline_id: input.pipelineId,
+            entry_type: input.entryType,
+            stage_slug: input.stageSlug,
+            summary: input.summary,
+        };
+        if (input.detail !== undefined)
+            body.detail = input.detail;
+        if (input.trustScore !== undefined)
+            body.trust_score = input.trustScore;
+        if (input.modelVersion !== undefined)
+            body.model_version = input.modelVersion;
+        if (input.dataSources !== undefined)
+            body.data_sources = input.dataSources;
+        if (input.inputPayload !== undefined)
+            body.input_payload = input.inputPayload;
+        if (input.systemState !== undefined)
+            body.system_state = input.systemState;
+        const data = await this.request('POST', '/api/v1/records', { authToken: this.requireApiKey(), body });
+        return {
+            id: data.id,
+            entryHash: data.entry_hash,
+            prevHash: data.prev_hash,
+            writtenAt: data.written_at,
+            chainHeight: data.chain_height ?? 0,
+        };
+    }
+    /**
+     * Verify a record by its SHA-256 entry hash. Public — no API key required.
+     * Maps to `GET /api/v1/verify/:hash`.
+     */
+    async verify(entryHash) {
+        const hash = entryHash.toLowerCase().trim();
+        if (!HASH_RE.test(hash)) {
+            throw new ValidationError('entryHash must be a 64-character hex SHA-256 string');
+        }
+        const data = await this.request('GET', `/api/v1/verify/${hash}`);
+        const anchor = data.anchor
+            ? {
+                anchored: data.anchor.anchored,
+                anchoredAt: data.anchor.anchored_at,
+                rootHash: data.anchor.root_hash,
+            }
+            : undefined;
+        return { found: data.found ?? false, record: data.record, anchor };
+    }
+    /**
+     * Get the current state of the evidence chain. Public — no API key required.
+     * Same data that powers https://kaironull.com/status.
+     * Maps to `GET /api/v1/chain/status`.
+     */
+    async chainStatus() {
+        const data = await this.request('GET', '/api/v1/chain/status');
+        const lastAnchor = data.last_anchor
+            ? {
+                rootHash: data.last_anchor.root_hash,
+                anchoredAt: data.last_anchor.anchored_at,
+                entryCount: data.last_anchor.entry_count ?? 0,
+            }
+            : undefined;
+        return {
+            chainHeight: data.chain_height ?? 0,
+            latestEntryHash: data.latest_entry_hash,
+            latestWrittenAt: data.latest_written_at,
+            healthy: data.healthy ?? false,
+            lastAnchor,
+        };
+    }
+    /**
+     * Revoke this client's own API key. Requires an API key — the key itself
+     * is the Bearer token and can only revoke itself.
+     * Maps to `DELETE /api/v1/keys/:id`.
+     */
+    async revokeKey(keyId) {
+        const data = await this.request('DELETE', `/api/v1/keys/${keyId}`, { authToken: this.requireApiKey() });
+        return {
+            keyId: data.key_id,
+            orgId: data.org_id,
+            label: data.label,
+            revokedAt: data.revoked_at,
+            status: data.status,
+        };
+    }
+    /**
+     * Export the full evidence bundle for offline audit or regulator handoff.
+     * Requires an API key. Maps to `GET /api/v1/reports`.
+     */
+    async exportReport(options = {}) {
+        const params = {};
+        if (options.from)
+            params.from = options.from;
+        if (options.to)
+            params.to = options.to;
+        if (options.limit)
+            params.limit = String(options.limit);
+        return this.request('GET', '/api/v1/reports', { authToken: this.requireApiKey(), params });
+    }
+}
+function isJson(res) {
+    return (res.headers.get('Content-Type') ?? '').includes('application/json');
+}
+async function errorMessage(res) {
+    if (!isJson(res))
+        return undefined;
+    try {
+        const payload = (await res.json());
+        return payload.error;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+/** Errors raised by the KairoNull SDK. */
+export declare class KairoNullError extends Error {
+    constructor(message: string);
+}
+/** Missing, invalid, or revoked API key (HTTP 401/403). */
+export declare class AuthenticationError extends KairoNullError {
+    constructor(message: string);
+}
+/** Request body failed validation, client-side or server-side (HTTP 400). */
+export declare class ValidationError extends KairoNullError {
+    constructor(message: string);
+}
+/** Any other non-2xx response from the KairoNull API. */
+export declare class APIError extends KairoNullError {
+    readonly statusCode: number;
+    readonly responseBody: string;
+    constructor(message: string, statusCode: number, responseBody?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAE1C,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,2DAA2D;AAC3D,qBAAa,mBAAoB,SAAQ,cAAc;gBACzC,OAAO,EAAE,MAAM;CAI5B;AAED,6EAA6E;AAC7E,qBAAa,eAAgB,SAAQ,cAAc;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAED,yDAAyD;AACzD,qBAAa,QAAS,SAAQ,cAAc;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;gBAEjB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,SAAK;CAMnE"}

package/dist/errors.js

@@ -0,0 +1,33 @@
+/** Errors raised by the KairoNull SDK. */
+export class KairoNullError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'KairoNullError';
+    }
+}
+/** Missing, invalid, or revoked API key (HTTP 401/403). */
+export class AuthenticationError extends KairoNullError {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthenticationError';
+    }
+}
+/** Request body failed validation, client-side or server-side (HTTP 400). */
+export class ValidationError extends KairoNullError {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+/** Any other non-2xx response from the KairoNull API. */
+export class APIError extends KairoNullError {
+    statusCode;
+    responseBody;
+    constructor(message, statusCode, responseBody = '') {
+        super(`${message} (HTTP ${statusCode})`);
+        this.name = 'APIError';
+        this.statusCode = statusCode;
+        this.responseBody = responseBody;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAE1C,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;IAC9B,CAAC;CACF;AAED,2DAA2D;AAC3D,MAAM,OAAO,mBAAoB,SAAQ,cAAc;IACrD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACnC,CAAC;CACF;AAED,6EAA6E;AAC7E,MAAM,OAAO,eAAgB,SAAQ,cAAc;IACjD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;IAC/B,CAAC;CACF;AAED,yDAAyD;AACzD,MAAM,OAAO,QAAS,SAAQ,cAAc;IACjC,UAAU,CAAQ;IAClB,YAAY,CAAQ;IAE7B,YAAY,OAAe,EAAE,UAAkB,EAAE,YAAY,GAAG,EAAE;QAChE,KAAK,CAAC,GAAG,OAAO,UAAU,UAAU,GAAG,CAAC,CAAA;QACxC,IAAI,CAAC,IAAI,GAAG,UAAU,CAAA;QACtB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;QAC5B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;IAClC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * KairoNull Node.js SDK
+ *
+ * A thin client for the Umbra Trust Protocol (UTP) REST API — record AI
+ * decisions to a hash-chained, RFC3161-anchored evidence ledger, and verify
+ * records independently.
+ *
+ * ```ts
+ * import { KairoNull } from '@kaironull/sdk'
+ *
+ * const client = new KairoNull({ apiKey: 'utp_live_...' })
+ *
+ * const result = await client.record({
+ *   pipelineId: 'credit-decisioning',
+ *   entryType: 'flag',
+ *   stageSlug: 'risk-review',
+ *   summary: 'Application flagged for manual review: DTI ratio 0.61 exceeds threshold',
+ *   trustScore: 0.42,
+ * })
+ * console.log(result.entryHash)
+ *
+ * const verified = await client.verify(result.entryHash)
+ * console.log(verified.found)
+ * ```
+ */
+export { KairoNull } from './client.js';
+export type { KairoNullOptions } from './client.js';
+export { KairoNullError, AuthenticationError, ValidationError, APIError } from './errors.js';
+export type { EntryType, RecordInput, RecordResult, VerifyResult, AnchorInfo, ChainStatus, LastAnchor, RevokedKey, ExportReportOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC5F,YAAY,EACV,SAAS,EACT,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,WAAW,EACX,UAAU,EACV,UAAU,EACV,mBAAmB,GACpB,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,28 @@
+/**
+ * KairoNull Node.js SDK
+ *
+ * A thin client for the Umbra Trust Protocol (UTP) REST API — record AI
+ * decisions to a hash-chained, RFC3161-anchored evidence ledger, and verify
+ * records independently.
+ *
+ * ```ts
+ * import { KairoNull } from '@kaironull/sdk'
+ *
+ * const client = new KairoNull({ apiKey: 'utp_live_...' })
+ *
+ * const result = await client.record({
+ *   pipelineId: 'credit-decisioning',
+ *   entryType: 'flag',
+ *   stageSlug: 'risk-review',
+ *   summary: 'Application flagged for manual review: DTI ratio 0.61 exceeds threshold',
+ *   trustScore: 0.42,
+ * })
+ * console.log(result.entryHash)
+ *
+ * const verified = await client.verify(result.entryHash)
+ * console.log(verified.found)
+ * ```
+ */
+export { KairoNull } from './client.js';
+export { KairoNullError, AuthenticationError, ValidationError, APIError } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEvC,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+/** Typed response shapes for the KairoNull SDK. */
+export type EntryType = 'pass' | 'flag' | 'block' | 'escalate';
+export interface RecordInput {
+    pipelineId: string;
+    entryType: EntryType;
+    stageSlug: string;
+    summary: string;
+    detail?: Record<string, unknown>;
+    trustScore?: number;
+    modelVersion?: string;
+    dataSources?: string[];
+    inputPayload?: Record<string, unknown>;
+    systemState?: Record<string, unknown>;
+}
+/** Response from client.record() — POST /api/v1/records */
+export interface RecordResult {
+    id: string;
+    entryHash: string;
+    prevHash: string;
+    writtenAt: string;
+    chainHeight: number;
+}
+/** RFC3161 anchor coverage for a ledger entry. */
+export interface AnchorInfo {
+    anchored: boolean;
+    anchoredAt?: string;
+    rootHash?: string;
+}
+/** Response from client.verify() — GET /api/v1/verify/:hash */
+export interface VerifyResult {
+    found: boolean;
+    record?: Record<string, unknown>;
+    anchor?: AnchorInfo;
+}
+export interface LastAnchor {
+    rootHash: string;
+    anchoredAt: string;
+    entryCount: number;
+}
+/** Response from client.chainStatus() — GET /api/v1/chain/status */
+export interface ChainStatus {
+    chainHeight: number;
+    latestEntryHash: string | null;
+    latestWrittenAt: string | null;
+    healthy: boolean;
+    lastAnchor?: LastAnchor;
+}
+/** Response from client.revokeKey() — DELETE /api/v1/keys/:id */
+export interface RevokedKey {
+    keyId: string;
+    orgId: string;
+    label: string;
+    revokedAt: string;
+    status: string;
+}
+export interface ExportReportOptions {
+    from?: string;
+    to?: string;
+    limit?: number;
+}
+//# 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":"AAAA,mDAAmD;AAEnD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAA;AAE9D,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,SAAS,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACtC;AAED,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,OAAO,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,MAAM,CAAC,EAAE,UAAU,CAAA;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,CAAC,EAAE,UAAU,CAAA;CACxB;AAED,iEAAiE;AACjE,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;CACf"}

package/dist/types.js

@@ -0,0 +1,3 @@
+/** Typed response shapes for the KairoNull SDK. */
+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,mDAAmD"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@kaironull/sdk",
+  "version": "0.1.0",
+  "description": "Node.js SDK for the KairoNull Umbra Trust Protocol — AI decision evidence capture and verification",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai-governance",
+    "audit-trail",
+    "evidence",
+    "eu-ai-act",
+    "compliance"
+  ],
+  "author": "KairoNull <dane@kaironull.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BlackFlag-Digital/PropertyVR.git",
+    "directory": "kairon-null/sdk/node"
+  },
+  "homepage": "https://kaironull.com",
+  "bugs": {
+    "url": "https://github.com/BlackFlag-Digital/PropertyVR/issues"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}