@breadstone/archipel-mcp 0.0.40 → 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.40",
+  "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-blob-storage/api/Class.AwsS3BlobProvider.md

@@ -1,196 +0,0 @@
----
-title: 'Class: AwsS3BlobProvider'
-generated: true
-editUrl: false
----
-# Class: AwsS3BlobProvider
-
-Defined in: [providers/AwsS3BlobProvider.ts:38](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/providers/AwsS3BlobProvider.ts#L38)
-
-Provides an implementation of [IBlobProvider](Interface.IBlobProvider) for Amazon S3.
-
-## Implements
-
-- [`IBlobProvider`](Interface.IBlobProvider)
-
-## Constructors
-
-### Constructor
-
-```ts
-new AwsS3BlobProvider(options): AwsS3BlobProvider;
-```
-
-Defined in: [providers/AwsS3BlobProvider.ts:55](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/providers/AwsS3BlobProvider.ts#L55)
-
-Initializes a new instance of the AwsS3BlobProvider class.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `options` | [`IAwsS3ProviderOptions`](Interface.IAwsS3ProviderOptions) | The provider configuration options. |
-
-#### Returns
-
-`AwsS3BlobProvider`
-
-## Accessors
-
-### defaultBucket
-
-#### Get Signature
-
-```ts
-get defaultBucket(): string;
-```
-
-Defined in: [providers/AwsS3BlobProvider.ts:90](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/providers/AwsS3BlobProvider.ts#L90)
-
-Gets the default bucket configured for the provider.
-
-##### Returns
-
-`string`
-
-#### Implementation of
-
-[`IBlobProvider`](Interface.IBlobProvider).[`defaultBucket`](Interface.IBlobProvider#defaultbucket)
-
-***
-
-### providerId
-
-#### Get Signature
-
-```ts
-get providerId(): string;
-```
-
-Defined in: [providers/AwsS3BlobProvider.ts:83](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/providers/AwsS3BlobProvider.ts#L83)
-
-Gets the identifier used to persist provider metadata.
-
-##### Returns
-
-`string`
-
-#### Implementation of
-
-[`IBlobProvider`](Interface.IBlobProvider).[`providerId`](Interface.IBlobProvider#providerid)
-
-## Methods
-
-### createSignedUrl()
-
-```ts
-createSignedUrl(request): Promise<string>;
-```
-
-Defined in: [providers/AwsS3BlobProvider.ts:210](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/providers/AwsS3BlobProvider.ts#L210)
-
-Creates a pre-signed URL for the specified blob object.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `request` | [`IBlobSignedUrlRequest`](Interface.IBlobSignedUrlRequest) | The request describing the object to link. |
-
-#### Returns
-
-`Promise`\<`string`\>
-
-The generated pre-signed URL.
-
-#### Implementation of
-
-[`IBlobProvider`](Interface.IBlobProvider).[`createSignedUrl`](Interface.IBlobProvider#createsignedurl)
-
-***
-
-### deleteObject()
-
-```ts
-deleteObject(request): Promise<void>;
-```
-
-Defined in: [providers/AwsS3BlobProvider.ts:186](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/providers/AwsS3BlobProvider.ts#L186)
-
-Deletes a blob object from Amazon S3.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `request` | [`IBlobDeleteRequest`](Interface.IBlobDeleteRequest) | The delete request describing the object to remove. |
-
-#### Returns
-
-`Promise`\<`void`\>
-
-#### Implementation of
-
-[`IBlobProvider`](Interface.IBlobProvider).[`deleteObject`](Interface.IBlobProvider#deleteobject)
-
-***
-
-### downloadObject()
-
-```ts
-downloadObject<TData>(request): Promise<IBlobDownloadResult<TData>>;
-```
-
-Defined in: [providers/AwsS3BlobProvider.ts:156](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/providers/AwsS3BlobProvider.ts#L156)
-
-Downloads a blob object from Amazon S3.
-
-#### Type Parameters
-
-| Type Parameter |
-| ------ |
-| `TData` |
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `request` | [`IBlobDownloadRequest`](Interface.IBlobDownloadRequest) | The download request describing the object to download. |
-
-#### Returns
-
-`Promise`\<[`IBlobDownloadResult`](Interface.IBlobDownloadResult)\<`TData`\>\>
-
-The download result including payload and metadata.
-
-#### Implementation of
-
-[`IBlobProvider`](Interface.IBlobProvider).[`downloadObject`](Interface.IBlobProvider#downloadobject)
-
-***
-
-### uploadObject()
-
-```ts
-uploadObject(request): Promise<IBlobUploadResult>;
-```
-
-Defined in: [providers/AwsS3BlobProvider.ts:105](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/providers/AwsS3BlobProvider.ts#L105)
-
-Uploads a blob object to Amazon S3.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `request` | [`IBlobUploadRequest`](Interface.IBlobUploadRequest) | The upload request describing the object to upload. |
-
-#### Returns
-
-`Promise`\<[`IBlobUploadResult`](Interface.IBlobUploadResult)\>
-
-The resulting upload metadata.
-
-#### Implementation of
-
-[`IBlobProvider`](Interface.IBlobProvider).[`uploadObject`](Interface.IBlobProvider#uploadobject)

package/data/packages/platform-blob-storage/api/Class.AzureBlobProvider.md

@@ -1,196 +0,0 @@
----
-title: 'Class: AzureBlobProvider'
-generated: true
-editUrl: false
----
-# Class: AzureBlobProvider
-
-Defined in: [providers/AzureBlobProvider.ts:35](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/providers/AzureBlobProvider.ts#L35)
-
-Provides an implementation of [IBlobProvider](Interface.IBlobProvider) for Microsoft Azure Blob Storage.
-
-## Implements
-
-- [`IBlobProvider`](Interface.IBlobProvider)
-
-## Constructors
-
-### Constructor
-
-```ts
-new AzureBlobProvider(options): AzureBlobProvider;
-```
-
-Defined in: [providers/AzureBlobProvider.ts:53](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/providers/AzureBlobProvider.ts#L53)
-
-Initializes a new instance of the AzureBlobProvider class.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `options` | [`IAzureBlobProviderOptions`](Interface.IAzureBlobProviderOptions) | The provider configuration options. |
-
-#### Returns
-
-`AzureBlobProvider`
-
-## Accessors
-
-### defaultBucket
-
-#### Get Signature
-
-```ts
-get defaultBucket(): string;
-```
-
-Defined in: [providers/AzureBlobProvider.ts:84](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/providers/AzureBlobProvider.ts#L84)
-
-Gets the default bucket (container) configured for the provider.
-
-##### Returns
-
-`string`
-
-#### Implementation of
-
-[`IBlobProvider`](Interface.IBlobProvider).[`defaultBucket`](Interface.IBlobProvider#defaultbucket)
-
-***
-
-### providerId
-
-#### Get Signature
-
-```ts
-get providerId(): string;
-```
-
-Defined in: [providers/AzureBlobProvider.ts:77](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/providers/AzureBlobProvider.ts#L77)
-
-Gets the identifier used to persist provider metadata.
-
-##### Returns
-
-`string`
-
-#### Implementation of
-
-[`IBlobProvider`](Interface.IBlobProvider).[`providerId`](Interface.IBlobProvider#providerid)
-
-## Methods
-
-### createSignedUrl()
-
-```ts
-createSignedUrl(request): Promise<string>;
-```
-
-Defined in: [providers/AzureBlobProvider.ts:194](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/providers/AzureBlobProvider.ts#L194)
-
-Creates a SAS-signed URL for the specified blob object.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `request` | [`IBlobSignedUrlRequest`](Interface.IBlobSignedUrlRequest) | The request describing the object to link. |
-
-#### Returns
-
-`Promise`\<`string`\>
-
-The generated SAS URL.
-
-#### Implementation of
-
-[`IBlobProvider`](Interface.IBlobProvider).[`createSignedUrl`](Interface.IBlobProvider#createsignedurl)
-
-***
-
-### deleteObject()
-
-```ts
-deleteObject(request): Promise<void>;
-```
-
-Defined in: [providers/AzureBlobProvider.ts:175](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/providers/AzureBlobProvider.ts#L175)
-
-Deletes a blob object from Azure Blob Storage.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `request` | [`IBlobDeleteRequest`](Interface.IBlobDeleteRequest) | The delete request describing the object to remove. |
-
-#### Returns
-
-`Promise`\<`void`\>
-
-#### Implementation of
-
-[`IBlobProvider`](Interface.IBlobProvider).[`deleteObject`](Interface.IBlobProvider#deleteobject)
-
-***
-
-### downloadObject()
-
-```ts
-downloadObject<TData>(request): Promise<IBlobDownloadResult<TData>>;
-```
-
-Defined in: [providers/AzureBlobProvider.ts:147](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/providers/AzureBlobProvider.ts#L147)
-
-Downloads a blob object from Azure Blob Storage.
-
-#### Type Parameters
-
-| Type Parameter |
-| ------ |
-| `TData` |
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `request` | [`IBlobDownloadRequest`](Interface.IBlobDownloadRequest) | The download request describing the object to download. |
-
-#### Returns
-
-`Promise`\<[`IBlobDownloadResult`](Interface.IBlobDownloadResult)\<`TData`\>\>
-
-The download result including payload and metadata.
-
-#### Implementation of
-
-[`IBlobProvider`](Interface.IBlobProvider).[`downloadObject`](Interface.IBlobProvider#downloadobject)
-
-***
-
-### uploadObject()
-
-```ts
-uploadObject(request): Promise<IBlobUploadResult>;
-```
-
-Defined in: [providers/AzureBlobProvider.ts:99](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/providers/AzureBlobProvider.ts#L99)
-
-Uploads a blob object to Azure Blob Storage.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `request` | [`IBlobUploadRequest`](Interface.IBlobUploadRequest) | The upload request describing the object to upload. |
-
-#### Returns
-
-`Promise`\<[`IBlobUploadResult`](Interface.IBlobUploadResult)\>
-
-The resulting upload metadata.
-
-#### Implementation of
-
-[`IBlobProvider`](Interface.IBlobProvider).[`uploadObject`](Interface.IBlobProvider#uploadobject)