@breadstone/archipel-mcp 0.0.11 → 0.0.14

package/data/guides/testing.md

@@ -1,319 +0,0 @@
----
-title: Testing
-description: Testing strategies and patterns for Archipel-powered NestJS applications.
-order: 3
----
-
-# Testing
-
-This guide covers testing patterns for applications that use Archipel packages. It walks through unit testing services, testing port adapters, building in-memory adapters for integration tests, and verifying that modules compose correctly.
-
-Archipel uses [Vitest](https://vitest.dev/) as the test runner. All examples follow the Arrange-Act-Assert pattern.
-
----
-
-## Unit Testing Services
-
-When testing services that depend on Archipel ports or other services, mock the dependencies and test business logic in isolation. Don't try to instantiate real modules — that's for integration tests.
-
-```typescript
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { UserService } from './UserService';
-import { type AuthSubjectPort } from '@breadstone/archipel-platform-authentication';
-
-describe('UserService', () => {
-  let service: UserService;
-  let mockAuthSubject: { findById: ReturnType<typeof vi.fn> };
-
-  beforeEach(() => {
-    mockAuthSubject = {
-      findById: vi.fn(),
-    };
-    service = new UserService(mockAuthSubject as unknown as AuthSubjectPort);
-  });
-
-  it('should return user when found', async () => {
-    const user = { id: 'user-1', userName: 'alice', email: 'alice@test.com' };
-    mockAuthSubject.findById.mockResolvedValue(user);
-
-    const result = await service.getUser('user-1');
-
-    expect(result).toEqual(user);
-    expect(mockAuthSubject.findById).toHaveBeenCalledWith('user-1');
-  });
-
-  it('should throw when user not found', async () => {
-    mockAuthSubject.findById.mockResolvedValue(null);
-
-    await expect(service.getUser('missing')).rejects.toThrow();
-  });
-});
-```
-
-The key principle: mock at the boundary (the port), not inside the implementation. Your test shouldn't know that `AuthSubjectPort` calls Prisma under the hood — it only knows the port interface.
-
-### Mocking the MappingService
-
-The `MappingService` from `platform-core` is commonly injected in controllers to convert entities to response DTOs. Mock it in unit tests to avoid requiring mapping profile registration:
-
-```typescript
-import { MappingService } from '@breadstone/archipel-platform-core';
-
-const mockMappingService = {
-  map: vi.fn((key, source) => source), // pass-through by default
-} as unknown as MappingService;
-```
-
-When the mapping output matters for a specific test, configure the mock:
-
-```typescript
-it('should return mapped user response', async () => {
-  mockMappingService.map = vi.fn().mockReturnValue({
-    id: 'user-1',
-    displayName: 'Alice',
-  });
-
-  const result = await controller.getUser('user-1');
-
-  expect(result).toEqual({ id: 'user-1', displayName: 'Alice' });
-  expect(mockMappingService.map).toHaveBeenCalledWith(USER_TO_RESPONSE, expect.any(Object));
-});
-```
-
-### Mocking Repositories
-
-Repositories extend `RepositoryBase` and use the `execute(query)` pattern internally. In tests, mock the repository's public methods directly — don't try to mock `execute()` or `PrismaService` internals:
-
-```typescript
-const mockUserRepository = {
-  findById: vi.fn(),
-  findByEmail: vi.fn(),
-  create: vi.fn(),
-};
-```
-
-This keeps your tests decoupled from the data access implementation. If you later switch from Prisma to another ORM or change query structure, service tests stay unchanged.
-
----
-
-## Testing Port Adapters
-
-Port adapters translate between your application's data model and the interface the platform library expects. They deserve their own tests because mapping errors are a common source of bugs.
-
-```typescript
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { PrismaAuthSubjectAdapter } from './PrismaAuthSubjectAdapter';
-
-describe('PrismaAuthSubjectAdapter', () => {
-  let adapter: PrismaAuthSubjectAdapter;
-  let mockPrisma: {
-    user: {
-      findUnique: ReturnType<typeof vi.fn>;
-      findFirst: ReturnType<typeof vi.fn>;
-    };
-  };
-
-  beforeEach(() => {
-    mockPrisma = {
-      user: {
-        findUnique: vi.fn(),
-        findFirst: vi.fn(),
-      },
-    };
-    adapter = new PrismaAuthSubjectAdapter(mockPrisma as never);
-  });
-
-  describe('findById', () => {
-    it('should return null when user does not exist', async () => {
-      mockPrisma.user.findUnique.mockResolvedValue(null);
-
-      const result = await adapter.findById('non-existent');
-
-      expect(result).toBeNull();
-    });
-
-    it('should map database record to IAuthSubject', async () => {
-      const dbUser = {
-        id: 'user-1',
-        userName: 'alice',
-        email: 'alice@example.com',
-        password: '$argon2id$hash',
-        isVerified: true,
-        isAnonymous: false,
-        roles: ['user', 'admin'],
-        mfaEnabled: false,
-      };
-      mockPrisma.user.findUnique.mockResolvedValue(dbUser);
-
-      const result = await adapter.findById('user-1');
-
-      expect(result).toEqual({
-        id: 'user-1',
-        userName: 'alice',
-        email: 'alice@example.com',
-        password: '$argon2id$hash',
-        isVerified: true,
-        isAnonymous: false,
-        roles: ['user', 'admin'],
-        mfaEnabled: false,
-      });
-    });
-  });
-
-  describe('findByLogin', () => {
-    it('should search by both userName and email', async () => {
-      mockPrisma.user.findFirst.mockResolvedValue(null);
-
-      await adapter.findByLogin('alice@example.com');
-
-      expect(mockPrisma.user.findFirst).toHaveBeenCalledWith({
-        where: {
-          OR: [{ userName: 'alice@example.com' }, { email: 'alice@example.com' }],
-        },
-        select: expect.any(Object),
-      });
-    });
-  });
-});
-```
-
-### Testing Schema Mapping
-
-When your database schema doesn't match the port interface directly, your adapter performs a mapping. Test that mapping explicitly — it's where subtle bugs hide:
-
-```typescript
-it('should derive isAnonymous from user type field', async () => {
-  const dbUser = {
-    id: 'u1',
-    username: 'guest_42',
-    emailAddress: null,
-    passwordHash: null,
-    emailVerified: false,
-    type: 'anonymous',
-    userRoles: [{ role: { name: 'guest' } }],
-    twoFactorEnabled: false,
-  };
-  mockPrisma.user.findUnique.mockResolvedValue(dbUser);
-
-  const result = await adapter.findById('u1');
-
-  expect(result?.isAnonymous).toBe(true);
-  expect(result?.roles).toEqual(['guest']);
-});
-```
-
----
-
-## In-Memory Adapters
-
-For integration tests where you need working ports without a real database, create in-memory implementations. They're fast, deterministic, and let you seed exactly the state you need for each test.
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { AuthSubjectPort, type IAuthSubject } from '@breadstone/archipel-platform-authentication';
-
-@Injectable()
-export class InMemoryAuthSubjectAdapter extends AuthSubjectPort {
-  private readonly _subjects = new Map<string, IAuthSubject>();
-
-  public seed(subjects: IAuthSubject[]): void {
-    this._subjects.clear();
-    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. Store state in a `Map`, expose a `seed()` method for setup, and implement the port interface. Your tests run in milliseconds without touching a database.
-
----
-
-## Integration Testing with Module Composition
-
-To verify that modules wire together correctly — that all providers resolve, ports are bound to the right adapters, and services function end-to-end — bootstrap a minimal NestJS test module:
-
-```typescript
-import { Test } from '@nestjs/testing';
-import { AuthModule, AuthTokenService, AuthSubjectPort } from '@breadstone/archipel-platform-authentication';
-import { ConfigModule } from '@breadstone/archipel-platform-core';
-import { InMemoryAuthSubjectAdapter } from './InMemoryAuthSubjectAdapter';
-import { InMemoryMfaSubjectAdapter } from './InMemoryMfaSubjectAdapter';
-import { InMemorySessionAdapter } from './InMemorySessionAdapter';
-import { InMemoryVerificationAdapter } from './InMemoryVerificationAdapter';
-
-describe('Auth module integration', () => {
-  let authTokenService: AuthTokenService;
-  let authSubjectAdapter: InMemoryAuthSubjectAdapter;
-
-  beforeEach(async () => {
-    const module = await Test.createTestingModule({
-      imports: [
-        ConfigModule.register('test', TEST_CONFIG_ENTRIES),
-        AuthModule.register({
-          authSubject: InMemoryAuthSubjectAdapter,
-          mfaSubject: InMemoryMfaSubjectAdapter,
-          sessionPersistence: InMemorySessionAdapter,
-          verificationSubject: InMemoryVerificationAdapter,
-        }),
-      ],
-    }).compile();
-
-    authTokenService = module.get(AuthTokenService);
-    authSubjectAdapter = module.get(AuthSubjectPort) as InMemoryAuthSubjectAdapter;
-  });
-
-  it('should resolve AuthTokenService with all dependencies', () => {
-    expect(authTokenService).toBeDefined();
-  });
-
-  it('should generate a valid JWT for a seeded user', async () => {
-    authSubjectAdapter.seed([
-      {
-        id: 'user-1',
-        userName: 'alice',
-        email: 'alice@test.com',
-        password: '$argon2id$hash',
-        isVerified: true,
-        isAnonymous: false,
-        roles: ['user'],
-        mfaEnabled: false,
-      },
-    ]);
-
-    const token = await authTokenService.signToken({
-      id: 'user-1',
-      email: 'alice@test.com',
-      roles: ['user'],
-    });
-
-    expect(token).toBeDefined();
-    expect(typeof token).toBe('string');
-  });
-});
-```
-
-This catches wiring errors early. If you forget to register a required port, mistype an adapter class, or have a circular dependency, `Test.createTestingModule(...).compile()` throws immediately with a clear error message.
-
----
-
-## Pre-Release Checklist
-
-Before shipping a new Archipel integration, verify:
-
-- [ ] All required port adapters have unit tests covering happy path and null/error cases
-- [ ] Schema mapping is tested explicitly when database fields differ from port interfaces
-- [ ] Module composition boots without missing provider errors (integration test)
-- [ ] Health indicators report correct status for connected infrastructure
-- [ ] Error responses use documented error shapes, not raw NestJS exceptions
-- [ ] Required environment variables fail fast at startup when missing

package/data/guides/tsdoc-guidelines.md

@@ -1,45 +0,0 @@
----
-title: API Documentation Standards
-description: Documentation standards for stable Archipel public APIs and generated reference pages.
-order: 5
-tags: [guides, docs, api, standards]
----
-
-# API Documentation Standards
-
-Use these standards for package APIs that are consumed by application teams.
-
-## What must be documented
-
-For every exported public symbol:
-
-- purpose and intended usage,
-- input/output contract,
-- failure behavior,
-- minimal usage example when non-obvious.
-
-## Consumer-first writing rules
-
-- Explain **what integrators need to do**, not repository internals.
-- Mark required vs optional integration points explicitly.
-- Keep examples small and runnable.
-- Avoid architecture jargon without practical effect.
-
-## Recommended structure for package overview pages
-
-1. Capability summary
-2. Installation/import information
-3. Required ports/adapters
-4. Optional extension points
-5. Minimal registration example
-6. Link to generated API reference
-
-## Stability signaling
-
-Document stability expectations clearly:
-
-- `Stable`: safe for long-lived integrations
-- `Evolving`: may receive additive changes
-- `Experimental`: breaking changes possible
-
-If a symbol is internal, do not expose it from the package barrel.

package/data/packages/index.md

@@ -1,52 +0,0 @@
----
-title: Packages
-description: All Archipel platform packages with their primary capabilities.
----
-
-# Packages
-
-Archipel is organized into 17 independent NestJS modules. Each package can be installed and used on its own — you only pull in what you need.
-
-Every package follows the same structure: a dynamic NestJS module with `register()` configuration, abstract ports for contracts you implement, and concrete services you consume.
-
-## Foundation
-
-| Package                                             | Description                                                                                                  |
-| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| [`platform-core`](./platform-core/)                 | Configuration, mapping, templates, event pub/sub, and shared utilities. Every other package depends on this. |
-| [`platform-cryptography`](./platform-cryptography/) | Bcrypt password hashing, prefixed UUID generation, and TOTP multi-factor authentication.                     |
-| [`platform-database`](./platform-database/)         | Prisma + PostgreSQL integration with the repository/query pattern and transactional support.                 |
-
-## Identity & Access
-
-| Package                                                 | Description                                                                                                    |
-| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| [`platform-authentication`](./platform-authentication/) | JWT, OAuth (GitHub, Google, Microsoft, Apple), MFA, sessions, anonymous auth, and email verification.          |
-| [`platform-payments`](./platform-payments/)             | Multi-provider payment client (Stripe, LemonSqueezy, Paddle, Creem) with feature gating and quota enforcement. |
-
-## Infrastructure
-
-| Package                                             | Description                                                                                                                 |
-| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| [`platform-blob-storage`](./platform-blob-storage/) | Provider-agnostic blob storage (Vercel, Azure, AWS S3) with metadata tracking and image variant support.                    |
-| [`platform-caching`](./platform-caching/)           | Layered caching with in-memory LRU and Redis-backed implementations, TTL, stale-while-revalidate, and metrics.              |
-| [`platform-esigning`](./platform-esigning/)         | Provider-agnostic e-signing with support for DocuSign, Adobe Sign, Dropbox Sign, signNow, and a built-in internal provider. |
-| [`platform-mailing`](./platform-mailing/)           | Multi-strategy email delivery (SMTP, Postmark, Resend, Plunk, Log) with template rendering and verification flows.          |
-| [`platform-documents`](./platform-documents/)       | Document generation with pluggable renderers for DOCX, PDF, and image processing.                                           |
-
-## Operations
-
-| Package                                       | Description                                                                                                  |
-| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| [`platform-openapi`](./platform-openapi/)     | Feature-scoped Swagger/OpenAPI documentation with multi-document registry and discovery.                     |
-| [`platform-logging`](./platform-logging/)     | Sentry integration for structured error tracking and analytics.                                              |
-| [`platform-telemetry`](./platform-telemetry/) | OpenTelemetry tracing, metrics, a rule engine for conditional recording, and graceful noop fallback.         |
-| [`platform-analytics`](./platform-analytics/) | Provider-agnostic analytics and error tracking (Sentry, Application Insights, Datadog) with no-op fallback.  |
-| [`platform-reporting`](./platform-reporting/) | Contributor-based reporting engine with dataset registration and query execution.                            |
-| [`platform-mcp`](./platform-mcp/)             | Decorator-driven MCP (Model Context Protocol) server module with auto-discovery and multi-transport support. |
-
-## AI & Extensibility
-
-| Package                                             | Description                                                                                                            |
-| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| [`platform-intelligence`](./platform-intelligence/) | Multi-provider AI text generation (OpenAI, Anthropic, Google, Grok) with capability registry and intent orchestration. |

package/data/packages/platform-analytics/api/Class.AnalyticsClientPort.md

@@ -1,141 +0,0 @@
----
-title: 'Abstract Class: AnalyticsClientPort'
-generated: true
-editUrl: false
----
-# Abstract Class: AnalyticsClientPort
-
-Defined in: [contracts/AnalyticsClientPort.ts:16](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/contracts/AnalyticsClientPort.ts#L16)
-
-Abstract port for analytics and error tracking clients.
-Each provider (Sentry, Application Insights, Datadog) must implement this contract
-so that the consuming application can switch providers without changing business logic.
-
-## Extended by
-
-- [`NoopAnalyticsClient`](Class.NoopAnalyticsClient)
-- [`SentryAnalyticsClient`](Class.SentryAnalyticsClient)
-- [`AppInsightsAnalyticsClient`](Class.AppInsightsAnalyticsClient)
-- [`DatadogAnalyticsClient`](Class.DatadogAnalyticsClient)
-
-## Constructors
-
-### Constructor
-
-```ts
-new AnalyticsClientPort(): AnalyticsClientPort;
-```
-
-#### Returns
-
-`AnalyticsClientPort`
-
-## Methods
-
-### addBreadcrumb()
-
-```ts
-abstract addBreadcrumb(breadcrumb): void;
-```
-
-Defined in: [contracts/AnalyticsClientPort.ts:59](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/contracts/AnalyticsClientPort.ts#L59)
-
-Add a breadcrumb entry to the analytics trail.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `breadcrumb` | [`IAnalyticsBreadcrumb`](Interface.IAnalyticsBreadcrumb) | The breadcrumb to add. |
-
-#### Returns
-
-`void`
-
-***
-
-### captureException()
-
-```ts
-abstract captureException(error, context?): void;
-```
-
-Defined in: [contracts/AnalyticsClientPort.ts:26](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/contracts/AnalyticsClientPort.ts#L26)
-
-Capture an exception with optional context.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `error` | `Error` | The error to capture. |
-| `context?` | `Record`\<`string`, `unknown`\> | Optional additional context metadata. |
-
-#### Returns
-
-`void`
-
-***
-
-### captureMessage()
-
-```ts
-abstract captureMessage(
-   message, 
-   level, 
-   context?): void;
-```
-
-Defined in: [contracts/AnalyticsClientPort.ts:36](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/contracts/AnalyticsClientPort.ts#L36)
-
-Capture a message with a specific severity level.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `message` | `string` | The message to capture. |
-| `level` | [`AnalyticsLevel`](TypeAlias.AnalyticsLevel) | Severity level of the message. |
-| `context?` | `Record`\<`string`, `unknown`\> | Optional additional context metadata. |
-
-#### Returns
-
-`void`
-
-***
-
-### clearUser()
-
-```ts
-abstract clearUser(): void;
-```
-
-Defined in: [contracts/AnalyticsClientPort.ts:51](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/contracts/AnalyticsClientPort.ts#L51)
-
-Clear the current user context.
-
-#### Returns
-
-`void`
-
-***
-
-### setUser()
-
-```ts
-abstract setUser(user): void;
-```
-
-Defined in: [contracts/AnalyticsClientPort.ts:44](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/contracts/AnalyticsClientPort.ts#L44)
-
-Set the current user context for subsequent events.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `user` | [`IAnalyticsUser`](Interface.IAnalyticsUser) | The user context to set. |
-
-#### Returns
-
-`void`

package/data/packages/platform-analytics/api/Class.AnalyticsModule.md

@@ -1,47 +0,0 @@
----
-title: 'Class: AnalyticsModule'
-generated: true
-editUrl: false
----
-# Class: AnalyticsModule
-
-Defined in: [AnalyticsModule.ts:43](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/AnalyticsModule.ts#L43)
-
-NestJS module providing generic analytics and error tracking infrastructure.
-The specific analytics provider (Sentry, Application Insights, Datadog) is selected via the options.
-
-## Constructors
-
-### Constructor
-
-```ts
-new AnalyticsModule(): AnalyticsModule;
-```
-
-#### Returns
-
-`AnalyticsModule`
-
-## Methods
-
-### register()
-
-```ts
-static register(options): DynamicModule;
-```
-
-Defined in: [AnalyticsModule.ts:53](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/AnalyticsModule.ts#L53)
-
-Configures the module with the specified options.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `options` | [`IAnalyticsModuleOptions`](Interface.IAnalyticsModuleOptions) | The module configuration options. |
-
-#### Returns
-
-`DynamicModule`
-
-Dynamic module definition.