@breadstone/archipel-mcp 0.0.13 → 0.0.14

package/data/guides/getting-started.md

@@ -1,351 +0,0 @@
----
-title: Getting Started
-description: Set up an Archipel-powered NestJS application from scratch.
-order: 1
----
-
-# Getting Started
-
-This guide walks you through adding Archipel packages to a NestJS application. By the end, you'll have a working setup with configuration management, database access, and authentication.
-
-## Prerequisites
-
-- Node.js 20 or later
-- A NestJS application (v10+)
-- PostgreSQL database (for `platform-database`)
-- Prisma CLI (`npx prisma`)
-
-## Install the Foundation
-
-Every Archipel application starts with `platform-core`. It provides configuration management, object mapping, caching, and cryptographic utilities that other packages depend on.
-
-```bash
-yarn add @breadstone/archipel-platform-core
-```
-
-### Set Up Configuration
-
-Archipel uses a type-safe configuration system. Instead of reading `process.env` directly, you define typed config keys and register them with the `ConfigModule`. This gives you compile-time safety, centralized validation, and default values — all scoped to your module.
-
-Create a config file for your application:
-
-```typescript
-// src/env.ts
-import { createConfigKey, type IConfigRegistryEntry } from '@breadstone/archipel-platform-core';
-
-export const DATABASE_URL = createConfigKey<string>('DATABASE_URL');
-export const JWT_SECRET = createConfigKey<string>('JWT_SECRET');
-export const JWT_EXPIRATION = createConfigKey<string>('JWT_EXPIRATION');
-
-export const APP_CONFIG_ENTRIES: ReadonlyArray<IConfigRegistryEntry> = [
-  { key: DATABASE_URL, module: 'app', required: true, description: 'PostgreSQL connection string' },
-  { key: JWT_SECRET, module: 'app', required: true, description: 'Secret for signing JWTs' },
-  { key: JWT_EXPIRATION, module: 'app', required: false, defaultValue: '1h', description: 'JWT token lifetime' },
-];
-```
-
-Register it in your root module:
-
-```typescript
-// src/app.module.ts
-import { Module } from '@nestjs/common';
-import { ConfigModule } from '@breadstone/archipel-platform-core';
-import { APP_CONFIG_ENTRIES } from './env';
-
-@Module({
-  imports: [ConfigModule.register('app', APP_CONFIG_ENTRIES)],
-})
-export class AppModule {}
-```
-
-Now you can inject `ConfigService` anywhere and read values with full type safety:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { ConfigService } from '@breadstone/archipel-platform-core';
-import { JWT_SECRET } from './env';
-
-@Injectable()
-export class TokenService {
-  private readonly _secret: string;
-
-  constructor(configService: ConfigService) {
-    this._secret = configService.get(JWT_SECRET);
-    // TypeScript knows this is a string — no cast needed
-  }
-}
-```
-
-The `ConfigModule` validates all required keys at startup. If `DATABASE_URL` is missing from the environment, the application fails immediately with a clear error message instead of crashing later at runtime.
-
-### Set Up Object Mapping
-
-The `MappingModule` provides a centralized service for transforming domain entities into response DTOs. This keeps transformation logic out of your services and controllers and makes it testable in isolation.
-
-```typescript
-import { Module } from '@nestjs/common';
-import { ConfigModule, MappingModule } from '@breadstone/archipel-platform-core';
-import { APP_CONFIG_ENTRIES } from './env';
-import { UserMappingProfile } from './mapping/UserMappingProfile';
-
-@Module({
-  imports: [ConfigModule.register('app', APP_CONFIG_ENTRIES), MappingModule],
-  providers: [UserMappingProfile],
-})
-export class AppModule {}
-```
-
-You define mapping profiles that register transformations:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { MappingProfileBase, type MappingRegistry } from '@breadstone/archipel-platform-core';
-import { USER_TO_RESPONSE } from './mapping-keys';
-
-@Injectable()
-export class UserMappingProfile extends MappingProfileBase {
-  public override configure(registry: MappingRegistry): void {
-    registry.createMap(USER_TO_RESPONSE, (source: IUserEntity) => ({
-      id: source.id,
-      name: source.userName,
-      email: source.email,
-    }));
-  }
-}
-```
-
-Then use `MappingService.map()` in controllers to convert entities to responses without leaking mapping logic into services.
-
----
-
-## Add Database Access
-
-Install the database package:
-
-```bash
-yarn add @breadstone/archipel-platform-database
-```
-
-`platform-database` provides a repository + query pattern on top of Prisma. Instead of calling Prisma directly from services, you define query objects and execute them through a repository base class. This keeps data access logic encapsulated, testable, and separate from business logic.
-
-Register the module:
-
-```typescript
-// src/app.module.ts
-import { Module } from '@nestjs/common';
-import { ConfigModule, MappingModule } from '@breadstone/archipel-platform-core';
-import { DatabaseModule } from '@breadstone/archipel-platform-database';
-import { APP_CONFIG_ENTRIES } from './env';
-
-@Module({
-  imports: [ConfigModule.register('app', APP_CONFIG_ENTRIES), MappingModule, DatabaseModule.register()],
-})
-export class AppModule {}
-```
-
-### Define Queries
-
-A query is a plain object that describes a database operation. It receives a Prisma client and returns a result:
-
-```typescript
-// src/users/queries/findUserByIdQuery.ts
-import { type IRepositoryQuery } from '@breadstone/archipel-platform-database';
-import { type PrismaClient } from '@prisma/client';
-
-export interface IUserEntity {
-  id: string;
-  userName: string;
-  email: string;
-}
-
-export const findUserByIdQuery = (id: string): IRepositoryQuery<PrismaClient, IUserEntity | null> => ({
-  execute: (prisma) =>
-    prisma.user.findUnique({
-      where: { id },
-      select: { id: true, userName: true, email: true },
-    }),
-});
-```
-
-### Create a Repository
-
-Repositories extend `RepositoryBase` and execute queries:
-
-```typescript
-// src/users/UserRepository.ts
-import { Injectable } from '@nestjs/common';
-import { RepositoryBase } from '@breadstone/archipel-platform-database';
-import { findUserByIdQuery, type IUserEntity } from './queries/findUserByIdQuery';
-
-@Injectable()
-export class UserRepository extends RepositoryBase {
-  public async findById(id: string): Promise<IUserEntity | null> {
-    return this.execute(findUserByIdQuery(id));
-  }
-}
-```
-
-This pattern means your services never touch Prisma directly. They call repository methods, which execute typed queries. When you need to test a service, you mock the repository — not Prisma internals.
-
----
-
-## Add Authentication
-
-Install the authentication package:
-
-```bash
-yarn add @breadstone/archipel-platform-authentication
-```
-
-Authentication is the first package where you encounter **ports** — abstract classes that define contracts between the library and your application. `AuthModule` requires four port implementations that tell it how to look up users, sessions, MFA state, and verification records in your specific data store.
-
-### Implement the Required Ports
-
-Here's the most important one — `AuthSubjectPort`, which handles user lookup:
-
-```typescript
-// src/adapters/PrismaAuthSubjectAdapter.ts
-import { Injectable } from '@nestjs/common';
-import { AuthSubjectPort, type IAuthSubject } from '@breadstone/archipel-platform-authentication';
-import { PrismaService } from '@breadstone/archipel-platform-database';
-
-@Injectable()
-export class PrismaAuthSubjectAdapter extends AuthSubjectPort {
-  private readonly _prisma: PrismaService;
-
-  constructor(prisma: PrismaService) {
-    super();
-    this._prisma = prisma;
-  }
-
-  public async findById(id: string): Promise<IAuthSubject | null> {
-    const user = await this._prisma.user.findUnique({
-      where: { id },
-      select: {
-        id: true,
-        userName: true,
-        email: true,
-        password: true,
-        isVerified: true,
-        isAnonymous: true,
-        roles: true,
-        mfaEnabled: true,
-      },
-    });
-
-    return user ?? null;
-  }
-
-  public async findByLogin(login: string): Promise<IAuthSubject | null> {
-    const user = await this._prisma.user.findFirst({
-      where: { OR: [{ userName: login }, { email: login }] },
-      select: {
-        id: true,
-        userName: true,
-        email: true,
-        password: true,
-        isVerified: true,
-        isAnonymous: true,
-        roles: true,
-        mfaEnabled: true,
-      },
-    });
-
-    return user ?? null;
-  }
-
-  public async findAnonymous(userName: string): Promise<IAuthSubject | null> {
-    const user = await this._prisma.user.findFirst({
-      where: { userName, isAnonymous: true },
-      select: {
-        id: true,
-        userName: true,
-        email: true,
-        password: true,
-        isVerified: true,
-        isAnonymous: true,
-        roles: true,
-        mfaEnabled: true,
-      },
-    });
-
-    return user ?? null;
-  }
-}
-```
-
-You'll implement the same pattern for `MfaSubjectPort`, `SessionPersistencePort`, and `VerificationSubjectPort`. Each port's abstract methods are documented in the [platform-authentication API reference](/packages/platform-authentication/api/).
-
-### Register the Module
-
-Pass your adapter classes to `AuthModule.register()`:
-
-```typescript
-// src/app.module.ts
-import { Module } from '@nestjs/common';
-import { ConfigModule, MappingModule } from '@breadstone/archipel-platform-core';
-import { DatabaseModule } from '@breadstone/archipel-platform-database';
-import { AuthModule } from '@breadstone/archipel-platform-authentication';
-import { APP_CONFIG_ENTRIES } from './env';
-import { PrismaAuthSubjectAdapter } from './adapters/PrismaAuthSubjectAdapter';
-import { PrismaMfaSubjectAdapter } from './adapters/PrismaMfaSubjectAdapter';
-import { PrismaSessionAdapter } from './adapters/PrismaSessionAdapter';
-import { PrismaVerificationAdapter } from './adapters/PrismaVerificationAdapter';
-
-@Module({
-  imports: [
-    ConfigModule.register('app', APP_CONFIG_ENTRIES),
-    MappingModule,
-    DatabaseModule.register(),
-    AuthModule.register({
-      authSubject: PrismaAuthSubjectAdapter,
-      mfaSubject: PrismaMfaSubjectAdapter,
-      sessionPersistence: PrismaSessionAdapter,
-      verificationSubject: PrismaVerificationAdapter,
-    }),
-  ],
-})
-export class AppModule {}
-```
-
-The `AuthModule` now has everything it needs. Its internal services (`AuthTokenService`, `SessionService`, `MfaService`, `VerificationService`) are available for injection in your controllers and services.
-
-### Optional Ports
-
-`AuthModule` also accepts two optional ports:
-
-- **`socialAuth`** — Provide a `SocialAuthPort` adapter to enable OAuth strategies (GitHub, Google, Microsoft, Apple). Without it, those routes don't exist.
-- **`tokenEnricher`** — Provide a `TokenEnricherPort` adapter to add custom claims (subscription tier, org ID, etc.) to every JWT. Without it, tokens contain only the base claims.
-
-```typescript
-AuthModule.register({
-  authSubject: PrismaAuthSubjectAdapter,
-  mfaSubject: PrismaMfaSubjectAdapter,
-  sessionPersistence: PrismaSessionAdapter,
-  verificationSubject: PrismaVerificationAdapter,
-  socialAuth: PrismaSocialAuthAdapter,     // optional: enables OAuth
-  tokenEnricher: AppTokenEnricherAdapter,  // optional: enriches JWTs
-}),
-```
-
----
-
-## Adding More Packages
-
-Every Archipel package follows the same integration pattern:
-
-1. **Install** the package with `yarn add @breadstone/archipel-<name>`
-2. **Check** its documentation page under [Packages](/packages/) for required ports and configuration
-3. **Implement** adapter classes for required ports (if any)
-4. **Register** the module with `SomeModule.register({ ... })`
-5. **Inject** the package's services where you need them
-
-Some packages have no ports at all — `platform-logging`, `platform-telemetry`, `platform-openapi`, and several others just need a module registration and you're done.
-
----
-
-## Next Steps
-
-- Read the [Implementing Ports](/guides/implementing-ports) guide for a thorough explanation of the port/adapter pattern across all packages
-- Browse the [Packages](/packages/) section for detailed documentation on each module
-- Check the [Architecture](/architecture/) overview for the dependency graph and design principles

package/data/guides/implementing-ports.md

@@ -1,317 +0,0 @@
----
-title: Implementing Ports
-description: How the port/adapter pattern works in Archipel and how to implement adapters for each package.
-order: 2
----
-
-# Implementing Ports
-
-Archipel libraries don't hardcode how you store data, send emails, or check permissions. Instead, they define **ports** — abstract classes describing what the library needs — and your application provides **adapters** — concrete classes that implement those methods with your specific database, API, or logic.
-
-This guide covers why ports are abstract classes, which ports exist across all packages, how to write and register adapters, and what happens when optional ports are omitted.
-
-## Why Abstract Classes?
-
-NestJS uses a token-based dependency injection system. Every injectable needs a token for resolution. Archipel uses abstract classes as ports because they serve two purposes simultaneously:
-
-1. **Type contract** — They define the method signatures your adapter must implement. TypeScript enforces this at compile time.
-2. **DI token** — NestJS can use the class reference directly as an injection token, so there's no need for separate `Symbol()` tokens or string identifiers.
-
-```typescript
-// Inside the platform library — you don't write this, it's already there
-@Injectable()
-export class SessionService {
-  constructor(
-    private readonly _sessionPersistence: SessionPersistencePort,
-    // The abstract class IS the DI token
-  ) {}
-}
-```
-
-When you pass `{ sessionPersistence: PrismaSessionAdapter }` to `register()`, the library binds your concrete class to the abstract class token. NestJS resolves it automatically wherever the port is injected.
-
----
-
-## All Ports Reference
-
-Every port across all Archipel packages:
-
-| Package                   | Port                         | Purpose                                        | Required |
-| ------------------------- | ---------------------------- | ---------------------------------------------- | -------- |
-| `platform-authentication` | `AuthSubjectPort`            | User lookup for authentication strategies      | Yes      |
-| `platform-authentication` | `MfaSubjectPort`             | MFA state persistence (enable/disable, verify) | Yes      |
-| `platform-authentication` | `SessionPersistencePort`     | Session storage, querying, and cleanup         | Yes      |
-| `platform-authentication` | `VerificationSubjectPort`    | Email/PIN verification persistence             | Yes      |
-| `platform-authentication` | `SocialAuthPort`             | OAuth user creation and account linking        | No       |
-| `platform-authentication` | `TokenEnricherPort`          | Add custom claims to JWTs                      | No       |
-| `platform-blob-storage`   | `BlobObjectPersistencePort`  | Track blob metadata after upload/delete        | No       |
-| `platform-blob-storage`   | `BlobVariantPersistencePort` | Track image variant metadata                   | No       |
-| `platform-payments`       | `FeatureAccessPort`          | Feature quota checks and usage recording       | No       |
-
-Packages not listed here (`platform-core`, `platform-database`, `platform-logging`, `platform-telemetry`, `platform-openapi`, `platform-reporting`, `platform-documents`, `platform-mailing`, `platform-mcp`) have no ports — they work out of the box with configuration only.
-
----
-
-## Writing an Adapter
-
-### Step 1: Create the Adapter File
-
-Create one file per adapter in an `adapters/` directory in your application:
-
-```
-src/
-  adapters/
-    PrismaAuthSubjectAdapter.ts
-    PrismaMfaSubjectAdapter.ts
-    PrismaSessionAdapter.ts
-    PrismaVerificationAdapter.ts
-```
-
-### Step 2: Extend the Port
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { AuthSubjectPort, type IAuthSubject } from '@breadstone/archipel-platform-authentication';
-import { PrismaService } from '@breadstone/archipel-platform-database';
-
-@Injectable()
-export class PrismaAuthSubjectAdapter extends AuthSubjectPort {
-  private readonly _prisma: PrismaService;
-
-  constructor(prisma: PrismaService) {
-    super();
-    this._prisma = prisma;
-  }
-
-  public async findById(id: string): Promise<IAuthSubject | null> {
-    const user = await this._prisma.user.findUnique({
-      where: { id },
-      select: {
-        id: true,
-        userName: true,
-        email: true,
-        password: true,
-        isVerified: true,
-        isAnonymous: true,
-        roles: true,
-        mfaEnabled: true,
-      },
-    });
-
-    return user ?? null;
-  }
-
-  public async findByLogin(login: string): Promise<IAuthSubject | null> {
-    const user = await this._prisma.user.findFirst({
-      where: { OR: [{ userName: login }, { email: login }] },
-      select: {
-        id: true,
-        userName: true,
-        email: true,
-        password: true,
-        isVerified: true,
-        isAnonymous: true,
-        roles: true,
-        mfaEnabled: true,
-      },
-    });
-
-    return user ?? null;
-  }
-
-  public async findAnonymous(userName: string): Promise<IAuthSubject | null> {
-    const user = await this._prisma.user.findFirst({
-      where: { userName, isAnonymous: true },
-      select: {
-        id: true,
-        userName: true,
-        email: true,
-        password: true,
-        isVerified: true,
-        isAnonymous: true,
-        roles: true,
-        mfaEnabled: true,
-      },
-    });
-
-    return user ?? null;
-  }
-}
-```
-
-**Key rules:**
-
-- Always annotate with `@Injectable()` — the adapter is a NestJS provider and participates in DI.
-- Always call `super()` in the constructor — the abstract class may have a constructor that sets up internal state.
-- Return the port's interface type (`IAuthSubject`, `ISessionRecord`, etc.), not your raw Prisma model. The port defines the contract.
-- Inject your own dependencies via constructor — the adapter has full access to NestJS DI, so it can use your `PrismaService`, `HttpService`, or anything else.
-- One adapter per port — don't combine multiple ports in one class. NestJS resolves each port token independently.
-
-### Step 3: Register
-
-Pass the adapter class (not an instance) to the module's `register()` method:
-
-```typescript
-AuthModule.register({
-  authSubject: PrismaAuthSubjectAdapter,
-  mfaSubject: PrismaMfaSubjectAdapter,
-  sessionPersistence: PrismaSessionAdapter,
-  verificationSubject: PrismaVerificationAdapter,
-});
-```
-
-NestJS handles instantiation and dependency resolution. You pass the class reference, the framework does the rest.
-
----
-
-## Schema Mapping
-
-Your database schema won't always match the port interface field-for-field. The adapter is where you handle the translation. This is one of the main reasons adapters exist — they decouple the library's expectations from your specific data model.
-
-```typescript
-public async findById(id: string): Promise<IAuthSubject | null> {
-  const user = await this._prisma.user.findUnique({
-    where: { id },
-    include: { userRoles: { include: { role: true } } },
-  });
-
-  if (!user) return null;
-
-  return {
-    id: user.id,
-    userName: user.username,              // different casing
-    email: user.emailAddress,             // different field name
-    password: user.passwordHash,          // different field name
-    isVerified: user.emailVerified,       // different field name
-    isAnonymous: user.type === 'anonymous', // derived from enum
-    roles: user.userRoles.map((ur) => ur.role.name), // flattened relation
-    mfaEnabled: user.twoFactorEnabled,    // different field name
-  };
-}
-```
-
-As long as the returned object satisfies the port's interface, the platform library doesn't care what your underlying schema looks like.
-
----
-
-## Adapters for External APIs
-
-Ports aren't limited to database adapters. You can implement an adapter that calls an external API, talks to a microservice, or reads from a cache — anything that fulfills the contract.
-
-```typescript
-@Injectable()
-export class Auth0AuthSubjectAdapter extends AuthSubjectPort {
-  private readonly _http: HttpService;
-
-  constructor(http: HttpService) {
-    super();
-    this._http = http;
-  }
-
-  public async findById(id: string): Promise<IAuthSubject | null> {
-    const { data } = await firstValueFrom(this._http.get(`https://my-tenant.auth0.com/api/v2/users/${id}`));
-
-    return {
-      id: data.user_id,
-      userName: data.nickname,
-      email: data.email,
-      password: '',
-      isVerified: data.email_verified,
-      isAnonymous: false,
-      roles: data.app_metadata?.roles ?? [],
-      mfaEnabled: data.multifactor?.length > 0,
-    };
-  }
-
-  public async findByLogin(login: string): Promise<IAuthSubject | null> {
-    const { data } = await firstValueFrom(
-      this._http.get('https://my-tenant.auth0.com/api/v2/users', {
-        params: { q: `email:"${login}" OR nickname:"${login}"` },
-      }),
-    );
-
-    return data[0] ? this.mapToAuthSubject(data[0]) : null;
-  }
-
-  // ...
-}
-```
-
-The library has no idea it's talking to Auth0. It calls `findById()` and gets back an `IAuthSubject` — that's the entire contract.
-
----
-
-## In-Memory Adapters for Testing
-
-For integration tests where you need a working port without a real database, create in-memory implementations:
-
-```typescript
-@Injectable()
-export class InMemoryAuthSubjectAdapter extends AuthSubjectPort {
-  private readonly _subjects = new Map<string, IAuthSubject>();
-
-  public seed(subjects: IAuthSubject[]): void {
-    subjects.forEach((s) => this._subjects.set(s.id, s));
-  }
-
-  public async findById(id: string): Promise<IAuthSubject | null> {
-    return this._subjects.get(id) ?? null;
-  }
-
-  public async findByLogin(login: string): Promise<IAuthSubject | null> {
-    return [...this._subjects.values()].find((s) => s.userName === login || s.email === login) ?? null;
-  }
-
-  public async findAnonymous(userName: string): Promise<IAuthSubject | null> {
-    return [...this._subjects.values()].find((s) => s.userName === userName && s.isAnonymous) ?? null;
-  }
-}
-```
-
-This pattern works for any port. Seed with test data, inject into the module under test, and your tests run fast and deterministically without database fixtures. See the [Testing](/guides/testing) guide for full integration test examples.
-
----
-
-## Optional Ports
-
-Some ports are optional. When not provided, the library gracefully degrades — the feature that depends on that port simply isn't available. The library's internal services use `@Optional()` on the injection, so they receive `undefined` and skip the corresponding logic.
-
-### TokenEnricherPort (Authentication)
-
-When omitted, JWTs contain only the base claims (`id`, `email`, `roles`). When provided, `AuthTokenService` calls your adapter's `enrichClaims()` method and merges the result into every token.
-
-```typescript
-@Injectable()
-export class AppTokenEnricherAdapter extends TokenEnricherPort {
-  public async enrichClaims(subject: IAuthSubject): Promise<Record<string, unknown>> {
-    return {
-      subscriptionTier: 'pro',
-      organizationId: 'org-123',
-    };
-  }
-}
-```
-
-### SocialAuthPort (Authentication)
-
-When omitted, OAuth strategies (GitHub, Google, Microsoft, Apple) are not registered — the routes don't exist. When provided, all configured strategies become active and the library handles the OAuth callback flow.
-
-### BlobObjectPersistencePort / BlobVariantPersistencePort (Blob Storage)
-
-When omitted, blob uploads and deletes work normally, but metadata isn't tracked in your database. When provided, `BlobService` calls the persistence port after each operation so you can maintain your own blob inventory.
-
-### FeatureAccessPort (Payments)
-
-When omitted, `FeatureGuard` and `FeatureUsageInterceptor` have no access port and will deny or skip feature checks. When provided, they delegate quota enforcement and usage recording to your adapter.
-
----
-
-## Common Mistakes
-
-**Not calling `super()`** — If you forget `super()` in the constructor, JavaScript throws a runtime error. Abstract classes are still real classes with constructors.
-
-**Returning raw Prisma objects** — If your Prisma model includes extra fields beyond what the port interface expects, don't return it raw. Always map to the exact interface shape. Extra fields won't cause type errors but may leak internal data.
-
-**Sharing adapters across ports** — Don't make one class implement two different ports. Each port has its own DI token, and NestJS resolves them independently. One class, one port, one responsibility.
-
-**Registering instances instead of classes** — `register()` expects the class reference (`PrismaAuthSubjectAdapter`), not `new PrismaAuthSubjectAdapter()`. NestJS creates the instance and injects its dependencies automatically.