@allternit/gizzi-code 1.0.0

package/src/utils/sessionStorage.js

@@ -0,0 +1,435 @@
+/**
+ * @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.
+ */
+/**
+ * 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',
+};
+/**
+ * Valid user types for runtime validation
+ * @constant {readonly UserType[]}
+ */
+export const VALID_USER_TYPES = [
+    'anonymous',
+    'free',
+    'pro',
+    'enterprise',
+    'admin',
+];
+/**
+ * Checks if localStorage/sessionStorage is available
+ * @returns {boolean} True if storage APIs are available
+ */
+function isStorageAvailable() {
+    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;
+    }
+}
+/**
+ * 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(json, defaultValue) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return defaultValue ?? null;
+    }
+}
+/**
+ * Safely stringifies JSON with error handling
+ *
+ * @param {unknown} value - Value to stringify
+ * @returns {string | null} JSON string or null on error
+ */
+function safeJsonStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * In-memory fallback storage when sessionStorage is unavailable
+ * @constant {Map<string, string>}
+ */
+const memoryStorage = 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) {
+    if (isStorageAvailable()) {
+        return window.sessionStorage.getItem(key);
+    }
+    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, value) {
+    try {
+        if (isStorageAvailable()) {
+            window.sessionStorage.setItem(key, value);
+        }
+        else {
+            memoryStorage.set(key, value);
+        }
+        return true;
+    }
+    catch (error) {
+        console.error(`Failed to set storage item '${key}':`, error);
+        return false;
+    }
+}
+/**
+ * Removes an item from storage
+ *
+ * @param {string} key - Storage key to remove
+ * @returns {boolean} True if successful
+ */
+function removeStorageItem(key) {
+    try {
+        if (isStorageAvailable()) {
+            window.sessionStorage.removeItem(key);
+        }
+        else {
+            memoryStorage.delete(key);
+        }
+        return true;
+    }
+    catch (error) {
+        console.error(`Failed to remove storage item '${key}':`, error);
+        return false;
+    }
+}
+/**
+ * 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, options = {}) {
+    if (!session) {
+        return { success: false, data: null, error: 'Session is required' };
+    }
+    const existingMetadata = loadSessionMetadata();
+    const metadata = {
+        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 = {
+        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 };
+}
+/**
+ * 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() {
+    const serialized = getStorageItem(STORAGE_KEYS.SESSION);
+    if (!serialized) {
+        return { success: false, data: null, error: 'No session found in storage' };
+    }
+    const data = safeJsonParse(serialized);
+    if (!data) {
+        return { success: false, data: null, error: 'Failed to parse session data' };
+    }
+    // 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' };
+        }
+    }
+    // Update last activity
+    const updatedMetadata = {
+        ...data.metadata,
+        lastActivity: new Date().toISOString(),
+    };
+    // Silently update last activity in storage
+    const updatedData = { ...data, metadata: updatedMetadata };
+    const serializedUpdated = safeJsonStringify(updatedData);
+    if (serializedUpdated) {
+        setStorageItem(STORAGE_KEYS.SESSION, serializedUpdated);
+    }
+    return { success: true, data: updatedData, error: null };
+}
+/**
+ * Clears all session data from storage
+ *
+ * @returns {boolean} True if successful
+ * @example
+ * ```typescript
+ * clearSession(); // Logs out the user
+ * ```
+ */
+export function clearSession() {
+    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;
+        }
+    }
+    // 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() {
+    const stored = getStorageItem(STORAGE_KEYS.USER_TYPE);
+    if (stored && VALID_USER_TYPES.includes(stored)) {
+        return stored;
+    }
+    // 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)) {
+            return sessionType;
+        }
+    }
+    return 'anonymous';
+}
+/**
+ * Loads session metadata without loading the full session
+ *
+ * @returns {SessionMetadata | null} The metadata or null if not found
+ */
+function loadSessionMetadata() {
+    const sessionResult = loadSession();
+    if (sessionResult.success && sessionResult.data) {
+        return sessionResult.data.metadata;
+    }
+    return null;
+}
+/**
+ * Saves messages to session storage
+ *
+ * @param {TypedMessage[]} messages - Messages to save
+ * @returns {StorageResult<void>} Result of the operation
+ */
+export function saveMessages(messages) {
+    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 };
+}
+/**
+ * Loads messages from session storage
+ *
+ * @returns {StorageResult<TypedMessage[]>} The loaded messages or error
+ */
+export function loadMessages() {
+    const serialized = getStorageItem(STORAGE_KEYS.MESSAGES);
+    if (!serialized) {
+        return { success: false, data: null, error: 'No messages found in storage' };
+    }
+    const messages = safeJsonParse(serialized, []);
+    if (!messages) {
+        return { success: false, data: null, error: 'Failed to parse messages' };
+    }
+    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) {
+    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' };
+    }
+    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() {
+    const serialized = getStorageItem(STORAGE_KEYS.PREFERENCES);
+    if (!serialized) {
+        return { success: false, data: null, error: 'No preferences found in storage' };
+    }
+    const preferences = safeJsonParse(serialized, {});
+    if (!preferences) {
+        return { success: false, data: null, error: 'Failed to parse preferences' };
+    }
+    return { success: true, data: preferences, error: null };
+}
+/**
+ * Gets the timestamp of the last user activity
+ *
+ * @returns {Date | null} The last activity date or null if not found
+ */
+export function getLastActivity() {
+    const stored = getStorageItem(STORAGE_KEYS.LAST_ACTIVITY);
+    if (!stored) {
+        return null;
+    }
+    try {
+        const date = new Date(stored);
+        return isNaN(date.getTime()) ? null : date;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Updates the last activity timestamp to now
+ *
+ * @returns {boolean} True if successful
+ */
+export function updateLastActivity() {
+    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() {
+    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) {
+    return typeof value === 'string' && VALID_USER_TYPES.includes(value);
+}
+// Default export
+export default {
+    STORAGE_KEYS,
+    VALID_USER_TYPES,
+    saveSession,
+    loadSession,
+    clearSession,
+    getUserType,
+    saveMessages,
+    loadMessages,
+    savePreferences,
+    loadPreferences,
+    getLastActivity,
+    updateLastActivity,
+    hasActiveSession,
+    isUserType,
+};