@verentis/sdk 0.2.4 → 0.2.6

package/dist/index.js

@@ -167,6 +167,9 @@ var ContextModule = class {
   _file = null;
   _entryPoint = null;
   _apiUrl = null;
+  _application = null;
+  _installation = null;
+  _grants = null;
   /** The current workspace */
   get workspace() {
     if (!this._workspace) {
@@ -207,13 +210,39 @@ 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;
+  }
+  /**
+   * The boundaries of a brokered token (canvas documents), as the host sent them with the token; `null` when the
+   * token is not boundary-confined by a broker (or in standalone mode).
+   */
+  get grants() {
+    return this._grants ? this._grants.map((grant) => ({ ...grant })) : null;
+  }
+  /** Update the token's grants from the host's init or token refresh message */
+  setGrants(grants) {
+    if (!Array.isArray(grants)) {
+      this._grants = null;
+      return;
+    }
+    this._grants = grants.filter((grant) => typeof grant === "object" && grant !== null && typeof grant.type === "string" && typeof grant.identifier === "string" && typeof grant.path === "string" && grant.path.startsWith("/") && (grant.mode === "read" || grant.mode === "write") && typeof grant.source === "string").map((grant) => ({ type: grant.type, identifier: grant.identifier, path: grant.path, mode: grant.mode, source: grant.source }));
+  }
   /** 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) {
@@ -441,6 +470,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.
    */
@@ -532,11 +604,18 @@ var FilesModule = class {
     if (options.contentType) metadata.contentType = options.contentType;
     if (options.branch) metadata.branch = options.branch;
     formData.append("metadata", JSON.stringify(metadata));
-    await this.http.request("POST", `/files/${normalizedPath}`, {
+    await this.http.request("POST", `/files/${normalizedPath.split("/").map(encodeURIComponent).join("/")}`, {
       body: formData,
-      headers: this.workspaceHeaders()
+      headers: {
+        ...this.workspaceHeaders(),
+        ...options.createOnly ? { "If-None-Match": "*" } : {}
+      }
     });
   }
+  /** Create without a read-before-write race or overwrite of an existing live file. */
+  async create(path, options) {
+    await this.write(path, { ...options, createOnly: true });
+  }
   /**
    * Move or rename a file.
    */
@@ -557,14 +636,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" }
       }
     });
   }
@@ -576,6 +660,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(/\/$/, "");
 }
@@ -592,6 +679,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: {
@@ -772,6 +905,176 @@ 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;
@@ -779,7 +1082,113 @@ function isHeaderAction(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/collaboration/native.ts
+var NativeCollaborationError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "NativeCollaborationError";
+  }
+  code;
+};
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function natural(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function identifier(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= 256;
+}
+function pointer(value) {
+  return record(value) && typeof value.x === "number" && Number.isFinite(value.x) && typeof value.y === "number" && Number.isFinite(value.y);
+}
+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)));
+}
+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)
+    return false;
+  const ids = value.scene.elements.map((item) => item.id);
+  if (new Set(ids).size !== ids.length) return false;
+  const connectionIds = value.participants.map((item) => record(item) ? item.id : void 0);
+  if (new Set(connectionIds).size !== connectionIds.length) return false;
+  return value.participants.every((item) => record(item) && identifier(item.id) && typeof item.name === "string" && item.name.length <= 1024 && typeof item.readOnly === "boolean" && (item.pointer === null || pointer(item.pointer)) && (item.kind === void 0 || item.kind === "user" || item.kind === "agent"));
+}
+function isNativeSaveResult(value) {
+  return isNativeSnapshot(value) && record(value) && record(value.receipt) && natural(value.receipt.generation) && identifier(value.receipt.correlation) && typeof value.receipt.revision === "string" && value.receipt.revision.length > 0 && value.receipt.revision.length <= 1024;
+}
+function validateNativeCommand(command) {
+  if (!record(command)) throw new Error("Invalid collaboration command.");
+  switch (command.operation) {
+    case "join":
+    case "snapshot":
+    case "close":
+      break;
+    case "presence":
+      if (command.pointer !== null && !pointer(command.pointer))
+        throw new Error("Invalid collaboration pointer.");
+      break;
+    case "save":
+      if (!natural(command.generation) || !identifier(command.correlation))
+        throw new Error("Invalid collaboration save frontier.");
+      break;
+    case "apply": {
+      const changes = command.changes;
+      if (!record(changes) || !identifier(changes.operationId) || !Array.isArray(changes.changes) || changes.changes.length > 1e4 || !changes.changes.every((change) => record(change) && identifier(change.id) && (change.expectedVersion === null || natural(change.expectedVersion)) && (change.element === null || element(change.element) && change.element.id === change.id)) || changes.files !== void 0 && !files(changes.files) || (changes.appState !== void 0 ? !record(changes.appState) || !natural(changes.appStateExpectedSequence) : changes.appStateExpectedSequence !== void 0))
+        throw new Error("Invalid collaboration changes.");
+      const ids = changes.changes.map((change) => change.id);
+      if (new Set(ids).size !== ids.length) throw new Error("Duplicate collaboration element changes.");
+      break;
+    }
+    default:
+      throw new Error("Unsupported collaboration command.");
+  }
+  if (new TextEncoder().encode(JSON.stringify(command)).byteLength > 10 * 1024 * 1024)
+    throw new Error("Collaboration request exceeds the document limit.");
+}
+var NativeCollaborationClient = class {
+  constructor(bridge) {
+    this.bridge = bridge;
+  }
+  bridge;
+  async snapshotRequest(command) {
+    if (!this.bridge) throw new Error("Native collaboration requires an installed workspace host.");
+    const result = await this.bridge.requestNativeCollaboration(command);
+    if (!isNativeSnapshot(result)) throw new Error("Invalid native collaboration snapshot.");
+    return result;
+  }
+  join() {
+    return this.snapshotRequest({ operation: "join" });
+  }
+  snapshot() {
+    return this.snapshotRequest({ operation: "snapshot" });
+  }
+  apply(changes) {
+    return this.snapshotRequest({ operation: "apply", changes });
+  }
+  presence(value) {
+    return this.snapshotRequest({ operation: "presence", pointer: value });
+  }
+  async save(generation, correlation) {
+    if (!this.bridge) throw new Error("Native collaboration requires an installed workspace host.");
+    const result = await this.bridge.requestNativeCollaboration({ operation: "save", generation, correlation });
+    if (!isNativeSaveResult(result) || result.receipt.generation !== generation || result.receipt.correlation !== correlation)
+      throw new Error("Invalid native collaboration save receipt.");
+    return result;
+  }
+  async close() {
+    if (!this.bridge) throw new Error("Native collaboration requires an installed workspace host.");
+    const result = await this.bridge.requestNativeCollaboration({ operation: "close" });
+    if (result !== null) throw new Error("Invalid native collaboration close response.");
+  }
+};
+
 // src/transport/bridge.transport.ts
+var HOST_MESSAGE_CHANNEL_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
 var Bridge = class {
   constructor(expectedHostOrigin) {
     this.expectedHostOrigin = expectedHostOrigin;
@@ -806,8 +1215,10 @@ var Bridge = class {
   sessionId = null;
   actions = /* @__PURE__ */ new Map();
   requests = /* @__PURE__ */ new Set();
-  backendRequests = /* @__PURE__ */ new Map();
+  hostMessageHandlers = /* @__PURE__ */ new Map();
+  hostMessageRequests = /* @__PURE__ */ new Set();
   wopiRequests = /* @__PURE__ */ new Map();
+  collaborationRequests = /* @__PURE__ */ new Map();
   /** Post `verentis:ready` to the host to start the handshake */
   sendReady(capabilities) {
     console.info("[Verentis SDK] Sending verentis:ready to host");
@@ -869,28 +1280,6 @@ 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");
@@ -938,6 +1327,38 @@ var Bridge = class {
       }
     });
   }
+  requestNativeCollaboration(command) {
+    if (this._destroyed || !this.sessionId || !this._hostOrigin)
+      return Promise.reject(new Error("An initialized workspace host is required."));
+    if (this.collaborationRequests.size >= 4)
+      return Promise.reject(new Error("Too many native collaboration requests."));
+    try {
+      validateNativeCommand(command);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.collaborationRequests.delete(requestId);
+        reject(new NativeCollaborationError("Native collaboration timed out.", "unavailable"));
+      }, 3e4);
+      this.collaborationRequests.set(requestId, { resolve, reject, timer });
+      try {
+        this.postToHost({
+          type: "verentis:collaboration:request",
+          version: 1,
+          requestId,
+          sessionId: this.sessionId,
+          command
+        });
+      } catch (error) {
+        clearTimeout(timer);
+        this.collaborationRequests.delete(requestId);
+        reject(error);
+      }
+    });
+  }
   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.");
@@ -1001,6 +1422,49 @@ var Bridge = class {
       this.publishActions();
     }
   }
+  /**
+   * Handle messages the workspace sends on a channel declared in the manifest `spec.messages` — for
+   * example an agent asking the open app to select a record. The handler's return value is the reply;
+   * a thrown error is reported back as the failure. May be called before the init handshake.
+   */
+  onHostMessage(channel, handler) {
+    if (this._destroyed) throw new Error("Bridge has been destroyed.");
+    if (!HOST_MESSAGE_CHANNEL_PATTERN.test(channel)) throw new Error(`Invalid host message channel '${channel}'.`);
+    if (this.hostMessageHandlers.has(channel)) throw new Error(`Channel '${channel}' already has a handler.`);
+    this.hostMessageHandlers.set(channel, handler);
+    return () => {
+      if (this.hostMessageHandlers.get(channel) === handler) this.hostMessageHandlers.delete(channel);
+    };
+  }
+  async receiveHostMessage(message) {
+    if (!this._hostOrigin || message.sessionId !== this.sessionId || typeof message.channel !== "string" || typeof message.requestId !== "string" || !message.requestId || message.requestId.length > 128 || this.hostMessageRequests.has(message.requestId)) return;
+    this.hostMessageRequests.add(message.requestId);
+    if (this.hostMessageRequests.size > 1e3) this.hostMessageRequests.delete(this.hostMessageRequests.values().next().value);
+    const reply = {
+      type: "verentis:host:reply",
+      version: 1,
+      sessionId: message.sessionId,
+      requestId: message.requestId,
+      channel: message.channel
+    };
+    const handler = this.hostMessageHandlers.get(message.channel);
+    if (!handler) {
+      this.postToHost({ ...reply, error: `The application does not handle '${message.channel.slice(0, 64)}' messages.` });
+      return;
+    }
+    let response;
+    try {
+      response = { result: await handler(message.payload) };
+    } catch (error) {
+      response = { error: (error instanceof Error ? error.message : "Message failed.").slice(0, 500) || "Message failed." };
+    }
+    if (this._destroyed || this.sessionId !== message.sessionId) return;
+    try {
+      this.postToHost({ ...reply, ...response });
+    } catch {
+      this.postToHost({ ...reply, error: "The reply could not be sent to the workspace." });
+    }
+  }
   /** Subscribe to a specific message type from the host */
   on(type, listener) {
     if (!this.listeners.has(type)) {
@@ -1019,17 +1483,19 @@ var Bridge = class {
     if (!this._hostOrigin) this._initReject(new Error("Bridge has been destroyed."));
     this.actions.clear();
     this.requests.clear();
+    this.hostMessageHandlers.clear();
+    this.hostMessageRequests.clear();
     this.listeners.clear();
-    for (const pending of this.backendRequests.values()) {
+    for (const pending of this.wopiRequests.values()) {
       clearTimeout(pending.timer);
       pending.reject(new Error("Bridge has been destroyed."));
     }
-    this.backendRequests.clear();
-    for (const pending of this.wopiRequests.values()) {
+    this.wopiRequests.clear();
+    for (const pending of this.collaborationRequests.values()) {
       clearTimeout(pending.timer);
       pending.reject(new Error("Bridge has been destroyed."));
     }
-    this.wopiRequests.clear();
+    this.collaborationRequests.clear();
     if (typeof window !== "undefined") {
       window.removeEventListener("message", this._messageHandler);
     }
@@ -1055,26 +1521,28 @@ var Bridge = class {
       const initData = data;
       this._initResolve({ context: initData.context, token: initData.token });
     }
-    if (data.type === "verentis:backend:response") {
+    if (data.type === "verentis:wopi:response") {
       if (!this._hostOrigin || data.sessionId !== this.sessionId) return;
-      const pending = this.backendRequests.get(data.requestId);
+      const pending = this.wopiRequests.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);
+      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:wopi:response") {
+    if (data.type === "verentis:collaboration:response") {
       if (!this._hostOrigin || data.sessionId !== this.sessionId) return;
-      const pending = this.wopiRequests.get(data.requestId);
+      const pending = this.collaborationRequests.get(data.requestId);
       if (!pending) return;
       clearTimeout(pending.timer);
-      this.wopiRequests.delete(data.requestId);
+      this.collaborationRequests.delete(data.requestId);
       if (data.error || !Object.hasOwn(data, "result"))
-        pending.reject(new Error("Collaboration authorization is unavailable."));
+        pending.reject(new NativeCollaborationError(
+          typeof data.error === "string" ? data.error.slice(0, 500) : "Native collaboration is unavailable.",
+          typeof data.code === "string" ? data.code.slice(0, 64) : "unavailable"
+        ));
       else pending.resolve(data.result);
       return;
     }
@@ -1082,6 +1550,10 @@ var Bridge = class {
       void this.invokeAction(data);
       return;
     }
+    if (data.type === "verentis:host:message") {
+      void this.receiveHostMessage(data);
+      return;
+    }
     const typeListeners = this.listeners.get(data.type);
     if (typeListeners) {
       for (const listener of typeListeners) {
@@ -1093,16 +1565,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
@@ -1131,24 +1605,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,
@@ -1182,6 +1639,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;
@@ -1211,8 +1688,11 @@ var VerentisClient = class {
   installations;
   resources;
   settings;
+  email;
+  business;
   context;
   bridge;
+  collaboration;
   _auth;
   _http;
   _ready;
@@ -1221,11 +1701,13 @@ var VerentisClient = class {
     const environment = detectEnvironment();
     if (environment === "iframe" && !options?.auth) {
       this.bridge = new Bridge();
+      this.collaboration = new NativeCollaborationClient(this.bridge);
       const bridgeAuth = new BridgeAuth("*");
       this._auth = bridgeAuth;
       this._ready = this.initFromBridge(bridgeAuth);
     } else {
       this.bridge = null;
+      this.collaboration = new NativeCollaborationClient(null);
       this._auth = createAuthStrategy(options);
       const apiUrl = options?.apiUrl;
       if (!apiUrl) {
@@ -1242,6 +1724,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;
     }
@@ -1254,6 +1738,14 @@ var VerentisClient = class {
   whenReady() {
     return this._ready;
   }
+  /**
+   * The current `Authorization` header value, refreshed when near expiry.
+   * Forward it to the app's own backend, which exchanges it at Security's
+   * `/connect/token` (RFC 8693) as the installation's confidential client.
+   */
+  getAuthorizationHeader() {
+    return this._auth.getAuthHeader();
+  }
   /** Clean up resources (timers, event listeners) */
   destroy() {
     this._auth.destroy?.();
@@ -1266,6 +1758,10 @@ var VerentisClient = class {
     bridgeAuth.setHostOrigin(hostOrigin);
     bridgeAuth.setToken(token);
     this.context.setFromAppContext(context);
+    this.context.setGrants(token.grants);
+    this.bridge.on("verentis:token:refreshed", (message) => {
+      if (message.type === "verentis:token:refreshed") this.context.setGrants(message.token?.grants);
+    });
     const http = new HttpTransport(
       context.apiUrl,
       bridgeAuth,
@@ -1278,6 +1774,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() {
@@ -1330,11 +1828,49 @@ function stripParams(mime) {
   return idx === -1 ? mime.trim() : mime.slice(0, idx).trim();
 }
 
+// src/collaboration/lifecycle.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function exactHttpsOrigin(value) {
+  if (typeof value !== "string" || value.length > 256)
+    throw new Error("Invalid framing origin.");
+  const origin = new URL(value);
+  if (origin.protocol !== "https:" || origin.origin !== value || origin.href !== `${value}/` || !/^[a-z0-9-]+(?:\.[a-z0-9-]+)*$/.test(origin.hostname))
+    throw new Error("Invalid framing origin.");
+  return value;
+}
+function isTrustedMessage(event, source, origin) {
+  return Boolean(source && origin && event.source === source && event.origin === origin);
+}
+function validateCollaborationDocument(value, context, now = Date.now()) {
+  const branch = context.file?.branch;
+  const node = context.file?.nodeId;
+  const workspace = context.workspace?.id;
+  if (!branch || !node || !workspace || !isRecord(value) || value.nodeId !== node || value.workspaceId !== workspace || value.branch !== branch.trim().toLowerCase() || typeof value.fileId !== "string" || !/^[a-f0-9]{32}$/.test(value.fileId) || typeof value.sessionId !== "string" || !/^(?:[a-f0-9]{32}|[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12})$/.test(value.sessionId) || typeof value.accessTokenTtl !== "number" || !Number.isSafeInteger(value.accessTokenTtl) || value.accessTokenTtl <= now || typeof value.name !== "string" || !value.name || value.name.length > 1024 || typeof value.readOnly !== "boolean")
+    throw new Error("Invalid live launch.");
+  return {
+    sessionId: value.sessionId,
+    workspaceId: value.workspaceId,
+    branch: value.branch,
+    nodeId: value.nodeId,
+    fileId: value.fileId,
+    name: value.name,
+    readOnly: value.readOnly,
+    accessTokenTtl: value.accessTokenTtl
+  };
+}
+function isDurableSaveConfirmed(result, request, currentGeneration, editorModified) {
+  if (!isRecord(request) || !isRecord(result) || !isRecord(result.receipt))
+    return false;
+  return editorModified === false && result.state === "ready" && result.continuationAvailable !== true && Number.isSafeInteger(currentGeneration) && currentGeneration >= 0 && currentGeneration === request.generation && typeof request.correlation === "string" && request.correlation.length > 0 && result.receipt.generation === request.generation && result.receipt.correlation === request.correlation && typeof result.receipt.revision === "string" && result.receipt.revision.length > 0;
+}
+
 // src/index.ts
 function createVerentisClient(options) {
   return new VerentisClient(options);
 }
 
-export { ApiKeyAuth, Bridge, BridgeAuth, ContextModule, EnginesModule, ExecutionsModule, FilesModule, HttpTransport, InstallationsModule, ResourcesModule, SettingsModule, TokenAuth, VerentisClient, createVerentisClient, findBestMatch, isHeaderAction, isTerminalStatus, matchMimeType };
+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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map