@letsping/sdk 0.2.1 → 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,6 +4,8 @@ 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.
@@ -11,8 +13,8 @@ LetsPing is a behavioral firewall and Human-in-the-Loop (HITL) infrastructure la
 - **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
@@ -263,13 +265,21 @@ interface Decision {
 }
 ```
 
-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.
@@ -341,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.1",
-  "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

@@ -27,6 +27,8 @@ export interface EscrowEnvelope {
         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;
@@ -54,6 +56,35 @@ export declare function signIngestBody(agentId: string, secret: string, body: {
     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;
@@ -69,24 +100,37 @@ export declare function chainHandoff(previous: EscrowEnvelope, nextData: {
         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;
-    }>;
-    waitForDecision(id: string, options?: {
-        originalPayload?: Record<string, any>;
-        timeoutMs?: number;
-    }): Promise<Decision>;
-    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> }>;
 }

package/src/index.ts

@@ -62,13 +62,85 @@ export interface Decision {
     };
 }
 
+/** Status of a request returned by GET /status/:id. Use with defer() + getRequestStatus() for polling without reading the raw HTTP API. */
+export interface RequestStatus {
+    id: string;
+    status: "PENDING" | "APPROVED" | "REJECTED";
+    payload?: any;
+    patched_payload?: any;
+    resolved_at?: string | null;
+    actor_id?: string | null;
+}
+
+/** Base URL for error documentation. Errors may include a link to a specific anchor. */
+export const LETSPING_DOCS_BASE = "https://letsping.co/docs";
+
+/** Known error codes for programmatic handling and doc links. */
+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 class LetsPingError extends Error {
-    constructor(message: string, public status?: number) {
+    /** HTTP status when the error came from the API (e.g. 402, 429). */
+    public readonly status?: number;
+    /** Stable code for handling (e.g. LETSPING_402_QUOTA). Use for branching or logging. */
+    public readonly code?: LetsPingErrorCode;
+    /** Link to the relevant doc section. Present when code is set. */
+    public readonly documentationUrl?: string;
+
+    constructor(
+        message: string,
+        status?: number,
+        code?: LetsPingErrorCode,
+        documentationUrl?: string
+    ) {
         super(message);
         this.name = "LetsPingError";
+        this.status = status;
+        this.code = code ?? (status ? statusToCode(status) : undefined);
+        this.documentationUrl = documentationUrl ?? (this.code ? codeToDocUrl(this.code) : undefined);
     }
 }
 
+function statusToCode(status: number): LetsPingErrorCode {
+    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}` as LetsPingErrorCode);
+    }
+}
+
+function codeToDocUrl(code: LetsPingErrorCode): string {
+    const anchor: Record<string, string> = {
+        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: number, body: { message?: string; error?: string; code?: string }): { message: string; code: LetsPingErrorCode; documentationUrl: string } {
+    const message = body?.message ?? body?.error ?? `API Error [${responseStatus}]`;
+    const code = (body?.code as LetsPingErrorCode) ?? statusToCode(responseStatus);
+    return { message, code, documentationUrl: codeToDocUrl(code) };
+}
+
 interface EncEnvelope {
     _lp_enc: true;
     iv: string;
@@ -162,6 +234,8 @@ export interface EscrowEnvelope {
         handoff_signature: string | null;
         upstream_agent_id: string | null;
         downstream_agent_id: string | null;
+        x402_mandate?: any;
+        ap2_mandate?: any;
     };
 }
 
@@ -173,6 +247,8 @@ export function verifyEscrow(event: EscrowEnvelope, secret: string): boolean {
         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;
@@ -232,6 +308,139 @@ export function signIngestBody(
     };
 }
 
+/** Credentials returned by createAgentWorkspace. Use api_key for Bearer auth and ingestWithAgentSignature for signed ingest. */
+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;
+}
+
+/**
+ * Request a signup token, redeem it to create a workspace, and register one agent. Returns credentials so the agent can call ingestWithAgentSignature.
+ * Rate limits apply (see letsping.co/docs). Throws on 4xx/5xx or if self-serve signup is disabled.
+ * @param options.baseUrl - App root URL (e.g. https://letsping.co). Defaults to LETSPING_BASE_URL or https://letsping.co.
+ */
+export async function createAgentWorkspace(options?: { baseUrl?: string }): Promise<AgentWorkspaceCredentials> {
+    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(() => ({})) as { error?: string; code?: string };
+        const { message, code, documentationUrl } = parseApiError(tokenRes.status, err);
+        throw new LetsPingError(message, tokenRes.status, code, documentationUrl);
+    }
+    const { token } = (await tokenRes.json()) as { token: string };
+    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(() => ({})) as { error?: string; message?: string };
+        const { message, code, documentationUrl } = parseApiError(redeemRes.status, err);
+        throw new LetsPingError(message, redeemRes.status, code, documentationUrl);
+    }
+    const redeem = (await redeemRes.json()) as {
+        project_id: string;
+        api_key: string;
+        ingest_url: string;
+        agents_register_url: string;
+        org_id?: string;
+        docs_url?: string;
+    };
+    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(() => ({})) as { error?: string };
+        const { message, code, documentationUrl } = parseApiError(registerRes.status, err);
+        throw new LetsPingError(message, registerRes.status, code, documentationUrl);
+    }
+    const reg = (await registerRes.json()) as { agent_id: string; agent_secret: string };
+    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,
+    };
+}
+
+/** Options for ingestWithAgentSignature. */
+export interface IngestWithAgentSignatureOptions {
+    projectId: string;
+    ingestUrl: string;
+    apiKey: string;
+}
+
+/** Ingest payload: service, action, and payload. */
+export interface IngestPayload {
+    service: string;
+    action: string;
+    payload: Record<string, any>;
+}
+
+/**
+ * Build a signed ingest body and POST it to the ingest URL with Bearer apiKey. Returns the JSON response; throws on non-2xx.
+ * Use this so the agent quickstart does not require hand-rolled HMAC or curl. See also: signIngestBody.
+ */
+export async function ingestWithAgentSignature(
+    agentId: string,
+    agentSecret: string,
+    payload: IngestPayload,
+    options: IngestWithAgentSignatureOptions
+): Promise<Record<string, any>> {
+    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(() => ({}))) as Record<string, any>;
+    if (!res.ok) {
+        const { message, code, documentationUrl } = parseApiError(res.status, data as { error?: string });
+        throw new LetsPingError(message, res.status, code, documentationUrl);
+    }
+    return data;
+}
+
 export function verifyAgentSignature(
     agentId: string,
     secret: string,
@@ -276,12 +485,23 @@ export function chainHandoff(previous: EscrowEnvelope, nextData: {
     };
 }
 
+/** Optional retry config for ingest and status calls. Disabled when maxAttempts is 1 or omitted. */
+export interface RetryOptions {
+    /** Max attempts per request (default 1 = no retry). Try 3 for transient resilience. */
+    maxAttempts?: number;
+    /** Initial delay in ms before first retry (default 1000). */
+    initialDelayMs?: number;
+    /** Cap on delay between retries in ms (default 10000). */
+    maxDelayMs?: number;
+}
+
 export class LetsPing {
     private readonly apiKey: string;
     private readonly baseUrl: string;
     private readonly encryptionKey: string | null;
+    private readonly retry: Required<RetryOptions>;
 
-    constructor(apiKey?: string, options?: { baseUrl?: string; encryptionKey?: string }) {
+    constructor(apiKey?: string, options?: { baseUrl?: string; encryptionKey?: string; retry?: RetryOptions }) {
         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.");
 
@@ -290,6 +510,12 @@ export class LetsPing {
         this.encryptionKey = options?.encryptionKey
             ?? process.env.LETSPING_ENCRYPTION_KEY
             ?? null;
+        const r = options?.retry ?? {};
+        this.retry = {
+            maxAttempts: r.maxAttempts ?? 1,
+            initialDelayMs: r.initialDelayMs ?? 1000,
+            maxDelayMs: r.maxDelayMs ?? 10000,
+        };
     }
 
     private _encrypt(payload: Record<string, any>): Record<string, any> {
@@ -335,6 +561,13 @@ export class LetsPing {
         };
     }
 
+    /**
+     * 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: RequestOptions): Promise<Decision> {
         if (options.schema && (options.schema as any)._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.");
@@ -447,8 +680,13 @@ export class LetsPing {
                 delay = Math.min(delay * 1.5, maxDelay);
             }
 
-            throw new LetsPingError(`Request ${id} timed out waiting for approval.`);
-        } catch (error: any) {
+        throw new LetsPingError(
+            `Request ${id} timed out waiting for approval.`,
+            undefined,
+            "LETSPING_TIMEOUT",
+            `${LETSPING_DOCS_BASE}#timeouts`
+        );
+    } catch (error: any) {
             if (span) {
                 span.recordException(error);
                 span.setStatus({ code: otel.SpanStatusCode.ERROR });
@@ -458,6 +696,24 @@ export class LetsPing {
         }
     }
 
+    /**
+     * 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: string): Promise<RequestStatus> {
+        const raw = await this.request<RequestStatus>("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: RequestOptions): Promise<{ id: string }> {
         const otel = await getOtel();
         let span: any = null;
@@ -533,30 +789,76 @@ export class LetsPing {
             "User-Agent": `letsping-node/${SDK_VERSION}`,
         };
 
-        try {
-            const response = await fetch(`${this.baseUrl}${path}`, {
-                method,
-                headers,
-                body: body ? JSON.stringify(body) : undefined,
-            });
+        const maxAttempts = Math.max(1, this.retry.maxAttempts);
+        let lastError: LetsPingError | null = null;
 
-            if (!response.ok) {
-                const errorText = await response.text();
-                let message = errorText;
-                try {
-                    const json = JSON.parse(errorText);
-                    if (json.message) message = json.message;
-                } catch { }
-                throw new LetsPingError(`API Error [${response.status}]: ${message}`, response.status);
-            }
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                const response = await fetch(`${this.baseUrl}${path}`, {
+                    method,
+                    headers,
+                    body: body ? JSON.stringify(body) : undefined,
+                });
 
-            return response.json() as Promise<T>;
-        } catch (e: any) {
-            if (e instanceof LetsPingError) throw e;
-            throw new LetsPingError(`Network Error: ${e.message}`);
+                if (!response.ok) {
+                    const errorText = await response.text();
+                    let errorBody: { message?: string; error?: string; code?: string } = {};
+                    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() as T;
+            } catch (e: any) {
+                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"}`,
+                    undefined,
+                    "LETSPING_NETWORK",
+                    `${LETSPING_DOCS_BASE}#errors`
+                );
+                if (attempt < maxAttempts) {
+                    await this._delay(attempt);
+                    continue;
+                }
+                throw lastError;
+            }
         }
+
+        throw lastError ?? new LetsPingError("Request failed", undefined, "LETSPING_NETWORK", `${LETSPING_DOCS_BASE}#errors`);
     }
 
+    private _delay(attempt: number): Promise<void> {
+        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: string,
         options?: { originalPayload?: Record<string, any>; timeoutMs?: number }
@@ -604,9 +906,22 @@ export class LetsPing {
             delay = Math.min(delay * 1.5, maxDelay);
         }
 
-        throw new LetsPingError(`Request ${id} timed out waiting for approval.`);
+        throw new LetsPingError(
+            `Request ${id} timed out waiting for approval.`,
+            undefined,
+            "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: string, action: string, priority: Priority = "medium"): (context: string | Record<string, any>) => Promise<string> {
         return async (context: string | Record<string, any>): Promise<string> => {
             let payload: Record<string, any>;
@@ -646,6 +961,15 @@ export class LetsPing {
         };
     }
 
+    /**
+     * 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: string,
         signatureHeader: string,
@@ -656,25 +980,26 @@ export class LetsPing {
 
         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);
+            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);
+            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 * 1000; // 5 minutes
         if (skewMs > maxSkewMs) {
-            throw new LetsPingError("LetsPing Error: Webhook replay window exceeded", 401);
+            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);
+            throw new LetsPingError("LetsPing Error: Invalid webhook signature", 401, "LETSPING_WEBHOOK_INVALID", docUrl);
         }
 
         const payload = JSON.parse(payloadStr);