@heossi/bee

Official TypeScript / JavaScript SDK for Bee — The Progressive Intelligence Engine by HEOSSI.

Bee exposes an OpenAI-compatible /chat/completions surface backed by a domain-specialised LoRA-routed model ladder — Cell, Brood, Comb, Buzz, Hive, Swarm, Enclave. This SDK is the typed entry point.

• ✅ Pure ESM, zero runtime dependencies
• ✅ Native fetch (Node 18+, Deno, Bun, every browser)
• ✅ Streaming via async iterator
• ✅ Multimodal content (text + image_url) on Hive / Swarm / Enclave
• ✅ Structured errors (BeeAuthError, BeeRateLimitError, BeeTimeoutError)

Install

npm install @heossi/bee
# or pnpm add @heossi/bee
# or yarn add @heossi/bee

Quickstart

Get an API key from bee.heossi.com/app/account/api-keys.

import { BeeClient } from "@heossi/bee";

const bee = new BeeClient({ apiKey: process.env.BEE_API_KEY! });

const out = await bee.chat.completions.create({
  model: "bee-cell",
  messages: [
    { role: "system", content: "You are a precise assistant." },
    { role: "user", content: "Summarise the SOLID principles in 2 lines." },
  ],
});

console.log(out.choices[0].message.content);

Streaming

const stream = await bee.chat.completions.create({
  model: "bee-cell",
  messages: [{ role: "user", content: "Write a short haiku about bees." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

Vision (Hive / Swarm / Enclave tiers)

const out = await bee.chat.completions.create({
  model: "bee-hive",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "What is in this image?" },
        {
          type: "image_url",
          image_url: { url: "https://example.com/photo.jpg" },
        },
      ],
    },
  ],
});

List models

const { data } = await bee.models.list();
for (const m of data) console.log(m.id);

Self-hosted Bee Enclave

Override baseURL to point at your on-prem deployment:

const bee = new BeeClient({
  apiKey: process.env.BEE_API_KEY!,
  baseURL: "https://bee.your-company.example/bee",
});

Error handling

import { BeeAuthError, BeeRateLimitError, BeeTimeoutError } from "@heossi/bee";

try {
  await bee.chat.completions.create({ messages: [{ role: "user", content: "Hi" }] });
} catch (err) {
  if (err instanceof BeeRateLimitError) {
    console.warn(`Rate-limited. Retry after ${err.retryAfterSeconds}s`);
  } else if (err instanceof BeeAuthError) {
    console.error("Bad API key or plan does not grant this tier");
  } else if (err instanceof BeeTimeoutError) {
    console.error("Request timed out");
  } else {
    throw err;
  }
}

OpenAI SDK compatibility

Because Bee speaks the OpenAI Chat Completions wire format, you can also point the official openai package at Bee directly — useful for migration:

import OpenAI from "openai";

const bee = new OpenAI({
  apiKey: process.env.BEE_API_KEY,
  baseURL: "https://bee.heossi.com/bee",
});

@heossi/bee is the lighter, dependency-free option when you don't need the full OpenAI SDK surface.

Other surfaces

• MCP server for Claude Desktop / Cursor / VS Code → see bee.heossi.com/docs/mcp
• Python SDK → pip install bee-sdk
• REST reference → bee.heossi.com/docs
• Status & roadmap → bee.heossi.com/status, bee.heossi.com/roadmap

License

Apache-2.0 — © HEOSSI (Pte.) Ltd.