@kuckit/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,620 @@
+import { AwilixContainer, AwilixContainer as AwilixContainer$1, Resolver, Resolver as Resolver$1, asClass, asFunction, asValue } from "awilix";
+import * as Domain from "@kuckit/domain";
+import { CacheStore, Clock, EventBus, Logger, RateLimiterStore } from "@kuckit/domain";
+import { auth } from "@kuckit/auth";
+import * as Application from "@kuckit/application";
+import * as Contracts from "@kuckit/contracts";
+import { PgTable, PgTable as PgTable$1 } from "drizzle-orm/pg-core";
+
+//#region src/types.d.ts
+/**
+ * Core SDK configuration
+ * This is the minimal config needed to bootstrap the SDK
+ */
+interface CoreConfig {
+  databaseUrl: string;
+  enableFileLogging: boolean;
+  logDir: string;
+  logLevel: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
+  env: string;
+}
+/**
+ * Core cradle interface - the stable contract for all SDK consumers
+ * This defines the services available in the DI container after core registration
+ *
+ * Keep this minimal and stable; breaking changes require major version bumps
+ */
+interface CoreCradle {
+  config: CoreConfig;
+  dbPool: unknown;
+  db: unknown;
+  clock: Clock;
+  logger: Logger;
+  errorHandler: unknown;
+  auth: typeof auth;
+  aiProvider: unknown;
+  eventBus: EventBus;
+  cacheStore: CacheStore;
+  rateLimiterStore: RateLimiterStore;
+  requestId?: string;
+  session?: {
+    user?: {
+      id?: string;
+    };
+  } | null;
+  requestLogger?: Logger;
+  [key: string]: Resolver$1<any> | any;
+}
+/**
+ * Core container type with CoreCradle
+ */
+type CoreContainer = AwilixContainer$1<CoreCradle>;
+//#endregion
+//#region src/core/container.d.ts
+interface CreateKuckitOptions {
+  /**
+   * Core configuration for the SDK
+   */
+  config: CoreConfig;
+  /**
+   * Optional callback to register additional services after core registration
+   */
+  extraRegistrations?: (container: CoreContainer) => void | Promise<void>;
+}
+/**
+ * Factory function to create a Kuckit DI container
+ *
+ * This is the primary entry point for applications using the SDK.
+ * It creates an Awilix container with core infrastructure services pre-registered.
+ *
+ * @example
+ * ```ts
+ * const container = await createKuckitContainer({
+ *   config: {
+ *     databaseUrl: process.env.DATABASE_URL!,
+ *     enableFileLogging: true,
+ *     logDir: './logs',
+ *     logLevel: 'INFO',
+ *     env: 'production',
+ *   },
+ *   extraRegistrations: (container) => {
+ *     // Register your custom services
+ *     container.register({
+ *       myService: asClass(MyService).singleton(),
+ *     })
+ *   },
+ * })
+ * ```
+ */
+declare const createKuckitContainer: (opts: CreateKuckitOptions) => Promise<CoreContainer>;
+/**
+ * Cleanup container resources gracefully
+ *
+ * Call this when shutting down your application to close database connections
+ * and other resources.
+ */
+declare const disposeContainer: (container: CoreContainer) => Promise<void>;
+//#endregion
+//#region src/core/core.module.d.ts
+/**
+ * Register core infrastructure services into the container
+ *
+ * This registers:
+ * - Database pool and connection
+ * - Clock
+ * - Logger (structured, Loki/Prometheus compatible)
+ * - AI provider
+ * - Auth
+ * - Event bus
+ * - Cache store
+ * - Rate limiter store
+ * - Request-scoped logger
+ */
+declare const registerCoreModule: (container: CoreContainer) => void;
+//#endregion
+//#region src/modules/types.d.ts
+/**
+ * Built-in capability types for common module features
+ */
+type BuiltInCapability = 'nav.item' | 'settings.page' | 'dashboard.widget' | 'api.webhook' | 'api.public' | 'slot.provider';
+/**
+ * Module capability type - built-in or custom
+ * Custom capabilities must be prefixed with 'custom.'
+ */
+type ModuleCapability = BuiltInCapability | `custom.${string}`;
+/**
+ * Module metadata for discovery and documentation
+ */
+interface KuckitModuleMeta {
+  /** Unique identifier, e.g., 'kuckit.users' or 'acme.billing' */
+  id: string;
+  /** Human-readable name */
+  displayName?: string;
+  /** Module description */
+  description?: string;
+  /** Module version */
+  version?: string;
+  /** Capabilities this module provides */
+  capabilities?: ModuleCapability[];
+}
+/**
+ * Context passed to module hooks
+ */
+interface KuckitModuleContext<TConfig = unknown> {
+  /** DI container for registering services */
+  container: CoreContainer;
+  /** Environment name (development, production, etc.) */
+  env: string;
+  /** Module-specific configuration */
+  config: TConfig;
+  /** Register a Drizzle schema for this module */
+  registerSchema: (tableName: string, schema: PgTable$1) => void;
+}
+/**
+ * API registration for oRPC routers or other API handlers
+ */
+interface ApiRegistration {
+  /** Type of API handler */
+  type: 'rpc-router' | 'rest-router' | 'graphql-resolver';
+  /** Router/handler name, e.g., 'users' */
+  name: string;
+  /** The actual router/handler instance */
+  router: unknown;
+  /** Optional path prefix */
+  prefix?: string;
+}
+/**
+ * Module lifecycle hooks
+ */
+interface KuckitModuleHooks<TConfig = unknown> {
+  /**
+   * Called early - register DI bindings (repositories, services, use cases)
+   * This is where you wire up your module's dependencies
+   */
+  register?(ctx: KuckitModuleContext<TConfig>): void | Promise<void>;
+  /**
+   * Called after all modules registered - register API endpoints
+   * Use addApiRegistration to contribute routes to the application
+   */
+  registerApi?(ctx: KuckitModuleContext<TConfig> & {
+    addApiRegistration: (reg: ApiRegistration) => void;
+  }): void | Promise<void>;
+  /**
+   * Called after everything is wired - final initialization
+   * Good place for startup tasks like cache warming, health checks, etc.
+   */
+  onBootstrap?(ctx: KuckitModuleContext<TConfig>): void | Promise<void>;
+  /**
+   * Optional: cleanup on shutdown
+   * Close connections, flush buffers, etc.
+   */
+  onShutdown?(ctx: KuckitModuleContext<TConfig>): void | Promise<void>;
+}
+/**
+ * Complete module definition combining metadata and hooks
+ */
+interface KuckitModuleDefinition<TConfig = unknown> extends KuckitModuleMeta, KuckitModuleHooks<TConfig> {}
+/**
+ * Module specification in application config
+ *
+ * You can specify a module in two ways:
+ * 1. `module`: Direct reference to a module definition (preferred in monorepos)
+ * 2. `package`: NPM package name for dynamic import (for published packages)
+ */
+interface ModuleSpec<TConfig = unknown> {
+  /** Direct module definition (preferred in monorepos for better type safety) */
+  module?: KuckitModuleDefinition<TConfig>;
+  /** NPM package name or relative path for dynamic import, e.g., '@acme/billing-module' */
+  package?: string;
+  /** Module-specific configuration */
+  config?: TConfig;
+  /** Whether to skip this module */
+  disabled?: boolean;
+}
+//#endregion
+//#region src/modules/define-module.d.ts
+/**
+ * Helper to define a Kuckit module with type safety
+ *
+ * This is the primary way to create a module for the Kuckit SDK.
+ * It provides type inference for the configuration and validates
+ * the module structure at compile time.
+ *
+ * @example
+ * ```ts
+ * // In your module's main file (e.g., src/module.ts)
+ * import { defineKuckitModule, asClass, asFunction } from '@kuckit/sdk'
+ *
+ * interface BillingModuleConfig {
+ *   currency: string
+ *   taxRate: number
+ * }
+ *
+ * export const kuckitModule = defineKuckitModule<BillingModuleConfig>({
+ *   id: 'acme.billing',
+ *   displayName: 'Billing',
+ *   description: 'Invoice and payment processing',
+ *   version: '1.0.0',
+ *
+ *   register(ctx) {
+ *     ctx.container.register({
+ *       invoiceRepository: asClass(DrizzleInvoiceRepository).scoped(),
+ *       paymentService: asFunction(makePaymentService).singleton(),
+ *     })
+ *   },
+ *
+ *   registerApi(ctx) {
+ *     ctx.addApiRegistration({
+ *       type: 'rpc-router',
+ *       name: 'billing',
+ *       router: createBillingRouter(ctx.container),
+ *     })
+ *   },
+ *
+ *   onBootstrap(ctx) {
+ *     const logger = ctx.container.resolve('logger')
+ *     logger.info(`Billing module initialized with currency: ${ctx.config.currency}`)
+ *   },
+ * })
+ * ```
+ *
+ * @param mod - The module definition object
+ * @returns The same module definition (for type inference)
+ */
+declare const defineKuckitModule: <TConfig = unknown>(mod: KuckitModuleDefinition<TConfig>) => KuckitModuleDefinition<TConfig>;
+//#endregion
+//#region src/modules/loader.d.ts
+interface LoadModulesOptions {
+  /** DI container to register services into */
+  container: CoreContainer;
+  /** Environment name (development, production, etc.) */
+  env: string;
+  /** List of modules to load */
+  modules: ModuleSpec[];
+  /** Hook to wire collected API registrations into your router */
+  onApiRegistrations?: (regs: ApiRegistration[]) => void | Promise<void>;
+  /** Hook called when all modules are loaded and bootstrapped */
+  onComplete?: () => void | Promise<void>;
+}
+/**
+ * Load and initialize Kuckit modules
+ *
+ * This function orchestrates the module loading lifecycle:
+ *
+ * 1. **Import Phase**: Dynamic import each module package
+ * 2. **Register Phase**: Run register() hooks (DI bindings)
+ * 3. **API Phase**: Run registerApi() hooks (API routes)
+ * 4. **Wire Phase**: Call onApiRegistrations callback
+ * 5. **Bootstrap Phase**: Run onBootstrap() hooks
+ * 6. **Complete Phase**: Call onComplete callback
+ *
+ * @example
+ * ```ts
+ * await loadKuckitModules({
+ *   container,
+ *   env: 'production',
+ *   modules: [
+ *     { package: '@kuckit/users-module' },
+ *     { package: '@acme/billing-module', config: { currency: 'USD' } },
+ *     { package: './src/modules/custom', disabled: process.env.DISABLE_CUSTOM === 'true' },
+ *   ],
+ *   onApiRegistrations: (registrations) => {
+ *     // Wire up oRPC routers, REST routes, etc.
+ *     for (const reg of registrations) {
+ *       if (reg.type === 'rpc-router') {
+ *         rootRouter.merge(reg.name, reg.router)
+ *       }
+ *     }
+ *   },
+ *   onComplete: () => {
+ *     console.log('All modules loaded!')
+ *   },
+ * })
+ * ```
+ */
+declare const loadKuckitModules: (opts: LoadModulesOptions) => Promise<void>;
+/**
+ * Create a shutdown handler for loaded modules
+ *
+ * Returns a function that calls onShutdown() on all modules in reverse order.
+ * Call this during graceful shutdown.
+ *
+ * @example
+ * ```ts
+ * const shutdown = createModuleShutdownHandler(loadedModules, container, env)
+ *
+ * process.on('SIGTERM', async () => {
+ *   await shutdown()
+ *   process.exit(0)
+ * })
+ * ```
+ */
+declare const createModuleShutdownHandler: (modules: KuckitModuleDefinition[], container: CoreContainer, env: string) => (() => Promise<void>);
+//#endregion
+//#region src/modules/registry.d.ts
+/**
+ * Information about a loaded module
+ */
+interface LoadedModuleInfo {
+  /** Module unique identifier */
+  id: string;
+  /** Human-readable name */
+  displayName?: string;
+  /** Module description */
+  description?: string;
+  /** Module version */
+  version?: string;
+  /** Capabilities this module provides */
+  capabilities: ModuleCapability[];
+}
+/**
+ * Registry for loaded Kuckit modules
+ *
+ * Tracks all loaded modules and their capabilities for querying.
+ */
+declare class ModuleRegistry {
+  private modules;
+  private frozen;
+  /**
+   * Register a loaded module
+   * @throws Error if registry is frozen or module ID already exists
+   */
+  register(module: KuckitModuleDefinition): void;
+  /**
+   * Get all registered modules
+   */
+  getAll(): LoadedModuleInfo[];
+  /**
+   * Get a module by ID
+   */
+  getById(id: string): LoadedModuleInfo | undefined;
+  /**
+   * Check if a module is registered
+   */
+  has(id: string): boolean;
+  /**
+   * Get all modules that have a specific capability
+   */
+  getWithCapability(capability: ModuleCapability): LoadedModuleInfo[];
+  /**
+   * Check if a specific module has a capability
+   */
+  hasCapability(moduleId: string, capability: ModuleCapability): boolean;
+  /**
+   * Get all unique capabilities across all modules
+   */
+  getAllCapabilities(): ModuleCapability[];
+  /**
+   * Freeze the registry to prevent further modifications
+   */
+  freeze(): void;
+  /**
+   * Check if registry is frozen
+   */
+  isFrozen(): boolean;
+  /**
+   * Get the number of registered modules
+   */
+  get size(): number;
+  /**
+   * Clear all modules (only works if not frozen)
+   */
+  clear(): void;
+}
+/**
+ * Get the global module registry
+ * Creates one if it doesn't exist
+ */
+declare function getModuleRegistry(): ModuleRegistry;
+/**
+ * Get all modules that have a specific capability
+ * Convenience function that uses the global registry
+ */
+declare function getModulesWithCapability(capability: ModuleCapability): LoadedModuleInfo[];
+/**
+ * Reset the global registry (mainly for testing)
+ */
+declare function resetModuleRegistry(): void;
+//#endregion
+//#region src/config/types.d.ts
+/**
+ * Configuration for a single Kuckit module
+ */
+interface KuckitModuleConfig<TConfig = unknown> {
+  /** NPM package name, e.g., '@kuckit/users-module' or '@acme/billing-module' */
+  package: string;
+  /** Module-specific configuration */
+  config?: TConfig;
+  /** Whether this module is enabled (default: true). Can use environment variables. */
+  enabled?: boolean;
+}
+/**
+ * Discovery configuration for auto-detecting modules
+ */
+interface KuckitDiscoveryConfig {
+  /** Enable auto-discovery of modules in node_modules (default: false) */
+  enabled?: boolean;
+  /** Glob patterns for module detection (default: ['@star/kuckit-star-module']) */
+  patterns?: string[];
+}
+/**
+ * Client-specific configuration
+ */
+interface KuckitClientConfig {
+  /** Component registry mode: 'global' or 'context' (default: 'context') */
+  componentRegistry?: 'global' | 'context';
+  /** Enable automatic route injection (default: true) */
+  routeInjection?: boolean;
+}
+/**
+ * Server-specific configuration
+ */
+interface KuckitServerConfig {
+  /** API route prefix (default: '/api') */
+  apiPrefix?: string;
+}
+/**
+ * Unified Kuckit configuration
+ *
+ * This is the single source of truth for both server and client module configuration.
+ * Place this in `kuckit.config.ts` at your project root.
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from '@kuckit/sdk'
+ *
+ * export default defineConfig({
+ *   modules: [
+ *     { package: '@kuckit/users-module' },
+ *     { package: '@acme/billing-module', config: { currency: 'USD' } },
+ *     {
+ *       package: '@acme/analytics-module',
+ *       enabled: process.env.NODE_ENV === 'production',
+ *     },
+ *   ],
+ *
+ *   server: {
+ *     apiPrefix: '/api',
+ *   },
+ *
+ *   client: {
+ *     routeInjection: true,
+ *   },
+ * })
+ * ```
+ */
+interface KuckitConfig {
+  /** List of modules to load */
+  modules: KuckitModuleConfig[];
+  /** Auto-discovery settings (Phase 3.2) */
+  discovery?: KuckitDiscoveryConfig;
+  /** Client-specific settings */
+  client?: KuckitClientConfig;
+  /** Server-specific settings */
+  server?: KuckitServerConfig;
+}
+/**
+ * Result of loading a Kuckit config file
+ */
+interface LoadedKuckitConfig extends KuckitConfig {
+  /** Path to the config file that was loaded */
+  _configPath: string;
+}
+//#endregion
+//#region src/config/define-config.d.ts
+/**
+ * Define a Kuckit configuration with full type safety.
+ *
+ * This helper provides IntelliSense support and type checking for your configuration.
+ *
+ * @example
+ * ```typescript
+ * // kuckit.config.ts
+ * import { defineConfig } from '@kuckit/sdk'
+ *
+ * export default defineConfig({
+ *   modules: [
+ *     { package: '@kuckit/users-module' },
+ *     { package: '@acme/billing-module', config: { currency: 'USD' } },
+ *   ],
+ *
+ *   server: {
+ *     apiPrefix: '/api',
+ *   },
+ *
+ *   client: {
+ *     routeInjection: true,
+ *   },
+ * })
+ * ```
+ */
+declare function defineConfig(config: KuckitConfig): KuckitConfig;
+//#endregion
+//#region src/config/loader.d.ts
+/**
+ * Find the config file path by searching from cwd upward
+ */
+declare function findConfigFile(cwd?: string): string | null;
+/**
+ * Check if a unified config file exists
+ */
+declare function hasUnifiedConfig(cwd?: string): boolean;
+/**
+ * Load Kuckit configuration from file
+ *
+ * Uses jiti for TypeScript support at runtime.
+ * Falls back to dynamic import for JS/MJS files.
+ *
+ * @param cwd - Directory to start searching from (default: process.cwd())
+ * @throws Error if config file not found or invalid
+ */
+declare function loadKuckitConfig(cwd?: string): Promise<LoadedKuckitConfig>;
+/**
+ * Try to load config, returning null if not found
+ */
+declare function tryLoadKuckitConfig(cwd?: string): Promise<LoadedKuckitConfig | null>;
+//#endregion
+//#region src/schema/registry.d.ts
+/**
+ * Entry for a registered schema
+ */
+interface SchemaEntry {
+  /** Module that owns this schema */
+  moduleId: string;
+  /** Table name identifier */
+  tableName: string;
+  /** Drizzle table schema */
+  schema: PgTable$1;
+}
+/**
+ * Registry for module-owned database schemas
+ *
+ * Allows modules to register their Drizzle schemas during the register() hook.
+ * The CLI uses this registry to aggregate schemas for drizzle-kit operations.
+ */
+declare class SchemaRegistry {
+  private schemas;
+  /**
+   * Register a schema from a module
+   * @param moduleId - Module identifier (e.g., 'acme.billing')
+   * @param tableName - Table name identifier (e.g., 'invoices')
+   * @param schema - Drizzle PgTable schema
+   */
+  register(moduleId: string, tableName: string, schema: PgTable$1): void;
+  /**
+   * Get all registered schemas
+   */
+  getAll(): Map<string, SchemaEntry>;
+  /**
+   * Get schemas registered by a specific module
+   */
+  getByModule(moduleId: string): SchemaEntry[];
+  /**
+   * Get all schemas as a flat object for drizzle-kit
+   * Keys are table names, values are PgTable schemas
+   */
+  getAllSchemas(): Record<string, PgTable$1>;
+  /**
+   * Check if any schemas are registered
+   */
+  hasSchemas(): boolean;
+  /**
+   * Get the count of registered schemas
+   */
+  get size(): number;
+  /**
+   * Clear all schemas (mainly for testing)
+   */
+  clear(): void;
+}
+/**
+ * Get the global schema registry
+ * Creates one if it doesn't exist
+ */
+declare function getSchemaRegistry(): SchemaRegistry;
+/**
+ * Reset the global schema registry (mainly for testing)
+ */
+declare function resetSchemaRegistry(): void;
+//#endregion
+export { type ApiRegistration, Application, type AwilixContainer, type BuiltInCapability, Contracts, type CoreConfig, type CoreContainer, type CoreCradle, type CreateKuckitOptions, Domain, type KuckitClientConfig, type KuckitConfig, type KuckitDiscoveryConfig, type KuckitModuleConfig, type KuckitModuleContext, type KuckitModuleDefinition, type KuckitModuleHooks, type KuckitModuleMeta, type KuckitServerConfig, type LoadModulesOptions, type LoadedKuckitConfig, type LoadedModuleInfo, type ModuleCapability, ModuleRegistry, type ModuleSpec, type PgTable, type Resolver, type SchemaEntry, SchemaRegistry, asClass, asFunction, asValue, createKuckitContainer, createModuleShutdownHandler, defineConfig, defineKuckitModule, disposeContainer, findConfigFile, getModuleRegistry, getModulesWithCapability, getSchemaRegistry, hasUnifiedConfig, loadKuckitConfig, loadKuckitModules, registerCoreModule, resetModuleRegistry, resetSchemaRegistry, tryLoadKuckitConfig };