@ringg/react-native 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -81,6 +81,28 @@ interface SlashCommand {
     description: string;
 }
 
+/**
+ * GENERATED FILE — DO NOT EDIT.
+ * Source: tokens/tokens.json + tokens/defaults.json
+ * Regenerate: node scripts/generate-tokens.mjs
+ */
+
+declare const DEFAULT_WIDGET_THEME: ResolvedWidgetTheme;
+declare const WIDGET_PRESET_THEMES: Record<string, WidgetTheme>;
+declare const WIDGET_DEFAULTS: {
+    readonly mode: "prod";
+    readonly title: "Ringg AI Support";
+    readonly description: "Ringg AI offers 24/7 voice support to handle your business calls efficiently and professionally";
+    readonly defaultTab: "audio";
+    readonly hideTabSelector: false;
+    readonly defaultExpanded: false;
+    readonly bypassStartScreen: false;
+    readonly bypassFeedbackScreen: false;
+    readonly voiceCallShowAnimation: false;
+    readonly voiceCallShowTranscript: true;
+    readonly notificationTuneUrl: "https://assets.ringg.ai/audios/misc/widget_notification.mp3";
+};
+
 /**
  * Widget configuration types.
  * These define the public API surface for consumers initializing the widget.
@@ -263,6 +285,11 @@ interface CalendarBookingPayload extends BaseComponent {
     component_type: "calendar_booking";
     data: CalendarBookingData;
 }
+interface GroupedSlots {
+    date: string;
+    dateLabel: string;
+    slots: CalendarSlot[];
+}
 type FormFieldType = "text" | "email" | "tel" | "number" | "select" | "multiselect" | "textarea" | "date" | "boolean";
 interface FormFieldOption {
     value: string;
@@ -561,6 +588,8 @@ interface EventBus {
     /** Remove all listeners for one event, or all events if omitted. */
     off(event?: WidgetEventName): void;
 }
+/** Web implementation — dispatches/listens via DOM CustomEvents on `window`. */
+declare function createDomEventBus(): EventBus;
 /** In-memory event bus — for React Native or testing. */
 declare function createCallbackEventBus(): EventBus;
 
@@ -578,6 +607,7 @@ interface Clock {
     setTimeout(fn: () => void, ms: number): TimerHandle;
     clearTimeout(handle: TimerHandle): void;
 }
+declare function createSystemClock(): Clock;
 
 /**
  * Small platform ports — capabilities core needs but cannot implement
@@ -594,6 +624,9 @@ interface NotificationPlayer {
     /** Best-effort playback; must never throw (autoplay policies etc.) */
     play(): void;
 }
+/** No-op defaults for platforms/tests that don't wire these up */
+declare const grantedMicPermission: MicPermissionPort;
+declare const silentNotificationPlayer: NotificationPlayer;
 
 /**
  * API client for the Ringg backend.
@@ -609,6 +642,101 @@ interface EnvironmentUrls {
 interface UrlResolver {
     resolve(mode: EnvironmentMode): EnvironmentUrls;
 }
+declare function createStaticUrlResolver(urls: Record<EnvironmentMode, EnvironmentUrls>): UrlResolver;
+interface WebcallResponse {
+    call_id: string;
+    user_token: string;
+    enabled_slash_commands?: SlashCommand[];
+}
+interface FeedbackPayload {
+    rating: number;
+    comment: string;
+}
+interface ApiClientConfig {
+    urlResolver: UrlResolver;
+    mode: EnvironmentMode;
+    /** Sent as X-API-KEY */
+    xApiKey?: string;
+    /** Sent as Authorization; wins over xApiKey when both are set */
+    authorization?: string;
+    /** Sent as `Origin`. Omitted entirely when unset — see RinggWidgetConfig. */
+    clientOrigin?: string;
+}
+interface RinggApiClient {
+    readonly backendUrl: string;
+    readonly livekitUrl: string;
+    /** Initiate a webcall — returns the LiveKit token and call ID. */
+    startWebcall(params: {
+        agentId: string;
+        variables: WidgetVariables;
+        mediaType: "audio" | "text";
+    }): Promise<WebcallResponse>;
+    /** Submit post-call feedback. Best-effort — callers decide error handling. */
+    submitFeedback(callId: string, feedback: FeedbackPayload): Promise<void>;
+    /** Call a component API endpoint (for interactive flow on_complete actions). */
+    callComponentApi(method: "POST" | "GET", endpoint: string, payload: Record<string, string>): Promise<ComponentActionResponse>;
+}
+declare function createRinggApiClient(config: ApiClientConfig): RinggApiClient;
+
+/**
+ * Theme engine — resolves, merges, and provides theme values.
+ * Pure functions with no framework dependency.
+ *
+ * Default and preset theme VALUES live in tokens/tokens.json (shared across
+ * all implementations via codegen) — only merging/contrast LOGIC lives here.
+ */
+
+/** Merge a partial user theme with the defaults. Returns a fully resolved theme. */
+declare function mergeWidgetTheme(theme?: WidgetTheme): ResolvedWidgetTheme;
+/** Merge a component-level theme with the widget theme as fallback. */
+declare function mergeComponentTheme(componentTheme?: ComponentTheme, widgetTheme?: ResolvedWidgetTheme): ComponentTheme;
+/** Get button border radius based on style */
+declare function getButtonRadius(style?: ButtonStyle): string;
+/** Check if a color is considered "light" (for auto-contrast) */
+declare function isLightColor(hexColor: string): boolean;
+/** Get a contrasting text color (black or white) for a given background */
+declare function getContrastingTextColor(bgColor: string): string;
+
+/**
+ * Gradient-aware style utilities for the widget theme system.
+ *
+ * CSS `backgroundColor` does not support gradient values — only the
+ * `background` shorthand does. These helpers detect whether a color value is
+ * a solid hex/rgb or a CSS gradient string, and extract a solid fallback
+ * color for surfaces that can't render gradients (borders, React Native).
+ *
+ * Parsing is deliberately explicit — small named steps instead of regexes —
+ * so a bad input can be walked through in a debugger function by function.
+ */
+/** Detect whether a CSS color value is a gradient string. */
+declare function isGradient(color: string): boolean;
+/** Extract all color stops from a gradient string, in order. */
+declare function extractColorsFromGradient(gradient: string): string[];
+/**
+ * Return the dominant (first) color from a gradient, or the color as-is for
+ * solid values. Falls back to the original string if no colors can be extracted.
+ */
+declare function getDominantColor(color: string): string;
+/**
+ * Determine the correct CSS properties for a background color.
+ * Returns `{ backgroundColor }` for solid colors, `{ background }` for gradients.
+ * On React Native, gradients aren't natively supported — use `getDominantColor()`
+ * to fall back to a solid color.
+ */
+declare function colorToBackground(color: string): {
+    backgroundColor?: string;
+    background?: string;
+};
+/**
+ * Always return a solid hex/rgb color string. Use for properties that don't
+ * support gradients: border, box-shadow, accent-color.
+ */
+declare function colorToSolid(color: string): string;
+/**
+ * Return the correct CSS properties for a border color.
+ * Solid colors -> `{ borderColor }`, gradients -> `{ borderImage, borderStyle }`.
+ */
+declare function colorToBorder(color: string): Record<string, string>;
 
 /**
  * RPC message formatting — transforms between backend RPC format and internal
@@ -622,12 +750,61 @@ interface UrlResolver {
  * This module handles both directions.
  */
 
+/**
+ * Transform a backend RPC payload into the internal component format.
+ * Returns null if the component type is unknown.
+ */
+declare function transformRpcToComponent(componentName: string, rpcPayload: Record<string, unknown>): SimpleComponentPayload | InteractiveFlowPayload | null;
+interface RpcMessage {
+    method: string;
+    payload: string;
+}
+/**
+ * Format a component response payload for sending back to the backend via RPC.
+ * Used when the user interacts with a component (selects a slot, submits a
+ * form, taps a button).
+ */
+declare function formatComponentResponse(componentName: string, componentId: string, responseData: Record<string, unknown>, originalConfig: unknown): RpcMessage;
+/** Format a slash command for sending via RPC. */
+declare function formatSlashCommand(command: string): RpcMessage;
 /** A Block Kit action as it goes on the wire (the UI-only `label` never does). */
 interface BlocksActionWire {
     action_id: string;
     value?: unknown;
     values: Record<string, unknown>;
 }
+/**
+ * Format a Block Kit interaction for the agent. Envelope mirrors the dashboard
+ * test widget the bot bridge was tested against: `component_id` and `values`
+ * are always present; `tool_id` is omitted when falsy and `value` when
+ * undefined (never sent as null/empty keys).
+ */
+declare function formatBlocksAction(toolId: string | undefined, componentId: string, action: BlocksActionWire): RpcMessage;
+/**
+ * Format a raw dynamic-data payload (client packs: disease search/submit).
+ * The payload already carries its own `component_type` envelope.
+ */
+declare function formatDynamicData(payload: Record<string, unknown>): RpcMessage;
+
+/**
+ * Component data helpers — pure functions for working with interactive
+ * component data. Shared across web and React Native renderers.
+ */
+
+/** Group calendar slots by date for display */
+declare function groupSlotsByDate(slots: CalendarSlot[]): GroupedSlots[];
+/** Format a slot time for display */
+declare function formatSlotTime(datetime: string, timezone?: string): string;
+/** Format a slot date for display */
+declare function formatSlotDate(datetime: string, timezone?: string): string;
+/** Interpolate a payload template with collected values */
+declare function buildPayload(template: Record<string, string>, values: Record<string, string>): Record<string, string>;
+declare function isCalendarBooking(payload: ComponentPayload): payload is CalendarBookingPayload;
+declare function isForm(payload: ComponentPayload): payload is FormPayload;
+declare function isButtons(payload: ComponentPayload): payload is ButtonsPayload;
+declare function isConfirmation(payload: ComponentPayload): payload is ConfirmationPayload;
+declare function isInteractiveFlow(payload: ComponentPayload): payload is InteractiveFlowPayload;
+declare function isBlocks(payload: ComponentPayload): payload is BlocksPayload;
 
 /**
  * Base store — the one state-sharing primitive in core.
@@ -645,6 +822,14 @@ interface Store<T> {
     getSnapshot(): T;
     subscribe(listener: (snapshot: T) => void): () => void;
 }
+/** Internal store handle: the public read API plus commit/dispose. */
+interface StoreHandle<T> extends Store<T> {
+    /** Rebuild the immutable snapshot from current state and notify subscribers. */
+    commit(): void;
+    /** Drop all subscribers. */
+    dispose(): void;
+}
+declare function createStore<T>(build: () => T): StoreHandle<T>;
 
 /**
  * Shell store — widget open/close/feedback lifecycle and the active call id.
@@ -677,6 +862,7 @@ interface ShellStore extends Store<ShellSnapshot> {
     setCurrentCallId(callId: string | null): void;
     dispose(): void;
 }
+declare function createShellStore(eventBus: EventBus, initialCallMode?: MediaType, defaultExpanded?: boolean): ShellStore;
 
 /**
  * Session store — the call lifecycle state machine.
@@ -724,6 +910,7 @@ interface SessionStore extends Store<SessionSnapshot> {
     clearError(): void;
     dispose(): void;
 }
+declare function createSessionStore(api: RinggApiClient, transport: TransportAdapter, mic: MicPermissionPort): SessionStore;
 
 /**
  * Message store — the single ordered conversation timeline.
@@ -782,6 +969,7 @@ interface MessageStore extends Store<MessageSnapshot> {
     reset(): void;
     dispose(): void;
 }
+declare function createMessageStore(clock: Clock): MessageStore;
 
 /**
  * Typing store — drives the "agent is typing" indicator (text mode).
@@ -812,6 +1000,7 @@ interface TypingStore extends Store<TypingSnapshot> {
     waitMinDuration(): Promise<void>;
     dispose(): void;
 }
+declare function createTypingStore(clock: Clock): TypingStore;
 
 /**
  * Component store — interactive components pushed by the backend mid-call.
@@ -859,6 +1048,9 @@ interface ComponentStore extends Store<ComponentSnapshot> {
     reset(): void;
     dispose(): void;
 }
+declare function createComponentStore(clock: Clock, 
+/** Commits a component to the timeline — wired to MessageStore + host events by the controller */
+commitComponent: (component: ComponentPayload) => void): ComponentStore;
 
 /**
  * Slash command store — merges commands declared in config with commands the
@@ -874,6 +1066,22 @@ interface SlashCommandStore extends Store<SlashCommandSnapshot> {
     reset(): void;
     dispose(): void;
 }
+declare function createSlashCommandStore(configCommands?: SlashCommand[]): SlashCommandStore;
+
+/**
+ * Timing constants — every value encodes a UX bug that was found and fixed in
+ * the production widget. Values live in tokens/defaults.json (shared across
+ * all implementations via codegen); change them there, never here.
+ */
+/** Chat-widget RPCs land before the agent's text streams in; buffer them this
+ * long waiting for the text so the widget sorts below it. */
+declare const CHAT_WIDGET_GRACE_MS: number;
+/** Once the agent text lands, release buffered widgets after this beat so the
+ * message paints first. */
+declare const CHAT_WIDGET_AFTER_TEXT_MS: number;
+/** Keep the typing dots visible at least this long — instant replies
+ * otherwise make the indicator flash. */
+declare const MIN_TYPING_INDICATOR_MS: number;
 
 /**
  * RinggWidgetController — the composition root of the widget brain.
@@ -999,7 +1207,39 @@ declare const useRinggSlashCommands: (controller: RinggWidgetController) => Slas
  *     reply arriving does not yank the view while the user is reading.
  */
 
-interface RinggWidgetProps {
+/**
+ * The managed form: hand it a config and it owns everything underneath.
+ *
+ * This is the RN counterpart of web's `loadAgent({ agentId, authorization })`.
+ * The transport, the endpoint table and the microphone port are ours, not the
+ * integrator's, so the app does not carry our infrastructure in its source.
+ */
+interface ManagedRinggWidgetProps {
+    config: RinggWidgetConfig;
+    /**
+     * Overrides for the ports the widget wires by default. Supply `transport` to
+     * bring your own (a mock in tests, a shared room), `urlResolver` to point at
+     * something other than the Ringg endpoints, `notification` to give the widget
+     * a sound, or `onDomAction` to handle agent-triggered app actions.
+     */
+    ports?: Partial<ControllerPorts>;
+    /**
+     * Called once with the controller the widget built, for hosts that want to
+     * listen for events or drive the panel imperatively without owning its
+     * lifecycle. The controller is destroyed on unmount — do not keep using it.
+     */
+    onReady?: (controller: RinggWidgetController) => void;
+    controller?: never;
+    room?: never;
+}
+/**
+ * The controlled form: you built the controller, you own its lifecycle.
+ *
+ * Reach for it when the widget cannot own the transport — a custom adapter, a
+ * room shared with the rest of the app, or a headless setup where the widget is
+ * one of several views on one controller.
+ */
+interface ControlledRinggWidgetProps {
     controller: RinggWidgetController;
     /**
      * The LiveKit room from `createLiveKitTransport()`. Optional: it only powers
@@ -1007,7 +1247,15 @@ interface RinggWidgetProps {
      * fully functional and the visualizer shows its ambient idle animation.
      */
     room?: Room;
+    config?: never;
+    ports?: never;
+    onReady?: never;
 }
+type RinggWidgetProps = ManagedRinggWidgetProps | ControlledRinggWidgetProps;
+/**
+ * The widget. Pass `config` and it owns the transport, endpoints and
+ * microphone; pass `controller` when you built those yourself.
+ */
 declare const RinggWidget: FC<RinggWidgetProps>;
 
 /**
@@ -1064,6 +1312,23 @@ interface LiveKitTransport {
 }
 declare const createLiveKitTransport: (options?: LiveKitTransportOptions) => LiveKitTransport;
 
+/**
+ * The Ringg-hosted endpoints, baked into the platform entry point.
+ *
+ * Core deliberately embeds no URLs — they arrive through a `UrlResolver` the
+ * entry point supplies. Every other entry point already carries this table:
+ * web bundles it in `cdn.tsx` so `loadAgent({ agentId, authorization })` needs
+ * nothing else, and Flutter exposes it as `defaultUrlResolver`. React Native
+ * was the only one asking integrators to type endpoints into their own app,
+ * which leaked our infrastructure into their source for no benefit.
+ *
+ * `mode` selects the row; it defaults to `prod`.
+ */
+
+declare const DEFAULT_ENVIRONMENT_URLS: Record<EnvironmentMode, EnvironmentUrls>;
+/** `ControllerPorts.urlResolver` default for the managed `<RinggWidget config />`. */
+declare const defaultUrlResolver: UrlResolver;
+
 /**
  * Native audio session — React Native's replacement for the web adapter's
  * hidden `<audio>` elements.
@@ -1352,4 +1617,4 @@ declare const Markdown: FC<MarkdownProps>;
 /** `"header-title"` → `"ringg-header-title"`. */
 declare const ringgId: (name: string) => string;
 
-export { type AudioSessionPort, type ControllerPorts, GradientFill, type HostAction, type HostActionHandler, type LiveKitTransport, type LiveKitTransportOptions, Markdown, type PlayTune, RinggWidget, type RinggWidgetConfig, type RinggWidgetController, type RinggWidgetProps, type TransportAdapter, WidgetThemeProvider, appOrigin, createAudioSession, createCallbackEventBus, createHostActionDispatcher, createLiveKitTransport, createNativeMicPermission, createNotificationPlayer, createRinggWidgetController, createSilentNotificationPlayer, resolveButtonRadius, resolveFontFamily, resolveRadius, ringgId, solidColor, toSize, toViewStyle, useRinggComponents, useRinggMessages, useRinggSession, useRinggShell, useRinggSlashCommands, useRinggTyping, useStoreSnapshot, useWidgetTheme };
+export { type ApiClientConfig, type AudioSessionPort, type BaseComponent, type BlocksActionWire, type BlocksData, type BlocksPayload, type ButtonAction, type ButtonIconConfig, type ButtonItem, type ButtonSize, type ButtonStyle, type ButtonsConfig, type ButtonsData, type ButtonsPayload, CHAT_WIDGET_AFTER_TEXT_MS, CHAT_WIDGET_GRACE_MS, type CalendarBookingData, type CalendarBookingEventPayload, type CalendarBookingPayload, type CalendarSlot, type ChatMessage, type Clock, type ComponentAcknowledgementPayload, type ComponentActionResponse, type ComponentPayload, type ComponentSnapshot, type ComponentStore, type ComponentTheme, type ConfirmationData, type ConfirmationPayload, type ConnectionState, type ControlledRinggWidgetProps, type ControllerPorts, type ConversationStatusPayload, type CustomComponentPayload, WIDGET_DEFAULTS as DEFAULT_CONFIG, DEFAULT_ENVIRONMENT_URLS, DEFAULT_WIDGET_THEME, type DomAction, type DomActionKind, type DomActionLogEntry, type DomActionLogger, type DynamicDataExtension, type EnvironmentMode, type EnvironmentUrls, type ErrorState, type EventBus, type EventLogsConfig, type FeedbackPayload, type FeedbackScreenConfig, type FeedbackStatusPayload, type FlowStep, type FormData, type FormField, type FormFieldOption, type FormFieldType, type FormPayload, GradientFill, type GroupedSlots, type HostAction, type HostActionHandler, type IncomingChatMessage, type IncomingTextStream, type InnerWindowConfig, type InteractiveFlowData, type InteractiveFlowPayload, type LegalDisclaimerConfig, type LiveKitTransport, type LiveKitTransportOptions, MIN_TYPING_INDICATOR_MS, type ManagedRinggWidgetProps, Markdown, type MediaType, type MessageSnapshot, type MessageStore, type MicPermissionPort, type NotificationPlayer, type PendingResponse, type PlayTune, type PortableStyles, type ResolvedWidgetTheme, type RinggApiClient, RinggWidget, type RinggWidgetConfig, type RinggWidgetController, type RinggWidgetProps, type RpcInvocation, type RpcMessage, type SessionPhase, type SessionSnapshot, type SessionStartResult, type SessionStore, type ShellSnapshot, type ShellStore, type SimpleComponentPayload, type SlashCommand, type SlashCommandSnapshot, type SlashCommandStore, type SlashCommandToolType, type Store, type StoreHandle, type TimerHandle, type TranscriptionSegment, type TransportAdapter, type TriggerAlignment, type TriggerPlacement, type TypingSnapshot, type TypingStore, type UrlResolver, type VoiceCallConfig, WIDGET_PRESET_THEMES, type WebcallResponse, type WidgetAlignment, type WidgetEventMap, type WidgetEventName, type WidgetPositionConfig, type WidgetStatusPayload, type WidgetTheme, WidgetThemeProvider, type WidgetVariables, type WidgetViewState, appOrigin, buildPayload, colorToBackground, colorToBorder, colorToSolid, createAudioSession, createCallbackEventBus, createComponentStore, createDomEventBus, createHostActionDispatcher, createLiveKitTransport, createMessageStore, createNativeMicPermission, createNotificationPlayer, createRinggApiClient, createRinggWidgetController, createSessionStore, createShellStore, createSilentNotificationPlayer, createSlashCommandStore, createStaticUrlResolver, createStore, createSystemClock, createTypingStore, defaultUrlResolver, extractColorsFromGradient, formatBlocksAction, formatComponentResponse, formatDynamicData, formatSlashCommand, formatSlotDate, formatSlotTime, getButtonRadius, getContrastingTextColor, getDominantColor, grantedMicPermission, groupSlotsByDate, isBlocks, isButtons, isCalendarBooking, isConfirmation, isForm, isGradient, isInteractiveFlow, isLightColor, mergeComponentTheme, mergeWidgetTheme, resolveButtonRadius, resolveFontFamily, resolveRadius, ringgId, silentNotificationPlayer, solidColor, toSize, toViewStyle, transformRpcToComponent, useRinggComponents, useRinggMessages, useRinggSession, useRinggShell, useRinggSlashCommands, useRinggTyping, useStoreSnapshot, useWidgetTheme };