@letsping/sdk 0.1.6 → 0.2.0

package/README.md

@@ -92,36 +92,115 @@ const { id } = await lp.defer({
 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.
+### Webhook Rehydration (Next.js Example)
+
+When you pass `state_snapshot` to `ask` / `defer`, the SDK:
+
+- Encrypts the snapshot with either `LETSPING_ENCRYPTION_KEY` or a one‑time DEK.
+- Uploads it directly to your storage bucket using a signed URL.
+- Includes a `state_download_url` (and DEK) in subsequent webhooks.
+
+You can use the built‑in `webhookHandler` to validate and hydrate webhooks in a Next.js App Router route:
 
 ```typescript
-// app/api/webhook/letsping/route.ts
-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
+// Example Next.js App Router route
+import { NextRequest, NextResponse } from "next/server";
+import { LetsPing } from "@letsping/sdk";
+
+const lp = new LetsPing();
+const WEBHOOK_SECRET = process.env.LETSPING_WEBHOOK_SECRET!;
+
+export async function POST(req: NextRequest) {
+  const rawBody = await req.text();
+  const signature = req.headers.get("x-letsping-signature") || "";
+
+  try {
+    const { id, event, data, state_snapshot } = await lp.webhookHandler(
+      rawBody,
+      signature,
+      WEBHOOK_SECRET
+    );
+
+    // At this point:
+    // - `data` contains the decision payload (status, payload, patched_payload, metadata, etc.)
+    // - `state_snapshot` contains your decrypted agent state, if Cryo-Sleep was used.
+
+    await handleDecision({ id, event, data, state_snapshot });
+
+    return NextResponse.json({ ok: true });
+  } catch (err: any) {
+    console.error("LetsPing webhook error:", err);
+    return NextResponse.json({ error: "invalid webhook" }, { status: 400 });
+  }
+}
+
+async function handleDecision(args: {
+  id: string;
+  event: string;
+  data: any;
+  state_snapshot?: Record<string, any>;
+}) {
+  // Example: resume a workflow run or LangGraph thread using `state_snapshot`
 }
 ```
 
+This pattern works similarly for Express/Fastify — call `lp.webhookHandler(rawBody, signature, secret)`, then resume your framework using the provided `state_snapshot`.
+
 ### LangGraph Integration (Persisted State)
 
-LetsPing provides a `LetsPingCheckpointer` for LangGraph JS/TS that automatically encrypts and parks your agent's state in Cryo-Sleep storage.
+LetsPing provides a `LetsPingCheckpointer` for LangGraph JS/TS under `@letsping/sdk/integrations/langgraph`.  
+In v0.2 this checkpointer persists checkpoints **remotely** via the LetsPing control plane — encrypted alongside your existing Cryo‑Sleep state in Supabase Storage. Threads can survive process restarts without you wiring your own database.
 
 ```typescript
 import { StateGraph } from "@langchain/langgraph";
 import { LetsPing } from "@letsping/sdk";
+import { LetsPingCheckpointer } from "@letsping/sdk/integrations/langgraph";
+
+const lp = new LetsPing(process.env.LETSPING_API_KEY!);
+const checkpointer = new LetsPingCheckpointer(lp);
+
+const builder = new StateGraph<any /* your state type */>({});
+const graph = builder.compile({ checkpointer });
+```
+
+#### Auto‑resuming a thread after approval (webhook + checkpointer)
 
-// Import the checkpointer from the specific integration path
+Because checkpoints are stored remotely, you can resume a LangGraph thread from any worker once a human clicks Approve. A minimal Next.js webhook + auto‑resume flow looks like:
+
+```ts
+// Example Next.js App Router route for LangGraph auto-resume
+import { NextRequest, NextResponse } from "next/server";
+import { LetsPing } from "@letsping/sdk";
+import { StateGraph } from "@langchain/langgraph";
 import { LetsPingCheckpointer } from "@letsping/sdk/integrations/langgraph";
+import { graphBuilder } from "@/lib/langgraph"; // your app's graph definition
 
 const lp = new LetsPing(process.env.LETSPING_API_KEY!);
 const checkpointer = new LetsPingCheckpointer(lp);
+const graph = graphBuilder.compile({ checkpointer });
+
+export async function POST(req: NextRequest) {
+  const raw = await req.text();
+  const sig = req.headers.get("x-letsping-signature") || "";
+
+  const event = await lp.webhookHandler(raw, sig, process.env.LETSPING_WEBHOOK_SECRET!);
+  const { data, state_snapshot } = event;
+
+  // You decide how to encode the thread id into your state snapshot.
+  const threadId = state_snapshot?.thread_id as string | undefined;
+  if (!threadId) return NextResponse.json({ ok: false, error: "missing_thread_id" }, { status: 400 });
+
+  // Resume the graph from the latest remote checkpoint.
+  await graph.invoke(state_snapshot.input, {
+    configurable: { thread_id: threadId },
+  });
+
+  return NextResponse.json({ ok: true });
+}
 ```
 
+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.
+
 ## API Reference
 
 ### `new LetsPing(apiKey, options?)`
@@ -163,4 +242,68 @@ interface Decision {
 For full documentation, request schema examples, error codes, and dashboard integration see:  
 https://letsping.co/docs#sdk
 
-Deploy agents with confidence.
+Deploy agents with confidence.
+
+## 2-Minute Demo (Node/TypeScript)
+
+You can feel the full LetsPing loop (intercept → approve → resume) in under 2 minutes.
+
+```ts
+// demo.ts
+import { LetsPing } from "@letsping/sdk";
+
+async function main() {
+  const apiKey = process.env.LETSPING_API_KEY;
+  if (!apiKey) {
+    console.error("Missing LETSPING_API_KEY env var.");
+    process.exit(1);
+  }
+
+  const lp = new LetsPing(apiKey);
+
+  console.log("Sending demo approval request to LetsPing…");
+  const decision = await lp.ask({
+    service: "demo-agent",
+    action: "transfer_funds",
+    priority: "high",
+    payload: {
+      amount: 500,
+      currency: "USD",
+      recipient: "acct_demo_123",
+    },
+  });
+
+  if (decision.status === "REJECTED") {
+    console.log("Demo request REJECTED by human. No action taken.");
+  } else if (decision.status === "APPROVED_WITH_MODIFICATIONS") {
+    console.log("APPROVED WITH MODIFICATIONS:");
+    console.dir(decision.diff_summary, { depth: null });
+  } else {
+    console.log("APPROVED with original payload.");
+  }
+}
+
+main().catch((err) => {
+  console.error("Demo failed:", err);
+  process.exit(1);
+});
+```
+
+Run:
+
+```bash
+export LETSPING_API_KEY="lp_live_..."
+node demo.ts
+```
+
+Then open the LetsPing dashboard for your project, approve/reject the `demo-agent / transfer_funds` request, and watch the script resume.
+
+If you’re using the local tunnel (`npx @letsping/cli dev`), you can also point the SDK at it during local development:
+
+```ts
+const lp = new LetsPing(process.env.LETSPING_API_KEY!, {
+  baseUrl: "http://localhost:<port>/api",
+});
+```
+
+All `ask` / `defer` calls made through that client will flow through your local tunnel into the LetsPing dashboard.

package/dist/index.d.mts

@@ -0,0 +1,37 @@
+type Priority = "low" | "medium" | "high" | "critical";
+interface RequestOptions {
+    service: string;
+    action: string;
+    payload: Record<string, any>;
+    priority?: Priority;
+    schema?: Record<string, any>;
+    timeoutMs?: number;
+}
+interface Decision {
+    status: "APPROVED" | "REJECTED";
+    payload: any;
+    patched_payload?: any;
+    metadata?: {
+        resolved_at: string;
+        actor_id: string;
+        method?: string;
+    };
+}
+declare class LetsPingError extends Error {
+    status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+declare class LetsPing {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(apiKey?: string, options?: {
+        baseUrl?: string;
+    });
+    ask(options: RequestOptions): Promise<Decision>;
+    defer(options: RequestOptions): Promise<{
+        id: string;
+    }>;
+    private request;
+}
+
+export { type Decision, LetsPing, LetsPingError, type Priority, type RequestOptions };

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+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;
+    /**
+     * Optional distributed tracing identifiers. If provided, these will be
+     * attached to the request envelope so downstream frameworks can stitch
+     * together multi-agent flows.
+     */
+    trace_id?: string;
+    parent_request_id?: string;
+}
+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;
+    };
+}
+export declare class LetsPingError extends Error {
+    status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+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 { computeDiff };