@breadstone/archipel-mcp 0.0.15 → 0.0.16

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

@@ -0,0 +1,260 @@
+---
+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.
+
+## Error Handling
+
+Payment client methods such as `fetchPrices`, `createCheckoutSession`, and `fetchSubscription` **propagate errors** to the caller. They do not silently return empty results. Wrap calls in `try/catch` if you need fallback behavior:
+
+```typescript
+try {
+  const prices = await this._paymentClient.fetchPrices(productId);
+  return prices;
+} catch (error) {
+  this._logger.error('Failed to fetch prices', { productId, error: (error as Error).message });
+  return []; // Fallback to empty list
+}
+```
+
+All client implementations log errors with structured metadata before re-throwing.
+
+---
+
+## 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

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