@djangocfg/ext-base 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,246 @@
+import { ReactNode } from 'react';
+export { createExtensionAPI, getSharedAuthStorage } from './api.cjs';
+
+/**
+ * Pagination types for extension packages
+ */
+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;
+}
+interface PaginationParams {
+    page?: number;
+    page_size?: number;
+    ordering?: string;
+}
+interface PaginationState {
+    page: number;
+    pageSize: number;
+    totalCount: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrevious: boolean;
+}
+interface InfinitePaginationReturn<T> {
+    items: T[];
+    isLoading: boolean;
+    isLoadingMore: boolean;
+    error: any;
+    hasMore: boolean;
+    totalCount: number;
+    loadMore: () => void;
+    refresh: () => Promise<void>;
+}
+interface InfinitePaginationOptions {
+    pageSize?: number;
+    revalidateFirstPage?: boolean;
+    parallel?: boolean;
+}
+
+/**
+ * Context and provider types for extension packages
+ */
+
+interface ExtensionContextOptions {
+    revalidateOnFocus?: boolean;
+    revalidateOnReconnect?: boolean;
+    revalidateIfStale?: boolean;
+}
+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;
+}
+interface ExtensionProviderProps {
+    /**
+     * Extension metadata for registration
+     */
+    metadata: ExtensionMetadata;
+    /**
+     * SWR configuration options
+     */
+    options?: ExtensionContextOptions;
+    /**
+     * Child components
+     */
+    children: ReactNode;
+}
+
+/**
+ * Error types for extension packages
+ */
+interface ExtensionError {
+    message: string;
+    code?: string;
+    details?: unknown;
+    timestamp: string;
+}
+type ErrorHandler = (error: Error | ExtensionError) => void;
+
+/**
+ * Logger types for extension packages
+ */
+interface ExtensionLogger {
+    info: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+    debug: (...args: any[]) => void;
+    success: (...args: any[]) => void;
+}
+interface LoggerOptions {
+    tag: string;
+    level?: 'debug' | 'info' | 'warn' | 'error';
+    enabled?: boolean;
+}
+
+/**
+ * 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
+ */
+declare const isDevelopment: boolean;
+/**
+ * Check if running in production mode
+ */
+declare const isProduction: boolean;
+/**
+ * Check if running in test mode
+ */
+declare const isTest: boolean;
+/**
+ * Check if this is a static build (Next.js export)
+ */
+declare const isStaticBuild: boolean;
+/**
+ * Check if code is running on client side
+ * Safe to use in both client and server contexts
+ */
+declare const isClient: boolean;
+/**
+ * Check if code is running on server side
+ * Safe to use in both client and server contexts
+ */
+declare const isServer: boolean;
+/**
+ * Get API URL from environment
+ * Returns empty string if not set
+ */
+declare const getApiUrl: () => string;
+/**
+ * Environment configuration object
+ */
+declare const env: {
+    readonly isDevelopment: boolean;
+    readonly isProduction: boolean;
+    readonly isTest: boolean;
+    readonly isStaticBuild: boolean;
+    readonly isClient: boolean;
+    readonly isServer: boolean;
+    readonly getApiUrl: () => string;
+};
+
+/**
+ * Error handling utilities for extension packages
+ */
+
+/**
+ * Checks if an error is an ExtensionError
+ */
+declare function isExtensionError(error: unknown): error is ExtensionError;
+/**
+ * Creates an ExtensionError from any error
+ */
+declare function createExtensionError(error: unknown, code?: string, details?: unknown): ExtensionError;
+/**
+ * Formats an error message for display
+ */
+declare function formatErrorMessage(error: unknown): string;
+/**
+ * Safe error handler that logs and optionally calls callback
+ */
+declare function handleExtensionError(error: unknown, logger?: {
+    error: (...args: any[]) => void;
+}, callback?: (error: ExtensionError) => void): void;
+
+/**
+ * Logger factory for extension packages
+ */
+
+/**
+ * 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);
+ * ```
+ */
+declare function createExtensionLogger(options: LoggerOptions): ExtensionLogger;
+
+export { type ErrorHandler, type ExtensionContextOptions, type ExtensionError, type ExtensionLogger, type ExtensionMetadata, type ExtensionProviderProps, type InfinitePaginationOptions, type InfinitePaginationReturn, type LoggerOptions, type PaginatedResponse, type PaginationParams, type PaginationState, createExtensionError, createExtensionLogger, env, formatErrorMessage, getApiUrl, handleExtensionError, isClient, isDevelopment, isExtensionError, isProduction, isServer, isStaticBuild, isTest };

package/dist/index.d.ts

@@ -0,0 +1,246 @@
+import { ReactNode } from 'react';
+export { createExtensionAPI, getSharedAuthStorage } from './api.js';
+
+/**
+ * Pagination types for extension packages
+ */
+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;
+}
+interface PaginationParams {
+    page?: number;
+    page_size?: number;
+    ordering?: string;
+}
+interface PaginationState {
+    page: number;
+    pageSize: number;
+    totalCount: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrevious: boolean;
+}
+interface InfinitePaginationReturn<T> {
+    items: T[];
+    isLoading: boolean;
+    isLoadingMore: boolean;
+    error: any;
+    hasMore: boolean;
+    totalCount: number;
+    loadMore: () => void;
+    refresh: () => Promise<void>;
+}
+interface InfinitePaginationOptions {
+    pageSize?: number;
+    revalidateFirstPage?: boolean;
+    parallel?: boolean;
+}
+
+/**
+ * Context and provider types for extension packages
+ */
+
+interface ExtensionContextOptions {
+    revalidateOnFocus?: boolean;
+    revalidateOnReconnect?: boolean;
+    revalidateIfStale?: boolean;
+}
+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;
+}
+interface ExtensionProviderProps {
+    /**
+     * Extension metadata for registration
+     */
+    metadata: ExtensionMetadata;
+    /**
+     * SWR configuration options
+     */
+    options?: ExtensionContextOptions;
+    /**
+     * Child components
+     */
+    children: ReactNode;
+}
+
+/**
+ * Error types for extension packages
+ */
+interface ExtensionError {
+    message: string;
+    code?: string;
+    details?: unknown;
+    timestamp: string;
+}
+type ErrorHandler = (error: Error | ExtensionError) => void;
+
+/**
+ * Logger types for extension packages
+ */
+interface ExtensionLogger {
+    info: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+    debug: (...args: any[]) => void;
+    success: (...args: any[]) => void;
+}
+interface LoggerOptions {
+    tag: string;
+    level?: 'debug' | 'info' | 'warn' | 'error';
+    enabled?: boolean;
+}
+
+/**
+ * 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
+ */
+declare const isDevelopment: boolean;
+/**
+ * Check if running in production mode
+ */
+declare const isProduction: boolean;
+/**
+ * Check if running in test mode
+ */
+declare const isTest: boolean;
+/**
+ * Check if this is a static build (Next.js export)
+ */
+declare const isStaticBuild: boolean;
+/**
+ * Check if code is running on client side
+ * Safe to use in both client and server contexts
+ */
+declare const isClient: boolean;
+/**
+ * Check if code is running on server side
+ * Safe to use in both client and server contexts
+ */
+declare const isServer: boolean;
+/**
+ * Get API URL from environment
+ * Returns empty string if not set
+ */
+declare const getApiUrl: () => string;
+/**
+ * Environment configuration object
+ */
+declare const env: {
+    readonly isDevelopment: boolean;
+    readonly isProduction: boolean;
+    readonly isTest: boolean;
+    readonly isStaticBuild: boolean;
+    readonly isClient: boolean;
+    readonly isServer: boolean;
+    readonly getApiUrl: () => string;
+};
+
+/**
+ * Error handling utilities for extension packages
+ */
+
+/**
+ * Checks if an error is an ExtensionError
+ */
+declare function isExtensionError(error: unknown): error is ExtensionError;
+/**
+ * Creates an ExtensionError from any error
+ */
+declare function createExtensionError(error: unknown, code?: string, details?: unknown): ExtensionError;
+/**
+ * Formats an error message for display
+ */
+declare function formatErrorMessage(error: unknown): string;
+/**
+ * Safe error handler that logs and optionally calls callback
+ */
+declare function handleExtensionError(error: unknown, logger?: {
+    error: (...args: any[]) => void;
+}, callback?: (error: ExtensionError) => void): void;
+
+/**
+ * Logger factory for extension packages
+ */
+
+/**
+ * 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);
+ * ```
+ */
+declare function createExtensionLogger(options: LoggerOptions): ExtensionLogger;
+
+export { type ErrorHandler, type ExtensionContextOptions, type ExtensionError, type ExtensionLogger, type ExtensionMetadata, type ExtensionProviderProps, type InfinitePaginationOptions, type InfinitePaginationReturn, type LoggerOptions, type PaginatedResponse, type PaginationParams, type PaginationState, createExtensionError, createExtensionLogger, env, formatErrorMessage, getApiUrl, handleExtensionError, isClient, isDevelopment, isExtensionError, isProduction, isServer, isStaticBuild, isTest };

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createExtensionError, createExtensionLogger, formatErrorMessage, handleExtensionError, isExtensionError } from './chunk-YQGNYUBX.js';
+export { createExtensionAPI, env, getApiUrl, getSharedAuthStorage, isClient, isDevelopment, isProduction, isServer, isStaticBuild, isTest } from './chunk-MECBWZG4.js';
+import './chunk-3RG5ZIWI.js';

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@djangocfg/ext-base",
+  "version": "1.0.0",
+  "description": "Base utilities and common code for DjangoCFG extensions",
+  "keywords": [
+    "django",
+    "djangocfg",
+    "extension",
+    "base",
+    "utilities",
+    "typescript",
+    "react"
+  ],
+  "author": {
+    "name": "DjangoCFG",
+    "url": "https://djangocfg.com"
+  },
+  "homepage": "https://djangocfg.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/markolofsen/django-cfg.git",
+    "directory": "extensions/base"
+  },
+  "bugs": {
+    "url": "https://github.com/markolofsen/django-cfg/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./hooks": {
+      "types": "./dist/hooks.d.ts",
+      "import": "./dist/hooks.mjs",
+      "require": "./dist/hooks.cjs"
+    },
+    "./auth": {
+      "types": "./dist/auth.d.ts",
+      "import": "./dist/auth.mjs",
+      "require": "./dist/auth.cjs"
+    },
+    "./api": {
+      "types": "./dist/api.d.ts",
+      "import": "./dist/api.mjs",
+      "require": "./dist/api.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@djangocfg/api": "^2.1.14",
+    "consola": "^3.4.2",
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19",
+    "swr": "^2.3.7"
+  },
+  "devDependencies": {
+    "@djangocfg/api": "^2.1.14",
+    "@djangocfg/typescript-config": "^2.1.14",
+    "@types/node": "^24.7.2",
+    "@types/react": "^19.0.0",
+    "consola": "^3.4.2",
+    "swr": "^2.3.7",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/api/createExtensionAPI.ts

@@ -0,0 +1,63 @@
+/**
+ * Factory for creating extension API instances
+ *
+ * Provides consistent API setup across all extensions with shared authentication
+ */
+
+import { isStaticBuild, getApiUrl } from '../config';
+
+/**
+ * Creates an extension API instance with shared authentication storage
+ *
+ * @param APIClass - The generated API class from your extension
+ * @returns Configured API instance with shared auth storage
+ *
+ * @example
+ * ```typescript
+ * // In your extension's api/index.ts
+ * import { API } from './generated/ext_newsletter';
+ * import { createExtensionAPI } from '@djangocfg/ext-base/api';
+ *
+ * export const apiNewsletter = createExtensionAPI(API);
+ * ```
+ */
+export function createExtensionAPI<T>(APIClass: new (url: string, options?: any) => T): T {
+  // Dynamically import accounts API to get shared storage
+  // This avoids circular dependencies and keeps the import lazy
+  let storage: any;
+
+  try {
+    // @ts-ignore - dynamic import for shared storage
+    const { api: accountsApi } = require('@djangocfg/api');
+    storage = (accountsApi as any)._storage;
+  } catch (error) {
+    // If @djangocfg/api is not available, use undefined storage
+    // This allows extensions to work in isolation if needed
+    storage = undefined;
+  }
+
+  const apiUrl = isStaticBuild ? '' : getApiUrl();
+
+  return new APIClass(apiUrl, storage ? { storage } : undefined);
+}
+
+/**
+ * Get shared authentication storage from accounts API
+ *
+ * @returns Storage instance or undefined if not available
+ *
+ * @example
+ * ```typescript
+ * const storage = getSharedAuthStorage();
+ * const api = new API(apiUrl, { storage });
+ * ```
+ */
+export function getSharedAuthStorage(): any | undefined {
+  try {
+    // @ts-ignore - dynamic import
+    const { api: accountsApi } = require('@djangocfg/api');
+    return (accountsApi as any)._storage;
+  } catch (error) {
+    return undefined;
+  }
+}

package/src/api/index.ts

@@ -0,0 +1,5 @@
+/**
+ * API utilities for extensions
+ */
+
+export * from './createExtensionAPI';

package/src/auth/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Auth utilities for extension packages
+ *
+ * Re-exports useAuth from @djangocfg/api for convenience
+ */
+
+'use client';
+
+// Re-export useAuth for convenience
+// Extensions can import from either:
+// - @djangocfg/api/auth (direct)
+// - @djangocfg/ext-base/auth (convenience re-export)
+export { useAuth, type UserProfile, type AuthContextType } from '@djangocfg/api/auth';