shield360 1.1.0 → 1.2.1

package/dist/flags/client.js

@@ -0,0 +1,301 @@
+"use strict";
+/**
+ * Shield360 feature flags for Node: fetch an environment's flags, evaluate
+ * them locally, and stamp the variation served on the active span.
+ *
+ *   import Shield360 from 'shield360';
+ *   Shield360.init({ applicationName: 'checkout-api' });  // or SHIELD360_URL / SHIELD360_API_KEY
+ *   if (Shield360.flags.isEnabled('new-checkout', { key: user.id, plan: user.plan })) { ... }
+ *   const model = Shield360.flags.getFlag('model-choice', { key: user.id }, 'gpt-4o-mini');
+ *
+ * The client polls GET /api/flags/rules (every 30 seconds by default, with
+ * jitter, sending the last ETag so an unchanged environment costs a 304),
+ * keeps the rules in memory and evaluates with the same engine as the server
+ * (./engine.ts, a byte-identical copy of sdk/flags-core). It never throws
+ * into the app: until rules arrive, for an unknown flag, or on any error, the
+ * caller's default is returned.
+ *
+ * Each evaluation sets `shield360.flag.<key>` = the served variation's key on
+ * the active span, so cost, latency and evals can be compared per variant.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flags = exports.FlagsClient = exports.DEFAULT_POLL_INTERVAL_MS = exports.SPAN_ATTRIBUTE_PREFIX = exports.RULES_PATH = void 0;
+exports.promptRefOf = promptRefOf;
+const api_1 = require("@opentelemetry/api");
+const config_1 = __importDefault(require("../config"));
+const prompt_hub_1 = __importDefault(require("../features/prompt-hub"));
+const engine_1 = require("./engine");
+exports.RULES_PATH = '/api/flags/rules';
+exports.SPAN_ATTRIBUTE_PREFIX = 'shield360.flag.';
+exports.DEFAULT_POLL_INTERVAL_MS = 30000;
+const MIN_POLL_INTERVAL_MS = 5000;
+const DEFAULT_TIMEOUT_MS = 10000;
+/** The Prompt Hub reference a flag value names, or null. */
+function promptRefOf(value) {
+    if (typeof value === 'string') {
+        const text = value.trim();
+        const at = text.lastIndexOf('@');
+        const name = at > 0 ? text.slice(0, at) : text;
+        const version = at > 0 ? text.slice(at + 1) : '';
+        if (!name || (at === 0))
+            return null;
+        return version ? { name, version } : { name };
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const v = value;
+        if (typeof v.name !== 'string' || !v.name.trim())
+            return null;
+        if (v.version !== undefined && v.version !== null && typeof v.version !== 'string')
+            return null;
+        return v.version ? { name: v.name.trim(), version: v.version } : { name: v.name.trim() };
+    }
+    return null;
+}
+function sameKind(value, fallback) {
+    if (fallback === undefined || fallback === null)
+        return true;
+    if (typeof fallback === 'object')
+        return value !== null && typeof value === 'object';
+    return typeof value === typeof fallback;
+}
+class FlagsClient {
+    constructor(options = {}) {
+        this.flags = new Map();
+        this.segments = [];
+        this.etag = null;
+        this.fetched = false;
+        this.timer = null;
+        this.started = false;
+        this.inFlight = null;
+        this.waiters = [];
+        this.warned = false;
+        this.options = { ...options };
+    }
+    /** Changes the options; takes effect on the next fetch. */
+    configure(options) {
+        this.options = { ...this.options, ...options };
+    }
+    destination() {
+        const env = typeof process !== 'undefined' ? process.env : {};
+        const url = (this.options.url ?? config_1.default.shield360Url ?? env.SHIELD360_URL ?? '').trim().replace(/\/+$/, '');
+        const apiKey = (this.options.apiKey ?? config_1.default.shield360ApiKey ?? env.SHIELD360_API_KEY ?? '').trim();
+        return url && apiKey ? { url, apiKey } : null;
+    }
+    applicationName() {
+        return this.options.applicationName ?? config_1.default.applicationName;
+    }
+    /** Starts polling (once). Called on first use; call it at startup to fetch early. */
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        void this.refresh().finally(() => this.schedule());
+    }
+    schedule() {
+        if (!this.started)
+            return;
+        const interval = Math.max(this.options.pollIntervalMs ?? exports.DEFAULT_POLL_INTERVAL_MS, MIN_POLL_INTERVAL_MS);
+        // ±10% jitter, so many processes started together do not poll together.
+        const delay = Math.round(interval * (0.9 + Math.random() * 0.2));
+        this.timer = setTimeout(() => {
+            void this.refresh().finally(() => this.schedule());
+        }, delay);
+        const t = this.timer;
+        if (typeof t.unref === 'function')
+            t.unref();
+    }
+    /** Stops polling. Rules already fetched keep being served. */
+    close() {
+        this.started = false;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+    }
+    /** Whether rules have been fetched at least once. */
+    isReady() {
+        return this.fetched;
+    }
+    /** Resolves true once rules have been fetched, or false after `timeoutMs`. */
+    ready(timeoutMs = DEFAULT_TIMEOUT_MS) {
+        this.start();
+        if (this.fetched)
+            return Promise.resolve(true);
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => resolve(false), timeoutMs);
+            const t = timer;
+            if (typeof t.unref === 'function')
+                t.unref();
+            this.waiters.push((ok) => {
+                clearTimeout(timer);
+                resolve(ok);
+            });
+        });
+    }
+    /** Fetches the rules now. Resolves true when the rules are current; never rejects. */
+    refresh() {
+        if (!this.inFlight) {
+            this.inFlight = this.fetchRules().finally(() => {
+                this.inFlight = null;
+            });
+        }
+        return this.inFlight;
+    }
+    async fetchRules() {
+        const dest = this.destination();
+        if (!dest) {
+            if (!this.warned) {
+                this.warned = true;
+                api_1.diag.warn('shield360 flags: no Shield360 URL and API key (SHIELD360_URL, SHIELD360_API_KEY); every flag serves its default.');
+            }
+            return false;
+        }
+        const doFetch = this.options.fetch ?? (typeof fetch === 'function' ? fetch : undefined);
+        if (!doFetch)
+            return false;
+        const controller = typeof AbortController === 'function' ? new AbortController() : null;
+        const timeout = setTimeout(() => controller?.abort(), this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        try {
+            const headers = { Authorization: `Bearer ${dest.apiKey}`, Accept: 'application/json' };
+            if (this.etag)
+                headers['If-None-Match'] = this.etag;
+            const response = await doFetch(`${dest.url}${exports.RULES_PATH}`, { method: 'GET', headers, signal: controller?.signal });
+            if (response.status === 304) {
+                this.markFetched();
+                return true;
+            }
+            if (!response.ok) {
+                api_1.diag.debug(`shield360 flags: rules fetch answered ${response.status}`);
+                return false;
+            }
+            const body = (await response.json());
+            if (!body || !Array.isArray(body.flags))
+                return false;
+            const next = new Map();
+            for (const raw of body.flags) {
+                // A flag that does not validate is left out: its callers get their default.
+                if ((0, engine_1.validateFlag)(raw).length)
+                    continue;
+                const flag = raw;
+                next.set(flag.key, flag);
+            }
+            const segments = [];
+            for (const raw of Array.isArray(body.segments) ? body.segments : []) {
+                if (!(0, engine_1.validateSegment)(raw).length)
+                    segments.push(raw);
+            }
+            this.flags = next;
+            this.segments = segments;
+            this.etag = response.headers.get('etag');
+            this.markFetched();
+            return true;
+        }
+        catch (err) {
+            api_1.diag.debug(`shield360 flags: rules fetch failed: ${err instanceof Error ? err.name : 'error'}`);
+            return false;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    markFetched() {
+        this.fetched = true;
+        const waiting = this.waiters;
+        this.waiters = [];
+        for (const w of waiting)
+            w(true);
+    }
+    /** The flag's value for this context, with the variation and why; never throws. */
+    getFlagDetail(key, context = {}, defaultValue) {
+        try {
+            this.start();
+            if (!this.fetched)
+                return { value: defaultValue, variation: null, reason: { kind: 'NOT_READY' } };
+            const flag = this.flags.get(key);
+            const app = this.applicationName();
+            if (!flag || (flag.appName && flag.appName !== app)) {
+                return { value: defaultValue, variation: null, reason: { kind: 'FLAG_NOT_FOUND' } };
+            }
+            const result = (0, engine_1.evaluate)(flag, context, this.segments);
+            if (result.variation === null)
+                return { value: defaultValue, variation: null, reason: result.reason };
+            if (!sameKind(result.value, defaultValue)) {
+                return { value: defaultValue, variation: null, reason: { kind: 'WRONG_TYPE' } };
+            }
+            if (this.options.recordOnSpan !== false) {
+                const span = api_1.trace.getActiveSpan();
+                if (span && span.isRecording())
+                    span.setAttribute(`${exports.SPAN_ATTRIBUTE_PREFIX}${key}`, result.variation);
+            }
+            return { value: result.value, variation: result.variation, reason: result.reason };
+        }
+        catch {
+            return { value: defaultValue, variation: null, reason: { kind: 'ERROR' } };
+        }
+    }
+    getFlag(key, context = {}, defaultValue) {
+        return this.getFlagDetail(key, context, defaultValue).value;
+    }
+    /** Whether a boolean flag is on for this context; false until rules arrive, for an unknown flag, or on error. */
+    isEnabled(key, context = {}) {
+        return this.getFlag(key, context, false) === true;
+    }
+    /**
+     * AI: the model a model-switch flag serves this context — a string flag whose
+     * variations are provider/model ids such as `openai/gpt-4o-mini`. The default
+     * until rules arrive, for an unknown flag, or for an empty value.
+     */
+    model(key, context = {}, defaultModel) {
+        const value = this.getFlag(key, context, defaultModel);
+        return typeof value === 'string' && value.trim() ? value : defaultModel;
+    }
+    /**
+     * AI: whether a kill switch is engaged for this context — true means stop the
+     * feature. A kill switch is a boolean flag that serves true while the feature
+     * may run; switching it off (or serving false) engages it. Until rules
+     * arrive, or for an unknown flag, it is not engaged: the feature keeps running.
+     */
+    killSwitch(key, context = {}) {
+        return this.getFlag(key, context, true) === false;
+    }
+    /**
+     * AI: the Prompt Hub prompt a prompt-version flag serves this context. The
+     * flag's variations name prompts (`{ "name": "support-reply", "version":
+     * "1.2.0" }` or `"support-reply@1.2.0"`); the one served is fetched from
+     * Prompt Hub with the SDK's own fetch. Never rejects: on any failure
+     * `prompt` is null and `error` says why.
+     */
+    async prompt(key, context = {}, defaultRef, options = {}) {
+        let ref = defaultRef;
+        let variation = null;
+        try {
+            const detail = this.getFlagDetail(key, context, undefined);
+            const served = detail.variation !== null ? promptRefOf(detail.value) : null;
+            if (served) {
+                ref = served;
+                variation = detail.variation;
+            }
+            const dest = this.destination();
+            const shouldCompile = options.shouldCompile ?? !!options.variables;
+            const answer = (await prompt_hub_1.default.getPrompts({
+                name: ref.name,
+                ...(ref.version ? { version: ref.version } : {}),
+                shouldCompile,
+                variables: options.variables || {},
+                ...(dest ? { url: dest.url, apiKey: dest.apiKey } : {}),
+            }));
+            const error = answer && answer.err ? String(answer.err) : null;
+            const prompt = error ? null : (answer?.res ?? answer?.data ?? null);
+            return { name: ref.name, version: ref.version ?? null, variation, prompt, error: prompt === null && !error ? 'empty response' : error };
+        }
+        catch (err) {
+            return { name: ref?.name ?? '', version: ref?.version ?? null, variation, prompt: null, error: err instanceof Error ? err.message : 'error' };
+        }
+    }
+}
+exports.FlagsClient = FlagsClient;
+/** The SDK's own client, behind `Shield360.flags`. It reads init()'s settings when it first fetches. */
+exports.flags = new FlagsClient();
+//# sourceMappingURL=client.js.map

package/dist/flags/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/flags/client.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;;;;AAqEH,kCAgBC;AAnFD,4CAAiD;AACjD,uDAAwC;AACxC,wEAA+C;AAC/C,qCASkB;AAEL,QAAA,UAAU,GAAG,kBAAkB,CAAC;AAChC,QAAA,qBAAqB,GAAG,iBAAiB,CAAC;AAC1C,QAAA,wBAAwB,GAAG,KAAM,CAAC;AAC/C,MAAM,oBAAoB,GAAG,IAAK,CAAC;AACnC,MAAM,kBAAkB,GAAG,KAAM,CAAC;AAgDlC,4DAA4D;AAC5D,SAAgB,WAAW,CAAC,KAAc;IACxC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC1B,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACjC,MAAM,IAAI,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC/C,MAAM,OAAO,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACjD,IAAI,CAAC,IAAI,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QACrC,OAAO,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IAChD,CAAC;IACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAChE,MAAM,CAAC,GAAG,KAAgC,CAAC;QAC3C,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE;YAAE,OAAO,IAAI,CAAC;QAC9D,IAAI,CAAC,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAChG,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,OAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;IACrG,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,QAAQ,CAAC,KAAgB,EAAE,QAAiB;IACnD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7D,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC;IACrF,OAAO,OAAO,KAAK,KAAK,OAAO,QAAQ,CAAC;AAC1C,CAAC;AAED,MAAa,WAAW;IAYtB,YAAY,UAAwB,EAAE;QAV9B,UAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;QAC1C,aAAQ,GAAc,EAAE,CAAC;QACzB,SAAI,GAAkB,IAAI,CAAC;QAC3B,YAAO,GAAG,KAAK,CAAC;QAChB,UAAK,GAAyC,IAAI,CAAC;QACnD,YAAO,GAAG,KAAK,CAAC;QAChB,aAAQ,GAA4B,IAAI,CAAC;QACzC,YAAO,GAAoC,EAAE,CAAC;QAC9C,WAAM,GAAG,KAAK,CAAC;QAGrB,IAAI,CAAC,OAAO,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC;IAChC,CAAC;IAED,2DAA2D;IAC3D,SAAS,CAAC,OAAqB;QAC7B,IAAI,CAAC,OAAO,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;IACjD,CAAC;IAEO,WAAW;QACjB,MAAM,GAAG,GAAG,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAE,EAAyC,CAAC;QACtG,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,gBAAe,CAAC,YAAY,IAAI,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACrH,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,gBAAe,CAAC,eAAe,IAAI,GAAG,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC9G,OAAO,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAChD,CAAC;IAEO,eAAe;QACrB,OAAO,IAAI,CAAC,OAAO,CAAC,eAAe,IAAI,gBAAe,CAAC,eAAe,CAAC;IACzE,CAAC;IAED,qFAAqF;IACrF,KAAK;QACH,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrD,CAAC;IAEO,QAAQ;QACd,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,IAAI,gCAAwB,EAAE,oBAAoB,CAAC,CAAC;QACzG,wEAAwE;QACxE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;QACjE,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC3B,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACrD,CAAC,EAAE,KAAK,CAAC,CAAC;QACV,MAAM,CAAC,GAAG,IAAI,CAAC,KAA0C,CAAC;QAC1D,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,UAAU;YAAE,CAAC,CAAC,KAAK,EAAE,CAAC;IAC/C,CAAC;IAED,8DAA8D;IAC9D,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,IAAI,CAAC,KAAK;YAAE,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,qDAAqD;IACrD,OAAO;QACL,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,8EAA8E;IAC9E,KAAK,CAAC,SAAS,GAAG,kBAAkB;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC/C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC;YAC1D,MAAM,CAAC,GAAG,KAA0C,CAAC;YACrD,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,UAAU;gBAAE,CAAC,CAAC,KAAK,EAAE,CAAC;YAC7C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE;gBACvB,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,OAAO,CAAC,EAAE,CAAC,CAAC;YACd,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED,sFAAsF;IACtF,OAAO;QACL,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;gBAC7C,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;YACvB,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAEO,KAAK,CAAC,UAAU;QACtB,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAChC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACjB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;gBACnB,UAAI,CAAC,IAAI,CAAC,kHAAkH,CAAC,CAAC;YAChI,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACxF,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAC3B,MAAM,UAAU,GAAG,OAAO,eAAe,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,eAAe,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACxF,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAC,CAAC;QACpG,IAAI,CAAC;YACH,MAAM,OAAO,GAA2B,EAAE,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;YAC/G,IAAI,IAAI,CAAC,IAAI;gBAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC;YACpD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,GAAG,kBAAU,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;YACnH,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBAC5B,IAAI,CAAC,WAAW,EAAE,CAAC;gBACnB,OAAO,IAAI,CAAC;YACd,CAAC;YACD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,UAAI,CAAC,KAAK,CAAC,yCAAyC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;gBACvE,OAAO,KAAK,CAAC;YACf,CAAC;YACD,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAc,CAAC;YAClD,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAC;YACtD,MAAM,IAAI,GAAG,IAAI,GAAG,EAA0B,CAAC;YAC/C,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBAC7B,4EAA4E;gBAC5E,IAAI,IAAA,qBAAY,EAAC,GAAG,CAAC,CAAC,MAAM;oBAAE,SAAS;gBACvC,MAAM,IAAI,GAAG,GAAqB,CAAC;gBACnC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAC3B,CAAC;YACD,MAAM,QAAQ,GAAc,EAAE,CAAC;YAC/B,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;gBACpE,IAAI,CAAC,IAAA,wBAAe,EAAC,GAAG,CAAC,CAAC,MAAM;oBAAE,QAAQ,CAAC,IAAI,CAAC,GAAc,CAAC,CAAC;YAClE,CAAC;YACD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;YAClB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;YACzB,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACzC,IAAI,CAAC,WAAW,EAAE,CAAC;YACnB,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,UAAI,CAAC,KAAK,CAAC,wCAAwC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;YAChG,OAAO,KAAK,CAAC;QACf,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAEO,WAAW;QACjB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAClB,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,mFAAmF;IACnF,aAAa,CAAkC,GAAW,EAAE,UAA6B,EAAE,EAAE,YAAe;QAC1G,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,EAAE,CAAC;YACb,IAAI,CAAC,IAAI,CAAC,OAAO;gBAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,CAAC;YAClG,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACjC,MAAM,GAAG,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;YACnC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,KAAK,GAAG,CAAC,EAAE,CAAC;gBACpD,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,CAAC;YACtF,CAAC;YACD,MAAM,MAAM,GAAG,IAAA,iBAAQ,EAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;YACtD,IAAI,MAAM,CAAC,SAAS,KAAK,IAAI;gBAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;YACtG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,YAAY,CAAC,EAAE,CAAC;gBAC1C,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,CAAC;YAClF,CAAC;YACD,IAAI,IAAI,CAAC,OAAO,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC;gBACxC,MAAM,IAAI,GAAG,WAAK,CAAC,aAAa,EAAE,CAAC;gBACnC,IAAI,IAAI,IAAI,IAAI,CAAC,WAAW,EAAE;oBAAE,IAAI,CAAC,YAAY,CAAC,GAAG,6BAAqB,GAAG,GAAG,EAAE,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;YACxG,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,KAAU,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;QAC1F,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC;QAC7E,CAAC;IACH,CAAC;IAOD,OAAO,CAAC,GAAW,EAAE,UAA6B,EAAE,EAAE,YAAmC;QACvF,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,KAAK,CAAC;IAC9D,CAAC;IAED,iHAAiH;IACjH,SAAS,CAAC,GAAW,EAAE,UAA6B,EAAE;QACpD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC;IACpD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAW,EAAE,UAA6B,EAAE,EAAE,YAAoB;QACtE,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;QACvD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC;IAC1E,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,GAAW,EAAE,UAA6B,EAAE;QACrD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,KAAK,CAAC;IACpD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,UAA6B,EAAE,EAAE,UAAqB,EAAE,UAA6B,EAAE;QAC/G,IAAI,GAAG,GAAc,UAAU,CAAC;QAChC,IAAI,SAAS,GAAkB,IAAI,CAAC;QACpC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAwB,GAAG,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;YAClF,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC5E,IAAI,MAAM,EAAE,CAAC;gBACX,GAAG,GAAG,MAAM,CAAC;gBACb,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;YAC/B,CAAC;YACD,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;YAChC,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;YACnE,MAAM,MAAM,GAAG,CAAC,MAAM,oBAAS,CAAC,UAAU,CAAC;gBACzC,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChD,aAAa;gBACb,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,EAAE;gBAClC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACxD,CAAC,CAAiE,CAAC;YACpE,MAAM,KAAK,GAAG,MAAM,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC/D,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,GAAG,IAAI,MAAM,EAAE,IAAI,IAAI,IAAI,CAAC,CAAC;YACpE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;QAC1I,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,IAAI,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,IAAI,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QAChJ,CAAC;IACH,CAAC;CACF;AA9OD,kCA8OC;AAED,wGAAwG;AAC3F,QAAA,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC"}

package/dist/flags/engine.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Shield360 feature flags: the evaluation engine.
+ *
+ * Canonical source: sdk/flags-core/src/engine.ts. Byte-identical copies live at
+ * sdk/typescript/src/flags/engine.ts (the TypeScript SDK) and
+ * src/client/src/lib/platform/flags/engine.ts (the server); tests in both fail
+ * when a copy differs. The Python, Go and .NET SDKs port it
+ * (sdk/python/src/shield360/flags/_engine.py, sdk/go/flags/engine.go,
+ * sdk/dotnet/src/Shield360/Flags/FlagEngine.cs), and every implementation is
+ * held to sdk/flags-core/testdata/vectors.json. Change the canonical file,
+ * copy it, port it, and add vectors.
+ *
+ * Pure and dependency-free: no imports, no Node built-ins, no clock, no
+ * randomness. The same flag and context always give the same answer.
+ */
+export type FlagType = 'boolean' | 'string' | 'number' | 'json';
+export declare const FLAG_TYPES: readonly FlagType[];
+export type FlagValue = boolean | string | number | null | FlagValue[] | {
+    [key: string]: FlagValue;
+};
+export type Variation = {
+    key: string;
+    name?: string;
+    value: FlagValue;
+};
+export declare const OPERATORS: readonly ["equals", "not_equals", "in", "not_in", "contains", "starts_with", "lt", "lte", "gt", "gte", "semver_eq", "semver_lt", "semver_lte", "semver_gt", "semver_gte", "in_segment", "not_in_segment"];
+export type Operator = (typeof OPERATORS)[number];
+/**
+ * Segment operators: the condition's attribute is the literal `segment` and its
+ * values are segment keys. `in_segment` holds when the context is in any of
+ * them, `not_in_segment` when it is in none. A condition naming a segment the
+ * caller did not pass (or one that does not validate) never holds, either way.
+ */
+export declare const SEGMENT_OPERATORS: readonly Operator[];
+export declare const SEGMENT_ATTRIBUTE = "segment";
+export declare const isSegmentOperator: (v: unknown) => boolean;
+export type ConditionValue = string | number | boolean;
+export type Condition = {
+    attribute: string;
+    operator: Operator;
+    values: ConditionValue[];
+};
+export type RolloutWeight = {
+    variation: string;
+    weight: number;
+};
+export type Rollout = {
+    bucketBy?: string;
+    weights: RolloutWeight[];
+};
+export type Serve = {
+    variation: string;
+} | {
+    rollout: Rollout;
+};
+export type Rule = {
+    id: string;
+    description?: string;
+    conditions: Condition[];
+    serve: Serve;
+};
+/**
+ * A named, reusable set of conditions of one environment: the context is in
+ * the segment when every condition holds. Segments do not reference segments.
+ */
+export type Segment = {
+    key: string;
+    conditions: Condition[];
+    version?: number;
+};
+export type FlagDefinition = {
+    key: string;
+    type: FlagType;
+    variations: Variation[];
+    /** The variation served while the flag is off (and while it is archived). */
+    offVariation: string;
+    on: boolean;
+    rules: Rule[];
+    /** Served when the flag is on and no rule matches. */
+    fallthrough: Serve;
+    salt: string;
+    archived?: boolean;
+    version?: number;
+    /** service.name of the one app this flag is for; null for every app. */
+    appName?: string | null;
+};
+export type ContextValue = string | number | boolean | null | undefined | ConditionValue[];
+export type EvaluationContext = {
+    [attribute: string]: ContextValue;
+};
+export type ReasonKind = 'OFF' | 'ARCHIVED' | 'RULE_MATCH' | 'FALLTHROUGH' | 'ERROR';
+export type Reason = {
+    kind: ReasonKind;
+    ruleIndex?: number;
+    ruleId?: string;
+    inRollout?: boolean;
+    bucket?: number;
+    errorKind?: 'MALFORMED_FLAG';
+};
+export type Evaluation = {
+    /** The served variation's key; null only when the flag is malformed. */
+    variation: string | null;
+    value: FlagValue;
+    reason: Reason;
+};
+/** Buckets run 0..99,999: a rollout weight of 1 is a thousandth of a percent. */
+export declare const BUCKETS = 100000;
+export declare const DEFAULT_BUCKET_BY = "key";
+/**
+ * Counts every implementation checks alike. Lengths and sizes (names, text
+ * values, JSON size) are the server's to limit: string length is counted
+ * differently from one language to the next.
+ */
+export declare const LIMITS: {
+    variations: number;
+    rules: number;
+    conditions: number;
+    conditionValues: number;
+    /** Segments one condition may name. */
+    segmentsPerCondition: number;
+};
+export declare const isFlagKey: (v: unknown) => v is string;
+export declare const isVariationKey: (v: unknown) => v is string;
+export declare const isAttributeName: (v: unknown) => v is string;
+export declare const isOperator: (v: unknown) => v is Operator;
+/** UTF-8 bytes of a string, without TextEncoder (so nothing global is assumed). */
+export declare function utf8(text: string): number[];
+/** MurmurHash3 (x86, 32-bit, seed 0) of the UTF-8 bytes of `text`, unsigned. */
+export declare function murmur3(text: string): number;
+/** The bucket (0..99,999) a value falls in for a flag: stable across runs, processes and SDKs. */
+export declare function bucketOf(flagKey: string, salt: string, value: string): number;
+/**
+ * The text of a scalar, the same in every SDK: strings as they are, booleans
+ * as true/false, integers without a decimal point, other numbers as their
+ * shortest round-trip form. Null for anything else.
+ */
+export declare function textOf(v: unknown): string | null;
+/** A finite number, or the text of one (no spaces); null otherwise. */
+export declare function numberOf(v: unknown): number | null;
+type SemVer = {
+    major: number;
+    minor: number;
+    patch: number;
+    pre: string[];
+};
+/** A semantic version; a missing minor or patch is 0, build metadata is ignored. */
+export declare function parseSemver(v: unknown): SemVer | null;
+/** -1, 0 or 1, by semver precedence. */
+export declare function compareSemver(a: SemVer, b: SemVer): number;
+/**
+ * Whether the context satisfies one condition. A missing (or null) attribute
+ * never matches, negated operators included. An array attribute matches a
+ * positive operator when any element does, and a negated one when none does.
+ */
+export declare function conditionMatches(condition: Condition, context: EvaluationContext, segments?: Segment[]): boolean;
+/** The valid segment of this key among `segments`, or null. */
+export declare function findSegment(segments: Segment[] | undefined, key: unknown): Segment | null;
+/** Whether the context is in the segment: every one of its conditions holds. */
+export declare function segmentMatches(segment: Segment, context: EvaluationContext): boolean;
+/** Every condition holds (a rule with none never matches). */
+export declare function ruleMatches(rule: Rule, context: EvaluationContext, segments?: Segment[]): boolean;
+/** The segment keys a flag's rules name, each once, in order of first use. */
+export declare function segmentKeysOf(flag: Pick<FlagDefinition, 'rules'>): string[];
+/** The variation a rollout serves this context, and the bucket it fell in. */
+export declare function rolloutVariation(flag: Pick<FlagDefinition, 'key' | 'salt'>, rollout: Rollout, context: EvaluationContext): {
+    variation: string;
+    bucket: number;
+};
+export type ValidationError = {
+    path: string;
+    code: string;
+};
+/** Whether `value` is of the flag's type. */
+export declare function valueMatchesType(type: FlagType, value: unknown): boolean;
+/** Null, a string, a boolean, a finite number, or arrays and plain objects of them, at most 20 deep. */
+export declare function plainJson(v: unknown, depth: number): boolean;
+/**
+ * Everything wrong with a flag definition, by path; empty when it is valid.
+ * The server refuses to save an invalid flag; the SDKs and the engine treat
+ * one as malformed and serve the caller's default.
+ */
+export declare function validateFlag(input: unknown): ValidationError[];
+/**
+ * Everything wrong with a segment, by path; empty when it is valid. A segment
+ * has a key (the flag key pattern) and 1..20 conditions with the same
+ * operators as a rule's, except the segment operators: segments do not nest.
+ */
+export declare function validateSegment(input: unknown): ValidationError[];
+/**
+ * The variation a flag serves a context (`segments` are the environment's
+ * segments, for rules that name them):
+ *   archived  -> the off variation (ARCHIVED)
+ *   off       -> the off variation (OFF)
+ *   on        -> the first rule, in order, whose conditions all hold (RULE_MATCH),
+ *                else the fallthrough (FALLTHROUGH)
+ * A rollout picks by bucket. A malformed flag serves nothing (ERROR): the
+ * caller's default applies. Never throws.
+ */
+export declare function evaluate(flag: FlagDefinition, context?: EvaluationContext, segments?: Segment[]): Evaluation;
+export {};