@djangocfg/ext-support 1.0.0

package/src/api/generated/ext_support/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_support/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 @@
+/**
+ * Support Extension API
+ *
+ * Pre-configured API instance with shared authentication
+ */
+import { API } from './generated/ext_support';
+import { createExtensionAPI } from '@djangocfg/ext-base/api';
+
+export const apiSupport = createExtensionAPI(API);

package/src/config.ts

@@ -0,0 +1,20 @@
+/**
+ * Support extension configuration
+ */
+
+import type { ExtensionMetadata } from '@djangocfg/ext-base';
+
+export const extensionConfig: ExtensionMetadata = {
+  name: 'support',
+  version: '1.0.0',
+  author: 'DjangoCFG',
+  displayName: 'Support',
+  description: 'Customer support and ticketing system',
+  icon: '🎫',
+  license: 'MIT',
+  githubUrl: 'https://github.com/markolofsen/django-cfg',
+  homepage: 'https://djangocfg.com',
+  keywords: ['support', 'tickets', 'helpdesk', 'customer-service'],
+  dependencies: [],
+  minVersion: '2.0.0',
+} as const;

package/src/contexts/SupportContext.tsx

@@ -0,0 +1,250 @@
+'use client';
+
+import React, { createContext, useContext, type ReactNode } from 'react';
+import {
+  useSupportTicketsList,
+  useSupportTicketsRetrieve,
+  useCreateSupportTicketsCreate,
+  useUpdateSupportTicketsUpdate,
+  usePartialUpdateSupportTicketsPartialUpdate,
+  useDeleteSupportTicketsDestroy,
+  useSupportTicketsMessagesList,
+  useSupportTicketsMessagesRetrieve,
+  useCreateSupportTicketsMessagesCreate,
+  useUpdateSupportTicketsMessagesUpdate,
+  usePartialUpdateSupportTicketsMessagesPartialUpdate,
+  useDeleteSupportTicketsMessagesDestroy,
+} from '../api/generated/ext_support/_utils/hooks';
+import type {
+  Ticket,
+  TicketRequest,
+  PatchedTicketRequest,
+  Message,
+  MessageRequest,
+  MessageCreateRequest,
+  PatchedMessageRequest,
+} from './types';
+
+// ─────────────────────────────────────────────────────────────────────────
+// Context Type
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface SupportContextValue {
+  // Tickets
+  tickets: Ticket[] | undefined;
+  isLoadingTickets: boolean;
+  ticketsError: Error | undefined;
+  refreshTickets: () => Promise<void>;
+
+  // Ticket operations
+  getTicket: (uuid: string) => Promise<Ticket | undefined>;
+  createTicket: (data: TicketRequest) => Promise<Ticket>;
+  updateTicket: (uuid: string, data: TicketRequest) => Promise<Ticket>;
+  partialUpdateTicket: (uuid: string, data: PatchedTicketRequest) => Promise<Ticket>;
+  deleteTicket: (uuid: string) => Promise<void>;
+
+  // Messages
+  getMessages: (ticketUuid: string) => Promise<Message[] | undefined>;
+  getMessage: (ticketUuid: string, messageUuid: string) => Promise<Message | undefined>;
+  createMessage: (ticketUuid: string, data: MessageCreateRequest) => Promise<Message>;
+  updateMessage: (ticketUuid: string, messageUuid: string, data: MessageRequest) => Promise<Message>;
+  partialUpdateMessage: (
+    ticketUuid: string,
+    messageUuid: string,
+    data: PatchedMessageRequest
+  ) => Promise<Message>;
+  deleteMessage: (ticketUuid: string, messageUuid: string) => Promise<void>;
+  refreshMessages: (ticketUuid: string) => Promise<void>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Context
+// ─────────────────────────────────────────────────────────────────────────
+
+const SupportContext = createContext<SupportContextValue | undefined>(undefined);
+
+// ─────────────────────────────────────────────────────────────────────────
+// Provider
+// ─────────────────────────────────────────────────────────────────────────
+
+export function SupportProvider({ children }: { children: ReactNode }) {
+  // List tickets (first page only for count)
+  const {
+    data: ticketsData,
+    error: ticketsError,
+    isLoading: isLoadingTickets,
+    mutate: mutateTickets,
+  } = useSupportTicketsList({ page: 1, page_size: 1 });
+
+  const refreshTickets = async () => {
+    await mutateTickets();
+  };
+
+  // Ticket mutations
+  const createTicketMutation = useCreateSupportTicketsCreate();
+  const updateTicketMutation = useUpdateSupportTicketsUpdate();
+  const partialUpdateTicketMutation = usePartialUpdateSupportTicketsPartialUpdate();
+  const deleteTicketMutation = useDeleteSupportTicketsDestroy();
+
+  // Message mutations
+  const createMessageMutation = useCreateSupportTicketsMessagesCreate();
+  const updateMessageMutation = useUpdateSupportTicketsMessagesUpdate();
+  const partialUpdateMessageMutation = usePartialUpdateSupportTicketsMessagesPartialUpdate();
+  const deleteMessageMutation = useDeleteSupportTicketsMessagesDestroy();
+
+  // Get single ticket
+  const getTicket = async (uuid: string): Promise<Ticket | undefined> => {
+    const { data } = useSupportTicketsRetrieve(uuid);
+    return data;
+  };
+
+  // Create ticket
+  const createTicket = async (data: TicketRequest): Promise<Ticket> => {
+    const result = await createTicketMutation(data);
+    await refreshTickets();
+    return result as Ticket;
+  };
+
+  // Update ticket
+  const updateTicket = async (uuid: string, data: TicketRequest): Promise<Ticket> => {
+    const result = await updateTicketMutation(uuid, data);
+    await refreshTickets();
+    return result as Ticket;
+  };
+
+  // Partial update ticket (currently not supported by generated API)
+  const partialUpdateTicket = async (
+    uuid: string,
+    data: PatchedTicketRequest
+  ): Promise<Ticket> => {
+    // TODO: Fix generator to include data parameter for PATCH requests
+    // const result = await partialUpdateTicketMutation(uuid, data);
+    // For now, fallback to full update
+    const result = await updateTicketMutation(uuid, data as unknown as TicketRequest);
+    await refreshTickets();
+    return result as Ticket;
+  };
+
+  // Delete ticket
+  const deleteTicket = async (uuid: string): Promise<void> => {
+    await deleteTicketMutation(uuid);
+    await refreshTickets();
+  };
+
+  // Get messages for ticket
+  const getMessages = async (ticketUuid: string): Promise<Message[] | undefined> => {
+    const { data } = useSupportTicketsMessagesList(ticketUuid, { page: 1, page_size: 100 });
+    return data?.results;
+  };
+
+  // Get single message
+  const getMessage = async (
+    ticketUuid: string,
+    messageUuid: string
+  ): Promise<Message | undefined> => {
+    const { data } = useSupportTicketsMessagesRetrieve(
+      ticketUuid,
+      messageUuid
+    );
+    return data;
+  };
+
+  // Create message
+  const createMessage = async (
+    ticketUuid: string,
+    data: MessageCreateRequest
+  ): Promise<Message> => {
+    const result = await createMessageMutation(ticketUuid, data);
+    return result as Message;
+  };
+
+  // Update message
+  const updateMessage = async (
+    ticketUuid: string,
+    messageUuid: string,
+    data: MessageRequest
+  ): Promise<Message> => {
+    const result = await updateMessageMutation(
+      ticketUuid,
+      messageUuid,
+      data
+    );
+    return result as Message;
+  };
+
+  // Partial update message (currently not supported by generated API)
+  const partialUpdateMessage = async (
+    ticketUuid: string,
+    messageUuid: string,
+    data: PatchedMessageRequest
+  ): Promise<Message> => {
+    // TODO: Fix generator to include data parameter for PATCH requests
+    // const result = await partialUpdateMessageMutation(ticketUuid, messageUuid, data);
+    // For now, fallback to full update
+    const result = await updateMessageMutation(
+      ticketUuid,
+      messageUuid,
+      data as MessageRequest
+    );
+    return result as Message;
+  };
+
+  // Delete message
+  const deleteMessage = async (ticketUuid: string, messageUuid: string): Promise<void> => {
+    await deleteMessageMutation(ticketUuid, messageUuid);
+  };
+
+  // Refresh messages for specific ticket
+  const refreshMessages = async (ticketUuid: string): Promise<void> => {
+    // We'll use mutate from the hook, but we need to get it dynamically
+    // For now, we can just refresh tickets which will update everything
+    await refreshTickets();
+  };
+
+  const value: SupportContextValue = {
+    tickets: ticketsData?.results,
+    isLoadingTickets,
+    ticketsError,
+    refreshTickets,
+    getTicket,
+    createTicket,
+    updateTicket,
+    partialUpdateTicket,
+    deleteTicket,
+    getMessages,
+    getMessage,
+    createMessage,
+    updateMessage,
+    partialUpdateMessage,
+    deleteMessage,
+    refreshMessages,
+  };
+
+  return <SupportContext.Provider value={value}>{children}</SupportContext.Provider>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────
+
+export function useSupportContext(): SupportContextValue {
+  const context = useContext(SupportContext);
+  if (!context) {
+    throw new Error('useSupportContext must be used within SupportProvider');
+  }
+  return context;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Re-export types for external use
+// ─────────────────────────────────────────────────────────────────────────
+
+export type {
+  Ticket,
+  TicketRequest,
+  PatchedTicketRequest,
+  Message,
+  MessageRequest,
+  MessageCreateRequest,
+  PatchedMessageRequest,
+} from './types';

package/src/contexts/SupportExtensionProvider.tsx

@@ -0,0 +1,38 @@
+/**
+ * Main Support Extension Provider
+ *
+ * Wraps support context with ExtensionProvider for proper registration
+ */
+
+'use client';
+
+import type { ReactNode } from 'react';
+import { ExtensionProvider } from '@djangocfg/ext-base/hooks';
+import { extensionConfig } from '../config';
+import { SupportProvider } from './SupportContext';
+
+interface SupportExtensionProviderProps {
+  children: ReactNode;
+}
+
+/**
+ * Main provider for Support extension
+ *
+ * Provides support context for ticket management
+ *
+ * @example
+ * ```tsx
+ * <SupportExtensionProvider>
+ *   <YourApp />
+ * </SupportExtensionProvider>
+ * ```
+ */
+export function SupportExtensionProvider({ children }: SupportExtensionProviderProps) {
+  return (
+    <ExtensionProvider metadata={extensionConfig}>
+      <SupportProvider>
+        {children}
+      </SupportProvider>
+    </ExtensionProvider>
+  );
+}

package/src/contexts/types.ts

@@ -0,0 +1,26 @@
+/**
+ * Support Types
+ * Centralized type definitions for support context
+ */
+
+import type {
+  useSupportTicketsRetrieve,
+  useUpdateSupportTicketsUpdate,
+  usePartialUpdateSupportTicketsPartialUpdate,
+  useSupportTicketsMessagesRetrieve,
+  useUpdateSupportTicketsMessagesUpdate,
+  useCreateSupportTicketsMessagesCreate,
+  usePartialUpdateSupportTicketsMessagesPartialUpdate,
+} from '../api/generated/ext_support/_utils/hooks';
+
+// ─────────────────────────────────────────────────────────────────────────
+// Support Types
+// ─────────────────────────────────────────────────────────────────────────
+
+export type Ticket = NonNullable<Awaited<ReturnType<typeof useSupportTicketsRetrieve>>['data']>;
+export type TicketRequest = Parameters<ReturnType<typeof useUpdateSupportTicketsUpdate>>[1];
+export type PatchedTicketRequest = Parameters<ReturnType<typeof usePartialUpdateSupportTicketsPartialUpdate>>[1];
+export type Message = NonNullable<Awaited<ReturnType<typeof useSupportTicketsMessagesRetrieve>>['data']>;
+export type MessageRequest = Parameters<ReturnType<typeof useUpdateSupportTicketsMessagesUpdate>>[2];
+export type MessageCreateRequest = Parameters<ReturnType<typeof useCreateSupportTicketsMessagesCreate>>[1];
+export type PatchedMessageRequest = Parameters<ReturnType<typeof usePartialUpdateSupportTicketsMessagesPartialUpdate>>[2];

package/src/hooks/index.ts

@@ -0,0 +1,33 @@
+'use client';
+
+/**
+ * @djangocfg/ext-support/hooks
+ *
+ * React hooks for support extension.
+ * Use this entry point in client components.
+ */
+
+// Re-export everything from main entry (server-safe code)
+export * from '../index';
+
+// SWR hooks from generated API
+export * from '../api/generated/ext_support/_utils/hooks';
+
+// Context and providers
+export {
+  SupportProvider,
+  useSupportContext,
+} from '../contexts/SupportContext';
+
+// Layout context hooks
+export {
+  SupportLayoutProvider,
+  useSupportLayoutContext,
+} from '../layouts/SupportLayout/context';
+
+// Layout components (they use hooks internally)
+export * from '../layouts/SupportLayout/components';
+
+// Custom hooks
+export { useInfiniteMessages } from '../layouts/SupportLayout/hooks/useInfiniteMessages';
+export { useInfiniteTickets } from '../layouts/SupportLayout/hooks/useInfiniteTickets';