@bayonai/sdk

TypeScript SDK for the BayonAI Firebase API.

Published package: @bayonai/sdk

npm install @bayonai/sdk

import { createBayonAiClient } from "@bayonai/sdk";

const bayonai = createBayonAiClient({
  apiKey: process.env.BAYONAI_API_KEY,
});

const response = await bayonai.conversations.send({
  personaId: "journalapp",
  messages: [{ role: "user", content: "TEST" }],
});

The SDK keeps the API's chat contract intact: messages is sent to BayonAI as a stringified JSON array.

The SDK has the deployed BayonAI API endpoint hardcoded. Consumers do not configure a base URL; endpoint changes are released with a new SDK version.

The package requires an environment with fetch, URL, and AbortController (for example, Node.js 18+ or a modern browser). A custom fetch implementation can be supplied when the host owns its transport.

Authentication

Server-side integrations can pass an organization API key:

const bayonai = createBayonAiClient({
  apiKey: process.env.BAYONAI_API_KEY,
});

External-user flows can use bearer tokens per request:

await bayonai.conversations.send(
  {
    personaId: "agent-1",
    messages: [{ role: "user", content: "Hello" }],
  },
  { bearerToken: accessToken },
);

API keys are for server-side integrations and should be kept in secret management. External-user sessions should use the per-request bearer token; the bearer token takes precedence over the configured API key. Pass credentials only through apiKey or bearerToken; the SDK deliberately removes authorization and x-api-key values supplied through custom headers.

Timeout and cancellation

Requests have no timeout by default for backward compatibility. Set a positive client-level timeout, and use an AbortController when the host needs to cancel one request:

const bayonai = createBayonAiClient({
  apiKey: process.env.BAYONAI_API_KEY,
  timeoutMs: 30_000,
});

const controller = new AbortController();
const response = await bayonai.conversations.send(
  {
    personaId: "journalapp",
    messages: [{ role: "user", content: "Hello" }],
  },
  { signal: controller.signal },
);

Timeouts and aborts reject with BayonAiError using kind: "network".

Response behavior

The SDK parses application/json and application/*+json responses. Successful HTTP 204 and 205 responses resolve to undefined; unsuccessful responses remain BayonAiError values with kind: "http", even when an upstream JSON body is empty or malformed.

CommonJS

The published package also supports CommonJS consumers:

const { createBayonAiClient } = require("@bayonai/sdk");

const bayonai = createBayonAiClient({
  apiKey: process.env.BAYONAI_API_KEY,
});

Verification and release

From packages/bayonai-sdk:

npm run build
npm test
npm run consumer:smoke
npm run release:dry-run

consumer:smoke verifies ESM imports, CommonJS requires, and TypeScript declarations from the packed tarball. Release changes are recorded in CHANGELOG.md; release:dry-run must pass before a real public publish.