Skip to Content
Baseera Docs

TypeScript

Tips for typing tools, events, messages and tokens with the Baseera packages.

Every package ships its own types, for both ESM and CommonJS. You do not install separate @types packages.

Type a tool's input

useBaseeraTool infers the type of run and describe from your Zod schema, so you do not write it twice.

import { useBaseeraTool } from "@baseera/react";
import { z } from "zod";

const markPaidInput = z.object({ number: z.string(), paidOn: z.string().date() });

useBaseeraTool({
  name: "markInvoicePaid",
  description: "Mark an invoice as paid",
  kind: "write",
  input: markPaidInput,
  run: ({ number, paidOn }) => api.markPaid(number, paidOn), // number: string, paidOn: string
});

Reuse the type elsewhere with z.infer:

type MarkPaidInput = z.infer<typeof markPaidInput>;

input must be a z.object(...). Zod 4 is required.

Narrow stream events

SequencedEvent is a union on type, so a switch narrows event for you. Use Extract to name one member:

import type { SequencedEvent } from "@baseera/core";

type ToolCallEvent = Extract<SequencedEvent, { type: "tool.call" }>;

const calls: ToolCallEvent[] = [];
for await (const event of turn) {
  switch (event.type) {
    case "text.delta":
      append(event.delta);
      break;
    case "tool.call":
      calls.push(event);
      break;
    case "error":
      report(event.error.code);
      break;
  }
}

The protocol can add event types. Keep a default branch that ignores what it does not know.

Narrow messages

import type { ChatMessage } from "@baseera/react";

function sourcesOf(message: ChatMessage) {
  return message.role === "assistant" ? message.sources : [];
}

message.role tells the union apart: "user" messages have no toolCalls or sources.

Narrow results

The server helpers return discriminated unions on ok:

const result = await verifyFinish(options);
if (!result.ok) {
  return Response.json({ error: result.code }, { status: result.code === "unavailable" ? 503 : 409 });
}
result.finish.userId; // typed after the check

Narrow errors

import { BaseeraError, type ClientErrorCode } from "@baseera/core";

function isRetryable(code: ClientErrorCode): boolean {
  return code === "rate_limited" || code === "provider_rate_limited" || code === "network_error";
}

try {
  await client.startSession();
} catch (error) {
  if (error instanceof BaseeraError && isRetryable(error.code)) retry();
}

Where the types live

You needImport from
ChatMessage, ChatState, ToolKind, Source, PendingApproval, RegisteredTool, TurnContext@baseera/react or @baseera/core
BaseeraProviderProps, BaseeraTheme, BaseeraChat, BaseeraApprovals, BaseeraToolOptions@baseera/react
BaseeraSurfaceProps, BaseeraApprovalsProps, BaseeraFieldProps@baseera/ui/connected
ApprovalCardProps, ToolStatusProps, BaseeraThemeInput, SurfaceLabels, ApprovalLabels@baseera/ui
BaseeraStaticChatProps@baseera/ui/static
UserTokenInput, SignUserTokenOptions, UserTokenClaims@baseera/node or @baseera/core
VerifyWebhookResult, BaseeraWebhookEvent, KbUpsertInput, BaseeraOptions@baseera/node
SequencedEvent, TurnEvent, ErrorCode, ClientErrorCode@baseera/core

Module resolution

The packages have an exports map with types first, and both import and require conditions. Use moduleResolution of bundler, node16 or nodenext. The older node (node10) resolution does not read exports and will not find the subpath entries @baseera/ui/connected and @baseera/ui/static.

tsconfig.json
{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler",
    "jsx": "preserve"
  }
}

Next steps

On this page