@djangocfg/ext-base 1.0.3 → 1.0.4

package/dist/index.d.cts

@@ -0,0 +1,363 @@
+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;
+}
+/**
+ * Extension category types
+ */
+type ExtensionCategory = 'forms' | 'payments' | 'content' | 'support' | 'utilities' | 'analytics' | 'security' | 'integration' | 'other';
+/**
+ * Extension categories with display names for CLI and UI
+ */
+declare const EXTENSION_CATEGORIES: Array<{
+    title: string;
+    value: ExtensionCategory;
+}>;
+/**
+ * Code example for extension documentation
+ */
+interface ExtensionExample {
+    /**
+     * Example title
+     */
+    title: string;
+    /**
+     * Example description
+     */
+    description?: string;
+    /**
+     * Code snippet
+     */
+    code: string;
+    /**
+     * Programming language for syntax highlighting
+     */
+    language: string;
+}
+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[];
+    /**
+     * Minimum required DjangoCFG version
+     */
+    minVersion?: string;
+    /**
+     * Extension category for marketplace organization
+     */
+    category?: ExtensionCategory;
+    /**
+     * Tags for search and filtering
+     */
+    tags?: string[];
+    /**
+     * List of key features
+     */
+    features?: string[];
+    /**
+     * npm package URL
+     * @example 'https://www.npmjs.com/package/@djangocfg/ext-newsletter'
+     */
+    npmUrl?: string;
+    /**
+     * Marketplace-safe ID (package name with @ and / replaced by -)
+     * @example '@djangocfg/ext-newsletter' -> 'djangocfg-ext-newsletter'
+     */
+    marketplaceId?: string;
+    /**
+     * Marketplace URL
+     * @example 'https://hub.djangocfg.com/extensions/djangocfg-ext-newsletter'
+     */
+    marketplaceUrl?: string;
+    /**
+     * Installation command
+     * @example 'pnpm add @djangocfg/ext-newsletter'
+     */
+    installCommand?: string;
+    /**
+     * Download URL for npm tarball
+     * @example 'https://registry.npmjs.org/@djangocfg/ext-newsletter/-/ext-newsletter-1.0.0.tgz'
+     */
+    downloadUrl?: string;
+    /**
+     * Code examples for documentation
+     */
+    examples?: ExtensionExample[];
+    /**
+     * npm package dependencies
+     */
+    packageDependencies?: Record<string, string>;
+    /**
+     * npm peer dependencies
+     */
+    packagePeerDependencies?: Record<string, string>;
+    /**
+     * npm dev dependencies
+     */
+    packageDevDependencies?: Record<string, string>;
+    /**
+     * README content in markdown
+     */
+    readme?: string;
+    /**
+     * Preview image URL (1200x630 recommended)
+     * @example 'https://unpkg.com/@djangocfg/ext-leads@latest/preview.svg'
+     */
+    preview?: string;
+    /**
+     * GitHub stars count
+     */
+    githubStars?: number;
+}
+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;
+}
+
+/**
+ * Base extension configuration
+ */
+declare const extensionConfig: ExtensionMetadata;
+
+/**
+ * Extension configuration and environment utilities
+ */
+declare const isDevelopment: boolean;
+declare const isProduction: boolean;
+declare const isStaticBuild: boolean;
+/**
+ * Get API URL from environment or default
+ */
+declare function 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;
+
+/**
+ * Helper to create extension configuration from package.json
+ */
+
+/**
+ * Package.json structure
+ */
+interface PackageJson {
+    name: string;
+    version: string;
+    description?: string;
+    keywords?: string[];
+    author?: string | {
+        name: string;
+        email?: string;
+        url?: string;
+    };
+    license?: string;
+    homepage?: string;
+    repository?: string | {
+        type: string;
+        url: string;
+        directory?: string;
+    };
+    dependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+}
+/**
+ * Manual metadata fields that must be provided
+ */
+interface ExtensionConfigInput {
+    /**
+     * Extension short name (e.g., 'leads', 'payments')
+     */
+    name: string;
+    /**
+     * Display name for marketplace
+     */
+    displayName: string;
+    /**
+     * Extension category
+     */
+    category: ExtensionMetadata['category'];
+    /**
+     * Key features list
+     */
+    features: string[];
+    /**
+     * Code examples (optional)
+     */
+    examples?: ExtensionMetadata['examples'];
+    /**
+     * Minimum required DjangoCFG version (optional)
+     */
+    minVersion?: string;
+    /**
+     * GitHub stars count (optional)
+     */
+    githubStars?: number;
+}
+declare function createExtensionConfig(packageJson: PackageJson, config: ExtensionConfigInput): ExtensionMetadata;
+
+/**
+ * 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 { EXTENSION_CATEGORIES, type ErrorHandler, type ExtensionCategory, type ExtensionConfigInput, type ExtensionContextOptions, type ExtensionError, type ExtensionExample, type ExtensionLogger, type ExtensionMetadata, type ExtensionProviderProps, type InfinitePaginationOptions, type InfinitePaginationReturn, type LoggerOptions, type PaginatedResponse, type PaginationParams, type PaginationState, createExtensionConfig, createExtensionError, createExtensionLogger, extensionConfig, formatErrorMessage, getApiUrl, handleExtensionError, isDevelopment, isExtensionError, isProduction, isStaticBuild };

package/dist/index.d.ts

@@ -0,0 +1,363 @@
+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;
+}
+/**
+ * Extension category types
+ */
+type ExtensionCategory = 'forms' | 'payments' | 'content' | 'support' | 'utilities' | 'analytics' | 'security' | 'integration' | 'other';
+/**
+ * Extension categories with display names for CLI and UI
+ */
+declare const EXTENSION_CATEGORIES: Array<{
+    title: string;
+    value: ExtensionCategory;
+}>;
+/**
+ * Code example for extension documentation
+ */
+interface ExtensionExample {
+    /**
+     * Example title
+     */
+    title: string;
+    /**
+     * Example description
+     */
+    description?: string;
+    /**
+     * Code snippet
+     */
+    code: string;
+    /**
+     * Programming language for syntax highlighting
+     */
+    language: string;
+}
+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[];
+    /**
+     * Minimum required DjangoCFG version
+     */
+    minVersion?: string;
+    /**
+     * Extension category for marketplace organization
+     */
+    category?: ExtensionCategory;
+    /**
+     * Tags for search and filtering
+     */
+    tags?: string[];
+    /**
+     * List of key features
+     */
+    features?: string[];
+    /**
+     * npm package URL
+     * @example 'https://www.npmjs.com/package/@djangocfg/ext-newsletter'
+     */
+    npmUrl?: string;
+    /**
+     * Marketplace-safe ID (package name with @ and / replaced by -)
+     * @example '@djangocfg/ext-newsletter' -> 'djangocfg-ext-newsletter'
+     */
+    marketplaceId?: string;
+    /**
+     * Marketplace URL
+     * @example 'https://hub.djangocfg.com/extensions/djangocfg-ext-newsletter'
+     */
+    marketplaceUrl?: string;
+    /**
+     * Installation command
+     * @example 'pnpm add @djangocfg/ext-newsletter'
+     */
+    installCommand?: string;
+    /**
+     * Download URL for npm tarball
+     * @example 'https://registry.npmjs.org/@djangocfg/ext-newsletter/-/ext-newsletter-1.0.0.tgz'
+     */
+    downloadUrl?: string;
+    /**
+     * Code examples for documentation
+     */
+    examples?: ExtensionExample[];
+    /**
+     * npm package dependencies
+     */
+    packageDependencies?: Record<string, string>;
+    /**
+     * npm peer dependencies
+     */
+    packagePeerDependencies?: Record<string, string>;
+    /**
+     * npm dev dependencies
+     */
+    packageDevDependencies?: Record<string, string>;
+    /**
+     * README content in markdown
+     */
+    readme?: string;
+    /**
+     * Preview image URL (1200x630 recommended)
+     * @example 'https://unpkg.com/@djangocfg/ext-leads@latest/preview.svg'
+     */
+    preview?: string;
+    /**
+     * GitHub stars count
+     */
+    githubStars?: number;
+}
+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;
+}
+
+/**
+ * Base extension configuration
+ */
+declare const extensionConfig: ExtensionMetadata;
+
+/**
+ * Extension configuration and environment utilities
+ */
+declare const isDevelopment: boolean;
+declare const isProduction: boolean;
+declare const isStaticBuild: boolean;
+/**
+ * Get API URL from environment or default
+ */
+declare function 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;
+
+/**
+ * Helper to create extension configuration from package.json
+ */
+
+/**
+ * Package.json structure
+ */
+interface PackageJson {
+    name: string;
+    version: string;
+    description?: string;
+    keywords?: string[];
+    author?: string | {
+        name: string;
+        email?: string;
+        url?: string;
+    };
+    license?: string;
+    homepage?: string;
+    repository?: string | {
+        type: string;
+        url: string;
+        directory?: string;
+    };
+    dependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+}
+/**
+ * Manual metadata fields that must be provided
+ */
+interface ExtensionConfigInput {
+    /**
+     * Extension short name (e.g., 'leads', 'payments')
+     */
+    name: string;
+    /**
+     * Display name for marketplace
+     */
+    displayName: string;
+    /**
+     * Extension category
+     */
+    category: ExtensionMetadata['category'];
+    /**
+     * Key features list
+     */
+    features: string[];
+    /**
+     * Code examples (optional)
+     */
+    examples?: ExtensionMetadata['examples'];
+    /**
+     * Minimum required DjangoCFG version (optional)
+     */
+    minVersion?: string;
+    /**
+     * GitHub stars count (optional)
+     */
+    githubStars?: number;
+}
+declare function createExtensionConfig(packageJson: PackageJson, config: ExtensionConfigInput): ExtensionMetadata;
+
+/**
+ * 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 { EXTENSION_CATEGORIES, type ErrorHandler, type ExtensionCategory, type ExtensionConfigInput, type ExtensionContextOptions, type ExtensionError, type ExtensionExample, type ExtensionLogger, type ExtensionMetadata, type ExtensionProviderProps, type InfinitePaginationOptions, type InfinitePaginationReturn, type LoggerOptions, type PaginatedResponse, type PaginationParams, type PaginationState, createExtensionConfig, createExtensionError, createExtensionLogger, extensionConfig, formatErrorMessage, getApiUrl, handleExtensionError, isDevelopment, isExtensionError, isProduction, isStaticBuild };