@nexussdk/flags 0.0.1 → 0.0.3

package/src/client.ts

@@ -1,273 +0,0 @@
-/**
- * @fileoverview NexusFlagsClient — Full-featured feature flags SDK client.
- * In-memory evaluation, SSE real-time sync, ABAC targeting, and MurmurHash3 rollout.
- * @module @nexus/sdk-flags/client
- */
-
-import type {
-  FlagEvaluationResult,
-  FlagVariants,
-  FeatureFlag,
-  UserContext,
-} from '@nexussdk/contracts';
-import { resolveApiKey, resolveBaseUrl, fetchWithRetry } from '@nexussdk/core';
-import { evaluateFlag } from './evaluator.js';
-import { SSEManager } from './sse-manager.js';
-import { FlagStorage } from './storage.js';
-
-/**
- * Options for initializing the NexusFlagsClient.
- *
- * @example
- * const client = new NexusFlagsClient({
- *   apiKey: 'pk_live_...',
- *   baseUrl: 'http://localhost:8080',
- *   user: { id: 'usr_12345', country: 'VN' },
- *   realtime: true,
- * });
- */
-export interface NexusFlagsOptions {
-  /**
-   * Public API Key ('pk_live_...' or 'pk_test_...').
-   * If omitted, resolved automatically via env variables.
-   */
-  apiKey?: string;
-  /**
-   * Base ingestion URL. Defaults to 'https://api.nexus.dev'.
-   */
-  baseUrl?: string;
-  /**
-   * Initial user identity context for targeting and percentage rollouts.
-   */
-  user?: UserContext;
-  /**
-   * Pre-hydrated flags evaluated on the server (SSR) to prevent client-side UI flicker.
-   */
-  bootstrap?: Record<string, FlagEvaluationResult>;
-  /**
-   * Toggle real-time SSE updates. Defaults to true.
-   */
-  realtime?: boolean;
-  /**
-   * Network timeout in milliseconds for evaluation fetch. Defaults to 3000ms.
-   */
-  timeoutMs?: number;
-}
-
-/**
- * Public interface for the NexusFlagsClient.
- */
-export interface INexusFlagsClient {
-  /**
-   * Synchronously checks if a flag is active for the current user.
-   *
-   * @param key - Unique flag identifier.
-   * @param defaultValue - Fallback returned if flag is absent or evaluating.
-   * @returns `true` if the flag is enabled.
-   *
-   * @example
-   * const showBanner = client.isEnabled('promo_banner_v2', false);
-   */
-  isEnabled(key: string, defaultValue?: boolean): boolean;
-
-  /**
-   * Synchronously retrieves a specific dynamic configuration variant.
-   *
-   * @param key - Unique flag identifier.
-   * @param variantKey - Property inside the variant object.
-   * @param defaultValue - Fallback returned if flag/variant is missing.
-   * @returns The variant value cast to type T.
-   *
-   * @example
-   * const rate = client.getVariant<number>('promo_banner_v2', 'discount_rate', 10);
-   */
-  getVariant<T = unknown>(key: string, variantKey: string, defaultValue?: T): T;
-
-  /**
-   * Updates current user context and re-evaluates all flags.
-   *
-   * @param user - New user context to apply.
-   * @returns Promise that resolves after flags are refreshed.
-   *
-   * @example
-   * await client.identify({ id: 'usr_99', country: 'SG' });
-   */
-  identify(user: UserContext): Promise<void>;
-
-  /**
-   * Resets user context to an anonymous persistent device identifier.
-   *
-   * @example
-   * client.reset(); // called on logout
-   */
-  reset(): void;
-
-  /**
-   * Subscribes to runtime flag changes triggered by SSE updates.
-   *
-   * @param key - Flag key to observe.
-   * @param callback - Called with new evaluation result when the flag changes.
-   * @returns Unsubscribe function — call to remove the listener.
-   *
-   * @example
-   * const unsub = client.onFlagChange('checkout_v2', (result) => {
-   *   setCheckoutEnabled(result.enabled);
-   * });
-   * // On component unmount:
-   * unsub();
-   */
-  onFlagChange(key: string, callback: (result: FlagEvaluationResult) => void): () => void;
-
-  /**
-   * Gracefully shuts down active SSE connections and observers.
-   *
-   * @example
-   * client.destroy();
-   */
-  destroy(): void;
-}
-
-/**
- * Feature Flags Client — the primary SDK entry point for flag evaluation.
- *
- * @implements {INexusFlagsClient}
- *
- * @example
- * const client = new NexusFlagsClient({ apiKey: 'pk_live_...' });
- * const enabled = client.isEnabled('new_checkout', false);
- */
-export class NexusFlagsClient implements INexusFlagsClient {
-  private readonly apiKey: string;
-  private readonly baseUrl: string;
-  private readonly timeoutMs: number;
-  private user: UserContext;
-  private readonly storage: FlagStorage;
-  private readonly listeners = new Map<string, Set<(res: FlagEvaluationResult) => void>>();
-  private sseManager?: SSEManager;
-  private flagDefinitions = new Map<string, FeatureFlag>();
-
-  constructor(options: NexusFlagsOptions = {}) {
-    this.apiKey = resolveApiKey(options.apiKey);
-    this.baseUrl = resolveBaseUrl(options.baseUrl);
-    this.timeoutMs = options.timeoutMs ?? 3_000;
-    this.storage = new FlagStorage(this.apiKey.substring(0, 16));
-    this.user = options.user ?? { id: this.storage.getOrCreateAnonymousId() };
-
-    // Hydrate bootstrap flags (SSR pre-evaluation)
-    if (options.bootstrap) {
-      this.storage.setAll(options.bootstrap);
-    }
-
-    if (options.realtime !== false) {
-      this.initRealtimeSync();
-    }
-
-    // Prefetch flags asynchronously on init
-    void this.refreshFlags();
-  }
-
-  /**
-   * Evaluates whether a given feature flag is enabled for the current context.
-   */
-  public isEnabled(key: string, defaultValue = false): boolean {
-    const cached = this.storage.get(key);
-    return cached !== undefined ? cached.enabled : defaultValue;
-  }
-
-  /**
-   * Retrieves a typed variant configuration for an active feature flag.
-   */
-  public getVariant<T = unknown>(key: string, variantKey: string, defaultValue?: T): T {
-    const cached = this.storage.get(key);
-    if (!cached?.enabled || !cached.variants) {
-      return defaultValue as T;
-    }
-    const value = (cached.variants as FlagVariants)[variantKey];
-    return value !== undefined ? (value as T) : (defaultValue as T);
-  }
-
-  /**
-   * Identifies an authenticated user and triggers a flag evaluation refresh.
-   */
-  public async identify(user: UserContext): Promise<void> {
-    this.user = { ...this.user, ...user };
-    await this.refreshFlags();
-  }
-
-  /**
-   * Resets the active user context to a new anonymous identifier.
-   */
-  public reset(): void {
-    this.user = { id: this.storage.getOrCreateAnonymousId() };
-    void this.refreshFlags();
-  }
-
-  /**
-   * Registers a listener callback invoked when a flag's evaluation state changes.
-   */
-  public onFlagChange(key: string, callback: (result: FlagEvaluationResult) => void): () => void {
-    if (!this.listeners.has(key)) {
-      this.listeners.set(key, new Set());
-    }
-    this.listeners.get(key)!.add(callback);
-    return () => this.listeners.get(key)?.delete(callback);
-  }
-
-  /**
-   * Destroys the client, terminating SSE connections and clearing listeners.
-   */
-  public destroy(): void {
-    this.sseManager?.disconnect();
-    this.listeners.clear();
-    this.storage.clear();
-  }
-
-  private initRealtimeSync(): void {
-    this.sseManager = new SSEManager({
-      url: `${this.baseUrl}/api/v1/flags/stream`,
-      apiKey: this.apiKey,
-      onEvent: (event) => {
-        if (event.type === 'FLAG_UPDATE' && event.data) {
-          // Use locally evaluated result if we have the flag definition
-          const flagDef = this.flagDefinitions.get(event.key);
-          const result = flagDef
-            ? evaluateFlag(flagDef, this.user)
-            : event.data;
-
-          this.storage.set(event.key, result);
-          this.listeners.get(event.key)?.forEach((cb) => cb(result));
-        } else if (event.type === 'FLAG_DELETE') {
-          this.storage.delete(event.key);
-          this.flagDefinitions.delete(event.key);
-        }
-      },
-    });
-    this.sseManager.connect();
-  }
-
-  private async refreshFlags(): Promise<void> {
-    try {
-      const result = await fetchWithRetry<Record<string, FeatureFlag>>({
-        url: `${this.baseUrl}/api/v1/flags/eval`,
-        method: 'GET',
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          'X-Nexus-User-Id': this.user.id ?? 'anon',
-          'X-Nexus-Country': this.user.country ?? '',
-        },
-        timeoutMs: this.timeoutMs,
-        maxRetries: 2,
-      });
-
-      for (const [key, flag] of Object.entries(result.data)) {
-        this.flagDefinitions.set(key, flag);
-        const evaluated = evaluateFlag(flag, this.user);
-        this.storage.set(key, evaluated);
-        this.listeners.get(key)?.forEach((cb) => cb(evaluated));
-      }
-    } catch {
-      // Offline fallback: retain existing in-memory cache silently
-      // Never throw from a background refresh — host app must not be affected
-    }
-  }
-}

package/src/evaluator.ts

@@ -1,268 +0,0 @@
-/**
- * @fileoverview MurmurHash3 32-bit implementation and ABAC rule evaluator.
- * Pure TypeScript — no external dependencies. Implements deterministic rollout bucketing.
- * @module @nexus/sdk-flags/evaluator
- */
-
-import type { FeatureFlag, FlagEvaluationResult, TargetingRule, UserContext } from '@nexussdk/contracts';
-
-// ---------------------------------------------------------------------------
-// MurmurHash3 32-bit Implementation (Pure TypeScript)
-// Used for deterministic user-to-bucket mapping without server round-trips.
-// ---------------------------------------------------------------------------
-
-/**
- * Converts a string to a Uint32 MurmurHash3 hash.
- * Implements the MurmurHash3 32-bit algorithm (x86 variant).
- *
- * @param key - Input string to hash.
- * @param seed - Optional seed value. Defaults to 0.
- * @returns Unsigned 32-bit integer hash value.
- *
- * @example
- * const hash = murmur3('user123:checkout_v2', 0);
- * const bucket = hash % 100; // 0-99 deterministic bucket
- */
-export function murmur3(key: string, seed = 0): number {
-  let h = seed >>> 0;
-  const c1 = 0xcc9e2d51;
-  const c2 = 0x1b873593;
-
-  let i = 0;
-  // Process 4-byte chunks
-  const length4 = Math.floor(key.length / 4) * 4;
-  while (i < length4) {
-    let k =
-      ((key.charCodeAt(i) & 0xff)) |
-      ((key.charCodeAt(i + 1) & 0xff) << 8) |
-      ((key.charCodeAt(i + 2) & 0xff) << 16) |
-      ((key.charCodeAt(i + 3) & 0xff) << 24);
-
-    k = Math.imul(k, c1);
-    k = (k << 15) | (k >>> 17);
-    k = Math.imul(k, c2);
-
-    h ^= k;
-    h = (h << 13) | (h >>> 19);
-    h = (Math.imul(h, 5) + 0xe6546b64) >>> 0;
-    i += 4;
-  }
-
-  // Process remaining bytes
-  let k2 = 0;
-  const rem = key.length & 3;
-  if (rem >= 3) k2 ^= (key.charCodeAt(i + 2) & 0xff) << 16;
-  if (rem >= 2) k2 ^= (key.charCodeAt(i + 1) & 0xff) << 8;
-  if (rem >= 1) {
-    k2 ^= key.charCodeAt(i) & 0xff;
-    k2 = Math.imul(k2, c1);
-    k2 = (k2 << 15) | (k2 >>> 17);
-    k2 = Math.imul(k2, c2);
-    h ^= k2;
-  }
-
-  // Finalization mix
-  h ^= key.length;
-  h ^= h >>> 16;
-  h = Math.imul(h, 0x85ebca6b);
-  h ^= h >>> 13;
-  h = Math.imul(h, 0xc2b2ae35);
-  h ^= h >>> 16;
-
-  return h >>> 0; // Ensure unsigned
-}
-
-/**
- * Computes the deterministic rollout bucket (0-99) for a given user+flag combination.
- * Uses MurmurHash3 for even distribution without server state.
- *
- * @param userId - User's unique identifier (anonymous ID if not authenticated).
- * @param flagKey - Flag programmatic key.
- * @returns Bucket value between 0 and 99 (inclusive).
- *
- * @example
- * const bucket = computeRolloutBucket('usr_12345', 'checkout_v2');
- * // isEnabled = bucket < flag.rolloutPercentage
- */
-export function computeRolloutBucket(userId: string, flagKey: string): number {
-  const hashInput = `${userId}:${flagKey}`;
-  return murmur3(hashInput) % 100;
-}
-
-// ---------------------------------------------------------------------------
-// ABAC Rule Evaluator
-// ---------------------------------------------------------------------------
-
-/**
- * Performs a simple semantic version comparison.
- * Compares two semver strings in "MAJOR.MINOR.PATCH" format.
- *
- * @param a - First version string.
- * @param b - Second version string.
- * @returns Positive if a > b, negative if a < b, 0 if equal.
- */
-function compareSemver(a: string, b: string): number {
-  const partsA = a.replace(/^v/, '').split('.').map(Number);
-  const partsB = b.replace(/^v/, '').split('.').map(Number);
-  for (let i = 0; i < 3; i++) {
-    const diff = (partsA[i] ?? 0) - (partsB[i] ?? 0);
-    if (diff !== 0) return diff;
-  }
-  return 0;
-}
-
-/**
- * Extracts a nested attribute value from the UserContext by dot-notation path.
- *
- * @param ctx - UserContext object.
- * @param attributePath - Dot-separated path (e.g. "custom.tier", "country").
- * @returns The attribute value or `undefined` if not found.
- */
-function resolveAttribute(ctx: UserContext, attributePath: string): unknown {
-  const parts = attributePath.split('.');
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let current: any = ctx;
-  for (const part of parts) {
-    if (current == null || typeof current !== 'object') return undefined;
-    current = current[part];
-  }
-  return current;
-}
-
-/**
- * Evaluates a single targeting rule against the user context.
- *
- * @param rule - The ABAC targeting rule to evaluate.
- * @param userCtx - The current user context.
- * @returns `true` if the rule passes for this user.
- */
-function evaluateSingleRule(rule: TargetingRule, userCtx: UserContext): boolean {
-  const userValue = resolveAttribute(userCtx, rule.attribute);
-  const targets = rule.values;
-
-  switch (rule.operator) {
-    case 'EQUALS':
-      return userValue === targets[0];
-    case 'NOT_EQUALS':
-      return userValue !== targets[0];
-    case 'IN':
-      return targets.includes(userValue as string | number | boolean);
-    case 'NOT_IN':
-      return !targets.includes(userValue as string | number | boolean);
-    case 'CONTAINS':
-      return typeof userValue === 'string' && userValue.includes(String(targets[0]));
-    case 'NOT_CONTAINS':
-      return typeof userValue === 'string' && !userValue.includes(String(targets[0]));
-    case 'STARTS_WITH':
-      return typeof userValue === 'string' && userValue.startsWith(String(targets[0]));
-    case 'ENDS_WITH':
-      return typeof userValue === 'string' && userValue.endsWith(String(targets[0]));
-    case 'GREATER_THAN':
-      return typeof userValue === 'number' && userValue > Number(targets[0]);
-    case 'LESS_THAN':
-      return typeof userValue === 'number' && userValue < Number(targets[0]);
-    case 'SEMVER_GTE':
-      return (
-        typeof userValue === 'string' &&
-        typeof targets[0] === 'string' &&
-        compareSemver(userValue, String(targets[0])) >= 0
-      );
-    case 'SEMVER_LTE':
-      return (
-        typeof userValue === 'string' &&
-        typeof targets[0] === 'string' &&
-        compareSemver(userValue, String(targets[0])) <= 0
-      );
-    default:
-      return false;
-  }
-}
-
-/**
- * Evaluates a FeatureFlag against a UserContext using the full ABAC + rollout engine.
- *
- * Evaluation Order:
- * 1. Kill-switch check (`isEnabled === false` → KILL_SWITCH)
- * 2. All targeting rules must pass (ABAC evaluation)
- * 3. Percentage rollout via MurmurHash3 bucketing
- * 4. Default enabled state
- *
- * @param flag - The feature flag definition from the cache.
- * @param userCtx - Current user context for targeting evaluation.
- * @returns Full {@link FlagEvaluationResult} with reason explanation.
- *
- * @example
- * const result = evaluateFlag(flag, { id: 'usr_12345', country: 'VN' });
- * if (result.enabled) {
- *   console.log(result.variants.discount_rate); // 20
- * }
- */
-export function evaluateFlag(flag: FeatureFlag, userCtx: UserContext): FlagEvaluationResult {
-  // Step 1: Kill-switch
-  if (!flag.isEnabled) {
-    return {
-      key: flag.key,
-      enabled: false,
-      variants: {},
-      reason: 'KILL_SWITCH',
-      version: flag.version,
-    };
-  }
-
-  // Step 2: ABAC targeting rules — all must pass (AND logic)
-  if (flag.targetingRules.length > 0) {
-    const allRulesPass = flag.targetingRules.every((rule) =>
-      evaluateSingleRule(rule, userCtx),
-    );
-    if (!allRulesPass) {
-      return {
-        key: flag.key,
-        enabled: false,
-        variants: {},
-        reason: 'FALLBACK',
-        version: flag.version,
-      };
-    }
-    // All targeting rules matched
-    if (flag.rolloutPercentage >= 100) {
-      return {
-        key: flag.key,
-        enabled: true,
-        variants: flag.variants,
-        reason: 'TARGETING_MATCH',
-        version: flag.version,
-      };
-    }
-  }
-
-  // Step 3: Percentage rollout (MurmurHash3)
-  if (flag.rolloutPercentage > 0) {
-    const userId = userCtx.id ?? 'anon';
-    const bucket = computeRolloutBucket(userId, flag.key);
-    if (bucket < flag.rolloutPercentage) {
-      return {
-        key: flag.key,
-        enabled: true,
-        variants: flag.variants,
-        reason: flag.targetingRules.length > 0 ? 'TARGETING_MATCH' : 'ROLLOUT_MATCH',
-        version: flag.version,
-      };
-    }
-    return {
-      key: flag.key,
-      enabled: false,
-      variants: {},
-      reason: 'FALLBACK',
-      version: flag.version,
-    };
-  }
-
-  // Step 4: Full kill-switch off (rolloutPercentage === 0 with no rules)
-  return {
-    key: flag.key,
-    enabled: false,
-    variants: {},
-    reason: 'KILL_SWITCH',
-    version: flag.version,
-  };
-}

package/src/index.ts

@@ -1,14 +0,0 @@
-/**
- * @fileoverview Public export interface for @nexussdk/flags.
- *
- * @example
- * import { NexusFlagsClient } from '@nexussdk/flags';
- * const client = new NexusFlagsClient({ apiKey: 'pk_live_...' });
- */
-
-export { NexusFlagsClient } from './client.js';
-export type { NexusFlagsOptions, INexusFlagsClient } from './client.js';
-export { evaluateFlag, murmur3, computeRolloutBucket } from './evaluator.js';
-export { SSEManager } from './sse-manager.js';
-export type { SSEManagerOptions } from './sse-manager.js';
-export { FlagStorage } from './storage.js';