@bodhiapp/bodhi-browser-types 0.0.1

package/bodhiext.ts

@@ -0,0 +1,255 @@
+/**
+ * Public API types for window.bodhiext interface
+ *
+ * This file defines the contract web pages use to communicate with the Bodhi browser extension.
+ * Used primarily by inject.ts to create the window.bodhiext API surface.
+ */
+
+import type { OpenAiApiError, PingResponse, CreateChatCompletionRequest, CreateChatCompletionResponse, CreateChatCompletionStreamResponse } from '@bodhiapp/ts-client';
+import { isOperationErrorStructure } from './protocol';
+
+//-----------------------------------------------------------------------------------
+// HTTP RESPONSE TYPES
+//-----------------------------------------------------------------------------------
+
+/**
+ * HTTP response wrapper - body can be success type OR error type
+ * Use isApiErrorResponse() to narrow the type based on status
+ */
+export interface ApiResponse<T = unknown> {
+  body: T | OpenAiApiError;
+  status: number;
+  headers: Record<string, string>;
+}
+
+/**
+ * Stream chunk returned by sendStreamRequest
+ *
+ * This is the chunk structure yielded by the ReadableStream from sendStreamRequest.
+ * Different from StreamChunkMessage which is the internal message wrapper.
+ */
+export interface StreamChunk {
+  body: unknown;
+  headers?: Record<string, string>;
+  status?: number;
+  done?: boolean;
+}
+
+/**
+ * Server state information returned by /bodhi/v1/info endpoint
+ */
+export interface ServerStateInfo {
+  /** Current application status */
+  status: 'setup' | 'ready' | 'resource-admin' | 'error' | 'unreachable';
+  /** Application version */
+  version?: string;
+  /** Server URL (added by extension) */
+  url?: string;
+  /** Error details if status is 'error' or 'unreachable' */
+  error?: {
+    message: string;
+    type?: string;
+    code?: string;
+    param?: string;
+  };
+}
+
+//-----------------------------------------------------------------------------------
+// ERROR TYPES (Thrown by extension)
+//-----------------------------------------------------------------------------------
+
+/**
+ * API error thrown when server returns HTTP 4xx/5xx
+ * Used for streaming responses (non-streaming returns ApiResponse)
+ */
+export interface ApiError extends Error {
+  response: {
+    status: number;
+    body: OpenAiApiError;
+    headers?: Record<string, string>;
+  };
+}
+
+/**
+ * Operation error thrown when HTTP request couldn't complete
+ * (network unreachable, timeout, extension error)
+ */
+export interface OperationError extends Error {
+  error: {
+    message: string;
+    type: string; // Relaxed: any string allowed for custom error types
+  };
+}
+
+/**
+ * Union of all extension-thrown errors
+ */
+export type ExtensionError = ApiError | OperationError;
+
+/**
+ * Type guard: API error (has response field)
+ */
+export function isApiError(err: unknown): err is ApiError {
+  return (
+    err instanceof Error &&
+    'response' in err &&
+    typeof (err as ApiError).response === 'object' &&
+    (err as ApiError).response !== null &&
+    typeof (err as ApiError).response.status === 'number' &&
+    'body' in (err as ApiError).response
+  );
+}
+
+/**
+ * Type guard: Operation error (has error field, no response)
+ */
+export function isOperationError(err: unknown): err is OperationError {
+  return err instanceof Error && 'error' in err && !('response' in err) && isOperationErrorStructure((err as OperationError).error);
+}
+
+//-----------------------------------------------------------------------------------
+// CHAT API TYPES (OpenAI-compatible from @bodhiapp/ts-client)
+//-----------------------------------------------------------------------------------
+
+/**
+ * Chat API uses types from @bodhiapp/ts-client.
+ * Consumers should import these types directly from @bodhiapp/ts-client:
+ * - ChatCompletionRequestMessage
+ * - ChatCompletionResponseMessage
+ * - CreateChatCompletionRequest
+ * - CreateChatCompletionResponse
+ * - CreateChatCompletionStreamResponse
+ * - ChatChoice
+ * - ChatChoiceStream
+ * - ChatCompletionStreamResponseDelta
+ */
+
+/**
+ * Chat completions API interface
+ */
+export interface ChatCompletionsApi {
+  /**
+   * Create a chat completion
+   *
+   * Non-streaming: Returns ApiResponse - caller checks status for success/error
+   * Streaming: Yields chunks via AsyncIterable - throws ApiError or OperationError on error
+   *
+   * @param params - Chat completion parameters
+   * @returns Non-streaming: Promise<ApiResponse<CreateChatCompletionResponse>>, Streaming: AsyncIterable<CreateChatCompletionStreamResponse>
+   */
+  create(params: CreateChatCompletionRequest & { stream?: false }): Promise<ApiResponse<CreateChatCompletionResponse>>;
+  create(params: CreateChatCompletionRequest & { stream: true }): AsyncIterable<CreateChatCompletionStreamResponse>;
+  create(params: CreateChatCompletionRequest): Promise<ApiResponse<CreateChatCompletionResponse>> | AsyncIterable<CreateChatCompletionStreamResponse>;
+}
+
+/**
+ * Chat API namespace
+ */
+export interface ChatApi {
+  completions: ChatCompletionsApi;
+}
+
+//-----------------------------------------------------------------------------------
+// PUBLIC API INTERFACE
+//-----------------------------------------------------------------------------------
+
+/**
+ * Public window.bodhiext interface
+ *
+ * This interface defines all methods available to web pages through window.bodhiext.
+ * The extension creates this interface in inject.ts and attaches it to the window object.
+ */
+export interface BodhiExtPublicApi {
+  /**
+   * Send a generic API request through the extension to the backend server.
+   *
+   * @template TReq - Request body type (inferred from body parameter)
+   * @template TRes - Response body type (must be specified explicitly)
+   * @param method - HTTP method (GET, POST, PUT, DELETE, etc.)
+   * @param endpoint - API endpoint path (e.g., '/v1/chat/completions')
+   * @param body - Optional request body (will be JSON stringified)
+   * @param headers - Optional additional headers
+   * @returns Promise resolving to ApiResponse with body, headers, and status
+   */
+  sendApiRequest<TReq = unknown, TRes = unknown>(method: string, endpoint: string, body?: TReq, headers?: Record<string, string>): Promise<ApiResponse<TRes>>;
+
+  /**
+   * Send a streaming API request through the extension.
+   *
+   * Used for SSE (Server-Sent Events) endpoints like streaming chat completions.
+   * Returns a ReadableStream that yields StreamChunk objects.
+   *
+   * @template TReq - Request body type (inferred from body parameter)
+   * @param method - HTTP method (typically POST for streaming)
+   * @param endpoint - API endpoint path (e.g., '/v1/chat/completions')
+   * @param body - Optional request body
+   * @param headers - Optional additional headers
+   * @returns ReadableStream yielding StreamChunk objects
+   */
+  sendStreamRequest<TReq = unknown>(method: string, endpoint: string, body?: TReq, headers?: Record<string, string>): ReadableStream<StreamChunk>;
+
+  /**
+   * Send a generic extension request.
+   *
+   * Used for extension-specific operations like test_connection, get_extension_id, etc.
+   * This is a low-level API for extension capabilities.
+   *
+   * @param action - Extension action name (e.g., 'test_connection')
+   * @param params - Optional action parameters
+   * @returns Promise resolving to action-specific response
+   */
+  sendExtRequest(action: string, params?: any): Promise<any>;
+
+  /**
+   * Simple health check to verify extension connectivity.
+   *
+   * Returns ApiResponse - caller should check status to determine success/error.
+   * On success (2xx), body is PingResponse. On error (4xx/5xx), body is OpenAiApiError.
+   *
+   * @returns Promise resolving to ApiResponse<PingResponse>
+   */
+  ping(): Promise<ApiResponse<PingResponse>>;
+
+  /**
+   * Get server state information from /bodhi/v1/info endpoint.
+   *
+   * Returns the current status of the backend server including
+   * whether it's in setup mode, ready, or has errors.
+   *
+   * @returns Promise resolving to ServerStateInfo
+   */
+  serverState(): Promise<ServerStateInfo>;
+
+  /**
+   * OpenAI-compatible chat API.
+   *
+   * Provides chat completion functionality compatible with OpenAI's API structure.
+   */
+  chat: ChatApi;
+
+  /**
+   * Get the extension ID.
+   *
+   * The extension ID is fetched asynchronously during initialization.
+   * This method returns a promise that resolves to the extension ID once available.
+   *
+   * @returns Promise resolving to the extension ID string
+   */
+  getExtensionId(): Promise<string>;
+}
+
+//-----------------------------------------------------------------------------------
+// WINDOW AUGMENTATION
+//-----------------------------------------------------------------------------------
+
+/**
+ * Window augmentation for TypeScript
+ *
+ * Declares the optional bodhiext property on the Window interface.
+ * This allows TypeScript code to access window.bodhiext with proper typing.
+ */
+declare global {
+  interface Window {
+    bodhiext?: BodhiExtPublicApi;
+  }
+}

package/common.ts

@@ -0,0 +1,99 @@
+/**
+ * Shared constants for Bodhi Browser Extension
+ *
+ * Constants used by both inject.ts and background/content.ts scripts,
+ * or common to the entire extension.
+ */
+
+//-----------------------------------------------------------------------------------
+// HTTP CONSTANTS
+//-----------------------------------------------------------------------------------
+
+export const CONTENT_TYPE_JSON = 'application/json';
+export const CONTENT_TYPE_EVENT_STREAM = 'text/event-stream';
+export const CONTENT_TYPE_HEADER = 'Content-Type';
+export const HTTP_METHOD_GET = 'GET';
+export const HTTP_METHOD_POST = 'POST';
+
+//-----------------------------------------------------------------------------------
+// API ENDPOINTS
+//-----------------------------------------------------------------------------------
+
+export const ENDPOINT_PING = '/ping';
+export const ENDPOINT_CHAT_COMPLETIONS = '/v1/chat/completions';
+
+//-----------------------------------------------------------------------------------
+// DEFAULT VALUES
+//-----------------------------------------------------------------------------------
+
+export const DEFAULT_API_BASE_URL = 'http://localhost:1135';
+export const DEFAULT_API_TIMEOUT = 10000; // 10 seconds for API requests
+export const DEFAULT_STREAM_TIMEOUT = 60000; // 60 seconds for streaming
+
+//-----------------------------------------------------------------------------------
+// STORAGE
+//-----------------------------------------------------------------------------------
+
+export const STORAGE_KEY_BACKEND_URL = 'backendUrl';
+
+//-----------------------------------------------------------------------------------
+// SSE (Server-Sent Events)
+//-----------------------------------------------------------------------------------
+
+export const SSE_DONE_MARKER = '[DONE]';
+export const SSE_DATA_PREFIX = 'data: ';
+export const SSE_CHUNK_DELIMITER = '\n\n';
+
+//-----------------------------------------------------------------------------------
+// EXTENSION ACTIONS
+//-----------------------------------------------------------------------------------
+
+export const EXT_ACTIONS = {
+  GET_EXTENSION_ID: 'get_extension_id',
+  TEST_CONNECTION: 'test_connection',
+} as const;
+
+//-----------------------------------------------------------------------------------
+// ERROR TYPES
+//-----------------------------------------------------------------------------------
+
+export const ERROR_TYPES = {
+  NETWORK_ERROR: 'network_error',
+  EXTENSION_ERROR: 'extension_error',
+  TIMEOUT_ERROR: 'timeout_error',
+  AUTH_ERROR: 'auth_error',
+} as const;
+
+// Type union for connection error types
+export type ConnectionErrorType = (typeof ERROR_TYPES)[keyof typeof ERROR_TYPES];
+
+//-----------------------------------------------------------------------------------
+// DOCUMENT STATES
+//-----------------------------------------------------------------------------------
+
+export const DOCUMENT_STATE_COMPLETE = 'complete';
+
+//-----------------------------------------------------------------------------------
+// EVENT NAMES
+//-----------------------------------------------------------------------------------
+
+export const EVENT_INITIALIZED = 'bodhiext:initialized';
+
+//-----------------------------------------------------------------------------------
+// PORT NAMES
+//-----------------------------------------------------------------------------------
+
+export const BODHI_STREAM_PORT = 'BODHI_STREAM_PORT';
+
+//-----------------------------------------------------------------------------------
+// FALLBACKS
+//-----------------------------------------------------------------------------------
+
+export const ORIGIN_WILDCARD = '*';
+
+//-----------------------------------------------------------------------------------
+// ERROR MESSAGES
+//-----------------------------------------------------------------------------------
+
+export const ERROR_MISSING_REQUEST_ID = 'Invalid message format: missing requestId or request';
+export const ERROR_CONNECTION_CLOSED = 'Connection closed unexpectedly';

package/index.ts

@@ -0,0 +1,88 @@
+// Bodhi Browser Extension - Shared Types and Constants
+// This package provides the shared protocol definitions for communication
+// between web pages, external extensions, and bodhi-browser-ext
+//
+// NOTE: OpenAI types (CreateChatCompletionRequest, PingResponse, etc.)
+// are NOT re-exported. Import them directly from '@bodhiapp/ts-client' when needed.
+
+//-----------------------------------------------------------------------------------
+// PUBLIC API TYPES (window.bodhiext)
+//-----------------------------------------------------------------------------------
+
+export type { ApiResponse, StreamChunk, ServerStateInfo, ApiError, OperationError, ExtensionError, ChatCompletionsApi, ChatApi, BodhiExtPublicApi } from './bodhiext';
+
+export { isApiError, isOperationError } from './bodhiext';
+
+//-----------------------------------------------------------------------------------
+// INTERNAL PROTOCOL TYPES
+//-----------------------------------------------------------------------------------
+
+export type {
+  ApiRequest,
+  ApiRequestMessage,
+  OperationErrorResponse,
+  ApiResponseSuccessMessage,
+  OperationErrorResponseMessage,
+  ApiResponseMessage,
+  ErrorMessage,
+  StreamChunkMessage,
+  StreamApiErrorMessage,
+  StreamErrorMessage,
+  StreamMessage,
+  StreamController,
+  SSEChunk,
+  ExtRequest,
+  ExtRequestMessage,
+  ExtError,
+  ExtErrorResponse,
+  ExtResponse,
+  ExtResponseMessage,
+  GetExtensionIdRequest,
+  GetExtensionIdResponse,
+  TestConnectionRequest,
+  TestConnectionResponse,
+} from './protocol';
+
+export {
+  MESSAGE_TYPES,
+  isOperationErrorResponse,
+  isApiErrorResponse,
+  isApiSuccessResponse,
+  isStreamChunk,
+  isStreamApiError,
+  isStreamError,
+  isExtError,
+  isOpenAiApiErrorBody,
+  isOperationErrorStructure,
+} from './protocol';
+
+//-----------------------------------------------------------------------------------
+// COMMON CONSTANTS
+//-----------------------------------------------------------------------------------
+
+export {
+  CONTENT_TYPE_JSON,
+  CONTENT_TYPE_EVENT_STREAM,
+  CONTENT_TYPE_HEADER,
+  HTTP_METHOD_GET,
+  HTTP_METHOD_POST,
+  ENDPOINT_PING,
+  ENDPOINT_CHAT_COMPLETIONS,
+  DEFAULT_API_BASE_URL,
+  DEFAULT_API_TIMEOUT,
+  DEFAULT_STREAM_TIMEOUT,
+  STORAGE_KEY_BACKEND_URL,
+  SSE_DONE_MARKER,
+  SSE_DATA_PREFIX,
+  SSE_CHUNK_DELIMITER,
+  EXT_ACTIONS,
+  ERROR_TYPES,
+  DOCUMENT_STATE_COMPLETE,
+  EVENT_INITIALIZED,
+  BODHI_STREAM_PORT,
+  ORIGIN_WILDCARD,
+  ERROR_MISSING_REQUEST_ID,
+  ERROR_CONNECTION_CLOSED,
+} from './common';
+
+export type { ConnectionErrorType } from './common';

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@bodhiapp/bodhi-browser-types",
+  "version": "0.0.1",
+  "description": "TypeScript types for Bodhi Browser Extension",
+  "type": "module",
+  "main": "index.ts",
+  "types": "index.ts",
+  "exports": {
+    ".": {
+      "types": "./index.ts",
+      "import": "./index.ts",
+      "require": "./index.ts"
+    }
+  },
+  "files": ["*.ts"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BodhiSearch/bodhi-browser.git",
+    "directory": "bodhi-browser-ext/src/types"
+  },
+  "license": "MIT",
+  "author": "BodhiSearch",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/protocol.ts

@@ -0,0 +1,315 @@
+/**
+ * Internal extension protocol types
+ *
+ * Message passing types and constants for communication between
+ * inject.ts, content.ts, and background.ts (service worker).
+ * Used primarily by background/*, content.ts files.
+ */
+
+import type { OpenAiApiError, ErrorBody } from '@bodhiapp/ts-client';
+import type { ApiResponse, ServerStateInfo } from './bodhiext';
+
+//-----------------------------------------------------------------------------------
+// VALIDATION HELPERS
+//-----------------------------------------------------------------------------------
+
+/**
+ * Private helper: Check if value is non-null object
+ * Not exported - implementation detail for other helpers
+ */
+function isNonNullObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object';
+}
+
+/**
+ * Validate OpenAI API error body structure
+ * { error: { message: string, type: string } }
+ */
+export function isOpenAiApiErrorBody(body: unknown): body is OpenAiApiError {
+  return (
+    isNonNullObject(body) &&
+    'error' in body &&
+    isNonNullObject(body.error) &&
+    'message' in body.error &&
+    typeof body.error.message === 'string' &&
+    'type' in body.error &&
+    typeof body.error.type === 'string'
+  );
+}
+
+/**
+ * Validate OperationErrorResponse structure
+ * { message: string, type: string }
+ */
+export function isOperationErrorStructure(obj: unknown): obj is OperationErrorResponse {
+  return isNonNullObject(obj) && 'message' in obj && typeof obj.message === 'string' && 'type' in obj && typeof obj.type === 'string';
+}
+
+//-----------------------------------------------------------------------------------
+// MESSAGE TYPE CONSTANTS
+//-----------------------------------------------------------------------------------
+
+export const MESSAGE_TYPES = {
+  API_REQUEST: 'BODHI_API_REQUEST',
+  API_RESPONSE: 'BODHI_API_RESPONSE',
+  STREAM_REQUEST: 'BODHI_STREAM_REQUEST',
+  STREAM_CHUNK: 'BODHI_STREAM_CHUNK',
+  STREAM_ERROR: 'BODHI_STREAM_ERROR',
+  STREAM_API_ERROR: 'BODHI_STREAM_API_ERROR',
+  ERROR: 'BODHI_ERROR',
+  EXT_REQUEST: 'BODHI_EXT_REQUEST',
+  EXT_RESPONSE: 'BODHI_EXT_RESPONSE',
+} as const;
+
+//-----------------------------------------------------------------------------------
+// API REQUEST/RESPONSE TYPES
+//-----------------------------------------------------------------------------------
+
+export interface ApiRequest<T = unknown> {
+  method: string;
+  endpoint: string;
+  body?: T;
+  headers?: Record<string, string>;
+}
+
+export interface ApiRequestMessage<TReq = unknown> {
+  type: string;
+  requestId: string;
+  request: ApiRequest<TReq>;
+}
+
+/**
+ * Operation-level error response (network unreachable, timeout, extension error)
+ * NOT an API error (those come through ApiResponse with OpenAiApiError body)
+ * This is a response type, not a thrown error
+ */
+export interface OperationErrorResponse {
+  message: string;
+  type: string; // Relaxed: any string allowed for custom error types
+}
+
+/**
+ * Success API response message (HTTP request completed, regardless of status code)
+ */
+export interface ApiResponseSuccessMessage<T = unknown> {
+  type: string;
+  requestId: string;
+  response: ApiResponse<T>;
+}
+
+/**
+ * Operation error response message - HTTP request couldn't complete
+ */
+export interface OperationErrorResponseMessage {
+  type: string;
+  requestId: string;
+  error: OperationErrorResponse;
+}
+
+/**
+ * API response message - discriminated union
+ */
+export type ApiResponseMessage<T = unknown> = ApiResponseSuccessMessage<T> | OperationErrorResponseMessage;
+
+/**
+ * Type guard for operation error response
+ */
+export function isOperationErrorResponse(msg: ApiResponseMessage): msg is OperationErrorResponseMessage {
+  return isNonNullObject(msg) && 'error' in msg && isOperationErrorStructure(msg.error);
+}
+
+/**
+ * Type guard to check if response is an API error (4xx/5xx)
+ * Narrows body type to OpenAiApiError
+ */
+export function isApiErrorResponse<T>(response: ApiResponse<T>): response is ApiResponse<T> & { body: OpenAiApiError; status: number } {
+  return isNonNullObject(response) && typeof response.status === 'number' && response.status >= 400 && isOpenAiApiErrorBody(response.body);
+}
+
+/**
+ * Type guard to check if response is successful (2xx)
+ * Narrows body type to T
+ */
+export function isApiSuccessResponse<T>(response: ApiResponse<T>): response is ApiResponse<T> & { body: T; status: number } {
+  return response !== null && typeof response === 'object' && typeof response.status === 'number' && response.status >= 200 && response.status < 300 && 'body' in response;
+}
+
+export interface ErrorMessage {
+  type: string;
+  requestId: string;
+  response: {
+    body: ErrorBody;
+    status: number;
+    headers: Record<string, string>;
+  };
+}
+
+//-----------------------------------------------------------------------------------
+// STREAMING MESSAGE TYPES (Discriminated Union)
+//-----------------------------------------------------------------------------------
+
+/**
+ * Stream chunk message - successful SSE chunk received
+ * Uses ApiResponse<T> wrapper for consistency with non-streaming pattern
+ */
+export interface StreamChunkMessage<T = unknown> {
+  type: typeof MESSAGE_TYPES.STREAM_CHUNK;
+  requestId: string;
+  response: ApiResponse<T>;
+}
+
+/**
+ * Stream API error message - server returned error response (not SSE)
+ * E.g., 400/401/500 JSON error instead of SSE stream
+ */
+export interface StreamApiErrorMessage {
+  type: typeof MESSAGE_TYPES.STREAM_API_ERROR;
+  requestId: string;
+  response: ApiResponse<OpenAiApiError>;
+}
+
+/**
+ * Stream error message - network/extension level error
+ * E.g., connection refused, timeout, extension error
+ */
+export interface StreamErrorMessage {
+  type: typeof MESSAGE_TYPES.STREAM_ERROR;
+  requestId: string;
+  error: OperationErrorResponse;
+}
+
+/**
+ * Union type for all streaming messages
+ */
+export type StreamMessage<T = unknown> = StreamChunkMessage<T> | StreamApiErrorMessage | StreamErrorMessage;
+
+/**
+ * Type guard for stream chunk message
+ */
+export function isStreamChunk<T>(msg: StreamMessage<T>): msg is StreamChunkMessage<T> {
+  return msg !== null && typeof msg === 'object' && msg.type === MESSAGE_TYPES.STREAM_CHUNK;
+}
+
+/**
+ * Type guard for stream API error
+ */
+export function isStreamApiError(msg: StreamMessage): msg is StreamApiErrorMessage {
+  return msg !== null && typeof msg === 'object' && msg.type === MESSAGE_TYPES.STREAM_API_ERROR;
+}
+
+/**
+ * Type guard for stream error
+ */
+export function isStreamError(msg: StreamMessage): msg is StreamErrorMessage {
+  return msg !== null && typeof msg === 'object' && msg.type === MESSAGE_TYPES.STREAM_ERROR;
+}
+
+/**
+ * Interface for stream controller to handle SSE responses
+ */
+export interface StreamController {
+  enqueue: (chunk: any) => void;
+  error: (err: Error) => void;
+  complete: () => void;
+}
+
+/**
+ * Interface for SSE data chunk
+ */
+export interface SSEChunk {
+  done?: boolean;
+  [key: string]: any;
+}
+
+//-----------------------------------------------------------------------------------
+// GENERIC EXTENSION REQUEST/RESPONSE TYPES
+//-----------------------------------------------------------------------------------
+
+/**
+ * Generic extension request interface
+ */
+export interface ExtRequest {
+  action: string;
+  params?: any;
+}
+
+/**
+ * Generic extension request message
+ */
+export interface ExtRequestMessage {
+  type: 'BODHI_EXT_REQUEST';
+  requestId: string;
+  request: ExtRequest;
+}
+
+/**
+ * Extension-level error structure
+ */
+export interface ExtError {
+  message: string;
+  type?: string;
+}
+
+/**
+ * Error response for extension operations
+ */
+export interface ExtErrorResponse {
+  error: ExtError;
+}
+
+/**
+ * Union type for extension response (flattened - no wrapper for success)
+ * Success: T (the actual response data)
+ * Error: { error: ExtError }
+ */
+export type ExtResponse<T = unknown> = T | ExtErrorResponse;
+
+/**
+ * Type guard to check if extension response is an error
+ */
+export function isExtError<T>(res: ExtResponse<T>): res is ExtErrorResponse {
+  return res !== null && typeof res === 'object' && 'error' in res;
+}
+
+/**
+ * Generic extension response message
+ */
+export interface ExtResponseMessage<T = unknown> {
+  type: 'BODHI_EXT_RESPONSE';
+  requestId: string;
+  response: ExtResponse<T>;
+}
+
+//-----------------------------------------------------------------------------------
+// ACTION-SPECIFIC TYPES
+//-----------------------------------------------------------------------------------
+
+/**
+ * Get Extension ID request (no params needed)
+ */
+export interface GetExtensionIdRequest extends ExtRequest {
+  action: 'get_extension_id';
+  params?: undefined;
+}
+
+/**
+ * Get Extension ID response body
+ */
+export interface GetExtensionIdResponse {
+  extension_id: string;
+}
+
+/**
+ * Test Connection request
+ */
+export interface TestConnectionRequest extends ExtRequest {
+  action: 'test_connection';
+  params: {
+    url: string;
+  };
+}
+
+/**
+ * Test Connection response body (reuses ServerStateInfo)
+ */
+export type TestConnectionResponse = ServerStateInfo;