@breadstone/archipel-mcp 0.0.19 → 0.0.21

package/data/guides/ai-text-generation.md

@@ -299,6 +299,8 @@ export class ChatOrchestrator {
 
 Capabilities are resolved by priority (lowest number first). If multiple capabilities can handle the same intent, the one with the highest priority (lowest value) wins.
 
+> **Capacity limit:** The registry enforces a maximum of **500** registered capabilities. Attempts to exceed this limit are logged as warnings and silently ignored.
+
 ---
 
 ## Inspecting Configuration
@@ -317,6 +319,14 @@ console.log(config.model); // 'gpt-4o-mini'
 
 `IntelligenceTextGenerator` wraps all provider errors in `IntelligenceProviderError`, which includes `provider`, `model`, and `retryable` metadata. The generator automatically retries retryable failures (e.g. transient network errors) with exponential backoff before giving up.
 
+Two additional error classes handle configuration and validation failures:
+
+| Error class                        | Code                          | When thrown                                                           |
+| ---------------------------------- | ----------------------------- | --------------------------------------------------------------------- |
+| `IntelligenceProviderError`        | `INTELLIGENCE_PROVIDER`       | Provider SDK failures during text generation                          |
+| `IntelligenceValidationError`      | `INTELLIGENCE_VALIDATION`     | Invalid generation parameters (temperature, topP, maxOutputTokens)    |
+| `IntelligenceConfigurationError`   | `INTELLIGENCE_CONFIGURATION`  | Unsupported provider, missing API key, or missing SDK package         |
+
 ### Timeout & Retry Defaults
 
 | Setting     | Default  | Description                                                 |

package/data/guides/analytics-and-error-tracking.md

@@ -174,6 +174,12 @@ this._analytics.addBreadcrumb({
 
 ---
 
+## Lifecycle
+
+All built-in analytics clients (Sentry, Application Insights, Datadog) implement `OnModuleInit` and `OnModuleDestroy`. SDK initialization happens at module startup, and pending events are flushed with a 5-second timeout on shutdown. No manual cleanup is needed.
+
+---
+
 ## Development Tips
 
 - Use the **Noop** provider during local development and testing to avoid sending events to production analytics.

package/data/guides/cryptography-and-otp.md

@@ -228,6 +228,24 @@ export class AuthService {
 
 ---
 
+## Error Handling
+
+`CryptoService` throws a `CryptoValidationError` for invalid inputs such as empty UUID prefixes:
+
+```typescript
+import { CryptoValidationError } from '@breadstone/archipel-platform-cryptography';
+
+try {
+  crypto.getRandomGuid('');
+} catch (error) {
+  if (error instanceof CryptoValidationError) {
+    // error.code → 'CRYPTO_VALIDATION'
+  }
+}
+```
+
+---
+
 ## Security Best Practices
 
 | Practice                            | Why                                                       |

package/data/guides/document-generation.md

@@ -168,6 +168,32 @@ This logs each step of the rendering process: template loading, placeholder pars
 
 ---
 
+## Error Handling
+
+The document library throws typed domain errors for different failure scenarios:
+
+| Error class                | When thrown                                       |
+| -------------------------- | ------------------------------------------------- |
+| `DocumentRenderError`      | Template rendering failures (DOCX, PDF)           |
+| `DocumentValidationError`  | Invalid templates, missing placeholders           |
+| `ImageProcessingError`     | Image resize/conversion failures                  |
+
+```typescript
+import { DocumentRenderError } from '@breadstone/archipel-platform-documents';
+
+try {
+  const result = await this._engine.render(template, data);
+} catch (error) {
+  if (error instanceof DocumentRenderError) {
+    // Handle render failure
+  }
+}
+```
+
+All errors extend `DocumentError` — catch the base class for a blanket handler.
+
+---
+
 ## Next Steps
 
 - See the [Blob Storage](/guides/blob-storage) guide for storing generated documents

package/data/guides/email-delivery.md

@@ -207,6 +207,28 @@ await this._mailService.send(
 
 ---
 
+## Error Handling
+
+All delivery strategies throw a `MailDeliveryError` when email sending fails. The error wraps the underlying provider error and identifies which provider failed:
+
+```typescript
+import { MailDeliveryError } from '@breadstone/archipel-platform-mailing';
+
+try {
+  await this._mail.send(options, content, true);
+} catch (error) {
+  if (error instanceof MailDeliveryError) {
+    // error.provider → 'postmark', 'smtp', 'resend', 'sendgrid', 'mailgun'
+    // error.code     → 'MAIL_DELIVERY'
+    // error.cause    → Original provider SDK error
+  }
+}
+```
+
+Map `MailDeliveryError` to an appropriate HTTP response in your global exception filter. The `provider` property helps with targeted alerting and retry decisions.
+
+---
+
 ## 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.
@@ -229,5 +251,6 @@ await this._mailService.send(
 
 ## Next Steps
 
+- See the [Email Templates](/guides/email-templates) guide for creating, registering, and overriding email templates with ResourceManager
 - 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/email-templates.md

@@ -0,0 +1,298 @@
+---
+title: Email Templates
+description: Create, register, and override email templates using the ResourceManager from platform-core and the template engine from platform-mailing.
+order: 8
+---
+
+# Email Templates
+
+This guide explains how to create email templates for `platform-mailing` and register them with `ResourceManager` from `platform-core`. It covers the template syntax, the built-in template names, how to provide your own HTML/TXT files, and how to override library defaults.
+
+> **Prerequisite:** You should be familiar with [Email Delivery](/guides/email-delivery) for general mail setup and [Resource Management](/guides/resource-management) for how `ResourceManager` strategies work.
+
+---
+
+## How It Works
+
+`platform-mailing` does **not** ship ready-made template files. It defines a list of known template **names** and loads the actual content through `ResourceManager` at startup.
+
+```
+┌──────────────┐     ┌─────────────────────────┐     ┌──────────────────┐
+│ MailService   │────▶│ MailTemplateEngine       │────▶│ ResourceManager  │
+│ sendTemplate()│     │ compileTemplate()        │     │ tryLoadAsync()   │
+└──────────────┘     └─────────────────────────┘     └──────────────────┘
+                              │                              │
+                              ▼                              ▼
+                     ContentTemplateEngine          FileResourceStrategy
+                     (variable interpolation)       BlobResourceStrategy
+                                                    EmbeddedResourceStrategy
+```
+
+1. `MailService.sendTemplate()` passes the template name and context variables to `MailTemplateEngine`.
+2. `MailTemplateEngine` looks up the pre-loaded template content by name and format (`.html` or `.txt`).
+3. `ContentTemplateEngine` from `platform-core` interpolates `{{placeholders}}` with the provided context.
+4. The compiled string is handed to the configured delivery strategy (SMTP, Resend, Postmark, etc.).
+
+---
+
+## Built-In Template Names
+
+`FileTemplateFetchStrategy` expects these template names. For each name, both `.html` and `.txt` variants are loaded (if available):
+
+| Template Name            | Purpose                                           |
+| ------------------------ | ------------------------------------------------- |
+| `AuthRegister`           | Welcome email sent after user registration        |
+| `AuthVerify`             | Email address verification with token/link        |
+| `AuthForgotPassword`     | Password reset email with token/link              |
+| `AppointmentInvitation`  | Invitation to an appointment or event             |
+| `AppointmentUpdate`      | Notification about an appointment change          |
+
+The strategy loads `AuthRegister.html`, `AuthRegister.txt`, `AuthVerify.html`, etc. Missing variants are silently skipped — you can provide only `.html` if you don't need plain-text fallbacks.
+
+---
+
+## Creating Template Files
+
+### Template Syntax
+
+Templates use a Handlebars-style syntax powered by `ContentTemplateEngine`:
+
+| Syntax                                         | Description                       |
+| ---------------------------------------------- | --------------------------------- |
+| `{{variableName}}`                             | Simple variable substitution      |
+| `{{#if condition}}...{{/if}}`                  | Conditional block                 |
+| `{{#if condition}}...{{else}}...{{/if}}`       | Conditional with else             |
+| `{{#unless condition}}...{{/unless}}`          | Negative conditional              |
+| `{{#each items}}...{{/each}}`                  | Loop over array                   |
+| `{{#with object}}...{{/with}}`                 | Context switching                 |
+| `{{@index}}`, `{{@first}}`, `{{@last}}`        | Loop metadata inside `#each`      |
+| `{{nested.property}}`                          | Dot notation for nested values    |
+
+### Example: `AuthVerify.html`
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>Verify your email</title>
+</head>
+<body>
+  <h1>Hello, {{userName}}!</h1>
+  <p>Please verify your email address by clicking the link below:</p>
+  <p>
+    <a href="{{verificationUrl}}">Verify Email</a>
+  </p>
+  {{#if expiresInHours}}
+  <p>This link expires in {{expiresInHours}} hours.</p>
+  {{/if}}
+  <p>If you did not create an account, you can safely ignore this email.</p>
+</body>
+</html>
+```
+
+### Example: `AuthVerify.txt`
+
+```text
+Hello, {{userName}}!
+
+Please verify your email address by visiting the following link:
+
+{{verificationUrl}}
+
+{{#if expiresInHours}}This link expires in {{expiresInHours}} hours.{{/if}}
+
+If you did not create an account, you can safely ignore this email.
+```
+
+### Security
+
+When the format is `html`, `MailTemplateEngine` automatically **escapes all context values** (`&`, `<`, `>`, `"`, `'`) before interpolation to prevent XSS in email clients. Plain-text templates (`txt`) are not escaped.
+
+---
+
+## Registering Templates with ResourceManager
+
+### File-Based Templates (Recommended)
+
+Place your template files in your application's assets directory and register the path with `ResourceModule`:
+
+```
+my-app/
+├── src/
+│   ├── assets/
+│   │   ├── AuthRegister.html
+│   │   ├── AuthRegister.txt
+│   │   ├── AuthVerify.html
+│   │   ├── AuthVerify.txt
+│   │   ├── AuthForgotPassword.html
+│   │   ├── AppointmentInvitation.html
+│   │   └── AppointmentUpdate.html
+│   └── app.module.ts
+```
+
+```typescript
+import { Module } from '@nestjs/common';
+import { join } from 'node:path';
+import { ResourceModule, FileResourceStrategy } from '@breadstone/archipel-platform-core';
+import { MailModule } from '@breadstone/archipel-platform-mailing';
+
+@Module({
+  imports: [
+    ResourceModule.forRoot({
+      strategies: [
+        new FileResourceStrategy({
+          basePaths: [
+            join(__dirname, 'assets'),
+          ],
+          includeSubfolders: true,
+        }),
+      ],
+    }),
+    MailModule,
+  ],
+})
+export class AppModule {}
+```
+
+Set the environment variable to use the file strategy:
+
+```env
+MAIL_TEMPLATE_STRATEGY=file
+```
+
+### Blob-Based Templates
+
+For templates managed via a CMS or shared across multiple services, use `BlobTemplateFetchStrategy`. Upload a manifest file (`templates/templates.json`) and the template files to your blob storage:
+
+**`templates/templates.json`**
+```json
+[
+  "templates/AuthRegister.html",
+  "templates/AuthRegister.txt",
+  "templates/AuthVerify.html",
+  "templates/AuthVerify.txt",
+  "templates/AuthForgotPassword.html"
+]
+```
+
+Set the environment variable:
+
+```env
+MAIL_TEMPLATE_STRATEGY=blob
+```
+
+The `BlobTemplateFetchStrategy` downloads the manifest, then fetches each listed file from blob storage via `BlobService` from `platform-blob-storage`.
+
+---
+
+## Overriding Library Templates
+
+If a library ships default template files in its `assets/` folder, you can override them by listing your application's assets directory **before** the library path:
+
+```typescript
+ResourceModule.forRoot({
+  strategies: [
+    new FileResourceStrategy({
+      basePaths: [
+        join(__dirname, 'assets'),                    // ← Your overrides (checked first)
+        join(__dirname, '..', 'node_modules', '@breadstone', 'archipel-platform-mailing', 'assets'),
+      ],
+      includeSubfolders: true,
+    }),
+  ],
+})
+```
+
+`ResourceManager` tries strategies and base paths in order — the first match wins. By placing your directory first, any file you provide takes precedence.
+
+---
+
+## Sending a Templated Email
+
+Once templates are registered, use `MailService.sendTemplate()`:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { MailService } from '@breadstone/archipel-platform-mailing';
+
+@Injectable()
+export class RegistrationService {
+  private readonly _mailService: MailService;
+
+  constructor(mailService: MailService) {
+    this._mailService = mailService;
+  }
+
+  public async sendWelcomeEmail(email: string, userName: string): Promise<void> {
+    await this._mailService.sendTemplate(
+      {
+        to: email,
+        subject: 'Welcome to our platform',
+      },
+      {
+        templateName: 'AuthRegister',
+        templateParams: {
+          userName,
+          dashboardUrl: 'https://yourapp.com/dashboard',
+          year: new Date().getFullYear(),
+        },
+      },
+    );
+  }
+}
+```
+
+The `templateName` must match one of the registered template file names (without extension). The `templateParams` object is passed to the template engine for variable substitution.
+
+---
+
+## Template Format Selection
+
+The environment variable `MAIL_TEMPLATE_ENGINE_FORMAT` controls which variant is used:
+
+| Value  | Behavior                                    |
+| ------ | ------------------------------------------- |
+| `html` | Sends HTML email using `TemplateName.html`  |
+| `txt`  | Sends plain-text email using `TemplateName.txt` |
+
+---
+
+## Debugging
+
+If a template is not found at runtime, `MailTemplateEngine.compileTemplate()` throws with the message:
+
+```
+Template with key 'AuthVerify' not found.
+```
+
+To diagnose, enable `debug: true` in `ResourceModule.forRoot()`. This logs every available resource at startup so you can verify that your template files are discovered:
+
+```
+[FileResourceStrategy] Available resources:
+  - AuthVerify.html (text/html, 1.2 KB) → /app/dist/assets/AuthVerify.html
+  - AuthVerify.txt (text/plain, 320 B) → /app/dist/assets/AuthVerify.txt
+```
+
+Also check that `MAIL_TEMPLATE_STRATEGY` is set correctly (`file` or `blob`).
+
+---
+
+## Checklist
+
+- [ ] Template files created for all required template names (`.html` and/or `.txt`)
+- [ ] `ResourceModule.forRoot()` registered with base paths including your template directory
+- [ ] `MAIL_TEMPLATE_STRATEGY` set to `file` or `blob`
+- [ ] `MAIL_TEMPLATE_ENGINE_FORMAT` set to `html` or `txt`
+- [ ] Placeholders in templates match the keys passed in `templateParams`
+- [ ] App-level overrides listed **before** library asset paths in `basePaths`
+- [ ] `debug: true` used during development to verify template availability
+
+---
+
+## Next Steps
+
+- See the [Email Delivery](/guides/email-delivery) guide for provider setup, attachments, and verification flows
+- See the [Resource Management](/guides/resource-management) guide for advanced strategies (blob, caching, custom strategies)
+- See the [Document Generation](/guides/document-generation) guide for PDF/DOCX template rendering
+- Browse the [platform-mailing API reference](/packages/platform-mailing/api/) for complete method signatures

package/data/guides/esigning-integration.md

@@ -27,7 +27,7 @@ yarn add @breadstone/archipel-platform-esigning
 | **DocuSign**     | Industry-standard e-signature platform   |
 | **Adobe Sign**   | Adobe Acrobat Sign integration           |
 | **Dropbox Sign** | Dropbox (formerly HelloSign) integration |
-| **Internal**     | Custom/self-managed signing              |
+| **Internal**     | Custom/self-managed signing (max 10,000 in-memory requests) |
 
 ---
 

package/data/guides/index.md

@@ -42,6 +42,7 @@ Practical guides for working with Archipel packages in your NestJS application.
 | Guide                                                      | What you'll learn                                                                 |
 | ---------------------------------------------------------- | --------------------------------------------------------------------------------- |
 | [Email Delivery](./email-delivery)                         | Multi-provider email sending, template engines, and verification flows.           |
+| [Email Templates](./email-templates)                       | Create, register, and override email templates with ResourceManager.              |
 | [Payments & Feature Gating](./payments-and-feature-gating) | Payment provider integration, webhook handling, and feature-based access control. |
 
 ## Operations & Observability

package/data/guides/mcp-server.md

@@ -216,6 +216,15 @@ export class GuideResources {
 
 ---
 
+## Operational Limits
+
+| Limit                | Value      | Description                                                              |
+| -------------------- | ---------- | ------------------------------------------------------------------------ |
+| **Max transports**   | 1,000      | `McpServerService` tracks up to 1,000 concurrent transports              |
+| **Shutdown timeout** | 5 seconds  | Transports and server are closed with a 5-second timeout on shutdown     |
+
+---
+
 ## Next Steps
 
 - Browse the [platform-mcp API reference](/packages/platform-mcp/api/) for complete decorator options

package/data/guides/payments-and-feature-gating.md

@@ -252,6 +252,24 @@ try {
 
 All client implementations log errors with structured metadata before re-throwing.
 
+All payment clients throw `PaymentError` — a domain error that wraps the underlying SDK error:
+
+```typescript
+import { PaymentError } from '@breadstone/archipel-platform-payments';
+
+try {
+  await this._paymentClient.createCheckoutSession(params);
+} catch (error) {
+  if (error instanceof PaymentError) {
+    // error.provider → 'stripe', 'paddle', 'mollie', 'lemonsqueezy'
+    // error.code     → 'PAYMENT'
+    // error.cause    → Original provider SDK error
+  }
+}
+```
+
+Map `PaymentError` to an HTTP response in your global exception filter. The `provider` property enables provider-specific alerting.
+
 ---
 
 ## Next Steps

package/data/guides/telemetry-and-observability.md

@@ -171,7 +171,13 @@ This prevents noisy endpoints (health checks, readiness probes) from overwhelmin
 
 ## Graceful Shutdown
 
-The module registers a shutdown hook that flushes all pending telemetry data before the process exits. This ensures you don't lose metrics or traces during deployments or scaling events.
+The module registers a shutdown hook that flushes all pending telemetry data before the process exits. The SDK shutdown is capped at **5 seconds** to prevent the process from hanging if the OTEL collector is unreachable.
+
+### Lifecycle Details
+
+- **`MetricsService`** creates metric instruments eagerly via `OnModuleInit` (not lazily on first use).
+- **`OtelSdkHolder`** enforces a write-once guard — calling `setSdk()` twice logs a warning instead of overwriting.
+- **`TelemetryRuleEngine`** logs rule evaluation failures as warnings instead of silently swallowing errors. This ensures you don't lose metrics or traces during deployments or scaling events.
 
 ---
 

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

@@ -14,6 +14,11 @@ Uses the `applicationinsights` SDK for error tracking and analytics.
 
 - [`AnalyticsClientPort`](Class.AnalyticsClientPort)
 
+## Implements
+
+- `OnModuleInit`
+- `OnModuleDestroy`
+
 ## Constructors
 
 ### Constructor
@@ -22,7 +27,7 @@ Uses the `applicationinsights` SDK for error tracking and analytics.
 new AppInsightsAnalyticsClient(configService): AppInsightsAnalyticsClient;
 ```
 
-Defined in: [application-insights/AppInsightsAnalyticsClient.ts:32](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/application-insights/AppInsightsAnalyticsClient.ts#L32)
+Defined in: [application-insights/AppInsightsAnalyticsClient.ts:33](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/application-insights/AppInsightsAnalyticsClient.ts#L33)
 
 #### Parameters
 
@@ -46,7 +51,7 @@ Defined in: [application-insights/AppInsightsAnalyticsClient.ts:32](https://gith
 addBreadcrumb(breadcrumb): void;
 ```
 
-Defined in: [application-insights/AppInsightsAnalyticsClient.ts:81](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/application-insights/AppInsightsAnalyticsClient.ts#L81)
+Defined in: [application-insights/AppInsightsAnalyticsClient.ts:100](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/application-insights/AppInsightsAnalyticsClient.ts#L100)
 
 Add a breadcrumb entry to the analytics trail.
 
@@ -72,7 +77,7 @@ Add a breadcrumb entry to the analytics trail.
 captureException(error, context?): void;
 ```
 
-Defined in: [application-insights/AppInsightsAnalyticsClient.ts:49](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/application-insights/AppInsightsAnalyticsClient.ts#L49)
+Defined in: [application-insights/AppInsightsAnalyticsClient.ts:68](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/application-insights/AppInsightsAnalyticsClient.ts#L68)
 
 Capture an exception with optional context.
 
@@ -102,7 +107,7 @@ captureMessage(
    context?): void;
 ```
 
-Defined in: [application-insights/AppInsightsAnalyticsClient.ts:57](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/application-insights/AppInsightsAnalyticsClient.ts#L57)
+Defined in: [application-insights/AppInsightsAnalyticsClient.ts:76](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/application-insights/AppInsightsAnalyticsClient.ts#L76)
 
 Capture a message with a specific severity level.
 
@@ -130,7 +135,7 @@ Capture a message with a specific severity level.
 clearUser(): void;
 ```
 
-Defined in: [application-insights/AppInsightsAnalyticsClient.ts:75](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/application-insights/AppInsightsAnalyticsClient.ts#L75)
+Defined in: [application-insights/AppInsightsAnalyticsClient.ts:94](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/application-insights/AppInsightsAnalyticsClient.ts#L94)
 
 Clear the current user context.
 
@@ -144,13 +149,57 @@ Clear the current user context.
 
 ***
 
+### onModuleDestroy()
+
+```ts
+onModuleDestroy(): Promise<void>;
+```
+
+Defined in: [application-insights/AppInsightsAnalyticsClient.ts:62](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/application-insights/AppInsightsAnalyticsClient.ts#L62)
+
+Flushes pending Application Insights telemetry before shutdown.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Implementation of
+
+```ts
+OnModuleDestroy.onModuleDestroy
+```
+
+***
+
+### onModuleInit()
+
+```ts
+onModuleInit(): void;
+```
+
+Defined in: [application-insights/AppInsightsAnalyticsClient.ts:47](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/application-insights/AppInsightsAnalyticsClient.ts#L47)
+
+Initializes the Application Insights SDK.
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+```ts
+OnModuleInit.onModuleInit
+```
+
+***
+
 ### setUser()
 
 ```ts
 setUser(user): void;
 ```
 
-Defined in: [application-insights/AppInsightsAnalyticsClient.ts:66](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/application-insights/AppInsightsAnalyticsClient.ts#L66)
+Defined in: [application-insights/AppInsightsAnalyticsClient.ts:85](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/application-insights/AppInsightsAnalyticsClient.ts#L85)
 
 Set the current user context for subsequent events.