npm - @breadstone/archipel-mcp - Versions diffs - 0.0.53 → 0.0.55 - Mend

@breadstone/archipel-mcp 0.0.53 → 0.0.55

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 (232) hide show

package/data/packages/platform-queue/index.md DELETED Viewed

@@ -1,192 +0,0 @@
----
-title: platform-queue
-description: Provider-agnostic queue infrastructure with support for in-memory FIFO, BullMQ (Redis), Azure Service Bus, and Vercel Queues.
-order: 19
-tags: [queue, job-queue, fifo, memory-queue, bullmq, redis, azure-service-bus, vercel-queues, ports-and-adapters, health]
-package: '@breadstone/archipel-platform-queue'
----
-# platform-queue
-Provider-agnostic queue infrastructure for NestJS. Exposes a unified `IQueue` contract with four ready-made implementations: in-memory FIFO (`MemoryQueue`), BullMQ/Redis (`BullMqQueue`), Azure Service Bus (`AzureQueue`), and Vercel Queues (`VercelQueue`). Jobs follow a lifecycle from pending through processing to completed or failed, with full metadata tracking.
-**Package:** `@breadstone/archipel-platform-queue`
-<InstallTabs />
-## Architecture
-```mermaid
-graph TD
-    Core["@breadstone/archipel-platform-queue<br/><i>IQueue, models, errors, MemoryQueue</i>"]
-    BullMQ["@breadstone/archipel-platform-queue/bullmq<br/><i>BullMqQueue</i>"]
-    Azure["@breadstone/archipel-platform-queue/azure<br/><i>AzureQueue</i>"]
-    Vercel["@breadstone/archipel-platform-queue/vercel<br/><i>VercelQueue</i>"]
-    BullMQ -->|implements| Core
-    Azure -->|implements| Core
-    Vercel -->|implements| Core
-    BullMQ -.-|requires| R["bullmq"]
-    Azure -.-|requires| S["@azure/service-bus"]
-    Vercel -.-|requires| V["@vercel/queue"]
-```
-Each provider SDK is an **optional peer dependency**. Install only the one you need. `MemoryQueue` ships with the core entry point and requires no additional dependencies.
----
-## Quick Start
-### 1. Install the provider SDK (optional)
-```bash
-# Pick one (or use MemoryQueue without any extra SDK):
-yarn add bullmq
-yarn add @azure/service-bus
-yarn add @vercel/queue
-```
-### 2. Register the queue
-```typescript
-import { Module } from '@nestjs/common';
-import { IQueue, MemoryQueue } from '@breadstone/archipel-platform-queue';
-@Module({
-  providers: [
-    {
-      provide: 'IQueue',
-      useFactory: () => new MemoryQueue({ maxJobs: 5_000 }),
-    },
-  ],
-  exports: ['IQueue'],
-})
-export class AppModule {}
-```
-### Switching providers
-Replace the imports — no other code change needed:
-```typescript
-import { BullMqQueue } from '@breadstone/archipel-platform-queue/bullmq';
-{
-  provide: 'IQueue',
-  useFactory: () => new BullMqQueue({ redisUrl: 'redis://localhost:6379' }),
-}
-```
----
-## Queue Providers
-### Memory (built-in)
-**Entry point:** `@breadstone/archipel-platform-queue`
-| Variable         | Required | Default | Description                           |
-| ---------------- | -------- | ------- | ------------------------------------- |
-| `QUEUE_MAX_JOBS` | No       | `10000` | Maximum jobs retained before eviction |
-### BullMQ
-**Subpath:** `@breadstone/archipel-platform-queue/bullmq`
-**SDK:** `bullmq` ≥ 5.0.0
-| Variable          | Required | Default | Description                                  |
-| ----------------- | -------- | ------- | -------------------------------------------- |
-| `BULLMQ_REDIS_URL`| Yes      | —       | Redis connection URL (e.g. `redis://localhost:6379`) |
-| `BULLMQ_PREFIX`   | No       | `""`    | Optional key prefix for all BullMQ queues    |
-```typescript
-import { BullMqQueue, BULLMQ_CONFIG_ENTRIES } from '@breadstone/archipel-platform-queue/bullmq';
-```
-### Azure Service Bus
-**Subpath:** `@breadstone/archipel-platform-queue/azure`
-**SDK:** `@azure/service-bus` ≥ 7.0.0
-| Variable                  | Required | Default | Description                              |
-| ------------------------- | -------- | ------- | ---------------------------------------- |
-| `AZURE_CONNECTION_STRING` | Yes      | —       | Azure Service Bus connection string      |
-| `AZURE_RECEIVE_WAIT_MS`  | No       | `5000`  | Max wait time (ms) when receiving messages|
-```typescript
-import { AzureQueue, AZURE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-queue/azure';
-```
-### Vercel Queues
-**Subpath:** `@breadstone/archipel-platform-queue/vercel`
-**SDK:** `@vercel/queue` ≥ 0.1.0
-| Variable                                | Required | Default | Description                                           |
-| --------------------------------------- | -------- | ------- | ----------------------------------------------------- |
-| `VERCEL_QUEUE_REGION`                   | Yes      | —       | Vercel region code (e.g. `iad1`, `fra1`, `sfo1`)      |
-| `VERCEL_QUEUE_CONSUMER_GROUP`           | Yes      | —       | Consumer group name for receiving messages             |
-| `VERCEL_QUEUE_TOKEN`                    | No       | —       | OIDC bearer token (auto-fetched when omitted)          |
-| `VERCEL_QUEUE_DEPLOYMENT_ID`            | No       | —       | Deployment ID for per-deployment message isolation     |
-| `VERCEL_QUEUE_VISIBILITY_TIMEOUT_SECONDS`| No      | `300`   | Visibility timeout in seconds for received messages    |
-```typescript
-import { VercelQueue, VERCEL_CONFIG_ENTRIES } from '@breadstone/archipel-platform-queue/vercel';
-```
----
-## Job Lifecycle
-| Status       | Description                                          |
-| ------------ | ---------------------------------------------------- |
-| `pending`    | Job is waiting to be picked up                       |
-| `processing` | Job has been dequeued and is being processed         |
-| `completed`  | Job finished successfully via `markCompleted()`      |
-| `failed`     | Job finished with an error via `markFailed()`        |
----
-## Error Handling
-| Error Class             | Base Class   | When Thrown                                    |
-| ----------------------- | ------------ | ---------------------------------------------- |
-| `QueueError`            | `Error`      | Base class for all queue errors                |
-| `QueueJobNotFoundError` | `QueueError` | Job ID does not exist                          |
-| `QueueJobStateError`    | `QueueError` | Job is in wrong state for requested transition |
-| `QueueValidationError`  | `QueueError` | Empty queue name or error message              |
----
-## Health Check
-The `QueueHealthIndicator` reports the queue subsystem as available. Import it from the `/health` subpath:
-```typescript
-import { QueueHealthIndicator } from '@breadstone/archipel-platform-queue/health';
-import { HealthModule } from '@breadstone/archipel-platform-health';
-@Module({
-  imports: [
-    QueueModule.register({ /* ... */ }),
-    HealthModule.withIndicators([QueueHealthIndicator]),
-  ],
-})
-export class AppModule {}
-```
-| Key | Check | Dependencies |
-| --- | ----- | ------------ |
-| `queue` | Always reports `up` | None |
----
-## Peer Dependencies
-| Package              | Required | Notes                            |
-| -------------------- | -------- | -------------------------------- |
-| `@nestjs/common`    | Yes      | NestJS core                      |
-| `bullmq`            | Optional | Required for BullMQ provider     |
-| `@azure/service-bus` | Optional | Required for Azure Service Bus   |
-| `@vercel/queue`     | Optional | Required for Vercel Queues       |

package/data/packages/platform-reporting/index.md DELETED Viewed

@@ -1,233 +0,0 @@
----
-title: platform-reporting
-description: Business reporting framework with pluggable data contributors and query execution.
-order: 10
-tags: [reporting, analytics, datasets, queries, contributors]
-package: '@breadstone/archipel-platform-reporting'
----
-# platform-reporting
-Extensible business reporting framework using a contributor registry pattern. Feature modules register data contributors that expose datasets, and the central facade handles catalog discovery and query execution.
-**Package:** `@breadstone/archipel-platform-reporting`
-<InstallTabs />
-## Quick Start
-```typescript
-import { Module } from '@nestjs/common';
-import { ReportingModule } from '@breadstone/archipel-platform-reporting';
-@Module({
-  imports: [ReportingModule],
-})
-export class AppModule {}
-```
----
-## Contributor Pattern
-Each feature module provides an `IReportingContributor` that exposes the datasets it can report on. Contributors are registered with the `ReportingContributorRegistry` and discovered by the `ReportingFacade`.
-> **Capacity limit:** The registry enforces a maximum of **200** registered contributors. Attempts to exceed this limit are logged as warnings and silently ignored.
-### IReportingContributor
-```typescript
-interface IReportingContributor {
-  readonly featureKey: string;
-  listDatasets(): Promise<IReportingDataset[]>;
-  executeQuery(dataset: IReportingDataset, request: IReportingQuery): Promise<IReportingQueryResult>;
-}
-```
-### Implementing a Contributor
-```typescript
-import { Injectable } from '@nestjs/common';
-import type {
-  IReportingContributor,
-  IReportingDataset,
-  IReportingQuery,
-  IReportingQueryResult,
-} from '@breadstone/archipel-platform-reporting';
-@Injectable()
-export class OrderReportingContributor implements IReportingContributor {
-  public readonly featureKey = 'orders';
-  constructor(private readonly _prisma: PrismaService) {}
-  public async listDatasets(): Promise<IReportingDataset[]> {
-    return [
-      {
-        datasetId: 'orders.summary',
-        featureKey: 'orders',
-        datasetKey: 'summary',
-        name: 'Order Summary',
-        description: 'Aggregated order data by period',
-        fields: [
-          { fieldId: 'period', label: 'Period', type: 'string', isNullable: false },
-          { fieldId: 'orderCount', label: 'Order Count', type: 'number', isNullable: false },
-          { fieldId: 'revenue', label: 'Revenue', type: 'number', isNullable: false },
-          { fieldId: 'avgOrderValue', label: 'Avg. Order Value', type: 'number', isNullable: false },
-        ],
-      },
-      {
-        datasetId: 'orders.by-product',
-        featureKey: 'orders',
-        datasetKey: 'by-product',
-        name: 'Orders by Product',
-        description: 'Order breakdown by product',
-        fields: [
-          { fieldId: 'productName', label: 'Product', type: 'string', isNullable: false },
-          { fieldId: 'quantity', label: 'Quantity Sold', type: 'number', isNullable: false },
-          { fieldId: 'revenue', label: 'Revenue', type: 'number', isNullable: false },
-        ],
-      },
-    ];
-  }
-  public async executeQuery(dataset: IReportingDataset, request: IReportingQuery): Promise<IReportingQueryResult> {
-    // Execute query against database
-    const rows = await this._prisma.$queryRaw`
-            SELECT /* ... */
-        `;
-    return {
-      datasetId: dataset.datasetId,
-      fields: dataset.fields,
-      rows,
-      total: rows.length,
-    };
-  }
-}
-```
-### Registering a Contributor
-```typescript
-import { Module, type OnModuleInit } from '@nestjs/common';
-import { ReportingContributorRegistry } from '@breadstone/archipel-platform-reporting';
-@Module({
-  providers: [OrderReportingContributor],
-})
-export class OrderModule implements OnModuleInit {
-  constructor(
-    private readonly _registry: ReportingContributorRegistry,
-    private readonly _contributor: OrderReportingContributor,
-  ) {}
-  public onModuleInit(): void {
-    this._registry.register(this._contributor);
-  }
-}
-```
----
-## ReportingFacade
-Central API for catalog browsing and query execution. Each `executeQuery()` call is subject to a **30-second timeout** — queries that exceed this limit throw a `ReportingExecutionError`.
-### Browse Catalog
-```typescript
-import { ReportingFacade } from '@breadstone/archipel-platform-reporting';
-@Controller('api/v1/reports')
-export class ReportController {
-  constructor(private readonly _reporting: ReportingFacade) {}
-  @Get('datasets')
-  public async listDatasets(): Promise<IReportingDataset[]> {
-    return this._reporting.getCatalog();
-  }
-  @Get('datasets/:id')
-  public async getDataset(@Param('id') id: string): Promise<IReportingDataset> {
-    return this._reporting.getDataset(id);
-  }
-}
-```
-### Execute Query
-```typescript
-@Post('query')
-public async runQuery(@Body() body: IReportingQuery): Promise<IReportingQueryResult> {
-    return this._reporting.executeQuery(body);
-}
-```
----
-## Data Model
-### IReportingDataset
-```typescript
-interface IReportingDataset {
-  readonly datasetId: string; // e.g. 'orders.summary'
-  readonly featureKey: string; // e.g. 'orders'
-  readonly datasetKey: string; // e.g. 'summary'
-  readonly name: string; // Human-readable name
-  readonly description?: string;
-  readonly fields: IReportingDatasetField[];
-}
-```
-### IReportingDatasetField
-```typescript
-interface IReportingDatasetField {
-  readonly fieldId: string;
-  readonly label: string;
-  readonly type: ReportingFieldType; // 'boolean' | 'datetime' | 'json' | 'number' | 'string'
-  readonly isNullable: boolean;
-  readonly description?: string;
-}
-```
-### IReportingQuery
-```typescript
-interface IReportingQuery {
-  readonly datasetId: string;
-  readonly filters?: IReportingQueryFilter[];
-  readonly sorts?: IReportingQuerySort[];
-  readonly limit?: number;
-  readonly offset?: number;
-}
-```
-### IReportingQueryResult
-```typescript
-interface IReportingQueryResult {
-  readonly datasetId: string;
-  readonly fields: IReportingDatasetField[];
-  readonly rows: ReadonlyArray<Record<string, unknown>>;
-  readonly total: number;
-}
-```
----
-## Exports Summary
-| Export                          | Type          | Description               |
-| ------------------------------- | ------------- | ------------------------- |
-| `ReportingModule`               | NestJS Module | Global reporting module   |
-| `ReportingFacade`               | Service       | Catalog + query execution |
-| `ReportingContributorRegistry`  | Service       | Contributor registration  |
-| `IReportingContributor`         | Interface     | Contributor contract      |
-| `ReportingDataset`              | Model         | Dataset definition        |
-| `ReportingDatasetField`         | Model         | Field definition          |
-| `ReportingQuery`                | Model         | Query structure           |
-| `ReportingQueryResult`          | Model         | Query result              |
-| `ReportingDatasetNotFoundError` | Error         | Dataset lookup failure    |

package/data/packages/platform-resources/index.md DELETED Viewed

@@ -1,137 +0,0 @@
----
-title: platform-resources
-description: Multi-strategy resource management with MIME type detection and optional caching.
-order: 3
-tags: [resources, files, blob, mime, caching]
-package: '@breadstone/archipel-platform-resources'
----
-# platform-resources
-Multi-strategy resource management for NestJS applications. Loads files from the file system, embedded buffers, or blob storage with MIME type detection and optional caching. Extracted from `platform-core` to provide a focused, independently versionable resource module.
-**Package:** `@breadstone/archipel-platform-resources`
-<InstallTabs />
-## Installation
-```typescript
-import {
-  ResourceModule,
-  ResourceManager,
-  FileResourceStrategy,
-  BlobResourceStrategy,
-  EmbeddedResourceStrategy,
-  ResourceNotFoundError,
-} from '@breadstone/archipel-platform-resources';
-```
----
-## Module Registration
-Register the module with one or more resource strategies:
-```typescript
-import { Module } from '@nestjs/common';
-import { ResourceModule, FileResourceStrategy, EmbeddedResourceStrategy } from '@breadstone/archipel-platform-resources';
-import { join } from 'node:path';
-@Module({
-  imports: [
-    ResourceModule.forRoot({
-      strategies: [
-        new FileResourceStrategy({
-          basePath: join(__dirname, '..', 'assets'),
-        }),
-        new EmbeddedResourceStrategy([
-          { name: 'fallback.html', buffer: Buffer.from('<html>Fallback</html>') },
-        ]),
-      ],
-    }),
-  ],
-})
-export class AppModule {}
-```
-## Using ResourceManager
-Inject and use `ResourceManager` to load resources at runtime:
-```typescript
-import { Injectable } from '@nestjs/common';
-import { ResourceManager } from '@breadstone/archipel-platform-resources';
-@Injectable()
-export class TemplateService {
-  constructor(private readonly _resourceManager: ResourceManager) {}
-  public async loadTemplate(name: string): Promise<string> {
-    const result = await this._resourceManager.get(name);
-    return result.buffer.toString('utf-8');
-  }
-}
-```
----
-## Strategies
-| Strategy                    | Description                                                       |
-| --------------------------- | ----------------------------------------------------------------- |
-| `FileResourceStrategy`     | Loads resources from the local file system with glob support       |
-| `BlobResourceStrategy`     | Loads resources from a blob storage adapter (Vercel, Azure, S3)    |
-| `EmbeddedResourceStrategy` | Serves pre-loaded in-memory buffers                                |
-### BlobResourceStrategy
-For loading resources from cloud blob storage, provide an adapter that implements `IBlobServiceAdapter`:
-```typescript
-import { BlobResourceStrategy, type IBlobServiceAdapter } from '@breadstone/archipel-platform-resources';
-const blobStrategy = new BlobResourceStrategy({
-  adapter: myBlobAdapter,
-  containerName: 'templates',
-});
-```
-### Custom Strategies
-Implement `IResourceStrategy` to create your own resource loading strategy:
-```typescript
-import type { IResourceStrategy, IResourceResult } from '@breadstone/archipel-platform-resources';
-export class CustomStrategy implements IResourceStrategy {
-  public async get(name: string): Promise<IResourceResult | undefined> {
-    // Custom loading logic
-  }
-}
-```
----
-## Interfaces
-| Interface              | Description                              |
-| ---------------------- | ---------------------------------------- |
-| `IResourceResult`     | Result object with `buffer` and `metadata` |
-| `IResourceMetadata`   | Metadata including `mimeType` and `size`  |
-| `IResourceStrategy`   | Strategy contract for resource loading    |
-| `IBlobServiceAdapter`  | Adapter contract for blob storage access  |
----
-## Error Classes
-| Error                    | Description                                   |
-| ------------------------ | --------------------------------------------- |
-| `ResourceNotFoundError` | Thrown when a requested resource is not found   |
----
-## API Reference
-The auto-generated API reference is published when API docs are generated for this package.