@breadstone/archipel-mcp 0.0.14 → 0.0.16

package/data/guides/document-generation.md

@@ -0,0 +1,174 @@
+---
+title: Document Generation
+description: Generate PDF and DOCX documents from templates with variable substitution and image processing.
+order: 11
+---
+
+# Document Generation
+
+This guide covers generating documents with `platform-documents`: template setup, variable substitution, image processing, and rendering to PDF or DOCX.
+
+---
+
+## Installation
+
+```bash
+yarn add @breadstone/archipel-platform-documents
+```
+
+---
+
+## Module Registration
+
+```typescript
+import { Module } from '@nestjs/common';
+import { DocumentModule } from '@breadstone/archipel-platform-documents';
+
+@Module({
+  imports: [
+    DocumentModule.forRoot({
+      maxImageWidth: 1920,
+      maxImageHeight: 1080,
+      delimiters: { start: '[[', end: ']]' },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Options
+
+| Option           | Default | Description                                       |
+| ---------------- | ------- | ------------------------------------------------- |
+| `maxImageWidth`  | `1920`  | Maximum width for embedded images (in pixels)     |
+| `maxImageHeight` | `1080`  | Maximum height for embedded images (in pixels)    |
+| `delimiters`     | `[[ ]]` | Start and end delimiters for template variables   |
+| `debug`          | `false` | Enable verbose logging for the rendering pipeline |
+
+---
+
+## Creating Templates
+
+Templates are document files (DOCX) with placeholder variables. By default, placeholders use double brackets:
+
+```
+Dear [[customerName]],
+
+Your order [[orderId]] has been confirmed.
+Total: [[orderTotal]]
+
+Thank you for your business.
+```
+
+You can change the delimiter format:
+
+```typescript
+DocumentModule.forRoot({
+  delimiters: { start: '{{', end: '}}' },
+});
+```
+
+---
+
+## Rendering Documents
+
+Use `DocumentEngine` to render templates with data:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { DocumentEngine } from '@breadstone/archipel-platform-documents';
+
+@Injectable()
+export class InvoiceService {
+  private readonly _documentEngine: DocumentEngine;
+
+  constructor(documentEngine: DocumentEngine) {
+    this._documentEngine = documentEngine;
+  }
+
+  public async generateInvoice(orderId: string, data: Record<string, unknown>): Promise<Buffer> {
+    return this._documentEngine.render({
+      template: 'invoice-template.docx',
+      data: {
+        customerName: data['customerName'],
+        orderId,
+        orderTotal: data['total'],
+        date: new Date().toLocaleDateString(),
+      },
+      format: 'pdf', // or 'docx'
+    });
+  }
+}
+```
+
+### Supported Output Formats
+
+| Format | Renderer      | Description                           |
+| ------ | ------------- | ------------------------------------- |
+| `pdf`  | PDF Renderer  | Convert template to PDF               |
+| `docx` | DOCX Renderer | Keep as DOCX with filled placeholders |
+
+---
+
+## Image Processing
+
+The `SharpImageProcessor` automatically optimizes embedded images:
+
+- Resizes images that exceed `maxImageWidth` or `maxImageHeight`
+- Preserves aspect ratio
+- Compresses images for smaller file sizes
+
+This is useful for templates that include dynamic images (logos, product photos, signatures).
+
+---
+
+## Serving Documents via HTTP
+
+```typescript
+import { Controller, Get, Res, Param } from '@nestjs/common';
+import { Response } from 'express';
+
+@Controller('invoices')
+export class InvoiceController {
+  private readonly _invoiceService: InvoiceService;
+
+  constructor(invoiceService: InvoiceService) {
+    this._invoiceService = invoiceService;
+  }
+
+  @Get(':orderId/pdf')
+  public async downloadInvoice(@Param('orderId') orderId: string, @Res() res: Response): Promise<void> {
+    const pdf = await this._invoiceService.generateInvoice(orderId, {
+      /* ... */
+    });
+
+    res.set({
+      'Content-Type': 'application/pdf',
+      'Content-Disposition': `attachment; filename="invoice-${orderId}.pdf"`,
+    });
+
+    res.send(pdf);
+  }
+}
+```
+
+---
+
+## Debug Mode
+
+Enable debug logging to trace the rendering pipeline:
+
+```typescript
+DocumentModule.forRoot({
+  debug: true,
+});
+```
+
+This logs each step of the rendering process: template loading, placeholder parsing, variable substitution, image processing, and final output generation.
+
+---
+
+## Next Steps
+
+- See the [Blob Storage](/guides/blob-storage) guide for storing generated documents
+- Browse the [platform-documents API reference](/packages/platform-documents/api/) for complete method signatures

package/data/guides/email-delivery.md

@@ -0,0 +1,233 @@
+---
+title: Email Delivery
+description: Send transactional emails with multiple providers, template engines, and email verification flows.
+order: 8
+---
+
+# Email Delivery
+
+This guide covers sending emails with `platform-mailing`: choosing a delivery provider, configuring template rendering, sending transactional emails, and integrating email verification flows.
+
+---
+
+## Installation
+
+```bash
+yarn add @breadstone/archipel-platform-mailing
+```
+
+---
+
+## Choose a Delivery Strategy
+
+`platform-mailing` supports multiple email providers. You select the strategy via environment variables — no code changes required to switch providers.
+
+| Strategy     | Value for `MAIL_DELIVERY_STRATEGY` | When to use                          |
+| ------------ | ---------------------------------- | ------------------------------------ |
+| **SMTP**     | `smtp`                             | Any SMTP server (self-hosted, relay) |
+| **Postmark** | `postmark`                         | Postmark transactional email         |
+| **Resend**   | `resend`                           | Resend API                           |
+| **SendGrid** | `sendgrid`                         | Twilio SendGrid                      |
+| **Mailgun**  | `mailgun`                          | Mailgun API                          |
+| **Log**      | `log`                              | Development only — logs to console   |
+
+---
+
+## Module Registration
+
+`MailModule` is a global module. Register it once in your root module:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { MailModule } from '@breadstone/archipel-platform-mailing';
+
+@Module({
+  imports: [MailModule],
+})
+export class AppModule {}
+```
+
+The module reads all configuration from environment variables. No `register()` call is needed.
+
+---
+
+## Configuration
+
+### Core Variables
+
+```env
+MAIL_DELIVERY_STRATEGY=resend
+MAIL_TEMPLATE_STRATEGY=file
+MAIL_TEMPLATE_ENGINE_FORMAT=html
+MAIL_FROM_ADDRESS=noreply@yourapp.com
+MAIL_FROM_NAME=YourApp
+```
+
+### Provider-Specific Variables
+
+#### SMTP
+
+```env
+MAIL_SMTP_HOST=smtp.example.com
+MAIL_SMTP_PORT=587
+MAIL_SMTP_USER=user@example.com
+MAIL_SMTP_PASS=password
+MAIL_SMTP_SECURE=true
+```
+
+#### Resend
+
+```env
+MAIL_RESEND_API_KEY=re_...
+```
+
+#### Postmark
+
+```env
+MAIL_POSTMARK_API_KEY=...
+```
+
+#### SendGrid
+
+```env
+MAIL_SENDGRID_API_KEY=SG...
+```
+
+#### Mailgun
+
+```env
+MAIL_MAILGUN_API_KEY=key-...
+MAIL_MAILGUN_DOMAIN=mg.yourapp.com
+```
+
+### Template Strategies
+
+Templates can be loaded from the filesystem or from blob storage:
+
+| Strategy | Value for `MAIL_TEMPLATE_STRATEGY` | Description                                 |
+| -------- | ---------------------------------- | ------------------------------------------- |
+| **File** | `file`                             | Load templates from a local directory       |
+| **Blob** | `blob`                             | Load templates from `platform-blob-storage` |
+
+For file-based templates, place your `.html` or `.txt` files in the configured template directory.
+
+---
+
+## Sending Emails
+
+Inject `MailService` to send emails with templates:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { MailService } from '@breadstone/archipel-platform-mailing';
+
+@Injectable()
+export class NotificationService {
+  private readonly _mailService: MailService;
+
+  constructor(mailService: MailService) {
+    this._mailService = mailService;
+  }
+
+  public async sendWelcomeEmail(email: string, userName: string): Promise<void> {
+    await this._mailService.send({
+      to: email,
+      subject: 'Welcome to YourApp',
+      template: 'welcome',
+      context: {
+        userName,
+        dashboardUrl: 'https://yourapp.com/dashboard',
+      },
+    });
+  }
+}
+```
+
+The `template` field is the template name (without extension). The `context` object is passed to the template engine for variable substitution.
+
+---
+
+## Email Verification
+
+`MailVerificationService` provides a complete email verification flow:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { MailVerificationService } from '@breadstone/archipel-platform-mailing';
+import { VerificationService } from '@breadstone/archipel-platform-authentication';
+
+@Injectable()
+export class RegistrationService {
+  private readonly _mailVerification: MailVerificationService;
+  private readonly _verification: VerificationService;
+
+  constructor(mailVerification: MailVerificationService, verification: VerificationService) {
+    this._mailVerification = mailVerification;
+    this._verification = verification;
+  }
+
+  public async sendVerificationEmail(userId: string, email: string): Promise<void> {
+    const token = await this._verification.exhibitToken({ userId, email });
+
+    await this._mailVerification.sendVerification(email, token);
+  }
+}
+```
+
+---
+
+## Sending Attachments
+
+`MailService.send()` accepts an optional `attachments` parameter for attaching files to outgoing emails:
+
+```typescript
+import type { IMailAttachment } from '@breadstone/archipel-platform-mailing';
+
+const invoice: IMailAttachment = {
+  filename: 'invoice-2024-001.pdf',
+  content: pdfBuffer,
+  contentType: 'application/pdf',
+};
+
+await this._mailService.send(
+  { to: 'user@example.com', subject: 'Your Invoice' },
+  '<p>Please find your invoice attached.</p>',
+  true,
+  [invoice],
+);
+```
+
+### Constraints
+
+| Rule          | Detail                                                                                                   |
+| ------------- | -------------------------------------------------------------------------------------------------------- |
+| **MIME types** | Only allowed types are accepted: PDF, Word, Excel, ZIP, PNG, JPEG, GIF, WebP, plain text, and CSV       |
+| **Max size**   | Each attachment must not exceed **25 MB**                                                                 |
+| **Validation** | `MailService` validates MIME type and size before passing to the delivery strategy. Invalid attachments throw immediately |
+
+---
+
+## Security
+
+`MailService` applies automatic sanitization to the email subject to prevent SMTP header injection attacks. Any carriage-return (`\r`) or line-feed (`\n`) characters found in the subject string are replaced with a space before the message is handed to the delivery strategy. This protection runs transparently on every `send` call.
+
+---
+
+## Health Checks
+
+`MailHealthIndicator` is registered automatically and verifies connectivity to the configured mail provider. It appears in your `/health` endpoint alongside other health indicators.
+
+---
+
+## Development Tips
+
+- Use `MAIL_DELIVERY_STRATEGY=log` during local development to see email content in the console without sending real emails.
+- Use the **blob** template strategy when templates are shared across multiple services or managed by a CMS.
+- Template variables use the format defined by the template engine. Place templates in a well-organized directory structure (e.g., `templates/mail/welcome.html`).
+
+---
+
+## Next Steps
+
+- See the [Authentication & Authorization](/guides/authentication-and-authorization) guide for integrating email verification into the login flow
+- Browse the [platform-mailing API reference](/packages/platform-mailing/api/) for complete method signatures

package/data/guides/esigning-integration.md

@@ -0,0 +1,247 @@
+---
+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
+```
+
+---
+
+## Webhook Verification
+
+`EsigningService.verifyWebhook()` validates webhook payloads and normalizes the event. It accepts an optional `headers` parameter for providers that require timestamp or nonce validation:
+
+```typescript
+const event = await esigningService.verifyWebhook(
+  request.rawBody,       // Raw request body
+  signatureHeader,       // Signature header value
+  request.headers,       // Optional: full headers for timestamp/nonce validation
+);
+```
+
+When persistence is configured, the service automatically updates the signing request status in your database.
+
+---
+
+## 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