@letsping/sdk 0.3.1 → 0.3.2

package/dist/index.mjs

@@ -0,0 +1,848 @@
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+
+// package.json
+var require_package = __commonJS({
+  "package.json"(exports, module) {
+    module.exports = {
+      name: "@letsping/sdk",
+      version: "0.3.2",
+      description: "Agent trust layer: behavioral firewall, HITL, and Cryo-Sleep state for AI agents. Works with LangGraph, Vercel AI SDK, and custom runners.",
+      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"
+        },
+        "./integrations/langgraph": {
+          types: "./dist/integrations/langgraph.d.ts",
+          require: "./dist/integrations/langgraph.js",
+          import: "./dist/integrations/langgraph.mjs"
+        }
+      },
+      files: [
+        "dist"
+      ],
+      scripts: {
+        build: "tsup && tsc --emitDeclarationOnly --outDir dist",
+        dev: "tsup --watch",
+        clean: "rm -rf dist .turbo"
+      },
+      engines: {
+        node: ">=18.0.0"
+      },
+      homepage: "https://letsping.co",
+      license: "MIT",
+      keywords: [
+        "letsping",
+        "agent",
+        "hitl",
+        "human-in-the-loop",
+        "behavioral-firewall",
+        "langgraph",
+        "vercel-ai",
+        "cryo-sleep",
+        "state-parking"
+      ],
+      peerDependencies: {
+        "@langchain/core": ">=0.1.52",
+        "@langchain/langgraph": ">=0.0.1",
+        "@opentelemetry/api": "^1.0.0"
+      },
+      peerDependenciesMeta: {
+        "@opentelemetry/api": {
+          optional: true
+        },
+        "@langchain/langgraph": {
+          optional: true
+        },
+        "@langchain/core": {
+          optional: true
+        }
+      },
+      devDependencies: {
+        "@langchain/core": "^1.1.28",
+        "@langchain/langgraph": "^1.1.5",
+        "@opentelemetry/api": "^1.9.0",
+        "@types/node": "^22.0.0",
+        tsup: "^8.0.0",
+        typescript: "^5.7.2"
+      },
+      publishConfig: {
+        access: "public"
+      },
+      repository: {
+        type: "git",
+        url: "https://github.com/CordiaLabs/LetsPing.git",
+        directory: "packages/sdk"
+      }
+    };
+  }
+});
+
+// src/index.ts
+import { createCipheriv, createDecipheriv, randomBytes, createHmac } from "crypto";
+var SDK_VERSION = "0.2.1";
+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 LETSPING_DOCS_BASE = "https://letsping.co/docs";
+var LetsPingError = class extends Error {
+  constructor(message, status, code, documentationUrl) {
+    super(message);
+    this.name = "LetsPingError";
+    this.status = status;
+    this.code = code ?? (status ? statusToCode(status) : void 0);
+    this.documentationUrl = documentationUrl ?? (this.code ? codeToDocUrl(this.code) : void 0);
+  }
+};
+function statusToCode(status) {
+  switch (status) {
+    case 401:
+      return "LETSPING_401_AUTH";
+    case 402:
+      return "LETSPING_402_QUOTA";
+    case 403:
+      return "LETSPING_403_FORBIDDEN";
+    case 404:
+      return "LETSPING_404_NOT_FOUND";
+    case 429:
+      return "LETSPING_429_RATE_LIMIT";
+    case 408:
+      return "LETSPING_TIMEOUT";
+    default:
+      return status >= 500 ? "LETSPING_NETWORK" : `LETSPING_${status}`;
+  }
+}
+function codeToDocUrl(code) {
+  const anchor = {
+    LETSPING_401_AUTH: "#auth",
+    LETSPING_402_QUOTA: "#billing",
+    LETSPING_403_FORBIDDEN: "#auth",
+    LETSPING_404_NOT_FOUND: "#requests",
+    LETSPING_429_RATE_LIMIT: "#rate-limits",
+    LETSPING_TIMEOUT: "#timeouts",
+    LETSPING_NETWORK: "#errors",
+    LETSPING_WEBHOOK_INVALID: "#webhooks"
+  };
+  return `${LETSPING_DOCS_BASE}${anchor[code] ?? ""}`;
+}
+function parseApiError(responseStatus, body) {
+  const message = body?.message ?? body?.error ?? `API Error [${responseStatus}]`;
+  const code = body?.code ?? statusToCode(responseStatus);
+  return { message, code, documentationUrl: codeToDocUrl(code) };
+}
+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 = randomBytes(12);
+  const cipher = 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 = 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;
+}
+function verifyEscrow(event, secret) {
+  if (!event.escrow || !event.escrow.handoff_signature) return false;
+  const base = {
+    id: event.id,
+    event: event.event,
+    data: event.data,
+    upstream_agent_id: event.escrow.upstream_agent_id,
+    downstream_agent_id: event.escrow.downstream_agent_id,
+    x402_mandate: event.escrow.x402_mandate ?? null,
+    ap2_mandate: event.escrow.ap2_mandate ?? null
+  };
+  const expected = createHmac("sha256", secret).update(JSON.stringify(base)).digest("hex");
+  return expected === event.escrow.handoff_signature;
+}
+function signAgentCall(agentId, secret, call) {
+  const canonical = JSON.stringify({
+    project_id: call.project_id,
+    service: call.service,
+    action: call.action,
+    payload: call.payload
+  });
+  const signature = createHmac("sha256", secret).update(canonical).digest("hex");
+  return {
+    agent_id: agentId,
+    agent_signature: signature
+  };
+}
+function signIngestBody(agentId, secret, body) {
+  const { agent_id, agent_signature } = signAgentCall(agentId, secret, {
+    project_id: body.project_id,
+    service: body.service,
+    action: body.action,
+    payload: body.payload
+  });
+  return {
+    ...body,
+    agent_id,
+    agent_signature
+  };
+}
+async function createAgentWorkspace(options) {
+  const baseUrl = (options?.baseUrl ?? process.env.LETSPING_BASE_URL ?? "https://letsping.co").replace(/\/+$/, "");
+  const tokenRes = await fetch(`${baseUrl}/api/agent-signup/request-token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: "{}"
+  });
+  if (!tokenRes.ok) {
+    const err = await tokenRes.json().catch(() => ({}));
+    const { message, code, documentationUrl } = parseApiError(tokenRes.status, err);
+    throw new LetsPingError(message, tokenRes.status, code, documentationUrl);
+  }
+  const { token } = await tokenRes.json();
+  if (!token) {
+    throw new LetsPingError("LetsPing Error: No token in request-token response");
+  }
+  const redeemRes = await fetch(`${baseUrl}/api/agent-signup`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ token })
+  });
+  if (!redeemRes.ok) {
+    const err = await redeemRes.json().catch(() => ({}));
+    const { message, code, documentationUrl } = parseApiError(redeemRes.status, err);
+    throw new LetsPingError(message, redeemRes.status, code, documentationUrl);
+  }
+  const redeem = await redeemRes.json();
+  if (!redeem.api_key || !redeem.agents_register_url) {
+    throw new LetsPingError("LetsPing Error: Invalid redeem response (missing api_key or agents_register_url)");
+  }
+  const registerRes = await fetch(redeem.agents_register_url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${redeem.api_key}`,
+      "Content-Type": "application/json"
+    },
+    body: "{}"
+  });
+  if (!registerRes.ok) {
+    const err = await registerRes.json().catch(() => ({}));
+    const { message, code, documentationUrl } = parseApiError(registerRes.status, err);
+    throw new LetsPingError(message, registerRes.status, code, documentationUrl);
+  }
+  const reg = await registerRes.json();
+  if (!reg.agent_id || !reg.agent_secret) {
+    throw new LetsPingError("LetsPing Error: Invalid register response (missing agent_id or agent_secret)");
+  }
+  return {
+    project_id: redeem.project_id,
+    api_key: redeem.api_key,
+    ingest_url: redeem.ingest_url,
+    agents_register_url: redeem.agents_register_url,
+    agent_id: reg.agent_id,
+    agent_secret: reg.agent_secret,
+    org_id: redeem.org_id,
+    docs_url: redeem.docs_url
+  };
+}
+async function ingestWithAgentSignature(agentId, agentSecret, payload, options) {
+  const body = signIngestBody(agentId, agentSecret, {
+    project_id: options.projectId,
+    service: payload.service,
+    action: payload.action,
+    payload: payload.payload ?? {}
+  });
+  const res = await fetch(options.ingestUrl, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${options.apiKey}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(body)
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const { message, code, documentationUrl } = parseApiError(res.status, data);
+    throw new LetsPingError(message, res.status, code, documentationUrl);
+  }
+  return data;
+}
+function verifyAgentSignature(agentId, secret, call, signature) {
+  const { agent_signature } = signAgentCall(agentId, secret, call);
+  return agent_signature === signature;
+}
+function chainHandoff(previous, nextData, secret) {
+  const base = {
+    id: previous.id,
+    event: previous.event,
+    data: nextData.payload,
+    upstream_agent_id: nextData.upstream_agent_id,
+    downstream_agent_id: nextData.downstream_agent_id
+  };
+  const handoff_signature = createHmac("sha256", secret).update(JSON.stringify(base)).digest("hex");
+  return {
+    payload: nextData.payload,
+    escrow: {
+      mode: "handoff",
+      upstream_agent_id: nextData.upstream_agent_id,
+      downstream_agent_id: nextData.downstream_agent_id,
+      handoff_signature
+    }
+  };
+}
+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;
+    const r = options?.retry ?? {};
+    this.retry = {
+      maxAttempts: r.maxAttempts ?? 1,
+      initialDelayMs: r.initialDelayMs ?? 1e3,
+      maxDelayMs: r.maxDelayMs ?? 1e4
+    };
+  }
+  _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 = randomBytes(12);
+      const cipher = 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"
+    };
+  }
+  /**
+   * Send a request and block until a human approves or rejects it (or timeout). Use for HITL steps in your agent.
+   * @param options - service, action, payload; optional priority, schema, state_snapshot, timeoutMs, role
+   * @returns Decision with status APPROVED | REJECTED | APPROVED_WITH_MODIFICATIONS and payload (or patched_payload)
+   * @throws LetsPingError with code/documentationUrl on API or network errors, or LETSPING_TIMEOUT if no decision in time
+   * @see https://letsping.co/docs#ask
+   */
+  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 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"
+        }
+      });
+    }
+    const traceId = options.trace_id;
+    const parentId = options.parent_request_id;
+    const basePayload = options.payload || {};
+    const metaKey = "_lp_meta";
+    const existingMeta = basePayload[metaKey] || {};
+    const enrichedPayload = {
+      ...basePayload,
+      [metaKey]: {
+        ...existingMeta,
+        ...traceId ? { trace_id: traceId } : {},
+        ...parentId ? { parent_request_id: parentId } : {}
+      }
+    };
+    try {
+      const res = await this.request("POST", "/ingest", {
+        service: options.service,
+        action: options.action,
+        payload: this._encrypt(enrichedPayload),
+        priority: options.priority || "medium",
+        schema: options.schema,
+        metadata: { role: options.role, sdk: "node", trace_id: traceId, parent_request_id: parentId }
+      });
+      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);
+        }
+      }
+      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" };
+            }
+            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);
+      }
+      throw new LetsPingError(
+        `Request ${id} timed out waiting for approval.`,
+        void 0,
+        "LETSPING_TIMEOUT",
+        `${LETSPING_DOCS_BASE}#timeouts`
+      );
+    } catch (error) {
+      if (span) {
+        span.recordException(error);
+        span.setStatus({ code: otel.SpanStatusCode.ERROR });
+        span.end();
+      }
+      throw error;
+    }
+  }
+  /**
+   * Fetch the current status of a request by id. Use after defer() to poll until status is APPROVED or REJECTED without calling the raw HTTP API.
+   * @param id - Request id returned from defer()
+   * @returns RequestStatus with status PENDING | APPROVED | REJECTED, payload, resolved_at, actor_id
+   * @see https://letsping.co/docs#requests
+   */
+  async getRequestStatus(id) {
+    const raw = await this.request("GET", `/status/${id}`);
+    return raw;
+  }
+  /**
+   * Send a request and return immediately with the request id. Poll with getRequestStatus(id) or waitForDecision(id) until resolved.
+   * Use for async flows (e.g. webhook rehydration) where you do not want to block in-process.
+   * @param options - service, action, payload; optional priority, schema, state_snapshot, role
+   * @returns { id } - use id with getRequestStatus(id) or waitForDecision(id)
+   * @see https://letsping.co/docs#defer
+   */
+  async defer(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"
+        }
+      });
+    }
+    const traceId = options.trace_id;
+    const parentId = options.parent_request_id;
+    const basePayload = options.payload || {};
+    const metaKey = "_lp_meta";
+    const existingMeta = basePayload[metaKey] || {};
+    const enrichedPayload = {
+      ...basePayload,
+      [metaKey]: {
+        ...existingMeta,
+        ...traceId ? { trace_id: traceId } : {},
+        ...parentId ? { parent_request_id: parentId } : {}
+      }
+    };
+    try {
+      const res = await this.request("POST", "/ingest", {
+        service: options.service,
+        action: options.action,
+        payload: this._encrypt(enrichedPayload),
+        priority: options.priority || "medium",
+        schema: options.schema,
+        metadata: { role: options.role, sdk: "node", trace_id: traceId, parent_request_id: parentId }
+      });
+      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/${SDK_VERSION}`
+    };
+    const maxAttempts = Math.max(1, this.retry.maxAttempts);
+    let lastError = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+          method,
+          headers,
+          body: body ? JSON.stringify(body) : void 0
+        });
+        if (!response.ok) {
+          const errorText = await response.text();
+          let errorBody = {};
+          try {
+            errorBody = JSON.parse(errorText);
+          } catch {
+          }
+          const { message, code, documentationUrl } = parseApiError(response.status, errorBody);
+          lastError = new LetsPingError(message, response.status, code, documentationUrl);
+          const retryable = response.status === 429 || response.status >= 500;
+          if (retryable && attempt < maxAttempts) {
+            await this._delay(attempt);
+            continue;
+          }
+          throw lastError;
+        }
+        return await response.json();
+      } catch (e) {
+        if (e instanceof LetsPingError) {
+          lastError = e;
+          const retryable = e.status === 429 || e.status != null && e.status >= 500;
+          if (retryable && attempt < maxAttempts) {
+            await this._delay(attempt);
+            continue;
+          }
+          throw e;
+        }
+        lastError = new LetsPingError(
+          `Network Error: ${e?.message ?? "Unknown"}`,
+          void 0,
+          "LETSPING_NETWORK",
+          `${LETSPING_DOCS_BASE}#errors`
+        );
+        if (attempt < maxAttempts) {
+          await this._delay(attempt);
+          continue;
+        }
+        throw lastError;
+      }
+    }
+    throw lastError ?? new LetsPingError("Request failed", void 0, "LETSPING_NETWORK", `${LETSPING_DOCS_BASE}#errors`);
+  }
+  _delay(attempt) {
+    const delay = Math.min(
+      this.retry.initialDelayMs * Math.pow(1.5, attempt - 1) + Math.random() * 200,
+      this.retry.maxDelayMs
+    );
+    return new Promise((r) => setTimeout(r, delay));
+  }
+  /**
+   * Poll for a decision on a request created with defer(). Blocks until status is APPROVED/REJECTED or timeout.
+   * @param id - request id from defer()
+   * @param options - originalPayload (fallback if payload not in response), timeoutMs (default 24h)
+   * @returns Decision same shape as ask()
+   * @see https://letsping.co/docs#requests
+   */
+  async waitForDecision(id, options) {
+    const basePayload = options?.originalPayload || {};
+    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) ?? basePayload;
+          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" };
+          }
+          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);
+    }
+    throw new LetsPingError(
+      `Request ${id} timed out waiting for approval.`,
+      void 0,
+      "LETSPING_TIMEOUT",
+      `${LETSPING_DOCS_BASE}#timeouts`
+    );
+  }
+  /**
+   * Build a callable tool (e.g. for LangChain) that runs ask(service, action, payload) and returns a result string.
+   * @param service - LetsPing service name
+   * @param action - action name
+   * @param priority - optional priority (default medium)
+   * @returns Async function(context) => string; context can be JSON string or object
+   * @see https://letsping.co/docs#tool
+   */
+  tool(service, action, priority = "medium") {
+    return async (context) => {
+      let payload;
+      try {
+        if (typeof context === "string") {
+          try {
+            payload = JSON.parse(context);
+          } catch {
+            payload = { raw_context: context };
+          }
+        } else if (typeof context === "object" && context !== null) {
+          payload = context;
+        } else {
+          payload = { raw_context: String(context) };
+        }
+        const result = await this.ask({ service, action, payload, priority });
+        if (result.status === "REJECTED") {
+          return "STOP: Action Rejected by Human.";
+        }
+        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}`;
+      }
+    };
+  }
+  /**
+   * Validate and parse an incoming LetsPing webhook body. Verifies signature and optionally fetches/decrypts state_snapshot.
+   * @param payloadStr - raw request body (e.g. await req.text())
+   * @param signatureHeader - x-letsping-signature header
+   * @param webhookSecret - secret from dashboard → Settings → Webhooks
+   * @returns { id, event, data, state_snapshot } for resuming your workflow
+   * @throws LetsPingError with code LETSPING_WEBHOOK_INVALID and documentationUrl on invalid signature or replay
+   * @see https://letsping.co/docs#webhooks
+   */
+  async webhookHandler(payloadStr, signatureHeader, webhookSecret) {
+    const sigParts = signatureHeader.split(",").map((p) => p.split("="));
+    const sigMap = Object.fromEntries(sigParts);
+    const rawTs = sigMap["t"];
+    const rawSig = sigMap["v1"];
+    const docUrl = `${LETSPING_DOCS_BASE}#webhooks`;
+    if (!rawTs || !rawSig) {
+      throw new LetsPingError("LetsPing Error: Missing webhook signature fields", 401, "LETSPING_WEBHOOK_INVALID", docUrl);
+    }
+    const ts = Number(rawTs);
+    if (!Number.isFinite(ts)) {
+      throw new LetsPingError("LetsPing Error: Invalid webhook timestamp", 401, "LETSPING_WEBHOOK_INVALID", docUrl);
+    }
+    const now = Date.now();
+    const skewMs = Math.abs(now - ts);
+    const maxSkewMs = 5 * 60 * 1e3;
+    if (skewMs > maxSkewMs) {
+      throw new LetsPingError("LetsPing Error: Webhook replay window exceeded", 401, "LETSPING_WEBHOOK_INVALID", docUrl);
+    }
+    const expected = createHmac("sha256", webhookSecret).update(payloadStr).digest("hex");
+    if (rawSig !== expected) {
+      throw new LetsPingError("LetsPing Error: Invalid webhook signature", 401, "LETSPING_WEBHOOK_INVALID", docUrl);
+    }
+    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 = 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
+    };
+  }
+};
+export {
+  LETSPING_DOCS_BASE,
+  LetsPing,
+  LetsPingError,
+  chainHandoff,
+  computeDiff,
+  createAgentWorkspace,
+  ingestWithAgentSignature,
+  signAgentCall,
+  signIngestBody,
+  verifyAgentSignature,
+  verifyEscrow
+};
+//# sourceMappingURL=index.mjs.map