@verentis/sdk 0.2.6 → 1.0.1

package/dist/index.js

@@ -259,6 +259,7 @@ var ContextModule = class {
 };
 
 // src/modules/executions.ts
+var SCRIPT_ARGUMENTS_SCHEMA = "verentis.io/script-arguments/v1";
 var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
   "Completed",
   "Failed",
@@ -289,7 +290,8 @@ var ExecutionsModule = class {
         tool: options?.tool,
         mode: options?.mode,
         arguments: options?.arguments ?? [],
-        parameters: serializeParameters(options?.parameters)
+        parameters: serializeParameters(options?.parameters),
+        ...options?.invocationKey ? { invocationKey: options.invocationKey } : {}
       }),
       headers: { "Content-Type": "application/json" }
     });
@@ -314,10 +316,30 @@ var ExecutionsModule = class {
       headers: { "Content-Type": "application/json" }
     });
   }
+  /**
+   * Read the arguments a script declares (its exported `<script>.arguments.json`), e.g. to build a form
+   * before {@link run}. Returns `null` for scripts that declare none. Reading never runs the script.
+   */
+  async getArguments(filePath, options) {
+    const path = `${filePath}.arguments.json`.replace(/\/+/g, "/").replace(/^\//, "");
+    const response = await this.http.requestRaw("GET", `/files/raw/${path}`, {
+      params: { branch: options?.branch ?? "main" },
+      headers: { ...this.workspaceId ? { "X-Workspace-Id": this.workspaceId } : {}, Accept: "application/json" }
+    });
+    if (response.status === 404) return null;
+    if (!response.ok) {
+      throw new Error(`Failed to read script arguments: ${response.status} ${response.statusText}`);
+    }
+    const descriptor = await response.json();
+    if (descriptor?.schema !== SCRIPT_ARGUMENTS_SCHEMA || !Array.isArray(descriptor.arguments)) {
+      throw new Error(`Unsupported script argument descriptor for ${filePath}`);
+    }
+    return descriptor;
+  }
   /** Get an execution by id. */
-  async get(id, options) {
+  async get(id2, options) {
     const workspaceId = this.requireWorkspaceId(options?.workspaceId);
-    return this.http.request("GET", `/executions/${encodeURIComponent(id)}`, {
+    return this.http.request("GET", `/executions/${encodeURIComponent(id2)}`, {
       params: { workspaceId }
     });
   }
@@ -342,17 +364,17 @@ var ExecutionsModule = class {
     });
   }
   /** Get the captured stdout/stderr of an execution. */
-  async logs(id, options) {
+  async logs(id2, options) {
     const workspaceId = this.requireWorkspaceId(options?.workspaceId);
-    return this.http.request("GET", `/executions/${encodeURIComponent(id)}/logs`, {
+    return this.http.request("GET", `/executions/${encodeURIComponent(id2)}/logs`, {
       params: { workspaceId }
     });
   }
   /** Cancel a pending or running execution. */
-  async cancel(id, options) {
+  async cancel(id2, options) {
     const workspaceId = this.requireWorkspaceId(options?.workspaceId);
-    return this.http.request("POST", `/executions/${encodeURIComponent(id)}/cancel`, {
-      body: JSON.stringify({ id, workspaceId }),
+    return this.http.request("POST", `/executions/${encodeURIComponent(id2)}/cancel`, {
+      body: JSON.stringify({ id: id2, workspaceId }),
       headers: { "Content-Type": "application/json" }
     });
   }
@@ -360,16 +382,16 @@ var ExecutionsModule = class {
    * Poll an execution until it reaches a terminal status. Returns immediately if it is already
    * terminal. Throws if `timeoutMs` elapses or the supplied signal aborts.
    */
-  async wait(id, options) {
+  async wait(id2, options) {
     const interval = options?.intervalMs ?? 1e3;
     const deadline = options?.timeoutMs ? Date.now() + options.timeoutMs : void 0;
     for (; ; ) {
-      const execution = await this.get(id, { workspaceId: options?.workspaceId });
+      const execution = await this.get(id2, { workspaceId: options?.workspaceId });
       if (isTerminalStatus(execution.status)) {
         return execution;
       }
       if (deadline !== void 0 && Date.now() >= deadline) {
-        throw new Error(`Timed out waiting for execution '${id}' to complete`);
+        throw new Error(`Timed out waiting for execution '${id2}' to complete`);
       }
       await delay(interval, options?.signal);
     }
@@ -386,11 +408,11 @@ var ExecutionsModule = class {
     return this.wait(execution.id, options);
   }
   requireWorkspaceId(override) {
-    const id = override ?? this.workspaceId;
-    if (!id) {
+    const id2 = override ?? this.workspaceId;
+    if (!id2) {
       throw new Error("workspaceId is required: provide it in options or when creating the client");
     }
-    return id;
+    return id2;
   }
 };
 function serializeParameters(parameters) {
@@ -431,8 +453,8 @@ var EnginesModule = class {
       }
     });
   }
-  async get(id, options) {
-    return this.http.request("GET", `/engines/${encodeURIComponent(id)}`, {
+  async get(id2, options) {
+    return this.http.request("GET", `/engines/${encodeURIComponent(id2)}`, {
       params: { workspaceId: this.requireWorkspaceId(options?.workspaceId) }
     });
   }
@@ -653,11 +675,11 @@ var FilesModule = class {
     });
   }
   workspaceHeaders() {
-    const headers = {};
+    const headers2 = {};
     if (this.workspaceId) {
-      headers["X-Workspace-Id"] = this.workspaceId;
+      headers2["X-Workspace-Id"] = this.workspaceId;
     }
-    return headers;
+    return headers2;
   }
 };
 function requireNonBlank(value, name) {
@@ -749,14 +771,14 @@ var InstallationsModule = class {
       }
     });
   }
-  async update(id, options) {
+  async update(id2, options) {
     const workspaceId = this.requireWorkspaceId(options?.workspaceId);
     return this.http.request(
       "PUT",
-      `/installations/${encodeURIComponent(id)}`,
+      `/installations/${encodeURIComponent(id2)}`,
       {
         body: JSON.stringify({
-          id,
+          id: id2,
           workspaceId,
           packageVersion: options?.packageVersion,
           installMode: options?.installMode
@@ -765,8 +787,8 @@ var InstallationsModule = class {
       }
     );
   }
-  async uninstall(id, options) {
-    await this.http.request("DELETE", `/installations/${encodeURIComponent(id)}`, {
+  async uninstall(id2, options) {
+    await this.http.request("DELETE", `/installations/${encodeURIComponent(id2)}`, {
       params: { workspaceId: this.requireWorkspaceId(options?.workspaceId) }
     });
   }
@@ -792,10 +814,10 @@ var ResourcesModule = class {
       params: { workspaceId: this.requireWorkspaceId(options?.workspaceId) }
     });
   }
-  async get(id, options) {
+  async get(id2, options) {
     return this.http.request(
       "GET",
-      `/resources/${encodeURIComponent(id)}`,
+      `/resources/${encodeURIComponent(id2)}`,
       { params: { workspaceId: this.requireWorkspaceId(options?.workspaceId) } }
     );
   }
@@ -847,7 +869,7 @@ var SettingsModule = class {
       }
     });
   }
-  /** Upsert a setting value by its full key. Requires the `fabric.setting.update` scope. */
+  /** Upsert a setting value by its full key. Requires the `setting.write` scope. */
   async set(key, value, options) {
     await this.http.request("PUT", `/settings/${encodeURIComponent(key)}`, {
       params: {
@@ -858,7 +880,7 @@ var SettingsModule = class {
       headers: { "Content-Type": "application/json" }
     });
   }
-  /** Delete a stored value (reverting to the definition default). Requires `fabric.setting.delete`. */
+  /** Delete a stored value (reverting to the definition default). Requires `setting.delete`. */
   async reset(key, options) {
     await this.http.request("DELETE", `/settings/${encodeURIComponent(key)}`, {
       params: {
@@ -905,104 +927,78 @@ var SettingsModule = class {
   }
 };
 
-// src/modules/email.ts
-var EmailModule = class {
+// src/types.ts
+var ApiError = class extends Error {
+  constructor(status, detail, title, code, retryAfterMs) {
+    super(title ?? `API error ${status}: ${detail}`);
+    this.status = status;
+    this.detail = detail;
+    this.title = title;
+    this.code = code;
+    this.retryAfterMs = retryAfterMs;
+    this.name = "ApiError";
+  }
+  status;
+  detail;
+  title;
+  code;
+  retryAfterMs;
+};
+
+// src/modules/notifications.ts
+var NotificationsModule = class {
   constructor(http, workspaceId) {
     this.http = http;
     this.workspaceId = workspaceId;
   }
   http;
   workspaceId;
-  async preview(installationId, options) {
-    return this.http.request("GET", `/installations/${encodeURIComponent(installationId)}/email-consent-preview`, {
-      params: { workspaceId: this.workspace(options) }
-    });
-  }
-  async consents(options) {
-    return this.http.request("GET", "/email/consents", { params: { workspaceId: this.workspace(options) } });
-  }
-  /** Approve exactly the reviewed signed candidate; tracking stays off unless explicitly opted in. */
-  async consent(preview, approval, options) {
-    if (approval !== true) throw new Error("Explicit email consent is required");
-    if (!options?.senderGrants?.length) throw new Error("Explicit purpose/sender grants are required");
-    return this.http.request("PUT", `/email/consents/${encodeURIComponent(preview.installationId)}`, {
-      params: { workspaceId: preview.workspaceId },
+  async send(options) {
+    const request = {
       body: JSON.stringify({
-        candidateDigest: preview.candidateDigest,
-        enabled: true,
-        allowOpenTracking: options?.allowOpenTracking ?? false,
-        allowClickTracking: options?.allowClickTracking ?? false,
-        senderGrants: options.senderGrants.map((grant) => ({ purpose: grant.purpose, senderId: grant.senderId }))
-      }),
-      headers: { "Content-Type": "application/json" }
-    });
-  }
-  async revoke(consent, options) {
-    return this.http.request("PUT", `/email/consents/${encodeURIComponent(consent.installationId)}`, {
-      params: { workspaceId: this.workspace(options) },
-      body: JSON.stringify({ candidateDigest: consent.candidateDigest, enabled: false, allowOpenTracking: false, allowClickTracking: false }),
-      headers: { "Content-Type": "application/json" }
-    });
-  }
-  async senders(options) {
-    return this.http.request("GET", "/email/senders", { params: { workspaceId: this.workspace(options) } });
-  }
-  async invoicePdf(recordId, installationId, options) {
-    this.mainBranch(options);
-    return this.http.request("POST", "/email/artifacts/invoice", {
-      body: JSON.stringify({ workspaceId: this.workspace(options), recordId, installationId }),
-      headers: { "Content-Type": "application/json" }
-    });
-  }
-  /** Authenticated immutable bytes; no public URL. The caller owns any local object URL it creates. */
-  async artifactContent(artifactId, options) {
-    this.mainBranch(options);
-    return this.http.request("GET", `/email/artifacts/${encodeURIComponent(artifactId)}/content`, {
-      params: { workspaceId: this.workspace(options), branch: "main" }
-    });
-  }
-  /** A stable key binds this exact request. After a lost response inspect status; never automatically resend. */
-  async dispatch(options) {
-    this.mainBranch(options);
-    return this.http.request("POST", "/email/dispatches", {
-      body: JSON.stringify({
-        workspaceId: this.workspace(options),
+        workspaceId: this.requireWorkspaceId(options.workspaceId),
         installationId: options.installationId,
-        recordId: options.recordId,
-        purpose: options.purpose,
-        templateId: options.templateId,
-        senderId: options.senderId,
-        recipients: options.recipients,
-        artifactIds: options.artifactIds,
+        typeKey: options.typeKey,
         idempotencyKey: options.idempotencyKey,
-        replyTo: options.replyTo
+        userIds: options.userIds,
+        audienceScope: options.audienceScope,
+        emailAddresses: options.emailAddresses,
+        parameters: options.parameters
       }),
       headers: { "Content-Type": "application/json" }
-    });
-  }
-  async outcome(id, options) {
-    this.mainBranch(options);
-    return this.http.request("GET", `/email/dispatches/${encodeURIComponent(id)}`, {
-      params: { workspaceId: this.workspace(options) }
-    });
-  }
-  async history(options) {
-    this.mainBranch(options);
-    return this.http.request("GET", "/email/dispatches", {
-      params: { workspaceId: this.workspace(options), recordId: options?.recordId, installationId: options?.installationId }
-    });
-  }
-  async status(id, options) {
-    return this.outcome(id, options);
+    };
+    const deadline = Date.now() + 1e4;
+    for (; ; ) {
+      try {
+        return await this.http.request("POST", "/notifications/send", request);
+      } catch (error) {
+        if (!(error instanceof ApiError) || error.status !== 409 || error.code !== "execution_not_ready") {
+          throw error;
+        }
+        const delay2 = Math.max(250, error.retryAfterMs ?? 1e3);
+        if (Date.now() + delay2 > deadline) throw error;
+        await new Promise((resolve) => setTimeout(resolve, delay2));
+      }
+    }
   }
-  workspace(options) {
-    const value = options?.workspaceId ?? this.workspaceId;
-    if (!value) throw new Error("A workspace is required for transactional email");
-    return value;
+  async request(id2, options) {
+    return this.http.request(
+      "GET",
+      `/notifications/requests/${encodeURIComponent(id2)}`,
+      {
+        params: {
+          workspaceId: this.requireWorkspaceId(options?.workspaceId),
+          installationId: options?.installationId
+        }
+      }
+    );
   }
-  mainBranch(options) {
-    if (options?.branch !== void 0 && options.branch !== "main")
-      throw new Error("Transactional email currently supports only the main business branch");
+  requireWorkspaceId(override) {
+    const workspaceId = override ?? this.workspaceId;
+    if (!workspaceId) {
+      throw new Error("workspaceId is required: provide it in options or when creating the client");
+    }
+    return workspaceId;
   }
 };
 
@@ -1032,8 +1028,8 @@ var BusinessModule = class _BusinessModule {
       body: JSON.stringify(command)
     });
   }
-  async read(id) {
-    return this.http.request("GET", `/business/records/${encodeURIComponent(id)}`, { headers: this.headers() });
+  async read(id2) {
+    return this.http.request("GET", `/business/records/${encodeURIComponent(id2)}`, { headers: this.headers() });
   }
   async list(kind) {
     return this.http.request("GET", "/business/records", {
@@ -1075,6 +1071,201 @@ var BusinessModule = class _BusinessModule {
   }
 };
 
+// src/modules/chat.ts
+var JSON_HEADERS = { "Content-Type": "application/json" };
+var ChatModule = class {
+  constructor(http, bridge = null, executions) {
+    this.http = http;
+    this.bridge = bridge;
+    this.executions = executions;
+  }
+  http;
+  bridge;
+  executions;
+  // ── Conversations ─────────────────────────────────────────────────
+  listConversations(options) {
+    return this.http.request("GET", "/chat/conversations", { params: page(options) });
+  }
+  createConversation(options) {
+    const { idempotencyKey, ...body } = options;
+    return this.http.request("POST", "/chat/conversations", { body: JSON.stringify(body), headers: headers(idempotencyKey) });
+  }
+  /** Opens (or returns the existing) direct conversation with one participant. */
+  openDirect(participant) {
+    return this.createConversation({ kind: "direct", participants: [participant] });
+  }
+  getConversation(conversationId) {
+    return this.http.request("GET", `/chat/conversations/${id(conversationId)}`);
+  }
+  updateConversation(conversationId, changes) {
+    return this.http.request("PATCH", `/chat/conversations/${id(conversationId)}`, { body: JSON.stringify(changes), headers: JSON_HEADERS });
+  }
+  join(conversationId) {
+    return this.http.request("POST", `/chat/conversations/${id(conversationId)}/join`, { body: "{}", headers: JSON_HEADERS });
+  }
+  listPublicChannels(options) {
+    return this.http.request("GET", "/chat/channels", { params: { ...page(options), query: options?.query } });
+  }
+  // ── Members ───────────────────────────────────────────────────────
+  listMembers(conversationId) {
+    return this.http.request("GET", `/chat/conversations/${id(conversationId)}/members`);
+  }
+  addMembers(conversationId, participants, role) {
+    return this.http.request("POST", `/chat/conversations/${id(conversationId)}/members`, {
+      body: JSON.stringify({ participants, role }),
+      headers: JSON_HEADERS
+    });
+  }
+  /** Removes a member; pass yourself to leave. */
+  async removeMember(conversationId, participant) {
+    await this.http.request("DELETE", `/chat/conversations/${id(conversationId)}/members/${participant.kind}/${id(participant.id)}`);
+  }
+  changeRole(conversationId, participant, role) {
+    return this.http.request("PUT", `/chat/conversations/${id(conversationId)}/members/${participant.kind}/${id(participant.id)}/role`, {
+      body: JSON.stringify({ role }),
+      headers: JSON_HEADERS
+    });
+  }
+  // ── Messages ──────────────────────────────────────────────────────
+  listMessages(conversationId, options) {
+    return this.http.request("GET", `/chat/conversations/${id(conversationId)}/messages`, {
+      params: { before: options?.before, limit: options?.limit }
+    });
+  }
+  getMessage(conversationId, messageId) {
+    return this.http.request("GET", `/chat/conversations/${id(conversationId)}/messages/${id(messageId)}`);
+  }
+  send(conversationId, parts, options) {
+    return this.http.request("POST", `/chat/conversations/${id(conversationId)}/messages`, {
+      body: JSON.stringify({ parts, replyTo: options?.replyTo }),
+      headers: headers(options?.idempotencyKey)
+    });
+  }
+  /** Sends Markdown text (rendered without raw HTML by every reader). */
+  sendText(conversationId, markdown, options) {
+    return this.send(conversationId, [{ type: "text", data: { markdown } }], options);
+  }
+  /** Edits your own message; pass the revision you saw to reject a concurrent edit. */
+  edit(conversationId, messageId, parts, options) {
+    return this.http.request("PATCH", `/chat/conversations/${id(conversationId)}/messages/${id(messageId)}`, {
+      body: JSON.stringify({ parts }),
+      headers: { ...JSON_HEADERS, ...options?.revision ? { "If-Match": `"${options.revision}"` } : {} }
+    });
+  }
+  delete(conversationId, messageId) {
+    return this.http.request("DELETE", `/chat/conversations/${id(conversationId)}/messages/${id(messageId)}`);
+  }
+  /**
+   * Durable changes after a position: `afterSeq` is a snapshot's `highWatermark` (or the last sequence you applied);
+   * `after` is the `next` cursor of a previous page.
+   */
+  events(conversationId, options) {
+    return this.http.request("GET", `/chat/conversations/${id(conversationId)}/events`, {
+      params: { after: options?.after, afterSeq: options?.afterSeq, limit: options?.limit }
+    });
+  }
+  // ── Read state and preferences ────────────────────────────────────
+  /** Marks messages read through a sequence; never moves back and never past what the server has. */
+  markRead(conversationId, readThroughSeq) {
+    return this.http.request("PUT", `/chat/conversations/${id(conversationId)}/read-state`, {
+      body: JSON.stringify({ readThroughSeq }),
+      headers: JSON_HEADERS
+    });
+  }
+  setPreferences(conversationId, preferences) {
+    return this.http.request("PUT", `/chat/conversations/${id(conversationId)}/preferences`, {
+      body: JSON.stringify(preferences),
+      headers: JSON_HEADERS
+    });
+  }
+  // ── People, bots and commands ─────────────────────────────────────
+  /** People in your workspace (name and avatar only). */
+  searchPeople(options) {
+    return this.http.request("GET", "/chat/people", { params: { ...page(options), query: options?.query } });
+  }
+  listBots() {
+    return this.http.request("GET", "/chat/bots");
+  }
+  /** Workspace managers (`chat.manage`) decide whether a bot may message people directly. */
+  updateBotSettings(botId, settings) {
+    return this.http.request("PUT", `/chat/bots/${id(botId)}/settings`, { body: JSON.stringify(settings), headers: JSON_HEADERS });
+  }
+  listCommands() {
+    return this.http.request("GET", "/chat/commands");
+  }
+  /** Validates and records a command invocation, returning the Execution request to run as you. */
+  invokeCommand(conversationId, command, args, options) {
+    return this.http.request("POST", `/chat/conversations/${id(conversationId)}/commands`, {
+      body: JSON.stringify({ command, arguments: args ?? {} }),
+      headers: headers(options?.idempotencyKey)
+    });
+  }
+  /**
+   * Invokes an installed app's command and runs its script with your own authorisation. Retrying with the same
+   * idempotency key reuses the invocation key, so Execution never runs it twice.
+   */
+  async runCommand(conversationId, command, args, options) {
+    if (!this.executions) throw new Error("Running commands needs the executions module.");
+    const invocation = await this.invokeCommand(conversationId, command, args, options);
+    const execution = await this.executions.run(invocation.filePath, {
+      workspaceId: invocation.workspaceId,
+      branch: invocation.branch,
+      parameters: JSON.parse(invocation.parameters),
+      invocationKey: invocation.invocationKey
+    });
+    return { invocation, execution };
+  }
+  /**
+   * Posts as the installed app's bot from a running script. The bot is derived from the script's execution; the
+   * conversation must have added the bot (or, for `userId`, the workspace must allow it to message people).
+   * Retries briefly while Execution's start event is still on its way.
+   */
+  async postAsBot(options) {
+    const { idempotencyKey, ...body } = options;
+    const request = { body: JSON.stringify(body), headers: headers(idempotencyKey ?? globalThis.crypto?.randomUUID?.()) };
+    const deadline = Date.now() + 1e4;
+    for (; ; ) {
+      try {
+        return await this.http.request("POST", "/chat/bot-messages", request);
+      } catch (error) {
+        if (!(error instanceof ApiError) || error.status !== 409 || error.code !== "execution_not_ready") throw error;
+        const delay2 = Math.max(250, error.retryAfterMs ?? 1e3);
+        if (Date.now() + delay2 > deadline) throw error;
+        await new Promise((resolve) => setTimeout(resolve, delay2));
+      }
+    }
+  }
+  // ── Live hints ────────────────────────────────────────────────────
+  /**
+   * Subscribes to live change hints through the host (installed apps only). Returns an unsubscribe function.
+   * Hints carry ids only; duplicates and reordering are normal, and hints are lost while disconnected.
+   */
+  subscribeChanges(handlers) {
+    if (!this.bridge) throw new Error("Live chat hints are only available to apps running inside the workspace.");
+    return this.bridge.subscribeChat(handlers);
+  }
+};
+function id(value) {
+  return encodeURIComponent(value);
+}
+function page(options) {
+  return { cursor: options?.cursor, limit: options?.limit };
+}
+function headers(idempotencyKey) {
+  return idempotencyKey ? { ...JSON_HEADERS, "Idempotency-Key": idempotencyKey } : JSON_HEADERS;
+}
+
+// src/transport/app-commands.ts
+var APP_COMMAND_BATCH_SIZE = 200;
+var APP_COMMANDS_CAPABILITY = "commands";
+var APP_COMMAND_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/#@-]{0,255}$/;
+function isAppCommand(value) {
+  if (!value || typeof value !== "object") return false;
+  const c = value;
+  const optionalText = (key, max) => c[key] === void 0 || typeof c[key] === "string" && c[key].length <= max;
+  return typeof c.id === "string" && APP_COMMAND_ID_PATTERN.test(c.id) && typeof c.label === "string" && c.label.trim().length > 0 && c.label.length <= 200 && optionalText("description", 500) && optionalText("group", 100) && optionalText("disabledReason", 200) && (c.icon === void 0 || typeof c.icon === "string" && /^lucide:[a-z0-9-]{1,64}$/.test(c.icon)) && (c.keywords === void 0 || Array.isArray(c.keywords) && c.keywords.length <= 16 && c.keywords.every((k) => typeof k === "string" && k.length <= 64)) && (c.variant === void 0 || ["default", "outline", "destructive"].includes(String(c.variant))) && ["enabled", "busy"].every((key) => c[key] === void 0 || typeof c[key] === "boolean");
+}
+
 // src/transport/header-actions.ts
 function isHeaderAction(value) {
   if (!value || typeof value !== "object") return false;
@@ -1107,7 +1298,7 @@ function element(value) {
   return record(value) && identifier(value.id) && natural(value.version) && (value.versionNonce === void 0 || natural(value.versionNonce)) && (value.isDeleted === void 0 || typeof value.isDeleted === "boolean");
 }
 function files(value) {
-  return record(value) && Object.keys(value).length <= 1e4 && Object.entries(value).every(([id, file]) => record(file) && identifier(id) && file.id === id && typeof file.dataURL === "string" && file.dataURL.length <= 10 * 1024 * 1024 && typeof file.mimeType === "string" && file.mimeType.length > 0 && file.mimeType.length <= 128 && natural(file.created) && (file.lastRetrieved === void 0 || natural(file.lastRetrieved)));
+  return record(value) && Object.keys(value).length <= 1e4 && Object.entries(value).every(([id2, file]) => record(file) && identifier(id2) && file.id === id2 && typeof file.dataURL === "string" && file.dataURL.length <= 10 * 1024 * 1024 && typeof file.mimeType === "string" && file.mimeType.length > 0 && file.mimeType.length <= 128 && natural(file.created) && (file.lastRetrieved === void 0 || natural(file.lastRetrieved)));
 }
 function isNativeSnapshot(value) {
   if (!record(value) || !natural(value.sequence) || !natural(value.savedSequence) || value.savedSequence > value.sequence || typeof value.revision !== "string" || !value.revision || value.revision.length > 1024 || typeof value.readOnly !== "boolean" || !record(value.scene) || !Array.isArray(value.scene.elements) || value.scene.elements.length > 1e4 || !value.scene.elements.every(element) || !files(value.scene.files) || !record(value.scene.appState) || !Array.isArray(value.participants) || value.participants.length > 20)
@@ -1215,6 +1406,14 @@ var Bridge = class {
   sessionId = null;
   actions = /* @__PURE__ */ new Map();
   requests = /* @__PURE__ */ new Set();
+  commands = /* @__PURE__ */ new Map();
+  commandUpserts = /* @__PURE__ */ new Set();
+  commandRemovals = /* @__PURE__ */ new Set();
+  commandReset = false;
+  commandFlushScheduled = false;
+  commandRequests = /* @__PURE__ */ new Set();
+  _hostCapabilities = [];
+  chatSubscribers = /* @__PURE__ */ new Set();
   hostMessageHandlers = /* @__PURE__ */ new Map();
   hostMessageRequests = /* @__PURE__ */ new Set();
   wopiRequests = /* @__PURE__ */ new Map();
@@ -1243,6 +1442,17 @@ var Bridge = class {
   get hostOrigin() {
     return this._hostOrigin;
   }
+  /** Capabilities the host announced in `verentis:init`. */
+  get hostCapabilities() {
+    return this._hostCapabilities;
+  }
+  /**
+   * Whether the host exports page commands to its command registry. Older hosts ignore registrations;
+   * commands still run locally, they are just not discoverable in the workspace palette.
+   */
+  get supportsCommands() {
+    return this._hostCapabilities.includes(APP_COMMANDS_CAPABILITY);
+  }
   /** Send a message to the host */
   postToHost(message) {
     if (this._destroyed) throw new Error("Bridge has been destroyed.");
@@ -1381,6 +1591,113 @@ var Bridge = class {
       }
     };
   }
+  /**
+   * Export a page command to the workspace command registry while it is active. There is no count limit;
+   * dispose the registration when the control unmounts. May be called before the init handshake.
+   */
+  registerCommand(descriptor, handler) {
+    if (this._destroyed) throw new Error("Bridge has been destroyed.");
+    if (!isAppCommand(descriptor)) throw new Error("Invalid command.");
+    if (this.commands.has(descriptor.id)) throw new Error(`Command '${descriptor.id}' is already registered.`);
+    const command = { descriptor: cloneCommand(descriptor), handler, busy: false };
+    this.commands.set(descriptor.id, command);
+    this.queueCommand(descriptor.id, "upsert");
+    return {
+      update: (next) => {
+        if (this.commands.get(descriptor.id) !== command) throw new Error("Command has been disposed.");
+        if (!isAppCommand(next) || next.id !== descriptor.id) throw new Error("Invalid command update.");
+        if (sameCommand(command.descriptor, next)) return;
+        command.descriptor = cloneCommand(next);
+        this.queueCommand(descriptor.id, "upsert");
+      },
+      dispose: () => {
+        if (this.commands.get(descriptor.id) !== command) return;
+        this.commands.delete(descriptor.id);
+        this.queueCommand(descriptor.id, "remove");
+      }
+    };
+  }
+  queueCommand(id2, change) {
+    if (change === "upsert") {
+      this.commandRemovals.delete(id2);
+      this.commandUpserts.add(id2);
+    } else {
+      this.commandUpserts.delete(id2);
+      this.commandRemovals.add(id2);
+    }
+    this.scheduleCommandFlush();
+  }
+  scheduleCommandFlush() {
+    if (this.commandFlushScheduled) return;
+    this.commandFlushScheduled = true;
+    queueMicrotask(() => {
+      this.commandFlushScheduled = false;
+      this.flushCommands();
+    });
+  }
+  commandSnapshot(id2) {
+    const command = this.commands.get(id2);
+    if (!command) return null;
+    return command.busy ? { ...command.descriptor, busy: true } : command.descriptor;
+  }
+  flushCommands() {
+    if (!this.sessionId || !this._hostOrigin || this._destroyed) return;
+    const upsert = [...this.commandUpserts].map((id2) => this.commandSnapshot(id2)).filter((c) => !!c);
+    const remove = this.commandReset ? [] : [...this.commandRemovals];
+    let reset = this.commandReset;
+    this.commandUpserts.clear();
+    this.commandRemovals.clear();
+    this.commandReset = false;
+    if (!reset && !upsert.length && !remove.length) return;
+    let offset = 0;
+    let removeOffset = 0;
+    do {
+      const batchUpsert = upsert.slice(offset, offset + APP_COMMAND_BATCH_SIZE);
+      offset += batchUpsert.length;
+      const room = APP_COMMAND_BATCH_SIZE - batchUpsert.length;
+      const batchRemove = remove.slice(removeOffset, removeOffset + room);
+      removeOffset += batchRemove.length;
+      this.postToHost({
+        type: "verentis:commands:update",
+        version: 1,
+        sessionId: this.sessionId,
+        ...reset ? { reset: true } : {},
+        upsert: batchUpsert,
+        remove: batchRemove
+      });
+      reset = false;
+    } while (offset < upsert.length || removeOffset < remove.length);
+  }
+  async invokeCommand(message) {
+    if (message.sessionId !== this.sessionId || typeof message.requestId !== "string" || message.requestId.length > 128 || !message.requestId || this.commandRequests.has(message.requestId) || typeof message.commandId !== "string") return;
+    this.commandRequests.add(message.requestId);
+    if (this.commandRequests.size > 1e3) this.commandRequests.delete(this.commandRequests.values().next().value);
+    const command = this.commands.get(message.commandId);
+    const reply = {
+      type: "verentis:command:result",
+      version: 1,
+      sessionId: message.sessionId,
+      requestId: message.requestId,
+      commandId: message.commandId
+    };
+    if (!command || command.busy || command.descriptor.busy || command.descriptor.enabled === false) {
+      this.postToHost({ ...reply, error: "Command is unavailable." });
+      return;
+    }
+    command.busy = true;
+    this.queueCommand(message.commandId, "upsert");
+    try {
+      await command.handler();
+      if (!this._destroyed && this.sessionId === message.sessionId) this.postToHost(reply);
+    } catch (error) {
+      if (!this._destroyed && this.sessionId === message.sessionId) {
+        this.postToHost({ ...reply, error: (error instanceof Error ? error.message : "Command failed.").slice(0, 500) || "Command failed." });
+      }
+    } finally {
+      command.busy = false;
+      if (this.commands.get(message.commandId) === command) this.queueCommand(message.commandId, "upsert");
+    }
+  }
   publishActions() {
     if (!this.sessionId || this._destroyed) return;
     this.postToHost({
@@ -1465,6 +1782,41 @@ var Bridge = class {
       this.postToHost({ ...reply, error: "The reply could not be sent to the workspace." });
     }
   }
+  /**
+   * Subscribes to the host's chat live hints (see `ChatModule.subscribeChanges`). The first subscriber asks the host
+   * to relay; the last one to leave stops it. Messages from another session are ignored.
+   */
+  subscribeChat(handlers) {
+    if (this._destroyed) throw new Error("Bridge has been destroyed.");
+    this.chatSubscribers.add(handlers);
+    const subscribe = () => {
+      if (this.sessionId && this._hostOrigin && this.chatSubscribers.size > 0)
+        this.postToHost({ type: "verentis:chat:subscribe", version: 1, sessionId: this.sessionId });
+    };
+    if (this.chatSubscribers.size === 1) {
+      if (this._hostOrigin) subscribe();
+      else void this._initPromise.then(subscribe, () => void 0);
+    }
+    return () => {
+      if (!this.chatSubscribers.delete(handlers) || this.chatSubscribers.size > 0) return;
+      if (!this._destroyed && this.sessionId && this._hostOrigin)
+        this.postToHost({ type: "verentis:chat:unsubscribe", version: 1, sessionId: this.sessionId });
+    };
+  }
+  receiveChat(data) {
+    if (data.type !== "verentis:chat:changed" && data.type !== "verentis:chat:connection" && data.type !== "verentis:chat:subscribed" && data.type !== "verentis:chat:error") return false;
+    if (!this._hostOrigin || data.sessionId !== this.sessionId) return true;
+    for (const subscriber of [...this.chatSubscribers]) {
+      try {
+        if (data.type === "verentis:chat:changed") subscriber.onChange(data.hint);
+        else if (data.type === "verentis:chat:error") subscriber.onError?.(String(data.reason).slice(0, 500));
+        else subscriber.onConnection?.(data.status);
+      } catch (error) {
+        console.error("[Verentis SDK] Chat subscriber failed", error);
+      }
+    }
+    return true;
+  }
   /** Subscribe to a specific message type from the host */
   on(type, listener) {
     if (!this.listeners.has(type)) {
@@ -1483,8 +1835,13 @@ var Bridge = class {
     if (!this._hostOrigin) this._initReject(new Error("Bridge has been destroyed."));
     this.actions.clear();
     this.requests.clear();
+    this.commands.clear();
+    this.commandUpserts.clear();
+    this.commandRemovals.clear();
+    this.commandRequests.clear();
     this.hostMessageHandlers.clear();
     this.hostMessageRequests.clear();
+    this.chatSubscribers.clear();
     this.listeners.clear();
     for (const pending of this.wopiRequests.values()) {
       clearTimeout(pending.timer);
@@ -1513,6 +1870,13 @@ var Bridge = class {
       this._initTimer = void 0;
       this._hostOrigin = event.origin;
       this.sessionId = typeof data.sessionId === "string" ? data.sessionId : null;
+      this._hostCapabilities = Array.isArray(data.capabilities) ? data.capabilities.filter((c) => typeof c === "string").slice(0, 64) : [];
+      if (this.sessionId && this.commands.size > 0) {
+        this.commandReset = true;
+        this.commandRemovals.clear();
+        for (const id2 of this.commands.keys()) this.commandUpserts.add(id2);
+        this.scheduleCommandFlush();
+      }
       console.info("[Verentis SDK] Received verentis:init from host", {
         origin: event.origin,
         workspaceId: data.context.workspace.id,
@@ -1550,10 +1914,15 @@ var Bridge = class {
       void this.invokeAction(data);
       return;
     }
+    if (data.type === "verentis:command:invoke") {
+      void this.invokeCommand(data);
+      return;
+    }
     if (data.type === "verentis:host:message") {
       void this.receiveHostMessage(data);
       return;
     }
+    if (this.receiveChat(data)) return;
     const typeListeners = this.listeners.get(data.type);
     if (typeListeners) {
       for (const listener of typeListeners) {
@@ -1562,22 +1931,18 @@ var Bridge = class {
     }
   }
 };
-
-// src/types.ts
-var ApiError = class extends Error {
-  constructor(status, detail, title, code) {
-    super(title ?? `API error ${status}: ${detail}`);
-    this.status = status;
-    this.detail = detail;
-    this.title = title;
-    this.code = code;
-    this.name = "ApiError";
-  }
-  status;
-  detail;
-  title;
-  code;
-};
+function cloneCommand(command) {
+  return { ...command, ...command.keywords ? { keywords: [...command.keywords] } : {} };
+}
+function sameCommand(a, b) {
+  const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const key of keys) {
+    if (key === "keywords") {
+      if ((a.keywords ?? []).join("\0") !== (b.keywords ?? []).join("\0")) return false;
+    } else if (a[key] !== b[key]) return false;
+  }
+  return true;
+}
 
 // src/transport/http.transport.ts
 var HttpTransport = class {
@@ -1592,17 +1957,17 @@ var HttpTransport = class {
   async request(method, path, options) {
     const url = this.buildUrl(path, options?.params);
     console.info("[Verentis SDK] Request started", { method, path, url });
-    const headers = {};
+    const headers2 = {};
     const authHeader = await this.auth.getAuthHeader();
     if (authHeader) {
-      headers["Authorization"] = authHeader;
+      headers2["Authorization"] = authHeader;
     }
     if (options?.headers) {
-      Object.assign(headers, options.headers);
+      Object.assign(headers2, options.headers);
     }
     const response = await fetch(url, {
       method,
-      headers,
+      headers: headers2,
       body: options?.body
     });
     await this.ensureSuccess(response);
@@ -1621,15 +1986,15 @@ var HttpTransport = class {
   async requestRaw(method, path, options) {
     const url = this.buildUrl(path, options?.params);
     console.info("[Verentis SDK] Raw request started", { method, path, url });
-    const headers = {};
+    const headers2 = {};
     const authHeader = await this.auth.getAuthHeader();
     if (authHeader) {
-      headers["Authorization"] = authHeader;
+      headers2["Authorization"] = authHeader;
     }
     if (options?.headers) {
-      Object.assign(headers, options.headers);
+      Object.assign(headers2, options.headers);
     }
-    const response = await fetch(url, { method, headers, body: options?.body });
+    const response = await fetch(url, { method, headers: headers2, body: options?.body });
     console.info("[Verentis SDK] Raw request completed", {
       method,
       path,
@@ -1657,7 +2022,15 @@ var HttpTransport = class {
       if (!(error instanceof SyntaxError)) throw error;
     }
     console.error("[Verentis SDK] Request failed", { status: response.status, code });
-    throw new ApiError(response.status, detail, title, code);
+    const retryAfter = response.headers.get("Retry-After");
+    const retryAfterMs = retryAfter === null ? void 0 : /^\d+$/.test(retryAfter) ? Number(retryAfter) * 1e3 : Date.parse(retryAfter) - Date.now();
+    throw new ApiError(
+      response.status,
+      detail,
+      title,
+      code,
+      retryAfterMs !== void 0 && Number.isFinite(retryAfterMs) ? Math.max(0, retryAfterMs) : void 0
+    );
   }
   buildUrl(path, params) {
     const base = `${this.baseUrl}/${this.apiVersion}${path}`;
@@ -1688,8 +2061,9 @@ var VerentisClient = class {
   installations;
   resources;
   settings;
-  email;
+  notifications;
   business;
+  chat;
   context;
   bridge;
   collaboration;
@@ -1724,8 +2098,9 @@ var VerentisClient = class {
       this.installations = new InstallationsModule(this._http, options?.workspaceId);
       this.resources = new ResourcesModule(this._http, options?.workspaceId);
       this.settings = new SettingsModule(this._http, options?.workspaceId);
-      this.email = new EmailModule(this._http, options?.workspaceId);
+      this.notifications = new NotificationsModule(this._http, options?.workspaceId);
       this.business = new BusinessModule(this._http);
+      this.chat = new ChatModule(this._http, null, this.executions);
       this._ready = Promise.resolve();
       return;
     }
@@ -1774,8 +2149,9 @@ var VerentisClient = class {
     this.installations = new InstallationsModule(http, context.workspace.id);
     this.resources = new ResourcesModule(http, context.workspace.id);
     this.settings = new SettingsModule(http, context.workspace.id);
-    this.email = new EmailModule(http, context.workspace.id);
+    this.notifications = new NotificationsModule(http, context.workspace.id);
     this.business = new BusinessModule(http);
+    this.chat = new ChatModule(http, this.bridge, this.executions);
   }
 };
 function detectEnvironment() {
@@ -1871,6 +2247,6 @@ function createVerentisClient(options) {
   return new VerentisClient(options);
 }
 
-export { ApiError, ApiKeyAuth, Bridge, BridgeAuth, BusinessModule, ContextModule, EmailModule, EnginesModule, ExecutionsModule, FilesModule, HOST_MESSAGE_CHANNEL_PATTERN, HttpTransport, InstallationsModule, NativeCollaborationClient, NativeCollaborationError, ResourcesModule, SettingsModule, TokenAuth, VerentisClient, createVerentisClient, exactHttpsOrigin, findBestMatch, isDurableSaveConfirmed, isHeaderAction, isNativeSaveResult, isNativeSnapshot, isTerminalStatus, isTrustedMessage, matchMimeType, validateCollaborationDocument, validateNativeCommand };
+export { APP_COMMANDS_CAPABILITY, APP_COMMAND_BATCH_SIZE, APP_COMMAND_ID_PATTERN, ApiError, ApiKeyAuth, Bridge, BridgeAuth, BusinessModule, ChatModule, ContextModule, EnginesModule, ExecutionsModule, FilesModule, HOST_MESSAGE_CHANNEL_PATTERN, HttpTransport, InstallationsModule, NativeCollaborationClient, NativeCollaborationError, NotificationsModule, ResourcesModule, SCRIPT_ARGUMENTS_SCHEMA, SettingsModule, TokenAuth, VerentisClient, createVerentisClient, exactHttpsOrigin, findBestMatch, isAppCommand, isDurableSaveConfirmed, isHeaderAction, isNativeSaveResult, isNativeSnapshot, isTerminalStatus, isTrustedMessage, matchMimeType, validateCollaborationDocument, validateNativeCommand };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map