@action-x/ad-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1552 @@
+/**
+ * Action Card Variant
+ */
+export declare type ActionCardVariant = 'horizontal' | 'vertical' | 'compact';
+
+/**
+ * Analytics 信息（用于 SDK 内部传递）
+ */
+export declare interface AdAnalyticsInfo {
+    requestId: string;
+    slotId: string;
+    position: number;
+    totalAds: number;
+}
+
+/**
+ * Convert AdaptedAdContent to KoahAd format
+ * This allows using adapted ads with existing components
+ */
+export declare function adaptAdToKoahAd(adaptedAd: AdaptedAdContent): KoahAd;
+
+/**
+ * Adapted Ad Content
+ * Backend adapts the ad content based on slot requirements
+ */
+export declare interface AdaptedAdContent {
+    original: {
+        id: string;
+        type: AdFormat;
+        score: number;
+    };
+    adapted: {
+        title: string;
+        body: string;
+        ctaText: string;
+        image?: AdaptedAdImage;
+        price?: AdaptedAdPrice;
+        rating?: number;
+        brand?: string;
+        styling?: AdaptedAdStyling;
+        /** Entity link content (for entity_link format) */
+        entityLinkContent?: EntityLinkAdContent;
+    };
+    tracking: {
+        impressionUrl: string;
+        clickUrl: string;
+        viewToken: string;
+    };
+}
+
+/**
+ * Adapted Ad Image
+ */
+export declare interface AdaptedAdImage {
+    url: string;
+    width: number;
+    height: number;
+    aspectRatio: string;
+    fallbackColor?: string;
+}
+
+/**
+ * Adapted Ad Price
+ */
+export declare interface AdaptedAdPrice {
+    display: string;
+    value: number;
+    currency: string;
+}
+
+/**
+ * Adapted Ad Styling Suggestions
+ */
+export declare interface AdaptedAdStyling {
+    backgroundColor?: string;
+    textColor?: string;
+    accentColor?: string;
+    borderRadius?: string;
+    padding?: string;
+}
+
+/**
+ * Ad Format Types
+ * Supported native ad formats
+ */
+export declare type AdFormat = 'action_card' | 'suffix' | 'followup' | 'source' | 'static' | 'lead_gen' | 'entity_link';
+
+/**
+ * AdManager - Framework-agnostic ad management
+ */
+export declare class AdManager {
+    private config;
+    private slots;
+    private eventBus;
+    private isLoading;
+    private enabled;
+    private currentRequestId;
+    private adsAnalyticsMap;
+    constructor(config: AdManagerConfig);
+    /**
+     * Request ads for all configured slots
+     * ClientInfo is automatically collected and injected
+     *
+     * @param context - Conversation and user context
+     * @returns Promise resolving to ad response batch
+     */
+    requestAds(context: {
+        conversationContext: ConversationContext;
+        userContext?: UserContext;
+    }): Promise<AdResponseBatch>;
+    /**
+     * Render a single ad from a slot into a container element
+     *
+     * @param slotId - Slot ID to render
+     * @param container - DOM element to render into
+     * @param options - Rendering options
+     * @returns Rendered HTMLElement or null if slot/ad not found
+     */
+    render(slotId: string, container: HTMLElement, options?: {
+        adIndex?: number;
+        variant?: 'horizontal' | 'vertical' | 'compact' | 'block' | 'inline' | 'minimal' | 'card' | 'list-item';
+        onClick?: (ad: any) => void;
+        onImpression?: (ad: any) => void;
+    }): HTMLElement | null;
+    /**
+     * Get ad slots data
+     */
+    getSlots(slotId?: string): Record<string, AdSlotResponse> | AdSlotResponse | undefined;
+    /**
+     * Check if a slot has ads
+     */
+    hasAds(slotId: string): boolean;
+    /**
+     * Get ads for a specific slot
+     */
+    getAds(slotId: string): any[];
+    /**
+     * Check if currently loading
+     */
+    getLoadingStatus(): boolean;
+    /**
+     * Enable or disable ads
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<AdManagerConfig>): void;
+    /**
+     * Clear all slot data
+     */
+    clearSlots(): void;
+    /**
+     * Register event listener
+     */
+    on<K extends keyof AdManagerEvents>(event: K, callback: AdManagerEvents[K]): void;
+    /**
+     * Remove event listener
+     */
+    off<K extends keyof AdManagerEvents>(event: K, callback: AdManagerEvents[K]): void;
+    /**
+     * Remove all event listeners
+     */
+    removeAllListeners(event?: string): void;
+    /**
+     * Get current requestId
+     */
+    getCurrentRequestId(): string | null;
+    /**
+     * Get analytics info for a single ad
+     */
+    getAdAnalytics(adId: string): AdAnalyticsInfo | null;
+    /**
+     * Get analytics info for multiple ads
+     */
+    getAdsAnalytics(adIds: string[]): Map<string, AdAnalyticsInfo>;
+    /**
+     * Track ad click using Analytics API
+     */
+    trackAdClick(adId: string, destinationUrl: string, adData?: {
+        title?: string;
+        format?: string;
+        source?: string;
+    }): Promise<ClickResponse | null>;
+    /**
+     * Track ad impression using Analytics API
+     */
+    trackAdImpressionAPI(adId: string, adData?: {
+        title?: string;
+        format?: string;
+        source?: string;
+        viewToken?: string;
+    }): Promise<ImpressionResponse | null>;
+    /**
+     * Destroy the manager and clean up
+     */
+    destroy(): void;
+}
+
+/**
+ * Configuration for AdManager
+ */
+export declare interface AdManagerConfig {
+    /** Base URL for API requests */
+    apiBaseUrl: string;
+    /** API Key for authentication */
+    apiKey?: string;
+    /** Ad slot configurations */
+    slots: AdSlotRequest[];
+    /** Whether ads are enabled */
+    enabled?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+
+/**
+ * Events emitted by AdManager
+ */
+export declare type AdManagerEvents = {
+    'adsUpdated': (slots: Record<string, AdSlotResponse>) => void;
+    'adsLoading': () => void;
+    'adsError': (error: Error) => void;
+    'adClicked': (adId: string, slotId: string) => void;
+    'adImpression': (adId: string, slotId: string) => void;
+};
+
+/**
+ * Ad Request Batch
+ * Request multiple ad slots in one API call
+ */
+export declare interface AdRequestBatch {
+    conversationContext: ConversationContext;
+    userContext?: UserContext;
+    slots: AdSlotRequest[];
+}
+
+/**
+ * Ad Response Batch
+ */
+export declare interface AdResponseBatch {
+    requestId: string;
+    timestamp: number;
+    intent: IntentResult;
+    slots: AdSlotResponse[];
+    globalSuggestions?: GlobalSuggestions;
+    metadata?: ResponseMetadata;
+}
+
+/**
+ * Slot 信息
+ */
+export declare interface AdSlotInfo {
+    ads: any[];
+    count: number;
+    status: string;
+}
+
+/**
+ * Ad Slot Placement Context
+ */
+export declare interface AdSlotPlacement {
+    position: 'above_fold' | 'below_fold' | 'sidebar' | 'inline';
+    context: string;
+}
+
+/**
+ * Ad Slot Preferences
+ */
+export declare interface AdSlotPreferences {
+    maxTitleLength?: number;
+    maxBodyLength?: number;
+    requireImage?: boolean;
+    imageAspectRatio?: string;
+    showPrice?: boolean;
+    showRating?: boolean;
+}
+
+/**
+ * Ad Slot Request
+ * Frontend declares requirements for each ad slot
+ */
+export declare interface AdSlotRequest {
+    slotId: string;
+    slotName: string;
+    format: AdFormat;
+    variant?: string;
+    size: AdSlotSize;
+    count?: number;
+    preferences?: AdSlotPreferences;
+    placement: AdSlotPlacement;
+}
+
+/**
+ * Ad Slot Response
+ */
+export declare interface AdSlotResponse {
+    slotId: string;
+    status: 'filled' | 'no_fill' | 'error';
+    error?: string;
+    ads: AdaptedAdContent[];
+    suggestions?: AdSlotSuggestions;
+    metadata?: SlotDecisionMetadata;
+}
+
+/**
+ * Ad Slot Size Requirements
+ */
+export declare interface AdSlotSize {
+    width: number;
+    height: number;
+    minWidth?: number;
+    maxWidth?: number;
+    aspectRatio?: string;
+}
+
+/**
+ * Ad Slot Suggestions
+ */
+export declare interface AdSlotSuggestions {
+    layout?: 'horizontal' | 'vertical' | 'grid';
+    columns?: number;
+    spacing?: string;
+}
+
+/**
+ * Ad Source Types
+ * Where the ad originates from
+ */
+export declare type AdSource = 'internal' | 'affiliate' | 'programmatic' | 'mock';
+
+/**
+ * Ad Tracking Options
+ */
+export declare interface AdTrackingOptions {
+    intersectionThreshold?: number;
+    minViewTimeMs?: number;
+    onClick?: (ad: KoahAd) => void;
+    onImpression?: (ad: KoahAd) => void;
+}
+
+/**
+ * Analytics 错误类型
+ */
+export declare class AnalyticsError extends Error {
+    code: string;
+    originalError?: unknown | undefined;
+    constructor(message: string, code: string, originalError?: unknown | undefined);
+}
+
+/**
+ * Analytics 发送配置
+ */
+export declare interface AnalyticsSendConfig {
+    baseUrl?: string;
+    timeout?: number;
+    retryAttempts?: number;
+    retryDelay?: number;
+    debug?: boolean;
+}
+
+/**
+ * Analytics 发送器类
+ */
+export declare class AnalyticsSender {
+    private baseUrl;
+    private timeout;
+    private retryAttempts;
+    private retryDelay;
+    private debug;
+    constructor(config?: AnalyticsSendConfig);
+    /**
+     * 发送广告展示事件
+     */
+    trackImpression(data: ImpressionEventData): Promise<ImpressionResponse | null>;
+    /**
+     * 发送广告点击事件
+     */
+    trackClick(data: ClickEventData): Promise<ClickResponse | null>;
+    /**
+     * 通用请求发送方法（带重试）
+     * 自动添加 X-API-Key header
+     */
+    private sendRequest;
+    /**
+     * 延迟辅助方法
+     */
+    private delay;
+}
+
+/**
+ * App Information (injected at build time)
+ */
+export declare interface AppInfo {
+    bundle: string;
+    ver: string;
+    name: string;
+    publisher: {
+        id: string;
+        domain?: string;
+    };
+    cat?: string[];
+}
+
+/**
+ * Badge Style for Entity Links
+ * Controls how affiliate links are visually indicated to users
+ */
+export declare type BadgeStyle = 'hover' | 'subtle' | 'explicit' | 'none';
+
+/**
+ * Chat Completion Request
+ */
+export declare interface ChatCompletionRequest {
+    messages: ChatMessage[];
+    adEnabled?: boolean;
+    adFormats?: AdFormat[];
+    placement?: string;
+    stream?: boolean;
+}
+
+/**
+ * Chat Completion Response
+ */
+export declare interface ChatCompletionResponse {
+    message: ChatMessage;
+    intent?: IntentResult;
+    ads?: KoahAd[];
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+
+/**
+ * Chat Message
+ */
+export declare interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+
+/**
+ * Clear client info cache
+ *
+ * Forces re-collection on next call. Useful when device state changes.
+ */
+export declare function clearClientInfoCache(): void;
+
+/**
+ * 点击事件数据
+ */
+export declare interface ClickEventData {
+    requestId: string;
+    adId: string;
+    sessionId: string;
+    destinationUrl: string;
+    adTitle?: string;
+    slotId?: string;
+    format?: string;
+    source?: string;
+    userId?: string;
+    impressionEventId?: string;
+    timeToClickMs?: number;
+    viewToken?: string;
+}
+
+/**
+ * 点击事件响应
+ */
+export declare interface ClickResponse {
+    success: boolean;
+    eventId: string;
+    redirectUrl: string;
+}
+
+/**
+ * Client Information (auto-collected by SDK)
+ * This complies with OpenRTB 2.5/2.6 specifications
+ */
+export declare interface ClientInfo {
+    device: DeviceInfo;
+    app: AppInfo;
+    user: UserInfo;
+    geo?: GeoInfo;
+    timestamp: number;
+}
+
+export declare class ClientInfoCollector {
+    private static instance;
+    private cachedStaticInfo;
+    private cacheTimestamp;
+    private readonly CACHE_TTL;
+    private inferAppInfo;
+    /**
+     * 自动推断bundle/domain
+     */
+    private inferBundle;
+    /**
+     * 自动推断应用名称
+     */
+    private inferAppName;
+    /**
+     * 自动推断应用版本
+     */
+    private inferAppVersion;
+    /**
+     * 自动推断publisher ID
+     */
+    private inferPublisherId;
+    private constructor();
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): ClientInfoCollector;
+    /**
+     * Collect all available client information
+     * @param options Optional overrides from app
+     * @returns ClientInfo object compliant with OpenRTB 2.5/2.6
+     */
+    collect(options?: ClientInfoOptions): ClientInfo;
+    /**
+     * Collect static device information (cached)
+     * These values don't change during app lifecycle
+     */
+    private collectStaticInfo;
+    /**
+     * Collect dynamic device information (not cached)
+     * These values may change during app lifecycle
+     */
+    private collectDynamicInfo;
+    /**
+     * Collect user information
+     */
+    private collectUserInfo;
+    /**
+     * Collect geographic information (inferred)
+     */
+    private collectGeoInfo;
+    /**
+     * Detect Operating System
+     */
+    private detectOS;
+    /**
+     * Detect OS Version
+     */
+    private detectOSVersion;
+    /**
+     * Detect Device Type (OpenRTB standard)
+     * 0 = Unknown/Other
+     * 1 = Mobile/Phone
+     * 2 = Tablet
+     * 3 = Personal Computer
+     * 4 = Connected TV
+     * 5 = Set Top Box
+     */
+    private detectDeviceType;
+    /**
+     * Detect Device Model
+     */
+    private detectModel;
+    /**
+     * Detect Device Make
+     */
+    private detectMake;
+    /**
+     * Get Network Connection Info
+     */
+    private getConnectionInfo;
+    /**
+     * Map Network Information API type to OpenRTB
+     * 0 = Unknown
+     * 1 = Ethernet
+     * 2 = WiFi
+     * 3 = 2G
+     * 4 = 3G
+     * 5 = 4G
+     * 6 = 5G
+     */
+    private mapConnectionType;
+    /**
+     * Infer country from language and timezone
+     */
+    private inferCountry;
+    /**
+     * Generate UUID v4
+     */
+    private generateUUID;
+    /**
+     * Get fallback info for SSR or restricted environments
+     */
+    private getFallbackInfo;
+    /**
+     * Clear cache (call when device state changes)
+     */
+    clearCache(): void;
+}
+
+/**
+ * Client Info Collection Options
+ * Allows app to override certain fields
+ */
+export declare interface ClientInfoOptions {
+    device?: Partial<DeviceInfo>;
+    app?: Partial<AppInfo>;
+    user?: Partial<UserInfo>;
+    geo?: Partial<GeoInfo>;
+}
+
+/**
+ * Conversation Context
+ */
+export declare interface ConversationContext {
+    query: string;
+    response?: string;
+    intent?: IntentResult;
+    conversationHistory?: ConversationMessage[];
+}
+
+/**
+ * Conversation Message
+ * Individual message in conversation history
+ */
+export declare interface ConversationMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    timestamp?: number;
+}
+
+/**
+ * 创建带配置的 Analytics 实例
+ */
+export declare function createAnalytics(config: AnalyticsSendConfig): {
+    trackImpression: (data: ImpressionEventData) => Promise<ImpressionResponse | null>;
+    trackClick: (data: ClickEventData) => Promise<ClickResponse | null>;
+};
+
+/**
+ * 创建带配置的 Session 实例
+ */
+export declare function createSession(config?: SessionConfig): {
+    getSessionId: () => string;
+    regenerateSessionId: () => string;
+    clearSessionId: () => void;
+};
+
+/**
+ * Decision Result
+ * Complete response from the ad decision engine
+ */
+export declare interface DecisionResult {
+    ads: KoahAd[];
+    intent: IntentResult;
+    routing: RoutingInfo;
+}
+
+/**
+ * Device Information (auto-collected by SDK)
+ */
+export declare interface DeviceInfo {
+    ua: string;
+    os: string;
+    osv: string;
+    devicetype: number;
+    model?: string;
+    make?: string;
+    language: string;
+    connectiontype: number;
+    bandwidth?: number;
+    ip?: string;
+    ifa?: string;
+    lmt?: number;
+    att?: number;
+}
+
+/**
+ * DOM Renderer - Create DOM elements with event binding
+ */
+export declare class DOMRenderer {
+    /**
+     * Render Action Card ad into container
+     */
+    static renderActionCard(ad: AdaptedAdContent, container: HTMLElement, options?: {
+        variant?: 'horizontal' | 'vertical' | 'compact';
+        analytics?: AdAnalyticsInfo;
+        onClick?: (ad: AdaptedAdContent) => void;
+        onImpression?: (ad: AdaptedAdContent) => void;
+    }): HTMLElement;
+    /**
+     * Render Suffix ad into container
+     */
+    static renderSuffixAd(ad: AdaptedAdContent, container: HTMLElement, options?: {
+        variant?: 'block' | 'inline' | 'minimal';
+        analytics?: AdAnalyticsInfo;
+        onClick?: (ad: AdaptedAdContent) => void;
+        onImpression?: (ad: AdaptedAdContent) => void;
+    }): HTMLElement;
+    /**
+     * Render Sponsored Source ad into container
+     */
+    static renderSponsoredSource(ad: AdaptedAdContent, container: HTMLElement, options?: {
+        variant?: 'card' | 'list-item' | 'minimal';
+        analytics?: AdAnalyticsInfo;
+        onClick?: (ad: AdaptedAdContent) => void;
+        onImpression?: (ad: AdaptedAdContent) => void;
+    }): HTMLElement;
+    /**
+     * Render Lead Gen ad into container
+     */
+    static renderLeadGenAd(ad: AdaptedAdContent, container: HTMLElement, options?: {
+        analytics?: AdAnalyticsInfo;
+        onClick?: (ad: AdaptedAdContent) => void;
+        onImpression?: (ad: AdaptedAdContent) => void;
+    }): HTMLElement;
+    /**
+     * Render multiple ads into container
+     */
+    static renderAds(ads: AdaptedAdContent[], container: HTMLElement, renderFn?: (ad: AdaptedAdContent, container: HTMLElement, options?: any) => void, options?: any): HTMLElement;
+    /**
+     * Handle ad click
+     * First tracks the click (async, non-blocking), then opens the URL.
+     */
+    private static handleClick;
+    /**
+     * Track ad impression using IntersectionObserver (50% visible + 1000ms delay)
+     * Falls back to immediate tracking if IntersectionObserver is unavailable.
+     */
+    private static trackImpression;
+    /**
+     * Generate HTML for Suffix Ad variants
+     */
+    private static generateSuffixAdHTML;
+    /**
+     * Generate HTML for Sponsored Source Ad variants
+     */
+    private static generateSponsoredSourceHTML;
+}
+
+/**
+ * Enhanced Content Props
+ * Props for the EnhancedContent component
+ */
+export declare interface EnhancedContentProps {
+    /** Original content text */
+    content: string;
+    /** Enhancement configuration */
+    enhancements: EnhancementOptions;
+    /** Custom class name */
+    className?: string;
+    /** Callback when entity link is clicked */
+    onEntityClick?: (entity: EntityInfo) => void;
+}
+
+/**
+ * Enhanced Entity Fragment
+ * Represents a single entity with its enhanced HTML and tracking data
+ */
+export declare interface EnhancedEntityFragment {
+    /** Original entity text (for replacement) */
+    originalText: string;
+    /** Enhanced HTML with tracking attributes */
+    enhancedHTML: string;
+    /** Entity information */
+    entity: EntityInfo;
+    /** Link replacement information */
+    replacement: LinkReplacement;
+    /** Tracking parameters */
+    tracking: {
+        /** Ad ID */
+        adId: string;
+        /** Request ID from useAiAds */
+        requestId: string;
+        /** Slot ID */
+        slotId: string;
+        /** Position in entities array */
+        position: number;
+        /** Unique entity ID for tracking */
+        entityId: string;
+    };
+}
+
+/**
+ * Options for enhancing entity fragments
+ */
+export declare interface EnhanceFragmentsOptions {
+    /** Ad ID */
+    adId: string;
+    /** Request ID */
+    requestId: string;
+    /** Slot ID */
+    slotId: string;
+    /** Badge style for visual indicator */
+    badgeStyle?: BadgeStyle;
+    /** Minimum confidence threshold (default: 0.7) */
+    minConfidence?: number;
+}
+
+/**
+ * Enhancement Options
+ * Configuration options for content enhancement
+ */
+export declare interface EnhancementOptions {
+    /** List of entities to enhance */
+    entities: EntityInfo[];
+    /** Link replacements for entities */
+    replacements: LinkReplacement[];
+    /** Maximum number of links to add (default: 5) */
+    maxLinks?: number;
+    /** Minimum confidence threshold (default: 0.7) */
+    minConfidence?: number;
+    /** Visual badge style (default: 'subtle') */
+    badgeStyle?: BadgeStyle;
+    /** How to handle overlapping entities (default: 'longest') */
+    overlapStrategy?: OverlapStrategy;
+}
+
+/**
+ * Entity Information (Frontend)
+ * Matches backend EntityInfo structure
+ */
+export declare interface EntityInfo {
+    /** The exact text of the entity in the original content */
+    text: string;
+    /** Starting position in the original text (0-based) */
+    startPosition: number;
+    /** Ending position in the original text (exclusive) */
+    endPosition: number;
+    /** Type of the entity */
+    type: EntityType;
+    /** Confidence score from 0 to 1 */
+    confidence: number;
+    /** Product category (optional, inferred from context) */
+    category?: string;
+    /** Brand name (optional, if entity is a product) */
+    brand?: string;
+    /** Normalized entity name for matching */
+    normalizedName?: string;
+}
+
+/**
+ * Entity Link Enhancement Content (Frontend)
+ * Content enhancement with entity-linked affiliate URLs
+ * Matches backend EntityLinkAdContent structure
+ */
+export declare interface EntityLinkAdContent {
+    /** Original text before enhancement */
+    originalText: string;
+    /** Processed text with entity links */
+    processedText: string;
+    /** List of all recognized entities */
+    entities: EntityInfo[];
+    /** List of applied link replacements */
+    replacements: LinkReplacement[];
+    /** Processing metadata */
+    metadata: {
+        /** Processing time in milliseconds */
+        processingTime: number;
+        /** Total number of entities recognized */
+        entityCount: number;
+        /** Number of entities successfully linked */
+        linkCount: number;
+        /** NER method used ('llm' | 'ner_model') */
+        nerMethod: 'llm' | 'ner_model';
+        /** Average confidence score */
+        avgConfidence: number;
+    };
+}
+
+/**
+ * Entity Type for NER
+ * Types of entities that can be recognized and enhanced
+ */
+export declare type EntityType = 'product' | 'brand' | 'service' | 'category';
+
+/**
+ * Extended Ad Request Batch with Client Info
+ */
+export declare interface ExtendedAdRequestBatch extends AdRequestBatch {
+    clientInfo: ClientInfo;
+}
+
+/**
+ * fetchAds - Unified ad fetching interface
+ *
+ * Supports all stages (pre-request and post-response) with intelligent decision making.
+ * The backend automatically detects the stage and returns appropriate ad formats based on context completeness.
+ * Automatically injects client information for OpenRTB compliance.
+ *
+ * @param params - Ad request parameters
+ * @param options - Additional options (apiBaseUrl, apiKey, etc.)
+ * @returns Promise resolving to ad response batch
+ */
+export declare function fetchAds(params: {
+    conversationContext: ConversationContext;
+    userContext?: UserContext;
+    slots: AdSlotRequest[];
+}, options?: {
+    apiBaseUrl?: string;
+    apiKey?: string;
+}): Promise<AdResponseBatch>;
+
+/**
+ * Follow-up Ad Content
+ * Ad mixed into suggested questions
+ */
+export declare interface FollowUpAdContent {
+    question_text: string;
+    is_ad: boolean;
+    ad_destination?: string;
+    icon?: string;
+}
+
+/**
+ * Follow-up Ad Variant
+ */
+export declare type FollowUpVariant = 'bubble' | 'pill' | 'underline';
+
+/**
+ * 生成 View Token（用于展示去重）
+ */
+export declare function generateViewToken(adId: string, sessionId: string): string;
+
+/**
+ * Geographic Information (inferred)
+ */
+export declare interface GeoInfo {
+    country?: string;
+    timezone?: string;
+    lat?: number;
+    lon?: number;
+    region?: string;
+    city?: string;
+}
+
+/**
+ * Get app information only
+ */
+export declare function getAppInfo(): AppInfo;
+
+/**
+ * Get current client information (convenience function)
+ *
+ * This is a shortcut for getClientInfoCollector().collect()
+ *
+ * @param options - Optional custom options
+ * @returns Complete client information
+ */
+export declare function getClientInfo(options?: ClientInfoOptions): ClientInfo;
+
+export declare const getClientInfoCollector: () => ClientInfoCollector;
+
+/**
+ * Get client info as JSON string
+ *
+ * Useful for logging or sending to APIs
+ */
+export declare function getClientInfoJSON(options?: ClientInfoOptions): string;
+
+/**
+ * Get client info summary (human-readable)
+ *
+ * Returns a simplified summary for debugging/display
+ */
+export declare function getClientInfoSummary(): string;
+
+/**
+ * Get device information only
+ */
+export declare function getDeviceInfo(): DeviceInfo;
+
+/**
+ * Get geo information only
+ */
+export declare function getGeoInfo(): GeoInfo | undefined;
+
+/**
+ * 获取 Session ID（便捷方法）
+ */
+export declare const getSessionId: () => string;
+
+/**
+ * Get user ID (persistent across sessions)
+ */
+export declare function getUserId(): string;
+
+/**
+ * Get user information only
+ */
+export declare function getUserInfo(): UserInfo;
+
+/**
+ * Get or create the viewability tracker singleton
+ */
+export declare function getViewabilityTracker(config?: ViewabilityConfig, baseUrl?: string): ViewabilityTracker;
+
+/**
+ * Global Suggestions
+ */
+export declare interface GlobalSuggestions {
+    priority?: string[];
+    hideIfNoFill?: string[];
+}
+
+/**
+ * HTML Renderer - Generate ad HTML strings
+ * CSS class names use ax-ad-* namespace
+ */
+export declare class HTMLRenderer {
+    /**
+     * Render Action Card ad as HTML string
+     *
+     * @param ad - Adapted ad content
+     * @param options - Rendering options
+     * @returns HTML string
+     */
+    static renderActionCard(ad: AdaptedAdContent, options?: {
+        variant?: 'horizontal' | 'vertical' | 'compact';
+        includeWrapper?: boolean;
+    }): string;
+    /**
+     * Render Suffix ad as HTML string
+     *
+     * @param ad - Adapted ad content
+     * @returns HTML string
+     */
+    static renderSuffixAd(ad: AdaptedAdContent): string;
+    /**
+     * Render Sponsored Source ad as HTML string
+     *
+     * @param ad - Adapted ad content
+     * @returns HTML string
+     */
+    static renderSponsoredSource(ad: AdaptedAdContent): string;
+    /**
+     * Render Lead Gen ad as HTML string
+     *
+     * @param ad - Adapted ad content
+     * @returns HTML string
+     */
+    static renderLeadGenAd(ad: AdaptedAdContent): string;
+    /**
+     * Render multiple ads
+     *
+     * @param ads - Array of adapted ads
+     * @param renderFn - Render function to use
+     * @returns HTML string with all ads
+     */
+    static renderAds(ads: AdaptedAdContent[], renderFn?: (ad: AdaptedAdContent) => string): string;
+}
+
+/**
+ * Analytics API 事件类型定义
+ *
+ * 用于 Frontend SDK 与 Backend Analytics API 的交互
+ * 兼容 React SDK 和 Universal SDK
+ */
+/**
+ * 展示事件数据
+ */
+export declare interface ImpressionEventData {
+    requestId: string;
+    adId: string;
+    position: number;
+    totalAds: number;
+    sessionId: string;
+    adTitle?: string;
+    slotId?: string;
+    format?: string;
+    source?: string;
+    userId?: string;
+    viewToken?: string;
+}
+
+/**
+ * 展示事件响应
+ */
+export declare interface ImpressionResponse {
+    success: boolean;
+    eventId: string;
+    impressionId: string;
+}
+
+/**
+ * Intent Recognition Result
+ * Represents the output of intent analysis
+ */
+export declare interface IntentResult {
+    type: IntentType;
+    confidence: number;
+    keywords: string[];
+    reasoning?: string;
+}
+
+/**
+ * Intent Type Enumeration
+ * Defines the primary intent categories for ad targeting
+ */
+export declare enum IntentType {
+    SHOPPING = "shopping",
+    LEAD_GEN = "lead_gen",
+    SOFTWARE = "software",
+    CONTENT = "content",
+    GENERIC = "generic"
+}
+
+/**
+ * Standardized Koah Ad Format
+ * All adapters normalize to this format
+ */
+export declare interface KoahAd {
+    id: string;
+    type: AdFormat;
+    score: number;
+    source: AdSource;
+    content: {
+        title: string;
+        body: string;
+        image?: string;
+        cta_text?: string;
+        rating?: number;
+        price?: string;
+        brand?: string;
+        suffix_content?: SuffixAdContent;
+        followup_content?: FollowUpAdContent;
+        source_content?: SponsoredSourceContent;
+        entity_link_content?: EntityLinkAdContent;
+    };
+    tracking: {
+        click_url: string;
+        impression_url: string;
+    };
+    metadata?: {
+        original_source?: string;
+        category?: string;
+        ecpm?: number;
+        [key: string]: any;
+    };
+    /** Enhanced entity fragments (Mode A) - only for entity_link type */
+    enhancedFragments?: EnhancedEntityFragment[];
+}
+
+/**
+ * Link Replacement
+ * Represents a link replacement for an entity or existing URL
+ */
+export declare interface LinkReplacement {
+    /** The original text to be replaced/linked */
+    originalText: string;
+    /** Original URL if the text already had a link */
+    originalUrl?: string;
+    /** The affiliate URL to replace with */
+    affiliateUrl: string;
+    /** Associated entity information */
+    entity?: EntityInfo;
+    /** Unique tracking ID for this replacement */
+    trackingId: string;
+    /** Affiliate network identifier */
+    affiliateNetwork: 'amazon' | 'wildfire' | 'other';
+    /** Commission rate (optional, for analytics) */
+    commissionRate?: number;
+    /** Product price (optional, for display) */
+    price?: string;
+}
+
+/**
+ * Overlap Strategy
+ * How to handle overlapping entity mentions
+ */
+export declare type OverlapStrategy = 'longest' | 'first' | 'all';
+
+/**
+ * Placement Types
+ * Where ads can be displayed in the UI
+ */
+export declare type PlacementType = RequestContext['placement'];
+
+/**
+ * Request Context for Ad Decision
+ */
+export declare interface RequestContext {
+    query: string;
+    response?: string;
+    adFormats: AdFormat[];
+    placement: 'post_response' | 'sidebar' | 'empty_state' | 'inline';
+}
+
+/**
+ * Response Metadata
+ * Provides transparency about the decision process
+ */
+export declare interface ResponseMetadata {
+    detectedStage: 'pre_request' | 'post_response' | 'unknown';
+    availableContext: {
+        hasQuery: boolean;
+        hasResponse: boolean;
+        hasHistory: boolean;
+        hasProfile: boolean;
+        historyLength?: number;
+    };
+    reasoning?: string;
+}
+
+/**
+ * Routing Information
+ * Tracks the decision process
+ */
+export declare interface RoutingInfo {
+    primarySource: string;
+    fallbackTriggered: boolean;
+    log: RoutingLogEntry[];
+}
+
+/**
+ * Routing Log Entry
+ * Individual routing attempt log
+ */
+export declare interface RoutingLogEntry {
+    strategy: string;
+    adapter: string;
+    adsFound: number;
+    status: 'success' | 'no_fill' | 'error';
+    error?: string;
+    timestamp?: number;
+}
+
+export declare const SDK_VERSION = "0.1.0";
+
+/**
+ * Session 管理配置
+ */
+export declare interface SessionConfig {
+    sessionKey?: string;
+    storage?: 'sessionStorage' | 'memory';
+}
+
+/**
+ * Session 管理器
+ */
+export declare class SessionManager {
+    private sessionKey;
+    private storage;
+    private memoryCache;
+    constructor(config?: SessionConfig);
+    /**
+     * 获取 Session ID
+     */
+    getSessionId(): string;
+    /**
+     * 重新生成 Session ID
+     */
+    regenerateSessionId(): string;
+    /**
+     * 生成新的 Session ID
+     */
+    private generateSessionId;
+    /**
+     * 清除 Session ID
+     */
+    clearSessionId(): void;
+}
+
+/**
+ * Slot Decision Metadata
+ * Per-slot decision reasoning and suggestions
+ */
+export declare interface SlotDecisionMetadata {
+    reasoning?: Array<{
+        reason: string;
+        confidence: number;
+    }>;
+    suggestions?: {
+        layout?: string;
+        variant?: string;
+        position?: number;
+        timing?: {
+            showAfter?: number;
+            requiresInterest?: string[];
+        };
+        tone?: 'casual' | 'professional' | 'friendly' | 'technical';
+    };
+}
+
+/**
+ * Source Ad Variant
+ */
+export declare type SourceVariant = 'card' | 'list-item' | 'minimal';
+
+/**
+ * Sponsored Source Content
+ * Ad mixed into citation list
+ */
+export declare interface SponsoredSourceContent {
+    source_name: string;
+    source_url: string;
+    favicon?: string;
+    snippet?: string;
+    is_ad: boolean;
+    ad_destination?: string;
+}
+
+/**
+ * Suffix Ad Content
+ * Text appended after AI response
+ */
+export declare interface SuffixAdContent {
+    prefix: string;
+    text: string;
+    product_name: string;
+    cta_text?: string;
+    cta_url?: string;
+}
+
+/**
+ * TextWeaver Template
+ */
+export declare interface SuffixTemplate {
+    id: string;
+    template: string;
+    emoji: string;
+    tone: 'casual' | 'professional' | 'enthusiastic';
+}
+
+/**
+ * Suffix Ad Variant
+ */
+export declare type SuffixVariant = 'inline' | 'block' | 'minimal';
+
+/**
+ * 发送广告点击事件（便捷方法）
+ */
+export declare const trackAdClick: (data: ClickEventData) => Promise<ClickResponse | null>;
+
+/**
+ * 发送广告展示事件（便捷方法）
+ */
+export declare const trackAdImpression: (data: ImpressionEventData) => Promise<ImpressionResponse | null>;
+
+/**
+ * 批量发送点击事件
+ */
+export declare function trackClicksBatch(events: ClickEventData[]): Promise<(ClickResponse | null)[]>;
+
+/**
+ * 批量发送展示事件
+ */
+export declare function trackImpressionsBatch(events: ImpressionEventData[]): Promise<(ImpressionResponse | null)[]>;
+
+/**
+ * useAdSlots Hook Options
+ */
+export declare interface UseAdSlotsOptions {
+    apiBaseUrl?: string;
+    apiKey?: string;
+    slots: AdSlotRequest[];
+    enabled?: boolean;
+}
+
+/**
+ * useAdSlots Hook Return
+ */
+export declare interface UseAdSlotsResult {
+    slots: Record<string, AdSlotResponse>;
+    isLoading: boolean;
+    error: Error | null;
+    requestAds: (context: {
+        conversationContext: ConversationContext;
+        userContext?: UserContext;
+    }) => Promise<void>;
+    clearSlots: () => void;
+}
+
+/**
+ * User Context
+ */
+export declare interface UserContext {
+    userId?: string;
+    sessionId: string;
+    demographics?: UserDemographics;
+    profile?: UserProfile;
+}
+
+/**
+ * User Demographics
+ */
+export declare interface UserDemographics {
+    country?: string;
+    language?: string;
+}
+
+/**
+ * User Information (basic)
+ */
+export declare interface UserInfo {
+    id: string;
+    language: string;
+    buyeruid?: string;
+}
+
+/**
+ * User Profile
+ * User interests and behavior patterns (optional, for personalization)
+ */
+export declare interface UserProfile {
+    interests?: string[];
+    behavior?: {
+        preferredTopics?: string[];
+        interactionStyle?: 'concise' | 'detailed' | 'technical' | 'casual';
+        avgSessionLength?: number;
+    };
+    purchaseIntent?: {
+        categories?: string[];
+        priceRange?: string;
+        timeline?: 'immediate' | 'within_week' | 'within_month' | 'researching';
+    };
+}
+
+export declare interface ViewabilityConfig {
+    /** Minimum visible percentage to consider "in view" (default: 50) */
+    minVisiblePercentage?: number;
+    /** Minimum duration in ms to consider "viewable" (default: 1000) */
+    minViewableDuration?: number;
+    /** Maximum tracking duration in ms (default: 60000 = 1 minute) */
+    maxTrackingDuration?: number;
+    /** Batch events before sending (default: 5 events or 10 seconds) */
+    batchConfig?: {
+        maxBatchSize?: number;
+        maxBatchWaitMs?: number;
+    };
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+
+export declare interface ViewabilityEventData {
+    adId: string;
+    sessionId: string;
+    requestId?: string;
+    viewToken?: string;
+    eventType: ViewabilityEventType;
+    visiblePercentage: number;
+    maxVisiblePercentage: number;
+    totalVisibleTimeMs: number;
+    isViewable: boolean;
+    viewportWidth?: number;
+    viewportHeight?: number;
+    elementWidth?: number;
+    elementHeight?: number;
+    positionX?: number;
+    positionY?: number;
+    timestamp: number;
+}
+
+/**
+ * Viewability Tracking Module (IAB/MRC Compliant)
+ *
+ * IAB/MRC Standard:
+ * - Viewable: >50% of ad pixels in view for >1 second
+ * - Uses IntersectionObserver API for efficient tracking
+ *
+ * Event-driven approach: Only sends data on state changes, not periodic sampling
+ */
+export declare type ViewabilityEventType = 'enter_viewport' | 'become_viewable' | 'update_viewability' | 'exit_viewport' | 'end_tracking';
+
+export declare interface ViewabilityMetrics {
+    /** Current visible percentage (0-100) */
+    visiblePercentage: number;
+    /** Maximum visible percentage observed */
+    maxVisiblePercentage: number;
+    /** Total time visible in ms */
+    totalVisibleTimeMs: number;
+    /** Current continuous visible time in ms */
+    currentVisibleTimeMs: number;
+    /** Whether meets IAB/MRC viewable criteria */
+    isViewable: boolean;
+    /** Time when became viewable (null if not viewable yet) */
+    viewableAt: number | null;
+    /** Time when entered viewport (null if never entered) */
+    enteredViewportAt: number | null;
+    /** Total number of times entered viewport */
+    enterCount: number;
+}
+
+/**
+ * ViewabilityTracker class for tracking ad viewability
+ * Event-driven: Only sends data on state changes
+ */
+export declare class ViewabilityTracker {
+    private observers;
+    private metrics;
+    private timers;
+    private batchTimers;
+    private eventQueue;
+    private config;
+    private baseUrl;
+    private isTracking;
+    constructor(config?: ViewabilityConfig, baseUrl?: string);
+    /**
+     * Start tracking viewability for an ad element
+     */
+    startTracking(adId: string, element: HTMLElement, sessionId: string, requestId?: string, viewToken?: string): void;
+    /**
+     * Stop tracking an ad element
+     */
+    stopTracking(adId: string): void;
+    /**
+     * Get current metrics for an ad
+     */
+    getMetrics(adId: string): ViewabilityMetrics | undefined;
+    /**
+     * Handle IntersectionObserver callback
+     * Event-driven: Only process when state actually changes
+     */
+    private handleIntersection;
+    /**
+     * Start monitoring loop for tracking duration
+     * Runs every 100ms to track continuous visible time
+     */
+    private startMonitoring;
+    /**
+     * Queue an event to be sent (batched)
+     */
+    private queueEvent;
+    /**
+     * Flush the event queue and send to server
+     */
+    private flushQueue;
+    /**
+     * End tracking and send final metrics
+     */
+    private endTracking;
+    /**
+     * Cleanup resources for an ad
+     */
+    private cleanup;
+    /**
+     * Create thresholds for IntersectionObserver
+     */
+    private createThresholds;
+    /**
+     * Stop all tracking
+     */
+    stopAll(): void;
+    /**
+     * Debug logging
+     */
+    private log;
+    /**
+     * Send any pending events before page unload
+     */
+    setupBeforeUnload(): void;
+}
+
+export { }