@breadstone/archipel-platform-feature-flags 0.0.32

package/src/guards/FeatureFlagGuard.d.ts

@@ -0,0 +1,30 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { FeatureFlagReaderPort } from '../contracts/FeatureFlagReaderPort';
+/**
+ * Guard that checks if a feature flag is enabled before allowing access to a route.
+ * Use the {@link FeatureFlag} decorator to specify which flag to check.
+ *
+ * @public
+ */
+export declare class FeatureFlagGuard implements CanActivate {
+    private readonly _featureFlagReader;
+    private readonly _reflector;
+    private readonly _logger;
+    /**
+     * Constructs a new instance of the `FeatureFlagGuard` class.
+     *
+     * @public
+     * @param featureFlagReader - The feature flag reader port.
+     * @param reflector - The NestJS reflector.
+     */
+    constructor(featureFlagReader: FeatureFlagReaderPort, reflector: Reflector);
+    /**
+     * Determines whether the guarded feature flag is enabled.
+     *
+     * @public
+     * @param context - The execution context.
+     * @returns `true` when the feature flag is enabled and access is allowed.
+     */
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}

package/src/guards/FeatureFlagGuard.js

@@ -0,0 +1,69 @@
+"use strict";
+// #region Imports
+var FeatureFlagGuard_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeatureFlagGuard = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const FeatureFlagReaderPort_1 = require("../contracts/FeatureFlagReaderPort");
+const FeatureFlag_1 = require("../decorators/FeatureFlag");
+// #endregion
+/**
+ * Guard that checks if a feature flag is enabled before allowing access to a route.
+ * Use the {@link FeatureFlag} decorator to specify which flag to check.
+ *
+ * @public
+ */
+let FeatureFlagGuard = FeatureFlagGuard_1 = class FeatureFlagGuard {
+    // #endregion
+    // #region Ctor
+    /**
+     * Constructs a new instance of the `FeatureFlagGuard` class.
+     *
+     * @public
+     * @param featureFlagReader - The feature flag reader port.
+     * @param reflector - The NestJS reflector.
+     */
+    constructor(featureFlagReader, reflector) {
+        this._logger = new common_1.Logger(FeatureFlagGuard_1.name);
+        this._featureFlagReader = featureFlagReader;
+        this._reflector = reflector;
+    }
+    // #endregion
+    // #region Methods
+    /**
+     * Determines whether the guarded feature flag is enabled.
+     *
+     * @public
+     * @param context - The execution context.
+     * @returns `true` when the feature flag is enabled and access is allowed.
+     */
+    async canActivate(context) {
+        const flagKey = this._reflector.get(FeatureFlag_1.FEATURE_FLAG_KEY_METADATA, context.getHandler());
+        if (!flagKey) {
+            return true;
+        }
+        try {
+            const request = context.switchToHttp().getRequest();
+            const user = request.user;
+            const isEnabled = await this._featureFlagReader.isEnabled(flagKey, {
+                userId: user?.id,
+            });
+            return isEnabled;
+        }
+        catch (error) {
+            this._logger.error(`[FeatureFlagGuard] Failed to evaluate flag "${flagKey}"`, {
+                flagKey,
+                error: error.message,
+            });
+            return false;
+        }
+    }
+};
+exports.FeatureFlagGuard = FeatureFlagGuard;
+exports.FeatureFlagGuard = FeatureFlagGuard = FeatureFlagGuard_1 = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__metadata("design:paramtypes", [FeatureFlagReaderPort_1.FeatureFlagReaderPort, core_1.Reflector])
+], FeatureFlagGuard);
+//# sourceMappingURL=FeatureFlagGuard.js.map

package/src/guards/index.d.ts

@@ -0,0 +1 @@
+export { FeatureFlagGuard } from './FeatureFlagGuard';

package/src/guards/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeatureFlagGuard = void 0;
+var FeatureFlagGuard_1 = require("./FeatureFlagGuard");
+Object.defineProperty(exports, "FeatureFlagGuard", { enumerable: true, get: function () { return FeatureFlagGuard_1.FeatureFlagGuard; } });
+//# sourceMappingURL=index.js.map

package/src/index.d.ts

@@ -0,0 +1,11 @@
+export { FeatureFlagReaderPort } from './contracts/FeatureFlagReaderPort';
+export { FeatureFlagWriterPort } from './contracts/FeatureFlagWriterPort';
+export { FEATURE_FLAG_KEY_METADATA, FeatureFlag } from './decorators/FeatureFlag';
+export { PLATFORM_FEATURE_FLAGS_CONFIG_ENTRIES } from './env';
+export { FeatureFlagError } from './errors/FeatureFlagError';
+export { FeatureFlagModule } from './FeatureFlagModule';
+export { FeatureFlagGuard } from './guards/FeatureFlagGuard';
+export type { IFeatureFlagContext } from './models/IFeatureFlagContext';
+export type { IFeatureFlagDefinition } from './models/IFeatureFlagDefinition';
+export type { IFeatureFlagEvaluation } from './models/IFeatureFlagEvaluation';
+export type { IFeatureFlagModuleOptions } from './models/IFeatureFlagModuleOptions';

package/src/index.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeatureFlagGuard = exports.FeatureFlagModule = exports.FeatureFlagError = exports.PLATFORM_FEATURE_FLAGS_CONFIG_ENTRIES = exports.FeatureFlag = exports.FEATURE_FLAG_KEY_METADATA = exports.FeatureFlagWriterPort = exports.FeatureFlagReaderPort = void 0;
+var FeatureFlagReaderPort_1 = require("./contracts/FeatureFlagReaderPort");
+Object.defineProperty(exports, "FeatureFlagReaderPort", { enumerable: true, get: function () { return FeatureFlagReaderPort_1.FeatureFlagReaderPort; } });
+var FeatureFlagWriterPort_1 = require("./contracts/FeatureFlagWriterPort");
+Object.defineProperty(exports, "FeatureFlagWriterPort", { enumerable: true, get: function () { return FeatureFlagWriterPort_1.FeatureFlagWriterPort; } });
+var FeatureFlag_1 = require("./decorators/FeatureFlag");
+Object.defineProperty(exports, "FEATURE_FLAG_KEY_METADATA", { enumerable: true, get: function () { return FeatureFlag_1.FEATURE_FLAG_KEY_METADATA; } });
+Object.defineProperty(exports, "FeatureFlag", { enumerable: true, get: function () { return FeatureFlag_1.FeatureFlag; } });
+var env_1 = require("./env");
+Object.defineProperty(exports, "PLATFORM_FEATURE_FLAGS_CONFIG_ENTRIES", { enumerable: true, get: function () { return env_1.PLATFORM_FEATURE_FLAGS_CONFIG_ENTRIES; } });
+var FeatureFlagError_1 = require("./errors/FeatureFlagError");
+Object.defineProperty(exports, "FeatureFlagError", { enumerable: true, get: function () { return FeatureFlagError_1.FeatureFlagError; } });
+var FeatureFlagModule_1 = require("./FeatureFlagModule");
+Object.defineProperty(exports, "FeatureFlagModule", { enumerable: true, get: function () { return FeatureFlagModule_1.FeatureFlagModule; } });
+var FeatureFlagGuard_1 = require("./guards/FeatureFlagGuard");
+Object.defineProperty(exports, "FeatureFlagGuard", { enumerable: true, get: function () { return FeatureFlagGuard_1.FeatureFlagGuard; } });
+//# sourceMappingURL=index.js.map

package/src/models/IFeatureFlagContext.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Context passed to feature flag evaluation for targeting and segmentation.
+ *
+ * @public
+ */
+export interface IFeatureFlagContext {
+    /** Unique identifier of the current user. */
+    readonly userId?: string;
+    /** Groups or segments the user belongs to (e.g. beta testers, enterprise). */
+    readonly groups?: ReadonlyArray<string>;
+    /** Arbitrary attributes for custom targeting rules. */
+    readonly attributes?: Readonly<Record<string, unknown>>;
+}

package/src/models/IFeatureFlagContext.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IFeatureFlagContext.js.map

package/src/models/IFeatureFlagDefinition.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Represents a full feature flag definition for admin operations (create / update / read).
+ *
+ * @public
+ */
+export interface IFeatureFlagDefinition {
+    /** Unique key identifying the feature flag. */
+    readonly key: string;
+    /** Whether the feature flag is currently enabled. */
+    readonly enabled: boolean;
+    /** Optional human-readable description. */
+    readonly description?: string;
+    /** Optional label / environment tag (e.g. `"production"`, `"staging"`). */
+    readonly label?: string;
+    /** Optional variant value for multivariate flags. */
+    readonly variant?: unknown;
+}

package/src/models/IFeatureFlagDefinition.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IFeatureFlagDefinition.js.map

package/src/models/IFeatureFlagEvaluation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Result of evaluating a single feature flag.
+ *
+ * @public
+ */
+export interface IFeatureFlagEvaluation {
+    /** The unique key identifying the feature flag. */
+    readonly key: string;
+    /** Whether the feature flag is currently enabled. */
+    readonly enabled: boolean;
+    /** Optional variant value for multivariate flags / A/B testing. */
+    readonly variant?: unknown;
+}

package/src/models/IFeatureFlagEvaluation.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IFeatureFlagEvaluation.js.map

package/src/models/IFeatureFlagModuleOptions.d.ts

@@ -0,0 +1,30 @@
+import type { IConfigRegistryEntry } from '@breadstone/archipel-platform-configuration';
+import type { Type } from '@nestjs/common';
+import type { FeatureFlagReaderPort } from '../contracts/FeatureFlagReaderPort';
+import type { FeatureFlagWriterPort } from '../contracts/FeatureFlagWriterPort';
+/**
+ * Configuration options for the {@link FeatureFlagModule}.
+ *
+ * @public
+ */
+export interface IFeatureFlagModuleOptions {
+    /**
+     * Concrete implementation of the {@link FeatureFlagReaderPort}.
+     * For example, `AzureFeatureFlagReader` or `VercelFeatureFlagReader`.
+     */
+    readonly featureFlagReader: Type<FeatureFlagReaderPort>;
+    /**
+     * Optional concrete implementation of the {@link FeatureFlagWriterPort}.
+     * For example, `AzureFeatureFlagWriter` or `VercelFeatureFlagWriter`.
+     * When provided the module will also export the writer port for CRUD operations.
+     */
+    readonly featureFlagWriter?: Type<FeatureFlagWriterPort>;
+    /**
+     * Provider-specific configuration entries to register with the config module.
+     */
+    readonly configEntries?: ReadonlyArray<Omit<IConfigRegistryEntry, 'module'>>;
+    /**
+     * When `true` the module is registered globally.
+     */
+    readonly isGlobal?: boolean;
+}

package/src/models/IFeatureFlagModuleOptions.js

@@ -0,0 +1,4 @@
+"use strict";
+// #region Imports
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IFeatureFlagModuleOptions.js.map

package/src/models/index.d.ts

@@ -0,0 +1,4 @@
+export type { IFeatureFlagContext } from './IFeatureFlagContext';
+export type { IFeatureFlagDefinition } from './IFeatureFlagDefinition';
+export type { IFeatureFlagEvaluation } from './IFeatureFlagEvaluation';
+export type { IFeatureFlagModuleOptions } from './IFeatureFlagModuleOptions';

package/src/models/index.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/src/vercel/VercelFeatureFlagReader.d.ts

@@ -0,0 +1,54 @@
+import { ConfigService } from '@breadstone/archipel-platform-configuration';
+import { type OnModuleInit } from '@nestjs/common';
+import { FeatureFlagReaderPort } from '../contracts/FeatureFlagReaderPort';
+import type { IFeatureFlagContext } from '../models/IFeatureFlagContext';
+import type { IFeatureFlagEvaluation } from '../models/IFeatureFlagEvaluation';
+/**
+ * Vercel Edge Config implementation of the {@link FeatureFlagReaderPort}.
+ * Uses `@vercel/edge-config` for reading feature flag state from a Vercel Edge Config store.
+ *
+ * Feature flags are expected to be stored as a single object in Edge Config
+ * under the configured prefix key (default: `featureFlags`). The object maps
+ * flag keys to their values (boolean for simple on/off, or any value for variants).
+ *
+ * @example
+ * Edge Config structure:
+ * ```json
+ * {
+ *   "featureFlags": {
+ *     "new-checkout-flow": true,
+ *     "pricing-tier": "enterprise",
+ *     "max-upload-size": 100
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare class VercelFeatureFlagReader extends FeatureFlagReaderPort implements OnModuleInit {
+    private readonly _configService;
+    private readonly _logger;
+    private _edgeConfigClient;
+    private _flagPrefix;
+    constructor(configService: ConfigService);
+    /**
+     * Initializes the Vercel Edge Config client.
+     *
+     * @public
+     */
+    onModuleInit(): Promise<void>;
+    /** @inheritdoc */
+    isEnabled(key: string, _context?: IFeatureFlagContext): Promise<boolean>;
+    /** @inheritdoc */
+    getVariant<T = unknown>(key: string, defaultValue: T, _context?: IFeatureFlagContext): Promise<T>;
+    /** @inheritdoc */
+    getAllFlags(_context?: IFeatureFlagContext): Promise<ReadonlyArray<IFeatureFlagEvaluation>>;
+    /** @inheritdoc */
+    refresh(): Promise<void>;
+    /** @inheritdoc */
+    ping(): Promise<boolean>;
+    /**
+     * Ensures the Edge Config client has been initialized.
+     */
+    private ensureInitialized;
+}

package/src/vercel/VercelFeatureFlagReader.js

@@ -0,0 +1,158 @@
+"use strict";
+// #region Imports
+var VercelFeatureFlagReader_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VercelFeatureFlagReader = void 0;
+const tslib_1 = require("tslib");
+const archipel_platform_configuration_1 = require("@breadstone/archipel-platform-configuration");
+const common_1 = require("@nestjs/common");
+const edge_config_1 = require("@vercel/edge-config");
+const FeatureFlagReaderPort_1 = require("../contracts/FeatureFlagReaderPort");
+const FeatureFlagError_1 = require("../errors/FeatureFlagError");
+const env_1 = require("./env");
+// #endregion
+/** Default prefix for feature flag keys in Edge Config. */
+const DEFAULT_FLAG_PREFIX = 'featureFlags';
+/**
+ * Vercel Edge Config implementation of the {@link FeatureFlagReaderPort}.
+ * Uses `@vercel/edge-config` for reading feature flag state from a Vercel Edge Config store.
+ *
+ * Feature flags are expected to be stored as a single object in Edge Config
+ * under the configured prefix key (default: `featureFlags`). The object maps
+ * flag keys to their values (boolean for simple on/off, or any value for variants).
+ *
+ * @example
+ * Edge Config structure:
+ * ```json
+ * {
+ *   "featureFlags": {
+ *     "new-checkout-flow": true,
+ *     "pricing-tier": "enterprise",
+ *     "max-upload-size": 100
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+let VercelFeatureFlagReader = VercelFeatureFlagReader_1 = class VercelFeatureFlagReader extends FeatureFlagReaderPort_1.FeatureFlagReaderPort {
+    // #endregion
+    // #region Ctor
+    constructor(configService) {
+        super();
+        this._logger = new common_1.Logger(VercelFeatureFlagReader_1.name);
+        this._flagPrefix = DEFAULT_FLAG_PREFIX;
+        this._configService = configService;
+    }
+    // #endregion
+    // #region Methods
+    /**
+     * Initializes the Vercel Edge Config client.
+     *
+     * @public
+     */
+    async onModuleInit() {
+        try {
+            const connectionString = this._configService.get(env_1.VERCEL_EDGE_CONFIG.key);
+            if (!connectionString) {
+                throw new FeatureFlagError_1.FeatureFlagError('vercel', 'EDGE_CONFIG must be configured for the Vercel feature flag provider.');
+            }
+            this._edgeConfigClient = (0, edge_config_1.createClient)(connectionString);
+            this._flagPrefix = this._configService.get(env_1.VERCEL_FEATURE_FLAG_PREFIX.key) ?? DEFAULT_FLAG_PREFIX;
+            this._logger.log('[VercelFeatureFlagReader] Initialized successfully');
+        }
+        catch (error) {
+            if (error instanceof FeatureFlagError_1.FeatureFlagError) {
+                throw error;
+            }
+            throw new FeatureFlagError_1.FeatureFlagError('vercel', 'Failed to initialize Vercel Edge Config client', error);
+        }
+    }
+    /** @inheritdoc */
+    async isEnabled(key, _context) {
+        this.ensureInitialized();
+        try {
+            const flags = await this._edgeConfigClient.get(this._flagPrefix);
+            if (!flags || !(key in flags)) {
+                return false;
+            }
+            return Boolean(flags[key]);
+        }
+        catch (error) {
+            this._logger.error(`[VercelFeatureFlagReader] isEnabled failed for flag "${key}"`, {
+                key,
+                error: error.message,
+            });
+            throw new FeatureFlagError_1.FeatureFlagError('vercel', `Failed to evaluate feature flag "${key}"`, error);
+        }
+    }
+    /** @inheritdoc */
+    async getVariant(key, defaultValue, _context) {
+        this.ensureInitialized();
+        try {
+            const flags = await this._edgeConfigClient.get(this._flagPrefix);
+            if (!flags || !(key in flags)) {
+                return defaultValue;
+            }
+            return flags[key] ?? defaultValue;
+        }
+        catch (error) {
+            this._logger.error(`[VercelFeatureFlagReader] getVariant failed for flag "${key}"`, {
+                key,
+                error: error.message,
+            });
+            throw new FeatureFlagError_1.FeatureFlagError('vercel', `Failed to get variant for feature flag "${key}"`, error);
+        }
+    }
+    /** @inheritdoc */
+    async getAllFlags(_context) {
+        this.ensureInitialized();
+        try {
+            const flags = await this._edgeConfigClient.get(this._flagPrefix);
+            if (!flags) {
+                return [];
+            }
+            return Object.entries(flags).map(([key, value]) => ({
+                key,
+                enabled: Boolean(value),
+                variant: typeof value === 'boolean' ? undefined : value,
+            }));
+        }
+        catch (error) {
+            this._logger.error('[VercelFeatureFlagReader] getAllFlags failed', {
+                error: error.message,
+            });
+            throw new FeatureFlagError_1.FeatureFlagError('vercel', 'Failed to retrieve all feature flags', error);
+        }
+    }
+    /** @inheritdoc */
+    async refresh() {
+        // Vercel Edge Config is near-realtime and does not require explicit refresh.
+        // This method is a no-op but can be extended in the future if needed.
+    }
+    /** @inheritdoc */
+    async ping() {
+        try {
+            this.ensureInitialized();
+            await this._edgeConfigClient.digest();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Ensures the Edge Config client has been initialized.
+     */
+    ensureInitialized() {
+        if (!this._edgeConfigClient) {
+            throw new FeatureFlagError_1.FeatureFlagError('vercel', 'VercelFeatureFlagReader has not been initialized. Ensure onModuleInit() ran.');
+        }
+    }
+};
+exports.VercelFeatureFlagReader = VercelFeatureFlagReader;
+exports.VercelFeatureFlagReader = VercelFeatureFlagReader = VercelFeatureFlagReader_1 = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__metadata("design:paramtypes", [archipel_platform_configuration_1.ConfigService])
+], VercelFeatureFlagReader);
+//# sourceMappingURL=VercelFeatureFlagReader.js.map

package/src/vercel/VercelFeatureFlagWriter.d.ts

@@ -0,0 +1,71 @@
+import { ConfigService } from '@breadstone/archipel-platform-configuration';
+import { type OnModuleInit } from '@nestjs/common';
+import { FeatureFlagWriterPort } from '../contracts/FeatureFlagWriterPort';
+import type { IFeatureFlagDefinition } from '../models/IFeatureFlagDefinition';
+/**
+ * Vercel Edge Config implementation of the {@link FeatureFlagWriterPort}.
+ * Uses the Vercel REST API to manage feature flags stored in a Vercel Edge Config store.
+ *
+ * @remarks
+ * The Vercel admin client stores feature flags as a single object under the configured
+ * prefix key (default: `featureFlags`). Each flag key maps to a {@link IFeatureFlagDefinition}
+ * serialized as JSON.
+ *
+ * @public
+ */
+export declare class VercelFeatureFlagWriter extends FeatureFlagWriterPort implements OnModuleInit {
+    private readonly _configService;
+    private readonly _logger;
+    private _apiToken;
+    private _edgeConfigId;
+    private _teamId;
+    private _flagPrefix;
+    constructor(configService: ConfigService);
+    /**
+     * Initializes the Vercel admin client by reading configuration.
+     *
+     * @public
+     */
+    onModuleInit(): Promise<void>;
+    /** @inheritdoc */
+    getFlag(key: string): Promise<IFeatureFlagDefinition | undefined>;
+    /** @inheritdoc */
+    listFlags(): Promise<ReadonlyArray<IFeatureFlagDefinition>>;
+    /** @inheritdoc */
+    createFlag(definition: IFeatureFlagDefinition): Promise<void>;
+    /** @inheritdoc */
+    updateFlag(key: string, updates: Partial<Omit<IFeatureFlagDefinition, 'key'>>): Promise<void>;
+    /** @inheritdoc */
+    deleteFlag(key: string): Promise<void>;
+    /** @inheritdoc */
+    ping(): Promise<boolean>;
+    /**
+     * Reads the current flags object from Edge Config via the Vercel REST API.
+     */
+    private readFlagsFromEdgeConfig;
+    /**
+     * Writes the flags object to Edge Config via the Vercel REST API.
+     */
+    private writeFlagsToEdgeConfig;
+    /**
+     * Builds a full Vercel API URL, appending the team ID query parameter if configured.
+     */
+    private buildUrl;
+    /**
+     * Performs an HTTP request to the Vercel REST API with timeout and authorization.
+     */
+    private request;
+    /**
+     * Converts a stored value into an {@link IFeatureFlagDefinition}.
+     */
+    private toDefinition;
+    /**
+     * Converts an {@link IFeatureFlagDefinition} into the stored value shape.
+     * Simple boolean flags are stored as booleans; flags with metadata are stored as objects.
+     */
+    private toStoredValue;
+    /**
+     * Ensures the admin client has been initialized.
+     */
+    private ensureInitialized;
+}