@breadstone/archipel-mcp 0.0.10 → 0.0.11

package/data/guides/esigning-integration.md

@@ -0,0 +1,231 @@
+---
+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

@@ -0,0 +1,351 @@
+---
+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