@miragon/bpmn-iq-daemon-client

Typed HTTP SDK for the BPMN IQ daemon. Wraps fetch + an EventSource-style SSE reader. Used by:

• apps/agent — push/pull workspace models, hydrate, listen for SSE
• packages/workspace-mcp, packages/engine-mcp — backing client for the MCP plugins so MCP tools never touch in-process daemon state
• 3rd-party consumers who want to read or write daemon state from their own tooling (CI, editor plugins, dashboards)

Pure TypeScript, no runtime deps beyond the platform fetch. Carries types from @miragon/bpmn-iq-types and @miragon/bpmn-iq-analyzer.

Public API

import {
  DaemonClient,
  DaemonError,
  resolveDaemonUrl,
  DEFAULT_DAEMON_URL,
} from "@miragon/bpmn-iq-daemon-client";

const url = resolveDaemonUrl(process.env.BPMN_IQ_DAEMON);  // → string
const client = new DaemonClient(url, wsId);

await client.registerWorkspace({
  name: "my-project",
  repoId,           // optional: deterministic id from git remote
  repoSlug,         // optional: "Org/Repo" for display
  branch,           // optional: current git branch
});
await client.upsertModel("flows/order.bpmn", xml);
const { models } = await client.listWorkspaceModels(wsId);
const peers = await client.listWorkspacesForRepo(repoId);
await client.streamEvents(handler, abortSignal);

DaemonClient methods

| Method | Endpoint | | -------------------------------------------------------------- | ---------------------------------------------- | | registerWorkspace({ name, repoId?, repoSlug?, branch? }) | POST /api/workspaces | | heartbeat() | POST /api/workspaces/:wsId/heartbeat | | unregisterWorkspace() | DELETE /api/workspaces/:wsId | | upsertModel(relPath, xml) | POST /api/workspaces/:wsId/models | | removeModel(relPath) | DELETE /api/workspaces/:wsId/models?relPath= | | getModel(modelId) | GET /api/models/:id | | listModels() | GET /api/models | | listWorkspaceModels(wsId) | GET /api/workspaces/:wsId/models | | listWorkspacesForRepo(repoId) | GET /api/workspaces?repoId= | | streamEvents(onEvent, signal) | GET /api/events?ws= (SSE) |

heartbeat() returns false (rather than throwing) when the workspace has been swept — callers can re-register on demand.

resolveDaemonUrl(flag)

Resolution order: --daemon flag value → BPMN_IQ_DAEMON env → http://localhost:4000. Trailing slash is stripped.

Errors

DaemonError carries the HTTP status so callers can branch on 404, 409, etc. without parsing message strings.

Build

pnpm --filter @miragon/bpmn-iq-daemon-client build      # tsc → dist/
pnpm --filter @miragon/bpmn-iq-daemon-client typecheck

ES modules only ("type": "module"). Single export entry: dist/index.js.