@verentis/sdk 0.1.1 → 0.2.2

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

@@ -745,6 +745,13 @@ 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();
@@ -753,6 +760,9 @@ var Bridge = class {
   _hostOrigin = null;
   _messageHandler;
   _destroyed = false;
+  sessionId = null;
+  actions = /* @__PURE__ */ new Map();
+  requests = /* @__PURE__ */ new Set();
   constructor() {
     this._initPromise = new Promise((resolve) => {
       this._initResolve = resolve;
@@ -782,6 +792,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 +827,69 @@ var Bridge = class {
   setDirty(isDirty) {
     this.postToHost({ type: "verentis:dirty", version: 1, isDirty });
   }
+  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,6 +903,8 @@ var Bridge = class {
   /** Clean up event listeners */
   destroy() {
     this._destroyed = true;
+    this.actions.clear();
+    this.requests.clear();
     this.listeners.clear();
     if (typeof window !== "undefined") {
       window.removeEventListener("message", this._messageHandler);
@@ -837,9 +913,12 @@ 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 (data.type === "verentis:init") {
+      if (this._hostOrigin) return;
       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 +927,10 @@ var Bridge = class {
       const initData = data;
       this._initResolve({ context: initData.context, token: initData.token });
     }
+    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) {
@@ -1116,6 +1199,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