npm - @breadstone/archipel-mcp - Versions diffs - 0.0.13 → 0.0.14 - Mend

@breadstone/archipel-mcp 0.0.13 → 0.0.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (612) hide show

package/data/guides/document-generation.md DELETED Viewed

@@ -1,174 +0,0 @@
----
-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 DELETED Viewed

@@ -1,196 +0,0 @@
----
-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);
-  }
-}
-```
----
-## 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 DELETED Viewed

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