@tonbo/sdk
v1.1.0
Published
The Tonbo SDK: your Tonbo key, Streams tokens and databases opened by name.
Readme
@tonbo/sdk
The Tonbo SDK for Node.js: your Tonbo key, Streams tokens, and Tonbo databases opened by name.
npm install @tonbo/sdk @tonbo/[email protected]@tonbo/sqlite-ursula (0.11.3 or later in 0.11) is an optional peer, needed only by @tonbo/sdk/database. Node.js 22.19 or later.
Open a database by name
import { openDatabase } from "@tonbo/sdk/database";
const db = await openDatabase("notes"); // a node:sqlite DatabaseSync
db.exec("CREATE TABLE IF NOT EXISTS notes (body TEXT)");
db.prepare("INSERT INTO notes VALUES (?)").run("hello");
await db.synced(); // the commit is in the stream
db.close();openDatabase looks the name up in the Management API, waits while the database is being created, and opens it with @tonbo/sqlite-ursula, handing that package a token provider that exchanges your key for short-lived Streams tokens. Your key never reaches the data plane. The signal or timeoutMs (30 s by default) bounds the lookup and the open together. resolveDatabase(name) answers { url, token } for any other opener.
A process sends one token at a time, so every database open on a thread at once uses one credential; an open with another one fails second_credential.
The client
import { Tonbo } from "@tonbo/sdk";
const tonbo = new Tonbo(); // apiKey, else TONBO_API_KEY, else your `tonbo login`
const acme = new Tonbo({ account: "acme" }); // your login, acting in the acme organization
const { token, expiresAt } = await tonbo.tokens.streams();
const forBrowser = await tonbo.tokens.downScope({
databases: ["notes"],
readOnly: true,
expiresIn: 300,
});
const created = await tonbo.databases.create("notes");
const all = await tonbo.databases.list();
await tonbo.databases.delete("notes");- The credential is the
apiKeyoption, elseTONBO_API_KEY, else yourtonbo loginon this computer (from@tonbo/cli0.12,~/.config/tonbo/login.json), else the file an oldertonbo loginwrote. A login file is never read when it is a symlink or readable by group or others, and a login made on another computer is refused. - The account. An API key reaches only its own account. Your
tonbo loginreaches every account you belong to, one at a time: theaccountoption (a name or id), elseTONBO_ACCOUNT, else the defaulttonbo account useset, else your personal account. Beside an API key,accountandTONBO_ACCOUNTmust name the key's own account. Agents and CI should use an Agent key or an API key of one account, not your login. - Origins.
apiOrigin, elseTONBO_API_ORIGIN, elsehttps://api.tonbo.dev; the token endpoint's origin isauthOrigin, elseTONBO_AUTH_ORIGIN, else the API origin without itsapi.label. Each is https, or http to a loopback host. - Network. The SDK's own requests use Node's
fetch, so its trust store and proxy settings apply to them, notURSULA_VFS_CA_FILE.
Errors
Every failure is a TonboError with a kind, an action (retry, stop or fix), a fix where one is known, the status and the requestId. A refused key reaches a database open as the cause of @tonbo/sqlite-ursula's unauthorized error. No message carries a key or a token.
The rules this package follows are contracts/sdk/v1.json in the Tonbo repository.
