Skip to Content
Baseera Docs

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

ExportUse it to
signUserTokenSign the short-lived token your browser sends, so Baseera knows who the user is.
verifyWebhookCheck the signature and timestamp of a webhook from Baseera.
createBaseeraPush knowledge (kb) and send signals from your backend.
verifyFinishGuard the route that finishes a record in immersive mode.
purgeTenantKnowledgeDelete everything one of your tenants has in your knowledge bases.
signTenantUploadTokenSign the token that lets a tenant's admin upload documents.
baseera eval runA 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:

VariableMeaning
BASEERA_SECRET_KEYThe agent's secret key, sk_ and 64 hex characters.
BASEERA_AGENT_IDThe agent's id (a uuid).
BASEERA_RUNTIME_URLThe 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.

app/api/invoices/[id]/send/route.ts
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? }
  • name is an identifier: letters, digits and _ . : -, up to 64 characters.
  • data is a flat object of up to 20 keys, values are strings (up to 500 characters), numbers, booleans or null, 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 answers duplicate: true. The same key with different content is idempotency_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
OptionMeaning
--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 jsonWrite 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.
--yesStart 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.

.github/workflows/agent-evals.yml
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 }

Next steps

On this page