modulex-js 0.1.0 → 1.0.0

package/dist/index.js

@@ -63,6 +63,12 @@ var ModulexError = class extends Error {
     this.body = body;
     this.headers = headers;
     this.name = "ModulexError";
+    const env = extractErrorEnvelope(body);
+    if (env) {
+      if (typeof env.code === "string") this.code = env.code;
+      if (typeof env.reason === "string") this.reason = env.reason;
+      if (typeof env.layer === "string") this.layer = env.layer;
+    }
   }
 };
 var BadRequestError = class extends ModulexError {
@@ -105,10 +111,18 @@ var RateLimitError = class extends ModulexError {
   constructor(message, body, headers) {
     super(message, 429, body, headers);
     this.name = "RateLimitError";
-    const retryHeader = headers?.get("retry-after");
-    this.retryAfter = retryHeader ? Number(retryHeader) : void 0;
+    this.retryAfter = parseNumericHeader(headers, "retry-after");
+    this.limit = parseNumericHeader(headers, "x-ratelimit-limit");
+    this.remaining = parseNumericHeader(headers, "x-ratelimit-remaining");
+    this.reset = parseNumericHeader(headers, "x-ratelimit-reset");
   }
 };
+function parseNumericHeader(headers, name) {
+  const raw = headers?.get(name);
+  if (raw == null) return void 0;
+  const n = Number(raw);
+  return Number.isNaN(n) ? void 0 : n;
+}
 var InternalError = class extends ModulexError {
   constructor(message, body, headers) {
     super(message, 500, body, headers);
@@ -166,18 +180,43 @@ function createErrorFromStatus(status, body, headers) {
       return new ModulexError(message, status, body, headers);
   }
 }
+function extractErrorEnvelope(body) {
+  if (!body || typeof body !== "object") return void 0;
+  const b = body;
+  const detail = b.detail;
+  if (detail && typeof detail === "object" && !Array.isArray(detail)) {
+    return detail;
+  }
+  if (typeof b.code === "string" || typeof b.reason === "string") {
+    return b;
+  }
+  return void 0;
+}
 function extractErrorMessage(body, status) {
-  if (body && typeof body === "object" && "detail" in body) {
-    const detail = body.detail;
+  if (body && typeof body === "object") {
+    const b = body;
+    const detail = b.detail;
     if (typeof detail === "string") return detail;
     if (Array.isArray(detail)) {
       return detail.map((d) => `${d.loc?.join(".")}: ${d.msg}`).join("; ");
     }
+    const env = extractErrorEnvelope(body);
+    if (env) {
+      const reason = env.reason ?? env.message;
+      const code = env.code;
+      if (typeof reason === "string" && typeof code === "string") return `${reason} (${code})`;
+      if (typeof reason === "string") return reason;
+      if (typeof code === "string") return code;
+    }
+    if (typeof b.message === "string") return b.message;
   }
   return `HTTP ${status} error`;
 }
 
 // src/streaming.ts
+function resolveEventType(event, data) {
+  return typeof data.type === "string" && data.type ? data.type : event;
+}
 async function* parseSSEStream(response, signal) {
   const body = response.body;
   if (!body) {
@@ -210,8 +249,10 @@ async function* parseSSEStream(response, signal) {
             } catch {
               parsedData = { raw: dataStr };
             }
+            const ev = currentEvent || "message";
             yield {
-              event: currentEvent || "message",
+              event: ev,
+              type: resolveEventType(ev, parsedData),
               data: parsedData,
               id: currentId,
               retry: currentRetry
@@ -263,8 +304,10 @@ async function* parseSSEStream(response, signal) {
       } catch {
         parsedData = { raw: dataStr };
       }
+      const ev = currentEvent || "message";
       yield {
-        event: currentEvent || "message",
+        event: ev,
+        type: resolveEventType(ev, parsedData),
         data: parsedData,
         id: currentId,
         retry: currentRetry
@@ -605,7 +648,8 @@ var Auth = class extends BaseResource {
   /**
    * POST /auth/invitations/{id}/accept
    *
-   * Accepts a pending organization invitation.
+   * Accepts a pending organization invitation. On success the response
+   * includes the joined organization and the granted role.
    */
   async acceptInvitation(invitationId, options) {
     return this._post(
@@ -699,7 +743,9 @@ var Organizations = class extends BaseResource {
   /**
    * POST /organizations/invite
    *
-   * Sends an invitation email to add a user to the current organization.
+   * Sends an invitation email to add a user to the current organization. The
+   * invited user joins as `admin`; the org `member` role was retired, so the
+   * backend rejects `role: 'member'` with HTTP 422.
    */
   async invite(params, options) {
     return this._post("/organizations/invite", params, options);
@@ -731,7 +777,9 @@ var Organizations = class extends BaseResource {
   /**
    * PUT /organizations/{orgId}/users/{userId}/role
    *
-   * Updates a member's role within an organization.
+   * Updates a member's role within an organization. Only `'admin'` is accepted —
+   * the org `member` role was retired, so the backend rejects `role: 'member'`
+   * with HTTP 422.
    */
   async updateRole(organizationId, userId, params, options) {
     return this._put(
@@ -752,6 +800,67 @@ var Organizations = class extends BaseResource {
       options
     );
   }
+  /**
+   * POST /organizations/invite/preview
+   *
+   * Previews the prorated cost of adding one seat to the current organization,
+   * for displaying to the user before confirming an invite. The organization is
+   * resolved from the `X-Organization-ID` header, so no request body is sent.
+   *
+   * Returns a discriminated union on `preview_available`: when `false`, the
+   * organization has no active paid subscription (a `reason` is provided); when
+   * `true`, full prorated pricing detail is returned.
+   *
+   * @remarks Admin-only: requires organization admin (or owner) permission.
+   */
+  async invitePreview(options) {
+    return this._post("/organizations/invite/preview", void 0, options);
+  }
+  /**
+   * GET /organizations/settings
+   *
+   * Returns the per-organization preference settings (model visibility and the
+   * default composer LLM) for the current organization. The organization is
+   * resolved from the `X-Organization-ID` header.
+   *
+   * @remarks Available to any organization member.
+   */
+  async getSettings(options) {
+    return this._get("/organizations/settings", options);
+  }
+  /**
+   * PUT /organizations/settings/llm-model-visibility
+   *
+   * Sets which models are visible in the dropdown for a single integration.
+   * Send the FULL desired visible list; an empty `models` array resets that
+   * integration's visibility to the catalog default. The organization is
+   * resolved from the `X-Organization-ID` header.
+   *
+   * @remarks Admin-only: requires organization admin (or owner) permission.
+   */
+  async setModelVisibility(params, options) {
+    return this._put(
+      "/organizations/settings/llm-model-visibility",
+      params,
+      options
+    );
+  }
+  /**
+   * PUT /organizations/settings/composer-llm
+   *
+   * Persists the organization's default composer LLM. Composer requests that
+   * omit an explicit LLM fall back to this value. The organization is resolved
+   * from the `X-Organization-ID` header.
+   *
+   * @remarks Admin-only: requires organization admin (or owner) permission.
+   */
+  async setComposerLlm(params, options) {
+    return this._put(
+      "/organizations/settings/composer-llm",
+      params,
+      options
+    );
+  }
 };
 
 // src/resources/workflows.ts
@@ -759,7 +868,13 @@ var Workflows = class extends BaseResource {
   /**
    * POST /workflows
    *
-   * Creates a new workflow with the given schema.
+   * Creates a new workflow with the given schema. Returns HTTP 201.
+   * Requires organization admin/owner role.
+   *
+   * `params.visibility` is passed through unchanged with no client-side default;
+   * omit it to let the backend default to `"organization"`. `"private"` is no
+   * longer creator-only — it behaves like `"organization"` (any org admin/owner
+   * can view/run/resume).
    */
   async create(params, options) {
     return this._post("/workflows", params, options);
@@ -816,6 +931,7 @@ var Workflows = class extends BaseResource {
    * PUT /workflows/{workflowId}
    *
    * Updates an existing workflow. Only provided fields are changed.
+   * Requires organization admin/owner role.
    */
   async update(workflowId, params, options) {
     return this._put(`/workflows/${workflowId}`, params, options);
@@ -823,7 +939,9 @@ var Workflows = class extends BaseResource {
   /**
    * DELETE /workflows/{workflowId}
    *
-   * Soft-deletes a workflow.
+   * Permanently (hard) deletes a workflow. This is IRREVERSIBLE — the workflow
+   * row and its schema are removed from the database, not soft-deleted.
+   * Requires organization admin/owner role.
    */
   async delete(workflowId, options) {
     return this._delete(
@@ -849,6 +967,19 @@ var Workflows = class extends BaseResource {
       }
     });
   }
+  /**
+   * GET /workflows/{workflowId}/changes — SSE stream
+   *
+   * Opens a Server-Sent Events stream of real-time collaboration changes for a
+   * workflow (canvas/composer sync). This is a data-only stream: each yielded
+   * value is a {@link WorkflowChangeEvent} discriminated on its `type` field
+   * (`connected`, `workflow_updated`, `user_joined`, `user_left`).
+   */
+  async *listenChanges(workflowId, options) {
+    for await (const frame of this.streamSSE(`/workflows/${workflowId}/changes`, options)) {
+      yield frame.data;
+    }
+  }
 };
 
 // src/resources/executions.ts
@@ -856,9 +987,14 @@ var Executions = class extends BaseResource {
   /**
    * POST /workflows/run
    *
-   * Initiates a workflow run. Supports four modes: existing workflow, ad-hoc
-   * workflow, direct LLM call, and system workflow. Returns immediately with
-   * run metadata; stream events via `listen()`.
+   * Initiates a workflow run. Supports two modes: a saved workflow (`workflowId`,
+   * which requires an active deployment — the backend returns 400 otherwise) or
+   * an inline ad-hoc definition (`workflow`). Returns immediately with run
+   * metadata (`status` is `"running"` for streaming runs); stream events via
+   * `listen()`.
+   *
+   * The legacy direct-LLM mode was removed; an `llm_config`-only request now
+   * returns HTTP 410 — use `client.assistant.chat()` instead.
    */
   async run(params, options) {
     return this._post("/workflows/run", params, options);
@@ -868,6 +1004,10 @@ var Executions = class extends BaseResource {
    *
    * Returns the persisted state snapshot of a workflow thread at its latest
    * checkpoint.
+   *
+   * Throws `NotFoundError` on HTTP 404 — the thread does not exist OR is not
+   * owned by your organization. Ownership failures return an identical 404 (not
+   * 403) by design, so there is no existence leak.
    */
   async getState(threadId, options) {
     return this._get(`/workflows/state/${threadId}`, options);
@@ -876,6 +1016,11 @@ var Executions = class extends BaseResource {
    * POST /workflows/resume/{threadId}
    *
    * Resumes a workflow that is waiting at an interrupt node.
+   *
+   * Guard responses: 400 (missing `resumeValue` or `runId`); 404 — a
+   * `NotFoundError` — when there is no checkpoint for the thread OR the
+   * run/thread is not owned by your organization. Ownership failures return an
+   * identical 404 (not 403) by design, so there is no existence leak.
    */
   async resume(params, options) {
     const { threadId, ...rest } = params;
@@ -888,7 +1033,13 @@ var Executions = class extends BaseResource {
   /**
    * POST /workflows/cancel/{runId}
    *
-   * Requests cancellation of an in-progress workflow run.
+   * Requests cancellation of an in-progress workflow run. On success the
+   * response `status` is `"cancellation_requested"`.
+   *
+   * Guard responses: 404 — a `NotFoundError` — when the run is unknown OR is not
+   * owned by your organization (ownership failures return an identical 404, not
+   * 403, by design, so there is no existence leak); 400 (the run is not in a
+   * `running`/`interrupted` state).
    */
   async cancel(runId, params, options) {
     return this._post(
@@ -900,14 +1051,53 @@ var Executions = class extends BaseResource {
   /**
    * GET /workflows/listen/{runId} — SSE stream
    *
-   * Opens a Server-Sent Events stream for real-time execution events of
-   * an in-progress workflow run. Yields typed `WorkflowSSEEvent` values.
+   * Opens a Server-Sent Events stream for real-time execution events of an
+   * in-progress workflow run. This is a data-only stream: each yielded value is
+   * a {@link WorkflowSSEEvent} discriminated on its `type` field (`metadata`,
+   * `node_started`, `node_update`, `interrupt`, `resumed`, `done`, `cancelled`,
+   * `error`). The stream ends after a `done` or `error` event.
+   *
+   * A 404 on connect throws `NotFoundError` before any event is yielded — the
+   * run does not exist OR is not owned by your organization (ownership failures
+   * return an identical 404, not 403). The stream does NOT auto-reconnect on a
+   * 404.
    */
-  listen(runId, options) {
-    return this.streamSSE(
-      `/workflows/listen/${runId}`,
-      options
-    );
+  async *listen(runId, options) {
+    for await (const frame of this.streamSSE(`/workflows/listen/${runId}`, options)) {
+      yield frame.data;
+    }
+  }
+};
+
+// src/resources/workflow-runs.ts
+var WorkflowRuns = class extends BaseResource {
+  /**
+   * GET /workflow-runs
+   *
+   * Lists workflow runs for the organization, newest first. Pass `workflowId`
+   * for per-workflow history. Pagination is via `has_more` (no total count).
+   */
+  async list(params, options) {
+    return this._get("/workflow-runs", {
+      ...options,
+      params: {
+        ...params,
+        ...options?.params
+      }
+    });
+  }
+  /**
+   * GET /workflow-runs/{runPk}
+   *
+   * Returns the full durable run record (including input/output snapshots).
+   *
+   * NOTE: `runPk` is the run table primary key (the `id` field of a
+   * {@link WorkflowRunListItem} / {@link WorkflowRunDetail}), NOT the string
+   * `run_id` used by `executions.listen()` / `executions.cancel()`. Passing a
+   * `run_id` here returns 404.
+   */
+  async get(runPk, options) {
+    return this._get(`/workflow-runs/${runPk}`, options);
   }
 };
 
@@ -1077,7 +1267,8 @@ var Credentials = class extends BaseResource {
   /**
    * GET /credentials/{credentialId}
    *
-   * Returns a single credential record.
+   * Returns a single credential record, including ownership and (optionally
+   * masked) auth detail fields not present on the list endpoint.
    */
   async get(credentialId, params, options) {
     return this._get(`/credentials/${credentialId}`, {
@@ -1092,6 +1283,8 @@ var Credentials = class extends BaseResource {
    * POST /credentials
    *
    * Creates a new credential. The auth data is encrypted at rest.
+   *
+   * @remarks Requires admin/owner role on the organization.
    */
   async create(params, options) {
     return this._post("/credentials", params, options);
@@ -1153,6 +1346,8 @@ var Credentials = class extends BaseResource {
    * GET /credentials/{credentialId}/usage
    *
    * Returns usage statistics for a credential.
+   *
+   * @remarks Requires admin/owner role on the organization.
    */
   async usage(credentialId, params, options) {
     return this._get(`/credentials/${credentialId}/usage`, {
@@ -1167,7 +1362,9 @@ var Credentials = class extends BaseResource {
   /**
    * GET /credentials/{credentialId}/audit
    *
-   * Returns the audit log for a credential.
+   * Returns the audit log for a credential as an array of entries.
+   *
+   * @remarks Requires admin/owner role on the organization.
    */
   async audit(credentialId, params, options) {
     return this._get(`/credentials/${credentialId}/audit`, {
@@ -1182,7 +1379,10 @@ var Credentials = class extends BaseResource {
   /**
    * POST /credentials/bulk-modulex-keys/stream — SSE
    *
-   * Streams bulk ModuleX managed key provisioning events.
+   * Streams bulk ModuleX managed key provisioning events. Each event's
+   * `data` field can be parsed as a {@link ModulexKeyBulkEventData}.
+   *
+   * @remarks Requires admin/owner role on the organization.
    */
   bulkModulexKeys(options) {
     return this.streamSSEPost("/credentials/bulk-modulex-keys/stream", void 0, options);
@@ -1193,7 +1393,11 @@ var Credentials = class extends BaseResource {
    * Creates a credential for a Model Context Protocol (MCP) server.
    */
   async mcpServer(params, options) {
-    return this._post("/credentials/mcp-server", params, options);
+    return this._post(
+      "/credentials/mcp-server",
+      params,
+      options
+    );
   }
   /**
    * POST /credentials/{credentialId}/refresh-discovery
@@ -1218,6 +1422,37 @@ var Credentials = class extends BaseResource {
       options
     );
   }
+  /**
+   * POST /credentials/oauth2/initiate
+   *
+   * Initiates an OAuth2 authorization flow for an integration and returns the
+   * authorization URL the user should be redirected to, along with a `state`
+   * token correlating the flow.
+   *
+   * @remarks Requires admin/owner role on the organization.
+   */
+  async initiateOAuth2(params, options) {
+    return this._post(
+      "/credentials/oauth2/initiate",
+      params,
+      options
+    );
+  }
+  /**
+   * POST /credentials/{credentialId}/oauth2/refresh
+   *
+   * Manually refreshes the access token of an existing OAuth2 credential and
+   * returns the updated credential record.
+   *
+   * @remarks Requires admin/owner role on the organization.
+   */
+  async refreshOAuth2(credentialId, options) {
+    return this._post(
+      `/credentials/${credentialId}/oauth2/refresh`,
+      void 0,
+      options
+    );
+  }
 };
 
 // src/resources/integrations.ts
@@ -1261,7 +1496,7 @@ var Integrations = class extends BaseResource {
    */
   async tool(integrationName, options) {
     return this._get(
-      `/integrations/tools/${integrationName}`,
+      `/integrations/tools/${encodeURIComponent(integrationName)}`,
       options
     );
   }
@@ -1283,7 +1518,7 @@ var Integrations = class extends BaseResource {
    */
   async llmProvider(providerName, options) {
     return this._get(
-      `/integrations/llm-providers/${providerName}`,
+      `/integrations/llm-providers/${encodeURIComponent(providerName)}`,
       options
     );
   }
@@ -1305,7 +1540,7 @@ var Integrations = class extends BaseResource {
    */
   async knowledgeProvider(providerName, options) {
     return this._get(
-      `/integrations/knowledge-providers/${providerName}`,
+      `/integrations/knowledge-providers/${encodeURIComponent(providerName)}`,
       options
     );
   }
@@ -1316,7 +1551,7 @@ var Integrations = class extends BaseResource {
    */
   async get(integrationName, options) {
     return this._get(
-      `/integrations/${integrationName}`,
+      `/integrations/${encodeURIComponent(integrationName)}`,
       options
     );
   }
@@ -1328,6 +1563,9 @@ var Knowledge = class extends BaseResource {
    * GET /knowledge-bases
    *
    * Lists knowledge bases for the current organization.
+   *
+   * The backend returns a bare JSON array (no pagination envelope); the
+   * `limit`/`offset`/`status` query params control which records are returned.
    */
   async list(params, options) {
     return this._get("/knowledge-bases", {
@@ -1344,6 +1582,8 @@ var Knowledge = class extends BaseResource {
    * POST /knowledge-bases
    *
    * Creates a new knowledge base.
+   *
+   * Requires an organization admin or owner role; non-admin keys receive 403.
    */
   async create(params, options) {
     return this._post("/knowledge-bases", params, options);
@@ -1371,6 +1611,8 @@ var Knowledge = class extends BaseResource {
    * PUT /knowledge-bases/{kbId}
    *
    * Updates a knowledge base's name, description, or configuration.
+   *
+   * Requires an organization admin or owner role; non-admin keys receive 403.
    */
   async update(knowledgeBaseId, params, options) {
     return this._put(
@@ -1384,6 +1626,8 @@ var Knowledge = class extends BaseResource {
    *
    * Deletes a knowledge base. Pass `deleteFiles: true` to also remove
    * the underlying stored files.
+   *
+   * Requires an organization admin or owner role; non-admin keys receive 403.
    */
   async delete(knowledgeBaseId, params, options) {
     return this._delete(
@@ -1402,6 +1646,9 @@ var Knowledge = class extends BaseResource {
    * POST /knowledge-bases/{kbId}/archive
    *
    * Archives a knowledge base, pausing ingestion without deleting data.
+   * Returns the updated knowledge base record.
+   *
+   * Requires an organization admin or owner role; non-admin keys receive 403.
    */
   async archive(knowledgeBaseId, options) {
     return this._post(
@@ -1414,6 +1661,9 @@ var Knowledge = class extends BaseResource {
    * GET /knowledge-bases/{kbId}/documents
    *
    * Returns documents within a knowledge base.
+   *
+   * The backend returns a bare JSON array; the `limit`/`offset`/`status`
+   * query params control which records are returned.
    */
   async documents(knowledgeBaseId, params, options) {
     return this._get(
@@ -1434,6 +1684,8 @@ var Knowledge = class extends BaseResource {
    *
    * Uploads a document file to a knowledge base for ingestion.
    * Builds a `FormData` with the file and optional metadata JSON.
+   *
+   * Requires an organization admin or owner role; non-admin keys receive 403.
    */
   async uploadDocument(knowledgeBaseId, params, options) {
     const formData = new FormData();
@@ -1461,7 +1713,8 @@ var Knowledge = class extends BaseResource {
   /**
    * GET /knowledge-bases/{kbId}/documents/{docId}/status
    *
-   * Returns the processing status and progress of a document.
+   * Returns the processing status of a document. Some fields are conditional
+   * on the document's `status` value.
    */
   async documentStatus(knowledgeBaseId, documentId, options) {
     return this._get(
@@ -1474,6 +1727,8 @@ var Knowledge = class extends BaseResource {
    *
    * Deletes a document and its chunks from the knowledge base.
    * Pass `deleteFile: true` to also remove the source file from storage.
+   *
+   * Requires an organization admin or owner role; non-admin keys receive 403.
    */
   async deleteDocument(knowledgeBaseId, documentId, params, options) {
     return this._delete(
@@ -1491,7 +1746,9 @@ var Knowledge = class extends BaseResource {
   /**
    * POST /knowledge-bases/{kbId}/documents/{docId}/retry
    *
-   * Retries ingestion of a failed document.
+   * Retries ingestion of a failed document. Returns the updated document record.
+   *
+   * Requires an organization admin or owner role; non-admin keys receive 403.
    */
   async retryDocument(knowledgeBaseId, documentId, options) {
     return this._post(
@@ -1635,6 +1892,7 @@ var Schedules = class extends BaseResource {
    * POST /schedules/{scheduleId}/pause
    *
    * Pauses a schedule, preventing future runs until resumed.
+   * Returns the updated schedule.
    */
   async pause(scheduleId, options) {
     return this._post(
@@ -1646,7 +1904,7 @@ var Schedules = class extends BaseResource {
   /**
    * POST /schedules/{scheduleId}/resume
    *
-   * Resumes a paused schedule.
+   * Resumes a paused schedule. Returns the updated schedule.
    */
   async resume(scheduleId, options) {
     return this._post(
@@ -1713,204 +1971,293 @@ var Schedules = class extends BaseResource {
   }
 };
 
-// src/resources/templates.ts
-var Templates = class extends BaseResource {
+// src/resources/composer.ts
+var Composer = class extends BaseResource {
   /**
-   * GET /templates
+   * POST /composer/chat
    *
-   * Returns the public template library.
+   * Starts a new Composer chat or sends a message to an existing session.
+   * Returns a run ID that can be used to listen to the SSE stream.
+   *
+   * Errors: 409 if the chat has a pending HITL question (answer it via
+   * `resume()` first); 402/403/429 for billing/limit gates.
    */
-  async list(options) {
-    return this._get("/templates", options);
+  async chat(params, options) {
+    return this._post("/composer/chat", params, options);
   }
   /**
-   * GET /templates/{templateId}
+   * GET /composer/chats
    *
-   * Returns a single template including its full workflow schema.
+   * Lists the current user's Composer chats, newest first, with cursor
+   * pagination (`next_cursor` is an ISO `updated_at` timestamp).
    */
-  async get(templateId, options) {
-    return this._get(`/templates/${templateId}`, options);
+  async list(params, options) {
+    return this._get("/composer/chats", {
+      ...options,
+      params: {
+        ...options?.params,
+        limit: params?.limit,
+        cursor: params?.cursor
+      }
+    });
   }
   /**
-   * GET /templates/me
+   * GET /composer/chat/{composerChatId}
    *
-   * Returns templates created by the authenticated user.
+   * Returns a Composer chat session with its messages, touched workflows, and
+   * any open HITL question (`pending_user_input_request`).
    */
-  async mine(options) {
-    return this._get("/templates/me", options);
+  async get(composerChatId, options) {
+    return this._get(
+      `/composer/chat/${composerChatId}`,
+      options
+    );
   }
   /**
-   * POST /templates
+   * GET /composer/chat/{composerChatId}/listen/{runId} — SSE
+   *
+   * Opens a Server-Sent Events stream for real-time Composer output. This is a
+   * data-only stream: each yielded value is a {@link ComposerSSEEvent}
+   * discriminated on `type`. A `user_input_request` frame signals a HITL pause —
+   * answer it with `resume()`.
    *
-   * Publishes a workflow as a new template.
+   * A 404 on connect throws `NotFoundError` before any event is yielded — the
+   * chat/run does not exist OR is not owned by your organization (ownership
+   * failures return an identical 404, not 403). The stream does NOT
+   * auto-reconnect on a 404.
    */
-  async create(params, options) {
-    return this._post("/templates", params, options);
+  async *listen(composerChatId, runId, options) {
+    for await (const frame of this.streamSSE(
+      `/composer/chat/${composerChatId}/listen/${runId}`,
+      options
+    )) {
+      yield frame.data;
+    }
   }
   /**
-   * POST /templates/{templateId}/like
+   * POST /composer/chat/{composerChatId}/resume
+   *
+   * Answers an open HITL question and resumes the paused run. Returns a NEW
+   * `run_id` to listen on.
    *
-   * Toggles the authenticated user's like on a template.
+   * Errors: 404 (a `NotFoundError`) when the chat does not exist OR is not owned
+   * by your organization (ownership failures return an identical 404, not 403);
+   * 410 if the `requestId` is not pending or already consumed; 403 if the caller
+   * is not the user who triggered the question. The `llm` config is required in
+   * production (the backend returns 400 if omitted).
    */
-  async like(templateId, options) {
+  async resume(composerChatId, params, options) {
     return this._post(
-      `/templates/${templateId}/like`,
-      void 0,
+      `/composer/chat/${composerChatId}/resume`,
+      params,
       options
     );
   }
   /**
-   * POST /templates/{templateId}/use
+   * PATCH /composer/chat/{composerChatId}/focus
    *
-   * Imports a template as a new workflow in the current organization.
+   * Sets (or clears, with `workflowId: null`) the chat's focused workflow.
    */
-  async use(templateId, options) {
-    return this._post(
-      `/templates/${templateId}/use`,
-      void 0,
+  async focus(composerChatId, params, options) {
+    return this._patch(
+      `/composer/chat/${composerChatId}/focus`,
+      params,
       options
     );
   }
   /**
-   * POST /templates/{templateId}/update-request
+   * POST /composer/chat/{composerChatId}/save
    *
-   * Submits an update request for a published template.
+   * Saves the Composer's pending workflow changes. Without `workflowId` it
+   * targets the chat's focused workflow (400 if there is none). Returns a
+   * `workflow_sync` payload for refreshing the canvas.
    */
-  async updateRequest(templateId, params, options) {
+  async save(composerChatId, params, options) {
     return this._post(
-      `/templates/${templateId}/update-request`,
+      `/composer/chat/${composerChatId}/save`,
       params,
       options
     );
   }
   /**
-   * POST /templates/creators
+   * POST /composer/chat/{composerChatId}/revert
    *
-   * Creates or updates the authenticated user's template creator profile.
+   * Reverts pending changes to the last snapshot. Without `workflowId` it
+   * targets the focused workflow (400 if there is none, or if no snapshot
+   * exists). Returns a `workflow_sync` payload.
    */
-  async createCreator(params, options) {
-    return this._post("/templates/creators", params, options);
+  async revert(composerChatId, params, options) {
+    return this._post(
+      `/composer/chat/${composerChatId}/revert`,
+      params,
+      options
+    );
   }
   /**
-   * GET /templates/creators/me
+   * DELETE /composer/chat/{composerChatId}
    *
-   * Returns the authenticated user's template creator profile.
+   * Deletes a Composer chat session. Pass `permanent: true` for a hard delete
+   * (default is a soft delete). `permanent` is sent as a query parameter.
    */
-  async getCreator(options) {
-    return this._get("/templates/creators/me", options);
+  async delete(composerChatId, params, options) {
+    return this._delete(
+      `/composer/chat/${composerChatId}`,
+      void 0,
+      {
+        ...options,
+        params: { ...options?.params, permanent: params?.permanent }
+      }
+    );
   }
-};
-
-// src/resources/composer.ts
-var Composer = class extends BaseResource {
   /**
-   * POST /composer/chat
+   * GET /composer/chat/{composerChatId}/status
    *
-   * Starts a new Composer chat or sends a message to an existing session.
-   * Returns a run ID that can be used to listen to the SSE stream.
+   * Returns the real-time status of a Composer chat session, including HITL
+   * pause state (`awaiting_input` / `pending_request_id`).
    */
-  async chat(params, options) {
-    return this._post("/composer/chat", params, options);
+  async status(composerChatId, options) {
+    return this._get(
+      `/composer/chat/${composerChatId}/status`,
+      options
+    );
   }
   /**
-   * GET /composer/chat/{composerChatId}
+   * POST /composer/chat/{composerChatId}/cancel
    *
-   * Returns a Composer chat session with its messages and workflow snapshot status.
+   * Cancels the in-progress run for a Composer chat session.
+   *
+   * Throws `NotFoundError` on HTTP 404 — the chat does not exist OR is not owned
+   * by your organization (ownership failures return an identical 404, not 403,
+   * so there is no existence leak).
    */
-  async get(composerChatId, options) {
-    return this._get(
-      `/composer/chat/${composerChatId}`,
+  async cancel(composerChatId, options) {
+    return this._post(
+      `/composer/chat/${composerChatId}/cancel`,
+      void 0,
       options
     );
   }
+};
+
+// src/resources/assistant.ts
+var Assistant = class extends BaseResource {
   /**
-   * GET /composer/chat/{composerChatId}/listen/{runId} — SSE
+   * POST /assistant/chat
+   *
+   * Starts a new Assistant chat or sends a message to an existing one. Returns
+   * a run ID to listen on.
    *
-   * Opens a Server-Sent Events stream for real-time Composer output during a run.
+   * Errors: 409 if the chat has a pending HITL question or a run is already in
+   * progress (answer via `resume()` / `cancel()` first); 402/403/429 at the
+   * billing gate.
    */
-  listen(composerChatId, runId, options) {
-    return this.streamSSE(
-      `/composer/chat/${composerChatId}/listen/${runId}`,
-      options
-    );
+  async chat(params, options) {
+    return this._post("/assistant/chat", params, options);
   }
   /**
-   * POST /composer/chat/{composerChatId}/save
+   * GET /assistant/chats
    *
-   * Saves the Composer's current workflow changes to the associated workflow.
+   * Lists the current user's Assistant chats, newest first, with cursor
+   * pagination (`next_cursor` is an ISO `updated_at` timestamp).
    */
-  async save(composerChatId, options) {
-    return this._post(
-      `/composer/chat/${composerChatId}/save`,
-      void 0,
-      options
-    );
+  async list(params, options) {
+    return this._get("/assistant/chats", {
+      ...options,
+      params: {
+        ...options?.params,
+        limit: params?.limit,
+        cursor: params?.cursor
+      }
+    });
   }
   /**
-   * POST /composer/chat/{composerChatId}/revert
+   * GET /assistant/chat/{chatId}
    *
-   * Reverts the Composer's pending changes, restoring the last saved state.
+   * Returns an Assistant chat with its messages and any open HITL question
+   * (`pending_user_input_request`).
    */
-  async revert(composerChatId, options) {
-    return this._post(
-      `/composer/chat/${composerChatId}/revert`,
-      void 0,
-      options
-    );
+  async get(chatId, options) {
+    return this._get(`/assistant/chat/${chatId}`, options);
   }
   /**
-   * GET /composer/chat/workflow/{workflowId}/history
+   * GET /assistant/chat/{chatId}/listen/{runId} — SSE
+   *
+   * Opens a Server-Sent Events stream for real-time Assistant output. This is a
+   * data-only stream: each yielded value is an {@link AssistantSSEEvent}
+   * discriminated on `type`. A `user_input_request` frame signals a HITL pause —
+   * answer it with `resume()`.
    *
-   * Returns the Composer chat history associated with a workflow.
+   * A 404 on connect throws `NotFoundError` before any event is yielded — the
+   * chat/run does not exist OR is not owned by your organization (ownership
+   * failures return an identical 404, not 403). The stream does NOT
+   * auto-reconnect on a 404.
    */
-  async history(workflowId, params, options) {
-    return this._get(
-      `/composer/chat/workflow/${workflowId}/history`,
-      {
-        ...options,
-        params: {
-          ...options?.params,
-          limit: params?.limit
-        }
-      }
-    );
+  async *listen(chatId, runId, options) {
+    for await (const frame of this.streamSSE(
+      `/assistant/chat/${chatId}/listen/${runId}`,
+      options
+    )) {
+      yield frame.data;
+    }
   }
   /**
-   * DELETE /composer/chat/{composerChatId}
+   * POST /assistant/chat/{chatId}/resume
+   *
+   * Answers an open HITL question and resumes the paused run. Returns a NEW
+   * `run_id` to listen on.
    *
-   * Deletes a Composer chat session. Pass `permanent: true` to also delete
-   * the associated workflow.
+   * Errors: 404 (a `NotFoundError`) when the chat is not found OR is not owned by
+   * your organization (ownership failures return an identical 404, not 403); 410
+   * if the question was already answered or cancelled; 403 if the caller is not
+   * the user who triggered it. `llm` is required (400 if omitted).
    */
-  async delete(composerChatId, params, options) {
-    return this._delete(
-      `/composer/chat/${composerChatId}`,
+  async resume(chatId, params, options) {
+    return this._post(
+      `/assistant/chat/${chatId}/resume`,
       params,
       options
     );
   }
   /**
-   * GET /composer/chat/{composerChatId}/status
+   * GET /assistant/chat/{chatId}/status
    *
-   * Returns the real-time status of a Composer chat session.
+   * Returns real-time status including HITL pause state (`awaiting_input` /
+   * `pending_request_id`).
    */
-  async status(composerChatId, options) {
-    return this._get(
-      `/composer/chat/${composerChatId}/status`,
-      options
-    );
+  async status(chatId, options) {
+    return this._get(`/assistant/chat/${chatId}/status`, options);
   }
   /**
-   * POST /composer/chat/{composerChatId}/cancel
+   * POST /assistant/chat/{chatId}/cancel
    *
-   * Cancels the in-progress run for a Composer chat session.
+   * Cancels the in-progress run and clears any pending HITL question. The
+   * returned `run_id` is the run that was cancelled. Errors: 404 (a
+   * `NotFoundError`) when the chat is not found OR is not owned by your
+   * organization (ownership failures return an identical 404, not 403); 400 if
+   * there is no active execution.
    */
-  async cancel(composerChatId, options) {
+  async cancel(chatId, options) {
     return this._post(
-      `/composer/chat/${composerChatId}/cancel`,
+      `/assistant/chat/${chatId}/cancel`,
       void 0,
       options
     );
   }
+  /**
+   * DELETE /assistant/chat/{chatId}
+   *
+   * Deletes an Assistant chat. Pass `permanent: true` for a hard delete
+   * (default is a soft delete).
+   */
+  async delete(chatId, params, options) {
+    return this._delete(`/assistant/chat/${chatId}`, void 0, {
+      ...options,
+      params: {
+        ...options?.params,
+        permanent: params?.permanent
+      }
+    });
+  }
 };
 
 // src/resources/dashboard.ts
@@ -2002,54 +2349,6 @@ var Dashboard = class extends BaseResource {
   }
 };
 
-// src/resources/subscriptions.ts
-var Subscriptions = class extends BaseResource {
-  /**
-   * GET /subscriptions/organization-plans
-   *
-   * Returns the list of available organization subscription plans.
-   */
-  async organizationPlans(options) {
-    return this._get(
-      "/subscriptions/organization-plans",
-      options
-    );
-  }
-  /**
-   * GET /subscriptions/organization-billing
-   *
-   * Returns the current organization's billing status and active subscription.
-   */
-  async billing(options) {
-    return this._get("/subscriptions/organization-billing", options);
-  }
-  /**
-   * POST /subscriptions/checkout-link
-   *
-   * Creates a Stripe Checkout session and returns the redirect URL.
-   */
-  async checkoutLink(params, options) {
-    return this._post(
-      "/subscriptions/checkout-link",
-      params,
-      options
-    );
-  }
-  /**
-   * POST /subscriptions/customer-portal
-   *
-   * Creates a Stripe Customer Portal session and returns the redirect URL
-   * for the user to manage their billing.
-   */
-  async customerPortal(options) {
-    return this._post(
-      "/subscriptions/customer-portal",
-      void 0,
-      options
-    );
-  }
-};
-
 // src/resources/notifications.ts
 var Notifications = class extends BaseResource {
   /**
@@ -2064,6 +2363,14 @@ var Notifications = class extends BaseResource {
    * POST /notifications/organization
    *
    * Creates a new notification for the organization or a specific user.
+   *
+   * Requires an organization context: an `X-Organization-ID` header is sent
+   * automatically from the client's configured `organizationId` or from
+   * `options.organizationId`. If neither is set, no header is sent and the
+   * backend responds with HTTP 400 ("X-Organization-ID header is required").
+   *
+   * @returns The created notification wrapped in a `{ success, notification }`
+   *   envelope.
    */
   async create(params, options) {
     return this._post(
@@ -2076,44 +2383,10 @@ var Notifications = class extends BaseResource {
 
 // src/resources/system.ts
 var System = class extends BaseResource {
-  /**
-   * GET /system/health
-   *
-   * Returns the service health status, name, and version.
-   */
-  async health(options) {
-    return this._get(
-      "/system/health",
-      options
-    );
-  }
-  /**
-   * GET /system/metrics
-   *
-   * Returns Prometheus-format metrics as plain text.
-   * This endpoint bypasses the JSON-parsing logic of `BaseResource.get()` and
-   * reads the raw response body as a string.
-   */
-  async metrics(options) {
-    const orgId = options?.organizationId ?? this._config.organizationId;
-    const url = `${this._config.baseUrl}/system/metrics`;
-    const headers = {
-      "Authorization": `Bearer ${this._config.apiKey}`
-    };
-    if (orgId) {
-      headers["X-Organization-ID"] = orgId;
-    }
-    const response = await this._config.fetch(url, {
-      method: "GET",
-      headers,
-      signal: options?.signal
-    });
-    return response.text();
-  }
   /**
    * GET /system/timezones
    *
-   * Returns the list of supported IANA timezone identifiers.
+   * Returns popular timezone groups plus the full list of IANA identifiers.
    */
   async timezones(options) {
     return this._get("/system/timezones", options);
@@ -2121,7 +2394,8 @@ var System = class extends BaseResource {
   /**
    * GET /system/timezones/search
    *
-   * Searches supported IANA timezone identifiers by query string.
+   * Searches supported IANA timezones by query string. `query` must be at least
+   * 2 characters (the backend returns 422 otherwise). Returns at most 20 results.
    */
   async searchTimezones(query, options) {
     return this._get("/system/timezones/search", {
@@ -2152,10 +2426,14 @@ var Modulex = class {
   get workflows() {
     return this._workflows ?? (this._workflows = new Workflows(this._config));
   }
-  /** Workflow execution endpoints (run, resume, cancel, listen). */
+  /** Workflow execution-control endpoints (run, resume, cancel, listen). */
   get executions() {
     return this._executions ?? (this._executions = new Executions(this._config));
   }
+  /** Durable workflow run-history endpoints (list, get persisted runs). */
+  get workflowRuns() {
+    return this._workflowRuns ?? (this._workflowRuns = new WorkflowRuns(this._config));
+  }
   /** Workflow deployment endpoints. */
   get deployments() {
     return this._deployments ?? (this._deployments = new Deployments(this._config));
@@ -2180,22 +2458,18 @@ var Modulex = class {
   get schedules() {
     return this._schedules ?? (this._schedules = new Schedules(this._config));
   }
-  /** Template endpoints. */
-  get templates() {
-    return this._templates ?? (this._templates = new Templates(this._config));
-  }
   /** Composer (AI workflow builder) endpoints. */
   get composer() {
     return this._composer ?? (this._composer = new Composer(this._config));
   }
+  /** Assistant (HITL chat agent) endpoints. */
+  get assistant() {
+    return this._assistant ?? (this._assistant = new Assistant(this._config));
+  }
   /** Dashboard and analytics endpoints. */
   get dashboard() {
     return this._dashboard ?? (this._dashboard = new Dashboard(this._config));
   }
-  /** Subscription and billing endpoints. */
-  get subscriptions() {
-    return this._subscriptions ?? (this._subscriptions = new Subscriptions(this._config));
-  }
   /** Notification endpoints. */
   get notifications() {
     return this._notifications ?? (this._notifications = new Notifications(this._config));