Types
The Widget SDK exports TypeScript interfaces and enums for configuration, theming, and branding. These types are used when calling initWidget() and customizing the widget appearance.
Core Types
WidgetInitOptions
Main configuration object passed to initWidget().
export type WidgetInitOptions = {
/**
* HTMLElement or selector that will host the widget UI.
* Defaults to the first element with `[data-orga-widget]`.
*/
target?: HTMLElement | string;
/**
* Function that returns the session configuration (ephemeral token + ICE servers).
* Mirrors the existing React SDK requirement so we can reuse backends.
*/
fetchSessionConfig: () => Promise<SessionConfigResponse>;
/**
* Optional session configuration endpoint to seed OrgaAI.init.
* Used only for logging / diagnostics.
*/
sessionConfigEndpoint?: string;
/**
* Optional voice/model configuration to seed OrgaAI.init.
*/
voice?: OrgaAIVoice;
/**
* Logging verbosity override.
*/
logLevel?: 'disabled' | 'error' | 'warn' | 'info' | 'debug';
/**
* Theme/layout preset for the widget shell.
*/
theme?: WidgetThemeName;
/**
* Controls whether the transcript panel is visible.
*/
transcript?: TranscriptMode;
/**
* Controls camera preview behavior.
*/
videoPreview?: VideoPreviewMode;
/**
* UI branding: name, tagline, and color palette.
*/
branding?: Partial<WidgetBranding>;
};| Field | Type | Required | Description |
|---|---|---|---|
target | HTMLElement | string | No | DOM element or CSS selector where the widget mounts. |
fetchSessionConfig | () => Promise<SessionConfigResponse> | Yes | Async function that returns session credentials from your backend. |
sessionConfigEndpoint | string | No | Human-readable endpoint label for logging. |
voice | OrgaAIVoice | No | Default voice/model for the session. |
logLevel | "disabled" | "error" | "warn" | "info" | "debug" | No | Controls internal logging verbosity. |
theme | WidgetThemeName | No | Layout preset for the widget shell. |
transcript | TranscriptMode | No | Whether to show the transcript panel. |
videoPreview | VideoPreviewMode | No | Controls camera preview behavior. |
branding | Partial<WidgetBranding> | No | Branding configuration (merged with defaults). |
SessionConfigResponse
Response shape expected from your backend’s fetchSessionConfig function.
export type SessionConfigResponse = {
ephemeralToken: string;
iceServers: Array<{
urls: string | string[];
username?: string;
credential?: string;
}>;
};| Field | Type | Required | Description |
|---|---|---|---|
ephemeralToken | string | Yes | Short-lived JWT token for authenticating the WebRTC session. |
iceServers | Array<{ urls, username?, credential? }> | Yes | Array of STUN/TURN server configurations for WebRTC. |
Theme & Layout Types
WidgetThemeName
Layout preset for the widget shell.
export type WidgetThemeName = 'floating-badge' | 'panel' | 'full';| Value | Description |
|---|---|
"floating-badge" | Widget appears as a docked badge in the corner that expands into a panel (default). |
"panel" | Widget renders as a panel at the point where you place the host element. |
"full" | Large, full-panel experience intended for dedicated assistant pages. |
TranscriptMode
Controls whether the transcript panel is visible.
export type TranscriptMode = 'hidden' | 'panel';| Value | Description |
|---|---|
"hidden" | Hide the transcript panel entirely. |
"panel" | Show a live transcript panel alongside the widget (default). |
VideoPreviewMode
Controls camera preview and toggle behavior.
export type VideoPreviewMode = 'hidden' | 'optional' | 'always';| Value | Description |
|---|---|
"hidden" | Camera preview is completely hidden. |
"optional" | Camera preview is available but can be toggled on/off (default). |
"always" | Camera preview is always visible when the camera is enabled. |
Branding Types
WidgetBranding
Complete branding configuration for the widget UI.
export type WidgetBranding = {
brandName: string;
tagline?: string;
accentColor: string;
backgroundColor: string;
borderColor: string;
textColor: string;
secondaryTextColor: string;
badgeIconUrl?: string;
logoUrl?: string;
logoAlt?: string;
};| Field | Type | Required | Default | Description |
|---|---|---|---|---|
brandName | string | Yes | "Orga Assistant" | Product or company name shown in the header. |
tagline | string | No | "Your realtime copilot" | Short subtitle beneath the brand name. |
accentColor | string | Yes | "#2D9FBC" | Main accent color used for buttons and badge. |
backgroundColor | string | Yes | "#ffffff" | Widget body background. |
borderColor | string | Yes | "#e2e8f0" | Border color for panels and transcript boxes. |
textColor | string | Yes | "#0f172a" | Primary text color. |
secondaryTextColor | string | Yes | "#475569" | Secondary / muted text. |
badgeIconUrl | string | No | Orga logo data URI | URL or data:image/* URI for the floating badge icon. Non-HTTPS URLs are ignored. |
logoUrl | string | No | undefined | Optional logo shown in the header. Non-HTTPS URLs are ignored. |
logoAlt | string | No | brandName | Alt text for the header logo. |
WidgetFeatureConfig
Feature configuration for transcript and video preview.
export type WidgetFeatureConfig = {
transcript: TranscriptMode;
videoPreview: VideoPreviewMode;
};| Field | Type | Description |
|---|---|---|
transcript | TranscriptMode | Whether to show the transcript panel. |
videoPreview | VideoPreviewMode | Controls camera preview behavior. |
Re-exported Core Types
For convenience, the Widget SDK re-exports types from @orga-ai/core so you don’t need a second import.
| Type | Description |
|---|---|
OrgaAIVoice | Supported voice presets (e.g., "fable", "alloy"). |
ConnectionState | Connection lifecycle states: "disconnected", "connecting", "connected". |
OrgaAIModel | Supported model names (e.g., "orga-1-beta"). |
Foundational types originate in
@orga-ai/core; they are re-exported here so a second import is rarely necessary.
Example Usage
import type {
WidgetInitOptions,
WidgetThemeName,
WidgetBranding,
} from '@orga-ai/widget';
import { initWidget } from '@orga-ai/widget';
const options: WidgetInitOptions = {
fetchSessionConfig: () =>
fetch('/api/orga-session').then((res) => res.json()),
theme: 'floating-badge' as WidgetThemeName,
branding: {
brandName: 'My App',
tagline: "Your app's assistant",
accentColor: '#2D9FBC',
backgroundColor: '#ffffff',
borderColor: '#e2e8f0',
textColor: '#0f172a',
secondaryTextColor: '#475569',
} as Partial<WidgetBranding>,
};
initWidget(options);This example shows how to use the provided types to safely configure the widget in a TypeScript app.
Default Values
When you don’t provide certain options, the widget uses these defaults:
const DEFAULT_BRANDING: WidgetBranding = {
brandName: 'Orga Assistant',
tagline: 'Your realtime copilot',
accentColor: '#2D9FBC',
backgroundColor: '#ffffff',
borderColor: '#e2e8f0',
textColor: '#0f172a',
secondaryTextColor: '#475569',
};
const DEFAULT_FEATURES: WidgetFeatureConfig = {
transcript: 'panel',
videoPreview: 'optional',
};
const defaultTheme: WidgetThemeName = 'floating-badge';
const defaultVoice: OrgaAIVoice = 'fable';
const defaultLogLevel = 'info';All branding fields are optional when passed via branding; they are merged with DEFAULT_BRANDING and sanitized.