@breadstone/archipel-mcp 0.0.13 → 0.0.15

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

@@ -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

package/data/guides/resource-management.md

@@ -1,352 +0,0 @@
----
-title: Resource Management
-description: Register and load files (templates, assets, configs) from disk, blob storage, or memory using the strategy-based ResourceManager.
-order: 17
----
-
-# Resource Management
-
-This guide covers working with `ResourceManager` from `platform-core`: registering file strategies, loading resources at runtime, and using the built-in caching layer. If your application ships email templates, HTML pages, CSS/JS assets, or any other file-based content, this is how you make it available to services.
-
----
-
-## Installation
-
-`ResourceManager` is part of `platform-core` — no extra package needed.
-
-```bash
-yarn add @breadstone/archipel-platform-core
-```
-
----
-
-## Overview: Strategy Pattern
-
-`ResourceManager` does not load files directly. It delegates to one or more **strategies**, tried in priority order. The first strategy that can resolve the key wins.
-
-| Strategy                   | Source             | Sync | Async | When to use                            |
-| -------------------------- | ------------------ | ---- | ----- | -------------------------------------- |
-| `FileResourceStrategy`     | Local filesystem   | Yes  | Yes   | Templates, assets bundled with the app |
-| `BlobResourceStrategy`     | Cloud blob storage | No   | Yes   | User-uploaded templates, dynamic files |
-| `EmbeddedResourceStrategy` | In-memory map      | Yes  | Yes   | Fallback content, test fixtures        |
-
-Strategies are evaluated in the order you provide them. A typical setup:
-
-```
-FileResourceStrategy → BlobResourceStrategy → EmbeddedResourceStrategy
-```
-
-If the file exists on disk, it's served immediately. If not, blob storage is checked. If that also misses, the embedded fallback is returned. If nothing matches, a `ResourceNotFoundError` is thrown.
-
----
-
-## Module Registration
-
-`ResourceModule` is a global module. Register it once in your root module with `forRoot()`:
-
-```typescript
-import { Module } from '@nestjs/common';
-import { join } from 'node:path';
-import { ResourceModule, FileResourceStrategy, EmbeddedResourceStrategy } from '@breadstone/archipel-platform-core';
-
-@Module({
-  imports: [
-    ResourceModule.forRoot({
-      strategies: [
-        new FileResourceStrategy({
-          basePaths: [
-            join(__dirname, 'assets'),
-            join(__dirname, '..', 'node_modules', '@breadstone', 'archipel-platform-core', 'assets'),
-            join(__dirname, '..', 'node_modules', '@breadstone', 'archipel-platform-openapi', 'assets'),
-            join(__dirname, '..', 'node_modules', '@breadstone', 'archipel-platform-mailing', 'assets'),
-          ],
-          includeSubfolders: true,
-        }),
-        new EmbeddedResourceStrategy({
-          'fallback.html': '<html><body>Service unavailable</body></html>',
-        }),
-      ],
-      debug: false,
-    }),
-  ],
-})
-export class AppModule {}
-```
-
-### Configuration Options
-
-| Option       | Type                                     | Default | Description                                      |
-| ------------ | ---------------------------------------- | ------- | ------------------------------------------------ |
-| `strategies` | `IResourceStrategy[]`                    | —       | Strategies in priority order. Required.          |
-| `cache`      | `ILayeredCache<string, IResourceResult>` | —       | Optional cache instance from `platform-caching`. |
-| `cacheTtl`   | `number` (seconds)                       | `3600`  | TTL for cached resources.                        |
-| `debug`      | `boolean`                                | `false` | Log all available resources on startup.          |
-
----
-
-## Loading Resources
-
-Inject `ResourceManager` and call its load methods. Every method has a `try*` variant that returns `undefined` instead of throwing.
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { ResourceManager } from '@breadstone/archipel-platform-core';
-
-@Injectable()
-export class InvoiceService {
-  private readonly _resourceManager: ResourceManager;
-
-  constructor(resourceManager: ResourceManager) {
-    this._resourceManager = resourceManager;
-  }
-
-  public async generateInvoice(): Promise<string> {
-    // Load an HTML template as string
-    const template = await this._resourceManager.loadAsStringAsync('invoice-template.html');
-
-    // ... fill template with data
-    return template;
-  }
-}
-```
-
-### Method Reference
-
-| Method                    | Returns                                 | Throws on miss | Notes                         |
-| ------------------------- | --------------------------------------- | -------------- | ----------------------------- |
-| `load(key)`               | `IResourceResult`                       | Yes            | Sync                          |
-| `tryLoad(key)`            | `IResourceResult \| undefined`          | No             | Sync                          |
-| `loadAsync(key)`          | `Promise<IResourceResult>`              | Yes            | Required for blob strategy    |
-| `tryLoadAsync(key)`       | `Promise<IResourceResult \| undefined>` | No             |                               |
-| `loadAsString(key, enc?)` | `string`                                | Yes            | Defaults to `utf-8`           |
-| `loadAsStringAsync(key)`  | `Promise<string>`                       | Yes            |                               |
-| `loadAsBuffer(key)`       | `Buffer \| undefined`                   | No             |                               |
-| `loadAsBufferAsync(key)`  | `Promise<Buffer \| undefined>`          | No             |                               |
-| `exists(key)`             | `boolean`                               | —              | Sync                          |
-| `existsAsync(key)`        | `Promise<boolean>`                      | —              |                               |
-| `invalidate(key)`         | `void`                                  | —              | Clears cache for key          |
-| `invalidateAsync(key)`    | `Promise<void>`                         | —              |                               |
-| `whatDoIHave()`           | `void`                                  | —              | Logs all resources to console |
-
-### The `IResourceResult` Object
-
-When you use the full `load()` / `tryLoad()` methods you get rich metadata alongside the content:
-
-```typescript
-interface IResourceResult {
-  content: Buffer;
-  metadata: IResourceMetadata;
-}
-
-interface IResourceMetadata {
-  key: string; // Resource identifier you requested
-  path: string; // Resolved file / blob path
-  mimeType: string; // e.g. 'text/html', 'application/pdf'
-  size: number; // Size in bytes
-  encoding?: string; // e.g. 'utf-8'
-  source: string; // Strategy name that resolved it (e.g. 'file')
-  cachedAt?: Date; // Present when served from cache
-}
-```
-
----
-
-## Strategy Details
-
-### FileResourceStrategy
-
-Searches one or more base paths on the filesystem. Each path is tried in order. If `includeSubfolders` is enabled, a recursive glob search runs as fallback when the direct lookup misses.
-
-```typescript
-new FileResourceStrategy({
-  basePaths: [join(__dirname, 'assets'), join(__dirname, 'templates')],
-  includeSubfolders: true,
-  defaultEncoding: 'utf-8',
-});
-```
-
-The key you pass to `load()` is the **filename** (e.g. `'invoice-template.html'`). The strategy joins it with each base path and checks if the file exists.
-
-### BlobResourceStrategy
-
-Loads from cloud blob storage via a minimal `IBlobServiceAdapter` interface. This is **async-only** — calling `load()` (sync) will throw.
-
-```typescript
-import { BlobResourceStrategy, IBlobServiceAdapter } from '@breadstone/archipel-platform-core';
-
-const blobAdapter: IBlobServiceAdapter = {
-  async downloadFile(key: string) {
-    // Your blob storage client logic here
-    return { data: buffer, contentType: 'text/html' };
-  },
-};
-
-new BlobResourceStrategy(blobAdapter, {
-  keyPrefix: 'templates/',
-});
-```
-
-With `keyPrefix: 'templates/'`, a call to `loadAsync('invoice.html')` resolves to the blob key `templates/invoice.html`.
-
-### EmbeddedResourceStrategy
-
-Stores resources as plain strings in memory. Useful for fallback content or test fixtures.
-
-```typescript
-new EmbeddedResourceStrategy({
-  'maintenance.html': '<h1>We are down for maintenance</h1>',
-  'default-logo.svg': '<svg>...</svg>',
-});
-```
-
-You can also register resources dynamically after construction:
-
-```typescript
-const embedded = new EmbeddedResourceStrategy();
-embedded.register('dynamic-content.txt', 'Hello World');
-```
-
----
-
-## Real-World Examples
-
-### Email Templates
-
-`platform-mailing` uses `ResourceManager` to load HTML email templates:
-
-```typescript
-// In MailModule.ts — factory creates the strategy
-ResourceModule.forRoot({
-  strategies: [
-    new FileResourceStrategy({
-      basePaths: [
-        join(__dirname, 'assets'), // App-level overrides
-        join(__dirname, '..', 'node_modules', '@breadstone', 'archipel-platform-mailing', 'assets'),
-      ],
-    }),
-  ],
-});
-```
-
-Templates like `AuthVerify.html`, `AuthRegister.html`, and `AuthForgotPassword.html` are loaded by key:
-
-```typescript
-const template = await this._resourceManager.loadAsStringAsync('AuthVerify.html');
-```
-
-By listing your own `assets/` first, you can override built-in templates without modifying the library.
-
-### Swagger UI Assets
-
-`platform-openapi` loads its theme files (`swagger.css`, `swagger.js`, `swagger.html`) through the same mechanism:
-
-```typescript
-const css = this._resourceManager.loadAsString('swagger.css');
-const js = this._resourceManager.loadAsString('swagger.js');
-```
-
-### Application Index Page
-
-`platform-core`'s `HostService` loads `index.html` as a template for the root route:
-
-```typescript
-const html = await this._resourceManager.loadAsStringAsync('index.html');
-```
-
----
-
-## Caching
-
-Pass a cache instance from `platform-caching` to avoid repeated file reads or blob downloads:
-
-```typescript
-import { LayeredCacheFactory } from '@breadstone/archipel-platform-caching';
-
-ResourceModule.forRoot({
-  strategies: [
-    new FileResourceStrategy({ basePaths: [...] }),
-  ],
-  cache: LayeredCacheFactory.create<string, IResourceResult>({
-    maxSize: 100,
-  }),
-  cacheTtl: 1800, // 30 minutes
-})
-```
-
-- On load: cache is checked first. On hit, the resource is returned immediately.
-- On miss: strategies are tried, and the result is cached for future requests.
-- Use `invalidate(key)` or `invalidateAsync(key)` to clear a cached resource (e.g. after an upload replaces a template).
-
----
-
-## Debugging
-
-Enable `debug: true` in the module config to have `ResourceManager` call `whatDoIHave()` at startup. This logs every resource available through every strategy — helpful when a resource isn't found and you need to verify the base paths.
-
-```
-[ResourceManager] ResourceManager initialized with 2 strategies: file, embedded
-[FileResourceStrategy] Available resources:
-  - index.html (text/html, 2.4 KB) → /app/dist/assets/index.html
-  - swagger.css (text/css, 1.1 KB) → /app/dist/assets/swagger.css
-  ...
-[EmbeddedResourceStrategy] Available resources:
-  - fallback.html (text/html, 52 B) → embedded
-```
-
----
-
-## Writing a Custom Strategy
-
-Implement `IResourceStrategy` to support a new source (e.g. a database, S3 directly, or a remote API):
-
-```typescript
-import { IResourceStrategy, IResourceResult } from '@breadstone/archipel-platform-core';
-
-export class DatabaseResourceStrategy implements IResourceStrategy {
-  public get name(): string {
-    return 'database';
-  }
-
-  public load(key: string): IResourceResult | undefined {
-    // Sync lookup — return undefined if not found
-  }
-
-  public async loadAsync(key: string): Promise<IResourceResult | undefined> {
-    // Async lookup — return undefined if not found
-  }
-
-  public exists(key: string): boolean {
-    // ...
-  }
-
-  public async existsAsync(key: string): Promise<boolean> {
-    // ...
-  }
-
-  public whatDoIHave(): void {
-    // Log available resources for debugging
-  }
-}
-```
-
-Then add it to the strategies array:
-
-```typescript
-ResourceModule.forRoot({
-  strategies: [
-    new FileResourceStrategy({ basePaths: [...] }),
-    new DatabaseResourceStrategy(prisma),
-  ],
-})
-```
-
----
-
-## Checklist
-
-- [ ] `ResourceModule.forRoot()` registered in the root module
-- [ ] Base paths include library asset directories for all used packages
-- [ ] App-level overrides listed **before** library paths in `basePaths`
-- [ ] Async methods used when `BlobResourceStrategy` is in the chain
-- [ ] Cache configured for production (avoids repeated disk/network reads)
-- [ ] `debug: true` used during development to verify resource availability