@breadstone/archipel-mcp 0.0.15 → 0.0.16

package/data/packages/platform-mailing/index.md

@@ -0,0 +1,383 @@
+---
+title: platform-mailing
+description: Multi-strategy email delivery with support for SMTP, Postmark, Resend, SendGrid, and Mailgun.
+order: 7
+tags: [mailing, email, smtp, postmark, resend, sendgrid, mailgun, templates, verification, strategy-pattern]
+package: '@breadstone/archipel-platform-mailing'
+---
+
+# platform-mailing
+
+Multi-strategy email delivery system with pluggable transports (SMTP, Postmark, Resend, SendGrid, Mailgun, Log), template engines (file-based, blob-based), and email verification support. Each external provider SDK is an **optional peer dependency** — install only the one you need.
+
+**Package:** `@breadstone/archipel-platform-mailing`
+
+## Architecture
+
+```mermaid
+graph TD
+    Module["MailModule"]
+    MailService["MailService<br/><i>send() / sendTemplate()</i>"]
+    Base["DeliveryStrategyBase<br/><i>Abstract send() contract</i>"]
+
+    SMTP["SmtpDeliveryStrategy<br/><i>Built-in (nodemailer)</i>"]
+    Log["LogDeliveryStrategy<br/><i>Built-in (dev)</i>"]
+    Postmark["PostmarkDeliveryStrategy<br/><i>postmark</i>"]
+    Resend["ResendDeliveryStrategy<br/><i>resend</i>"]
+    SendGrid["SendGridDeliveryStrategy<br/><i>@sendgrid/mail</i>"]
+    Mailgun["MailgunDeliveryStrategy<br/><i>mailgun.js</i>"]
+
+    Module --> MailService
+    MailService --> Base
+    SMTP -->|extends| Base
+    Log -->|extends| Base
+    Postmark -->|extends| Base
+    Resend -->|extends| Base
+    SendGrid -->|extends| Base
+    Mailgun -->|extends| Base
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { Module } from '@nestjs/common';
+import { MailModule } from '@breadstone/archipel-platform-mailing';
+
+@Module({
+  imports: [MailModule],
+})
+export class AppModule {}
+```
+
+The module auto-selects delivery and template strategies based on environment variables.
+
+---
+
+## Environment Variables
+
+### Core
+
+| Variable                      | Description            | Values                                                                      | Required |
+| ----------------------------- | ---------------------- | --------------------------------------------------------------------------- | -------- |
+| `MAIL_SENDER_EMAIL`           | Default "from" address | `noreply@example.com`                                                       | Yes      |
+| `MAIL_DELIVERY_STRATEGY`      | Transport strategy     | `'smtp'` / `'postmark'` / `'resend'` / `'sendgrid'` / `'mailgun'` / `'log'` | Yes      |
+| `MAIL_TEMPLATE_STRATEGY`      | Template source        | `'file'` / `'blob'`                                                         | Yes      |
+| `MAIL_TEMPLATE_ENGINE_FORMAT` | Template format        | `'html'` / `'txt'`                                                          | Yes      |
+
+### SMTP (built-in)
+
+| Variable             | Description      | Default     | Required |
+| -------------------- | ---------------- | ----------- | -------- |
+| `MAIL_SMTP_HOST`     | SMTP server host | `localhost` | If SMTP  |
+| `MAIL_SMTP_PORT`     | SMTP server port | `587`       | If SMTP  |
+| `MAIL_SMTP_SECURE`   | Use TLS          | `false`     | No       |
+| `MAIL_SMTP_USER`     | Auth username    | —           | If SMTP  |
+| `MAIL_SMTP_PASSWORD` | Auth password    | —           | If SMTP  |
+
+---
+
+## Delivery Providers
+
+### Postmark
+
+**Subpath:** `@breadstone/archipel-platform-mailing/postmark`
+**SDK:** `postmark` ≥ 4.0.0
+
+| Variable                | Description      | Required |
+| ----------------------- | ---------------- | -------- |
+| `MAIL_POSTMARK_API_KEY` | Postmark API key | Yes      |
+
+```typescript
+import { PostmarkDeliveryStrategy, POSTMARK_CONFIG_ENTRIES } from '@breadstone/archipel-platform-mailing/postmark';
+```
+
+### Resend
+
+**Subpath:** `@breadstone/archipel-platform-mailing/resend`
+**SDK:** `resend` ≥ 4.0.0
+
+| Variable              | Description    | Required |
+| --------------------- | -------------- | -------- |
+| `MAIL_RESEND_API_KEY` | Resend API key | Yes      |
+
+```typescript
+import { ResendDeliveryStrategy, RESEND_CONFIG_ENTRIES } from '@breadstone/archipel-platform-mailing/resend';
+```
+
+### SendGrid
+
+**Subpath:** `@breadstone/archipel-platform-mailing/sendgrid`
+**SDK:** `@sendgrid/mail` ≥ 8.0.0
+
+| Variable                | Description      | Required |
+| ----------------------- | ---------------- | -------- |
+| `MAIL_SENDGRID_API_KEY` | SendGrid API key | Yes      |
+
+```typescript
+import { SendGridDeliveryStrategy, SENDGRID_CONFIG_ENTRIES } from '@breadstone/archipel-platform-mailing/sendgrid';
+```
+
+### Mailgun
+
+**Subpath:** `@breadstone/archipel-platform-mailing/mailgun`
+**SDK:** `mailgun.js` ≥ 10.0.0
+
+| Variable               | Description                            | Required |
+| ---------------------- | -------------------------------------- | -------- |
+| `MAIL_MAILGUN_API_KEY` | Mailgun API key                        | Yes      |
+| `MAIL_MAILGUN_DOMAIN`  | Mailgun domain (e.g. `mg.example.com`) | Yes      |
+
+```typescript
+import { MailgunDeliveryStrategy, MAILGUN_CONFIG_ENTRIES } from '@breadstone/archipel-platform-mailing/mailgun';
+```
+
+### Log (built-in)
+
+Logs emails to the console. No SDK or env vars required — useful for development and testing.
+
+### Switching Providers
+
+Change a single environment variable — no code change needed:
+
+```bash
+# Switch from SMTP to Resend
+MAIL_DELIVERY_STRATEGY=resend
+MAIL_RESEND_API_KEY=re_xxxxxxxxxxxx
+```
+
+---
+
+## DeliveryStrategyBase
+
+All providers extend this abstract contract:
+
+```typescript
+abstract class DeliveryStrategyBase {
+  abstract send(
+    from: string,
+    to: string,
+    subject: string,
+    content: string,
+    isHtml: boolean,
+    attachments?: Array<IMailAttachment>,
+  ): Promise<void>;
+}
+```
+
+---
+
+## Attachment Support
+
+`MailService.send()` accepts an optional fourth parameter for file attachments:
+
+```typescript
+import type { IMailAttachment } from '@breadstone/archipel-platform-mailing';
+
+const attachment: IMailAttachment = {
+  filename: 'invoice.pdf',
+  content: pdfBuffer,       // Buffer or string
+  contentType: 'application/pdf',
+};
+
+await this._mail.send(
+  { to: 'user@example.com', subject: 'Your Invoice' },
+  '<p>Please find your invoice attached.</p>',
+  true,
+  [attachment],
+);
+```
+
+### Validation
+
+| Constraint    | Detail                                                                                                                  |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| **MIME types** | PDF, Word (.doc/.docx), Excel (.xls/.xlsx), ZIP, PNG, JPEG, GIF, WebP, plain text, CSV                                |
+| **Max size**   | 25 MB per attachment                                                                                                   |
+| **Behavior**   | Invalid MIME type or oversized attachments throw immediately — the email is **not** sent                                |
+
+### IMailAttachment Interface
+
+```typescript
+interface IMailAttachment {
+  readonly filename: string;
+  readonly content: Buffer | string;
+  readonly contentType: string;
+}
+```
+
+---
+
+## MailService
+
+Core service for sending emails.
+
+### Send Plain Email
+
+```typescript
+import { MailService } from '@breadstone/archipel-platform-mailing';
+
+@Injectable()
+export class NotificationService {
+  constructor(private readonly _mail: MailService) {}
+
+  public async sendWelcome(userEmail: string, userName: string): Promise<void> {
+    await this._mail.send(
+      { to: userEmail, subject: `Welcome, ${userName}!` },
+      `<h1>Welcome</h1><p>Hey ${userName}, we're glad you're here.</p>`,
+      true, // isHtml
+    );
+  }
+}
+```
+
+### Send Templated Email
+
+```typescript
+await this._mail.sendTemplate(
+  { to: userEmail, subject: 'Your Order Confirmation' },
+  {
+    templateName: 'order-confirmation',
+    templateParams: {
+      orderNumber: 'ORD-12345',
+      total: '€39.97',
+    },
+  },
+);
+```
+
+### Custom Sender
+
+```typescript
+await this._mail.send(
+  {
+    from: 'support@example.com', // overrides MAIL_SENDER_EMAIL
+    to: 'customer@example.com',
+    subject: 'Support Ticket #4567',
+  },
+  'Your ticket has been received.',
+  false, // plain text
+);
+```
+
+---
+
+## Template Strategies
+
+### File-Based Templates
+
+Load templates from the filesystem:
+
+```typescript
+// Set MAIL_TEMPLATE_STRATEGY=file
+// Templates stored as files: assets/templates/welcome.html
+```
+
+### Blob-Based Templates
+
+Load templates from blob storage (e.g., Vercel Blob):
+
+```typescript
+// Set MAIL_TEMPLATE_STRATEGY=blob
+// Templates stored in blob storage: templates/welcome.html
+```
+
+---
+
+## MailVerificationService
+
+Email address verification flow:
+
+```typescript
+import { MailVerificationService } from '@breadstone/archipel-platform-mailing';
+
+@Injectable()
+export class RegistrationService {
+  constructor(private readonly _mailVerification: MailVerificationService) {}
+
+  public async sendVerification(email: string): Promise<void> {
+    await this._mailVerification.sendVerificationEmail(email);
+  }
+}
+```
+
+---
+
+## Health Check
+
+```typescript
+import { MailHealthIndicator } from '@breadstone/archipel-platform-mailing';
+
+// Registered with HealthOrchestrator automatically
+// Checks mail delivery readiness
+```
+
+---
+
+## Real-World Example: Transactional Email Pipeline
+
+```typescript
+@Injectable()
+export class OrderEmailService {
+  constructor(
+    private readonly _mail: MailService,
+    private readonly _analytics: AnalyticsService,
+  ) {}
+
+  public async sendOrderConfirmation(order: IOrder): Promise<void> {
+    try {
+      await this._mail.sendTemplate(
+        {
+          to: order.customerEmail,
+          subject: `Order ${order.number} Confirmed`,
+        },
+        {
+          templateName: 'order-confirmation',
+          templateParams: {
+            customerName: order.customerName,
+            orderNumber: order.number,
+            total: `€${order.total.toFixed(2)}`,
+            deliveryDate: order.estimatedDelivery.toLocaleDateString('de-DE'),
+          },
+        },
+      );
+    } catch (error) {
+      this._analytics.captureException(error, {
+        tags: { module: 'mailing', orderId: order.id },
+      });
+    }
+  }
+}
+```
+
+---
+
+## Exports Summary
+
+### Core (`@breadstone/archipel-platform-mailing`)
+
+| Export                      | Type           | Description                     |
+| --------------------------- | -------------- | ------------------------------- |
+| `MailModule`                | NestJS Module  | Global mail module              |
+| `MailService`               | Service        | Send emails (plain + templated) |
+| `MailVerificationService`   | Service        | Email verification              |
+| `MailTemplateEngine`        | Service        | Template variable substitution  |
+| `DeliveryStrategyBase`      | Abstract class | Base for delivery strategies    |
+| `SmtpDeliveryStrategy`      | Strategy       | SMTP transport (built-in)       |
+| `LogDeliveryStrategy`       | Strategy       | Log-only (built-in)             |
+| `ResendDeliveryStrategy`    | Strategy       | Resend API                      |
+| `SendGridDeliveryStrategy`  | Strategy       | SendGrid API                    |
+| `MailgunDeliveryStrategy`   | Strategy       | Mailgun API                     |
+| `FileTemplateFetchStrategy` | Strategy       | File-based templates            |
+| `BlobTemplateFetchStrategy` | Strategy       | Blob-stored templates           |
+| `MailHealthIndicator`       | Health         | Mail readiness check            |
+
+### Provider subpaths
+
+| Subpath     | Exports                                                                                  |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| `/postmark` | `PostmarkDeliveryStrategy`, `POSTMARK_API_KEY`, `POSTMARK_CONFIG_ENTRIES`                |
+| `/resend`   | `ResendDeliveryStrategy`, `RESEND_API_KEY`, `RESEND_CONFIG_ENTRIES`                      |
+| `/sendgrid` | `SendGridDeliveryStrategy`, `SENDGRID_API_KEY`, `SENDGRID_CONFIG_ENTRIES`                |
+| `/mailgun`  | `MailgunDeliveryStrategy`, `MAILGUN_API_KEY`, `MAILGUN_DOMAIN`, `MAILGUN_CONFIG_ENTRIES` |

package/data/packages/platform-mcp/api/Class.McpDiscoveryService.md

@@ -0,0 +1,64 @@
+---
+title: 'Class: McpDiscoveryService'
+generated: true
+editUrl: false
+---
+# Class: McpDiscoveryService
+
+Defined in: [services/McpDiscoveryService.ts:16](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpDiscoveryService.ts#L16)
+
+Discovers all NestJS providers that have methods decorated with
+`@McpTool`, `@McpResource`, or `@McpPrompt` and registers them
+in the [McpRegistryService](Class.McpRegistryService).
+
+## Implements
+
+- `OnModuleInit`
+
+## Constructors
+
+### Constructor
+
+```ts
+new McpDiscoveryService(
+   _discoveryService, 
+   _metadataScanner, 
+   _registry): McpDiscoveryService;
+```
+
+Defined in: [services/McpDiscoveryService.ts:25](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpDiscoveryService.ts#L25)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `_discoveryService` | `DiscoveryService` |
+| `_metadataScanner` | `MetadataScanner` |
+| `_registry` | [`McpRegistryService`](Class.McpRegistryService) |
+
+#### Returns
+
+`McpDiscoveryService`
+
+## Methods
+
+### onModuleInit()
+
+```ts
+onModuleInit(): void;
+```
+
+Defined in: [services/McpDiscoveryService.ts:39](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpDiscoveryService.ts#L39)
+
+Called by NestJS after the module is initialized.
+Scans all providers and registers discovered MCP handlers.
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+```ts
+OnModuleInit.onModuleInit
+```

package/data/packages/platform-mcp/api/Class.McpModule.md

@@ -0,0 +1,82 @@
+---
+title: 'Class: McpModule'
+generated: true
+editUrl: false
+---
+# Class: McpModule
+
+Defined in: [module/McpModule.ts:28](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/module/McpModule.ts#L28)
+
+NestJS dynamic module that bootstraps an MCP server.
+
+Import via `McpModule.register()` for synchronous configuration
+or `McpModule.registerAsync()` for factory-based configuration.
+
+## Example
+
+```typescript
+McpModule.register({
+    name: 'my-mcp-server',
+    version: '1.0.0',
+})
+```
+
+## Constructors
+
+### Constructor
+
+```ts
+new McpModule(): McpModule;
+```
+
+#### Returns
+
+`McpModule`
+
+## Methods
+
+### register()
+
+```ts
+static register(options): DynamicModule;
+```
+
+Defined in: [module/McpModule.ts:37](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/module/McpModule.ts#L37)
+
+Registers the MCP module with synchronous options.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `options` | [`IMcpModuleOptions`](Interface.IMcpModuleOptions) | MCP server configuration. |
+
+#### Returns
+
+`DynamicModule`
+
+A configured dynamic module.
+
+***
+
+### registerAsync()
+
+```ts
+static registerAsync(options): DynamicModule;
+```
+
+Defined in: [module/McpModule.ts:58](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/module/McpModule.ts#L58)
+
+Registers the MCP module with asynchronous options.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `options` | [`IMcpModuleAsyncOptions`](Interface.IMcpModuleAsyncOptions) | Async MCP server configuration. |
+
+#### Returns
+
+`DynamicModule`
+
+A configured dynamic module.

package/data/packages/platform-mcp/api/Class.McpRegistryService.md

@@ -0,0 +1,146 @@
+---
+title: 'Class: McpRegistryService'
+generated: true
+editUrl: false
+---
+# Class: McpRegistryService
+
+Defined in: [services/McpRegistryService.ts:35](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpRegistryService.ts#L35)
+
+Central registry that stores all MCP tool, resource, and prompt handlers
+discovered from NestJS providers.
+
+## Constructors
+
+### Constructor
+
+```ts
+new McpRegistryService(): McpRegistryService;
+```
+
+#### Returns
+
+`McpRegistryService`
+
+## Accessors
+
+### prompts
+
+#### Get Signature
+
+```ts
+get prompts(): ReadonlyMap<string, IRegisteredPrompt>;
+```
+
+Defined in: [services/McpRegistryService.ts:64](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpRegistryService.ts#L64)
+
+Returns all registered prompts.
+
+##### Returns
+
+`ReadonlyMap`\<`string`, [`IRegisteredPrompt`](Interface.IRegisteredPrompt)\>
+
+***
+
+### resources
+
+#### Get Signature
+
+```ts
+get resources(): ReadonlyMap<string, IRegisteredResource>;
+```
+
+Defined in: [services/McpRegistryService.ts:57](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpRegistryService.ts#L57)
+
+Returns all registered resources.
+
+##### Returns
+
+`ReadonlyMap`\<`string`, [`IRegisteredResource`](Interface.IRegisteredResource)\>
+
+***
+
+### tools
+
+#### Get Signature
+
+```ts
+get tools(): ReadonlyMap<string, IRegisteredTool>;
+```
+
+Defined in: [services/McpRegistryService.ts:50](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpRegistryService.ts#L50)
+
+Returns all registered tools.
+
+##### Returns
+
+`ReadonlyMap`\<`string`, [`IRegisteredTool`](Interface.IRegisteredTool)\>
+
+## Methods
+
+### registerPrompt()
+
+```ts
+registerPrompt(metadata, handler): void;
+```
+
+Defined in: [services/McpRegistryService.ts:108](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpRegistryService.ts#L108)
+
+Registers a prompt handler.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `metadata` | [`IMcpPromptMetadata`](Interface.IMcpPromptMetadata) | Prompt metadata from the decorator. |
+| `handler` | (...`args`) => `unknown` | Bound method that handles the prompt generation. |
+
+#### Returns
+
+`void`
+
+***
+
+### registerResource()
+
+```ts
+registerResource(metadata, handler): void;
+```
+
+Defined in: [services/McpRegistryService.ts:93](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpRegistryService.ts#L93)
+
+Registers a resource handler.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `metadata` | [`IMcpResourceMetadata`](Interface.IMcpResourceMetadata) | Resource metadata from the decorator. |
+| `handler` | (...`args`) => `unknown` | Bound method that handles the resource read. |
+
+#### Returns
+
+`void`
+
+***
+
+### registerTool()
+
+```ts
+registerTool(metadata, handler): void;
+```
+
+Defined in: [services/McpRegistryService.ts:78](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpRegistryService.ts#L78)
+
+Registers a tool handler.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `metadata` | [`IMcpToolMetadata`](Interface.IMcpToolMetadata) | Tool metadata from the decorator. |
+| `handler` | (...`args`) => `unknown` | Bound method that handles the tool invocation. |
+
+#### Returns
+
+`void`