@fairfox/polly 0.1.0

package/dist/shared/lib/message-bus.d.ts

@@ -0,0 +1,233 @@
+import type { ExtensionAdapters, MessageSender } from "../adapters";
+import type { BaseMessage, Context, ExtensionMessage, MessageResponse, RoutedMessage, RoutedResponse } from "../types/messages";
+import type { BackgroundHelpers, ContentScriptHelpers, DevToolsHelpers, OptionsHelpers, PopupHelpers, SidePanelHelpers } from "./context-specific-helpers";
+export declare function isRoutedMessage<TMessage extends BaseMessage = BaseMessage>(value: unknown): value is RoutedMessage<TMessage>;
+export declare function isRoutedResponse<TMessage extends BaseMessage = BaseMessage>(value: unknown): value is RoutedResponse<TMessage>;
+type PendingRequest<TMessage extends BaseMessage = ExtensionMessage> = {
+    resolve: (value: MessageResponse<TMessage> | undefined) => void;
+    reject: (error: Error) => void;
+    timestamp: number;
+    timeout: NodeJS.Timeout;
+};
+export declare class MessageBus<TMessage extends BaseMessage = ExtensionMessage> {
+    context: Context;
+    adapters: ExtensionAdapters;
+    helpers: ContentScriptHelpers | DevToolsHelpers | PopupHelpers | OptionsHelpers | SidePanelHelpers | BackgroundHelpers | Record<string, never>;
+    pendingRequests: Map<string, PendingRequest<TMessage>>;
+    private handlers;
+    private port;
+    private errorHandler;
+    private userErrorHandlers;
+    messageListener: ((message: unknown, sender: MessageSender, sendResponse: (response: unknown) => void) => boolean) | null;
+    constructor(context: Context, adapters?: ExtensionAdapters, options?: {
+        skipListenerSetup?: boolean;
+    });
+    /**
+     * Send a message with type safety.
+     * Response type is inferred from message type, though TypeScript requires
+     * the return type to be widened due to Map storage limitations.
+     * Runtime type safety is ensured by handler registration and invocation.
+     */
+    send<T extends TMessage>(payload: T, options?: {
+        target?: Context | Context[];
+        tabId?: number;
+        timeout?: number;
+    }): Promise<MessageResponse<Extract<TMessage, {
+        type: T extends {
+            type: infer TType;
+        } ? TType : never;
+    }>> | undefined>;
+    /**
+     * Broadcast message to all contexts.
+     * Used for state synchronization.
+     */
+    broadcast<T extends TMessage>(payload: T): void;
+    /**
+     * Register a typed message handler.
+     * Handler signature is enforced based on message type.
+     * Multiple handlers can be registered for the same message type.
+     */
+    on<T extends TMessage["type"]>(type: T, handler: (payload: Extract<TMessage, {
+        type: T;
+    }>, message: RoutedMessage<Extract<TMessage, {
+        type: T;
+    }>>) => Promise<MessageResponse<Extract<TMessage, {
+        type: T;
+    }>>> | MessageResponse<Extract<TMessage, {
+        type: T;
+    }>>): void;
+    /**
+     * Register multiple message handlers at once.
+     * Reduces boilerplate when defining many handlers.
+     *
+     * @example
+     * ```typescript
+     * bus.registerHandlers({
+     *   'MY_MESSAGE': async (payload) => ({ success: true }),
+     *   'ANOTHER_MESSAGE': async (payload) => ({ data: payload }),
+     * })
+     * ```
+     */
+    registerHandlers(handlers: Record<string, Function | undefined>): void;
+    /**
+     * Register a global error handler.
+     * Called when errors occur during message handling.
+     *
+     * @example
+     * ```typescript
+     * bus.onError((error, bus) => {
+     *   console.error(`[${bus.context}] Error:`, error)
+     *   // Report to error tracking service
+     * })
+     * ```
+     */
+    onError(handler: (error: Error, bus: MessageBus<TMessage>) => void): void;
+    /**
+     * Send message to background context.
+     * Explicit routing API for better DX.
+     *
+     * @example
+     * ```typescript
+     * const result = await bus.sendToBackground({ type: 'GET_SETTINGS' })
+     * ```
+     */
+    sendToBackground<T extends TMessage>(payload: T, options?: {
+        timeout?: number;
+    }): Promise<MessageResponse<Extract<TMessage, {
+        type: T extends {
+            type: infer TType;
+        } ? TType : never;
+    }>> | undefined>;
+    /**
+     * Send message to a specific content script.
+     *
+     * @example
+     * ```typescript
+     * const result = await bus.sendToContentScript(tabId, { type: 'ANALYZE_PAGE' })
+     * ```
+     */
+    sendToContentScript<T extends TMessage>(tabId: number, payload: T, options?: {
+        timeout?: number;
+    }): Promise<MessageResponse<Extract<TMessage, {
+        type: T extends {
+            type: infer TType;
+        } ? TType : never;
+    }>> | undefined>;
+    /**
+     * Send message to all tabs.
+     * Useful for broadcasting updates to all content scripts.
+     *
+     * @example
+     * ```typescript
+     * await bus.sendToAllTabs({ type: 'REFRESH_UI' })
+     * ```
+     */
+    sendToAllTabs<T extends TMessage>(payload: T, options?: {
+        timeout?: number;
+    }): Promise<Array<MessageResponse<Extract<TMessage, {
+        type: T extends {
+            type: infer TType;
+        } ? TType : never;
+    }>> | undefined>>;
+    /**
+     * Send message to popup context.
+     *
+     * @example
+     * ```typescript
+     * await bus.sendToPopup({ type: 'UPDATE_UI', data: newData })
+     * ```
+     */
+    sendToPopup<T extends TMessage>(payload: T, options?: {
+        timeout?: number;
+    }): Promise<MessageResponse<Extract<TMessage, {
+        type: T extends {
+            type: infer TType;
+        } ? TType : never;
+    }>> | undefined>;
+    /**
+     * Send message to options page.
+     *
+     * @example
+     * ```typescript
+     * await bus.sendToOptions({ type: 'SETTINGS_UPDATED' })
+     * ```
+     */
+    sendToOptions<T extends TMessage>(payload: T, options?: {
+        timeout?: number;
+    }): Promise<MessageResponse<Extract<TMessage, {
+        type: T extends {
+            type: infer TType;
+        } ? TType : never;
+    }>> | undefined>;
+    /**
+     * Send message to devtools panel.
+     *
+     * @example
+     * ```typescript
+     * await bus.sendToDevTools({ type: 'INSPECTION_DATA', data: pageData })
+     * ```
+     */
+    sendToDevTools<T extends TMessage>(payload: T, options?: {
+        timeout?: number;
+    }): Promise<MessageResponse<Extract<TMessage, {
+        type: T extends {
+            type: infer TType;
+        } ? TType : never;
+    }>> | undefined>;
+    /**
+     * Send message to side panel.
+     *
+     * @example
+     * ```typescript
+     * await bus.sendToSidePanel({ type: 'UPDATE_ACTIVITY_LOG' })
+     * ```
+     */
+    sendToSidePanel<T extends TMessage>(payload: T, options?: {
+        timeout?: number;
+    }): Promise<MessageResponse<Extract<TMessage, {
+        type: T extends {
+            type: infer TType;
+        } ? TType : never;
+    }>> | undefined>;
+    /**
+     * Connect with long-lived port.
+     * Used for persistent connections (DevTools, Content Scripts).
+     */
+    connect(name: string): void;
+    /**
+     * Disconnect port if connected.
+     */
+    disconnect(): void;
+    /**
+     * Remove all handlers and clean up.
+     */
+    destroy(): void;
+    private setupListeners;
+    handleMessage(message: RoutedMessage<TMessage> | RoutedResponse<TMessage>, _sender?: unknown): Promise<unknown>;
+    sendMessage<T extends TMessage = TMessage>(message: RoutedMessage<T>): void;
+    private sendResponse;
+    private inferTarget;
+    /**
+     * Create context-specific helpers based on current context.
+     * @private
+     */
+    private createContextHelpers;
+    /**
+     * Notify all registered error handlers.
+     * @private
+     */
+    private notifyErrorHandlers;
+}
+/**
+ * Create a MessageBus for the given context.
+ *
+ * IMPORTANT: Only call this ONCE per context in your application.
+ * Calling it multiple times will create multiple message listeners, causing
+ * handlers to execute multiple times. Store the returned bus and reuse it.
+ *
+ * For background scripts, use createBackground() instead.
+ */
+export declare function getMessageBus<TMessage extends BaseMessage = ExtensionMessage>(context: Context, adapters?: ExtensionAdapters, options?: {
+    skipListenerSetup?: boolean;
+}): MessageBus<TMessage>;
+export {};