@opentabs-dev/plugin-sdk 0.0.12 → 0.0.14

package/dist/errors.d.ts

@@ -1,3 +1,11 @@
+/** Standard error categories for structured error metadata. */
+export type ErrorCategory = 'auth' | 'rate_limit' | 'not_found' | 'validation' | 'internal' | 'timeout';
+/** Optional structured metadata for ToolError. */
+export interface ToolErrorOptions {
+    retryable?: boolean;
+    retryAfterMs?: number;
+    category?: ErrorCategory;
+}
 /**
  * Typed error for tool handlers — the platform catches these
  * and returns structured MCP error responses.
@@ -5,8 +13,26 @@
 export declare class ToolError extends Error {
     /** Machine-readable error code (e.g., 'CHANNEL_NOT_FOUND') */
     readonly code: string;
+    /** Whether this error is retryable (defaults to false). */
+    readonly retryable: boolean;
+    /** Suggested delay before retrying, in milliseconds. */
+    readonly retryAfterMs: number | undefined;
+    /** Error category for structured error classification. */
+    readonly category: ErrorCategory | undefined;
     constructor(message: string, 
     /** Machine-readable error code (e.g., 'CHANNEL_NOT_FOUND') */
-    code: string);
+    code: string, opts?: ToolErrorOptions);
+    /** Authentication or authorization error (not retryable). */
+    static auth(message: string): ToolError;
+    /** Resource not found (not retryable). Accepts an optional domain-specific code. */
+    static notFound(message: string, code?: string): ToolError;
+    /** Rate limited (retryable). Accepts an optional retry delay in milliseconds. */
+    static rateLimited(message: string, retryAfterMs?: number): ToolError;
+    /** Input validation error (not retryable). */
+    static validation(message: string): ToolError;
+    /** Operation timed out (retryable). */
+    static timeout(message: string): ToolError;
+    /** Internal/unexpected error (not retryable). */
+    static internal(message: string): ToolError;
 }
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAGhC,8DAA8D;aAC9C,IAAI,EAAE,MAAM;gBAF5B,OAAO,EAAE,MAAM;IACf,8DAA8D;IAC9C,IAAI,EAAE,MAAM;CAK/B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAIA,+DAA+D;AAC/D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,GAAG,YAAY,GAAG,UAAU,GAAG,SAAS,CAAC;AAExG,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED;;;GAGG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAUhC,8DAA8D;aAC9C,IAAI,EAAE,MAAM;IAV9B,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,CAAC;gBAG3C,OAAO,EAAE,MAAM;IACf,8DAA8D;IAC9C,IAAI,EAAE,MAAM,EAC5B,IAAI,CAAC,EAAE,gBAAgB;IASzB,6DAA6D;IAC7D,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS;IAIvC,oFAAoF;IACpF,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS;IAI1D,iFAAiF;IACjF,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS;IAIrE,8CAA8C;IAC9C,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS;IAI7C,uCAAuC;IACvC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS;IAI1C,iDAAiD;IACjD,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS;CAG5C"}

package/dist/errors.js

@@ -7,12 +7,45 @@
  */
 export class ToolError extends Error {
     code;
+    /** Whether this error is retryable (defaults to false). */
+    retryable;
+    /** Suggested delay before retrying, in milliseconds. */
+    retryAfterMs;
+    /** Error category for structured error classification. */
+    category;
     constructor(message, 
     /** Machine-readable error code (e.g., 'CHANNEL_NOT_FOUND') */
-    code) {
+    code, opts) {
         super(message);
         this.code = code;
         this.name = 'ToolError';
+        this.retryable = opts?.retryable ?? false;
+        this.retryAfterMs = opts?.retryAfterMs;
+        this.category = opts?.category;
+    }
+    /** Authentication or authorization error (not retryable). */
+    static auth(message) {
+        return new ToolError(message, 'AUTH_ERROR', { category: 'auth', retryable: false });
+    }
+    /** Resource not found (not retryable). Accepts an optional domain-specific code. */
+    static notFound(message, code) {
+        return new ToolError(message, code ?? 'NOT_FOUND', { category: 'not_found', retryable: false });
+    }
+    /** Rate limited (retryable). Accepts an optional retry delay in milliseconds. */
+    static rateLimited(message, retryAfterMs) {
+        return new ToolError(message, 'RATE_LIMITED', { category: 'rate_limit', retryable: true, retryAfterMs });
+    }
+    /** Input validation error (not retryable). */
+    static validation(message) {
+        return new ToolError(message, 'VALIDATION_ERROR', { category: 'validation', retryable: false });
+    }
+    /** Operation timed out (retryable). */
+    static timeout(message) {
+        return new ToolError(message, 'TIMEOUT', { category: 'timeout', retryable: true });
+    }
+    /** Internal/unexpected error (not retryable). */
+    static internal(message) {
+        return new ToolError(message, 'INTERNAL_ERROR', { category: 'internal', retryable: false });
     }
 }
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,iCAAiC;AACjC,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAIhB;IAHlB,YACE,OAAe;IACf,8DAA8D;IAC9C,IAAY;QAE5B,KAAK,CAAC,OAAO,CAAC,CAAC;QAFC,SAAI,GAAJ,IAAI,CAAQ;QAG5B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,iCAAiC;AACjC,8EAA8E;AAY9E;;;GAGG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAWhB;IAVlB,2DAA2D;IAClD,SAAS,CAAU;IAC5B,wDAAwD;IAC/C,YAAY,CAAqB;IAC1C,0DAA0D;IACjD,QAAQ,CAA4B;IAE7C,YACE,OAAe;IACf,8DAA8D;IAC9C,IAAY,EAC5B,IAAuB;QAEvB,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAQ;QAI5B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,SAAS,GAAG,IAAI,EAAE,SAAS,IAAI,KAAK,CAAC;QAC1C,IAAI,CAAC,YAAY,GAAG,IAAI,EAAE,YAAY,CAAC;QACvC,IAAI,CAAC,QAAQ,GAAG,IAAI,EAAE,QAAQ,CAAC;IACjC,CAAC;IAED,6DAA6D;IAC7D,MAAM,CAAC,IAAI,CAAC,OAAe;QACzB,OAAO,IAAI,SAAS,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;IACtF,CAAC;IAED,oFAAoF;IACpF,MAAM,CAAC,QAAQ,CAAC,OAAe,EAAE,IAAa;QAC5C,OAAO,IAAI,SAAS,CAAC,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;IAClG,CAAC;IAED,iFAAiF;IACjF,MAAM,CAAC,WAAW,CAAC,OAAe,EAAE,YAAqB;QACvD,OAAO,IAAI,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;IAC3G,CAAC;IAED,8CAA8C;IAC9C,MAAM,CAAC,UAAU,CAAC,OAAe;QAC/B,OAAO,IAAI,SAAS,CAAC,OAAO,EAAE,kBAAkB,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;IAClG,CAAC;IAED,uCAAuC;IACvC,MAAM,CAAC,OAAO,CAAC,OAAe;QAC5B,OAAO,IAAI,SAAS,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACrF,CAAC;IAED,iDAAiD;IACjD,MAAM,CAAC,QAAQ,CAAC,OAAe;QAC7B,OAAO,IAAI,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9F,CAAC;CACF"}

package/dist/index.d.ts

@@ -107,6 +107,7 @@ export declare abstract class OpenTabsPlugin {
     onToolInvocationEnd?(toolName: string, success: boolean, durationMs: number): void;
 }
 export { ToolError } from './errors.js';
+export type { ErrorCategory, ToolErrorOptions } from './errors.js';
 export { waitForSelector, waitForSelectorRemoval, querySelectorAll, getTextContent, observeDOM } from './dom.js';
 export type { WaitForSelectorOptions, ObserveDOMOptions } from './dom.js';
 export { fetchFromPage, fetchJSON, postJSON } from './fetch.js';
@@ -115,4 +116,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;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"}
+{"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;AAGxC,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.12",
+  "version": "0.0.14",
   "type": "module",
   "exports": {
     ".": {
@@ -20,7 +20,7 @@
     "generate:icons": "bun scripts/generate-icon-names.ts"
   },
   "dependencies": {
-    "@opentabs-dev/shared": "^0.0.12"
+    "@opentabs-dev/shared": "^0.0.14"
   },
   "peerDependencies": {
     "zod": "^4.0.0"