@intentproof/sdk 0.1.2 → 0.1.4

package/dist/index.js

@@ -126,8 +126,376 @@ function snapshot(value, options = {}) {
   }
 }
 
+// src/validators.ts
+import { Ajv2020 } from "ajv/dist/2020.js";
+import * as AjvFormats from "ajv-formats";
+
+// src/generated/embed/execution-event.v1.ts
+var execution_event_v1_default = {
+  $comment: "Normative IntentProof source tree: https://github.com/IntentProof/intentproof-spec/tree/main/schema \u2014 $id is a logical URI; see README.",
+  $defs: {
+    ExecutionError: {
+      additionalProperties: false,
+      properties: {
+        cause: {
+          $ref: "#/$defs/ExecutionError",
+          description: "Optional chained cause; MUST conform to ExecutionError when present."
+        },
+        code: { description: "Optional stable machine-readable code.", type: "string" },
+        message: {
+          description: "Human-readable error message (may be empty string if the runtime provides none).",
+          type: "string"
+        },
+        name: {
+          description: "Exception or error type name (e.g. Error, TypeError).",
+          minLength: 1,
+          type: "string"
+        },
+        stack: {
+          description: "Optional stringified stack trace; null when stacks are suppressed.",
+          type: ["string", "null"]
+        }
+      },
+      required: ["name", "message"],
+      type: "object"
+    },
+    JsonValue: {
+      anyOf: [
+        { type: "null" },
+        { type: "boolean" },
+        { type: "number" },
+        { type: "string" },
+        { items: { $ref: "#/$defs/JsonValue" }, type: "array" },
+        { additionalProperties: { $ref: "#/$defs/JsonValue" }, type: "object" }
+      ],
+      description: "Any JSON-serializable value per semantics/serialization_rules.md."
+    }
+  },
+  $id: "https://intentproof.dev/schema/execution_event.v1.schema.json",
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  additionalProperties: false,
+  allOf: [
+    {
+      if: { properties: { status: { const: "ok" } }, required: ["status"] },
+      then: { not: { required: ["error"] }, required: ["output"] }
+    },
+    {
+      if: { properties: { status: { const: "error" } }, required: ["status"] },
+      then: { required: ["error"] }
+    }
+  ],
+  properties: {
+    action: {
+      description: "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.",
+      minLength: 1,
+      type: "string"
+    },
+    attributes: {
+      additionalProperties: { type: ["string", "number", "boolean", "null"] },
+      description: "Flat primitive key/value metadata attached to the event.",
+      propertyNames: { pattern: "^[A-Za-z0-9_.:-]{1,256}$" },
+      type: "object"
+    },
+    completedAt: {
+      description: "RFC 3339 / ISO 8601 instant when execution completed.",
+      format: "date-time",
+      type: "string"
+    },
+    correlationId: {
+      description: "Optional cross-cutting identifier for distributed tracing. MUST be trimmed and non-empty when present.",
+      minLength: 1,
+      type: "string"
+    },
+    durationMs: {
+      description: "Wall-clock duration in milliseconds between startedAt and completedAt.",
+      minimum: 0,
+      type: "number"
+    },
+    error: {
+      $ref: "#/$defs/ExecutionError",
+      description: "Structured error when status is error."
+    },
+    id: {
+      description: "Stable unique identifier for this execution record.",
+      minLength: 1,
+      type: "string"
+    },
+    inputs: {
+      additionalProperties: true,
+      description: "Captured call inputs. Values MUST be JSON-serializable (see semantics/serialization_rules.md).",
+      type: "object"
+    },
+    intent: {
+      description: "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.",
+      minLength: 1,
+      type: "string"
+    },
+    output: {
+      $ref: "#/$defs/JsonValue",
+      description: "Captured return value when status is ok, or optional captured value when captureError allows output on failure."
+    },
+    startedAt: {
+      description: "RFC 3339 / ISO 8601 instant when execution started.",
+      format: "date-time",
+      type: "string"
+    },
+    status: {
+      description: "Terminal execution status.",
+      enum: ["ok", "error"],
+      type: "string"
+    }
+  },
+  required: [
+    "id",
+    "intent",
+    "action",
+    "status",
+    "inputs",
+    "startedAt",
+    "completedAt",
+    "durationMs"
+  ],
+  title: "IntentProof ExecutionEvent v1",
+  type: "object"
+};
+
+// src/generated/embed/intentproof-config.v1.ts
+var intentproof_config_v1_default = {
+  $comment: "Normative IntentProof source tree: https://github.com/IntentProof/intentproof-spec/tree/main/schema \u2014 $id is a logical URI; see README.",
+  $defs: {
+    WrapOptionsV1: {
+      $comment: "Normative IntentProof source tree: https://github.com/IntentProof/intentproof-spec/tree/main/schema \u2014 $id is a logical URI; see README.",
+      $id: "https://intentproof.dev/schema/wrap_options.v1.schema.json",
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      additionalProperties: false,
+      properties: {
+        action: {
+          description: "Default operation identifier (often dotted like vendor.service.method); SDKs MAY derive from the callable when omitted.",
+          minLength: 1,
+          type: "string"
+        },
+        attributes: {
+          additionalProperties: { type: ["string", "number", "boolean", "null"] },
+          description: "Static attributes merged into each emitted ExecutionEvent.attributes.",
+          type: "object"
+        },
+        captureError: {
+          default: true,
+          description: "When true, failures MUST populate error; when false with captureOutput semantics, see semantics/wrap_behavior.md.",
+          type: "boolean"
+        },
+        captureInputs: {
+          default: true,
+          description: "When false, inputs MUST be serialized as an empty object {}.",
+          type: "boolean"
+        },
+        captureOutput: {
+          default: true,
+          description: "When false and status is ok, output MUST be null.",
+          type: "boolean"
+        },
+        captureStack: {
+          default: true,
+          description: "When false, error.stack MUST be null on emitted events.",
+          type: "boolean"
+        },
+        exporterTimeoutMs: {
+          description: "Maximum time an exporter hook may block the wrap boundary; 0 means SDK default.",
+          minimum: 0,
+          type: "number"
+        },
+        intent: {
+          description: "Default natural-language intent for wrapped executions when the call site does not override it.",
+          minLength: 1,
+          type: "string"
+        },
+        propagateCorrelation: {
+          default: true,
+          description: "When true, nested wraps inherit the active correlationId.",
+          type: "boolean"
+        }
+      },
+      title: "IntentProof WrapOptions v1",
+      type: "object"
+    }
+  },
+  $id: "https://intentproof.dev/schema/intentproof_config.v1.schema.json",
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  additionalProperties: false,
+  properties: {
+    correlation: {
+      additionalProperties: false,
+      properties: {
+        generateOnMissing: {
+          default: true,
+          description: "When true, SDK generates a UUID when no correlation is active.",
+          type: "boolean"
+        },
+        headerName: {
+          default: "x-intentproof-correlation-id",
+          description: "HTTP header used for inbound correlation extraction when applicable.",
+          type: "string"
+        }
+      },
+      type: "object"
+    },
+    defaultWrapOptions: { $ref: "#/$defs/WrapOptionsV1" },
+    exporters: {
+      description: "Ordered list of exporter identifiers or inline hooks (SDK-defined encoding).",
+      items: {
+        additionalProperties: true,
+        properties: {
+          endpoint: {
+            description: "Required for http exporters when used.",
+            format: "uri",
+            type: "string"
+          },
+          failOpen: {
+            default: true,
+            description: "When true, exporter failures MUST NOT change user-visible outcomes.",
+            type: "boolean"
+          },
+          headers: {
+            additionalProperties: { type: "string" },
+            description: "Optional HTTP headers for http exporters.",
+            type: "object"
+          },
+          type: {
+            description: "Exporter kind; custom MUST include implementation-specific fields.",
+            enum: ["console", "http", "otel", "custom"],
+            type: "string"
+          }
+        },
+        required: ["type"],
+        type: "object"
+      },
+      type: "array"
+    },
+    serialization: {
+      additionalProperties: false,
+      properties: {
+        maxDepth: {
+          default: 32,
+          description: "Maximum object graph depth for input/output capture.",
+          minimum: 1,
+          type: "integer"
+        },
+        maxStringLength: {
+          default: 65536,
+          description: "Maximum serialized string length for any single field.",
+          minimum: 1,
+          type: "integer"
+        },
+        redactKeys: {
+          description: "Case-insensitive key names to replace with [REDACTED] in captured objects.",
+          items: { type: "string" },
+          type: "array"
+        }
+      },
+      type: "object"
+    },
+    version: {
+      const: 1,
+      description: "Config document version; MUST be 1 for this schema.",
+      type: "integer"
+    }
+  },
+  title: "IntentProof Runtime Config v1",
+  type: "object"
+};
+
+// src/generated/embed/wrap-options.v1.ts
+var wrap_options_v1_default = {
+  $comment: "Normative IntentProof source tree: https://github.com/IntentProof/intentproof-spec/tree/main/schema \u2014 $id is a logical URI; see README.",
+  $id: "https://intentproof.dev/schema/wrap_options.v1.schema.json",
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  additionalProperties: false,
+  properties: {
+    action: {
+      description: "Default operation identifier (often dotted like vendor.service.method); SDKs MAY derive from the callable when omitted.",
+      minLength: 1,
+      type: "string"
+    },
+    attributes: {
+      additionalProperties: { type: ["string", "number", "boolean", "null"] },
+      description: "Static attributes merged into each emitted ExecutionEvent.attributes.",
+      type: "object"
+    },
+    captureError: {
+      default: true,
+      description: "When true, failures MUST populate error; when false with captureOutput semantics, see semantics/wrap_behavior.md.",
+      type: "boolean"
+    },
+    captureInputs: {
+      default: true,
+      description: "When false, inputs MUST be serialized as an empty object {}.",
+      type: "boolean"
+    },
+    captureOutput: {
+      default: true,
+      description: "When false and status is ok, output MUST be null.",
+      type: "boolean"
+    },
+    captureStack: {
+      default: true,
+      description: "When false, error.stack MUST be null on emitted events.",
+      type: "boolean"
+    },
+    exporterTimeoutMs: {
+      description: "Maximum time an exporter hook may block the wrap boundary; 0 means SDK default.",
+      minimum: 0,
+      type: "number"
+    },
+    intent: {
+      description: "Default natural-language intent for wrapped executions when the call site does not override it.",
+      minLength: 1,
+      type: "string"
+    },
+    propagateCorrelation: {
+      default: true,
+      description: "When true, nested wraps inherit the active correlationId.",
+      type: "boolean"
+    }
+  },
+  title: "IntentProof WrapOptions v1",
+  type: "object"
+};
+
+// src/validators.ts
+var ajv = new Ajv2020({
+  allErrors: true,
+  strict: false
+});
+var addFormats = AjvFormats.default;
+addFormats(ajv);
+var validateExecutionEvent = ajv.compile(
+  execution_event_v1_default
+);
+var validateWrapOptions = ajv.compile(
+  wrap_options_v1_default
+);
+var validateIntentProofConfig = ajv.compile(
+  intentproof_config_v1_default
+);
+function errorsText(v) {
+  return ajv.errorsText(v.errors, { separator: "; " });
+}
+function assertValidExecutionEventWire(data) {
+  if (!validateExecutionEvent(data)) {
+    throw new TypeError(
+      `ExecutionEvent wire JSON failed schema validation: ${errorsText(validateExecutionEvent)}`
+    );
+  }
+}
+
 // src/client.ts
 var correlationStore = new AsyncLocalStorage();
+function normalizeInputsForExecutionEvent(inputs) {
+  if (inputs !== null && typeof inputs === "object" && !Array.isArray(inputs)) {
+    return inputs;
+  }
+  return { args: inputs };
+}
 function assertCorrelationId(id) {
   if (typeof id !== "string") {
     throw new TypeError(
@@ -153,7 +521,8 @@ function runWithCorrelationId(correlationId, fn) {
   return correlationStore.run(correlationId, fn);
 }
 function defaultOnExporterError(error, _event) {
-  console.error("[intentproof] exporter error", error);
+  const message = error instanceof Error ? error.message : String(error);
+  console.error("[intentproof] exporter error", message);
 }
 function toErrorSnapshot(e, includeStack) {
   if (e instanceof Error) {
@@ -352,9 +721,12 @@ var IntentProofClient = class {
         correlationId,
         intent: options.intent,
         action: options.action,
-        inputs,
+        inputs: normalizeInputsForExecutionEvent(inputs),
         startedAt: startedAt.toISOString(),
-        attributes: mergeAttrs(self.defaultAttributes, options.attributes)
+        attributes: mergeAttrs(
+          self.defaultAttributes,
+          options.attributes
+        )
       };
       try {
         const out = fn.apply(this, args);
@@ -462,6 +834,7 @@ var IntentProofClient = class {
     this.dispatch(event);
   }
   dispatch(event) {
+    assertValidExecutionEventWire(JSON.parse(JSON.stringify(event)));
     for (const ex of this.exporters) {
       try {
         const r = ex.export(event);
@@ -719,7 +1092,7 @@ var BoundedQueueExporter = class {
 };
 
 // src/index.ts
-var VERSION = "0.1.2";
+var VERSION = "0.1.4";
 var client = getIntentProofClient();
 function createIntentProofClient(config) {
   return new IntentProofClient(config);
@@ -731,12 +1104,16 @@ export {
   MemoryExporter,
   VERSION,
   assertCorrelationId,
+  assertValidExecutionEventWire,
   assertWrapOptionsShape,
   client,
   createIntentProofClient,
   getCorrelationId,
   getIntentProofClient,
   runWithCorrelationId,
-  snapshot
+  snapshot,
+  validateExecutionEvent,
+  validateIntentProofConfig,
+  validateWrapOptions
 };
 //# sourceMappingURL=index.js.map