@mergedapp/feature-flags 0.1.3

package/dist/remote-evaluator.js

@@ -0,0 +1,158 @@
+import { FeatureFlagNetworkError, FeatureFlagVerificationError } from "./errors.js";
+import { importPublicKey, resetPublicKeyCache, verifyFeatureFlagTokenDetailed } from "./jwt.js";
+import { serializeCanonicalValue } from "./persistence.js";
+const REMOTE_FETCH_TIMEOUT_MS = 5_000;
+export class RemoteFeatureFlagEvaluator {
+    publicKeyPem;
+    publicKeyCrypto = null;
+    evaluationCache = new Map();
+    inflightEvaluations = new Map();
+    apiUrl;
+    clientKey;
+    organizationId;
+    environmentId;
+    teamId;
+    constructor(config) {
+        this.apiUrl = config.apiUrl.replace(/\/$/, "");
+        this.clientKey = config.clientKey;
+        this.organizationId = config.organizationId.trim();
+        this.environmentId = config.environmentId.trim();
+        this.teamId = config.teamId?.trim() || null;
+        this.publicKeyPem = config.publicKey ?? null;
+    }
+    async evaluate(context) {
+        const contextKey = serializeCanonicalValue(context ?? null);
+        const cached = this.evaluationCache.get(contextKey);
+        if (cached && this.isCachedEvaluationValid(cached)) {
+            return cached;
+        }
+        if (cached) {
+            this.evaluationCache.delete(contextKey);
+        }
+        const inflight = this.inflightEvaluations.get(contextKey);
+        if (inflight) {
+            return inflight;
+        }
+        const evaluationPromise = this.evaluateUncached(context).finally(() => {
+            this.inflightEvaluations.delete(contextKey);
+        });
+        this.inflightEvaluations.set(contextKey, evaluationPromise);
+        const evaluation = await evaluationPromise;
+        if (this.isCachedEvaluationValid(evaluation)) {
+            this.evaluationCache.set(contextKey, evaluation);
+        }
+        else {
+            this.evaluationCache.delete(contextKey);
+        }
+        return evaluation;
+    }
+    async evaluateUncached(context) {
+        await this.ensureVerificationKey();
+        const response = await this.fetchSignedFlags(context ?? null);
+        const verified = await this.verifyWithRetry(response.token);
+        return {
+            expiresAt: verified.expiresAt,
+            fetchedAt: new Date().toISOString(),
+            flags: verified.flags,
+        };
+    }
+    isCachedEvaluationValid(evaluation) {
+        if (!evaluation.expiresAt) {
+            return false;
+        }
+        const expiresAt = new Date(evaluation.expiresAt).getTime();
+        return Number.isFinite(expiresAt) && expiresAt > Date.now();
+    }
+    async fetchSignedFlags(context) {
+        const url = new URL("/api/feature-flags/evaluate/signed", this.apiUrl);
+        const payload = {
+            organizationId: this.organizationId,
+            environmentId: this.environmentId,
+            ...(this.teamId ? { teamId: this.teamId } : {}),
+            ...(context ? { context } : {}),
+        };
+        let response;
+        try {
+            response = await this.fetchWithTimeout(url, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this.clientKey}`,
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                },
+                body: JSON.stringify(payload),
+            });
+        }
+        catch (error) {
+            if (error instanceof FeatureFlagNetworkError) {
+                throw error;
+            }
+            throw new FeatureFlagNetworkError("Failed to fetch feature flags.", { cause: error });
+        }
+        if (!response.ok) {
+            throw new FeatureFlagNetworkError(`Feature flag API returned ${response.status}: ${response.statusText}`);
+        }
+        return (await response.json());
+    }
+    async fetchPublicKey() {
+        const url = `${this.apiUrl}/api/feature-flags/public-key`;
+        let response;
+        try {
+            response = await this.fetchWithTimeout(url);
+        }
+        catch (error) {
+            if (error instanceof FeatureFlagNetworkError) {
+                throw error;
+            }
+            throw new FeatureFlagNetworkError("Failed to fetch public key.", { cause: error });
+        }
+        if (!response.ok) {
+            throw new FeatureFlagNetworkError(`Public key endpoint returned ${response.status}: ${response.statusText}`);
+        }
+        const body = (await response.json());
+        return body.publicKey;
+    }
+    async verifyWithRetry(token) {
+        try {
+            return await verifyFeatureFlagTokenDetailed({ token, publicKey: this.publicKeyCrypto });
+        }
+        catch (error) {
+            if (!(error instanceof FeatureFlagVerificationError)) {
+                throw error;
+            }
+            resetPublicKeyCache();
+            this.publicKeyPem = await this.fetchPublicKey();
+            this.publicKeyCrypto = await importPublicKey(this.publicKeyPem);
+            return verifyFeatureFlagTokenDetailed({ token, publicKey: this.publicKeyCrypto });
+        }
+    }
+    async ensureVerificationKey() {
+        if (!this.publicKeyPem) {
+            this.publicKeyPem = await this.fetchPublicKey();
+        }
+        if (!this.publicKeyCrypto) {
+            this.publicKeyCrypto = await importPublicKey(this.publicKeyPem);
+        }
+    }
+    async fetchWithTimeout(input, init) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => {
+            controller.abort();
+        }, REMOTE_FETCH_TIMEOUT_MS);
+        try {
+            return await fetch(input, {
+                ...init,
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new FeatureFlagNetworkError(`Feature flag request timed out after ${REMOTE_FETCH_TIMEOUT_MS}ms.`, { cause: error });
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+export type { EvaluatedFlag, FeatureFlagEvaluationContext, FeatureFlagType, SignedEvaluateResponse, EvaluateResponse, PublicKeyResponse, FeatureFlagDefinition, } from "@repo/types-v2";
+export type { FeatureFlagError, FeatureFlagNetworkError, FeatureFlagVerificationError } from "./errors.js";
+export type FlagRegistry = object;
+export type FeatureFlagRuntimeSource = "network" | "persisted" | "defaults";
+export type FeatureFlagRuntimeStatus = {
+    source: FeatureFlagRuntimeSource;
+    isStale: boolean;
+    lastSuccessfulRefreshAt: string | null;
+    tokenExpiresAt: string | null;
+    lastError: Error | null;
+};
+export type PersistedFeatureFlagSnapshot = {
+    schemaVersion: number;
+    scopeKey: string;
+    organizationId: string;
+    environmentId: string;
+    teamId: string | null;
+    clientKeyFingerprint: string;
+    contextHash: string;
+    token: string;
+    publicKeyPem: string;
+    fetchedAt: string;
+    tokenExpiresAt: string | null;
+};
+export type FeatureFlagSnapshotStore = {
+    load(key: string): Promise<PersistedFeatureFlagSnapshot | null>;
+    save(key: string, snapshot: PersistedFeatureFlagSnapshot): Promise<void>;
+    remove(key: string): Promise<void>;
+};
+export type FeatureFlagSnapshotPersistenceConfig = {
+    store?: FeatureFlagSnapshotStore;
+    keyPrefix?: string;
+};
+export type FeatureFlagClientConfig<TFlags extends FlagRegistry = FlagRegistry> = {
+    clientKey: string;
+    apiUrl: string;
+    organizationId: string;
+    environmentId: string;
+    teamId?: string;
+    flagIds?: {
+        readonly [K in string & keyof TFlags]: string;
+    };
+    publicKey?: string;
+    refreshInterval?: number;
+    evaluationContext?: import("@repo/types-v2").FeatureFlagEvaluationContext;
+    snapshotPersistence?: false | FeatureFlagSnapshotPersistenceConfig;
+    onError?: (error: Error) => void;
+    onFlagsChanged?: (flags: import("@repo/types-v2").EvaluatedFlag[]) => void;
+};
+export type GenerateConfig = {
+    apiUrl: string;
+    clientKey: string;
+    outputPath: string;
+    teamId?: string;
+    organizationId: string;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/featureflags.config.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Merged feature flags CLI config",
+  "description": "Configuration for merged-ff code generation and related CLI workflows.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional JSON Schema URL used by IDEs for autocomplete and validation."
+    },
+    "apiUrl": {
+      "type": "string",
+      "description": "Base URL for the feature flags API.",
+      "format": "uri"
+    },
+    "clientKey": {
+      "type": "string",
+      "description": "API key used for fetching feature flag definitions."
+    },
+    "organizationId": {
+      "type": "string",
+      "description": "Organization scope used when fetching feature flag definitions."
+    },
+    "teamId": {
+      "type": "string",
+      "description": "Optional team scope used when fetching feature flag definitions."
+    },
+    "outputPath": {
+      "type": "string",
+      "description": "Output path for the generated feature flags TypeScript module."
+    },
+    "environmentId": {
+      "type": "string",
+      "description": "Optional environment identifier for app-local conventions. The generate command ignores this field."
+    }
+  }
+}

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@mergedapp/feature-flags",
+  "version": "0.1.3",
+  "type": "module",
+  "description": "Type-safe client SDK for Merged feature flags with ES256 JWT verification",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "merged-ff": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "require": "./dist/react.cjs"
+    },
+    "./openfeature/web": {
+      "types": "./dist/openfeature/web.d.ts",
+      "import": "./dist/openfeature/web.js",
+      "require": "./dist/openfeature/web.cjs"
+    },
+    "./openfeature/server": {
+      "types": "./dist/openfeature/server.d.ts",
+      "import": "./dist/openfeature/server.js",
+      "require": "./dist/openfeature/server.cjs"
+    },
+    "./nestjs": {
+      "types": "./dist/nestjs.d.ts",
+      "import": "./dist/nestjs.js",
+      "require": "./dist/nestjs.cjs"
+    },
+    "./featureflags.config.schema.json": "./featureflags.config.schema.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "featureflags.config.schema.json",
+    "!**/*.map"
+  ],
+  "scripts": {
+    "build": "node ./scripts/build.mjs",
+    "dev": "node ./scripts/build.mjs",
+    "test": "vitest run",
+    "check-types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "jose": "^6.0.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@openfeature/core": "^1.9.2",
+    "@openfeature/server-sdk": "^1.20.2",
+    "@openfeature/web-sdk": "^1.7.3",
+    "react": "^18.0.0 || ^19.0.0",
+    "rxjs": "^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/core": {
+      "optional": true
+    },
+    "@openfeature/core": {
+      "optional": true
+    },
+    "@openfeature/server-sdk": {
+      "optional": true
+    },
+    "@openfeature/web-sdk": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "rxjs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/core": "^11.0.1",
+    "@openfeature/core": "^1.9.2",
+    "@openfeature/server-sdk": "^1.20.2",
+    "@openfeature/web-sdk": "^1.7.3",
+    "@repo/types-v2": "workspace:*",
+    "@repo/typescript-config": "workspace:*",
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.1.4",
+    "@types/react-dom": "^19.1.5",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "typescript": "6.0.3",
+    "vitest": "^3.0.5"
+  }
+}