@convai/web-widget 0.1.4 → 0.2.0

package/ui/react/components/rtc-widget/styles/theme.d.ts

@@ -0,0 +1,187 @@
+export declare const aeroTheme: {
+    colors: {
+        primary: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+        convai: {
+            light: string;
+            medium: string;
+            dark: string;
+        };
+        neutral: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+        glass: {
+            light: string;
+            medium: string;
+            dark: string;
+            backdrop: string;
+            card: string;
+            backdropLight: string;
+            borderLight: string;
+        };
+        accent: {
+            purple: string;
+            green: string;
+            blue: string;
+            orange: string;
+            red: string;
+        };
+        error: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+        text: {
+            primary: string;
+            secondary: string;
+            tertiary: string;
+            inverse: string;
+        };
+    };
+    typography: {
+        fontFamily: {
+            primary: string;
+            title: string;
+            header: string;
+            body: string;
+            mono: string;
+        };
+        fontSize: {
+            xs: string;
+            sm: string;
+            base: string;
+            lg: string;
+            xl: string;
+            "2xl": string;
+            "3xl": string;
+            "4xl": string;
+        };
+        sizes: {
+            xs: string;
+            sm: string;
+            body: string;
+            lg: string;
+            xl: string;
+            "2xl": string;
+            "3xl": string;
+            "4xl": string;
+            caption: string;
+        };
+        fontWeight: {
+            normal: number;
+            medium: number;
+            semibold: number;
+            bold: number;
+        };
+        lineHeight: {
+            tight: number;
+            normal: number;
+            relaxed: number;
+        };
+    };
+    spacing: {
+        xs: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+        "2xl": string;
+        "3xl": string;
+    };
+    borderRadius: {
+        none: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+        "2xl": string;
+        full: string;
+    };
+    shadows: {
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+        glass: string;
+    };
+    glass: {
+        backdrop: string;
+        backdropLight: string;
+        backdropHeavy: string;
+        border: string;
+        borderLight: string;
+    };
+    transitions: {
+        fast: string;
+        normal: string;
+        slow: string;
+        spring: string;
+        snappy: string;
+    };
+    zIndex: {
+        base: number;
+        dropdown: number;
+        sticky: number;
+        fixed: number;
+        modal: number;
+        popover: number;
+        tooltip: number;
+    };
+};
+export declare const glassStyles: {
+    container: string;
+    overlay: string;
+    card: string;
+    input: string;
+    button: string;
+};
+export declare const iconSizes: {
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    "2xl": string;
+};
+export declare const variants: {
+    button: {
+        primary: string;
+        secondary: string;
+        ghost: string;
+    };
+    input: {
+        default: string;
+        search: string;
+    };
+    card: {
+        default: string;
+        elevated: string;
+        interactive: string;
+    };
+};

package/ui/react/components/rtc-widget/types/index.d.ts

@@ -0,0 +1,59 @@
+export interface RTCChatMessage {
+    id: string;
+    text: string;
+    isUser: boolean;
+    timestamp: string;
+    sender: string;
+    showLogo?: boolean;
+}
+export interface CharacterVerbosityConfig {
+    characterId: string;
+    label?: string;
+}
+export interface ConviUIProps {
+    isOpen: boolean;
+    backgroundOpacity?: number;
+    alwaysExpanded?: boolean;
+    characterName?: string;
+    characterImage?: string;
+    verbosityLevels?: Array<{
+        index: number;
+        characterId: string;
+        label?: string;
+    }>;
+    currentVerbosityIndex?: number;
+    onVerbosityChange?: (index: number, characterId: string) => void;
+    verbosityChanged?: boolean;
+    messages: RTCChatMessage[];
+    isStreaming?: boolean;
+    inputMode?: "conversation" | "speaker" | "voice" | "verbosity";
+    inputValue: string;
+    liveUserText?: string;
+    localIsTyping: boolean;
+    convaiIsTyping: boolean;
+    chatbotMic: boolean;
+    isPressingMic: boolean;
+    isTalking: boolean;
+    isMuted: boolean;
+    isVoiceMode: boolean;
+    isSettingsOpen: boolean;
+    isSpeakerEditMode: boolean;
+    isVerbosityMode: boolean;
+    isCreatingSpeaker?: boolean;
+    onToggle: () => void;
+    onClose: () => void;
+    onInputChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    onKeyPress: (e: React.KeyboardEvent) => void;
+    onSend: () => void;
+    onMicPress: () => void;
+    onMicRelease: () => void;
+    setIsPressingMic: (value: boolean) => void;
+    onToggleMute: () => void;
+    onToggleVoiceMode: () => void;
+    onSettingsToggle: () => void;
+    onReset: () => void;
+    onToggleVerbosityMode: () => void;
+    onContinue?: () => void;
+    settingsButtonRef?: React.RefObject<HTMLButtonElement>;
+    convaiClient?: any;
+}

package/ui/react/hooks/useCharacterInfo.d.ts

@@ -0,0 +1,18 @@
+import { type CharacterInfo } from "@convai/web-sdk/core";
+/**
+ * Fetch a character's display name and avatar for the widget header.
+ *
+ * The request itself lives in `core/characterInfo` so the vanilla widget runs
+ * the same code rather than a hand-synced copy of it.
+ *
+ * @param characterId - Character to look up
+ * @param apiKey - Convai API key, sent as `X-API-Key`
+ * @param authToken - Preferred over `apiKey`, sent as `API-AUTH-TOKEN`
+ * @param baseUrl - Origin to ask; defaults to `https://api.convai.com`. Pass
+ *   `client.characterInfoUrl` so a non-SaaS deployment is not asked to send
+ *   its credential to Convai's public API.
+ */
+export declare const useCharacterInfo: (characterId?: string, apiKey?: string, authToken?: string, baseUrl?: string | null) => CharacterInfo & {
+    isLoading: boolean;
+    error: Error | null;
+};

package/ui/react/hooks/useLocalCameraTrack.d.ts

@@ -0,0 +1,21 @@
+import { TrackReferenceOrPlaceholder } from "@livekit/components-react";
+/**
+ * Hook to get the local camera track reference from LiveKit.
+ *
+ * Returns a track reference that can be used with LiveKit components
+ * to display the local participant's camera feed.
+ *
+ * @returns {TrackReferenceOrPlaceholder} Track reference for the local camera
+ *
+ * @example
+ * ```tsx
+ * function VideoComponent() {
+ *   const cameraTrackRef = useLocalCameraTrack();
+ *
+ *   return (
+ *     <VideoTrack trackRef={cameraTrackRef} />
+ *   );
+ * }
+ * ```
+ */
+export declare const useLocalCameraTrack: () => TrackReferenceOrPlaceholder;

package/ui/react/icons.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The icons the React widget draws, as inline SVG.
+ *
+ * These were the only 15 icons `react-icons` supplied, and that package is an
+ * 84 MB install — every icon set it ships — for 9 KB of bundled output. Each
+ * entry below is the exact element tree react-icons 5.6.0 generates for that
+ * icon, and `IconBase` reproduces its renderer: the same default
+ * `stroke`/`fill`/`strokeWidth`, `size` -> `height`/`width`, `color` both as
+ * an attribute and in `style`, and the `xmlns`. `__tests__/icons.test.tsx`
+ * pins that equivalence against the server-rendered markup of the original
+ * components, so a change here that alters a single attribute fails a test.
+ *
+ * Only the props the widget passes are supported — `size` and `color`, plus
+ * ordinary SVG attributes. react-icons' `IconContext` is not: nothing in this
+ * package ever provided one.
+ */
+import React from "react";
+export interface IconProps extends React.SVGAttributes<SVGElement> {
+    size?: string | number;
+    color?: string;
+    title?: string;
+}
+export declare const FaUser: (props: IconProps) => React.ReactElement;
+export declare const FiMoreVertical: (props: IconProps) => React.ReactElement;
+export declare const FiMic: (props: IconProps) => React.ReactElement;
+export declare const FiSend: (props: IconProps) => React.ReactElement;
+export declare const FiPhoneOff: (props: IconProps) => React.ReactElement;
+export declare const IoClose: (props: IconProps) => React.ReactElement;
+export declare const IoVideocam: (props: IconProps) => React.ReactElement;
+export declare const IoVideocamOff: (props: IconProps) => React.ReactElement;
+export declare const IoVolumeMute: (props: IconProps) => React.ReactElement;
+export declare const IoVolumeHigh: (props: IconProps) => React.ReactElement;
+export declare const LiaRedoAltSolid: (props: IconProps) => React.ReactElement;
+export declare const MdDragIndicator: (props: IconProps) => React.ReactElement;
+export declare const MdScreenShare: (props: IconProps) => React.ReactElement;
+export declare const MdStopScreenShare: (props: IconProps) => React.ReactElement;
+export declare const PiWaveform: (props: IconProps) => React.ReactElement;

package/ui/shared/lightbox.d.ts

@@ -0,0 +1,15 @@
+export interface LightboxOptions {
+    src: string;
+    alt: string;
+    /** Shown under the image; normally `describeUrl(src)`. */
+    caption: string;
+    /** Target of "Open original". */
+    href: string;
+    root: Document | ShadowRoot;
+    /** Where focus goes back to on close. Defaults to whatever was focused on open. */
+    returnFocusTo?: HTMLElement | null;
+}
+export interface LightboxHandle {
+    close(): void;
+}
+export declare function openLightbox(opts: LightboxOptions): LightboxHandle;

package/ui/shared/linkStyles.d.ts

@@ -0,0 +1,64 @@
+/**
+ * How a link in the chat panel LOOKS: glyph SVGs, the style objects both
+ * renderers apply, the cssText serialiser the vanilla widget uses, and the
+ * card budget.
+ *
+ * This is the rendering half of what used to be one module in
+ * @convai/web-sdk. The other half — what a link IS and how it is labelled
+ * (`linkKindForUrl`, `describeUrl`, `fileNameOf`, `hoverTitle`, …) — is pure
+ * functions with no presentation in them, and stays public in the SDK so a
+ * hand-built UI labels links the same way this one does. Import those from
+ * `@convai/web-sdk/core`, not from here.
+ */
+/** How long a card may shimmer before it is treated as failed. */
+export declare const PREVIEW_TIMEOUT_MS = 12000;
+/** Cards beyond this in one message render as plain anchors. */
+export declare const MAX_CARDS_PER_MESSAGE = 6;
+export type GlyphName = "document" | "email" | "phone" | "sms" | "ftp" | "zoom" | "close" | "external";
+/** Inline SVG for a glyph. Strings, not elements, so both renderers can use them. */
+export declare function glyph(name: GlyphName): string;
+export type StyleObject = Record<string, string | number>;
+/** `{ marginTop: 6 }` → `margin-top: 6px;` — the vanilla widget authors cssText. */
+export declare function toCssText(style: StyleObject): string;
+/**
+ * Every visual the link layer draws, as one style object per element. React
+ * spreads these; vanilla serialises them with `toCssText`. Chrome derives from
+ * `currentColor` because the widget sits on a host page whose background it
+ * cannot know.
+ */
+export declare const presentationStyles: {
+    link: StyleObject;
+    /** Applied on focus-visible by the renderer; kept here so both agree. */
+    linkFocus: StyleObject;
+    blocked: StyleObject;
+    card: StyleObject;
+    cardButton: StyleObject;
+    zoom: StyleObject;
+    media: StyleObject;
+    videoMedia: StyleObject;
+    skeleton: StyleObject;
+    caption: StyleObject;
+    unavailable: StyleObject;
+    fileCard: StyleObject;
+    fileIcon: StyleObject;
+    fileBody: StyleObject;
+    fileName: StyleObject;
+    fileMeta: StyleObject;
+    contact: StyleObject;
+    contactGlyph: StyleObject;
+    badge: StyleObject;
+    lightboxBackdrop: StyleObject;
+    lightbox: StyleObject;
+    lightboxImage: StyleObject;
+    lightboxCaption: StyleObject;
+    lightboxControls: StyleObject;
+    lightboxButton: StyleObject;
+    lightboxFallback: StyleObject;
+    siteCard: StyleObject;
+    siteHeader: StyleObject;
+    siteFavicon: StyleObject;
+    siteName: StyleObject;
+    siteTitle: StyleObject;
+    siteDescription: StyleObject;
+    siteImage: StyleObject;
+};

package/ui/shared/logger.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Copied verbatim from @convai/web-sdk rather than imported: it is internal
+ * there, and keeping it identical means the one `window.__CONVAI_DEBUG__` flag
+ * still turns on the SDK's logs and this package's together.
+ *
+ * Logger utility that only logs in development mode (or when debug is enabled at runtime).
+ * Completely silent in production builds unless explicitly enabled.
+ *
+ * To see logs after a production build, enable at runtime in the browser console:
+ *   window.__CONVAI_DEBUG__ = true
+ * Then refresh the page. Logs will appear with the [Convai] prefix.
+ *
+ * To test logger behavior:
+ * - Development: Set NODE_ENV=development or run on localhost
+ * - Production: Set NODE_ENV=production or deploy to production
+ * - Production + debug: Set window.__CONVAI_DEBUG__ = true before/during use
+ */
+export declare const logger: {
+    log: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+    trace: (...args: unknown[]) => void;
+};
+export declare const loggerConfig: {
+    environment: string;
+    isDevelopment: boolean;
+    isProduction: boolean;
+};

package/ui/vanilla/ConvaiWidget.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Vanilla ConvaiWidget - Complete UI widget for Convai conversations
+ * Ports the React ConvaiWidget to vanilla TypeScript with DOM manipulation
+ */
+import type { VanillaWidgetOptions, VanillaWidget } from "./types";
+/**
+ * Create a Convai chat widget in the specified container
+ *
+ * @param container - HTML element to attach the widget to
+ * @param options - Widget configuration options
+ * @returns VanillaWidget instance with destroy method
+ *
+ * @example Simple usage with config
+ * ```typescript
+ * import { createConvaiWidget } from '@convai/web-sdk/vanilla';
+ *
+ * const widget = createConvaiWidget(document.body, {
+ *   apiKey: 'your-api-key',
+ *   characterId: 'your-character-id',
+ *   enableVideo: false
+ * });
+ * ```
+ *
+ * @example Advanced usage with client instance
+ * ```typescript
+ * import { ConvaiClient, createConvaiWidget } from '@convai/web-sdk/vanilla';
+ *
+ * const client = new ConvaiClient({
+ *   apiKey: 'your-api-key',
+ *   characterId: 'your-character-id'
+ * });
+ *
+ * const widget = createConvaiWidget(document.body, {
+ *   convaiClient: client,
+ *   showVideo: true,
+ *   showScreenShare: true,
+ *   defaultVoiceMode: true
+ * });
+ * ```
+ */
+export declare function createConvaiWidget(container: HTMLElement, options: VanillaWidgetOptions): VanillaWidget;
+/**
+ * Destroy a Convai widget instance
+ * @param widget - Widget instance to destroy
+ */
+export declare function destroyConvaiWidget(widget: VanillaWidget): void;

package/ui/vanilla/WidgetEventSubscriptions.d.ts

@@ -0,0 +1,14 @@
+type WidgetEventListener = (...args: unknown[]) => void;
+type SubscribeToWidgetEvent = (listener: WidgetEventListener) => (() => void) | void;
+/**
+ * Owns widget event listeners so a destroyed widget cannot mutate detached DOM
+ * or notify its host when a client event arrives late.
+ */
+export declare class WidgetEventSubscriptions {
+    private readonly isDestroyed;
+    private readonly unsubscribes;
+    constructor(isDestroyed: () => boolean);
+    register(subscribe: SubscribeToWidgetEvent, listener: WidgetEventListener): void;
+    unsubscribeAll(): void;
+}
+export {};

package/ui/vanilla/icons.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Vanilla JS Icons
+ * Reuses the same icons from the React example
+ * Uses inline SVG for consistency and no external dependencies
+ */
+export type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+export type LogoState = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'typing' | 'listening' | 'processing';
+/**
+ * Icons object with all icon creation functions
+ * Matches the icons from react-icons used in the React example
+ */
+export declare const Icons: {
+    ConvaiLogo: (size?: IconSize, state?: LogoState, className?: string) => SVGSVGElement;
+    ChevronDown: (size?: IconSize, className?: string) => SVGSVGElement;
+    Close: (size?: IconSize, className?: string) => SVGSVGElement;
+    Send: (size?: IconSize, className?: string) => SVGSVGElement;
+    Mic: (size?: IconSize, className?: string) => SVGSVGElement;
+    Waveform: (size?: IconSize, className?: string) => SVGSVGElement;
+    PhoneOff: (size?: IconSize, className?: string) => SVGSVGElement;
+    Video: (size?: IconSize, className?: string) => SVGSVGElement;
+    VideoOff: (size?: IconSize, className?: string) => SVGSVGElement;
+    VolumeMute: (size?: IconSize, className?: string) => SVGSVGElement;
+    VolumeHigh: (size?: IconSize, className?: string) => SVGSVGElement;
+    MoreVertical: (size?: IconSize, className?: string) => SVGSVGElement;
+    ScreenShare: (size?: IconSize, className?: string) => SVGSVGElement;
+    StopScreenShare: (size?: IconSize, className?: string) => SVGSVGElement;
+    Redo: (size?: IconSize, className?: string) => SVGSVGElement;
+    DragIndicator: (size?: IconSize, className?: string) => SVGSVGElement;
+    User: (size?: IconSize, className?: string) => SVGSVGElement;
+};
+/**
+ * Helper to create icon wrapper div
+ */
+export declare function createIconWrapper(icon: SVGSVGElement, size?: IconSize, color?: string, className?: string): HTMLDivElement;