@clarityops/preferences 0.1.1

package/src/PreferencesService.ts

@@ -0,0 +1,443 @@
+import type {
+  UserPreferences,
+  PrepareAvatarUploadResponse,
+  ConfirmAvatarUploadResponse,
+  MyAvatarResponse,
+  PreferencesConfig,
+} from './types';
+
+/**
+ * Validate if a token is a well-formed JWT with 3 segments
+ */
+function isValidJwtFormat(token: string | null | undefined): boolean {
+  if (!token || typeof token !== 'string') return false;
+  // Check for placeholder values
+  if (token === 'null' || token === 'undefined' || token.trim() === '') return false;
+  // JWT must have exactly 3 segments
+  const segments = token.split('.');
+  return segments.length === 3;
+}
+
+/**
+ * Check if a JWT token is expired
+ */
+function isTokenExpired(token: string): boolean {
+  try {
+    const payload = JSON.parse(atob(token.split('.')[1]));
+    const currentTime = Math.floor(Date.now() / 1000);
+    return payload.exp < currentTime;
+  } catch {
+    return true;
+  }
+}
+
+// Shared refresh lock to prevent concurrent refresh attempts across service instances
+let refreshInProgress: Promise<string | null> | null = null;
+let lastRefreshTime = 0;
+const REFRESH_DEBOUNCE_MS = 5000; // Minimum 5 seconds between refresh attempts
+
+/**
+ * Service class for user preferences and avatar management
+ * Shared across InsightForge and InsightFlow platforms
+ */
+export class PreferencesService {
+  private baseUrl: string;
+  private brandingUrl: string;
+  private getToken: () => string | null;
+  private onTokenInvalid?: () => Promise<string | null>;
+
+  constructor(config: PreferencesConfig) {
+    this.baseUrl = config.apiBaseUrl;
+    this.brandingUrl = config.brandingUrl;
+    this.getToken = config.getToken;
+    this.onTokenInvalid = config.onTokenInvalid;
+  }
+
+  /**
+   * Update the config (e.g., when token changes)
+   */
+  updateConfig(config: Partial<PreferencesConfig>) {
+    if (config.getToken) {
+      this.getToken = config.getToken;
+    }
+    if (config.onTokenInvalid !== undefined) {
+      this.onTokenInvalid = config.onTokenInvalid;
+    }
+    if (config.apiBaseUrl) {
+      this.baseUrl = config.apiBaseUrl;
+    }
+    if (config.brandingUrl) {
+      this.brandingUrl = config.brandingUrl;
+    }
+  }
+
+  /**
+   * Refresh token with debounce to prevent multiple simultaneous refresh attempts
+   */
+  private async refreshWithDebounce(): Promise<string | null> {
+    const now = Date.now();
+    
+    // If a refresh is already in progress, wait for it
+    if (refreshInProgress) {
+      console.log('[PreferencesService] ⏳ Waiting for existing refresh to complete...');
+      return refreshInProgress;
+    }
+    
+    // Debounce: if we just refreshed, get current token from localStorage
+    if (now - lastRefreshTime < REFRESH_DEBOUNCE_MS) {
+      console.log('[PreferencesService] ⏳ Recent refresh detected, using current token');
+      return this.getToken();
+    }
+    
+    // Start a new refresh
+    if (this.onTokenInvalid) {
+      console.log('[PreferencesService] 🔄 Starting token refresh...');
+      lastRefreshTime = now;
+      refreshInProgress = this.onTokenInvalid().finally(() => {
+        refreshInProgress = null;
+      });
+      return refreshInProgress;
+    }
+    
+    return null;
+  }
+
+  /**
+   * Get a valid token, refreshing if necessary with debounce protection
+   */
+  private async getValidToken(): Promise<string> {
+    let token = this.getToken();
+    
+    // Check if token is valid format
+    if (!isValidJwtFormat(token)) {
+      console.warn('[PreferencesService] Token is missing or malformed, attempting refresh...');
+      token = await this.refreshWithDebounce();
+      if (!isValidJwtFormat(token)) {
+        throw new Error('Authentication required - no valid token available');
+      }
+    }
+    
+    // Check if token is expired
+    if (isTokenExpired(token!)) {
+      console.warn('[PreferencesService] Token is expired, attempting refresh...');
+      token = await this.refreshWithDebounce();
+      if (!token || isTokenExpired(token)) {
+        throw new Error('Session expired - please log in again');
+      }
+    }
+    
+    return token!;
+  }
+
+  private async request<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
+    const token = await this.getValidToken();
+    
+    const response = await fetch(`${this.baseUrl}${endpoint}`, {
+      ...options,
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        ...options.headers,
+      },
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: 'Request failed' }));
+      
+      // If we get a 401, try to refresh and retry once
+      if (response.status === 401 && this.onTokenInvalid) {
+        console.warn('[PreferencesService] Got 401, attempting token refresh and retry...');
+        const newToken = await this.onTokenInvalid();
+        if (newToken && isValidJwtFormat(newToken)) {
+          const retryResponse = await fetch(`${this.baseUrl}${endpoint}`, {
+            ...options,
+            headers: {
+              'Authorization': `Bearer ${newToken}`,
+              'Content-Type': 'application/json',
+              ...options.headers,
+            },
+          });
+          
+          if (retryResponse.ok) {
+            return retryResponse.json();
+          }
+        }
+      }
+      
+      throw new Error(error.error || error.message || 'Request failed');
+    }
+
+    const data = await response.json();
+    return data;
+  }
+
+  /**
+   * Get user preferences
+   */
+  async getPreferences(): Promise<{ data: { preferences: UserPreferences } }> {
+    return this.request('/forge/users/me/preferences');
+  }
+
+  /**
+   * Update preferences (merge update)
+   */
+  async updatePreferences(preferences: Partial<UserPreferences>): Promise<{ data: { preferences: UserPreferences }; message?: string }> {
+    return this.request('/forge/users/me/preferences', {
+      method: 'PATCH',
+      body: JSON.stringify(preferences),
+    });
+  }
+
+  /**
+   * Replace all preferences
+   */
+  async replacePreferences(preferences: UserPreferences): Promise<{ data: { preferences: UserPreferences }; message?: string }> {
+    return this.request('/forge/users/me/preferences', {
+      method: 'PUT',
+      body: JSON.stringify(preferences),
+    });
+  }
+
+  /**
+   * Step 1: Prepare avatar upload - get signed URL for GCS
+   */
+  async prepareAvatarUpload(filename: string, mimeType: string): Promise<PrepareAvatarUploadResponse> {
+    const token = await this.getValidToken();
+    
+    const response = await fetch(`${this.brandingUrl}/branding/prepare-avatar-upload`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        filename,
+        mime_type: mimeType,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: 'Failed to prepare upload' }));
+      
+      // If we get a 401, try to refresh and retry once
+      if (response.status === 401 && this.onTokenInvalid) {
+        console.warn('[PreferencesService] Got 401 on prepareAvatarUpload, attempting refresh...');
+        const newToken = await this.onTokenInvalid();
+        if (newToken && isValidJwtFormat(newToken)) {
+          const retryResponse = await fetch(`${this.brandingUrl}/branding/prepare-avatar-upload`, {
+            method: 'POST',
+            headers: {
+              'Authorization': `Bearer ${newToken}`,
+              'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+              filename,
+              mime_type: mimeType,
+            }),
+          });
+          
+          if (retryResponse.ok) {
+            const data = await retryResponse.json();
+            if (data.success) return data.data;
+          }
+        }
+      }
+      
+      throw new Error(error.error || error.message || 'Failed to prepare avatar upload');
+    }
+
+    const data = await response.json();
+    if (!data.success) {
+      throw new Error(data.error || 'Failed to prepare avatar upload');
+    }
+
+    return data.data;
+  }
+
+  /**
+   * Step 2: Upload file directly to GCS
+   */
+  async uploadToGCS(uploadUrl: string, file: File): Promise<void> {
+    const response = await fetch(uploadUrl, {
+      method: 'PUT',
+      headers: {
+        'Content-Type': file.type,
+      },
+      body: file,
+    });
+
+    if (!response.ok) {
+      throw new Error('Failed to upload file to storage');
+    }
+  }
+
+  /**
+   * Step 3: Confirm avatar upload
+   */
+  async confirmAvatarUpload(storagePath: string): Promise<ConfirmAvatarUploadResponse> {
+    const token = await this.getValidToken();
+    
+    const response = await fetch(`${this.brandingUrl}/branding/confirm-avatar-upload`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        storage_path: storagePath,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: 'Failed to confirm upload' }));
+      
+      // If we get a 401, try to refresh and retry once
+      if (response.status === 401 && this.onTokenInvalid) {
+        console.warn('[PreferencesService] Got 401 on confirmAvatarUpload, attempting refresh...');
+        const newToken = await this.onTokenInvalid();
+        if (newToken && isValidJwtFormat(newToken)) {
+          const retryResponse = await fetch(`${this.brandingUrl}/branding/confirm-avatar-upload`, {
+            method: 'POST',
+            headers: {
+              'Authorization': `Bearer ${newToken}`,
+              'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+              storage_path: storagePath,
+            }),
+          });
+          
+          if (retryResponse.ok) {
+            const data = await retryResponse.json();
+            if (data.success) return data.data;
+          }
+        }
+      }
+      
+      throw new Error(error.error || error.message || 'Failed to confirm avatar upload');
+    }
+
+    const data = await response.json();
+    if (!data.success) {
+      throw new Error(data.error || 'Failed to confirm avatar upload');
+    }
+
+    return data.data;
+  }
+
+  /**
+   * Get current user's avatar
+   */
+  async getMyAvatar(): Promise<MyAvatarResponse> {
+    const token = await this.getValidToken();
+    
+    const response = await fetch(`${this.brandingUrl}/branding/my-avatar`, {
+      headers: {
+        'Authorization': `Bearer ${token}`,
+      },
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: 'Failed to fetch avatar' }));
+      
+      // If we get a 401, try to refresh and retry once
+      if (response.status === 401 && this.onTokenInvalid) {
+        console.warn('[PreferencesService] Got 401 on getMyAvatar, attempting refresh...');
+        const newToken = await this.onTokenInvalid();
+        if (newToken && isValidJwtFormat(newToken)) {
+          const retryResponse = await fetch(`${this.brandingUrl}/branding/my-avatar`, {
+            headers: {
+              'Authorization': `Bearer ${newToken}`,
+            },
+          });
+          
+          if (retryResponse.ok) {
+            const data = await retryResponse.json();
+            if (data.success) return data.data;
+          }
+        }
+      }
+      
+      throw new Error(error.error || error.message || 'Failed to fetch avatar');
+    }
+
+    const data = await response.json();
+    if (!data.success) {
+      throw new Error(data.error || 'Failed to fetch avatar');
+    }
+
+    return data.data;
+  }
+
+  /**
+   * Get any user's avatar
+   */
+  async getUserAvatar(userId: string): Promise<MyAvatarResponse> {
+    const token = await this.getValidToken();
+    
+    const response = await fetch(`${this.brandingUrl}/branding/users/${userId}/avatar`, {
+      headers: {
+        'Authorization': `Bearer ${token}`,
+      },
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: 'Failed to fetch avatar' }));
+      
+      // If we get a 401, try to refresh and retry once
+      if (response.status === 401 && this.onTokenInvalid) {
+        console.warn('[PreferencesService] Got 401 on getUserAvatar, attempting refresh...');
+        const newToken = await this.onTokenInvalid();
+        if (newToken && isValidJwtFormat(newToken)) {
+          const retryResponse = await fetch(`${this.brandingUrl}/branding/users/${userId}/avatar`, {
+            headers: {
+              'Authorization': `Bearer ${newToken}`,
+            },
+          });
+          
+          if (retryResponse.ok) {
+            const data = await retryResponse.json();
+            if (data.success) return data.data;
+          }
+        }
+      }
+      
+      throw new Error(error.error || error.message || 'Failed to fetch avatar');
+    }
+
+    const data = await response.json();
+    if (!data.success) {
+      throw new Error(data.error || 'Failed to fetch avatar');
+    }
+
+    return data.data;
+  }
+
+  /**
+   * Complete avatar upload flow (3-step process)
+   */
+  async uploadAvatar(file: File): Promise<string> {
+    // Validate file type
+    const validTypes = ['image/png', 'image/jpeg', 'image/jpg', 'image/webp'];
+    if (!validTypes.includes(file.type)) {
+      throw new Error('Please select a PNG, JPEG, or WebP image');
+    }
+
+    // Validate file size (5MB max)
+    const maxSize = 5 * 1024 * 1024;
+    if (file.size > maxSize) {
+      throw new Error('Image must be less than 5MB');
+    }
+
+    // Step 1: Prepare upload
+    const prepareData = await this.prepareAvatarUpload(file.name, file.type);
+
+    // Step 2: Upload to GCS
+    await this.uploadToGCS(prepareData.upload_url, file);
+
+    // Step 3: Confirm upload
+    const confirmData = await this.confirmAvatarUpload(prepareData.storage_path);
+
+    return confirmData.avatar_url;
+  }
+}

package/src/avatar-cache.ts

@@ -0,0 +1,55 @@
+/**
+ * In-memory cache for avatar URLs
+ * Shared across all components using the preferences context
+ */
+
+interface CacheEntry {
+  url: string;
+  cachedAt: number;
+}
+
+// Cache TTL: 1 day (as per API guidance)
+export const AVATAR_CACHE_TTL = 24 * 60 * 60 * 1000;
+
+// Global in-memory cache
+const avatarCache = new Map<string, CacheEntry>();
+
+/**
+ * Get cached avatar URL if valid
+ */
+export function getCachedAvatar(userId: string): string | null {
+  const cached = avatarCache.get(userId);
+  if (cached && Date.now() - cached.cachedAt < AVATAR_CACHE_TTL) {
+    return cached.url;
+  }
+  return null;
+}
+
+/**
+ * Set avatar URL in cache
+ */
+export function setCachedAvatar(userId: string, url: string): void {
+  avatarCache.set(userId, {
+    url,
+    cachedAt: Date.now(),
+  });
+}
+
+/**
+ * Clear cached avatar for a specific user or all users
+ */
+export function clearAvatarCache(userId?: string): void {
+  if (userId) {
+    avatarCache.delete(userId);
+  } else {
+    avatarCache.clear();
+  }
+}
+
+/**
+ * Check if cache entry exists and is valid
+ */
+export function hasCachedAvatar(userId: string): boolean {
+  const cached = avatarCache.get(userId);
+  return cached !== undefined && Date.now() - cached.cachedAt < AVATAR_CACHE_TTL;
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @clarityops/preferences
+ *
+ * Shared user preferences context for InsightForge and InsightFlow platforms.
+ * Provides unified avatar, theme, and notification preferences management.
+ */
+
+// Context and hooks
+export {
+  PreferencesProvider,
+  usePreferences,
+  usePreferencesSafe,
+  useAvatar,
+  type PreferencesProviderProps,
+} from './PreferencesContext';
+
+// Service
+export { PreferencesService } from './PreferencesService';
+
+// Types
+export type {
+  UserPreferences,
+  AvatarData,
+  PreferencesConfig,
+  PreferencesContextValue,
+  PrepareAvatarUploadResponse,
+  ConfirmAvatarUploadResponse,
+  MyAvatarResponse,
+} from './types';
+
+// Cache utilities
+export {
+  getCachedAvatar,
+  setCachedAvatar,
+  clearAvatarCache,
+  hasCachedAvatar,
+  AVATAR_CACHE_TTL,
+} from './avatar-cache';

package/src/types.ts

@@ -0,0 +1,94 @@
+/**
+ * User preferences types shared across InsightForge and InsightFlow
+ */
+
+export interface AnalysisCenterFilterPreset {
+  id: string;
+  name: string;
+  pattern: 'one_time' | 'recurring_structured' | 'continuous_monitoring';
+  category: string | null;
+  depth: 'quick_scan' | 'deep_dive' | null;
+  createdAt: string;
+}
+
+export interface UserPreferences {
+  theme?: 'light' | 'dark' | 'system';
+  avatar_url?: string;
+  locale?: string;
+  notification_settings?: {
+    email?: boolean;
+    push?: boolean;
+    sound?: boolean;
+    sound_volume?: number; // 0-100
+  };
+  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;
+}
+
+export interface AvatarData {
+  avatarUrl: string | null;
+  hasAvatar: boolean;
+  loading: boolean;
+  error: string | null;
+  refresh: () => Promise<void>;
+  handleImageError: () => void;
+}
+
+export interface PrepareAvatarUploadResponse {
+  upload_id: string;
+  user_id: string;
+  upload_url: string;
+  storage_path: string;
+  expires_at: string;
+  max_size_bytes: number;
+  allowed_types: string[];
+}
+
+export interface ConfirmAvatarUploadResponse {
+  user_id: string;
+  avatar_url: string;
+  file_size_bytes: number;
+  storage_path: string;
+}
+
+export interface MyAvatarResponse {
+  user_id: string;
+  has_avatar: boolean;
+  avatar_url: string | null;
+  expires_at?: string;
+  cache_max_age_seconds?: number;
+}
+
+export interface PreferencesConfig {
+  apiBaseUrl: string;
+  brandingUrl: string;
+  getToken: () => string | null;
+  /** Called when token is invalid/expired to attempt refresh */
+  onTokenInvalid?: () => Promise<string | null>;
+}
+
+export interface PreferencesContextValue {
+  // Preferences state
+  preferences: UserPreferences;
+  loading: boolean;
+  error: string | null;
+  
+  // Avatar data
+  avatar: AvatarData;
+  
+  // Actions
+  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>;
+}