@breadstone/archipel-mcp 0.0.15 → 0.0.16

package/data/packages/platform-core/index.md

@@ -0,0 +1,487 @@
+---
+title: platform-core
+description: Foundation library providing mapping, templates, event pub/sub, and shared utilities.
+order: 1
+tags: [core, mapping, templates, event-hub]
+package: '@breadstone/archipel-platform-core'
+---
+
+# platform-core
+
+The foundation library that every other Archipel package depends on. Provides object mapping, template engines, event pub/sub, and shared utilities.
+
+> **Note:** Configuration has moved to [`platform-configuration`](../platform-configuration/), caching to [`platform-caching`](../platform-caching/), and cryptography/OTP to [`platform-cryptography`](../platform-cryptography/). Re-exports are still available from `platform-core` for backward compatibility.
+
+**Package:** `@breadstone/archipel-platform-core`
+
+## Installation
+
+```typescript
+import {
+  ConfigModule,
+  ConfigRegistry,
+  MappingModule,
+  MappingService,
+  BcryptService,
+  CryptoService,
+  OtpService,
+  MemoryLayeredCache,
+  RedisLayeredCache,
+  ContentTemplateEngine,
+  EventHub,
+} from '@breadstone/archipel-platform-core';
+```
+
+---
+
+## Configuration System
+
+> **Extracted:** Configuration has been extracted into [`platform-configuration`](../platform-configuration/). The imports below still work via re-exports for backward compatibility. New code should import from `@breadstone/archipel-platform-configuration` directly.
+>
+> See the [Configuration Management guide](../../guides/configuration) for full documentation.
+
+### Defining Config Keys
+
+```typescript
+import { createConfigKey, type IConfigRegistryEntry } from '@breadstone/archipel-platform-core';
+
+// Type-safe config keys with phantom types
+const SMTP_HOST = createConfigKey<string>('SMTP_HOST');
+const SMTP_PORT = createConfigKey<number>('SMTP_PORT');
+const SMTP_SECURE = createConfigKey<boolean>('SMTP_SECURE');
+
+export const MY_MODULE_CONFIG_ENTRIES: ReadonlyArray<IConfigRegistryEntry> = [
+  { key: SMTP_HOST, module: 'my-module', required: true, description: 'SMTP server hostname' },
+  { key: SMTP_PORT, module: 'my-module', required: false, defaultValue: 587, description: 'SMTP port' },
+  { key: SMTP_SECURE, module: 'my-module', required: false, defaultValue: true },
+];
+```
+
+### Registering in a Module
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@breadstone/archipel-platform-core';
+import { MY_MODULE_CONFIG_ENTRIES } from './env';
+
+@Module({
+  imports: [ConfigModule.register('my-module', MY_MODULE_CONFIG_ENTRIES)],
+})
+export class MyModule {}
+```
+
+### Using the ConfigService
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@breadstone/archipel-platform-core';
+
+@Injectable()
+export class SmtpClient {
+  private readonly _host: string;
+  private readonly _port: number;
+
+  constructor(configService: ConfigService) {
+    this._host = configService.get<string>('SMTP_HOST');
+    this._port = configService.tryGet<number>('SMTP_PORT', 587);
+  }
+}
+```
+
+### ConfigRegistry (Static Access)
+
+```typescript
+import { ConfigRegistry } from '@breadstone/archipel-platform-core';
+
+// List all registered modules
+const modules = ConfigRegistry.getModules(); // ['my-module', 'platform-auth', ...]
+
+// Get all required entries
+const required = ConfigRegistry.getRequired();
+
+// Get entries grouped by module
+const grouped = ConfigRegistry.getByModule();
+```
+
+---
+
+## Caching
+
+Layered caching with pluggable backends, metrics, and stale-while-revalidate support.
+
+### ILayeredCache Interface
+
+```typescript
+interface ILayeredCache<TKey, TValue> {
+  get(key: TKey): TValue | undefined;
+  getAsync(key: TKey): Promise<TValue | undefined>;
+  set(key: TKey, value: TValue): void;
+  setAsync(key: TKey, value: TValue): Promise<void>;
+  invalidate(key: TKey): void;
+  invalidateAsync(key: TKey): Promise<void>;
+  warm?(key: TKey): Promise<TValue | undefined>;
+  stats?(): ICacheStats;
+}
+```
+
+### MemoryLayeredCache
+
+In-memory LRU cache with TTL and stale-while-revalidate.
+
+```typescript
+import { MemoryLayeredCache } from '@breadstone/archipel-platform-core';
+
+const productCache = new MemoryLayeredCache<string, IProduct>(
+  async (key) => {
+    // Load function — called on cache miss
+    return await this._productRepository.findById(key);
+  },
+  {
+    ttlMs: 60_000, // 60 seconds TTL
+    staleWhileRevalidate: true, // Serve stale data while refreshing
+    maxEntries: 1000, // LRU eviction after 1000 entries
+    cacheName: 'products', // For metrics labeling
+    metricsRecorder: telemetryRecorder,
+  },
+);
+
+// Usage
+const product = await productCache.getAsync('prod-123');
+
+// Invalidate after mutation
+productCache.invalidate('prod-123');
+
+// Check stats
+const stats = productCache.stats();
+// → { hits: 142, misses: 23, loads: 23, loadErrors: 0, evictions: 0 }
+```
+
+### RedisLayeredCache
+
+Redis-backed distributed cache for multi-instance deployments.
+
+```typescript
+import { RedisLayeredCache } from '@breadstone/archipel-platform-core';
+
+const sessionCache = new RedisLayeredCache<string, ISessionData>(
+  async (key) => await this._sessionStore.findByToken(key),
+  {
+    url: 'redis://localhost:6379',
+    keyPrefix: 'session:',
+    ttlSeconds: 3600,
+    serialize: (value) => JSON.stringify(value),
+    deserialize: (raw) => JSON.parse(raw),
+    cacheName: 'sessions',
+  },
+);
+```
+
+### ICacheMetricsRecorder
+
+Integrate cache metrics with your observability stack.
+
+```typescript
+import type { ICacheMetricsRecorder } from '@breadstone/archipel-platform-core';
+
+class MyMetricsRecorder implements ICacheMetricsRecorder {
+  public recordHit(cache: string): void {
+    /* prometheus counter */
+  }
+  public recordMiss(cache: string): void {
+    /* prometheus counter */
+  }
+  public recordLoadSuccess(cache: string): void {
+    /* ... */
+  }
+  public recordLoadError(cache: string): void {
+    /* ... */
+  }
+  public recordEviction(cache: string): void {
+    /* ... */
+  }
+}
+```
+
+---
+
+## Mapping Service
+
+Centralized object mapping with type-safe keys and profiles.
+
+### Defining Mapping Keys
+
+```typescript
+import { createMappingKey } from '@breadstone/archipel-platform-core';
+import type { IUserEntity } from './entities';
+import type { UserResponse } from './responses';
+
+export const USER_TO_RESPONSE = createMappingKey<IUserEntity, UserResponse>('UserEntity→UserResponse');
+export const USER_TO_SUMMARY = createMappingKey<IUserEntity, UserSummary>('UserEntity→UserSummary');
+```
+
+### Creating a Mapping Profile
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { MappingProfileBase, type IMappingBuilder } from '@breadstone/archipel-platform-core';
+import { USER_TO_RESPONSE, USER_TO_SUMMARY } from './mapping-keys';
+
+@Injectable()
+export class UserMappingProfile extends MappingProfileBase {
+  public override configure(builder: IMappingBuilder): void {
+    builder.createKeyedMap(USER_TO_RESPONSE, (source) => ({
+      id: source.id,
+      name: source.userName,
+      email: source.email,
+      verified: source.isVerified,
+      roles: [...source.roles],
+    }));
+
+    builder.createKeyedMap(USER_TO_SUMMARY, (source) => ({
+      id: source.id,
+      displayName: source.userName ?? source.email ?? 'Anonymous',
+    }));
+  }
+}
+```
+
+### Registering Profiles in a Module
+
+```typescript
+import { Module } from '@nestjs/common';
+import { MappingModule } from '@breadstone/archipel-platform-core';
+import { UserMappingProfile } from './mappers/UserMappingProfile';
+import { OrderMappingProfile } from './mappers/OrderMappingProfile';
+
+@Module({
+  imports: [MappingModule.withProfiles([UserMappingProfile, OrderMappingProfile])],
+})
+export class AppModule {}
+```
+
+### Using in a Controller
+
+```typescript
+import { Controller, Get, Param } from '@nestjs/common';
+import { MappingService } from '@breadstone/archipel-platform-core';
+import { USER_TO_RESPONSE } from './mapping-keys';
+
+@Controller('users')
+export class UserController {
+  constructor(
+    private readonly _userService: UserService,
+    private readonly _mappingService: MappingService,
+  ) {}
+
+  @Get(':id')
+  public async getUser(@Param('id') id: string): Promise<UserResponse> {
+    const entity = await this._userService.findById(id);
+    return this._mappingService.map(USER_TO_RESPONSE, entity);
+  }
+}
+```
+
+---
+
+## Cryptography & OTP
+
+### BcryptService
+
+Password hashing with bcrypt.
+
+```typescript
+import { BcryptService } from '@breadstone/archipel-platform-core';
+
+@Injectable()
+export class AccountService {
+  constructor(private readonly _bcrypt: BcryptService) {}
+
+  public async register(password: string): Promise<void> {
+    const hash = await this._bcrypt.hash(password);
+    // Store hash in database
+  }
+
+  public async verifyPassword(input: string, storedHash: string): Promise<boolean> {
+    return this._bcrypt.compare(input, storedHash);
+  }
+}
+```
+
+### CryptoService
+
+UUID-based identifier generation.
+
+```typescript
+import { CryptoService } from '@breadstone/archipel-platform-core';
+
+const crypto = new CryptoService();
+const token = crypto.getRandomGuid('verify');
+// → "verify-a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+```
+
+### OtpService
+
+TOTP one-time password generation and verification (otplib).
+
+```typescript
+import { OtpService } from '@breadstone/archipel-platform-core';
+import type { IOtpService } from '@breadstone/archipel-platform-core';
+
+@Injectable()
+export class MfaSetupService {
+  constructor(@Inject(OTP_SERVICE_TOKEN) private readonly _otp: IOtpService) {}
+
+  public setup(userEmail: string): { secret: string; uri: string } {
+    const secret = this._otp.generateSecret();
+    const uri = this._otp.generateUri({
+      issuer: 'MyApp',
+      label: userEmail,
+      secret,
+    });
+    return { secret, uri };
+  }
+
+  public verify(token: string, secret: string): boolean {
+    return this._otp.verify(token, secret);
+    // Window = 1 → accepts current + previous 30s interval
+  }
+}
+```
+
+---
+
+## Event System
+
+Type-safe publish/subscribe with RxJS.
+
+### Defining Events
+
+```typescript
+import { createEventKey, type IEventMap } from '@breadstone/archipel-platform-core';
+
+interface IOrderEvents extends IEventMap {
+  'order.created': { orderId: string; userId: string };
+  'order.shipped': { orderId: string; trackingNumber: string };
+  'order.cancelled': { orderId: string; reason: string };
+}
+
+export const ORDER_CREATED = createEventKey<IOrderEvents, 'order.created'>('order.created');
+export const ORDER_SHIPPED = createEventKey<IOrderEvents, 'order.shipped'>('order.shipped');
+```
+
+### Publishing & Subscribing
+
+```typescript
+import { EventHub } from '@breadstone/archipel-platform-core';
+import { ORDER_CREATED, ORDER_SHIPPED } from './events';
+
+@Injectable()
+export class OrderService {
+  constructor(private readonly _events: EventHub) {}
+
+  public async createOrder(userId: string): Promise<void> {
+    const orderId = '...';
+    // ... create order logic
+
+    this._events.publish(ORDER_CREATED, { orderId, userId });
+  }
+}
+
+@Injectable()
+export class NotificationService {
+  constructor(events: EventHub) {
+    events.subscribe(ORDER_CREATED, (payload) => {
+      // payload is typed as { orderId: string; userId: string }
+      this.sendOrderConfirmation(payload.userId, payload.orderId);
+    });
+  }
+}
+```
+
+---
+
+## Content Template Engine
+
+Handlebars-style template compilation with block helpers.
+
+```typescript
+import { ContentTemplateEngine } from '@breadstone/archipel-platform-core';
+
+const engine = new ContentTemplateEngine();
+
+// Simple variable substitution
+const result = engine.compileTemplate('Hello {{name}}, welcome to {{app}}!', { name: 'Alice', app: 'MyApp' });
+// → "Hello Alice, welcome to MyApp!"
+
+// Block helpers
+const list = engine.compileTemplate('{{#each items}}- {{this.name}}: {{this.price}}€\n{{/each}}', {
+  items: [
+    { name: 'Widget', price: 9.99 },
+    { name: 'Gadget', price: 19.99 },
+  ],
+});
+
+// Conditionals
+const conditional = engine.compileTemplate('{{#if isPremium}}Premium Member{{/if}}{{#if !isPremium}}Free Tier{{/if}}', {
+  isPremium: true,
+});
+```
+
+---
+
+## Identifier Generation
+
+Pluggable ID generation via `IdentifierModule`.
+
+```typescript
+import { IdentifierModule, ID_GENERATOR_TOKEN, type IIdGenerator } from '@breadstone/archipel-platform-core';
+
+// Module setup — choose strategy
+@Module({
+  imports: [IdentifierModule.register('CUID')],
+})
+export class AppModule {}
+
+// Usage in a service
+@Injectable()
+export class OrderService {
+  constructor(@Inject(ID_GENERATOR_TOKEN) private readonly _idGen: IIdGenerator) {}
+
+  public createOrder(): string {
+    return this._idGen.generate(); // CUID, UUID, or GUID depending on registration
+  }
+}
+```
+
+---
+
+## Utility Services
+
+| Service                      | Purpose                                                                  |
+| ---------------------------- | ------------------------------------------------------------------------ |
+| `DeviceParserService`        | Parse `User-Agent` headers into `IDeviceInfo` (browser, OS, device type) |
+| `HostService`                | Host configuration (title, logo, features, health endpoints)             |
+| `UserAvatarGeneratorService` | Generate deterministic avatars from user identifiers                     |
+| `UsernameGeneratorService`   | Generate random usernames from word lists                                |
+
+---
+
+## Module Summary
+
+| Export                  | Type          | Description                                                                         |
+| ----------------------- | ------------- | ----------------------------------------------------------------------------------- |
+| `ConfigModule`          | NestJS Module | Configuration registration and validation (re-export from `platform-configuration`) |
+| `MappingModule`         | NestJS Module | Mapping profile registration                                                        |
+| `EventModule`           | NestJS Module | Event pub/sub system                                                                |
+| `IdentifierModule`      | NestJS Module | ID generation strategy                                                              |
+| `HostModule`            | NestJS Module | Host services and templates                                                         |
+| `HealthModule`          | NestJS Module | Health check orchestration                                                          |
+| `MappingService`        | Service       | Central object mapping                                                              |
+| `ConfigService`         | Service       | Type-safe config access (re-export from `platform-configuration`)                   |
+| `BcryptService`         | Service       | Password hashing                                                                    |
+| `CryptoService`         | Service       | UUID generation                                                                     |
+| `OtpService`            | Service       | TOTP generation/verification                                                        |
+| `EventHub`              | Service       | Event publish/subscribe                                                             |
+| `ContentTemplateEngine` | Service       | Template compilation                                                                |
+| `MemoryLayeredCache`    | Class         | In-memory LRU cache                                                                 |
+| `RedisLayeredCache`     | Class         | Redis-backed cache                                                                  |

package/data/packages/platform-cryptography/api/Class.BcryptService.md

@@ -0,0 +1,95 @@
+---
+title: 'Class: BcryptService'
+generated: true
+editUrl: false
+---
+# Class: BcryptService
+
+Defined in: [BcryptService.ts:40](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-cryptography/src/BcryptService.ts#L40)
+
+The `BcryptService` class.
+Provides bcrypt hashing and comparison with configurable salt rounds,
+optional pepper (HMAC pre-hash), and SHA-256 pre-hash for passwords
+exceeding bcrypt's 72-byte input limit.
+
+## Constructors
+
+### Constructor
+
+```ts
+new BcryptService(options?): BcryptService;
+```
+
+Defined in: [BcryptService.ts:56](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-cryptography/src/BcryptService.ts#L56)
+
+Initializes a new instance of the `BcryptService` class.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `options?` | [`IBcryptOptions`](Interface.IBcryptOptions) | Optional bcrypt configuration. When omitted, defaults to 12 rounds and no pepper. |
+
+#### Returns
+
+`BcryptService`
+
+## Methods
+
+### compare()
+
+```ts
+compare(data, encrypted): Promise<boolean>;
+```
+
+Defined in: [BcryptService.ts:98](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-cryptography/src/BcryptService.ts#L98)
+
+Compares the given data with the encrypted data.
+
+Uses bcrypt's native `compare()` function which performs a
+**constant-time** comparison internally, preventing timing-based
+side-channel attacks. The same password preparation (pepper / SHA-256
+pre-hash) is applied to the input before comparison so behaves
+symmetrically with [BcryptService.hash](#hash).
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `data` | `string` | The data to be compared. |
+| `encrypted` | `string` | The encrypted data to be compared. |
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+`true` if the data matches the encrypted hash; otherwise `false`.
+
+***
+
+### hash()
+
+```ts
+hash(data): Promise<string>;
+```
+
+Defined in: [BcryptService.ts:77](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-cryptography/src/BcryptService.ts#L77)
+
+Hashes the given data using bcrypt with a generated salt.
+
+When a pepper is configured, the input is HMAC-SHA-256'd first,
+which both adds a server-side secret and normalizes the length.
+When no pepper is set but the input exceeds 72 bytes, a SHA-256
+pre-hash is applied to prevent silent bcrypt truncation.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `data` | `string` | The data to be hashed. |
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The bcrypt hash string.

package/data/packages/platform-cryptography/api/Class.CryptoService.md

@@ -0,0 +1,51 @@
+---
+title: 'Class: CryptoService'
+generated: true
+editUrl: false
+---
+# Class: CryptoService
+
+Defined in: [CryptoService.ts:15](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-cryptography/src/CryptoService.ts#L15)
+
+The `CryptoService` class.
+Represents the service that provides cryptographic operations.
+
+## Constructors
+
+### Constructor
+
+```ts
+new CryptoService(): CryptoService;
+```
+
+Defined in: [CryptoService.ts:21](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-cryptography/src/CryptoService.ts#L21)
+
+Initializes a new instance of the `CryptoService` class.
+
+#### Returns
+
+`CryptoService`
+
+## Methods
+
+### getRandomGuid()
+
+```ts
+getRandomGuid(prefix): string;
+```
+
+Defined in: [CryptoService.ts:36](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-cryptography/src/CryptoService.ts#L36)
+
+Generates a random GUID prefixed with the given string.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `prefix` | `string` | The prefix to prepend to the generated UUID. |
+
+#### Returns
+
+`string`
+
+The prefixed UUID string.

package/data/packages/platform-cryptography/api/Class.CryptographyError.md

@@ -0,0 +1,56 @@
+---
+title: 'Abstract Class: CryptographyError'
+generated: true
+editUrl: false
+---
+# Abstract Class: CryptographyError
+
+Defined in: [errors/CryptographyError.ts:7](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-cryptography/src/errors/CryptographyError.ts#L7)
+
+Base class for cryptography-related domain errors.
+
+## Extends
+
+- `Error`
+
+## Extended by
+
+- [`InvalidOtpError`](Class.InvalidOtpError)
+- [`WeakPasswordError`](Class.WeakPasswordError)
+
+## Constructors
+
+### Constructor
+
+```ts
+protected new CryptographyError(message, code): CryptographyError;
+```
+
+Defined in: [errors/CryptographyError.ts:16](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-cryptography/src/errors/CryptographyError.ts#L16)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `message` | `string` |
+| `code` | `string` |
+
+#### Returns
+
+`CryptographyError`
+
+#### Overrides
+
+```ts
+Error.constructor
+```
+
+## Properties
+
+### code
+
+```ts
+readonly code: string;
+```
+
+Defined in: [errors/CryptographyError.ts:10](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-cryptography/src/errors/CryptographyError.ts#L10)