@intentproof/sdk 0.1.4 → 0.2.1

package/dist/exporter.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Posts signed ExecutionEvents to a configured ingest URL when set.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpExporter = void 0;
+exports.resolveIngestURL = resolveIngestURL;
+exports.ingestRequestHeaders = ingestRequestHeaders;
+const DEFAULT_LOCAL_INGEST_URL = 'http://127.0.0.1:9787/v1/events';
+function resolveIngestURL(explicit) {
+    const raw = (explicit ?? process.env.INTENTPROOF_INGEST_URL ?? '').trim();
+    if (raw) {
+        return normalizeIngestURL(raw);
+    }
+    if (process.env.INTENTPROOF_USE_LOCAL_INGEST === '1') {
+        return DEFAULT_LOCAL_INGEST_URL;
+    }
+    return null;
+}
+function ingestRequestHeaders() {
+    const headers = { 'Content-Type': 'application/json' };
+    const token = (process.env.INTENTPROOF_INGEST_TOKEN ?? '').trim();
+    if (token) {
+        headers.Authorization = `Bearer ${token}`;
+    }
+    return headers;
+}
+function normalizeIngestURL(raw) {
+    const trimmed = raw.trim().replace(/\/+$/, '');
+    if (trimmed.endsWith('/v1/events')) {
+        return trimmed;
+    }
+    return trimmed + '/v1/events';
+}
+class HttpExporter {
+    ingestURL;
+    pending = new Set();
+    constructor(ingestURL) {
+        this.ingestURL = ingestURL;
+    }
+    enqueue(event) {
+        const body = JSON.stringify(event);
+        const task = fetch(this.ingestURL, {
+            method: 'POST',
+            headers: ingestRequestHeaders(),
+            body,
+        })
+            .then(async (res) => {
+            if (res.status === 202 || res.status === 200) {
+                return;
+            }
+            const text = await res.text().catch(() => '');
+            throw new Error(`ingest POST ${res.status}${text ? `: ${text.slice(0, 200)}` : ''}`);
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`[intentproof] ingest export failed: ${msg}`);
+        });
+        this.pending.add(task);
+        void task.finally(() => {
+            this.pending.delete(task);
+        });
+    }
+    async flush() {
+        await Promise.all([...this.pending]);
+    }
+}
+exports.HttpExporter = HttpExporter;

package/dist/index.d.ts

@@ -1,524 +1,3 @@
-import { ValidateFunction } from 'ajv';
-
-/**
- * This file was automatically generated by json-schema-to-typescript.
- * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
- * and run json-schema-to-typescript to regenerate this file.
- */
-interface IntentProofRuntimeConfigV1 {
-    /**
-     * Config document version; MUST be 1 for this schema.
-     */
-    version?: 1;
-    defaultWrapOptions?: IntentProofWrapOptionsV1$1;
-    /**
-     * Ordered list of exporter identifiers or inline hooks (SDK-defined encoding).
-     */
-    exporters?: {
-        /**
-         * Exporter kind; custom MUST include implementation-specific fields.
-         */
-        type: "console" | "http" | "otel" | "custom";
-        /**
-         * Required for http exporters when used.
-         */
-        endpoint?: string;
-        /**
-         * Optional HTTP headers for http exporters.
-         */
-        headers?: {
-            [k: string]: string;
-        };
-        /**
-         * When true, exporter failures MUST NOT change user-visible outcomes.
-         */
-        failOpen?: boolean;
-        [k: string]: unknown;
-    }[];
-    correlation?: {
-        /**
-         * HTTP header used for inbound correlation extraction when applicable.
-         */
-        headerName?: string;
-        /**
-         * When true, SDK generates a UUID when no correlation is active.
-         */
-        generateOnMissing?: boolean;
-    };
-    serialization?: {
-        /**
-         * Maximum object graph depth for input/output capture.
-         */
-        maxDepth?: number;
-        /**
-         * Maximum serialized string length for any single field.
-         */
-        maxStringLength?: number;
-        /**
-         * Case-insensitive key names to replace with [REDACTED] in captured objects.
-         */
-        redactKeys?: string[];
-    };
-}
-/**
- * Process-wide defaults merged under per-wrap options.
- */
-interface IntentProofWrapOptionsV1$1 {
-    /**
-     * Default natural-language intent for wrapped executions when the call site does not override it.
-     */
-    intent?: string;
-    /**
-     * Default operation identifier (often dotted like vendor.service.method); SDKs MAY derive from the callable when omitted.
-     */
-    action?: string;
-    /**
-     * When false, inputs MUST be serialized as an empty object {}.
-     */
-    captureInputs?: boolean;
-    /**
-     * When false and status is ok, output MUST be null.
-     */
-    captureOutput?: boolean;
-    /**
-     * When true, failures MUST populate error; when false with captureOutput semantics, see semantics/wrap_behavior.md.
-     */
-    captureError?: boolean;
-    /**
-     * When false, error.stack MUST be null on emitted events.
-     */
-    captureStack?: boolean;
-    /**
-     * When true, nested wraps inherit the active correlationId.
-     */
-    propagateCorrelation?: boolean;
-    /**
-     * Static attributes merged into each emitted ExecutionEvent.attributes.
-     */
-    attributes?: {
-        [k: string]: string | number | boolean | null;
-    };
-    /**
-     * Maximum time an exporter hook may block the wrap boundary; 0 means SDK default.
-     */
-    exporterTimeoutMs?: number;
-}
-
-/**
- * This file was automatically generated by json-schema-to-typescript.
- * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
- * and run json-schema-to-typescript to regenerate this file.
- */
-type IntentProofExecutionEventV1 = {
-    [k: string]: unknown;
-} & {
-    /**
-     * Stable unique identifier for this execution record.
-     */
-    id: string;
-    /**
-     * Natural-language description of what the user or caller was trying to achieve (often a full sentence or question). No fixed grammar; SHOULD stay human-readable in logs and UIs.
-     */
-    intent: string;
-    /**
-     * Stable identifier for the concrete operation. Many systems use hierarchical dotted names (e.g. vendor.resource.operation); REST paths, RPC names, or other conventions are allowed. The schema does not constrain the format.
-     */
-    action: string;
-    /**
-     * Terminal execution status.
-     */
-    status: "ok" | "error";
-    /**
-     * Captured call inputs. Values MUST be JSON-serializable (see semantics/serialization_rules.md).
-     */
-    inputs: {
-        [k: string]: unknown;
-    };
-    /**
-     * Captured return value when status is ok, or optional captured value when captureError allows output on failure.
-     */
-    output?: null | boolean | number | string | JsonValue[] | {
-        [k: string]: JsonValue;
-    };
-    error?: ExecutionError;
-    /**
-     * RFC 3339 / ISO 8601 instant when execution started.
-     */
-    startedAt: string;
-    /**
-     * RFC 3339 / ISO 8601 instant when execution completed.
-     */
-    completedAt: string;
-    /**
-     * Wall-clock duration in milliseconds between startedAt and completedAt.
-     */
-    durationMs: number;
-    /**
-     * Optional cross-cutting identifier for distributed tracing. MUST be trimmed and non-empty when present.
-     */
-    correlationId?: string;
-    /**
-     * Flat primitive key/value metadata attached to the event.
-     */
-    attributes?: {
-        [k: string]: string | number | boolean | null;
-    };
-};
-/**
- * Any JSON-serializable value per semantics/serialization_rules.md.
- */
-type JsonValue = null | boolean | number | string | JsonValue[] | {
-    [k: string]: JsonValue;
-};
-/**
- * Structured error when status is error.
- */
-interface ExecutionError {
-    /**
-     * Exception or error type name (e.g. Error, TypeError).
-     */
-    name: string;
-    /**
-     * Human-readable error message (may be empty string if the runtime provides none).
-     */
-    message: string;
-    /**
-     * Optional stable machine-readable code.
-     */
-    code?: string;
-    /**
-     * Optional stringified stack trace; null when stacks are suppressed.
-     */
-    stack?: string | null;
-    cause?: ExecutionError1;
-}
-/**
- * Optional chained cause; MUST conform to ExecutionError when present.
- */
-interface ExecutionError1 {
-    /**
-     * Exception or error type name (e.g. Error, TypeError).
-     */
-    name: string;
-    /**
-     * Human-readable error message (may be empty string if the runtime provides none).
-     */
-    message: string;
-    /**
-     * Optional stable machine-readable code.
-     */
-    code?: string;
-    /**
-     * Optional stringified stack trace; null when stacks are suppressed.
-     */
-    stack?: string | null;
-    cause?: ExecutionError1;
-}
-
-/**
- * This file was automatically generated by json-schema-to-typescript.
- * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
- * and run json-schema-to-typescript to regenerate this file.
- */
-interface IntentProofWrapOptionsV1 {
-    /**
-     * Default natural-language intent for wrapped executions when the call site does not override it.
-     */
-    intent?: string;
-    /**
-     * Default operation identifier (often dotted like vendor.service.method); SDKs MAY derive from the callable when omitted.
-     */
-    action?: string;
-    /**
-     * When false, inputs MUST be serialized as an empty object {}.
-     */
-    captureInputs?: boolean;
-    /**
-     * When false and status is ok, output MUST be null.
-     */
-    captureOutput?: boolean;
-    /**
-     * When true, failures MUST populate error; when false with captureOutput semantics, see semantics/wrap_behavior.md.
-     */
-    captureError?: boolean;
-    /**
-     * When false, error.stack MUST be null on emitted events.
-     */
-    captureStack?: boolean;
-    /**
-     * When true, nested wraps inherit the active correlationId.
-     */
-    propagateCorrelation?: boolean;
-    /**
-     * Static attributes merged into each emitted ExecutionEvent.attributes.
-     */
-    attributes?: {
-        [k: string]: string | number | boolean | null;
-    };
-    /**
-     * Maximum time an exporter hook may block the wrap boundary; 0 means SDK default.
-     */
-    exporterTimeoutMs?: number;
-}
-
-/**
- * Public types for the SDK.
- *
- * Wire shapes (`ExecutionEvent`, `ExecutionError`, JSON `IntentProofConfig` subset) are generated from
- * `intentproof-spec` JSON Schemas — see `src/generated/`. Regenerate: `npm run generate:types -w @intentproof/sdk`.
- * `WrapOptions` adds TypeScript-only capture callbacks and snapshot options; it is not identical to the
- * JSON `wrap_options` schema (see `IntentProofWrapOptionsV1` for the schema flags).
- */
-
-type ExecutionStatus = IntentProofExecutionEventV1["status"];
-/** Wire error payload — same fields as the normative `ExecutionError` object in the JSON Schema. */
-type ExecutionErrorSnapshot = Readonly<ExecutionError>;
-/** One record per wrapped invocation; identical to the `execution_event` v1 schema shape. */
-type ExecutionEvent = Readonly<IntentProofExecutionEventV1>;
-/**
- * Event fields built in {@link import("./client.js").IntentProofClient.wrap} before status, completion
- * time, `output`, and `error` are set. Declared with `Pick` so it stays aligned with the generated
- * wire type (avoids `Omit` on the schema’s index-signature intersection).
- */
-type ExecutionEventBase = Pick<IntentProofExecutionEventV1, "id" | "intent" | "action" | "inputs" | "startedAt"> & Partial<Pick<IntentProofExecutionEventV1, "correlationId" | "attributes">>;
-interface Exporter {
-    /** Must not throw synchronously; async exporters may return a Promise. */
-    export(event: ExecutionEvent): void | Promise<void>;
-    /** Wait until async side-effects are idle (optional). */
-    flush?(): void | Promise<void>;
-    /** Stop accepting work and drain (optional). */
-    shutdown?(): void | Promise<void>;
-}
-interface SerializeOptions {
-    /** Max object nesting when snapshotting (default 6). */
-    maxDepth?: number;
-    /** Max enumerable own keys per object (default 50). */
-    maxKeys?: number;
-    /**
-     * Own-property keys to replace with `[REDACTED]` (case-insensitive exact match).
-     * Nested objects are walked recursively.
-     */
-    redactKeys?: string[];
-    /** Truncate string primitives longer than this (default unlimited). */
-    maxStringLength?: number;
-}
-/**
- * Call-site `wrap` options. Includes snapshot tuning plus TypeScript-only `capture*` callbacks.
- * For the JSON `wrap_options` document shape (booleans, attributes, etc.), see {@link IntentProofWrapOptionsV1}.
- */
-interface WrapOptions extends SerializeOptions {
-    /** Non-empty after trim; enforced at runtime in {@link import("./client.js").assertWrapOptionsShape}. */
-    intent: string;
-    /** Non-empty after trim; enforced at runtime in {@link import("./client.js").assertWrapOptionsShape}. */
-    action: string;
-    /** Non-empty after trim when set; enforced at runtime. Otherwise uses active context. */
-    correlationId?: string;
-    /** Extra dimensions on the emitted event. */
-    attributes?: Readonly<Record<string, string | number | boolean>>;
-    captureInput?: (args: unknown[]) => unknown;
-    captureOutput?: (result: unknown) => unknown;
-    captureError?: (error: unknown) => unknown;
-    /**
-     * When false, omit `error.stack` from recorded failures (reduces path/log leakage).
-     * Overrides {@link IntentProofConfig.includeErrorStack} for this wrap only.
-     */
-    includeErrorStack?: boolean;
-}
-type SchemaConfigFields = Partial<Pick<IntentProofRuntimeConfigV1, "version" | "defaultWrapOptions" | "correlation" | "serialization">>;
-/**
- * Runtime SDK configuration. `exporters` are live class instances; all other fields that appear in
- * `intentproof_config` JSON are taken from the generated {@link IntentProofRuntimeConfigV1} shape.
- */
-type IntentProofConfig = {
-    exporters?: Exporter[];
-    /** Invoked when an exporter throws synchronously or rejects. Defaults to `console.error` when unset. */
-    onExporterError?: (error: unknown, event: ExecutionEvent) => void;
-    /** Default attributes merged into every event (e.g. service, env). */
-    defaultAttributes?: Readonly<Record<string, string | number | boolean>>;
-    /**
-     * When false, omit error stack traces from export payloads (default true).
-     * Prefer false in production unless you operate a locked-down ingest pipeline.
-     */
-    includeErrorStack?: boolean;
-} & SchemaConfigFields;
-
-/**
- * Validates a correlation id: non-empty string after trim (same as `WrapOptions.correlationId` /
- * {@link assertWrapOptionsShape}). Used by {@link runWithCorrelationId}.
- */
-declare function assertCorrelationId(id: unknown): asserts id is string;
-/** Active correlation id from async context, if any. */
-declare function getCorrelationId(): string | undefined;
-/**
- * Run `fn` with an explicit `correlationId` in async context. The id must be a non-empty string
- * after trim ({@link assertCorrelationId}) — the parameter name implies a caller-supplied id.
- */
-declare function runWithCorrelationId<T>(correlationId: string, fn: () => T): T;
-/** Runtime validation for {@link IntentProofClient.wrap} options. */
-declare function assertWrapOptionsShape(options: WrapOptions): void;
-declare class IntentProofClient {
-    private exporters;
-    private onExporterError;
-    private defaultAttributes;
-    private includeErrorStack;
-    constructor(config?: IntentProofConfig);
-    configure(config: IntentProofConfig): void;
-    /**
-     * Await optional {@link Exporter.flush} on each exporter (parallel).
-     * Used for graceful shutdown or tests.
-     */
-    flush(): Promise<void>;
-    /**
-     * {@link Exporter.shutdown} when present, otherwise {@link Exporter.flush}.
-     */
-    shutdown(): Promise<void>;
-    /** Read active correlation id (AsyncLocalStorage). */
-    getCorrelationId(): string | undefined;
-    /**
-     * Run `fn` with a generated correlation id for nested `wrap` calls (callers do not supply an id).
-     */
-    withCorrelation<T>(fn: () => T): T;
-    /**
-     * Run `fn` under an optional inbound `correlationId`. Non-empty after trim uses that id;
-     * empty or whitespace-only values generate a UUID instead (e.g. missing request header).
-     * To require a validated, non-blank id, use {@link runWithCorrelationId}.
-     */
-    withCorrelation<T>(correlationId: string, fn: () => T): T;
-    /**
-     * Wrap a function to emit one `ExecutionEvent` per invocation (sync or async).
-     */
-    wrap<A extends unknown[], R>(options: WrapOptions, fn: (...args: A) => R): (...args: A) => R;
-    private handleAsync;
-    private emitComplete;
-    private dispatch;
-}
-declare function getIntentProofClient(): IntentProofClient;
-
-/** JSON-safe value for `ExecutionEvent` inputs/output (depth/key limits, optional redaction). */
-declare function snapshot(value: unknown, options?: SerializeOptions): unknown;
-
-interface MemoryExporterOptions {
-    /** Keep at most this many recent events (default 1000). Must be a finite number >= 1. */
-    maxEvents?: number;
-}
-/**
- * Default exporter: ring buffer in memory for debugging and tests.
- */
-declare class MemoryExporter implements Exporter {
-    private readonly maxEvents;
-    private readonly events;
-    constructor(options?: MemoryExporterOptions);
-    export(event: ExecutionEvent): void;
-    /** Mutable snapshot for inspection — newest last. */
-    getEvents(): readonly ExecutionEvent[];
-    clear(): void;
-    flush(): Promise<void>;
-}
-
-interface HttpExporterOptions {
-    url: string;
-    method?: string;
-    headers?: Record<string, string>;
-    /** Serialize event for wire format (default JSON body). */
-    body?: (event: ExecutionEvent) => string;
-    /**
-     * When true, await each request (blocks until HTTP completes). Default false.
-     */
-    awaitEach?: boolean;
-    /** Abort the request after this many milliseconds (global `AbortSignal.timeout`). */
-    timeoutMs?: number;
-    onError?: (error: unknown, event: ExecutionEvent) => void;
-}
-/**
- * POST execution events as JSON. Uses global `fetch` (Node 18+).
- * Fire-and-forget by default to avoid slowing callers.
- */
-declare class HttpExporter implements Exporter {
-    private readonly url;
-    private readonly method;
-    private readonly headers;
-    private readonly body;
-    private readonly awaitEach;
-    private readonly timeoutMs?;
-    private readonly onError?;
-    private readonly inFlight;
-    private closed;
-    constructor(options: HttpExporterOptions);
-    private track;
-    export(event: ExecutionEvent): void | Promise<void>;
-    /** Waits until every started request has settled (success or failure). */
-    flush(): Promise<void>;
-    /** Stops accepting new events and waits for in-flight requests to finish. */
-    shutdown(): Promise<void>;
-}
-
-type QueueOverflowStrategy = "drop-newest" | "drop-oldest";
-interface BoundedQueueExporterOptions {
-    /** Downstream exporter (often {@link import("./http.js").HttpExporter}). */
-    exporter: Exporter;
-    /** Maximum concurrent async exports to the inner exporter (default `4`). */
-    maxConcurrent?: number;
-    /**
-     * Maximum **queued** events waiting for a worker slot (default `1000`).
-     * Use `0` for unlimited backlog (not recommended under sustained overload).
-     */
-    maxQueue?: number;
-    /** How to handle overflow when the queue is full (default `drop-newest`). */
-    strategy?: QueueOverflowStrategy;
-    onDrop?: (event: ExecutionEvent, reason: string) => void;
-    onInnerError?: (error: unknown, event: ExecutionEvent) => void;
-}
-/**
- * Bounded concurrency + backlog for async-heavy exporters.
- * Sync inner exporters run on the microtask queue and still respect {@link maxConcurrent}.
- */
-declare class BoundedQueueExporter implements Exporter {
-    private readonly inner;
-    private readonly maxConcurrent;
-    private readonly maxQueue;
-    private readonly strategy;
-    private readonly onDrop?;
-    private readonly onInnerError?;
-    private readonly queue;
-    private active;
-    /** When false, {@link export} drops events with reason `shutdown`; queued work still drains. */
-    private accepting;
-    private idleResolvers;
-    constructor(options: BoundedQueueExporterOptions);
-    export(event: ExecutionEvent): void;
-    private pump;
-    private runInner;
-    private resolveIdleWaitersIfNeeded;
-    /** Resolves when the queue is empty and no inner export is in flight. */
-    flush(): Promise<void>;
-    /**
-     * Stops accepting new events; does **not** drop items already in the queue—
-     * {@link flush} waits until queued and in-flight work finishes.
-     */
-    shutdown(): Promise<void>;
-}
-
-/** Compiled validator for `execution_event` v1 (wire / export shape, camelCase keys). */
-declare const validateExecutionEvent: ValidateFunction;
-/** Compiled validator for `wrap_options` v1. */
-declare const validateWrapOptions: ValidateFunction;
-/** Compiled validator for `intentproof_config` v1 (runtime JSON document subset). */
-declare const validateIntentProofConfig: ValidateFunction;
-/**
- * Ensures an execution record matches the pinned `execution_event` schema (throws on failure).
- */
-declare function assertValidExecutionEventWire(data: unknown): void;
-
-/**
- * @packageDocumentation
- * Structured `ExecutionEvent` emission for verification / ingest pipelines.
- */
-
-declare const VERSION: string;
-
-/** Default singleton — same instance as `getIntentProofClient()`. */
-declare const client: IntentProofClient;
-/** Isolated client instance (tests, workers, per-tenant configuration). */
-declare function createIntentProofClient(config?: IntentProofConfig): IntentProofClient;
-
-export { BoundedQueueExporter, type BoundedQueueExporterOptions, type ExecutionError, type ExecutionErrorSnapshot, type ExecutionEvent, type ExecutionEventBase, type ExecutionStatus, type Exporter, HttpExporter, type HttpExporterOptions, IntentProofClient, type IntentProofConfig, type IntentProofExecutionEventV1, type IntentProofRuntimeConfigV1, type IntentProofWrapOptionsV1, type JsonValue, MemoryExporter, type MemoryExporterOptions, type QueueOverflowStrategy, type SerializeOptions, VERSION, type WrapOptions, assertCorrelationId, assertValidExecutionEventWire, assertWrapOptionsShape, client, createIntentProofClient, getCorrelationId, getIntentProofClient, runWithCorrelationId, snapshot, validateExecutionEvent, validateIntentProofConfig, validateWrapOptions };
+export { configure, flush, getInstanceId, getOutbox, getPublicKey, getTenantId, SDK_VERSION, } from './client';
+export { pushSubjectMapping, runWithCorrelationId, wrap, } from './instrumentation';
+export { canonicalizeEvent, eventContentHash, loadPrivateKey, signEvent, verifyEventSignature, SENTINEL_PREV_HASH, } from './signing';