@verentis/sdk 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -30,6 +30,14 @@ var BridgeAuth = class {
   _refreshTimer = null;
   _pendingRefresh = null;
   _messageHandler;
+  _requestId = null;
+  _refreshReject = null;
+  _requestTimer = null;
+  _destroyed = false;
+  setHostOrigin(origin) {
+    if (!origin || origin === "*" || origin === "null") throw new Error("A trusted host origin is required.");
+    this.hostOrigin = origin;
+  }
   /** Set the initial token received from the host's `verentis:init` message */
   setToken(info) {
     this._token = info.accessToken;
@@ -44,7 +52,9 @@ var BridgeAuth = class {
     return `Bearer ${this._token}`;
   }
   destroy() {
+    this._destroyed = true;
     if (this._refreshTimer) clearTimeout(this._refreshTimer);
+    this.failRefresh("Authentication has been destroyed.");
     if (typeof window !== "undefined") {
       window.removeEventListener("message", this._messageHandler);
     }
@@ -54,11 +64,16 @@ var BridgeAuth = class {
   }
   _refreshResolve = null;
   requestRefresh() {
+    if (this._destroyed || this.hostOrigin === "*")
+      return Promise.reject(new Error("Authentication is not initialized."));
     if (this._pendingRefresh) return this._pendingRefresh;
     const requestId = crypto.randomUUID();
-    this._pendingRefresh = new Promise((resolve) => {
+    this._requestId = requestId;
+    this._pendingRefresh = new Promise((resolve, reject) => {
       this._refreshResolve = resolve;
+      this._refreshReject = reject;
     });
+    this._requestTimer = setTimeout(() => this.failRefresh("Token refresh timed out."), 2e4);
     const message = {
       type: "verentis:token:refresh",
       version: 1,
@@ -68,21 +83,35 @@ var BridgeAuth = class {
     return this._pendingRefresh;
   }
   handleMessage(event) {
-    if (event.origin !== this.hostOrigin) return;
+    if (this._destroyed || event.origin !== this.hostOrigin || event.source !== window.parent) return;
     const data = event.data;
-    if (data?.type !== "verentis:token:refreshed") return;
+    if (data?.version !== 1 || data?.type !== "verentis:token:refreshed" || !this._requestId || data.requestId !== this._requestId || typeof data.token?.accessToken !== "string" || !Number.isFinite(Date.parse(data.token.expiresAt)) || Date.parse(data.token.expiresAt) <= Date.now() + SKEW_MS) return;
+    if (this._requestTimer) clearTimeout(this._requestTimer);
+    this._requestTimer = null;
+    this._requestId = null;
     this._token = data.token.accessToken;
     this._expiresAt = new Date(data.token.expiresAt).getTime();
     this._pendingRefresh = null;
     this._refreshResolve?.();
     this._refreshResolve = null;
+    this._refreshReject = null;
     this.scheduleRefresh();
   }
   scheduleRefresh() {
     if (this._refreshTimer) clearTimeout(this._refreshTimer);
     if (this._expiresAt === 0) return;
     const delay2 = Math.max(0, this._expiresAt - Date.now() - SKEW_MS);
-    this._refreshTimer = setTimeout(() => void this.requestRefresh(), delay2);
+    this._refreshTimer = setTimeout(() => void this.requestRefresh().catch(() => {
+    }), delay2);
+  }
+  failRefresh(message) {
+    if (this._requestTimer) clearTimeout(this._requestTimer);
+    this._requestTimer = null;
+    this._requestId = null;
+    this._pendingRefresh = null;
+    this._refreshReject?.(new Error(message));
+    this._refreshReject = null;
+    this._refreshResolve = null;
   }
 };
 
@@ -140,6 +169,8 @@ var ContextModule = class {
   _file = null;
   _entryPoint = null;
   _apiUrl = null;
+  _application = null;
+  _installation = null;
   /** The current workspace */
   get workspace() {
     if (!this._workspace) {
@@ -180,13 +211,24 @@ var ContextModule = class {
   get hasEntryPoint() {
     return this._entryPoint !== null;
   }
+  get application() {
+    return this._application ? { ...this._application } : null;
+  }
+  get installation() {
+    return this._installation ? { ...this._installation } : null;
+  }
   /** Update context from the host's init message */
   setFromAppContext(ctx) {
+    if (ctx.application !== void 0 && (typeof ctx.application !== "object" || ctx.application === null || typeof ctx.application.manifestPath !== "string" || !ctx.application.manifestPath.startsWith("/") || typeof ctx.application.manifestNodeId !== "string" || !ctx.application.manifestNodeId.trim() || typeof ctx.application.branch !== "string" || !ctx.application.branch || ctx.application.branch !== ctx.application.branch.trim().toLowerCase() || /[\u0000-\u001f\u007f]/.test(ctx.application.branch))) {
+      throw new Error("Invalid application launch metadata");
+    }
     this._workspace = ctx.workspace;
     this._surface = ctx.surface ?? "file";
     this._file = ctx.file ?? null;
     this._entryPoint = ctx.entryPoint ?? null;
     this._apiUrl = ctx.apiUrl;
+    this._application = ctx.application ? { ...ctx.application } : null;
+    this._installation = ctx.installation ? { ...ctx.installation } : null;
   }
   /** Set workspace info directly (standalone mode) */
   setWorkspace(workspace) {
@@ -414,6 +456,49 @@ var FilesModule = class {
       headers: this.workspaceHeaders()
     });
   }
+  /** Read metadata by stable node identity on an explicit branch. */
+  async getNode(nodeId, options) {
+    requireNonBlank(nodeId, "Node ID");
+    requireNonBlank(options.branch, "Branch");
+    return this.http.request("GET", `/nodes/${encodeURIComponent(nodeId)}/file`, {
+      headers: { ...this.workspaceHeaders(), "X-Branch": options.branch }
+    });
+  }
+  /** Read bytes and their matching content revision in the same response. */
+  async readNodeContent(nodeId, options) {
+    requireNonBlank(nodeId, "Node ID");
+    requireNonBlank(options.branch, "Branch");
+    const response = await this.http.requestRaw("GET", `/nodes/${encodeURIComponent(nodeId)}/content`, {
+      headers: { ...this.workspaceHeaders(), "X-Branch": options.branch, Accept: "*/*" }
+    });
+    await this.http.ensureSuccess(response);
+    const revision = response.headers.get("ETag");
+    if (!revision || !/^"[a-fA-F0-9]{32}"$/.test(revision)) {
+      throw new Error("Node-content response did not include a valid strong revision ETag.");
+    }
+    return { content: await response.blob(), revision };
+  }
+  /** Replace existing node bytes conditionally; never creates or changes path/MIME. */
+  async writeNodeContent(nodeId, options) {
+    requireNonBlank(nodeId, "Node ID");
+    requireNonBlank(options.branch, "Branch");
+    requireNonBlank(options.idempotencyKey, "Idempotency key");
+    const revision = /^[a-fA-F0-9]{32}$/.test(options.revision) ? `"${options.revision}"` : options.revision;
+    if (!/^"[a-fA-F0-9]{32}"$/.test(revision)) {
+      throw new Error("A single strong node-content revision is required.");
+    }
+    const content = typeof options.content === "string" ? new Blob([options.content]) : options.content instanceof ArrayBuffer ? new Blob([options.content]) : options.content;
+    return this.http.request("PUT", `/nodes/${encodeURIComponent(nodeId)}/content`, {
+      body: content,
+      headers: {
+        ...this.workspaceHeaders(),
+        "X-Branch": options.branch,
+        "If-Match": revision,
+        "Idempotency-Key": options.idempotencyKey,
+        "Content-Type": "application/octet-stream"
+      }
+    });
+  }
   /**
    * Read the raw content of a file as a Blob.
    */
@@ -530,14 +615,19 @@ var FilesModule = class {
    * Delete a file.
    */
   async remove(options) {
-    await this.http.request("DELETE", "/files", {
-      body: JSON.stringify({
-        path: normalizePath(options.path),
-        branch: options.branch
-      }),
+    const path = normalizePath(options.path);
+    requireNonBlank(path, "File path");
+    const branch = options.branch ?? "main";
+    requireNonBlank(branch, "Branch");
+    if (options.headStamp !== void 0) requireNonBlank(options.headStamp, "Path head stamp");
+    if (options.idempotencyKey !== void 0) requireNonBlank(options.idempotencyKey, "Idempotency key");
+    await this.http.request("DELETE", `/files/${path.split("/").map(encodeURIComponent).join("/")}`, {
+      params: { branch },
       headers: {
         ...this.workspaceHeaders(),
-        "Content-Type": "application/json"
+        ...options.headStamp === void 0 ? {} : { "If-Match": options.headStamp },
+        ...options.idempotencyKey === void 0 ? {} : { "Idempotency-Key": options.idempotencyKey },
+        ...options.mode === void 0 ? {} : { "X-Delete-Mode": options.mode === "deep" ? "Deep" : "Shallow" }
       }
     });
   }
@@ -549,6 +639,9 @@ var FilesModule = class {
     return headers;
   }
 };
+function requireNonBlank(value, name) {
+  if (value.trim().length === 0) throw new Error(`${name} is required.`);
+}
 function normalizePath(path) {
   return path.replace(/\/+/g, "/").replace(/^\//, "").replace(/\/$/, "");
 }
@@ -565,6 +658,52 @@ var InstallationsModule = class {
   }
   http;
   workspaceId;
+  /** Resolve canonical publisher/package identity, never the installation's runtime display name. */
+  async resolvePackageId(identity, options) {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*\/[a-z0-9]+(?:-[a-z0-9]+)*$/.test(identity)) {
+      throw new Error("A canonical publisher/package identity is required");
+    }
+    const result = await this.http.request("GET", `/packages/by-package-id/${identity}`, {
+      params: { workspaceId: this.requireWorkspaceId(options?.workspaceId) }
+    });
+    if (!result || typeof result.id !== "string" || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(result.id)) {
+      throw new Error("The catalog response omitted its stable package identity");
+    }
+    return result.id;
+  }
+  /** Resolves the complete required graph without installing anything or granting capabilities. */
+  async preview(packageId, options) {
+    return this.http.request("POST", "/installations/graphs/preview", {
+      body: JSON.stringify({
+        workspaceId: this.requireWorkspaceId(options?.workspaceId),
+        packageId,
+        packageVersion: options?.packageVersion,
+        installPath: options?.installPath,
+        branch: options?.branch,
+        installMode: options?.installMode
+      }),
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+  /** Explicit, single-use consent to a displayed preview. Never automatically retries accepted installs. */
+  async install(preview, consent) {
+    if (consent !== true) throw new Error("Explicit consent to the installation graph is required");
+    return this.http.request("POST", "/installations/graphs", {
+      body: JSON.stringify({
+        workspaceId: preview.workspaceId,
+        operationId: preview.operationId,
+        fingerprint: preview.fingerprint,
+        consent
+      }),
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+  /** Inspect durable outcomes after a failure or lost response instead of resubmitting consent. */
+  async graphResult(operationId, options) {
+    return this.http.request("GET", `/installations/graphs/${encodeURIComponent(operationId)}`, {
+      params: { workspaceId: this.requireWorkspaceId(options?.workspaceId) }
+    });
+  }
   async list(options) {
     return this.http.request("GET", "/installations", {
       params: {
@@ -745,23 +884,212 @@ var SettingsModule = class {
   }
 };
 
+// src/modules/email.ts
+var EmailModule = 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 },
+      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),
+        installationId: options.installationId,
+        recordId: options.recordId,
+        purpose: options.purpose,
+        templateId: options.templateId,
+        senderId: options.senderId,
+        recipients: options.recipients,
+        artifactIds: options.artifactIds,
+        idempotencyKey: options.idempotencyKey,
+        replyTo: options.replyTo
+      }),
+      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);
+  }
+  workspace(options) {
+    const value = options?.workspaceId ?? this.workspaceId;
+    if (!value) throw new Error("A workspace is required for transactional email");
+    return value;
+  }
+  mainBranch(options) {
+    if (options?.branch !== void 0 && options.branch !== "main")
+      throw new Error("Transactional email currently supports only the main business branch");
+  }
+};
+
+// src/modules/business.ts
+var BusinessModule = class _BusinessModule {
+  constructor(http, branch = "main") {
+    this.http = http;
+    this.branch = branch;
+  }
+  http;
+  branch;
+  withBranch(branch) {
+    return new _BusinessModule(this.http, branch);
+  }
+  async context() {
+    return this.http.request("GET", "/business/context", { headers: this.headers() });
+  }
+  async command(command) {
+    if (!command.idempotencyKey?.trim() || command.idempotencyKey.length > 200 || /[\u0000-\u001f\u007f-\u009f]/.test(command.idempotencyKey)) {
+      throw new Error("A bounded printable idempotency key is required");
+    }
+    if (command.expectedRevision !== void 0 && !/^"[a-f0-9]{32}"$/.test(command.expectedRevision)) {
+      throw new Error("An exact strong quoted canonical revision is required");
+    }
+    return this.http.request("POST", "/business/commands", {
+      headers: this.headers(),
+      body: JSON.stringify(command)
+    });
+  }
+  async read(id) {
+    return this.http.request("GET", `/business/records/${encodeURIComponent(id)}`, { headers: this.headers() });
+  }
+  async list(kind) {
+    return this.http.request("GET", "/business/records", {
+      headers: this.headers(),
+      params: kind ? { kind } : {}
+    });
+  }
+  /** null means unresolved, not success; do not invent a new operation key. */
+  async outcome(request) {
+    return this.http.request("POST", "/business/outcomes", {
+      headers: this.headers(),
+      body: JSON.stringify(request)
+    });
+  }
+  /** Recover using the exact original command, without reproducing server fingerprint encoding. */
+  async outcomeFor(command) {
+    return this.outcome({ operation: command.operation, idempotencyKey: command.idempotencyKey, command });
+  }
+  async report(report, range = {}) {
+    return this.http.request("GET", `/business/reports/${report}`, {
+      headers: this.headers(),
+      params: range
+    });
+  }
+  /** Retained historical expense receipt bytes, even after the original native file is removed. */
+  async receipt(nodeId, revision) {
+    const response = await this.http.requestRaw("GET", `/business/receipts/${encodeURIComponent(nodeId)}/content`, {
+      headers: this.headers(),
+      params: { revision }
+    });
+    await this.http.ensureSuccess(response);
+    return response.blob();
+  }
+  headers() {
+    if (!this.branch || this.branch.length > 128 || this.branch !== this.branch.trim().toLowerCase() || /[\u0000-\u001f\u007f-\u009f]/.test(this.branch)) {
+      throw new Error("Business operations require a canonical branch");
+    }
+    return { "X-Branch": this.branch, "Content-Type": "application/json" };
+  }
+};
+
+// src/transport/header-actions.ts
+function isHeaderAction(value) {
+  if (!value || typeof value !== "object") return false;
+  const a = value;
+  return typeof a.id === "string" && /^[a-z][a-z0-9.-]{0,63}$/.test(a.id) && typeof a.label === "string" && a.label.trim().length > 0 && a.label.length <= 100 && Array.isArray(a.scopes) && a.scopes.length <= 32 && a.scopes.every((s) => typeof s === "string" && /^[a-zA-Z0-9._:-]{1,128}$/.test(s)) && (a.icon === void 0 || typeof a.icon === "string" && /^lucide:[a-z0-9-]{1,64}$/.test(a.icon)) && (a.variant === void 0 || ["default", "outline", "destructive"].includes(String(a.variant))) && ["enabled", "visible", "busy"].every((key) => a[key] === void 0 || typeof a[key] === "boolean") && (a.disabledReason === void 0 || typeof a.disabledReason === "string" && a.disabledReason.length <= 200) && (a.kind === void 0 || a.kind === "clipboard");
+}
+
 // src/transport/bridge.transport.ts
 var Bridge = class {
-  listeners = /* @__PURE__ */ new Map();
-  _initResolve;
-  _initPromise;
-  _hostOrigin = null;
-  _messageHandler;
-  _destroyed = false;
-  constructor() {
-    this._initPromise = new Promise((resolve) => {
+  constructor(expectedHostOrigin) {
+    this.expectedHostOrigin = expectedHostOrigin;
+    this._initPromise = new Promise((resolve, reject) => {
       this._initResolve = resolve;
+      this._initReject = reject;
+    });
+    void this._initPromise.catch(() => {
     });
     this._messageHandler = this.handleMessage.bind(this);
     if (typeof window !== "undefined") {
       window.addEventListener("message", this._messageHandler);
     }
   }
+  expectedHostOrigin;
+  listeners = /* @__PURE__ */ new Map();
+  _initResolve;
+  _initReject;
+  _initTimer;
+  _initPromise;
+  _hostOrigin = null;
+  _messageHandler;
+  _destroyed = false;
+  sessionId = null;
+  actions = /* @__PURE__ */ new Map();
+  requests = /* @__PURE__ */ new Set();
+  backendRequests = /* @__PURE__ */ new Map();
+  wopiRequests = /* @__PURE__ */ new Map();
   /** Post `verentis:ready` to the host to start the handshake */
   sendReady(capabilities) {
     console.info("[Verentis SDK] Sending verentis:ready to host");
@@ -770,10 +1098,16 @@ var Bridge = class {
       version: 1,
       capabilities
     };
-    window.parent.postMessage(message, "*");
+    window.parent.postMessage(message, this.expectedHostOrigin ?? "*");
   }
   /** Wait for the host to send `verentis:init` with context and token */
   waitForInit() {
+    if (!this._hostOrigin && !this._destroyed && !this._initTimer) {
+      this._initTimer = setTimeout(() => {
+        this._initReject(new Error("Workspace handshake timed out."));
+        this.destroy();
+      }, 2e4);
+    }
     return this._initPromise;
   }
   /** Get the host origin (available after init) */
@@ -782,6 +1116,7 @@ var Bridge = class {
   }
   /** Send a message to the host */
   postToHost(message) {
+    if (this._destroyed) throw new Error("Bridge has been destroyed.");
     if (!this._hostOrigin) {
       throw new Error("Bridge not initialized: host origin unknown. Wait for init first.");
     }
@@ -816,6 +1151,138 @@ var Bridge = class {
   setDirty(isDirty) {
     this.postToHost({ type: "verentis:dirty", version: 1, isDirty });
   }
+  /** The host, not the app, selects the installation, file, branch and permission ceiling. */
+  requestBackendCredential() {
+    if (this._destroyed || !this.sessionId || !this._hostOrigin)
+      return Promise.reject(new Error("An initialized workspace host is required."));
+    if (this.backendRequests.size >= 4)
+      return Promise.reject(new Error("A backend credential request is already pending."));
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.backendRequests.delete(requestId);
+        reject(new Error("Backend authorization timed out."));
+      }, 2e4);
+      this.backendRequests.set(requestId, { resolve, reject, timer });
+      try {
+        this.postToHost({ type: "verentis:backend:request", version: 1, requestId, sessionId: this.sessionId });
+      } catch {
+        clearTimeout(timer);
+        this.backendRequests.delete(requestId);
+        reject(new Error("The workspace host is unavailable."));
+      }
+    });
+  }
+  /** The trusted parent selects the approved installation, document and action. */
+  requestWopiLaunch() {
+    return this.requestWopi("launch");
+  }
+  /** Recover only the target selected by a completed server-owned derived operation. */
+  requestWopiContinuation() {
+    return this.requestWopi("continue");
+  }
+  getWopiStatus() {
+    return this.requestWopi("status");
+  }
+  requestWopiSave(generation) {
+    if (!Number.isSafeInteger(generation) || generation < 0)
+      return Promise.reject(new Error("Invalid edit generation."));
+    return this.requestWopi("save", generation);
+  }
+  closeWopiSession() {
+    return this.requestWopi("close");
+  }
+  requestWopi(operation, generation) {
+    if (this._destroyed || !this.sessionId || !this._hostOrigin)
+      return Promise.reject(new Error("An initialized workspace host is required."));
+    if (this.wopiRequests.size >= 4)
+      return Promise.reject(new Error("Too many collaboration requests."));
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.wopiRequests.delete(requestId);
+        reject(new Error("Collaboration authorization timed out."));
+      }, 3e4);
+      this.wopiRequests.set(requestId, { resolve, reject, timer });
+      try {
+        this.postToHost({
+          type: "verentis:wopi:request",
+          version: 1,
+          requestId,
+          sessionId: this.sessionId,
+          operation,
+          ...generation === void 0 ? {} : { generation }
+        });
+      } catch {
+        clearTimeout(timer);
+        this.wopiRequests.delete(requestId);
+        reject(new Error("The workspace host is unavailable."));
+      }
+    });
+  }
+  registerAction(descriptor, handler) {
+    if (!this.sessionId || this._destroyed) throw new Error("Header actions require an initialized workspace host.");
+    if (!isHeaderAction(descriptor)) throw new Error("Invalid header action.");
+    if (this.actions.has(descriptor.id)) throw new Error(`Action '${descriptor.id}' is already registered.`);
+    if (this.actions.size >= 16) throw new Error("At most 16 header actions may be registered.");
+    const action = { descriptor: { ...descriptor, scopes: [...descriptor.scopes] }, handler, busy: false };
+    this.actions.set(descriptor.id, action);
+    this.publishActions();
+    return {
+      update: (next) => {
+        if (this.actions.get(descriptor.id) !== action) throw new Error("Action has been disposed.");
+        if (!isHeaderAction(next) || next.id !== descriptor.id) throw new Error("Invalid header action update.");
+        action.descriptor = { ...next, scopes: [...next.scopes] };
+        this.publishActions();
+      },
+      dispose: () => {
+        if (this.actions.get(descriptor.id) !== action) return;
+        this.actions.delete(descriptor.id);
+        this.publishActions();
+      }
+    };
+  }
+  publishActions() {
+    if (!this.sessionId || this._destroyed) return;
+    this.postToHost({
+      type: "verentis:actions:set",
+      version: 1,
+      sessionId: this.sessionId,
+      actions: [...this.actions.values()].map((a) => ({ ...a.descriptor, busy: a.busy || a.descriptor.busy }))
+    });
+  }
+  async invokeAction(message) {
+    if (message.sessionId !== this.sessionId || typeof message.requestId !== "string" || message.requestId.length > 128 || !message.requestId || this.requests.has(message.requestId)) return;
+    this.requests.add(message.requestId);
+    if (this.requests.size > 1e3) this.requests.delete(this.requests.values().next().value);
+    const action = this.actions.get(message.actionId);
+    const reply = {
+      type: "verentis:action:result",
+      version: 1,
+      sessionId: message.sessionId,
+      requestId: message.requestId,
+      actionId: message.actionId
+    };
+    if (!action || action.busy || action.descriptor.busy || action.descriptor.enabled === false || action.descriptor.visible === false) {
+      this.postToHost({ ...reply, error: "Action is unavailable." });
+      return;
+    }
+    action.busy = true;
+    this.publishActions();
+    try {
+      const result = await action.handler();
+      if (!this._destroyed && this.sessionId === message.sessionId) {
+        this.postToHost({ ...reply, result: result || void 0 });
+      }
+    } catch (error) {
+      if (!this._destroyed && this.sessionId === message.sessionId) {
+        this.postToHost({ ...reply, error: (error instanceof Error ? error.message : "Action failed.").slice(0, 500) });
+      }
+    } finally {
+      action.busy = false;
+      this.publishActions();
+    }
+  }
   /** Subscribe to a specific message type from the host */
   on(type, listener) {
     if (!this.listeners.has(type)) {
@@ -829,7 +1296,22 @@ var Bridge = class {
   /** Clean up event listeners */
   destroy() {
     this._destroyed = true;
+    clearTimeout(this._initTimer);
+    this._initTimer = void 0;
+    if (!this._hostOrigin) this._initReject(new Error("Bridge has been destroyed."));
+    this.actions.clear();
+    this.requests.clear();
     this.listeners.clear();
+    for (const pending of this.backendRequests.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("Bridge has been destroyed."));
+    }
+    this.backendRequests.clear();
+    for (const pending of this.wopiRequests.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("Bridge has been destroyed."));
+    }
+    this.wopiRequests.clear();
     if (typeof window !== "undefined") {
       window.removeEventListener("message", this._messageHandler);
     }
@@ -837,9 +1319,16 @@ var Bridge = class {
   handleMessage(event) {
     if (this._destroyed) return;
     const data = event.data;
-    if (!data?.type?.startsWith("verentis:")) return;
+    if (event.source !== window.parent || data?.version !== 1 || typeof data?.type !== "string" || !data.type.startsWith("verentis:")) return;
+    if (this._hostOrigin && event.origin !== this._hostOrigin) return;
+    if (this.expectedHostOrigin && event.origin !== this.expectedHostOrigin) return;
     if (data.type === "verentis:init") {
+      if (this._hostOrigin) return;
+      if (!data.context?.workspace?.id || !data.token || event.origin === "null") return;
+      clearTimeout(this._initTimer);
+      this._initTimer = void 0;
       this._hostOrigin = event.origin;
+      this.sessionId = typeof data.sessionId === "string" ? data.sessionId : null;
       console.info("[Verentis SDK] Received verentis:init from host", {
         origin: event.origin,
         workspaceId: data.context.workspace.id,
@@ -848,6 +1337,33 @@ var Bridge = class {
       const initData = data;
       this._initResolve({ context: initData.context, token: initData.token });
     }
+    if (data.type === "verentis:backend:response") {
+      if (!this._hostOrigin || data.sessionId !== this.sessionId) return;
+      const pending = this.backendRequests.get(data.requestId);
+      if (!pending) return;
+      clearTimeout(pending.timer);
+      this.backendRequests.delete(data.requestId);
+      const value = data.credential;
+      if (data.error || !value || typeof value.launchCredential !== "string" || value.launchCredential.length > 512 || !value.launchCredential || typeof value.delegationId !== "string" || typeof value.backendClientId !== "string" || !Number.isFinite(Date.parse(value.expiresAt)) || Date.parse(value.expiresAt) <= Date.now())
+        pending.reject(new Error("Backend authorization was denied or is not configured."));
+      else pending.resolve(value);
+      return;
+    }
+    if (data.type === "verentis:wopi:response") {
+      if (!this._hostOrigin || data.sessionId !== this.sessionId) return;
+      const pending = this.wopiRequests.get(data.requestId);
+      if (!pending) return;
+      clearTimeout(pending.timer);
+      this.wopiRequests.delete(data.requestId);
+      if (data.error || !Object.hasOwn(data, "result"))
+        pending.reject(new Error("Collaboration authorization is unavailable."));
+      else pending.resolve(data.result);
+      return;
+    }
+    if (data.type === "verentis:action:invoke") {
+      void this.invokeAction(data);
+      return;
+    }
     const typeListeners = this.listeners.get(data.type);
     if (typeListeners) {
       for (const listener of typeListeners) {
@@ -859,16 +1375,18 @@ var Bridge = class {
 
 // src/types.ts
 var ApiError = class extends Error {
-  constructor(status, detail, title) {
+  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;
 };
 
 // src/transport/http.transport.ts
@@ -897,24 +1415,7 @@ var HttpTransport = class {
       headers,
       body: options?.body
     });
-    if (!response.ok) {
-      let detail = "";
-      let title;
-      try {
-        const body = await response.json();
-        detail = body.detail ?? body.message ?? JSON.stringify(body);
-        title = body.title;
-      } catch {
-        detail = await response.text().catch(() => response.statusText);
-      }
-      console.error("[Verentis SDK] Request failed", {
-        method,
-        path,
-        status: response.status,
-        detail
-      });
-      throw new ApiError(response.status, detail, title);
-    }
+    await this.ensureSuccess(response);
     console.info("[Verentis SDK] Request succeeded", {
       method,
       path,
@@ -948,6 +1449,26 @@ var HttpTransport = class {
     });
     return response;
   }
+  async ensureSuccess(response) {
+    if (response.ok) return;
+    const raw = await response.text();
+    let detail = raw || response.statusText;
+    let title;
+    let code;
+    try {
+      const body = JSON.parse(raw);
+      if (body !== null && typeof body === "object") {
+        if ("detail" in body && typeof body.detail === "string") detail = body.detail;
+        else if ("message" in body && typeof body.message === "string") detail = body.message;
+        if ("title" in body && typeof body.title === "string") title = body.title;
+        if ("code" in body && typeof body.code === "string") code = body.code;
+      }
+    } catch (error) {
+      if (!(error instanceof SyntaxError)) throw error;
+    }
+    console.error("[Verentis SDK] Request failed", { status: response.status, code });
+    throw new ApiError(response.status, detail, title, code);
+  }
   buildUrl(path, params) {
     const base = `${this.baseUrl}/${this.apiVersion}${path}`;
     if (!params) return base;
@@ -977,6 +1498,8 @@ var VerentisClient = class {
   installations;
   resources;
   settings;
+  email;
+  business;
   context;
   bridge;
   _auth;
@@ -1008,6 +1531,8 @@ 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.business = new BusinessModule(this._http);
       this._ready = Promise.resolve();
       return;
     }
@@ -1029,7 +1554,7 @@ var VerentisClient = class {
     this.bridge.sendReady();
     const { context, token } = await this.bridge.waitForInit();
     const hostOrigin = this.bridge.hostOrigin;
-    Object.assign(bridgeAuth, new BridgeAuth(hostOrigin));
+    bridgeAuth.setHostOrigin(hostOrigin);
     bridgeAuth.setToken(token);
     this.context.setFromAppContext(context);
     const http = new HttpTransport(
@@ -1044,6 +1569,8 @@ 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.business = new BusinessModule(http);
   }
 };
 function detectEnvironment() {
@@ -1101,10 +1628,13 @@ function createVerentisClient(options) {
   return new VerentisClient(options);
 }
 
+exports.ApiError = ApiError;
 exports.ApiKeyAuth = ApiKeyAuth;
 exports.Bridge = Bridge;
 exports.BridgeAuth = BridgeAuth;
+exports.BusinessModule = BusinessModule;
 exports.ContextModule = ContextModule;
+exports.EmailModule = EmailModule;
 exports.EnginesModule = EnginesModule;
 exports.ExecutionsModule = ExecutionsModule;
 exports.FilesModule = FilesModule;
@@ -1116,6 +1646,7 @@ exports.TokenAuth = TokenAuth;
 exports.VerentisClient = VerentisClient;
 exports.createVerentisClient = createVerentisClient;
 exports.findBestMatch = findBestMatch;
+exports.isHeaderAction = isHeaderAction;
 exports.isTerminalStatus = isTerminalStatus;
 exports.matchMimeType = matchMimeType;
 //# sourceMappingURL=index.cjs.map