@jewel998/config 0.1.6 → 0.1.7

package/dist/cache/browserStorage.d.ts

@@ -1,3 +1,2 @@
 import type { BrowserStorageOptions, CacheStorage } from "../types.js";
 export declare const browserStorage: (options?: BrowserStorageOptions) => CacheStorage;
-//# sourceMappingURL=browserStorage.d.ts.map

package/dist/cache/memoryStorage.d.ts

@@ -1,3 +1,2 @@
 import type { CacheStorage } from "../types.js";
 export declare const memoryStorage: () => CacheStorage;
-//# sourceMappingURL=memoryStorage.d.ts.map

package/dist/cache/storage.d.ts

@@ -0,0 +1,14 @@
+export interface CacheStorage {
+    get<T>(key: string): Promise<T | undefined> | T | undefined;
+    set<T>(key: string, value: T): Promise<void> | void;
+    delete(key: string): Promise<void> | void;
+}
+export interface CacheDriver {
+    name: string;
+    getItem<T>(key: string): Promise<T | undefined>;
+    setItem<T>(key: string, value: T): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+export declare const memoryStorage: () => CacheStorage;
+export declare const createDriverStorage: (driver: CacheDriver, storageKey?: string) => CacheStorage;
+export declare const browserStorage: (storageKey?: string) => CacheStorage;

package/dist/cache/storage.js

@@ -0,0 +1,43 @@
+/// <reference lib="dom" />
+export const memoryStorage = () => {
+    const store = new Map();
+    return {
+        get: (key) => store.get(key),
+        set: (key, value) => {
+            store.set(key, value);
+        },
+        delete: (key) => {
+            store.delete(key);
+        },
+    };
+};
+export const createDriverStorage = (driver, storageKey = "@jewel998/config") => ({
+    get: async (key) => driver.getItem(`${storageKey}:${key}`),
+    set: async (key, value) => {
+        await driver.setItem(`${storageKey}:${key}`, value);
+    },
+    delete: async (key) => {
+        await driver.removeItem(`${storageKey}:${key}`);
+    },
+});
+export const browserStorage = (storageKey = "@jewel998/config") => {
+    const isBrowser = typeof window !== "undefined" && typeof window.localStorage !== "undefined";
+    if (!isBrowser) {
+        return memoryStorage();
+    }
+    const driver = {
+        name: "localStorage",
+        getItem: async (key) => {
+            const serialized = window.localStorage.getItem(key);
+            return serialized ? JSON.parse(serialized) : undefined;
+        },
+        setItem: async (key, value) => {
+            window.localStorage.setItem(key, JSON.stringify(value));
+        },
+        removeItem: async (key) => {
+            window.localStorage.removeItem(key);
+        },
+    };
+    return createDriverStorage(driver, storageKey);
+};
+//# sourceMappingURL=storage.js.map

package/dist/cache/types.d.ts

@@ -0,0 +1,2 @@
+export type { CacheEntry, CacheStorage, BrowserStorageOptions, } from "../types.js";
+export { DEFAULT_CACHE_TTL } from "../types.js";

package/dist/cache/types.js

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

package/dist/client/ConfigClient.d.ts

@@ -15,4 +15,3 @@ export interface ConfigClientInternals {
     onContextChange?: (ctx: EvaluationContext) => void;
 }
 export declare const buildConfigClient: (internals: ConfigClientInternals) => ConfigClient;
-//# sourceMappingURL=ConfigClient.d.ts.map

package/dist/context/autoContext.d.ts

@@ -25,4 +25,3 @@ export declare function autoContext(user?: {
  * Deep-merge two evaluation contexts. User-provided values take precedence.
  */
 export declare function mergeContext(auto: EvaluationContext, user: EvaluationContext): EvaluationContext;
-//# sourceMappingURL=autoContext.d.ts.map

package/dist/createConfig.d.ts

@@ -3,4 +3,3 @@ export declare function createConfig(options: CreateConfigOptions & {
     loadingStrategy: "pessimistic";
 }): Promise<ConfigClient>;
 export declare function createConfig(options: CreateConfigOptions): ConfigClient;
-//# sourceMappingURL=createConfig.d.ts.map

package/dist/errors/index.d.ts

@@ -0,0 +1,16 @@
+export type ConfigErrorCode = "MISSING_CLIENT_ID" | "AUTHENTICATION_FAILED" | "INITIALIZATION_FAILED" | "TIMEOUT" | "RATE_LIMITED" | "REVOKED" | "NETWORK_ERROR";
+export declare class ConfigError extends Error {
+    readonly code: ConfigErrorCode;
+    name: string;
+    constructor(message: string, code: ConfigErrorCode);
+}
+export declare class InitializationError extends ConfigError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+export declare class TimeoutError extends ConfigError {
+    constructor(timeoutMs: number);
+}
+export declare class AuthenticationError extends ConfigError {
+    constructor(message: string);
+}

package/dist/errors/index.js

@@ -0,0 +1,29 @@
+export class ConfigError extends Error {
+    code;
+    name = "ConfigError";
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+export class InitializationError extends ConfigError {
+    cause;
+    constructor(message, cause) {
+        super(message, "INITIALIZATION_FAILED");
+        this.cause = cause;
+        this.name = "InitializationError";
+    }
+}
+export class TimeoutError extends ConfigError {
+    constructor(timeoutMs) {
+        super(`Config initialization timed out after ${timeoutMs}ms`, "TIMEOUT");
+        this.name = "TimeoutError";
+    }
+}
+export class AuthenticationError extends ConfigError {
+    constructor(message) {
+        super(message, "AUTHENTICATION_FAILED");
+        this.name = "AuthenticationError";
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/events/EventEmitter.d.ts

@@ -6,4 +6,3 @@ export declare class TypedEventEmitter implements EventEmitterInterface {
     emit<E extends ConfigEventType>(event: E, payload: ConfigEventPayloads[E]): void;
     removeAllListeners(): void;
 }
-//# sourceMappingURL=EventEmitter.d.ts.map

package/dist/fetch/batchFetcher.d.ts

@@ -1,3 +1,2 @@
 import type { ConfigFetcher, HttpTransport } from "../types.js";
 export declare const createBatchFetcher: (transport: HttpTransport) => ConfigFetcher;
-//# sourceMappingURL=batchFetcher.d.ts.map

package/dist/fetch/projectedFetcher.d.ts

@@ -1,3 +1,2 @@
 import type { ConfigFetcher, HttpTransport } from "../types.js";
 export declare const createProjectedFetcher: (transport: HttpTransport) => ConfigFetcher;
-//# sourceMappingURL=projectedFetcher.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { initConfig } from "./initConfig.js";
+export type { InitConfigOptions, Flags } from "./initConfig.js";
+export { createConfig } from "./createConfig.js";
+export type { CacheStorage, ClientIdRecord, ConfigClient, ConfigEventCallback, ConfigEventPayloads, ConfigEventType, ConfigRecord, CreateConfigOptions, EnvironmentRecord, EvaluationWarning, FetchGranularity, LoadingStrategy, ProjectRecord, RetryConfig, } from "./types.js";
+export type { EvaluationContext, EvaluationPlugin, PipelineStepId, PipelineStepResult, PipelineHelpers, } from "./plugins/types.js";
+export { PIPELINE_ORDER } from "./plugins/types.js";
+export { autoContext, mergeContext } from "./context/autoContext.js";
+export { WEBHOOK_FORMATS, WEBHOOK_FORMAT_INFO, TEMPLATE_VARIABLES, WEBHOOK_EVENT_TYPES, WEBHOOK_RESOURCE_CATEGORIES, SAMPLE_WEBHOOK_EVENT, } from "./webhook-formats.js";
+export type { WebhookFormat, WebhookEventType, WebhookResourceCategory, } from "./webhook-formats.js";
+export { memoryStorage } from "./cache/memoryStorage.js";
+export { browserStorage } from "./cache/browserStorage.js";
+export { AuthenticationError, ConfigError, InitializationError, TimeoutError, } from "./errors/index.js";
+export type { ConfigErrorCode } from "./errors/index.js";

package/dist/initConfig.d.ts

@@ -63,4 +63,3 @@ export interface Flags {
  * ```
  */
 export declare function initConfig(options: InitConfigOptions): Flags;
-//# sourceMappingURL=initConfig.d.ts.map

package/dist/loading/deferred.d.ts

@@ -0,0 +1,2 @@
+import type { LoadingResult } from "../types.js";
+export declare const executeDeferred: () => LoadingResult;

package/dist/loading/deferred.js

@@ -0,0 +1,5 @@
+export const executeDeferred = () => {
+    // No network activity at init time
+    return { initialData: {}, status: "ready" };
+};
+//# sourceMappingURL=deferred.js.map

package/dist/loading/optimistic.d.ts

@@ -0,0 +1,2 @@
+import type { LoadingContext, LoadingResult } from "../types.js";
+export declare const executeOptimistic: (ctx: LoadingContext) => LoadingResult;

package/dist/loading/pessimistic.d.ts

@@ -0,0 +1,2 @@
+import type { LoadingContext, LoadingResult } from "../types.js";
+export declare const executePessimistic: (ctx: LoadingContext) => Promise<LoadingResult>;

package/dist/plugins/evaluatePipeline.d.ts

@@ -12,4 +12,3 @@ import type { EvaluationContext, EvaluationPlugin, PipelineHelpers } from "./typ
  * Steps with no registered plugin are transparently skipped.
  */
 export declare function evaluatePipeline(plugins: EvaluationPlugin[], flag: ConfigFlagData, context: EvaluationContext, helpers: PipelineHelpers): unknown;
-//# sourceMappingURL=evaluatePipeline.d.ts.map

package/dist/plugins/index.d.ts

@@ -0,0 +1,4 @@
+export type { PipelineStepId, EvaluationContext, PipelineStepResult, EvaluationPlugin, PipelineHelpers, } from "./types.js";
+export { PIPELINE_ORDER } from "./types.js";
+export type { ConfigFlagData, TargetingRule, PredicateGroup, Predicate, PredicateOperator, Segment, } from "./models.js";
+export { evaluatePipeline } from "./evaluatePipeline.js";

package/dist/plugins/lifecycle/archivedPlugin.d.ts

@@ -11,4 +11,3 @@ import type { EvaluationPlugin } from "../types.js";
  * short-circuit before any other evaluation logic runs.
  */
 export declare function archivedPlugin(): EvaluationPlugin;
-//# sourceMappingURL=archivedPlugin.d.ts.map

package/dist/plugins/lifecycle/index.d.ts

@@ -0,0 +1,3 @@
+export { archivedPlugin } from "./archivedPlugin.js";
+export { validateStateTransition, VALID_TRANSITIONS, } from "./stateTransitions.js";
+export type { LifecycleState } from "./stateTransitions.js";

package/dist/plugins/lifecycle/stateTransitions.d.ts

@@ -24,4 +24,3 @@ export declare const VALID_TRANSITIONS: Record<LifecycleState, LifecycleState[]>
  * @returns `true` if the transition is valid, `false` otherwise
  */
 export declare function validateStateTransition(current: LifecycleState, target: LifecycleState): boolean;
-//# sourceMappingURL=stateTransitions.d.ts.map

package/dist/plugins/models.d.ts

@@ -0,0 +1,50 @@
+/** The full config flag document as fetched from Firestore */
+export interface ConfigFlagData {
+    key: string;
+    value: unknown;
+    valueType: "string" | "number" | "boolean" | "json";
+    version: string;
+    lifecycleState: "draft" | "active" | "stale" | "archived";
+    targetingRules?: TargetingRule[];
+    rolloutPercentage?: number;
+    rolloutValue?: unknown;
+    overrides?: Record<string, unknown>;
+    schedule?: {
+        targetValue: unknown;
+        activateAt: string;
+    };
+    prerequisites?: Array<{
+        flagKey: string;
+        operator?: "equals" | "not_equals" | "greater_than" | "less_than" | "contains";
+        requiredValue: unknown;
+    }>;
+}
+/** A single targeting rule */
+export interface TargetingRule {
+    id: string;
+    priority: number;
+    value: unknown;
+    conditions: PredicateGroup[];
+}
+/** A group of predicates combined with AND logic */
+export interface PredicateGroup {
+    predicates: Predicate[];
+}
+/** A single predicate */
+export interface Predicate {
+    attribute: string;
+    operator: PredicateOperator;
+    value: string | number | boolean | string[];
+}
+/** Supported predicate operators */
+export type PredicateOperator = "equals" | "not_equals" | "contains" | "starts_with" | "ends_with" | "in_list" | "not_in_list" | "greater_than" | "less_than" | "regex_match" | "in_segment" | "not_in_segment";
+/** A reusable audience segment */
+export interface Segment {
+    id: string;
+    name: string;
+    description: string;
+    conditions: PredicateGroup[];
+    createdAt: string;
+    updatedAt: string;
+    createdBy: string;
+}

package/dist/plugins/models.js

@@ -0,0 +1,5 @@
+// ═══════════════════════════════════════════════════════════════
+// Config Flag Data Models (SDK-side)
+// ═══════════════════════════════════════════════════════════════
+export {};
+//# sourceMappingURL=models.js.map

package/dist/plugins/overrides/index.d.ts

@@ -0,0 +1 @@
+export { overridesPlugin } from "./overridesPlugin.js";

package/dist/plugins/overrides/overridesPlugin.d.ts

@@ -9,4 +9,3 @@ import type { EvaluationPlugin } from "../types.js";
  * - If userId not in overrides or value is null/undefined → skip (Req 4.4, 4.7)
  */
 export declare function overridesPlugin(): EvaluationPlugin;
-//# sourceMappingURL=overridesPlugin.d.ts.map

package/dist/plugins/prerequisites/index.d.ts

@@ -0,0 +1,2 @@
+export { prerequisitePlugin } from "./prerequisitePlugin.js";
+export type { PrerequisitePluginOptions } from "./prerequisitePlugin.js";

package/dist/plugins/prerequisites/prerequisitePlugin.d.ts

@@ -21,4 +21,3 @@ export interface PrerequisitePluginOptions {
  * that tracks which flags are currently being evaluated for prerequisites.
  */
 export declare function prerequisitePlugin(options?: PrerequisitePluginOptions): EvaluationPlugin;
-//# sourceMappingURL=prerequisitePlugin.d.ts.map

package/dist/plugins/rollout/computeBucket.d.ts

@@ -9,4 +9,3 @@
  * Deterministic — same inputs always produce the same bucket.
  */
 export declare function computeBucket(configKey: string, userId: string): number;
-//# sourceMappingURL=computeBucket.d.ts.map

package/dist/plugins/rollout/index.d.ts

@@ -0,0 +1,2 @@
+export { computeBucket } from "./computeBucket.js";
+export { rolloutPlugin } from "./rolloutPlugin.js";

package/dist/plugins/rollout/murmurhash3.d.ts

@@ -0,0 +1,5 @@
+/**
+ * MurmurHash3_x86_32 — deterministic 32-bit hash.
+ * Used for percentage rollout bucketing (same algorithm as flagd/OpenFeature).
+ */
+export declare function murmurhash3_32(key: string, seed?: number): number;

package/dist/plugins/rollout/murmurhash3.js

@@ -0,0 +1,56 @@
+// ═══════════════════════════════════════════════════════════════
+// MurmurHash3_x86_32
+// Public domain — Austin Appleby
+// Adapted for TypeScript (operates on UTF-8 encoded string bytes)
+// ═══════════════════════════════════════════════════════════════
+/**
+ * MurmurHash3_x86_32 — deterministic 32-bit hash.
+ * Used for percentage rollout bucketing (same algorithm as flagd/OpenFeature).
+ */
+export function murmurhash3_32(key, seed = 0) {
+    const encoder = new TextEncoder();
+    const bytes = encoder.encode(key);
+    const len = bytes.length;
+    let h1 = seed >>> 0;
+    const c1 = 0xcc9e2d51;
+    const c2 = 0x1b873593;
+    let i = 0;
+    while (i + 4 <= len) {
+        let k1 = (bytes[i] |
+            (bytes[i + 1] << 8) |
+            (bytes[i + 2] << 16) |
+            (bytes[i + 3] << 24)) >>>
+            0;
+        k1 = Math.imul(k1, c1) >>> 0;
+        k1 = ((k1 << 15) | (k1 >>> 17)) >>> 0;
+        k1 = Math.imul(k1, c2) >>> 0;
+        h1 ^= k1;
+        h1 = ((h1 << 13) | (h1 >>> 19)) >>> 0;
+        h1 = (Math.imul(h1, 5) + 0xe6546b64) >>> 0;
+        i += 4;
+    }
+    let k1 = 0;
+    const remainder = len & 3;
+    if (remainder >= 3) {
+        k1 ^= bytes[i + 2] << 16;
+    }
+    if (remainder >= 2) {
+        k1 ^= bytes[i + 1] << 8;
+    }
+    if (remainder >= 1) {
+        k1 ^= bytes[i];
+        k1 = Math.imul(k1, c1) >>> 0;
+        k1 = ((k1 << 15) | (k1 >>> 17)) >>> 0;
+        k1 = Math.imul(k1, c2) >>> 0;
+        h1 ^= k1;
+    }
+    h1 ^= len;
+    // fmix32
+    h1 ^= h1 >>> 16;
+    h1 = Math.imul(h1, 0x85ebca6b) >>> 0;
+    h1 ^= h1 >>> 13;
+    h1 = Math.imul(h1, 0xc2b2ae35) >>> 0;
+    h1 ^= h1 >>> 16;
+    return h1 >>> 0;
+}
+//# sourceMappingURL=murmurhash3.js.map

package/dist/plugins/rollout/rolloutPlugin.d.ts

@@ -10,4 +10,3 @@ import type { EvaluationPlugin } from "../types.js";
  * - Otherwise: compute bucket, if bucket < rolloutPercentage → return rollout value, else skip
  */
 export declare function rolloutPlugin(): EvaluationPlugin;
-//# sourceMappingURL=rolloutPlugin.d.ts.map

package/dist/plugins/schedule/index.d.ts

@@ -0,0 +1 @@
+export { schedulePlugin } from "./schedulePlugin.js";

package/dist/plugins/schedule/schedulePlugin.d.ts

@@ -11,4 +11,3 @@ import type { EvaluationPlugin } from "../types.js";
  * - If activateAt is in the future → skip (Requirement 6.5)
  */
 export declare function schedulePlugin(): EvaluationPlugin;
-//# sourceMappingURL=schedulePlugin.d.ts.map

package/dist/plugins/targeting/index.d.ts

@@ -0,0 +1,3 @@
+export { targetingPlugin } from "./targetingPlugin.js";
+export { evaluatePredicate, evaluatePredicateGroups } from "./predicates.js";
+export { resolveSegment } from "./segmentResolver.js";

package/dist/plugins/targeting/predicates.d.ts

@@ -0,0 +1,22 @@
+import type { Predicate, PredicateGroup } from "../models.js";
+type AttributeValue = string | number | boolean | string[];
+/**
+ * Evaluate a single predicate against the provided attributes.
+ *
+ * Returns false for:
+ * - Missing attributes in context
+ * - Type mismatches (e.g., greater_than on a non-numeric value)
+ * - Invalid regex patterns (also calls emitError)
+ * - in_segment / not_in_segment (handled externally by segment resolver)
+ */
+export declare function evaluatePredicate(predicate: Predicate, attributes: Record<string, AttributeValue>, emitError?: (message: string) => void): boolean;
+/**
+ * Evaluate predicate groups in Disjunctive Normal Form (DNF).
+ *
+ * Groups are OR'd — any group matching means the whole expression matches.
+ * Within each group, predicates are AND'd — all must match.
+ *
+ * Returns false if groups array is empty.
+ */
+export declare function evaluatePredicateGroups(groups: PredicateGroup[], attributes: Record<string, AttributeValue>, emitError?: (message: string) => void): boolean;
+export {};

package/dist/plugins/targeting/predicates.js

@@ -0,0 +1,110 @@
+// ═══════════════════════════════════════════════════════════════
+// Predicate Evaluator — DNF logic for targeting rules
+// ═══════════════════════════════════════════════════════════════
+/**
+ * Evaluate a single predicate against the provided attributes.
+ *
+ * Returns false for:
+ * - Missing attributes in context
+ * - Type mismatches (e.g., greater_than on a non-numeric value)
+ * - Invalid regex patterns (also calls emitError)
+ * - in_segment / not_in_segment (handled externally by segment resolver)
+ */
+export function evaluatePredicate(predicate, attributes, emitError) {
+    const { attribute, operator, value } = predicate;
+    // in_segment / not_in_segment are resolved externally by the segment resolver
+    if (operator === "in_segment" || operator === "not_in_segment") {
+        return false;
+    }
+    // Missing attribute → predicate is non-matching (Property 4)
+    if (!(attribute in attributes)) {
+        return false;
+    }
+    const attrValue = attributes[attribute];
+    // Attribute value is undefined/null → non-matching
+    if (attrValue === undefined || attrValue === null) {
+        return false;
+    }
+    switch (operator) {
+        case "equals":
+            return attrValue === value;
+        case "not_equals":
+            return attrValue !== value;
+        case "contains": {
+            if (typeof attrValue !== "string" || typeof value !== "string") {
+                return false;
+            }
+            return attrValue.includes(value);
+        }
+        case "starts_with": {
+            if (typeof attrValue !== "string" || typeof value !== "string") {
+                return false;
+            }
+            return attrValue.startsWith(value);
+        }
+        case "ends_with": {
+            if (typeof attrValue !== "string" || typeof value !== "string") {
+                return false;
+            }
+            return attrValue.endsWith(value);
+        }
+        case "in_list": {
+            if (!Array.isArray(value)) {
+                return false;
+            }
+            return value.includes(attrValue);
+        }
+        case "not_in_list": {
+            if (!Array.isArray(value)) {
+                return false;
+            }
+            return !value.includes(attrValue);
+        }
+        case "greater_than": {
+            if (typeof attrValue !== "number" || typeof value !== "number") {
+                return false;
+            }
+            return attrValue > value;
+        }
+        case "less_than": {
+            if (typeof attrValue !== "number" || typeof value !== "number") {
+                return false;
+            }
+            return attrValue < value;
+        }
+        case "regex_match": {
+            if (typeof attrValue !== "string" || typeof value !== "string") {
+                return false;
+            }
+            try {
+                const regex = new RegExp(value);
+                return regex.test(attrValue);
+            }
+            catch {
+                emitError?.(`Invalid regex pattern: ${value}`);
+                return false;
+            }
+        }
+        default:
+            return false;
+    }
+}
+/**
+ * Evaluate predicate groups in Disjunctive Normal Form (DNF).
+ *
+ * Groups are OR'd — any group matching means the whole expression matches.
+ * Within each group, predicates are AND'd — all must match.
+ *
+ * Returns false if groups array is empty.
+ */
+export function evaluatePredicateGroups(groups, attributes, emitError) {
+    if (groups.length === 0) {
+        return false;
+    }
+    // OR across groups: at least one group must fully match
+    return groups.some((group) => {
+        // AND within each group: all predicates must match
+        return group.predicates.every((predicate) => evaluatePredicate(predicate, attributes, emitError));
+    });
+}
+//# sourceMappingURL=predicates.js.map

package/dist/plugins/targeting/segmentResolver.d.ts

@@ -13,4 +13,3 @@ type AttributeValue = string | number | boolean | string[];
  */
 export declare function resolveSegment(segmentId: string, segments: Record<string, Segment>, attributes: Record<string, AttributeValue>, emitError?: (message: string) => void): boolean;
 export {};
-//# sourceMappingURL=segmentResolver.d.ts.map

package/dist/plugins/targeting/targetingPlugin.d.ts

@@ -16,4 +16,3 @@ import type { EvaluationPlugin } from "../types.js";
  * 7. No rule matches → return { resolved: false }
  */
 export declare function targetingPlugin(segments?: Record<string, Segment>): EvaluationPlugin;
-//# sourceMappingURL=targetingPlugin.d.ts.map

package/dist/plugins/types.d.ts

@@ -0,0 +1,34 @@
+import type { ConfigFlagData } from "./models.js";
+/** Pipeline step identifier — determines execution order */
+export type PipelineStepId = "archived" | "prerequisites" | "overrides" | "schedule" | "targeting" | "rollout";
+/** The fixed execution order (per Requirement 11) */
+export declare const PIPELINE_ORDER: PipelineStepId[];
+/** Evaluation context provided by the consumer */
+export interface EvaluationContext {
+    userId?: string;
+    attributes?: Record<string, string | number | boolean | string[]>;
+    consentGranted?: boolean;
+}
+/** Result from a pipeline step */
+export type PipelineStepResult = {
+    resolved: true;
+    value: unknown;
+} | {
+    resolved: false;
+};
+/** A registered evaluation plugin */
+export interface EvaluationPlugin {
+    /** Which pipeline step this plugin handles */
+    stepId: PipelineStepId;
+    /** Evaluate a config flag at this pipeline step */
+    evaluate(flag: ConfigFlagData, context: EvaluationContext, helpers: PipelineHelpers): PipelineStepResult;
+}
+/** Helpers provided to plugins for cross-cutting concerns */
+export interface PipelineHelpers {
+    /** Evaluate another flag (for prerequisites) */
+    evaluateFlag(key: string, context: EvaluationContext): unknown;
+    /** Emit an error */
+    emitError(message: string): void;
+    /** Current timestamp (injectable for testing) */
+    now(): number;
+}

package/dist/plugins/types.js

@@ -0,0 +1,13 @@
+// ═══════════════════════════════════════════════════════════════
+// Plugin System Types and Pipeline Interfaces
+// ═══════════════════════════════════════════════════════════════
+/** The fixed execution order (per Requirement 11) */
+export const PIPELINE_ORDER = [
+    "archived",
+    "prerequisites",
+    "overrides",
+    "schedule",
+    "targeting",
+    "rollout",
+];
+//# sourceMappingURL=types.js.map

package/dist/retry/RetryEngine.d.ts

@@ -2,4 +2,3 @@ import type { RetryConfig } from "../types.js";
 export declare const sleep: (ms: number) => Promise<void>;
 export declare const isNonRetryableError: (error: unknown) => boolean;
 export declare const withRetry: <T>(fn: () => Promise<T>, options?: RetryConfig, onRetry?: (attempt: number, error: Error, nextDelay: number) => void) => Promise<T>;
-//# sourceMappingURL=RetryEngine.d.ts.map

package/dist/transport/HttpTransport.d.ts

@@ -8,4 +8,3 @@ export interface TransportConfig {
     getContext?: () => EvaluationContext;
 }
 export declare const createHttpTransport: (config: TransportConfig) => HttpTransport;
-//# sourceMappingURL=HttpTransport.d.ts.map

package/dist/types.d.ts

@@ -0,0 +1,203 @@
+import type { EvaluationContext, EvaluationPlugin } from "./plugins/types.js";
+/** Loading strategy for SDK initialization */
+export type LoadingStrategy = "optimistic" | "pessimistic" | "deferred";
+/** Evaluation mode for the SDK */
+export type EvaluationMode = "server" | "client";
+/** Fetch granularity for remote config retrieval */
+export type FetchGranularity = "batch" | "projected";
+/** Default cache TTL: 7 days in milliseconds */
+export declare const DEFAULT_CACHE_TTL: number;
+/** Default pessimistic timeout in milliseconds */
+export declare const DEFAULT_TIMEOUT = 10000;
+export interface CreateConfigOptions {
+    /** Required. The clientId token generated in the Portal. */
+    clientId: string;
+    /**
+     * Loading strategy for initialization.
+     * - "optimistic" (default): Sync return, background fetch
+     * - "pessimistic": Async, blocks until fetch completes
+     * - "deferred": Sync return, lazy fetch on first access
+     */
+    loadingStrategy?: LoadingStrategy;
+    /**
+     * Fetch granularity for remote config retrieval.
+     * - "batch" (default): Fetch all keys in one request
+     * - "projected": Fetch only requested keys on demand
+     */
+    fetchGranularity?: FetchGranularity;
+    /** Cache storage adapter. Default: memoryStorage() */
+    storage?: CacheStorage;
+    /** Retry configuration for failed fetches */
+    retry?: RetryConfig;
+    /** Timeout for pessimistic loading (ms). Default: 10000 */
+    timeout?: number;
+    /**
+     * Your self-hosted API URL. Points to your Firebase deployment.
+     * Default: https://jewel998-config.web.app/api (demo instance)
+     *
+     * @example "https://your-project.web.app/api"
+     */
+    baseUrl?: string;
+    /**
+     * Evaluation plugins to register (tree-shakeable pipeline steps).
+     * Only used with server keys (svr_). Client keys (cid_) receive pre-resolved values.
+     */
+    plugins?: EvaluationPlugin[];
+    /** Evaluation context for targeting (can be updated post-init via setContext) */
+    context?: EvaluationContext;
+    /** Enable consent-aware mode (GDPR): if true and context.consentGranted !== true, returns defaults */
+    consentAware?: boolean;
+}
+export interface ConfigClient {
+    /** Get a typed config value by key. */
+    getValue<T = unknown>(key: string): T | undefined;
+    getValue<T = unknown>(key: string, defaultValue: T): T;
+    /** Get a boolean flag by key. Returns false if missing. */
+    getFlag(key: string): boolean;
+    /** Get all config key-value pairs. */
+    getAll(): Record<string, unknown>;
+    /** Force refresh from remote. Updates cache and emits 'updated'. */
+    refresh(): Promise<void>;
+    /** Update the evaluation context (used by plugins for targeting, rollout, etc.) */
+    setContext(newContext: EvaluationContext): void;
+    /** Subscribe to a lifecycle event. */
+    on<E extends ConfigEventType>(event: E, callback: ConfigEventCallback<E>): void;
+    /** Unsubscribe from a lifecycle event. */
+    off<E extends ConfigEventType>(event: E, callback: ConfigEventCallback<E>): void;
+}
+export interface RetryConfig {
+    /** Maximum number of retry attempts. Default: 3 */
+    maxRetries?: number;
+    /** Base delay in milliseconds. Default: 1000 */
+    baseDelay?: number;
+    /** Backoff multiplier. Default: 2 (exponential) */
+    multiplier?: number;
+    /** Maximum delay cap in milliseconds. Default: 30000 */
+    maxDelay?: number;
+}
+export declare const DEFAULT_RETRY: Required<RetryConfig>;
+export interface CacheStorage {
+    /** Get a value by key. Returns undefined if missing or TTL expired. */
+    get<T>(key: string): T | undefined;
+    /** Set a value with optional TTL override (ms). Default TTL: 7 days. */
+    set<T>(key: string, value: T, ttl?: number): void;
+    /** Delete a specific key from cache. */
+    delete(key: string): void;
+    /** Clear all cached values. */
+    clear(): void;
+}
+export interface CacheEntry<T = unknown> {
+    value: T;
+    expiresAt: number;
+}
+export interface BrowserStorageOptions {
+    /** localStorage key prefix. Default: "@jewel998/config" */
+    prefix?: string;
+    /** Default TTL in milliseconds. Default: 604800000 (7 days) */
+    defaultTtl?: number;
+}
+export type ConfigEventType = "ready" | "updated" | "fetchError" | "revoked";
+export interface ConfigEventPayloads {
+    ready: {
+        loadingStrategy: LoadingStrategy;
+        cachedKeys: number;
+    };
+    updated: {
+        keys: string[];
+        source: "background" | "refresh";
+    };
+    fetchError: {
+        error: Error;
+        retryCount: number;
+        willRetry: boolean;
+    };
+    revoked: {
+        clientId: string;
+        message: string;
+    };
+}
+export type ConfigEventCallback<E extends ConfigEventType> = (payload: ConfigEventPayloads[E]) => void;
+export interface LoadingContext {
+    clientId: string;
+    fetcher: ConfigFetcher;
+    cache: CacheStorage;
+    events: EventEmitterInterface;
+    retry: Required<RetryConfig>;
+    timeout: number;
+    granularity: FetchGranularity;
+}
+export interface LoadingResult {
+    initialData: Record<string, unknown>;
+    status: "ready" | "pending";
+}
+export interface LoadingStrategyHandler {
+    execute(context: LoadingContext): LoadingResult | Promise<LoadingResult>;
+}
+export interface ConfigFetcher {
+    /** Fetch all configs for the bound project+environment */
+    fetchAll(): Promise<Record<string, unknown>>;
+    /** Fetch specific keys only */
+    fetchKeys(keys: string[]): Promise<Record<string, unknown>>;
+}
+export interface HttpTransport {
+    request<T>(endpoint: string, body?: Record<string, unknown>): Promise<T>;
+}
+export interface GetConfigRequest {
+    clientId: string;
+    keys?: string[];
+    context?: {
+        userId?: string;
+        attributes?: Record<string, string | number | boolean | string[]>;
+    };
+}
+export interface EvaluationWarning {
+    key: string;
+    reason: "evaluation_error" | "segment_not_found" | "prerequisite_failed";
+    message: string;
+}
+export interface GetConfigResponse {
+    data: Record<string, unknown>;
+    segments?: Record<string, unknown>;
+    version: string;
+    timestamp: string;
+    warnings?: EvaluationWarning[];
+}
+export interface EventEmitterInterface {
+    on<E extends ConfigEventType>(event: E, callback: ConfigEventCallback<E>): void;
+    off<E extends ConfigEventType>(event: E, callback: ConfigEventCallback<E>): void;
+    emit<E extends ConfigEventType>(event: E, payload: ConfigEventPayloads[E]): void;
+    removeAllListeners(): void;
+}
+export interface ProjectRecord {
+    id: string;
+    name: string;
+    ownerId: string;
+    authorizedUsers: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface EnvironmentRecord {
+    id: string;
+    projectId: string;
+    name: string;
+    allowedDomains: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ClientIdRecord {
+    token: string;
+    status: "active" | "revoked";
+    createdAt: string;
+    revokedAt: string | null;
+    createdBy: string;
+    label?: string;
+}
+export interface ConfigRecord {
+    key: string;
+    value: unknown;
+    valueType: "string" | "number" | "boolean" | "json";
+    version: string;
+    publishedAt: string;
+    updatedAt: string;
+    updatedBy: string;
+}

package/dist/types.js

@@ -0,0 +1,14 @@
+// ═══════════════════════════════════════════════════════════════
+// Core SDK Types
+// ═══════════════════════════════════════════════════════════════
+/** Default cache TTL: 7 days in milliseconds */
+export const DEFAULT_CACHE_TTL = 7 * 24 * 60 * 60 * 1000; // 604_800_000 ms
+/** Default pessimistic timeout in milliseconds */
+export const DEFAULT_TIMEOUT = 10_000;
+export const DEFAULT_RETRY = {
+    maxRetries: 3,
+    baseDelay: 1000,
+    multiplier: 2,
+    maxDelay: 30_000,
+};
+//# sourceMappingURL=types.js.map

package/dist/webhook-formats.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Supported webhook format identifiers.
+ */
+export declare const WEBHOOK_FORMATS: readonly ["standard", "slack", "discord", "google-chat", "ms-teams", "custom"];
+export type WebhookFormat = (typeof WEBHOOK_FORMATS)[number];
+/**
+ * Human-readable descriptions for each webhook format.
+ */
+export declare const WEBHOOK_FORMAT_INFO: Record<WebhookFormat, {
+    label: string;
+    description: string;
+}>;
+/**
+ * Available template variables for the custom format.
+ * Used by: portal UI (variable reference), docs page, and the function's template engine.
+ */
+export declare const TEMPLATE_VARIABLES: readonly [{
+    readonly variable: "{{action}}";
+    readonly description: "The action that occurred";
+    readonly example: "create, update, delete, state_change";
+}, {
+    readonly variable: "{{resource.category}}";
+    readonly description: "Resource category";
+    readonly example: "config, segment, api_key, team";
+}, {
+    readonly variable: "{{resource.path}}";
+    readonly description: "Full resource path";
+    readonly example: "environments/prod/configs/feature.dark_mode";
+}, {
+    readonly variable: "{{resource.name}}";
+    readonly description: "Human-readable resource name";
+    readonly example: "feature.dark_mode";
+}, {
+    readonly variable: "{{environment}}";
+    readonly description: "Environment name (empty if none)";
+    readonly example: "production";
+}, {
+    readonly variable: "{{actor.id}}";
+    readonly description: "User ID of the person who made the change";
+    readonly example: "user_abc123";
+}, {
+    readonly variable: "{{timestamp}}";
+    readonly description: "ISO 8601 timestamp of the event";
+    readonly example: "2025-01-15T09:30:00.000Z";
+}, {
+    readonly variable: "{{project.id}}";
+    readonly description: "Project identifier";
+    readonly example: "proj_xyz";
+}, {
+    readonly variable: "{{webhook.id}}";
+    readonly description: "Webhook identifier";
+    readonly example: "whk_123";
+}, {
+    readonly variable: "{{changes.old}}";
+    readonly description: "Previous value as JSON string (empty if create)";
+    readonly example: "{\"enabled\": true}";
+}, {
+    readonly variable: "{{changes.new}}";
+    readonly description: "New value as JSON string (empty if delete)";
+    readonly example: "{\"enabled\": false}";
+}];
+/**
+ * Event types that can trigger webhooks.
+ */
+export declare const WEBHOOK_EVENT_TYPES: readonly ["create", "update", "delete", "state_change"];
+export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
+/**
+ * Resource categories for webhook filtering.
+ */
+export declare const WEBHOOK_RESOURCE_CATEGORIES: readonly ["config", "segment", "api_key", "project", "team", "environment"];
+export type WebhookResourceCategory = (typeof WEBHOOK_RESOURCE_CATEGORIES)[number];
+/**
+ * Sample payload used for preview/testing (shared between portal and docs).
+ */
+export declare const SAMPLE_WEBHOOK_EVENT: {
+    readonly action: "update";
+    readonly resourceCategory: "config";
+    readonly resourcePath: "environments/production/configs/feature.dark_mode";
+    readonly resourceName: "feature.dark_mode";
+    readonly environment: "production";
+    readonly actorId: "user_abc123";
+    readonly timestamp: "2025-01-15T09:30:00.000Z";
+    readonly oldValue: {
+        readonly value: false;
+    };
+    readonly newValue: {
+        readonly value: true;
+    };
+    readonly projectId: "proj_xyz";
+    readonly webhookId: "whk_sample";
+};

package/dist/webhook-formats.js

@@ -0,0 +1,141 @@
+// ═══════════════════════════════════════════════════════════════
+// Webhook Format Constants — shared between portal, docs, and functions
+// ═══════════════════════════════════════════════════════════════
+/**
+ * Supported webhook format identifiers.
+ */
+export const WEBHOOK_FORMATS = [
+    "standard",
+    "slack",
+    "discord",
+    "google-chat",
+    "ms-teams",
+    "custom",
+];
+/**
+ * Human-readable descriptions for each webhook format.
+ */
+export const WEBHOOK_FORMAT_INFO = {
+    standard: {
+        label: "Standard JSON",
+        description: "Plain JSON payload with all event details",
+    },
+    slack: {
+        label: "Slack",
+        description: "Block Kit formatted message for Slack channels",
+    },
+    discord: {
+        label: "Discord",
+        description: "Rich embed message for Discord channels",
+    },
+    "google-chat": {
+        label: "Google Chat",
+        description: "Cards v2 formatted message for Google Chat",
+    },
+    "ms-teams": {
+        label: "Microsoft Teams",
+        description: "Adaptive Card for Microsoft Teams channels",
+    },
+    custom: {
+        label: "Custom Template",
+        description: "User-defined template with {{variable}} interpolation",
+    },
+};
+/**
+ * Available template variables for the custom format.
+ * Used by: portal UI (variable reference), docs page, and the function's template engine.
+ */
+export const TEMPLATE_VARIABLES = [
+    {
+        variable: "{{action}}",
+        description: "The action that occurred",
+        example: "create, update, delete, state_change",
+    },
+    {
+        variable: "{{resource.category}}",
+        description: "Resource category",
+        example: "config, segment, api_key, team",
+    },
+    {
+        variable: "{{resource.path}}",
+        description: "Full resource path",
+        example: "environments/prod/configs/feature.dark_mode",
+    },
+    {
+        variable: "{{resource.name}}",
+        description: "Human-readable resource name",
+        example: "feature.dark_mode",
+    },
+    {
+        variable: "{{environment}}",
+        description: "Environment name (empty if none)",
+        example: "production",
+    },
+    {
+        variable: "{{actor.id}}",
+        description: "User ID of the person who made the change",
+        example: "user_abc123",
+    },
+    {
+        variable: "{{timestamp}}",
+        description: "ISO 8601 timestamp of the event",
+        example: "2025-01-15T09:30:00.000Z",
+    },
+    {
+        variable: "{{project.id}}",
+        description: "Project identifier",
+        example: "proj_xyz",
+    },
+    {
+        variable: "{{webhook.id}}",
+        description: "Webhook identifier",
+        example: "whk_123",
+    },
+    {
+        variable: "{{changes.old}}",
+        description: "Previous value as JSON string (empty if create)",
+        example: '{"enabled": true}',
+    },
+    {
+        variable: "{{changes.new}}",
+        description: "New value as JSON string (empty if delete)",
+        example: '{"enabled": false}',
+    },
+];
+/**
+ * Event types that can trigger webhooks.
+ */
+export const WEBHOOK_EVENT_TYPES = [
+    "create",
+    "update",
+    "delete",
+    "state_change",
+];
+/**
+ * Resource categories for webhook filtering.
+ */
+export const WEBHOOK_RESOURCE_CATEGORIES = [
+    "config",
+    "segment",
+    "api_key",
+    "project",
+    "team",
+    "environment",
+];
+/**
+ * Sample payload used for preview/testing (shared between portal and docs).
+ */
+export const SAMPLE_WEBHOOK_EVENT = {
+    action: "update",
+    resourceCategory: "config",
+    resourcePath: "environments/production/configs/feature.dark_mode",
+    resourceName: "feature.dark_mode",
+    environment: "production",
+    actorId: "user_abc123",
+    timestamp: "2025-01-15T09:30:00.000Z",
+    oldValue: { value: false },
+    newValue: { value: true },
+    projectId: "proj_xyz",
+    webhookId: "whk_sample",
+};
+//# sourceMappingURL=webhook-formats.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jewel998/config",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "private": false,
   "type": "module",
   "sideEffects": false,