@breadstone/archipel-mcp 0.0.1

package/data/packages/platform-openapi/index.md

@@ -0,0 +1,170 @@
+---
+title: platform-openapi
+description: Multi-tenant Swagger/OpenAPI documentation with feature-scoped discovery.
+order: 8
+tags: [openapi, swagger, documentation, api, multi-tenant]
+package: '@breadstone/archipel-platform-openapi'
+---
+
+# platform-openapi
+
+Multi-tenant Swagger/OpenAPI documentation system with feature-scoped discovery, customizable themes, and automatic endpoint registration.
+
+**Package:** `@breadstone/archipel-platform-openapi`
+
+## Quick Start
+
+```typescript
+import { Module } from '@nestjs/common';
+import { SwaggerFeature, Api } from '@breadstone/archipel-platform-openapi';
+
+@SwaggerFeature({
+  name: 'User Management',
+  description: 'User CRUD and profile operations',
+  version: '1.0',
+})
+@Controller('api/v1/users')
+export class UserController {
+  @Api({
+    summary: 'Get user by ID',
+    responses: { 200: { description: 'User found' } },
+  })
+  @Get(':id')
+  public async getUser(@Param('id') id: string): Promise<UserResponse> {
+    // ...
+  }
+}
+```
+
+---
+
+## Feature-Scoped Documentation
+
+The key concept is **per-feature Swagger documents** — each feature or module gets its own Swagger UI page, so teams can work independently without cluttering a single monolithic spec.
+
+### @SwaggerFeature Decorator
+
+Associates a controller with a named feature group:
+
+```typescript
+import { SwaggerFeature } from '@breadstone/archipel-platform-openapi';
+
+@SwaggerFeature({
+  name: 'Orders',
+  description: 'Order management and fulfillment',
+  version: '2.0',
+  tags: ['orders', 'fulfillment'],
+})
+@Controller('api/v1/orders')
+export class OrderController {
+  /* ... */
+}
+```
+
+### @Api Decorator
+
+Enriches individual endpoints with OpenAPI metadata:
+
+```typescript
+import { Api } from '@breadstone/archipel-platform-openapi';
+
+@Api({
+    summary: 'Create a new order',
+    description: 'Creates an order and initiates payment processing.',
+    responses: {
+        201: { description: 'Order created successfully' },
+        400: { description: 'Invalid order data' },
+        402: { description: 'Payment required' },
+    },
+})
+@Post()
+public async createOrder(@Body() body: CreateOrderDto): Promise<OrderResponse> { /* ... */ }
+```
+
+---
+
+## Multi-Document Service
+
+Generate separate Swagger documents per feature:
+
+```typescript
+import { SwaggerMultiDocumentService } from '@breadstone/archipel-platform-openapi';
+
+@Injectable()
+export class DocsController {
+  constructor(private readonly _swaggerDocs: SwaggerMultiDocumentService) {}
+
+  public generateAll(): Map<string, OpenAPIObject> {
+    return this._swaggerDocs.generateAll();
+    // Returns a map: 'User Management' → OpenAPI spec, 'Orders' → OpenAPI spec, ...
+  }
+}
+```
+
+### Bootstrap Setup
+
+```typescript
+import { SwaggerModule } from '@nestjs/swagger';
+import { SwaggerMultiDocumentService, SwaggerTheme } from '@breadstone/archipel-platform-openapi';
+
+async function bootstrap(): Promise<void> {
+  const app = await NestFactory.create(AppModule);
+  const docsService = app.get(SwaggerMultiDocumentService);
+  const documents = docsService.generateAll();
+
+  for (const [featureName, spec] of documents) {
+    const path = `docs/${featureName.toLowerCase().replace(/\s+/g, '-')}`;
+    SwaggerModule.setup(path, app, spec, {
+      customCss: SwaggerTheme.getDefaultCss(),
+    });
+  }
+
+  await app.listen(3000);
+}
+```
+
+---
+
+## Discovery & Registry
+
+### SwaggerFeatureDiscovery
+
+Auto-discovers all `@SwaggerFeature` decorated controllers at bootstrap:
+
+```typescript
+import { SwaggerFeatureDiscovery } from '@breadstone/archipel-platform-openapi';
+
+const discovery = app.get(SwaggerFeatureDiscovery);
+const features = discovery.discoverAll();
+// → [{ name: 'User Management', controllers: [...] }, ...]
+```
+
+### SwaggerFeatureRegistry
+
+Programmatic registry for feature configurations:
+
+```typescript
+import { SwaggerFeatureRegistry } from '@breadstone/archipel-platform-openapi';
+
+const registry = app.get(SwaggerFeatureRegistry);
+registry.register({
+  name: 'Admin',
+  description: 'Admin-only endpoints',
+  version: '1.0',
+  controllers: [AdminController],
+});
+```
+
+---
+
+## Exports Summary
+
+| Export                        | Type      | Description                     |
+| ----------------------------- | --------- | ------------------------------- |
+| `Api`                         | Decorator | OpenAPI endpoint metadata       |
+| `SwaggerFeature`              | Decorator | Feature-scoped Swagger grouping |
+| `SwaggerFeatureDiscovery`     | Service   | Auto-discover features          |
+| `SwaggerFeatureRegistry`      | Service   | Manage feature configs          |
+| `SwaggerMultiDocumentService` | Service   | Generate per-feature specs      |
+| `SwaggerTheme`                | Utility   | Theme customization             |
+| `IFeatureSwaggerConfig`       | Interface | Feature config shape            |

package/data/packages/platform-payments/api/Class.FeatureAccessPort.md

@@ -0,0 +1,79 @@
+---
+title: 'Abstract Class: FeatureAccessPort'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-payments**](../)
+
+---
+
+# Abstract Class: FeatureAccessPort
+
+Defined in: [contracts/FeatureAccessPort.ts:14](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-payments/src/contracts/FeatureAccessPort.ts#L14)
+
+Abstract port for checking and recording feature usage.
+Consuming projects must provide a concrete implementation (e.g. backed by Prisma
+with subscription + usage tables) and register it via `PaymentModule.register()`.
+
+## Constructors
+
+### Constructor
+
+```ts
+new FeatureAccessPort(): FeatureAccessPort;
+```
+
+#### Returns
+
+`FeatureAccessPort`
+
+## Methods
+
+### checkAccess()
+
+```ts
+abstract checkAccess(userId, featureKey): Promise<IFeatureAccessResult>;
+```
+
+Defined in: [contracts/FeatureAccessPort.ts:26](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-payments/src/contracts/FeatureAccessPort.ts#L26)
+
+Checks whether a user is allowed to use the specified feature
+without incrementing usage.
+
+#### Parameters
+
+| Parameter    | Type     | Description               |
+| ------------ | -------- | ------------------------- |
+| `userId`     | `string` | The user identifier.      |
+| `featureKey` | `string` | The feature key to check. |
+
+#### Returns
+
+`Promise`\<[`IFeatureAccessResult`](Interface.IFeatureAccessResult)\>
+
+The access check result including quota information.
+
+---
+
+### recordUsage()
+
+```ts
+abstract recordUsage(userId, featureKey): Promise<void>;
+```
+
+Defined in: [contracts/FeatureAccessPort.ts:36](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-payments/src/contracts/FeatureAccessPort.ts#L36)
+
+Records one unit of feature usage. Implementations should
+throw if the quota has been exceeded.
+
+#### Parameters
+
+| Parameter    | Type     | Description                          |
+| ------------ | -------- | ------------------------------------ |
+| `userId`     | `string` | The user identifier.                 |
+| `featureKey` | `string` | The feature key to record usage for. |
+
+#### Returns
+
+`Promise`\<`void`\>

package/data/packages/platform-payments/api/Class.FeatureGuard.md

@@ -0,0 +1,73 @@
+---
+title: 'Class: FeatureGuard'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-payments**](../)
+
+---
+
+# Class: FeatureGuard
+
+Defined in: [guards/FeatureGuard.ts:26](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-payments/src/guards/FeatureGuard.ts#L26)
+
+Guard that checks if the user has access to a specific feature
+by delegating to the registered [FeatureAccessPort](Class.FeatureAccessPort).
+
+## Implements
+
+- `CanActivate`
+
+## Constructors
+
+### Constructor
+
+```ts
+new FeatureGuard(featureAccessPort, reflector): FeatureGuard;
+```
+
+Defined in: [guards/FeatureGuard.ts:43](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-payments/src/guards/FeatureGuard.ts#L43)
+
+Constructs a new instance of the `FeatureGuard` class.
+
+#### Parameters
+
+| Parameter           | Type                                           | Description              |
+| ------------------- | ---------------------------------------------- | ------------------------ |
+| `featureAccessPort` | [`FeatureAccessPort`](Class.FeatureAccessPort) | The feature access port. |
+| `reflector`         | `Reflector`                                    | The NestJS reflector.    |
+
+#### Returns
+
+`FeatureGuard`
+
+## Methods
+
+### canActivate()
+
+```ts
+canActivate(context): Promise<boolean>;
+```
+
+Defined in: [guards/FeatureGuard.ts:59](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-payments/src/guards/FeatureGuard.ts#L59)
+
+Determines whether the current user has access to the guarded feature.
+
+#### Parameters
+
+| Parameter | Type               | Description            |
+| --------- | ------------------ | ---------------------- |
+| `context` | `ExecutionContext` | The execution context. |
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+`true` when the user is allowed to proceed.
+
+#### Implementation of
+
+```ts
+CanActivate.canActivate;
+```

package/data/packages/platform-payments/api/Class.FeatureUsageInterceptor.md

@@ -0,0 +1,74 @@
+---
+title: 'Class: FeatureUsageInterceptor'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-payments**](../)
+
+---
+
+# Class: FeatureUsageInterceptor
+
+Defined in: [interceptors/FeatureUsageInterceptor.ts:19](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-payments/src/interceptors/FeatureUsageInterceptor.ts#L19)
+
+Interceptor that records feature usage after successful request handling.
+Delegates recording to the registered [FeatureAccessPort](Class.FeatureAccessPort).
+
+## Implements
+
+- `NestInterceptor`
+
+## Constructors
+
+### Constructor
+
+```ts
+new FeatureUsageInterceptor(featureAccessPort, reflector): FeatureUsageInterceptor;
+```
+
+Defined in: [interceptors/FeatureUsageInterceptor.ts:36](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-payments/src/interceptors/FeatureUsageInterceptor.ts#L36)
+
+Constructs a new instance of the `FeatureUsageInterceptor` class.
+
+#### Parameters
+
+| Parameter           | Type                                           | Description              |
+| ------------------- | ---------------------------------------------- | ------------------------ |
+| `featureAccessPort` | [`FeatureAccessPort`](Class.FeatureAccessPort) | The feature access port. |
+| `reflector`         | `Reflector`                                    | The NestJS reflector.    |
+
+#### Returns
+
+`FeatureUsageInterceptor`
+
+## Methods
+
+### intercept()
+
+```ts
+intercept(context, next): Observable<unknown>;
+```
+
+Defined in: [interceptors/FeatureUsageInterceptor.ts:53](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-payments/src/interceptors/FeatureUsageInterceptor.ts#L53)
+
+Records feature usage after the request handler completes successfully.
+
+#### Parameters
+
+| Parameter | Type               | Description            |
+| --------- | ------------------ | ---------------------- |
+| `context` | `ExecutionContext` | The execution context. |
+| `next`    | `CallHandler`      | The call handler.      |
+
+#### Returns
+
+`Observable`\<`unknown`\>
+
+The observable response stream.
+
+#### Implementation of
+
+```ts
+NestInterceptor.intercept;
+```

package/data/packages/platform-payments/api/Class.LemonSqueezyClient.md

@@ -0,0 +1,168 @@
+---
+title: 'Class: LemonSqueezyClient'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-payments**](../)
+
+---
+
+# Class: LemonSqueezyClient
+
+Defined in: [lemonsqueezy/LemonSqueezyClient.ts:29](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-payments/src/lemonsqueezy/LemonSqueezyClient.ts#L29)
+
+LemonSqueezy implementation of the [PaymentClientPort](Class.PaymentClientPort).
+Uses the official `@lemonsqueezy/lemonsqueezy.js` SDK.
+
+## Extends
+
+- [`PaymentClientPort`](Class.PaymentClientPort)
+
+## Constructors
+
+### Constructor
+
+```ts
+new LemonSqueezyClient(configService): LemonSqueezyClient;
+```
+
+Defined in: [lemonsqueezy/LemonSqueezyClient.ts:39](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-payments/src/lemonsqueezy/LemonSqueezyClient.ts#L39)
+
+#### Parameters
+
+| Parameter       | Type            |
+| --------------- | --------------- |
+| `configService` | `ConfigService` |
+
+#### Returns
+
+`LemonSqueezyClient`
+
+#### Overrides
+
+[`PaymentClientPort`](Class.PaymentClientPort).[`constructor`](Class.PaymentClientPort#constructor)
+
+## Methods
+
+### constructWebhookEvent()
+
+```ts
+constructWebhookEvent(payload, signature): INormalizedWebhookEvent;
+```
+
+Defined in: [lemonsqueezy/LemonSqueezyClient.ts:142](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-payments/src/lemonsqueezy/LemonSqueezyClient.ts#L142)
+
+Construct and normalize a webhook event from raw payload.
+
+#### Parameters
+
+| Parameter   | Type                                      | Description               |
+| ----------- | ----------------------------------------- | ------------------------- |
+| `payload`   | `string` \| `Buffer`\<`ArrayBufferLike`\> | Raw webhook body.         |
+| `signature` | `string`                                  | Webhook signature header. |
+
+#### Returns
+
+[`INormalizedWebhookEvent`](Interface.INormalizedWebhookEvent)
+
+Normalized webhook event.
+
+#### Overrides
+
+[`PaymentClientPort`](Class.PaymentClientPort).[`constructWebhookEvent`](Class.PaymentClientPort#constructwebhookevent)
+
+---
+
+### createCheckoutSession()
+
+```ts
+createCheckoutSession(
+   priceId,
+   successUrl,
+   _cancelUrl,
+userId?): Promise<INormalizedCheckoutSession>;
+```
+
+Defined in: [lemonsqueezy/LemonSqueezyClient.ts:77](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-payments/src/lemonsqueezy/LemonSqueezyClient.ts#L77)
+
+Create a checkout session.
+
+#### Parameters
+
+| Parameter    | Type     | Description              |
+| ------------ | -------- | ------------------------ |
+| `priceId`    | `string` | Price identifier.        |
+| `successUrl` | `string` | Success redirect URL.    |
+| `_cancelUrl` | `string` | Cancel redirect URL.     |
+| `userId?`    | `string` | Optional user reference. |
+
+#### Returns
+
+`Promise`\<[`INormalizedCheckoutSession`](Interface.INormalizedCheckoutSession)\>
+
+Normalized checkout session.
+
+#### Overrides
+
+[`PaymentClientPort`](Class.PaymentClientPort).[`createCheckoutSession`](Class.PaymentClientPort#createcheckoutsession)
+
+---
+
+### fetchPrices()
+
+```ts
+fetchPrices(productId): Promise<INormalizedPrice[]>;
+```
+
+Defined in: [lemonsqueezy/LemonSqueezyClient.ts:55](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-payments/src/lemonsqueezy/LemonSqueezyClient.ts#L55)
+
+Fetch all active prices for a product.
+
+#### Parameters
+
+| Parameter   | Type     | Description                  |
+| ----------- | -------- | ---------------------------- |
+| `productId` | `string` | External product identifier. |
+
+#### Returns
+
+`Promise`\<[`INormalizedPrice`](Interface.INormalizedPrice)[]\>
+
+Array of normalized prices.
+
+#### Overrides
+
+[`PaymentClientPort`](Class.PaymentClientPort).[`fetchPrices`](Class.PaymentClientPort#fetchprices)
+
+---
+
+### fetchSubscription()
+
+```ts
+fetchSubscription(subscriptionId): Promise<
+  | INormalizedSubscription
+| null>;
+```
+
+Defined in: [lemonsqueezy/LemonSqueezyClient.ts:123](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-payments/src/lemonsqueezy/LemonSqueezyClient.ts#L123)
+
+Retrieve subscription details.
+
+#### Parameters
+
+| Parameter        | Type     | Description              |
+| ---------------- | -------- | ------------------------ |
+| `subscriptionId` | `string` | Subscription identifier. |
+
+#### Returns
+
+`Promise`\<
+\| [`INormalizedSubscription`](Interface.INormalizedSubscription)
+\| `null`\>
+
+Normalized subscription or `null` if not found.
+
+#### Overrides
+
+[`PaymentClientPort`](Class.PaymentClientPort).[`fetchSubscription`](Class.PaymentClientPort#fetchsubscription)