@letsping/sdk 0.1.5 → 0.1.6

package/README.md

@@ -10,9 +10,9 @@ LetsPing is a behavioral firewall and Human-in-the-Loop (HITL) infrastructure la
 - **Smart-Accept Drift Adaptation:** Approval decisions mathematically alter the baseline. Old unused reasoning paths decay automatically via Exponential Moving Average (EMA).
 
 ## Requirements
-
 - Node.js 18+
 - TypeScript 5+ (recommended)
+- (Optional) `@langchain/langgraph` and `@langchain/core` for state persistence
 
 ## Installation
 
@@ -96,7 +96,7 @@ console.log(`Approval request queued → ${id}`);
 LetsPing does **not** magically inject state back into your framework natively. You must handle the webhook and rehydrate your specific framework manually.
 
 ```typescript
-// Example Webhook Route Handler
+// app/api/webhook/letsping/route.ts
 if (body.status === "APPROVED") {
     let hydratedState = null;
     if (body.state_download_url) {
@@ -107,6 +107,21 @@ if (body.status === "APPROVED") {
 }
 ```
 
+### 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.
+
+```typescript
+import { StateGraph } from "@langchain/langgraph";
+import { LetsPing } from "@letsping/sdk";
+
+// Import the checkpointer from the specific integration path
+import { LetsPingCheckpointer } from "@letsping/sdk/integrations/langgraph";
+
+const lp = new LetsPing(process.env.LETSPING_API_KEY!);
+const checkpointer = new LetsPingCheckpointer(lp);
+```
+
 ## API Reference
 
 ### `new LetsPing(apiKey, options?)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letsping/sdk",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Behavioral Firewall and Cryo-Sleep State Parking for Autonomous Agents",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -10,6 +10,11 @@
       "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"
     }
   },
   "scripts": {
@@ -17,22 +22,31 @@
     "dev": "tsup --watch",
     "clean": "rm -rf dist .turbo"
   },
-  "dependencies": {},
   "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": {
-    "tsup": "^8.0.0",
-    "typescript": "^5.7.2",
+    "@langchain/core": "^1.1.28",
+    "@langchain/langgraph": "^1.1.5",
+    "@opentelemetry/api": "^1.9.0",
     "@types/node": "^22.0.0",
-    "@opentelemetry/api": "^1.9.0"
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.2"
   },
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/src/index.ts

@@ -1,6 +1,6 @@
 import { createCipheriv, createDecipheriv, randomBytes, createHmac } from "node:crypto";
 
-let SDK_VERSION = "0.1.5";
+let SDK_VERSION = "0.1.6";
 try {
 
     SDK_VERSION = require("../package.json").version;

package/src/integrations/langgraph.ts

@@ -0,0 +1,65 @@
+import { BaseCheckpointSaver, Checkpoint, CheckpointMetadata, CheckpointTuple } from "@langchain/langgraph";
+import { RunnableConfig } from "@langchain/core/runnables";
+import { LetsPing } from "../index";
+
+export class LetsPingCheckpointer extends BaseCheckpointSaver {
+    private checkpoints: Record<string, [Checkpoint, CheckpointMetadata]> = {};
+
+    constructor(public client: LetsPing) {
+        super();
+    }
+
+    async put(
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        newVersions?: Record<string, string | number>
+    ): Promise<RunnableConfig> {
+        const threadId = config.configurable?.thread_id;
+        const checkpointId = checkpoint.id;
+
+        this.checkpoints[`${threadId}:${checkpointId}`] = [checkpoint, metadata];
+
+        return {
+            configurable: {
+                thread_id: threadId,
+                checkpoint_id: checkpointId,
+            }
+        };
+    }
+
+    // --- NEW METHODS REQUIRED BY LANGGRAPH V0.1+ ---
+    async putWrites(config: RunnableConfig, writes: any, taskId: string): Promise<void> {
+        // No-op for V1: LetsPing focuses on primary state parking, not granular sub-task writes.
+    }
+
+    async deleteThread(threadId: string): Promise<void> {
+        for (const key of Object.keys(this.checkpoints)) {
+            if (key.startsWith(`${threadId}:`)) {
+                delete this.checkpoints[key];
+            }
+        }
+    }
+
+    async getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined> {
+        const threadId = config.configurable?.thread_id;
+        const checkpointId = config.configurable?.checkpoint_id;
+
+        if (checkpointId) {
+            const match = this.checkpoints[`${threadId}:${checkpointId}`];
+            if (match) return { config, checkpoint: match[0], metadata: match[1] };
+        }
+
+        let latest: CheckpointTuple | undefined;
+        for (const [key, val] of Object.entries(this.checkpoints)) {
+            if (key.startsWith(`${threadId}:`)) {
+                latest = { config, checkpoint: val[0], metadata: val[1] };
+            }
+        }
+        return latest;
+    }
+
+    async *list(config: RunnableConfig, options?: any): AsyncGenerator<CheckpointTuple> {
+        yield* [];
+    }
+}

package/tsup.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig } from "tsup";
 
 export default defineConfig({
-    entry: ["src/index.ts"],
+    entry: ["src/index.ts", "src/integrations/langgraph.ts"],
     format: ["cjs", "esm"],
     dts: true,
     clean: true,

package/dist/index.d.mts

@@ -1,37 +0,0 @@
-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

@@ -1,52 +0,0 @@
-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;
-}
-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 };