@verentis/sdk 0.1.1 → 0.2.3

package/README.md

@@ -10,6 +10,53 @@ npm install @verentis/sdk
 
 ## Quick Start
 
+### Hosted header actions (SDK 0.2)
+
+Applications register buttons after `await client.whenReady()`. The workspace owns their
+presentation; handlers execute inside the application with its existing delegated token.
+
+```ts
+const save = client.bridge!.registerAction({
+  id: 'document.save',
+  label: 'Save',
+  icon: 'lucide:save',
+  variant: 'default',
+  scopes: ['node.file.read', 'node.node.create', 'node.node.update', 'node.journal.create'],
+  enabled: false,
+}, async () => {
+  await persistDocument()
+})
+
+// Pass the complete descriptor when document state changes.
+save.update({ id: 'document.save', label: 'Save', scopes: [
+  'node.file.read', 'node.node.create', 'node.node.update', 'node.journal.create',
+], enabled: true })
+save.dispose()
+```
+
+Use stable app-local IDs, up to 16 actions, Lucide icon identifiers, and explicit `scopes`
+(`[]` for client-only operations). `enabled`, `visible`, `busy`, and `disabledReason` communicate
+state without serializing handlers. The host checks required scopes against the delegated grant;
+registration never expands permissions. Throw on failure so the host can display it.
+
+For clipboard actions, set `kind: 'clipboard'` and return `{ clipboardText: source }`. The host starts
+the clipboard write in the user's click gesture while awaiting the text, preserving browser
+user-activation requirements. For operations that navigate after completion, return
+`{ navigate: { path: '/applications', newTab: false } }` instead of navigating before the result.
+
+The protocol uses session-bound `verentis:actions:set`, `verentis:action:invoke`, and
+`verentis:action:result` messages. Reload/navigation disposes pending work; an unanswered invocation
+times out as **outcome unknown**, never an automatic retry. App handlers must not report successful
+completion before their mutation finishes.
+
+Migrated actions are hosted only: there is no legacy-host or standalone-toolbar fallback.
+Fullscreen apps can hide the host header only when they register no actions. Keep specialized
+controls (zoom, editing modes, contextual forms) within the app.
+
+Release the 0.2 SDK before deploying apps that require `^0.2.0`, together with the matching host.
+Local sibling-repository development can link the built SDK; published applications must resolve
+the released SDK from npm.
+
 ### Standalone mode (local development)
 
 ```ts

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;
   }
 };
 
@@ -745,23 +774,41 @@ var SettingsModule = class {
   }
 };
 
+// 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();
   /** Post `verentis:ready` to the host to start the handshake */
   sendReady(capabilities) {
     console.info("[Verentis SDK] Sending verentis:ready to host");
@@ -774,6 +821,12 @@ var Bridge = class {
   }
   /** 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 +835,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 +870,91 @@ 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."));
+      }
+    });
+  }
+  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 +968,17 @@ 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();
     if (typeof window !== "undefined") {
       window.removeEventListener("message", this._messageHandler);
     }
@@ -837,9 +986,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 +1004,22 @@ 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:action:invoke") {
+      void this.invokeAction(data);
+      return;
+    }
     const typeListeners = this.listeners.get(data.type);
     if (typeListeners) {
       for (const listener of typeListeners) {
@@ -1029,7 +1201,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(
@@ -1116,6 +1288,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