/**
 * Thin JSON-typed Web-Storage adapter (localStorage or sessionStorage).
 *
 * Centralizes the SSR-guard + try/catch + silent quota-failure pattern
 * that every per-feature storage util would otherwise re-implement.
 *
 * Optional `namespace` prefix supports platform / user partitioning —
 * the resolver runs lazily at call time so the namespace can vary across
 * the lifetime of the page (e.g. proxy-auth switches user, which switches
 * the key suffix).
 *
 * Backend selection (`backend: 'local' | 'session'`):
 *   - `'local'` (default): persists across browser sessions. Use for
 *     UI state, chat history metadata, feature-flag opt-ins.
 *   - `'session'`: cleared when the tab closes. Use for ANY auth-adjacent
 *     value (bearer tokens, act-as identity, proxy credentials). Reduces
 *     the XSS-exfiltration attack window from "indefinite" to "until tab
 *     close" without losing per-session ergonomics.
 */

export type WebStorageBackend = 'local' | 'session'

export interface LocalStorageAdapter<T> {
  load(): T | null
  save(value: T): void
  clear(): void
  /** Resolved storage key for the current call. Useful for tests. */
  resolveKey(): string
}

export interface LocalStorageAdapterOptions<T> {
  /** Base storage key. Combined with `namespace()` when provided. */
  key: string
  /** Optional dynamic namespace prefix appended via `.` separator.
   *  Called on EVERY read/write so the key can vary across the page
   *  lifetime (e.g. when the platform or user identity changes). */
  namespace?: () => string | null | undefined
  /** Runtime shape check. Falsey return → `load()` yields null. */
  validate?: (parsed: unknown) => parsed is T
  /** Diagnostic prefix written to `console.warn` on parse / write
   *  failures. Defaults to `'[local-storage]'`. */
  logTag?: string
  /** Which Web-Storage backend to use. Defaults to `'local'`. Pass
   *  `'session'` for anything auth-adjacent so the value evaporates
   *  when the tab closes. */
  backend?: WebStorageBackend
}

function getStorage(backend: WebStorageBackend): Storage | null {
  if (typeof window === 'undefined') return null
  try {
    return backend === 'session' ? window.sessionStorage : window.localStorage
  } catch {
    // Some sandboxed contexts (Safari private mode older versions,
    // strict CSP) throw on storage access — treat as unavailable.
    return null
  }
}

export function createLocalStorageAdapter<T>(
  options: LocalStorageAdapterOptions<T>,
): LocalStorageAdapter<T> {
  const tag = options.logTag ?? '[local-storage]'
  const backend: WebStorageBackend = options.backend ?? 'local'
  const resolveKey = (): string => {
    const ns = options.namespace?.()
    return ns ? `${ns}.${options.key}` : options.key
  }

  return {
    resolveKey,
    load() {
      const storage = getStorage(backend)
      if (!storage) return null
      try {
        const raw = storage.getItem(resolveKey())
        if (!raw) return null
        const parsed = JSON.parse(raw) as unknown
        if (options.validate && !options.validate(parsed)) return null
        return parsed as T
      } catch (err) {
        console.warn(`${tag} parse failed for key ${resolveKey()}:`, err)
        return null
      }
    },
    save(value: T) {
      const storage = getStorage(backend)
      if (!storage) return
      try {
        storage.setItem(resolveKey(), JSON.stringify(value))
      } catch (err) {
        console.warn(`${tag} write failed for key ${resolveKey()}:`, err)
      }
    },
    clear() {
      const storage = getStorage(backend)
      if (!storage) return
      try {
        storage.removeItem(resolveKey())
      } catch (err) {
        console.warn(`${tag} clear failed for key ${resolveKey()}:`, err)
      }
    },
  }
}