npm - @breadstone/archipel-mcp - Versions diffs - 0.0.53 → 0.0.55 - Mend

@breadstone/archipel-mcp 0.0.53 → 0.0.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (232) hide show

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

@@ -1,610 +0,0 @@
----
-title: platform-payments
-description: Provider-agnostic payment infrastructure with support for Stripe, Paddle, LemonSqueezy, and Mollie.
-order: 4
-tags: [payments, stripe, paddle, lemonsqueezy, mollie, feature-gating, quotas, guards, interceptors, ports-and-adapters, health]
-package: '@breadstone/archipel-platform-payments'
----
-# platform-payments
-Provider-agnostic payment infrastructure for NestJS. Exposes a unified `PaymentClientPort` abstraction with four ready-made implementations (Stripe, Paddle, LemonSqueezy, Mollie), a feature-gating guard, and a usage-tracking interceptor. Feature access checks are fully decoupled via the `FeatureAccessPort`.
-**Package:** `@breadstone/archipel-platform-payments`
-<InstallTabs />
-## Architecture
-```mermaid
-graph TD
-    Core["@breadstone/archipel-platform-payments<br/><i>Port, models, guard, interceptor, module</i>"]
-    Stripe["@breadstone/archipel-platform-payments/stripe<br/><i>StripeClient</i>"]
-    Paddle["@breadstone/archipel-platform-payments/paddle<br/><i>PaddleClient</i>"]
-    Lemon["@breadstone/archipel-platform-payments/lemonsqueezy<br/><i>LemonSqueezyClient</i>"]
-    Mollie["@breadstone/archipel-platform-payments/mollie<br/><i>MollieClient</i>"]
-    Stripe -->|implements| Core
-    Paddle -->|implements| Core
-    Lemon -->|implements| Core
-    Mollie -->|implements| Core
-    Stripe -.-|requires| S["stripe"]
-    Paddle -.-|requires| P["@paddle/paddle-node-sdk"]
-    Lemon -.-|requires| L["@lemonsqueezy/lemonsqueezy.js"]
-    Mollie -.-|requires| M["@mollie/api-client"]
-```
-Each provider SDK is an **optional peer dependency**. Install only the one you need.
----
-## Quick Start
-### 1. Install the provider SDK
-```bash
-# Pick one:
-yarn add stripe
-yarn add @paddle/paddle-node-sdk
-yarn add @lemonsqueezy/lemonsqueezy.js
-yarn add @mollie/api-client
-```
-### 2. Register the module
-```typescript
-import { Module } from '@nestjs/common';
-import { PaymentModule } from '@breadstone/archipel-platform-payments';
-import { StripeClient, STRIPE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-payments/stripe';
-@Module({
-  imports: [
-    PaymentModule.register({
-      paymentClient: StripeClient,
-      configEntries: STRIPE_CONFIG_ENTRIES,
-      featureAccess: PrismaFeatureAccessAdapter, // optional
-      isGlobal: false,
-    }),
-  ],
-})
-export class AppModule {}
-```
-### Switching providers
-Replace the imports — no other code change needed:
-```typescript
-import { PaddleClient, PADDLE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-payments/paddle';
-PaymentModule.register({
-  paymentClient: PaddleClient,
-  configEntries: PADDLE_CONFIG_ENTRIES,
-});
-```
----
-## Module Configuration
-### IPaymentModuleOptions
-| Property        | Type                                                  | Required | Default | Description                                   |
-| --------------- | ----------------------------------------------------- | -------- | ------- | --------------------------------------------- |
-| `paymentClient` | `Type<PaymentClientPort>`                             | **Yes**  | —       | Provider implementation (e.g. `StripeClient`) |
-| `configEntries` | `ReadonlyArray<Omit<IConfigRegistryEntry, 'module'>>` | No       | `[]`    | Provider-specific config entries              |
-| `featureAccess` | `Type<FeatureAccessPort>`                             | No       | —       | Feature quota checking and usage recording    |
-| `isGlobal`      | `boolean`                                             | No       | `false` | Register as a global module                   |
----
-## Payment Providers
-### Stripe
-**Subpath:** `@breadstone/archipel-platform-payments/stripe`
-**SDK:** `stripe` ≥ 22.0.0
-| Variable                | Description                   | Required |
-| ----------------------- | ----------------------------- | -------- |
-| `STRIPE_API_KEY`        | Stripe secret API key         | Yes      |
-| `STRIPE_WEBHOOK_SECRET` | Stripe webhook signing secret | Yes      |
-```typescript
-import { StripeClient, STRIPE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-payments/stripe';
-```
-### Paddle
-**Subpath:** `@breadstone/archipel-platform-payments/paddle`
-**SDK:** `@paddle/paddle-node-sdk` ≥ 3.0.0
-| Variable                | Description               | Required | Default      |
-| ----------------------- | ------------------------- | -------- | ------------ |
-| `PADDLE_API_KEY`        | Paddle API key            | Yes      | —            |
-| `PADDLE_WEBHOOK_SECRET` | Paddle webhook secret key | Yes      | —            |
-| `PADDLE_ENVIRONMENT`    | `production` or `sandbox` | No       | `production` |
-```typescript
-import { PaddleClient, PADDLE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-payments/paddle';
-```
-### LemonSqueezy
-**Subpath:** `@breadstone/archipel-platform-payments/lemonsqueezy`
-**SDK:** `@lemonsqueezy/lemonsqueezy.js` ≥ 4.0.0
-| Variable                      | Description                         | Required |
-| ----------------------------- | ----------------------------------- | -------- |
-| `LEMONSQUEEZY_API_KEY`        | LemonSqueezy API key                | Yes      |
-| `LEMONSQUEEZY_WEBHOOK_SECRET` | LemonSqueezy webhook signing secret | Yes      |
-| `LEMONSQUEEZY_STORE_ID`       | LemonSqueezy store ID               | Yes      |
-```typescript
-import { LemonSqueezyClient, LEMONSQUEEZY_CONFIG_ENTRIES } from '@breadstone/archipel-platform-payments/lemonsqueezy';
-```
-### Mollie
-**Subpath:** `@breadstone/archipel-platform-payments/mollie`
-**SDK:** `@mollie/api-client` ≥ 4.0.0
-| Variable                | Description                            | Required |
-| ----------------------- | -------------------------------------- | -------- |
-| `MOLLIE_API_KEY`        | Mollie API key                         | Yes      |
-| `MOLLIE_WEBHOOK_SECRET` | Mollie webhook secret for verification | Yes      |
-```typescript
-import { MollieClient, MOLLIE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-payments/mollie';
-```
-::: info Mollie Limitations
-Mollie does not have a native price catalog API. `fetchPrices()` returns an empty array — maintain prices in your local database. `fetchSubscription()` expects the format `"customerId:subscriptionId"`.
-:::
----
-## PaymentClientPort
-All providers implement this abstract contract. Inject `PaymentClientPort` in services to stay provider-agnostic:
-```typescript
-abstract class PaymentClientPort {
-  abstract fetchPrices(productId: string): Promise<INormalizedPrice[]>;
-  abstract createCheckoutSession(
-    priceId: string,
-    successUrl: string,
-    cancelUrl: string,
-    userId?: string,
-  ): Promise<INormalizedCheckoutSession>;
-  abstract fetchSubscription(subscriptionId: string): Promise<INormalizedSubscription | null>;
-  abstract constructWebhookEvent(
-    payload: string | Buffer,
-    signature: string,
-  ): Promise<INormalizedWebhookEvent> | INormalizedWebhookEvent;
-}
-```
-### Usage in services
-```typescript
-import { PaymentClientPort } from '@breadstone/archipel-platform-payments';
-@Injectable()
-export class CheckoutService {
-  constructor(private readonly _paymentClient: PaymentClientPort) {}
-  public async createCheckout(priceId: string, userId: string): Promise<string | null> {
-    const session = await this._paymentClient.createCheckoutSession(
-      priceId,
-      'https://app.example.com/success',
-      'https://app.example.com/cancel',
-      userId,
-    );
-    return session.url;
-  }
-}
-```
-### Prices
-```typescript
-const prices = await this._paymentClient.fetchPrices('prod_ABC123');
-// → INormalizedPrice[]
-```
-> **Error handling:** `fetchPrices` **throws** on API or network errors instead of returning an empty array. Errors are logged with structured metadata before being re-thrown. Wrap calls in `try/catch` if you need fallback behavior.
-### Subscriptions
-```typescript
-const subscription = await this._paymentClient.fetchSubscription('sub_ABC123');
-// → INormalizedSubscription | null
-```
-### Webhook Events
-```typescript
-const event = await this._paymentClient.constructWebhookEvent(rawBody, signature);
-// → INormalizedWebhookEvent
-```
----
-## Normalized Types
-All providers map their native API responses into these shared interfaces.
-### INormalizedPrice
-| Field           | Type                                               | Description                     |
-| --------------- | -------------------------------------------------- | ------------------------------- |
-| `id`            | `string`                                           | Price identifier                |
-| `productId`     | `string`                                           | Associated product identifier   |
-| `amount`        | `number`                                           | Price amount (in smallest unit) |
-| `currency`      | `string`                                           | ISO 4217 currency code          |
-| `interval`      | `'week' \| 'month' \| 'quarter' \| 'year' \| null` | Billing interval                |
-| `intervalCount` | `number`                                           | Number of intervals per cycle   |
-| `active`        | `boolean`                                          | Whether the price is active     |
-### INormalizedCheckoutSession
-| Field               | Type                                          | Description              |
-| ------------------- | --------------------------------------------- | ------------------------ |
-| `id`                | `string`                                      | Session identifier       |
-| `url`               | `string \| null`                              | Checkout URL to redirect |
-| `subscriptionId`    | `string \| null`                              | Created subscription ID  |
-| `customerId`        | `string \| null`                              | Customer identifier      |
-| `clientReferenceId` | `string \| null`                              | Client-supplied ref      |
-| `paymentStatus`     | `'paid' \| 'unpaid' \| 'no_payment_required'` | Payment status           |
-### INormalizedSubscription
-| Field                | Type                 | Description                       |
-| -------------------- | -------------------- | --------------------------------- |
-| `id`                 | `string`             | Subscription identifier           |
-| `customerId`         | `string`             | Customer identifier               |
-| `status`             | `SubscriptionStatus` | Current status                    |
-| `priceId`            | `string`             | Associated price identifier       |
-| `currentPeriodStart` | `Date`               | Start of current billing period   |
-| `currentPeriodEnd`   | `Date`               | End of current billing period     |
-| `cancelAtPeriodEnd`  | `boolean`            | Whether cancellation is scheduled |
-| `trialStart`         | `Date \| null`       | Trial start date                  |
-| `trialEnd`           | `Date \| null`       | Trial end date                    |
-### SubscriptionStatus
-```typescript
-type SubscriptionStatus =
-  | 'active'
-  | 'canceled'
-  | 'incomplete'
-  | 'incompleteExpired'
-  | 'pastDue'
-  | 'trialing'
-  | 'unpaid'
-  | 'paused';
-```
-### INormalizedWebhookEvent
-| Field  | Type                        | Description                     |
-| ------ | --------------------------- | ------------------------------- |
-| `type` | `string` (see values below) | Normalized event type           |
-| `data` | `object`                    | Event payload (see shape below) |
-**Event types:** `checkout.session.completed`, `subscription.updated`, `subscription.deleted`, `invoice.payment_failed`, `invoice.payment_succeeded`, `unknown`
-**Data shape:**
-```typescript
-{
-  checkoutSession?: INormalizedCheckoutSession;
-  subscription?: INormalizedSubscription;
-  invoice?: {
-    id: string;
-    subscriptionId: string | null;
-    status: 'draft' | 'open' | 'paid' | 'uncollectible' | 'void';
-  };
-}
-```
----
-## FeatureAccessPort
-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,
-    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                              |
-| ----------- | --------- | ---------------------------------------- |
-| `allowed`   | `boolean` | Whether the user can use the feature     |
-| `used`      | `number`  | Current usage count in the active period |
-| `limit`     | `number`  | Maximum allowed (`-1` = unlimited)       |
-| `remaining` | `number`  | Remaining quota (`-1` = unlimited)       |
-| `resetAt`   | `Date`    | When the usage period resets             |
-### Real-World Adapter: Prisma + Subscription
-```typescript
-@Injectable()
-export class PrismaFeatureAccessAdapter extends FeatureAccessPort {
-  private readonly _prisma: PrismaService;
-  constructor(prisma: PrismaService) {
-    super();
-    this._prisma = prisma;
-  }
-  public async checkAccess(
-    userId: string,
-    featureKey: string,
-    context?: IFeatureAccessContext,
-  ): Promise<IFeatureAccessResult> {
-    const subscription = await this._prisma.subscription.findFirst({
-      where: { userId, tenantId: context?.tenantId, status: 'active' },
-      include: { plan: { include: { features: true } } },
-    });
-    const feature = subscription?.plan.features.find((f) => f.key === featureKey);
-    if (!feature) {
-      return { allowed: false, used: 0, limit: 0, remaining: 0, resetAt: new Date() };
-    }
-    const periodStart = this.getCurrentPeriodStart(subscription.currentPeriodStart);
-    const usage = await this._prisma.featureUsage.count({
-      where: {
-        userId,
-        tenantId: context?.tenantId,
-        featureKey,
-        createdAt: { gte: periodStart },
-      },
-    });
-    const limit = feature.limit;
-    const remaining = limit === -1 ? -1 : Math.max(0, limit - usage);
-    return {
-      allowed: limit === -1 || usage < limit,
-      used: usage,
-      limit,
-      remaining,
-      resetAt: subscription.currentPeriodEnd,
-    };
-  }
-  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 },
-    });
-  }
-  private getCurrentPeriodStart(periodStart: Date): Date {
-    return periodStart;
-  }
-}
-```
----
-## Feature Gating
-### @RequiresFeature Decorator
-Mark controller endpoints with a feature key:
-```typescript
-import { RequiresFeature } from '@breadstone/archipel-platform-payments';
-@Controller('recipes')
-export class RecipeController {
-  @Post()
-  @RequiresFeature('RECIPE_CREATION')
-  public async createRecipe(@Body() body: CreateRecipeDto): Promise<RecipeResponse> {
-    // Only executed if user has quota for RECIPE_CREATION
-  }
-}
-```
-### FeatureGuard
-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
-app.useGlobalGuards(app.get(FeatureGuard));
-// Per-controller
-@Controller('recipes')
-@UseGuards(JwtAuthGuard, FeatureGuard)
-export class RecipeController {
-  /* ... */
-}
-```
-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
-Records feature usage after successful request completion:
-```typescript
-@Controller('recipes')
-@UseGuards(JwtAuthGuard, FeatureGuard)
-@UseInterceptors(FeatureUsageInterceptor)
-export class RecipeController {
-  @Post()
-  @RequiresFeature('RECIPE_CREATION')
-  public async createRecipe(@Body() body: CreateRecipeDto): Promise<RecipeResponse> {
-    // After successful response, FeatureUsageInterceptor calls
-    // FeatureAccessPort.recordUsage(userId, 'RECIPE_CREATION', context)
-  }
-}
-```
----
-## End-to-End Example: Feature-Gated API with Stripe
-```typescript
-// 1. Define feature keys
-export const FEATURES = {
-  RECIPE_CREATION: 'RECIPE_CREATION',
-  AI_SUGGESTIONS: 'AI_SUGGESTIONS',
-  EXPORT_PDF: 'EXPORT_PDF',
-} as const;
-// 2. Implement the adapter
-@Injectable()
-export class AppFeatureAccessAdapter extends FeatureAccessPort {
-  // ... (see Real-World Adapter above)
-}
-// 3. Register with Stripe
-import { StripeClient, STRIPE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-payments/stripe';
-@Module({
-  imports: [
-    PaymentModule.register({
-      paymentClient: StripeClient,
-      configEntries: STRIPE_CONFIG_ENTRIES,
-      featureAccess: AppFeatureAccessAdapter,
-    }),
-  ],
-})
-export class AppModule {}
-// 4. Use in controllers
-@Controller('recipes')
-@UseGuards(JwtAuthGuard, FeatureGuard)
-@UseInterceptors(FeatureUsageInterceptor)
-export class RecipeController {
-  constructor(private readonly _paymentClient: PaymentClientPort) {}
-  @Post()
-  @RequiresFeature(FEATURES.RECIPE_CREATION)
-  public async create(@Body() body: CreateRecipeDto): Promise<RecipeResponse> {
-    return this._recipeService.create(body);
-  }
-  @Post(':id/ai-suggestions')
-  @RequiresFeature(FEATURES.AI_SUGGESTIONS)
-  public async suggest(@Param('id') id: string): Promise<SuggestionResponse> {
-    return this._aiService.suggest(id);
-  }
-}
-```
----
-## Error Handling
-All payment clients throw a `PaymentError` when provider operations fail (checkout session creation, webhook signature verification, price fetching, etc.). This domain error wraps the underlying SDK error and exposes structured metadata:
-```typescript
-import { PaymentError } from '@breadstone/archipel-platform-payments';
-try {
-  await this._paymentClient.createCheckoutSession(priceId, successUrl, cancelUrl, userId);
-} catch (error) {
-  if (error instanceof PaymentError) {
-    logger.error('Payment operation failed', {
-      provider: error.provider,  // 'stripe', 'paddle', 'mollie', 'lemonsqueezy'
-      code: error.code,          // 'PAYMENT'
-      cause: error.cause,        // Original provider SDK error
-    });
-  }
-}
-```
-| Property   | Type     | Description                                        |
-| ---------- | -------- | -------------------------------------------------- |
-| `code`     | `string` | Always `'PAYMENT'`                                 |
-| `provider` | `string` | Provider that failed (`stripe`, `paddle`, etc.)    |
-| `cause`    | `unknown`| Original error from the provider SDK               |
----
-## Health Check
-The `PaymentHealthIndicator` verifies that a `PaymentClientPort` is injected. If no payment client is registered, it reports `disabled: true`. Import it from the `/health` subpath:
-```typescript
-import { PaymentHealthIndicator } from '@breadstone/archipel-platform-payments/health';
-import { HealthModule } from '@breadstone/archipel-platform-health';
-@Module({
-  imports: [
-    PaymentModule.register({ /* ... */ }),
-    HealthModule.withIndicators([PaymentHealthIndicator]),
-  ],
-})
-export class AppModule {}
-```
-| Key | Check | Dependencies |
-| --- | ----- | ------------ |
-| `payment` | `up` if `PaymentClientPort` injected, else `disabled` | `@Optional() PaymentClientPort` |
----
-## Exports Summary
-### Core (`@breadstone/archipel-platform-payments`)
-| Export                       | Type          | Description                         |
-| ---------------------------- | ------------- | ----------------------------------- |
-| `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               |
-| `RequiresFeature`            | Decorator     | Marks feature-gated endpoints       |
-| `FEATURE_KEY_METADATA`       | Constant      | Metadata key for feature decorators |
-| `INormalizedPrice`           | Interface     | Normalized price                    |
-| `INormalizedCheckoutSession` | Interface     | Normalized checkout session         |
-| `INormalizedSubscription`    | Interface     | Normalized subscription             |
-| `INormalizedWebhookEvent`    | Interface     | Normalized webhook event            |
-| `SubscriptionStatus`         | Type Alias    | Subscription status union           |
-| `PaymentError`               | Error class   | Domain error for payment failures   |
-| `PaymentHealthIndicator`     | Health        | Payment readiness check (`/health` subpath) |
-### Provider subpaths
-| Subpath         | Exports                                                                                                                             |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `/stripe`       | `StripeClient`, `STRIPE_API_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_CONFIG_ENTRIES`                                                  |
-| `/paddle`       | `PaddleClient`, `PADDLE_API_KEY`, `PADDLE_WEBHOOK_SECRET`, `PADDLE_ENVIRONMENT`, `PADDLE_CONFIG_ENTRIES`                            |
-| `/lemonsqueezy` | `LemonSqueezyClient`, `LEMONSQUEEZY_API_KEY`, `LEMONSQUEEZY_WEBHOOK_SECRET`, `LEMONSQUEEZY_STORE_ID`, `LEMONSQUEEZY_CONFIG_ENTRIES` |
-| `/mollie`       | `MollieClient`, `MOLLIE_API_KEY`, `MOLLIE_WEBHOOK_SECRET`, `MOLLIE_CONFIG_ENTRIES`                                                  |