@volidator/node 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Volidator Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,6 +7,8 @@ Volidator encrypts every log entry locally — on your server — before sending
 [![npm](https://img.shields.io/npm/v/@volidator/node)](https://www.npmjs.com/package/@volidator/node)
 [![license](https://img.shields.io/npm/l/@volidator/node)](LICENSE)
 
+**[Website & Sign Up](https://volidator.com) | [Developer Documentation](https://docs.volidator.com)**
+
 ---
 
 ## What is Volidator?
@@ -52,6 +54,7 @@ Volidator solves this with **Zero-Knowledge Audit Trails**:
 14. [`@volidator/react`](#14-volidatorreact)
 15. [AI Agent Auditing (VolidatorAgent)](#15-ai-agent-auditing-volidatoragent)
 16. [Batch Ingestion (logBatch)](#16-batch-ingestion-logbatch)
+17. [Large Payloads (Claim Check Pattern)](#17-large-payloads-claim-check-pattern)
 
 ---
 
@@ -65,8 +68,12 @@ npm install @volidator/node
 
 ## 2. Environment Setup
 
-Store secrets as environment variables. Never hardcode them.
+Generate a secure 32-byte encryption key (64 hex characters) with the `vol-dek-` prefix:
+```bash
+node -e "const b=require('crypto').randomBytes(32);console.log('vol-dek-'+b.toString('hex'))"
+```
 
+Then add it as an environment secret:
 ```bash
 # Authenticates your server with the Volidator ingestion endpoint
 VOLIDATOR_API_KEY="val_live_xxxxxxxx..."
@@ -87,9 +94,29 @@ import { VolidatorClient } from "@volidator/node";
 export const volidator = new VolidatorClient({
   apiKey: process.env.VOLIDATOR_API_KEY!,
   encryptionKey: process.env.VOLIDATOR_ENCRYPTION_KEY!,
+  
+  // Optional configuration for delivery retries and sizes:
+  maxRetries: 3,         // Retry up to 3 times on transient errors (default: 3)
+  maxMetadataSize: 10240, // Cap serialized metadata size at 10KB (default: 10KB)
+  
+  onDeliveryFailure: (payload, error) => {
+    // Callback invoked when a log permanently fails to deliver after all retries
+    console.error(`Log delivery failed permanently for action "${payload.action}": ${error.message}`);
+  }
 });
 ```
 
+### Transient Errors & Retry Strategy
+By default, the SDK automatically retries log delivery on network errors or 5xx server responses using an exponential backoff strategy (delays: ~500ms → ~1500ms → ~4500ms). Client errors (4xx) are never retried.
+
+> **⚠️ Serverless / Edge Function execution time caveat:**
+> Worst-case retry attempts take up to ~6.5 seconds. If you are running inside a serverless or Edge environment (e.g. Vercel, Next.js Edge, Cloudflare Workers) with strict duration limits:
+> - Wrap log calls in `ctx.waitUntil(volidator.log(...))` so the worker doesn't block response delivery.
+> - Or reduce `maxRetries` to `1` (or `0` to disable retries) to avoid hitting runtime execution limits.
+
+### Metadata Limits & Truncation
+Log metadata is subject to a hard depth limit of **5 levels** and string value length limit of **1000 characters**. In non-production environments (`NODE_ENV !== 'production'`), the SDK will emit warnings in the console if any metadata is truncated.
+
 ---
 
 ## 4. Log an Event
@@ -476,7 +503,7 @@ await volidator.agent.handoff({
 });
 ```
 
-### Trace Correlation (OpenTelemetry Compatibility)
+### Trace Correlation & Logical Clocks (Lamport Timestamps)
 
 Pass standard trace metadata (`traceId`, `spanId`, `parentSpanId`) to map out parent-child relationships and causality graphs between agent steps.
 
@@ -490,6 +517,11 @@ await volidator.agent.toolCall({
 });
 ```
 
+#### Deterministic Edge Trace Ordering
+To resolve NTP (Network Time Protocol) clock drift anomalies between distributed edge servers or serverless invocations, the SDK automatically maintains and propagates a **Lamport Logical Clock** value inside request headers (`x-volidator-clock`). Clocks are synchronized across boundary calls using:
+$$\text{localClock} = \max(\text{localClock}, \text{incomingClock}) + 1$$
+This guarantees that visualizer graphs and dashboard causality lines render completely deterministically in chronological order.
+
 ---
 
 ## 16. Batch Ingestion (`logBatch`)
@@ -513,6 +545,44 @@ console.log(`Successfully ingested ${accepted} logs, failed to prepare ${rejecte
 
 ---
 
+## 17. Large Payloads (Claim Check Pattern)
+
+When logging autonomous agent thinking processes, prompt contexts, or tool data, payloads can easily grow quite large. If your encrypted log payload exceeds **30KB**, the SDK automatically and transparently switches to the **Claim Check Pattern**:
+* The SDK uploads the encrypted ciphertext chunk to Cloudflare R2 object storage securely before database ingestion.
+* It writes a content-addressed SHA-256 hash pointer to the database log record instead of the full payload, setting `isClaimCheck` to true.
+* The Volidator dashboard and embed widgets detect this flag and automatically retrieve the encrypted chunk from the storage proxy to decrypt it locally in the browser.
+
+This maintains absolute Zero-Knowledge privacy guarantees for large payloads without bloat.
+
+---
+
+## 18. Fluent Batcher (`batcher`)
+
+Instead of managing arrays and calling `logBatch` manually, you can use the fluent `batcher()` client helper. This is highly recommended for loop-heavy agent runs or script execution paths.
+
+```typescript
+const batcher = volidator.batcher({
+  autoFlushCount: 50,      // Automatically flush and send when buffer hits 50 logs
+  autoFlushInterval: 5000, // Or automatically flush every 5 seconds (Node-only, see warning)
+});
+
+// Inside your loop or agent reasoning cycle:
+batcher.push({
+  actor: "agent-1",
+  action: "thought",
+  metadata: { step: 1, text: "Thinking..." }
+});
+
+// Always call flush manually at the end of the script or request path to send any leftovers:
+await batcher.flush();
+```
+
+> **⚠️ Serverless / Edge Warning:**
+> `autoFlushInterval` uses `setInterval` internally. In serverless and Edge environments (like Cloudflare Workers, Vercel Edge, Next.js Edge), the V8 isolate is **frozen or destroyed** as soon as the response is returned to the user. Background timers will silently fail to execute, resulting in dropped logs.
+> **Only use `autoFlushInterval` in long-lived Node.js applications** (Express, Fastify, CLI tools). For serverless/edge functions, **always manually call `await batcher.flush()`** or pass the promise to `ctx.waitUntil()`.
+
+---
+
 ## License
 
 MIT © Volidator Contributors

package/dist/{chunk-KEXIKZGN.js → chunk-AJL3OYF2.js}

@@ -1,11 +1,13 @@
 import {
   VolidatorClient
-} from "./chunk-YI4DCCHT.js";
+} from "./chunk-UDBMJC25.js";
 
 // src/middleware/next.ts
 function withVolidator(client, handler) {
   return async (req, ctx = {}, ...args) => {
     const extractedContext = VolidatorClient.extractContext(req);
+    const extractedTrace = VolidatorClient.extractTraceContext(req);
+    const incomingClock = extractedTrace.logicalClock || 0;
     const scopedLog = async (payload) => {
       return client.log({
         ...payload,
@@ -46,11 +48,13 @@ function withVolidator(client, handler) {
         compliance: scopedCompliance
       }
     };
-    return handler(req, newCtx, ...args);
+    return VolidatorClient.logicalClockStore.run({ clock: incomingClock }, () => {
+      return handler(req, newCtx, ...args);
+    });
   };
 }
 
 export {
   withVolidator
 };
-//# sourceMappingURL=chunk-KEXIKZGN.js.map
+//# sourceMappingURL=chunk-AJL3OYF2.js.map

package/dist/chunk-AJL3OYF2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/middleware/next.ts"],"sourcesContent":["import { VolidatorClient, LogPayload } from \"../index\";\n\n/**\n * Next.js App Router Middleware for Volidator.\n * Automatically extracts telemetry context (IP, User Agent, Location)\n * from the Next.js standard Request object and injects it into every\n * `volidator.log()` and `volidator.compliance.*()` call made inside\n * the wrapped handler.\n */\nexport function withVolidator<T extends Function>(\n  client: VolidatorClient,\n  handler: T\n): (req: Request, ctx?: any, ...args: any[]) => Promise<any> {\n  return async (req: Request, ctx: any = {}, ...args: any[]) => {\n    const extractedContext = VolidatorClient.extractContext(req);\n    const extractedTrace = VolidatorClient.extractTraceContext(req);\n    const incomingClock = extractedTrace.logicalClock || 0;\n\n    // ---------------------------------------------------------------------------\n    // Scoped log — merges request-level IP/UA context into every log call.\n    // ---------------------------------------------------------------------------\n    const scopedLog = async (payload: LogPayload) => {\n      return client.log({\n        ...payload,\n        context: {\n          ...extractedContext,\n          ...payload.context,\n          location: {\n            ...extractedContext.location,\n            ...(payload.context?.location || {}),\n          },\n          device: {\n            ...extractedContext.device,\n            ...(payload.context?.device || {}),\n          },\n        },\n      });\n    };\n\n    // ---------------------------------------------------------------------------\n    // Scoped compliance — mirrors VolidatorCompliance but routes through\n    // scopedLog so that IP/UA telemetry is preserved in compliance events.\n    // ---------------------------------------------------------------------------\n    const withControl = (\n      action: string,\n      soc2Control: string,\n      isoControl: string,\n      payload: Omit<LogPayload, \"action\">\n    ) =>\n      scopedLog({\n        ...payload,\n        action,\n        metadata: {\n          ...payload.metadata,\n          soc2_control: soc2Control,\n          iso27001: isoControl,\n        },\n      });\n\n    const scopedCompliance = {\n      accessRevoked: (p: Omit<LogPayload, \"action\">) =>\n        withControl(\"access.revoked\", \"CC6.1\", \"A.9.2.6\", p),\n      accessGranted: (p: Omit<LogPayload, \"action\">) =>\n        withControl(\"access.granted\", \"CC6.1\", \"A.9.2.1\", p),\n      dataExported: (p: Omit<LogPayload, \"action\">) =>\n        withControl(\"data.exported\", \"CC6.6\", \"A.12.4.1\", p),\n      systemConfigChanged: (p: Omit<LogPayload, \"action\">) =>\n        withControl(\"system.config_changed\", \"CC6.2\", \"A.12.1.2\", p),\n      mfaEnabled: (p: Omit<LogPayload, \"action\">) =>\n        withControl(\"mfa.enabled\", \"CC6.3\", \"A.9.4.2\", p),\n    };\n\n    const newCtx = {\n      ...ctx,\n      volidator: {\n        log: scopedLog,\n        compliance: scopedCompliance,\n      },\n    };\n\n    return VolidatorClient.logicalClockStore.run({ clock: incomingClock }, () => {\n      return handler(req, newCtx, ...args);\n    });\n  };\n}\n"],"mappings":";;;;;AASO,SAAS,cACd,QACA,SAC2D;AAC3D,SAAO,OAAO,KAAc,MAAW,CAAC,MAAM,SAAgB;AAC5D,UAAM,mBAAmB,gBAAgB,eAAe,GAAG;AAC3D,UAAM,iBAAiB,gBAAgB,oBAAoB,GAAG;AAC9D,UAAM,gBAAgB,eAAe,gBAAgB;AAKrD,UAAM,YAAY,OAAO,YAAwB;AAC/C,aAAO,OAAO,IAAI;AAAA,QAChB,GAAG;AAAA,QACH,SAAS;AAAA,UACP,GAAG;AAAA,UACH,GAAG,QAAQ;AAAA,UACX,UAAU;AAAA,YACR,GAAG,iBAAiB;AAAA,YACpB,GAAI,QAAQ,SAAS,YAAY,CAAC;AAAA,UACpC;AAAA,UACA,QAAQ;AAAA,YACN,GAAG,iBAAiB;AAAA,YACpB,GAAI,QAAQ,SAAS,UAAU,CAAC;AAAA,UAClC;AAAA,QACF;AAAA,MACF,CAAC;AAAA,IACH;AAMA,UAAM,cAAc,CAClB,QACA,aACA,YACA,YAEA,UAAU;AAAA,MACR,GAAG;AAAA,MACH;AAAA,MACA,UAAU;AAAA,QACR,GAAG,QAAQ;AAAA,QACX,cAAc;AAAA,QACd,UAAU;AAAA,MACZ;AAAA,IACF,CAAC;AAEH,UAAM,mBAAmB;AAAA,MACvB,eAAe,CAAC,MACd,YAAY,kBAAkB,SAAS,WAAW,CAAC;AAAA,MACrD,eAAe,CAAC,MACd,YAAY,kBAAkB,SAAS,WAAW,CAAC;AAAA,MACrD,cAAc,CAAC,MACb,YAAY,iBAAiB,SAAS,YAAY,CAAC;AAAA,MACrD,qBAAqB,CAAC,MACpB,YAAY,yBAAyB,SAAS,YAAY,CAAC;AAAA,MAC7D,YAAY,CAAC,MACX,YAAY,eAAe,SAAS,WAAW,CAAC;AAAA,IACpD;AAEA,UAAM,SAAS;AAAA,MACb,GAAG;AAAA,MACH,WAAW;AAAA,QACT,KAAK;AAAA,QACL,YAAY;AAAA,MACd;AAAA,IACF;AAEA,WAAO,gBAAgB,kBAAkB,IAAI,EAAE,OAAO,cAAc,GAAG,MAAM;AAC3E,aAAO,QAAQ,KAAK,QAAQ,GAAG,IAAI;AAAA,IACrC,CAAC;AAAA,EACH;AACF;","names":[]}

package/dist/{chunk-YI4DCCHT.js → chunk-UDBMJC25.js}

@@ -1,6 +1,8 @@
 // src/index.ts
-var VolidatorClient = class _VolidatorClient {
+import { AsyncLocalStorage } from "async_hooks";
+var _VolidatorClient = class _VolidatorClient {
   constructor(config) {
+    this.fallbackLogicalClock = 0;
     this.apiKey = config.apiKey;
     this.endpoint = config.endpoint || "https://ingestion.volidator.com";
     this.projectId = config.projectId;
@@ -8,6 +10,8 @@ var VolidatorClient = class _VolidatorClient {
     this.redactKeys = config.redactKeys || [];
     this.referenceKeys = config.referenceKeys || [];
     this.maxMetadataSize = config.maxMetadataSize || 10240;
+    this.maxRetries = config.maxRetries !== void 0 ? config.maxRetries : 3;
+    this.onDeliveryFailure = config.onDeliveryFailure;
     if (config.keyring && config.activeEncryptionKeyId) {
       this.keyring = config.keyring;
       this.activeKeyId = config.activeEncryptionKeyId;
@@ -28,6 +32,22 @@ var VolidatorClient = class _VolidatorClient {
     this.compliance = new VolidatorCompliance(this);
     this.agent = new VolidatorAgent(this);
   }
+  /**
+   * Increments and returns the current Lamport Logical Clock counter.
+   * If a logicalClockStore context is active, it reads, syncs, and updates
+   * the thread-scoped clock; otherwise, it falls back to a global instance-scoped counter.
+   *
+   * @param incomingClock Optional logical clock sequence from incoming trace parent header
+   */
+  getAndIncrementClock(incomingClock) {
+    const store = _VolidatorClient.logicalClockStore.getStore();
+    if (store) {
+      store.clock = Math.max(store.clock, incomingClock || 0) + 1;
+      return store.clock;
+    }
+    this.fallbackLogicalClock = Math.max(this.fallbackLogicalClock, incomingClock || 0) + 1;
+    return this.fallbackLogicalClock;
+  }
   // ---------------------------------------------------------------------------
   // Telemetry Context Parser (Zero-latency header parsing)
   // ---------------------------------------------------------------------------
@@ -69,11 +89,23 @@ var VolidatorClient = class _VolidatorClient {
       }
       return "";
     };
+    const result = {};
+    const clockVal = getHeader("x-volidator-clock");
+    if (clockVal) {
+      const parsed = parseInt(clockVal, 10);
+      if (!isNaN(parsed)) {
+        result.logicalClock = parsed;
+      }
+    }
     const traceparent = getHeader("traceparent");
-    if (!traceparent) return {};
-    const parts = traceparent.split("-");
-    if (parts.length !== 4) return {};
-    return { traceId: parts[1], spanId: parts[2] };
+    if (traceparent) {
+      const parts = traceparent.split("-");
+      if (parts.length === 4) {
+        result.traceId = parts[1];
+        result.spanId = parts[2];
+      }
+    }
+    return result;
   }
   static resolveTelemetryConfig(config) {
     const preset = config.preset || "standard";
@@ -196,6 +228,12 @@ var VolidatorClient = class _VolidatorClient {
   // prepareLogEntry() — Prepares, redacts, and encrypts a single log entry payload
   // ---------------------------------------------------------------------------
   async prepareLogEntry(payload, maxMetaOverride) {
+    const PAYLOAD_5MB_LIMIT = 5 * 1024 * 1024;
+    const metadata = payload.metadata || {};
+    const payloadSize = new TextEncoder().encode(JSON.stringify(metadata)).length;
+    if (payloadSize > PAYLOAD_5MB_LIMIT) {
+      throw new Error(`Volidator SDK Error: Audit log payload exceeds the 5MB hard limit (${payloadSize} bytes).`);
+    }
     const actorRaw = payload.actor || payload.actorId || "unknown";
     const targetRaw = payload.target || payload.targetId || "unknown";
     const tenantRaw = payload.tenant || payload.tenantId || "";
@@ -277,13 +315,20 @@ var VolidatorClient = class _VolidatorClient {
         safeMetadata[k] = v;
       }
     }
+    let didTruncateDepth = false;
+    let didTruncateString = false;
     const limitDepth = (obj, currentDepth = 1) => {
       if (currentDepth > 5) {
+        didTruncateDepth = true;
         return "[Truncated - Depth Exceeded]";
       }
       if (typeof obj !== "object" || obj === null) {
         if (typeof obj === "string") {
-          return truncate(obj, 1e3);
+          const truncatedVal = truncate(obj, 1e3);
+          if (truncatedVal.length !== obj.length) {
+            didTruncateString = true;
+          }
+          return truncatedVal;
         }
         return obj;
       }
@@ -297,6 +342,14 @@ var VolidatorClient = class _VolidatorClient {
       return result;
     };
     const processedMetadata = limitDepth(safeMetadata);
+    if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+      if (didTruncateDepth) {
+        console.warn("[Volidator] Warning: Log metadata exceeded maximum depth limit (5) and was truncated.");
+      }
+      if (didTruncateString) {
+        console.warn("[Volidator] Warning: One or more log metadata string values exceeded the 1000-character limit and were truncated.");
+      }
+    }
     const serializedMeta = JSON.stringify(processedMetadata);
     const maxMetaLimit = maxMetaOverride || this.maxMetadataSize;
     if (serializedMeta.length > maxMetaLimit) {
@@ -320,6 +373,7 @@ var VolidatorClient = class _VolidatorClient {
     let traceId = payload.traceId;
     let spanId = payload.spanId;
     let parentSpanId = payload.parentSpanId;
+    let logicalClock = payload.logicalClock;
     if (payload.req) {
       const extractedTrace = _VolidatorClient.extractTraceContext(payload.req);
       if (!traceId && extractedTrace.traceId) {
@@ -328,7 +382,11 @@ var VolidatorClient = class _VolidatorClient {
       if (!spanId && extractedTrace.spanId) {
         spanId = extractedTrace.spanId;
       }
+      if (logicalClock === void 0 && extractedTrace.logicalClock !== void 0) {
+        logicalClock = extractedTrace.logicalClock;
+      }
     }
+    const resolvedClock = this.getAndIncrementClock(logicalClock);
     if (spanId) {
       enrichedPayload.spanId = spanId;
     }
@@ -341,14 +399,39 @@ var VolidatorClient = class _VolidatorClient {
     const targetBlindIndex = await this.generateBlindIndex(target, activeKeyBuffer);
     const tenantBlindIndex = tenant ? await this.generateBlindIndex(tenant, activeKeyBuffer) : void 0;
     const traceBlindIndex = traceId ? await this.generateBlindIndex(traceId, activeKeyBuffer) : void 0;
-    const encryptedPayload = await this.encryptPayload(enrichedPayload);
+    let encryptedPayload = await this.encryptPayload(enrichedPayload);
+    let isClaimCheck = false;
+    if (encryptedPayload.length > 30720) {
+      const binaryBuffer = new TextEncoder().encode(encryptedPayload);
+      const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", binaryBuffer);
+      const hashHex = Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+      try {
+        const uploadRes = await fetch(`${this.endpoint}/v1/log/upload/${hashHex}`, {
+          method: "PUT",
+          headers: {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/octet-stream"
+          },
+          body: encryptedPayload
+        });
+        if (!uploadRes.ok) {
+          throw new Error(`Upload failed with status: ${uploadRes.status}`);
+        }
+        encryptedPayload = hashHex;
+        isClaimCheck = true;
+      } catch (err) {
+        console.error(`[Volidator] Claim check upload failed: ${err.message}`);
+      }
+    }
     return {
       actorBlindIndex,
       actionBlindIndex,
       targetBlindIndex,
       tenantBlindIndex,
       traceBlindIndex,
-      encryptedPayload
+      encryptedPayload,
+      logicalClock: resolvedClock,
+      isClaimCheck
     };
   }
   // ---------------------------------------------------------------------------
@@ -356,20 +439,44 @@ var VolidatorClient = class _VolidatorClient {
   // ---------------------------------------------------------------------------
   async log(payload, maxMetaOverride) {
     const entry = await this.prepareLogEntry(payload, maxMetaOverride);
-    try {
-      const res = await fetch(`${this.endpoint}/v1/log`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify(entry)
-      });
-      return res.ok;
-    } catch (err) {
-      console.error(`[Volidator] Failed to send log: ${err.message}`);
-      return false;
+    let attempt = 0;
+    let delay = 500;
+    let lastError = new Error("Unknown error");
+    while (attempt <= this.maxRetries) {
+      try {
+        const res = await fetch(`${this.endpoint}/v1/log`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(entry)
+        });
+        if (res.ok) {
+          return true;
+        }
+        lastError = new Error(`Server returned status ${res.status}`);
+        if (res.status >= 400 && res.status < 500) {
+          break;
+        }
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+      }
+      attempt++;
+      if (attempt <= this.maxRetries) {
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        delay *= 3;
+      }
+    }
+    console.error(`[Volidator] Failed to send log after ${attempt} attempts: ${lastError.message}`);
+    if (this.onDeliveryFailure) {
+      try {
+        this.onDeliveryFailure(payload, lastError);
+      } catch (cbErr) {
+        console.error(`[Volidator] Error in onDeliveryFailure callback: ${cbErr.message}`);
+      }
     }
+    return false;
   }
   // ---------------------------------------------------------------------------
   // logBatch() — Bulk encrypt and ingest a batch of up to 100 audit events
@@ -416,12 +523,79 @@ var VolidatorClient = class _VolidatorClient {
     }
   }
   // ---------------------------------------------------------------------------
+  // batcher() — Convenience batcher for buffered log ingestion
+  // ---------------------------------------------------------------------------
+  /**
+   * Creates a convenience batcher instance for buffering and ingestion.
+   * 
+   * ⚠️ SERVERLESS/EDGE CAVEAT:
+   * autoFlushInterval uses setInterval internally. In serverless/edge environments
+   * (e.g. Cloudflare Workers, Vercel Edge), the V8 isolate is frozen or destroyed
+   * once the response is sent. Background timers will silently fail to fire, leading
+   * to dropped logs. Only use autoFlushInterval in long-lived Node.js processes.
+   * In serverless/edge environments, always call await batcher.flush() explicitly
+   * before returning the response, or wrap it in ctx.waitUntil().
+   */
+  batcher(options) {
+    const client = this;
+    let buffer = [];
+    let intervalId = null;
+    const flush = async () => {
+      if (intervalId) {
+        clearInterval(intervalId);
+        intervalId = null;
+      }
+      if (buffer.length === 0) {
+        if (options?.autoFlushInterval) {
+          startTimer();
+        }
+        return { accepted: 0, rejected: 0 };
+      }
+      const payloadsToFlush = [...buffer];
+      buffer = [];
+      if (options?.autoFlushInterval) {
+        startTimer();
+      }
+      return client.logBatch(payloadsToFlush);
+    };
+    const startTimer = () => {
+      if (options?.autoFlushInterval && !intervalId) {
+        intervalId = setInterval(() => {
+          flush().catch((err) => {
+            console.error(`[Volidator] Batcher auto-flush failed: ${err.message}`);
+          });
+        }, options.autoFlushInterval);
+        if (intervalId && typeof intervalId.unref === "function") {
+          intervalId.unref();
+        }
+      }
+    };
+    const push = (payload) => {
+      buffer.push(payload);
+      const maxCount = options?.autoFlushCount || 100;
+      if (buffer.length >= Math.min(maxCount, 100)) {
+        flush().catch((err) => {
+          console.error(`[Volidator] Batcher auto-flush on count failed: ${err.message}`);
+        });
+      }
+    };
+    const size = () => buffer.length;
+    startTimer();
+    return {
+      push,
+      flush,
+      size
+    };
+  }
+  // ---------------------------------------------------------------------------
   // generateEmbedToken() — Sign a HS256 JWT for the embeddable dashboard widget
   // ---------------------------------------------------------------------------
   async generateEmbedToken(config) {
-    if (!this.projectId || !this.clientSecret) {
+    const projectId = config.projectId || this.projectId;
+    const clientSecret = config.clientSecret || this.clientSecret;
+    if (!projectId || !clientSecret) {
       throw new Error(
-        "generateEmbedToken() requires projectId and clientSecret in the VolidatorClient constructor."
+        "generateEmbedToken() requires projectId and clientSecret to be provided in either the configuration or the VolidatorClient constructor."
       );
     }
     const {
@@ -448,7 +622,7 @@ var VolidatorClient = class _VolidatorClient {
     const expiresInSeconds = Math.min(parsedExpiry, maxExpiry);
     const now = Math.floor(Date.now() / 1e3);
     const payload = {
-      pid: this.projectId,
+      pid: projectId,
       scope: defaultScope,
       iat: now,
       exp: now + expiresInSeconds
@@ -481,7 +655,7 @@ var VolidatorClient = class _VolidatorClient {
       }
       payload.view = compressed;
     }
-    const token = await this.signHS256JWT(payload, this.clientSecret);
+    const token = await this.signHS256JWT(payload, clientSecret);
     const keyringString = Object.entries(this.keyring).map(([id, key]) => `${id}:${key}`).join(",");
     const hostParam = hostOrigin ? `?host=${encodeURIComponent(hostOrigin)}` : "";
     const embedUrl = `${dashboardUrl}/embed/${token}${hostParam}#${keyringString}`;
@@ -530,6 +704,13 @@ var VolidatorClient = class _VolidatorClient {
     }
   }
 };
+/**
+ * Thread-local asynchronous context storage used to maintain
+ * and increment Lamport logical clock sequences across execution boundaries
+ * (e.g. within API requests or serverless handler contexts).
+ */
+_VolidatorClient.logicalClockStore = new AsyncLocalStorage();
+var VolidatorClient = _VolidatorClient;
 var VolidatorCompliance = class {
   constructor(client) {
     this.client = client;
@@ -660,4 +841,4 @@ export {
   VolidatorCompliance,
   VolidatorAgent
 };
-//# sourceMappingURL=chunk-YI4DCCHT.js.map
+//# sourceMappingURL=chunk-UDBMJC25.js.map