@djangocfg/ext-base 1.0.0

package/src/types/context.ts

@@ -0,0 +1,93 @@
+/**
+ * Context and provider types for extension packages
+ */
+
+import type { ReactNode } from 'react';
+
+export interface ExtensionContextOptions {
+  revalidateOnFocus?: boolean;
+  revalidateOnReconnect?: boolean;
+  revalidateIfStale?: boolean;
+}
+
+export interface ExtensionMetadata {
+  /**
+   * Unique extension name (e.g., 'newsletter', 'payments')
+   */
+  name: string;
+
+  /**
+   * Extension version (semver format recommended)
+   */
+  version: string;
+
+  /**
+   * Extension author name or organization
+   */
+  author: string;
+
+  /**
+   * Extension display name
+   */
+  displayName?: string;
+
+  /**
+   * Extension description
+   */
+  description?: string;
+
+  /**
+   * GitHub repository URL
+   * @example 'https://github.com/username/repo'
+   */
+  githubUrl?: string;
+
+  /**
+   * Extension homepage URL
+   */
+  homepage?: string;
+
+  /**
+   * License identifier (e.g., 'MIT', 'Apache-2.0')
+   */
+  license?: string;
+
+  /**
+   * Keywords for search and discovery
+   */
+  keywords?: string[];
+
+  /**
+   * Extension icon URL or emoji
+   * @example '📧' or 'https://example.com/icon.png'
+   */
+  icon?: string;
+
+  /**
+   * List of extension dependencies
+   * @example ['payments', 'auth']
+   */
+  dependencies?: string[];
+
+  /**
+   * Minimum required DjangoCFG version
+   */
+  minVersion?: string;
+}
+
+export interface ExtensionProviderProps {
+  /**
+   * Extension metadata for registration
+   */
+  metadata: ExtensionMetadata;
+
+  /**
+   * SWR configuration options
+   */
+  options?: ExtensionContextOptions;
+
+  /**
+   * Child components
+   */
+  children: ReactNode;
+}

package/src/types/error.ts

@@ -0,0 +1,12 @@
+/**
+ * Error types for extension packages
+ */
+
+export interface ExtensionError {
+  message: string;
+  code?: string;
+  details?: unknown;
+  timestamp: string;
+}
+
+export type ErrorHandler = (error: Error | ExtensionError) => void;

package/src/types/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Common types for extension packages
+ *
+ * Re-exports all types from individual modules
+ */
+
+// Pagination types
+export * from './pagination';
+
+// Context and provider types
+export * from './context';
+
+// Error types
+export * from './error';
+
+// Logger types
+export * from './logger';

package/src/types/logger.ts

@@ -0,0 +1,17 @@
+/**
+ * Logger types for extension packages
+ */
+
+export interface ExtensionLogger {
+  info: (...args: any[]) => void;
+  warn: (...args: any[]) => void;
+  error: (...args: any[]) => void;
+  debug: (...args: any[]) => void;
+  success: (...args: any[]) => void;
+}
+
+export interface LoggerOptions {
+  tag: string;
+  level?: 'debug' | 'info' | 'warn' | 'error';
+  enabled?: boolean;
+}

package/src/types/pagination.ts

@@ -0,0 +1,47 @@
+/**
+ * Pagination types for extension packages
+ */
+
+export interface PaginatedResponse<T> {
+  results: T[];
+  count: number;
+  next?: number | null;
+  previous?: number | null;
+  next_page?: number | null;
+  previous_page?: number | null;
+  has_next?: boolean;
+  has_previous?: boolean;
+  total_pages?: number;
+}
+
+export interface PaginationParams {
+  page?: number;
+  page_size?: number;
+  ordering?: string;
+}
+
+export interface PaginationState {
+  page: number;
+  pageSize: number;
+  totalCount: number;
+  totalPages: number;
+  hasNext: boolean;
+  hasPrevious: boolean;
+}
+
+export interface InfinitePaginationReturn<T> {
+  items: T[];
+  isLoading: boolean;
+  isLoadingMore: boolean;
+  error: any;
+  hasMore: boolean;
+  totalCount: number;
+  loadMore: () => void;
+  refresh: () => Promise<void>;
+}
+
+export interface InfinitePaginationOptions {
+  pageSize?: number;
+  revalidateFirstPage?: boolean;
+  parallel?: boolean;
+}

package/src/utils/errors.ts

@@ -0,0 +1,71 @@
+/**
+ * Error handling utilities for extension packages
+ */
+
+import type { ExtensionError } from '../types';
+
+/**
+ * Checks if an error is an ExtensionError
+ */
+export function isExtensionError(error: unknown): error is ExtensionError {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'message' in error &&
+    'timestamp' in error
+  );
+}
+
+/**
+ * Creates an ExtensionError from any error
+ */
+export function createExtensionError(
+  error: unknown,
+  code?: string,
+  details?: unknown
+): ExtensionError {
+  const message = error instanceof Error ? error.message : String(error);
+
+  return {
+    message,
+    code,
+    details,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/**
+ * Formats an error message for display
+ */
+export function formatErrorMessage(error: unknown): string {
+  if (isExtensionError(error)) {
+    return error.code ? `[${error.code}] ${error.message}` : error.message;
+  }
+
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}
+
+/**
+ * Safe error handler that logs and optionally calls callback
+ */
+export function handleExtensionError(
+  error: unknown,
+  logger?: { error: (...args: any[]) => void },
+  callback?: (error: ExtensionError) => void
+): void {
+  const extensionError = isExtensionError(error)
+    ? error
+    : createExtensionError(error);
+
+  if (logger) {
+    logger.error('Extension error:', extensionError);
+  }
+
+  if (callback) {
+    callback(extensionError);
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Utility functions for extension packages
+ */
+
+export {
+  isExtensionError,
+  createExtensionError,
+  formatErrorMessage,
+  handleExtensionError,
+} from './errors';