@hachther/akilio-widget 0.7.0 → 1.0.0

package/dist/types.d.ts

@@ -7,13 +7,16 @@ export type AkilioLocale = string;
 export type AkilioMessageRole = 'user' | 'assistant';
 export type AkilioFeedbackRating = 'up' | 'down';
 export type AkilioAssistantMode = 'auto' | 'general' | 'knowledge' | 'ecommerce' | 'hybrid';
-export type AkilioChatIntent = 'answer' | 'summarize_page' | 'contact';
+export type AkilioChatIntent = 'answer' | 'summarize_page' | 'summarize_conversation' | 'contact';
 export type AkilioCapabilitySurface = 'widget' | 'public_api';
 export type AkilioWidgetBranding = 'akilio_required' | 'removable' | 'white_label';
-export type AkilioCommerceCapabilityType = 'product_search' | 'product_recommendation';
+export type AkilioCommerceCapabilityType = 'product_search' | 'product_recommendation' | 'product_comparison' | 'compatibility_check' | 'bundle_building' | 'upsell' | 'cross_sell' | 'shipping_estimate' | 'cart_actions' | (string & {});
+export type AkilioCommerceActionType = 'view_product' | 'compare' | 'add_to_cart';
+export type AkilioCartActionType = 'update_quantity' | 'remove_from_cart' | (string & {});
 export type AkilioCommerceEventType = 'search' | 'recommendation' | 'compare' | 'add_to_cart' | 'checkout' | 'purchase';
 export type AkilioCredentialsMode = 'omit' | 'same-origin' | 'include';
 export type StreamEventType = 'open' | 'close' | 'answer-complete' | 'question' | 'answer-start' | 'answer-delta' | 'error' | 'typing-cancel' | 'draft-change' | 'typing-start' | 'typing-complete' | 'reset' | 'ready';
+export type ConfidentLevel = 'high' | 'medium' | 'low' | 'none';
 export type AkilioTokenProvider = () => string | null | undefined | Promise<string | null | undefined>;
 export interface AkilioIssuedWidgetToken {
     token: string;
@@ -55,15 +58,94 @@ export interface AkilioThemeConfig {
     logo_url?: string;
     brand_name?: string;
     color_mode?: AkilioColorMode;
+    launcher_position?: AkilioLauncherPosition;
 }
 export interface AkilioPageContext {
     url?: string;
     title?: string;
-    audience?: string;
     productArea?: string;
     channel?: string;
     metadata?: Record<string, unknown>;
 }
+export type AkilioEntrySurface = 'widget_launcher' | 'inline_widget' | 'product_card' | 'product_detail' | 'pricing' | 'cart' | 'checkout' | 'help_center' | 'portal' | 'demo' | 'integration' | 'api';
+export type AkilioEntryTrigger = 'manual_open' | 'inline_cta' | 'section_prompt' | 'text_selection' | 'product_question' | 'plan_question' | 'comparison' | 'cart_question' | 'checkout_help' | 'error_help' | 'proactive_suggestion' | 'external_handoff';
+export type AkilioEntrySubjectType = 'product' | 'product_variant' | 'plan' | 'cart' | 'order' | 'article' | 'faq' | 'knowledge_document' | 'workspace_offering';
+export interface AkilioEntryContext {
+    schema_version?: '1.0';
+    origin: {
+        surface: AkilioEntrySurface;
+        trigger: AkilioEntryTrigger;
+    };
+    page?: {
+        url: string;
+        title?: string;
+        section?: {
+            id?: string;
+            title?: string;
+            anchor?: string;
+        };
+    };
+    subject?: {
+        type: AkilioEntrySubjectType;
+        id: string;
+        parent_id?: string;
+    };
+    selection?: {
+        text: string;
+        start_offset?: number;
+        end_offset?: number;
+        selector?: string;
+    };
+    state?: {
+        cart_id?: string;
+        order_id?: string;
+        error_code?: string;
+        error_message?: string;
+    };
+    metadata?: {
+        referrer?: string;
+        campaign?: string;
+        experiment?: string;
+    };
+}
+export type AkilioWidgetAnalyticsEventType = 'contextual_entry_impression' | 'contextual_entry_open' | 'contextual_entry_dismissed' | 'contextual_entry_question_submitted' | 'widget_opened' | 'widget_closed' | 'suggestion_clicked';
+export interface AkilioWidgetAnalyticsEvent {
+    event_id: string;
+    event_type: AkilioWidgetAnalyticsEventType;
+    entry_context?: AkilioEntryContext;
+    metadata: Record<string, string | undefined>;
+}
+export interface AkilioInlineDecisionSubject {
+    type: 'product' | 'product_variant' | 'plan' | 'workspace_offering';
+    id: string;
+    parent_id?: string;
+}
+export interface AkilioInlineDecisionCardProps {
+    title: string;
+    description: string;
+    subject?: AkilioInlineDecisionSubject;
+    page?: AkilioEntryContext['page'];
+    primaryQuestion: string;
+    followUpQuestions?: string[];
+    onStartConversation?: (question: string, entryContext: AkilioEntryContext) => void;
+    className?: string;
+}
+export interface AkilioSectionPromptProps {
+    sectionTitle: string;
+    sectionId?: string;
+    question: string;
+    page?: AkilioEntryContext['page'];
+    onStartConversation?: (question: string, entryContext: AkilioEntryContext) => void;
+    className?: string;
+}
+export interface AkilioTextSelectionPromptProps {
+    container: HTMLElement | null;
+    sectionTitle?: string;
+    sectionId?: string;
+    minCharacters?: number;
+    question: string;
+    onStartConversation?: (question: string, entryContext: AkilioEntryContext) => void;
+}
 export interface AkilioSource {
     title?: string | null;
     url?: string | null;
@@ -80,9 +162,16 @@ export interface AkilioProductVariant {
     compare_at_price?: string | null;
     currency?: string;
     inventory_quantity?: number;
-    options?: unknown;
+    options?: {
+        Size?: string;
+    };
     available: boolean;
 }
+export interface AkilioProductAttribute {
+    key: string;
+    label: string;
+    value: string;
+}
 export interface AkilioProduct {
     id: string;
     external_id: string;
@@ -92,15 +181,53 @@ export interface AkilioProduct {
     product_type?: string;
     url?: string;
     image_url?: string;
-    tags?: unknown;
-    attributes?: unknown;
-    available: string;
+    tags?: string[];
+    attributes?: AkilioProductAttribute[];
+    available: boolean;
     variants: AkilioProductVariant[];
-    business_rule_decision?: Record<string, unknown>;
+    business_rule_decision?: {
+        allowed: boolean;
+        score_adjustment: number;
+        reasons: string[];
+        required_product_ids: string[];
+    };
+    search_relevance?: number;
 }
 export interface AkilioCommerceCapability {
     capability: AkilioCommerceCapabilityType;
     products: AkilioProduct[];
+    suggestedProducts?: AkilioProduct[];
+    actions?: AkilioCommercePublicAction[];
+    /** Controls the presentation of a trusted product-detail response. */
+    display?: 'list' | 'detail';
+}
+export interface AkilioCommercePublicAction {
+    type: AkilioCommerceActionType;
+    product_id?: string;
+    variant_id?: string;
+    label_key?: string;
+    label_parameters?: Record<string, string>;
+    requires_confirmation?: boolean;
+    confirmation?: {
+        capability_id: string;
+        request_endpoint: string;
+        approve_endpoint_template: string;
+        execution_endpoint: string;
+        payload: {
+            items: {
+                variant_id: string;
+                quantity: number;
+            }[];
+        };
+        idempotency_key_required?: boolean;
+    };
+}
+/** OpenAPI `CommercePublicResponse`; its product/action payloads are extensible. */
+export interface AkilioCommercePublicResponse {
+    capability: AkilioCommerceCapabilityType;
+    products: AkilioProduct[];
+    suggested_products?: AkilioProduct[];
+    actions?: AkilioCommercePublicAction[];
 }
 export interface AkilioCommerceEvent {
     event_type: AkilioCommerceEventType;
@@ -112,6 +239,83 @@ export interface AkilioCommerceEvent {
     currency?: string;
     metadata?: Record<string, unknown>;
 }
+/** Compact cart summary returned alongside a chat response. */
+export interface AkilioCartState {
+    id: string;
+    provider_cart_id: string;
+    provider: string;
+    status: string;
+    item_count: number;
+    updated_at: string;
+}
+export interface AkilioCartLine {
+    id: string;
+    line_id: string;
+    product_id?: string | null;
+    /** Product snapshot returned with the cart line, when available. */
+    product?: {
+        id: string;
+        title: string;
+        vendor?: string | null;
+        image_url?: string | null;
+        url?: string | null;
+    } | null;
+    /** Variant snapshot returned with the cart line, when available. */
+    variant?: {
+        id: string;
+        title?: string | null;
+        sku?: string | null;
+        options?: Record<string, string> | null;
+    } | null;
+    variant_id?: string | null;
+    title: string;
+    quantity: number;
+    price: string;
+    currency: string;
+    /** Provider-approved actions appropriate for this cart's current state. */
+    actions?: AkilioCartAction[];
+}
+export interface AkilioCartCheckout {
+    mode: 'provider' | 'internal' | 'external_redirect' | string;
+    status: string;
+    next_action?: {
+        type: 'contact_request' | 'external_redirect' | string;
+        url?: string;
+    };
+}
+/**
+ * A widget-safe action supplied with the current cart. Cart actions are
+ * intentionally independent from chat product actions: they may not target a
+ * product and their destination is supplied by the cart provider.
+ */
+export interface AkilioCartAction {
+    id?: string;
+    type: AkilioCartActionType;
+    label?: string;
+    label_key?: string;
+    label_parameters?: Record<string, string>;
+    requires_confirmation?: boolean;
+    confirmation?: {
+        capability_id: string;
+        request_endpoint: string;
+        approve_endpoint_template: string;
+        execution_endpoint: string;
+        payload: Record<string, unknown>;
+        idempotency_key_required?: boolean;
+    };
+}
+export interface AkilioCart {
+    id: string;
+    provider: string;
+    provider_cart_id: string;
+    checkout_url?: string;
+    checkout: AkilioCartCheckout;
+    status: 'active' | 'checkout_started' | 'completed' | 'expired' | string;
+    lines: AkilioCartLine[];
+}
+export interface AkilioCurrentCartResponse {
+    cart: AkilioCart | null;
+}
 export interface AkilioProjectConfig {
     project_key: string;
     name: string;
@@ -119,6 +323,7 @@ export interface AkilioProjectConfig {
     title: string;
     placeholder: string;
     starter_questions: string[];
+    welcome_message?: string;
     theme_config: AkilioThemeConfig;
     default_language: string;
     supported_languages: string[];
@@ -148,21 +353,45 @@ export interface AkilioContactRequestCapability {
     consent_text: string;
     required_fields: string[];
 }
-export type AkilioContactOptionType = 'email' | 'phone' | 'form';
-export interface AkilioContactOption {
-    type: AkilioContactOptionType;
+export type AkilioQuickActionType = 'email' | 'phone' | 'form';
+export interface AkilioQuickActionOption {
+    type: AkilioQuickActionType;
     label: string;
     value?: string;
     url: string;
 }
+export type AkilioCustomerActionType = 'start_contact_request' | 'start_human_handoff';
 export interface AkilioCustomerAction {
-    type: 'start_contact_request';
+    type: AkilioCustomerActionType;
     label: string;
     prompt: string;
     endpoint: string;
     method: string;
     requires_confirmation: boolean;
+    confirmation_mode?: 'form_consent' | string;
     fields: string[];
+    quickActions?: AkilioQuickActionOption[];
+}
+export interface AkilioProactiveAction {
+    type: 'summarize_conversation' | string;
+    label?: string;
+    intent: 'summarize_conversation' | string;
+    message?: string;
+}
+export type AkilioContextRelation = 'initial' | 'continuation' | 'new_topic' | 'explicit_reset';
+export interface AkilioMarketContext {
+    scope_type: string;
+    code?: string;
+    name?: string;
+    parent_code?: string;
+    source?: string;
+    confidence?: number;
+    approximate?: boolean;
+}
+export interface AkilioChatHumanEscalation {
+    id: string;
+    status?: string;
+    reason: 'customer_request' | 'insufficient_evidence' | 'sensitive_question' | 'invalid_citation' | 'policy_review';
 }
 export type AkilioPreferredContactMethod = 'email' | 'phone' | 'either';
 export interface AkilioContactRequest {
@@ -175,11 +404,20 @@ export interface AkilioContactRequest {
     preferred_contact_time?: string;
     message: string;
     consent_given: boolean;
+    website?: string;
 }
 export interface AkilioContactRequestResponse {
     id: string;
     status?: string;
     created_at: string;
+    handoff: AkilioHumanHandoff;
+}
+export type AkilioHumanHandoffStatus = 'queued' | 'delivering' | 'delivered' | 'failed' | 'cancelled';
+/** Browser-safe status returned by the server-owned human-handoff workflow. */
+export interface AkilioHumanHandoff {
+    id: string;
+    status: AkilioHumanHandoffStatus;
+    created_at: string;
 }
 export interface AkilioPublicRuntimeCapabilities {
     chat: AkilioChatIntentCatalog;
@@ -197,12 +435,15 @@ export interface AkilioWidgetPolicy {
 export interface AkilioChatRequest {
     project_key: string;
     conversation_id?: string;
+    context_id?: string;
+    reset_context?: boolean;
+    capability_confirmation_id?: string;
+    clarification_response?: AkilioClarificationResponse;
     message: string;
     /** Explicit action selected from the public config capability catalog. */
     intent?: AkilioChatIntent;
     locale?: string;
     channel?: string;
-    audience?: string;
     product_area?: string;
     assistant_mode?: AkilioAssistantMode | null;
     page?: {
@@ -210,6 +451,7 @@ export interface AkilioChatRequest {
         title?: string;
         [key: string]: unknown;
     };
+    entry_context?: AkilioEntryContext;
     anonymous_id?: string;
     external_user_id?: string;
     consent?: {
@@ -222,27 +464,102 @@ export interface AkilioWidgetTokenResponse {
     token: string;
     token_type?: string;
     expires_in: number;
+    continuation_token?: string;
+    continuation_expires_in?: number;
+}
+export interface AkilioCapability {
+    id: string;
+    code?: string;
+    name?: string;
+    input_schema?: Record<string, unknown>;
+    output_schema?: Record<string, unknown>;
+    requires_confirmation?: boolean;
+    risk_level?: string;
+    provider?: string;
+    executable?: boolean;
+}
+export interface AkilioCapabilityConfirmation {
+    id: string;
+    capability_id: string;
+    expires_at?: string;
+    action?: string;
+}
+export interface AkilioCustomerServiceToolResponse {
+    tool_id: string;
+    result: unknown;
+}
+export interface AkilioAgentTool {
+    tool_id: string;
+    requires_confirmation?: boolean;
+    action?: 'confirm_human_request' | 'start_contact_request' | string;
+    payload?: Record<string, unknown>;
+    result?: {
+        escalation_id?: string;
+        [key: string]: unknown;
+    };
+}
+export interface AkilioIntentDecision {
+    schema_version?: string;
+    intent_id?: string;
+    confidence?: number;
+    source?: string;
+    reason?: string;
+    entities?: Record<string, unknown>;
+    clarification?: AkilioClarification | null;
+}
+export interface AkilioClarificationOption {
+    value: string;
+    label: string;
+}
+export interface AkilioClarificationField {
+    key: string;
+    label: string;
+    type: 'text' | 'email' | 'tel' | 'number' | 'select' | string;
+    required: boolean;
+    options?: AkilioClarificationOption[];
+}
+export interface AkilioClarification {
+    question: string;
+    submission_template: string;
+    reason?: string;
+    missing_entities?: string[];
+    fields?: AkilioClarificationField[];
+    options?: AkilioClarificationOption[];
+}
+export interface AkilioClarificationResponse {
+    source_message_id: string;
+    values: Record<string, string>;
 }
 export interface AkilioChatResponse {
     schema_version?: string;
     conversation_id: string;
+    context_id: string;
+    context_relation: AkilioContextRelation;
+    context_changed: boolean;
     message_id: string;
-    response_type?: string;
-    content?: Record<string, unknown>;
+    response_type: string;
+    /** Canonical response body. Use markdown for the rich widget surface. */
+    content: {
+        plain_text: string;
+        markdown: string;
+    };
+    /** @deprecated Compatibility field. The widget renders `content` instead. */
     answer?: string;
-    confidence?: string | number | null;
-    sources: AkilioSource[];
-    provider?: string;
-    model?: string;
-    cost_usd?: string;
-    commerce?: AkilioCommerceCapability | null;
+    confidence?: ConfidentLevel;
+    sources?: AkilioSource[];
+    commerce?: AkilioCommercePublicResponse | null;
+    cart_state?: AkilioCartState | null;
     suggestions?: string[];
     intent?: AkilioChatIntent;
-    contact_options?: AkilioContactOption[];
-    actions?: AkilioCustomerAction[];
     warnings?: string[];
-    assistant_mode?: string;
-    active_route?: string;
+    effective_market?: AkilioMarketContext | null;
+    grounded?: boolean;
+    refused?: boolean;
+    escalation?: AkilioChatHumanEscalation | null;
+    actions?: AkilioCustomerAction[];
+    proactive_actions?: AkilioProactiveAction[];
+    agent_tool?: Record<string, unknown> | null;
+    intent_decision?: AkilioIntentDecision;
 }
 export type AkilioStreamEventName = 'status' | 'conversation' | 'answer.delta' | 'final' | 'error' | 'done';
 export interface AkilioStreamEvent {
@@ -281,6 +598,7 @@ export interface AkilioPublicApi {
     cancelTyping(): void;
     submit(): Promise<AkilioChatResponse>;
     ask(text: string, options?: AkilioDraftOptions): Promise<AkilioChatResponse>;
+    startConversation(text: string, entryContext: AkilioEntryContext): Promise<AkilioChatResponse>;
     reset(): Promise<void>;
     getState(): AkilioPublicState;
 }
@@ -298,7 +616,7 @@ export interface AkilioConversationMessageResponse {
     role: AkilioMessageRole;
     content: string;
     sources?: AkilioSource[];
-    confidence?: string | number | null;
+    confidence?: ConfidentLevel;
     metadata?: Record<string, unknown>;
     structured_content?: string;
     created_at: string;
@@ -325,13 +643,16 @@ export interface AkilioChatMessage {
     model?: string;
     costUsd?: string;
     commerce?: AkilioCommerceCapability | null;
+    agentTool?: AkilioAgentTool | null;
+    clarification?: AkilioClarification | null;
     suggestions?: string[];
     /** True while answer deltas are still arriving. */
     streaming?: boolean;
     error?: boolean;
     feedback?: AkilioFeedbackRating;
-    contactOptions?: AkilioContactOption[];
     actions?: AkilioCustomerAction[];
+    proactiveActions?: AkilioProactiveAction[];
+    intentDecision?: AkilioIntentDecision;
 }
 export interface AkilioCopyOverrides {
     launcher?: string;
@@ -370,7 +691,22 @@ export interface AkilioCopyOverrides {
     contactSubmit?: string;
     contactSending?: string;
     contactSuccess?: string;
+    handoffQueued?: string;
+    handoffDelivering?: string;
+    handoffDelivered?: string;
+    handoffFailed?: string;
+    handoffCancelled?: string;
     contactFailed?: string;
+    humanRequestTitle?: string;
+    humanRequestDescription?: string;
+    humanRequestConsequences?: string;
+    humanRequestConfirm?: string;
+    humanRequestCancel?: string;
+    humanRequestSending?: string;
+    humanRequestFailed?: string;
+    humanRequestSuccess?: string;
+    clarificationNeeded?: string;
+    clarificationSubmit?: string;
     voteUp?: string;
     voteDown?: string;
     requestFailed?: string;
@@ -390,15 +726,51 @@ export interface AkilioCopyOverrides {
     tourAction?: string;
     tourDismiss?: string;
     summarizePage?: string;
+    summarizeConversation?: string;
+    proactiveSummaryTitle?: string;
+    proactiveSummaryMessage?: string;
+    proactiveSummaryDismiss?: string;
     privacyDefaultNotice?: string;
     switchToLightMode?: string;
     switchToDarkMode?: string;
     products?: string;
+    suggestedProducts?: string;
+    matchedProducts?: string;
+    productRecommendations?: string;
+    productComparison?: string;
+    compatibleProducts?: string;
+    bundleProducts?: string;
+    upgradeOptions?: string;
+    complementaryProducts?: string;
+    commerceActionConfirm?: string;
+    commerceActionCancel?: string;
+    commerceActionWorking?: string;
+    commerceActionComplete?: string;
+    commerceActionFailed?: string;
+    addToCart?: string;
+    compareProduct?: string;
+    updateQuantity?: string;
+    removeFromCart?: string;
+    cart?: string;
+    cartEmpty?: string;
+    cartItems?: string;
+    checkout?: string;
+    cartUnavailable?: string;
+    refreshCart?: string;
     viewProduct?: string;
     fromPrice?: string;
     unavailable?: string;
     inStock?: string;
     outOfStock?: string;
+    rateLimited?: string;
+    launcherAnswerReady?: string;
+    launcherContact?: string;
+    launcherPageHelp?: string;
+    launcherProductHelp?: string;
+    launcherPlanHelp?: string;
+    productDetails?: string;
+    productVariants?: string;
+    productSpecifications?: string;
 }
 export interface AkilioLauncherRenderProps {
     open: boolean;
@@ -407,6 +779,8 @@ export interface AkilioLauncherRenderProps {
     toggleChat: () => void;
 }
 export type AkilioLauncher = 'default' | 'hidden' | ((controls: AkilioLauncherRenderProps) => ReactNode);
+/** Visual behaviour for the built-in launcher. */
+export type AkilioLauncherExperience = 'adaptive' | 'static';
 export type AkilioStyleIsolation = 'shadow' | 'scoped' | 'none';
 export interface AkilioContextualPromptOptions {
     enabled?: boolean;
@@ -416,11 +790,43 @@ export interface AkilioContextualPromptOptions {
     placeholder?: string;
     dismissible?: boolean;
 }
+export interface AkilioProactiveSummaryOptions {
+    enabled?: boolean;
+    /** Score required to show the prompt. Defaults to 4. */
+    threshold?: number;
+    /** Change this value when page content changes and the prompt should reappear. */
+    version?: string;
+}
 export type IntegrationType = 'shopify' | 'woocommerce' | 'wordpress' | 'prestashop' | 'magento' | 'wix' | 'webflow' | 'squarespace' | 'nextjs' | 'react' | 'vue' | 'angular' | 'vanilla' | 'unknown';
+/** Complete dictionary: TypeScript reports missing keys when adding built-in languages. */
+export interface AkilioLanguagePack {
+    direction: 'ltr' | 'rtl';
+    messages: Required<AkilioCopyOverrides> & {
+        suggestions: string[];
+    };
+    whiteLabel: Pick<Required<AkilioCopyOverrides>, 'launcher' | 'title' | 'configFailed'>;
+}
+/** Partial dictionaries inherit missing strings from their parent locale, then English. */
+export interface AkilioLanguagePackOverrides {
+    direction?: 'ltr' | 'rtl';
+    messages?: AkilioCopyOverrides & {
+        suggestions?: string[];
+    };
+    whiteLabel?: Partial<AkilioLanguagePack['whiteLabel']>;
+}
+export type AkilioTranslations = Record<string, AkilioLanguagePackOverrides>;
 export interface AkilioWidgetProps {
+    /** Business display name; copy.title takes precedence. */
+    agentName?: string;
+    /** Introductory text shown before the first message. */
+    welcomeMessage?: string;
+    /** Initial prompts. An empty list hides prompts; capability actions remain available. */
+    starterPrompts?: string[];
     apiBaseUrl?: string;
     projectKey: string;
     locale?: AkilioLocale;
+    /** Per-widget language dictionaries, also accepted by Akilio.mount(). */
+    translations?: AkilioTranslations;
     mode?: AkilioMode;
     colorMode?: AkilioColorMode;
     /** Show a header control that lets visitors override the configured/system theme. */
@@ -445,8 +851,12 @@ export interface AkilioWidgetProps {
     launcher?: AkilioLauncher;
     /** Position of the built-in launcher. right-middle opens a desktop drawer. */
     launcherPosition?: AkilioLauncherPosition;
+    /** Use the adaptive Akilio launcher or retain the original static capsule. */
+    launcherExperience?: AkilioLauncherExperience;
     /** Show a question prompt as the reader approaches the end of the page. */
     contextualPrompt?: boolean | AkilioContextualPromptOptions;
+    /** Offer a one-click page summary when the visitor shows meaningful reading intent. */
+    proactiveSummary?: boolean | AkilioProactiveSummaryOptions;
     persistOpenState?: boolean;
     /** Show a one-time, dependency-free coachmark beside the default launcher. */
     enableTour?: boolean;
@@ -459,11 +869,12 @@ export interface AkilioWidgetProps {
     anonymousId?: string;
     externalUserId?: string;
     channel?: string;
-    audience?: string;
     productArea?: string;
     /** Optional routing hint sent to the chat endpoint as assistant_mode. */
     assistantMode?: AkilioAssistantMode;
     pageContext?: AkilioPageContext | (() => AkilioPageContext);
+    /** Context supplied when this widget instance is opened from a decision surface. */
+    entryContext?: AkilioEntryContext;
     auth?: AkilioAuthConfig;
     /** Convenience alias for auth.accessToken. */
     accessToken?: string;
@@ -491,6 +902,7 @@ export interface ChatPanelProps {
     allowColorModeToggle: boolean;
     widgetAvailable: boolean;
     showBranding: boolean;
+    businessLogo?: string;
     showPoweredBy: boolean;
     copy: AkilioResolvedCopy;
     locale: string;
@@ -512,16 +924,26 @@ export interface ChatPanelProps {
     onDraftChange?: (draft: string, manual: boolean) => void;
     onFeedback: (message: AkilioChatMessage, rating: AkilioFeedbackRating) => void;
     contactRequestCapability?: AkilioContactRequestCapability;
-    onContactRequest: (request: AkilioContactRequest) => Promise<AkilioContactRequestResponse>;
+    onContactRequest: (request: AkilioContactRequest, actionType: AkilioCustomerActionType) => Promise<AkilioContactRequestResponse>;
+    onConfirmHumanRequest: (message: AkilioChatMessage, tool: AkilioAgentTool, request: AkilioContactRequest) => Promise<void>;
+    onClarificationSubmit: (message: AkilioChatMessage, values: Record<string, string>, submission: string) => Promise<void>;
     onSuggestion: (suggestion: string) => void;
+    onProactiveAction: (action: AkilioProactiveAction) => void;
+    /** Resolved starter prompts for the empty chat state. */
+    starterQuestions?: string[];
     intentActions?: Array<{
         intent: AkilioChatIntent;
         label: string;
     }>;
     onIntentAction: (intent: AkilioChatIntent, label: string) => void;
     onProductClick: (message: AkilioChatMessage, product: AkilioProduct, variant?: AkilioProductVariant) => void;
+    onCommerceAction: (message: AkilioChatMessage, action: AkilioCommercePublicAction) => Promise<void>;
     primaryColor?: string;
     slug?: string;
+    cart: AkilioCart | null;
+    cartLoading?: boolean;
+    onRefreshCart: () => void;
+    onCartAction: (line: AkilioCartLine, action: AkilioCartAction, quantity?: number) => Promise<void>;
 }
 export type IntegrationDetection = {
     integration: IntegrationType;