@core-sdk/feature-flags-sdk 0.1.0

package/dist/cache.d.ts

@@ -0,0 +1,14 @@
+export interface CacheEntry<T> {
+    value: T;
+    expiresAt: number;
+}
+export declare class TtlMemoryCache<T> {
+    private readonly ttlMs;
+    private readonly store;
+    constructor(ttlMs: number);
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    delete(key: string): void;
+    clear(): void;
+}
+//# 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,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC;IACT,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,cAAc,CAAC,CAAC;IAGf,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFlC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;gBAE7B,KAAK,EAAE,MAAM;IAE1C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAU/B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAIhC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,KAAK,IAAI,IAAI;CAGd"}

package/dist/cache.js

@@ -0,0 +1,26 @@
+export class TtlMemoryCache {
+    ttlMs;
+    store = new Map();
+    constructor(ttlMs) {
+        this.ttlMs = ttlMs;
+    }
+    get(key) {
+        const e = this.store.get(key);
+        if (!e)
+            return undefined;
+        if (Date.now() > e.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return e.value;
+    }
+    set(key, value) {
+        this.store.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+    }
+    delete(key) {
+        this.store.delete(key);
+    }
+    clear() {
+        this.store.clear();
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,31 @@
+import { type EvaluateFlagResult, type EvaluationContext } from "@core-sdk/feature-flags-core";
+import type { FeatureFlagRecord, FeatureFlagsSdkConfig } from "./types.js";
+export declare class FeatureFlagsClient {
+    private readonly config;
+    private readonly fetchImpl;
+    private readonly cache;
+    constructor(config: FeatureFlagsSdkConfig);
+    private headers;
+    private parseJson;
+    /**
+     * Load all flags for project into memory cache.
+     */
+    bootstrap(): Promise<FeatureFlagRecord[]>;
+    /**
+     * Cached definition by key; fetches detail endpoint on miss.
+     */
+    getFlag(flagKey: string): Promise<FeatureFlagRecord | undefined>;
+    evaluate(flagKey: string, context?: EvaluationContext): EvaluateFlagResult;
+    evaluateAsync(flagKey: string, context?: EvaluationContext): Promise<EvaluateFlagResult>;
+    isEnabled(flagKey: string, context?: EvaluationContext): Promise<boolean>;
+    /**
+     * Change history for a flag (pass-through JSON — shape depends on API).
+     */
+    getHistory(flagKey: string): Promise<unknown>;
+    /**
+     * Specific version snapshot (for rollback preview on client).
+     */
+    getVersionDetail(flagKey: string, version: number): Promise<unknown>;
+    invalidate(flagKey?: string): 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,EAGL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,8BAA8B,CAAC;AAStC,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EAEtB,MAAM,YAAY,CAAC;AAiBpB,qBAAa,kBAAkB;IAIjB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;gBAE7B,MAAM,EAAE,qBAAqB;YAO5C,OAAO;YAQP,SAAS;IAUvB;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAsB/C;;OAEG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IA2BtE,QAAQ,CACN,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB,GAC9B,kBAAkB;IAUf,aAAa,CACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,kBAAkB,CAAC;IAQxB,SAAS,CACb,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,OAAO,CAAC;IAUnB;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAanD;;OAEG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAc1E,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;CAOnC"}

package/dist/client.js

@@ -0,0 +1,145 @@
+import { evaluateFlag, } from "@core-sdk/feature-flags-core";
+import { TtlMemoryCache } from "./cache.js";
+import { flagDetailPath, flagHistoryPath, flagsCollectionPath, flagVersionPath, } from "./paths.js";
+import { parseFlagRecord, unwrapFlagList } from "./normalize.js";
+function defaultFetch() {
+    const f = globalThis.fetch;
+    if (typeof f !== "function") {
+        throw new Error("fetch is not available; pass fetchImpl in config");
+    }
+    return f.bind(globalThis);
+}
+function toDefinition(rec) {
+    return {
+        enabled: rec.enabled,
+        rules: rec.rules,
+    };
+}
+export class FeatureFlagsClient {
+    config;
+    fetchImpl;
+    cache;
+    constructor(config) {
+        this.config = config;
+        this.fetchImpl = config.fetchImpl ?? defaultFetch();
+        this.cache = new TtlMemoryCache(config.cacheTtlMs ?? 60_000);
+    }
+    async headers() {
+        const extra = this.config.getHeaders ? await this.config.getHeaders() : {};
+        return {
+            Accept: "application/json",
+            ...extra,
+        };
+    }
+    async parseJson(res) {
+        const text = await res.text();
+        if (!text)
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error(`Invalid JSON response (${res.status})`);
+        }
+    }
+    /**
+     * Load all flags for project into memory cache.
+     */
+    async bootstrap() {
+        const url = flagsCollectionPath(this.config.baseUrl, this.config.projectKey);
+        const res = await this.fetchImpl(url, { headers: await this.headers() });
+        if (!res.ok) {
+            throw new Error(`bootstrap failed: ${res.status}`);
+        }
+        const json = await this.parseJson(res);
+        const rows = unwrapFlagList(json);
+        const list = [];
+        for (const row of rows) {
+            const rec = parseFlagRecord(row);
+            if (rec) {
+                this.cache.set(rec.key, rec);
+                list.push(rec);
+            }
+        }
+        return list;
+    }
+    /**
+     * Cached definition by key; fetches detail endpoint on miss.
+     */
+    async getFlag(flagKey) {
+        const hit = this.cache.get(flagKey);
+        if (hit)
+            return hit;
+        const url = flagDetailPath(this.config.baseUrl, this.config.projectKey, flagKey);
+        const res = await this.fetchImpl(url, { headers: await this.headers() });
+        if (res.status === 404)
+            return undefined;
+        if (!res.ok) {
+            throw new Error(`getFlag failed: ${res.status}`);
+        }
+        const json = await this.parseJson(res);
+        const raw = json && typeof json === "object" && "data" in json
+            ? json.data
+            : json;
+        const rec = parseFlagRecord(raw);
+        if (rec) {
+            this.cache.set(rec.key, rec);
+            return rec;
+        }
+        return undefined;
+    }
+    evaluate(flagKey, context = {}) {
+        const rec = this.cache.get(flagKey);
+        if (!rec) {
+            throw new Error(`Flag not in cache: ${flagKey}; call bootstrap() or getFlag() first`);
+        }
+        return evaluateFlag(toDefinition(rec), context);
+    }
+    async evaluateAsync(flagKey, context = {}) {
+        const rec = (await this.getFlag(flagKey)) ?? this.cache.get(flagKey);
+        if (!rec) {
+            throw new Error(`Unknown flag: ${flagKey}`);
+        }
+        return evaluateFlag(toDefinition(rec), context);
+    }
+    async isEnabled(flagKey, context = {}) {
+        try {
+            const r = await this.evaluateAsync(flagKey, context);
+            return r.enabled;
+        }
+        catch (e) {
+            console.error(`Error evaluating flag ${flagKey}:`, e);
+            return false;
+        }
+    }
+    /**
+     * Change history for a flag (pass-through JSON — shape depends on API).
+     */
+    async getHistory(flagKey) {
+        const url = flagHistoryPath(this.config.baseUrl, this.config.projectKey, flagKey);
+        const res = await this.fetchImpl(url, { headers: await this.headers() });
+        if (!res.ok) {
+            throw new Error(`getHistory failed: ${res.status}`);
+        }
+        return this.parseJson(res);
+    }
+    /**
+     * Specific version snapshot (for rollback preview on client).
+     */
+    async getVersionDetail(flagKey, version) {
+        const url = flagVersionPath(this.config.baseUrl, this.config.projectKey, flagKey, version);
+        const res = await this.fetchImpl(url, { headers: await this.headers() });
+        if (!res.ok) {
+            throw new Error(`getVersionDetail failed: ${res.status}`);
+        }
+        return this.parseJson(res);
+    }
+    invalidate(flagKey) {
+        if (flagKey === undefined) {
+            this.cache.clear();
+        }
+        else {
+            this.cache.delete(flagKey);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { FeatureFlagsClient } from "./client.js";
+export type { FeatureFlagRecord, FeatureFlagsSdkConfig, FlagListJson, HistoryEntryJson, HttpFetch, } 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,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,YAAY,EACZ,gBAAgB,EAChB,SAAS,GACV,MAAM,YAAY,CAAC"}

package/dist/index.js

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

package/dist/normalize.d.ts

@@ -0,0 +1,10 @@
+import type { FeatureFlagRecord } from "./types.js";
+/**
+ * Parse one flag object from API JSON.
+ */
+export declare function parseFlagRecord(raw: unknown): FeatureFlagRecord | null;
+/**
+ * Extract array from list response (raw array or `{ data: [] }`).
+ */
+export declare function unwrapFlagList(json: unknown): unknown[];
+//# sourceMappingURL=normalize.d.ts.map

package/dist/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AA8BpD;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAOtE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,EAAE,CAKvD"}

package/dist/normalize.js

@@ -0,0 +1,54 @@
+function isObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function asRules(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const item of v) {
+        if (!isObject(item))
+            continue;
+        const id = item.id;
+        const field = item.field;
+        const operator = item.operator;
+        if (typeof id !== "string" || typeof field !== "string" || typeof operator !== "string") {
+            continue;
+        }
+        if (!["eq", "neq", "contains", "in"].includes(operator))
+            continue;
+        const active = item.active === false ? false : true;
+        out.push({
+            id,
+            field,
+            operator: operator,
+            value: item.value,
+            active,
+        });
+    }
+    return out;
+}
+/**
+ * Parse one flag object from API JSON.
+ */
+export function parseFlagRecord(raw) {
+    if (!isObject(raw))
+        return null;
+    const key = raw.key;
+    if (typeof key !== "string" || key.length === 0)
+        return null;
+    const enabled = Boolean(raw.enabled);
+    const rules = asRules(raw.rules);
+    return { key, enabled, rules };
+}
+/**
+ * Extract array from list response (raw array or `{ data: [] }`).
+ */
+export function unwrapFlagList(json) {
+    if (Array.isArray(json))
+        return json;
+    if (isObject(json) && Array.isArray(json.data))
+        return json.data;
+    if (isObject(json) && Array.isArray(json.flags))
+        return json.flags;
+    return [];
+}

package/dist/paths.d.ts

@@ -0,0 +1,6 @@
+/** Internal route builders — consumers only pass baseUrl + projectKey. */
+export declare function flagsCollectionPath(baseUrl: string, projectKey: string): string;
+export declare function flagDetailPath(baseUrl: string, projectKey: string, flagKey: string): string;
+export declare function flagHistoryPath(baseUrl: string, projectKey: string, flagKey: string): string;
+export declare function flagVersionPath(baseUrl: string, projectKey: string, flagKey: string, version: number): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAE1E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,MAAM,CAGR;AAED,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,MAAM,CAKR;AAED,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,MAAM,CAKR;AAED,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,MAAM,CAKR"}

package/dist/paths.js

@@ -0,0 +1,17 @@
+/** Internal route builders — consumers only pass baseUrl + projectKey. */
+export function flagsCollectionPath(baseUrl, projectKey) {
+    const b = baseUrl.replace(/\/$/, "");
+    return `${b}/projects/${encodeURIComponent(projectKey)}/flags`;
+}
+export function flagDetailPath(baseUrl, projectKey, flagKey) {
+    const b = baseUrl.replace(/\/$/, "");
+    return `${b}/projects/${encodeURIComponent(projectKey)}/flags/${encodeURIComponent(flagKey)}`;
+}
+export function flagHistoryPath(baseUrl, projectKey, flagKey) {
+    const b = baseUrl.replace(/\/$/, "");
+    return `${b}/projects/${encodeURIComponent(projectKey)}/flags/${encodeURIComponent(flagKey)}/history`;
+}
+export function flagVersionPath(baseUrl, projectKey, flagKey, version) {
+    const b = baseUrl.replace(/\/$/, "");
+    return `${b}/projects/${encodeURIComponent(projectKey)}/flags/${encodeURIComponent(flagKey)}/versions/${version}`;
+}

package/dist/types.d.ts

@@ -0,0 +1,31 @@
+import type { DeclarativeRule } from "@core-sdk/feature-flags-core";
+/**
+ * Normalized flag row after bootstrap / get — enough for evaluateFlag.
+ */
+export interface FeatureFlagRecord {
+    readonly key: string;
+    readonly enabled: boolean;
+    readonly rules: readonly DeclarativeRule[];
+}
+export type HttpFetch = (input: string, init?: RequestInit) => Promise<Response>;
+export interface FeatureFlagsSdkConfig {
+    readonly baseUrl: string;
+    readonly projectKey: string;
+    /** Default globalThis.fetch */
+    readonly fetchImpl?: HttpFetch;
+    /** Extra headers (e.g. Authorization) */
+    readonly getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Cache TTL for in-memory flag definitions (default 60_000) */
+    readonly cacheTtlMs?: number;
+}
+/** Loose API body — server may wrap in `{ data }`. */
+export type FlagListJson = unknown;
+export interface HistoryEntryJson {
+    readonly id?: string;
+    readonly at?: string;
+    readonly action?: string;
+    readonly version?: number;
+    readonly summaryNote?: string;
+    readonly [key: string]: unknown;
+}
+//# 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,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;CAC5C;AAED,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEjF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+BAA+B;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,yCAAyC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACrF,gEAAgE;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,sDAAsD;AACtD,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC;AAEnC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC"}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@core-sdk/feature-flags-sdk",
+  "version": "0.1.0",
+  "description": "HTTP client + cache for feature flags; uses @core-sdk/feature-flags-core for evaluation",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@core-sdk/feature-flags-core": "0.1.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.9"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}