Bridge SDK

BridgeApi

REST API client for ORO Claude Bridge — sessions, messages, and attachments.

BridgeApi

Typed HTTP client for the Bridge REST API. All methods return promises and throw BridgeApiError on non-2xx responses.

Constructor

import { BridgeApi } from '@oro.ad/bridge-sdk'

const api = new BridgeApi({
  baseUrl: 'http://localhost:3000',
  logger: myLogger,           // optional Logger
  timeoutMs: 30_000,          // optional default client-side timeout
  defaultHeaders: {           // optional
    'X-Client-Id': 'my-app'
  }
})

Option	Type	Default	Description
`baseUrl`	`string`	required	Bridge server URL (trailing slash stripped)
`fetch`	`Fetch`	`globalThis.fetch`	Custom fetch implementation
`logger`	`Logger`	`noopLogger`	Optional structured logger
`defaultHeaders`	`Record<string, string>`	`{}`	Headers sent with every request
`timeoutMs`	`number`	—	Default per-request client-side timeout; raises `BridgeTimeoutError` via `AbortController`

Every method throws one of BridgeApiError (non-2xx), BridgeConnectError (transport), BridgeTimeoutError (timeout exceeded), or BridgeValidationError (bad local input, e.g. unreadable attachment file). See errors.

Session Management

listSessions

const sessions: SessionSummary[] = await api.listSessions()

Returns all active sessions with their status, title, model, message count, and loop state.

getSession

const session = await api.getSession('claude_abc123')

createSession

const { conversationId } = await api.createSession({
  title: 'My Session'
})

adoptSession

Attach an existing Claude Code session to the bridge.

const result = await api.adoptSession({
  claudeSessionId: 'sess_xyz',
  title: 'Adopted Session'
})

updateSession / updateSessionTitle

await api.updateSession(conversationId, { title: 'New Title' })
// or shorthand:
await api.updateSessionTitle(conversationId, 'New Title')

deleteSession

await api.deleteSession(conversationId)

Session Control

compactSession

Triggers context compaction (summarization) for a session.

await api.compactSession(conversationId)

clearSession

Clears all messages from a session.

await api.clearSession(conversationId)

setLoopMode

Enable or disable autonomous loop mode.

const { loop } = await api.setLoopMode(conversationId, {
  enabled: true,
  config: {
    trigger: 'idle_timeout',
    idleTimeoutSec: 300,
    resumePrompt: 'Continue working on the task.',
    maxCostUsdPerHour: 5.0
  }
})

Messages

sendMessage

const { messageId } = await api.sendMessage(conversationId, {
  content: 'Hello Claude!',
  attachments: [],
  senderId: 'user_123',
  senderNickname: '@john'
})

getMessages

const { messages, total } = await api.getMessages(conversationId, {
  limit: 50,
  before: 'msg_xyz'   // cursor pagination
})

getMessage

const message: BridgeMessage = await api.getMessage(conversationId, messageId)

getMessageResult

Waits for the assistant to complete processing a message.

const result: MessageResult = await api.getMessageResult(
  conversationId,
  messageId,
  { timeoutMs: 120_000 }
)

console.log(result.content)     // assistant response
console.log(result.costUsd)     // cost in USD
console.log(result.usage)       // token usage breakdown

Attachments

uploadAttachment

Upload from file path or raw bytes.

// From file
const attachment = await api.uploadAttachment(conversationId, {
  filepath: '/path/to/image.png',
  filename: 'image.png',
  mimeType: 'image/png'
})

// From buffer
const attachment = await api.uploadAttachment(conversationId, {
  data: buffer,
  filename: 'doc.pdf',
  mimeType: 'application/pdf'
})

downloadAttachment

const bytes: Uint8Array = await api.downloadAttachment(attachmentId)

deleteAttachment

await api.deleteAttachment(attachmentId)

Health & Info

await api.health()   // { ok: true }
const info = await api.info()
// { version, uptime, claudeVersion, workDir, activeSessions }

listClaudeSessions

List Claude CLI sessions discovered on disk (under ~/.claude/). These are sessions tracked by the Claude CLI itself, not bridge sessions — use adoptSession to promote one into a bridge session.

const found = await api.listClaudeSessions({ limit: 50 })
// [{ sessionId, projectKey, path, cwd, gitBranch, firstUserMessage, modifiedAt, ... }]

Timeouts & cancellation

Set a default timeout on construction (applies to every request) or per-call (overrides the default). Exceeded timeouts throw BridgeTimeoutError:

const api = new BridgeApi({ baseUrl, timeoutMs: 15_000 })

// Per-call override — useful for attachment uploads or long polls:
await api.uploadAttachment(id, file, { timeoutMs: 60_000 })
await api.downloadAttachment(id, { timeoutMs: 60_000 })

getMessageResult has its own timeoutMs that's passed to the server as the long-poll deadline. Set BridgeApiOptions.timeoutMs at least as high to avoid the client timing out before the server responds.

Error handling

import {
  BridgeApiError,
  BridgeConnectError,
  BridgeTimeoutError,
  BridgeValidationError,
} from '@oro.ad/bridge-sdk'

try {
  await api.sendMessage(id, body)
}
catch (err) {
  if (err instanceof BridgeTimeoutError) { /* retry / surface */ }
  else if (err instanceof BridgeApiError && err.status === 404) { /* gone */ }
  else if (err instanceof BridgeConnectError) { /* network down */ }
  else if (err instanceof BridgeValidationError) { /* bad input */ }
  else throw err
}

Overview

Introduction to @oro.ad/bridge-sdk — typed transport layer for ORO Claude Bridge.

BridgeClient

WebSocket client for real-time streaming events from ORO Claude Bridge.