@letsping/sdk 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-02-28
+
+### Added
+- First-run experience: single-command demo path and dashboard "Run this" flow for time to first approval.
+- Framework-specific examples: LangGraph + Next.js, Vercel AI SDK + tools, Python + FastAPI (clone, set key, run).
+- Agent path in SDK: helpers for agent workspace creation and signed ingest so agent quickstart does not require raw curl/HMAC.
+- Ergonomic improvements: structured error codes with documentation links, JSDoc "See also" on key methods, optional retries and status helper for defer flows.
+- README "Guides" section: HITL in 2 min, LangGraph, Vercel AI SDK, agent-only, webhooks (links to docs and examples).
+
+### Changed
+- Compatibility: Node.js 18+ (unchanged). All packages aligned to 0.3.0 for coordinated release; public CordiaLabs/LetsPing repo synced with examples and READMEs.
+
+## [0.2.1] - 2025-02-28
+
+### Changed
+- Package metadata: repository, homepage, license, keywords, engines (Node 18+).
+
+## [0.2.0] - 2025-02
+
+### Added
+- LangGraph integration (`@letsping/sdk/integrations/langgraph`) for state persistence and HITL.
+- Agent identity and escrow helpers: `signAgentCall`, `verifyEscrow`, `chainHandoff`.
+- Cryo-Sleep state parking with signed URLs.
+- Behavioral firewall (Markov-based anomaly detection) and smart-accept drift.
+
+### Changed
+- Improved TypeScript types and exports.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 LetsPing / Cordia Labs
+
+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

@@ -4,14 +4,17 @@ The official Node.js/TypeScript SDK for [LetsPing](https://letsping.co).
 
 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.
 
+**What you get with this SDK:** One client that connects your agent to the full LetsPing stack: a hosted dashboard for triage and approvals, a Markov-based behavioral firewall that learns your graph and intercepts anomalies, Cryo-Sleep state parking so long-running flows survive serverless limits, and audit trails for compliance. Use LangGraph (or any runtime) for the graph; use LetsPing for the human layer and guardrails.
+
 ### 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).
+- **Agent Identity & Escrow Helpers:** Optional HMAC-based helpers (`signAgentCall`, `verifyEscrow`, `chainHandoff`) for cryptographically linking agent calls and handoffs to LetsPing requests.
 
 ## Requirements
-- Node.js 18+
-- TypeScript 5+ (recommended)
+
+- **Compatibility:** Node.js 18+. TypeScript 5+ recommended.
 - (Optional) `@langchain/langgraph` and `@langchain/core` for state persistence
 
 ## Installation
@@ -22,6 +25,27 @@ npm install @letsping/sdk
 
 ## Usage
 
+### Minimal drop-in example
+
+The fastest way to see your first approval in the dashboard:
+
+```ts
+import { LetsPing } from "@letsping/sdk";
+
+const apiKey = process.env.LETSPING_API_KEY;
+if (!apiKey) throw new Error("Missing LETSPING_API_KEY env var.");
+
+const lp = new LetsPing(apiKey);
+
+const decision = await lp.ask({
+  service: "billing-agent",
+  action: "refund_user",
+  payload: { user_id: "u_123", amount: 100 },
+});
+```
+
+Every example in this README follows the same pattern: **either pass the key explicitly or rely on `LETSPING_API_KEY` via env**.
+
 ### Blocking Request (`ask`)
 
 Execution suspends until the request is approved, rejected, or times out.
@@ -34,7 +58,7 @@ const lp = new LetsPing(process.env.LETSPING_API_KEY!);
 async function processRefund(userId: string, amount: number) {
   try {
     const decision = await lp.ask({
-      service: "billing-service",
+      service: "billing-agent",
       action: "refund_user",
       priority: "high",
       payload: { userId, amount },
@@ -199,7 +223,7 @@ export async function POST(req: NextRequest) {
 }
 ```
 
-In your agent runner, you simply include `thread_id` and `state_snapshot` when you first call LetsPing from inside a LangGraph node. The checkpointer and webhook then keep the thread resumable across restarts.
+In your agent runner, you simply include `thread_id` and `state_snapshot` when you first call LetsPing from inside a LangGraph node. The checkpointer and webhook then keep the thread resumable across restarts. If the human edited the payload in the dashboard, `data.patched_payload` (or `data.payload`) is available in the webhook payload — use your framework’s normal state-update or channel overwrite semantics to inject the approved payload into the resumed graph so the run sees the correct values.
 
 ## API Reference
 
@@ -219,7 +243,7 @@ Blocks until resolved (approve / reject / timeout).
 | `payload`    | `Record<string, any>`           | Context passed to human operator (and returned in Decision)                 |
 | `priority`   | `"low" \| "medium" \| "high" \| "critical"` | Routing priority in dashboard                                               |
 | `schema`     | `object`                        | JSON Schema (draft 07) — generates editable form in dashboard               |
-| `timeoutMs`  | `number`                        | Max wait time (default: 86_400_000 ms = 24 hours)                           |
+| `timeoutMs`  | `number`                        | Max wait time in **milliseconds** (default: 86_400_000 ms = 24 hours)      |
 
 ### `lp.defer(options): Promise<{ id: string }>`
 
@@ -229,19 +253,40 @@ Fire-and-forget: queues request and returns request ID immediately. Same options
 
 ```typescript
 interface Decision {
-  status: "APPROVED" | "REJECTED";
+  status: "APPROVED" | "REJECTED" | "APPROVED_WITH_MODIFICATIONS";
   payload: Record<string, any>;          // Original payload sent by agent
   patched_payload?: Record<string, any>; // Human-edited values (if modified)
-  metadata: {
+  diff_summary?: any;                    // Field-level diff between payload and patched_payload
+  metadata?: {
     actor_id: string;                    // ID/email of the approving/rejecting human
     resolved_at: string;                 // ISO 8601 timestamp
+    method?: string;                     // Optional resolution method (e.g. "dashboard")
   };
 }
 ```
 
-For full documentation, request schema examples, error codes, and dashboard integration see:  
+**Structured errors:** All API and network errors are thrown as `LetsPingError` with optional `status`, `code` (e.g. `LETSPING_402_QUOTA`, `LETSPING_429_RATE_LIMIT`, `LETSPING_TIMEOUT`), and `documentationUrl` so you can branch or log and link users to the right doc. See https://letsping.co/docs#errors.
+
+**Optional retries:** Pass `retry: { maxAttempts: 3, initialDelayMs: 1000, maxDelayMs: 10000 }` in the constructor to enable exponential backoff for ingest and status calls (429 and 5xx are retried).
+
+**Status helper:** Use `lp.getRequestStatus(id)` after `defer()` to poll for request status without calling the raw HTTP API. See https://letsping.co/docs#requests.
+
+For full documentation, request schema examples, and dashboard integration see:  
 https://letsping.co/docs#sdk
 
+### Agent-to-Agent Escrow (optional)
+
+For multi-agent systems that want cryptographic guarantees around handoffs, the SDK exposes:
+
+- `createAgentWorkspace(options?)` to do request-token → redeem → register in one call. Returns `{ project_id, api_key, ingest_url, agent_id, agent_secret }` so the agent gets its own workspace without a human. Rate limits apply; see [agent quickstart](https://letsping.co/agent/quickstart).
+- `ingestWithAgentSignature(agentId, agentSecret, payload, options)` to POST a signed ingest (no hand-rolled HMAC or curl). Options: `{ projectId, ingestUrl, apiKey }`.
+- `signAgentCall(agentId, secret, call)` to attach `agent_id` and `agent_signature` to `/ingest` calls.
+- `signIngestBody(agentId, secret, body)` to take an existing ingest body (`{ project_id, service, action, payload }`) and return it with `agent_id` and `agent_signature` attached.
+- `verifyEscrow(event, secret)` to validate LetsPing escrow webhooks.
+- `chainHandoff(previous, nextData, secret)` to safely construct downstream handoffs tied to the original request id.
+
+See the one-page spec at `/docs/agent-escrow-spec` in the LetsPing web app for the exact wire format and interoperability rules.
+
 Deploy agents with confidence.
 
 ## 2-Minute Demo (Node/TypeScript)
@@ -306,4 +351,10 @@ const lp = new LetsPing(process.env.LETSPING_API_KEY!, {
 });
 ```
 
-All `ask` / `defer` calls made through that client will flow through your local tunnel into the LetsPing dashboard.
+All `ask` / `defer` calls made through that client will flow through your local tunnel into the LetsPing dashboard.
+
+---
+
+**Compatibility:** Node 18+, TypeScript 5+. Optional: `@langchain/langgraph`, `@langchain/core` for LangGraph integration.
+
+**License:** MIT. Source: [CordiaLabs/LetsPing](https://github.com/CordiaLabs/LetsPing) (packages/sdk).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@letsping/sdk",
-  "version": "0.2.0",
-  "description": "Behavioral Firewall and Cryo-Sleep State Parking for Autonomous Agents",
+  "version": "0.3.0",
+  "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",
@@ -22,6 +22,22 @@
     "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",
@@ -48,5 +64,10 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CordiaLabs/LetsPing.git",
+    "directory": "packages/sdk"
   }
-}
+}

package/src/index.d.ts

@@ -8,28 +8,129 @@ export interface RequestOptions {
     timeoutMs?: number;
 }
 export interface Decision {
-    status: "APPROVED" | "REJECTED";
+    status: "APPROVED" | "REJECTED" | "APPROVED_WITH_MODIFICATIONS";
     payload: any;
     patched_payload?: any;
+    diff_summary?: any;
     metadata?: {
         resolved_at: string;
         actor_id: string;
         method?: string;
     };
 }
+export interface EscrowEnvelope {
+    id: string;
+    event: string;
+    data: any;
+    escrow?: {
+        mode: "none" | "handoff" | "finalized";
+        handoff_signature: string | null;
+        upstream_agent_id: string | null;
+        downstream_agent_id: string | null;
+        x402_mandate?: any;
+        ap2_mandate?: any;
+    };
+}
+export declare function verifyEscrow(event: EscrowEnvelope, secret: string): boolean;
+export interface AgentCallPayload {
+    project_id: string;
+    service: string;
+    action: string;
+    payload: any;
+}
+export declare function signAgentCall(agentId: string, secret: string, call: AgentCallPayload): {
+    agent_id: string;
+    agent_signature: string;
+};
+export declare function signIngestBody(agentId: string, secret: string, body: {
+    project_id: string;
+    service: string;
+    action: string;
+    payload: any;
+}): {
+    project_id: string;
+    service: string;
+    action: string;
+    payload: any;
+    agent_id: string;
+    agent_signature: string;
+};
+export declare function verifyAgentSignature(agentId: string, secret: string, call: AgentCallPayload, signature: string): boolean;
+
+export interface AgentWorkspaceCredentials {
+    project_id: string;
+    api_key: string;
+    ingest_url: string;
+    agents_register_url: string;
+    agent_id: string;
+    agent_secret: string;
+    org_id?: string;
+    docs_url?: string;
+}
+export declare function createAgentWorkspace(options?: { baseUrl?: string }): Promise<AgentWorkspaceCredentials>;
+
+export interface IngestWithAgentSignatureOptions {
+    projectId: string;
+    ingestUrl: string;
+    apiKey: string;
+}
+export interface IngestPayload {
+    service: string;
+    action: string;
+    payload: Record<string, any>;
+}
+export declare function ingestWithAgentSignature(
+    agentId: string,
+    agentSecret: string,
+    payload: IngestPayload,
+    options: IngestWithAgentSignatureOptions
+): Promise<Record<string, any>>;
+export declare function chainHandoff(previous: EscrowEnvelope, nextData: {
+    service: string;
+    action: string;
+    payload: any;
+    upstream_agent_id: string;
+    downstream_agent_id: string;
+}, secret: string): {
+    payload: any;
+    escrow: {
+        mode: "handoff";
+        upstream_agent_id: string;
+        downstream_agent_id: string;
+        handoff_signature: string;
+    };
+};
+export declare const LETSPING_DOCS_BASE: string;
+export type LetsPingErrorCode = "LETSPING_401_AUTH" | "LETSPING_402_QUOTA" | "LETSPING_403_FORBIDDEN" | "LETSPING_404_NOT_FOUND" | "LETSPING_429_RATE_LIMIT" | "LETSPING_TIMEOUT" | "LETSPING_NETWORK" | "LETSPING_WEBHOOK_INVALID" | string;
 export declare class LetsPingError extends Error {
-    status?: number | undefined;
-    constructor(message: string, status?: number | undefined);
+    status?: number;
+    code?: LetsPingErrorCode;
+    documentationUrl?: string;
+    constructor(message: string, status?: number, code?: LetsPingErrorCode, documentationUrl?: string);
+}
+export interface RetryOptions {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+}
+export interface RequestStatus {
+    id: string;
+    status: "PENDING" | "APPROVED" | "REJECTED";
+    payload?: any;
+    patched_payload?: any;
+    resolved_at?: string | null;
+    actor_id?: string | null;
 }
 export declare class LetsPing {
-    private readonly apiKey;
-    private readonly baseUrl;
     constructor(apiKey?: string, options?: {
         baseUrl?: string;
+        encryptionKey?: string;
+        retry?: RetryOptions;
     });
     ask(options: RequestOptions): Promise<Decision>;
-    defer(options: RequestOptions): Promise<{
-        id: string;
-    }>;
-    private request;
+    defer(options: RequestOptions): Promise<{ id: string }>;
+    waitForDecision(id: string, options?: { originalPayload?: Record<string, any>; timeoutMs?: number }): Promise<Decision>;
+    getRequestStatus(id: string): Promise<RequestStatus>;
+    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> }>;
 }