@breadstone/archipel-mcp 0.0.41 → 0.0.42

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

@@ -314,15 +314,30 @@ type SubscriptionStatus =
 
 ## FeatureAccessPort
 
-Abstract port for checking feature quotas and recording usage. This enables feature-gating with any billing system.
+Abstract port for checking feature quotas and recording usage. This enables feature-gating with any billing system and optional request-scoped tenancy context.
 
 ```typescript
 abstract class FeatureAccessPort {
-  abstract checkAccess(userId: string, featureKey: string): Promise<IFeatureAccessResult>;
-  abstract recordUsage(userId: string, featureKey: string): Promise<void>;
+  abstract checkAccess(
+    userId: string,
+    featureKey: string,
+    context?: IFeatureAccessContext,
+  ): Promise<IFeatureAccessResult>;
+
+  abstract recordUsage(userId: string, featureKey: string, context?: IFeatureAccessContext): Promise<void>;
 }
 ```
 
+`FeatureGuard` and `FeatureUsageInterceptor` create `IFeatureAccessContext` from the authenticated request subject. The guard resolves `request.user.id`, converts numeric ids to strings, forwards `request.user.tenantId` when present, and includes the original subject for adapters that need additional claims.
+
+### IFeatureAccessContext
+
+| Field      | Type                 | Description                                                |
+| ---------- | -------------------- | ---------------------------------------------------------- |
+| `userId`   | `string`             | Authenticated user identifier resolved from `request.user` |
+| `tenantId` | `string \| number`   | Optional tenant identifier from the authenticated subject   |
+| `subject`  | `unknown`            | Original authenticated subject from the request             |
+
 ### IFeatureAccessResult
 
 | Field       | Type      | Description                              |
@@ -345,9 +360,13 @@ export class PrismaFeatureAccessAdapter extends FeatureAccessPort {
     this._prisma = prisma;
   }
 
-  public async checkAccess(userId: string, featureKey: string): Promise<IFeatureAccessResult> {
+  public async checkAccess(
+    userId: string,
+    featureKey: string,
+    context?: IFeatureAccessContext,
+  ): Promise<IFeatureAccessResult> {
     const subscription = await this._prisma.subscription.findFirst({
-      where: { userId, status: 'active' },
+      where: { userId, tenantId: context?.tenantId, status: 'active' },
       include: { plan: { include: { features: true } } },
     });
 
@@ -360,6 +379,7 @@ export class PrismaFeatureAccessAdapter extends FeatureAccessPort {
     const usage = await this._prisma.featureUsage.count({
       where: {
         userId,
+        tenantId: context?.tenantId,
         featureKey,
         createdAt: { gte: periodStart },
       },
@@ -377,14 +397,14 @@ export class PrismaFeatureAccessAdapter extends FeatureAccessPort {
     };
   }
 
-  public async recordUsage(userId: string, featureKey: string): Promise<void> {
-    const access = await this.checkAccess(userId, featureKey);
+  public async recordUsage(userId: string, featureKey: string, context?: IFeatureAccessContext): Promise<void> {
+    const access = await this.checkAccess(userId, featureKey, context);
     if (!access.allowed) {
       throw new Error(`Feature quota exceeded for ${featureKey}`);
     }
 
     await this._prisma.featureUsage.create({
-      data: { userId, featureKey },
+      data: { userId, tenantId: context?.tenantId, featureKey },
     });
   }
 
@@ -417,7 +437,7 @@ export class RecipeController {
 
 ### FeatureGuard
 
-Checks the `@RequiresFeature` metadata against `FeatureAccessPort.checkAccess()`. Apply it globally or per-controller:
+Checks the `@RequiresFeature` metadata against `FeatureAccessPort.checkAccess()`. Metadata is resolved from route handlers first and controller classes second. Apply the guard globally or per-controller:
 
 ```typescript
 // Global registration
@@ -431,7 +451,7 @@ export class RecipeController {
 }
 ```
 
-The guard attaches the `IFeatureAccessResult` to the request as `request.featureAccess`, enabling downstream access to quota information.
+The guard passes `IFeatureAccessContext` into the access port and attaches the `IFeatureAccessResult` to the request as `request.featureAccess`, enabling downstream access to quota information.
 
 ### FeatureUsageInterceptor
 
@@ -446,7 +466,7 @@ export class RecipeController {
   @RequiresFeature('RECIPE_CREATION')
   public async createRecipe(@Body() body: CreateRecipeDto): Promise<RecipeResponse> {
     // After successful response, FeatureUsageInterceptor calls
-    // FeatureAccessPort.recordUsage(userId, 'RECIPE_CREATION')
+    // FeatureAccessPort.recordUsage(userId, 'RECIPE_CREATION', context)
   }
 }
 ```
@@ -514,7 +534,7 @@ All payment clients throw a `PaymentError` when provider operations fail (checko
 import { PaymentError } from '@breadstone/archipel-platform-payments';
 
 try {
-  await this._paymentClient.createCheckoutSession(params);
+  await this._paymentClient.createCheckoutSession(priceId, successUrl, cancelUrl, userId);
 } catch (error) {
   if (error instanceof PaymentError) {
     logger.error('Payment operation failed', {
@@ -566,6 +586,7 @@ export class AppModule {}
 | `PaymentModule`              | NestJS Module | Main module with `register()`       |
 | `PaymentClientPort`          | Abstract Port | Provider-agnostic payment contract  |
 | `FeatureAccessPort`          | Abstract Port | Feature quota checking              |
+| `IFeatureAccessContext`      | Interface     | Request-scoped access context       |
 | `IFeatureAccessResult`       | Interface     | Quota check result                  |
 | `FeatureGuard`               | Guard         | Enforces `@RequiresFeature`         |
 | `FeatureUsageInterceptor`    | Interceptor   | Records feature usage               |

package/data/patterns/guard-pattern.md

@@ -53,6 +53,7 @@ export const RequiresFeature = (featureKey: string) =>
 import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
 import { FeatureAccessPort } from '../contracts/FeatureAccessPort';
+import type { IFeatureAccessContext } from '../contracts/IFeatureAccessContext';
 
 @Injectable()
 export class FeatureGuard implements CanActivate {
@@ -76,7 +77,10 @@ export class FeatureGuard implements CanActivate {
   // #region Methods
 
   public async canActivate(context: ExecutionContext): Promise<boolean> {
-    const featureKey = this._reflector.get<string>(FEATURE_KEY_METADATA, context.getHandler());
+    const featureKey = this._reflector.getAllAndOverride<string | undefined>(FEATURE_KEY_METADATA, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
 
     if (!featureKey) {
       return true; // No feature requirement on this endpoint
@@ -84,12 +88,18 @@ export class FeatureGuard implements CanActivate {
 
     const request = context.switchToHttp().getRequest();
     const user = request.user;
+    const userId = typeof user?.id === 'number' ? String(user.id) : user?.id;
 
-    if (!user || !user.id) {
+    if (!userId) {
       return false;
     }
 
-    const access = await this._featureAccessPort.checkAccess(user.id, featureKey);
+    const accessContext: IFeatureAccessContext = {
+      userId,
+      tenantId: user?.tenantId,
+      subject: user,
+    };
+    const access = await this._featureAccessPort.checkAccess(userId, featureKey, accessContext);
     request.featureAccess = access; // Attach for downstream use
 
     return access.allowed;
@@ -130,7 +140,10 @@ export class FeatureUsageInterceptor implements NestInterceptor {
   // #region Methods
 
   public intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
-    const featureKey = this._reflector.get<string>(FEATURE_KEY_METADATA, context.getHandler());
+    const featureKey = this._reflector.getAllAndOverride<string | undefined>(FEATURE_KEY_METADATA, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
 
     if (!featureKey) {
       return next.handle();
@@ -138,11 +151,17 @@ export class FeatureUsageInterceptor implements NestInterceptor {
 
     const request = context.switchToHttp().getRequest();
     const user = request.user;
+    const userId = typeof user?.id === 'number' ? String(user.id) : user?.id;
 
     return next.handle().pipe(
       tap(async () => {
-        if (user && user.id) {
-          await this._featureAccessPort.recordUsage(user.id, featureKey);
+        if (userId) {
+          const accessContext: IFeatureAccessContext = {
+            userId,
+            tenantId: user?.tenantId,
+            subject: user,
+          };
+          await this._featureAccessPort.recordUsage(userId, featureKey, accessContext);
         }
       }),
     );
@@ -153,6 +172,8 @@ export class FeatureUsageInterceptor implements NestInterceptor {
 }
 ```
 
+The context object lets adapters evaluate tenant-specific plans or inspect claims from the authenticated subject without pushing billing concerns into controllers.
+
 ### Step 4: Controller Usage
 
 ```typescript

package/data/patterns/module-pattern.md

@@ -24,9 +24,13 @@ full customization through dependency injection.
 
 export abstract class FeatureAccessPort {
 
-  public abstract checkAccess(userId: string, featureKey: string): Promise<IFeatureAccessResult>;
+  public abstract checkAccess(
+    userId: string,
+    featureKey: string,
+    context?: IFeatureAccessContext,
+  ): Promise<IFeatureAccessResult>;
 
-  public abstract recordUsage(userId: string, featureKey: string): Promise<void>;
+  public abstract recordUsage(userId: string, featureKey: string, context?: IFeatureAccessContext): Promise<void>;
 
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breadstone/archipel-mcp",
-  "version": "0.0.41",
+  "version": "0.0.42",
   "description": "MCP server providing Archipel platform knowledge - documentation, query patterns, and coding conventions - to AI development tools.",
   "type": "commonjs",
   "main": "./src/main.js",

package/data/packages/platform-bootstrap/api/Function.useExpressServer.md

@@ -1,32 +0,0 @@
----
-title: 'Function: useExpressServer()'
-generated: true
-editUrl: false
----
-# Function: useExpressServer()
-
-```ts
-function useExpressServer<TApplication>(options?): PlatformBootstrapStep<TApplication>;
-```
-
-Defined in: server/express/useExpressServer.ts:14
-
-Creates an Express-compatible server bootstrap step.
-
-## Type Parameters
-
-| Type Parameter | Default type |
-| ------ | ------ |
-| `TApplication` *extends* `INestApplication`\<`any`\> | `INestApplication`\<`any`\> |
-
-## Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `options?` | [`IExpressServerStepOptions`](Interface.IExpressServerStepOptions) | Express server options. |
-
-## Returns
-
-[`PlatformBootstrapStep`](TypeAlias.PlatformBootstrapStep)\<`TApplication`\>
-
-A platform bootstrap step.

package/data/packages/platform-bootstrap/api/Interface.IExpressServerStepOptions.md

@@ -1,46 +0,0 @@
----
-title: 'Interface: IExpressServerStepOptions'
-generated: true
-editUrl: false
----
-# Interface: IExpressServerStepOptions
-
-Defined in: server/express/IExpressServerStepOptions.ts:9
-
-Options for the Express-compatible server bootstrap step.
-
-## Properties
-
-### compression?
-
-```ts
-readonly optional compression?: boolean | CompressionOptions;
-```
-
-Defined in: server/express/IExpressServerStepOptions.ts:17
-
-Compression middleware options, or `false` to skip compression.
-
-***
-
-### json?
-
-```ts
-readonly optional json?: boolean | OptionsJson;
-```
-
-Defined in: server/express/IExpressServerStepOptions.ts:11
-
-JSON body parser options, or `false` to skip JSON body parsing.
-
-***
-
-### urlEncoded?
-
-```ts
-readonly optional urlEncoded?: boolean | OptionsUrlencoded;
-```
-
-Defined in: server/express/IExpressServerStepOptions.ts:14
-
-URL-encoded body parser options, or `false` to skip URL-encoded body parsing.