@vanira/sdk-react-native 0.0.2

package/src/runtime/platform.ts

@@ -0,0 +1,17 @@
+/**
+ * Platform detection helpers for the Vanira SDK runtime layer.
+ * Used by resolveRuntimeConfig and (in Task 0.4+) preset DOM dispatch.
+ */
+
+/**
+ * Whether CustomEvent and globalThis.dispatchEvent are available.
+ * Used to gate browser-only `vanira:preset` window events without relying on
+ * runtime.capabilities.supportsDom alone.
+ */
+export function canDispatchBrowserEvent(): boolean {
+    return (
+        typeof CustomEvent !== 'undefined' &&
+        typeof globalThis !== 'undefined' &&
+        typeof globalThis.dispatchEvent === 'function'
+    );
+}

package/src/runtime/reactNativeRuntime.ts

@@ -0,0 +1,68 @@
+/**
+ * React Native Runtime
+ *
+ * Pre-wires all React Native adapters into a VaniraRuntime.
+ * Import this module only in React Native environments.
+ *
+ * Prerequisites:
+ *   1. Install react-native-webrtc and call registerGlobals() at app entry.
+ *   2. Link native modules per the react-native-webrtc installation guide.
+ *   3. Add microphone permissions to AndroidManifest.xml and Info.plist.
+ *
+ * Usage:
+ *   import { createReactNativeClient } from 'vanira-sdk/runtime/react-native';
+ *   const client = createReactNativeClient({ agentId: '...', apiKey: '...' });
+ *
+ * Platform differences versus browser:
+ *   - supportsAudioEndedEvent: false — audio routes via native stack, no onended
+ *   - supportsDom: false — no document/window
+ *   - supportsHtmlAudio: false — no Audio element
+ *   - supportsCustomElements: false — no customElements API
+ *   - supportsLocalStorage: false — use AsyncStorage instead
+ *   - supportsBroadcastChannel: false — no cross-tab (no tabs on mobile)
+ *   - callType: 'web' — API only accepts web | sip; mobile is indicated via runtimeName
+ *   - runtimeName: 'react-native' — explicit backend runtime identification
+ */
+
+import type { WebRTCClientConfig } from '../types';
+
+import { WebRTCClient } from '../core/WebRTCClient';
+import { VaniraAI } from '../core/VaniraAI';
+
+import {
+    reactNativeDefaultBundle,
+    reactNativeCapabilities,
+} from './runtimeBundles';
+
+// Re-export bundle + capabilities (single source of truth in runtimeBundles.ts)
+export { reactNativeCapabilities };
+export const reactNativeRuntime = reactNativeDefaultBundle;
+
+// ─── Factory functions ────────────────────────────────────────────────────────
+
+/**
+ * Create a WebRTCClient pre-wired for React Native.
+ *
+ * The callId is auto-generated with an 'rn_' prefix for tracing.
+ * The /calls/create request body will include `{ type: 'web', runtime: 'react-native' }`.
+ */
+export function createReactNativeClient(
+    config: Omit<WebRTCClientConfig, 'audioAdapter' | 'mediaAdapter' | 'peerAdapter' | 'dataChannelAdapter'>
+): WebRTCClient {
+    return new WebRTCClient({
+        ...config,
+        runtime: reactNativeRuntime,
+    });
+}
+
+/**
+ * Create a VaniraAI instance pre-wired for React Native.
+ */
+export function createReactNativeAI(
+    config: Omit<WebRTCClientConfig, 'audioAdapter' | 'mediaAdapter' | 'peerAdapter' | 'dataChannelAdapter'>
+): VaniraAI {
+    return new VaniraAI({
+        ...config,
+        runtime: reactNativeRuntime,
+    });
+}

package/src/runtime/resolveRuntimeConfig.ts

@@ -0,0 +1,75 @@
+/**
+ * Runtime resolution for WebRTCClient (wired in Task 0.2).
+ *
+ * Layered resolution:
+ *   1. config.runtime provided → use it (factories inject browser/RN bundle)
+ *   2. isReactNative() → throw (RN must use @vanira/sdk-react-native factories)
+ *   3. else → browserDefaultBundle (bare new WebRTCClient() on web)
+ */
+
+import type { WebRTCClientConfig } from '../types';
+import type { VaniraRuntime, RuntimeCapabilities } from './types';
+import type { AudioAdapter, MediaAdapter } from '../adapters/interfaces';
+import type { PeerConnectionAdapter, DataChannelAdapter } from '../adapters/PeerConnectionAdapter';
+import type { StorageAdapter } from '../adapters/storage/StorageAdapter';
+
+import { browserDefaultBundle } from './runtimeBundles';
+
+/** Resolved adapters + metadata after config override merge. */
+export interface ResolvedRuntimeConfig {
+    readonly name: VaniraRuntime['name'];
+    readonly runtimeName: string;
+    readonly callType: 'web';
+    readonly callIdPrefix: string;
+    readonly capabilities: RuntimeCapabilities;
+    readonly audio: AudioAdapter;
+    readonly media: MediaAdapter;
+    readonly peer: PeerConnectionAdapter;
+    readonly dataChannel: DataChannelAdapter;
+    readonly storage: StorageAdapter;
+}
+
+const RN_RUNTIME_REQUIRED_MESSAGE =
+    '[VaniraSDK] runtime is required. Import createReactNativeClient/createReactNativeAI from \'@vanira/sdk-react-native\'.';
+
+/**
+ * True when running in React Native (after react-native-webrtc registerGlobals()).
+ * Do not infer platform from typeof window — RN polyfills window.
+ */
+export function isReactNative(): boolean {
+    return (
+        typeof navigator !== 'undefined' &&
+        (navigator as Navigator & { product?: string }).product === 'ReactNative'
+    );
+}
+
+function mergeRuntime(base: VaniraRuntime, config: WebRTCClientConfig): ResolvedRuntimeConfig {
+    return {
+        name: base.name,
+        runtimeName: base.runtimeName,
+        callType: base.callType,
+        callIdPrefix: base.callIdPrefix,
+        capabilities: base.capabilities,
+        audio: config.audioAdapter ?? base.audio,
+        media: config.mediaAdapter ?? base.media,
+        peer: config.peerAdapter ?? base.peer,
+        dataChannel: config.dataChannelAdapter ?? base.dataChannel,
+        storage: config.storageAdapter ?? base.storage,
+    };
+}
+
+/**
+ * Resolve platform adapters and metadata from WebRTCClientConfig.
+ * Individual adapter fields on config override the bundle defaults.
+ */
+export function resolveRuntimeConfig(config: WebRTCClientConfig): ResolvedRuntimeConfig {
+    if (config.runtime) {
+        return mergeRuntime(config.runtime, config);
+    }
+
+    if (isReactNative()) {
+        throw new Error(RN_RUNTIME_REQUIRED_MESSAGE);
+    }
+
+    return mergeRuntime(browserDefaultBundle, config);
+}

package/src/runtime/runtimeBundles.ts

@@ -0,0 +1,74 @@
+/**
+ * Platform runtime bundles — adapter singletons and metadata.
+ *
+ * Must NOT import from core/ (WebRTCClient, VaniraAI) to avoid circular deps.
+ * Consumed by browserRuntime.ts, reactNativeRuntime.ts, and resolveRuntimeConfig.ts.
+ */
+
+import type { VaniraRuntime, RuntimeCapabilities } from './types';
+
+import { BrowserAudioAdapter } from '../adapters/browser/BrowserAudioAdapter';
+import { BrowserMediaAdapter } from '../adapters/browser/BrowserMediaAdapter';
+import { BrowserPeerAdapter } from '../adapters/browser/BrowserPeerAdapter';
+import { BrowserDataChannelAdapter } from '../adapters/browser/BrowserDataChannelAdapter';
+
+import { RNAudioAdapter } from '../adapters/react-native/RNAudioAdapter';
+import { RNMediaAdapter } from '../adapters/react-native/RNMediaAdapter';
+import { RNPeerAdapter } from '../adapters/react-native/RNPeerAdapter';
+import { RNDataChannelAdapter } from '../adapters/react-native/RNDataChannelAdapter';
+
+import { BrowserDualStorageAdapter } from '../adapters/storage/BrowserDualStorageAdapter';
+import { MemoryStorageAdapter } from '../adapters/storage/MemoryStorageAdapter';
+
+// ─── Capabilities ─────────────────────────────────────────────────────────────
+
+export const browserCapabilities: RuntimeCapabilities = {
+    supportsAudioEndedEvent: true,
+    supportsScreenShare:
+        typeof navigator !== 'undefined' &&
+        typeof (navigator.mediaDevices as MediaDevices & { getDisplayMedia?: unknown })
+            ?.getDisplayMedia === 'function',
+    supportsDom: typeof document !== 'undefined',
+    supportsHtmlAudio: typeof Audio !== 'undefined',
+    supportsCustomElements: typeof customElements !== 'undefined',
+    supportsLocalStorage: typeof localStorage !== 'undefined',
+    supportsBroadcastChannel: typeof BroadcastChannel !== 'undefined',
+};
+
+export const reactNativeCapabilities: RuntimeCapabilities = {
+    supportsAudioEndedEvent: false,
+    supportsScreenShare: false,
+    supportsDom: false,
+    supportsHtmlAudio: false,
+    supportsCustomElements: false,
+    supportsLocalStorage: false,
+    supportsBroadcastChannel: false,
+};
+
+// ─── Default bundles ────────────────────────────────────────────────────────
+
+export const browserDefaultBundle: VaniraRuntime = {
+    name: 'browser',
+    callType: 'web',
+    runtimeName: 'browser',
+    callIdPrefix: 'web_',
+    capabilities: browserCapabilities,
+    audio: new BrowserAudioAdapter(),
+    media: new BrowserMediaAdapter(),
+    peer: new BrowserPeerAdapter(),
+    dataChannel: new BrowserDataChannelAdapter(),
+    storage: new BrowserDualStorageAdapter(),
+};
+
+export const reactNativeDefaultBundle: VaniraRuntime = {
+    name: 'react-native',
+    callType: 'web',
+    runtimeName: 'react-native',
+    callIdPrefix: 'rn_',
+    capabilities: reactNativeCapabilities,
+    audio: new RNAudioAdapter(),
+    media: new RNMediaAdapter(),
+    peer: new RNPeerAdapter(),
+    dataChannel: new RNDataChannelAdapter(),
+    storage: new MemoryStorageAdapter(),
+};

package/src/runtime/types.ts

@@ -0,0 +1,135 @@
+/**
+ * Runtime types for the Vanira SDK cross-platform layer.
+ *
+ * A VaniraRuntime bundles all platform adapters, capability flags, and
+ * protocol metadata into a single composable object.  The WebRTCClient
+ * accepts a VaniraRuntime in its config so all platform details are
+ * injected from a single source of truth per platform.
+ *
+ * Current runtimes:
+ *   browserRuntime  — Web browsers
+ *   reactNativeRuntime — React Native via react-native-webrtc
+ *
+ * Future:
+ *   flutterRuntime — Dart, implemented separately in flutter-sdk/
+ */
+
+import type { AudioAdapter, MediaAdapter } from '../adapters/interfaces';
+import type { PeerConnectionAdapter, DataChannelAdapter } from '../adapters/PeerConnectionAdapter';
+import type { StorageAdapter } from '../adapters/storage/StorageAdapter';
+
+// ─── RuntimeCapabilities ──────────────────────────────────────────────────────
+
+/**
+ * Declarative flags describing what the current platform supports.
+ * Use these instead of hardcoded platform checks throughout the codebase.
+ *
+ * The backend also receives the runtime name and uses it to skip
+ * `playedStream` waiting for platforms that don't fire `onended`.
+ */
+export interface RuntimeCapabilities {
+    /**
+     * Whether HTMLAudioElement.onended fires after a TTS stream finishes.
+     * Browser: true — fires naturally after the stream ends.
+     * RN: false — react-native-webrtc routes audio natively, no onended event.
+     * Flutter: false — flutter_webrtc routes audio natively.
+     */
+    supportsAudioEndedEvent: boolean;
+
+    /**
+     * Whether getDisplayMedia (screen capture) is available.
+     * Browser: true (desktop), false on mobile browsers.
+     * RN: false — no screen capture API.
+     * Flutter: false — flutter_webrtc does not expose getDisplayMedia.
+     */
+    supportsScreenShare: boolean;
+
+    /**
+     * Whether document, window, and DOM APIs are present.
+     * Browser: true.  RN: false.  Flutter: false.
+     */
+    supportsDom: boolean;
+
+    /**
+     * Whether new Audio() / HTMLAudioElement is constructable.
+     * Browser: true.  RN: false.  Flutter: false.
+     */
+    supportsHtmlAudio: boolean;
+
+    /**
+     * Whether customElements.define() is available for widget registration.
+     * Browser: true.  RN: false.  Flutter: false.
+     */
+    supportsCustomElements: boolean;
+
+    /**
+     * Whether localStorage / sessionStorage are available.
+     * Browser: true.  RN: false (AsyncStorage used instead).  Flutter: false.
+     */
+    supportsLocalStorage: boolean;
+
+    /**
+     * Whether BroadcastChannel (cross-tab communication) is available.
+     * Browser: true.  RN: false.  Flutter: false.
+     */
+    supportsBroadcastChannel: boolean;
+}
+
+// ─── VaniraRuntime ────────────────────────────────────────────────────────────
+
+/**
+ * A VaniraRuntime encapsulates everything the WebRTCClient needs to know
+ * about the current platform:
+ *
+ *   - Which adapters to use for media, audio, peer connection, data channel
+ *   - What metadata to send to the backend (type, runtime)
+ *   - How to generate call IDs
+ *   - What features are available (capabilities)
+ *
+ * The WebRTCClient accepts a runtime via config.runtime and extracts all
+ * adapter + metadata from it.  Individual adapter fields on config are still
+ * supported for backward compatibility.
+ */
+export interface VaniraRuntime {
+    /** Human-readable runtime identifier */
+    readonly name: 'browser' | 'react-native' | 'flutter' | string;
+
+    /**
+     * Sent as `type` in the /calls/create request body.
+     * Must be `web` for all WebRTC flows — the API only accepts `web` | `sip`.
+     * Use `runtimeName` for browser vs react-native vs flutter.
+     */
+    readonly callType: 'web';
+
+    /**
+     * Sent as `runtime` in the /calls/create request body.
+     * Replaces the old callId prefix convention.
+     * Values: 'browser' | 'react-native' | 'flutter'
+     */
+    readonly runtimeName: string;
+
+    /**
+     * Prefix used when auto-generating a callId (no prefix conflicts with
+     * runtime field, but kept for logging / tracing convenience).
+     * 'web_' | 'rn_' | 'flutter_'
+     */
+    readonly callIdPrefix: string;
+
+    /** Runtime capability flags */
+    readonly capabilities: RuntimeCapabilities;
+
+    /** Audio output adapter (remote TTS playback) */
+    readonly audio: AudioAdapter;
+
+    /** Media input adapter (microphone access) */
+    readonly media: MediaAdapter;
+
+    /** RTCPeerConnection factory adapter */
+    readonly peer: PeerConnectionAdapter;
+
+    /** DataChannel event binding + message normalisation adapter */
+    readonly dataChannel: DataChannelAdapter;
+
+    /** Session persistence for prospect/call id (continue mode) */
+    readonly storage: StorageAdapter;
+}

package/src/types/react-native-incall-manager.d.ts

@@ -0,0 +1,17 @@
+declare module 'react-native-incall-manager' {
+  type StartOptions = {
+    media?: 'audio' | 'video';
+    auto?: boolean;
+    ringback?: string;
+  };
+
+  const InCallManager: {
+    start(options?: StartOptions): void;
+    stop(): void;
+    setSpeakerphoneOn(enabled: boolean): void;
+    setForceSpeakerphoneOn(enabled: boolean | null): void;
+    setKeepScreenOn(enabled: boolean): void;
+  };
+
+  export default InCallManager;
+}

package/src/types/react-native-webrtc.d.ts

@@ -0,0 +1,47 @@
+declare module 'react-native-webrtc' {
+  import type {Component} from 'react';
+  import type {ViewProps} from 'react-native';
+
+  export interface MediaStreamTrack {
+    stop(): void;
+  }
+
+  export interface MediaStream {
+    getTracks(): MediaStreamTrack[];
+    toURL(): string;
+  }
+
+  export const mediaDevices: {
+    getUserMedia(constraints: {
+      video?: boolean | {facingMode?: string};
+      audio?: boolean;
+    }): Promise<MediaStream>;
+  };
+
+  export type RTCViewProps = ViewProps & {
+    streamURL: string | null;
+    objectFit?: 'contain' | 'cover';
+    mirror?: boolean;
+  };
+
+  export class RTCView extends Component<RTCViewProps> {}
+}
+
+declare module 'react-native-view-shot' {
+  import type {Component} from 'react';
+  import type {ViewProps} from 'react-native';
+
+  export type CaptureOptions = {
+    format?: 'jpg' | 'png' | 'webm' | 'raw';
+    quality?: number;
+    result?: 'tmpfile' | 'base64' | 'data-uri' | 'zip-base64';
+  };
+
+  export type ViewShotProperties = ViewProps & {
+    options?: CaptureOptions;
+  };
+
+  export default class ViewShot extends Component<ViewShotProperties> {
+    capture?(options?: CaptureOptions): Promise<string>;
+  }
+}

package/src/types.ts

@@ -0,0 +1,133 @@
+export interface TTSVoice {
+    tts_provider: string;
+}
+
+export interface Agent {
+    tts_voice?: TTSVoice;
+    chat_welcome_message?: any;
+}
+
+export type WidgetMode = 'voice_only' | 'chat_voice' | 'avatar_only' | 'chat_avatar' | 'chat_only';
+
+export interface WidgetConfig {
+    agent_id: string;
+    client_id: string;
+    mode: WidgetMode;
+    icon?: string;
+    gradient?: string;
+    primary_color?: string;
+    secondary_color?: string;
+    icon_config?: {
+        logo_text?: string;
+        title?: string;
+        button_text?: string;
+    };
+    agent?: Agent;
+    client?: {
+        base_prospect_group_id?: string;
+    };
+}
+
+export interface WebRTCClientConfig {
+    agentId: string;
+    /** Your sk_live_* or pk_live_* key. Required when using createCall(). */
+    apiKey?: string;
+    /** Override the Vanira API base URL. Defaults to https://api.vanira.io */
+    backendUrl?: string;
+    /** WebRTC worker URL. Required when calling connect() directly; set automatically by createCall(). */
+    serverUrl?: string;
+    /** Call ID. Set automatically by createCall(); supply manually if managing the session yourself. */
+    callId?: string;
+    /** Optional prospect ID. If supplied, the SDK resumes the prospect context. */
+    prospectId?: string;
+    /** Lifecycle behavior when starting a connection ('continue' or 'new') */
+    sessionBehavior?: 'continue' | 'new';
+    /** Callback when session starts or resumes with resolved IDs and server URL */
+    onSessionStarted?: (payload: { prospectId: string; callId: string; serverUrl: string }) => void;
+    onConnected?: () => void;
+    onDisconnected?: () => void;
+    onError?: (error: unknown) => void;
+    onTranscription?: (text: string, isFinal: boolean) => void;
+    onLocalStream?: (stream: MediaStream) => void;
+    onRemoteTrack?: (track: MediaStreamTrack, stream: MediaStream) => void;
+    onClientToolCall?: (toolCall: unknown) => void;
+    /**
+     * @deprecated ICE comes from POST /calls/create — do not pass manually.
+     */
+    iceServers?: RTCIceServer[];
+    token?: string;
+
+    // ── Runtime (preferred — sets all adapters + protocol metadata at once) ──
+    //
+    // Provide a VaniraRuntime to inject all platform adapters and backend
+    // metadata (callType, runtimeName) in a single object.
+    //
+    //   import { browserRuntime }      from 'vanira-sdk/runtime/browser';
+    //   import { reactNativeRuntime }  from 'vanira-sdk/runtime/react-native';
+    //
+    // Individual adapter fields below are still supported for custom setups
+    // and remain the source of truth when runtime is not provided.
+    runtime?: import('./runtime/types').VaniraRuntime;
+
+    // ── Platform adapters (individual — overridden by runtime if provided) ───
+
+    /**
+     * Audio output adapter. Controls how incoming remote audio is played.
+     * Default (browser): HTMLAudioElement-backed player.
+     * React Native: no-op stub (react-native-webrtc routes audio natively).
+     */
+    audioAdapter?: import('./adapters/interfaces').AudioAdapter;
+
+    /**
+     * Media input adapter. Controls how the microphone is accessed.
+     * Default (browser): navigator.mediaDevices.getUserMedia.
+     * React Native: react-native-webrtc mediaDevices.getUserMedia polyfill.
+     */
+    mediaAdapter?: import('./adapters/interfaces').MediaAdapter;
+
+    /**
+     * RTCPeerConnection factory adapter.
+     * Default (browser): BrowserPeerAdapter (wraps new RTCPeerConnection()).
+     * React Native: RNPeerAdapter (wraps react-native-webrtc global).
+     */
+    peerAdapter?: import('./adapters/PeerConnectionAdapter').PeerConnectionAdapter;
+
+    /**
+     * DataChannel event binding + message normalisation adapter.
+     * Default (browser): BrowserDataChannelAdapter (handles string/ArrayBuffer/Blob).
+     * React Native: RNDataChannelAdapter (string-only, no binary normalisation).
+     */
+    dataChannelAdapter?: import('./adapters/PeerConnectionAdapter').DataChannelAdapter;
+
+    /**
+     * Session persistence adapter for prospect/call id when sessionBehavior is 'continue'.
+     * Default (browser): BrowserDualStorageAdapter (sessionStorage + localStorage).
+     * React Native: MemoryStorageAdapter unless overridden — inject createSyncStorageAdapter for production.
+     */
+    storageAdapter?: import('./adapters/storage/StorageAdapter').StorageAdapter;
+
+    /**
+     * Fired when a client_tool_call includes a preset_id, before onClientToolCall and
+     * before the browser vanira:preset DOM event (when dispatch is available).
+     * Primary preset delivery path on React Native (no DOM).
+     */
+    onPreset?: (payload: PresetEventPayload) => void;
+}
+
+/** Payload for onPreset and VaniraAI 'preset' event */
+export interface PresetEventPayload {
+    toolCall: unknown;
+    client: import('./core/WebRTCClient').WebRTCClient;
+}
+
+export interface ControlEvent {
+    event: string;
+    text?: string;
+    isFinal?: boolean;
+    name?: string;
+    tool_call?: unknown;
+    data?: unknown;
+    // Index signature allows accessing arbitrary fields from server events
+    // without casting, while the named fields above provide IDE autocomplete.
+    [key: string]: unknown;
+}

package/src/ui/VaniraWidget.ts

@@ -0,0 +1,87 @@
+import { ConfigService } from '../api/services/ConfigService';
+import { WidgetProviderFactory } from './factory/WidgetFactory';
+import { IWidgetProvider } from './abstraction/interfaces';
+
+export class VaniraWidget extends HTMLElement {
+    private shadow: ShadowRoot;
+    private provider: IWidgetProvider | null = null;
+
+    // Config attributes
+    private widgetId: string = "";
+    private agentId: string = "";
+    private pkKey: string = "";
+    private serverUrl: string = "https://inboxapi.vanira.io";
+    private position: string = "bottom-right";
+    private primaryColor: string = "#000000";
+    private secondaryColor: string = "#000000";
+    private gradient: string | null = null;
+    private positionType: string = "fixed";
+
+    static get observedAttributes() {
+        return ['widget-id', 'agent-id', 'position', 'primary-color', 'secondary-color', 'server-url', 'gradient', 'position-type', 'pk-key'];
+    }
+
+    constructor() {
+        super();
+        this.shadow = this.attachShadow({ mode: 'open' });
+    }
+
+    connectedCallback() {
+        console.log("[VaniraAI Widget] Initializing...");
+        this.readAttributes();
+
+        // Initial Config based on attributes
+        const initialConfig = {
+            widgetId: this.widgetId,
+            agentId: this.agentId,
+            pkKey: this.pkKey,
+            serverUrl: this.serverUrl,
+            position: this.position,
+            primaryColor: this.primaryColor,
+            secondaryColor: this.secondaryColor,
+            gradient: this.gradient,
+            positionType: this.positionType
+        };
+
+        // Factory Pattern: Create specific provider
+        this.provider = WidgetProviderFactory.getProvider(initialConfig);
+
+        // UI Renderer: Delegate to provider (SRP)
+        if (this.provider) {
+            this.provider.ui_renderer(this.shadow);
+        }
+
+        // Fetch expanded config if widgetId is present
+        if (this.widgetId && !this.agentId) {
+            this.initializeExpandedConfig();
+        }
+    }
+
+    private readAttributes() {
+        this.widgetId = this.getAttribute('widget-id') || "";
+        this.agentId = this.getAttribute('agent-id') || "";
+        this.pkKey = this.getAttribute('pk-key') || "";
+        this.serverUrl = this.getAttribute('server-url') || "https://inboxapi.vanira.io";
+        this.position = this.getAttribute('position') || "bottom-right";
+        this.primaryColor = this.getAttribute('primary-color') || "#000000";
+        this.secondaryColor = this.getAttribute('secondary-color') || this.primaryColor;
+        this.gradient = this.getAttribute('gradient');
+        this.positionType = this.getAttribute('position-type') || "fixed";
+    }
+
+    async initializeExpandedConfig() {
+        try {
+            const config = await ConfigService.fetchWidgetConfig(this.widgetId, this.pkKey || undefined);
+
+            // Pass API config to provider to update state/UI
+            if (this.provider) {
+                // This will trigger internal re-render in provider
+                await this.provider.initialize(config);
+            }
+        } catch (error) {
+            console.error("[VaniraAI Widget] Config failed:", error);
+            // specific error handling or Fallback_principle logic can be added here
+            // Provider already has default state (Graceful degradation)
+        }
+    }
+}

package/src/ui/abstraction/AbstractWidgetProvider.ts

@@ -0,0 +1,18 @@
+import { IWidgetProvider } from './interfaces';
+
+export abstract class AbstractWidgetProvider implements IWidgetProvider {
+    protected config: any;
+    protected root: ShadowRoot | null = null;
+
+    constructor(config: any) {
+        this.config = config;
+    }
+
+    abstract create_call(): Promise<void>;
+    abstract end_call(): void;
+    abstract ui_renderer(root: ShadowRoot): void;
+
+    async initialize(config: any): Promise<void> {
+        this.config = config;
+    }
+}