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

@breadstone/archipel-mcp 0.0.11 → 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 (604) hide show

package/data/guides/openapi-and-feature-discovery.md DELETED Viewed

@@ -1,266 +0,0 @@
----
-title: OpenAPI & Feature Discovery
-description: Set up multi-document Swagger UI, annotate controllers with the @Api decorator, and use @SwaggerFeature for automatic per-module documentation discovery.
-order: 16
----
-# OpenAPI & Feature Discovery
-This guide covers the full lifecycle of API documentation with `platform-openapi`: installing the package, configuring environment variables, annotating controllers, registering feature modules, and bootstrapping the multi-document Swagger UI.
----
-## Installation
-```bash
-yarn add @breadstone/archipel-platform-openapi
-```
----
-## Configuration
-### Environment Variables
-All four variables are **required**:
-```env
-APP_VERSION=1.0.0
-SWAGGER_CONTACT_NAME=Your Team
-SWAGGER_CONTACT_URL=https://yourcompany.com
-SWAGGER_CONTACT_EMAIL=api@yourcompany.com
-```
-| Variable                | Purpose                                            |
-| ----------------------- | -------------------------------------------------- |
-| `APP_VERSION`           | Version shown in every generated OpenAPI document. |
-| `SWAGGER_CONTACT_NAME`  | Contact name in the info block.                    |
-| `SWAGGER_CONTACT_URL`   | Contact URL in the info block.                     |
-| `SWAGGER_CONTACT_EMAIL` | Contact email in the info block.                   |
----
-## Overview: How It Works
-```
-  @SwaggerFeature()        SwaggerFeatureDiscovery       SwaggerFeatureRegistry       SwaggerMultiDocumentService
-  ──────────────────       ──────────────────────       ──────────────────────       ───────────────────────────
-  Decorator stores          Reads global store and       Holds finalized list of      Builds per-feature OpenAPI
-  metadata in global        registers features into      features. Sorted, locked,    documents, sets up Swagger
-  store at import time.     the registry.                immutable after finalize().  UI routes, and index page.
-```
-1. Each feature module is decorated with `@SwaggerFeature()` — metadata is stored globally when the module is imported.
-2. During bootstrap, `SwaggerFeatureDiscovery` reads all registered features and pushes them into `SwaggerFeatureRegistry`.
-3. `SwaggerMultiDocumentService` finalizes the registry, builds one OpenAPI document per feature (filtered by tag), and mounts Swagger UI + JSON endpoints.
----
-## Step 1: Annotate Feature Modules
-Decorate each feature module with `@SwaggerFeature()`. This tells the discovery system which tag corresponds to which documentation section.
-```typescript
-import { Module } from '@nestjs/common';
-import { SwaggerFeature } from '@breadstone/archipel-platform-openapi';
-import { TipController } from './TipController';
-import { TipService } from './TipService';
-@SwaggerFeature({
-  name: 'tip',
-  title: 'My App API — Tips',
-  description: 'API endpoints for tip management.',
-  tag: 'Tip',
-  tags: ['Tip'],
-})
-@Module({
-  controllers: [TipController],
-  providers: [TipService],
-  exports: [TipService],
-})
-export class TipModule {}
-```
-| Property      | Required | Description                                                                  |
-| ------------- | -------- | ---------------------------------------------------------------------------- |
-| `name`        | Yes      | Short identifier used for the URL path (e.g. `docs/tip`).                    |
-| `title`       | Yes      | Human-readable title shown in the Swagger UI header.                         |
-| `description` | Yes      | Description shown in the Swagger UI header and on the index page.            |
-| `tag`         | Yes      | Primary OpenAPI tag — operations with this tag are included in the document. |
-| `tags`        | Yes      | Array of all tags to include. Usually `[tag]`.                               |
-| `path`        | No       | Custom URL path. Defaults to `docs/{name}`.                                  |
----
-## Step 2: Annotate Controllers with `@Api()`
-`@Api()` is a convenience decorator that combines multiple `@nestjs/swagger` decorators into one. Use it on methods or classes to keep controller annotations concise.
-```typescript
-import { Controller, Get, Post, Body, Param, HttpCode, HttpStatus } from '@nestjs/common';
-import { Api } from '@breadstone/archipel-platform-openapi';
-import { CreateTipRequest } from './dto/CreateTipRequest';
-import { TipResponse } from './dto/TipResponse';
-@Controller('api/v1/tips')
-export class TipController {
-  @Get()
-  @Api({
-    tags: 'Tip',
-    operation: { summary: 'List all tips' },
-    responses: [{ status: 200, description: 'Tips retrieved.', type: [TipResponse] }],
-  })
-  public listTips(): Promise<TipResponse[]> {
-    // ...
-  }
-  @Get(':tipId')
-  @Api({
-    tags: 'Tip',
-    auth: 'bearer',
-    operation: { summary: 'Get a tip by ID' },
-    params: { name: 'tipId', type: String },
-    responses: [
-      { status: 200, description: 'Tip found.', type: TipResponse },
-      { status: 404, description: 'Tip not found.' },
-    ],
-  })
-  public getTip(@Param('tipId') tipId: string): Promise<TipResponse> {
-    // ...
-  }
-  @Post()
-  @HttpCode(HttpStatus.CREATED)
-  @Api({
-    tags: 'Tip',
-    auth: 'bearer',
-    operation: { summary: 'Create a new tip' },
-    body: { type: CreateTipRequest },
-    responses: [
-      { status: 201, description: 'Tip created.', type: TipResponse },
-      { status: 400, description: 'Validation failed.' },
-    ],
-  })
-  public createTip(@Body() body: CreateTipRequest): Promise<TipResponse> {
-    // ...
-  }
-}
-```
-### `@Api()` Options Reference
-| Option       | Type                                          | Description                                          |
-| ------------ | --------------------------------------------- | ---------------------------------------------------- |
-| `auth`       | `'bearer' \| 'basic' \| 'oauth2' \| 'cookie'` | Adds the corresponding auth decorator.               |
-| `tags`       | `string \| string[]`                          | OpenAPI tag(s) for the operation.                    |
-| `operation`  | `ApiOperationOptions`                         | Summary, description, deprecation flag, etc.         |
-| `responses`  | `ApiResponseOptions \| ApiResponseOptions[]`  | One or more response definitions.                    |
-| `headers`    | `ApiHeaderOptions[]`                          | Expected request headers.                            |
-| `params`     | `ApiParamOptions \| ApiParamOptions[]`        | Path parameter definitions.                          |
-| `query`      | `ApiQueryOptions \| ApiQueryOptions[]`        | Query parameter definitions.                         |
-| `body`       | `ApiBodyOptions`                              | Request body definition.                             |
-| `scopes`     | `string[]`                                    | OAuth2 scopes (only relevant when `auth: 'oauth2'`). |
-| `extensions` | `Record<string, string \| number \| boolean>` | Custom OpenAPI extension properties (`x-*`).         |
----
-## Step 3: Bootstrap the Swagger UI
-In your application bootstrap (`main.ts`), wire up discovery and the multi-document service:
-```typescript
-import { NestFactory } from '@nestjs/core';
-import {
-  SwaggerFeatureDiscovery,
-  SwaggerFeatureRegistry,
-  SwaggerMultiDocumentService,
-} from '@breadstone/archipel-platform-openapi';
-import { ConfigService, ContentTemplateEngine, HostService, ResourceManager } from '@breadstone/archipel-platform-core';
-import { AppModule } from './AppModule';
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  // Resolve services
-  const configService = app.get(ConfigService);
-  const hostService = app.get(HostService);
-  const resourceManager = app.get(ResourceManager);
-  const contentTemplateEngine = app.get(ContentTemplateEngine);
-  // 1. Discover features
-  const featureRegistry = new SwaggerFeatureRegistry();
-  const discovery = new SwaggerFeatureDiscovery();
-  discovery.registerDiscoveredFeatures(featureRegistry);
-  discovery.registerDefaultFeatures(featureRegistry);
-  // 2. Setup multi-document Swagger UI
-  const swaggerService = new SwaggerMultiDocumentService(
-    app,
-    configService,
-    hostService,
-    featureRegistry,
-    resourceManager,
-    contentTemplateEngine,
-  );
-  await swaggerService.setupMultipleSwaggerDocuments();
-  await app.listen(3000);
-}
-bootstrap();
-```
-After bootstrap the following routes are available:
-| Route              | What it serves                                      |
-| ------------------ | --------------------------------------------------- |
-| `/docs`            | Main index page with a searchable feature grid.     |
-| `/docs/{name}`     | Swagger UI for a single feature (e.g. `/docs/tip`). |
-| `/api/{name}.json` | Raw OpenAPI JSON for a single feature.              |
-| `/docs/all`        | Combined Swagger UI with every endpoint.            |
-| `/api/all.json`    | Combined OpenAPI JSON.                              |
----
-## How Tag Filtering Works
-Each feature declares a `tag` (e.g. `'Tip'`). When the document is built:
-1. A full OpenAPI document is created from the entire application.
-2. All paths that do **not** have an operation tagged with the feature's tag are removed.
-3. Schema references used only by removed operations are pruned.
-4. The special tag `'*'` (used by the default `all` feature) skips filtering entirely.
-This means the `tag` value in `@SwaggerFeature()` must match the `tags` value you pass to `@Api()` on your controllers.
----
-## Exporting OpenAPI Specs Programmatically
-If you need the generated OpenAPI documents outside of a running HTTP server (e.g. for CI contract checks or SDK generation), use `generateOpenApiDocuments()`:
-```typescript
-const documents = swaggerService.generateOpenApiDocuments();
-for (const { feature, document } of documents) {
-  const json = JSON.stringify(document, null, 2);
-  writeFileSync(`specs/${feature.name}.json`, json);
-}
-```
----
-## Theme Customization
-`SwaggerTheme` loads `swagger.css` and `swagger.js` from the package assets via `ResourceManager`. These files customize the Swagger UI appearance (colors, dark theme, responsive layout). The theme is applied automatically — no additional configuration is needed.
-To override the theme, provide your own `swagger.css` / `swagger.js` files through a `FileResourceStrategy` with a higher-priority base path so that `ResourceManager` picks them up before the built-in assets.
----
-## Checklist
-- [ ] All four environment variables set (`APP_VERSION`, `SWAGGER_CONTACT_*`)
-- [ ] Every feature module decorated with `@SwaggerFeature()`
-- [ ] Tags in `@SwaggerFeature({ tag })` match tags in `@Api({ tags })`
-- [ ] `SwaggerFeatureDiscovery` called before `setupMultipleSwaggerDocuments()`
-- [ ] `registerDefaultFeatures()` called for the combined `/docs/all` document

package/data/guides/payments-and-feature-gating.md DELETED Viewed

@@ -1,244 +0,0 @@
----
-title: Payments & Feature Gating
-description: Integrate payment providers (Stripe, Paddle, LemonSqueezy, Mollie) and gate features by subscription tier.
-order: 9
----
-# Payments & Feature Gating
-This guide covers payment integration with `platform-payments`: choosing a payment provider, handling webhooks, gating features by subscription tier, and tracking feature usage.
----
-## Installation
-```bash
-yarn add @breadstone/archipel-platform-payments
-```
----
-## Choose a Payment Provider
-`platform-payments` normalizes payment operations across multiple providers. You implement the `PaymentClientPort` for your chosen provider:
-| Provider         | What it provides                        |
-| ---------------- | --------------------------------------- |
-| **Stripe**       | Cards, subscriptions, invoices          |
-| **Paddle**       | SaaS billing, tax handling              |
-| **LemonSqueezy** | Digital products, memberships           |
-| **Mollie**       | European payment methods, subscriptions |
----
-## Module Registration
-```typescript
-import { Module } from '@nestjs/common';
-import { PaymentModule } from '@breadstone/archipel-platform-payments';
-import { StripePaymentClient } from './adapters/StripePaymentClient';
-import { PrismaFeatureAccessAdapter } from './adapters/PrismaFeatureAccessAdapter';
-import { STRIPE_CONFIG_ENTRIES } from './env';
-@Module({
-  imports: [
-    PaymentModule.register({
-      paymentClient: StripePaymentClient,
-      featureAccess: PrismaFeatureAccessAdapter,
-      configEntries: [...STRIPE_CONFIG_ENTRIES],
-    }),
-  ],
-})
-export class AppModule {}
-```
----
-## Implementing the Payment Client Port
-The `PaymentClientPort` defines the contract between the library and your payment provider. Implement it for your chosen provider:
-```typescript
-import { Injectable } from '@nestjs/common';
-import {
-  PaymentClientPort,
-  type INormalizedCheckoutSession,
-  type INormalizedSubscription,
-  type INormalizedWebhookEvent,
-} from '@breadstone/archipel-platform-payments';
-@Injectable()
-export class StripePaymentClient extends PaymentClientPort {
-  public async createCheckoutSession(params: Record<string, unknown>): Promise<INormalizedCheckoutSession> {
-    // Use Stripe SDK to create a checkout session
-    // Return a normalized result
-  }
-  public async getSubscription(subscriptionId: string): Promise<INormalizedSubscription | null> {
-    // Fetch subscription details from Stripe
-    // Return normalized subscription data
-  }
-  public async handleWebhook(payload: Buffer, signature: string): Promise<INormalizedWebhookEvent> {
-    // Verify webhook signature and normalize the event
-  }
-}
-```
-The library uses **normalized models** (`INormalizedSubscription`, `INormalizedCheckoutSession`, `INormalizedWebhookEvent`) so your application code works identically regardless of the payment provider.
----
-## Feature Gating
-The `FeatureAccessPort` lets you restrict functionality based on subscription tiers.
-### Step 1: Implement the Port
-```typescript
-import { Injectable } from '@nestjs/common';
-import { FeatureAccessPort } from '@breadstone/archipel-platform-payments';
-import { PrismaService } from '@breadstone/archipel-platform-database';
-@Injectable()
-export class PrismaFeatureAccessAdapter extends FeatureAccessPort {
-  private readonly _prisma: PrismaService;
-  constructor(prisma: PrismaService) {
-    super();
-    this._prisma = prisma;
-  }
-  public async hasAccess(userId: string, feature: string): Promise<boolean> {
-    const subscription = await this._prisma.subscription.findFirst({
-      where: { userId, status: 'active' },
-      include: { plan: true },
-    });
-    if (!subscription) {
-      return false;
-    }
-    return subscription.plan.features.includes(feature);
-  }
-  public async recordUsage(userId: string, feature: string): Promise<void> {
-    await this._prisma.featureUsage.create({
-      data: { userId, feature, usedAt: new Date() },
-    });
-  }
-  public async getUsageCount(userId: string, feature: string, since: Date): Promise<number> {
-    return this._prisma.featureUsage.count({
-      where: { userId, feature, usedAt: { gte: since } },
-    });
-  }
-}
-```
-### Step 2: Use the Feature Guard
-The `FeatureGuard` decorator restricts endpoints to users with access to specific features:
-```typescript
-import { Controller, Post, UseGuards } from '@nestjs/common';
-import { JwtAuthGuard } from '@breadstone/archipel-platform-authentication';
-import { FeatureGuard } from '@breadstone/archipel-platform-payments';
-@Controller('exports')
-@UseGuards(JwtAuthGuard)
-export class ExportController {
-  @Post('pdf')
-  @FeatureGuard('export:pdf')
-  public async exportPdf(): Promise<void> {
-    // Only accessible to users with 'export:pdf' feature
-  }
-  @Post('csv')
-  @FeatureGuard('export:csv')
-  public async exportCsv(): Promise<void> {
-    // Only accessible to users with 'export:csv' feature
-  }
-}
-```
-### Step 3: Track Usage with Interceptor
-`FeatureUsageInterceptor` automatically records feature usage after a successful request:
-```typescript
-import { Controller, Post, UseGuards, UseInterceptors } from '@nestjs/common';
-import { JwtAuthGuard } from '@breadstone/archipel-platform-authentication';
-import { FeatureGuard, FeatureUsageInterceptor } from '@breadstone/archipel-platform-payments';
-@Controller('ai')
-@UseGuards(JwtAuthGuard)
-export class AiController {
-  @Post('generate')
-  @FeatureGuard('ai:generate')
-  @UseInterceptors(FeatureUsageInterceptor)
-  public async generate(): Promise<string> {
-    // Usage is recorded automatically after success
-    return 'generated content';
-  }
-}
-```
----
-## Handling Webhooks
-Payment providers send webhook events for subscription changes, payment failures, etc. Create a dedicated webhook controller:
-```typescript
-import { Controller, Post, Req, Headers, RawBodyRequest } from '@nestjs/common';
-import { PaymentClientPort } from '@breadstone/archipel-platform-payments';
-import { Request } from 'express';
-@Controller('webhooks/payments')
-export class PaymentWebhookController {
-  private readonly _paymentClient: PaymentClientPort;
-  constructor(paymentClient: PaymentClientPort) {
-    this._paymentClient = paymentClient;
-  }
-  @Post()
-  public async handleWebhook(
-    @Req() request: RawBodyRequest<Request>,
-    @Headers('stripe-signature') signature: string,
-  ): Promise<void> {
-    const event = await this._paymentClient.handleWebhook(request.rawBody!, signature);
-    switch (event.type) {
-      case 'subscription.created':
-      case 'subscription.updated':
-        // Update subscription in your database
-        break;
-      case 'subscription.deleted':
-        // Handle cancellation
-        break;
-      case 'payment.failed':
-        // Notify user, retry logic
-        break;
-    }
-  }
-}
-```
----
-## Best Practices
-1. **Define feature keys as constants.** Never use inline strings for feature identifiers.
-2. **Verify webhook signatures.** Always validate the webhook payload before processing.
-3. **Use normalized models.** Don't leak provider-specific types into your business logic.
-4. **Implement idempotent webhook handlers.** Webhooks can be delivered multiple times.
-5. **Separate feature gating from billing logic.** The `FeatureAccessPort` should only check access, not manage subscriptions.
----
-## Next Steps
-- See the [Authentication & Authorization](/guides/authentication-and-authorization) guide for securing payment endpoints
-- Browse the [platform-payments API reference](/packages/platform-payments/api/) for complete method signatures