@allternit/gizzi-code 1.0.0 → 1.0.1

package/src/utils/sessionStorage.ts

@@ -1,559 +1,325 @@
 /**
- * @fileoverview Session storage utilities for gizzi-code integration
- * @module utils/sessionStorage
- *
- * Provides session persistence, storage management, and user type detection
- * with safe fallbacks for environments without storage access.
+ * Session Storage
+ * Production-quality session management with filesystem persistence
  */
 
-import type { UserSession } from '../state/AppStateStore';
-import type { TypedMessage } from '../types/message';
+import { writeFile, readFile, mkdir, access, constants } from 'fs/promises'
+import { join } from 'path'
+import { homedir } from 'os'
+import { log } from '../runtime/util/log.js'
 
-/**
- * Storage keys used throughout the application
- * @constant {Record<string, string>}
- */
-export const STORAGE_KEYS = {
-  SESSION: 'gizzi_session',
-  USER_TYPE: 'gizzi_user_type',
-  MESSAGES: 'gizzi_messages',
-  PREFERENCES: 'gizzi_preferences',
-  LAST_ACTIVITY: 'gizzi_last_activity',
-  SESSION_METADATA: 'gizzi_session_metadata',
-} as const;
-
-/**
- * User type categories
- * @typedef {'anonymous' | 'free' | 'pro' | 'enterprise' | 'admin'} UserType
- */
-export type UserType = 'anonymous' | 'free' | 'pro' | 'enterprise' | 'admin';
-
-/**
- * Valid user types for runtime validation
- * @constant {readonly UserType[]}
- */
-export const VALID_USER_TYPES: readonly UserType[] = [
-  'anonymous',
-  'free',
-  'pro',
-  'enterprise',
-  'admin',
-] as const;
-
-/**
- * Session metadata stored alongside the session
- * @interface SessionMetadata
- */
-export interface SessionMetadata {
-  /** When the session was created */
-  readonly createdAt: string;
-
-  /** Last activity timestamp (ISO string) */
-  readonly lastActivity: string;
-
-  /** Number of messages in this session */
-  readonly messageCount: number;
+export type UserType = 'anonymous' | 'authenticated' | 'admin' | 'ant' | 'beta'
 
-  /** Session version for migration purposes */
-  readonly version: number;
+export interface SessionData {
+  sessionId: string
+  userId?: string
+  userType: UserType
+  email?: string
+  accessToken?: string
+  refreshToken?: string
+  createdAt: number
+  lastActivity: number
+  expiresAt?: number
+  metadata?: Record<string, unknown>
+}
 
-  /** Device/browser information */
-  readonly deviceInfo?: {
-    readonly userAgent: string;
-    readonly platform: string;
-    readonly language: string;
-  };
+export interface UserPreferences {
+  theme?: 'dark' | 'light' | 'system'
+  fontSize?: number
+  autoSave?: boolean
+  notifications?: boolean
+  telemetry?: boolean
+  [key: string]: unknown
 }
 
-/**
- * Complete session data structure
- * @interface SessionData
- */
-export interface SessionData {
-  /** User session information */
-  readonly session: UserSession;
+export interface Message {
+  id: string
+  role: 'user' | 'assistant' | 'system'
+  content: string
+  timestamp: number
+  attachments?: Attachment[]
+}
 
-  /** Session metadata */
-  readonly metadata: SessionMetadata;
+export interface Attachment {
+  id: string
+  filename: string
+  contentType: string
+  size: number
+  path: string
+}
 
-  /** Persisted messages */
-  readonly messages: readonly TypedMessage[];
+// In-memory cache
+const memoryStorage = new Map<string, unknown>()
+let currentSession: SessionData | null = null
+let preferencesCache: UserPreferences | null = null
 
-  /** User preferences */
-  readonly preferences: Readonly<Record<string, unknown>>;
+// Config directory
+function getConfigDir(): string {
+  return join(homedir(), '.config', 'gizzi')
 }
 
-/**
- * Storage operation result
- * @interface StorageResult
- */
-export interface StorageResult<T> {
-  /** Whether the operation succeeded */
-  readonly success: boolean;
-
-  /** The data if successful, null otherwise */
-  readonly data: T | null;
+function getSessionFilePath(): string {
+  return join(getConfigDir(), 'session.json')
+}
 
-  /** Error message if failed */
-  readonly error: string | null;
+function getPreferencesFilePath(): string {
+  return join(getConfigDir(), 'preferences.json')
 }
 
-/**
- * Checks if localStorage/sessionStorage is available
- * @returns {boolean} True if storage APIs are available
- */
-function isStorageAvailable(): boolean {
-  try {
-    if (typeof window === 'undefined') {
-      return false;
-    }
-    const testKey = '__gizzi_storage_test__';
-    window.sessionStorage.setItem(testKey, 'test');
-    window.sessionStorage.removeItem(testKey);
-    return true;
-  } catch {
-    return false;
-  }
+function getMessagesFilePath(): string {
+  return join(getConfigDir(), 'messages.json')
 }
 
-/**
- * Safely parses JSON with error handling
- *
- * @template T
- * @param {string} json - JSON string to parse
- * @param {T} [defaultValue] - Default value if parsing fails
- * @returns {T | null} Parsed value or default/null on error
- */
-function safeJsonParse<T>(json: string, defaultValue?: T): T | null {
+async function ensureConfigDir(): Promise<void> {
+  const configDir = getConfigDir()
   try {
-    return JSON.parse(json) as T;
+    await access(configDir, constants.F_OK)
   } catch {
-    return defaultValue ?? null;
+    await mkdir(configDir, { recursive: true })
   }
 }
 
-/**
- * Safely stringifies JSON with error handling
- *
- * @param {unknown} value - Value to stringify
- * @returns {string | null} JSON string or null on error
- */
-function safeJsonStringify(value: unknown): string | null {
+// Session Management
+export async function saveSession(data: SessionData): Promise<void> {
+  await ensureConfigDir()
+  
+  const session: SessionData = {
+    ...data,
+    lastActivity: Date.now(),
+  }
+  
+  currentSession = session
+  memoryStorage.set('__session', session)
+  
+  // Persist to disk
   try {
-    return JSON.stringify(value);
-  } catch {
-    return null;
+    await writeFile(getSessionFilePath(), JSON.stringify(session, null, 2))
+    log('debug', 'Session persisted to disk', { sessionId: data.sessionId })
+  } catch (error) {
+    log('error', 'Failed to persist session', error)
+    throw new Error('Failed to save session')
   }
 }
 
-/**
- * In-memory fallback storage when sessionStorage is unavailable
- * @constant {Map<string, string>}
- */
-const memoryStorage: Map<string, string> = new Map();
-
-/**
- * Gets an item from storage (sessionStorage or memory fallback)
- *
- * @param {string} key - Storage key
- * @returns {string | null} The stored value or null
- */
-function getStorageItem(key: string): string | null {
-  if (isStorageAvailable()) {
-    return window.sessionStorage.getItem(key);
+export async function loadSession(): Promise<SessionData | null> {
+  // Check memory first
+  if (currentSession) {
+    return currentSession
   }
-  return memoryStorage.get(key) ?? null;
-}
-
-/**
- * Sets an item in storage (sessionStorage or memory fallback)
- *
- * @param {string} key - Storage key
- * @param {string} value - Value to store
- * @returns {boolean} True if successful
- */
-function setStorageItem(key: string, value: string): boolean {
+  
+  // Try to load from disk
   try {
-    if (isStorageAvailable()) {
-      window.sessionStorage.setItem(key, value);
-    } else {
-      memoryStorage.set(key, value);
+    const data = await readFile(getSessionFilePath(), 'utf8')
+    const session: SessionData = JSON.parse(data)
+    
+    // Check if session is expired
+    if (session.expiresAt && session.expiresAt < Date.now()) {
+      log('info', 'Session expired')
+      await clearSession()
+      return null
     }
-    return true;
+    
+    currentSession = session
+    memoryStorage.set('__session', session)
+    
+    // Update last activity
+    session.lastActivity = Date.now()
+    await saveSession(session)
+    
+    return session
   } catch (error) {
-    console.error(`Failed to set storage item '${key}':`, error);
-    return false;
+    // File doesn't exist or is corrupted
+    return null
   }
 }
 
-/**
- * Removes an item from storage
- *
- * @param {string} key - Storage key to remove
- * @returns {boolean} True if successful
- */
-function removeStorageItem(key: string): boolean {
+export async function clearSession(): Promise<void> {
+  currentSession = null
+  memoryStorage.delete('__session')
+  
   try {
-    if (isStorageAvailable()) {
-      window.sessionStorage.removeItem(key);
-    } else {
-      memoryStorage.delete(key);
-    }
-    return true;
+    await writeFile(getSessionFilePath(), '{}')
+    log('info', 'Session cleared')
   } catch (error) {
-    console.error(`Failed to remove storage item '${key}':`, error);
-    return false;
+    log('error', 'Failed to clear session file', error)
   }
 }
 
-/**
- * Saves the current session to storage
- *
- * @param {UserSession} session - The session to save
- * @param {Object} [options] - Save options
- * @param {TypedMessage[]} [options.messages] - Messages to persist
- * @param {Record<string, unknown>} [options.preferences] - Preferences to persist
- * @returns {StorageResult<void>} Result of the save operation
- * @example
- * ```typescript
- * const result = saveSession(session, { messages, preferences });
- * if (!result.success) {
- *   console.error('Failed to save session:', result.error);
- * }
- * ```
- */
-export function saveSession(
-  session: UserSession,
-  options: {
-    messages?: TypedMessage[];
-    preferences?: Record<string, unknown>;
-  } = {}
-): StorageResult<void> {
-  if (!session) {
-    return { success: false, data: null, error: 'Session is required' };
-  }
-
-  const existingMetadata = loadSessionMetadata();
-  const metadata: SessionMetadata = {
-    createdAt: existingMetadata?.createdAt ?? new Date().toISOString(),
-    lastActivity: new Date().toISOString(),
-    messageCount: options.messages?.length ?? 0,
-    version: 1,
-    deviceInfo: isStorageAvailable()
-      ? {
-          userAgent: navigator.userAgent,
-          platform: navigator.platform,
-          language: navigator.language,
-        }
-      : undefined,
-  };
-
-  const sessionData: SessionData = {
-    session,
-    metadata,
-    messages: options.messages ?? [],
-    preferences: options.preferences ?? {},
-  };
-
-  const serialized = safeJsonStringify(sessionData);
-  if (!serialized) {
-    return { success: false, data: null, error: 'Failed to serialize session data' };
-  }
-
-  if (!setStorageItem(STORAGE_KEYS.SESSION, serialized)) {
-    return { success: false, data: null, error: 'Failed to write to storage' };
-  }
-
-  // Also save user type separately for quick access
-  setStorageItem(STORAGE_KEYS.USER_TYPE, session.userType);
-  setStorageItem(STORAGE_KEYS.LAST_ACTIVITY, metadata.lastActivity);
-
-  return { success: true, data: undefined, error: null };
+export function hasActiveSession(): boolean {
+  if (currentSession) return true
+  return memoryStorage.has('__session')
 }
 
-/**
- * Loads the session from storage
- *
- * @returns {StorageResult<SessionData>} The loaded session data or error
- * @example
- * ```typescript
- * const result = loadSession();
- * if (result.success && result.data) {
- *   const { session, messages } = result.data;
- *   // Restore session...
- * }
- * ```
- */
-export function loadSession(): StorageResult<SessionData> {
-  const serialized = getStorageItem(STORAGE_KEYS.SESSION);
-
-  if (!serialized) {
-    return { success: false, data: null, error: 'No session found in storage' };
-  }
+export function getSessionId(): string | undefined {
+  return currentSession?.sessionId
+}
 
-  const data = safeJsonParse<SessionData>(serialized);
+export function getUserType(): UserType {
+  return currentSession?.userType || 'anonymous'
+}
 
-  if (!data) {
-    return { success: false, data: null, error: 'Failed to parse session data' };
-  }
+export function isUserType(type: UserType): boolean {
+  return getUserType() === type
+}
 
-  // Validate session has not expired
-  if (data.session.expiresAt) {
-    const expiresAt = new Date(data.session.expiresAt);
-    if (expiresAt < new Date()) {
-      clearSession();
-      return { success: false, data: null, error: 'Session has expired' };
-    }
-  }
+export function isAuthenticated(): boolean {
+  return currentSession?.userType === 'authenticated' || 
+         currentSession?.userType === 'admin' ||
+         currentSession?.userType === 'ant'
+}
 
-  // Update last activity
-  const updatedMetadata: SessionMetadata = {
-    ...data.metadata,
-    lastActivity: new Date().toISOString(),
-  };
-
-  // Silently update last activity in storage
-  const updatedData: SessionData = { ...data, metadata: updatedMetadata };
-  const serializedUpdated = safeJsonStringify(updatedData);
-  if (serializedUpdated) {
-    setStorageItem(STORAGE_KEYS.SESSION, serializedUpdated);
+export async function updateLastActivity(): Promise<void> {
+  if (currentSession) {
+    currentSession.lastActivity = Date.now()
+    await saveSession(currentSession)
   }
+}
 
-  return { success: true, data: updatedData, error: null };
+export function getLastActivity(): number | undefined {
+  return currentSession?.lastActivity
 }
 
-/**
- * Clears all session data from storage
- *
- * @returns {boolean} True if successful
- * @example
- * ```typescript
- * clearSession(); // Logs out the user
- * ```
- */
-export function clearSession(): boolean {
-  const keysToRemove = [
-    STORAGE_KEYS.SESSION,
-    STORAGE_KEYS.USER_TYPE,
-    STORAGE_KEYS.MESSAGES,
-    STORAGE_KEYS.PREFERENCES,
-    STORAGE_KEYS.LAST_ACTIVITY,
-    STORAGE_KEYS.SESSION_METADATA,
-  ];
-
-  let allSuccess = true;
-  for (const key of keysToRemove) {
-    if (!removeStorageItem(key)) {
-      allSuccess = false;
-    }
+// Preferences Management
+export async function savePreferences(prefs: UserPreferences): Promise<void> {
+  await ensureConfigDir()
+  preferencesCache = prefs
+  
+  try {
+    await writeFile(getPreferencesFilePath(), JSON.stringify(prefs, null, 2))
+    log('debug', 'Preferences saved')
+  } catch (error) {
+    log('error', 'Failed to save preferences', error)
+    throw new Error('Failed to save preferences')
   }
-
-  // Also clear memory storage
-  memoryStorage.clear();
-
-  return allSuccess;
 }
 
-/**
- * Gets the user type from storage
- * Returns 'anonymous' if no user type is stored or on error
- *
- * @returns {UserType} The stored user type or 'anonymous'
- * @example
- * ```typescript
- * const userType = getUserType();
- * if (userType === 'pro') {
- *   // Show pro features
- * }
- * ```
- */
-export function getUserType(): UserType {
-  const stored = getStorageItem(STORAGE_KEYS.USER_TYPE);
-
-  if (stored && VALID_USER_TYPES.includes(stored as UserType)) {
-    return stored as UserType;
+export async function loadPreferences(): Promise<UserPreferences> {
+  if (preferencesCache) {
+    return preferencesCache
   }
-
-  // Try to infer from session
-  const sessionResult = loadSession();
-  if (sessionResult.success && sessionResult.data) {
-    const sessionType = sessionResult.data.session.userType;
-    if (VALID_USER_TYPES.includes(sessionType as UserType)) {
-      return sessionType as UserType;
+  
+  try {
+    const data = await readFile(getPreferencesFilePath(), 'utf8')
+    const prefs: UserPreferences = JSON.parse(data)
+    preferencesCache = prefs
+    return prefs
+  } catch {
+    // Return defaults
+    return {
+      theme: 'dark',
+      fontSize: 14,
+      autoSave: true,
+      notifications: true,
+      telemetry: true,
     }
   }
-
-  return 'anonymous';
 }
 
-/**
- * Loads session metadata without loading the full session
- *
- * @returns {SessionMetadata | null} The metadata or null if not found
- */
-function loadSessionMetadata(): SessionMetadata | null {
-  const sessionResult = loadSession();
-  if (sessionResult.success && sessionResult.data) {
-    return sessionResult.data.metadata;
-  }
-  return null;
+export async function getPreference<T>(key: string, defaultValue: T): Promise<T> {
+  const prefs = await loadPreferences()
+  return (prefs[key] as T) ?? defaultValue
 }
 
-/**
- * Saves messages to session storage
- *
- * @param {TypedMessage[]} messages - Messages to save
- * @returns {StorageResult<void>} Result of the operation
- */
-export function saveMessages(messages: TypedMessage[]): StorageResult<void> {
-  const serialized = safeJsonStringify(messages);
-
-  if (!serialized) {
-    return { success: false, data: null, error: 'Failed to serialize messages' };
-  }
-
-  if (!setStorageItem(STORAGE_KEYS.MESSAGES, serialized)) {
-    return { success: false, data: null, error: 'Failed to write messages to storage' };
-  }
-
-  // Update message count in session metadata
-  const sessionResult = loadSession();
-  if (sessionResult.success && sessionResult.data) {
-    const { session, metadata, preferences } = sessionResult.data;
-    saveSession(session, {
-      messages,
-      preferences,
-    });
-  }
-
-  return { success: true, data: undefined, error: null };
+export async function setPreference<T>(key: string, value: T): Promise<void> {
+  const prefs = await loadPreferences()
+  prefs[key] = value
+  await savePreferences(prefs)
 }
 
-/**
- * Loads messages from session storage
- *
- * @returns {StorageResult<TypedMessage[]>} The loaded messages or error
- */
-export function loadMessages(): StorageResult<TypedMessage[]> {
-  const serialized = getStorageItem(STORAGE_KEYS.MESSAGES);
-
-  if (!serialized) {
-    return { success: false, data: null, error: 'No messages found in storage' };
-  }
-
-  const messages = safeJsonParse<TypedMessage[]>(serialized, []);
-
-  if (!messages) {
-    return { success: false, data: null, error: 'Failed to parse messages' };
+// Message Persistence
+export async function saveMessages(messages: Message[]): Promise<void> {
+  await ensureConfigDir()
+  
+  try {
+    await writeFile(getMessagesFilePath(), JSON.stringify(messages, null, 2))
+  } catch (error) {
+    log('error', 'Failed to save messages', error)
   }
-
-  return { success: true, data: messages, error: null };
 }
 
-/**
- * Saves user preferences to storage
- *
- * @param {Record<string, unknown>} preferences - Preferences to save
- * @returns {StorageResult<void>} Result of the operation
- */
-export function savePreferences(preferences: Record<string, unknown>): StorageResult<void> {
-  const serialized = safeJsonStringify(preferences);
-
-  if (!serialized) {
-    return { success: false, data: null, error: 'Failed to serialize preferences' };
-  }
-
-  if (!setStorageItem(STORAGE_KEYS.PREFERENCES, serialized)) {
-    return { success: false, data: null, error: 'Failed to write preferences to storage' };
+export async function loadMessages(): Promise<Message[]> {
+  try {
+    const data = await readFile(getMessagesFilePath(), 'utf8')
+    return JSON.parse(data)
+  } catch {
+    return []
   }
-
-  return { success: true, data: undefined, error: null };
 }
 
-/**
- * Loads user preferences from storage
- *
- * @returns {StorageResult<Record<string, unknown>>} The loaded preferences or error
- */
-export function loadPreferences(): StorageResult<Record<string, unknown>> {
-  const serialized = getStorageItem(STORAGE_KEYS.PREFERENCES);
-
-  if (!serialized) {
-    return { success: false, data: null, error: 'No preferences found in storage' };
+export async function addMessage(message: Message): Promise<void> {
+  const messages = await loadMessages()
+  messages.push(message)
+  
+  // Keep only last 1000 messages
+  if (messages.length > 1000) {
+    messages.splice(0, messages.length - 1000)
   }
+  
+  await saveMessages(messages)
+}
 
-  const preferences = safeJsonParse<Record<string, unknown>>(serialized, {});
-
-  if (!preferences) {
-    return { success: false, data: null, error: 'Failed to parse preferences' };
+// Low-level storage (for other uses)
+export async function getSessionItem<T>(key: string): Promise<T | undefined> {
+  // Check memory first
+  if (memoryStorage.has(key)) {
+    return memoryStorage.get(key) as T
   }
-
-  return { success: true, data: preferences, error: null };
+  
+  // Could extend to read from separate files per key
+  return undefined
 }
 
-/**
- * Gets the timestamp of the last user activity
- *
- * @returns {Date | null} The last activity date or null if not found
- */
-export function getLastActivity(): Date | null {
-  const stored = getStorageItem(STORAGE_KEYS.LAST_ACTIVITY);
-
-  if (!stored) {
-    return null;
+export async function setSessionItem<T>(key: string, value: T): Promise<void> {
+  memoryStorage.set(key, value)
+  
+  // Persist to separate file
+  await ensureConfigDir()
+  try {
+    const filePath = join(getConfigDir(), `${key}.json`)
+    await writeFile(filePath, JSON.stringify(value, null, 2))
+  } catch (error) {
+    log('error', `Failed to persist ${key}`, error)
   }
+}
 
+export async function removeSessionItem(key: string): Promise<void> {
+  memoryStorage.delete(key)
+  
   try {
-    const date = new Date(stored);
-    return isNaN(date.getTime()) ? null : date;
+    const filePath = join(getConfigDir(), `${key}.json`)
+    await writeFile(filePath, '{}')
   } catch {
-    return null;
+    // Ignore
   }
 }
 
-/**
- * Updates the last activity timestamp to now
- *
- * @returns {boolean} True if successful
- */
-export function updateLastActivity(): boolean {
-  return setStorageItem(STORAGE_KEYS.LAST_ACTIVITY, new Date().toISOString());
-}
-
-/**
- * Checks if there is an active session in storage
- *
- * @returns {boolean} True if a valid session exists
- */
-export function hasActiveSession(): boolean {
-  const result = loadSession();
-  return result.success;
-}
-
-/**
- * Type guard to check if a value is a valid UserType
- *
- * @param {unknown} value - The value to check
- * @returns {boolean} True if the value is a valid UserType
- */
-export function isUserType(value: unknown): value is UserType {
-  return typeof value === 'string' && VALID_USER_TYPES.includes(value as UserType);
-}
-
 // Default export
 export default {
-  STORAGE_KEYS,
-  VALID_USER_TYPES,
+  // Session
   saveSession,
   loadSession,
   clearSession,
+  hasActiveSession,
+  getSessionId,
   getUserType,
-  saveMessages,
-  loadMessages,
+  isUserType,
+  isAuthenticated,
+  updateLastActivity,
+  getLastActivity,
+  
+  // Preferences
   savePreferences,
   loadPreferences,
-  getLastActivity,
-  updateLastActivity,
-  hasActiveSession,
-  isUserType,
-};
+  getPreference,
+  setPreference,
+  
+  // Messages
+  saveMessages,
+  loadMessages,
+  addMessage,
+  
+  // Low-level
+  getSessionItem,
+  setSessionItem,
+  removeSessionItem,
+}