@breadstone/archipel-mcp 0.0.53 → 0.0.55

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

@@ -1,337 +0,0 @@
----
-title: platform-database
-description: Prisma ORM integration with PostgreSQL, repository pattern, query abstraction, and pagination.
-order: 5
-tags: [database, prisma, postgresql, repository, queries, pagination, health]
-package: '@breadstone/archipel-platform-database'
----
-
-# platform-database
-
-Prisma ORM integration with PostgreSQL featuring a repository base class, type-safe query pattern, transactional support, and cursor-based pagination.
-
-**Package:** `@breadstone/archipel-platform-database`
-
-<InstallTabs />
-
-## Quick Start
-
-```typescript
-import { Module } from '@nestjs/common';
-import { ConfigModule } from '@breadstone/archipel-platform-core';
-import { DatabaseModule, PLATFORM_DATABASE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-database';
-
-@Module({
-  imports: [
-    ConfigModule.register('database', PLATFORM_DATABASE_CONFIG_ENTRIES),
-
-    // Global registration (recommended)
-    DatabaseModule.forRoot(),
-
-    // Feature-scoped registration
-    DatabaseModule.register(),
-  ],
-})
-export class AppModule {}
-```
-
----
-
-## Module Configuration
-
-```typescript
-interface IDatabaseModuleConfig {
-    accelerateUrl?: string;        // Prisma Accelerate URL (overrides DB_ACCELERATE_URL env var)
-    middlewares?: Array<unknown>;  // Future extension point
-}
-
-// Global setup
-DatabaseModule.forRoot(config?: IDatabaseModuleConfig): DynamicModule
-
-// Feature-scoped
-DatabaseModule.register(config?: IDatabaseModuleConfig): DynamicModule
-```
-
-### Config Keys
-
-Register all database config keys with `PLATFORM_DATABASE_CONFIG_ENTRIES`:
-
-```typescript
-import { ConfigModule } from '@breadstone/archipel-platform-core';
-import { PLATFORM_DATABASE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-database';
-
-ConfigModule.register('database', PLATFORM_DATABASE_CONFIG_ENTRIES);
-```
-
-### Environment Variables
-
-| Variable              | Description                               | Required            | Default |
-| --------------------- | ----------------------------------------- | ------------------- | ------- |
-| `DATABASE_URL`        | PostgreSQL connection string              | Yes                 | —       |
-| `DB_ACCELERATE_URL`   | Prisma Accelerate proxy URL               | No                  | `''`    |
-| `DB_AUTO_CONNECTION`  | Auto-connect on module init               | No                  | `true`  |
-| `DB_OPTIMIZE`         | Enable Prisma Optimize query analysis     | No                  | `true`  |
-| `DB_OPTIMIZE_API_KEY` | API key for the Prisma Optimize dashboard | If optimize enabled | `''`    |
-
-> **Accelerate resolution order:** `accelerateUrl` module parameter → `DB_ACCELERATE_URL` environment variable → no Accelerate.
-
----
-
-## Repository Pattern
-
-### RepositoryBase
-
-All repositories extend `RepositoryBase`, which provides the `execute()` method for running typed queries.
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { RepositoryBase, DatabaseService } from '@breadstone/archipel-platform-database';
-import type { Prisma } from '@prisma/client';
-
-@Injectable()
-export class OrderRepository extends RepositoryBase<Prisma.OrderDelegate, Prisma.OrderFindManyArgs, unknown> {
-  constructor(database: DatabaseService) {
-    super(database, database.order);
-  }
-}
-```
-
-### Query Pattern
-
-Queries are first-class objects that encapsulate data access logic:
-
-```typescript
-import { query, type IRepositoryQuery } from '@breadstone/archipel-platform-database';
-import type { Prisma } from '@prisma/client';
-
-// Define a query
-export const findOrdersByUser = (userId: string) =>
-  query<Prisma.OrderDelegate, IOrderEntity[]>('findOrdersByUser', async (model) => {
-    return model.findMany({
-      where: { userId },
-      orderBy: { createdAt: 'desc' },
-      select: {
-        id: true,
-        status: true,
-        total: true,
-        createdAt: true,
-      },
-    });
-  });
-
-// Define another query
-export const findOrderById = (orderId: string) =>
-  query<Prisma.OrderDelegate, IOrderEntity | null>('findOrderById', async (model) => {
-    return model.findUnique({
-      where: { id: orderId },
-      include: { items: true },
-    });
-  });
-```
-
-### Executing Queries
-
-```typescript
-@Injectable()
-export class OrderService {
-  constructor(private readonly _orderRepository: OrderRepository) {}
-
-  public async getOrdersByUser(userId: string): Promise<IOrderEntity[]> {
-    return this._orderRepository.execute(findOrdersByUser(userId));
-  }
-
-  public async getOrder(orderId: string): Promise<IOrderEntity | null> {
-    return this._orderRepository.execute(findOrderById(orderId));
-  }
-}
-```
-
-### Transactional Queries
-
-For multi-model writes, use `transactionalQuery`:
-
-```typescript
-import { transactionalQuery } from '@breadstone/archipel-platform-database';
-
-export const createOrderWithItems = (
-  userId: string,
-  items: Array<{ productId: string; quantity: number; price: number }>,
-) =>
-  transactionalQuery<IOrderEntity>('createOrderWithItems', async (tx) => {
-    const order = await tx.order.create({
-      data: {
-        userId,
-        status: 'pending',
-        total: items.reduce((sum, i) => sum + i.price * i.quantity, 0),
-      },
-    });
-
-    await tx.orderItem.createMany({
-      data: items.map((item) => ({
-        orderId: order.id,
-        productId: item.productId,
-        quantity: item.quantity,
-        unitPrice: item.price,
-      })),
-    });
-
-    return order;
-  });
-
-// Execute in a repository
-const order = await this._orderRepository.executeTransactional(createOrderWithItems(userId, items));
-```
-
----
-
-## Database Services
-
-### PrismaService
-
-Extended `PrismaClient` with Prisma Optimize support:
-
-```typescript
-import { PrismaService } from '@breadstone/archipel-platform-database';
-
-// Typically injected via DatabaseModule, not used directly
-@Injectable()
-export class MyService {
-  constructor(private readonly _prisma: PrismaService) {}
-}
-```
-
-### DatabaseService
-
-High-level database operations extending `PrismaService`:
-
-```typescript
-import { DatabaseService } from '@breadstone/archipel-platform-database';
-
-@Injectable()
-export class TransferService {
-  constructor(private readonly _db: DatabaseService) {}
-
-  public async transfer(fromId: string, toId: string, amount: number): Promise<void> {
-    await this._db.transactionCallback(async (tx) => {
-      await tx.account.update({
-        where: { id: fromId },
-        data: { balance: { decrement: amount } },
-      });
-      await tx.account.update({
-        where: { id: toId },
-        data: { balance: { increment: amount } },
-      });
-    });
-  }
-}
-```
-
----
-
-## Pagination
-
-Cursor-based pagination utility:
-
-```typescript
-import { paginator, type IPaginatedResult } from '@breadstone/archipel-platform-database';
-
-const paginate = paginator({ perPage: 20 });
-
-@Injectable()
-export class ProductService {
-  constructor(private readonly _prisma: PrismaService) {}
-
-  public async listProducts(page: number): Promise<IPaginatedResult<IProductEntity>> {
-    return paginate<IProductEntity>(
-      this._prisma.product,
-      { where: { isActive: true }, orderBy: { name: 'asc' } },
-      { page, perPage: 20 },
-    );
-  }
-}
-```
-
-### IPaginatedResult
-
-```typescript
-interface IPaginatedResult<T> {
-  data: T[];
-  meta: {
-    total: number; // Total matching records
-    lastPage: number; // Last page number
-    currentPage: number; // Current page
-    perPage: number; // Items per page
-    prev: number | null; // Previous page (null if first)
-    next: number | null; // Next page (null if last)
-  };
-}
-```
-
----
-
-## Entity Models
-
-Domain entities are defined as interfaces under `models/entities/`. They mirror the Prisma schema and serve as the type contract between repositories and services.
-
-```typescript
-// Property names MUST match Prisma schema exactly
-interface IOrderEntity {
-  readonly id: string;
-  readonly userId: string;
-  readonly status: string;
-  readonly total: number;
-  readonly createdAt: Date;
-  readonly updatedAt: Date;
-}
-```
-
-### Rules
-
-- Entity properties match Prisma schema property names exactly.
-- Entities are pure data — no methods or business logic.
-- Entities reference only other entity interfaces or primitives.
-- One entity interface per file.
-
----
-
-## Health Check
-
-The `DatabaseHealthIndicator` verifies database connectivity via a Prisma ping (`SELECT 1`). Import it from the `/health` subpath:
-
-```typescript
-import { DatabaseHealthIndicator } from '@breadstone/archipel-platform-database/health';
-import { HealthModule } from '@breadstone/archipel-platform-health';
-
-@Module({
-  imports: [
-    DatabaseModule,
-    HealthModule.withIndicators([DatabaseHealthIndicator]),
-  ],
-})
-export class AppModule {}
-```
-
-| Key | Check | Dependencies |
-| --- | ----- | ------------ |
-| `database` | Prisma `SELECT 1` ping | `PrismaHealthIndicator`, `DatabaseService` |
-
----
-
-## Exports Summary
-
-| Export                             | Type           | Description                              |
-| ---------------------------------- | -------------- | ---------------------------------------- |
-| `DatabaseModule`                   | NestJS Module  | `forRoot()` / `register()`               |
-| `DatabaseService`                  | Service        | Extended Prisma client with transactions |
-| `PrismaService`                    | Service        | Prisma client with extensions            |
-| `RepositoryBase`                   | Abstract class | Base class for repositories              |
-| `query()`                          | Factory        | Create typed query objects               |
-| `transactionalQuery()`             | Factory        | Create transactional query objects       |
-| `paginator()`                      | Factory        | Create pagination helper                 |
-| `DatabaseHealthIndicator`          | Health         | PostgreSQL health check (`/health` subpath) |
-| `PLATFORM_DATABASE_CONFIG_ENTRIES` | Constant       | Config entries for `ConfigModule`        |
-| `DB_ACCELERATE_URL`                | Config Key     | Prisma Accelerate URL                    |
-| `DB_AUTO_CONNECTION`               | Config Key     | Auto-connect toggle                      |
-| `DB_OPTIMIZE`                      | Config Key     | Prisma Optimize toggle                   |
-| `DB_OPTIMIZE_API_KEY`              | Config Key     | Prisma Optimize API key                  |
-| `DB` (Prisma)                      | Namespace      | Re-exported Prisma types                 |

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

@@ -1,255 +0,0 @@
----
-title: platform-documents
-description: Document generation engine supporting DOCX and PDF with template-based rendering.
-order: 9
-tags: [documents, docx, pdf, templates, generation, rendering]
-package: '@breadstone/archipel-platform-documents'
----
-
-# platform-documents
-
-Template-based document generation engine supporting DOCX and PDF output. Uses pluggable renderers and template parsers with image processing via Sharp.
-
-**Package:** `@breadstone/archipel-platform-documents`
-
-<InstallTabs />
-
-## Quick Start
-
-```typescript
-import { Module } from '@nestjs/common';
-import { DocumentModule } from '@breadstone/archipel-platform-documents';
-import { SharpImageProcessor } from '@breadstone/archipel-platform-documents/sharp';
-import { DocxDocumentRenderer2 } from '@breadstone/archipel-platform-documents/docx';
-import { PdfDocumentRenderer } from '@breadstone/archipel-platform-documents/pdf';
-
-@Module({
-  imports: [
-    DocumentModule.forRoot({
-      imageProcessor: SharpImageProcessor,
-      renderers: [DocxDocumentRenderer2, PdfDocumentRenderer],
-      maxImageWidth: 1920,
-      maxImageHeight: 1080,
-      delimiters: { start: '[[', end: ']]' },
-      debug: false,
-    }),
-  ],
-})
-export class AppModule {}
-```
-
----
-
-## Module Configuration
-
-### IDocumentModuleOptions
-
-| Property           | Type                          | Default | Description                                                               |
-| ------------------ | ----------------------------- | ------- | ------------------------------------------------------------------------- |
-| `imageProcessor`   | `Type<IImageProcessor>`       | —       | **Required.** Image processor class (e.g. `SharpImageProcessor`)          |
-| `renderers`        | `Type<IDocumentRenderer>[]`   | —       | **Required.** Renderer classes (e.g. `[DocxDocumentRenderer2, PdfDocumentRenderer]`) |
-| `maxImageWidth`    | `number`                      | `1920`  | Maximum width for embedded images                                         |
-| `maxImageHeight`   | `number`                      | `1080`  | Maximum height for embedded images                                        |
-| `delimiters.start` | `string`                      | `'[['`  | Template variable start delimiter                                         |
-| `delimiters.end`   | `string`                      | `']]'`  | Template variable end delimiter                                           |
-| `debug`            | `boolean`                     | `false` | Enable debug output                                                       |
-
----
-
-## DocumentEngine
-
-Main orchestrator for document rendering. Emits debug-level logs for document format detection and renderer initialization to aid troubleshooting.
-
-### Render from Template
-
-```typescript
-import { DocumentEngine } from '@breadstone/archipel-platform-documents';
-
-@Injectable()
-export class InvoiceService {
-  constructor(private readonly _docEngine: DocumentEngine) {}
-
-  public async generateInvoice(data: IInvoiceData): Promise<Buffer> {
-    const result = await this._docEngine.render({
-      templateId: 'invoice-template',
-      data: {
-        invoiceNumber: data.number,
-        customerName: data.customerName,
-        items: data.items.map((item) => ({
-          description: item.description,
-          qty: item.quantity,
-          unitPrice: `€${item.unitPrice.toFixed(2)}`,
-          total: `€${(item.quantity * item.unitPrice).toFixed(2)}`,
-        })),
-        subtotal: `€${data.subtotal.toFixed(2)}`,
-        tax: `€${data.tax.toFixed(2)}`,
-        total: `€${data.total.toFixed(2)}`,
-        date: new Date().toLocaleDateString('de-DE'),
-      },
-      templateFormat: 'docx',
-    });
-
-    return result.buffer;
-  }
-}
-```
-
-### Render from Buffer
-
-```typescript
-const templateBuffer = await fs.readFile('./templates/contract.docx');
-
-const result = await this._docEngine.render({
-  templateBuffer,
-  data: { clientName: 'Acme Corp', startDate: '2025-01-01' },
-  templateFormat: 'docx',
-});
-```
-
-### Templates with Images
-
-```typescript
-const result = await this._docEngine.render({
-  templateId: 'report-with-charts',
-  data: {
-    title: 'Q4 Report',
-    summary: 'Revenue increased by 23%.',
-  },
-  images: [
-    {
-      tag: 'revenueChart', // Matches [[revenueChart]] in template
-      buffer: chartImageBuffer,
-      contentType: 'image/png',
-      width: 800,
-      height: 400,
-    },
-  ],
-  templateFormat: 'docx',
-});
-```
-
----
-
-## Document Renderers
-
-### DOCX Renderer
-
-Renders DOCX (Microsoft Word) documents using `docxtemplater`:
-
-- Variable substitution: `[[variableName]]`
-- Loops: `[[#items]][[name]] - [[price]][[/items]]`
-- Conditionals: `[[#if showDiscount]]...[[/if]]`
-- Image placeholders: `[[imageName]]`
-
-### PDF Renderer
-
-Renders PDF documents using `pdf-lib`:
-
-- Text substitution in PDF form fields
-- Image insertion
-- Page manipulation
-
----
-
-## Image Processing
-
-### SharpImageProcessor
-
-Resizes and optimizes images before embedding in documents:
-
-```typescript
-import { SharpImageProcessor } from '@breadstone/archipel-platform-documents';
-
-// Used internally by DocumentEngine
-// Respects maxImageWidth and maxImageHeight from module options
-```
-
-Supported formats: PNG, JPEG, WebP, TIFF, AVIF.
-
----
-
-## Real-World Example: Contract Generator
-
-```typescript
-@Controller('api/v1/contracts')
-export class ContractController {
-  constructor(
-    private readonly _docEngine: DocumentEngine,
-    private readonly _blobService: BlobService,
-  ) {}
-
-  @Post(':id/generate')
-  public async generate(@Param('id') contractId: string, @Res() res: Response): Promise<void> {
-    const contract = await this._contractService.findById(contractId);
-
-    const result = await this._docEngine.render({
-      templateId: 'service-agreement',
-      data: {
-        clientName: contract.clientName,
-        startDate: contract.startDate.toLocaleDateString('de-DE'),
-        endDate: contract.endDate.toLocaleDateString('de-DE'),
-        monthlyFee: `€${contract.monthlyFee.toFixed(2)}`,
-        services: contract.services,
-      },
-      templateFormat: 'docx',
-    });
-
-    // Optionally store in blob storage
-    await this._blobService.uploadFile(
-      `contracts/${contractId}/${result.name}`,
-      result.buffer,
-      'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-    );
-
-    res.set({
-      'Content-Type': result.contentType,
-      'Content-Disposition': `attachment; filename="${result.name}"`,
-    });
-    res.send(result.buffer);
-  }
-}
-```
-
----
-
-## Error Handling
-
-The library provides a hierarchy of domain error classes for structured error handling:
-
-| Error class                | Base class      | When thrown                                       |
-| -------------------------- | --------------- | ------------------------------------------------- |
-| `DocumentError`            | `Error`         | Base class for all document errors                |
-| `DocumentRenderError`      | `DocumentError` | Template rendering failures (DOCX, PDF)           |
-| `DocumentValidationError`  | `DocumentError` | Invalid templates, missing placeholders           |
-| `ImageProcessingError`     | `DocumentError` | Image resize/conversion failures (Sharp)          |
-
-```typescript
-import {
-  DocumentRenderError,
-  DocumentValidationError,
-  ImageProcessingError,
-} from '@breadstone/archipel-platform-documents';
-```
-
-All errors extend `DocumentError`, so a single `catch (error instanceof DocumentError)` handles any document-related failure.
-
----
-
-## Exports Summary
-
-| Export                 | Type           | Description                               |
-| ---------------------- | -------------- | ----------------------------------------- |
-| `DocumentModule`       | NestJS Module  | `forRoot()` configuration                 |
-| `DocumentEngine`       | Service        | Main rendering orchestrator               |
-| `BaseDocumentRenderer` | Abstract class | Renderer base                             |
-| `IDocumentRenderer`    | Interface      | Renderer contract                         |
-| `SharpImageProcessor`  | Service        | Image resize/optimization                 |
-| `IImageProcessor`      | Interface      | Image processor contract                  |
-| `DocumentFormat`       | Enum           | `'docx'` / `'pdf'`                        |
-| `TemplateFormat`       | Enum           | Template format identifiers               |
-| `IRenderResult`        | Interface      | Render output (buffer, name, contentType) |
-| `IDocumentProbeReport` | Interface      | Template validation report                |
-| `DocumentError`        | Error class    | Base document error                       |
-| `DocumentRenderError`  | Error class    | Render failure error                      |
-| `DocumentValidationError` | Error class | Validation failure error                  |
-| `ImageProcessingError` | Error class    | Image processing failure error            |