@opentabs-dev/plugin-sdk 0.0.11 → 0.0.13

package/dist/index.d.ts

@@ -62,6 +62,49 @@ export declare abstract class OpenTabsPlugin {
      * persistent side effects can omit this.
      */
     teardown?(): void;
+    /**
+     * Called once after the adapter is registered on
+     * `globalThis.__openTabs.adapters`. Use for setting up page-level event
+     * listeners, observers, or other resources that should exist for the
+     * adapter's lifetime.
+     */
+    onActivate?(): void;
+    /**
+     * Called when the adapter is being removed — either before `teardown()`
+     * on plugin update, or when the tab navigates away from a matching URL.
+     * Use for cleanup of resources set up in `onActivate`.
+     *
+     * Ordering: `onDeactivate` fires before `teardown` when both are defined.
+     */
+    onDeactivate?(): void;
+    /**
+     * Called on in-page URL changes (pushState, replaceState, popstate,
+     * hashchange). Runs in the page context. If the plugin does not
+     * implement this method, no navigation listeners are set up.
+     *
+     * @param url — the new URL after the navigation (window.location.href)
+     */
+    onNavigate?(url: string): void;
+    /**
+     * Called before each `tool.handle()` execution. Runs in the page context.
+     * Receives the tool name (unprefixed, e.g. "send_message" not
+     * "slack_send_message"). Errors thrown here are caught and logged — they
+     * do not prevent tool execution.
+     *
+     * @param toolName — the unprefixed tool name
+     */
+    onToolInvocationStart?(toolName: string): void;
+    /**
+     * Called after each `tool.handle()` completes, whether it succeeded or
+     * threw. Receives the tool name, a boolean indicating success, and the
+     * wall-clock duration in milliseconds. Errors thrown here are caught and
+     * logged.
+     *
+     * @param toolName — the unprefixed tool name
+     * @param success — true if handle() resolved, false if it threw
+     * @param durationMs — wall-clock time of tool.handle() in milliseconds
+     */
+    onToolInvocationEnd?(toolName: string, success: boolean, durationMs: number): void;
 }
 export { ToolError } from './errors.js';
 export { waitForSelector, waitForSelectorRemoval, querySelectorAll, getTextContent, observeDOM } from './dom.js';
@@ -72,4 +115,6 @@ export { retry, sleep, waitUntil } from './timing.js';
 export type { RetryOptions, WaitUntilOptions } from './timing.js';
 export { getLocalStorage, setLocalStorage, getSessionStorage, getCookie } from './storage.js';
 export { getPageGlobal, getCurrentUrl, getPageTitle } from './page-state.js';
+export { log, _setLogTransport } from './log.js';
+export type { LogLevel, LogEntry, LogTransport } from './log.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -35,4 +35,8 @@ export { getLocalStorage, setLocalStorage, getSessionStorage, getCookie } from '
 // SDK utilities — Page State
 // ---------------------------------------------------------------------------
 export { getPageGlobal, getCurrentUrl, getPageTitle } from './page-state.js';
+// ---------------------------------------------------------------------------
+// SDK utilities — Logging
+// ---------------------------------------------------------------------------
+export { log, _setLogTransport } from './log.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,8EAA8E;AAC9E,gEAAgE;AAChE,8EAA8E;AAE9E,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1G,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AA0B3D,4EAA4E;AAC5E,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,MAAuC,EACN,EAAE,CAAC,MAAM,CAAC;AAE7C;;;GAGG;AACH,MAAM,OAAgB,cAAc;CAoCnC;AAED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGjH,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGhE,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGtD,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9F,8EAA8E;AAC9E,6BAA6B;AAC7B,8EAA8E;AAE9E,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,8EAA8E;AAC9E,gEAAgE;AAChE,8EAA8E;AAE9E,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1G,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AA0B3D,4EAA4E;AAC5E,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,MAAuC,EACN,EAAE,CAAC,MAAM,CAAC;AAE7C;;;GAGG;AACH,MAAM,OAAgB,cAAc;CA+EnC;AAED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGjH,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGhE,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGtD,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9F,8EAA8E;AAC9E,6BAA6B;AAC7B,8EAA8E;AAE9E,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE7E,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E,OAAO,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC"}

package/dist/log.d.ts

@@ -0,0 +1,41 @@
+/** Log levels matching the MCP LoggingLevel enum */
+type LogLevel = 'debug' | 'info' | 'warning' | 'error';
+/** A single structured log entry */
+interface LogEntry {
+    level: LogLevel;
+    message: string;
+    data: unknown[];
+    ts: string;
+}
+/** Transport function signature — receives a log entry for delivery */
+type LogTransport = (entry: LogEntry) => void;
+/**
+ * @internal
+ * Replaces the active log transport. Called by the adapter IIFE wrapper to
+ * route log entries to the Chrome extension instead of the console.
+ * Returns a function that restores the default transport.
+ */
+declare const _setLogTransport: (transport: LogTransport) => (() => void);
+/**
+ * Structured logging namespace for plugin tool handlers and lifecycle hooks.
+ *
+ * Log entries are routed to the MCP server when running inside the adapter
+ * runtime, or to the browser console when running standalone (unit tests, etc.).
+ *
+ * @example
+ * ```ts
+ * import { log } from '@opentabs-dev/plugin-sdk';
+ *
+ * log.info('Fetching channels', { workspaceId });
+ * log.error('Request failed', error);
+ * ```
+ */
+declare const log: Readonly<{
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}>;
+export { _setLogTransport, log };
+export type { LogEntry, LogLevel, LogTransport };
+//# sourceMappingURL=log.d.ts.map

package/dist/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAIA,oDAAoD;AACpD,KAAK,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAEvD,oCAAoC;AACpC,UAAU,QAAQ;IAChB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,uEAAuE;AACvE,KAAK,YAAY,GAAG,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;AA0F9C;;;;;GAKG;AACH,QAAA,MAAM,gBAAgB,GAAI,WAAW,YAAY,KAAG,CAAC,MAAM,IAAI,CAK9D,CAAC;AAkBF;;;;;;;;;;;;;GAaG;AACH,QAAA,MAAM,GAAG;qBAxBG,MAAM,WAAW,OAAO,EAAE,KAAG,IAAI;oBAAjC,MAAM,WAAW,OAAO,EAAE,KAAG,IAAI;oBAAjC,MAAM,WAAW,OAAO,EAAE,KAAG,IAAI;qBAAjC,MAAM,WAAW,OAAO,EAAE,KAAG,IAAI;EA6B3C,CAAC;AAiBH,OAAO,EAAE,gBAAgB,EAAE,GAAG,EAAE,CAAC;AACjC,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC"}

package/dist/log.js

@@ -0,0 +1,144 @@
+// ---------------------------------------------------------------------------
+// Structured logging API for plugin authors
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Safe serialization — entries travel over postMessage / WebSocket
+// ---------------------------------------------------------------------------
+const MAX_DATA_LENGTH = 10;
+const MAX_STRING_LENGTH = 4096;
+/**
+ * Produces a JSON-safe representation of a single argument.
+ * Handles circular references, DOM nodes, functions, and other
+ * non-serializable values without throwing.
+ */
+const safeSerializeArg = (value) => {
+    if (value === null || value === undefined)
+        return value;
+    const type = typeof value;
+    if (type === 'boolean' || type === 'number')
+        return value;
+    if (type === 'string') {
+        return value.length > MAX_STRING_LENGTH ? value.slice(0, MAX_STRING_LENGTH) + '…' : value;
+    }
+    if (type === 'function')
+        return `[Function: ${value.name || 'anonymous'}]`;
+    if (type === 'symbol')
+        return `[Symbol: ${value.description ?? ''}]`;
+    if (type === 'bigint')
+        return `[BigInt: ${value.toString()}]`;
+    // DOM nodes
+    if (typeof value.nodeType === 'number') {
+        const node = value;
+        const className = node.className ? `.${node.className.split(' ')[0] ?? ''}` : '';
+        return `[${node.nodeName ?? 'Node'}${node.id ? `#${node.id}` : ''}${className}]`;
+    }
+    // Errors
+    if (value instanceof Error) {
+        return { name: value.name, message: value.message, stack: value.stack };
+    }
+    // Fallback: attempt JSON round-trip to strip non-serializable properties
+    try {
+        const seen = new WeakSet();
+        const json = JSON.stringify(value, (_key, v) => {
+            if (typeof v === 'object' && v !== null) {
+                if (seen.has(v))
+                    return '[Circular]';
+                seen.add(v);
+            }
+            if (typeof v === 'function')
+                return `[Function: ${v.name || 'anonymous'}]`;
+            if (typeof v === 'bigint')
+                return `[BigInt: ${v.toString()}]`;
+            if (typeof v === 'symbol')
+                return `[Symbol: ${v.description ?? ''}]`;
+            return v;
+        });
+        return JSON.parse(json);
+    }
+    catch {
+        return `[Unserializable: ${typeof value}]`;
+    }
+};
+/**
+ * Safely serializes an array of log arguments into a postMessage/JSON-safe form.
+ * Truncates to MAX_DATA_LENGTH items.
+ */
+const safeSerialize = (args) => {
+    const capped = args.length > MAX_DATA_LENGTH ? args.slice(0, MAX_DATA_LENGTH) : args;
+    return capped.map(safeSerializeArg);
+};
+// ---------------------------------------------------------------------------
+// Default transport — console fallback
+// ---------------------------------------------------------------------------
+const CONSOLE_METHODS = {
+    debug: 'debug',
+    info: 'info',
+    warning: 'warn',
+    error: 'error',
+};
+const defaultTransport = (entry) => {
+    const method = CONSOLE_METHODS[entry.level];
+    console[method](`[sdk.log] ${entry.message}`, ...entry.data);
+};
+// ---------------------------------------------------------------------------
+// Transport slot — replaced by the adapter runtime (US-002)
+// ---------------------------------------------------------------------------
+let activeTransport = defaultTransport;
+/**
+ * @internal
+ * Replaces the active log transport. Called by the adapter IIFE wrapper to
+ * route log entries to the Chrome extension instead of the console.
+ * Returns a function that restores the default transport.
+ */
+const _setLogTransport = (transport) => {
+    activeTransport = transport;
+    return () => {
+        activeTransport = defaultTransport;
+    };
+};
+// ---------------------------------------------------------------------------
+// Public API — sdk.log namespace
+// ---------------------------------------------------------------------------
+const makeLogMethod = (level) => (message, ...args) => {
+    const entry = {
+        level,
+        message,
+        data: safeSerialize(args),
+        ts: new Date().toISOString(),
+    };
+    activeTransport(entry);
+};
+/**
+ * Structured logging namespace for plugin tool handlers and lifecycle hooks.
+ *
+ * Log entries are routed to the MCP server when running inside the adapter
+ * runtime, or to the browser console when running standalone (unit tests, etc.).
+ *
+ * @example
+ * ```ts
+ * import { log } from '@opentabs-dev/plugin-sdk';
+ *
+ * log.info('Fetching channels', { workspaceId });
+ * log.error('Request failed', error);
+ * ```
+ */
+const log = Object.freeze({
+    debug: makeLogMethod('debug'),
+    info: makeLogMethod('info'),
+    warn: makeLogMethod('warning'),
+    error: makeLogMethod('error'),
+});
+// ---------------------------------------------------------------------------
+// Runtime registration — allows the adapter IIFE wrapper to call
+// _setLogTransport without an explicit import (which would fail if the
+// plugin's installed SDK version predates the log module).
+// ---------------------------------------------------------------------------
+const ot = (globalThis.__openTabs ?? {});
+globalThis.__openTabs = ot;
+ot._setLogTransport = _setLogTransport;
+ot.log = log;
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+export { _setLogTransport, log };
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentabs-dev/plugin-sdk",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "type": "module",
   "exports": {
     ".": {
@@ -20,7 +20,7 @@
     "generate:icons": "bun scripts/generate-icon-names.ts"
   },
   "dependencies": {
-    "@opentabs-dev/shared": "^0.0.11"
+    "@opentabs-dev/shared": "^0.0.13"
   },
   "peerDependencies": {
     "zod": "^4.0.0"