npm package: @kuckit/sdk
Description: The Kuckit SDK provides the foundation for building modular applications with dependency injection, lifecycle management, and a plugin-style module system.
Latest version: 6.0.0

# @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