@mergedapp/feature-flags 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,175 @@
+import * as _repo_types_v2 from '@repo/types-v2';
+import { EvaluatedFlag, FeatureFlagEvaluationContext } from '@repo/types-v2';
+export { EvaluateResponse, EvaluatedFlag, FeatureFlagDefinition, FeatureFlagEvaluationContext, FeatureFlagType, PublicKeyResponse, SignedEvaluateResponse } from '@repo/types-v2';
+
+declare class FeatureFlagError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class FeatureFlagNetworkError extends FeatureFlagError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class FeatureFlagVerificationError extends FeatureFlagError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+/** Base type for a flag registry mapping flag names to their value types. */
+type FlagRegistry = object;
+type FeatureFlagRuntimeSource = "network" | "persisted" | "defaults";
+type FeatureFlagRuntimeStatus = {
+    source: FeatureFlagRuntimeSource;
+    isStale: boolean;
+    lastSuccessfulRefreshAt: string | null;
+    tokenExpiresAt: string | null;
+    lastError: Error | null;
+};
+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;
+};
+type FeatureFlagSnapshotStore = {
+    load(key: string): Promise<PersistedFeatureFlagSnapshot | null>;
+    save(key: string, snapshot: PersistedFeatureFlagSnapshot): Promise<void>;
+    remove(key: string): Promise<void>;
+};
+type FeatureFlagSnapshotPersistenceConfig = {
+    store?: FeatureFlagSnapshotStore;
+    keyPrefix?: string;
+};
+type FeatureFlagClientConfig<TFlags extends FlagRegistry = FlagRegistry> = {
+    /** API key with `lk_pub_*` or `lk_sec_*` prefix */
+    clientKey: string;
+    /** Base URL for the API (e.g. "https://api.merged.gg") */
+    apiUrl: string;
+    /** Organization scope for signed flag evaluation */
+    organizationId: string;
+    /** Environment scope for signed flag evaluation */
+    environmentId: string;
+    /** Optional team scope for signed flag evaluation */
+    teamId?: string;
+    /** Code-key-to-ID mapping from generated code. Enables type-safe lookups resolved to stable IDs. */
+    flagIds?: {
+        readonly [K in string & keyof TFlags]: string;
+    };
+    /** PEM-format ES256 public key. If omitted, auto-fetched from the public-key endpoint. */
+    publicKey?: string;
+    /** Polling interval in milliseconds. Default: 60_000 (60s). Set to 0 to disable. */
+    refreshInterval?: number;
+    /** Optional caller-provided evaluation context sent to the API when resolving flags. */
+    evaluationContext?: _repo_types_v2.FeatureFlagEvaluationContext;
+    /** Controls automatic persistence of the last successful signed evaluation. */
+    snapshotPersistence?: false | FeatureFlagSnapshotPersistenceConfig;
+    /** Called when an error occurs during refresh or verification */
+    onError?: (error: Error) => void;
+    /** Called when flags change after a refresh */
+    onFlagsChanged?: (flags: _repo_types_v2.EvaluatedFlag[]) => void;
+};
+type GenerateConfig = {
+    /** Base URL for the API */
+    apiUrl: string;
+    /** API key for fetching definitions */
+    clientKey: string;
+    /** Output path for the generated TypeScript file */
+    outputPath: string;
+    /** Optional team scope */
+    teamId?: string;
+    /** Organization ID required for fetching definitions */
+    organizationId: string;
+};
+
+type ChangeListener = (flags: EvaluatedFlag[]) => void;
+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>;
+    /** Returns true if the flag is enabled. Returns false for unknown flags. */
+    isEnabled<K extends string & keyof TFlags>(name: K): boolean;
+    /** Returns the flag's value with the type inferred from the flag registry. */
+    getValue<K extends string & keyof TFlags>(name: K): TFlags[K] | undefined;
+    /** Returns the full evaluated flag entry, or undefined if not found. */
+    getFlag<K extends string & keyof TFlags>(name: K): EvaluatedFlag | undefined;
+    /** Returns all evaluated flags. */
+    getAllFlags(): EvaluatedFlag[];
+    getStatus(): FeatureFlagRuntimeStatus;
+    getStatusSnapshot(): FeatureFlagRuntimeStatus;
+    /** Manually trigger a refresh from the server. */
+    refresh(): Promise<void>;
+    /** Subscribe to flag changes. Returns an unsubscribe function. */
+    onChange(listener: ChangeListener): () => void;
+    /** Get a snapshot function for useSyncExternalStore. */
+    getSnapshot(): EvaluatedFlag[];
+    /** Replace the caller-provided evaluation context used on subsequent refreshes. */
+    setEvaluationContext(context: FeatureFlagEvaluationContext | null | undefined): void;
+    /** Subscribe function for useSyncExternalStore. */
+    subscribe(onStoreChange: () => void): () => void;
+    /** Clean up timers, listeners, and cached data. */
+    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;
+}
+
+declare function createDefaultFeatureFlagRuntimeStatus(): FeatureFlagRuntimeStatus;
+declare function createLocalStorageFeatureFlagSnapshotStore(): FeatureFlagSnapshotStore;
+declare function createFileFeatureFlagSnapshotStore(params?: {
+    rootDirectory?: string;
+}): FeatureFlagSnapshotStore;
+
+export { type FeatureFlagClientConfig, FeatureFlagError, FeatureFlagNetworkError, type FeatureFlagRuntimeSource, type FeatureFlagRuntimeStatus, type FeatureFlagSnapshotPersistenceConfig, type FeatureFlagSnapshotStore, FeatureFlagVerificationError, type FlagRegistry, type GenerateConfig, MergedFeatureFlags, type PersistedFeatureFlagSnapshot, createDefaultFeatureFlagRuntimeStatus, createFileFeatureFlagSnapshotStore, createLocalStorageFeatureFlagSnapshotStore };

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+import * as _repo_types_v2 from '@repo/types-v2';
+import { EvaluatedFlag, FeatureFlagEvaluationContext } from '@repo/types-v2';
+export { EvaluateResponse, EvaluatedFlag, FeatureFlagDefinition, FeatureFlagEvaluationContext, FeatureFlagType, PublicKeyResponse, SignedEvaluateResponse } from '@repo/types-v2';
+
+declare class FeatureFlagError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class FeatureFlagNetworkError extends FeatureFlagError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class FeatureFlagVerificationError extends FeatureFlagError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+/** Base type for a flag registry mapping flag names to their value types. */
+type FlagRegistry = object;
+type FeatureFlagRuntimeSource = "network" | "persisted" | "defaults";
+type FeatureFlagRuntimeStatus = {
+    source: FeatureFlagRuntimeSource;
+    isStale: boolean;
+    lastSuccessfulRefreshAt: string | null;
+    tokenExpiresAt: string | null;
+    lastError: Error | null;
+};
+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;
+};
+type FeatureFlagSnapshotStore = {
+    load(key: string): Promise<PersistedFeatureFlagSnapshot | null>;
+    save(key: string, snapshot: PersistedFeatureFlagSnapshot): Promise<void>;
+    remove(key: string): Promise<void>;
+};
+type FeatureFlagSnapshotPersistenceConfig = {
+    store?: FeatureFlagSnapshotStore;
+    keyPrefix?: string;
+};
+type FeatureFlagClientConfig<TFlags extends FlagRegistry = FlagRegistry> = {
+    /** API key with `lk_pub_*` or `lk_sec_*` prefix */
+    clientKey: string;
+    /** Base URL for the API (e.g. "https://api.merged.gg") */
+    apiUrl: string;
+    /** Organization scope for signed flag evaluation */
+    organizationId: string;
+    /** Environment scope for signed flag evaluation */
+    environmentId: string;
+    /** Optional team scope for signed flag evaluation */
+    teamId?: string;
+    /** Code-key-to-ID mapping from generated code. Enables type-safe lookups resolved to stable IDs. */
+    flagIds?: {
+        readonly [K in string & keyof TFlags]: string;
+    };
+    /** PEM-format ES256 public key. If omitted, auto-fetched from the public-key endpoint. */
+    publicKey?: string;
+    /** Polling interval in milliseconds. Default: 60_000 (60s). Set to 0 to disable. */
+    refreshInterval?: number;
+    /** Optional caller-provided evaluation context sent to the API when resolving flags. */
+    evaluationContext?: _repo_types_v2.FeatureFlagEvaluationContext;
+    /** Controls automatic persistence of the last successful signed evaluation. */
+    snapshotPersistence?: false | FeatureFlagSnapshotPersistenceConfig;
+    /** Called when an error occurs during refresh or verification */
+    onError?: (error: Error) => void;
+    /** Called when flags change after a refresh */
+    onFlagsChanged?: (flags: _repo_types_v2.EvaluatedFlag[]) => void;
+};
+type GenerateConfig = {
+    /** Base URL for the API */
+    apiUrl: string;
+    /** API key for fetching definitions */
+    clientKey: string;
+    /** Output path for the generated TypeScript file */
+    outputPath: string;
+    /** Optional team scope */
+    teamId?: string;
+    /** Organization ID required for fetching definitions */
+    organizationId: string;
+};
+
+type ChangeListener = (flags: EvaluatedFlag[]) => void;
+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>;
+    /** Returns true if the flag is enabled. Returns false for unknown flags. */
+    isEnabled<K extends string & keyof TFlags>(name: K): boolean;
+    /** Returns the flag's value with the type inferred from the flag registry. */
+    getValue<K extends string & keyof TFlags>(name: K): TFlags[K] | undefined;
+    /** Returns the full evaluated flag entry, or undefined if not found. */
+    getFlag<K extends string & keyof TFlags>(name: K): EvaluatedFlag | undefined;
+    /** Returns all evaluated flags. */
+    getAllFlags(): EvaluatedFlag[];
+    getStatus(): FeatureFlagRuntimeStatus;
+    getStatusSnapshot(): FeatureFlagRuntimeStatus;
+    /** Manually trigger a refresh from the server. */
+    refresh(): Promise<void>;
+    /** Subscribe to flag changes. Returns an unsubscribe function. */
+    onChange(listener: ChangeListener): () => void;
+    /** Get a snapshot function for useSyncExternalStore. */
+    getSnapshot(): EvaluatedFlag[];
+    /** Replace the caller-provided evaluation context used on subsequent refreshes. */
+    setEvaluationContext(context: FeatureFlagEvaluationContext | null | undefined): void;
+    /** Subscribe function for useSyncExternalStore. */
+    subscribe(onStoreChange: () => void): () => void;
+    /** Clean up timers, listeners, and cached data. */
+    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;
+}
+
+declare function createDefaultFeatureFlagRuntimeStatus(): FeatureFlagRuntimeStatus;
+declare function createLocalStorageFeatureFlagSnapshotStore(): FeatureFlagSnapshotStore;
+declare function createFileFeatureFlagSnapshotStore(params?: {
+    rootDirectory?: string;
+}): FeatureFlagSnapshotStore;
+
+export { type FeatureFlagClientConfig, FeatureFlagError, FeatureFlagNetworkError, type FeatureFlagRuntimeSource, type FeatureFlagRuntimeStatus, type FeatureFlagSnapshotPersistenceConfig, type FeatureFlagSnapshotStore, FeatureFlagVerificationError, type FlagRegistry, type GenerateConfig, MergedFeatureFlags, type PersistedFeatureFlagSnapshot, createDefaultFeatureFlagRuntimeStatus, createFileFeatureFlagSnapshotStore, createLocalStorageFeatureFlagSnapshotStore };