# TypeScript types

Every type the NPM packages export. Most are re-exported from `@livelayer/sdk` through `@livelayer/react`, so importing from either works.

```ts
import type {
  AgentState,
  ConnectionState,
  TranscriptEntry,
  AgentConfig,
  AgentCommand,
  AgentCapability,
  AvatarWidgetProps,
  AvatarWidgetHandle,
  ControlledSession,
  DisplayMode,
  WidgetPosition,
  TeamMember,
  BrandingConfig,
  RoutePattern,
  PageContext,
  SoundEffectsConfig,
  AgentEventDetail,
  SessionOptions,
  SessionCallbacks,
  TrackerConfig,
  VisitorInfo,
} from "@livelayer/react";
```

## Session lifecycle

### `ConnectionState`

```ts
type ConnectionState = "idle" | "connecting" | "connected" | "disconnected" | "error";
```

The state of the LiveKit room connection.

### `AgentState`

```ts
type AgentState = "idle" | "listening" | "thinking" | "speaking";
```

What the agent is doing right now. Drives UI cues like the "thinking" pulse and mic-active indicator.

### `TranscriptEntry`

```ts
interface TranscriptEntry {
  id: string;
  role: "agent" | "user";
  text: string;
  final: boolean;
}
```

A single transcript line. Partial entries (`final: false`) are streamed in as the speaker talks; the final version replaces them once the speaker finishes.

### `AgentConfig`

```ts
interface AgentConfig {
  name: string;
  avatarImageUrl: string;
  idleLoopUrl?: string;
}
```

Server-published agent metadata. Surfaced once the session connects.

## Display & layout

### `DisplayMode`

```ts
type DisplayMode = "hidden" | "minimized" | "expanded";
```

Used by `<AvatarWidget>`'s `displayMode` and `defaultDisplayMode`.

### `WidgetPosition`

```ts
type WidgetPosition =
  | "top-left"
  | "top-right"
  | "bottom-left"
  | "bottom-right"
  | "custom";
```

Where the floating bubble docks. `"custom"` means "I'll position it myself with `className` / `style`."

## Agent commands & events

### `AgentCommand`

```ts
type AgentCommand = {
  type: string;
  [key: string]: unknown;
};
```

An open union — anything the agent emits over its data channel. Universal commands (`navigate`, `scroll_page`, `scroll_to`, `click`, `fill_field`, `submit_form`) are handled by the widget; everything else gets surfaced via `onAgentCommand` for your app to handle.

### `AgentCapability`

```ts
type AgentCapability =
  | "navigate"
  | "scroll"
  | "click"
  | "fill_forms"
  | "submit_forms"
  | "read_page";
```

Allowlist for what the agent is permitted to do on your page. See [Capabilities in `<AvatarWidget>`](/docs/develop/npm/react/avatar-widget#capabilities).

### `AgentEventDetail`

```ts
interface AgentEventDetail {
  eventName: string;
  data?: unknown;
}
```

The wrapper for every observability event surfaced to `onAgentEvent`. Use for analytics, logging, or piping to your own event bus.

## Component props

### `AvatarWidgetProps`

The full prop type for `<AvatarWidget>`. See the [reference page](/docs/develop/npm/react/avatar-widget) for every field.

### `AvatarWidgetHandle`

```ts
interface AvatarWidgetHandle {
  sendData(data: Record<string, unknown>): Promise<void>;
}
```

Imperative methods exposed via `forwardRef`. Right now only `sendData` (publish over the LiveKit data channel).

### `ControlledSession`

```ts
interface ControlledSession {
  agentId: string;
  baseUrl?: string;
  connectionState: ConnectionState;
  agentState: AgentState;
  transcript: TranscriptEntry[];
  agentConfig: AgentConfig | null;
  videoElement: HTMLVideoElement | null;
  audioElement: HTMLAudioElement | null;
  canResume: boolean;
  error: string | null;
  connect(): Promise<void>;
  disconnect(): void;
  sendData?(data: Record<string, unknown>): Promise<void>;
  subscribeToDataMessages?(handler: (msg: Record<string, unknown>) => void): () => void;
}
```

Pass to `<AvatarWidget>`'s `controlledSession` prop when you own the session lifecycle. See [Controlled session](/docs/develop/npm/react/controlled-session).

### `BrandingConfig`

```ts
interface BrandingConfig {
  logoUrl?: string;
  productName?: string;
  primaryColor?: string;
  accentColor?: string;
  backgroundColor?: string;
  textColor?: string;
}
```

### `TeamMember`

```ts
interface TeamMember {
  id: string;
  name: string;
  role?: string;
  avatarImageUrl?: string;
  previewVideoUrl?: string;
  agentId?: string;
}
```

Used by `<AvatarWidget>`'s `teamMembers` prop.

### `SoundEffectsConfig`

```ts
interface SoundEffectsConfig {
  chime?: boolean;
  confirmation?: boolean;
  thinking?: boolean;
}
```

Toggle individual sound effects.

## Routing

### `RoutePattern`

```ts
type RoutePattern = string | RegExp | ((pathname: string) => boolean);
```

Used by `showOn` and `hideOn`. Strings support glob-style `*` (single segment) and `**` (any depth).

## Page awareness

### `PageContext`

```ts
interface PageContext {
  headings: Array<{ level: number; text: string }>;
  links: Array<{ href: string; text: string }>;
  visibleText: string;
  formFields: Array<{ name: string; label: string; type: string; required?: boolean }>;
  regions: Array<{ name: string; description?: string; text: string }>;
  extras?: Record<string, unknown>;
}
```

The DOM snapshot sent to the agent on `request_page_context`. Override extraction via `getPageContext` on `<AvatarWidget>`.

## Session options

### `SessionOptions`

```ts
interface SessionOptions {
  agentId: string;
  baseUrl?: string;
  apiKey?: string;
  sessionEndpoint?: string;
  sessionBody?: Record<string, unknown>;
}
```

Passed to `useLiveKitSession()` and `new LiveKitSession()`.

### `SessionCallbacks`

```ts
interface SessionCallbacks {
  onConnectionStateChange?: (state: ConnectionState) => void;
  onAgentStateChange?: (state: AgentState) => void;
  onTranscript?: (entries: TranscriptEntry[]) => void;
  onAgentConfig?: (config: AgentConfig) => void;
  onAudioTrack?: (audio: HTMLAudioElement) => void;
  onVideoTrack?: (video: HTMLVideoElement) => void;
  onVideoTrackRemoved?: () => void;
  onError?: (message: string, code?: string) => void;
  onDataMessage?: (msg: Record<string, unknown>) => void;
  onResumabilityChange?: (canResume: boolean) => void;
}
```

The full callback set settable on a `LiveKitSession` instance. Used directly in vanilla SDK consumption; wrapped by `useLiveKitSession` for React.

## Tracker

### `TrackerConfig`

```ts
interface TrackerConfig {
  agentId: string;
  apiBase?: string;
  autoTrack?: boolean;
  autoTrackClicks?: boolean;
}
```

### `VisitorInfo`

```ts
interface VisitorInfo {
  id: string;
  isReturning: boolean;
  sessionCount: number;
}
```

Returned by `tracker.init()`.

## Read next

- [`AvatarWidget` reference](/docs/develop/npm/react/avatar-widget) — props in context
- [Hooks](/docs/develop/npm/react/hooks) — what each type looks like in use
- [`LiveKitSession`](/docs/develop/npm/sdk/livekit-session) — `SessionCallbacks` in context