Skip to Content
Baseera Docs

Signals

Tell Baseera something happened: a client signal from your UI with useBaseeraSignal, or a server signal from your backend with baseera.signal, and when checks run again.

Some facts are not in a field: a contract was uploaded, a payment bounced, a carrier changed a shipment. Signals let your app tell Baseera, so a check can depend on them.

There are two kinds. A client signal is sent from the page while the record is open. A server signal is sent from your backend, often while nobody has the record open.

Client signals

import { useBaseeraImmersive, useBaseeraSignal } from "@baseera/react";

function InvoiceScreen({ invoice }: { invoice: Invoice }) {
  const signal = useBaseeraSignal();

  useBaseeraImmersive({
    entity: { type: "invoice", ref: invoice.id },
    fields: [],
    checks: [
      {
        id: "contract-missing",
        severity: "blocking",
        fields: [],
        // `signals` maps each signal's name to the data it last carried.
        run: (_record, { signals }) =>
          "document.uploaded" in signals ? { ok: true } : { ok: false, message: "Upload the signed contract." },
      },
    ],
    finish: { label: "Send", action: ({ receipt }) => sendInvoice(invoice.id, receipt) },
  });

  return <Uploader onUploaded={(file) => signal("document.uploaded", { name: file.name })} />;
}

signal(name, data?) is a client API with no endpoint of its own.

  • With a record open, it re-runs your checks at once, without the 250 ms delay.
  • The latest data of each signal reaches checks as run(record, { signals }), a map of name to data. A signal sent without data is null, so test with in as above.
  • If a check newly fails, the notice logic speaks up as for any other change. See Notices and focus.
  • It is added to the record's trail as a signal event with its name and data.
  • Signals live as long as the record is open. They are cleared when it closes or another record starts.

Prop

Type

A signal that breaks either rule, or that arrives while no record is open, is ignored. In development the console says why.

Server signals

Send one from your backend with your secret key:

lib/baseera.ts
import { createBaseera } from "@baseera/node";

export const baseera = createBaseera({
  agentId: process.env.BASEERA_AGENT_ID!,
  secretKey: process.env.BASEERA_SECRET_KEY!,
  baseUrl: process.env.BASEERA_RUNTIME_URL!,
});
app/api/payments/webhook/route.ts
const result = await baseera.signal(
  { type: "invoice", ref: "INV-7" }, // the same entity you give useBaseeraImmersive
  "payment.received",
  { amount: 120.5, currency: "SAR", method: "bank_transfer" },
  { idempotencyKey: `payment-${payment.id}`, tenantId: org.id }, // both optional
);
if (!result.ok) console.error("baseera signal failed", result.code);

The result is { ok: true, duplicate: false } or { ok: false, code, retryAfter? }, with code one of invalid_request, invalid_server_token, idempotency_conflict, rate_limited or unavailable. It never throws.

The rules

  • Server only. It signs a 60-second token of purpose signal with your secret key. A publishable key or a browser cannot send one.
  • Small, flat, secret-free data. name is an identifier of letters, digits, _ . : -, up to 64 characters. data is a flat object: 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, and the SDK refuses it before anything is sent.
  • Retries are safe. 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.
  • Scope. With tenantId, only that tenant's sessions see the signal. Without it, every session of the agent does.
  • Limits. 600 calls a minute per secret key and 1,200 per agent.

What a server signal does

  1. The signal is kept for the record: 30 days, the newest 50 per record.
  2. It marks the record's cached AI check results stale.
  3. The next time someone opens the record, the AI checks run again, with the newest five signals in front of the model as untrusted data, never as instructions.

The previous result is still shown while the new run happens. A signal cannot set a check's result, and it cannot be used to spend more model calls than a person could: the usual per-record cap and interval apply.

A server signal does not reach checks that run in the browser through run(record, { signals }). Those see client signals only. If a browser check needs a server fact, load it into your page state and read it in the closure.

The Immersive page of the dashboard lists the latest server signals: name, record, tenant and time. Values are not shown. See The dashboard page.

There is no Queue in Baseera yet, so a signal does not add a queue item. Server signals are not on a record's timeline page yet.

Which one to use

The factUse
Happens in the page while the person worksClient signal
Happens in your backend, a partner system or a jobServer signal
Is already in a fieldNeither. A field change re-runs the checks.

Next steps

On this page