@skytalesh/sdk 0.4.0

package/README.md

@@ -0,0 +1,337 @@
+# @skytalesh/sdk
+
+[![npm version](https://img.shields.io/npm/v/@skytalesh/sdk.svg)](https://www.npmjs.com/package/@skytalesh/sdk)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+TypeScript/Node.js SDK for Skytale — encrypted channels for AI agents.
+
+Create MLS-encrypted communication channels with multi-protocol support (SLIM, A2A, ACP, MCP, ANP, LMOS, NLIP). Native Rust core via NAPI for performance.
+
+## Install
+
+```bash
+npm install @skytalesh/sdk
+```
+
+Prebuilt binaries are available for macOS (x64, ARM64), Linux (x64, ARM64), and Windows (x64). Requires Node.js 18+.
+
+## Setup
+
+Get an API key with the Skytale CLI:
+
+```bash
+skytale signup you@example.com
+```
+
+Or set the key directly:
+
+```bash
+export SKYTALE_API_KEY="sk_live_..."
+```
+
+## Quick Start
+
+```typescript
+import { SkytaleChannelManager } from '@skytalesh/sdk';
+
+const alice = new SkytaleChannelManager({
+  identity: 'alice-agent',
+  apiKey: process.env.SKYTALE_API_KEY,
+});
+
+await alice.create('acme/support/routing');
+const token = await alice.invite('acme/support/routing');
+
+const bob = new SkytaleChannelManager({
+  identity: 'bob-agent',
+  apiKey: process.env.SKYTALE_API_KEY,
+});
+
+await bob.joinWithToken('acme/support/routing', token);
+alice.send('acme/support/routing', 'Hello from Alice!');
+const messages = await bob.receive('acme/support/routing');
+console.log(messages); // ['Hello from Alice!']
+
+alice.close();
+bob.close();
+```
+
+## API Reference
+
+### `SkytaleChannelManager`
+
+High-level API for most use cases. Handles background message buffering and environment-based configuration.
+
+```typescript
+import { SkytaleChannelManager } from "@skytalesh/sdk";
+
+const mgr = new SkytaleChannelManager({
+  identity: "my-agent",      // string or Buffer
+  endpoint: "https://...",   // defaults to SKYTALE_RELAY env
+  apiKey: "sk_live_...",     // defaults to SKYTALE_API_KEY env
+  apiUrl: "https://...",     // defaults to SKYTALE_API_URL env
+  mock: false,               // enable mock mode for testing
+});
+```
+
+#### Constructor Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `identity` | `string \| Buffer` | Yes | Agent identity (strings are UTF-8 encoded) |
+| `endpoint` | `string` | No | Relay URL (default: `SKYTALE_RELAY` env or `https://relay.skytale.sh:5000`) |
+| `dataDir` | `string` | No | MLS state directory (default: auto-generated) |
+| `apiKey` | `string` | No | API key (default: `SKYTALE_API_KEY` env) |
+| `apiUrl` | `string` | No | API server URL (default: `SKYTALE_API_URL` env or `https://api.skytale.sh`) |
+| `mock` | `boolean` | No | Enable mock mode for testing without a relay (default: `false`) |
+
+#### `create(channelName: string): Promise<void>`
+
+Create a channel and start a background listener.
+
+```typescript
+await mgr.create("myorg/team/general");
+```
+
+#### `invite(channelName: string, maxUses?: number, ttl?: number): Promise<string>`
+
+Generate an invite token for a channel. Returns an `skt_inv_...` token.
+
+- `maxUses` — maximum number of times the token can be used (default: 1)
+- `ttl` — token lifetime in seconds (default: 3600)
+
+```typescript
+const token = await mgr.invite("myorg/team/general");
+```
+
+#### `joinWithToken(channelName: string, token: string, timeout?: number): Promise<void>`
+
+Join a channel using an invite token. MLS key exchange is handled automatically.
+
+- `timeout` — max milliseconds to wait (default: 60000)
+
+```typescript
+await mgr.joinWithToken("myorg/team/general", token);
+```
+
+#### `send(channelName: string, message: string | Buffer): void`
+
+Send a message. Strings are UTF-8 encoded automatically.
+
+```typescript
+mgr.send("myorg/team/general", "Hello!");
+```
+
+#### `receive(channelName: string, timeout?: number): Promise<string[]>`
+
+Drain all buffered messages. Waits up to `timeout` ms (default: 5000) if buffer is empty.
+
+```typescript
+const msgs = await mgr.receive("myorg/team/general");
+```
+
+#### `receiveLatest(channelName: string, timeout?: number): Promise<string | null>`
+
+Return only the most recent message, discarding older ones.
+
+```typescript
+const latest = await mgr.receiveLatest("myorg/team/general");
+```
+
+#### `sendEnvelope(channelName: string, envelope: Envelope): void`
+
+Send a structured envelope on a channel.
+
+#### `receiveEnvelopes(channelName: string, timeout?: number): Promise<Envelope[]>`
+
+Receive structured envelopes. Raw messages are auto-wrapped as `Protocol.RAW`.
+
+#### `listChannels(): string[]`
+
+Return names of all active channels.
+
+#### `close(): void`
+
+Stop all background listeners and release resources.
+
+#### `on('message', (channelName: string, message: Buffer) => void)`
+
+Event emitter for real-time message handling. Fires for every incoming message on any channel.
+
+```typescript
+mgr.on("message", (channel, msg) => {
+  console.log(`[${channel}] ${msg.toString()}`);
+});
+```
+
+## MCP Server
+
+Expose Skytale encrypted channels as MCP tools for Claude Desktop, Cursor, or any MCP client.
+
+```bash
+npx @skytalesh/mcp-server
+```
+
+### Claude Desktop Configuration
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "skytale": {
+      "command": "npx",
+      "args": ["@skytalesh/mcp-server"],
+      "env": {
+        "SKYTALE_API_KEY": "sk_live_..."
+      }
+    }
+  }
+}
+```
+
+### Cursor Configuration
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "skytale": {
+      "command": "npx",
+      "args": ["@skytalesh/mcp-server"]
+    }
+  }
+}
+```
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `skytale_create` | Create an encrypted channel |
+| `skytale_invite` | Generate an invite token for a channel |
+| `skytale_join` | Join a channel with an invite token |
+| `skytale_send` | Send a message on a channel |
+| `skytale_receive` | Receive messages from a channel |
+| `skytale_channels` | List active channels |
+
+## MCP Encrypted Transport
+
+Use Skytale as the transport layer for MCP protocol messages, replacing plaintext HTTP/stdio with MLS-encrypted channels.
+
+```typescript
+import { SkytaleChannelManager } from "@skytalesh/sdk";
+import { SkytaleTransport } from "@skytalesh/sdk/mcp-transport";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+
+const mgr = new SkytaleChannelManager({ identity: "agent-1", mock: true });
+await mgr.create("org/ns/mcp-rpc");
+
+const transport = new SkytaleTransport(mgr, "org/ns/mcp-rpc");
+const client = new Client({ name: "my-client", version: "1.0.0" });
+await client.connect(transport);
+```
+
+## Mock Mode
+
+Test agent logic without a running relay:
+
+```typescript
+const mgr = new SkytaleChannelManager({ identity: "test-agent", mock: true });
+await mgr.create("org/ns/test");
+mgr.send("org/ns/test", "hello");
+const msgs = await mgr.receive("org/ns/test"); // ["hello"]
+mgr.close();
+```
+
+Mock mode is useful for unit tests, CI pipelines, and local development. Also enabled by `SKYTALE_MOCK=1` env var.
+
+## Error Handling
+
+All methods throw typed exceptions extending `SkytaleError`:
+
+```typescript
+import { SkytaleChannelManager, ChannelError, AuthError, SkytaleError } from "@skytalesh/sdk";
+
+try {
+  const mgr = new SkytaleChannelManager({ identity: "agent" });
+  await mgr.create("bad-name");
+} catch (e) {
+  if (e instanceof AuthError) {
+    console.log(`Auth failed (HTTP ${e.httpStatus}): ${e.message}`);
+    console.log(`Fix: ${e.docUrl}`);
+  } else if (e instanceof ChannelError) {
+    console.log(`Channel error [${e.code}]: ${e.message}`);
+  } else if (e instanceof SkytaleError) {
+    console.log(`SDK error: ${e.message}`);
+  }
+}
+```
+
+### Error Types
+
+| Exception | When |
+|-----------|------|
+| `AuthError` | API key invalid, expired, or missing |
+| `TransportError` | Relay unreachable, connection error, timeout |
+| `ChannelError` | Invalid channel name, channel not found |
+| `MlsError` | Bad key package, invalid Welcome, decryption failure |
+| `QuotaExceededError` | Free tier message limit reached |
+
+Every exception includes `code`, `httpStatus`, and `docUrl` attributes.
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SKYTALE_RELAY` | Relay server URL | `https://relay.skytale.sh:5000` |
+| `SKYTALE_API_KEY` | API key for authentication | -- |
+| `SKYTALE_API_URL` | API server URL | `https://api.skytale.sh` |
+| `SKYTALE_DATA_DIR` | MLS state directory | Auto-generated |
+| `SKYTALE_IDENTITY` | Default agent identity | -- |
+| `SKYTALE_MOCK` | Enable mock mode (`1`, `true`, `yes`) | `false` |
+
+## Envelope & Protocol
+
+Protocol-tagged messages for multi-protocol channels:
+
+```typescript
+import { Protocol, type Envelope, serializeEnvelope, deserializeEnvelope } from "@skytalesh/sdk";
+
+const env: Envelope = {
+  protocol: Protocol.A2A,
+  contentType: "application/json",
+  payload: Buffer.from('{"parts":[]}'),
+};
+
+const data = serializeEnvelope(env);
+const env2 = deserializeEnvelope(data);
+```
+
+### Supported Protocols
+
+| Value | Description |
+|-------|-------------|
+| `Protocol.RAW` | Plain bytes (default, backward compatible) |
+| `Protocol.A2A` | Google Agent-to-Agent protocol |
+| `Protocol.MCP` | Model Context Protocol |
+| `Protocol.SLIM` | SLIM (Secure Lightweight Inter-agent Messaging) |
+| `Protocol.ACP` | IBM Agent Communication Protocol |
+| `Protocol.ANP` | Agent Network Protocol (DID-based) |
+| `Protocol.LMOS` | Eclipse LMOS (Web of Things) |
+| `Protocol.NLIP` | Natural Language Interaction Protocol |
+
+## Architecture
+
+```
+Your Agent --> SkytaleChannelManager --> gRPC --> Relay --> gRPC --> SkytaleChannelManager --> Their Agent
+                       |                                                    |
+                       +-- MLS encrypt                       MLS decrypt --+
+```
+
+All messages are encrypted end-to-end with MLS (RFC 9420). The relay cannot read message contents.
+
+## License
+
+Apache 2.0

package/js/api.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Lightweight HTTP client for the Skytale API server.
+ *
+ * Uses Node.js built-in `fetch` (Node 18+) to avoid external dependencies.
+ * All methods authenticate with the API key directly — the API server
+ * accepts both `sk_live_*` keys and JWTs in the Authorization header.
+ *
+ * @example
+ * ```typescript
+ * import { SkytaleAPI } from "@skytalesh/sdk";
+ *
+ * const api = new SkytaleAPI("https://api.skytale.sh", "sk_live_...");
+ * await api.registerChannel("org/ns/svc");
+ * const resp = await api.createInvite("org/ns/svc");
+ * console.log(resp.token); // "skt_inv_..."
+ * ```
+ */
+export declare class SkytaleAPI {
+    private readonly base;
+    private readonly apiKey;
+    private readonly maxRetries;
+    constructor(apiUrl: string, apiKey: string, maxRetries?: number);
+    private request;
+    registerChannel(name: string): Promise<{
+        id: string;
+        name: string;
+    }>;
+    createInvite(channel: string, maxUses?: number, ttlSeconds?: number): Promise<{
+        token: string;
+        expires_at: string;
+    }>;
+    join(channel: string, token: string, keyPackageB64: string, identity: string): Promise<{
+        request_id: string;
+    }>;
+    getPending(channel: string): Promise<{
+        requests: Array<{
+            id: string;
+            identity: string;
+            key_package: string;
+            created_at: string;
+        }>;
+    }>;
+    submitWelcome(requestId: string, welcomeB64: string): Promise<{
+        status: string;
+    }>;
+    getWelcome(requestId: string): Promise<{
+        status: string;
+        welcome?: string;
+    }>;
+}

package/js/api.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * Lightweight HTTP client for the Skytale API server.
+ *
+ * Uses Node.js built-in `fetch` (Node 18+) to avoid external dependencies.
+ * All methods authenticate with the API key directly — the API server
+ * accepts both `sk_live_*` keys and JWTs in the Authorization header.
+ *
+ * @example
+ * ```typescript
+ * import { SkytaleAPI } from "@skytalesh/sdk";
+ *
+ * const api = new SkytaleAPI("https://api.skytale.sh", "sk_live_...");
+ * await api.registerChannel("org/ns/svc");
+ * const resp = await api.createInvite("org/ns/svc");
+ * console.log(resp.token); // "skt_inv_..."
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkytaleAPI = void 0;
+const errors_1 = require("./errors");
+const RETRYABLE_CODES = new Set([408, 429, 500, 502, 503, 504]);
+function validateApiUrl(apiUrl) {
+    let parsed;
+    try {
+        parsed = new URL(apiUrl);
+    }
+    catch {
+        throw new Error(`Invalid API URL: ${apiUrl}`);
+    }
+    if (parsed.protocol === "https:")
+        return;
+    if (parsed.protocol === "http:" &&
+        (parsed.hostname === "localhost" ||
+            parsed.hostname === "127.0.0.1" ||
+            parsed.hostname === "::1")) {
+        return;
+    }
+    throw new Error(`API URL must use HTTPS (got ${parsed.protocol}//${parsed.hostname}). ` +
+        "HTTP is only allowed for localhost/127.0.0.1.");
+}
+function backoffDelay(attempt, retryAfter) {
+    if (retryAfter != null) {
+        const ra = parseFloat(retryAfter);
+        if (!isNaN(ra) && ra > 0 && ra <= 60)
+            return ra * 1000;
+    }
+    const base = Math.min(0.5 * 2 ** attempt, 5.0);
+    const jitter = 0.75 + 0.25 * Math.random();
+    return base * jitter * 1000;
+}
+function mapApiError(httpCode, errorCode, message) {
+    if (errorCode === "unauthorized" || httpCode === 401) {
+        return new errors_1.AuthError("unable to authenticate: API key is invalid or expired. " +
+            "Verify SKYTALE_API_KEY is set correctly, or generate a new key " +
+            "with `skytale keys create`.", { code: "unauthorized", httpStatus: httpCode });
+    }
+    if (errorCode === "quota_exceeded" || httpCode === 429) {
+        return new errors_1.QuotaExceededError("unable to send: monthly message quota exceeded. " +
+            "Upgrade your plan at https://skytale.sh/billing or wait for " +
+            "the next billing cycle.", { code: "quota_exceeded", httpStatus: httpCode });
+    }
+    if (errorCode === "not_found" || httpCode === 404) {
+        return new errors_1.ChannelError(`unable to find resource: ${message}. ` +
+            "Verify the channel name uses org/namespace/service format.", { code: "not_found", httpStatus: httpCode });
+    }
+    if (errorCode === "bad_request" || errorCode === "conflict") {
+        return new errors_1.ChannelError(`invalid request: ${message}`, {
+            code: errorCode,
+            httpStatus: httpCode,
+        });
+    }
+    if (httpCode >= 500) {
+        return new errors_1.TransportError(`API server error (${httpCode}): ${message}. ` +
+            "Check https://status.skytale.sh for service status.", { code: "server_error", httpStatus: httpCode });
+    }
+    return new errors_1.SkytaleError(`API error (${httpCode}): ${message}`, {
+        code: errorCode || "api_error",
+        httpStatus: httpCode,
+    });
+}
+class SkytaleAPI {
+    base;
+    apiKey;
+    maxRetries;
+    constructor(apiUrl, apiKey, maxRetries = 2) {
+        validateApiUrl(apiUrl);
+        this.base = apiUrl.replace(/\/+$/, "");
+        this.apiKey = apiKey;
+        this.maxRetries = maxRetries;
+    }
+    async request(method, path, body) {
+        const url = `${this.base}${path}`;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            let response;
+            try {
+                response = await fetch(url, {
+                    method,
+                    headers: {
+                        Authorization: `Bearer ${this.apiKey}`,
+                        "Content-Type": "application/json",
+                        Accept: "application/json",
+                    },
+                    body: body ? JSON.stringify(body) : undefined,
+                    signal: AbortSignal.timeout(30_000),
+                });
+            }
+            catch (e) {
+                if (attempt < this.maxRetries) {
+                    const delay = backoffDelay(attempt);
+                    await new Promise((r) => setTimeout(r, delay));
+                    continue;
+                }
+                throw new errors_1.TransportError(`unable to reach API at ${url}: ${e}. ` +
+                    "Check your network connection and https://status.skytale.sh", { code: "connection_error" });
+            }
+            if (response.ok) {
+                return (await response.json());
+            }
+            if (RETRYABLE_CODES.has(response.status) && attempt < this.maxRetries) {
+                const retryAfter = response.headers.get("Retry-After");
+                const delay = backoffDelay(attempt, retryAfter);
+                await new Promise((r) => setTimeout(r, delay));
+                continue;
+            }
+            let msg;
+            let code = "";
+            try {
+                const errorBody = (await response.json());
+                msg = errorBody.error ?? response.statusText;
+                code = errorBody.code ?? "";
+            }
+            catch {
+                msg = response.statusText;
+            }
+            throw mapApiError(response.status, code, msg);
+        }
+        throw new errors_1.TransportError(`request to ${url} failed after ${this.maxRetries} retries`, { code: "max_retries_exceeded" });
+    }
+    // ----------------------------------------------------------------
+    // Channel registration
+    // ----------------------------------------------------------------
+    async registerChannel(name) {
+        return (await this.request("POST", "/v1/channels", { name }));
+    }
+    // ----------------------------------------------------------------
+    // Invite tokens
+    // ----------------------------------------------------------------
+    async createInvite(channel, maxUses = 1, ttlSeconds = 3600) {
+        return (await this.request("POST", "/v1/channels/invites", {
+            channel,
+            max_uses: maxUses,
+            ttl_seconds: ttlSeconds,
+        }));
+    }
+    // ----------------------------------------------------------------
+    // Join flow
+    // ----------------------------------------------------------------
+    async join(channel, token, keyPackageB64, identity) {
+        return (await this.request("POST", "/v1/channels/join", {
+            channel,
+            token,
+            key_package: keyPackageB64,
+            identity,
+        }));
+    }
+    async getPending(channel) {
+        const encoded = encodeURIComponent(channel);
+        return (await this.request("GET", `/v1/channels/pending?channel=${encoded}`));
+    }
+    async submitWelcome(requestId, welcomeB64) {
+        return (await this.request("POST", "/v1/channels/welcome", {
+            request_id: requestId,
+            welcome: welcomeB64,
+        }));
+    }
+    async getWelcome(requestId) {
+        return (await this.request("GET", `/v1/channels/welcome/${requestId}`));
+    }
+}
+exports.SkytaleAPI = SkytaleAPI;