@breadstone/archipel-platform-feature-flags 0.0.32

package/src/vercel/VercelFeatureFlagWriter.js

@@ -0,0 +1,308 @@
+"use strict";
+// #region Imports
+var VercelFeatureFlagWriter_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VercelFeatureFlagWriter = void 0;
+const tslib_1 = require("tslib");
+const archipel_platform_configuration_1 = require("@breadstone/archipel-platform-configuration");
+const common_1 = require("@nestjs/common");
+const FeatureFlagWriterPort_1 = require("../contracts/FeatureFlagWriterPort");
+const FeatureFlagError_1 = require("../errors/FeatureFlagError");
+const env_1 = require("./env");
+// #endregion
+/** Base URL for the Vercel REST API. */
+const VERCEL_API_BASE = 'https://api.vercel.com';
+/** Default prefix for feature flag keys in Edge Config. */
+const DEFAULT_FLAG_PREFIX = 'featureFlags';
+/** Default request timeout in milliseconds. */
+const DEFAULT_TIMEOUT_MS = 3_000;
+/**
+ * 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
+ */
+let VercelFeatureFlagWriter = VercelFeatureFlagWriter_1 = class VercelFeatureFlagWriter extends FeatureFlagWriterPort_1.FeatureFlagWriterPort {
+    // #endregion
+    // #region Ctor
+    constructor(configService) {
+        super();
+        this._logger = new common_1.Logger(VercelFeatureFlagWriter_1.name);
+        this._flagPrefix = DEFAULT_FLAG_PREFIX;
+        this._configService = configService;
+    }
+    // #endregion
+    // #region Methods
+    /**
+     * Initializes the Vercel admin client by reading configuration.
+     *
+     * @public
+     */
+    async onModuleInit() {
+        try {
+            this._apiToken = this._configService.get(env_1.VERCEL_API_TOKEN.key);
+            this._edgeConfigId = this._configService.get(env_1.VERCEL_EDGE_CONFIG_ID.key);
+            this._teamId = this._configService.get(env_1.VERCEL_TEAM_ID.key);
+            this._flagPrefix = this._configService.get(env_1.VERCEL_FEATURE_FLAG_PREFIX.key) ?? DEFAULT_FLAG_PREFIX;
+            if (!this._apiToken) {
+                throw new FeatureFlagError_1.FeatureFlagError('vercel', 'VERCEL_API_TOKEN must be configured for the Vercel admin client.');
+            }
+            if (!this._edgeConfigId) {
+                throw new FeatureFlagError_1.FeatureFlagError('vercel', 'VERCEL_EDGE_CONFIG_ID must be configured for the Vercel admin client.');
+            }
+            this._logger.log('[VercelFeatureFlagWriter] Initialized successfully');
+        }
+        catch (error) {
+            if (error instanceof FeatureFlagError_1.FeatureFlagError) {
+                throw error;
+            }
+            throw new FeatureFlagError_1.FeatureFlagError('vercel', 'Failed to initialize Vercel admin client', error);
+        }
+    }
+    /** @inheritdoc */
+    async getFlag(key) {
+        this.ensureInitialized();
+        try {
+            const flags = await this.readFlagsFromEdgeConfig();
+            if (!flags || !(key in flags)) {
+                return undefined;
+            }
+            return this.toDefinition(key, flags[key]);
+        }
+        catch (error) {
+            if (error instanceof FeatureFlagError_1.FeatureFlagError) {
+                throw error;
+            }
+            this._logger.error(`[VercelFeatureFlagWriter] getFlag failed for "${key}"`, {
+                key,
+                error: error.message,
+            });
+            throw new FeatureFlagError_1.FeatureFlagError('vercel', `Failed to get feature flag "${key}"`, error);
+        }
+    }
+    /** @inheritdoc */
+    async listFlags() {
+        this.ensureInitialized();
+        try {
+            const flags = await this.readFlagsFromEdgeConfig();
+            if (!flags) {
+                return [];
+            }
+            return Object.entries(flags).map(([key, value]) => this.toDefinition(key, value));
+        }
+        catch (error) {
+            if (error instanceof FeatureFlagError_1.FeatureFlagError) {
+                throw error;
+            }
+            this._logger.error('[VercelFeatureFlagWriter] listFlags failed', {
+                error: error.message,
+            });
+            throw new FeatureFlagError_1.FeatureFlagError('vercel', 'Failed to list feature flags', error);
+        }
+    }
+    /** @inheritdoc */
+    async createFlag(definition) {
+        this.ensureInitialized();
+        try {
+            const flags = (await this.readFlagsFromEdgeConfig()) ?? {};
+            if (definition.key in flags) {
+                throw new FeatureFlagError_1.FeatureFlagError('vercel', `Feature flag "${definition.key}" already exists.`);
+            }
+            flags[definition.key] = this.toStoredValue(definition);
+            await this.writeFlagsToEdgeConfig(flags);
+            this._logger.log(`[VercelFeatureFlagWriter] Created flag "${definition.key}"`);
+        }
+        catch (error) {
+            if (error instanceof FeatureFlagError_1.FeatureFlagError) {
+                throw error;
+            }
+            this._logger.error(`[VercelFeatureFlagWriter] createFlag failed for "${definition.key}"`, {
+                key: definition.key,
+                error: error.message,
+            });
+            throw new FeatureFlagError_1.FeatureFlagError('vercel', `Failed to create feature flag "${definition.key}"`, error);
+        }
+    }
+    /** @inheritdoc */
+    async updateFlag(key, updates) {
+        this.ensureInitialized();
+        try {
+            const flags = (await this.readFlagsFromEdgeConfig()) ?? {};
+            if (!(key in flags)) {
+                throw new FeatureFlagError_1.FeatureFlagError('vercel', `Feature flag "${key}" does not exist.`);
+            }
+            const existing = this.toDefinition(key, flags[key]);
+            const updated = {
+                key,
+                enabled: updates.enabled ?? existing.enabled,
+                description: updates.description ?? existing.description,
+                label: updates.label ?? existing.label,
+                variant: updates.variant ?? existing.variant,
+            };
+            flags[key] = this.toStoredValue(updated);
+            await this.writeFlagsToEdgeConfig(flags);
+            this._logger.log(`[VercelFeatureFlagWriter] Updated flag "${key}"`);
+        }
+        catch (error) {
+            if (error instanceof FeatureFlagError_1.FeatureFlagError) {
+                throw error;
+            }
+            this._logger.error(`[VercelFeatureFlagWriter] updateFlag failed for "${key}"`, {
+                key,
+                error: error.message,
+            });
+            throw new FeatureFlagError_1.FeatureFlagError('vercel', `Failed to update feature flag "${key}"`, error);
+        }
+    }
+    /** @inheritdoc */
+    async deleteFlag(key) {
+        this.ensureInitialized();
+        try {
+            const flags = (await this.readFlagsFromEdgeConfig()) ?? {};
+            if (!(key in flags)) {
+                throw new FeatureFlagError_1.FeatureFlagError('vercel', `Feature flag "${key}" does not exist.`);
+            }
+            delete flags[key];
+            await this.writeFlagsToEdgeConfig(flags);
+            this._logger.log(`[VercelFeatureFlagWriter] Deleted flag "${key}"`);
+        }
+        catch (error) {
+            if (error instanceof FeatureFlagError_1.FeatureFlagError) {
+                throw error;
+            }
+            this._logger.error(`[VercelFeatureFlagWriter] deleteFlag failed for "${key}"`, {
+                key,
+                error: error.message,
+            });
+            throw new FeatureFlagError_1.FeatureFlagError('vercel', `Failed to delete feature flag "${key}"`, error);
+        }
+    }
+    /** @inheritdoc */
+    async ping() {
+        try {
+            this.ensureInitialized();
+            await this.readFlagsFromEdgeConfig();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Reads the current flags object from Edge Config via the Vercel REST API.
+     */
+    async readFlagsFromEdgeConfig() {
+        const url = this.buildUrl(`/v1/edge-config/${this._edgeConfigId}/item/${this._flagPrefix}`);
+        const response = await this.request(url, 'GET');
+        if (response.status === 404) {
+            return undefined;
+        }
+        if (!response.ok) {
+            throw new FeatureFlagError_1.FeatureFlagError('vercel', `Failed to read Edge Config (HTTP ${response.status}): ${await response.text()}`);
+        }
+        const body = (await response.json());
+        return body.value ?? undefined;
+    }
+    /**
+     * Writes the flags object to Edge Config via the Vercel REST API.
+     */
+    async writeFlagsToEdgeConfig(flags) {
+        const url = this.buildUrl(`/v1/edge-config/${this._edgeConfigId}/items`);
+        const response = await this.request(url, 'PATCH', {
+            items: [
+                {
+                    operation: 'upsert',
+                    key: this._flagPrefix,
+                    value: flags,
+                },
+            ],
+        });
+        if (!response.ok) {
+            throw new FeatureFlagError_1.FeatureFlagError('vercel', `Failed to write Edge Config (HTTP ${response.status}): ${await response.text()}`);
+        }
+    }
+    /**
+     * Builds a full Vercel API URL, appending the team ID query parameter if configured.
+     */
+    buildUrl(path) {
+        const url = new URL(path, VERCEL_API_BASE);
+        if (this._teamId) {
+            url.searchParams.set('teamId', this._teamId);
+        }
+        return url.toString();
+    }
+    /**
+     * Performs an HTTP request to the Vercel REST API with timeout and authorization.
+     */
+    async request(url, method, body) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+        try {
+            return await fetch(url, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this._apiToken}`,
+                    'Content-Type': 'application/json',
+                },
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    /**
+     * Converts a stored value into an {@link IFeatureFlagDefinition}.
+     */
+    toDefinition(key, value) {
+        if (typeof value === 'boolean') {
+            return { key, enabled: value };
+        }
+        if (typeof value === 'object' && value !== null) {
+            const obj = value;
+            return {
+                key,
+                enabled: Boolean(obj['enabled'] ?? true),
+                description: typeof obj['description'] === 'string' ? obj['description'] : undefined,
+                label: typeof obj['label'] === 'string' ? obj['label'] : undefined,
+                variant: obj['variant'],
+            };
+        }
+        return { key, enabled: Boolean(value) };
+    }
+    /**
+     * Converts an {@link IFeatureFlagDefinition} into the stored value shape.
+     * Simple boolean flags are stored as booleans; flags with metadata are stored as objects.
+     */
+    toStoredValue(definition) {
+        if (!definition.description && !definition.label && definition.variant === undefined) {
+            return definition.enabled;
+        }
+        return {
+            enabled: definition.enabled,
+            description: definition.description,
+            label: definition.label,
+            variant: definition.variant,
+        };
+    }
+    /**
+     * Ensures the admin client has been initialized.
+     */
+    ensureInitialized() {
+        if (!this._apiToken || !this._edgeConfigId) {
+            throw new FeatureFlagError_1.FeatureFlagError('vercel', 'VercelFeatureFlagWriter has not been initialized. Ensure onModuleInit() ran.');
+        }
+    }
+};
+exports.VercelFeatureFlagWriter = VercelFeatureFlagWriter;
+exports.VercelFeatureFlagWriter = VercelFeatureFlagWriter = VercelFeatureFlagWriter_1 = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__metadata("design:paramtypes", [archipel_platform_configuration_1.ConfigService])
+], VercelFeatureFlagWriter);
+//# sourceMappingURL=VercelFeatureFlagWriter.js.map

package/src/vercel/env.d.ts

@@ -0,0 +1,17 @@
+import { type IConfigRegistryEntry } from '@breadstone/archipel-platform-configuration';
+/** Vercel Edge Config connection string (includes store ID and token). */
+export declare const VERCEL_EDGE_CONFIG: import("@breadstone/archipel-platform-configuration").IConfigKey<string>;
+/** Optional: Vercel Edge Config read access token (when not embedded in connection string). */
+export declare const VERCEL_EDGE_CONFIG_TOKEN: import("@breadstone/archipel-platform-configuration").IConfigKey<string>;
+/** Optional: Prefix for feature flag keys in Edge Config. Defaults to `featureFlags`. */
+export declare const VERCEL_FEATURE_FLAG_PREFIX: import("@breadstone/archipel-platform-configuration").IConfigKey<string>;
+/** Vercel API token with write access to Edge Config. Required for write operations. */
+export declare const VERCEL_API_TOKEN: import("@breadstone/archipel-platform-configuration").IConfigKey<string>;
+/** Vercel Edge Config store ID. Required for write operations. */
+export declare const VERCEL_EDGE_CONFIG_ID: import("@breadstone/archipel-platform-configuration").IConfigKey<string>;
+/** Optional: Vercel Team ID for team-scoped API calls. */
+export declare const VERCEL_TEAM_ID: import("@breadstone/archipel-platform-configuration").IConfigKey<string>;
+/** Configuration entries required by the Vercel feature flag provider (read-only). */
+export declare const VERCEL_FEATURE_FLAG_CONFIG_ENTRIES: ReadonlyArray<Omit<IConfigRegistryEntry, 'module'>>;
+/** Configuration entries required by the Vercel feature flag writer provider. */
+export declare const VERCEL_FEATURE_FLAG_WRITER_CONFIG_ENTRIES: ReadonlyArray<Omit<IConfigRegistryEntry, 'module'>>;

package/src/vercel/env.js

@@ -0,0 +1,69 @@
+"use strict";
+// #region Imports
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERCEL_FEATURE_FLAG_WRITER_CONFIG_ENTRIES = exports.VERCEL_FEATURE_FLAG_CONFIG_ENTRIES = exports.VERCEL_TEAM_ID = exports.VERCEL_EDGE_CONFIG_ID = exports.VERCEL_API_TOKEN = exports.VERCEL_FEATURE_FLAG_PREFIX = exports.VERCEL_EDGE_CONFIG_TOKEN = exports.VERCEL_EDGE_CONFIG = void 0;
+const archipel_platform_configuration_1 = require("@breadstone/archipel-platform-configuration");
+// #endregion
+// ──────────────────────────────────────────────────────────────
+// Vercel Edge Config
+// ──────────────────────────────────────────────────────────────
+/** Vercel Edge Config connection string (includes store ID and token). */
+exports.VERCEL_EDGE_CONFIG = (0, archipel_platform_configuration_1.createConfigKey)('EDGE_CONFIG');
+/** Optional: Vercel Edge Config read access token (when not embedded in connection string). */
+exports.VERCEL_EDGE_CONFIG_TOKEN = (0, archipel_platform_configuration_1.createConfigKey)('VERCEL_EDGE_CONFIG_TOKEN');
+/** Optional: Prefix for feature flag keys in Edge Config. Defaults to `featureFlags`. */
+exports.VERCEL_FEATURE_FLAG_PREFIX = (0, archipel_platform_configuration_1.createConfigKey)('VERCEL_FEATURE_FLAG_PREFIX');
+// ──────────────────────────────────────────────────────────────
+// Vercel Edge Config Writer
+// ──────────────────────────────────────────────────────────────
+/** Vercel API token with write access to Edge Config. Required for write operations. */
+exports.VERCEL_API_TOKEN = (0, archipel_platform_configuration_1.createConfigKey)('VERCEL_API_TOKEN');
+/** Vercel Edge Config store ID. Required for write operations. */
+exports.VERCEL_EDGE_CONFIG_ID = (0, archipel_platform_configuration_1.createConfigKey)('VERCEL_EDGE_CONFIG_ID');
+/** Optional: Vercel Team ID for team-scoped API calls. */
+exports.VERCEL_TEAM_ID = (0, archipel_platform_configuration_1.createConfigKey)('VERCEL_TEAM_ID');
+// ──────────────────────────────────────────────────────────────
+// Registry entries
+// ──────────────────────────────────────────────────────────────
+/** Configuration entries required by the Vercel feature flag provider (read-only). */
+exports.VERCEL_FEATURE_FLAG_CONFIG_ENTRIES = [
+    {
+        key: exports.VERCEL_EDGE_CONFIG,
+        required: true,
+        description: 'Vercel Edge Config connection string.',
+    },
+    {
+        key: exports.VERCEL_EDGE_CONFIG_TOKEN,
+        required: false,
+        description: 'Vercel Edge Config read access token (when not embedded in connection string).',
+    },
+    {
+        key: exports.VERCEL_FEATURE_FLAG_PREFIX,
+        required: false,
+        description: 'Prefix for feature flag keys in Edge Config. Defaults to featureFlags.',
+    },
+];
+/** Configuration entries required by the Vercel feature flag writer provider. */
+exports.VERCEL_FEATURE_FLAG_WRITER_CONFIG_ENTRIES = [
+    {
+        key: exports.VERCEL_API_TOKEN,
+        required: true,
+        description: 'Vercel API token with write access to Edge Config.',
+    },
+    {
+        key: exports.VERCEL_EDGE_CONFIG_ID,
+        required: true,
+        description: 'Vercel Edge Config store ID.',
+    },
+    {
+        key: exports.VERCEL_TEAM_ID,
+        required: false,
+        description: 'Vercel Team ID for team-scoped API calls.',
+    },
+    {
+        key: exports.VERCEL_FEATURE_FLAG_PREFIX,
+        required: false,
+        description: 'Prefix for feature flag keys in Edge Config. Defaults to featureFlags.',
+    },
+];
+//# sourceMappingURL=env.js.map

package/src/vercel/index.d.ts

@@ -0,0 +1,3 @@
+export { VERCEL_API_TOKEN, VERCEL_EDGE_CONFIG, VERCEL_EDGE_CONFIG_ID, VERCEL_EDGE_CONFIG_TOKEN, VERCEL_FEATURE_FLAG_CONFIG_ENTRIES, VERCEL_FEATURE_FLAG_PREFIX, VERCEL_FEATURE_FLAG_WRITER_CONFIG_ENTRIES, VERCEL_TEAM_ID, } from './env';
+export { VercelFeatureFlagReader } from './VercelFeatureFlagReader';
+export { VercelFeatureFlagWriter } from './VercelFeatureFlagWriter';

package/src/vercel/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VercelFeatureFlagWriter = exports.VercelFeatureFlagReader = exports.VERCEL_TEAM_ID = exports.VERCEL_FEATURE_FLAG_WRITER_CONFIG_ENTRIES = exports.VERCEL_FEATURE_FLAG_PREFIX = exports.VERCEL_FEATURE_FLAG_CONFIG_ENTRIES = exports.VERCEL_EDGE_CONFIG_TOKEN = exports.VERCEL_EDGE_CONFIG_ID = exports.VERCEL_EDGE_CONFIG = exports.VERCEL_API_TOKEN = void 0;
+var env_1 = require("./env");
+Object.defineProperty(exports, "VERCEL_API_TOKEN", { enumerable: true, get: function () { return env_1.VERCEL_API_TOKEN; } });
+Object.defineProperty(exports, "VERCEL_EDGE_CONFIG", { enumerable: true, get: function () { return env_1.VERCEL_EDGE_CONFIG; } });
+Object.defineProperty(exports, "VERCEL_EDGE_CONFIG_ID", { enumerable: true, get: function () { return env_1.VERCEL_EDGE_CONFIG_ID; } });
+Object.defineProperty(exports, "VERCEL_EDGE_CONFIG_TOKEN", { enumerable: true, get: function () { return env_1.VERCEL_EDGE_CONFIG_TOKEN; } });
+Object.defineProperty(exports, "VERCEL_FEATURE_FLAG_CONFIG_ENTRIES", { enumerable: true, get: function () { return env_1.VERCEL_FEATURE_FLAG_CONFIG_ENTRIES; } });
+Object.defineProperty(exports, "VERCEL_FEATURE_FLAG_PREFIX", { enumerable: true, get: function () { return env_1.VERCEL_FEATURE_FLAG_PREFIX; } });
+Object.defineProperty(exports, "VERCEL_FEATURE_FLAG_WRITER_CONFIG_ENTRIES", { enumerable: true, get: function () { return env_1.VERCEL_FEATURE_FLAG_WRITER_CONFIG_ENTRIES; } });
+Object.defineProperty(exports, "VERCEL_TEAM_ID", { enumerable: true, get: function () { return env_1.VERCEL_TEAM_ID; } });
+var VercelFeatureFlagReader_1 = require("./VercelFeatureFlagReader");
+Object.defineProperty(exports, "VercelFeatureFlagReader", { enumerable: true, get: function () { return VercelFeatureFlagReader_1.VercelFeatureFlagReader; } });
+var VercelFeatureFlagWriter_1 = require("./VercelFeatureFlagWriter");
+Object.defineProperty(exports, "VercelFeatureFlagWriter", { enumerable: true, get: function () { return VercelFeatureFlagWriter_1.VercelFeatureFlagWriter; } });
+//# sourceMappingURL=index.js.map