@breadstone/archipel-mcp 0.0.40 → 0.0.42

package/data/guides/blob-storage.md

@@ -18,16 +18,17 @@ yarn add @breadstone/archipel-platform-blob-storage
 
 ---
 
-## Choose a Provider
+## Choose a Strategy
 
-`platform-blob-storage` abstracts file operations behind a unified `BlobService`. You select the provider at module registration time. Supported providers:
+`platform-blob-storage` abstracts file operations behind a unified `BlobService`. You select the storage strategy at module registration time. Built-in strategies:
 
-| Provider   | Kind constant              | When to use                                 |
-| ---------- | -------------------------- | ------------------------------------------- |
-| **Vercel** | `BlobProviderKinds.Vercel` | Vercel-hosted apps with Vercel Blob storage |
-| **Azure**  | `BlobProviderKinds.Azure`  | Azure Blob Storage accounts                 |
-| **AWS S3** | `BlobProviderKinds.AwsS3`  | Amazon S3 or S3-compatible providers        |
-| **Custom** | `BlobProviderKinds.Custom` | Your own storage backend                    |
+| Strategy                      | Import subpath        | When to use                                 |
+| ----------------------------- | --------------------- | ------------------------------------------- |
+| **Vercel**                    | `strategies/vercel`   | Vercel-hosted apps with Vercel Blob storage |
+| **Azure**                     | `strategies/azure`    | Azure Blob Storage accounts                 |
+| **AWS S3**                    | `strategies/aws-s3`   | Amazon S3 or S3-compatible providers        |
+| **Local**                     | `strategies/local`    | Local filesystem (development / testing)    |
+| **Custom**                    | —                     | Extend `BlobStorageStrategyBase`            |
 
 ---
 
@@ -35,14 +36,14 @@ yarn add @breadstone/archipel-platform-blob-storage
 
 ```typescript
 import { Module } from '@nestjs/common';
-import { BlobModule, BlobProviderKinds } from '@breadstone/archipel-platform-blob-storage';
+import { BlobModule } from '@breadstone/archipel-platform-blob-storage';
+import { AwsS3BlobStorageStrategy, AWS_S3_CONFIG_ENTRIES } from '@breadstone/archipel-platform-blob-storage/strategies/aws-s3';
 
 @Module({
   imports: [
-    BlobModule.forRoot({
-      provider: {
-        kind: BlobProviderKinds.AwsS3,
-      },
+    BlobModule.register({
+      storageStrategy: AwsS3BlobStorageStrategy,
+      configEntries: AWS_S3_CONFIG_ENTRIES,
     }),
   ],
 })
@@ -234,8 +235,11 @@ export class PrismaBlobVariantAdapter extends BlobVariantPersistencePort {
 ### Register with Persistence
 
 ```typescript
-BlobModule.forRoot({
-  provider: { kind: BlobProviderKinds.AwsS3 },
+import { AwsS3BlobStorageStrategy, AWS_S3_CONFIG_ENTRIES } from '@breadstone/archipel-platform-blob-storage/strategies/aws-s3';
+
+BlobModule.register({
+  storageStrategy: AwsS3BlobStorageStrategy,
+  configEntries: AWS_S3_CONFIG_ENTRIES,
   objectPersistence: PrismaBlobObjectAdapter,
   variantPersistence: PrismaBlobVariantAdapter,
 }),
@@ -245,7 +249,7 @@ BlobModule.forRoot({
 
 ## Security
 
-All built-in blob providers (AWS S3, Azure, Vercel) apply automatic key normalization via the internal `normalizeKey` method before any storage operation. This includes:
+All built-in blob storage strategies (AWS S3, Azure, Vercel, Local) apply automatic key normalization via the internal `normalizeKey` method before any storage operation. This includes:
 
 - **Path traversal prevention** — segments such as `..` and `.` are removed so callers cannot escape the intended directory.
 - **Backslash normalization** — backslashes (`\`) are converted to forward slashes before processing.

package/data/guides/implementing-ports.md

@@ -304,6 +304,8 @@ When omitted, blob uploads and deletes work normally, but metadata isn't tracked
 
 When omitted, `FeatureGuard` and `FeatureUsageInterceptor` have no access port and will deny or skip feature checks. When provided, they delegate quota enforcement and usage recording to your adapter.
 
+`FeatureGuard` calls `checkAccess(userId, featureKey, context)`, while `FeatureUsageInterceptor` calls `recordUsage(userId, featureKey, context)` after a successful request. The `IFeatureAccessContext` contains the resolved `userId`, optional `tenantId`, and original authenticated subject, so adapters can enforce tenant-scoped plans without controller-specific billing logic.
+
 ---
 
 ## Common Mistakes

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

@@ -36,16 +36,15 @@ yarn add @breadstone/archipel-platform-payments
 ```typescript
 import { Module } from '@nestjs/common';
 import { PaymentModule } from '@breadstone/archipel-platform-payments';
-import { StripePaymentClient } from './adapters/StripePaymentClient';
+import { StripeClient, STRIPE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-payments/stripe';
 import { PrismaFeatureAccessAdapter } from './adapters/PrismaFeatureAccessAdapter';
-import { STRIPE_CONFIG_ENTRIES } from './env';
 
 @Module({
   imports: [
     PaymentModule.register({
-      paymentClient: StripePaymentClient,
+      paymentClient: StripeClient,
       featureAccess: PrismaFeatureAccessAdapter,
-      configEntries: [...STRIPE_CONFIG_ENTRIES],
+      configEntries: STRIPE_CONFIG_ENTRIES,
     }),
   ],
 })
@@ -54,9 +53,9 @@ export class AppModule {}
 
 ---
 
-## Implementing the Payment Client Port
+## Using the Payment Client Port
 
-The `PaymentClientPort` defines the contract between the library and your payment provider. Implement it for your chosen provider:
+The built-in provider clients implement `PaymentClientPort`. Inject the port in application services so checkout and webhook code stays provider-agnostic:
 
 ```typescript
 import { Injectable } from '@nestjs/common';
@@ -64,23 +63,27 @@ 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
+export class CheckoutService {
+  private readonly _paymentClient: PaymentClientPort;
+
+  public constructor(paymentClient: PaymentClientPort) {
+    this._paymentClient = paymentClient;
   }
 
-  public async getSubscription(subscriptionId: string): Promise<INormalizedSubscription | null> {
-    // Fetch subscription details from Stripe
-    // Return normalized subscription data
+  public async createCheckout(priceId: string, userId: string): Promise<INormalizedCheckoutSession> {
+    return this._paymentClient.createCheckoutSession(
+      priceId,
+      'https://app.example.com/billing/success',
+      'https://app.example.com/billing/cancel',
+      userId,
+    );
   }
 
-  public async handleWebhook(payload: Buffer, signature: string): Promise<INormalizedWebhookEvent> {
-    // Verify webhook signature and normalize the event
+  public async getSubscription(subscriptionId: string): Promise<INormalizedSubscription | null> {
+    return this._paymentClient.fetchSubscription(subscriptionId);
   }
 }
 ```
@@ -97,7 +100,11 @@ The `FeatureAccessPort` lets you restrict functionality based on subscription ti
 
 ```typescript
 import { Injectable } from '@nestjs/common';
-import { FeatureAccessPort } from '@breadstone/archipel-platform-payments';
+import {
+  FeatureAccessPort,
+  type IFeatureAccessContext,
+  type IFeatureAccessResult,
+} from '@breadstone/archipel-platform-payments';
 import { PrismaService } from '@breadstone/archipel-platform-database';
 
 @Injectable()
@@ -109,53 +116,77 @@ export class PrismaFeatureAccessAdapter extends FeatureAccessPort {
     this._prisma = prisma;
   }
 
-  public async hasAccess(userId: string, feature: string): Promise<boolean> {
+  public async checkAccess(
+    userId: string,
+    featureKey: string,
+    context?: IFeatureAccessContext,
+  ): Promise<IFeatureAccessResult> {
     const subscription = await this._prisma.subscription.findFirst({
-      where: { userId, status: 'active' },
-      include: { plan: true },
+      where: { userId, tenantId: context?.tenantId, status: 'active' },
+      include: { plan: { include: { features: true } } },
     });
 
-    if (!subscription) {
-      return false;
+    const feature = subscription?.plan.features.find((planFeature) => planFeature.key === featureKey);
+    if (!feature) {
+      return { allowed: false, used: 0, limit: 0, remaining: 0, resetAt: new Date() };
     }
 
-    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() },
+    const used = await this._prisma.featureUsage.count({
+      where: {
+        userId,
+        tenantId: context?.tenantId,
+        featureKey,
+        usedAt: { gte: subscription.currentPeriodStart },
+      },
     });
+
+    const limit = feature.limit;
+    const remaining = limit === -1 ? -1 : Math.max(0, limit - used);
+
+    return {
+      allowed: limit === -1 || used < limit,
+      used,
+      limit,
+      remaining,
+      resetAt: subscription.currentPeriodEnd,
+    };
   }
 
-  public async getUsageCount(userId: string, feature: string, since: Date): Promise<number> {
-    return this._prisma.featureUsage.count({
-      where: { userId, feature, usedAt: { gte: since } },
+  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, tenantId: context?.tenantId, featureKey, usedAt: new Date() },
     });
   }
 }
 ```
 
+`FeatureGuard` and `FeatureUsageInterceptor` pass `IFeatureAccessContext` into this adapter. The context includes the resolved `userId`, an optional `tenantId` from `request.user.tenantId`, and the original authenticated subject.
+
 ### Step 2: Use the Feature Guard
 
-The `FeatureGuard` decorator restricts endpoints to users with access to specific features:
+Use `@RequiresFeature()` to mark endpoints and `FeatureGuard` to enforce access checks:
 
 ```typescript
 import { Controller, Post, UseGuards } from '@nestjs/common';
 import { JwtAuthGuard } from '@breadstone/archipel-platform-authentication';
-import { FeatureGuard } from '@breadstone/archipel-platform-payments';
+import { FeatureGuard, RequiresFeature } from '@breadstone/archipel-platform-payments';
 
 @Controller('exports')
-@UseGuards(JwtAuthGuard)
+@UseGuards(JwtAuthGuard, FeatureGuard)
 export class ExportController {
   @Post('pdf')
-  @FeatureGuard('export:pdf')
+  @RequiresFeature('export:pdf')
   public async exportPdf(): Promise<void> {
     // Only accessible to users with 'export:pdf' feature
   }
 
   @Post('csv')
-  @FeatureGuard('export:csv')
+  @RequiresFeature('export:csv')
   public async exportCsv(): Promise<void> {
     // Only accessible to users with 'export:csv' feature
   }
@@ -169,14 +200,14 @@ export class ExportController {
 ```typescript
 import { Controller, Post, UseGuards, UseInterceptors } from '@nestjs/common';
 import { JwtAuthGuard } from '@breadstone/archipel-platform-authentication';
-import { FeatureGuard, FeatureUsageInterceptor } from '@breadstone/archipel-platform-payments';
+import { FeatureGuard, FeatureUsageInterceptor, RequiresFeature } from '@breadstone/archipel-platform-payments';
 
 @Controller('ai')
-@UseGuards(JwtAuthGuard)
+@UseGuards(JwtAuthGuard, FeatureGuard)
+@UseInterceptors(FeatureUsageInterceptor)
 export class AiController {
   @Post('generate')
-  @FeatureGuard('ai:generate')
-  @UseInterceptors(FeatureUsageInterceptor)
+  @RequiresFeature('ai:generate')
   public async generate(): Promise<string> {
     // Usage is recorded automatically after success
     return 'generated content';
@@ -208,17 +239,16 @@ export class PaymentWebhookController {
     @Req() request: RawBodyRequest<Request>,
     @Headers('stripe-signature') signature: string,
   ): Promise<void> {
-    const event = await this._paymentClient.handleWebhook(request.rawBody!, signature);
+    const event = await this._paymentClient.constructWebhookEvent(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':
+      case 'invoice.payment_failed':
         // Notify user, retry logic
         break;
     }
@@ -234,7 +264,8 @@ export class PaymentWebhookController {
 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.
+5. **Use access context for tenancy.** Read `context.tenantId` instead of coupling controllers to billing tables.
+6. **Separate feature gating from billing logic.** The `FeatureAccessPort` should check access and record metered usage, not manage subscriptions.
 
 ## Error Handling
 
@@ -258,7 +289,7 @@ All payment clients throw `PaymentError` — a domain error that wraps the under
 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) {
     // error.provider → 'stripe', 'paddle', 'mollie', 'lemonsqueezy'

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

@@ -0,0 +1,197 @@
+---
+title: 'Class: AwsS3BlobStorageStrategy'
+generated: true
+editUrl: false
+---
+# Class: AwsS3BlobStorageStrategy
+
+Defined in: [strategies/aws-s3/AwsS3BlobStorageStrategy.ts:26](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/aws-s3/AwsS3BlobStorageStrategy.ts#L26)
+
+Provides a blob storage strategy backed by Amazon S3.
+
+## Extends
+
+- [`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase)
+
+## Constructors
+
+### Constructor
+
+```ts
+new AwsS3BlobStorageStrategy(configService): AwsS3BlobStorageStrategy;
+```
+
+Defined in: [strategies/aws-s3/AwsS3BlobStorageStrategy.ts:47](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/aws-s3/AwsS3BlobStorageStrategy.ts#L47)
+
+Initializes a new instance of the AwsS3BlobStorageStrategy class.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `configService` | `ConfigService` | The configuration service providing environment values. |
+
+#### Returns
+
+`AwsS3BlobStorageStrategy`
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`constructor`](Class.BlobStorageStrategyBase#constructor)
+
+## Properties
+
+### providerId
+
+```ts
+readonly providerId: string = 'aws-s3';
+```
+
+Defined in: [strategies/aws-s3/AwsS3BlobStorageStrategy.ts:77](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/aws-s3/AwsS3BlobStorageStrategy.ts#L77)
+
+Gets the unique identifier for this storage provider.
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`providerId`](Class.BlobStorageStrategyBase#providerid)
+
+## Accessors
+
+### defaultBucket
+
+#### Get Signature
+
+```ts
+get defaultBucket(): string;
+```
+
+Defined in: [strategies/aws-s3/AwsS3BlobStorageStrategy.ts:80](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/aws-s3/AwsS3BlobStorageStrategy.ts#L80)
+
+Gets the default bucket (container/directory) configured for the provider.
+
+##### Returns
+
+`string`
+
+Gets the default bucket (container/directory) configured for the provider.
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`defaultBucket`](Class.BlobStorageStrategyBase#defaultbucket)
+
+## Methods
+
+### createSignedUrl()
+
+```ts
+createSignedUrl(request): Promise<string>;
+```
+
+Defined in: [strategies/aws-s3/AwsS3BlobStorageStrategy.ts:177](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/aws-s3/AwsS3BlobStorageStrategy.ts#L177)
+
+Creates a signed URL for the specified blob object.
+Not all providers support this operation.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `request` | [`IBlobSignedUrlRequest`](Interface.IBlobSignedUrlRequest) | The request describing the object to link. |
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The generated signed URL.
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`createSignedUrl`](Class.BlobStorageStrategyBase#createsignedurl)
+
+***
+
+### deleteObject()
+
+```ts
+deleteObject(request): Promise<void>;
+```
+
+Defined in: [strategies/aws-s3/AwsS3BlobStorageStrategy.ts:159](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/aws-s3/AwsS3BlobStorageStrategy.ts#L159)
+
+Deletes a blob object from the storage backend.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `request` | [`IBlobDeleteRequest`](Interface.IBlobDeleteRequest) | The delete request describing the object to remove. |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`deleteObject`](Class.BlobStorageStrategyBase#deleteobject)
+
+***
+
+### downloadObject()
+
+```ts
+downloadObject<TData>(request): Promise<IBlobDownloadResult<TData>>;
+```
+
+Defined in: [strategies/aws-s3/AwsS3BlobStorageStrategy.ts:134](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/aws-s3/AwsS3BlobStorageStrategy.ts#L134)
+
+Downloads a blob object from the storage backend.
+
+#### 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.
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`downloadObject`](Class.BlobStorageStrategyBase#downloadobject)
+
+***
+
+### uploadObject()
+
+```ts
+uploadObject(request): Promise<IBlobUploadResult>;
+```
+
+Defined in: [strategies/aws-s3/AwsS3BlobStorageStrategy.ts:89](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-blob-storage/src/strategies/aws-s3/AwsS3BlobStorageStrategy.ts#L89)
+
+Uploads a blob object to the storage backend.
+
+#### 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.
+
+#### Overrides
+
+[`BlobStorageStrategyBase`](Class.BlobStorageStrategyBase).[`uploadObject`](Class.BlobStorageStrategyBase#uploadobject)