@letsping/sdk 0.1.0

package/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "@letsping/sdk",
+    "version": "0.1.0",
+    "description": "The Human-in-the-Loop SDK for Autonomous Agents",
+    "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"
+        }
+    },
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "clean": "rm -rf dist .turbo"
+    },
+    "dependencies": {},
+    "devDependencies": {
+        "tsup": "^8.0.0",
+        "typescript": "^5.0.0",
+        "@types/node": "^20.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/index.ts

@@ -0,0 +1,122 @@
+export type Priority = "low" | "medium" | "high" | "critical";
+
+export interface RequestOptions {
+    service: string;
+    action: string;
+    payload: Record<string, any>;
+    priority?: Priority;
+    /**
+     * JSON Schema object defining the structure of the payload for the Human UI.
+     * Note: If using Zod, use `zod-to-json-schema` before passing it here.
+     */
+    schema?: Record<string, any>;
+    timeoutMs?: number;
+}
+
+export interface Decision {
+    status: "APPROVED" | "REJECTED";
+    payload: any;
+    patched_payload?: any;
+    metadata?: {
+        resolved_at: string;
+        actor_id: string;
+        method?: string;
+    };
+}
+
+export class LetsPingError extends Error {
+    constructor(message: string, public status?: number) {
+        super(message);
+        this.name = "LetsPingError";
+    }
+}
+
+export class LetsPing {
+    private readonly apiKey: string;
+    private readonly baseUrl: string;
+
+    constructor(apiKey?: string, options?: { baseUrl?: string }) {
+        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";
+    }
+
+    async ask(options: RequestOptions): Promise<Decision> {
+        // Warn if a raw Zod object is passed, as it serializes to {}
+        if (options.schema && (options.schema as any)._def) {
+            console.warn("\x1b[33m%s\x1b[0m", "⚠️ LetsPing Warning: It looks like you passed a raw Zod object to 'schema'. This will result in an empty form. Please convert it to JSON Schema first (e.g. using 'zod-to-json-schema').");
+        }
+
+        const { id } = await this.request<{ id: string }>("POST", "/ingest", {
+            service: options.service,
+            action: options.action,
+            payload: options.payload,
+            priority: options.priority || "medium",
+            schema: options.schema
+        });
+
+        const timeout = options.timeoutMs || 24 * 60 * 60 * 1000;
+        const start = Date.now();
+        let delay = 1000;
+        const maxDelay = 10000;
+
+        while (Date.now() - start < timeout) {
+            try {
+                const check = await this.request<any>("GET", `/status/${id}`);
+
+                if (check.status === "APPROVED" || check.status === "REJECTED") {
+                    return {
+                        status: check.status,
+                        payload: options.payload,
+                        patched_payload: check.patched_payload || options.payload,
+                        metadata: {
+                            resolved_at: check.resolved_at,
+                            actor_id: check.actor_id
+                        }
+                    };
+                }
+            } catch (e: any) {
+                // Ignore 404 (pending) and 429 (rate limit), throw everything else
+                if (e.status !== 404 && e.status !== 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.`);
+    }
+
+    async defer(options: RequestOptions): Promise<{ id: string }> {
+        return this.request<{ id: string }>("POST", "/ingest", options);
+    }
+
+    private async request<T>(method: string, path: string, body?: any): Promise<T> {
+        const headers: Record<string, string> = {
+            "Authorization": `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+            "User-Agent": "letsping-node/0.1.0"
+        };
+
+        try {
+            const response = await fetch(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+            });
+
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new LetsPingError(`LetsPing API Error [${response.status}]: ${errorText}`, response.status);
+            }
+
+            return response.json() as Promise<T>;
+        } catch (e: any) {
+            if (e instanceof LetsPingError) throw e;
+            throw new LetsPingError(`Network Error: ${e.message}`);
+        }
+    }
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+    "compilerOptions": {
+        "target": "ES2020",
+        "module": "ESNext",
+        "moduleResolution": "Bundler",
+        "strict": true,
+        "declaration": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "baseUrl": "."
+    },
+    "include": [
+        "src"
+    ]
+}

package/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+    entry: ["src/index.ts"],
+    format: ["cjs", "esm"],
+    dts: true,
+    clean: true,
+    sourcemap: true,
+    splitting: false,
+});