@blimu/nestjs 1.1.1 → 1.1.4

package/dist/config/blimu.config.cjs

@@ -0,0 +1,31 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/config/blimu.config.ts
+var blimu_config_exports = {};
+__export(blimu_config_exports, {
+  BLIMU_CONFIG: () => BLIMU_CONFIG
+});
+module.exports = __toCommonJS(blimu_config_exports);
+var BLIMU_CONFIG = /* @__PURE__ */ Symbol("BLIMU_CONFIG");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BLIMU_CONFIG
+});
+//# sourceMappingURL=blimu.config.cjs.map

package/dist/config/blimu.config.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/config/blimu.config.ts"],"sourcesContent":["/**\n * Configuration interface for Blimu NestJS integration\n */\nexport interface BlimuConfig<TRequest = unknown> {\n  global?: boolean | undefined;\n  /**\n   * The API secret key for authenticating with Blimu Runtime API\n   */\n  apiKey: string;\n\n  /**\n   * The base URL for the Blimu Runtime API\n   * @default 'https://api.blimu.dev'\n   */\n  baseURL?: string | undefined;\n\n  /**\n   * Environment ID for the Blimu environment\n   * This will be used in future versions for environment-specific configurations\n   */\n  environmentId?: string | undefined;\n\n  /**\n   * Request timeout in milliseconds\n   * @default 30000\n   */\n  timeoutMs?: number | undefined;\n\n  /**\n   * Function to extract user ID from the request\n   *\n   * This function is called by the EntitlementGuard to determine which user\n   * to check entitlements for. It should return the user ID as a string.\n   *\n   * @param request - The incoming HTTP request\n   * @returns The user ID as a string, or a Promise that resolves to the user ID\n   *\n   * @example\n   * ```typescript\n   * // Extract from JWT token in Authorization header\n   * getUserId: (req) => {\n   *   const token = req.headers.authorization?.replace('Bearer ', '');\n   *   const decoded = jwt.verify(token, secret);\n   *   return decoded.sub;\n   * }\n   *\n   * // Extract from request.user (common with Passport.js)\n   * getUserId: (req) => req.user?.id\n   *\n   * // Extract from custom header\n   * getUserId: (req) => req.headers['x-user-id']\n   * ```\n   */\n  getUserId: (request: TRequest) => string | Promise<string>;\n}\n\n/**\n * Injection token for Blimu configuration\n */\nexport const BLIMU_CONFIG = Symbol('BLIMU_CONFIG');\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA2DO,IAAM,eAAe,uBAAO,cAAc;","names":[]}

package/dist/config/blimu.config.d.cts

@@ -0,0 +1,11 @@
+interface BlimuConfig<TRequest = unknown> {
+    global?: boolean | undefined;
+    apiKey: string;
+    baseURL?: string | undefined;
+    environmentId?: string | undefined;
+    timeoutMs?: number | undefined;
+    getUserId: (request: TRequest) => string | Promise<string>;
+}
+declare const BLIMU_CONFIG: unique symbol;
+
+export { BLIMU_CONFIG, type BlimuConfig };

package/dist/config/blimu.config.d.ts

@@ -1,9 +1,11 @@
-export interface BlimuConfig<TRequest = any> {
+interface BlimuConfig<TRequest = unknown> {
+    global?: boolean | undefined;
     apiKey: string;
-    baseURL?: string;
-    environmentId?: string;
-    timeoutMs?: number;
+    baseURL?: string | undefined;
+    environmentId?: string | undefined;
+    timeoutMs?: number | undefined;
     getUserId: (request: TRequest) => string | Promise<string>;
 }
-export declare const BLIMU_CONFIG: unique symbol;
-//# sourceMappingURL=blimu.config.d.ts.map
+declare const BLIMU_CONFIG: unique symbol;
+
+export { BLIMU_CONFIG, type BlimuConfig };

package/dist/config/blimu.config.mjs

@@ -0,0 +1,6 @@
+// src/config/blimu.config.ts
+var BLIMU_CONFIG = /* @__PURE__ */ Symbol("BLIMU_CONFIG");
+export {
+  BLIMU_CONFIG
+};
+//# sourceMappingURL=blimu.config.mjs.map

package/dist/config/blimu.config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/config/blimu.config.ts"],"sourcesContent":["/**\n * Configuration interface for Blimu NestJS integration\n */\nexport interface BlimuConfig<TRequest = unknown> {\n  global?: boolean | undefined;\n  /**\n   * The API secret key for authenticating with Blimu Runtime API\n   */\n  apiKey: string;\n\n  /**\n   * The base URL for the Blimu Runtime API\n   * @default 'https://api.blimu.dev'\n   */\n  baseURL?: string | undefined;\n\n  /**\n   * Environment ID for the Blimu environment\n   * This will be used in future versions for environment-specific configurations\n   */\n  environmentId?: string | undefined;\n\n  /**\n   * Request timeout in milliseconds\n   * @default 30000\n   */\n  timeoutMs?: number | undefined;\n\n  /**\n   * Function to extract user ID from the request\n   *\n   * This function is called by the EntitlementGuard to determine which user\n   * to check entitlements for. It should return the user ID as a string.\n   *\n   * @param request - The incoming HTTP request\n   * @returns The user ID as a string, or a Promise that resolves to the user ID\n   *\n   * @example\n   * ```typescript\n   * // Extract from JWT token in Authorization header\n   * getUserId: (req) => {\n   *   const token = req.headers.authorization?.replace('Bearer ', '');\n   *   const decoded = jwt.verify(token, secret);\n   *   return decoded.sub;\n   * }\n   *\n   * // Extract from request.user (common with Passport.js)\n   * getUserId: (req) => req.user?.id\n   *\n   * // Extract from custom header\n   * getUserId: (req) => req.headers['x-user-id']\n   * ```\n   */\n  getUserId: (request: TRequest) => string | Promise<string>;\n}\n\n/**\n * Injection token for Blimu configuration\n */\nexport const BLIMU_CONFIG = Symbol('BLIMU_CONFIG');\n"],"mappings":";AA2DO,IAAM,eAAe,uBAAO,cAAc;","names":[]}

package/dist/decorators/entitlement.decorator.cjs

@@ -0,0 +1,178 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/decorators/entitlement.decorator.ts
+var entitlement_decorator_exports = {};
+__export(entitlement_decorator_exports, {
+  Entitlement: () => Entitlement
+});
+module.exports = __toCommonJS(entitlement_decorator_exports);
+var import_common3 = require("@nestjs/common");
+
+// src/guards/entitlement.guard.ts
+var import_common2 = require("@nestjs/common");
+var import_reflect_metadata = require("reflect-metadata");
+
+// src/exceptions/blimu-forbidden.exception.ts
+var import_common = require("@nestjs/common");
+var BlimuForbiddenException = class _BlimuForbiddenException extends import_common.ForbiddenException {
+  /**
+   * The entitlement check result containing detailed failure information
+   */
+  entitlementResult;
+  /**
+   * The entitlement key that was checked
+   */
+  entitlementKey;
+  /**
+   * The resource ID that was checked
+   */
+  resourceId;
+  /**
+   * The user ID that was checked
+   */
+  userId;
+  constructor(entitlementResult, entitlementKey, resourceId, userId) {
+    const message = _BlimuForbiddenException.buildMessage(entitlementResult, entitlementKey);
+    super({
+      message,
+      entitlementResult,
+      entitlementKey,
+      resourceId,
+      userId
+    });
+    this.entitlementResult = entitlementResult;
+    this.entitlementKey = entitlementKey;
+    this.resourceId = resourceId;
+    this.userId = userId;
+  }
+  /**
+   * Builds a user-friendly error message from the entitlement check result
+   */
+  static buildMessage(result, entitlementKey) {
+    const reasons = [];
+    if (result.roles && !result.roles.allowed) {
+      reasons.push(
+        `Insufficient roles. Required: ${result.roles.allowedRoles?.join(", ") || "unknown"}. User has: ${result.roles.userRoles?.join(", ") || "none"}.`
+      );
+    }
+    if (result.plans && !result.plans.allowed) {
+      reasons.push(
+        `Plan restriction. Required plans: ${result.plans.allowedPlans?.join(", ") || "unknown"}. Current plan: ${result.plans.plan || "none"}.`
+      );
+    }
+    if (result.limit && !result.limit.allowed) {
+      reasons.push(`Usage limit exceeded. ${result.limit.reason || "Limit has been reached"}.`);
+    }
+    if (reasons.length === 0) {
+      return `Access denied for entitlement: ${entitlementKey}`;
+    }
+    return `Access denied for entitlement "${entitlementKey}": ${reasons.join(" ")}`;
+  }
+};
+
+// src/guards/entitlement.guard.ts
+var import_backend = require("@blimu/backend");
+
+// src/config/blimu.config.ts
+var BLIMU_CONFIG = /* @__PURE__ */ Symbol("BLIMU_CONFIG");
+
+// src/guards/entitlement.guard.ts
+var ENTITLEMENT_METADATA_KEY = /* @__PURE__ */ Symbol("entitlement");
+var SetEntitlementMetadata = (entitlementKey, getEntitlementInfo) => (0, import_common2.SetMetadata)(ENTITLEMENT_METADATA_KEY, {
+  entitlementKey,
+  getEntitlementInfo
+});
+var EntitlementGuard = class {
+  constructor(config, runtime) {
+    this.config = config;
+    this.runtime = runtime;
+  }
+  async canActivate(context) {
+    const request = context.switchToHttp().getRequest();
+    const handler = context.getHandler();
+    const metadata = Reflect.getMetadata(ENTITLEMENT_METADATA_KEY, handler);
+    if (!metadata) {
+      return true;
+    }
+    let userId;
+    try {
+      userId = await this.config.getUserId(request);
+    } catch {
+      throw new import_common2.ForbiddenException("Failed to extract user ID from request");
+    }
+    if (!userId) {
+      throw new import_common2.ForbiddenException("User ID is required for entitlement check");
+    }
+    const entitlementInfo = await metadata.getEntitlementInfo(request);
+    if (!entitlementInfo?.resourceId) {
+      throw new import_common2.ForbiddenException("Resource ID is required for entitlement check");
+    }
+    try {
+      const result = await this.runtime.entitlements.checkEntitlement({
+        userId,
+        entitlement: metadata.entitlementKey,
+        resourceId: entitlementInfo.resourceId,
+        ...entitlementInfo.amount !== void 0 ? { amount: entitlementInfo.amount } : {}
+      });
+      if (!result.allowed) {
+        throw new BlimuForbiddenException(
+          result,
+          metadata.entitlementKey,
+          entitlementInfo.resourceId,
+          userId
+        );
+      }
+      return true;
+    } catch (error) {
+      if (error instanceof BlimuForbiddenException || error instanceof import_common2.ForbiddenException) {
+        throw error;
+      }
+      console.error("Entitlement check failed:", error);
+      throw new import_common2.ForbiddenException("Failed to verify entitlements");
+    }
+  }
+};
+EntitlementGuard = __decorateClass([
+  (0, import_common2.Injectable)(),
+  __decorateParam(0, (0, import_common2.Inject)(BLIMU_CONFIG)),
+  __decorateParam(1, (0, import_common2.Inject)(import_backend.Blimu))
+], EntitlementGuard);
+
+// src/decorators/entitlement.decorator.ts
+var Entitlement = (entitlementKey, getEntitlementInfo) => {
+  return (0, import_common3.applyDecorators)(
+    SetEntitlementMetadata(entitlementKey, getEntitlementInfo),
+    (0, import_common3.UseGuards)(EntitlementGuard)
+  );
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Entitlement
+});
+//# sourceMappingURL=entitlement.decorator.cjs.map

package/dist/decorators/entitlement.decorator.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/decorators/entitlement.decorator.ts","../../src/guards/entitlement.guard.ts","../../src/exceptions/blimu-forbidden.exception.ts","../../src/config/blimu.config.ts"],"sourcesContent":["import { applyDecorators, UseGuards } from '@nestjs/common';\nimport {\n  EntitlementGuard,\n  SetEntitlementMetadata,\n  type EntitlementInfo,\n} from '../guards/entitlement.guard';\nimport type { EntitlementType } from '@blimu/types';\n\n/**\n * Decorator to check if the authenticated user has a specific entitlement on a resource.\n *\n * This decorator combines the entitlement metadata setting and guard application\n * to provide a clean, declarative way to protect routes with entitlement checks.\n *\n * @param entitlementKey - The entitlement key to check (e.g., 'brand:read', 'organization:create_workspace')\n * @param getEntitlementInfo - Function that returns entitlement information including resourceId and optionally amount for usage limits\n *\n * @example\n * Basic usage with path parameter:\n * ```typescript\n * @Get('/:resourceId')\n * @Entitlement('brand:read', (req) => ({ resourceId: req.params.resourceId }))\n * async getBrand(@Param('resourceId') resourceId: string) {\n *   // User is guaranteed to have 'brand:read' entitlement on this resource\n * }\n * ```\n *\n * @example\n * Using with typed parameters:\n * ```typescript\n * @Get('/:resourceType/:resourceId')\n * @Entitlement('workspace:delete', (req) => ({ resourceId: req.params.resourceId }))\n * async deleteResource(@Param() params: ResourceParamsDto) {\n *   // User is guaranteed to have 'workspace:delete' entitlement\n * }\n * ```\n *\n * @example\n * Complex resource ID extraction:\n * ```typescript\n * @Post('/organizations/:orgId/workspaces')\n * @Entitlement('organization:create_workspace', (req) => {\n *   const params = req.params as { orgId: string };\n *   return { resourceId: params.orgId };\n * })\n * async createWorkspace(@Param() params: CreateWorkspaceParamsDto, @Body() body: CreateWorkspaceDto) {\n *   // User is guaranteed to have 'organization:create_workspace' entitlement on the organization\n * }\n * ```\n *\n * @example\n * With usage limit consumption:\n * ```typescript\n * @Post('/api-calls')\n * @Entitlement('organization:make_api_call', (req) => ({\n *   resourceId: req.params.orgId,\n *   amount: req.body.apiCallsCount, // Amount to consume from usage limit\n * }))\n * async makeApiCalls(@Param('orgId') orgId: string, @Body() body: { apiCallsCount: number }) {\n *   // User is guaranteed to have 'organization:make_api_call' entitlement\n *   // and sufficient usage limit balance\n * }\n * ```\n *\n * @example\n * Async entitlement info extraction (e.g., from database):\n * ```typescript\n * @Delete('/items/:itemId')\n * @Entitlement('workspace:delete_item', async (req) => {\n *   // You could fetch the workspace ID from your database\n *   const item = await itemService.findById(req.params.itemId);\n *   return { resourceId: item.workspaceId };\n * })\n * async deleteItem(@Param('itemId') itemId: string) {\n *   // User is guaranteed to have 'workspace:delete_item' entitlement on the item's workspace\n * }\n * ```\n *\n * @example\n * Using with custom request type:\n * ```typescript\n * interface AuthenticatedRequest {\n *   user: { id: string; email: string };\n * }\n *\n * @Get('/:resourceId')\n * @Entitlement<AuthenticatedRequest>('brand:read', (req) => {\n *   // req is typed as AuthenticatedRequest, so req.user is properly typed\n *   console.log(req.user.email); // TypeScript knows this exists\n *   return { resourceId: req.params.resourceId };\n * })\n * async getBrand(@Param('resourceId') resourceId: string) {\n *   // User is guaranteed to have 'brand:read' entitlement on this resource\n * }\n * ```\n */\nexport const Entitlement = <TRequest = unknown>(\n  entitlementKey: EntitlementType,\n  getEntitlementInfo: (request: TRequest) => EntitlementInfo | Promise<EntitlementInfo>,\n): MethodDecorator => {\n  return applyDecorators(\n    SetEntitlementMetadata<TRequest>(entitlementKey, getEntitlementInfo),\n    UseGuards(EntitlementGuard),\n  );\n};\n","import {\n  type CanActivate,\n  type ExecutionContext,\n  ForbiddenException,\n  Injectable,\n  SetMetadata,\n  Inject,\n} from '@nestjs/common';\nimport 'reflect-metadata';\n\nimport type { EntitlementType } from '@blimu/types';\nimport { BlimuForbiddenException } from '../exceptions/blimu-forbidden.exception';\nimport { Blimu } from '@blimu/backend';\nimport { BLIMU_CONFIG, type BlimuConfig } from 'config/blimu.config';\n\nexport const ENTITLEMENT_KEY = 'entitlement';\nexport const ENTITLEMENT_METADATA_KEY = Symbol('entitlement');\n\n/**\n * Entitlement information returned by the getEntitlementInfo callback\n */\nexport interface EntitlementInfo {\n  resourceId: string;\n  amount?: number; // Amount to check against usage limit (for consumption)\n}\n\n/**\n * Metadata interface for entitlement checks\n */\nexport interface EntitlementMetadata<TRequest = unknown> {\n  entitlementKey: EntitlementType;\n  getEntitlementInfo: (request: TRequest) => EntitlementInfo | Promise<EntitlementInfo>;\n}\n\n/**\n * Sets entitlement metadata for a route handler\n * @internal This is used internally by the @Entitlement decorator\n */\nexport const SetEntitlementMetadata = <TRequest = unknown>(\n  entitlementKey: string,\n  getEntitlementInfo: (request: TRequest) => EntitlementInfo | Promise<EntitlementInfo>,\n): MethodDecorator =>\n  SetMetadata(ENTITLEMENT_METADATA_KEY, {\n    entitlementKey,\n    getEntitlementInfo,\n  } as EntitlementMetadata<TRequest>);\n\n/**\n * Guard that checks if the authenticated user has the required entitlement on a resource\n *\n * This guard automatically:\n * 1. Extracts the user from the request\n * 2. Extracts the resource ID using the provided extractor function\n * 3. Calls the Blimu Runtime API to check entitlements\n * 4. Allows or denies access based on the result\n */\n@Injectable()\nexport class EntitlementGuard<TRequest = unknown> implements CanActivate {\n  constructor(\n    @Inject(BLIMU_CONFIG)\n    private readonly config: BlimuConfig<TRequest>,\n    @Inject(Blimu)\n    private readonly runtime: Blimu,\n  ) {}\n\n  async canActivate(context: ExecutionContext): Promise<boolean> {\n    const request = context.switchToHttp().getRequest<TRequest>();\n    const handler = context.getHandler();\n    const metadata = Reflect.getMetadata(ENTITLEMENT_METADATA_KEY, handler) as\n      | EntitlementMetadata<TRequest>\n      | undefined;\n\n    if (!metadata) {\n      // No entitlement check required\n      return true;\n    }\n\n    // Extract user ID using the configured getUserId function\n    let userId: string;\n    try {\n      userId = await this.config.getUserId(request);\n    } catch {\n      throw new ForbiddenException('Failed to extract user ID from request');\n    }\n\n    if (!userId) {\n      throw new ForbiddenException('User ID is required for entitlement check');\n    }\n\n    // Extract entitlement info from request\n    const entitlementInfo = await metadata.getEntitlementInfo(request);\n\n    if (!entitlementInfo?.resourceId) {\n      throw new ForbiddenException('Resource ID is required for entitlement check');\n    }\n\n    try {\n      // Check entitlement\n      const result = await this.runtime.entitlements.checkEntitlement({\n        userId,\n        entitlement: metadata.entitlementKey,\n        resourceId: entitlementInfo.resourceId,\n        ...(entitlementInfo.amount !== undefined ? { amount: entitlementInfo.amount } : {}),\n      });\n\n      if (!result.allowed) {\n        throw new BlimuForbiddenException(\n          result,\n          metadata.entitlementKey,\n          entitlementInfo.resourceId,\n          userId,\n        );\n      }\n\n      return true;\n    } catch (error) {\n      if (error instanceof BlimuForbiddenException || error instanceof ForbiddenException) {\n        throw error;\n      }\n\n      // Log the error for debugging but don't expose internal details\n      console.error('Entitlement check failed:', error);\n      throw new ForbiddenException('Failed to verify entitlements');\n    }\n  }\n}\n","import { ForbiddenException } from '@nestjs/common';\nimport type { Schema } from '@blimu/backend';\nimport type { EntitlementType } from '@blimu/types';\n/**\n * Custom exception for Blimu entitlement check failures\n *\n * This exception extends NestJS's ForbiddenException and includes\n * the typed EntitlementCheckResult, providing detailed information\n * about why the entitlement check failed (roles, plans, limits, etc.)\n */\nexport class BlimuForbiddenException extends ForbiddenException {\n  /**\n   * The entitlement check result containing detailed failure information\n   */\n  public readonly entitlementResult: Schema.EntitlementCheckResult;\n\n  /**\n   * The entitlement key that was checked\n   */\n  public readonly entitlementKey: EntitlementType;\n\n  /**\n   * The resource ID that was checked\n   */\n  public readonly resourceId: string;\n\n  /**\n   * The user ID that was checked\n   */\n  public readonly userId: string;\n\n  constructor(\n    entitlementResult: Schema.EntitlementCheckResult,\n    entitlementKey: EntitlementType,\n    resourceId: string,\n    userId: string,\n  ) {\n    // Create a user-friendly message based on the failure reason\n    const message = BlimuForbiddenException.buildMessage(entitlementResult, entitlementKey);\n\n    super({\n      message,\n      entitlementResult,\n      entitlementKey,\n      resourceId,\n      userId,\n    });\n\n    this.entitlementResult = entitlementResult;\n    this.entitlementKey = entitlementKey;\n    this.resourceId = resourceId;\n    this.userId = userId;\n  }\n\n  /**\n   * Builds a user-friendly error message from the entitlement check result\n   */\n  private static buildMessage(\n    result: Schema.EntitlementCheckResult,\n    entitlementKey: EntitlementType,\n  ): string {\n    const reasons: string[] = [];\n\n    if (result.roles && !result.roles.allowed) {\n      reasons.push(\n        `Insufficient roles. Required: ${result.roles.allowedRoles?.join(', ') || 'unknown'}. User has: ${result.roles.userRoles?.join(', ') || 'none'}.`,\n      );\n    }\n\n    if (result.plans && !result.plans.allowed) {\n      reasons.push(\n        `Plan restriction. Required plans: ${result.plans.allowedPlans?.join(', ') || 'unknown'}. Current plan: ${result.plans.plan || 'none'}.`,\n      );\n    }\n\n    if (result.limit && !result.limit.allowed) {\n      reasons.push(`Usage limit exceeded. ${result.limit.reason || 'Limit has been reached'}.`);\n    }\n\n    if (reasons.length === 0) {\n      return `Access denied for entitlement: ${entitlementKey}`;\n    }\n\n    return `Access denied for entitlement \"${entitlementKey}\": ${reasons.join(' ')}`;\n  }\n}\n","/**\n * Configuration interface for Blimu NestJS integration\n */\nexport interface BlimuConfig<TRequest = unknown> {\n  global?: boolean | undefined;\n  /**\n   * The API secret key for authenticating with Blimu Runtime API\n   */\n  apiKey: string;\n\n  /**\n   * The base URL for the Blimu Runtime API\n   * @default 'https://api.blimu.dev'\n   */\n  baseURL?: string | undefined;\n\n  /**\n   * Environment ID for the Blimu environment\n   * This will be used in future versions for environment-specific configurations\n   */\n  environmentId?: string | undefined;\n\n  /**\n   * Request timeout in milliseconds\n   * @default 30000\n   */\n  timeoutMs?: number | undefined;\n\n  /**\n   * Function to extract user ID from the request\n   *\n   * This function is called by the EntitlementGuard to determine which user\n   * to check entitlements for. It should return the user ID as a string.\n   *\n   * @param request - The incoming HTTP request\n   * @returns The user ID as a string, or a Promise that resolves to the user ID\n   *\n   * @example\n   * ```typescript\n   * // Extract from JWT token in Authorization header\n   * getUserId: (req) => {\n   *   const token = req.headers.authorization?.replace('Bearer ', '');\n   *   const decoded = jwt.verify(token, secret);\n   *   return decoded.sub;\n   * }\n   *\n   * // Extract from request.user (common with Passport.js)\n   * getUserId: (req) => req.user?.id\n   *\n   * // Extract from custom header\n   * getUserId: (req) => req.headers['x-user-id']\n   * ```\n   */\n  getUserId: (request: TRequest) => string | Promise<string>;\n}\n\n/**\n * Injection token for Blimu configuration\n */\nexport const BLIMU_CONFIG = Symbol('BLIMU_CONFIG');\n"],"mappings":"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","names":["import_common","import_common"]}

package/dist/decorators/entitlement.decorator.d.cts

@@ -0,0 +1,9 @@
+import { EntitlementInfo } from '../guards/entitlement.guard.cjs';
+import { EntitlementType } from '@blimu/types';
+import '@nestjs/common';
+import '@blimu/backend';
+import '../config/blimu.config.cjs';
+
+declare const Entitlement: <TRequest = unknown>(entitlementKey: EntitlementType, getEntitlementInfo: (request: TRequest) => EntitlementInfo | Promise<EntitlementInfo>) => MethodDecorator;
+
+export { Entitlement };

package/dist/decorators/entitlement.decorator.d.ts

@@ -1,4 +1,9 @@
-import { EntitlementInfo } from '../guards/entitlement.guard';
-import type { EntitlementType } from '@blimu/types';
-export declare const Entitlement: <TRequest = any>(entitlementKey: EntitlementType, getEntitlementInfo: (request: TRequest) => EntitlementInfo | Promise<EntitlementInfo>) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
-//# sourceMappingURL=entitlement.decorator.d.ts.map
+import { EntitlementInfo } from '../guards/entitlement.guard.js';
+import { EntitlementType } from '@blimu/types';
+import '@nestjs/common';
+import '@blimu/backend';
+import '../config/blimu.config.js';
+
+declare const Entitlement: <TRequest = unknown>(entitlementKey: EntitlementType, getEntitlementInfo: (request: TRequest) => EntitlementInfo | Promise<EntitlementInfo>) => MethodDecorator;
+
+export { Entitlement };

package/dist/decorators/entitlement.decorator.mjs

@@ -0,0 +1,161 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/decorators/entitlement.decorator.ts
+import { applyDecorators, UseGuards } from "@nestjs/common";
+
+// src/guards/entitlement.guard.ts
+import {
+  ForbiddenException as ForbiddenException2,
+  Injectable,
+  SetMetadata,
+  Inject
+} from "@nestjs/common";
+import "reflect-metadata";
+
+// src/exceptions/blimu-forbidden.exception.ts
+import { ForbiddenException } from "@nestjs/common";
+var BlimuForbiddenException = class _BlimuForbiddenException extends ForbiddenException {
+  /**
+   * The entitlement check result containing detailed failure information
+   */
+  entitlementResult;
+  /**
+   * The entitlement key that was checked
+   */
+  entitlementKey;
+  /**
+   * The resource ID that was checked
+   */
+  resourceId;
+  /**
+   * The user ID that was checked
+   */
+  userId;
+  constructor(entitlementResult, entitlementKey, resourceId, userId) {
+    const message = _BlimuForbiddenException.buildMessage(entitlementResult, entitlementKey);
+    super({
+      message,
+      entitlementResult,
+      entitlementKey,
+      resourceId,
+      userId
+    });
+    this.entitlementResult = entitlementResult;
+    this.entitlementKey = entitlementKey;
+    this.resourceId = resourceId;
+    this.userId = userId;
+  }
+  /**
+   * Builds a user-friendly error message from the entitlement check result
+   */
+  static buildMessage(result, entitlementKey) {
+    const reasons = [];
+    if (result.roles && !result.roles.allowed) {
+      reasons.push(
+        `Insufficient roles. Required: ${result.roles.allowedRoles?.join(", ") || "unknown"}. User has: ${result.roles.userRoles?.join(", ") || "none"}.`
+      );
+    }
+    if (result.plans && !result.plans.allowed) {
+      reasons.push(
+        `Plan restriction. Required plans: ${result.plans.allowedPlans?.join(", ") || "unknown"}. Current plan: ${result.plans.plan || "none"}.`
+      );
+    }
+    if (result.limit && !result.limit.allowed) {
+      reasons.push(`Usage limit exceeded. ${result.limit.reason || "Limit has been reached"}.`);
+    }
+    if (reasons.length === 0) {
+      return `Access denied for entitlement: ${entitlementKey}`;
+    }
+    return `Access denied for entitlement "${entitlementKey}": ${reasons.join(" ")}`;
+  }
+};
+
+// src/guards/entitlement.guard.ts
+import { Blimu } from "@blimu/backend";
+
+// src/config/blimu.config.ts
+var BLIMU_CONFIG = /* @__PURE__ */ Symbol("BLIMU_CONFIG");
+
+// src/guards/entitlement.guard.ts
+var ENTITLEMENT_METADATA_KEY = /* @__PURE__ */ Symbol("entitlement");
+var SetEntitlementMetadata = (entitlementKey, getEntitlementInfo) => SetMetadata(ENTITLEMENT_METADATA_KEY, {
+  entitlementKey,
+  getEntitlementInfo
+});
+var EntitlementGuard = class {
+  constructor(config, runtime) {
+    this.config = config;
+    this.runtime = runtime;
+  }
+  async canActivate(context) {
+    const request = context.switchToHttp().getRequest();
+    const handler = context.getHandler();
+    const metadata = Reflect.getMetadata(ENTITLEMENT_METADATA_KEY, handler);
+    if (!metadata) {
+      return true;
+    }
+    let userId;
+    try {
+      userId = await this.config.getUserId(request);
+    } catch {
+      throw new ForbiddenException2("Failed to extract user ID from request");
+    }
+    if (!userId) {
+      throw new ForbiddenException2("User ID is required for entitlement check");
+    }
+    const entitlementInfo = await metadata.getEntitlementInfo(request);
+    if (!entitlementInfo?.resourceId) {
+      throw new ForbiddenException2("Resource ID is required for entitlement check");
+    }
+    try {
+      const result = await this.runtime.entitlements.checkEntitlement({
+        userId,
+        entitlement: metadata.entitlementKey,
+        resourceId: entitlementInfo.resourceId,
+        ...entitlementInfo.amount !== void 0 ? { amount: entitlementInfo.amount } : {}
+      });
+      if (!result.allowed) {
+        throw new BlimuForbiddenException(
+          result,
+          metadata.entitlementKey,
+          entitlementInfo.resourceId,
+          userId
+        );
+      }
+      return true;
+    } catch (error) {
+      if (error instanceof BlimuForbiddenException || error instanceof ForbiddenException2) {
+        throw error;
+      }
+      console.error("Entitlement check failed:", error);
+      throw new ForbiddenException2("Failed to verify entitlements");
+    }
+  }
+};
+EntitlementGuard = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(BLIMU_CONFIG)),
+  __decorateParam(1, Inject(Blimu))
+], EntitlementGuard);
+
+// src/decorators/entitlement.decorator.ts
+var Entitlement = (entitlementKey, getEntitlementInfo) => {
+  return applyDecorators(
+    SetEntitlementMetadata(entitlementKey, getEntitlementInfo),
+    UseGuards(EntitlementGuard)
+  );
+};
+export {
+  Entitlement
+};
+//# sourceMappingURL=entitlement.decorator.mjs.map

package/dist/decorators/entitlement.decorator.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/decorators/entitlement.decorator.ts","../../src/guards/entitlement.guard.ts","../../src/exceptions/blimu-forbidden.exception.ts","../../src/config/blimu.config.ts"],"sourcesContent":["import { applyDecorators, UseGuards } from '@nestjs/common';\nimport {\n  EntitlementGuard,\n  SetEntitlementMetadata,\n  type EntitlementInfo,\n} from '../guards/entitlement.guard';\nimport type { EntitlementType } from '@blimu/types';\n\n/**\n * Decorator to check if the authenticated user has a specific entitlement on a resource.\n *\n * This decorator combines the entitlement metadata setting and guard application\n * to provide a clean, declarative way to protect routes with entitlement checks.\n *\n * @param entitlementKey - The entitlement key to check (e.g., 'brand:read', 'organization:create_workspace')\n * @param getEntitlementInfo - Function that returns entitlement information including resourceId and optionally amount for usage limits\n *\n * @example\n * Basic usage with path parameter:\n * ```typescript\n * @Get('/:resourceId')\n * @Entitlement('brand:read', (req) => ({ resourceId: req.params.resourceId }))\n * async getBrand(@Param('resourceId') resourceId: string) {\n *   // User is guaranteed to have 'brand:read' entitlement on this resource\n * }\n * ```\n *\n * @example\n * Using with typed parameters:\n * ```typescript\n * @Get('/:resourceType/:resourceId')\n * @Entitlement('workspace:delete', (req) => ({ resourceId: req.params.resourceId }))\n * async deleteResource(@Param() params: ResourceParamsDto) {\n *   // User is guaranteed to have 'workspace:delete' entitlement\n * }\n * ```\n *\n * @example\n * Complex resource ID extraction:\n * ```typescript\n * @Post('/organizations/:orgId/workspaces')\n * @Entitlement('organization:create_workspace', (req) => {\n *   const params = req.params as { orgId: string };\n *   return { resourceId: params.orgId };\n * })\n * async createWorkspace(@Param() params: CreateWorkspaceParamsDto, @Body() body: CreateWorkspaceDto) {\n *   // User is guaranteed to have 'organization:create_workspace' entitlement on the organization\n * }\n * ```\n *\n * @example\n * With usage limit consumption:\n * ```typescript\n * @Post('/api-calls')\n * @Entitlement('organization:make_api_call', (req) => ({\n *   resourceId: req.params.orgId,\n *   amount: req.body.apiCallsCount, // Amount to consume from usage limit\n * }))\n * async makeApiCalls(@Param('orgId') orgId: string, @Body() body: { apiCallsCount: number }) {\n *   // User is guaranteed to have 'organization:make_api_call' entitlement\n *   // and sufficient usage limit balance\n * }\n * ```\n *\n * @example\n * Async entitlement info extraction (e.g., from database):\n * ```typescript\n * @Delete('/items/:itemId')\n * @Entitlement('workspace:delete_item', async (req) => {\n *   // You could fetch the workspace ID from your database\n *   const item = await itemService.findById(req.params.itemId);\n *   return { resourceId: item.workspaceId };\n * })\n * async deleteItem(@Param('itemId') itemId: string) {\n *   // User is guaranteed to have 'workspace:delete_item' entitlement on the item's workspace\n * }\n * ```\n *\n * @example\n * Using with custom request type:\n * ```typescript\n * interface AuthenticatedRequest {\n *   user: { id: string; email: string };\n * }\n *\n * @Get('/:resourceId')\n * @Entitlement<AuthenticatedRequest>('brand:read', (req) => {\n *   // req is typed as AuthenticatedRequest, so req.user is properly typed\n *   console.log(req.user.email); // TypeScript knows this exists\n *   return { resourceId: req.params.resourceId };\n * })\n * async getBrand(@Param('resourceId') resourceId: string) {\n *   // User is guaranteed to have 'brand:read' entitlement on this resource\n * }\n * ```\n */\nexport const Entitlement = <TRequest = unknown>(\n  entitlementKey: EntitlementType,\n  getEntitlementInfo: (request: TRequest) => EntitlementInfo | Promise<EntitlementInfo>,\n): MethodDecorator => {\n  return applyDecorators(\n    SetEntitlementMetadata<TRequest>(entitlementKey, getEntitlementInfo),\n    UseGuards(EntitlementGuard),\n  );\n};\n","import {\n  type CanActivate,\n  type ExecutionContext,\n  ForbiddenException,\n  Injectable,\n  SetMetadata,\n  Inject,\n} from '@nestjs/common';\nimport 'reflect-metadata';\n\nimport type { EntitlementType } from '@blimu/types';\nimport { BlimuForbiddenException } from '../exceptions/blimu-forbidden.exception';\nimport { Blimu } from '@blimu/backend';\nimport { BLIMU_CONFIG, type BlimuConfig } from 'config/blimu.config';\n\nexport const ENTITLEMENT_KEY = 'entitlement';\nexport const ENTITLEMENT_METADATA_KEY = Symbol('entitlement');\n\n/**\n * Entitlement information returned by the getEntitlementInfo callback\n */\nexport interface EntitlementInfo {\n  resourceId: string;\n  amount?: number; // Amount to check against usage limit (for consumption)\n}\n\n/**\n * Metadata interface for entitlement checks\n */\nexport interface EntitlementMetadata<TRequest = unknown> {\n  entitlementKey: EntitlementType;\n  getEntitlementInfo: (request: TRequest) => EntitlementInfo | Promise<EntitlementInfo>;\n}\n\n/**\n * Sets entitlement metadata for a route handler\n * @internal This is used internally by the @Entitlement decorator\n */\nexport const SetEntitlementMetadata = <TRequest = unknown>(\n  entitlementKey: string,\n  getEntitlementInfo: (request: TRequest) => EntitlementInfo | Promise<EntitlementInfo>,\n): MethodDecorator =>\n  SetMetadata(ENTITLEMENT_METADATA_KEY, {\n    entitlementKey,\n    getEntitlementInfo,\n  } as EntitlementMetadata<TRequest>);\n\n/**\n * Guard that checks if the authenticated user has the required entitlement on a resource\n *\n * This guard automatically:\n * 1. Extracts the user from the request\n * 2. Extracts the resource ID using the provided extractor function\n * 3. Calls the Blimu Runtime API to check entitlements\n * 4. Allows or denies access based on the result\n */\n@Injectable()\nexport class EntitlementGuard<TRequest = unknown> implements CanActivate {\n  constructor(\n    @Inject(BLIMU_CONFIG)\n    private readonly config: BlimuConfig<TRequest>,\n    @Inject(Blimu)\n    private readonly runtime: Blimu,\n  ) {}\n\n  async canActivate(context: ExecutionContext): Promise<boolean> {\n    const request = context.switchToHttp().getRequest<TRequest>();\n    const handler = context.getHandler();\n    const metadata = Reflect.getMetadata(ENTITLEMENT_METADATA_KEY, handler) as\n      | EntitlementMetadata<TRequest>\n      | undefined;\n\n    if (!metadata) {\n      // No entitlement check required\n      return true;\n    }\n\n    // Extract user ID using the configured getUserId function\n    let userId: string;\n    try {\n      userId = await this.config.getUserId(request);\n    } catch {\n      throw new ForbiddenException('Failed to extract user ID from request');\n    }\n\n    if (!userId) {\n      throw new ForbiddenException('User ID is required for entitlement check');\n    }\n\n    // Extract entitlement info from request\n    const entitlementInfo = await metadata.getEntitlementInfo(request);\n\n    if (!entitlementInfo?.resourceId) {\n      throw new ForbiddenException('Resource ID is required for entitlement check');\n    }\n\n    try {\n      // Check entitlement\n      const result = await this.runtime.entitlements.checkEntitlement({\n        userId,\n        entitlement: metadata.entitlementKey,\n        resourceId: entitlementInfo.resourceId,\n        ...(entitlementInfo.amount !== undefined ? { amount: entitlementInfo.amount } : {}),\n      });\n\n      if (!result.allowed) {\n        throw new BlimuForbiddenException(\n          result,\n          metadata.entitlementKey,\n          entitlementInfo.resourceId,\n          userId,\n        );\n      }\n\n      return true;\n    } catch (error) {\n      if (error instanceof BlimuForbiddenException || error instanceof ForbiddenException) {\n        throw error;\n      }\n\n      // Log the error for debugging but don't expose internal details\n      console.error('Entitlement check failed:', error);\n      throw new ForbiddenException('Failed to verify entitlements');\n    }\n  }\n}\n","import { ForbiddenException } from '@nestjs/common';\nimport type { Schema } from '@blimu/backend';\nimport type { EntitlementType } from '@blimu/types';\n/**\n * Custom exception for Blimu entitlement check failures\n *\n * This exception extends NestJS's ForbiddenException and includes\n * the typed EntitlementCheckResult, providing detailed information\n * about why the entitlement check failed (roles, plans, limits, etc.)\n */\nexport class BlimuForbiddenException extends ForbiddenException {\n  /**\n   * The entitlement check result containing detailed failure information\n   */\n  public readonly entitlementResult: Schema.EntitlementCheckResult;\n\n  /**\n   * The entitlement key that was checked\n   */\n  public readonly entitlementKey: EntitlementType;\n\n  /**\n   * The resource ID that was checked\n   */\n  public readonly resourceId: string;\n\n  /**\n   * The user ID that was checked\n   */\n  public readonly userId: string;\n\n  constructor(\n    entitlementResult: Schema.EntitlementCheckResult,\n    entitlementKey: EntitlementType,\n    resourceId: string,\n    userId: string,\n  ) {\n    // Create a user-friendly message based on the failure reason\n    const message = BlimuForbiddenException.buildMessage(entitlementResult, entitlementKey);\n\n    super({\n      message,\n      entitlementResult,\n      entitlementKey,\n      resourceId,\n      userId,\n    });\n\n    this.entitlementResult = entitlementResult;\n    this.entitlementKey = entitlementKey;\n    this.resourceId = resourceId;\n    this.userId = userId;\n  }\n\n  /**\n   * Builds a user-friendly error message from the entitlement check result\n   */\n  private static buildMessage(\n    result: Schema.EntitlementCheckResult,\n    entitlementKey: EntitlementType,\n  ): string {\n    const reasons: string[] = [];\n\n    if (result.roles && !result.roles.allowed) {\n      reasons.push(\n        `Insufficient roles. Required: ${result.roles.allowedRoles?.join(', ') || 'unknown'}. User has: ${result.roles.userRoles?.join(', ') || 'none'}.`,\n      );\n    }\n\n    if (result.plans && !result.plans.allowed) {\n      reasons.push(\n        `Plan restriction. Required plans: ${result.plans.allowedPlans?.join(', ') || 'unknown'}. Current plan: ${result.plans.plan || 'none'}.`,\n      );\n    }\n\n    if (result.limit && !result.limit.allowed) {\n      reasons.push(`Usage limit exceeded. ${result.limit.reason || 'Limit has been reached'}.`);\n    }\n\n    if (reasons.length === 0) {\n      return `Access denied for entitlement: ${entitlementKey}`;\n    }\n\n    return `Access denied for entitlement \"${entitlementKey}\": ${reasons.join(' ')}`;\n  }\n}\n","/**\n * Configuration interface for Blimu NestJS integration\n */\nexport interface BlimuConfig<TRequest = unknown> {\n  global?: boolean | undefined;\n  /**\n   * The API secret key for authenticating with Blimu Runtime API\n   */\n  apiKey: string;\n\n  /**\n   * The base URL for the Blimu Runtime API\n   * @default 'https://api.blimu.dev'\n   */\n  baseURL?: string | undefined;\n\n  /**\n   * Environment ID for the Blimu environment\n   * This will be used in future versions for environment-specific configurations\n   */\n  environmentId?: string | undefined;\n\n  /**\n   * Request timeout in milliseconds\n   * @default 30000\n   */\n  timeoutMs?: number | undefined;\n\n  /**\n   * Function to extract user ID from the request\n   *\n   * This function is called by the EntitlementGuard to determine which user\n   * to check entitlements for. It should return the user ID as a string.\n   *\n   * @param request - The incoming HTTP request\n   * @returns The user ID as a string, or a Promise that resolves to the user ID\n   *\n   * @example\n   * ```typescript\n   * // Extract from JWT token in Authorization header\n   * getUserId: (req) => {\n   *   const token = req.headers.authorization?.replace('Bearer ', '');\n   *   const decoded = jwt.verify(token, secret);\n   *   return decoded.sub;\n   * }\n   *\n   * // Extract from request.user (common with Passport.js)\n   * getUserId: (req) => req.user?.id\n   *\n   * // Extract from custom header\n   * getUserId: (req) => req.headers['x-user-id']\n   * ```\n   */\n  getUserId: (request: TRequest) => string | Promise<string>;\n}\n\n/**\n * Injection token for Blimu configuration\n */\nexport const BLIMU_CONFIG = Symbol('BLIMU_CONFIG');\n"],"mappings":"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","names":["ForbiddenException","ForbiddenException"]}

package/dist/exceptions/blimu-forbidden.exception.cjs

@@ -0,0 +1,86 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/exceptions/blimu-forbidden.exception.ts
+var blimu_forbidden_exception_exports = {};
+__export(blimu_forbidden_exception_exports, {
+  BlimuForbiddenException: () => BlimuForbiddenException
+});
+module.exports = __toCommonJS(blimu_forbidden_exception_exports);
+var import_common = require("@nestjs/common");
+var BlimuForbiddenException = class _BlimuForbiddenException extends import_common.ForbiddenException {
+  /**
+   * The entitlement check result containing detailed failure information
+   */
+  entitlementResult;
+  /**
+   * The entitlement key that was checked
+   */
+  entitlementKey;
+  /**
+   * The resource ID that was checked
+   */
+  resourceId;
+  /**
+   * The user ID that was checked
+   */
+  userId;
+  constructor(entitlementResult, entitlementKey, resourceId, userId) {
+    const message = _BlimuForbiddenException.buildMessage(entitlementResult, entitlementKey);
+    super({
+      message,
+      entitlementResult,
+      entitlementKey,
+      resourceId,
+      userId
+    });
+    this.entitlementResult = entitlementResult;
+    this.entitlementKey = entitlementKey;
+    this.resourceId = resourceId;
+    this.userId = userId;
+  }
+  /**
+   * Builds a user-friendly error message from the entitlement check result
+   */
+  static buildMessage(result, entitlementKey) {
+    const reasons = [];
+    if (result.roles && !result.roles.allowed) {
+      reasons.push(
+        `Insufficient roles. Required: ${result.roles.allowedRoles?.join(", ") || "unknown"}. User has: ${result.roles.userRoles?.join(", ") || "none"}.`
+      );
+    }
+    if (result.plans && !result.plans.allowed) {
+      reasons.push(
+        `Plan restriction. Required plans: ${result.plans.allowedPlans?.join(", ") || "unknown"}. Current plan: ${result.plans.plan || "none"}.`
+      );
+    }
+    if (result.limit && !result.limit.allowed) {
+      reasons.push(`Usage limit exceeded. ${result.limit.reason || "Limit has been reached"}.`);
+    }
+    if (reasons.length === 0) {
+      return `Access denied for entitlement: ${entitlementKey}`;
+    }
+    return `Access denied for entitlement "${entitlementKey}": ${reasons.join(" ")}`;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BlimuForbiddenException
+});
+//# sourceMappingURL=blimu-forbidden.exception.cjs.map

package/dist/exceptions/blimu-forbidden.exception.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/exceptions/blimu-forbidden.exception.ts"],"sourcesContent":["import { ForbiddenException } from '@nestjs/common';\nimport type { Schema } from '@blimu/backend';\nimport type { EntitlementType } from '@blimu/types';\n/**\n * Custom exception for Blimu entitlement check failures\n *\n * This exception extends NestJS's ForbiddenException and includes\n * the typed EntitlementCheckResult, providing detailed information\n * about why the entitlement check failed (roles, plans, limits, etc.)\n */\nexport class BlimuForbiddenException extends ForbiddenException {\n  /**\n   * The entitlement check result containing detailed failure information\n   */\n  public readonly entitlementResult: Schema.EntitlementCheckResult;\n\n  /**\n   * The entitlement key that was checked\n   */\n  public readonly entitlementKey: EntitlementType;\n\n  /**\n   * The resource ID that was checked\n   */\n  public readonly resourceId: string;\n\n  /**\n   * The user ID that was checked\n   */\n  public readonly userId: string;\n\n  constructor(\n    entitlementResult: Schema.EntitlementCheckResult,\n    entitlementKey: EntitlementType,\n    resourceId: string,\n    userId: string,\n  ) {\n    // Create a user-friendly message based on the failure reason\n    const message = BlimuForbiddenException.buildMessage(entitlementResult, entitlementKey);\n\n    super({\n      message,\n      entitlementResult,\n      entitlementKey,\n      resourceId,\n      userId,\n    });\n\n    this.entitlementResult = entitlementResult;\n    this.entitlementKey = entitlementKey;\n    this.resourceId = resourceId;\n    this.userId = userId;\n  }\n\n  /**\n   * Builds a user-friendly error message from the entitlement check result\n   */\n  private static buildMessage(\n    result: Schema.EntitlementCheckResult,\n    entitlementKey: EntitlementType,\n  ): string {\n    const reasons: string[] = [];\n\n    if (result.roles && !result.roles.allowed) {\n      reasons.push(\n        `Insufficient roles. Required: ${result.roles.allowedRoles?.join(', ') || 'unknown'}. User has: ${result.roles.userRoles?.join(', ') || 'none'}.`,\n      );\n    }\n\n    if (result.plans && !result.plans.allowed) {\n      reasons.push(\n        `Plan restriction. Required plans: ${result.plans.allowedPlans?.join(', ') || 'unknown'}. Current plan: ${result.plans.plan || 'none'}.`,\n      );\n    }\n\n    if (result.limit && !result.limit.allowed) {\n      reasons.push(`Usage limit exceeded. ${result.limit.reason || 'Limit has been reached'}.`);\n    }\n\n    if (reasons.length === 0) {\n      return `Access denied for entitlement: ${entitlementKey}`;\n    }\n\n    return `Access denied for entitlement \"${entitlementKey}\": ${reasons.join(' ')}`;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,oBAAmC;AAU5B,IAAM,0BAAN,MAAM,iCAAgC,iCAAmB;AAAA;AAAA;AAAA;AAAA,EAI9C;AAAA;AAAA;AAAA;AAAA,EAKA;AAAA;AAAA;AAAA;AAAA,EAKA;AAAA;AAAA;AAAA;AAAA,EAKA;AAAA,EAEhB,YACE,mBACA,gBACA,YACA,QACA;AAEA,UAAM,UAAU,yBAAwB,aAAa,mBAAmB,cAAc;AAEtF,UAAM;AAAA,MACJ;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AAED,SAAK,oBAAoB;AACzB,SAAK,iBAAiB;AACtB,SAAK,aAAa;AAClB,SAAK,SAAS;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA,EAKA,OAAe,aACb,QACA,gBACQ;AACR,UAAM,UAAoB,CAAC;AAE3B,QAAI,OAAO,SAAS,CAAC,OAAO,MAAM,SAAS;AACzC,cAAQ;AAAA,QACN,iCAAiC,OAAO,MAAM,cAAc,KAAK,IAAI,KAAK,SAAS,eAAe,OAAO,MAAM,WAAW,KAAK,IAAI,KAAK,MAAM;AAAA,MAChJ;AAAA,IACF;AAEA,QAAI,OAAO,SAAS,CAAC,OAAO,MAAM,SAAS;AACzC,cAAQ;AAAA,QACN,qCAAqC,OAAO,MAAM,cAAc,KAAK,IAAI,KAAK,SAAS,mBAAmB,OAAO,MAAM,QAAQ,MAAM;AAAA,MACvI;AAAA,IACF;AAEA,QAAI,OAAO,SAAS,CAAC,OAAO,MAAM,SAAS;AACzC,cAAQ,KAAK,yBAAyB,OAAO,MAAM,UAAU,wBAAwB,GAAG;AAAA,IAC1F;AAEA,QAAI,QAAQ,WAAW,GAAG;AACxB,aAAO,kCAAkC,cAAc;AAAA,IACzD;AAEA,WAAO,kCAAkC,cAAc,MAAM,QAAQ,KAAK,GAAG,CAAC;AAAA,EAChF;AACF;","names":[]}

package/dist/exceptions/blimu-forbidden.exception.d.cts

@@ -0,0 +1,14 @@
+import { ForbiddenException } from '@nestjs/common';
+import { Schema } from '@blimu/backend';
+import { EntitlementType } from '@blimu/types';
+
+declare class BlimuForbiddenException extends ForbiddenException {
+    readonly entitlementResult: Schema.EntitlementCheckResult;
+    readonly entitlementKey: EntitlementType;
+    readonly resourceId: string;
+    readonly userId: string;
+    constructor(entitlementResult: Schema.EntitlementCheckResult, entitlementKey: EntitlementType, resourceId: string, userId: string);
+    private static buildMessage;
+}
+
+export { BlimuForbiddenException };