@mantyx/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,608 @@
+// src/errors.ts
+var MantyxError = class extends Error {
+  code;
+  status;
+  hint;
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "MantyxError";
+    this.code = opts.code ?? "mantyx_error";
+    this.status = opts.status;
+    this.hint = opts.hint;
+  }
+};
+var MantyxNetworkError = class extends MantyxError {
+  constructor(message, opts = {}) {
+    super(message, { code: "network" });
+    this.name = "MantyxNetworkError";
+    if (opts.cause !== void 0) {
+      this.cause = opts.cause;
+    }
+  }
+};
+var MantyxAuthError = class extends MantyxError {
+  constructor(message = "Invalid or missing API key") {
+    super(message, { code: "unauthorized", status: 401 });
+    this.name = "MantyxAuthError";
+  }
+};
+var MantyxToolError = class extends MantyxError {
+  toolName;
+  constructor(toolName, message) {
+    super(`Local tool ${JSON.stringify(toolName)} failed: ${message}`, {
+      code: "local_tool_failed"
+    });
+    this.name = "MantyxToolError";
+    this.toolName = toolName;
+  }
+};
+var MantyxRunError = class extends MantyxError {
+  runId;
+  subtype;
+  constructor(runId, subtype, message) {
+    super(message, { code: subtype });
+    this.name = "MantyxRunError";
+    this.runId = runId;
+    this.subtype = subtype;
+  }
+};
+
+// src/sse.ts
+async function* readSseStream(body, opts = {}) {
+  if (!body) return;
+  const reader = body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let buffer = "";
+  let cancelled = false;
+  const onAbort = () => {
+    cancelled = true;
+    try {
+      void reader.cancel();
+    } catch {
+    }
+  };
+  if (opts.signal) {
+    if (opts.signal.aborted) {
+      onAbort();
+    } else {
+      opts.signal.addEventListener("abort", onAbort, { once: true });
+    }
+  }
+  try {
+    while (!cancelled) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let sepIdx;
+      while ((sepIdx = findSeparator(buffer)) !== -1) {
+        const raw = buffer.slice(0, sepIdx);
+        buffer = buffer.slice(sepIdx + (buffer.startsWith("\r", sepIdx) ? 4 : 2));
+        const ev = parseEventBlock(raw);
+        if (ev) yield ev;
+      }
+    }
+  } finally {
+    if (opts.signal) opts.signal.removeEventListener("abort", onAbort);
+    try {
+      reader.releaseLock();
+    } catch {
+    }
+  }
+}
+function findSeparator(s) {
+  const lf = s.indexOf("\n\n");
+  const crlf = s.indexOf("\r\n\r\n");
+  if (lf === -1) return crlf;
+  if (crlf === -1) return lf;
+  return Math.min(lf, crlf);
+}
+function parseEventBlock(block) {
+  const lines = block.split(/\r?\n/);
+  let id;
+  let event;
+  const dataLines = [];
+  for (const line of lines) {
+    if (line.length === 0) continue;
+    if (line.startsWith(":")) continue;
+    const colonIdx = line.indexOf(":");
+    const field = colonIdx === -1 ? line : line.slice(0, colonIdx);
+    let value = colonIdx === -1 ? "" : line.slice(colonIdx + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "id") id = value;
+    else if (field === "event") event = value;
+    else if (field === "data") dataLines.push(value);
+  }
+  if (dataLines.length === 0 && id === void 0 && event === void 0) {
+    return null;
+  }
+  return {
+    ...id !== void 0 ? { id } : {},
+    ...event !== void 0 ? { event } : {},
+    data: dataLines.join("\n")
+  };
+}
+
+// src/tools.ts
+function defineLocalTool(opts) {
+  if (!/^[a-zA-Z0-9_]{1,64}$/.test(opts.name)) {
+    throw new Error(
+      `Invalid local tool name ${JSON.stringify(opts.name)}: must match /^[a-zA-Z0-9_]{1,64}$/`
+    );
+  }
+  return {
+    kind: "local",
+    name: opts.name,
+    description: opts.description ?? "",
+    parameters: opts.parameters,
+    execute: opts.execute
+  };
+}
+function mantyxTool(id) {
+  if (typeof id !== "string" || id.length === 0) {
+    throw new Error("mantyxTool(id): id must be a non-empty string");
+  }
+  return { kind: "mantyx", id };
+}
+function mantyxPluginTool(name) {
+  if (typeof name !== "string" || !name.startsWith("@") || !name.includes("/")) {
+    throw new Error(
+      `mantyxPluginTool(name): expected "@plugin-slug/tool-name", got ${JSON.stringify(name)}`
+    );
+  }
+  return { kind: "mantyx_plugin", name };
+}
+function isLocalTool(t) {
+  return t.kind === "local";
+}
+
+// src/zod-to-json-schema.ts
+import { z } from "zod";
+function zodToJsonSchema(schema) {
+  const builtIn = z.toJSONSchema;
+  if (typeof builtIn === "function") {
+    try {
+      const out = builtIn.call(z, schema);
+      if (out && typeof out === "object") return out;
+    } catch {
+    }
+  }
+  return convertNode(schema);
+}
+function convertNode(schema) {
+  const def = schema._def;
+  const typeName = def?.typeName;
+  switch (typeName) {
+    case "ZodString":
+      return { type: "string" };
+    case "ZodNumber":
+      return { type: "number" };
+    case "ZodBoolean":
+      return { type: "boolean" };
+    case "ZodNull":
+      return { type: "null" };
+    case "ZodLiteral": {
+      const value = def.value;
+      return { const: value, type: typeof value };
+    }
+    case "ZodEnum": {
+      const values = def.values ?? [];
+      return { type: "string", enum: [...values] };
+    }
+    case "ZodArray": {
+      const inner = def.type;
+      return {
+        type: "array",
+        items: inner ? convertNode(inner) : {}
+      };
+    }
+    case "ZodOptional":
+    case "ZodNullable": {
+      const inner = def.innerType;
+      return inner ? convertNode(inner) : {};
+    }
+    case "ZodDefault": {
+      const inner = def.innerType;
+      return inner ? convertNode(inner) : {};
+    }
+    case "ZodObject": {
+      const shape = def.shape;
+      const fields = typeof shape === "function" ? shape() : shape;
+      const properties = {};
+      const required = [];
+      if (fields) {
+        for (const [key, value] of Object.entries(fields)) {
+          properties[key] = convertNode(value);
+          const innerDef = value._def;
+          const innerTypeName = innerDef?.typeName;
+          if (innerTypeName !== "ZodOptional" && innerTypeName !== "ZodDefault") {
+            required.push(key);
+          }
+        }
+      }
+      const out = { type: "object", properties };
+      if (required.length > 0) out.required = required;
+      return out;
+    }
+    default:
+      return {};
+  }
+}
+function toToolParametersWire(parameters) {
+  if (!parameters) return { type: "object", properties: {} };
+  if (typeof parameters._def !== "undefined") {
+    return zodToJsonSchema(parameters);
+  }
+  return parameters;
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.mantyx.com";
+var MantyxClient = class {
+  options;
+  constructor(opts) {
+    if (!opts.apiKey || typeof opts.apiKey !== "string") {
+      throw new MantyxError("apiKey is required");
+    }
+    if (!opts.workspaceSlug || typeof opts.workspaceSlug !== "string") {
+      throw new MantyxError("workspaceSlug is required");
+    }
+    const f = opts.fetch ?? globalThis.fetch;
+    if (typeof f !== "function") {
+      throw new MantyxError(
+        "Global fetch is not available; pass a custom `fetch` implementation in MantyxClientOptions."
+      );
+    }
+    this.options = {
+      apiKey: opts.apiKey,
+      workspaceSlug: opts.workspaceSlug,
+      baseUrl: (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
+      fetch: f,
+      timeoutMs: opts.timeoutMs ?? 6e4
+    };
+  }
+  // -------------------------------------------------------------- Models
+  async listModels() {
+    return this.request({
+      method: "GET",
+      path: "/models"
+    });
+  }
+  // ------------------------------------------------------------- One-shot
+  async runAgent(spec) {
+    const handlers = collectLocalHandlers(spec.tools ?? []);
+    const created = await this.request({
+      method: "POST",
+      path: "/agent-runs",
+      body: serializeAgentSpec(spec, {
+        prompt: spec.prompt,
+        messages: spec.messages
+      })
+    });
+    return this.driveRun(created.runId, handlers, {
+      ...spec.onAssistantDelta ? { onAssistantDelta: spec.onAssistantDelta } : {},
+      ...spec.onEvent ? { onEvent: spec.onEvent } : {},
+      ...spec.signal ? { signal: spec.signal } : {}
+    });
+  }
+  async *streamAgent(spec) {
+    const handlers = collectLocalHandlers(spec.tools ?? []);
+    const created = await this.request({
+      method: "POST",
+      path: "/agent-runs",
+      body: serializeAgentSpec(spec, {
+        prompt: spec.prompt,
+        messages: spec.messages
+      })
+    });
+    yield* this.streamRunEvents(created.runId, handlers, spec.signal);
+  }
+  // ------------------------------------------------------------- Sessions
+  async createSession(spec) {
+    const handlers = collectLocalHandlers(spec.tools ?? []);
+    const created = await this.request({
+      method: "POST",
+      path: "/agent-sessions",
+      body: serializeAgentSpec(spec)
+    });
+    return new AgentSession(this, created.sessionId, handlers);
+  }
+  async resumeSession(sessionId, opts = {}) {
+    await this.getSessionInfo(sessionId);
+    const handlers = collectLocalHandlers(opts.tools ?? []);
+    return new AgentSession(this, sessionId, handlers, opts.tools);
+  }
+  async endSession(sessionId) {
+    await this.request({
+      method: "DELETE",
+      path: `/agent-sessions/${encodeURIComponent(sessionId)}`
+    });
+  }
+  async getSessionInfo(sessionId) {
+    return this.request({
+      method: "GET",
+      path: `/agent-sessions/${encodeURIComponent(sessionId)}`
+    });
+  }
+  // ----------------------------------------------------------- Internals
+  /** Drive an existing run to completion (collect events, dispatch local tools). */
+  async driveRun(runId, handlers, opts = {}) {
+    const collected = [];
+    let finalText = "";
+    for await (const ev of this.streamRunEvents(runId, handlers, opts.signal)) {
+      collected.push(ev);
+      if (opts.onEvent) opts.onEvent(ev);
+      if (ev.type === "assistant_delta" && opts.onAssistantDelta) {
+        opts.onAssistantDelta(ev.text);
+      }
+      if (ev.type === "result") {
+        const r = ev;
+        if (r.subtype === "success") {
+          finalText = typeof r.text === "string" ? r.text : "";
+        } else {
+          throw new MantyxRunError(runId, r.subtype, r.error ?? r.subtype);
+        }
+      } else if (ev.type === "error") {
+        const e = ev;
+        throw new MantyxRunError(runId, e.code ?? "error", e.error);
+      } else if (ev.type === "cancelled") {
+        throw new MantyxRunError(runId, "cancelled", "Run was cancelled");
+      }
+    }
+    return { runId, text: finalText, events: collected };
+  }
+  async *streamRunEvents(runId, handlers, signal) {
+    const url = this.absoluteUrl(`/agent-runs/${encodeURIComponent(runId)}/stream`);
+    let lastSeq = 0;
+    while (true) {
+      const reqUrl = lastSeq > 0 ? `${url}?lastSeq=${lastSeq}` : url;
+      const res = await this.options.fetch(reqUrl, {
+        method: "GET",
+        headers: {
+          ...this.authHeaders(),
+          Accept: "text/event-stream",
+          ...lastSeq > 0 ? { "Last-Event-ID": String(lastSeq) } : {}
+        },
+        ...signal ? { signal } : {}
+      }).catch((err) => {
+        throw new MantyxNetworkError(`Failed to open SSE stream: ${err.message}`, {
+          cause: err
+        });
+      });
+      if (!res.ok) {
+        throw await this.errorFromResponse(res);
+      }
+      let terminal = false;
+      try {
+        for await (const sseEvent of readSseStream(res.body, { ...signal ? { signal } : {} })) {
+          let data = {};
+          try {
+            data = JSON.parse(sseEvent.data || "{}");
+          } catch {
+            data = {};
+          }
+          const evType = sseEvent.event ?? data.type ?? "message";
+          const seq = typeof data.seq === "number" ? data.seq : lastSeq;
+          if (typeof seq === "number" && seq > lastSeq) lastSeq = seq;
+          const ev = { seq, type: evType, ...data };
+          yield ev;
+          if (evType === "local_tool_call") {
+            const localEv = ev;
+            void this.dispatchLocalTool(runId, localEv, handlers).catch((err) => {
+              console.error("[mantyx-sdk] local tool dispatch failed:", err);
+            });
+          }
+          if (evType === "result" || evType === "error" || evType === "cancelled") {
+            terminal = true;
+            return;
+          }
+        }
+      } catch (err) {
+        if (signal?.aborted) {
+          throw new MantyxRunError(runId, "cancelled", "Run was cancelled by the client");
+        }
+        await sleep(500);
+        continue;
+      }
+      if (terminal) return;
+    }
+  }
+  async dispatchLocalTool(runId, ev, handlers) {
+    const handler = handlers.get(ev.name);
+    if (!handler) {
+      await this.postToolResult(runId, ev.toolUseId, {
+        error: `No local handler registered for tool ${JSON.stringify(ev.name)}`
+      });
+      return;
+    }
+    try {
+      const args = handler.parameters ? handler.parameters.parse?.(ev.args) ?? ev.args : ev.args;
+      const out = await handler.execute(args);
+      const resultText = typeof out === "string" ? out : JSON.stringify(out);
+      await this.postToolResult(runId, ev.toolUseId, { result: resultText });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      await this.postToolResult(runId, ev.toolUseId, {
+        error: new MantyxToolError(handler.name, message).message
+      });
+    }
+  }
+  async postToolResult(runId, toolUseId, payload) {
+    await this.request({
+      method: "POST",
+      path: `/agent-runs/${encodeURIComponent(runId)}/tool-results`,
+      body: { toolUseId, ...payload }
+    });
+  }
+  async cancelRun(runId) {
+    await this.request({
+      method: "POST",
+      path: `/agent-runs/${encodeURIComponent(runId)}/cancel`
+    });
+  }
+  // -------------------------------------------------------------- HTTP
+  absoluteUrl(path) {
+    return `${this.options.baseUrl}/api/v1/workspaces/${encodeURIComponent(this.options.workspaceSlug)}${path}`;
+  }
+  authHeaders() {
+    return { Authorization: `Bearer ${this.options.apiKey}` };
+  }
+  async request(args) {
+    const url = this.absoluteUrl(args.path);
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), args.timeoutMs ?? this.options.timeoutMs);
+    try {
+      const res = await this.options.fetch(url, {
+        method: args.method,
+        headers: {
+          ...this.authHeaders(),
+          ...args.body !== void 0 ? { "Content-Type": "application/json" } : {},
+          Accept: "application/json"
+        },
+        ...args.body !== void 0 ? { body: JSON.stringify(args.body) } : {},
+        signal: ctrl.signal
+      }).catch((err) => {
+        if (ctrl.signal.aborted) {
+          throw new MantyxNetworkError(`Request timed out after ${args.timeoutMs ?? this.options.timeoutMs}ms`);
+        }
+        throw new MantyxNetworkError(`Network error: ${err.message}`, { cause: err });
+      });
+      if (!res.ok) {
+        throw await this.errorFromResponse(res);
+      }
+      const text = await res.text();
+      if (!text) return void 0;
+      try {
+        return JSON.parse(text);
+      } catch (err) {
+        throw new MantyxError(`Failed to parse JSON response: ${err.message}`);
+      }
+    } finally {
+      clearTimeout(t);
+    }
+  }
+  async errorFromResponse(res) {
+    let body = {};
+    try {
+      body = await res.json();
+    } catch {
+    }
+    if (res.status === 401) {
+      return new MantyxAuthError(body.error ?? "Invalid API key");
+    }
+    return new MantyxError(body.error ?? `HTTP ${res.status}`, {
+      code: body.code ?? `http_${res.status}`,
+      status: res.status,
+      ...body.hint ? { hint: body.hint } : {}
+    });
+  }
+};
+var AgentSession = class {
+  id;
+  client;
+  handlers;
+  toolsForResume;
+  constructor(client, id, handlers, toolsForResume) {
+    this.client = client;
+    this.id = id;
+    this.handlers = handlers;
+    this.toolsForResume = toolsForResume;
+  }
+  async send(prompt, opts = {}) {
+    const created = await this.client.request({
+      method: "POST",
+      path: `/agent-sessions/${encodeURIComponent(this.id)}/messages`,
+      body: {
+        prompt,
+        ...this.toolsForResume ? { tools: serializeToolRefs(this.toolsForResume) } : {},
+        ...opts.metadata && Object.keys(opts.metadata).length > 0 ? { metadata: opts.metadata } : {}
+      }
+    });
+    return this.client.driveRun(created.runId, this.handlers, {
+      ...opts.onAssistantDelta ? { onAssistantDelta: opts.onAssistantDelta } : {},
+      ...opts.signal ? { signal: opts.signal } : {}
+    });
+  }
+  async *stream(prompt, opts = {}) {
+    const created = await this.client.request({
+      method: "POST",
+      path: `/agent-sessions/${encodeURIComponent(this.id)}/messages`,
+      body: {
+        prompt,
+        ...this.toolsForResume ? { tools: serializeToolRefs(this.toolsForResume) } : {},
+        ...opts.metadata && Object.keys(opts.metadata).length > 0 ? { metadata: opts.metadata } : {}
+      }
+    });
+    yield* this.client.streamRunEvents(created.runId, this.handlers, opts.signal);
+  }
+  async history() {
+    const info = await this.client.getSessionInfo(this.id);
+    return info.messages;
+  }
+  async info() {
+    return this.client.getSessionInfo(this.id);
+  }
+  async end() {
+    await this.client.endSession(this.id);
+  }
+};
+function serializeAgentSpec(spec, extra = {}) {
+  if (!spec.agentId && (typeof spec.systemPrompt !== "string" || spec.systemPrompt.length === 0)) {
+    throw new MantyxError("Either `agentId` or `systemPrompt` is required");
+  }
+  const body = {
+    tools: serializeToolRefs(spec.tools ?? [])
+  };
+  if (typeof spec.systemPrompt === "string") body.systemPrompt = spec.systemPrompt;
+  if (spec.agentId) body.agentId = spec.agentId;
+  if (spec.name) body.name = spec.name;
+  if (spec.modelId) body.modelId = spec.modelId;
+  if (spec.budgets) body.budgets = spec.budgets;
+  if (spec.metadata && Object.keys(spec.metadata).length > 0) body.metadata = spec.metadata;
+  if (extra.prompt !== void 0) body.prompt = extra.prompt;
+  if (extra.messages !== void 0) body.messages = extra.messages;
+  return body;
+}
+function serializeToolRefs(tools) {
+  return tools.map((t) => {
+    if (t.kind === "mantyx") return { kind: "mantyx", id: t.id };
+    if (t.kind === "mantyx_plugin") return { kind: "mantyx_plugin", name: t.name };
+    return {
+      kind: "local",
+      name: t.name,
+      description: t.description,
+      parameters: toToolParametersWire(t.parameters)
+    };
+  });
+}
+function collectLocalHandlers(tools) {
+  const map = /* @__PURE__ */ new Map();
+  for (const t of tools) {
+    if (isLocalTool(t)) map.set(t.name, t);
+  }
+  return map;
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// src/version.ts
+var SDK_VERSION = "0.1.0";
+export {
+  AgentSession,
+  DEFAULT_BASE_URL,
+  MantyxAuthError,
+  MantyxClient,
+  MantyxError,
+  MantyxNetworkError,
+  MantyxRunError,
+  MantyxToolError,
+  SDK_VERSION,
+  defineLocalTool,
+  isLocalTool,
+  mantyxPluginTool,
+  mantyxTool,
+  readSseStream,
+  toToolParametersWire,
+  zodToJsonSchema
+};
+//# sourceMappingURL=index.js.map