flagcraft 0.1.0

package/dist/cache.d.ts

@@ -0,0 +1,31 @@
+import { FlagDefinition, Ruleset } from './types.js';
+/**
+ * In-memory store for flag definitions and ETag.
+ * Replaces the entire cached ruleset atomically on updates.
+ */
+export declare class InMemoryCache {
+    private ruleset;
+    private flagMap;
+    private lastUpdated;
+    /**
+     * Checks if the cache has a valid state (has been initialized and not expired).
+     */
+    isStateValid(maxAge: number): boolean;
+    /**
+     * Replaces the entire cached ruleset atomically and updates the internal lookup map.
+     */
+    setRuleset(ruleset: Ruleset): void;
+    /**
+     * Retrieves a flag definition by its key in O(1) time.
+     */
+    getFlag(key: string): FlagDefinition | undefined;
+    /**
+     * Retrieves the current ETag associated with the cached ruleset.
+     */
+    getEtag(): string | null;
+    /**
+     * Retrieves the entire cached ruleset.
+     */
+    getRuleset(): Ruleset | null;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErD;;;GAGG;AACH,qBAAa,aAAa;IACtB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,OAAO,CAA0C;IACzD,OAAO,CAAC,WAAW,CAAqB;IAExC;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAKrC;;OAEG;IACI,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IASzC;;OAEG;IACI,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAIvD;;OAEG;IACI,OAAO,IAAI,MAAM,GAAG,IAAI;IAI/B;;OAEG;IACI,UAAU,IAAI,OAAO,GAAG,IAAI;CAGtC"}

package/dist/cache.js

@@ -0,0 +1,47 @@
+/**
+ * In-memory store for flag definitions and ETag.
+ * Replaces the entire cached ruleset atomically on updates.
+ */
+export class InMemoryCache {
+    ruleset = null;
+    flagMap = new Map();
+    lastUpdated = null;
+    /**
+     * Checks if the cache has a valid state (has been initialized and not expired).
+     */
+    isStateValid(maxAge) {
+        if (!this.lastUpdated)
+            return false;
+        return (Date.now() - this.lastUpdated.getTime()) <= maxAge;
+    }
+    /**
+     * Replaces the entire cached ruleset atomically and updates the internal lookup map.
+     */
+    setRuleset(ruleset) {
+        this.ruleset = ruleset;
+        this.lastUpdated = new Date();
+        this.flagMap.clear();
+        for (const flag of ruleset.flags) {
+            this.flagMap.set(flag.key, flag);
+        }
+    }
+    /**
+     * Retrieves a flag definition by its key in O(1) time.
+     */
+    getFlag(key) {
+        return this.flagMap.get(key);
+    }
+    /**
+     * Retrieves the current ETag associated with the cached ruleset.
+     */
+    getEtag() {
+        return this.ruleset ? this.ruleset.etag : null;
+    }
+    /**
+     * Retrieves the entire cached ruleset.
+     */
+    getRuleset() {
+        return this.ruleset;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,OAAO,aAAa;IACd,OAAO,GAAmB,IAAI,CAAC;IAC/B,OAAO,GAAgC,IAAI,GAAG,EAAE,CAAC;IACjD,WAAW,GAAgB,IAAI,CAAC;IAExC;;OAEG;IACH,YAAY,CAAC,MAAc;QACvB,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,OAAO,KAAK,CAAC;QACpC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,IAAI,MAAM,CAAC;IAC/D,CAAC;IAED;;OAEG;IACI,UAAU,CAAC,OAAgB;QAC9B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC;QAC9B,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAC/B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACrC,CAAC;IACL,CAAC;IAED;;OAEG;IACI,OAAO,CAAC,GAAW;QACtB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACI,OAAO;QACV,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACnD,CAAC;IAED;;OAEG;IACI,UAAU;QACb,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;CACJ"}

package/dist/client.d.ts

@@ -0,0 +1,45 @@
+import { EvaluationContext, FeatureFlagConfig, FlagDefinition } from './types.js';
+/**
+ * FeatureFlagClient is the main entry point for the flagcraft package.
+ * It provides zero-latency local flag evaluation, conditional ETag polling, and fail-open resilience.
+ */
+export declare class FeatureFlagClient {
+    private config;
+    private cache;
+    private poller;
+    private initialized;
+    private lastSuccessfulFetch;
+    private connectionStatus;
+    private consicutiveFailure;
+    private metricsQueue;
+    private flushTimer;
+    constructor(config: FeatureFlagConfig);
+    private flushMetrics;
+    trackMetrics(flagKey: string, isError: boolean): void;
+    private updateStatus;
+    getConnectionStatus(): 'connected' | 'degraded' | 'disconnected';
+    /**
+     * Bootstraps the SDK by performing an initial fetch of rulesets and starting the background polling loop.
+     * Guaranteed fail-open: never throws an error if the initial network call fails.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Evaluates a boolean feature flag from local memory in < 1ms.
+     * If the flag is not found, checks defaultValues from config, and falls back to false.
+     */
+    isEnabled(flagKey: string, context: EvaluationContext): boolean;
+    /**
+     * Evaluates a feature flag of any type (string, number, json, boolean) from local memory.
+     * If the flag is not found, returns the configured default value or undefined.
+     */
+    getValue(flagKey: string, context: EvaluationContext): unknown;
+    /**
+     * Returns a map of all currently cached flag definitions.
+     */
+    getAllFlags(): Record<string, FlagDefinition>;
+    /**
+     * Stops the polling loop and clears the cache. Should be called when shutting down the host application.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAW,MAAM,YAAY,CAAC;AAK3F;;;GAGG;AACH,qBAAa,iBAAiB;IAWd,OAAO,CAAC,MAAM;IAV1B,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,mBAAmB,CAAqB;IAChD,OAAO,CAAC,gBAAgB,CAA6D;IACrF,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,YAAY,CAAoD;IACxE,OAAO,CAAC,UAAU,CAA+C;gBAG7C,MAAM,EAAE,iBAAiB;YAgC/B,YAAY;IA0B1B,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IASrD,OAAO,CAAC,YAAY;IAUb,mBAAmB,IAAI,WAAW,GAAG,UAAU,GAAG,cAAc;IAIvE;;;OAGG;IACU,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBxC;;;OAGG;IACI,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO;IAYtE;;;OAGG;IACI,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO;IAWrE;;OAEG;IACI,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC;IAWpD;;OAEG;IACI,OAAO,IAAI,IAAI;CAUzB"}

package/dist/client.js

@@ -0,0 +1,168 @@
+import { InMemoryCache } from './cache.js';
+import { Poller } from './poller.js';
+import { evaluateFlag } from './evaluator.js';
+/**
+ * FeatureFlagClient is the main entry point for the flagcraft package.
+ * It provides zero-latency local flag evaluation, conditional ETag polling, and fail-open resilience.
+ */
+export class FeatureFlagClient {
+    config;
+    cache;
+    poller;
+    initialized = false;
+    lastSuccessfulFetch = null;
+    connectionStatus = 'disconnected';
+    consicutiveFailure = 0;
+    metricsQueue = [];
+    flushTimer = null;
+    constructor(config) {
+        this.config = config;
+        this.cache = new InMemoryCache();
+        const baseUrl = config.baseUrl || 'http://localhost:3001';
+        const interval = config.pollingInterval || 30000;
+        const onError = config.onError || ((err) => {
+            console.error('[FeatureFlagClient] Error:', err.message);
+        });
+        this.poller = new Poller({
+            baseUrl,
+            apiKey: config.apiKey,
+            interval,
+            onUpdate: (ruleset) => {
+                this.cache.setRuleset(ruleset);
+            },
+            onError,
+            onFetchSuccess: () => {
+                this.lastSuccessfulFetch = new Date();
+                this.consicutiveFailure = 0;
+                this.updateStatus('connected');
+            },
+            onFetchError: () => {
+                this.consicutiveFailure++;
+                this.updateStatus(this.consicutiveFailure < 3 ? 'degraded' : 'disconnected');
+            }
+        });
+        this.flushTimer = setInterval(() => {
+            this.flushMetrics();
+        }, 5000);
+    }
+    async flushMetrics() {
+        if (this.metricsQueue.length === 0)
+            return;
+        const batch = this.metricsQueue.splice(0, this.metricsQueue.length);
+        const baseUrl = this.config.baseUrl || 'http://localhost:3001';
+        try {
+            const url = `${baseUrl}/sdk/metrics`;
+            const payload = JSON.stringify({ metrics: batch });
+            await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.config.apiKey,
+                },
+                keepalive: true,
+                body: payload
+            });
+        }
+        catch (error) {
+            if (this.config.onError) {
+                this.config.onError(error instanceof Error ? error : new Error('Failed to flush metrics'));
+            }
+        }
+    }
+    trackMetrics(flagKey, isError) {
+        this.metricsQueue.push({
+            flagKey, isError
+        });
+        if (this.metricsQueue.length >= 100) {
+            this.flushMetrics();
+        }
+    }
+    updateStatus(newStatus) {
+        if (this.connectionStatus !== newStatus) {
+            this.connectionStatus = newStatus;
+            if (this.config.onConnectionStatusChange) {
+                this.config.onConnectionStatusChange(newStatus);
+            }
+        }
+    }
+    getConnectionStatus() {
+        return this.connectionStatus;
+    }
+    /**
+     * Bootstraps the SDK by performing an initial fetch of rulesets and starting the background polling loop.
+     * Guaranteed fail-open: never throws an error if the initial network call fails.
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        try {
+            await this.poller.fetchRuleset();
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            if (this.config.onError) {
+                this.config.onError(err);
+            }
+            else {
+                console.error('[FeatureFlagClient] Initialization failed (fail-open mode active):', err.message);
+            }
+        }
+        finally {
+            this.initialized = true;
+            this.poller.start();
+        }
+    }
+    /**
+     * Evaluates a boolean feature flag from local memory in < 1ms.
+     * If the flag is not found, checks defaultValues from config, and falls back to false.
+     */
+    isEnabled(flagKey, context) {
+        const flag = this.cache.getFlag(flagKey);
+        if (!flag) {
+            const defaultVal = this.config.defaultValues?.[flagKey];
+            return typeof defaultVal === 'boolean' ? defaultVal : false;
+        }
+        const val = evaluateFlag(flag, context);
+        this.trackMetrics(flagKey, false);
+        return Boolean(val);
+    }
+    /**
+     * Evaluates a feature flag of any type (string, number, json, boolean) from local memory.
+     * If the flag is not found, returns the configured default value or undefined.
+     */
+    getValue(flagKey, context) {
+        const flag = this.cache.getFlag(flagKey);
+        if (!flag) {
+            return this.config.defaultValues?.[flagKey];
+        }
+        const val = evaluateFlag(flag, context);
+        this.trackMetrics(flagKey, false);
+        return val;
+    }
+    /**
+     * Returns a map of all currently cached flag definitions.
+     */
+    getAllFlags() {
+        const ruleset = this.cache.getRuleset();
+        if (!ruleset || !ruleset.flags)
+            return {};
+        const map = {};
+        for (const flag of ruleset.flags) {
+            map[flag.key] = flag;
+        }
+        return map;
+    }
+    /**
+     * Stops the polling loop and clears the cache. Should be called when shutting down the host application.
+     */
+    destroy() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        this.poller.stop();
+        this.cache.setRuleset({ flags: [], etag: '' });
+        this.initialized = false;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/evaluator.d.ts

@@ -0,0 +1,40 @@
+import { EvaluationContext, FlagRule, FlagDefinition } from "./types.js";
+/**
+ * Deterministic rollout bucketing according to claude.md §7:
+ * bucket = hash(flag_key + user_id) % 100 -> returns stable value in [0, 99]
+ */
+export declare function hashBucket(flagKey: string, userId: string): number;
+/**
+ * Evaluates whether a user falls within the rollout percentage [0, 100]
+ */
+export declare function isUserInRollout(flagKey: string, userId: string, rolloutPct: number): boolean;
+export interface TargetingConditions {
+    [attribute: string]: unknown;
+}
+export interface TargetingRuleInput {
+    priority: number;
+    conditions: TargetingConditions;
+    value: unknown;
+}
+/**
+ * Checks whether a user's attributes satisfy ALL conditions in a rule.
+ * A rule matches only if every condition key matches the user's corresponding attribute.
+ */
+export declare function matchesConditions(conditions: TargetingConditions, attributes: Record<string, unknown>): boolean;
+/**
+ * Evaluates targeting rules in priority order against user attributes.
+ * Returns the value of the first matching rule, or undefined if no rule matches.
+ *
+ * Rules must be sorted by priority ASC (lowest number = highest priority).
+ */
+export declare function evaluateRules(rules: TargetingRuleInput[], attributes: Record<string, unknown>): unknown | undefined;
+export declare function evaluateFlags(rules: FlagRule[], context: EvaluationContext): unknown;
+/**
+ * Evaluates a complete FlagDefinition against an EvaluationContext.
+ * Order:
+ * 1. If !flag.enabled -> return flag.defaultValue
+ * 2. Check targeting rules in priority order. If match -> return rule.value
+ * 3. Check rollout bucketing: if user is in rollout -> return true (or active value); otherwise flag.defaultValue
+ */
+export declare function evaluateFlag(flag: FlagDefinition, context: EvaluationContext): unknown;
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../src/evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAgBzE;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAIlE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAM5F;AAID,MAAM,WAAW,mBAAmB;IAChC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,mBAAmB,CAAC;IAChC,KAAK,EAAE,OAAO,CAAC;CAClB;AAiDD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC7B,UAAU,EAAE,mBAAmB,EAC/B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,OAAO,CAUT;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CACzB,KAAK,EAAE,kBAAkB,EAAE,EAC3B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,OAAO,GAAG,SAAS,CAOrB;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,iBAAiB,WAG1E;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAmBtF"}

package/dist/evaluator.js

@@ -0,0 +1,135 @@
+/**
+ * Fast, pure-TypeScript FNV-1a 32-bit hash function.
+ * Zero external dependencies — works identically in Node.js and Browser SDKs.
+ */
+function fnv1aHash(str) {
+    let hash = 0x811c9dc5; // FNV offset basis
+    for (let i = 0; i < str.length; i++) {
+        hash ^= str.charCodeAt(i);
+        // Multiply by FNV prime (0x01000193) using bit shifts to maintain 32-bit integer arithmetic
+        hash += (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24);
+    }
+    return hash >>> 0; // Ensure unsigned 32-bit integer
+}
+/**
+ * Deterministic rollout bucketing according to claude.md §7:
+ * bucket = hash(flag_key + user_id) % 100 -> returns stable value in [0, 99]
+ */
+export function hashBucket(flagKey, userId) {
+    const combined = `${flagKey}:${userId}`;
+    const hashValue = fnv1aHash(combined);
+    return hashValue % 100;
+}
+/**
+ * Evaluates whether a user falls within the rollout percentage [0, 100]
+ */
+export function isUserInRollout(flagKey, userId, rolloutPct) {
+    if (rolloutPct <= 0)
+        return false;
+    if (rolloutPct >= 100)
+        return true;
+    const bucket = hashBucket(flagKey, userId);
+    return bucket < rolloutPct;
+}
+/**
+ * Evaluates a single condition value against a user's attribute value.
+ *
+ * Supported formats:
+ *   - Exact match:  { "plan": "enterprise" }
+ *   - Operators:    { "age": { "$gte": 18 } }
+ *
+ * Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin
+ */
+function matchConditionValue(userValue, conditionValue) {
+    // Operator object: { "$gte": 18, "$lt": 65 }
+    if (conditionValue !== null && typeof conditionValue === 'object' && !Array.isArray(conditionValue)) {
+        const ops = conditionValue;
+        const keys = Object.keys(ops);
+        // Only treat as operator object if all keys start with $
+        if (keys.length > 0 && keys.every(k => k.startsWith('$'))) {
+            return keys.every(op => {
+                const operand = ops[op];
+                switch (op) {
+                    case '$eq':
+                        return userValue === operand;
+                    case '$ne':
+                        return userValue !== operand;
+                    case '$gt':
+                        return typeof userValue === 'number' && typeof operand === 'number' && userValue > operand;
+                    case '$gte':
+                        return typeof userValue === 'number' && typeof operand === 'number' && userValue >= operand;
+                    case '$lt':
+                        return typeof userValue === 'number' && typeof operand === 'number' && userValue < operand;
+                    case '$lte':
+                        return typeof userValue === 'number' && typeof operand === 'number' && userValue <= operand;
+                    case '$in':
+                        return Array.isArray(operand) && operand.includes(userValue);
+                    case '$nin':
+                        return Array.isArray(operand) && !operand.includes(userValue);
+                    default:
+                        return false; // Unknown operator = no match
+                }
+            });
+        }
+    }
+    // Exact match (string, number, boolean, null)
+    return userValue === conditionValue;
+}
+/**
+ * Checks whether a user's attributes satisfy ALL conditions in a rule.
+ * A rule matches only if every condition key matches the user's corresponding attribute.
+ */
+export function matchesConditions(conditions, attributes) {
+    for (const [key, conditionValue] of Object.entries(conditions)) {
+        const userValue = attributes[key];
+        // If user doesn't have the attribute, the condition cannot match
+        if (userValue === undefined)
+            return false;
+        if (!matchConditionValue(userValue, conditionValue))
+            return false;
+    }
+    return true;
+}
+/**
+ * Evaluates targeting rules in priority order against user attributes.
+ * Returns the value of the first matching rule, or undefined if no rule matches.
+ *
+ * Rules must be sorted by priority ASC (lowest number = highest priority).
+ */
+export function evaluateRules(rules, attributes) {
+    for (const rule of rules) {
+        if (matchesConditions(rule.conditions, attributes)) {
+            return rule.value;
+        }
+    }
+    return undefined;
+}
+export function evaluateFlags(rules, context) {
+    const sortedRules = [...rules].sort((a, b) => a.priority - b.priority);
+    return evaluateRules(sortedRules, context.attributes || {});
+}
+/**
+ * Evaluates a complete FlagDefinition against an EvaluationContext.
+ * Order:
+ * 1. If !flag.enabled -> return flag.defaultValue
+ * 2. Check targeting rules in priority order. If match -> return rule.value
+ * 3. Check rollout bucketing: if user is in rollout -> return true (or active value); otherwise flag.defaultValue
+ */
+export function evaluateFlag(flag, context) {
+    if (!flag.enabled) {
+        return flag.defaultValue;
+    }
+    if (flag.rules && flag.rules.length > 0) {
+        const sortedRules = [...flag.rules].sort((a, b) => a.priority - b.priority);
+        const ruleValue = evaluateRules(sortedRules, context.attributes || {});
+        if (ruleValue !== undefined) {
+            return ruleValue;
+        }
+    }
+    const inRollout = isUserInRollout(flag.key, context.userId, flag.rolloutPct);
+    if (!inRollout) {
+        return flag.defaultValue;
+    }
+    return typeof flag.defaultValue === 'boolean' ? true : flag.defaultValue;
+}
+//# sourceMappingURL=evaluator.js.map

package/dist/evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.js","sourceRoot":"","sources":["../src/evaluator.ts"],"names":[],"mappings":"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"}

package/dist/hash.d.ts

@@ -0,0 +1,2 @@
+export declare function hashBucket(flagKey: string, userId: string): number;
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAUA,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAIlE"}

package/dist/hash.js

@@ -0,0 +1,14 @@
+function fnv1aHash(str) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < str.length; i++) {
+        hash ^= str.charCodeAt(i);
+        hash += (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24);
+    }
+    return hash >>> 0;
+}
+export function hashBucket(flagKey, userId) {
+    const combined = `${flagKey}:${userId}`;
+    const hashValue = fnv1aHash(combined);
+    return hashValue % 100;
+}
+//# sourceMappingURL=hash.js.map

package/dist/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAAA,SAAS,SAAS,CAAC,GAAW;IAC1B,IAAI,IAAI,GAAG,UAAU,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC1B,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC;AACtB,CAAC;AAGD,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,MAAc;IACtD,MAAM,QAAQ,GAAG,GAAG,OAAO,IAAI,MAAM,EAAE,CAAC;IACxC,MAAM,SAAS,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IACtC,OAAO,SAAS,GAAG,GAAG,CAAC;AAC3B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { FeatureFlagClient, FeatureFlagClient as FlagCraft, FeatureFlagClient as FlagCraftSDK, FeatureFlagClient as VanguardSDK } from './client.js';
+export { InMemoryCache } from './cache.js';
+export { Poller } from './poller.js';
+export { hashBucket, isUserInRollout, evaluateRules, matchesConditions, evaluateFlag, evaluateFlags } from './evaluator.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,IAAI,SAAS,EAAE,iBAAiB,IAAI,YAAY,EAAE,iBAAiB,IAAI,WAAW,EAAE,MAAM,aAAa,CAAC;AACrJ,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,iBAAiB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC5H,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { FeatureFlagClient, FeatureFlagClient as FlagCraft, FeatureFlagClient as FlagCraftSDK, FeatureFlagClient as VanguardSDK } from './client.js';
+export { InMemoryCache } from './cache.js';
+export { Poller } from './poller.js';
+export { hashBucket, isUserInRollout, evaluateRules, matchesConditions, evaluateFlag, evaluateFlags } from './evaluator.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,IAAI,SAAS,EAAE,iBAAiB,IAAI,YAAY,EAAE,iBAAiB,IAAI,WAAW,EAAE,MAAM,aAAa,CAAC;AACrJ,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,iBAAiB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC5H,cAAc,YAAY,CAAC"}

package/dist/poller.d.ts

@@ -0,0 +1,43 @@
+import { Ruleset } from './types.js';
+export interface PollerConfig {
+    baseUrl: string;
+    apiKey: string;
+    interval: number;
+    onUpdate: (ruleset: Ruleset) => void;
+    onError: (error: Error) => void;
+    onFetchSuccess?: () => void;
+    onFetchError?: () => void;
+}
+/**
+ * Conditional polling loop for fetching rulesets using ETag / 304 Not Modified.
+ * Uses the native `fetch` API.
+ */
+export declare class Poller {
+    private config;
+    private timer;
+    private currentEtag;
+    private isPolling;
+    private failureCount;
+    private _lastError;
+    constructor(config: PollerConfig);
+    get lastError(): Error | null;
+    /**
+     * Begins the periodic polling loop.
+     */
+    start(): void;
+    /**
+     * Stops the polling loop.
+     */
+    stop(): void;
+    private scheduleNext;
+    /**
+     * Fetches the latest ruleset from the API server using conditional polling (`If-None-Match`).
+     * - 200: Parses ruleset, updates current ETag, and calls `onUpdate`.
+     * - 304: No-op.
+     * - Error: Catches error, calls `onError`, and never throws to ensure fail-open resilience.
+     */
+    fetchRuleset(etag?: string | null): Promise<void>;
+    onFetchSuccess(): void;
+    onFetchError(): void;
+}
+//# sourceMappingURL=poller.d.ts.map

package/dist/poller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poller.d.ts","sourceRoot":"","sources":["../src/poller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACrC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAChC,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED;;;GAGG;AACH,qBAAa,MAAM;IAOH,OAAO,CAAC,MAAM;IAN1B,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,UAAU,CAAsB;gBAEpB,MAAM,EAAE,YAAY;IAExC,IAAW,SAAS,IAAI,KAAK,GAAG,IAAI,CAEnC;IAED;;OAEG;IACI,KAAK,IAAI,IAAI;IAMpB;;OAEG;IACI,IAAI,IAAI,IAAI;IAQnB,OAAO,CAAC,YAAY;IAYpB;;;;;OAKG;IACU,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAsC9D,cAAc;IAKd,YAAY;CAIf"}

package/dist/poller.js

@@ -0,0 +1,98 @@
+/**
+ * Conditional polling loop for fetching rulesets using ETag / 304 Not Modified.
+ * Uses the native `fetch` API.
+ */
+export class Poller {
+    config;
+    timer = null;
+    currentEtag = null;
+    isPolling = false;
+    failureCount = 0;
+    _lastError = null;
+    constructor(config) {
+        this.config = config;
+    }
+    get lastError() {
+        return this._lastError;
+    }
+    /**
+     * Begins the periodic polling loop.
+     */
+    start() {
+        if (this.isPolling)
+            return;
+        this.isPolling = true;
+        this.scheduleNext(this.config.interval);
+    }
+    /**
+     * Stops the polling loop.
+     */
+    stop() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.isPolling = false;
+    }
+    scheduleNext(delay) {
+        if (!this.isPolling)
+            return;
+        this.timer = setTimeout(async () => {
+            await this.fetchRuleset(this.currentEtag);
+            if (this.isPolling) {
+                const nextDelay = this.failureCount === 0 ? this.config.interval : (Math.min(this.config.interval * Math.pow(2, this.failureCount), 300000));
+                this.scheduleNext(nextDelay);
+            }
+        }, delay);
+    }
+    /**
+     * Fetches the latest ruleset from the API server using conditional polling (`If-None-Match`).
+     * - 200: Parses ruleset, updates current ETag, and calls `onUpdate`.
+     * - 304: No-op.
+     * - Error: Catches error, calls `onError`, and never throws to ensure fail-open resilience.
+     */
+    async fetchRuleset(etag) {
+        try {
+            const headers = {
+                'X-API-Key': this.config.apiKey,
+                'Accept': 'application/json'
+            };
+            const targetEtag = etag !== undefined ? etag : this.currentEtag;
+            if (targetEtag) {
+                headers['If-None-Match'] = targetEtag;
+            }
+            const url = `${this.config.baseUrl.replace(/\/$/, '')}/sdk/flags`;
+            const response = await fetch(url, {
+                method: 'GET',
+                headers
+            });
+            if (response.status === 304) {
+                this.onFetchSuccess();
+                return;
+            }
+            if (!response.ok) {
+                throw new Error(`Failed to fetch flags: HTTP ${response.status} ${response.statusText}`);
+            }
+            const data = (await response.json());
+            this.onFetchSuccess();
+            this.currentEtag = data.etag;
+            this.config.onUpdate(data);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this._lastError = err;
+            this.onFetchError();
+            this.config.onError(err);
+        }
+    }
+    onFetchSuccess() {
+        this.failureCount = 0;
+        this._lastError = null;
+        this.config.onFetchSuccess?.();
+    }
+    onFetchError() {
+        this.failureCount++;
+        this.config.onFetchError?.();
+    }
+}
+//# sourceMappingURL=poller.js.map

package/dist/poller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"poller.js","sourceRoot":"","sources":["../src/poller.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+export interface FeatureFlagConfig {
+    apiKey: string;
+    baseUrl?: string;
+    pollingInterval?: number;
+    defaultValues?: Record<string, unknown>;
+    onError?: (error: Error) => void;
+    onConnectionStatusChange?: (status: 'connected' | 'degraded' | 'disconnected') => void;
+}
+export interface FlagRule {
+    priority: number;
+    conditions: Record<string, unknown>;
+    value: unknown;
+}
+export interface FlagDefinition {
+    key: string;
+    enabled: boolean;
+    rolloutPct: number;
+    defaultValue: unknown;
+    rules: FlagRule[];
+}
+export interface EvaluationContext {
+    userId: string;
+    attributes?: Record<string, unknown>;
+}
+export interface Ruleset {
+    flags: FlagDefinition[];
+    etag: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,wBAAwB,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,cAAc,KAAK,IAAI,CAAC;CAC1F;AAED,MAAM,WAAW,QAAQ;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,KAAK,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,OAAO;IACpB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;CAChB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,39 @@
+{
+    "name": "flagcraft",
+    "version": "0.1.0",
+    "description": "Universal, fail-open feature flag evaluation SDK with ETag conditional caching and auto-rollback support.",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./*": {
+            "types": "./dist/*.d.ts",
+            "import": "./dist/*.js"
+        }
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Akash-1808/feature-flag.git"
+    },
+    "keywords": [
+        "feature-flags",
+        "sdk",
+        "vanguard",
+        "ab-testing",
+        "rollout",
+        "etag-caching"
+    ],
+    "author": "Vanguard Team",
+    "license": "MIT",
+    "scripts": {
+        "build": "tsc",
+        "test": "vitest run"
+    }
+}