@letsping/sdk 0.1.2 → 0.1.5

package/README.md

@@ -2,7 +2,12 @@
 
 The official Node.js/TypeScript SDK for [LetsPing](https://letsping.co).
 
-LetsPing is the Human-in-the-Loop control plane for autonomous agents — the durable state layer that pauses execution before sensitive actions, persists encrypted agent state, and resumes only after explicit human approval (or rejection/correction).
+LetsPing is a behavioral firewall and Human-in-the-Loop (HITL) infrastructure layer for Agentic AI. It provides mathematically secure state-parking (Cryo-Sleep) and execution governance for autonomous agents built on frameworks like LangGraph, Vercel AI SDK, and custom architectures.
+
+### Features
+- **The Behavioral Shield:** Silently profiles your agent's execution paths via Markov Chains. Automatically intercepts 0-probability reasoning anomalies (hallucinations/prompt injections).
+- **Cryo-Sleep State Parking:** Pauses execution and securely uploads massive agent states directly to storage using Signed URLs, entirely bypassing serverless timeouts and webhook payload limits.
+- **Smart-Accept Drift Adaptation:** Approval decisions mathematically alter the baseline. Old unused reasoning paths decay automatically via Exponential Moving Average (EMA).
 
 ## Requirements
 
@@ -78,12 +83,30 @@ const { id } = await lp.defer({
     subject: "Your invoice is ready",
     amount: 249.99
   },
-  priority: "medium"
+  priority: "medium",
+  // Optional: Pass the full LangGraph/Vercel state dict.
+  // It will be encrypted client-side and uploaded directly to S3.
+  state_snapshot: agentState
 });
 
 console.log(`Approval request queued → ${id}`);
 ```
 
+### Webhook Rehydration (Framework Agnostic)
+LetsPing does **not** magically inject state back into your framework natively. You must handle the webhook and rehydrate your specific framework manually.
+
+```typescript
+// Example Webhook Route Handler
+if (body.status === "APPROVED") {
+    let hydratedState = null;
+    if (body.state_download_url) {
+        const res = await fetch(body.state_download_url);
+        hydratedState = lp._decrypt(await res.json());
+    }
+    // Manually push `hydratedState` back into your LangGraph/Vercel thread
+}
+```
+
 ## API Reference
 
 ### `new LetsPing(apiKey, options?)`

package/dist/index.d.ts

@@ -1,37 +1,52 @@
-type Priority = "low" | "medium" | "high" | "critical";
-interface RequestOptions {
+export type Priority = "low" | "medium" | "high" | "critical";
+export interface RequestOptions {
     service: string;
     action: string;
     payload: Record<string, any>;
     priority?: Priority;
     schema?: Record<string, any>;
+    state_snapshot?: Record<string, any>;
     timeoutMs?: number;
+    role?: string;
 }
-interface Decision {
-    status: "APPROVED" | "REJECTED";
+export interface Decision {
+    status: "APPROVED" | "REJECTED" | "APPROVED_WITH_MODIFICATIONS";
     payload: any;
     patched_payload?: any;
+    diff_summary?: any;
     metadata?: {
         resolved_at: string;
         actor_id: string;
         method?: string;
     };
 }
-declare class LetsPingError extends Error {
+export declare class LetsPingError extends Error {
     status?: number | undefined;
     constructor(message: string, status?: number | undefined);
 }
-declare class LetsPing {
+declare function computeDiff(original: any, patched: any): any;
+export declare class LetsPing {
     private readonly apiKey;
     private readonly baseUrl;
+    private readonly encryptionKey;
     constructor(apiKey?: string, options?: {
         baseUrl?: string;
+        encryptionKey?: string;
     });
+    private _encrypt;
+    private _decrypt;
+    private _prepareStateUpload;
     ask(options: RequestOptions): Promise<Decision>;
     defer(options: RequestOptions): Promise<{
         id: string;
     }>;
     private request;
+    tool(service: string, action: string, priority?: Priority): (context: string | Record<string, any>) => Promise<string>;
+    webhookHandler(payloadStr: string, signatureHeader: string, webhookSecret: string): Promise<{
+        id: string;
+        event: string;
+        data: Decision;
+        state_snapshot?: Record<string, any>;
+    }>;
 }
-
-export { type Decision, LetsPing, LetsPingError, type Priority, type RequestOptions };
+export { computeDiff };

package/dist/index.js

@@ -1,8 +1,13 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -15,15 +20,85 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// package.json
+var require_package = __commonJS({
+  "package.json"(exports2, module2) {
+    module2.exports = {
+      name: "@letsping/sdk",
+      version: "0.1.5",
+      description: "Behavioral Firewall and Cryo-Sleep State Parking for Autonomous Agents",
+      main: "./dist/index.js",
+      module: "./dist/index.mjs",
+      types: "./dist/index.d.ts",
+      exports: {
+        ".": {
+          types: "./dist/index.d.ts",
+          require: "./dist/index.js",
+          import: "./dist/index.mjs"
+        }
+      },
+      scripts: {
+        build: "tsup && tsc --emitDeclarationOnly --outDir dist",
+        dev: "tsup --watch",
+        clean: "rm -rf dist .turbo"
+      },
+      dependencies: {},
+      peerDependencies: {
+        "@opentelemetry/api": "^1.0.0"
+      },
+      peerDependenciesMeta: {
+        "@opentelemetry/api": {
+          optional: true
+        }
+      },
+      devDependencies: {
+        tsup: "^8.0.0",
+        typescript: "^5.7.2",
+        "@types/node": "^22.0.0",
+        "@opentelemetry/api": "^1.9.0"
+      },
+      publishConfig: {
+        access: "public"
+      }
+    };
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
   LetsPing: () => LetsPing,
-  LetsPingError: () => LetsPingError
+  LetsPingError: () => LetsPingError,
+  computeDiff: () => computeDiff
 });
 module.exports = __toCommonJS(index_exports);
+var import_node_crypto = require("crypto");
+var SDK_VERSION = "0.1.5";
+try {
+  SDK_VERSION = require_package().version;
+} catch {
+}
+var otelApi = null;
+var otelTried = false;
+async function getOtel() {
+  if (otelTried) return otelApi;
+  otelTried = true;
+  try {
+    otelApi = await import("@opentelemetry/api");
+  } catch {
+  }
+  return otelApi;
+}
 var LetsPingError = class extends Error {
   constructor(message, status) {
     super(message);
@@ -31,66 +106,250 @@ var LetsPingError = class extends Error {
     this.name = "LetsPingError";
   }
 };
+function isEncEnvelope(v) {
+  return typeof v === "object" && v !== null && v._lp_enc === true && typeof v.iv === "string" && typeof v.ct === "string";
+}
+function encryptPayload(keyBase64, payload) {
+  const keyBuf = Buffer.from(keyBase64, "base64");
+  const iv = (0, import_node_crypto.randomBytes)(12);
+  const cipher = (0, import_node_crypto.createCipheriv)("aes-256-gcm", keyBuf, iv);
+  const plain = Buffer.from(JSON.stringify(payload), "utf8");
+  const ct = Buffer.concat([cipher.update(plain), cipher.final(), cipher.getAuthTag()]);
+  return {
+    _lp_enc: true,
+    iv: iv.toString("base64"),
+    ct: ct.toString("base64")
+  };
+}
+function decryptPayload(keyBase64, envelope) {
+  const keyBuf = Buffer.from(keyBase64, "base64");
+  const iv = Buffer.from(envelope.iv, "base64");
+  const ctFull = Buffer.from(envelope.ct, "base64");
+  const authTag = ctFull.subarray(ctFull.length - 16);
+  const ct = ctFull.subarray(0, ctFull.length - 16);
+  const decipher = (0, import_node_crypto.createDecipheriv)("aes-256-gcm", keyBuf, iv);
+  decipher.setAuthTag(authTag);
+  const plain = Buffer.concat([decipher.update(ct), decipher.final()]);
+  return JSON.parse(plain.toString("utf8"));
+}
+function computeDiff(original, patched) {
+  if (original === patched) return null;
+  if (typeof original !== "object" || typeof patched !== "object" || original === null || patched === null || Array.isArray(original) || Array.isArray(patched)) {
+    if (JSON.stringify(original) !== JSON.stringify(patched)) {
+      return { from: original, to: patched };
+    }
+    return null;
+  }
+  const changes = {};
+  let hasChanges = false;
+  const allKeys = /* @__PURE__ */ new Set([...Object.keys(original), ...Object.keys(patched)]);
+  for (const key of allKeys) {
+    const oV = original[key];
+    const pV = patched[key];
+    if (!(key in original)) {
+      changes[key] = { from: void 0, to: pV };
+      hasChanges = true;
+    } else if (!(key in patched)) {
+      changes[key] = { from: oV, to: void 0 };
+      hasChanges = true;
+    } else {
+      const nestedDiff = computeDiff(oV, pV);
+      if (nestedDiff) {
+        changes[key] = nestedDiff;
+        hasChanges = true;
+      }
+    }
+  }
+  return hasChanges ? changes : null;
+}
 var LetsPing = class {
   constructor(apiKey, options) {
     const key = apiKey || process.env.LETSPING_API_KEY;
     if (!key) throw new Error("LetsPing: API Key is required. Pass it to the constructor or set LETSPING_API_KEY env var.");
     this.apiKey = key;
     this.baseUrl = options?.baseUrl || "https://letsping.co/api";
+    this.encryptionKey = options?.encryptionKey ?? process.env.LETSPING_ENCRYPTION_KEY ?? null;
+  }
+  _encrypt(payload) {
+    if (!this.encryptionKey) return payload;
+    return encryptPayload(this.encryptionKey, payload);
+  }
+  _decrypt(val) {
+    if (!this.encryptionKey || !isEncEnvelope(val)) return val;
+    try {
+      return decryptPayload(this.encryptionKey, val);
+    } catch {
+      return val;
+    }
+  }
+  _prepareStateUpload(stateSnapshot, fallbackDek) {
+    if (this.encryptionKey) {
+      return {
+        data: this._encrypt(stateSnapshot),
+        contentType: "application/json"
+      };
+    } else if (fallbackDek) {
+      const keyBuf = Buffer.from(fallbackDek, "base64");
+      const iv = (0, import_node_crypto.randomBytes)(12);
+      const cipher = (0, import_node_crypto.createCipheriv)("aes-256-gcm", keyBuf, iv);
+      const plain = Buffer.from(JSON.stringify(stateSnapshot), "utf8");
+      const ct = Buffer.concat([cipher.update(plain), cipher.final(), cipher.getAuthTag()]);
+      const finalPayload = Buffer.concat([iv, ct]);
+      return {
+        data: finalPayload,
+        contentType: "application/octet-stream"
+      };
+    }
+    return {
+      data: stateSnapshot,
+      contentType: "application/json"
+    };
   }
   async ask(options) {
     if (options.schema && options.schema._def) {
       throw new LetsPingError("LetsPing Error: Raw Zod schema detected. You must convert it to JSON Schema (e.g. using 'zod-to-json-schema') before passing it to the SDK.");
     }
-    const { id } = await this.request("POST", "/ingest", {
-      service: options.service,
-      action: options.action,
-      payload: options.payload,
-      priority: options.priority || "medium",
-      schema: options.schema,
-      metadata: {
-        role: options.role,
-        sdk: "node"
+    const otel = await getOtel();
+    let span = null;
+    if (otel && otel.trace) {
+      const tracer = otel.trace.getTracer("letsping-sdk");
+      span = tracer.startSpan(`letsping.ask`, {
+        attributes: {
+          "letsping.service": options.service,
+          "letsping.action": options.action,
+          "letsping.priority": options.priority || "medium"
+        }
+      });
+    }
+    try {
+      const res = await this.request("POST", "/ingest", {
+        service: options.service,
+        action: options.action,
+        payload: this._encrypt(options.payload),
+        priority: options.priority || "medium",
+        schema: options.schema,
+        metadata: { role: options.role, sdk: "node" }
+      });
+      const { id, uploadUrl, dek } = res;
+      if (uploadUrl && options.state_snapshot) {
+        try {
+          const { data, contentType } = this._prepareStateUpload(options.state_snapshot, dek);
+          const putRes = await fetch(uploadUrl, {
+            method: "PUT",
+            headers: { "Content-Type": contentType },
+            body: Buffer.isBuffer(data) ? data : JSON.stringify(data)
+          });
+          if (!putRes.ok) {
+            console.warn("LetsPing: Failed to upload state_snapshot to storage", await putRes.text());
+          }
+        } catch (e) {
+          console.warn("LetsPing: Exception uploading state_snapshot", e.message);
+        }
       }
-    });
-    const timeout = options.timeoutMs || 24 * 60 * 60 * 1e3;
-    const start = Date.now();
-    let delay = 1e3;
-    const maxDelay = 1e4;
-    while (Date.now() - start < timeout) {
-      try {
-        const check = await this.request("GET", `/status/${id}`);
-        if (check.status === "APPROVED" || check.status === "REJECTED") {
-          return {
-            status: check.status,
-            payload: options.payload,
-            patched_payload: check.patched_payload || options.payload,
-            metadata: {
-              resolved_at: check.resolved_at,
-              actor_id: check.actor_id
+      if (span) span.setAttribute("letsping.request_id", id);
+      const timeout = options.timeoutMs || 24 * 60 * 60 * 1e3;
+      const start = Date.now();
+      let delay = 1e3;
+      const maxDelay = 1e4;
+      while (Date.now() - start < timeout) {
+        try {
+          const check = await this.request("GET", `/status/${id}`);
+          if (check.status === "APPROVED" || check.status === "REJECTED") {
+            const decryptedPayload = this._decrypt(check.payload) ?? options.payload;
+            const decryptedPatched = check.patched_payload ? this._decrypt(check.patched_payload) : void 0;
+            let diff_summary;
+            let finalStatus = check.status;
+            if (check.status === "APPROVED" && decryptedPatched !== void 0) {
+              finalStatus = "APPROVED_WITH_MODIFICATIONS";
+              const diff = computeDiff(decryptedPayload, decryptedPatched);
+              diff_summary = diff ? { changes: diff } : { changes: "Unknown structure changes" };
             }
-          };
-        }
-      } catch (e) {
-        const status = e.status;
-        if (status && status >= 400 && status < 500 && status !== 404 && status !== 429) {
-          throw e;
+            if (span) {
+              span.setAttribute("letsping.status", finalStatus);
+              if (check.actor_id) span.setAttribute("letsping.actor_id", check.actor_id);
+              span.end();
+            }
+            return {
+              status: finalStatus,
+              payload: decryptedPayload,
+              patched_payload: decryptedPatched,
+              diff_summary,
+              metadata: {
+                resolved_at: check.resolved_at,
+                actor_id: check.actor_id
+              }
+            };
+          }
+        } catch (e) {
+          const s = e.status;
+          if (s && s >= 400 && s < 500 && s !== 404 && s !== 429) throw e;
         }
+        const jitter = Math.random() * 200;
+        await new Promise((r) => setTimeout(r, delay + jitter));
+        delay = Math.min(delay * 1.5, maxDelay);
       }
-      const jitter = Math.random() * 200;
-      await new Promise((r) => setTimeout(r, delay + jitter));
-      delay = Math.min(delay * 1.5, maxDelay);
+      throw new LetsPingError(`Request ${id} timed out waiting for approval.`);
+    } catch (error) {
+      if (span) {
+        span.recordException(error);
+        span.setStatus({ code: otel.SpanStatusCode.ERROR });
+        span.end();
+      }
+      throw error;
     }
-    throw new LetsPingError(`Request ${id} timed out waiting for approval.`);
   }
   async defer(options) {
-    return this.request("POST", "/ingest", options);
+    const otel = await getOtel();
+    let span = null;
+    if (otel && otel.trace) {
+      const tracer = otel.trace.getTracer("letsping-sdk");
+      span = tracer.startSpan(`letsping.defer`, {
+        attributes: {
+          "letsping.service": options.service,
+          "letsping.action": options.action,
+          "letsping.priority": options.priority || "medium"
+        }
+      });
+    }
+    try {
+      const res = await this.request("POST", "/ingest", {
+        ...options,
+        payload: this._encrypt(options.payload)
+      });
+      if (res.uploadUrl && options.state_snapshot) {
+        try {
+          const { data, contentType } = this._prepareStateUpload(options.state_snapshot, res.dek);
+          const putRes = await fetch(res.uploadUrl, {
+            method: "PUT",
+            headers: { "Content-Type": contentType },
+            body: Buffer.isBuffer(data) ? data : JSON.stringify(data)
+          });
+          if (!putRes.ok) {
+            console.warn("LetsPing: Failed to upload state_snapshot to storage", await putRes.text());
+          }
+        } catch (e) {
+          console.warn("LetsPing: Exception uploading state_snapshot", e.message);
+        }
+      }
+      if (span) {
+        span.setAttribute("letsping.request_id", res.id);
+        span.end();
+      }
+      return { id: res.id };
+    } catch (error) {
+      if (span) {
+        span.recordException(error);
+        span.setStatus({ code: otel.SpanStatusCode.ERROR });
+        span.end();
+      }
+      throw error;
+    }
   }
   async request(method, path, body) {
     const headers = {
       "Authorization": `Bearer ${this.apiKey}`,
       "Content-Type": "application/json",
-      "User-Agent": "letsping-node/0.1.2"
+      "User-Agent": `letsping-node/${SDK_VERSION}`
     };
     try {
       const response = await fetch(`${this.baseUrl}${path}`, {
@@ -129,26 +388,82 @@ var LetsPing = class {
         } else {
           payload = { raw_context: String(context) };
         }
-        const result = await this.ask({
-          service,
-          action,
-          payload,
-          priority
-        });
+        const result = await this.ask({ service, action, payload, priority });
         if (result.status === "REJECTED") {
-          return `STOP: Action Rejected by Human.`;
+          return "STOP: Action Rejected by Human.";
         }
-        const finalPayload = result.patched_payload || result.payload;
-        return JSON.stringify(finalPayload);
+        if (result.status === "APPROVED_WITH_MODIFICATIONS") {
+          return JSON.stringify({
+            status: "APPROVED_WITH_MODIFICATIONS",
+            message: "The human reviewer authorized this action but modified your original payload. Please review the diff_summary to learn from this correction.",
+            diff_summary: result.diff_summary,
+            original_payload: result.payload,
+            executed_payload: result.patched_payload
+          });
+        }
+        return JSON.stringify({
+          status: "APPROVED",
+          executed_payload: result.payload
+        });
       } catch (e) {
         return `ERROR: System Failure: ${e.message}`;
       }
     };
   }
+  async webhookHandler(payloadStr, signatureHeader, webhookSecret) {
+    const hmac = (0, import_node_crypto.createHmac)("sha256", webhookSecret).update(payloadStr).digest("hex");
+    const sigParts = signatureHeader.split(",").map((p) => p.split("="));
+    const sigMap = Object.fromEntries(sigParts);
+    if (sigMap["v1"] !== hmac) {
+      throw new LetsPingError("LetsPing Error: Invalid webhook signature", 401);
+    }
+    const payload = JSON.parse(payloadStr);
+    const data = payload.data;
+    let state_snapshot = void 0;
+    if (data && data.state_download_url) {
+      try {
+        const res = await fetch(data.state_download_url);
+        if (res.ok) {
+          const contentType = res.headers.get("content-type") || "";
+          if (contentType.includes("application/octet-stream")) {
+            const fallbackDek = data.dek;
+            if (fallbackDek) {
+              const buffer = Buffer.from(await res.arrayBuffer());
+              const keyBuf = Buffer.from(fallbackDek, "base64");
+              const iv = buffer.subarray(0, 12);
+              const ctFull = buffer.subarray(12);
+              const authTag = ctFull.subarray(ctFull.length - 16);
+              const ct = ctFull.subarray(0, ctFull.length - 16);
+              const decipher = (0, import_node_crypto.createDecipheriv)("aes-256-gcm", keyBuf, iv);
+              decipher.setAuthTag(authTag);
+              const plain = Buffer.concat([decipher.update(ct), decipher.final()]);
+              state_snapshot = JSON.parse(plain.toString("utf8"));
+            } else {
+              console.warn("LetsPing: Missing fallback DEK to decrypt octet-stream storage file");
+            }
+          } else {
+            const encState = await res.json();
+            state_snapshot = this._decrypt(encState);
+          }
+        } else {
+          console.warn("LetsPing: Could not fetch state_snapshot from storage", await res.text());
+        }
+      } catch (e) {
+        console.warn("LetsPing: Exception downloading state_snapshot from webhook url", e.message);
+      }
+    }
+    return {
+      id: payload.id,
+      event: payload.event,
+      data,
+      state_snapshot
+    };
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   LetsPing,
-  LetsPingError
+  LetsPingError,
+  computeDiff
 });
 //# sourceMappingURL=index.js.map