@ai-ad-network/frontend-sdk 1.0.8 → 1.0.9

package/dist/client-info/collector.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Client Information Collector
+ *
+ * Automatically collects OpenRTB-compliant device and app information
+ * following OpenRTB 2.5/2.6 specifications.
+ *
+ * Features:
+ * - Static info caching (UA, OS, device type) - collected once
+ * - Dynamic info collection (connection type, bandwidth) - collected each time
+ * - Privacy-compliant (no permissions required for basic info)
+ * - Optional overrides for app-provided data (IDFA, location, etc.)
+ */
+import { ClientInfo, ClientInfoOptions } from '../types';
+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;
+}
+export declare const getClientInfoCollector: () => ClientInfoCollector;

package/dist/client-info/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Client Information Collection Module
+ *
+ * Automatically collects OpenRTB-compliant device and app information
+ *
+ * @example
+ * ```typescript
+ * import { getClientInfo } from '@ai-ad-network/frontend-sdk';
+ *
+ * // Get current client info
+ * const clientInfo = getClientInfo();
+ * console.log(clientInfo.device.os); // "macOS"
+ * console.log(clientInfo.user.id); // "uuid-xxx-xxx"
+ *
+ * // Get with custom options
+ * const customInfo = getClientInfo({ customUserId: 'user-123' });
+ * ```
+ */
+export { ClientInfoCollector, getClientInfoCollector } from './collector';
+export { getClientInfo, getDeviceInfo, getUserInfo, getAppInfo, getGeoInfo, getUserId, clearClientInfoCache, getClientInfoJSON, getClientInfoSummary, } from './utils';
+export type { DeviceInfo, AppInfo, UserInfo, GeoInfo, ClientInfo, ClientInfoOptions, } from '../types';

package/dist/client-info/utils.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Client Info Utility Functions
+ *
+ * Convenience functions for easy access to client information
+ */
+import type { ClientInfo, ClientInfoOptions } from '../types';
+/**
+ * Get current client information (convenience function)
+ *
+ * This is a shortcut for getClientInfoCollector().collect()
+ *
+ * @param options - Optional custom options
+ * @returns Complete client information
+ *
+ * @example
+ * ```typescript
+ * import { getClientInfo } from '@ai-ad-network/frontend-sdk';
+ *
+ * // Get all client info
+ * const info = getClientInfo();
+ * console.log(info.device.os); // "macOS"
+ * console.log(info.user.id); // "uuid-xxx-xxx"
+ *
+ * // Get with custom user ID
+ * const customInfo = getClientInfo({ customUserId: 'user-123' });
+ * ```
+ */
+export declare function getClientInfo(options?: ClientInfoOptions): ClientInfo;
+/**
+ * Get device information only
+ *
+ * @example
+ * ```typescript
+ * import { getDeviceInfo } from '@ai-ad-network/frontend-sdk';
+ *
+ * const device = getDeviceInfo();
+ * console.log(device.os); // "macOS"
+ * console.log(device.model); // "Mac"
+ * ```
+ */
+export declare function getDeviceInfo(): import(".").DeviceInfo;
+/**
+ * Get user information only
+ *
+ * @example
+ * ```typescript
+ * import { getUserInfo } from '@ai-ad-network/frontend-sdk';
+ *
+ * const user = getUserInfo();
+ * console.log(user.id); // "uuid-xxx-xxx"
+ * ```
+ */
+export declare function getUserInfo(): import(".").UserInfo;
+/**
+ * Get app information only
+ *
+ * @example
+ * ```typescript
+ * import { getAppInfo } from '@ai-ad-network/frontend-sdk';
+ *
+ * const app = getAppInfo();
+ * console.log(app.name); // "My App"
+ * console.log(app.bundle); // "example.com"
+ * ```
+ */
+export declare function getAppInfo(): import(".").AppInfo;
+/**
+ * Get geo information only
+ *
+ * @example
+ * ```typescript
+ * import { getGeoInfo } from '@ai-ad-network/frontend-sdk';
+ *
+ * const geo = getGeoInfo();
+ * console.log(geo?.country); // "CN"
+ * console.log(geo?.language); // "zh"
+ * ```
+ */
+export declare function getGeoInfo(): import(".").GeoInfo | undefined;
+/**
+ * Get user ID (persistent across sessions)
+ *
+ * This is a convenience function to quickly get the user ID
+ * without accessing the full client info object.
+ *
+ * @example
+ * ```typescript
+ * import { getUserId } from '@ai-ad-network/frontend-sdk';
+ *
+ * const userId = getUserId();
+ * console.log(userId); // "uuid-xxx-xxx"
+ *
+ * // Send to your analytics
+ * analytics.identify(userId);
+ * ```
+ */
+export declare function getUserId(): string;
+/**
+ * Clear client info cache
+ *
+ * Forces re-collection on next call. Useful when device state changes.
+ *
+ * @example
+ * ```typescript
+ * import { clearClientInfoCache } from '@ai-ad-network/frontend-sdk';
+ *
+ * // Clear cache (e.g., after network change)
+ * clearClientInfoCache();
+ *
+ * // Next call will re-collect fresh data
+ * const freshInfo = getClientInfo();
+ * ```
+ */
+export declare function clearClientInfoCache(): void;
+/**
+ * Get client info as JSON string
+ *
+ * Useful for logging or sending to APIs
+ *
+ * @example
+ * ```typescript
+ * import { getClientInfoJSON } from '@ai-ad-network/frontend-sdk';
+ *
+ * const json = getClientInfoJSON();
+ * console.log(json);
+ * // {"device":{"os":"macOS",...},"user":{"id":"xxx"},...}
+ *
+ * // Send to server
+ * fetch('/api/log', {
+ *   method: 'POST',
+ *   body: json,
+ *   headers: { 'Content-Type': 'application/json' }
+ * });
+ * ```
+ */
+export declare function getClientInfoJSON(options?: ClientInfoOptions): string;
+/**
+ * Get client info summary (human-readable)
+ *
+ * Returns a simplified summary for debugging/display
+ *
+ * @example
+ * ```typescript
+ * import { getClientInfoSummary } from '@ai-ad-network/frontend-sdk';
+ *
+ * const summary = getClientInfoSummary();
+ * console.log(summary);
+ * // macOS 14.5 / Chrome / user-123 / CN
+ * ```
+ */
+export declare function getClientInfoSummary(): string;

package/dist/components/ActionCardAd.d.ts

@@ -0,0 +1,26 @@
+import type { KoahAd, ActionCardVariant } from '@/types';
+/**
+ * ActionCardAd Props
+ */
+export interface ActionCardAdProps {
+    /** The ad data to display */
+    ad: KoahAd;
+    /** Visual variant */
+    variant?: ActionCardVariant;
+    /** Custom class name */
+    className?: string;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Tracking options */
+    onClick?: () => void;
+    onImpression?: () => void;
+}
+/**
+ * ActionCardAd - Rich media card component with modern glassmorphism design
+ *
+ * @example
+ * ```tsx
+ * <ActionCardAd ad={ad} variant="horizontal" />
+ * ```
+ */
+export declare function ActionCardAd({ ad, variant, className, isLoading, onClick, onImpression, }: ActionCardAdProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/AdAnalytics.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Ad Metrics Data Structure
+ */
+export interface AdMetrics {
+    adId: string;
+    adTitle: string;
+    impressions: number;
+    clicks: number;
+    ctr: number;
+    revenue: number;
+    source: 'internal' | 'affiliate' | 'programmatic';
+    lastUpdated: Date;
+}
+/**
+ * Aggregated Metrics
+ */
+export interface AggregatedMetrics {
+    totalImpressions: number;
+    totalClicks: number;
+    averageCtr: number;
+    totalRevenue: number;
+    topPerformingAd: AdMetrics | null;
+    bySource: Record<string, {
+        impressions: number;
+        clicks: number;
+        revenue: number;
+    }>;
+}
+/**
+ * AdAnalyticsDashboard Props
+ */
+export interface AdAnalyticsDashboardProps {
+    /** Initial metrics data */
+    data?: AdMetrics[];
+    /** Auto-refresh interval in ms */
+    refreshInterval?: number;
+    /** Callback to fetch fresh data */
+    onRefresh?: () => Promise<AdMetrics[]>;
+    /** Show/hide sections */
+    showRevenue?: boolean;
+    showBySource?: boolean;
+    /** Custom class name */
+    className?: string;
+}
+/**
+ * AdAnalyticsDashboard - Modern analytics dashboard with glassmorphism design
+ *
+ * @example
+ * ```tsx
+ * <AdAnalyticsDashboard
+ *   data={metricsData}
+ *   refreshInterval={30000}
+ *   onRefresh={async () => await fetchMetrics()}
+ * />
+ * ```
+ */
+export declare function AdAnalyticsDashboard({ data: initialData, refreshInterval, onRefresh, showRevenue, showBySource, className, }: AdAnalyticsDashboardProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * MiniDashboard - Compact version with modern design
+ */
+export interface MiniDashboardProps {
+    data?: AdMetrics[];
+    className?: string;
+}
+export declare function MiniDashboard({ data, className }: MiniDashboardProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/AdErrorBoundary.d.ts

@@ -0,0 +1,86 @@
+import React, { Component, ReactNode } from 'react';
+/**
+ * Error Boundary Props
+ */
+export interface AdErrorBoundaryProps {
+    /** Child components */
+    children: ReactNode;
+    /** Fallback component when error occurs */
+    fallback?: ReactNode | ((error: Error, errorInfo: React.ErrorInfo) => ReactNode);
+    /** Custom class name for error container */
+    className?: string;
+    /** Callback when error occurs */
+    onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+}
+/**
+ * Error Boundary State
+ */
+interface AdErrorBoundaryState {
+    hasError: boolean;
+    error?: Error;
+}
+/**
+ * AdErrorBoundary - Error boundary for ad components
+ *
+ * Catches JavaScript errors in ad components and displays a fallback UI.
+ *
+ * @example
+ * ```tsx
+ * <AdErrorBoundary
+ *   fallback={<CustomErrorFallback />}
+ *   onError={(error, errorInfo) => console.error('Ad error:', error)}
+ * >
+ *   <ActionCardAd ad={ad} />
+ * </AdErrorBoundary>
+ * ```
+ */
+export declare class AdErrorBoundary extends Component<AdErrorBoundaryProps, AdErrorBoundaryState> {
+    constructor(props: AdErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): AdErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
+    render(): string | number | boolean | Iterable<React.ReactNode> | import("react/jsx-runtime").JSX.Element | null | undefined;
+}
+/**
+ * withAdErrorBoundary - HOC to wrap components with error boundary
+ *
+ * @example
+ * ```tsx
+ * const SafeActionCard = withAdErrorBoundary(ActionCardAd, {
+ *   fallback: <CustomErrorFallback />,
+ * });
+ * ```
+ */
+export declare function withAdErrorBoundary<P extends object>(Component: React.ComponentType<P>, errorBoundaryProps?: Omit<AdErrorBoundaryProps, 'children'>): {
+    (props: P): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/**
+ * AdErrorHandler - Component to handle errors in ad hooks
+ */
+export interface AdErrorHandlerProps {
+    /** Error object */
+    error: Error | null;
+    /** Retry callback */
+    onRetry?: () => void;
+    /** Custom class name */
+    className?: string;
+    /** Hide error message */
+    silent?: boolean;
+}
+/**
+ * AdErrorHandler - Display error message with retry option
+ *
+ * @example
+ * ```tsx
+ * const { ads, error, refetch } = useAiAds(...);
+ *
+ * {error && (
+ *   <AdErrorHandler
+ *     error={error}
+ *     onRetry={() => refetch()}
+ *   />
+ * )}
+ * ```
+ */
+export declare function AdErrorHandler({ error, onRetry, className, silent }: AdErrorHandlerProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/AdProvider.d.ts

@@ -0,0 +1,121 @@
+import React, { ReactNode } from 'react';
+/**
+ * Ad Configuration Options
+ */
+export interface AdConfig {
+    /** Base URL for API requests */
+    apiBaseUrl?: string;
+    /** API Key for authentication (format: ak_tenant_key) */
+    apiKey?: string;
+    /** Default ad formats to request */
+    defaultFormats?: string[];
+    /** Default placement */
+    defaultPlacement?: 'post_response' | 'sidebar' | 'empty_state' | 'inline';
+    /** Enable/disable ads globally */
+    enabled?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom headers for API requests */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Maximum retry attempts */
+    maxRetries?: number;
+    /** User ID for tracking (hashed automatically) */
+    userId?: string;
+}
+/**
+ * Ad Context Type
+ */
+interface AdContextType {
+    config: AdConfig;
+    updateConfig: (updates: Partial<AdConfig>) => void;
+    resetConfig: () => void;
+}
+/**
+ * AdProvider Props
+ */
+export interface AdProviderProps {
+    /** Configuration options */
+    config?: Partial<AdConfig>;
+    /** Child components */
+    children: ReactNode;
+    /** Initial configuration (merged with defaults) */
+    initialConfig?: AdConfig;
+}
+/**
+ * AdProvider - Provider component for ad SDK configuration
+ *
+ * Wrap your app with this provider to configure the ad SDK globally.
+ *
+ * @example
+ * ```tsx
+ * import { AdProvider } from '@ai-ad-network/frontend-sdk';
+ *
+ * function App() {
+ *   return (
+ *     <AdProvider
+ *       config={{
+ *         apiBaseUrl: 'https://api.example.com/v1',
+ *         apiKey: 'ak_your_tenant_your_key',
+ *         enabled: true,
+ *         debug: process.env.NODE_ENV === 'development',
+ *       }}
+ *     >
+ *       <YourApp />
+ *     </AdProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function AdProvider({ config: configProp, initialConfig, children }: AdProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * useAdConfig - Hook to access ad configuration
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { config, updateConfig } = useAdConfig();
+ *
+ *   return (
+ *     <div>
+ *       <p>Ads enabled: {config.enabled}</p>
+ *       <button onClick={() => updateConfig({ enabled: false })}>
+ *         Disable ads
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useAdConfig(): AdContextType;
+/**
+ * withAdConfig - HOC to provide config as prop
+ *
+ * @example
+ * ```tsx
+ * const ComponentWithConfig = withAdConfig(MyComponent);
+ * ```
+ */
+export declare function withAdConfig<P extends {
+    adConfig?: AdConfig;
+}>(Component: React.ComponentType<P>): (props: Omit<P, "adConfig">) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Debug logger for ad SDK
+ */
+export declare class AdLogger {
+    private debug;
+    private prefix;
+    constructor(debug?: boolean);
+    enable(): void;
+    disable(): void;
+    log(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+    info(...args: any[]): void;
+}
+/**
+ * Create logger instance from config
+ */
+export declare function createLogger(config: AdConfig): AdLogger;
+export {};

package/dist/components/AdSkeleton.d.ts

@@ -0,0 +1,50 @@
+/**
+ * AdSkeleton Props
+ */
+export interface AdSkeletonProps {
+    /** Type of ad skeleton */
+    variant?: 'action_card' | 'suffix' | 'followup' | 'source';
+    /** Layout variant */
+    layout?: 'horizontal' | 'vertical' | 'compact';
+    /** Custom class name */
+    className?: string;
+    /** Number of skeletons to show */
+    count?: number;
+}
+/**
+ * AdSkeleton - Loading placeholder for ad components
+ *
+ * @example
+ * ```tsx
+ * <AdSkeleton variant="action_card" layout="horizontal" count={3} />
+ * ```
+ */
+export declare function AdSkeleton({ variant, layout, className, count, }: AdSkeletonProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * InlineLoading - Small inline loading indicator
+ */
+export interface InlineLoadingProps {
+    /** Size of the indicator */
+    size?: 'sm' | 'md' | 'lg';
+    /** Custom class name */
+    className?: string;
+}
+export declare function InlineLoading({ size, className }: InlineLoadingProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * DotsLoading - Animated dots loading indicator
+ */
+export interface DotsLoadingProps {
+    /** Custom class name */
+    className?: string;
+}
+export declare function DotsLoading({ className }: DotsLoadingProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * FullPageLoading - Full screen loading overlay
+ */
+export interface FullPageLoadingProps {
+    /** Message to display */
+    message?: string;
+    /** Custom class name */
+    className?: string;
+}
+export declare function FullPageLoading({ message, className }: FullPageLoadingProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/EnhancedContent.d.ts

@@ -0,0 +1,53 @@
+import type { EntityInfo, EnhancedContentProps } from '@/types';
+/**
+ * EnhancedContent Component
+ *
+ * Renders content with entity-linked affiliate URLs.
+ * Supports different badge styles and handles overlapping entities.
+ *
+ * @example
+ * ```tsx
+ * <EnhancedContent
+ *   content="推荐 Sony WH-1000XM5 降噪耳机"
+ *   enhancements={{
+ *     entities: [
+ *       {
+ *         text: "Sony WH-1000XM5",
+ *         type: "product",
+ *         startPosition: 12,
+ *         endPosition: 26,
+ *         confidence: 0.95,
+ *       }
+ *     ],
+ *     replacements: [
+ *       {
+ *         originalText: "Sony WH-1000XM5",
+ *         affiliateUrl: "https://amazon.com/dp/B09XS7JWHH?tag=koah20-20",
+ *         trackingId: "track-123",
+ *         affiliateNetwork: "amazon",
+ *       }
+ *     ]
+ *   }}
+ * />
+ * ```
+ */
+export declare function EnhancedContent({ content, enhancements, className, onEntityClick, }: EnhancedContentProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Convenience components for common use cases
+ */
+/**
+ * Inline variant - for embedding within existing text
+ */
+export declare function EnhancedContentInline(props: Omit<EnhancedContentProps, 'className'>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Block variant - for standalone content blocks
+ */
+export declare function EnhancedContentBlock(props: EnhancedContentProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to get entity statistics from enhanced content
+ */
+export declare function useEntityStats(entities: EntityInfo[]): {
+    totalCount: number;
+    byType: Record<string, number>;
+    avgConfidence: number;
+};