Validation
The helpers in @baseera/core that check input the way the runtime does, so a bad value is caught before it is sent.
@baseera/core exports small pure functions that mirror the runtime's own checks. Use them to refuse bad input early, with a clear message, instead of waiting for a 400. They never make a network call.
Keys
import { keyKind } from "@baseera/core";
keyKind("pk_" + "a".repeat(48)); // "publishable"
keyKind("sk_" + "a".repeat(64)); // "secret"
keyKind("something-else"); // nullkeyKind(key) returns the kind a key claims to be, or null when it is not shaped like a Baseera key: pk_ and 48 hex characters, or sk_ and 64 hex characters. It does not check that the key exists. maskSecretKey(last4) returns the display form sk_•••••••• plus the last four characters.
Allowed domains
Each agent has a list of allowed domains. The runtime refuses a request from any other origin.
import { normalizeAllowedOrigin, isOriginAllowed } from "@baseera/core";
normalizeAllowedOrigin(" App.Example.com/ "); // "app.example.com"
normalizeAllowedOrigin("not a domain"); // null
isOriginAllowed("https://app.example.com", ["app.example.com"]); // true
isOriginAllowed("https://shop.example.com", ["*.example.com"]); // true
isOriginAllowed("https://example.com", ["*.example.com"]); // falseEntry forms are app.example.com, localhost:3000, https://app.example.com and *.example.com. Without a scheme, https is required, except for localhost and 127.0.0.1, where http is also accepted. Without a port, only the scheme's default port matches. A wildcard matches any subdomain, never the bare domain. An agent holds at most MAX_ALLOWED_ORIGINS (50) entries.
Signals
import { parseSignalRequest, looksLikeSecret, SIGNAL_LIMITS } from "@baseera/core";
const parsed = parseSignalRequest({
entity: { type: "invoice", ref: "INV-7" },
name: "payment.received",
data: { amount: 120.5, currency: "SAR" },
});
if (!parsed.ok) console.error(parsed.message);parseSignalRequest(body) returns { ok: true, value } or { ok: false, message }. looksLikeSecret(value) is true for a string shaped like a secret. SIGNAL_LIMITS holds the limits: name up to 64 characters, up to 20 data keys, strings up to 500 characters, 2,048 bytes of data, and an 8,192-byte body.
Tenant uploads
import { checkTenantUpload } from "@baseera/core";
const problem = checkTenantUpload(file.name, file.size);
if (problem) showError(problem); // a TenantUploadErrorCode, or null when the file is fineIt mirrors the runtime's checks on the file name, type, size and emptiness, so a bad file is refused before it is sent. The codes are type, size, empty and name, among others.
User token claims
import { normalizeUserClaims } from "@baseera/core";
normalizeUserClaims({ plan: "pro", groups: ["finance", "admin"] });
// { plan: ["pro"], groups: ["finance", "admin"] }
normalizeUserClaims({ "bad name!": "x" }); // nullIt returns the claims with every value as a list, or null when anything is off. Nothing is repaired. See Signing user tokens for the limits.
Themes
import { validateAgentTheme, sanitizeAgentTheme, isSafeThemeColor } from "@baseera/core";
isSafeThemeColor("#3a86a4"); // true
isSafeThemeColor("red; background: url(x)"); // false
validateAgentTheme({ radius: "40px" });
// [{ field: "radius", code: "bad_radius", message: "The radius is 0px to 32px." }]
sanitizeAgentTheme({ radius: "12px", accent: { light: "#3a86a4" }, extra: 1 });
// { radius: "12px", accent: { light: "#3a86a4" } }isSafeThemeColor(value)accepts a plain color: hex,rgb(),hsl()oroklch()with numbers only, at most 64 characters.validateAgentTheme(raw)lists every problem. An empty array means the theme is valid. Codes arenot_an_object,unknown_field,bad_color,bad_pair,bad_radius,bad_fontandbad_logo.sanitizeAgentTheme(raw)keeps only the valid parts, or returnsundefinedwhen nothing is left. It never throws. The SDK runs everything it receives through it.parseThemeColor,contrastRatio,deriveStateToneandTHEME_MIN_CONTRAST(4.5) help you check readability.
Logos
inspectLogo(bytes) checks an image before upload. It returns { ok: true, type, width, height } or { ok: false, problem }, where problem is empty, too_large, unsupported_type, corrupt, animated, dimensions, trailing_data or disallowed_chunk. A logo is a PNG or WebP of at most 256 KB (LOGO_LIMITS.maxBytes) and 512 pixels on a side.
Tool input
validateJsonSchema(value, schema, options?) checks a value against a JSON Schema and returns a list of problem messages. It is empty when the value is valid.
import { validateJsonSchema } from "@baseera/core";
const problems = validateJsonSchema({ id: 5 }, { type: "object", properties: { id: { type: "string" } }, required: ["id"] });