@breadstone/archipel-mcp 0.0.54 → 0.0.55

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

@@ -1,150 +0,0 @@
----
-title: platform-logging
-description: Configurable logging module for NestJS with log-level management, request context propagation, and structured logging.
-order: 6
-tags: [logging, log-level, nestjs, request-context, structured-logging, correlation-id]
-package: '@breadstone/archipel-platform-logging'
----
-
-# platform-logging
-
-Configurable logging module for NestJS applications with application-wide log-level management, request-scoped context propagation, and structured logging. Wraps the built-in NestJS `Logger` and configures it via the central `ConfigModule`.
-
-**Package:** `@breadstone/archipel-platform-logging`
-
-<InstallTabs />
-
-## Quick Start
-
-```typescript
-import { Module } from '@nestjs/common';
-import { LoggerModule } from '@breadstone/archipel-platform-logging';
-
-@Module({
-  imports: [LoggerModule],
-})
-export class AppModule {}
-```
-
-The module is `@Global()` — once imported, `Logger` is available for injection across the entire application.
-
----
-
-## Using the Logger
-
-Inject the standard NestJS `Logger` provided by `LoggerModule`:
-
-```typescript
-import { Injectable, Logger } from '@nestjs/common';
-
-@Injectable()
-export class PaymentService {
-  constructor(private readonly _logger: Logger) {}
-
-  public async processPayment(orderId: string): Promise<void> {
-    this._logger.log(`Processing payment for order ${orderId}`);
-    // ...
-  }
-}
-```
-
----
-
-## Request Context Propagation
-
-### RequestIdMiddleware
-
-Extracts or generates a unique `x-request-id` per request and stores it in `AsyncLocalStorage` via `RequestContextStore`. Apply it globally:
-
-```typescript
-import { RequestIdMiddleware } from '@breadstone/archipel-platform-logging';
-
-export class AppModule implements NestModule {
-  public configure(consumer: MiddlewareConsumer): void {
-    consumer.apply(RequestIdMiddleware).forRoutes('*');
-  }
-}
-```
-
-The middleware:
-
-1. Reads the `x-request-id` header from the incoming request (if present from an API gateway or load balancer)
-2. Generates a UUID v4 if no header is found
-3. Sets the `x-request-id` header on the response
-4. Wraps the request execution in `RequestContextStore.run()` so the ID is available anywhere in the call stack
-
-### RequestContextStore
-
-`AsyncLocalStorage`-based per-request context store. Access the current request context from anywhere without passing parameters:
-
-```typescript
-import { RequestContextStore, type IRequestContext } from '@breadstone/archipel-platform-logging';
-
-// Get current context
-const context: IRequestContext | undefined = RequestContextStore.get();
-const requestId: string | undefined = RequestContextStore.getRequestId();
-
-// Run a callback within a context (used internally by middleware)
-RequestContextStore.run({ requestId: 'abc-123', userId: 'user-1' }, () => {
-  // context is available in all nested calls
-});
-```
-
-#### IRequestContext
-
-| Field       | Type     | Description                       |
-| ----------- | -------- | --------------------------------- |
-| `requestId` | `string` | Unique request correlation ID     |
-| `userId`    | `string?`| Optional authenticated user ID    |
-
-### ContextLogger
-
-Structured logger that automatically enriches every log entry with the current request context:
-
-```typescript
-import { ContextLogger } from '@breadstone/archipel-platform-logging';
-
-@Injectable()
-export class OrderService {
-  private readonly _logger = new ContextLogger(OrderService.name);
-
-  public async placeOrder(dto: CreateOrderDto): Promise<void> {
-    this._logger.log('Placing order', { orderId: dto.orderId });
-    // Output: { requestId: "abc-123", userId: "user-1", orderId: "...", message: "Placing order" }
-  }
-}
-```
-
-Methods: `log()`, `warn()`, `error()`, `debug()`, `verbose()` — all accept an optional `data` record that is merged with the request context.
-
----
-
-## Environment Variables
-
-| Variable        | Description                                                    | Required | Default |
-| --------------- | -------------------------------------------------------------- | -------- | ------- |
-| `APP_LOG_LEVEL` | Application log level (`'debug'`, `'info'`, `'warn'`, `'error'`) | No       | `warn`  |
-
-> **Startup validation:** The module validates `APP_LOG_LEVEL` at initialization. An unrecognized value triggers a warning and falls back to `warn`.
-
----
-
-## Peer Dependencies
-
-| Package   | Required | Notes                                          |
-| --------- | -------- | ---------------------------------------------- |
-| `express` | Yes      | Required for `RequestIdMiddleware` types (`Request`, `Response`) |
-
----
-
-## Exports Summary
-
-| Export                  | Type          | Description                                                        |
-| ----------------------- | ------------- | ------------------------------------------------------------------ |
-| `LoggerModule`          | NestJS Module | Global logging module with log-level control                       |
-| `Logger`                | Provider      | NestJS Logger configured with `APP_LOG_LEVEL`                      |
-| `ContextLogger`         | Class         | Structured logger enriched with request context                    |
-| `RequestContextStore`   | Class         | AsyncLocalStorage-based per-request context (requestId, userId)    |
-| `RequestIdMiddleware`   | Middleware    | Extracts/generates `x-request-id` and wraps in context store       |
-| `IRequestContext`       | Interface     | Shape of the per-request context                                   |
-| `REQUEST_ID_HEADER`     | Constant      | Header name (`'x-request-id'`)                                     |

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

@@ -1,470 +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, health]
-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`
-
-<InstallTabs />
-
-## 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
-```
-
----
-
-## SmtpConnectionVerifier
-
-Verifies SMTP server connectivity. Replaces the deprecated `MailVerificationService`.
-
-```typescript
-import { SmtpConnectionVerifier } from '@breadstone/archipel-platform-mailing';
-
-@Injectable()
-export class HealthCheckService {
-  constructor(private readonly _smtpVerifier: SmtpConnectionVerifier) {}
-
-  public async checkSmtp(): Promise<boolean> {
-    return this._smtpVerifier.verifyConnection();
-  }
-
-  public async sendTestEmail(to: string): Promise<boolean> {
-    return this._smtpVerifier.sendTestEmail(to);
-  }
-}
-```
-
-## MailVerificationService (Deprecated)
-
-::: warning Deprecated
-`MailVerificationService` is deprecated. Use `SmtpConnectionVerifier` instead — it provides `verifyConnection()` for SMTP connectivity checks and `sendTestEmail()` for sending test messages.
-:::
-
-```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);
-  }
-}
-```
-
----
-
-## MailModule.register()
-
-The `MailModule` supports a `register()` static method for explicit module configuration:
-
-```typescript
-import { MailModule } from '@breadstone/archipel-platform-mailing';
-
-@Module({
-  imports: [
-    MailModule.register({
-      configEntries: MY_CUSTOM_CONFIG_ENTRIES, // optional
-      isGlobal: true,                          // optional, default: false
-    }),
-  ],
-})
-export class AppModule {}
-```
-
----
-
-## Health Check
-
-The `MailHealthIndicator` validates that the required mail configuration values (`MAIL_HOST`, `MAIL_USER`, `MAIL_PORT`) are present and non-empty. Import it from the `/health` subpath:
-
-```typescript
-import { MailHealthIndicator } from '@breadstone/archipel-platform-mailing/health';
-import { HealthModule } from '@breadstone/archipel-platform-health';
-
-@Module({
-  imports: [
-    MailModule.register({ /* ... */ }),
-    HealthModule.withIndicators([MailHealthIndicator]),
-  ],
-})
-export class AppModule {}
-```
-
-| Key | Check | Dependencies |
-| --- | ----- | ------------ |
-| `mail` | Validates mail host, user, and port config | `ConfigService` |
-
----
-
-## 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 },
-      });
-    }
-  }
-}
-```
-
----
-
-## Error Handling
-
-All delivery strategies throw a `MailDeliveryError` when email sending fails. This domain error class wraps the underlying provider SDK error and exposes structured metadata for error handling and observability.
-
-```typescript
-import { MailDeliveryError } from '@breadstone/archipel-platform-mailing';
-
-try {
-  await this._mail.send(options, content, true);
-} catch (error) {
-  if (error instanceof MailDeliveryError) {
-    logger.error('Mail delivery failed', {
-      provider: error.provider,  // 'postmark', 'resend', 'sendgrid', etc.
-      code: error.code,          // 'MAIL_DELIVERY'
-      cause: error.cause,        // Original provider SDK error
-    });
-  }
-}
-```
-
-| Property   | Type     | Description                                    |
-| ---------- | -------- | ---------------------------------------------- |
-| `code`     | `string` | Always `'MAIL_DELIVERY'`                       |
-| `provider` | `string` | Provider that failed (`smtp`, `postmark`, etc.) |
-| `cause`    | `unknown`| Original error from the provider SDK           |
-
----
-
-## Exports Summary
-
-### Core (`@breadstone/archipel-platform-mailing`)
-
-| Export                      | Type           | Description                     |
-| --------------------------- | -------------- | ------------------------------- |
-| `MailModule`                | NestJS Module  | Global mail module              |
-| `MailService`               | Service        | Send emails (plain + templated) |
-| `SmtpConnectionVerifier`    | Service        | SMTP connectivity verification  |
-| `MailVerificationService`   | Service        | ~~Email verification~~ (deprecated — use `SmtpConnectionVerifier`) |
-| `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 (`/health` subpath) |
-| `MailDeliveryError`         | Error class    | Domain error for delivery failures |
-
-### 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` |