@verdictlayer/humanlatch-sdk 0.1.0

package/README.md

@@ -0,0 +1,183 @@
+# HumanLatch JavaScript SDK
+
+JavaScript/TypeScript SDK for sending AI-driven capability proposals to a HumanLatch control plane.
+
+Use this SDK when your app, agent, robot controller, chatbot, or manufacturing system needs to ask:
+
+- Can I run this capability automatically?
+- Do I need a human approval first?
+- Is this blocked by policy?
+
+The SDK works against either:
+
+- self-hosted HumanLatch CE
+- a remotely hosted HumanLatch API
+
+## Install
+
+```bash
+npm install @verdictlayer/humanlatch-sdk
+```
+
+This package is intended for npm publication as `@verdictlayer/humanlatch-sdk`.
+
+## Create a Client
+
+```ts
+import { HumanLatchClient } from "@verdictlayer/humanlatch-sdk";
+
+const client = new HumanLatchClient({
+  baseUrl: "https://your-humanlatch.example.com",
+  workspaceId: "your-workspace-id",
+  apiKey: process.env.HUMANLATCH_API_KEY,
+});
+```
+
+Use `token` for user-authenticated flows or `apiKey` for agent/service integrations.
+
+## Core Flow
+
+```ts
+const result = await client.proposeAction({
+  action_type: "support.refund.issue",
+  target: "order-10428",
+  summary: "Issue a refund above the autonomous threshold",
+  payload: {
+    amount: 850,
+    currency: "USD",
+    customer_id: "cust_2041",
+  },
+  context: {
+    environment: "production",
+    requested_by: "agent:support-bot",
+    domain: "chatbot",
+  },
+});
+
+if (client.isApproved(result)) {
+  await issueRefund();
+} else if (client.requiresApproval(result)) {
+  const final = await client.waitForDecision(result.id, { intervalMs: 2000, timeoutMs: 30000 });
+  if (client.isApproved(final)) {
+    await issueRefund();
+  }
+} else if (client.isBlocked(result)) {
+  throw new Error("Blocked by HumanLatch policy");
+}
+```
+
+## What You Send
+
+Every proposed capability should include:
+
+- `action_type`: machine-readable capability name
+- `target`: thing being affected
+- `summary`: human-readable explanation
+- `payload`: structured execution details
+- `context`: environment, source, actor, and policy context
+
+## Domain Examples
+
+### Cloud / DevOps
+
+```ts
+await client.proposeAction({
+  action_type: "aws.iam.policy_change",
+  target: "prod-admin-role",
+  summary: "Attach elevated access to a production IAM role",
+  payload: {
+    policy_arn: "arn:aws:iam::aws:policy/AdministratorAccess",
+  },
+  context: {
+    environment: "production",
+    requested_by: "agent:terraform-bot",
+    domain: "cloud",
+  },
+});
+```
+
+### Chatbot / Customer Operations
+
+```ts
+await client.proposeAction({
+  action_type: "support.refund.issue",
+  target: "order-10428",
+  summary: "Issue a refund above the autonomous threshold",
+  payload: {
+    amount: 850,
+    currency: "USD",
+  },
+  context: {
+    environment: "production",
+    requested_by: "agent:support-bot",
+    domain: "chatbot",
+  },
+});
+```
+
+### Robotics
+
+```ts
+await client.proposeAction({
+  action_type: "robot.motion.execute",
+  target: "cell-7-arm-a",
+  summary: "Move a robot into a maintenance zone",
+  payload: {
+    command: "enter_maintenance_zone",
+    speed: "reduced",
+  },
+  context: {
+    environment: "factory",
+    requested_by: "agent:cell-controller",
+    domain: "robotics",
+  },
+});
+```
+
+### Manufacturing
+
+```ts
+await client.proposeAction({
+  action_type: "manufacturing.line.override",
+  target: "line-3",
+  summary: "Override a conveyor safety threshold",
+  payload: {
+    threshold: 0.92,
+    duration_seconds: 180,
+  },
+  context: {
+    environment: "production",
+    requested_by: "agent:line-optimizer",
+    domain: "manufacturing",
+  },
+});
+```
+
+## Additional Methods
+
+```ts
+await client.listActions({ status: "pending_approval", limit: 50 });
+await client.getAction("action-id");
+await client.approveAction("action-id", { note: "Approved by supervisor" });
+await client.rejectAction("action-id", "Unsafe during shift handoff");
+await client.cancelAction("action-id");
+await client.waitForDecision("action-id", { intervalMs: 2000, timeoutMs: 30000 });
+```
+
+## Integration Model
+
+HumanLatch is not tied to one domain.
+
+Your app keeps its own UI, runtime, and execution engine. Before it performs a sensitive capability, it asks HumanLatch for a decision:
+
+- `approved_auto`: execute now
+- `pending_approval`: wait for human approval
+- `blocked`: do not execute
+
+That same control plane works for:
+
+- infrastructure agents
+- support bots
+- warehouse robots
+- manufacturing lines
+- internal copilots

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+export type HumanLatchStatus = "pending_approval" | "approved_auto" | "approved_manual" | "rejected" | "blocked" | "cancelled";
+export type HumanLatchHeaders = Record<string, string>;
+export interface ProposeActionInput {
+    action_type: string;
+    target: string;
+    summary: string;
+    payload?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+}
+export interface ProposeActionResult {
+    id: string;
+    status: HumanLatchStatus;
+    risk_score: number;
+    summary: string;
+}
+export interface ActionRecord extends ProposeActionResult {
+    workspace_id: string;
+    target: string;
+    action_type: string;
+    payload: Record<string, unknown>;
+    context: Record<string, unknown>;
+    proposed_by: string;
+    decided_by: string | null;
+    decided_at: string | null;
+    decision_note: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface ListActionsOptions {
+    status?: HumanLatchStatus;
+    limit?: number;
+    offset?: number;
+}
+export interface DecisionOptions {
+    note?: string;
+}
+export interface WaitForDecisionOptions {
+    intervalMs?: number;
+    timeoutMs?: number;
+}
+export interface HumanLatchClientOptions {
+    baseUrl: string;
+    workspaceId: string;
+    token?: string;
+    apiKey?: string;
+    headers?: HumanLatchHeaders;
+    fetch?: typeof fetch;
+}
+export declare class HumanLatchError extends Error {
+    readonly status: number;
+    readonly detail: unknown;
+    constructor(message: string, status: number, detail: unknown);
+}
+export declare class HumanLatchClient {
+    private readonly baseUrl;
+    private readonly workspaceId;
+    private readonly token?;
+    private readonly apiKey?;
+    private readonly headers;
+    private readonly fetchImpl;
+    constructor(options: HumanLatchClientOptions);
+    proposeAction(input: ProposeActionInput): Promise<ProposeActionResult>;
+    propose(input: ProposeActionInput): Promise<ProposeActionResult>;
+    listActions(options?: ListActionsOptions): Promise<ActionRecord[]>;
+    getAction(actionId: string): Promise<ActionRecord>;
+    approveAction(actionId: string, options?: DecisionOptions): Promise<ActionRecord>;
+    rejectAction(actionId: string, note: string): Promise<ActionRecord>;
+    cancelAction(actionId: string): Promise<ActionRecord>;
+    waitForDecision(actionId: string, options?: WaitForDecisionOptions): Promise<ActionRecord>;
+    isApproved(result: Pick<ProposeActionResult, "status">): boolean;
+    requiresApproval(result: Pick<ProposeActionResult, "status">): boolean;
+    isBlocked(result: Pick<ProposeActionResult, "status">): boolean;
+    private request;
+}

package/dist/index.js

@@ -0,0 +1,129 @@
+export class HumanLatchError extends Error {
+    constructor(message, status, detail) {
+        super(message);
+        this.name = "HumanLatchError";
+        this.status = status;
+        this.detail = detail;
+    }
+}
+export class HumanLatchClient {
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.workspaceId = options.workspaceId;
+        this.token = options.token;
+        this.apiKey = options.apiKey;
+        this.headers = options.headers ?? {};
+        this.fetchImpl = options.fetch ?? fetch;
+        if (!this.token && !this.apiKey) {
+            throw new Error("HumanLatchClient requires either a token or an apiKey.");
+        }
+    }
+    async proposeAction(input) {
+        return this.request("/api/v1/actions/propose", {
+            method: "POST",
+            body: JSON.stringify({
+                action_type: input.action_type,
+                target: input.target,
+                summary: input.summary,
+                payload: input.payload ?? {},
+                context: input.context ?? {},
+            }),
+        });
+    }
+    async propose(input) {
+        return this.proposeAction(input);
+    }
+    async listActions(options = {}) {
+        const query = new URLSearchParams();
+        if (options.status)
+            query.set("status", options.status);
+        if (typeof options.limit === "number")
+            query.set("limit", String(options.limit));
+        if (typeof options.offset === "number")
+            query.set("offset", String(options.offset));
+        return this.request(`/api/v1/actions?${query.toString()}`);
+    }
+    async getAction(actionId) {
+        return this.request(`/api/v1/actions/${actionId}`);
+    }
+    async approveAction(actionId, options = {}) {
+        return this.request(`/api/v1/actions/${actionId}/approve`, {
+            method: "POST",
+            body: JSON.stringify({ note: options.note }),
+        });
+    }
+    async rejectAction(actionId, note) {
+        return this.request(`/api/v1/actions/${actionId}/reject`, {
+            method: "POST",
+            body: JSON.stringify({ note }),
+        });
+    }
+    async cancelAction(actionId) {
+        return this.request(`/api/v1/actions/${actionId}/cancel`, {
+            method: "POST",
+        });
+    }
+    async waitForDecision(actionId, options = {}) {
+        const intervalMs = options.intervalMs ?? 2000;
+        const timeoutMs = options.timeoutMs ?? 60000;
+        const startedAt = Date.now();
+        while (true) {
+            const action = await this.getAction(actionId);
+            if (!this.requiresApproval(action)) {
+                return action;
+            }
+            if (Date.now() - startedAt >= timeoutMs) {
+                throw new Error(`Timed out waiting for HumanLatch decision for action ${actionId}.`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        }
+    }
+    isApproved(result) {
+        return result.status === "approved_auto" || result.status === "approved_manual";
+    }
+    requiresApproval(result) {
+        return result.status === "pending_approval";
+    }
+    isBlocked(result) {
+        return result.status === "blocked" || result.status === "rejected";
+    }
+    async request(path, init = {}) {
+        const separator = path.includes("?") ? "&" : "?";
+        const hasWorkspaceId = /(?:\?|&)workspace_id=/.test(path);
+        const workspaceQuery = hasWorkspaceId
+            ? ""
+            : `${separator}workspace_id=${encodeURIComponent(this.workspaceId)}`;
+        const url = `${this.baseUrl}${path}${workspaceQuery}`;
+        const headers = {
+            "Content-Type": "application/json",
+            ...this.headers,
+        };
+        if (this.token) {
+            headers.Authorization = `Bearer ${this.token}`;
+        }
+        if (this.apiKey) {
+            headers["X-API-Key"] = this.apiKey;
+        }
+        const response = await this.fetchImpl(url, {
+            ...init,
+            headers: {
+                ...headers,
+                ...init.headers,
+            },
+        });
+        if (!response.ok) {
+            const detail = await response.json().catch(() => null);
+            const message = typeof detail === "object" &&
+                detail !== null &&
+                "detail" in detail &&
+                typeof detail.detail === "string"
+                ? detail.detail
+                : "HumanLatch request failed";
+            throw new HumanLatchError(message, response.status, detail);
+        }
+        if (response.status === 204) {
+            return undefined;
+        }
+        return response.json();
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@verdictlayer/humanlatch-sdk",
+  "version": "0.1.0",
+  "description": "HumanLatch JavaScript SDK for proposing AI-driven capabilities to a HumanLatch control plane.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verdictlayer/humanlatch.git",
+    "directory": "sdk/javascript"
+  },
+  "homepage": "https://humanlatch.verdictlayer.com/developers",
+  "bugs": {
+    "url": "https://github.com/verdictlayer/humanlatch/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "keywords": [
+    "ai",
+    "approval",
+    "agent",
+    "policy",
+    "human-in-the-loop",
+    "robotics",
+    "manufacturing"
+  ],
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  }
+}