@breadstone/archipel-mcp 0.0.15 → 0.0.17

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/request-response-dtos.md

@@ -0,0 +1,411 @@
+---
+title: Request & Response DTOs
+description: Naming conventions, validation decorators, and class-transformer integration for request and response data transfer objects in Archipel NestJS applications.
+order: 4
+---
+
+# Request & Response DTOs
+
+This guide covers how to define, validate, and transform request and response DTOs in an Archipel-powered NestJS application. DTOs are the contract between your API and its consumers — they define what goes in and what comes out.
+
+For how controllers use DTOs together with `ResponseReturn`, see the [Controller Best Practices](/guides/controller-best-practices) guide.
+
+---
+
+## Naming Conventions
+
+DTOs follow a strict naming pattern:
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Create request | `Create{Resource}Request` | `CreateOrderRequest` |
+| Update request | `Update{Resource}Request` | `UpdateProfileRequest` |
+| Action request | `{Action}{Resource}Request` | `AuthLoginRequest`, `AuthVerifyPinRequest` |
+| Single response | `{Resource}Response` | `UserResponse`, `OrderResponse` |
+| List response | `{Resource}ListResponse` | `OrderListResponse` |
+| Action response | `{Action}{Resource}Response` | `AuthLoginResponse`, `AuthRefreshResponse` |
+| Availability / status | `{Resource}{Status}Response` | `AuthUsernameAvailabilityResponse` |
+
+### Grouping by Feature
+
+When a controller has many DTOs, prefix them with the feature name to keep imports clean:
+
+```typescript
+// Auth feature DTOs
+AuthLoginRequest
+AuthLoginResponse
+AuthRegisterRequest
+AuthRefreshResponse
+AuthChangePasswordRequest
+AuthChangeEmailRequest
+AuthForgotPasswordRequest
+AuthVerifyPinRequest
+AuthVerifyResponse
+AuthResendVerificationRequest
+AuthUsernameSuggestionsResponse
+AuthUsernameAvailabilityResponse
+AuthAvatarSuggestionResponse
+```
+
+All DTOs for a feature are exported from a `models/` barrel file:
+
+```typescript
+// models/index.ts
+export { AuthLoginRequest } from './AuthLoginRequest';
+export { AuthLoginResponse } from './AuthLoginResponse';
+export { AuthRegisterRequest } from './AuthRegisterRequest';
+// ...
+```
+
+---
+
+## File Organization
+
+**One public export per file.** Each DTO class gets its own file, named after the class.
+
+```
+src/
+  auth/
+    models/
+      AuthLoginRequest.ts
+      AuthLoginResponse.ts
+      AuthRegisterRequest.ts
+      AuthRefreshResponse.ts
+      UserResponse.ts
+      index.ts
+    AuthController.ts
+    AuthModule.ts
+```
+
+---
+
+## Request DTOs (Validation)
+
+Request DTOs are classes decorated with `class-validator` and `@ApiProperty` from `@nestjs/swagger`.
+
+### Basic Request
+
+```typescript
+import { ApiProperty } from '@nestjs/swagger';
+import { IsEmail, IsNotEmpty, IsString, MinLength } from 'class-validator';
+
+export class AuthLoginRequest {
+
+    /**
+     * The user's email address or username.
+     *
+     * @public
+     */
+    @ApiProperty({ description: 'Email address or username.' })
+    @IsNotEmpty()
+    @IsString()
+    public login!: string;
+
+    /**
+     * The user's password.
+     *
+     * @public
+     */
+    @ApiProperty({ description: 'Account password.' })
+    @IsNotEmpty()
+    @IsString()
+    @MinLength(8)
+    public password!: string;
+
+}
+```
+
+### Request with Optional Fields
+
+```typescript
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsEmail, IsNotEmpty, IsOptional, IsString, ValidateNested } from 'class-validator';
+import { Type } from 'class-transformer';
+
+export class AuthRegisterRequest {
+
+    @ApiProperty({ description: 'Email address for the new account.' })
+    @IsNotEmpty()
+    @IsEmail()
+    public email!: string;
+
+    @ApiProperty({ description: 'Password for the new account.', minLength: 8 })
+    @IsNotEmpty()
+    @IsString()
+    @MinLength(8)
+    public password!: string;
+
+    @ApiProperty({ description: 'Account type.', example: 'personal' })
+    @IsNotEmpty()
+    @IsString()
+    public type!: string;
+
+    @ApiPropertyOptional({ description: 'Optional profile information.' })
+    @IsOptional()
+    @ValidateNested()
+    @Type(() => ProfilePayload)
+    public profile?: ProfilePayload;
+
+}
+```
+
+### Nested Payloads
+
+When a request contains nested objects, define them as separate classes with `@ValidateNested()` and `@Type()`:
+
+```typescript
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { IsOptional, IsString } from 'class-validator';
+
+export class ProfilePayload {
+
+    @ApiPropertyOptional()
+    @IsOptional()
+    @IsString()
+    public avatar?: string;
+
+    @ApiPropertyOptional()
+    @IsOptional()
+    @IsString()
+    public firstName?: string;
+
+    @ApiPropertyOptional()
+    @IsOptional()
+    @IsString()
+    public lastName?: string;
+
+    @ApiPropertyOptional()
+    @IsOptional()
+    @IsString()
+    public userName?: string;
+
+}
+```
+
+---
+
+## Response DTOs (Transformation)
+
+Response DTOs use `@ApiProperty` for documentation and `@Expose()` from `class-transformer` for serialization control.
+
+### Basic Response
+
+```typescript
+import { ApiProperty } from '@nestjs/swagger';
+import { Expose } from 'class-transformer';
+
+export class AuthLoginResponse {
+
+    @ApiProperty({ description: 'JWT access token.' })
+    @Expose()
+    public accessToken!: string;
+
+    @ApiProperty({ description: 'Whether multi-factor authentication is required.' })
+    @Expose()
+    public mfaRequired!: boolean;
+
+}
+```
+
+### Response with Optional Fields
+
+```typescript
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Expose } from 'class-transformer';
+
+export class AuthLoginResponse {
+
+    @ApiProperty({ description: 'JWT access token.' })
+    @Expose()
+    public accessToken!: string;
+
+    @ApiProperty({ description: 'Whether MFA is required.' })
+    @Expose()
+    public mfaRequired!: boolean;
+
+    @ApiProperty({ description: 'Whether email verification is required.' })
+    @Expose()
+    public verificationRequired!: boolean;
+
+    @ApiPropertyOptional({ description: 'MFA challenge identifier.' })
+    @Expose()
+    public challengeId?: string;
+
+    @ApiPropertyOptional({ description: 'Available MFA methods.', type: [String] })
+    @Expose()
+    public methods?: Array<string>;
+
+    @ApiPropertyOptional({ description: 'Preferred MFA method.' })
+    @Expose()
+    public preferredMethod?: string;
+
+}
+```
+
+### User / Entity Response
+
+```typescript
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Expose } from 'class-transformer';
+
+export class UserResponse {
+
+    @ApiProperty({ description: 'Unique user identifier.' })
+    @Expose()
+    public id!: string;
+
+    @ApiProperty({ description: 'Email address.' })
+    @Expose()
+    public email!: string;
+
+    @ApiPropertyOptional({ description: 'Display username.' })
+    @Expose()
+    public userName?: string;
+
+    @ApiPropertyOptional({ description: 'First name.' })
+    @Expose()
+    public firstName?: string;
+
+    @ApiPropertyOptional({ description: 'Last name.' })
+    @Expose()
+    public lastName?: string;
+
+    @ApiPropertyOptional({ description: 'Avatar URL or base64 image.' })
+    @Expose()
+    public avatar?: string;
+
+    @ApiProperty({ description: 'Whether the email is verified.' })
+    @Expose()
+    public isVerified!: boolean;
+
+}
+```
+
+---
+
+## How ResponseReturn Uses DTOs
+
+When a controller calls `ResponseReturn.ok(AuthLoginResponse, data)`, the response pipeline:
+
+1. Instantiates `AuthLoginResponse` via `class-transformer`'s `plainToInstance()`
+2. Applies `@Expose()` / `@Exclude()` rules — only explicitly exposed fields appear in the output
+3. Wraps the result in the standard envelope: `{ success, status, data, timestamp }`
+
+This means the DTO class **controls what the client sees**. Even if the service returns extra fields, they won't leak unless the DTO exposes them.
+
+```typescript
+// Service returns: { id, email, password, internalFlag, ... }
+// DTO only exposes: { id, email, userName }
+// Client receives:  { success: true, status: 200, data: { id, email, userName }, timestamp: ... }
+```
+
+---
+
+## Validation Pipeline
+
+Archipel applications use a global `ValidationPipe` with strict settings:
+
+```typescript
+app.useGlobalPipes(new ValidationPipe({
+    whitelist: true,           // Strip properties not in the DTO
+    forbidNonWhitelisted: true, // Throw if unknown properties are sent
+    transform: true,            // Auto-transform payloads to DTO instances
+}));
+```
+
+This means:
+- Properties without decorators are **silently removed** (`whitelist`)
+- Unknown properties cause a **400 Bad Request** (`forbidNonWhitelisted`)
+- Request bodies are automatically transformed to class instances (`transform`)
+
+---
+
+## Cross-Field Validation
+
+When fields depend on each other (e.g., either `email` or `phone` is required, but not both), implement a custom class-level validator:
+
+```typescript
+import { ValidatorConstraint, ValidatorConstraintInterface, Validate, ValidationArguments } from 'class-validator';
+
+@ValidatorConstraint({ name: 'eitherEmailOrPhone', async: false })
+export class EitherEmailOrPhoneConstraint implements ValidatorConstraintInterface {
+
+    public validate(_: unknown, args: ValidationArguments): boolean {
+        const obj = args.object as { email?: string; phone?: string };
+        return Boolean(obj.email) !== Boolean(obj.phone);
+    }
+
+    public defaultMessage(): string {
+        return 'Exactly one of email or phone must be provided.';
+    }
+
+}
+
+@Validate(EitherEmailOrPhoneConstraint)
+export class ContactRequest {
+
+    @ApiPropertyOptional()
+    @IsOptional()
+    @IsEmail()
+    public email?: string;
+
+    @ApiPropertyOptional()
+    @IsOptional()
+    @IsString()
+    public phone?: string;
+
+}
+```
+
+**Never** do cross-field validation in controllers or services — always use class-level validators so it's reusable and testable.
+
+---
+
+## Constants for Limits
+
+Define and reuse constants for bounds that appear in validation and pagination:
+
+```typescript
+// constants.ts
+export const MAX_PAGE_SIZE = 100;
+export const MAX_SEARCH_LIMIT = 50;
+export const DEFAULT_PAGE_SIZE = 20;
+```
+
+```typescript
+import { Max, Min, IsOptional, IsInt } from 'class-validator';
+import { MAX_PAGE_SIZE, DEFAULT_PAGE_SIZE } from '../constants';
+
+export class PaginationQuery {
+
+    @ApiPropertyOptional({ default: DEFAULT_PAGE_SIZE, maximum: MAX_PAGE_SIZE })
+    @IsOptional()
+    @IsInt()
+    @Min(1)
+    @Max(MAX_PAGE_SIZE)
+    public limit?: number = DEFAULT_PAGE_SIZE;
+
+    @ApiPropertyOptional({ default: 0 })
+    @IsOptional()
+    @IsInt()
+    @Min(0)
+    public offset?: number = 0;
+
+}
+```
+
+---
+
+## Checklist
+
+Before submitting DTOs, verify:
+
+- [ ] One DTO class per file, named after the class
+- [ ] Request DTOs have `class-validator` decorators on every property
+- [ ] Response DTOs have `@Expose()` on every public property
+- [ ] Nested objects use `@ValidateNested()` + `@Type()`
+- [ ] All properties have `@ApiProperty` or `@ApiPropertyOptional`
+- [ ] No `any` types — use `unknown` or specific types
+- [ ] Cross-field validation uses class-level validators, not imperative checks
+- [ ] Pagination limits use shared constants with `@Max()`
+- [ ] DTOs exported from a `models/index.ts` barrel