@djangocfg/ext-knowbase 1.0.0

package/src/api/generated/ext_knowbase/storage.ts

@@ -0,0 +1,161 @@
+/**
+ * Storage adapters for cross-platform token storage.
+ *
+ * Supports:
+ * - LocalStorage (browser)
+ * - Cookies (SSR/browser)
+ * - Memory (Node.js/Electron/testing)
+ */
+
+import type { APILogger } from './logger';
+
+/**
+ * Storage adapter interface for cross-platform token storage.
+ */
+export interface StorageAdapter {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+/**
+ * LocalStorage adapter with safe try-catch for browser environments.
+ * Works in modern browsers with localStorage support.
+ * 
+ * Note: This adapter uses window.localStorage and should only be used in browser/client environments.
+ * For server-side usage, use MemoryStorageAdapter or CookieStorageAdapter instead.
+ */
+export class LocalStorageAdapter implements StorageAdapter {
+  private logger?: APILogger;
+
+  constructor(logger?: APILogger) {
+    this.logger = logger;
+  }
+
+  getItem(key: string): string | null {
+    try {
+      if (typeof window !== 'undefined' && window.localStorage) {
+        const value = localStorage.getItem(key);
+        this.logger?.debug(`LocalStorage.getItem("${key}"): ${value ? 'found' : 'not found'}`);
+        return value;
+      }
+      this.logger?.warn('LocalStorage not available: window.localStorage is undefined');
+    } catch (error) {
+      this.logger?.error('LocalStorage.getItem failed:', error);
+    }
+    return null;
+  }
+
+  setItem(key: string, value: string): void {
+    try {
+      if (typeof window !== 'undefined' && window.localStorage) {
+        localStorage.setItem(key, value);
+        this.logger?.debug(`LocalStorage.setItem("${key}"): success`);
+      } else {
+        this.logger?.warn('LocalStorage not available: window.localStorage is undefined');
+      }
+    } catch (error) {
+      this.logger?.error('LocalStorage.setItem failed:', error);
+    }
+  }
+
+  removeItem(key: string): void {
+    try {
+      if (typeof window !== 'undefined' && window.localStorage) {
+        localStorage.removeItem(key);
+        this.logger?.debug(`LocalStorage.removeItem("${key}"): success`);
+      } else {
+        this.logger?.warn('LocalStorage not available: window.localStorage is undefined');
+      }
+    } catch (error) {
+      this.logger?.error('LocalStorage.removeItem failed:', error);
+    }
+  }
+}
+
+/**
+ * Cookie-based storage adapter for SSR and browser environments.
+ * Useful for Next.js, Nuxt.js, and other SSR frameworks.
+ */
+export class CookieStorageAdapter implements StorageAdapter {
+  private logger?: APILogger;
+
+  constructor(logger?: APILogger) {
+    this.logger = logger;
+  }
+
+  getItem(key: string): string | null {
+    try {
+      if (typeof document === 'undefined') {
+        this.logger?.warn('Cookies not available: document is undefined (SSR context?)');
+        return null;
+      }
+      const value = `; ${document.cookie}`;
+      const parts = value.split(`; ${key}=`);
+      if (parts.length === 2) {
+        const result = parts.pop()?.split(';').shift() || null;
+        this.logger?.debug(`CookieStorage.getItem("${key}"): ${result ? 'found' : 'not found'}`);
+        return result;
+      }
+      this.logger?.debug(`CookieStorage.getItem("${key}"): not found`);
+    } catch (error) {
+      this.logger?.error('CookieStorage.getItem failed:', error);
+    }
+    return null;
+  }
+
+  setItem(key: string, value: string): void {
+    try {
+      if (typeof document !== 'undefined') {
+        document.cookie = `${key}=${value}; path=/; max-age=31536000`;
+        this.logger?.debug(`CookieStorage.setItem("${key}"): success`);
+      } else {
+        this.logger?.warn('Cookies not available: document is undefined (SSR context?)');
+      }
+    } catch (error) {
+      this.logger?.error('CookieStorage.setItem failed:', error);
+    }
+  }
+
+  removeItem(key: string): void {
+    try {
+      if (typeof document !== 'undefined') {
+        document.cookie = `${key}=; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT`;
+        this.logger?.debug(`CookieStorage.removeItem("${key}"): success`);
+      } else {
+        this.logger?.warn('Cookies not available: document is undefined (SSR context?)');
+      }
+    } catch (error) {
+      this.logger?.error('CookieStorage.removeItem failed:', error);
+    }
+  }
+}
+
+/**
+ * In-memory storage adapter for Node.js, Electron, and testing environments.
+ * Data is stored in RAM and cleared when process exits.
+ */
+export class MemoryStorageAdapter implements StorageAdapter {
+  private storage: Map<string, string> = new Map();
+  private logger?: APILogger;
+
+  constructor(logger?: APILogger) {
+    this.logger = logger;
+  }
+
+  getItem(key: string): string | null {
+    const value = this.storage.get(key) || null;
+    this.logger?.debug(`MemoryStorage.getItem("${key}"): ${value ? 'found' : 'not found'}`);
+    return value;
+  }
+
+  setItem(key: string, value: string): void {
+    this.storage.set(key, value);
+    this.logger?.debug(`MemoryStorage.setItem("${key}"): success`);
+  }
+
+  removeItem(key: string): void {
+    this.storage.delete(key);
+    this.logger?.debug(`MemoryStorage.removeItem("${key}"): success`);
+  }
+}

package/src/api/generated/ext_knowbase/validation-events.ts

@@ -0,0 +1,133 @@
+/**
+ * Zod Validation Events - Browser CustomEvent integration
+ *
+ * Dispatches browser CustomEvents when Zod validation fails, allowing
+ * React/frontend apps to listen and handle validation errors globally.
+ *
+ * @example
+ * ```typescript
+ * // In your React app
+ * window.addEventListener('zod-validation-error', (event) => {
+ *   const { operation, path, method, error, response } = event.detail;
+ *   console.error(`Validation failed for ${method} ${path}`, error);
+ *   // Show toast notification, log to Sentry, etc.
+ * });
+ * ```
+ */
+
+import type { ZodError } from 'zod'
+
+/**
+ * Validation error event detail
+ */
+export interface ValidationErrorDetail {
+  /** Operation/function name that failed validation */
+  operation: string
+  /** API endpoint path */
+  path: string
+  /** HTTP method */
+  method: string
+  /** Zod validation error */
+  error: ZodError
+  /** Raw response data that failed validation */
+  response: any
+  /** Timestamp of the error */
+  timestamp: Date
+}
+
+/**
+ * Custom event type for Zod validation errors
+ */
+export type ValidationErrorEvent = CustomEvent<ValidationErrorDetail>
+
+/**
+ * Dispatch a Zod validation error event.
+ *
+ * Only dispatches in browser environment (when window is defined).
+ * Safe to call in Node.js/SSR - will be a no-op.
+ *
+ * @param detail - Validation error details
+ */
+export function dispatchValidationError(detail: ValidationErrorDetail): void {
+  // Check if running in browser
+  if (typeof window === 'undefined') {
+    return
+  }
+
+  try {
+    const event = new CustomEvent<ValidationErrorDetail>('zod-validation-error', {
+      detail,
+      bubbles: true,
+      cancelable: false,
+    })
+
+    window.dispatchEvent(event)
+  } catch (error) {
+    // Silently fail - validation event dispatch should never crash the app
+    console.warn('Failed to dispatch validation error event:', error)
+  }
+}
+
+/**
+ * Add a global listener for Zod validation errors.
+ *
+ * @param callback - Function to call when validation error occurs
+ * @returns Cleanup function to remove the listener
+ *
+ * @example
+ * ```typescript
+ * const cleanup = onValidationError(({ operation, error }) => {
+ *   toast.error(`Validation failed in ${operation}`);
+ *   logToSentry(error);
+ * });
+ *
+ * // Later, remove listener
+ * cleanup();
+ * ```
+ */
+export function onValidationError(
+  callback: (detail: ValidationErrorDetail) => void
+): () => void {
+  if (typeof window === 'undefined') {
+    // Return no-op cleanup function for SSR
+    return () => {}
+  }
+
+  const handler = (event: Event) => {
+    if (event instanceof CustomEvent) {
+      callback(event.detail)
+    }
+  }
+
+  window.addEventListener('zod-validation-error', handler)
+
+  // Return cleanup function
+  return () => {
+    window.removeEventListener('zod-validation-error', handler)
+  }
+}
+
+/**
+ * Format Zod error for logging/display.
+ *
+ * @param error - Zod validation error
+ * @returns Formatted error message
+ */
+export function formatZodError(error: ZodError): string {
+  const issues = error.issues.map((issue, index) => {
+    const path = issue.path.join('.') || 'root'
+    const parts = [`${index + 1}. ${path}: ${issue.message}`]
+
+    if ('expected' in issue && issue.expected) {
+      parts.push(`   Expected: ${issue.expected}`)
+    }
+
+    if ('received' in issue && issue.received) {
+      parts.push(`   Received: ${issue.received}`)
+    }
+
+    return parts.join('\n')
+  })
+
+  return issues.join('\n')
+}

package/src/api/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Knowbase Extension API
+ *
+ * Pre-configured API instance with shared authentication
+ */
+import { API } from './generated/ext_knowbase';
+import { createExtensionAPI } from '@djangocfg/ext-base/api';
+
+export const apiKnowbase = createExtensionAPI(API);

package/src/components/Chat/ChatUIContext.tsx

@@ -0,0 +1,110 @@
+/**
+ * Chat UI Context
+ * Manages UI state for chat widget (toggle, expand, minimize)
+ */
+
+'use client';
+
+import React, { createContext, useContext, useState, useCallback, type ReactNode } from 'react';
+import type { ChatUIState } from './types';
+
+// ─────────────────────────────────────────────────────────────────────────
+// Context Type
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface ChatUIContextValue {
+  uiState: ChatUIState;
+  toggleChat: () => void;
+  openChat: () => void;
+  closeChat: () => void;
+  expandChat: () => void;
+  collapseChat: () => void;
+  minimizeChat: () => void;
+  toggleSources: () => void;
+  toggleTimestamps: () => void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Context
+// ─────────────────────────────────────────────────────────────────────────
+
+const ChatUIContext = createContext<ChatUIContextValue | undefined>(undefined);
+
+// ─────────────────────────────────────────────────────────────────────────
+// Provider
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface ChatUIProviderProps {
+  children: ReactNode;
+  initialState?: Partial<ChatUIState>;
+}
+
+export function ChatUIProvider({ children, initialState }: ChatUIProviderProps) {
+  const [uiState, setUIState] = useState<ChatUIState>({
+    isOpen: false,
+    isExpanded: false,
+    isMinimized: false,
+    showSources: true,
+    showTimestamps: false,
+    ...initialState,
+  });
+
+  const toggleChat = useCallback(() => {
+    setUIState((prev) => ({ ...prev, isOpen: !prev.isOpen }));
+  }, []);
+
+  const openChat = useCallback(() => {
+    setUIState((prev) => ({ ...prev, isOpen: true }));
+  }, []);
+
+  const closeChat = useCallback(() => {
+    setUIState((prev) => ({ ...prev, isOpen: false }));
+  }, []);
+
+  const expandChat = useCallback(() => {
+    setUIState((prev) => ({ ...prev, isExpanded: true, isMinimized: false }));
+  }, []);
+
+  const collapseChat = useCallback(() => {
+    setUIState((prev) => ({ ...prev, isExpanded: false }));
+  }, []);
+
+  const minimizeChat = useCallback(() => {
+    setUIState((prev) => ({ ...prev, isMinimized: true, isExpanded: false }));
+  }, []);
+
+  const toggleSources = useCallback(() => {
+    setUIState((prev) => ({ ...prev, showSources: !prev.showSources }));
+  }, []);
+
+  const toggleTimestamps = useCallback(() => {
+    setUIState((prev) => ({ ...prev, showTimestamps: !prev.showTimestamps }));
+  }, []);
+
+  const value: ChatUIContextValue = {
+    uiState,
+    toggleChat,
+    openChat,
+    closeChat,
+    expandChat,
+    collapseChat,
+    minimizeChat,
+    toggleSources,
+    toggleTimestamps,
+  };
+
+  return <ChatUIContext.Provider value={value}>{children}</ChatUIContext.Provider>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────
+
+export function useChatUI(): ChatUIContextValue {
+  const context = useContext(ChatUIContext);
+  if (!context) {
+    throw new Error('useChatUI must be used within ChatUIProvider');
+  }
+  return context;
+}
+