@intentproof/sdk 0.1.1 → 0.1.3

package/dist/index.d.cts

@@ -1,25 +1,286 @@
-/** Wire shape for emitted execution records (verification / ingest). */
-type ExecutionStatus = "ok" | "error";
-interface ExecutionErrorSnapshot {
-    readonly name: string;
-    readonly message: string;
-    readonly stack?: string;
+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[];
+    };
 }
-/** One record per wrapped invocation — stable fields for a verifier to consume. */
-interface ExecutionEvent {
-    readonly id: string;
-    readonly correlationId?: string;
-    readonly intent: string;
-    readonly action: string;
-    readonly inputs: unknown;
-    readonly output?: unknown;
-    readonly error?: ExecutionErrorSnapshot;
-    readonly status: ExecutionStatus;
-    readonly startedAt: string;
-    readonly completedAt: string;
-    readonly durationMs: number;
-    readonly attributes?: Readonly<Record<string, string | number | boolean>>;
+/**
+ * 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>;
@@ -41,6 +302,10 @@ interface SerializeOptions {
     /** 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;
@@ -59,9 +324,14 @@ interface WrapOptions extends SerializeOptions {
      */
     includeErrorStack?: boolean;
 }
-interface IntentProofConfig {
+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 if an exporter throws synchronously or rejects. Defaults to `console.error` when unset. */
+    /** 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>>;
@@ -70,7 +340,7 @@ interface IntentProofConfig {
      * 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` /
@@ -228,6 +498,17 @@ declare class BoundedQueueExporter implements Exporter {
     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.
@@ -240,4 +521,4 @@ declare const client: IntentProofClient;
 /** Isolated client instance (tests, workers, per-tenant configuration). */
 declare function createIntentProofClient(config?: IntentProofConfig): IntentProofClient;
 
-export { BoundedQueueExporter, type BoundedQueueExporterOptions, type ExecutionErrorSnapshot, type ExecutionEvent, type ExecutionStatus, type Exporter, HttpExporter, type HttpExporterOptions, IntentProofClient, type IntentProofConfig, MemoryExporter, type MemoryExporterOptions, type QueueOverflowStrategy, type SerializeOptions, VERSION, type WrapOptions, assertCorrelationId, assertWrapOptionsShape, client, createIntentProofClient, getCorrelationId, getIntentProofClient, runWithCorrelationId, snapshot };
+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 };