maidan 0.0.1 → 0.1.0

package/README.md

@@ -1,5 +1,50 @@
-# maidan
+# maidan (TypeScript)
 
-Official TypeScript client for Maidan, the operating layer for teams of AI agents.
+Official TypeScript client for [Maidan](https://github.com/david-engelmann/maidan), the
+operating layer for teams of AI agents. **REST + WebSocket** (MCP is a URL, not a
+dependency; A2A is a recipe). Dependency-free: uses the global `fetch` (Node 18+) and a
+WebSocket (global in the browser / Node 22+, or inject one via `options.WebSocket`).
 
-**0.0.1 is a name reservation.** The API is not stable.
+```sh
+npm install maidan
+```
+
+```js
+import { Client } from "maidan";
+
+const client = new Client("http://127.0.0.1:8080", process.env.MAIDAN_TOKEN);
+
+// Hero loop: claim the next ready task, do work, post, set a result.
+const { thread } = await client.claimNextThread(channelId);
+if (thread) {
+  await client.messages.post(thread.id, memberId, "on it");
+  await client.threads.setResult(thread.id, { ok: true });
+}
+
+// React to work instead of polling.
+const sub = await client.subscribe({ workspace_id: wid, kinds: ["message_posted"] }, (e) => {
+  console.log("event", e.kind, e.thread_id);
+});
+// sub.close();
+
+// Or block until a specific signal (wraps subscribe):
+const ready = await client.waitForReady(wid); // event or null on timeout
+```
+
+- Constructor: `new Client(baseUrl?, token?, options?)` — defaults from `MAIDAN_URL` /
+  `MAIDAN_TOKEN`; explicit args win. `client.mcpUrl` is `{baseUrl}/mcp/streamable`.
+- Errors throw `MaidanError` (`.status`, `.body`, `.retryAfter` on 429, `.isConflict` /
+  `.isForbidden` / `.isRateLimited`).
+- Surface (frozen v1): `workspaces.{create,get,import}`, `channels.{list,create}`,
+  `threads.{create,get,context,transition,setResult,getResult}`, `claimNextThread`,
+  `renewClaim`, `messages.{list,post}`, `artifacts.{upload,get,meta}`, `subscribe`, and
+  the `waitFor*` helpers. See the repo's `docs/Client Contract.md`.
+
+**Node < 22** has no global WebSocket — pass one for `subscribe`:
+
+```js
+import WebSocket from "ws";
+const client = new Client(url, token, { WebSocket });
+```
+
+Versioned independently of the server. `0.1.0` is the first usable release.

package/index.d.ts

@@ -1,5 +1,97 @@
+// Type declarations for the Maidan v1 client. See docs/Client Contract.md.
+
+// Intent-conveying ID types. The brand is optional so plain strings remain
+// assignable (usable now); stricter enforcement is a future refinement.
+export type WorkspaceId = string & { readonly __maidan?: "workspace" };
+export type ChannelId = string & { readonly __maidan?: "channel" };
+export type ThreadId = string & { readonly __maidan?: "thread" };
+export type MemberId = string & { readonly __maidan?: "member" };
+export type Sha256 = string & { readonly __maidan?: "sha256" };
+
+export interface ClientOptions {
+  fetch?: typeof fetch;
+  /** WebSocket constructor (global in browser / Node 22+; else pass the `ws` package). */
+  WebSocket?: any;
+}
+
+/** A single error type carrying the HTTP status and the server's JSON body. */
+export declare class MaidanError extends Error {
+  status: number;
+  body: unknown;
+  /** Seconds from `Retry-After` on a 429 (server rate limit). */
+  retryAfter?: number;
+  get isConflict(): boolean; // 409
+  get isForbidden(): boolean; // 403 (missing capability / channel access — not retryable)
+  get isRateLimited(): boolean; // 429
+}
+
+/** A subscription handle. */
+export interface Subscription {
+  close(): void;
+}
+
+/** An event frame from the bus (unknown `kind`s are still delivered). */
+export interface EventFrame {
+  kind: string;
+  log_id?: number;
+  workspace_id?: string;
+  channel_id?: string;
+  thread_id?: string;
+  member_id?: string;
+  [key: string]: unknown;
+}
+
 export declare class Client {
   baseUrl: string;
   token: string;
-  constructor(baseUrl: string, token: string);
+  /** `{baseUrl}/mcp/streamable` — a string only, no MCP dependency. */
+  mcpUrl: string;
+
+  constructor(baseUrl?: string, token?: string, options?: ClientOptions);
+
+  workspaces: {
+    create(name: string): Promise<any>;
+    get(id: WorkspaceId): Promise<any>;
+    /** Admin-only (`token:admin`). */
+    import(bundle: unknown, mode?: "restore"): Promise<any>;
+  };
+  channels: {
+    list(wid: WorkspaceId): Promise<any>;
+    create(wid: WorkspaceId, name: string, priv?: boolean): Promise<any>;
+  };
+  threads: {
+    create(cid: ChannelId, title: string): Promise<any>;
+    get(id: ThreadId): Promise<any>;
+    context(id: ThreadId, query?: Record<string, string | number>): Promise<any>;
+    transition(id: ThreadId, body: unknown): Promise<any>;
+    setResult(id: ThreadId, result: unknown): Promise<any>;
+    getResult(id: ThreadId): Promise<any>;
+  };
+  messages: {
+    list(tid: ThreadId, query?: Record<string, string | number>): Promise<any>;
+    post(tid: ThreadId, authorId: MemberId, body: string): Promise<any>;
+  };
+  artifacts: {
+    upload(bytes: Uint8Array | ArrayBuffer | string, kind: string): Promise<any>;
+    get(sha: Sha256): Promise<Uint8Array>;
+    meta(sha: Sha256): Promise<any>;
+  };
+
+  /** Hero: readiness/skill/lease-aware claim of the next thread in a channel. */
+  claimNextThread(cid: ChannelId, body?: unknown): Promise<any>;
+  /** Holder-only lease heartbeat. */
+  renewClaim(id: ThreadId): Promise<any>;
+
+  subscribe(
+    filter: Record<string, unknown>,
+    onEvent: (event: EventFrame) => void,
+    onError?: (err: unknown) => void,
+  ): Promise<Subscription>;
+
+  /** Wait helpers wrap `subscribe`; resolve with the event or null on timeout. */
+  waitForResult(threadId: ThreadId, workspaceId: WorkspaceId, timeoutMs?: number): Promise<EventFrame | null>;
+  waitForMention(memberId: MemberId, workspaceId: WorkspaceId, timeoutMs?: number): Promise<EventFrame | null>;
+  waitForReady(workspaceId: WorkspaceId, channelId?: ChannelId, timeoutMs?: number): Promise<EventFrame | null>;
 }
+
+export default Client;

package/index.js

@@ -1,6 +1,218 @@
+// Maidan TypeScript client (v1 surface). REST + WebSocket, dependency-free:
+// uses the global `fetch` (Node 18+) and a pluggable WebSocket (global in the
+// browser / Node 22+, or inject one via `options.WebSocket`). See docs/Client
+// Contract.md for the frozen surface.
+
+export class MaidanError extends Error {
+  constructor(status, body, message) {
+    super(message || `Maidan request failed: HTTP ${status}`);
+    this.name = "MaidanError";
+    this.status = status;
+    this.body = body;
+    // Retry-After (seconds) surfaced on 429 (server rate limit, Cluster 172).
+    this.retryAfter = undefined;
+  }
+  get isConflict() {
+    return this.status === 409;
+  }
+  get isForbidden() {
+    return this.status === 403;
+  }
+  get isRateLimited() {
+    return this.status === 429;
+  }
+}
+
+function envDefault(key) {
+  return typeof process !== "undefined" && process.env ? process.env[key] : undefined;
+}
+
 export class Client {
-  constructor(baseUrl, token) {
-    this.baseUrl = baseUrl;
-    this.token = token;
+  /**
+   * @param {string} [baseUrl] defaults to MAIDAN_URL
+   * @param {string} [token] defaults to MAIDAN_TOKEN
+   * @param {{ fetch?: typeof fetch, WebSocket?: any }} [options]
+   */
+  constructor(baseUrl, token, options = {}) {
+    this.baseUrl = (baseUrl || envDefault("MAIDAN_URL") || "http://127.0.0.1:8080").replace(
+      /\/+$/,
+      "",
+    );
+    this.token = token || envDefault("MAIDAN_TOKEN") || "";
+    this._fetch = options.fetch || (typeof fetch !== "undefined" ? fetch : undefined);
+    this._WebSocket = options.WebSocket || (typeof WebSocket !== "undefined" ? WebSocket : undefined);
+
+    // MCP is a URL, not a dependency (docs/Client Contract.md §4).
+    this.mcpUrl = `${this.baseUrl}/mcp/streamable`;
+
+    this.workspaces = {
+      create: (name) => this._req("POST", "/workspaces", { name }),
+      get: (id) => this._req("GET", `/workspaces/${id}`),
+      import: (bundle, mode) =>
+        this._req("POST", `/workspaces/import${mode ? `?mode=${mode}` : ""}`, bundle),
+    };
+    this.channels = {
+      list: (wid) => this._req("GET", `/workspaces/${wid}/channels`),
+      create: (wid, name, priv = false) =>
+        this._req("POST", `/workspaces/${wid}/channels`, { name, private: priv }),
+    };
+    this.threads = {
+      create: (cid, title) => this._req("POST", `/channels/${cid}/threads`, { title }),
+      get: (id) => this._req("GET", `/threads/${id}`),
+      context: (id, query) => this._req("GET", `/threads/${id}/context${qs(query)}`),
+      transition: (id, body) => this._req("POST", `/threads/${id}`, body),
+      setResult: (id, result) => this._req("PUT", `/threads/${id}/result`, { result }),
+      getResult: (id) => this._req("GET", `/threads/${id}/result`),
+    };
+    this.messages = {
+      list: (tid, query) => this._req("GET", `/threads/${tid}/messages${qs(query)}`),
+      post: (tid, authorId, body) =>
+        this._req("POST", `/threads/${tid}/messages`, { author_id: authorId, body }),
+    };
+    this.artifacts = {
+      upload: (bytes, kind) => this._reqRaw("POST", `/artifacts?kind=${kind}`, bytes),
+      get: (sha) => this._reqRaw("GET", `/artifacts/${sha}`),
+      meta: (sha) => this._req("GET", `/artifacts/${sha}/meta`),
+    };
+  }
+
+  /** POST /channels/{cid}/threads/claim-next — readiness/skill/lease-aware. */
+  claimNextThread(cid, body) {
+    return this._req("POST", `/channels/${cid}/threads/claim-next`, body || {});
+  }
+  /** POST /threads/{id}/claim/renew — holder-only lease heartbeat. */
+  renewClaim(id) {
+    return this._req("POST", `/threads/${id}/claim/renew`, {});
+  }
+
+  async _req(method, path, body) {
+    const headers = { authorization: `Bearer ${this.token}` };
+    const init = { method, headers };
+    if (body !== undefined) {
+      headers["content-type"] = "application/json";
+      init.body = JSON.stringify(body);
+    }
+    const resp = await this._fetch(`${this.baseUrl}${path}`, init);
+    return this._handle(resp);
   }
+
+  async _reqRaw(method, path, body) {
+    const headers = { authorization: `Bearer ${this.token}` };
+    const init = { method, headers };
+    if (body !== undefined) init.body = body;
+    const resp = await this._fetch(`${this.baseUrl}${path}`, init);
+    if (method === "GET") {
+      if (!resp.ok) await this._raise(resp);
+      return new Uint8Array(await resp.arrayBuffer());
+    }
+    return this._handle(resp);
+  }
+
+  async _handle(resp) {
+    if (!resp.ok) await this._raise(resp);
+    if (resp.status === 204) return undefined;
+    const text = await resp.text();
+    return text ? JSON.parse(text) : undefined;
+  }
+
+  async _raise(resp) {
+    let parsed;
+    const text = await resp.text().catch(() => "");
+    try {
+      parsed = text ? JSON.parse(text) : undefined;
+    } catch {
+      parsed = text;
+    }
+    const err = new MaidanError(resp.status, parsed);
+    if (resp.status === 429) {
+      const ra = resp.headers.get("retry-after");
+      if (ra) err.retryAfter = Number(ra);
+    }
+    throw err;
+  }
+
+  /**
+   * Subscribe to the event stream over WebSocket. `filter` follows
+   * contracts/ws-subscribe-filter.schema.json (set `workspace_id` to enable
+   * replay). Returns a handle with `close()`. Control frames (subscribe_ack,
+   * schema_version, replay_*) are skipped; each domain event is passed to
+   * `onEvent`. Unknown `kind`s are still delivered (forward-compat).
+   * @returns {Promise<{ close: () => void }>}
+   */
+  subscribe(filter, onEvent, onError) {
+    if (!this._WebSocket) {
+      return Promise.reject(
+        new Error("No WebSocket available; pass options.WebSocket (e.g. the `ws` package on Node <22)"),
+      );
+    }
+    const wsUrl = `${this.baseUrl.replace(/^http/, "ws")}/ws/subscribe`;
+    const ws = new this._WebSocket(wsUrl);
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      ws.onopen = () => {
+        ws.send(JSON.stringify({ filter: filter || {}, token: this.token }));
+        settled = true;
+        resolve({ close: () => ws.close() });
+      };
+      ws.onerror = (e) => {
+        if (!settled) reject(e);
+        else if (onError) onError(e);
+      };
+      ws.onmessage = (ev) => {
+        let frame;
+        try {
+          frame = JSON.parse(typeof ev.data === "string" ? ev.data : ev.data.toString());
+        } catch {
+          return;
+        }
+        if (frame && frame.type) return; // control frame (subscribe_ack, replay_hint, …)
+        if (frame && typeof frame.kind === "string") onEvent(frame);
+      };
+    });
+  }
+
+  /** Resolve with the first event whose `kind` matches, or null after `timeoutMs`. */
+  _waitForKind(filter, kind, timeoutMs = 30000) {
+    return new Promise((resolve, reject) => {
+      let handle;
+      const timer = setTimeout(() => {
+        if (handle) handle.close();
+        resolve(null);
+      }, timeoutMs);
+      this.subscribe(
+        { ...filter, kinds: [kind] },
+        (event) => {
+          clearTimeout(timer);
+          if (handle) handle.close();
+          resolve(event);
+        },
+        (e) => {
+          clearTimeout(timer);
+          reject(e);
+        },
+      ).then((h) => {
+        handle = h;
+      }, reject);
+    });
+  }
+
+  waitForResult(threadId, workspaceId, timeoutMs) {
+    return this._waitForKind({ workspace_id: workspaceId, thread_id: threadId }, "thread_result_set", timeoutMs);
+  }
+  waitForMention(memberId, workspaceId, timeoutMs) {
+    return this._waitForKind({ workspace_id: workspaceId, member_id: memberId }, "mention_recorded", timeoutMs);
+  }
+  waitForReady(workspaceId, channelId, timeoutMs) {
+    const f = { workspace_id: workspaceId };
+    if (channelId) f.channel_id = channelId;
+    return this._waitForKind(f, "thread_ready", timeoutMs);
+  }
+}
+
+function qs(query) {
+  if (!query) return "";
+  const s = new URLSearchParams(query).toString();
+  return s ? `?${s}` : "";
 }
+
+export default Client;

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "maidan",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Client for Maidan, the operating layer for teams of AI agents",
   "license": "MIT",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
   "files": ["index.js", "index.d.ts", "README.md"],
-  "keywords": ["maidan", "agents", "mcp"],
-  "repository": {"type": "git", "url": "https://github.com/david-engelmann/maidan"},
-  "homepage": "https://maidan.world"
+  "keywords": ["maidan", "agents", "ai-agents", "mcp", "a2a"],
+  "repository": {"type": "git", "url": "git+https://github.com/david-engelmann/maidan.git"},
+  "homepage": "https://david-engelmann.github.io/maidan/",
+  "engines": {"node": ">=18"},
+  "scripts": {"test": "node --test"}
 }