@djangocfg/ext-base 1.0.0

package/src/config/env.ts

@@ -0,0 +1,59 @@
+/**
+ * Environment configuration utilities
+ *
+ * Safe to use in both client and server contexts.
+ * Can be imported from server-safe entry point.
+ */
+
+/**
+ * Check if running in development mode
+ */
+export const isDevelopment = process.env.NODE_ENV === 'development';
+
+/**
+ * Check if running in production mode
+ */
+export const isProduction = process.env.NODE_ENV === 'production';
+
+/**
+ * Check if running in test mode
+ */
+export const isTest = process.env.NODE_ENV === 'test';
+
+/**
+ * Check if this is a static build (Next.js export)
+ */
+export const isStaticBuild = process.env.NEXT_PUBLIC_STATIC_BUILD === 'true';
+
+/**
+ * Check if code is running on client side
+ * Safe to use in both client and server contexts
+ */
+export const isClient = typeof window !== 'undefined';
+
+/**
+ * Check if code is running on server side
+ * Safe to use in both client and server contexts
+ */
+export const isServer = !isClient;
+
+/**
+ * Get API URL from environment
+ * Returns empty string if not set
+ */
+export const getApiUrl = (): string => {
+  return process.env.NEXT_PUBLIC_API_URL || '';
+};
+
+/**
+ * Environment configuration object
+ */
+export const env = {
+  isDevelopment,
+  isProduction,
+  isTest,
+  isStaticBuild,
+  isClient,
+  isServer,
+  getApiUrl,
+} as const;

package/src/config/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Configuration utilities
+ */
+
+export * from './env';

package/src/context/ExtensionProvider.tsx

@@ -0,0 +1,102 @@
+/**
+ * Base provider wrapper with SWR configuration and auth for extensions
+ */
+
+'use client';
+
+import { useEffect } from 'react';
+import { SWRConfig } from 'swr';
+import type { ExtensionContextOptions, ExtensionProviderProps } from '../types';
+import { createExtensionLogger } from '../logger';
+import { isDevelopment } from '../config';
+
+const DEFAULT_OPTIONS: ExtensionContextOptions = {
+  revalidateOnFocus: false,
+  revalidateOnReconnect: false,
+  revalidateIfStale: false,
+};
+
+// Extension registry for debugging and tracking
+const registeredExtensions = new Set<string>();
+
+/**
+ * Base provider with SWR configuration for extension contexts
+ *
+ * Provides:
+ * - SWR configuration for data fetching
+ * - Extension registration and metadata management
+ * - Auth context from @djangocfg/api (automatically available via useAuth)
+ *
+ * @example
+ * ```tsx
+ * // In extension package:
+ * export function NewsletterProvider({ children }: { children: ReactNode }) {
+ *   return (
+ *     <ExtensionProvider
+ *       metadata={{
+ *         name: 'newsletter',
+ *         version: '1.0.0',
+ *         author: 'DjangoCFG',
+ *         displayName: 'Newsletter',
+ *         description: 'Newsletter subscription management',
+ *         icon: '📧',
+ *         license: 'MIT',
+ *         githubUrl: 'https://github.com/markolofsen/django-cfg',
+ *         keywords: ['newsletter', 'email', 'subscription'],
+ *       }}
+ *       options={{ revalidateOnFocus: true }}
+ *     >
+ *       {children}
+ *     </ExtensionProvider>
+ *   );
+ * }
+ *
+ * // In components:
+ * import { useAuth } from '@djangocfg/api/auth';
+ *
+ * function MyComponent() {
+ *   const { user, isAuthenticated } = useAuth();
+ *   // Auth is automatically available!
+ * }
+ * ```
+ */
+export function ExtensionProvider({ children, metadata, options = {} }: ExtensionProviderProps) {
+  const config = { ...DEFAULT_OPTIONS, ...options };
+
+  // Register extension on mount
+  useEffect(() => {
+    if (registeredExtensions.has(metadata.name)) {
+      if (isDevelopment) {
+        console.warn(
+          `[ExtensionProvider] Extension "${metadata.name}" is already registered. ` +
+            `This might indicate that the extension is mounted multiple times.`
+        );
+      }
+      return;
+    }
+
+    registeredExtensions.add(metadata.name);
+
+    if (isDevelopment) {
+      const logger = createExtensionLogger({ tag: 'ext-base', level: 'info' });
+      logger.info(
+        `Extension registered: ${metadata.displayName || metadata.name} v${metadata.version}`
+      );
+    }
+
+    return () => {
+      registeredExtensions.delete(metadata.name);
+    };
+  }, [metadata.name, metadata.version, metadata.displayName]);
+
+  // Note: useAuth from @djangocfg/api is automatically available
+  // No need to wrap - extensions can import and use it directly
+  return <SWRConfig value={config}>{children}</SWRConfig>;
+}
+
+/**
+ * Get all registered extensions (for debugging)
+ */
+export function getRegisteredExtensions(): string[] {
+  return Array.from(registeredExtensions);
+}

package/src/context/createExtensionContext.tsx

@@ -0,0 +1,78 @@
+/**
+ * Utility for creating typed React contexts for extensions
+ */
+
+'use client';
+
+import { createContext, useContext, type Context, type ReactNode, type ReactElement } from 'react';
+
+export interface CreateExtensionContextOptions<T> {
+  /** Display name for the context (for debugging) */
+  displayName: string;
+
+  /** Error message when hook is used outside provider */
+  errorMessage?: string;
+}
+
+export interface ExtensionContextReturn<T> {
+  /** The React Context */
+  Context: Context<T | undefined>;
+
+  /** Provider component */
+  Provider: (props: { value: T; children: ReactNode }) => ReactElement;
+
+  /** Hook to access context value */
+  useContext: () => T;
+}
+
+/**
+ * Creates a typed React context with provider and hook
+ *
+ * @example
+ * ```tsx
+ * interface MyContextValue {
+ *   data: string[];
+ *   isLoading: boolean;
+ * }
+ *
+ * const { Provider, useContext } = createExtensionContext<MyContextValue>({
+ *   displayName: 'MyContext'
+ * });
+ *
+ * // In provider component:
+ * <Provider value={{ data: [], isLoading: false }}>
+ *   {children}
+ * </Provider>
+ *
+ * // In consumer component:
+ * const { data, isLoading } = useContext();
+ * ```
+ */
+export function createExtensionContext<T>({
+  displayName,
+  errorMessage,
+}: CreateExtensionContextOptions<T>): ExtensionContextReturn<T> {
+  const Context = createContext<T | undefined>(undefined);
+  Context.displayName = displayName;
+
+  const Provider = ({ value, children }: { value: T; children: ReactNode }) => {
+    return <Context.Provider value={value}>{children}</Context.Provider>;
+  };
+
+  const useContextHook = (): T => {
+    const context = useContext(Context);
+    if (context === undefined) {
+      throw new Error(
+        errorMessage ||
+          `use${displayName} must be used within ${displayName}Provider`
+      );
+    }
+    return context;
+  };
+
+  return {
+    Context,
+    Provider,
+    useContext: useContextHook,
+  };
+}

package/src/context/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Context utilities for extension packages
+ */
+
+export { createExtensionContext } from './createExtensionContext';
+export { ExtensionProvider } from './ExtensionProvider';
+export type { ExtensionContextReturn, CreateExtensionContextOptions } from './createExtensionContext';

package/src/hooks/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Common hooks for extension packages
+ */
+
+export { useInfinitePagination } from './useInfinitePagination';
+export { usePagination } from './usePagination';

package/src/hooks/useInfinitePagination.ts

@@ -0,0 +1,117 @@
+/**
+ * Generic hook for infinite scroll pagination
+ * Works with any paginated API endpoint
+ */
+
+'use client';
+
+import useSWRInfinite from 'swr/infinite';
+import type {
+  PaginatedResponse,
+  InfinitePaginationReturn,
+  InfinitePaginationOptions,
+} from '../types';
+
+const DEFAULT_PAGE_SIZE = 20;
+
+interface UseInfinitePaginationParams<T> {
+  /** Unique key prefix for SWR cache */
+  keyPrefix: string;
+
+  /** Fetcher function that takes (page, pageSize) and returns paginated data */
+  fetcher: (page: number, pageSize: number) => Promise<PaginatedResponse<T>>;
+
+  /** Options for pagination behavior */
+  options?: InfinitePaginationOptions;
+}
+
+/**
+ * Hook for infinite scroll with automatic pagination
+ *
+ * @example
+ * ```tsx
+ * const { items, loadMore, hasMore, isLoading } = useInfinitePagination({
+ *   keyPrefix: 'tickets',
+ *   fetcher: (page, pageSize) => apiSupport.tickets.list({ page, page_size: pageSize }),
+ *   options: { pageSize: 20 }
+ * });
+ * ```
+ */
+export function useInfinitePagination<T>({
+  keyPrefix,
+  fetcher,
+  options = {},
+}: UseInfinitePaginationParams<T>): InfinitePaginationReturn<T> {
+  const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+
+  const getKey = (pageIndex: number, previousPageData: PaginatedResponse<T> | null) => {
+    // Reached the end
+    if (previousPageData && !previousPageData.has_next && !previousPageData.next) {
+      return null;
+    }
+
+    // First page, no previous data
+    if (pageIndex === 0) {
+      return [keyPrefix, 'infinite', 1, pageSize];
+    }
+
+    // Add the page number to the SWR key
+    return [keyPrefix, 'infinite', pageIndex + 1, pageSize];
+  };
+
+  const swrFetcher = async ([, , page, size]: [string, string, number, number]) => {
+    return fetcher(page, size);
+  };
+
+  const {
+    data,
+    error,
+    isLoading,
+    isValidating,
+    size,
+    setSize,
+    mutate,
+  } = useSWRInfinite<PaginatedResponse<T>>(getKey, swrFetcher, {
+    revalidateFirstPage: options.revalidateFirstPage ?? false,
+    parallel: options.parallel ?? false,
+  });
+
+  // Flatten all pages into single array
+  const items: T[] = data ? data.flatMap((page) => page.results) : [];
+
+  // Check if there are more pages
+  const hasMore = data
+    ? Boolean(data[data.length - 1]?.has_next) || Boolean(data[data.length - 1]?.next)
+    : false;
+
+  // Total count from last page
+  const totalCount = data?.[data.length - 1]?.count ?? 0;
+
+  // Loading more state
+  const isLoadingMore = Boolean(
+    isValidating && data && typeof data[size - 1] !== 'undefined'
+  );
+
+  // Function to load next page
+  const loadMore = () => {
+    if (hasMore && !isLoadingMore) {
+      setSize(size + 1);
+    }
+  };
+
+  // Refresh all pages
+  const refresh = async () => {
+    await mutate();
+  };
+
+  return {
+    items,
+    isLoading,
+    isLoadingMore,
+    error,
+    hasMore,
+    totalCount,
+    loadMore,
+    refresh,
+  };
+}

package/src/hooks/usePagination.ts

@@ -0,0 +1,155 @@
+/**
+ * Generic hook for standard pagination
+ * Works with any paginated API endpoint
+ */
+
+'use client';
+
+import { useState, useCallback } from 'react';
+import useSWR from 'swr';
+import type { PaginatedResponse, PaginationParams, PaginationState } from '../types';
+
+const DEFAULT_PAGE_SIZE = 20;
+
+interface UsePaginationParams<T> {
+  /** Unique key prefix for SWR cache */
+  keyPrefix: string;
+
+  /** Fetcher function that takes pagination params and returns paginated data */
+  fetcher: (params: PaginationParams) => Promise<PaginatedResponse<T>>;
+
+  /** Initial page number (default: 1) */
+  initialPage?: number;
+
+  /** Items per page (default: 20) */
+  pageSize?: number;
+
+  /** Initial ordering */
+  initialOrdering?: string;
+}
+
+interface UsePaginationReturn<T> {
+  /** Current page items */
+  items: T[];
+
+  /** Pagination state */
+  pagination: PaginationState;
+
+  /** Loading state */
+  isLoading: boolean;
+
+  /** Error state */
+  error: any;
+
+  /** Go to specific page */
+  goToPage: (page: number) => void;
+
+  /** Go to next page */
+  nextPage: () => void;
+
+  /** Go to previous page */
+  previousPage: () => void;
+
+  /** Change page size */
+  setPageSize: (size: number) => void;
+
+  /** Change ordering */
+  setOrdering: (ordering: string) => void;
+
+  /** Refresh current page */
+  refresh: () => Promise<void>;
+}
+
+/**
+ * Hook for standard pagination with page controls
+ *
+ * @example
+ * ```tsx
+ * const { items, pagination, goToPage, nextPage } = usePagination({
+ *   keyPrefix: 'campaigns',
+ *   fetcher: (params) => apiNewsletter.campaigns.list(params),
+ *   pageSize: 10
+ * });
+ * ```
+ */
+export function usePagination<T>({
+  keyPrefix,
+  fetcher,
+  initialPage = 1,
+  pageSize: initialPageSize = DEFAULT_PAGE_SIZE,
+  initialOrdering,
+}: UsePaginationParams<T>): UsePaginationReturn<T> {
+  const [page, setPage] = useState(initialPage);
+  const [pageSize, setPageSizeState] = useState(initialPageSize);
+  const [ordering, setOrdering] = useState<string | undefined>(initialOrdering);
+
+  const params: PaginationParams = {
+    page,
+    page_size: pageSize,
+    ordering,
+  };
+
+  const { data, error, isLoading, mutate } = useSWR(
+    [keyPrefix, 'paginated', params],
+    () => fetcher(params),
+    {
+      revalidateOnFocus: false,
+      revalidateIfStale: false,
+    }
+  );
+
+  const items = data?.results ?? [];
+  const totalCount = data?.count ?? 0;
+  const totalPages = Math.ceil(totalCount / pageSize);
+  const hasNext = data?.has_next ?? Boolean(data?.next);
+  const hasPrevious = data?.has_previous ?? Boolean(data?.previous);
+
+  const pagination: PaginationState = {
+    page,
+    pageSize,
+    totalCount,
+    totalPages,
+    hasNext,
+    hasPrevious,
+  };
+
+  const goToPage = useCallback((newPage: number) => {
+    if (newPage >= 1 && newPage <= totalPages) {
+      setPage(newPage);
+    }
+  }, [totalPages]);
+
+  const nextPage = useCallback(() => {
+    if (hasNext) {
+      setPage((prev) => prev + 1);
+    }
+  }, [hasNext]);
+
+  const previousPage = useCallback(() => {
+    if (hasPrevious) {
+      setPage((prev) => Math.max(1, prev - 1));
+    }
+  }, [hasPrevious]);
+
+  const setPageSize = useCallback((newSize: number) => {
+    setPageSizeState(newSize);
+    setPage(1); // Reset to first page when changing page size
+  }, []);
+
+  const refresh = useCallback(async () => {
+    await mutate();
+  }, [mutate]);
+
+  return {
+    items,
+    pagination,
+    isLoading,
+    error,
+    goToPage,
+    nextPage,
+    previousPage,
+    setPageSize,
+    setOrdering,
+    refresh,
+  };
+}

package/src/hooks.ts

@@ -0,0 +1,17 @@
+/**
+ * @djangocfg/ext-base/hooks
+ *
+ * Client-only hooks and components for extension packages.
+ * Use this entry point in client components only.
+ */
+
+'use client';
+
+// Re-export everything from main entry (server-safe)
+export * from './index';
+
+// Client-only hooks
+export * from './hooks';
+
+// Client-only context utilities
+export * from './context';

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @djangocfg/ext-base
+ *
+ * Base utilities for extension packages.
+ * Server-safe entry point - can be used in both server and client components.
+ */
+
+// Types
+export type * from './types';
+
+// Config
+export * from './config';
+
+// API
+export * from './api';
+
+// Utils
+export * from './utils';
+
+// Logger
+export * from './logger';

package/src/logger/createExtensionLogger.ts

@@ -0,0 +1,61 @@
+/**
+ * Logger factory for extension packages
+ */
+
+import { createConsola } from 'consola';
+import type { ExtensionLogger, LoggerOptions } from '../types';
+
+const isDevelopment = process.env.NODE_ENV === 'development';
+
+const LEVEL_MAP = {
+  debug: 4,
+  info: 3,
+  warn: 2,
+  error: 1,
+} as const;
+
+/**
+ * Creates a tagged logger for an extension
+ *
+ * @example
+ * ```ts
+ * // In extension package
+ * export const logger = createExtensionLogger({
+ *   tag: 'ext-newsletter',
+ *   level: 'info'
+ * });
+ *
+ * // Usage
+ * logger.info('Campaign created:', campaignId);
+ * logger.error('Failed to send campaign:', error);
+ * ```
+ */
+export function createExtensionLogger(options: LoggerOptions): ExtensionLogger {
+  const { tag, level = 'info', enabled = true } = options;
+
+  if (!enabled) {
+    // Return no-op logger if disabled
+    const noop = () => {};
+    return {
+      info: noop,
+      warn: noop,
+      error: noop,
+      debug: noop,
+      success: noop,
+    };
+  }
+
+  const logLevel = isDevelopment ? LEVEL_MAP[level] : LEVEL_MAP.error;
+
+  const consola = createConsola({
+    level: logLevel,
+  }).withTag(tag);
+
+  return {
+    info: (...args: unknown[]) => consola.info(...(args as [any, ...any[]])),
+    warn: (...args: unknown[]) => consola.warn(...(args as [any, ...any[]])),
+    error: (...args: unknown[]) => consola.error(...(args as [any, ...any[]])),
+    debug: (...args: unknown[]) => consola.debug(...(args as [any, ...any[]])),
+    success: (...args: unknown[]) => consola.success(...(args as [any, ...any[]])),
+  };
+}

package/src/logger/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Logger utilities for extension packages
+ */
+
+export { createExtensionLogger } from './createExtensionLogger';