@donotdev/core 0.0.12 → 0.0.14

package/functions/index.d.ts

@@ -1,4 +1,7 @@
-type Platform = 'browser' | 'node' | 'neutral'
+import * as React from 'react';
+import { ReactNode } from 'react';
+
+type Platform$1 = 'browser' | 'node' | 'neutral'
 type Format = 'iife' | 'cjs' | 'esm'
 type Loader = 'base64' | 'binary' | 'copy' | 'css' | 'dataurl' | 'default' | 'empty' | 'file' | 'js' | 'json' | 'jsx' | 'local-css' | 'text' | 'ts' | 'tsx'
 type LogLevel = 'verbose' | 'debug' | 'info' | 'warning' | 'error' | 'silent'
@@ -25,7 +28,7 @@ interface CommonOptions {
   /** Documentation: https://esbuild.github.io/api/#supported */
   supported?: Record<string, boolean>
   /** Documentation: https://esbuild.github.io/api/#platform */
-  platform?: Platform
+  platform?: Platform$1
 
   /** Documentation: https://esbuild.github.io/api/#mangle-props */
   mangleProps?: RegExp
@@ -687,6 +690,1060 @@ declare global {
   }
 }
 
+// packages/core/types/src/auth/constants.ts
+
+
+
+// =============================================================================
+// User Role Constants
+// =============================================================================
+
+/**
+ * Standard user role names
+ * Apps can override these by providing their own role constants
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+declare const USER_ROLES = {
+  GUEST: 'guest',
+  USER: 'user',
+  ADMIN: 'admin',
+  SUPER: 'super',
+} as const;
+
+/**
+ * Type for user role names
+ * Apps can extend this with their own custom roles
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+type UserRole = (typeof USER_ROLES)[keyof typeof USER_ROLES] | string;
+
+// =============================================================================
+// Subscription Tier Constants
+// =============================================================================
+
+/**
+ * Standard subscription tier names
+ * Apps can override these by providing their own tier constants
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+declare const SUBSCRIPTION_TIERS = {
+  FREE: 'free',
+  PRO: 'pro',
+  PREMIUM: 'premium',
+} as const;
+
+/**
+ * Type for subscription tier names
+ * Apps can extend this with their own custom tiers
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+type SubscriptionTier =
+  | (typeof SUBSCRIPTION_TIERS)[keyof typeof SUBSCRIPTION_TIERS]
+  | string;
+
+// packages/core/types/src/common/index.ts
+
+
+
+// =============================================================================
+// PLATFORM CONSTANTS
+// =============================================================================
+
+/**
+ * Supported platform identifiers
+ * @constant
+ */
+declare const PLATFORMS = {
+  VITE: 'vite',
+  NEXTJS: 'nextjs',
+  UNKNOWN: 'unknown',
+} as const;
+
+/**
+ * Platform type derived from PLATFORMS constant
+ */
+type Platform = (typeof PLATFORMS)[keyof typeof PLATFORMS];
+
+// =============================================================================
+// ENVIRONMENT CONSTANTS
+// =============================================================================
+
+/**
+ * Supported environment modes
+ * @constant
+ */
+declare const ENVIRONMENTS = {
+  DEVELOPMENT: 'development',
+  PRODUCTION: 'production',
+  TEST: 'test',
+} as const;
+
+/**
+ * Environment mode type derived from ENVIRONMENTS constant
+ */
+type EnvironmentMode = (typeof ENVIRONMENTS)[keyof typeof ENVIRONMENTS];
+
+// =============================================================================
+// CONTEXT CONSTANTS
+// =============================================================================
+
+/**
+ * Supported execution contexts
+ * @constant
+ */
+declare const CONTEXTS = {
+  CLIENT: 'client',
+  SERVER: 'server',
+  BUILD: 'build',
+} as const;
+
+/**
+ * Context type derived from CONTEXTS constant
+ */
+type Context = (typeof CONTEXTS)[keyof typeof CONTEXTS];
+
+// =============================================================================
+// STORAGE CONSTANTS
+// =============================================================================
+
+/**
+ * Supported storage backend types
+ * @constant
+ */
+declare const STORAGE_TYPES = {
+  LOCAL: 'localStorage',
+  SESSION: 'sessionStorage',
+  INDEXED_DB: 'indexedDB',
+  MEMORY: 'memory',
+} as const;
+
+/**
+ * Storage type derived from STORAGE_TYPES constant
+ */
+type StorageType = (typeof STORAGE_TYPES)[keyof typeof STORAGE_TYPES];
+
+// =============================================================================
+// PWA CONSTANTS
+// =============================================================================
+
+/**
+ * PWA display modes
+ * @constant
+ */
+declare const PWA_DISPLAY_MODES = {
+  STANDALONE: 'standalone',
+  FULLSCREEN: 'fullscreen',
+  MINIMAL_UI: 'minimal-ui',
+  BROWSER: 'browser',
+} as const;
+
+/**
+ * PWA display mode type derived from PWA_DISPLAY_MODES constant
+ */
+type PWADisplayMode =
+  (typeof PWA_DISPLAY_MODES)[keyof typeof PWA_DISPLAY_MODES];
+
+/**
+ * PWA asset types
+ * @constant
+ */
+declare const PWA_ASSET_TYPES = {
+  MANIFEST: 'manifest',
+  SERVICE_WORKER: 'service-worker',
+  ICON: 'icon',
+} as const;
+
+/**
+ * PWA asset type derived from PWA_ASSET_TYPES constant
+ */
+type PWAAssetType =
+  (typeof PWA_ASSET_TYPES)[keyof typeof PWA_ASSET_TYPES];
+
+// =============================================================================
+// ROUTE DISCOVERY CONSTANTS
+// =============================================================================
+
+/**
+ * Route discovery sources
+ * @constant
+ */
+declare const ROUTE_SOURCES = {
+  AUTO: 'auto-discovery',
+  MANUAL: 'manual',
+  HYBRID: 'hybrid',
+} as const;
+
+/**
+ * Route source type derived from ROUTE_SOURCES constant
+ */
+type RouteSource = (typeof ROUTE_SOURCES)[keyof typeof ROUTE_SOURCES];
+
+// =============================================================================
+// AUTHENTICATION TYPES
+// =============================================================================
+
+/**
+ * Page-level authentication requirements
+ * @description Used in PageMeta and NavigationRoute for route-level auth
+ */
+type PageAuth =
+  | boolean
+  | {
+      /** Whether authentication is required */
+      required?: boolean;
+      /** Required user role */
+      role?: UserRole;
+      /** Required subscription tier */
+      tier?: SubscriptionTier;
+      /** Custom validation function */
+      validate?: (role: string, tier: string) => boolean;
+    };
+
+// =============================================================================
+// PAGE METADATA TYPES
+// =============================================================================
+
+/**
+ * Page metadata interface for route discovery and configuration
+ *
+ * @remarks
+ * **ALL PROPERTIES ARE OPTIONAL** - Framework provides smart defaults:
+ *
+ * - `auth`: false (public) by default - YOU must specify auth requirements explicitly
+ * - `title`: Auto-extracted from filename (ShowcasePage → "Showcase")
+ * - `entity`: Auto-extracted from path (pages/showcase/ → "showcase")
+ * - `action`: Auto-extracted from filename patterns (ListPage → "list", FormPage → "form")
+ * - `route`: Only needed for custom paths or dynamic routes like :id, :slug
+ *
+ * @example Simple page (no meta needed):
+ * ```tsx
+ * export function HomePage() {
+ *   return <PageContainer>...</PageContainer>;
+ * }
+ * // Framework provides: auth=false, title from home.title, entity=home
+ * ```
+ *
+ * @example Dynamic route (string format - explicit path):
+ * ```tsx
+ * export const meta: PageMeta = {
+ *   route: '/blog/:slug'  // Creates /blog/:slug
+ * };
+ * // Framework provides: auth=false, title from blog.title, entity=blog
+ * ```
+ *
+ * @example Dynamic route (object format - auto-generates base path):
+ * ```tsx
+ * export const meta: PageMeta = {
+ *   route: { params: ['id'] }  // Creates /myRoute/:id (base path from file location)
+ * };
+ * // For file at pages/myRoute/DetailPage.tsx → route becomes /myRoute/:id
+ * ```
+ *
+ * @example Auth-required (developer must be explicit):
+ * ```tsx
+ * export const meta: PageMeta = {
+ *   auth: { required: true }  // YOU decide what needs auth
+ * };
+ * ```
+ */
+interface PageMeta {
+  /** Authentication requirements for this route */
+  auth?: PageAuth;
+
+  /** Route configuration - just define the exact path you want */
+  route?: string | { params?: string[] };
+
+  /** Page title (optional - framework auto-extracts from filename if not provided) */
+  title?: string;
+
+  /**
+   * Translation/SEO namespace for this page
+   * @description Used for meta tags and translations
+   */
+  namespace?: string;
+
+  /**
+   * Icon for navigation (optional - framework provides smart defaults)
+   * @description **ONLY lucide-react JSX components** - extracted as component name string at build time for tree-shaking.
+   *
+   * **RESTRICTIONS:**
+   * - ✅ Only: `<Rocket />`, `<ShoppingCart />`, `<Home />` (lucide-react JSX components)
+   * - ❌ NOT: Emojis (`"🚀"`), strings (`"Rocket"`), or custom ReactNode
+   *
+   * **Why?** This is for build-time extraction and tree-shaking. The component name is extracted and stored as a string.
+   *
+   * **For flexible icons** (emojis, strings, custom components), use the `Icon` component directly in your JSX, not in PageMeta.
+   *
+   * @example
+   * ```tsx
+   * import { Rocket } from 'lucide-react';
+   * export const meta: PageMeta = {
+   *   icon: <Rocket />  // ✅ Correct - lucide-react component
+   * };
+   * ```
+   *
+   * @example
+   * ```tsx
+   * // ❌ WRONG - Don't use emojis or strings in PageMeta
+   * export const meta: PageMeta = {
+   *   icon: "🚀"  // ❌ Not supported in PageMeta
+   * };
+   * ```
+   */
+  icon?: ReactNode;
+
+  /**
+   * Hide from navigation menu (default: false - shows in navigation)
+   * @description Set to true to exclude this route from navigation menus
+   * @default false
+   * @example
+   * ```tsx
+   * export const meta: PageMeta = {
+   *   hideFromMenu: true // Won't appear in HeaderNavigation, Sidebar, etc.
+   * };
+   * ```
+   */
+  hideFromMenu?: boolean;
+}
+
+/**
+ * Route metadata (discovery-generated)
+ * @description Complete route metadata including auto-discovered fields from RouteDiscovery
+ *
+ * This extends PageMeta with fields that are automatically discovered from file paths:
+ * - `entity`: Auto-extracted from path (pages/showcase/ → "showcase")
+ * - `action`: Auto-extracted from filename patterns (ListPage → "list", FormPage → "form")
+ *
+ * These fields are always present in discovered routes but cannot be set in PageMeta.
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface RouteMeta extends PageMeta {
+  /** Entity/domain grouping - auto-discovered from file path (not user-configurable) */
+  entity?: string;
+  /** Action type for route categorization - auto-discovered from filename patterns (not user-configurable) */
+  action?: string | null;
+  /** File path where route was discovered */
+  file?: string;
+}
+
+// =============================================================================
+// PLUGIN CONFIGURATION TYPES
+// =============================================================================
+
+/**
+ * i18n Plugin Configuration
+ * @description Configuration for internationalization system
+ */
+interface I18nPluginConfig {
+  /** Mapping of language → namespace → loader function */
+  mapping: Record<string, Record<string, () => Promise<any>>>;
+  /** List of available language codes */
+  languages: string[];
+  /** List of eagerly loaded namespace identifiers */
+  eager: string[];
+  /** Fallback language code */
+  fallback: string;
+  /** Preloaded translation content (optional) */
+  content?: Record<string, Record<string, any>>;
+  /** Storage configuration */
+  storage: {
+    /** Storage backend type */
+    type: StorageType;
+    /** Storage key prefix */
+    prefix: string;
+    /** Time-to-live in seconds */
+    ttl: number;
+    /** Whether to encrypt stored data */
+    encryption: boolean;
+    /** Maximum storage size in bytes */
+    maxSize: number;
+  };
+  /** Performance configuration */
+  performance: {
+    /** Maximum cache size */
+    cacheSize: number;
+    /** Error cache TTL in seconds */
+    errorCacheTTL: number;
+  };
+  /** Discovery manifest metadata */
+  manifest: {
+    /** Total number of translation files */
+    totalFiles: number;
+    /** Total number of namespaces */
+    totalNamespaces: number;
+    /** Total number of languages */
+    totalLanguages: number;
+    /** Number of eagerly loaded namespaces */
+    eagerNamespaces: number;
+    /** ISO timestamp of generation */
+    generatedAt: string;
+  };
+  /** Whether debug mode is enabled */
+  debug: boolean;
+}
+
+/**
+ * Routes Plugin Configuration
+ * @description Complete route configuration populated by discovery system
+ */
+interface RoutesPluginConfig {
+  /**
+   * Array of discovered routes
+   * @description All routes discovered by the route discovery system
+   */
+  mapping: Array<{
+    /**
+     * URL path for the route (platform-agnostic)
+     * @description The URL path that users see in their browser
+     * @example '/showcase/layouts', '/users/:id', '/dashboard'
+     */
+    path: string;
+
+    /**
+     * Lazy component reference (Vite-specific)
+     * @description React.lazy() component for code splitting
+     * @example lazy(() => import("/src/pages/showcase/LayoutsPage"))
+     */
+    component: any;
+
+    /**
+     * Absolute file system path (Next.js-specific)
+     * @description The absolute path to the component file
+     * @example '/src/pages/showcase/LayoutsPage.tsx'
+     */
+    importPath: string;
+
+    /**
+     * Export name for named exports
+     * @example 'HomePage', 'AboutPage'
+     */
+    exportName?: string;
+
+    /**
+     * Authentication configuration (platform-agnostic)
+     * @description Defines whether the route requires authentication
+     */
+    auth: PageAuth;
+
+    /**
+     * Route metadata (platform-agnostic)
+     * @description Additional information about the route, including auto-discovered fields
+     */
+    meta: RouteMeta;
+  }>;
+
+  /**
+   * Discovery metadata and statistics
+   * @description Information about the route discovery process
+   */
+  manifest: {
+    /** Total number of discovered routes */
+    totalRoutes: number;
+    /** Number of routes requiring authentication */
+    authRequired: number;
+    /** Number of public routes */
+    publicRoutes: number;
+    /** Source of routes (auto-discovery vs manual) */
+    source: RouteSource;
+    /** ISO timestamp when routes were generated */
+    generatedAt: string;
+  };
+}
+
+/**
+ * Themes Plugin Configuration
+ * @description Configuration for theme discovery and management
+ */
+interface ThemesPluginConfig {
+  /** Mapping of theme names to theme configurations */
+  mapping: Record<string, any>;
+  /** Array of discovered themes */
+  discovered: Array<{
+    /** Theme identifier */
+    name: string;
+    /** Human-readable theme name */
+    displayName: string;
+    /** Whether this is a dark theme */
+    isDark: boolean;
+    /** Theme metadata */
+    meta: {
+      /** Icon identifier */
+      icon: string;
+      /** Theme description */
+      description?: string;
+      /** Theme category */
+      category?: string;
+      /** Theme author */
+      author?: string;
+      /** Additional metadata */
+      [key: string]: any;
+    };
+    /** Source file path */
+    source: string;
+    /** Whether theme is essential (cannot be disabled) */
+    essential: boolean;
+  }>;
+  /** CSS custom property variables */
+  variables: Record<string, string>;
+  /** Utility class mappings */
+  utilities: Record<string, Record<string, string>>;
+  /** Discovery manifest metadata */
+  manifest: {
+    /** Total number of discovered themes */
+    totalThemes: number;
+    /** Total number of CSS variables */
+    totalVariables: number;
+    /** Total number of utility classes */
+    totalUtilities: number;
+    /** ISO timestamp of generation */
+    generatedAt: string;
+  };
+}
+
+/**
+ * Assets Plugin Configuration
+ * @description Configuration for static asset management
+ */
+interface AssetsPluginConfig {
+  /** Mapping of asset paths to asset metadata */
+  mapping: Record<string, any>;
+  /** SVG content of logo.svg for inline rendering with CSS variable theming */
+  logoSvgContent?: string | null;
+  /** Discovery manifest metadata */
+  manifest: {
+    /** Total number of discovered assets */
+    totalAssets: number;
+    /** ISO timestamp of generation */
+    generatedAt: string;
+  };
+}
+
+/**
+ * PWA Plugin Configuration
+ * @description Configuration for Progressive Web App features
+ */
+interface PWAPluginConfig {
+  /** Array of PWA assets */
+  assets: Array<{
+    /** Type of PWA asset */
+    type: PWAAssetType;
+    /** Asset file path */
+    path: string;
+    /** Asset file size in bytes */
+    size?: number;
+    /** Asset content (for inline assets) */
+    content?: any;
+    /** Asset format (for images) */
+    format?: string;
+    /** Asset purpose (for icons) */
+    purpose?: string;
+  }>;
+  /** PWA manifest configuration */
+  manifest: {
+    /** Application name */
+    name: string;
+    /** Short application name */
+    short_name: string;
+    /** Application description */
+    description: string;
+    /** Start URL */
+    start_url: string;
+    /** Display mode */
+    display: PWADisplayMode;
+    /** Background color */
+    background_color: string;
+    /** Theme color */
+    theme_color: string;
+    /** Array of app icons */
+    icons: Array<{
+      /** Icon source path */
+      src: string;
+      /** Icon sizes (e.g., '192x192') */
+      sizes: string;
+      /** Icon MIME type */
+      type: string;
+      /** Icon purpose (e.g., 'any', 'maskable') */
+      purpose: string;
+    }>;
+  };
+  /** Discovery manifest metadata */
+  manifestInfo: {
+    /** Total number of PWA assets */
+    totalAssets: number;
+    /** Total number of icons */
+    totalIcons: number;
+    /** Whether service worker is present */
+    hasServiceWorker: boolean;
+    /** ISO timestamp of generation */
+    generatedAt: string;
+  };
+}
+
+/**
+ * Features Plugin Configuration
+ * @description Configuration for feature discovery and enablement
+ *
+ * @remarks
+ * This interface defines the structure for feature discovery data that is populated
+ * at build time and made available at runtime for feature availability checking.
+ *
+ * @example
+ * ```typescript
+ * // Generated by feature discovery system
+ * const featuresConfig: FeaturesPluginConfig = {
+ *   available: ['auth', 'billing', 'i18n', 'oauth'],
+ *   enabled: ['auth', 'i18n'],
+ *   overridden: false
+ * };
+ * ```
+ */
+interface FeaturesPluginConfig {
+  /**
+   * List of all available features discovered in packages/features/
+   * @example ['auth', 'billing', 'i18n', 'oauth']
+   */
+  available: string[];
+}
+
+// =============================================================================
+// FRAMEWORK CONFIGURATION
+// =============================================================================
+
+/**
+ * Complete DoNotDev framework configuration structure
+ * @description Single source of truth for all framework configuration
+ *
+ * @remarks
+ * All discovery plugins add their data to this unified config.
+ * Available at runtime via globalThis._DNDEV_CONFIG_ or window._DNDEV_CONFIG_
+ */
+interface DndevFrameworkConfig {
+  /** Framework platform (Vite or Next.js) */
+  platform: Platform;
+  /** Current environment mode */
+  mode: EnvironmentMode;
+  /** Framework version */
+  version: string;
+  /** Execution context */
+  context: Context;
+  /** Unix timestamp of config generation */
+  timestamp: number;
+  /** i18n plugin configuration (optional) */
+  i18n?: I18nPluginConfig;
+  /** Routes plugin configuration (optional) */
+  routes?: RoutesPluginConfig;
+  /** Themes plugin configuration (optional) */
+  themes?: ThemesPluginConfig;
+  /** Assets plugin configuration (optional) */
+  assets?: AssetsPluginConfig;
+  /** PWA plugin configuration (optional) */
+  pwa?: PWAPluginConfig;
+  /** Features plugin configuration (optional) */
+  features?: FeaturesPluginConfig;
+  /** Environment variables (VITE_* variables from .env files) */
+  env?: Record<string, string>;
+}
+
+// =============================================================================
+// GLOBAL AUGMENTATIONS
+// =============================================================================
+
+declare global {
+  interface Window {
+    /**
+     * Single source of truth for all DoNotDev framework configuration
+     * @description Set by platform detection and populated by discovery plugins
+     */
+    _DNDEV_CONFIG_?: DndevFrameworkConfig;
+
+    /**
+     * Global store registry for singleton Zustand stores
+     * @description Ensures single instance across code-split chunks
+     */
+    _DNDEV_STORES_?: Record<string, any>;
+
+    /** PapaParse CSV parser library (external) */
+    Papa?: {
+      parse: (input: string | File, config?: any) => any;
+      unparse: (data: any[], config?: any) => string;
+    };
+
+    /** Sentry error tracking library (external) */
+    Sentry?: {
+      captureException: (error: unknown) => void;
+      withScope: (callback: (scope: any) => void) => void;
+      getClient: () => { close: () => Promise<boolean> } | undefined;
+    };
+
+    /**
+     * Google APIs (Maps, One Tap, etc.)
+     * @description Unified type for all Google services
+     */
+    google?: {
+      /** Google Maps API */
+      maps?: {
+        places?: {
+          AutocompleteService: new () => any;
+          PlacesService: new (element: HTMLElement) => any;
+          PlacesServiceStatus: {
+            OK: string;
+          };
+        };
+        [key: string]: any;
+      };
+      /** Google Identity Services (One Tap) */
+      accounts?: {
+        id?: {
+          initialize: (config: any) => void;
+          prompt: (callback?: (notification: any) => void) => void;
+          cancel?: () => void;
+          disableAutoSelect?: () => void;
+        };
+      };
+      [key: string]: any;
+    };
+
+    /** FedCM Identity Credential API */
+    IdentityCredential?: any;
+  }
+
+  namespace NodeJS {
+    interface ProcessEnv {
+      /** Serialized framework config for Node.js environment */
+      _DNDEV_CONFIG_?: string;
+    }
+  }
+
+  namespace globalThis {
+    /** Framework configuration (same as window._DNDEV_CONFIG_) */
+    var _DNDEV_CONFIG_: DndevFrameworkConfig | undefined;
+    /** Store registry (same as window._DNDEV_STORES_) */
+    var _DNDEV_STORES_: Record<string, any> | undefined;
+
+    // Third-party framework globals (not owned by DoNotDev)
+    var __vite_plugin_react_preamble_installed__: boolean | undefined;
+    var __vite_hmr_port: number | undefined;
+    var __NEXT_DATA__: any | undefined;
+    var __REACT_QUERY_CLIENT__: any | undefined;
+    var __REACT_QUERY_PROVIDER__: any | undefined;
+    var __DNDEV_DEBUG: boolean | undefined;
+    var __FIREBASE_DEMO_MODE__: boolean | undefined;
+    // gc is already defined by Node.js globals - removed to avoid TS 5.9+ conflict
+    var getAvailableThemes: (() => string[]) | undefined;
+  }
+}
+
+// packages/core/types/src/functions/functionTypes.ts
+
+
+
+// =============================================================================
+// DEPLOYMENT CONFIGURATION TYPES (for functions.yaml generation)
+// =============================================================================
+
+/**
+ * Memory allocation options for Cloud Functions
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+type FunctionMemory =
+  | '128MB'
+  | '256MB'
+  | '512MB'
+  | '1GB'
+  | '2GB'
+  | '4GB'
+  | '8GB';
+
+/**
+ * Function trigger types
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+type FunctionTrigger =
+  | 'callable'
+  | 'http'
+  | 'pubsub'
+  | 'firestore'
+  | 'auth'
+  | 'storage'
+  | 'scheduled';
+
+/**
+ * Function-level deployment metadata
+ * @description Per-function configuration for Firebase deployment (like PageMeta for pages)
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface FunctionMeta {
+  /** Custom entry point name (defaults to export name) */
+  entryPoint?: string;
+  /** Deployment regions (overrides app defaults) */
+  region?: string[];
+  /** Platform version */
+  platform?: 'gcfv1' | 'gcfv2';
+  /** Category label for organization */
+  category?: 'auth' | 'crud' | 'analytics' | 'scheduled' | 'webhook' | string;
+  /** Additional labels */
+  labels?: Record<string, string>;
+  /** Trigger type (defaults to 'callable') */
+  trigger?: FunctionTrigger;
+  /** For scheduled functions - cron expression */
+  schedule?: string;
+  /** Memory allocation */
+  memory?: FunctionMemory;
+  /** Timeout in seconds */
+  timeoutSeconds?: number;
+  /** Minimum instances (for cold start optimization) */
+  minInstances?: number;
+  /** Maximum instances */
+  maxInstances?: number;
+}
+
+/**
+ * CRUD entity configuration for auto-generation
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface CrudConfig {
+  /** Entity collection names to generate CRUD for */
+  entities: string[];
+  /** Override defaults for all CRUD functions */
+  defaults?: Partial<FunctionMeta>;
+}
+
+/**
+ * App-level defaults for all functions
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface FunctionDefaults {
+  /** Default deployment regions */
+  region?: string[];
+  /** Default platform version */
+  platform?: 'gcfv1' | 'gcfv2';
+  /** App label for all functions */
+  labels?: Record<string, string>;
+  /** Default memory allocation */
+  memory?: FunctionMemory;
+  /** Default timeout in seconds */
+  timeoutSeconds?: number;
+}
+
+/**
+ * Complete functions configuration for an app
+ * @description Single config file pattern for functions.yaml generation
+ *
+ * @example
+ * ```typescript
+ * export const functionsConfig: FunctionsConfig = {
+ *   defaults: {
+ *     region: ['europe-west1'],
+ *     platform: 'gcfv2',
+ *     labels: { app: 'myapp' },
+ *   },
+ *   functions: {
+ *     setCustomClaims: { category: 'auth' },
+ *     getDashboardMetrics: { category: 'analytics', memory: '512MB' },
+ *   },
+ *   crud: {
+ *     entities: ['car', 'customer', 'inquiry'],
+ *   },
+ * };
+ * ```
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface FunctionsConfig {
+  /** App-level defaults applied to all functions */
+  defaults?: FunctionDefaults;
+  /** Static functions configuration (non-CRUD) */
+  functions?: Record<string, FunctionMeta>;
+  /** CRUD auto-generation configuration */
+  crud?: CrudConfig;
+}
+
+type $MergeBy<T, K> = Omit<T, keyof K> & K;
+
+type $PreservedValue<Value, Fallback> = [Value] extends [never] ? Fallback : Value;
+
+/**
+ * This interface can be augmented by users to add types to `i18next` default TypeOptions.
+ *
+ * Usage:
+ * ```ts
+ * // i18next.d.ts
+ * import 'i18next';
+ * declare module 'i18next' {
+ *   interface CustomTypeOptions {
+ *     defaultNS: 'custom';
+ *     returnNull: false;
+ *     returnObjects: false;
+ *     nsSeparator: ':';
+ *     keySeparator: '.';
+ *     compatibilityJSON: 'v4';
+ *     allowObjectInHTMLChildren: false;
+ *     resources: {
+ *       custom: {
+ *         foo: 'foo';
+ *       };
+ *     };
+ *   }
+ * }
+ * ```
+ */
+interface CustomTypeOptions {}
+
+type TypeOptions = $MergeBy<
+  {
+    /** @see {InitOptions.returnNull} */
+    returnNull: false;
+
+    /** @see {InitOptions.returnEmptyString} */
+    returnEmptyString: true;
+
+    /** @see {InitOptions.returnObjects} */
+    returnObjects: false;
+
+    /** @see {InitOptions.keySeparator} */
+    keySeparator: '.';
+
+    /** @see {InitOptions.nsSeparator} */
+    nsSeparator: ':';
+
+    /** @see {InitOptions.pluralSeparator} */
+    pluralSeparator: '_';
+
+    /** @see {InitOptions.contextSeparator} */
+    contextSeparator: '_';
+
+    /** @see {InitOptions.defaultNS} */
+    defaultNS: 'translation';
+
+    /** @see {InitOptions.fallbackNS} */
+    fallbackNS: false;
+
+    /** @see {InitOptions.compatibilityJSON} */
+    compatibilityJSON: 'v4';
+
+    /** @see {InitOptions.resources} */
+    resources: object;
+
+    /**
+     * Flag that allows HTML elements to receive objects. This is only useful for React applications
+     * where you pass objects to HTML elements so they can be replaced to their respective interpolation
+     * values (mostly with Trans component)
+     */
+    allowObjectInHTMLChildren: false;
+
+    /**
+     * Flag that enables strict key checking even if a `defaultValue` has been provided.
+     * This ensures all calls of `t` function don't accidentally use implicitly missing keys.
+     */
+    strictKeyChecks: false;
+
+    /**
+     * Prefix for interpolation
+     */
+    interpolationPrefix: '{{';
+
+    /**
+     * Suffix for interpolation
+     */
+    interpolationSuffix: '}}';
+
+    /** @see {InterpolationOptions.unescapePrefix} */
+    unescapePrefix: '-';
+
+    /** @see {InterpolationOptions.unescapeSuffix} */
+    unescapeSuffix: '';
+
+    /**
+     * Use a proxy-based selector to select a translation.
+     *
+     * Enables features like go-to definition, and better DX/faster autocompletion
+     * for TypeScript developers.
+     *
+     * If you're working with an especially large set of translations and aren't
+     * using context, you set `enableSelector` to `"optimize"` and i18next won't do
+     * any type-level processing of your translations at all.
+     *
+     * With `enableSelector` set to `"optimize"`, i18next is capable of supporting
+     * arbitrarily large/deep translation sets without causing any IDE slowdown
+     * whatsoever.
+     *
+     * @default false
+     */
+    enableSelector: false;
+  },
+  CustomTypeOptions
+>;
+
+type FlatNamespace = $PreservedValue<keyof TypeOptions['resources'], string>;
+type Namespace<T = FlatNamespace> = T | readonly T[];
+
+interface ReportNamespaces {
+  addUsedNamespaces(namespaces: Namespace): void;
+  getUsedNamespaces(): string[];
+}
+
+declare module 'i18next' {
+  // interface i18n {
+  //   reportNamespaces?: ReportNamespaces;
+  // }
+  interface CustomInstanceExtensions {
+    reportNamespaces?: ReportNamespaces;
+  }
+}
+
+type ObjectOrNever = TypeOptions['allowObjectInHTMLChildren'] extends true
+  ? Record<string, unknown>
+  : never;
+
+type ReactI18NextChildren = React.ReactNode | ObjectOrNever;
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicAttributes {
+      i18nIsDynamicList?: boolean;
+    }
+  }
+
+  interface HTMLAttributes<T> {
+    // This union is inspired by the typings for React.ReactNode. We do this to fix "This JSX tag's 'children' prop
+    // expects a single child of type 'ReactI18NextChildren', but multiple children were provided":
+    // https://github.com/DefinitelyTyped/DefinitelyTyped/blob/5a1e9f91ed0143adede394adb3f540e650455f71/types/react/index.d.ts#L268
+    children?: ReactI18NextChildren | Iterable<ReactI18NextChildren>;
+  }
+}
+
 // packages/core/config/functions/index.d.ts
 /**
  * @fileoverview Type Definitions for esbuild Configuration
@@ -748,5 +1805,28 @@ declare function createAppFunctionsConfig(
   options?: EsbuildOptions
 ): BuildOptions;
 
-export { createAppFunctionsConfig, createFunctionsEsbuildConfig, createRootFunctionsConfig };
+/**
+ * Generate functions.yaml content from config
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+declare function generateFunctionsYaml(config: FunctionsConfig): string;
+
+/**
+ * Generate yaml and return metadata
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+declare function generateFunctionsYamlWithInfo(config: FunctionsConfig): {
+  yaml: string;
+  functions: string[];
+  staticFunctions: string[];
+  crudFunctions: string[];
+};
+
+export { createAppFunctionsConfig, createFunctionsEsbuildConfig, createRootFunctionsConfig, generateFunctionsYaml, generateFunctionsYamlWithInfo };
 export type { EsbuildOptions };