@xopcai/extension-ui-sdk 0.0.149 → 0.0.151

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xopcai/extension-ui-sdk",
-  "version": "0.0.149",
+  "version": "0.0.151",
   "description": "Gateway Console extension UI SDK (iframe postMessage client)",
   "type": "module",
   "sideEffects": false,
@@ -16,6 +16,9 @@
     "src"
   ],
   "license": "MIT",
+  "dependencies": {
+    "@xopcai/gateway-contract": "0.0.0"
+  },
   "devDependencies": {
     "typedoc": "^0.28.19",
     "typedoc-plugin-markdown": "^4.11.0",

package/src/client.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createExtensionClient } from './client.js';
+import type { Transport } from './transport.js';
+
+describe('extension client product navigation', () => {
+  it('opens first-class product references through the host router', async () => {
+    const request = vi.fn(async () => undefined);
+    const transport = {
+      ready: Promise.resolve(),
+      request,
+      emit: vi.fn(),
+      on: vi.fn(() => () => undefined),
+    } as unknown as Transport;
+    const client = createExtensionClient({ transport });
+
+    await client.ui.openProduct({ kind: 'note', id: 'note/1' });
+
+    expect(request).toHaveBeenCalledWith('ui.navigate', {
+      path: '/notes/note%2F1',
+    });
+  });
+
+  it('rejects references without a routable product surface', async () => {
+    const transport = {
+      ready: Promise.resolve(),
+      request: vi.fn(),
+      emit: vi.fn(),
+      on: vi.fn(() => () => undefined),
+    } as unknown as Transport;
+    const client = createExtensionClient({ transport });
+
+    await expect(client.ui.openProduct({ kind: 'file', id: '/tmp/result.md' }))
+      .rejects.toThrow('cannot be opened');
+  });
+});

package/src/client.ts

@@ -1,3 +1,8 @@
+import {
+  productReferenceRoute,
+  type ProductReferenceLocator,
+} from '@xopcai/gateway-contract';
+
 import { Transport } from './transport.js';
 import type { ExtensionClient, StreamHandler, ThemeInfo } from './types.js';
 
@@ -88,6 +93,17 @@ export function createExtensionClient(options?: CreateExtensionClientOptions): E
       async navigate(path: string) {
         await transport.request('ui.navigate', { path });
       },
+      async openProduct(reference: ProductReferenceLocator) {
+        const path = productReferenceRoute({
+          ...reference,
+          title: reference.id,
+          capabilities: ['open'],
+        });
+        if (!path) {
+          throw new Error(`Product kind cannot be opened by route: ${reference.kind}`);
+        }
+        await transport.request('ui.navigate', { path });
+      },
       onWidgetResult(handler: (data: unknown) => void) {
         return transport.on('widget.data', handler);
       },

package/src/index.ts

@@ -1,4 +1,5 @@
 export { createExtensionClient, type CreateExtensionClientOptions } from './client.js';
+export type { ProductReferenceLocator } from '@xopcai/gateway-contract';
 export { Transport, type TransportOptions } from './transport.js';
 export {
   ExtensionErrorCode,

package/src/types.ts

@@ -97,6 +97,7 @@ export interface ExtensionClient {
     }): Promise<void>;
     closePanel(): void;
     navigate(path: string): Promise<void>;
+    openProduct(reference: ProductReferenceLocator): Promise<void>;
     /** Chat/tool widget iframe: host sends the tool result via `widget.data` after load. */
     onWidgetResult(handler: (data: unknown) => void): () => void;
   };
@@ -107,3 +108,4 @@ export interface ExtensionClient {
   onDispose(handler: () => void): () => void;
   onDidChangeVisibility(handler: (visible: boolean) => void): () => void;
 }
+import type { ProductReferenceLocator } from '@xopcai/gateway-contract';