@breadstone/archipel-mcp 0.0.11 → 0.0.14

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

@@ -1,335 +0,0 @@
----
-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): Promise<void>;
-}
-```
-
----
-
-## 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

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

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

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