@clawnexus/sdk 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# @clawnexus/sdk
+
+ClawLink Protocol SDK — programmatic client for the ClawNexus daemon API.
+
+Discover and manage OpenClaw-compatible AI instances from your Node.js applications.
+
+## Installation
+
+```bash
+npm install @clawnexus/sdk
+```
+
+Requires Node.js >= 22 and a running `clawnexus` daemon.
+
+## Quick Start
+
+```typescript
+import { ClawNexusClient } from "@clawnexus/sdk";
+
+const client = new ClawNexusClient();
+
+// List all discovered instances
+const { instances } = await client.listInstances();
+console.log(instances);
+
+// Get a specific instance by name or alias
+const inst = await client.getInstance("home");
+console.log(`${inst.alias} @ ${inst.address}:${inst.gateway_port}`);
+
+// Scan the network
+const scan = await client.scan();
+console.log(`Found ${scan.discovered} instance(s)`);
+
+// Set an alias
+await client.setAlias("my-agent-id", "office");
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+const client = new ClawNexusClient({
+  apiUrl: "http://localhost:17890",  // default
+  timeout: 5000,                     // default, in ms
+});
+```
+
+### Instance Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `health()` | `Record<string, unknown>` | Daemon health status |
+| `listInstances()` | `{ count, instances }` | List all known instances |
+| `getInstance(id)` | `ClawInstance` | Get instance by ID, alias, or address |
+| `setAlias(id, alias)` | `{ status, agent_id, alias }` | Set or update instance alias |
+| `removeInstance(id)` | `{ status, removed }` | Remove instance from registry |
+| `scan()` | `{ status, discovered, instances }` | Trigger network scan |
+| `relayConnect(clawId)` | `{ status, target }` | Connect via relay |
+| `relayStatus()` | `Record<string, unknown>` | Relay connection status |
+| `relayDisconnect(roomId)` | `{ status, room_id }` | Disconnect relay room |
+
+### Error Handling
+
+```typescript
+import { ClawNexusClient, ClawNexusApiError } from "@clawnexus/sdk";
+
+const client = new ClawNexusClient();
+
+try {
+  const inst = await client.getInstance("unknown");
+} catch (err) {
+  if (err instanceof ClawNexusApiError) {
+    console.log(err.statusCode);  // 404
+    console.log(err.message);     // "Instance not found"
+  }
+}
+```
+
+### Types
+
+The SDK re-exports all core types:
+
+```typescript
+import type {
+  ClawInstance,
+  PolicyConfig,
+  TaskRecord,
+  TaskStats,
+  InboxItem,
+} from "@clawnexus/sdk";
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,97 @@
+import type { ClawInstance, RegistryStatus, WhoamiResponse, PolicyConfig, TaskRecord, TaskStats, TaskDirection, TaskState, TaskSpec, InboxItem } from "./types.js";
+export interface ClawNexusClientOptions {
+    apiUrl?: string;
+    timeout?: number;
+}
+export declare class ClawNexusClient {
+    private readonly apiUrl;
+    private readonly timeout;
+    constructor(options?: ClawNexusClientOptions);
+    health(): Promise<Record<string, unknown>>;
+    listInstances(): Promise<{
+        count: number;
+        instances: ClawInstance[];
+    }>;
+    getInstance(idOrName: string): Promise<ClawInstance>;
+    setAlias(idOrName: string, alias: string): Promise<{
+        status: string;
+        agent_id: string;
+        alias: string;
+    }>;
+    removeInstance(idOrName: string): Promise<{
+        status: string;
+        removed: string;
+    }>;
+    scan(): Promise<{
+        status: string;
+        discovered: number;
+        instances: ClawInstance[];
+    }>;
+    register(): Promise<{
+        status: string;
+        claw_name: string | null;
+        pubkey: string | null;
+    }>;
+    registryStatus(): Promise<RegistryStatus>;
+    resolve(name: string): Promise<ClawInstance>;
+    whoami(): Promise<WhoamiResponse>;
+    relayConnect(targetClawId: string): Promise<{
+        status: string;
+        target: string;
+    }>;
+    relayStatus(): Promise<Record<string, unknown>>;
+    relayDisconnect(roomId: string): Promise<{
+        status: string;
+        room_id: string;
+    }>;
+    getPolicy(): Promise<PolicyConfig>;
+    updatePolicy(policy: PolicyConfig): Promise<{
+        status: string;
+    }>;
+    patchPolicy(partial: Partial<PolicyConfig>): Promise<{
+        status: string;
+        policy: PolicyConfig;
+    }>;
+    resetPolicy(): Promise<{
+        status: string;
+        policy: PolicyConfig;
+    }>;
+    listTasks(opts?: {
+        all?: boolean;
+        direction?: TaskDirection;
+        state?: TaskState;
+    }): Promise<{
+        count: number;
+        tasks: TaskRecord[];
+    }>;
+    getTask(taskId: string): Promise<TaskRecord>;
+    cancelTask(taskId: string, reason?: string): Promise<{
+        status: string;
+        task: TaskRecord;
+    }>;
+    getTaskStats(): Promise<TaskStats>;
+    propose(targetClawId: string, roomId: string, task: TaskSpec): Promise<{
+        status: string;
+        task: TaskRecord;
+    }>;
+    query(targetClawId: string, roomId: string, queryType: "capabilities" | "status" | "availability"): Promise<{
+        status: string;
+        message_id: string;
+    }>;
+    getInbox(): Promise<{
+        count: number;
+        items: InboxItem[];
+    }>;
+    approveInbox(messageId: string): Promise<{
+        status: string;
+        task: TaskRecord;
+    }>;
+    denyInbox(messageId: string, reason?: string): Promise<{
+        status: string;
+    }>;
+    private request;
+}
+export declare class ClawNexusApiError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number);
+}

package/dist/client.js

@@ -0,0 +1,128 @@
+"use strict";
+// ClawNexus SDK — HTTP client for clawnexus daemon API
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClawNexusApiError = exports.ClawNexusClient = void 0;
+class ClawNexusClient {
+    apiUrl;
+    timeout;
+    constructor(options = {}) {
+        this.apiUrl = options.apiUrl ?? "http://localhost:17890";
+        this.timeout = options.timeout ?? 5000;
+    }
+    async health() {
+        return this.request("GET", "/health");
+    }
+    async listInstances() {
+        return this.request("GET", "/instances");
+    }
+    async getInstance(idOrName) {
+        return this.request("GET", `/instances/${encodeURIComponent(idOrName)}`);
+    }
+    async setAlias(idOrName, alias) {
+        return this.request("PUT", `/instances/${encodeURIComponent(idOrName)}/alias`, { alias });
+    }
+    async removeInstance(idOrName) {
+        return this.request("DELETE", `/instances/${encodeURIComponent(idOrName)}`);
+    }
+    async scan() {
+        return this.request("POST", "/scan");
+    }
+    // --- Registry (v0.2) ---
+    async register() {
+        return this.request("POST", "/registry/register");
+    }
+    async registryStatus() {
+        return this.request("GET", "/registry/status");
+    }
+    async resolve(name) {
+        return this.request("GET", `/resolve/${encodeURIComponent(name)}`);
+    }
+    async whoami() {
+        return this.request("GET", "/whoami");
+    }
+    // --- Relay ---
+    async relayConnect(targetClawId) {
+        return this.request("POST", "/relay/connect", { target_claw_id: targetClawId });
+    }
+    async relayStatus() {
+        return this.request("GET", "/relay/status");
+    }
+    async relayDisconnect(roomId) {
+        return this.request("DELETE", `/relay/disconnect/${encodeURIComponent(roomId)}`);
+    }
+    // --- Layer B: Agent / Policy ---
+    async getPolicy() {
+        return this.request("GET", "/agent/policy");
+    }
+    async updatePolicy(policy) {
+        return this.request("PUT", "/agent/policy", policy);
+    }
+    async patchPolicy(partial) {
+        return this.request("PATCH", "/agent/policy", partial);
+    }
+    async resetPolicy() {
+        return this.request("POST", "/agent/policy/reset");
+    }
+    // --- Layer B: Tasks ---
+    async listTasks(opts) {
+        const params = new URLSearchParams();
+        if (opts?.all)
+            params.set("all", "true");
+        if (opts?.direction)
+            params.set("direction", opts.direction);
+        if (opts?.state)
+            params.set("state", opts.state);
+        const qs = params.toString() ? `?${params.toString()}` : "";
+        return this.request("GET", `/agent/tasks${qs}`);
+    }
+    async getTask(taskId) {
+        return this.request("GET", `/agent/tasks/${encodeURIComponent(taskId)}`);
+    }
+    async cancelTask(taskId, reason) {
+        return this.request("POST", `/agent/tasks/${encodeURIComponent(taskId)}/cancel`, { reason });
+    }
+    async getTaskStats() {
+        return this.request("GET", "/agent/tasks/stats");
+    }
+    // --- Layer B: Propose / Query ---
+    async propose(targetClawId, roomId, task) {
+        return this.request("POST", "/agent/propose", { target_claw_id: targetClawId, room_id: roomId, task });
+    }
+    async query(targetClawId, roomId, queryType) {
+        return this.request("POST", "/agent/query", { target_claw_id: targetClawId, room_id: roomId, query_type: queryType });
+    }
+    // --- Layer B: Inbox ---
+    async getInbox() {
+        return this.request("GET", "/agent/inbox");
+    }
+    async approveInbox(messageId) {
+        return this.request("POST", `/agent/inbox/${encodeURIComponent(messageId)}/approve`);
+    }
+    async denyInbox(messageId, reason) {
+        return this.request("POST", `/agent/inbox/${encodeURIComponent(messageId)}/deny`, { reason });
+    }
+    async request(method, urlPath, body) {
+        const res = await fetch(`${this.apiUrl}${urlPath}`, {
+            method,
+            headers: body ? { "Content-Type": "application/json" } : undefined,
+            body: body ? JSON.stringify(body) : undefined,
+            signal: AbortSignal.timeout(this.timeout),
+        });
+        const data = await res.json();
+        if (!res.ok) {
+            const error = data.error ?? `HTTP ${res.status}`;
+            throw new ClawNexusApiError(error, res.status);
+        }
+        return data;
+    }
+}
+exports.ClawNexusClient = ClawNexusClient;
+class ClawNexusApiError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = "ClawNexusApiError";
+    }
+}
+exports.ClawNexusApiError = ClawNexusApiError;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { ClawNexusClient, ClawNexusApiError } from './client.js';
+export type { ClawNexusClientOptions } from './client.js';
+export type { ClawInstance, RegistryFile, ControlUiConfig, PolicyConfig, TaskSpec, TaskState, TaskDirection, TaskRecord, TaskStats, InboxItem, } from './types.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+// @clawnexus/sdk — ClawNexus SDK
+// Discover and identify OpenClaw-compatible AI instances
+// See: DESIGN_010_ecosystem_compatibility.md
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClawNexusApiError = exports.ClawNexusClient = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "ClawNexusClient", { enumerable: true, get: function () { return client_js_1.ClawNexusClient; } });
+Object.defineProperty(exports, "ClawNexusApiError", { enumerable: true, get: function () { return client_js_1.ClawNexusApiError; } });

package/dist/types.d.ts

@@ -0,0 +1,119 @@
+export interface ClawInstance {
+    agent_id: string;
+    auto_name: string;
+    alias?: string;
+    assistant_name: string;
+    display_name: string;
+    lan_host: string;
+    address: string;
+    gateway_port: number;
+    tls: boolean;
+    tls_fingerprint?: string;
+    discovery_source: "mdns" | "scan" | "manual" | "local" | "registry";
+    network_scope: "local" | "vpn" | "public";
+    status: "online" | "offline" | "unknown";
+    last_seen: string;
+    discovered_at: string;
+    connectivity?: Connectivity;
+    is_self?: boolean;
+    claw_name?: string;
+    owner_pubkey?: string;
+    labels?: Record<string, string>;
+}
+export interface Connectivity {
+    lan_reachable: boolean;
+    relay_available: boolean;
+    preferred_channel: "lan" | "relay" | "local" | "unknown";
+    lan_latency_ms?: number;
+    last_lan_check: string;
+    unreachable_reason?: string;
+}
+export interface UnreachableInstance {
+    address: string;
+    port: number;
+    lan_host: string;
+    display_name: string;
+    reason: string;
+    discovered_at: string;
+}
+export interface RegistryFile {
+    schema_version: "2" | "3" | "4" | "5";
+    updated_at: string;
+    instances: ClawInstance[];
+}
+export interface ControlUiConfig {
+    assistantAgentId: string;
+    assistantName: string;
+    displayName?: string;
+    [key: string]: unknown;
+}
+export interface RegistryStatus {
+    registered: boolean;
+    claw_name: string | null;
+    pubkey: string | null;
+}
+export interface WhoamiResponse {
+    pubkey: string | null;
+    claw_name: string | null;
+}
+export interface PolicyConfig {
+    mode: "auto" | "queue" | "hybrid";
+    trust_threshold: number;
+    rate_limit: {
+        max_per_minute: number;
+        max_per_peer_minute: number;
+    };
+    delegation: {
+        allow: boolean;
+        max_depth: number;
+    };
+    capability_filter: string[];
+    access_control: {
+        whitelist: string[];
+        blacklist: string[];
+    };
+    auto_approve_types: string[];
+    max_concurrent_tasks: number;
+}
+export interface TaskSpec {
+    task_type: string;
+    description: string;
+    input?: Record<string, unknown>;
+    constraints?: {
+        max_duration_s?: number;
+        max_cost?: number;
+        priority?: "low" | "normal" | "high" | "critical";
+    };
+    delegation_depth?: number;
+}
+export type TaskState = "pending" | "accepted" | "executing" | "completed" | "failed" | "rejected" | "cancelled" | "timeout";
+export type TaskDirection = "outbound" | "inbound";
+export interface TaskRecord {
+    task_id: string;
+    direction: TaskDirection;
+    peer_claw_id: string;
+    task: TaskSpec;
+    state: TaskState;
+    created_at: string;
+    updated_at: string;
+    accepted_at?: string;
+    completed_at?: string;
+    result?: unknown;
+    error?: string;
+    progress_pct?: number;
+    message_id: string;
+    room_id?: string;
+}
+export interface TaskStats {
+    total: number;
+    by_state: Record<TaskState, number>;
+    by_direction: Record<TaskDirection, number>;
+    active: number;
+}
+export interface InboxItem {
+    message_id: string;
+    from: string;
+    type: string;
+    task?: TaskSpec;
+    timestamp: string;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+// Core types — mirrored from daemon for SDK consumers
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@clawnexus/sdk",
+  "version": "0.1.0",
+  "description": "ClawNexus SDK — programmatic client for discovering and managing OpenClaw instances",
+  "license": "MIT",
+  "author": "alan-silverstreams <alan@silverstream.tech>",
+  "homepage": "https://github.com/alan-silverstreams/ClawNexus",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alan-silverstreams/ClawNexus.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": "https://github.com/alan-silverstreams/ClawNexus/issues",
+  "keywords": [
+    "openclaw",
+    "ai",
+    "agent",
+    "sdk",
+    "clawlink",
+    "protocol",
+    "discovery",
+    "clawnexus"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm build"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  }
+}