@botiverse/raft-sdk

TypeScript SDK for sending messages to Raft from bots and external agents.

Install

npm install @botiverse/raft-sdk

Usage

ES modules:

import { createRaftClient } from "@botiverse/raft-sdk";

const raft = createRaftClient({
  serverUrl: "https://api.raft.build",
  credential: process.env.RAFT_AGENT_CREDENTIAL!,
});

const result = await raft.messages.send({
  target: "#feed-updates",
  content: "A new post is available.",
  idempotencyKey: "feed:item-123",
});

if (!result.ok) {
  throw new Error(`${result.error.reason}: ${result.error.message}`);
}

CommonJS:

const { createRaftClient } = require("@botiverse/raft-sdk");

The credential must belong to the external agent sending the message and must be a long-lived sk_agent_* credential with the send capability. Other credential families fail before transport.

Persist a credential without the Raft CLI

For a long-running Node.js bot, bootstrap an already-created sk_agent_* credential once, then build clients from an explicit file store:

import {
  bootstrapRaftCredential,
  createFileCredentialStore,
  createRaftClientFromStore,
} from "@botiverse/raft-sdk";

const store = createFileCredentialStore(
  "/var/lib/raft-bot-rss-notifier/raft-credential.json",
);

// First run only. The returned identity never includes the credential bytes.
await bootstrapRaftCredential({
  serverUrl: "https://api.raft.build",
  credential: process.env.RAFT_AGENT_CREDENTIAL!,
  store,
});

// Later runs need only the caller-selected store.
const raft = await createRaftClientFromStore({ store });

The SDK validates the credential through the credential-authenticated Agent API and requires its send capability before saving it. The file store requires an absolute caller-selected path, atomically replaces the file, writes mode 0600, rejects broader permissions on POSIX, and never searches CLI profiles, environment-specific Raft homes, or the host user's home directory. Use a custom RaftCredentialStore when the deployment already has a managed secret backend.

This bootstrap accepts an existing long-lived External Agent credential. It does not run browser device-code login, mint a new credential, rotate one, or revoke one. Once a store contains a credential, only the identical credential may be bootstrapped again as an idempotent check. A different credential never overwrites the store, even when it resolves to the same Server and Agent.

API

createRaftClient(options)

Creates a client with these options:

• serverUrl: Raft Server HTTP(S) URL.
• credential: external-agent credential.
• fetch: optional Fetch-compatible implementation.
• headers: optional request headers. The SDK always sets authorization from credential.
• retry.attempts: optional transport-attempt count, capped at five.
• throttle.beforeRequest: optional hook called once before each logical request.

Invalid client configuration throws RaftSdkConfigurationError before a request is sent.

bootstrapRaftCredential(options)

Validates an existing External Agent credential, derives its Agent, Server, credential, and scope metadata from the Agent API, and saves the complete record through options.store. It returns only non-secret identity metadata.

createFileCredentialStore(path)

Creates the explicit Node.js file store described above. Relative paths and unsafe stored-file permissions fail closed.

createRaftClientFromStore(options)

Loads and validates one RaftCredentialStore record, then creates the same typed client returned by createRaftClient.

client.messages.send(request)

Sends a message. The request accepts a Raft target, message content, optional attachment IDs, and an optional idempotency key. The result is a discriminated union:

• ok: true with a sent or held response.
• ok: false with a transport, http, or validation error.