@clarityops/preferences 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,204 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * User preferences types shared across InsightForge and InsightFlow
+ */
+interface AnalysisCenterFilterPreset {
+    id: string;
+    name: string;
+    pattern: 'one_time' | 'recurring_structured' | 'continuous_monitoring';
+    category: string | null;
+    depth: 'quick_scan' | 'deep_dive' | null;
+    createdAt: string;
+}
+interface UserPreferences {
+    theme?: 'light' | 'dark' | 'system';
+    avatar_url?: string;
+    locale?: string;
+    notification_settings?: {
+        email?: boolean;
+        push?: boolean;
+        sound?: boolean;
+        sound_volume?: number;
+    };
+    sidebar_collapsed?: boolean;
+    default_client_id?: string;
+    timezone?: string;
+    avatar_updated_at?: string;
+    avatar_storage_path?: string;
+    show_demo_companies?: boolean;
+    analysis_center_filter_presets?: AnalysisCenterFilterPreset[];
+    /** Show WebSocket debug panel for connection troubleshooting (platform admins only) */
+    show_ws_debug_panel?: boolean;
+}
+interface AvatarData {
+    avatarUrl: string | null;
+    hasAvatar: boolean;
+    loading: boolean;
+    error: string | null;
+    refresh: () => Promise<void>;
+    handleImageError: () => void;
+}
+interface PrepareAvatarUploadResponse {
+    upload_id: string;
+    user_id: string;
+    upload_url: string;
+    storage_path: string;
+    expires_at: string;
+    max_size_bytes: number;
+    allowed_types: string[];
+}
+interface ConfirmAvatarUploadResponse {
+    user_id: string;
+    avatar_url: string;
+    file_size_bytes: number;
+    storage_path: string;
+}
+interface MyAvatarResponse {
+    user_id: string;
+    has_avatar: boolean;
+    avatar_url: string | null;
+    expires_at?: string;
+    cache_max_age_seconds?: number;
+}
+interface PreferencesConfig {
+    apiBaseUrl: string;
+    brandingUrl: string;
+    getToken: () => string | null;
+    /** Called when token is invalid/expired to attempt refresh */
+    onTokenInvalid?: () => Promise<string | null>;
+}
+interface PreferencesContextValue {
+    preferences: UserPreferences;
+    loading: boolean;
+    error: string | null;
+    avatar: AvatarData;
+    updatePreferences: (prefs: Partial<UserPreferences>) => Promise<void>;
+    refreshPreferences: () => Promise<void>;
+    uploadAvatar: (file: File) => Promise<string>;
+    clearAvatarCache: (userId?: string) => void;
+    /** Sync preferences on login and apply theme immediately */
+    syncOnLogin: () => Promise<void>;
+}
+
+interface PreferencesProviderProps {
+    children: ReactNode;
+    config: PreferencesConfig;
+    /** Optional initial preferences to avoid loading state */
+    initialPreferences?: UserPreferences;
+}
+declare function PreferencesProvider({ children, config, initialPreferences, }: PreferencesProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access preferences context
+ * Throws if used outside PreferencesProvider
+ */
+declare function usePreferences(): PreferencesContextValue;
+/**
+ * Hook to safely access preferences context
+ * Returns null if used outside PreferencesProvider (useful during hot reload)
+ */
+declare function usePreferencesSafe(): PreferencesContextValue | null;
+/**
+ * Hook to access just avatar data
+ */
+declare function useAvatar(): AvatarData;
+
+/**
+ * Service class for user preferences and avatar management
+ * Shared across InsightForge and InsightFlow platforms
+ */
+declare class PreferencesService {
+    private baseUrl;
+    private brandingUrl;
+    private getToken;
+    private onTokenInvalid?;
+    constructor(config: PreferencesConfig);
+    /**
+     * Update the config (e.g., when token changes)
+     */
+    updateConfig(config: Partial<PreferencesConfig>): void;
+    /**
+     * Refresh token with debounce to prevent multiple simultaneous refresh attempts
+     */
+    private refreshWithDebounce;
+    /**
+     * Get a valid token, refreshing if necessary with debounce protection
+     */
+    private getValidToken;
+    private request;
+    /**
+     * Get user preferences
+     */
+    getPreferences(): Promise<{
+        data: {
+            preferences: UserPreferences;
+        };
+    }>;
+    /**
+     * Update preferences (merge update)
+     */
+    updatePreferences(preferences: Partial<UserPreferences>): Promise<{
+        data: {
+            preferences: UserPreferences;
+        };
+        message?: string;
+    }>;
+    /**
+     * Replace all preferences
+     */
+    replacePreferences(preferences: UserPreferences): Promise<{
+        data: {
+            preferences: UserPreferences;
+        };
+        message?: string;
+    }>;
+    /**
+     * Step 1: Prepare avatar upload - get signed URL for GCS
+     */
+    prepareAvatarUpload(filename: string, mimeType: string): Promise<PrepareAvatarUploadResponse>;
+    /**
+     * Step 2: Upload file directly to GCS
+     */
+    uploadToGCS(uploadUrl: string, file: File): Promise<void>;
+    /**
+     * Step 3: Confirm avatar upload
+     */
+    confirmAvatarUpload(storagePath: string): Promise<ConfirmAvatarUploadResponse>;
+    /**
+     * Get current user's avatar
+     */
+    getMyAvatar(): Promise<MyAvatarResponse>;
+    /**
+     * Get any user's avatar
+     */
+    getUserAvatar(userId: string): Promise<MyAvatarResponse>;
+    /**
+     * Complete avatar upload flow (3-step process)
+     */
+    uploadAvatar(file: File): Promise<string>;
+}
+
+/**
+ * In-memory cache for avatar URLs
+ * Shared across all components using the preferences context
+ */
+declare const AVATAR_CACHE_TTL: number;
+/**
+ * Get cached avatar URL if valid
+ */
+declare function getCachedAvatar(userId: string): string | null;
+/**
+ * Set avatar URL in cache
+ */
+declare function setCachedAvatar(userId: string, url: string): void;
+/**
+ * Clear cached avatar for a specific user or all users
+ */
+declare function clearAvatarCache(userId?: string): void;
+/**
+ * Check if cache entry exists and is valid
+ */
+declare function hasCachedAvatar(userId: string): boolean;
+
+export { AVATAR_CACHE_TTL, type AvatarData, type ConfirmAvatarUploadResponse, type MyAvatarResponse, type PreferencesConfig, type PreferencesContextValue, PreferencesProvider, type PreferencesProviderProps, PreferencesService, type PrepareAvatarUploadResponse, type UserPreferences, clearAvatarCache, getCachedAvatar, hasCachedAvatar, setCachedAvatar, useAvatar, usePreferences, usePreferencesSafe };

package/dist/index.d.ts

@@ -0,0 +1,204 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * User preferences types shared across InsightForge and InsightFlow
+ */
+interface AnalysisCenterFilterPreset {
+    id: string;
+    name: string;
+    pattern: 'one_time' | 'recurring_structured' | 'continuous_monitoring';
+    category: string | null;
+    depth: 'quick_scan' | 'deep_dive' | null;
+    createdAt: string;
+}
+interface UserPreferences {
+    theme?: 'light' | 'dark' | 'system';
+    avatar_url?: string;
+    locale?: string;
+    notification_settings?: {
+        email?: boolean;
+        push?: boolean;
+        sound?: boolean;
+        sound_volume?: number;
+    };
+    sidebar_collapsed?: boolean;
+    default_client_id?: string;
+    timezone?: string;
+    avatar_updated_at?: string;
+    avatar_storage_path?: string;
+    show_demo_companies?: boolean;
+    analysis_center_filter_presets?: AnalysisCenterFilterPreset[];
+    /** Show WebSocket debug panel for connection troubleshooting (platform admins only) */
+    show_ws_debug_panel?: boolean;
+}
+interface AvatarData {
+    avatarUrl: string | null;
+    hasAvatar: boolean;
+    loading: boolean;
+    error: string | null;
+    refresh: () => Promise<void>;
+    handleImageError: () => void;
+}
+interface PrepareAvatarUploadResponse {
+    upload_id: string;
+    user_id: string;
+    upload_url: string;
+    storage_path: string;
+    expires_at: string;
+    max_size_bytes: number;
+    allowed_types: string[];
+}
+interface ConfirmAvatarUploadResponse {
+    user_id: string;
+    avatar_url: string;
+    file_size_bytes: number;
+    storage_path: string;
+}
+interface MyAvatarResponse {
+    user_id: string;
+    has_avatar: boolean;
+    avatar_url: string | null;
+    expires_at?: string;
+    cache_max_age_seconds?: number;
+}
+interface PreferencesConfig {
+    apiBaseUrl: string;
+    brandingUrl: string;
+    getToken: () => string | null;
+    /** Called when token is invalid/expired to attempt refresh */
+    onTokenInvalid?: () => Promise<string | null>;
+}
+interface PreferencesContextValue {
+    preferences: UserPreferences;
+    loading: boolean;
+    error: string | null;
+    avatar: AvatarData;
+    updatePreferences: (prefs: Partial<UserPreferences>) => Promise<void>;
+    refreshPreferences: () => Promise<void>;
+    uploadAvatar: (file: File) => Promise<string>;
+    clearAvatarCache: (userId?: string) => void;
+    /** Sync preferences on login and apply theme immediately */
+    syncOnLogin: () => Promise<void>;
+}
+
+interface PreferencesProviderProps {
+    children: ReactNode;
+    config: PreferencesConfig;
+    /** Optional initial preferences to avoid loading state */
+    initialPreferences?: UserPreferences;
+}
+declare function PreferencesProvider({ children, config, initialPreferences, }: PreferencesProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access preferences context
+ * Throws if used outside PreferencesProvider
+ */
+declare function usePreferences(): PreferencesContextValue;
+/**
+ * Hook to safely access preferences context
+ * Returns null if used outside PreferencesProvider (useful during hot reload)
+ */
+declare function usePreferencesSafe(): PreferencesContextValue | null;
+/**
+ * Hook to access just avatar data
+ */
+declare function useAvatar(): AvatarData;
+
+/**
+ * Service class for user preferences and avatar management
+ * Shared across InsightForge and InsightFlow platforms
+ */
+declare class PreferencesService {
+    private baseUrl;
+    private brandingUrl;
+    private getToken;
+    private onTokenInvalid?;
+    constructor(config: PreferencesConfig);
+    /**
+     * Update the config (e.g., when token changes)
+     */
+    updateConfig(config: Partial<PreferencesConfig>): void;
+    /**
+     * Refresh token with debounce to prevent multiple simultaneous refresh attempts
+     */
+    private refreshWithDebounce;
+    /**
+     * Get a valid token, refreshing if necessary with debounce protection
+     */
+    private getValidToken;
+    private request;
+    /**
+     * Get user preferences
+     */
+    getPreferences(): Promise<{
+        data: {
+            preferences: UserPreferences;
+        };
+    }>;
+    /**
+     * Update preferences (merge update)
+     */
+    updatePreferences(preferences: Partial<UserPreferences>): Promise<{
+        data: {
+            preferences: UserPreferences;
+        };
+        message?: string;
+    }>;
+    /**
+     * Replace all preferences
+     */
+    replacePreferences(preferences: UserPreferences): Promise<{
+        data: {
+            preferences: UserPreferences;
+        };
+        message?: string;
+    }>;
+    /**
+     * Step 1: Prepare avatar upload - get signed URL for GCS
+     */
+    prepareAvatarUpload(filename: string, mimeType: string): Promise<PrepareAvatarUploadResponse>;
+    /**
+     * Step 2: Upload file directly to GCS
+     */
+    uploadToGCS(uploadUrl: string, file: File): Promise<void>;
+    /**
+     * Step 3: Confirm avatar upload
+     */
+    confirmAvatarUpload(storagePath: string): Promise<ConfirmAvatarUploadResponse>;
+    /**
+     * Get current user's avatar
+     */
+    getMyAvatar(): Promise<MyAvatarResponse>;
+    /**
+     * Get any user's avatar
+     */
+    getUserAvatar(userId: string): Promise<MyAvatarResponse>;
+    /**
+     * Complete avatar upload flow (3-step process)
+     */
+    uploadAvatar(file: File): Promise<string>;
+}
+
+/**
+ * In-memory cache for avatar URLs
+ * Shared across all components using the preferences context
+ */
+declare const AVATAR_CACHE_TTL: number;
+/**
+ * Get cached avatar URL if valid
+ */
+declare function getCachedAvatar(userId: string): string | null;
+/**
+ * Set avatar URL in cache
+ */
+declare function setCachedAvatar(userId: string, url: string): void;
+/**
+ * Clear cached avatar for a specific user or all users
+ */
+declare function clearAvatarCache(userId?: string): void;
+/**
+ * Check if cache entry exists and is valid
+ */
+declare function hasCachedAvatar(userId: string): boolean;
+
+export { AVATAR_CACHE_TTL, type AvatarData, type ConfirmAvatarUploadResponse, type MyAvatarResponse, type PreferencesConfig, type PreferencesContextValue, PreferencesProvider, type PreferencesProviderProps, PreferencesService, type PrepareAvatarUploadResponse, type UserPreferences, clearAvatarCache, getCachedAvatar, hasCachedAvatar, setCachedAvatar, useAvatar, usePreferences, usePreferencesSafe };