@kuckit/sdk 1.0.0

package/README.md

@@ -0,0 +1,134 @@
+# @kuckit/sdk
+
+The Kuckit SDK provides the foundation for building modular applications with dependency injection, lifecycle management, and a plugin-style module system.
+
+## Features
+
+- **DI Container** - Awilix-based dependency injection with scoped lifetimes
+- **Module Loader** - Plugin system with lifecycle hooks for registering services and APIs
+- **Core Services** - Pre-configured logger, event bus, cache, rate limiter, and database pool
+- **Type Safety** - Full TypeScript support with typed container resolution
+
+## Installation
+
+```bash
+# Using bun
+bun add @kuckit/sdk
+
+# Using npm
+npm install @kuckit/sdk
+```
+
+## Quick Start
+
+### 1. Create a Container
+
+```ts
+import { createKuckitContainer, loadKuckitModules } from '@kuckit/sdk'
+
+const container = await createKuckitContainer({
+	config: {
+		databaseUrl: process.env.DATABASE_URL!,
+		enableFileLogging: false,
+		logDir: './logs',
+		logLevel: 'INFO',
+		env: 'development',
+	},
+})
+```
+
+### 2. Load Modules
+
+```ts
+import { kuckitModule as usersModule } from '@kuckit/users-module'
+
+await loadKuckitModules({
+	container,
+	env: 'development',
+	modules: [
+		{ module: usersModule, config: { enableCaching: true } },
+		{ package: '@acme/billing-module' }, // npm package
+	],
+	onApiRegistrations: (registrations) => {
+		// Wire API routes to your framework (Express, Hono, etc.)
+	},
+})
+```
+
+### 3. Resolve Services
+
+```ts
+const logger = container.resolve('logger')
+const userRepository = container.resolve('userRepository')
+
+logger.info('Application started')
+```
+
+## Core Services
+
+After `createKuckitContainer()`, these services are available:
+
+| Token              | Type               | Description                    |
+| ------------------ | ------------------ | ------------------------------ |
+| `config`           | `CoreConfig`       | Application configuration      |
+| `db`               | Drizzle instance   | Database query builder         |
+| `dbPool`           | `Pool`             | Raw PostgreSQL connection pool |
+| `logger`           | `Logger`           | Structured logging             |
+| `eventBus`         | `EventBus`         | Pub/sub event system           |
+| `clock`            | `Clock`            | Time abstraction (testable)    |
+| `cacheStore`       | `CacheStore`       | Key-value cache                |
+| `rateLimiterStore` | `RateLimiterStore` | Rate limiting                  |
+| `auth`             | Auth utilities     | Authentication helpers         |
+
+## Building Modules
+
+See [Module Development Guide](./docs/MODULE_DEVELOPMENT.md) for a complete guide on creating third-party modules.
+
+```ts
+import { defineKuckitModule, asClass } from '@kuckit/sdk'
+
+export const kuckitModule = defineKuckitModule({
+	id: 'acme.billing',
+	displayName: 'Billing',
+
+	register(ctx) {
+		ctx.container.register({
+			invoiceRepository: asClass(InvoiceRepository).scoped(),
+		})
+	},
+})
+```
+
+## API Reference
+
+### `createKuckitContainer(options)`
+
+Creates a DI container with core services registered.
+
+### `loadKuckitModules(options)`
+
+Loads and initializes modules through their lifecycle hooks.
+
+### `defineKuckitModule(definition)`
+
+Type-safe helper to define a module with metadata and hooks.
+
+### `disposeContainer(container)`
+
+Gracefully closes database connections and cleans up resources.
+
+## Re-exports
+
+The SDK re-exports useful utilities:
+
+```ts
+// Awilix helpers
+import { asClass, asFunction, asValue } from '@kuckit/sdk'
+
+// Core packages (for advanced use)
+import { Domain, Application, Contracts } from '@kuckit/sdk'
+```
+
+## License
+
+MIT