objectiveai-viewer-sdk 2.0.5

package/README.md

@@ -0,0 +1,14 @@
+# objectiveai-viewer-sdk
+
+Plugin SDK for the [ObjectiveAI](https://objectiveai.dev) viewer. A thin TypeScript shim that lets plugin authors subscribe to events emitted by the host viewer from inside their iframe-mounted UI bundle, with the same `listen` surface as `@tauri-apps/api`.
+
+Production context (loaded inside the host viewer): the plugin's `index.html` runs inside an `<iframe sandbox>` pointed at `plugin://localhost/<repo>/`. `window.parent` is the host viewer's React app. `listen()` registers a callback for incoming `{kind: 'plugin-event', type, value}` messages forwarded by the bridge.
+
+Dev context (plugin author runs their own Tauri shell standalone): `window.parent === window` (no host). `listen()` falls through to `@tauri-apps/api`'s `listen`.
+
+The plugin author writes the same code in both contexts.
+
+## Links
+
+- Homepage: <https://objectiveai.dev>
+- Repository: <https://github.com/ObjectiveAI/objectiveai>

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * objectiveai-viewer-sdk
+ *
+ * Thin TypeScript shim that lets plugin authors subscribe to events
+ * emitted by the host viewer from inside their iframe-mounted UI
+ * bundle, with the same `listen` surface as `@tauri-apps/api`.
+ *
+ * Production context (loaded inside the host viewer):
+ *   - The plugin's `index.html` runs inside an `<iframe sandbox>`
+ *     pointed at `plugin://localhost/<repo>/`.
+ *   - `window.parent` is the host viewer's React app.
+ *   - `listen()` registers a callback for incoming
+ *     `{kind: 'plugin-event', type, value}` messages forwarded by the
+ *     bridge from the Rust-side `Event::Plugin` emissions.
+ *
+ * Dev context (plugin author runs their own Tauri shell standalone):
+ *   - `window.parent === window` (no host).
+ *   - `listen()` falls through to `@tauri-apps/api`'s `listen`.
+ *
+ * The plugin author writes the same code in both contexts.
+ */
+/**
+ * Register a handler for incoming plugin events. Returns an
+ * unsubscribe function. In iframe context the events come from the
+ * host's bridge; in standalone-dev context they come from
+ * `@tauri-apps/api`'s `listen`.
+ *
+ * `type` matches the `type` field of the `Event` emitted by the
+ * Rust backend — the string the plugin author registered in their
+ * manifest's `viewer_routes` entry.
+ */
+export declare function listen<T = unknown>(type: string, handler: (value: T) => void): () => void;
+/** Internal-use: clear in-flight state. Exposed for tests only.
+ * Note: the module-level `message` event listener stays attached —
+ * removing/re-attaching it would just register a duplicate. The
+ * listeners map is what carries per-test state. */
+export declare function __resetForTests(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAsCH;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,CAAC,GAAG,OAAO,EAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAC1B,MAAM,IAAI,CAyCZ;AAED;;;mDAGmD;AACnD,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}

package/dist/index.js

@@ -0,0 +1,116 @@
+/**
+ * objectiveai-viewer-sdk
+ *
+ * Thin TypeScript shim that lets plugin authors subscribe to events
+ * emitted by the host viewer from inside their iframe-mounted UI
+ * bundle, with the same `listen` surface as `@tauri-apps/api`.
+ *
+ * Production context (loaded inside the host viewer):
+ *   - The plugin's `index.html` runs inside an `<iframe sandbox>`
+ *     pointed at `plugin://localhost/<repo>/`.
+ *   - `window.parent` is the host viewer's React app.
+ *   - `listen()` registers a callback for incoming
+ *     `{kind: 'plugin-event', type, value}` messages forwarded by the
+ *     bridge from the Rust-side `Event::Plugin` emissions.
+ *
+ * Dev context (plugin author runs their own Tauri shell standalone):
+ *   - `window.parent === window` (no host).
+ *   - `listen()` falls through to `@tauri-apps/api`'s `listen`.
+ *
+ * The plugin author writes the same code in both contexts.
+ */
+/** True when running inside an iframe in the host viewer. */
+function isInIframe() {
+    return typeof window !== "undefined" && window.parent !== window;
+}
+const listeners = new Map();
+let messageHandlerAttached = false;
+function attachMessageHandler() {
+    if (messageHandlerAttached)
+        return;
+    if (typeof window === "undefined")
+        return;
+    window.addEventListener("message", (event) => {
+        const msg = event.data;
+        if (!msg || typeof msg !== "object")
+            return;
+        if (msg.kind !== "plugin-event")
+            return;
+        const set = listeners.get(msg.type);
+        if (!set)
+            return;
+        for (const fn of set) {
+            try {
+                fn(msg.value);
+            }
+            catch (e) {
+                // Don't let one handler take down the others.
+                // eslint-disable-next-line no-console
+                console.error("objectiveai-viewer-sdk listener threw:", e);
+            }
+        }
+    });
+    messageHandlerAttached = true;
+}
+/**
+ * Register a handler for incoming plugin events. Returns an
+ * unsubscribe function. In iframe context the events come from the
+ * host's bridge; in standalone-dev context they come from
+ * `@tauri-apps/api`'s `listen`.
+ *
+ * `type` matches the `type` field of the `Event` emitted by the
+ * Rust backend — the string the plugin author registered in their
+ * manifest's `viewer_routes` entry.
+ */
+export function listen(type, handler) {
+    if (!isInIframe()) {
+        // Standalone dev mode: register via @tauri-apps/api.
+        let unlisten = null;
+        let cancelled = false;
+        void (async () => {
+            try {
+                const mod = await import("@tauri-apps/api/event");
+                if (cancelled)
+                    return;
+                const u = await mod.listen(`plugin-${type}`, (e) => handler(e.payload?.value));
+                if (cancelled) {
+                    u();
+                }
+                else {
+                    unlisten = u;
+                }
+            }
+            catch {
+                // eslint-disable-next-line no-console
+                console.warn(`objectiveai-viewer-sdk: listen('${type}') called outside an iframe and ` +
+                    `@tauri-apps/api is unavailable; events will not fire.`);
+            }
+        })();
+        return () => {
+            cancelled = true;
+            if (unlisten)
+                unlisten();
+        };
+    }
+    attachMessageHandler();
+    const set = listeners.get(type) ?? new Set();
+    const fn = (value) => handler(value);
+    set.add(fn);
+    listeners.set(type, set);
+    return () => {
+        const s = listeners.get(type);
+        if (!s)
+            return;
+        s.delete(fn);
+        if (s.size === 0)
+            listeners.delete(type);
+    };
+}
+/** Internal-use: clear in-flight state. Exposed for tests only.
+ * Note: the module-level `message` event listener stays attached —
+ * removing/re-attaching it would just register a duplicate. The
+ * listeners map is what carries per-test state. */
+export function __resetForTests() {
+    listeners.clear();
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "objectiveai-viewer-sdk",
+  "version": "2.0.5",
+  "description": "Plugin SDK for the ObjectiveAI viewer: typed iframe-bridge for receiving host events.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "shx rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ObjectiveAI/objectiveai.git"
+  },
+  "homepage": "https://objectiveai.dev",
+  "author": {
+    "name": "ObjectiveAI",
+    "email": "admin@objectiveai.dev",
+    "url": "https://objectiveai.dev"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "objectiveai",
+    "viewer",
+    "plugin",
+    "sdk"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "jsdom": "^29.1.1",
+    "shx": "^0.4.0",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.5"
+  }
+}