@wytness/sdk 0.2.1 → 0.2.3

package/README.md

@@ -33,8 +33,8 @@ await sendEmail("team@company.com", "Report", "Weekly summary");
 - **Cryptographic signing** — every event is signed with Ed25519 (tweetnacl)
 - **Hash chaining** — tamper-evident chain of events per agent session
 - **Automatic redaction** — secrets in parameters are automatically redacted
-- **Kafka or HTTP** — stream events via Kafka or HTTP API
-- **File fallback** — events are saved locally if the network is unavailable
+- **HTTP transport** — stream events to api.wytness.dev over HTTPS
+- **File fallback** — events are saved locally if the API is unreachable
 
 ## HTTP Emitter (Recommended)
 
@@ -58,17 +58,54 @@ const client = new AuditClient({
 | `agentId` | `string` | required | Unique identifier for the agent |
 | `agentVersion` | `string` | `"0.1.0"` | Version of the agent |
 | `humanOperatorId` | `string` | `"unknown"` | ID of the human overseeing the agent |
-| `signingKeyPath` | `string` | `"./keys/signing.key"` | Path to Ed25519 private key |
-| `kafkaBootstrapServers` | `string\|undefined` | `undefined` | Kafka bootstrap servers |
-| `kafkaTopic` | `string` | `"wytness-events"` | Kafka topic name |
-| `httpEndpoint` | `string\|undefined` | `undefined` | HTTP API endpoint URL |
+| `signingKey` | `string\|undefined` | `undefined` | Base64-encoded Ed25519 private key (for serverless) |
+| `signingKeyPath` | `string` | `"./keys/signing.key"` | Path to Ed25519 private key. Ignored when `signingKey` is set. |
 | `httpApiKey` | `string\|undefined` | `undefined` | API key for HTTP endpoint |
+| `httpEndpoint` | `string` | `"https://api.wytness.dev"` | HTTP API endpoint URL |
 | `fallbackLogPath` | `string` | `"./audit_fallback.jsonl"` | Local fallback file path |
 
 ### `auditTool(client, fn, options)`
 
 Wraps a function to automatically log audit events. Captures function name, parameters, execution duration, success/failure status, cryptographic signature, and hash chain link.
 
+### `client.sessionId`
+
+Read-only property returning the UUID for this client instance.
+
+### `client.flush()`
+
+Returns a Promise that resolves when all pending HTTP requests complete. Call before process exit in serverless/short-lived environments.
+
+```typescript
+await client.flush();
+```
+
+### `hashValue(value)`
+
+SHA-256 hash of any value. Use when recording events manually to compute `inputs_hash` / `outputs_hash`.
+
+```typescript
+import { hashValue } from "@wytness/sdk";
+
+const result = await myTool(data);
+const outputsHash = hashValue(result);
+```
+
+### `AuditEventSchema`
+
+A Zod schema that validates and provides defaults for audit events. Use it when recording events manually:
+
+```typescript
+import { AuditEventSchema } from "@wytness/sdk";
+
+const event = AuditEventSchema.parse({
+  agent_id: "my-agent",
+  tool_name: "my_tool",
+  // ... other required fields
+  // Optional fields get sensible defaults (event_id, timestamp, status, etc.)
+});
+```
+
 ## Exports
 
 ```typescript
@@ -76,6 +113,7 @@ import {
   AuditClient,
   AuditClientOptions,
   auditTool,
+  hashValue,
   AuditEvent,
   AuditEventSchema,
   generateKeypair,
@@ -83,7 +121,8 @@ import {
   verifyEvent,
   computeEventHash,
   verifyChain,
-  createEmitter,
+  createHttpEmitter,
+  createFileEmitter,
 } from "@wytness/sdk";
 ```
 

package/dist/index.cjs

@@ -37,6 +37,7 @@ __export(src_exports, {
   createFileEmitter: () => createFileEmitter,
   createHttpEmitter: () => createHttpEmitter,
   generateKeypair: () => generateKeypair,
+  hashValue: () => hashValue,
   signEvent: () => signEvent,
   verifyChain: () => verifyChain,
   verifyEvent: () => verifyEvent
@@ -143,30 +144,79 @@ function fileEmit(path, eventDict) {
   (0, import_fs.mkdirSync)((0, import_path.dirname)(path), { recursive: true });
   (0, import_fs.appendFileSync)(path, JSON.stringify(eventDict) + "\n");
 }
+var pendingRequests = /* @__PURE__ */ new Set();
+var REPLAY_COOLDOWN_MS = 1e4;
+async function sendOne(apiUrl, apiKey, body) {
+  const resp = await fetch(`${apiUrl}/ingest`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-API-Key": apiKey
+    },
+    body,
+    signal: AbortSignal.timeout(1e4)
+  });
+  if (resp.status !== 201) {
+    throw new Error(`HTTP ${resp.status}`);
+  }
+  return true;
+}
 function createHttpEmitter(apiUrl, apiKey, fallbackPath) {
+  let replaying = false;
+  let lastReplayAttempt = 0;
+  const tryReplay = async () => {
+    const now = Date.now();
+    if (now - lastReplayAttempt < REPLAY_COOLDOWN_MS)
+      return;
+    if (replaying)
+      return;
+    replaying = true;
+    try {
+      lastReplayAttempt = now;
+      if (!(0, import_fs.existsSync)(fallbackPath))
+        return;
+      const stat = (0, import_fs.statSync)(fallbackPath);
+      if (stat.size === 0)
+        return;
+      const lines = (0, import_fs.readFileSync)(fallbackPath, "utf-8").split("\n").filter((l) => l.trim());
+      if (lines.length === 0)
+        return;
+      const remaining = [];
+      for (const line of lines) {
+        try {
+          await sendOne(apiUrl, apiKey, line);
+        } catch {
+          remaining.push(line);
+        }
+      }
+      if (remaining.length > 0) {
+        (0, import_fs.writeFileSync)(fallbackPath, remaining.join("\n") + "\n");
+      } else {
+        (0, import_fs.unlinkSync)(fallbackPath);
+      }
+      const replayed = lines.length - remaining.length;
+      if (replayed > 0) {
+        console.log(`wytness: replayed ${replayed} fallback events`);
+      }
+    } catch {
+    } finally {
+      replaying = false;
+    }
+  };
   return (eventDict) => {
     const doSend = async () => {
       try {
         const body = JSON.stringify(eventDict);
-        const resp = await fetch(`${apiUrl}/ingest`, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            "X-API-Key": apiKey
-          },
-          body,
-          signal: AbortSignal.timeout(1e4)
-        });
-        if (resp.status !== 201) {
-          console.error(`HTTP ingest failed: ${resp.status}`);
-          fileEmit(fallbackPath, eventDict);
-        }
+        await sendOne(apiUrl, apiKey, body);
+        tryReplay();
       } catch (e) {
         console.error(`HTTP ingest error: ${e}`);
         fileEmit(fallbackPath, eventDict);
       }
     };
-    doSend().catch(() => fileEmit(fallbackPath, eventDict));
+    const p = doSend();
+    pendingRequests.add(p);
+    p.finally(() => pendingRequests.delete(p));
   };
 }
 function createFileEmitter(fallbackPath) {
@@ -174,6 +224,9 @@ function createFileEmitter(fallbackPath) {
     fileEmit(fallbackPath, eventDict);
   };
 }
+async function flushPending() {
+  await Promise.allSettled([...pendingRequests]);
+}
 
 // src/client.ts
 var import_crypto3 = require("crypto");
@@ -232,6 +285,14 @@ var AuditClient = class {
       console.error(`wytness: failed to record event: ${e}`);
     }
   }
+  /**
+   * Wait for all pending HTTP requests to complete.
+   * Call this before process exit in serverless/short-lived environments
+   * to ensure all events are delivered.
+   */
+  async flush() {
+    await flushPending();
+  }
 };
 
 // src/decorator.ts
@@ -316,6 +377,7 @@ function auditTool(client, fnOrTaskId, options) {
   createFileEmitter,
   createHttpEmitter,
   generateKeypair,
+  hashValue,
   signEvent,
   verifyChain,
   verifyEvent

package/dist/index.d.cts

@@ -122,8 +122,15 @@ declare class AuditClient {
     get sessionId(): string;
     /** Record an audit event. Never throws — errors are logged and swallowed. */
     record(event: AuditEvent): void;
+    /**
+     * Wait for all pending HTTP requests to complete.
+     * Call this before process exit in serverless/short-lived environments
+     * to ensure all events are delivered.
+     */
+    flush(): Promise<void>;
 }
 
+declare function hashValue(value: unknown): string;
 interface AuditToolOptions {
     toolName?: string;
     taskId?: string;
@@ -142,4 +149,4 @@ interface AuditToolOptions {
  */
 declare function auditTool(client: AuditClient, fnOrTaskId?: ((...args: unknown[]) => unknown) | string, options?: AuditToolOptions | string): any;
 
-export { AuditClient, type AuditClientOptions, type AuditEvent, AuditEventSchema, auditTool, computeEventHash, createFileEmitter, createHttpEmitter, generateKeypair, signEvent, verifyChain, verifyEvent };
+export { AuditClient, type AuditClientOptions, type AuditEvent, AuditEventSchema, auditTool, computeEventHash, createFileEmitter, createHttpEmitter, generateKeypair, hashValue, signEvent, verifyChain, verifyEvent };

package/dist/index.d.ts

@@ -122,8 +122,15 @@ declare class AuditClient {
     get sessionId(): string;
     /** Record an audit event. Never throws — errors are logged and swallowed. */
     record(event: AuditEvent): void;
+    /**
+     * Wait for all pending HTTP requests to complete.
+     * Call this before process exit in serverless/short-lived environments
+     * to ensure all events are delivered.
+     */
+    flush(): Promise<void>;
 }
 
+declare function hashValue(value: unknown): string;
 interface AuditToolOptions {
     toolName?: string;
     taskId?: string;
@@ -142,4 +149,4 @@ interface AuditToolOptions {
  */
 declare function auditTool(client: AuditClient, fnOrTaskId?: ((...args: unknown[]) => unknown) | string, options?: AuditToolOptions | string): any;
 
-export { AuditClient, type AuditClientOptions, type AuditEvent, AuditEventSchema, auditTool, computeEventHash, createFileEmitter, createHttpEmitter, generateKeypair, signEvent, verifyChain, verifyEvent };
+export { AuditClient, type AuditClientOptions, type AuditEvent, AuditEventSchema, auditTool, computeEventHash, createFileEmitter, createHttpEmitter, generateKeypair, hashValue, signEvent, verifyChain, verifyEvent };

package/dist/index.js

@@ -92,36 +92,85 @@ function verifyChain(events) {
 }
 
 // src/emitter.ts
-import { mkdirSync, appendFileSync } from "fs";
+import { mkdirSync, appendFileSync, existsSync, readFileSync, unlinkSync, writeFileSync, statSync } from "fs";
 import { dirname } from "path";
 function fileEmit(path, eventDict) {
   mkdirSync(dirname(path), { recursive: true });
   appendFileSync(path, JSON.stringify(eventDict) + "\n");
 }
+var pendingRequests = /* @__PURE__ */ new Set();
+var REPLAY_COOLDOWN_MS = 1e4;
+async function sendOne(apiUrl, apiKey, body) {
+  const resp = await fetch(`${apiUrl}/ingest`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-API-Key": apiKey
+    },
+    body,
+    signal: AbortSignal.timeout(1e4)
+  });
+  if (resp.status !== 201) {
+    throw new Error(`HTTP ${resp.status}`);
+  }
+  return true;
+}
 function createHttpEmitter(apiUrl, apiKey, fallbackPath) {
+  let replaying = false;
+  let lastReplayAttempt = 0;
+  const tryReplay = async () => {
+    const now = Date.now();
+    if (now - lastReplayAttempt < REPLAY_COOLDOWN_MS)
+      return;
+    if (replaying)
+      return;
+    replaying = true;
+    try {
+      lastReplayAttempt = now;
+      if (!existsSync(fallbackPath))
+        return;
+      const stat = statSync(fallbackPath);
+      if (stat.size === 0)
+        return;
+      const lines = readFileSync(fallbackPath, "utf-8").split("\n").filter((l) => l.trim());
+      if (lines.length === 0)
+        return;
+      const remaining = [];
+      for (const line of lines) {
+        try {
+          await sendOne(apiUrl, apiKey, line);
+        } catch {
+          remaining.push(line);
+        }
+      }
+      if (remaining.length > 0) {
+        writeFileSync(fallbackPath, remaining.join("\n") + "\n");
+      } else {
+        unlinkSync(fallbackPath);
+      }
+      const replayed = lines.length - remaining.length;
+      if (replayed > 0) {
+        console.log(`wytness: replayed ${replayed} fallback events`);
+      }
+    } catch {
+    } finally {
+      replaying = false;
+    }
+  };
   return (eventDict) => {
     const doSend = async () => {
       try {
         const body = JSON.stringify(eventDict);
-        const resp = await fetch(`${apiUrl}/ingest`, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            "X-API-Key": apiKey
-          },
-          body,
-          signal: AbortSignal.timeout(1e4)
-        });
-        if (resp.status !== 201) {
-          console.error(`HTTP ingest failed: ${resp.status}`);
-          fileEmit(fallbackPath, eventDict);
-        }
+        await sendOne(apiUrl, apiKey, body);
+        tryReplay();
       } catch (e) {
         console.error(`HTTP ingest error: ${e}`);
         fileEmit(fallbackPath, eventDict);
       }
     };
-    doSend().catch(() => fileEmit(fallbackPath, eventDict));
+    const p = doSend();
+    pendingRequests.add(p);
+    p.finally(() => pendingRequests.delete(p));
   };
 }
 function createFileEmitter(fallbackPath) {
@@ -129,10 +178,13 @@ function createFileEmitter(fallbackPath) {
     fileEmit(fallbackPath, eventDict);
   };
 }
+async function flushPending() {
+  await Promise.allSettled([...pendingRequests]);
+}
 
 // src/client.ts
 import { randomUUID as randomUUID2 } from "crypto";
-import { existsSync, readFileSync, writeFileSync, mkdirSync as mkdirSync2 } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
 import { dirname as dirname2 } from "path";
 var AuditClient = class {
   agentId;
@@ -151,14 +203,14 @@ var AuditClient = class {
       this._secretKey = new Uint8Array(Buffer.from(options.signingKey, "base64"));
     } else {
       const keyPath = options.signingKeyPath ?? "./keys/signing.key";
-      if (existsSync(keyPath)) {
-        const raw = readFileSync(keyPath);
+      if (existsSync2(keyPath)) {
+        const raw = readFileSync2(keyPath);
         this._secretKey = new Uint8Array(raw);
       } else {
         const kp = generateKeypair();
         this._secretKey = kp.secretKey;
         mkdirSync2(dirname2(keyPath), { recursive: true });
-        writeFileSync(keyPath, Buffer.from(kp.secretKey));
+        writeFileSync2(keyPath, Buffer.from(kp.secretKey));
       }
     }
     const fallback = options.fallbackLogPath ?? "./audit_fallback.jsonl";
@@ -187,6 +239,14 @@ var AuditClient = class {
       console.error(`wytness: failed to record event: ${e}`);
     }
   }
+  /**
+   * Wait for all pending HTTP requests to complete.
+   * Call this before process exit in serverless/short-lived environments
+   * to ensure all events are delivered.
+   */
+  async flush() {
+    await flushPending();
+  }
 };
 
 // src/decorator.ts
@@ -270,6 +330,7 @@ export {
   createFileEmitter,
   createHttpEmitter,
   generateKeypair,
+  hashValue,
   signEvent,
   verifyChain,
   verifyEvent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wytness/sdk",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "TypeScript SDK for Wytness — audit logging for AI agents with cryptographic signing and chain integrity",
   "license": "MIT",
   "author": "Wytness <hello@wytness.dev>",