@bodhiapp/ext-types

Shared types and constants for Bodhi Browser extension communication protocol.

Overview

This package provides the core protocol definitions used by:

• bodhi-browser-ext: Chrome extension that bridges web pages to local LLM services
• @bodhiapp/bodhijs: JavaScript library for web applications and external extensions

Installation

npm install @bodhiapp/ext-types

Usage

Constants

import { MESSAGE_TYPES, BODHI_STREAM_PORT } from '@bodhiapp/ext-types';

// Message types for extension communication
console.log(MESSAGE_TYPES.API_REQUEST); // 'BODHI_API_REQUEST'
console.log(MESSAGE_TYPES.STREAM_REQUEST); // 'BODHI_STREAM_REQUEST'

// Port name for streaming connections
const port = chrome.runtime.connectExternal(extensionId, {
  name: BODHI_STREAM_PORT
});

Types

import type {
  ApiRequestMessage,
  ApiResponseMessage,
  ApiRequest,
  ApiResponse
} from '@bodhiapp/ext-types';

// Create a typed API request
const request: ApiRequestMessage = {
  type: MESSAGE_TYPES.API_REQUEST,
  requestId: 'unique-id',
  request: {
    method: 'POST',
    endpoint: '/v1/chat/completions',
    body: {
      model: 'llama3',
      messages: [{ role: 'user', content: 'Hello!' }]
    }
  }
};

// Handle typed response
function handleResponse(response: ApiResponseMessage) {
  const { status, body } = response.response;
  console.log('Status:', status);
  console.log('Body:', body);
}

Communication Patterns

Web Page → Extension (3-layer)

inject.js → content.js → background.js

Uses window.postMessage and chrome.runtime.sendMessage internally.

Extension → Extension (Direct)

External Extension → background.js

Uses chrome.runtime.sendMessageExternal and chrome.runtime.connectExternal.

Message Types

• API_REQUEST / API_RESPONSE: One-time REST API calls
• STREAM_REQUEST / STREAM_CHUNK: Streaming responses (SSE)
• STREAM_ERROR / ERROR: Error responses
• GET_EXTENSION_ID / SET_EXTENSION_ID: Extension detection
• TEST_CONNECTION / TEST_CONNECTION_RESPONSE: Backend testing

Streaming

For streaming communication, use:

import { BODHI_STREAM_PORT, MESSAGE_TYPES } from '@bodhiapp/ext-types';

// Create streaming connection
const port = chrome.runtime.connectExternal(extensionId, {
  name: BODHI_STREAM_PORT
});

// Send streaming request
port.postMessage({
  type: MESSAGE_TYPES.STREAM_REQUEST,
  requestId: 'stream-id',
  request: {
    method: 'POST',
    endpoint: '/v1/chat/completions',
    body: { stream: true, ... }
  }
});

// Handle chunks
port.onMessage.addListener((message: StreamChunkMessage) => {
  if (message.type === MESSAGE_TYPES.STREAM_CHUNK) {
    const chunk = message.response.body;
    if (chunk.done) {
      port.disconnect();
    } else {
      // Process chunk
    }
  }
});

Server State

import type { ServerStateInfo } from '@bodhiapp/ext-types';

// Server state from /bodhi/v1/info endpoint
const serverState: ServerStateInfo = {
  status: 'ready',
  version: '1.0.0',
  url: 'http://localhost:1135'
};

// Possible status values:
// - 'setup': Server requires initial setup
// - 'ready': Server ready for requests
// - 'resource-admin': Server needs resource configuration
// - 'error': Server encountered an error
// - 'unreachable': Cannot connect to server

Architecture

This package is the single source of truth for:

• Message type constants
• Request/response formats
• Streaming protocols
• Error structures
• Server state definitions

Both bodhi-browser-ext and @bodhiapp/bodhijs depend on this package to ensure consistent communication.

License

MIT

Repository

https://github.com/BodhiSearch/bodhi-browser