btcp-browser-agent 0.1.7 → 0.1.9

package/packages/extension/dist/script-messenger.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @btcp/extension - Script Messenger
+ *
+ * Type-safe message passing to injected scripts.
+ *
+ * @example
+ * ```typescript
+ * // Define message types
+ * type HelperMessages = {
+ *   getCount: { payload: { selector: string }; result: number };
+ *   getData: { payload: { id: string }; result: { name: string; value: number } };
+ * };
+ *
+ * // Create typed messenger
+ * const helper = createScriptMessenger<HelperMessages>(client, { scriptId: 'helper' });
+ *
+ * // Use with full type safety
+ * const count = await helper.send('getCount', { selector: '.item' });
+ * //    ^? number
+ * ```
+ */
+/**
+ * Message definition: maps action names to payload and result types
+ */
+export type MessageDefinitions = {
+    [action: string]: {
+        payload: unknown;
+        result: unknown;
+    };
+};
+/**
+ * Extract payload type for a specific action
+ */
+export type PayloadOf<T extends MessageDefinitions, K extends keyof T> = T[K]['payload'];
+/**
+ * Extract result type for a specific action
+ */
+export type ResultOf<T extends MessageDefinitions, K extends keyof T> = T[K]['result'];
+/**
+ * Options for creating a script messenger
+ */
+export interface ScriptMessengerOptions {
+    /** Target script ID (default: 'default') */
+    scriptId?: string;
+    /** Timeout in milliseconds for each message (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Script messenger for type-safe communication with injected scripts
+ */
+export interface ScriptMessenger<T extends MessageDefinitions> {
+    /**
+     * Send a message to the injected script
+     *
+     * @param action - The action name
+     * @param payload - The payload to send
+     * @returns The result from the script
+     */
+    send<K extends keyof T & string>(action: K, payload: PayloadOf<T, K>): Promise<ResultOf<T, K>>;
+    /**
+     * The script ID this messenger communicates with
+     */
+    readonly scriptId: string;
+    /**
+     * The default timeout for messages
+     */
+    readonly timeout: number;
+}
+/**
+ * Client interface required by ScriptMessenger
+ */
+export interface MessengerClient {
+    scriptSend(payload: unknown, options?: {
+        scriptId?: string;
+        timeout?: number;
+    }): Promise<unknown>;
+}
+/**
+ * Create a type-safe messenger for communicating with injected scripts
+ *
+ * @example
+ * ```typescript
+ * type Messages = {
+ *   getCount: { payload: { selector: string }; result: number };
+ *   fetchItems: { payload: { category: string }; result: Item[] };
+ * };
+ *
+ * const messenger = createScriptMessenger<Messages>(client, {
+ *   scriptId: 'helper',
+ * });
+ *
+ * const count = await messenger.send('getCount', { selector: '.item' });
+ * const items = await messenger.send('fetchItems', { category: 'books' });
+ * ```
+ */
+export declare function createScriptMessenger<T extends MessageDefinitions>(client: MessengerClient, options?: ScriptMessengerOptions): ScriptMessenger<T>;
+/**
+ * A messenger where each action is a method on the object
+ *
+ * @example
+ * ```typescript
+ * const helper = createMethodMessenger<{
+ *   getCount: { payload: { selector: string }; result: number };
+ * }>(client, { scriptId: 'helper' });
+ *
+ * const count = await helper.getCount({ selector: '.item' });
+ * ```
+ */
+export type MethodMessenger<T extends MessageDefinitions> = {
+    [K in keyof T & string]: (payload: PayloadOf<T, K>) => Promise<ResultOf<T, K>>;
+} & {
+    readonly scriptId: string;
+    readonly timeout: number;
+};
+/**
+ * Create a method-based messenger where each action is a method
+ *
+ * @example
+ * ```typescript
+ * type Messages = {
+ *   getCount: { payload: { selector: string }; result: number };
+ *   click: { payload: { ref: number }; result: void };
+ * };
+ *
+ * const helper = createMethodMessenger<Messages>(client, { scriptId: 'helper' });
+ *
+ * const count = await helper.getCount({ selector: '.item' });
+ * await helper.click({ ref: 5 });
+ * ```
+ */
+export declare function createMethodMessenger<T extends MessageDefinitions>(client: MessengerClient, options?: ScriptMessengerOptions): MethodMessenger<T>;
+//# sourceMappingURL=script-messenger.d.ts.map

package/packages/extension/dist/script-messenger.js

@@ -0,0 +1,86 @@
+/**
+ * @btcp/extension - Script Messenger
+ *
+ * Type-safe message passing to injected scripts.
+ *
+ * @example
+ * ```typescript
+ * // Define message types
+ * type HelperMessages = {
+ *   getCount: { payload: { selector: string }; result: number };
+ *   getData: { payload: { id: string }; result: { name: string; value: number } };
+ * };
+ *
+ * // Create typed messenger
+ * const helper = createScriptMessenger<HelperMessages>(client, { scriptId: 'helper' });
+ *
+ * // Use with full type safety
+ * const count = await helper.send('getCount', { selector: '.item' });
+ * //    ^? number
+ * ```
+ */
+/**
+ * Create a type-safe messenger for communicating with injected scripts
+ *
+ * @example
+ * ```typescript
+ * type Messages = {
+ *   getCount: { payload: { selector: string }; result: number };
+ *   fetchItems: { payload: { category: string }; result: Item[] };
+ * };
+ *
+ * const messenger = createScriptMessenger<Messages>(client, {
+ *   scriptId: 'helper',
+ * });
+ *
+ * const count = await messenger.send('getCount', { selector: '.item' });
+ * const items = await messenger.send('fetchItems', { category: 'books' });
+ * ```
+ */
+export function createScriptMessenger(client, options = {}) {
+    const scriptId = options.scriptId ?? 'default';
+    const timeout = options.timeout ?? 30000;
+    return {
+        scriptId,
+        timeout,
+        async send(action, payload) {
+            const messagePayload = { action, ...payload };
+            const result = await client.scriptSend(messagePayload, { scriptId, timeout });
+            return result;
+        },
+    };
+}
+/**
+ * Create a method-based messenger where each action is a method
+ *
+ * @example
+ * ```typescript
+ * type Messages = {
+ *   getCount: { payload: { selector: string }; result: number };
+ *   click: { payload: { ref: number }; result: void };
+ * };
+ *
+ * const helper = createMethodMessenger<Messages>(client, { scriptId: 'helper' });
+ *
+ * const count = await helper.getCount({ selector: '.item' });
+ * await helper.click({ ref: 5 });
+ * ```
+ */
+export function createMethodMessenger(client, options = {}) {
+    const messenger = createScriptMessenger(client, options);
+    return new Proxy({
+        scriptId: messenger.scriptId,
+        timeout: messenger.timeout,
+    }, {
+        get(target, prop) {
+            if (prop === 'scriptId' || prop === 'timeout') {
+                return target[prop];
+            }
+            if (typeof prop === 'string') {
+                return (payload) => messenger.send(prop, payload);
+            }
+            return undefined;
+        },
+    });
+}
+//# sourceMappingURL=script-messenger.js.map

package/packages/extension/dist/types.d.ts

@@ -5,7 +5,7 @@
  */
 import type { Command as CoreCommand, Response } from '../../core/dist/index.js';
 import type { SessionCommand } from './session-types.js';
-export type ExtensionAction = 'navigate' | 'back' | 'forward' | 'reload' | 'getUrl' | 'getTitle' | 'screenshot' | 'tabNew' | 'tabClose' | 'tabSwitch' | 'tabList' | 'groupCreate' | 'groupUpdate' | 'groupDelete' | 'groupList' | 'groupAddTabs' | 'groupRemoveTabs' | 'groupGet' | 'sessionGetCurrent' | 'popupInitialize';
+export type ExtensionAction = 'navigate' | 'back' | 'forward' | 'reload' | 'getUrl' | 'getTitle' | 'screenshot' | 'tabNew' | 'tabClose' | 'tabSwitch' | 'tabList' | 'groupCreate' | 'groupUpdate' | 'groupDelete' | 'groupList' | 'groupAddTabs' | 'groupRemoveTabs' | 'groupGet' | 'sessionGetCurrent' | 'popupInitialize' | 'scriptInject' | 'scriptSend';
 export interface ExtensionBaseCommand {
     /** Optional command ID. Auto-generated if not provided. */
     id?: string;
@@ -56,7 +56,63 @@ export interface TabListCommand extends ExtensionBaseCommand {
 export interface PopupInitializeCommand extends ExtensionBaseCommand {
     action: 'popupInitialize';
 }
-export type ExtensionCommand = NavigateCommand | BackCommand | ForwardCommand | ReloadCommand | GetUrlCommand | GetTitleCommand | ScreenshotCommand | TabNewCommand | TabCloseCommand | TabSwitchCommand | TabListCommand | PopupInitializeCommand | SessionCommand;
+/**
+ * Inject a script into the page's main world
+ *
+ * The script runs in the page context (not the content script isolated world),
+ * allowing access to page-level APIs like window, fetch interceptors, etc.
+ *
+ * @example
+ * ```typescript
+ * await client.execute({
+ *   action: 'scriptInject',
+ *   code: `
+ *     window.addEventListener('message', (event) => {
+ *       if (event.data?.type !== 'btcp:script-command') return;
+ *       if (event.data.scriptId !== 'helper') return;
+ *       const { commandId, payload } = event.data;
+ *       // Handle command and send ack
+ *       window.postMessage({ type: 'btcp:script-ack', commandId, result: { ok: true } }, '*');
+ *     });
+ *   `,
+ *   scriptId: 'helper'
+ * });
+ * ```
+ */
+export interface ScriptInjectCommand extends ExtensionBaseCommand {
+    action: 'scriptInject';
+    /** JavaScript code to inject into the page's main world */
+    code: string;
+    /** Unique identifier for this script (default: 'default') */
+    scriptId?: string;
+}
+/**
+ * Send a command to an injected script and wait for acknowledgment
+ *
+ * The content script posts a message to the page, and waits for the
+ * injected script to respond with an ack.
+ *
+ * @example
+ * ```typescript
+ * const result = await client.execute({
+ *   action: 'scriptSend',
+ *   scriptId: 'helper',
+ *   payload: { action: 'getData', selector: '.items' },
+ *   timeout: 5000
+ * });
+ * // result.data = { result: { items: [...] } }
+ * ```
+ */
+export interface ScriptSendCommand extends ExtensionBaseCommand {
+    action: 'scriptSend';
+    /** Payload to send to the injected script */
+    payload: unknown;
+    /** Target script ID (default: 'default') */
+    scriptId?: string;
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+export type ExtensionCommand = NavigateCommand | BackCommand | ForwardCommand | ReloadCommand | GetUrlCommand | GetTitleCommand | ScreenshotCommand | TabNewCommand | TabCloseCommand | TabSwitchCommand | TabListCommand | PopupInitializeCommand | SessionCommand | ScriptInjectCommand | ScriptSendCommand;
 export type Command = CoreCommand | ExtensionCommand;
 export type { Response };
 export type { SessionCommand, GroupInfo, SessionInfo, GroupCreateOptions, GroupUpdateOptions, } from './session-types.js';
@@ -86,4 +142,22 @@ export interface TabInfo {
     index: number;
 }
 export type ChromeTab = chrome.tabs.Tab;
+/**
+ * Command sent from content script to injected page script
+ */
+export interface ScriptCommandMessage {
+    type: 'btcp:script-command';
+    commandId: string;
+    scriptId: string;
+    payload: unknown;
+}
+/**
+ * Acknowledgment sent from injected page script to content script
+ */
+export interface ScriptAckMessage {
+    type: 'btcp:script-ack';
+    commandId: string;
+    result?: unknown;
+    error?: string;
+}
 //# sourceMappingURL=types.d.ts.map