npm package: @iota-big3/sdk-adapters
Description: Production-ready framework adapters for IOTA Big3 SDK - Express, Fastify, Koa with comprehensive middleware suite
Latest version: 2.0.0

# @iota-big3/sdk-adapters

Framework adapters for IOTA Big3 SDK - provides a unified interface for Express, Fastify, Koa, and other web frameworks.

## Current Status (December 2024)

- **Build**: ✅ TypeScript compilation successful (0 errors)
- **Tests**: ✅ 49/49 passing (100% pass rate, 3 skipped)
- **Phase**: Completed Phase 2e & 2h
- **Production Ready**: Yes (Express adapter fully implemented)
- **Documentation**: [Phase 2e & 2h Complete](./PHASE_2E_2H_COMPLETE.md)

## Installation

```bash
npm install @iota-big3/sdk-adapters
```

## Features

- 🚀 **Multi-Framework Support**: Express, Fastify, Koa (more coming)
- 🔌 **Middleware System**: CORS, Helmet, Rate Limiting, Compression, Logging
- 📊 **Metrics & Monitoring**: Built-in performance tracking
- 🔒 **Security**: Helmet security headers, rate limiting
- 🎯 **Type Safety**: Full TypeScript support
- 🔄 **Event-Driven**: Lifecycle events for all operations
- 🧩 **SDK Integrations**: Works with other IOTA Big3 SDKs

## Quick Start

```typescript
import { FrameworkAdaptersSDK } from "@iota-big3/sdk-adapters";

// Create SDK instance
const sdk = new FrameworkAdaptersSDK();

// Create an Express adapter
const adapter = sdk.createAdapter("express", {
  framework: "express",
  version: "4.18.0",
});

// Create Express app
const app = await adapter.createApp();

// Add middleware
const cors = MiddlewareHelpers.cors({
  origin: "https://example.com",
  credentials: true,
});
await adapter.addMiddleware(cors);

// Start server
app.listen(3000, () => {
  console.log("Server running on port 3000");
});
```

## SDK Integrations

The adapters SDK can integrate with other IOTA Big3 SDKs for enhanced functionality:

### With Event Bus

```typescript
import { EventBus } from "@iota-big3/sdk-events";

const eventBus = new EventBus();
const sdk = new FrameworkAdaptersSDK({ eventBus });

// Listen to adapter events
eventBus.on("adapters:route.registered", (event) => {
  console.log("New route registered:", event);
});
```

### With Logger

```typescript
import { Logger } from "@iota-big3/sdk-observability";

const logger = new Logger("my-app");
const sdk = new FrameworkAdaptersSDK({ logger });

// All adapter operations will be logged
```

### With Cache (Enhanced Rate Limiting)

```typescript
import { CacheManager } from "@iota-big3/sdk-performance";

const cache = new CacheManager({
  redis: { host: "localhost" },
});
const sdk = new FrameworkAdaptersSDK({ cache });

// Rate limiting now uses Redis instead of in-memory
```

### With Security

```typescript
import { SecurityManager } from "@iota-big3/sdk-security";

const security = new SecurityManager();
const sdk = new FrameworkAdaptersSDK({ security });

// Enhanced security validation for all requests
```

### Complete Integration Example

```typescript
import { FrameworkAdaptersSDK } from "@iota-big3/sdk-adapters";
import { EventBus } from "@iota-big3/sdk-events";
import { Logger } from "@iota-big3/sdk-observability";
import { CacheManager } from "@iota-big3/sdk-performance";

// Create SDK with multiple integrations
const sdk = new FrameworkAdaptersSDK({
  eventBus: new EventBus(),
  logger: new Logger("adapters"),
  cache: new CacheManager({ redis: { host: "localhost" } }),
  enableMetrics: true,
  enableLogging: true,
});

// Create adapter
const adapter = sdk.createAdapter("express", {
  framework: "express",
});

// Events are automatically forwarded to event bus
// Logging is automatic
// Rate limiting uses Redis cache
```

## Middleware

Built-in middleware helpers:

```typescript
import { MiddlewareHelpers } from "@iota-big3/sdk-adapters";

// CORS
const cors = MiddlewareHelpers.cors({
  origin: "https://example.com",
  methods: ["GET", "POST"],
  credentials: true,
});

// Security Headers
const helmet = MiddlewareHelpers.helmet({
  contentSecurityPolicy: true,
  hsts: true,
});

// Rate Limiting
const rateLimit = MiddlewareHelpers.rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // limit each IP to 100 requests per windowMs
});

// Request Logger
const logger = MiddlewareHelpers.logger({
  format: "combined",
});

// Compression
const compression = MiddlewareHelpers.compression({
  enabled: true,
});

// Error Handler
const errorHandler = MiddlewareHelpers.errorHandler({
  env: "production",
});
```

## Events

The SDK emits various events that can be listened to:

```typescript
// Direct event listening
adapter.on("route-registered", (data) => {
  console.log("Route registered:", data);
});

// Through event bus integration
eventBus.on("adapters:adapter.initialized", (event) => {
  console.log("Adapter initialized:", event);
});
```

## Configuration

The SDK can be configured through options or centralized config:

```typescript
// Option 1: Direct configuration
const sdk = new FrameworkAdaptersSDK({
  defaultFramework: "express",
  enableMetrics: true,
  enableLogging: true,
});

// Option 2: Through config integration
const config = new ConfigManager();
config.set("adapters", {
  defaultFramework: "fastify",
  enableMetrics: false,
});

const sdk = new FrameworkAdaptersSDK({ config });
```

## Documentation

See [https://docs.iota-big3.com](https://docs.iota-big3.com) for full documentation.

## License

MIT