@muxi-ai/muxi-typescript 0.20260107.0

package/README.md

@@ -0,0 +1,67 @@
+# MUXI TypeScript SDK
+
+Official TypeScript/Node SDK for [MUXI](https://muxi.org) — infrastructure for AI agents.
+
+**Highlights**
+- Fetch-based HTTP transport (Node 18+), automatic idempotency, SDK/client headers
+- Formation client/admin key auth; server HMAC auth
+- SSE helpers for chat/audio streams and deploy/log tails
+- Retries on 429/5xx/connection errors with exponential backoff
+
+## Installation
+
+```bash
+npm install @muxi-ai/muxi-typescript
+```
+
+## Quick Start (server)
+
+```ts
+import { ServerClient } from "@muxi-ai/muxi-typescript";
+
+const server = new ServerClient({
+  url: "https://server.example.com",
+  keyId: process.env.MUXI_KEY_ID!,
+  secretKey: process.env.MUXI_SECRET_KEY!,
+});
+
+console.log(await server.status());
+```
+
+## Quick Start (formation)
+
+```ts
+import { FormationClient } from "@muxi-ai/muxi-typescript";
+
+const formation = new FormationClient({
+  serverUrl: "https://server.example.com",
+  formationId: "your-formation",
+  clientKey: process.env.MUXI_CLIENT_KEY!,
+  adminKey: process.env.MUXI_ADMIN_KEY!,
+});
+
+console.log(await formation.health());
+
+// Streaming chat (SSE)
+for await (const evt of formation.chatStream({ message: "hello" })) {
+  console.log(evt);
+  break;
+}
+```
+
+## Formation base URL override
+
+- Default: `serverUrl + /api/{formationId}/v1`
+- Override: set `baseUrl` (e.g., `http://localhost:9012/v1` for direct formation)
+
+## Auth & headers
+
+- Server: HMAC with `keyId`/`secretKey` on `/rpc/*` calls.
+- Formation: `X-MUXI-CLIENT-KEY` or `X-MUXI-ADMIN-KEY`; optional `X-Muxi-User-ID` via `userId` param.
+- Idempotency: `X-Muxi-Idempotency-Key` auto-generated on every request.
+- SDK/Client headers set automatically (`X-Muxi-SDK`, `X-Muxi-Client`).
+
+## Streaming
+
+- Chat/audio: `chatStream` / `audioChatStream` return async generators of SSE events.
+- Deploy/log streams: `deployFormationStream`, `updateFormationStream`, `streamFormationLogs`, etc.

package/dist/auth.d.ts

@@ -0,0 +1 @@
+export declare function buildAuthHeader(keyId: string, secretKey: string, method: string, path: string): string;

package/dist/auth.js

@@ -0,0 +1,8 @@
+import { createHmac } from "crypto";
+export function buildAuthHeader(keyId, secretKey, method, path) {
+    const timestamp = Math.floor(Date.now() / 1000);
+    const signPath = path.split("?", 1)[0];
+    const message = `${timestamp};${method};${signPath}`;
+    const mac = createHmac("sha256", secretKey).update(message).digest("base64");
+    return `MUXI-HMAC key=${keyId}, timestamp=${timestamp}, signature=${mac}`;
+}

package/dist/envelope.d.ts

@@ -0,0 +1 @@
+export declare function unwrapEnvelope<T = unknown>(obj: any): T;

package/dist/envelope.js

@@ -0,0 +1,19 @@
+export function unwrapEnvelope(obj) {
+    if (obj === null || typeof obj !== "object")
+        return obj;
+    if (!Object.prototype.hasOwnProperty.call(obj, "data"))
+        return obj;
+    const data = obj.data;
+    const request = obj.request ?? {};
+    const requestId = request.id ?? obj.request_id;
+    const timestamp = obj.timestamp;
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+        const out = { ...data };
+        if (requestId && out.request_id === undefined)
+            out.request_id = requestId;
+        if (timestamp !== undefined && out.timestamp === undefined)
+            out.timestamp = timestamp;
+        return out;
+    }
+    return (data ?? obj);
+}

package/dist/errors.d.ts

@@ -0,0 +1,26 @@
+export declare class MuxiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly data?: unknown;
+    constructor(code: string, message: string, status: number, data?: unknown);
+}
+export declare class AuthenticationError extends MuxiError {
+}
+export declare class AuthorizationError extends MuxiError {
+}
+export declare class NotFoundError extends MuxiError {
+}
+export declare class ConflictError extends MuxiError {
+}
+export declare class ValidationError extends MuxiError {
+}
+export declare class RateLimitError extends MuxiError {
+    readonly retryAfter?: number;
+    constructor(message: string, status: number, retryAfter?: number, data?: unknown);
+}
+export declare class ServerError extends MuxiError {
+}
+export declare class ConnectionError extends MuxiError {
+    constructor(message: string);
+}
+export declare function mapError(status: number, code: string, message: string, details?: any, retryAfter?: number): MuxiError;

package/dist/errors.js

@@ -0,0 +1,48 @@
+export class MuxiError extends Error {
+    constructor(code, message, status, data) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.data = data;
+    }
+}
+export class AuthenticationError extends MuxiError {
+}
+export class AuthorizationError extends MuxiError {
+}
+export class NotFoundError extends MuxiError {
+}
+export class ConflictError extends MuxiError {
+}
+export class ValidationError extends MuxiError {
+}
+export class RateLimitError extends MuxiError {
+    constructor(message, status, retryAfter, data) {
+        super("RATE_LIMITED", message, status, data);
+        this.retryAfter = retryAfter;
+    }
+}
+export class ServerError extends MuxiError {
+}
+export class ConnectionError extends MuxiError {
+    constructor(message) {
+        super("CONNECTION_ERROR", message, 0);
+    }
+}
+export function mapError(status, code, message, details, retryAfter) {
+    if (status === 401)
+        return new AuthenticationError(code || "UNAUTHORIZED", message, status, details);
+    if (status === 403)
+        return new AuthorizationError(code || "FORBIDDEN", message, status, details);
+    if (status === 404)
+        return new NotFoundError(code || "NOT_FOUND", message, status, details);
+    if (status === 409)
+        return new ConflictError(code || "CONFLICT", message, status, details);
+    if (status === 422)
+        return new ValidationError(code || "VALIDATION_ERROR", message, status, details);
+    if (status === 429)
+        return new RateLimitError(message || "Too Many Requests", status, retryAfter, details);
+    if (status >= 500)
+        return new ServerError(code || "SERVER_ERROR", message, status, details);
+    return new MuxiError(code || "ERROR", message, status, details);
+}

package/dist/formation.d.ts

@@ -0,0 +1,89 @@
+export interface FormationClientOptions {
+    formationId: string;
+    clientKey?: string;
+    adminKey?: string;
+    serverUrl?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    debug?: boolean;
+}
+export interface RequestOptions {
+    params?: Record<string, any>;
+    body?: any;
+    userId?: string;
+    headers?: Record<string, string>;
+}
+export declare class FormationClient {
+    private readonly transport;
+    constructor(opts: FormationClientOptions);
+    health(): Promise<any>;
+    getStatus(): Promise<any>;
+    getConfig(): Promise<any>;
+    getFormationInfo(): Promise<any>;
+    getAgents(): Promise<any>;
+    getAgent(agentId: string): Promise<any>;
+    getMcpServers(): Promise<any>;
+    getMcpServer(id: string): Promise<any>;
+    getMcpTools(): Promise<any>;
+    getSecrets(): Promise<any>;
+    getSecret(key: string): Promise<any>;
+    setSecret(key: string, value: string): Promise<any>;
+    deleteSecret(key: string): Promise<any>;
+    chat(payload: Record<string, any>, userId?: string): Promise<any>;
+    chatStream(payload: Record<string, any>, userId?: string): AsyncGenerator<any, void, void>;
+    audioChat(payload: Record<string, any>, userId?: string): Promise<any>;
+    audioChatStream(payload: Record<string, any>, userId?: string): AsyncGenerator<any, void, void>;
+    getSessions(userId: string, limit?: number): Promise<any>;
+    getSession(sessionId: string, userId: string): Promise<any>;
+    getSessionMessages(sessionId: string, userId: string): Promise<any>;
+    restoreSession(sessionId: string, userId: string, messages: any[]): Promise<any>;
+    getRequests(userId: string): Promise<any>;
+    getRequestStatus(requestId: string, userId: string): Promise<any>;
+    cancelRequest(requestId: string, userId: string): Promise<any>;
+    getMemoryConfig(): Promise<any>;
+    getMemories(userId: string, limit?: number): Promise<any>;
+    addMemory(userId: string, type: string, detail: string): Promise<any>;
+    deleteMemory(userId: string, memoryId: string): Promise<any>;
+    getUserBuffer(userId: string): Promise<any>;
+    clearUserBuffer(userId: string): Promise<any>;
+    clearSessionBuffer(userId: string, sessionId: string): Promise<any>;
+    clearAllBuffers(): Promise<any>;
+    getMemoryBuffers(): Promise<any>;
+    getBufferStats(): Promise<any>;
+    getSchedulerConfig(): Promise<any>;
+    getSchedulerJobs(userId: string): Promise<any>;
+    getSchedulerJob(jobId: string): Promise<any>;
+    createSchedulerJob(jobType: string, schedule: string, message: string, userId: string): Promise<any>;
+    deleteSchedulerJob(jobId: string): Promise<any>;
+    getAsyncConfig(): Promise<any>;
+    getAsyncJobs(): Promise<any>;
+    getAsyncJob(jobId: string): Promise<any>;
+    cancelAsyncJob(jobId: string): Promise<any>;
+    getA2AConfig(): Promise<any>;
+    getLoggingConfig(): Promise<any>;
+    getLoggingDestinations(): Promise<any>;
+    listCredentialServices(): Promise<any>;
+    listCredentials(userId: string): Promise<any>;
+    getCredential(credentialId: string, userId: string): Promise<any>;
+    createCredential(userId: string, payload: Record<string, any>): Promise<any>;
+    deleteCredential(credentialId: string, userId: string): Promise<any>;
+    getUserIdentifiers(): Promise<any>;
+    getUserIdentifiersForUser(userId: string): Promise<any>;
+    linkUserIdentifier(muxiUserId: string, identifiers: any[]): Promise<any>;
+    unlinkUserIdentifier(identifier: string): Promise<any>;
+    getOverlordConfig(): Promise<any>;
+    getOverlordPersona(): Promise<any>;
+    getLlmSettings(): Promise<any>;
+    getTriggers(): Promise<any>;
+    getTrigger(name: string): Promise<any>;
+    fireTrigger(name: string, data: any, asyncMode?: boolean, userId?: string): Promise<any>;
+    getSops(): Promise<any>;
+    getSop(name: string): Promise<any>;
+    getAuditLog(): Promise<any>;
+    clearAuditLog(): Promise<any>;
+    streamEvents(userId: string): AsyncGenerator<any, void, void>;
+    streamRequest(userId: string, sessionId: string, requestId: string): AsyncGenerator<any, void, void>;
+    streamLogs(filters?: Record<string, any>): AsyncGenerator<any, void, void>;
+    resolveUser(identifier: string, createUser?: boolean): Promise<any>;
+}

package/dist/formation.js

@@ -0,0 +1,262 @@
+import { unwrapEnvelope } from "./envelope.js";
+import { ConnectionError, MuxiError, mapError } from "./errors.js";
+import { version } from "./version.js";
+import { randomUUID } from "crypto";
+const RETRY_STATUS = new Set([429, 500, 502, 503, 504]);
+function computeBaseUrl(opts) {
+    if (opts.baseUrl)
+        return opts.baseUrl.replace(/\/$/, "");
+    if (!opts.serverUrl)
+        throw new Error("serverUrl or baseUrl is required");
+    return `${opts.serverUrl.replace(/\/$/, "")}/api/${opts.formationId}/v1`;
+}
+function buildUrl(baseUrl, path, params) {
+    const rel = path.startsWith("/") ? path : `/${path}`;
+    const search = new URLSearchParams();
+    Object.entries(params || {}).forEach(([k, v]) => {
+        if (v === undefined || v === null)
+            return;
+        search.set(k, String(v));
+    });
+    const query = search.toString();
+    const fullPath = query ? `${rel}?${query}` : rel;
+    return { url: `${baseUrl}${fullPath}`, fullPath };
+}
+async function parseJson(resp) {
+    const text = await resp.text();
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+class FormationTransport {
+    constructor(baseUrl, adminKey, clientKey, timeoutMs, maxRetries, debug) {
+        this.baseUrl = baseUrl;
+        this.adminKey = adminKey?.trim();
+        this.clientKey = clientKey?.trim();
+        this.timeoutMs = timeoutMs ?? 30_000;
+        this.maxRetries = maxRetries ?? 0;
+        this.debug = !!debug;
+    }
+    headers(useAdmin, userId, extra) {
+        const headers = {
+            "X-Muxi-SDK": `typescript/${version}`,
+            "X-Muxi-Client": `node-${process.version}`,
+            "X-Muxi-Idempotency-Key": randomUUID(),
+        };
+        if (useAdmin) {
+            if (!this.adminKey)
+                throw new Error("admin key required");
+            headers["X-MUXI-ADMIN-KEY"] = this.adminKey;
+        }
+        else {
+            if (!this.clientKey)
+                throw new Error("client key required");
+            headers["X-MUXI-CLIENT-KEY"] = this.clientKey;
+        }
+        if (userId)
+            headers["X-Muxi-User-ID"] = userId;
+        if (extra)
+            Object.assign(headers, extra);
+        return headers;
+    }
+    async requestJson(method, path, opts) {
+        const { url, fullPath } = buildUrl(this.baseUrl, path, opts.params);
+        const headers = this.headers(opts.useAdmin, opts.userId, {
+            ...(opts.body !== undefined ? { "Content-Type": "application/json" } : {}),
+            ...(opts.headers || {}),
+        });
+        const body = opts.body === undefined ? undefined : JSON.stringify(opts.body);
+        let attempt = 0;
+        let backoff = 500;
+        while (true) {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                const resp = await fetch(url, { method, headers, body, signal: controller.signal });
+                clearTimeout(timeout);
+                if (this.debug)
+                    console.debug(`${method} ${fullPath} -> ${resp.status}`);
+                if (resp.status >= 400) {
+                    const payload = await parseJson(resp);
+                    const code = payload?.code || payload?.error || "ERROR";
+                    const message = payload?.message || resp.statusText;
+                    const retryAfter = Number(resp.headers.get("Retry-After") || 0);
+                    if (RETRY_STATUS.has(resp.status) && attempt < this.maxRetries) {
+                        const sleepFor = Math.min(backoff, 30_000);
+                        await new Promise((r) => setTimeout(r, sleepFor));
+                        backoff *= 2;
+                        attempt += 1;
+                        continue;
+                    }
+                    throw mapError(resp.status, code, message, payload, retryAfter);
+                }
+                const data = await parseJson(resp);
+                return unwrapEnvelope(data);
+            }
+            catch (err) {
+                clearTimeout(timeout);
+                if (err instanceof MuxiError)
+                    throw err;
+                if (attempt < this.maxRetries) {
+                    const sleepFor = Math.min(backoff, 30_000);
+                    await new Promise((r) => setTimeout(r, sleepFor));
+                    backoff *= 2;
+                    attempt += 1;
+                    continue;
+                }
+                throw new ConnectionError(err?.message || String(err));
+            }
+        }
+    }
+    async *streamSse(method, path, opts) {
+        const { url, fullPath } = buildUrl(this.baseUrl, path, opts.params);
+        const headers = this.headers(opts.useAdmin, opts.userId, {
+            Accept: "text/event-stream",
+            ...(opts.body !== undefined ? { "Content-Type": "application/json" } : {}),
+            ...(opts.headers || {}),
+        });
+        const body = opts.body === undefined ? undefined : JSON.stringify(opts.body);
+        const resp = await fetch(url, { method, headers, body });
+        if (!resp.ok || !resp.body) {
+            const payload = await parseJson(resp);
+            throw mapError(resp.status, payload?.code || "STREAM_ERROR", payload?.message || resp.statusText, payload);
+        }
+        if (this.debug)
+            console.debug(`${method} ${fullPath} -> stream ${resp.status}`);
+        const reader = resp.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let idx;
+            while ((idx = buffer.indexOf("\n")) >= 0) {
+                const line = buffer.slice(0, idx).trimEnd();
+                buffer = buffer.slice(idx + 1);
+                if (!line)
+                    continue;
+                if (line.startsWith("data:")) {
+                    const payload = line.slice(5).trim();
+                    if (!payload)
+                        continue;
+                    try {
+                        yield JSON.parse(payload);
+                    }
+                    catch {
+                        yield payload;
+                    }
+                }
+            }
+        }
+        if (buffer.trim()) {
+            const payload = buffer.trim();
+            try {
+                yield JSON.parse(payload);
+            }
+            catch {
+                yield payload;
+            }
+        }
+    }
+}
+export class FormationClient {
+    constructor(opts) {
+        const baseUrl = computeBaseUrl(opts);
+        this.transport = new FormationTransport(baseUrl, opts.adminKey, opts.clientKey, opts.timeoutMs, opts.maxRetries, opts.debug);
+    }
+    // Health / status / config
+    health() { return this.transport.requestJson("GET", "/health", { useAdmin: false }); }
+    getStatus() { return this.transport.requestJson("GET", "/status", { useAdmin: true }); }
+    getConfig() { return this.transport.requestJson("GET", "/config", { useAdmin: true }); }
+    getFormationInfo() { return this.transport.requestJson("GET", "/formation", { useAdmin: true }); }
+    // Agents / MCP
+    getAgents() { return this.transport.requestJson("GET", "/agents", { useAdmin: true }); }
+    getAgent(agentId) { return this.transport.requestJson("GET", `/agents/${agentId}`, { useAdmin: true }); }
+    getMcpServers() { return this.transport.requestJson("GET", "/mcp/servers", { useAdmin: true }); }
+    getMcpServer(id) { return this.transport.requestJson("GET", `/mcp/servers/${id}`, { useAdmin: true }); }
+    getMcpTools() { return this.transport.requestJson("GET", "/mcp/tools", { useAdmin: true }); }
+    // Secrets
+    getSecrets() { return this.transport.requestJson("GET", "/secrets", { useAdmin: true }); }
+    getSecret(key) { return this.transport.requestJson("GET", `/secrets/${key}`, { useAdmin: true }); }
+    setSecret(key, value) { return this.transport.requestJson("POST", `/secrets/${key}`, { useAdmin: true, body: { value } }); }
+    deleteSecret(key) { return this.transport.requestJson("DELETE", `/secrets/${key}`, { useAdmin: true }); }
+    // Chat
+    chat(payload, userId = "") { return this.transport.requestJson("POST", "/chat", { useAdmin: false, body: payload, userId }); }
+    chatStream(payload, userId = "") {
+        return this.transport.streamSse("POST", "/chat", { useAdmin: false, body: { ...payload, stream: true }, userId });
+    }
+    audioChat(payload, userId = "") { return this.transport.requestJson("POST", "/audiochat", { useAdmin: false, body: payload, userId }); }
+    audioChatStream(payload, userId = "") {
+        return this.transport.streamSse("POST", "/audiochat", { useAdmin: false, body: { ...payload, stream: true }, userId });
+    }
+    // Sessions / requests
+    getSessions(userId, limit) { return this.transport.requestJson("GET", "/sessions", { useAdmin: false, params: { user_id: userId, limit }, userId }); }
+    getSession(sessionId, userId) { return this.transport.requestJson("GET", `/sessions/${sessionId}`, { useAdmin: false, userId }); }
+    getSessionMessages(sessionId, userId) { return this.transport.requestJson("GET", `/sessions/${sessionId}/messages`, { useAdmin: false, userId }); }
+    restoreSession(sessionId, userId, messages) { return this.transport.requestJson("POST", `/sessions/${sessionId}/restore`, { useAdmin: false, userId, body: { messages } }); }
+    getRequests(userId) { return this.transport.requestJson("GET", "/requests", { useAdmin: false, userId }); }
+    getRequestStatus(requestId, userId) { return this.transport.requestJson("GET", `/requests/${requestId}`, { useAdmin: false, userId }); }
+    cancelRequest(requestId, userId) { return this.transport.requestJson("DELETE", `/requests/${requestId}`, { useAdmin: false, userId }); }
+    // Memory
+    getMemoryConfig() { return this.transport.requestJson("GET", "/memory", { useAdmin: true }); }
+    getMemories(userId, limit) { return this.transport.requestJson("GET", "/memory/user", { useAdmin: false, params: { user_id: userId, limit } }); }
+    addMemory(userId, type, detail) { return this.transport.requestJson("POST", "/memory", { useAdmin: false, body: { user_id: userId, type, detail } }); }
+    deleteMemory(userId, memoryId) { return this.transport.requestJson("DELETE", `/memory/${memoryId}`, { useAdmin: false, params: { user_id: userId } }); }
+    getUserBuffer(userId) { return this.transport.requestJson("GET", `/memory/buffer/${userId}`, { useAdmin: false }); }
+    clearUserBuffer(userId) { return this.transport.requestJson("DELETE", `/memory/buffer/${userId}`, { useAdmin: false }); }
+    clearSessionBuffer(userId, sessionId) { return this.transport.requestJson("DELETE", `/memory/buffer/${userId}/${sessionId}`, { useAdmin: false }); }
+    clearAllBuffers() { return this.transport.requestJson("DELETE", "/memory/buffer", { useAdmin: true }); }
+    getMemoryBuffers() { return this.transport.requestJson("GET", "/memory/buffers", { useAdmin: true }); }
+    getBufferStats() { return this.transport.requestJson("GET", "/memory/stats", { useAdmin: true }); }
+    // Scheduler
+    getSchedulerConfig() { return this.transport.requestJson("GET", "/scheduler/config", { useAdmin: true }); }
+    getSchedulerJobs(userId) { return this.transport.requestJson("GET", "/scheduler/jobs", { useAdmin: true, params: { user_id: userId } }); }
+    getSchedulerJob(jobId) { return this.transport.requestJson("GET", `/scheduler/jobs/${jobId}`, { useAdmin: true }); }
+    createSchedulerJob(jobType, schedule, message, userId) {
+        return this.transport.requestJson("POST", "/scheduler/jobs", { useAdmin: true, body: { type: jobType, schedule, message, user_id: userId } });
+    }
+    deleteSchedulerJob(jobId) { return this.transport.requestJson("DELETE", `/scheduler/jobs/${jobId}`, { useAdmin: true }); }
+    // Async / logging / a2a
+    getAsyncConfig() { return this.transport.requestJson("GET", "/async", { useAdmin: true }); }
+    getAsyncJobs() { return this.transport.requestJson("GET", "/async/jobs", { useAdmin: true }); }
+    getAsyncJob(jobId) { return this.transport.requestJson("GET", `/async/jobs/${jobId}`, { useAdmin: true }); }
+    cancelAsyncJob(jobId) { return this.transport.requestJson("DELETE", `/async/jobs/${jobId}`, { useAdmin: true }); }
+    getA2AConfig() { return this.transport.requestJson("GET", "/a2a", { useAdmin: true }); }
+    getLoggingConfig() { return this.transport.requestJson("GET", "/logging", { useAdmin: true }); }
+    getLoggingDestinations() { return this.transport.requestJson("GET", "/logging/destinations", { useAdmin: true }); }
+    // Credentials / identifiers
+    listCredentialServices() { return this.transport.requestJson("GET", "/credentials/services", { useAdmin: true }); }
+    listCredentials(userId) { return this.transport.requestJson("GET", "/credentials", { useAdmin: false, userId }); }
+    getCredential(credentialId, userId) { return this.transport.requestJson("GET", `/credentials/${credentialId}`, { useAdmin: false, userId }); }
+    createCredential(userId, payload) { return this.transport.requestJson("POST", "/credentials", { useAdmin: false, userId, body: payload }); }
+    deleteCredential(credentialId, userId) { return this.transport.requestJson("DELETE", `/credentials/${credentialId}`, { useAdmin: false, userId }); }
+    getUserIdentifiers() { return this.transport.requestJson("GET", "/users/identifiers", { useAdmin: true }); }
+    getUserIdentifiersForUser(userId) { return this.transport.requestJson("GET", `/users/${userId}/identifiers`, { useAdmin: true }); }
+    linkUserIdentifier(muxiUserId, identifiers) { return this.transport.requestJson("POST", "/users/identifiers", { useAdmin: true, body: { muxi_user_id: muxiUserId, identifiers } }); }
+    unlinkUserIdentifier(identifier) { return this.transport.requestJson("DELETE", `/users/identifiers/${identifier}`, { useAdmin: true }); }
+    // Overlord / LLM
+    getOverlordConfig() { return this.transport.requestJson("GET", "/overlord", { useAdmin: true }); }
+    getOverlordPersona() { return this.transport.requestJson("GET", "/overlord/persona", { useAdmin: true }); }
+    getLlmSettings() { return this.transport.requestJson("GET", "/llm/settings", { useAdmin: true }); }
+    // Triggers / SOP / Audit
+    getTriggers() { return this.transport.requestJson("GET", "/triggers", { useAdmin: false }); }
+    getTrigger(name) { return this.transport.requestJson("GET", `/triggers/${name}`, { useAdmin: false }); }
+    fireTrigger(name, data, asyncMode = false, userId = "") { return this.transport.requestJson("POST", `/triggers/${name}`, { useAdmin: false, userId, params: { async: String(asyncMode).toLowerCase() }, body: data }); }
+    getSops() { return this.transport.requestJson("GET", "/sops", { useAdmin: false }); }
+    getSop(name) { return this.transport.requestJson("GET", `/sops/${name}`, { useAdmin: false }); }
+    getAuditLog() { return this.transport.requestJson("GET", "/audit", { useAdmin: true }); }
+    clearAuditLog() { return this.transport.requestJson("DELETE", "/audit", { useAdmin: true, params: { confirm: "clear-audit-log" } }); }
+    // Events / logs streaming
+    streamEvents(userId) { return this.transport.streamSse("GET", `/events/${userId}`, { useAdmin: false }); }
+    streamRequest(userId, sessionId, requestId) { return this.transport.streamSse("GET", `/requests/${requestId}/stream`, { useAdmin: false, params: { user_id: userId, session_id: sessionId } }); }
+    streamLogs(filters) { return this.transport.streamSse("POST", "/logs/stream", { useAdmin: true, body: filters || {} }); }
+    // Resolve user
+    resolveUser(identifier, createUser = false) { return this.transport.requestJson("GET", "/users/resolve", { useAdmin: false, params: { identifier, create_user: String(createUser).toLowerCase() } }); }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { ServerClient, type ServerClientOptions } from "./server.js";
+export { FormationClient, type FormationClientOptions } from "./formation.js";
+export { MuxiError, ConnectionError } from "./errors.js";
+export { version } from "./version.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { ServerClient } from "./server.js";
+export { FormationClient } from "./formation.js";
+export { MuxiError, ConnectionError } from "./errors.js";
+export { version } from "./version.js";

package/dist/server.d.ts

@@ -0,0 +1,37 @@
+import type { RequestOptions } from "./transport.js";
+export interface ServerClientOptions {
+    url: string;
+    keyId: string;
+    secretKey: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    debug?: boolean;
+}
+export declare class ServerClient {
+    private readonly transport;
+    constructor(opts: ServerClientOptions);
+    ping(): Promise<any>;
+    health(): Promise<any>;
+    status(): Promise<any>;
+    listFormations(): Promise<any>;
+    getFormation(id: string): Promise<any>;
+    stopFormation(id: string): Promise<any>;
+    startFormation(id: string): Promise<any>;
+    restartFormation(id: string): Promise<any>;
+    rollbackFormation(id: string): Promise<any>;
+    deleteFormation(id: string): Promise<any>;
+    cancelUpdate(id: string): Promise<any>;
+    deployFormation(id: string, payload: Record<string, any>): Promise<any>;
+    updateFormation(id: string, payload: Record<string, any>): Promise<any>;
+    getFormationLogs(id: string, limit?: number): Promise<any>;
+    getServerLogs(limit?: number): Promise<any>;
+    deployFormationStream(id: string, payload: Record<string, any>): AsyncGenerator<any, void, unknown>;
+    updateFormationStream(id: string, payload: Record<string, any>): AsyncGenerator<any, void, unknown>;
+    startFormationStream(id: string): AsyncGenerator<any, void, unknown>;
+    restartFormationStream(id: string): AsyncGenerator<any, void, unknown>;
+    rollbackFormationStream(id: string): AsyncGenerator<any, void, unknown>;
+    streamFormationLogs(id: string): AsyncGenerator<any, void, unknown>;
+    _rpcGet<T = any>(path: string, options?: RequestOptions): Promise<T>;
+    _rpcPost<T = any>(path: string, body: Record<string, any>): Promise<T>;
+    _rpcDelete<T = any>(path: string): Promise<T>;
+}

package/dist/server.js

@@ -0,0 +1,60 @@
+import { Transport } from "./transport.js";
+async function* parseSseLines(lines) {
+    for await (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        if (!trimmed.startsWith("data:"))
+            continue;
+        const payload = trimmed.slice(5).trim();
+        if (!payload)
+            continue;
+        try {
+            yield JSON.parse(payload);
+        }
+        catch {
+            yield payload;
+        }
+    }
+}
+export class ServerClient {
+    constructor(opts) {
+        const topts = {
+            baseUrl: opts.url.replace(/\/$/, ""),
+            keyId: opts.keyId,
+            secretKey: opts.secretKey,
+            timeoutMs: opts.timeoutMs,
+            maxRetries: opts.maxRetries,
+            debug: opts.debug,
+        };
+        this.transport = new Transport(topts);
+    }
+    // Unauthenticated
+    ping() { return this.transport.requestJson("GET", "/ping"); }
+    health() { return this.transport.requestJson("GET", "/health"); }
+    // Authenticated
+    status() { return this._rpcGet("/rpc/server/status"); }
+    listFormations() { return this._rpcGet("/rpc/formations"); }
+    getFormation(id) { return this._rpcGet(`/rpc/formations/${id}`); }
+    stopFormation(id) { return this._rpcPost(`/rpc/formations/${id}/stop`, {}); }
+    startFormation(id) { return this._rpcPost(`/rpc/formations/${id}/start`, {}); }
+    restartFormation(id) { return this._rpcPost(`/rpc/formations/${id}/restart`, {}); }
+    rollbackFormation(id) { return this._rpcPost(`/rpc/formations/${id}/rollback`, {}); }
+    deleteFormation(id) { return this._rpcDelete(`/rpc/formations/${id}`); }
+    cancelUpdate(id) { return this._rpcPost(`/rpc/formations/${id}/cancel-update`, {}); }
+    deployFormation(id, payload) { return this._rpcPost(`/rpc/formations/${id}/deploy`, payload); }
+    updateFormation(id, payload) { return this._rpcPost(`/rpc/formations/${id}/update`, payload); }
+    getFormationLogs(id, limit) { return this._rpcGet(`/rpc/formations/${id}/logs`, { params: limit !== undefined ? { limit } : undefined }); }
+    getServerLogs(limit) { return this._rpcGet(`/rpc/server/logs`, { params: limit !== undefined ? { limit } : undefined }); }
+    // Streaming
+    deployFormationStream(id, payload) { return parseSseLines(this.transport.streamLines("POST", `/rpc/formations/${id}/deploy/stream`, { body: payload })); }
+    updateFormationStream(id, payload) { return parseSseLines(this.transport.streamLines("POST", `/rpc/formations/${id}/update/stream`, { body: payload })); }
+    startFormationStream(id) { return parseSseLines(this.transport.streamLines("POST", `/rpc/formations/${id}/start/stream`, { body: {} })); }
+    restartFormationStream(id) { return parseSseLines(this.transport.streamLines("POST", `/rpc/formations/${id}/restart/stream`, { body: {} })); }
+    rollbackFormationStream(id) { return parseSseLines(this.transport.streamLines("POST", `/rpc/formations/${id}/rollback/stream`, { body: {} })); }
+    streamFormationLogs(id) { return parseSseLines(this.transport.streamLines("GET", `/rpc/formations/${id}/logs/stream`)); }
+    // Generic RPC helpers
+    _rpcGet(path, options = {}) { return this.transport.requestJson("GET", path, options); }
+    _rpcPost(path, body) { return this.transport.requestJson("POST", path, { body }); }
+    _rpcDelete(path) { return this.transport.requestJson("DELETE", path); }
+}

package/dist/transport.d.ts

@@ -0,0 +1,21 @@
+export interface TransportOptions {
+    baseUrl: string;
+    keyId?: string;
+    secretKey?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    debug?: boolean;
+}
+export interface RequestOptions {
+    params?: Record<string, any>;
+    body?: any;
+    headers?: Record<string, string>;
+    authPath?: string;
+    stream?: boolean;
+}
+export declare class Transport {
+    private readonly opts;
+    constructor(opts: TransportOptions);
+    requestJson<T = any>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    streamLines(method: string, path: string, options?: RequestOptions): AsyncGenerator<string, void, void>;
+}

package/dist/transport.js

@@ -0,0 +1,138 @@
+import { buildAuthHeader } from "./auth.js";
+import { unwrapEnvelope } from "./envelope.js";
+import { ConnectionError, MuxiError, mapError } from "./errors.js";
+import { version } from "./version.js";
+import { randomUUID } from "crypto";
+const RETRY_STATUS = new Set([429, 500, 502, 503, 504]);
+function buildUrl(baseUrl, path, params) {
+    const rel = path.startsWith("/") ? path : `/${path}`;
+    const search = new URLSearchParams();
+    Object.entries(params || {}).forEach(([k, v]) => {
+        if (v === undefined || v === null)
+            return;
+        search.set(k, String(v));
+    });
+    const query = search.toString();
+    const fullPath = query ? `${rel}?${query}` : rel;
+    return { url: `${baseUrl}${fullPath}`, fullPath };
+}
+function baseHeaders(opts, method, pathForAuth, extra) {
+    const headers = {
+        "Content-Type": "application/json",
+        "X-Muxi-SDK": `typescript/${version}`,
+        "X-Muxi-Client": `node-${process.version}`,
+        "X-Muxi-Idempotency-Key": randomUUID(),
+    };
+    if (opts.keyId && opts.secretKey) {
+        headers.Authorization = buildAuthHeader(opts.keyId.trim(), opts.secretKey.trim(), method, pathForAuth);
+    }
+    if (extra)
+        Object.assign(headers, extra);
+    return headers;
+}
+async function parseJson(resp) {
+    const text = await resp.text();
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+export class Transport {
+    constructor(opts) {
+        this.opts = { ...opts, timeoutMs: opts.timeoutMs ?? 30_000, maxRetries: opts.maxRetries ?? 0 };
+    }
+    async requestJson(method, path, options = {}) {
+        const { url, fullPath } = buildUrl(this.opts.baseUrl, path, options.params);
+        const headers = baseHeaders(this.opts, method, options.authPath ?? fullPath, options.headers);
+        const body = options.body === undefined ? undefined : JSON.stringify(options.body);
+        let attempt = 0;
+        let backoff = 500;
+        while (true) {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.opts.timeoutMs);
+            try {
+                const resp = await fetch(url, {
+                    method,
+                    headers,
+                    body,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeout);
+                if (this.opts.debug) {
+                    console.debug(`${method} ${url} -> ${resp.status}`);
+                }
+                if (resp.status >= 400) {
+                    const payload = await parseJson(resp);
+                    const code = payload?.code || payload?.error || "ERROR";
+                    const message = payload?.message || resp.statusText;
+                    const retryAfter = Number(resp.headers.get("Retry-After") || 0);
+                    if (RETRY_STATUS.has(resp.status) && attempt < (this.opts.maxRetries ?? 0)) {
+                        const sleepFor = Math.min(backoff, 30_000);
+                        await new Promise((r) => setTimeout(r, sleepFor));
+                        backoff *= 2;
+                        attempt += 1;
+                        continue;
+                    }
+                    throw mapError(resp.status, code, message, payload, retryAfter);
+                }
+                const data = await parseJson(resp);
+                return unwrapEnvelope(data);
+            }
+            catch (err) {
+                clearTimeout(timeout);
+                if (err instanceof MuxiError)
+                    throw err;
+                if (attempt < (this.opts.maxRetries ?? 0)) {
+                    const sleepFor = Math.min(backoff, 30_000);
+                    await new Promise((r) => setTimeout(r, sleepFor));
+                    backoff *= 2;
+                    attempt += 1;
+                    continue;
+                }
+                throw new ConnectionError(err?.message || String(err));
+            }
+        }
+    }
+    async *streamLines(method, path, options = {}) {
+        const { url, fullPath } = buildUrl(this.opts.baseUrl, path, options.params);
+        const headers = baseHeaders(this.opts, method, options.authPath ?? fullPath, {
+            Accept: "text/event-stream",
+            ...(options.headers || {}),
+        });
+        const body = options.body === undefined ? undefined : JSON.stringify(options.body);
+        const resp = await fetch(url, {
+            method,
+            headers,
+            body,
+            signal: undefined,
+        });
+        if (!resp.ok || !resp.body) {
+            const payload = await parseJson(resp);
+            throw new MuxiError(payload?.code || "STREAM_ERROR", payload?.message || resp.statusText, resp.status, payload);
+        }
+        const reader = resp.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let idx;
+            while ((idx = buffer.indexOf("\n")) >= 0) {
+                const line = buffer.slice(0, idx).trimEnd();
+                buffer = buffer.slice(idx + 1);
+                if (!line)
+                    continue;
+                yield line;
+            }
+        }
+        if (buffer.trim()) {
+            yield buffer.trim();
+        }
+    }
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const version = "0.0.0";

package/dist/version.js

@@ -0,0 +1 @@
+export const version = "0.0.0";

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@muxi-ai/muxi-typescript",
+  "version": "0.20260107.0",
+  "description": "Official MUXI SDK for TypeScript",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "test": "npm run build && npm run test:unit && npm run test:e2e",
+    "test:unit": "node --test --loader ts-node/esm tests/unit/*.test.ts",
+    "test:e2e": "node --test --loader ts-node/esm tests/e2e/*.test.ts"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/muxi-ai/muxi-typescript.git"
+  },
+  "bugs": {
+    "url": "https://github.com/muxi-ai/muxi-typescript/issues"
+  },
+  "homepage": "https://github.com/muxi-ai/muxi-typescript#readme",
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  }
+}