@mergedapp/feature-flags 0.1.3

package/dist/cli/generate.d.ts

@@ -0,0 +1,3 @@
+type GenerateArgs = Record<string, string>;
+export declare function generate(args: GenerateArgs): Promise<void>;
+export {};

package/dist/cli/generate.js

@@ -0,0 +1,191 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, relative, resolve } from "node:path";
+import { FeatureFlagCliConfigLoader } from "./config-loader.js";
+function assertValidCodeKey(codeKey) {
+    if (!/^[a-z][A-Za-z0-9]*$/.test(codeKey)) {
+        throw new Error(`Invalid feature flag codeKey "${codeKey}". Code keys must be lowerCamelCase alphanumeric identifiers.`);
+    }
+}
+function flagTypeToTsType(flagType) {
+    switch (flagType) {
+        case "BOOLEAN":
+            return "boolean";
+        case "STRING":
+            return "string";
+        case "NUMBER":
+            return "number";
+        case "JSON":
+            return "Record<string, unknown>";
+        case "ARRAY":
+            return "unknown[]";
+        default:
+            return "unknown";
+    }
+}
+function escapeJsDoc(str) {
+    return str.replace(/\*\//g, "*\\/").replace(/\n/g, " ");
+}
+async function fetchDefinitions(params) {
+    const url = new URL("/api/feature-flags/definitions", params.apiUrl);
+    url.searchParams.set("organizationId", params.organizationId);
+    if (params.teamId) {
+        url.searchParams.set("teamId", params.teamId);
+    }
+    const response = await fetch(url.toString(), {
+        headers: { Authorization: `Bearer ${params.clientKey}` },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch definitions: ${response.status} ${response.statusText}`);
+    }
+    const body = (await response.json());
+    return body.definitions;
+}
+function generateCode(definitions) {
+    const activeFlags = definitions.filter((d) => !d.isArchived);
+    if (activeFlags.length === 0) {
+        return `// Auto-generated by @mergedapp/feature-flags. Do not edit.
+// Generated at: ${new Date().toISOString()}
+// No active feature flags found.
+
+import { MergedFeatureFlags } from "@mergedapp/feature-flags"
+import { createTypedHooks } from "@mergedapp/feature-flags/react"
+import type { FeatureFlagClientConfig } from "@mergedapp/feature-flags"
+
+export const FLAGS = {} as const
+
+export interface FlagValues {}
+
+export type FlagName = keyof typeof FLAGS
+
+export function createClient(config: FeatureFlagClientConfig) {
+  return new MergedFeatureFlags<FlagValues>({ ...config, flagIds: FLAGS })
+}
+
+export const { FeatureFlagProvider, FeatureFlag, useFeatureFlag, useFeatureFlags, useFeatureFlagClient, useFeatureFlagStatus } =
+  createTypedHooks<FlagValues>()
+`;
+    }
+    const flagEntries = activeFlags.map((flag) => {
+        assertValidCodeKey(flag.codeKey);
+        const doc = flag.description ? `  /** ${escapeJsDoc(flag.description)} */\n` : "";
+        return { key: flag.codeKey, id: flag.id, type: flag.type, doc };
+    });
+    const flagsConst = flagEntries.map((e) => `${e.doc}  ${e.key}: "${e.id}",`).join("\n");
+    const flagValuesEntries = flagEntries.map((e) => `  ${e.key}: ${flagTypeToTsType(e.type)}`).join("\n");
+    return `// Auto-generated by @mergedapp/feature-flags. Do not edit.
+// Generated at: ${new Date().toISOString()}
+
+import { MergedFeatureFlags } from "@mergedapp/feature-flags"
+import { createTypedHooks } from "@mergedapp/feature-flags/react"
+import type { FeatureFlagClientConfig } from "@mergedapp/feature-flags"
+
+/** Stable flag ID mapping. Names are for readability; IDs are used at runtime. */
+export const FLAGS = {
+${flagsConst}
+} as const
+
+/** Type-safe flag value types inferred from flag definitions. */
+export interface FlagValues {
+${flagValuesEntries}
+}
+
+export type FlagName = keyof typeof FLAGS
+
+/** Create a type-safe client bound to this flag registry. */
+export function createClient(config: FeatureFlagClientConfig) {
+  return new MergedFeatureFlags<FlagValues>({ ...config, flagIds: FLAGS })
+}
+
+/** Pre-typed React hooks, provider, and JSX wrapper bound to this flag registry. */
+export const { FeatureFlagProvider, FeatureFlag, useFeatureFlag, useFeatureFlags, useFeatureFlagClient, useFeatureFlagStatus } =
+  createTypedHooks<FlagValues>()
+`;
+}
+function generateNestCode(params) {
+    return `// Auto-generated by @mergedapp/feature-flags. Do not edit.
+// Generated at: ${new Date().toISOString()}
+
+import {
+  createTypedNestjsBindings,
+  FeatureFlagContext,
+  FeatureFlagsRequestContextStore,
+  FeatureFlagsService,
+  type FeatureFlagContextFactory,
+  type FeatureFlagEvaluationDetails,
+} from "@mergedapp/feature-flags/nestjs"
+import { FLAGS } from "${params.generatedModulePath}"
+import type { FlagValues } from "${params.generatedModulePath}"
+
+export {
+  FeatureFlagContext,
+  FeatureFlagsRequestContextStore,
+  FeatureFlagsService,
+}
+export type {
+  FeatureFlagContextFactory,
+  FeatureFlagEvaluationDetails,
+}
+
+export const { FeatureFlagsModule, RequireFeatureFlag, FeatureFlagGate } =
+  createTypedNestjsBindings<FlagValues>({ flagIds: FLAGS })
+`;
+}
+function resolveNestOutputPath(outputPath) {
+    const extension = extname(outputPath);
+    if (extension === ".ts") {
+        return outputPath.slice(0, -extension.length) + ".nest.ts";
+    }
+    return `${outputPath}.nest.ts`;
+}
+function resolveRelativeGeneratedModulePath(params) {
+    const mainBaseName = basename(params.mainOutputPath, extname(params.mainOutputPath));
+    const nestDirectory = dirname(params.nestOutputPath);
+    const mainDirectory = dirname(params.mainOutputPath);
+    if (nestDirectory === mainDirectory) {
+        return `./${mainBaseName}`;
+    }
+    const relativeDirectory = relative(nestDirectory, mainDirectory);
+    const normalizedDirectory = relativeDirectory.split("\\").join("/");
+    return `${normalizedDirectory.startsWith(".") ? normalizedDirectory : `./${normalizedDirectory}`}/${mainBaseName}`;
+}
+export async function generate(args) {
+    const loadedConfig = await FeatureFlagCliConfigLoader.load({ configPath: args.config });
+    const config = loadedConfig.config;
+    const apiUrl = args["api-url"] ?? config.apiUrl ?? process.env.FEATURE_FLAG_API_URL;
+    const clientKey = args["client-key"] ?? config.clientKey ?? process.env.FEATURE_FLAG_CLIENT_KEY;
+    const outputPath = args.output ??
+        FeatureFlagCliConfigLoader.resolveConfigRelativePath({
+            value: config.outputPath,
+            configPath: loadedConfig.configPath,
+        }) ??
+        "./src/generated/feature-flags.ts";
+    const teamId = args["team-id"] ?? config.teamId;
+    const organizationId = args["organization-id"] ?? config.organizationId ?? process.env.FEATURE_FLAG_ORGANIZATION_ID;
+    if (!apiUrl) {
+        throw new Error("Missing --api-url or FEATURE_FLAG_API_URL env var.");
+    }
+    if (!clientKey) {
+        throw new Error("Missing --client-key or FEATURE_FLAG_CLIENT_KEY env var.");
+    }
+    if (!organizationId) {
+        throw new Error("Missing --organization-id, FEATURE_FLAG_ORGANIZATION_ID, or config.organizationId.");
+    }
+    console.log(`Fetching flag definitions from ${apiUrl}...`);
+    const definitions = await fetchDefinitions({ apiUrl, clientKey, organizationId, teamId });
+    console.log(`Found ${definitions.length} flag definitions.`);
+    const code = generateCode(definitions);
+    const resolvedPath = resolve(outputPath);
+    const resolvedNestPath = resolveNestOutputPath(resolvedPath);
+    const nestCode = generateNestCode({
+        generatedModulePath: resolveRelativeGeneratedModulePath({
+            mainOutputPath: resolvedPath,
+            nestOutputPath: resolvedNestPath,
+        }),
+    });
+    await mkdir(dirname(resolvedPath), { recursive: true });
+    await mkdir(dirname(resolvedNestPath), { recursive: true });
+    await writeFile(resolvedPath, code, "utf-8");
+    await writeFile(resolvedNestPath, nestCode, "utf-8");
+    console.log(`Generated typed flags at ${resolvedPath}`);
+    console.log(`Generated typed NestJS bindings at ${resolvedNestPath}`);
+}

package/dist/cli/parse-args.d.ts

@@ -0,0 +1 @@
+export declare function parseArgs(args: string[]): Record<string, string>;

package/dist/cli/parse-args.js

@@ -0,0 +1,15 @@
+export function parseArgs(args) {
+    const result = {};
+    for (const arg of args) {
+        const keyValueMatch = arg.match(/^--([^=]+)=(.+)$/);
+        if (keyValueMatch) {
+            result[keyValueMatch[1]] = keyValueMatch[2];
+            continue;
+        }
+        const flagMatch = arg.match(/^--(.+)$/);
+        if (flagMatch) {
+            result[flagMatch[1]] = "true";
+        }
+    }
+    return result;
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { generate } from "./cli/generate.js";
+import { audit } from "./cli/audit.js";
+import { cleanup } from "./cli/cleanup.js";
+import { parseArgs } from "./cli/parse-args.js";
+const [command, ...args] = process.argv.slice(2);
+async function main() {
+    const parsed = parseArgs(args);
+    switch (command) {
+        case "generate":
+            await generate(parsed);
+            break;
+        case "audit":
+            await audit(parsed);
+            break;
+        case "cleanup":
+            await cleanup(parsed);
+            break;
+        default:
+            console.log(`@mergedapp/feature-flags CLI
+
+Usage:
+  merged-ff generate  Generate typed SDK from flag definitions
+  merged-ff audit     Scan codebase for unused/stale flags
+  merged-ff cleanup   Remove stale flag references (interactive)
+
+Options:
+  --api-url=<url>       API base URL
+  --client-key=<key>    API key (or set FEATURE_FLAG_CLIENT_KEY env var)
+  --output=<path>       Output path for generated file (default: ./src/generated/feature-flags.ts)
+  --dir=<path>          Directory to scan (audit/cleanup, default: ./src)
+  --config=<path>       Config file path for generate/audit (default: auto-discover featureflags.config.{json,js,mjs,cjs} from cwd upward)
+  --dry-run             Preview changes without applying (cleanup)
+  --organization-id=<id>  Organization ID (required)
+  --team-id=<id>        Team ID scope`);
+            if (command) {
+                console.error(`\nUnknown command: ${command}`);
+                process.exit(1);
+            }
+    }
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,67 @@
+import type { EvaluatedFlag, FeatureFlagEvaluationContext } from "@repo/types-v2";
+import type { FeatureFlagClientConfig, FeatureFlagRuntimeStatus, FlagRegistry } from "./types.js";
+type ChangeListener = (flags: EvaluatedFlag[]) => void;
+export declare class MergedFeatureFlags<TFlags extends FlagRegistry = FlagRegistry> {
+    private flagsById;
+    private flagsByName;
+    private publicKeyPem;
+    private publicKeyCrypto;
+    private refreshTimer;
+    private backoffMs;
+    private consecutiveFailures;
+    private listeners;
+    private storeListeners;
+    private initialized;
+    private visibilityHandler;
+    private pendingScopeTransition;
+    private runtimeStatus;
+    private snapshotStorePromise;
+    private readonly keyPrefix;
+    private contextSignature;
+    private readonly flagIds;
+    private readonly clientKey;
+    private readonly apiUrl;
+    private readonly organizationId;
+    private readonly environmentId;
+    private readonly teamId;
+    private readonly refreshInterval;
+    private readonly onError;
+    private readonly onFlagsChanged;
+    private readonly snapshotPersistence;
+    private evaluationContext;
+    constructor(config: FeatureFlagClientConfig<TFlags>);
+    initialize(): Promise<void>;
+    isEnabled<K extends string & keyof TFlags>(name: K): boolean;
+    getValue<K extends string & keyof TFlags>(name: K): TFlags[K] | undefined;
+    getFlag<K extends string & keyof TFlags>(name: K): EvaluatedFlag | undefined;
+    getAllFlags(): EvaluatedFlag[];
+    getStatus(): FeatureFlagRuntimeStatus;
+    getStatusSnapshot(): FeatureFlagRuntimeStatus;
+    refresh(): Promise<void>;
+    onChange(listener: ChangeListener): () => void;
+    getSnapshot(): EvaluatedFlag[];
+    setEvaluationContext(context: FeatureFlagEvaluationContext | null | undefined): void;
+    subscribe(onStoreChange: () => void): () => void;
+    destroy(): void;
+    private resolveFlag;
+    private clearFlags;
+    private emitChange;
+    private updateFlags;
+    private hasFlagsChanged;
+    private setRuntimeStatus;
+    private fetchSignedFlags;
+    private fetchPublicKey;
+    private verifyWithRetry;
+    private ensureVerificationKey;
+    private getTrustedSnapshotVerificationKey;
+    private getSnapshotStore;
+    private getScopeParts;
+    private restorePersistedSnapshot;
+    private persistSnapshot;
+    private startPolling;
+    private scheduleNextPoll;
+    private safeRefresh;
+    private resetBackoff;
+    private incrementBackoff;
+}
+export {};