@beeos-ai/bridge-client

Ed25519 authenticated WebSocket client for connecting agents to the BeeOS Bridge server.

Install

npm install @beeos-ai/bridge-client

Quick Start

import { BridgeClient, generateKeyPair } from "@beeos-ai/bridge-client";

// Generate a keypair (saved to disk for reuse)
const keys = generateKeyPair("./agent-keys.json");

const client = new BridgeClient({
  bridgeUrl: "wss://bridge.beeos.ai",
  service: "my-agent",
  keyFile: "./agent-keys.json",
});

client.on("connected", () => {
  console.log("Connected to bridge");
  client.send(JSON.stringify({ type: "hello" }));
});

client.on("message", (data) => {
  console.log("Received:", data.toString());
});

client.on("disconnected", (reason) => {
  console.log("Disconnected:", reason);
});

client.on("error", (err) => {
  console.error("Error:", err);
});

await client.connect();

Authentication

The client authenticates with an Ed25519 keypair. You can provide keys in three ways:

Key file (recommended) — auto-generates if file doesn't exist:

const client = new BridgeClient({
  bridgeUrl: "wss://bridge.beeos.ai",
  service: "my-agent",
  keyFile: "./keys.json",
});

Raw keys:

const client = new BridgeClient({
  bridgeUrl: "wss://bridge.beeos.ai",
  service: "my-agent",
  privateKey: myPrivateKey,  // Uint8Array (32 bytes)
  publicKey: myPublicKey,    // Uint8Array (32 bytes)
});

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | bridgeUrl | string | — | Bridge server WebSocket URL | | service | string | — | Service/agent identifier | | keyFile | string | — | Path to key file (JSON or raw base64 seed) | | privateKey | Uint8Array | — | Raw Ed25519 private key (32 bytes) | | publicKey | Uint8Array | — | Raw Ed25519 public key (32 bytes) | | reconnect.enabled | boolean | true | Auto-reconnect on disconnect | | reconnect.maxRetries | number | Infinity | Max reconnect attempts | | reconnect.baseDelay | number | 1000 | Base delay in ms (exponential backoff) | | reconnect.maxDelay | number | 30000 | Max delay in ms | | heartbeat.interval | number | 30000 | Ping interval in ms | | heartbeat.timeout | number | 10000 | Pong timeout in ms | | proxy | string | $HTTPS_PROXY | HTTPS proxy URL |

API

BridgeClient

• connect(): Promise<void> — Connect and authenticate with the bridge.
• send(data: string | Buffer): Promise<void> — Send data to the bridge.
• close(graceful?: boolean): Promise<void> — Disconnect. Graceful (default) sends close frame; non-graceful terminates immediately.
• state — Current state: "idle" | "connecting" | "connected" | "reconnecting" | "closed".
• publicKey — Base64-encoded Ed25519 public key.
• publicKeyFingerprint — SHA-256 hex fingerprint of the public key.

Events

• connected — Connection established and authenticated.
• disconnected(reason: string) — Connection lost.
• message(data: Buffer | string) — Data received from bridge.
• error(err: Error) — Error occurred.

Key Utilities

• generateKeyPair(saveTo?: string): KeyPair — Generate a new Ed25519 keypair.
• loadKeyPair(filePath: string): KeyPair — Load keypair from file (auto-generates if missing).
• fingerprint(publicKey: Uint8Array): string — SHA-256 hex fingerprint.

Requirements

• Node.js >= 18

License

MIT