@honeybee-ai/hivemind-sdk

Platform SDK for the Honeybee Hivemind API. Typed client for marketplace, Colony, Carapace, billing, and telemetry. Zod-validated contracts for every API surface.

Install

npm install @honeybee-ai/hivemind-sdk

Requires Node.js 20+.

Quick start

import { createHivemindClient } from '@honeybee-ai/hivemind-sdk';

const client = createHivemindClient({ profileName: 'personal' });

// List your hives
const { data } = await client.listHives();

// Search the marketplace
const specs = await client.searchSpecs('code-review');

// Scan text with Carapace
const result = await client.scan({ message: 'some user input' });

Authentication uses profiles stored by wgl auth login. The client handles token refresh automatically, with a mutex to prevent concurrent refresh races.

Subpath imports

The package exposes 4 subpath entry points alongside the main export:

@honeybee-ai/hivemind-sdk/contracts

Zod schemas for every API request and response. Namespaced by product surface.

import { marketplace, colony, carapace, billing } from '@honeybee-ai/hivemind-sdk/contracts';

// Validate marketplace input
const parsed = marketplace.publishSpecInput.parse(userInput);

// Shared pagination
import { paginationInput, paginatedResponse } from '@honeybee-ai/hivemind-sdk/contracts';

Covers: marketplace specs, marketplace integrations, Colony hives/keys, Carapace scans/dashboard, billing/pollen, auth, and common pagination/error shapes.

@honeybee-ai/hivemind-sdk/integrations

Types for building Incubator plugins and integration modules.

import type {
  IntegrationModule,
  IntegrationFactory,
  IncubatorPlugin,
  PluginFactory,
  ToolEntry,
  ToolDef,
  ToolResult,
} from '@honeybee-ai/hivemind-sdk/integrations';

IntegrationModule is the base interface (start/stop/onEvent/getTools). IncubatorPlugin extends it with getToolEntries() for rich tool support. Legacy IntegrationModule packages are auto-wrapped by the plugin manager.

@honeybee-ai/hivemind-sdk/telemetry

Local-first telemetry with optional cloud sync. Events write to local JSONL immediately. Cloud ingest is opt-in and pre-aggregated.

import {
  TelemetryReporter,
  createTelemetryFromEnv,
  NO_OP_TELEMETRY,
} from '@honeybee-ai/hivemind-sdk/telemetry';

// Auto-configure from TELEMETRY_ENDPOINT + TELEMETRY_API_KEY env vars
const reporter = createTelemetryFromEnv({ projectRoot: process.cwd() });

// Record an event (sync queue push, never throws)
reporter.record('scan.complete', { score: 42, action: 'PASS' });

// Query local telemetry
import { localOverview, localTimeline, localEvents } from '@honeybee-ai/hivemind-sdk/telemetry';

Telemetry never sends without explicit configuration. NO_OP_TELEMETRY is a safe default that discards everything.

@honeybee-ai/hivemind-sdk/config

Unified config resolution for the Honeybee toolchain. Handles .wglrc files (user preferences) and .honeyb/ directories (runtime state).

import {
  resolveConfig,
  loadProjectRc,
  loadGlobalRc,
  getHomeDir,
  loadSessionState,
  saveSessionState,
} from '@honeybee-ai/hivemind-sdk/config';

import type { WglRcConfig, ResolvedConfig } from '@honeybee-ai/hivemind-sdk/config';

// Resolve all config sources (global rc + project rc + env vars + defaults)
const config: ResolvedConfig = resolveConfig(process.cwd());

Also exports constants (HONEYB_DIR, AUTH_FILE, SPECS_DIR, etc.), auth store helpers, session/brood state management, and log rotation utilities.

Platform client methods

The client returned by createHivemindClient() provides:

| Surface | Methods | |---------|---------| | Marketplace (specs) | searchSpecs, getSpec, downloadSpec, publishSpec, updateSpec, forkSpec, listMySpecs, deleteSpec, listReviews, createReview, deleteReview | | Marketplace (integrations) | searchIntegrations, getIntegration, downloadIntegration, publishIntegration, updateIntegration, deleteIntegration, listIntegrationReviews, createIntegrationReview, deleteIntegrationReview | | Colony | listHives, createHive, getHive, deleteHive, pauseHive, resumeHive, startHive, getHiveEvents, getHiveAgents, setProviderKey, setSecret, listSecrets, deleteSecret, listKeys, createKey, revokeKey | | Billing | getBalance, getTransactions, getRates, purchasePollen, estimateCost | | Carapace | scan, carapaceDashboard, carapaceUsage, carapaceBlocked, listCarapaceKeys, createCarapaceKey, deleteCarapaceKey | | Telemetry | telemetryOverview, telemetryTimeline, telemetryEvents | | Fleet | registerNode, heartbeatNode, listNodes, getNode, removeNode, drainNode | | Auth | getMe |

Auth

import {
  startDeviceFlow,
  pollDeviceFlow,
  exchangeGitHubToken,
  getActiveProfile,
  setProfile,
  listProfiles,
} from '@honeybee-ai/hivemind-sdk';

Device flow authenticates via GitHub OAuth. The CLI (wgl auth login) handles this interactively. The SDK exposes the primitives if you need to build your own auth flow.

License

MIT