Node
Server helpers for Baseera hosts: sign user tokens, verify webhooks, push knowledge, guard finish routes, and run evals from CI.
@baseera/node is for your backend and your CI. It holds everything that needs the agent's secret key (sk_), so none of it can run in a browser.
import { signUserToken, verifyFinish, verifyWebhook, createBaseera } from "@baseera/node";It needs Node 20 or later, and has no peer dependencies. Never import it into browser code, and never log or return a secret key.
What it does
| Export | Use it to |
|---|---|
signUserToken | Sign the short-lived token your browser sends, so Baseera knows who the user is. |
verifyWebhook | Check the signature and timestamp of a webhook from Baseera. |
createBaseera | Push knowledge (kb) and send signals from your backend. |
verifyFinish | Guard the route that finishes a record in immersive mode. |
purgeTenantKnowledge | Delete everything one of your tenants has in your knowledge bases. |
signTenantUploadToken | Sign the token that lets a tenant's admin upload documents. |
baseera eval run | A command that runs an agent's eval suite in CI. |
Environment
The helpers that call the runtime read these values from your environment, which you pass in:
| Variable | Meaning |
|---|---|
BASEERA_SECRET_KEY | The agent's secret key, sk_ and 64 hex characters. |
BASEERA_AGENT_ID | The agent's id (a uuid). |
BASEERA_RUNTIME_URL | The runtime's URL. It must be https, except for localhost. |
Every server-to-server call signs a fresh 60-second token with your secret key and sends the token and the agent id. The key itself is never sent, and never logged.
verifyFinish
In immersive mode, finish() in the browser records the finish with Baseera and gets a single-use receipt. Then it calls your finish.action({ receipt }), which posts the receipt to your route. Your route must call verifyFinish before it changes anything.
import { verifyFinish } from "@baseera/node";
export async function POST(request: Request, { params }: { params: Promise<{ id: string }> }) {
const { id } = await params;
const { receipt } = await request.json();
const invoice = await db.invoice.findUnique({ where: { id } });
if (!invoice || invoice.status === "closed") return Response.json({ error: "closed" }, { status: 409 });
// Your own blocking checks, computed here from your data, not taken from the browser.
const blocking: string[] = [];
if (!invoice.taxId) blocking.push("tax-id-missing");
const result = await verifyFinish({
receipt,
entity: { type: "invoice", ref: id },
openBlocking: blocking,
agentId: process.env.BASEERA_AGENT_ID!,
secretKey: process.env.BASEERA_SECRET_KEY!,
baseUrl: process.env.BASEERA_RUNTIME_URL!,
});
if (!result.ok) return Response.json({ error: result.code }, { status: result.code === "unavailable" ? 503 : 409 });
await db.invoice.update({ where: { id }, data: { status: "sent", sentBy: result.finish.userId } });
return Response.json({ ok: true });
}What it guarantees
Check results run in the browser, so Baseera cannot vouch that they are true. The guarantee is narrower:
- The finish was recorded by Baseera first, for this record and agent, once, in the last 10 minutes.
- The record says which blocking checks were open (as the browser reported them), who finished, when, and the written override reason (10 to 1,000 characters), which must cover every open check.
- If you pass your own server-computed blocking check ids as
openBlocking, the override must cover those too. That part does not depend on the browser, so compute them from your own data and always pass them.
A route that never calls verifyFinish gets none of this.
Options and result
Prop
Type
{ ok: true, finish: { userId, tenantId, openBlocking, override: { reason, checks } | null, createdAt } }
{ ok: false, code: "receipt_not_found" | "entity_mismatch" | "receipt_expired" | "receipt_used" | "override_required" | "unavailable" }verifyFinish never throws and fails closed. A network error, a timeout (5 seconds), a redirect, a non-200 status, a malformed body, a bad key or a non-HTTPS baseUrl (except localhost) all return { ok: false, code: "unavailable" }. Treat unavailable as a refusal and let the person retry. A successful call uses the receipt up: if your route fails after it, the person finishes again to get a new receipt.
purgeTenantKnowledge
Deletes everything one of your tenants has in your organization's knowledge bases: sources, documents, chunks and embeddings. Knowledge shared by all tenants, and other tenants, are not touched. Call it when a customer leaves or asks to be forgotten.
import { purgeTenantKnowledge } from "@baseera/node";
const result = await purgeTenantKnowledge({
tenantId: org.id, // the same id you put in your users' tokens
agentId: process.env.BASEERA_AGENT_ID!,
secretKey: process.env.BASEERA_SECRET_KEY!,
baseUrl: process.env.BASEERA_RUNTIME_URL!,
});
if (result.ok) console.log(result.record); // { id, tenantId, sources, chunks, requestedAt, completedAt }Otherwise the result is { ok: false, code: "invalid_server_token" | "invalid_request" | "unavailable" }. Nothing is known to be deleted, so retry on unavailable. Purging twice is harmless.
signal
Some events have no user on the page: a payment arrives, a carrier updates a shipment. Send them from your backend so the record's AI checks run again the next time someone opens it.
import { createBaseera } from "@baseera/node";
const baseera = createBaseera({
agentId: process.env.BASEERA_AGENT_ID!,
secretKey: process.env.BASEERA_SECRET_KEY!,
baseUrl: process.env.BASEERA_RUNTIME_URL!,
});
const result = await baseera.signal(
{ type: "invoice", ref: "INV-7" },
"payment.received",
{ amount: 120.5, currency: "SAR", method: "bank_transfer" },
{ idempotencyKey: `payment-${payment.id}`, tenantId: org.id },
);
// { ok: true, duplicate: false } | { ok: false, code, retryAfter? }nameis an identifier: letters, digits and_ . : -, up to 64 characters.datais a flat object of up to 20 keys, values are strings (up to 500 characters), numbers, booleans ornull, 2 KB in all. A key named like a secret (password,token,apiKey) or a value shaped like one is refused before anything is sent.- The SDK sends an
Idempotency-Key(yours, or a random one) and tries once more after a network error or a 5xx. The same key with the same content answersduplicate: true. The same key with different content isidempotency_conflict. - Limits: 600 calls a minute per secret key and 1,200 per agent. A signal is kept for 30 days, the newest 50 per record.
Run evals from CI
The package installs a baseera command that starts one of an agent's eval suites, waits for it, prints a summary, and exits with a code your pipeline can act on.
export BASEERA_AGENT_ID=6f1c1f3e-2b7a-4d3e-9a51-0c1d2e3f4a5b
export BASEERA_SECRET_KEY=sk_your_secret_key
export BASEERA_URL=https://runtime.example.com
npx baseera eval run --suite core --target draft --repeats 3 --report junit --out reports/baseera.xml --yes| Option | Meaning |
|---|---|
--agent <id> | The agent's id (uuid). Default $BASEERA_AGENT_ID. |
--suite <name or id> | A suite of that agent, by name (unique per agent, case-insensitive, Arabic names work) or by id. |
--target <t> | production (default), draft, or a version such as v7. |
--repeats <1-5> | Run every case this many times. Default 1. |
--min-pass-rate <0-100> | Fail below this pass rate. Default: the agent's own minimum for publishing. |
--report junit or --report json | Write a report, to --out <file> or to standard output. |
--timeout <seconds> | Stop waiting after this long (10 to 3600, default 600). The run itself keeps going. |
--yes | Start the run. |
--url <url> | The runtime's URL. Default $BASEERA_URL. |
A run calls the model with your organization's own provider key and costs money. Without --yes the command only prints the estimate and exits with code 2.
Exit codes: 0 the suite reached the pass rate, 1 it did not, 2 anything else (bad usage or configuration, a rejected key, a run already in progress, a limit, a run that could not finish, a timeout). A pipeline that must not pass on infrastructure trouble should treat any non-zero code as a failure.
name: agent-evals
on:
pull_request:
jobs:
evals:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/setup-node@v4
with: { node-version: 22 }
- name: Run the core suite on the draft
env:
BASEERA_AGENT_ID: ${{ vars.BASEERA_AGENT_ID }}
BASEERA_SECRET_KEY: ${{ secrets.BASEERA_SECRET_KEY }}
BASEERA_URL: ${{ vars.BASEERA_URL }}
run: npx --yes --package @baseera/node baseera eval run --suite core --target draft --report junit --out baseera.xml --yes
- uses: actions/upload-artifact@v4
if: always()
with: { name: baseera-evals, path: baseera.xml }