@breadstone/archipel-mcp 0.0.11 → 0.0.14

package/data/guides/esigning-integration.md

@@ -1,231 +0,0 @@
----
-title: E-Signing Integration
-description: Integrate electronic signature workflows with DocuSign, Adobe Sign, Dropbox Sign, SignNow, or an internal provider.
-order: 12
----
-
-# E-Signing Integration
-
-This guide covers electronic signature workflows with `platform-esigning`: provider setup, creating signing requests, tracking signer status, and handling webhook notifications.
-
----
-
-## Installation
-
-```bash
-yarn add @breadstone/archipel-platform-esigning
-```
-
----
-
-## Choose a Provider
-
-`platform-esigning` abstracts e-signing operations behind a `EsigningClientPort`. Supported providers:
-
-| Provider         | Description                              |
-| ---------------- | ---------------------------------------- |
-| **DocuSign**     | Industry-standard e-signature platform   |
-| **Adobe Sign**   | Adobe Acrobat Sign integration           |
-| **Dropbox Sign** | Dropbox (formerly HelloSign) integration |
-| **SignNow**      | SignNow e-signature platform             |
-| **Internal**     | Custom/self-managed signing              |
-
----
-
-## Module Registration
-
-```typescript
-import { Module } from '@nestjs/common';
-import { EsigningModule } from '@breadstone/archipel-platform-esigning';
-import { DocuSignClient } from './adapters/DocuSignClient';
-import { PrismaSigningRequestAdapter } from './adapters/PrismaSigningRequestAdapter';
-import { DOCUSIGN_CONFIG_ENTRIES } from './env';
-
-@Module({
-  imports: [
-    EsigningModule.register({
-      provider: DocuSignClient,
-      persistence: PrismaSigningRequestAdapter,
-      configEntries: [...DOCUSIGN_CONFIG_ENTRIES],
-    }),
-  ],
-})
-export class AppModule {}
-```
-
----
-
-## Configuration
-
-```env
-ESIGNING_API_BASE_URL=https://demo.docusign.net/restapi
-ESIGNING_API_KEY=your-api-key
-ESIGNING_WEBHOOK_SECRET=your-webhook-secret
-```
-
----
-
-## Implementing the Client Port
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import {
-  EsigningClientPort,
-  type ISigningRequest,
-  type ISigningSession,
-  type ISignedDocument,
-} from '@breadstone/archipel-platform-esigning';
-
-@Injectable()
-export class DocuSignClient extends EsigningClientPort {
-  public async createSigningSession(request: ISigningRequest): Promise<ISigningSession> {
-    // Call DocuSign API to create an envelope
-    // Return normalized signing session with redirect URLs
-  }
-
-  public async getSigningStatus(sessionId: string): Promise<ISigningSession> {
-    // Fetch signing status from DocuSign
-  }
-
-  public async downloadSignedDocument(sessionId: string): Promise<ISignedDocument> {
-    // Download the completed document from DocuSign
-  }
-
-  public async cancelSigningSession(sessionId: string): Promise<void> {
-    // Void the envelope in DocuSign
-  }
-}
-```
-
----
-
-## Implementing the Persistence Port
-
-Track signing request state in your database:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { EsigningPersistencePort, type ISigningRequest } from '@breadstone/archipel-platform-esigning';
-import { PrismaService } from '@breadstone/archipel-platform-database';
-
-@Injectable()
-export class PrismaSigningRequestAdapter extends EsigningPersistencePort {
-  private readonly _prisma: PrismaService;
-
-  constructor(prisma: PrismaService) {
-    super();
-    this._prisma = prisma;
-  }
-
-  public async save(request: ISigningRequest): Promise<void> {
-    await this._prisma.signingRequest.upsert({
-      where: { id: request.id },
-      create: {
-        id: request.id,
-        userId: request.userId,
-        documentId: request.documentId,
-        status: request.status,
-        providerSessionId: request.providerSessionId,
-      },
-      update: {
-        status: request.status,
-        providerSessionId: request.providerSessionId,
-      },
-    });
-  }
-
-  public async findById(id: string): Promise<ISigningRequest | null> {
-    return this._prisma.signingRequest.findUnique({ where: { id } });
-  }
-
-  public async findByUserId(userId: string): Promise<ReadonlyArray<ISigningRequest>> {
-    return this._prisma.signingRequest.findMany({ where: { userId } });
-  }
-}
-```
-
----
-
-## Creating a Signing Request
-
-Use `EsigningService` to orchestrate the signing workflow:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { EsigningService } from '@breadstone/archipel-platform-esigning';
-
-@Injectable()
-export class ContractService {
-  private readonly _esigningService: EsigningService;
-
-  constructor(esigningService: EsigningService) {
-    this._esigningService = esigningService;
-  }
-
-  public async sendForSigning(userId: string, documentUrl: string, signerEmail: string): Promise<string> {
-    const session = await this._esigningService.createSession({
-      userId,
-      documentUrl,
-      signers: [
-        {
-          email: signerEmail,
-          name: 'Signer',
-          order: 1,
-        },
-      ],
-      callbackUrl: 'https://yourapp.com/webhooks/esigning',
-    });
-
-    return session.signingUrl; // Redirect the user to this URL
-  }
-}
-```
-
----
-
-## Handling Webhooks
-
-E-signing providers send webhook events when documents are signed, declined, or expired:
-
-```typescript
-import { Controller, Post, Req, Headers, RawBodyRequest } from '@nestjs/common';
-import { EsigningService } from '@breadstone/archipel-platform-esigning';
-import { Request } from 'express';
-
-@Controller('webhooks/esigning')
-export class EsigningWebhookController {
-  private readonly _esigningService: EsigningService;
-
-  constructor(esigningService: EsigningService) {
-    this._esigningService = esigningService;
-  }
-
-  @Post()
-  public async handleWebhook(
-    @Req() request: RawBodyRequest<Request>,
-    @Headers('x-webhook-signature') signature: string,
-  ): Promise<void> {
-    await this._esigningService.handleWebhook(request.rawBody!, signature);
-    // The service verifies the signature, updates the signing request status,
-    // and emits domain events for your application to react to.
-  }
-}
-```
-
----
-
-## Best Practices
-
-1. **Always verify webhook signatures.** Never trust webhook payloads without signature validation.
-2. **Use the persistence port.** Track signing request state to handle retries, status queries, and auditing.
-3. **Implement idempotent webhook handlers.** Providers may deliver the same event multiple times.
-4. **Store signed documents.** Use `platform-blob-storage` to archive completed signed documents.
-5. **Handle expiration.** Set up a scheduled job to check for expired signing sessions and notify users.
-
----
-
-## Next Steps
-
-- See the [Document Generation](/guides/document-generation) guide for creating documents to send for signing
-- See the [Blob Storage](/guides/blob-storage) guide for storing signed documents
-- Browse the [platform-esigning API reference](/packages/platform-esigning/api/) for complete method signatures

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