@feedvalue/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,626 @@
+/**
+ * @feedvalue/core - Type Definitions
+ *
+ * Core types for the FeedValue SDK. These types are shared across
+ * all framework packages (React, Vue) and the vanilla API.
+ */
+/**
+ * Widget position on screen
+ */
+type WidgetPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left' | 'center';
+/**
+ * Widget theme mode
+ */
+type WidgetTheme = 'light' | 'dark' | 'auto';
+/**
+ * Trigger icon type
+ */
+type TriggerIconType = 'none' | 'chat' | 'message' | 'feedback' | 'comment' | 'help' | 'lightbulb';
+/**
+ * Custom field types
+ */
+type CustomFieldType = 'text' | 'email' | 'emoji';
+/**
+ * Emoji sentiment values
+ */
+type EmojiSentiment = 'angry' | 'disappointed' | 'satisfied' | 'excited';
+/**
+ * Custom field definition
+ */
+interface CustomField {
+    id: string;
+    type: CustomFieldType;
+    label: string;
+    placeholder?: string;
+    required: boolean;
+    order: number;
+}
+/**
+ * Widget styling configuration
+ */
+interface WidgetStyling {
+    primaryColor: string;
+    backgroundColor: string;
+    textColor: string;
+    buttonTextColor: string;
+    borderRadius: string;
+    customCSS?: string | undefined;
+}
+/**
+ * Widget UI configuration
+ */
+interface WidgetUIConfig {
+    position: WidgetPosition;
+    triggerText: string;
+    triggerIcon: TriggerIconType;
+    formTitle: string;
+    submitButtonText: string;
+    thankYouMessage: string;
+    showBranding: boolean;
+    customFields?: CustomField[] | undefined;
+}
+/**
+ * Full widget configuration (from API)
+ */
+interface WidgetConfig {
+    widgetId: string;
+    widgetKey: string;
+    appId: string;
+    config: WidgetUIConfig;
+    styling: WidgetStyling;
+}
+/**
+ * Options passed to FeedValue.init()
+ */
+interface FeedValueOptions {
+    /** Widget ID from FeedValue dashboard */
+    widgetId: string;
+    /** API base URL (defaults to production) */
+    apiBaseUrl?: string | undefined;
+    /** Enable debug logging */
+    debug?: boolean | undefined;
+    /** Initial configuration overrides */
+    config?: Partial<FeedValueConfig> | undefined;
+    /**
+     * Headless mode - disables all DOM rendering.
+     * Use this when you want full control over the UI.
+     * The SDK will still fetch config and provide all API methods
+     * (open, close, submit, etc.) but won't render any elements.
+     *
+     * @default false
+     */
+    headless?: boolean | undefined;
+}
+/**
+ * Runtime configuration (can be changed after init)
+ */
+interface FeedValueConfig {
+    /** Widget theme */
+    theme: WidgetTheme;
+    /** Widget position override */
+    position?: WidgetPosition;
+    /** Auto-show widget on init */
+    autoShow: boolean;
+    /** Enable debug logging */
+    debug: boolean;
+    /** Locale for internationalization */
+    locale: string;
+}
+/**
+ * Widget state (for framework integration)
+ * Used by useSyncExternalStore in React and reactive refs in Vue
+ */
+interface FeedValueState {
+    /** Widget is ready (config loaded) */
+    isReady: boolean;
+    /** Modal is open */
+    isOpen: boolean;
+    /** Widget is visible on page */
+    isVisible: boolean;
+    /** Current error (if any) */
+    error: Error | null;
+    /** Feedback submission in progress */
+    isSubmitting: boolean;
+}
+/**
+ * Feedback submission data
+ */
+interface FeedbackData {
+    /** Feedback message content */
+    message: string;
+    /** Sentiment rating (from emoji field) */
+    sentiment?: EmojiSentiment | undefined;
+    /** Custom field values */
+    customFieldValues?: Record<string, string> | undefined;
+    /** Page metadata */
+    metadata?: FeedbackMetadata | undefined;
+}
+/**
+ * Feedback metadata (auto-collected)
+ */
+interface FeedbackMetadata {
+    /** Current page URL */
+    page_url: string;
+    /** Referrer URL */
+    referrer?: string | undefined;
+    /** User agent string */
+    user_agent?: string | undefined;
+}
+/**
+ * Event types emitted by FeedValue
+ */
+interface FeedValueEvents {
+    /** Widget is ready (config loaded) */
+    ready: () => void;
+    /** Modal opened */
+    open: () => void;
+    /** Modal closed */
+    close: () => void;
+    /** Feedback submitted successfully */
+    submit: (feedback: FeedbackData) => void;
+    /** Error occurred */
+    error: (error: Error) => void;
+    /** State changed (for generic listeners) */
+    stateChange: (state: FeedValueState) => void;
+}
+/**
+ * Event handler type
+ */
+type EventHandler<K extends keyof FeedValueEvents> = FeedValueEvents[K];
+/**
+ * User data for identification
+ */
+interface UserData {
+    /** User email */
+    email?: string;
+    /** User display name */
+    name?: string;
+    /** Custom user properties */
+    [key: string]: string | undefined;
+}
+/**
+ * User traits for identify()
+ */
+interface UserTraits {
+    /** User email */
+    email?: string;
+    /** User display name */
+    name?: string;
+    /** Company or organization */
+    company?: string;
+    /** User plan/tier */
+    plan?: string;
+    /** Custom traits */
+    [key: string]: unknown;
+}
+/**
+ * User identification data for API submissions
+ * Sent with feedback when identify() or setData() has been called
+ */
+interface SubmissionUserData {
+    /** User ID (from identify()) */
+    user_id?: string;
+    /** User email (from setData or identify traits) */
+    email?: string;
+    /** User display name (from setData or identify traits) */
+    name?: string;
+    /** Additional user traits (from identify()) */
+    traits?: Record<string, unknown>;
+    /** Custom user data (from setData()) */
+    custom_data?: Record<string, string>;
+}
+/**
+ * API response for widget config
+ */
+interface ConfigResponse {
+    widget_id: string;
+    widget_key: string;
+    config: Partial<WidgetUIConfig>;
+    styling: Partial<WidgetStyling>;
+    submission_token?: string;
+    token_expires_at?: number;
+}
+/**
+ * API response for feedback submission
+ */
+interface FeedbackResponse {
+    success: boolean;
+    feedback_id: string;
+    message?: string;
+    blocked?: boolean;
+}
+/**
+ * FeedValue instance interface
+ * This is the public API for the widget
+ */
+interface FeedValueInstance {
+    /** Initialize the widget (fetch config, prepare DOM) */
+    init(): Promise<void>;
+    /** Destroy the widget (cleanup DOM, event listeners) */
+    destroy(): void;
+    /** Open the feedback modal */
+    open(): void;
+    /** Close the feedback modal */
+    close(): void;
+    /** Toggle the feedback modal */
+    toggle(): void;
+    /** Show the trigger button */
+    show(): void;
+    /** Hide the trigger button */
+    hide(): void;
+    /** Check if modal is open */
+    isOpen(): boolean;
+    /** Check if trigger is visible */
+    isVisible(): boolean;
+    /** Check if widget is ready */
+    isReady(): boolean;
+    /** Check if running in headless mode (no DOM rendering) */
+    isHeadless(): boolean;
+    /** Set user data (email, name, custom fields) */
+    setData(data: Partial<UserData>): void;
+    /** Identify user with ID and traits */
+    identify(userId: string, traits?: UserTraits): void;
+    /** Reset user data and state */
+    reset(): void;
+    /** Programmatically submit feedback */
+    submit(feedback: Partial<FeedbackData>): Promise<void>;
+    /** Subscribe to an event */
+    on<K extends keyof FeedValueEvents>(event: K, callback: EventHandler<K>): void;
+    /** Subscribe to an event for a single emission */
+    once<K extends keyof FeedValueEvents>(event: K, callback: EventHandler<K>): void;
+    /** Unsubscribe from an event */
+    off<K extends keyof FeedValueEvents>(event: K, callback?: EventHandler<K>): void;
+    /** Returns a promise that resolves when the widget is ready */
+    waitUntilReady(): Promise<void>;
+    /** Update runtime configuration */
+    setConfig(config: Partial<FeedValueConfig>): void;
+    /** Get current configuration */
+    getConfig(): FeedValueConfig;
+    /** Subscribe to state changes */
+    subscribe(callback: () => void): () => void;
+    /** Get current state snapshot */
+    getSnapshot(): FeedValueState;
+}
+
+/**
+ * @feedvalue/core - FeedValue Class
+ *
+ * Main FeedValue SDK class. Provides the public API for interacting
+ * with the feedback widget.
+ *
+ * For vanilla JavaScript usage, this class also handles DOM rendering.
+ * Framework packages (React, Vue) use this class as a headless core.
+ */
+
+/**
+ * FeedValue SDK
+ *
+ * @example
+ * ```ts
+ * // Initialize
+ * const feedvalue = FeedValue.init({ widgetId: 'abc123' });
+ *
+ * // Control
+ * feedvalue.open();
+ * feedvalue.close();
+ *
+ * // User data
+ * feedvalue.setData({ email: 'user@example.com' });
+ * feedvalue.identify('user-123', { plan: 'pro' });
+ *
+ * // Events
+ * feedvalue.on('submit', (feedback) => {
+ *   console.log('Feedback submitted:', feedback);
+ * });
+ * ```
+ */
+declare class FeedValue implements FeedValueInstance {
+    private readonly widgetId;
+    private readonly apiClient;
+    private readonly emitter;
+    private readonly headless;
+    private config;
+    private widgetConfig;
+    private state;
+    private stateSubscribers;
+    private stateSnapshot;
+    private _userData;
+    private _userId;
+    private _userTraits;
+    private triggerButton;
+    private modal;
+    private overlay;
+    private stylesInjected;
+    private autoCloseTimeout;
+    /**
+     * Create a new FeedValue instance
+     * Use FeedValue.init() for public API
+     */
+    private constructor();
+    /**
+     * Initialize FeedValue
+     * Returns existing instance if already initialized for this widgetId
+     */
+    static init(options: FeedValueOptions): FeedValue;
+    /**
+     * Get existing instance by widgetId
+     */
+    static getInstance(widgetId: string): FeedValue | undefined;
+    /**
+     * Initialize the widget
+     */
+    init(): Promise<void>;
+    /**
+     * Destroy the widget
+     */
+    destroy(): void;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    show(): void;
+    hide(): void;
+    isOpen(): boolean;
+    isVisible(): boolean;
+    isReady(): boolean;
+    isHeadless(): boolean;
+    setData(data: Partial<UserData>): void;
+    identify(userId: string, traits?: UserTraits): void;
+    reset(): void;
+    /**
+     * Get current user data (for debugging/testing)
+     */
+    getUserData(): {
+        userId: string | null;
+        data: UserData;
+        traits: UserTraits;
+    };
+    submit(feedback: Partial<FeedbackData>): Promise<void>;
+    /**
+     * Build user data object for API submission
+     * Combines data from identify() and setData() calls
+     */
+    private buildSubmissionUserData;
+    /**
+     * Validate feedback data before submission
+     * @throws Error if validation fails
+     */
+    private validateFeedback;
+    on<K extends keyof FeedValueEvents>(event: K, callback: EventHandler<K>): void;
+    /**
+     * Subscribe to an event for a single emission.
+     * The handler will be automatically removed after the first call.
+     */
+    once<K extends keyof FeedValueEvents>(event: K, callback: EventHandler<K>): void;
+    off<K extends keyof FeedValueEvents>(event: K, callback?: EventHandler<K>): void;
+    /**
+     * Returns a promise that resolves when the widget is ready.
+     * Useful for programmatic initialization flows.
+     *
+     * @throws {Error} If initialization fails
+     */
+    waitUntilReady(): Promise<void>;
+    setConfig(config: Partial<FeedValueConfig>): void;
+    getConfig(): FeedValueConfig;
+    /**
+     * Get widget configuration (from API)
+     */
+    getWidgetConfig(): WidgetConfig | null;
+    /**
+     * Subscribe to state changes
+     * Used by React's useSyncExternalStore
+     */
+    subscribe(callback: () => void): () => void;
+    /**
+     * Get current state snapshot
+     * Used by React's useSyncExternalStore
+     */
+    getSnapshot(): FeedValueState;
+    /**
+     * Update state and notify subscribers
+     */
+    private updateState;
+    /**
+     * Render widget DOM elements (for vanilla usage)
+     */
+    private renderWidget;
+    /**
+     * Sanitize CSS to block potentially dangerous patterns
+     * Prevents CSS injection attacks via url(), @import, and other vectors
+     */
+    private sanitizeCSS;
+    /**
+     * Inject CSS styles
+     */
+    private injectStyles;
+    /**
+     * Get base CSS styles
+     */
+    private getBaseStyles;
+    /**
+     * Get trigger button position styles
+     */
+    private getPositionStyles;
+    /**
+     * Get modal position styles
+     */
+    private getModalPositionStyles;
+    /**
+     * Render trigger button using safe DOM methods
+     */
+    private renderTrigger;
+    /**
+     * Render modal using safe DOM methods (no innerHTML)
+     */
+    private renderModal;
+    /**
+     * Handle form submission
+     */
+    private handleFormSubmit;
+    /**
+     * Show error message (safe - uses textContent)
+     */
+    private showError;
+    /**
+     * Show success message using safe DOM methods
+     */
+    private showSuccess;
+    /**
+     * Reset form to initial state
+     */
+    private resetForm;
+    /**
+     * Debug logging
+     */
+    private log;
+}
+
+/**
+ * @feedvalue/core - Type-Safe Event Emitter
+ *
+ * A minimal, type-safe event emitter for FeedValue events.
+ * Provides compile-time type checking for event names and handlers.
+ */
+
+/**
+ * Type-safe event emitter for FeedValue events
+ *
+ * @example
+ * ```ts
+ * const emitter = new TypedEventEmitter();
+ *
+ * emitter.on('ready', () => console.log('Ready!'));
+ * emitter.on('submit', (feedback) => console.log('Submitted:', feedback));
+ *
+ * emitter.emit('ready');
+ * emitter.emit('submit', { message: 'Great app!' });
+ * ```
+ */
+declare class TypedEventEmitter {
+    private listeners;
+    /**
+     * Subscribe to an event
+     *
+     * @param event - Event name
+     * @param handler - Event handler function
+     */
+    on<K extends keyof FeedValueEvents>(event: K, handler: EventHandler<K>): void;
+    /**
+     * Subscribe to an event for a single emission.
+     * The handler will be automatically removed after the first call.
+     *
+     * @param event - Event name
+     * @param handler - Event handler function
+     */
+    once<K extends keyof FeedValueEvents>(event: K, handler: EventHandler<K>): void;
+    /**
+     * Unsubscribe from an event
+     *
+     * @param event - Event name
+     * @param handler - Optional handler to remove (removes all if not provided)
+     */
+    off<K extends keyof FeedValueEvents>(event: K, handler?: EventHandler<K>): void;
+    /**
+     * Emit an event to all subscribers
+     *
+     * @param event - Event name
+     * @param args - Arguments to pass to handlers
+     */
+    emit<K extends keyof FeedValueEvents>(event: K, ...args: Parameters<EventHandler<K>>): void;
+    /**
+     * Remove all event listeners
+     */
+    removeAllListeners(): void;
+}
+
+/**
+ * @feedvalue/core - API Client
+ *
+ * Handles all communication with the FeedValue API.
+ * Includes request deduplication, caching, and error handling.
+ */
+
+/**
+ * Default API base URL
+ */
+declare const DEFAULT_API_BASE_URL = "https://api.feedvalue.com";
+/**
+ * API client for FeedValue
+ */
+declare class ApiClient {
+    private baseUrl;
+    private debug;
+    private pendingRequests;
+    private configCache;
+    private submissionToken;
+    private tokenExpiresAt;
+    private fingerprint;
+    constructor(baseUrl?: string, debug?: boolean);
+    /**
+     * Validate widget ID to prevent path injection attacks
+     * @throws Error if widget ID is invalid
+     */
+    private validateWidgetId;
+    /**
+     * Set client fingerprint for anti-abuse protection
+     */
+    setFingerprint(fingerprint: string): void;
+    /**
+     * Get client fingerprint
+     */
+    getFingerprint(): string | null;
+    /**
+     * Check if submission token is valid
+     */
+    hasValidToken(): boolean;
+    /**
+     * Fetch widget configuration
+     * Uses caching and request deduplication
+     */
+    fetchConfig(widgetId: string): Promise<ConfigResponse>;
+    /**
+     * Actually fetch config from API
+     */
+    private doFetchConfig;
+    /**
+     * Submit feedback with optional user data
+     */
+    submitFeedback(widgetId: string, feedback: FeedbackData, userData?: SubmissionUserData): Promise<FeedbackResponse>;
+    /**
+     * Parse error from response
+     */
+    private parseError;
+    /**
+     * Clear all caches
+     */
+    clearCache(): void;
+    /**
+     * Debug logging
+     */
+    private log;
+}
+
+/**
+ * Simple fingerprint generation for anti-abuse protection.
+ * Uses a session-based UUID stored in sessionStorage.
+ *
+ * This replaces the previous complex fingerprinting system (canvas, WebGL, audio)
+ * which was overkill for an MVP feedback widget and raised privacy concerns.
+ */
+/**
+ * Generate or retrieve a session fingerprint.
+ *
+ * The fingerprint is:
+ * - Generated once per browser session using crypto.randomUUID()
+ * - Stored in sessionStorage for consistency within a session
+ * - Automatically cleared when the browser tab/window is closed
+ *
+ * @returns A unique fingerprint string for the current session
+ */
+declare function generateFingerprint(): string;
+/**
+ * Clear the stored fingerprint.
+ * Useful for testing or when user requests data reset.
+ */
+declare function clearFingerprint(): void;
+
+export { ApiClient, type ConfigResponse, type CustomField, type CustomFieldType, DEFAULT_API_BASE_URL, type EmojiSentiment, type EventHandler, FeedValue, type FeedValueConfig, type FeedValueEvents, type FeedValueInstance, type FeedValueOptions, type FeedValueState, type FeedbackData, type FeedbackMetadata, type FeedbackResponse, type SubmissionUserData, type TriggerIconType, TypedEventEmitter, type UserData, type UserTraits, type WidgetConfig, type WidgetPosition, type WidgetStyling, type WidgetTheme, type WidgetUIConfig, clearFingerprint, generateFingerprint };