@xopcai/extension-ui-sdk 0.0.31

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xopcai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@xopcai/extension-ui-sdk",
+  "version": "0.0.31",
+  "description": "Gateway Console extension UI SDK (iframe postMessage client)",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-markdown": "^4.11.0",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "docs": "typedoc --options typedoc.json"
+  }
+}

package/src/client.ts

@@ -0,0 +1,126 @@
+import { Transport } from './transport.js';
+import type { ExtensionClient, StreamHandler, ThemeInfo } from './types.js';
+
+export type CreateExtensionClientOptions = {
+  transport?: Transport;
+};
+
+export function createExtensionClient(options?: CreateExtensionClientOptions): ExtensionClient {
+  const transport = options?.transport ?? new Transport();
+
+  const client: ExtensionClient = {
+    async whenReady() {
+      await transport.ready;
+    },
+
+    theme: {
+      async getTheme() {
+        return transport.request<ThemeInfo>('theme.get');
+      },
+      onThemeChange(handler: (t: ThemeInfo) => void) {
+        return transport.on('theme.changed', (data) => {
+          handler(data as ThemeInfo);
+        });
+      },
+    },
+
+    agent: {
+      async sendMessage(message: string, opts?: { sessionKey?: string; newSession?: boolean }) {
+        return transport.request<{ sessionKey: string }>('agent.sendMessage', {
+          message,
+          sessionKey: opts?.sessionKey,
+          newSession: opts?.newSession,
+        });
+      },
+      onStreamEvent(sessionKey: string, handler: StreamHandler) {
+        transport.emit('agent.subscribe', { sessionKey });
+        const unsub = transport.on(`agent.stream.${sessionKey}`, handler);
+        return () => {
+          transport.emit('agent.unsubscribe', { sessionKey });
+          unsub();
+        };
+      },
+    },
+
+    session: {
+      async listSessions() {
+        return transport.request<unknown[]>('session.list');
+      },
+      async navigateToSession(sessionKey: string) {
+        await transport.request('session.navigate', { sessionKey });
+      },
+    },
+
+    config: {
+      async getExtensionConfig<T = Record<string, unknown>>() {
+        return transport.request<T>('config.get');
+      },
+      async setExtensionConfig(patch: Record<string, unknown>) {
+        await transport.request('config.set', patch);
+      },
+    },
+
+    storage: {
+      async get<T = unknown>(key: string) {
+        return transport.request<T | undefined>('storage.get', { key });
+      },
+      async set(key: string, value: unknown) {
+        await transport.request('storage.set', { key, value });
+      },
+      async remove(key: string) {
+        await transport.request('storage.remove', { key });
+      },
+      async keys() {
+        return transport.request<string[]>('storage.keys');
+      },
+    },
+
+    ui: {
+      resize(height: number) {
+        transport.emit('ui.resize', { height });
+      },
+      async showNotification(options) {
+        await transport.request('ui.notification', options);
+      },
+      closePanel() {
+        transport.emit('ui.closePanel', undefined);
+      },
+      async navigate(path: string) {
+        await transport.request('ui.navigate', { path });
+      },
+      onWidgetResult(handler: (data: unknown) => void) {
+        return transport.on('widget.data', handler);
+      },
+    },
+
+    events: {
+      emit(event: string, data?: unknown) {
+        transport.emit(`ext.${event}`, data);
+      },
+      on(event: string, handler: (data: unknown) => void) {
+        return transport.on(`ext.${event}`, handler);
+      },
+    },
+
+    onDispose(handler: () => void) {
+      return transport.on('panel.dispose', () => {
+        handler();
+      });
+    },
+
+    onDidChangeVisibility(handler: (visible: boolean) => void) {
+      return transport.on('panel.visibility', (data) => {
+        const v =
+          typeof data === 'object' &&
+          data !== null &&
+          'visible' in data &&
+          typeof (data as { visible: unknown }).visible === 'boolean'
+            ? (data as { visible: boolean }).visible
+            : Boolean(data);
+        handler(v);
+      });
+    },
+  };
+
+  return client;
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export { createExtensionClient, type CreateExtensionClientOptions } from './client.js';
+export { Transport, type TransportOptions } from './transport.js';
+export {
+  ExtensionErrorCode,
+  type ExtensionClient,
+  type ExtensionEventMessage,
+  type ExtensionRequest,
+  type ExtensionToHostMessage,
+  type HostEventMessage,
+  type HostInit,
+  type HostResponse,
+  type HostToExtensionMessage,
+  type StreamHandler,
+  type ThemeInfo,
+} from './types.js';

package/src/transport.ts

@@ -0,0 +1,160 @@
+import type {
+  ExtensionEventMessage,
+  ExtensionRequest,
+  HostInit,
+  HostResponse,
+  HostToExtensionMessage,
+} from './types.js';
+
+type PendingRequest = {
+  resolve: (v: unknown) => void;
+  reject: (e: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+};
+
+export type TransportOptions = {
+  timeout?: number;
+};
+
+export class Transport {
+  private extensionId = '';
+  private pending = new Map<string, PendingRequest>();
+  private eventHandlers = new Map<string, Set<(data: unknown) => void>>();
+  private initResolve: ((init: HostInit) => void) | null = null;
+  private initPromise: Promise<HostInit>;
+  private disposed = false;
+  private readonly timeout: number;
+  private requestCounter = 0;
+
+  constructor(options?: TransportOptions) {
+    this.timeout = options?.timeout ?? 10_000;
+    this.initPromise = new Promise<HostInit>((resolve) => {
+      this.initResolve = resolve;
+    });
+    window.addEventListener('message', this.handleMessage);
+  }
+
+  get ready(): Promise<HostInit> {
+    return this.initPromise;
+  }
+
+  get id(): string {
+    return this.extensionId;
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    window.removeEventListener('message', this.handleMessage);
+    for (const [, p] of this.pending) {
+      clearTimeout(p.timer);
+      p.reject(new Error('Transport disposed'));
+    }
+    this.pending.clear();
+    this.eventHandlers.clear();
+  }
+
+  async request<T = unknown>(method: string, params?: unknown): Promise<T> {
+    await this.initPromise;
+    if (this.disposed) {
+      throw new Error('Transport disposed');
+    }
+    const requestId = this.nextRequestId();
+    const message: ExtensionRequest = {
+      source: 'xopc-extension',
+      extensionId: this.extensionId,
+      type: 'request',
+      requestId,
+      method,
+      params,
+    };
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(requestId);
+        reject(new Error(`Request '${method}' timed out after ${this.timeout}ms`));
+      }, this.timeout);
+      this.pending.set(requestId, {
+        resolve: resolve as (v: unknown) => void,
+        reject,
+        timer,
+      });
+      window.parent.postMessage(message, '*');
+    });
+  }
+
+  emit(event: string, data?: unknown): void {
+    if (!this.extensionId || this.disposed) return;
+    const message: ExtensionEventMessage = {
+      source: 'xopc-extension',
+      extensionId: this.extensionId,
+      type: 'event',
+      event,
+      data,
+    };
+    window.parent.postMessage(message, '*');
+  }
+
+  on(event: string, handler: (data: unknown) => void): () => void {
+    let set = this.eventHandlers.get(event);
+    if (!set) {
+      set = new Set();
+      this.eventHandlers.set(event, set);
+    }
+    set.add(handler);
+    return () => {
+      set!.delete(handler);
+      if (set!.size === 0) {
+        this.eventHandlers.delete(event);
+      }
+    };
+  }
+
+  private nextRequestId(): string {
+    this.requestCounter += 1;
+    return `req_${Date.now()}_${this.requestCounter}`;
+  }
+
+  private handleMessage = (event: MessageEvent): void => {
+    if (this.disposed) return;
+    const msg = event.data as HostToExtensionMessage | undefined;
+    if (!msg || msg.source !== 'xopc-host') return;
+
+    switch (msg.type) {
+      case 'init': {
+        this.extensionId = msg.extensionId;
+        this.initResolve?.(msg);
+        this.initResolve = null;
+        return;
+      }
+      case 'response': {
+        const r = msg as HostResponse;
+        const pending = this.pending.get(r.requestId);
+        if (!pending) return;
+        clearTimeout(pending.timer);
+        this.pending.delete(r.requestId);
+        if (r.error) {
+          pending.reject(new Error(r.error.message || `Error ${r.error.code}`));
+        } else {
+          pending.resolve(r.result);
+        }
+        return;
+      }
+      case 'event': {
+        const ev = msg as { event: string; data?: unknown };
+        const handlers = this.eventHandlers.get(ev.event);
+        if (handlers) {
+          for (const h of handlers) {
+            try {
+              h(ev.data);
+            } catch {
+              /* ignore handler errors */
+            }
+          }
+        }
+        return;
+      }
+      default:
+        return;
+    }
+  };
+}

package/src/types.ts

@@ -0,0 +1,109 @@
+export enum ExtensionErrorCode {
+  PermissionDenied = 4001,
+  InvalidRequest = 4002,
+  MethodNotFound = 4003,
+  InternalError = 4004,
+  Timeout = 4005,
+  ExtensionNotFound = 4006,
+  RateLimited = 4007,
+}
+
+export interface ThemeInfo {
+  mode: 'light' | 'dark';
+  tokens: Record<string, string>;
+  fontFamily?: string;
+  fontFamilyMono?: string;
+}
+
+export interface ExtensionRequest {
+  source: 'xopc-extension';
+  extensionId: string;
+  type: 'request';
+  requestId: string;
+  method: string;
+  params?: unknown;
+}
+
+export interface ExtensionEventMessage {
+  source: 'xopc-extension';
+  extensionId: string;
+  type: 'event';
+  event: string;
+  data?: unknown;
+}
+
+export interface HostInit {
+  source: 'xopc-host';
+  type: 'init';
+  extensionId: string;
+  permissions: string[];
+  theme: ThemeInfo;
+  locale: string;
+}
+
+export interface HostResponse {
+  source: 'xopc-host';
+  type: 'response';
+  requestId: string;
+  result?: unknown;
+  error?: { code: number; message: string };
+}
+
+export interface HostEventMessage {
+  source: 'xopc-host';
+  type: 'event';
+  event: string;
+  data?: unknown;
+}
+
+export type HostToExtensionMessage = HostInit | HostResponse | HostEventMessage;
+export type ExtensionToHostMessage = ExtensionRequest | ExtensionEventMessage;
+
+export type StreamHandler = (payload: unknown) => void;
+
+export interface ExtensionClient {
+  whenReady(): Promise<void>;
+  theme: {
+    getTheme(): Promise<ThemeInfo>;
+    onThemeChange(handler: (t: ThemeInfo) => void): () => void;
+  };
+  agent: {
+    sendMessage(
+      message: string,
+      options?: { sessionKey?: string; newSession?: boolean },
+    ): Promise<{ sessionKey: string }>;
+    onStreamEvent(sessionKey: string, handler: StreamHandler): () => void;
+  };
+  session: {
+    listSessions(): Promise<unknown[]>;
+    navigateToSession(sessionKey: string): Promise<void>;
+  };
+  config: {
+    getExtensionConfig<T = Record<string, unknown>>(): Promise<T>;
+    setExtensionConfig(patch: Record<string, unknown>): Promise<void>;
+  };
+  storage: {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+    remove(key: string): Promise<void>;
+    keys(): Promise<string[]>;
+  };
+  ui: {
+    resize(height: number): void;
+    showNotification(options: {
+      type?: 'success' | 'error' | 'info';
+      title: string;
+      message?: string;
+    }): Promise<void>;
+    closePanel(): void;
+    navigate(path: string): Promise<void>;
+    /** Chat/tool widget iframe: host sends the tool result via `widget.data` after load. */
+    onWidgetResult(handler: (data: unknown) => void): () => void;
+  };
+  events: {
+    emit(event: string, data?: unknown): void;
+    on(event: string, handler: (data: unknown) => void): () => void;
+  };
+  onDispose(handler: () => void): () => void;
+  onDidChangeVisibility(handler: (visible: boolean) => void): () => void;
+}