@breadstone/archipel-mcp 0.0.9 → 0.0.11

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

@@ -0,0 +1,266 @@
+---
+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

@@ -0,0 +1,244 @@
+---
+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