@nebulr-group/bridge-auth-core 0.1.1 → 0.4.0-beta.0

package/dist/flags/flag.d.ts

@@ -0,0 +1,199 @@
+import { type EvalContext, type Rule, type FlagState } from './evaluator.js';
+import { AttributeProviderRegistry, type AttributeProvider } from './attribute-providers.js';
+/**
+ * The attribute types the SDK and admin UI both understand. `semver` is a
+ * commonly-needed string subtype that powers `app_version > 4.12` style rules;
+ * runtime evaluation treats it as a string with regex-friendly comparators.
+ */
+export type DeclaredAttributeType = 'string' | 'number' | 'boolean' | 'date' | 'semver' | 'json';
+export interface AttributeDeclaration {
+    name: string;
+    type: DeclaredAttributeType;
+    /** Unix-ms when this declaration was made. */
+    timestamp: number;
+}
+export type FlagValueType = 'boolean' | 'string' | 'number' | 'json';
+export interface CachedFlag {
+    key: string;
+    state: FlagState;
+    valueType: FlagValueType;
+    offValue: unknown;
+    onValue: unknown;
+    rule?: Rule;
+}
+export interface EvalTelemetry {
+    flag: string;
+    value: unknown;
+    variantIndex: number;
+    identity?: string;
+    /** Unix-ms when this eval happened. */
+    timestamp: number;
+    /** Optional opaque fingerprint of the call site (TBP-156). */
+    callSiteFingerprint?: string;
+}
+export interface DiscoveryTelemetry {
+    flag: string;
+    defaultValue: unknown;
+    observedType: FlagValueType;
+    timestamp: number;
+}
+export interface AttributeObservation {
+    /** Attribute key as the dev supplied it (e.g. 'country', 'myapp:foo'). */
+    key: string;
+    /** The sample value observed for the key in this eval. */
+    sampleValue: unknown;
+    /** Inferred type — fed into discovery so the admin UI gets a sensible picker. */
+    observedType: FlagValueType;
+    timestamp: number;
+}
+export interface BridgeFlagsHooks {
+    /** Called on every successful eval. Should not throw. */
+    onEval?: (ev: EvalTelemetry) => void;
+    /** Called the first time the SDK sees an unknown flag key. */
+    onDiscover?: (ev: DiscoveryTelemetry) => void;
+    /**
+     * Called once per distinct (key, sampleValue) seen in `bridge.flag()`
+     * per-call `context.attributes`. The batcher relays this to
+     * `/v1/flags/discover` with `kind: 'attribute'` so the admin UI's attribute
+     * catalog shows what dev code actually supplies.
+     */
+    onAttributeObserved?: (ev: AttributeObservation) => void;
+    /**
+     * @deprecated Use per-call `bridge.flag(key, default, { attributes: {...} })`
+     * instead — per-call observations now feed the admin attribute catalog
+     * automatically via `onAttributeObserved`. `declareAttributes()` will be
+     * removed in a future minor release.
+     */
+    onAttributeDeclaration?: (decl: AttributeDeclaration) => void;
+}
+/**
+ * The result of a flag evaluation. `passed` is true when a targeting rule (or
+ * global on) resolved this flag to its on-value; false when the flag is off,
+ * no rule matched, or the flag isn't in the cache yet. `value` is always the
+ * Bridge-decided value — the on-value when passed, the off/default value when not.
+ */
+export interface FlagEvalResult<T> {
+    passed: boolean;
+    value: T;
+}
+/**
+ * BridgeFlags — the SDK-side flag cache + eval entry point. Most apps see
+ * exactly one instance, wired up at bootstrap time. Tests construct their
+ * own instances directly.
+ */
+/**
+ * Runtime mode for the SDK. Backends (Node servers) opt into `'backend'` to
+ * disable auto-anonymous identity — per locked decision #27, backend evals
+ * with no identity refuse to bucket rolled-out rules and return the safe
+ * default. Frontends use `'frontend'` (the default).
+ */
+export type BridgeFlagsMode = 'frontend' | 'backend';
+/**
+ * Minimal shape of the SDK's usage reporter — kept narrow so `BridgeFlags`
+ * doesn't depend on the full `UsageReporter` class. Framework wrappers pass
+ * `bridge.usage` (which has the same `report(metric, value?)` signature).
+ */
+export interface FlagUsageReporterLike {
+    report(metric: string, value?: number): void;
+}
+export declare class BridgeFlags {
+    private cache;
+    private context;
+    private hooks;
+    private discoveredKeys;
+    /** Per-runtime dedup for attribute observations: `${key}::${canonicalValue}`. */
+    private observedAttributeKeys;
+    private attributeDeclarations;
+    private mode;
+    private serverInstanceIdValue?;
+    private missingIdentityWarned;
+    /** Billing 2.0 US-10 (TBP-262): self-report `bridge.flag_evaluations` per eval. */
+    private usageReporter?;
+    /**
+     * Phase 1 / US-13 (TBP-293, TBP-294) — AttributeProvider registry consulted
+     * on every flag eval. Bridge-managed providers (`bridge:auth`,
+     * `bridge:billing`) are auto-registered by framework SDKs; apps register
+     * their own providers via `registerAttributeProvider()`.
+     */
+    private readonly registry;
+    constructor(options?: {
+        mode?: BridgeFlagsMode;
+        usageReporter?: FlagUsageReporterLike;
+    });
+    /**
+     * Register an `AttributeProvider`. Idempotent on `provider.name` —
+     * re-registering with the same name replaces the previous instance.
+     * Provider attributes flow into every `flag()` eval automatically.
+     * Dev-supplied attrs (via `setContext` / per-call `context`) win on
+     * collision (locked decision #20).
+     */
+    registerAttributeProvider(provider: AttributeProvider): void;
+    /** Remove a previously-registered provider by name. No-op if not present. */
+    unregisterAttributeProvider(name: string): void;
+    /**
+     * Expose the registry for advanced callers (e.g. async `applyTo()` refreshes
+     * driven by framework auth events). Most consumers should prefer
+     * `registerAttributeProvider` / `unregisterAttributeProvider`.
+     */
+    getAttributeProviderRegistry(): AttributeProviderRegistry;
+    /**
+     * Wire a usage reporter post-construction. The flag-eval path will call
+     * `reporter.report('bridge.flag_evaluations', 1)` on every successful eval
+     * (i.e. when a cached flag is present and evaluated). Discovery-only paths
+     * — first-sight unknown flag → default — do NOT count.
+     */
+    setUsageReporter(reporter: FlagUsageReporterLike | undefined): void;
+    /** Read the active runtime mode. */
+    getMode(): BridgeFlagsMode;
+    /**
+     * Set a stable server-instance identity (TBP-172). When set, backend flags
+     * that explicitly opt into system-level targeting can bucket on this value
+     * (e.g. canary a feature to one specific instance). Most evals continue to
+     * use the per-call/per-context identity.
+     */
+    setServerInstanceId(id: string): void;
+    /** Read the configured server-instance id, or undefined when not set. */
+    getServerInstanceId(): string | undefined;
+    /** Replace or merge the eval context. */
+    setContext(ctx: EvalContext, merge?: boolean): void;
+    /** Return a defensive shallow copy of the current eval context. */
+    getContext(): EvalContext;
+    /** Replace the cache from a bulk hydrate (e.g. response from bridge-api). */
+    hydrate(flags: CachedFlag[]): void;
+    /** Replace or insert a single flag (used by live updates). */
+    upsert(flag: CachedFlag): void;
+    /** Remove a flag from the cache. */
+    remove(key: string): void;
+    /** Register telemetry hooks. Replaces any previous hooks. */
+    setHooks(hooks: BridgeFlagsHooks): void;
+    /**
+     * Read a flag value. Returns `defaultValue` when the flag isn't known yet.
+     * TypeScript infers `T` from `defaultValue`, so callers don't write casts.
+     *
+     * An optional per-call `context` overrides the SDK's global context for
+     * just this eval. Attributes deep-merge — per-call wins on overlap, global
+     * keys not in the override are preserved.
+     */
+    flag<T>(key: string, defaultValue: T, context?: Partial<EvalContext>): FlagEvalResult<T>;
+    /**
+     * Internal — evaluate the cached flag against an eval context.
+     */
+    private evaluateCached;
+    /** Number of cached flags. Useful for debugging + tests. */
+    cacheSize(): number;
+    /** Get a snapshot of cached flag keys. */
+    cachedKeys(): string[];
+    /**
+     * @deprecated Per-call observations now power the admin attribute catalog
+     * automatically — just pass attributes when you evaluate a flag:
+     *   `bridge.flag('feat', false, { attributes: { plan: 'pro' } })`.
+     * The SDK reports each `(key, sampleValue)` once via `onAttributeObserved`,
+     * which the batcher relays to `/v1/flags/discover` with `kind: 'attribute'`.
+     * `declareAttributes()` will be removed in a future minor release.
+     */
+    declareAttributes(declarations: Record<string, DeclaredAttributeType>): void;
+    /** Read the current attribute type declarations. Useful for tests + framework wrappers. */
+    getAttributeDeclarations(): Record<string, DeclaredAttributeType>;
+    private safeHook;
+}
+//# sourceMappingURL=flag.d.ts.map

package/dist/flags/flag.d.ts.map

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

package/dist/flags/flag.js

@@ -0,0 +1,337 @@
+// bridge.flag(key, default) — the canonical SDK call (TBP-160).
+//
+// One method, one signature. The TypeScript return type matches the default
+// value's type (boolean / string / number / structured), so callers don't
+// need a separate cast.
+//
+// Local-first evaluation:
+//   1. Look up the flag in the in-memory cache
+//   2. If absent → return the developer's `defaultValue` (and emit a
+//      "discovered" hook so the SDK can register the key with bridge-api)
+//   3. If present → evaluate locally against the dev-supplied context
+//   4. Always emit an `onEval` hook so the SDK can batch eval telemetry
+//
+// Hooks are pluggable so this module stays platform-agnostic. The actual
+// wiring (HTTP batcher, fetch client, etc.) is the SDK integration's job
+// — see TBP-157 / TBP-156 for the implementations.
+import { evaluateRule, } from './evaluator.js';
+import { AttributeProviderRegistry, } from './attribute-providers.js';
+export class BridgeFlags {
+    cache = new Map();
+    context = { attributes: {} };
+    hooks = {};
+    discoveredKeys = new Set();
+    /** Per-runtime dedup for attribute observations: `${key}::${canonicalValue}`. */
+    observedAttributeKeys = new Set();
+    attributeDeclarations = new Map();
+    mode = 'frontend';
+    serverInstanceIdValue;
+    missingIdentityWarned = new Set();
+    /** Billing 2.0 US-10 (TBP-262): self-report `bridge.flag_evaluations` per eval. */
+    usageReporter;
+    /**
+     * Phase 1 / US-13 (TBP-293, TBP-294) — AttributeProvider registry consulted
+     * on every flag eval. Bridge-managed providers (`bridge:auth`,
+     * `bridge:billing`) are auto-registered by framework SDKs; apps register
+     * their own providers via `registerAttributeProvider()`.
+     */
+    registry = new AttributeProviderRegistry();
+    constructor(options = {}) {
+        if (options.mode)
+            this.mode = options.mode;
+        if (options.usageReporter)
+            this.usageReporter = options.usageReporter;
+    }
+    /**
+     * Register an `AttributeProvider`. Idempotent on `provider.name` —
+     * re-registering with the same name replaces the previous instance.
+     * Provider attributes flow into every `flag()` eval automatically.
+     * Dev-supplied attrs (via `setContext` / per-call `context`) win on
+     * collision (locked decision #20).
+     */
+    registerAttributeProvider(provider) {
+        this.registry.register(provider);
+    }
+    /** Remove a previously-registered provider by name. No-op if not present. */
+    unregisterAttributeProvider(name) {
+        this.registry.unregister(name);
+    }
+    /**
+     * Expose the registry for advanced callers (e.g. async `applyTo()` refreshes
+     * driven by framework auth events). Most consumers should prefer
+     * `registerAttributeProvider` / `unregisterAttributeProvider`.
+     */
+    getAttributeProviderRegistry() {
+        return this.registry;
+    }
+    /**
+     * Wire a usage reporter post-construction. The flag-eval path will call
+     * `reporter.report('bridge.flag_evaluations', 1)` on every successful eval
+     * (i.e. when a cached flag is present and evaluated). Discovery-only paths
+     * — first-sight unknown flag → default — do NOT count.
+     */
+    setUsageReporter(reporter) {
+        this.usageReporter = reporter;
+    }
+    /** Read the active runtime mode. */
+    getMode() {
+        return this.mode;
+    }
+    /**
+     * Set a stable server-instance identity (TBP-172). When set, backend flags
+     * that explicitly opt into system-level targeting can bucket on this value
+     * (e.g. canary a feature to one specific instance). Most evals continue to
+     * use the per-call/per-context identity.
+     */
+    setServerInstanceId(id) {
+        if (typeof id !== 'string' || id.length === 0)
+            return;
+        this.serverInstanceIdValue = id;
+    }
+    /** Read the configured server-instance id, or undefined when not set. */
+    getServerInstanceId() {
+        return this.serverInstanceIdValue;
+    }
+    /** Replace or merge the eval context. */
+    setContext(ctx, merge = false) {
+        if (merge) {
+            this.context = {
+                identity: ctx.identity ?? this.context.identity,
+                attributes: { ...this.context.attributes, ...ctx.attributes },
+            };
+        }
+        else {
+            this.context = ctx;
+        }
+    }
+    /** Return a defensive shallow copy of the current eval context. */
+    getContext() {
+        return { identity: this.context.identity, attributes: { ...this.context.attributes } };
+    }
+    /** Replace the cache from a bulk hydrate (e.g. response from bridge-api). */
+    hydrate(flags) {
+        this.cache.clear();
+        for (const f of flags) {
+            this.cache.set(f.key, f);
+        }
+    }
+    /** Replace or insert a single flag (used by live updates). */
+    upsert(flag) {
+        this.cache.set(flag.key, flag);
+    }
+    /** Remove a flag from the cache. */
+    remove(key) {
+        this.cache.delete(key);
+    }
+    /** Register telemetry hooks. Replaces any previous hooks. */
+    setHooks(hooks) {
+        this.hooks = hooks;
+    }
+    /**
+     * Read a flag value. Returns `defaultValue` when the flag isn't known yet.
+     * TypeScript infers `T` from `defaultValue`, so callers don't write casts.
+     *
+     * An optional per-call `context` overrides the SDK's global context for
+     * just this eval. Attributes deep-merge — per-call wins on overlap, global
+     * keys not in the override are preserved.
+     */
+    flag(key, defaultValue, context) {
+        const cached = this.cache.get(key);
+        const now = Date.now();
+        const observedType = inferType(defaultValue);
+        // Phase 1 / US-13 — merge AttributeProvider-supplied attrs into the eval
+        // context on every call. Precedence (locked decision #20):
+        //   providers (lowest)  <  setContext globals  <  per-call context (highest)
+        // Sync-only here: `collectSync()` skips any async provider for this eval
+        // (those refresh via `applyTo()` on auth/billing change events).
+        const providerAttrs = this.registry.size() > 0 ? this.registry.collectSync() : undefined;
+        let effectiveCtx;
+        if (!context && !providerAttrs) {
+            effectiveCtx = this.context;
+        }
+        else {
+            effectiveCtx = {
+                identity: context?.identity ?? this.context.identity,
+                attributes: {
+                    ...(providerAttrs ?? {}),
+                    ...this.context.attributes,
+                    ...(context?.attributes ?? {}),
+                },
+            };
+        }
+        // Observe per-call attribute keys so the admin UI's attribute catalog
+        // surfaces what dev code actually supplies (powers TBP-178 collision
+        // detection + custom attribute autocomplete). Dedup per (key, value) in
+        // this runtime to keep the batcher quiet.
+        if (context?.attributes) {
+            for (const [attrKey, attrVal] of Object.entries(context.attributes)) {
+                if (!attrKey)
+                    continue;
+                const dedupKey = `${attrKey}::${canonicalSampleKey(attrVal)}`;
+                if (this.observedAttributeKeys.has(dedupKey))
+                    continue;
+                this.observedAttributeKeys.add(dedupKey);
+                this.safeHook(() => this.hooks.onAttributeObserved?.({
+                    key: attrKey,
+                    sampleValue: attrVal,
+                    observedType: inferType(attrVal),
+                    timestamp: now,
+                }));
+            }
+        }
+        // Backend mode (TBP-170): refuse to evaluate user-level rules without an
+        // identity. Returns the developer's `defaultValue` rather than guessing
+        // with anonymous bucketing. Warn once per flag per runtime.
+        if (this.mode === 'backend' && !effectiveCtx.identity && cached?.state === 'on-with-rule') {
+            if (!this.missingIdentityWarned.has(key)) {
+                this.missingIdentityWarned.add(key);
+                try {
+                    // eslint-disable-next-line no-console
+                    globalThis.console?.warn?.(`[bridge.flag] '${key}': backend eval requires an explicit identity; returning default. ` +
+                        `Pass context.identity per call, or use a server-instance id for system-level flags.`);
+                }
+                catch {
+                    // ignore console errors
+                }
+            }
+            return { passed: false, value: defaultValue };
+        }
+        if (!cached) {
+            // First sight — emit a discovery event so the server creates the
+            // record. Dedupe per (key) in this runtime; server is the authority.
+            if (!this.discoveredKeys.has(key)) {
+                this.discoveredKeys.add(key);
+                this.safeHook(() => this.hooks.onDiscover?.({
+                    flag: key,
+                    defaultValue,
+                    observedType,
+                    timestamp: now,
+                }));
+            }
+            return { passed: false, value: defaultValue };
+        }
+        const result = this.evaluateCached(cached, effectiveCtx);
+        const value = result.value === undefined ? defaultValue : result.value;
+        this.safeHook(() => this.hooks.onEval?.({
+            flag: key,
+            value,
+            variantIndex: result.variantIndex,
+            identity: effectiveCtx.identity,
+            timestamp: now,
+        }));
+        // Billing 2.0 US-10 (TBP-262): SDK-side flag_evaluations self-report.
+        // Fire-and-forget; the reporter handles batching + errors. One call per
+        // eval — there's no batched flag API, so no multiplier needed.
+        if (this.usageReporter) {
+            this.safeHook(() => this.usageReporter?.report('bridge.flag_evaluations', 1));
+        }
+        // Fail-safe type check: if the cached value doesn't match the dev's
+        // declared default type, fall back to the default. Protects the app
+        // from admin-side type mistakes (TBP-159 validation should catch most
+        // of these at save time; this is the last-mile safety net).
+        if (!typeMatches(value, observedType)) {
+            return { passed: false, value: defaultValue };
+        }
+        return { passed: result.matched, value };
+    }
+    /**
+     * Internal — evaluate the cached flag against an eval context.
+     */
+    evaluateCached(cached, ctx) {
+        switch (cached.state) {
+            case 'off':
+                return { value: cached.offValue, variantIndex: -1, matched: false, excludedByRollout: false };
+            case 'on':
+                return { value: cached.onValue, variantIndex: 0, matched: true, excludedByRollout: false };
+            case 'on-with-rule': {
+                if (!cached.rule) {
+                    // Defensive: state says on-with-rule but no rule. Fall back to on.
+                    return { value: cached.onValue, variantIndex: -1, matched: false, excludedByRollout: false };
+                }
+                return evaluateRule(cached.rule, cached.key, ctx);
+            }
+            default:
+                return { value: cached.offValue, variantIndex: -1, matched: false, excludedByRollout: false };
+        }
+    }
+    /** Number of cached flags. Useful for debugging + tests. */
+    cacheSize() {
+        return this.cache.size;
+    }
+    /** Get a snapshot of cached flag keys. */
+    cachedKeys() {
+        return Array.from(this.cache.keys());
+    }
+    /**
+     * @deprecated Per-call observations now power the admin attribute catalog
+     * automatically — just pass attributes when you evaluate a flag:
+     *   `bridge.flag('feat', false, { attributes: { plan: 'pro' } })`.
+     * The SDK reports each `(key, sampleValue)` once via `onAttributeObserved`,
+     * which the batcher relays to `/v1/flags/discover` with `kind: 'attribute'`.
+     * `declareAttributes()` will be removed in a future minor release.
+     */
+    declareAttributes(declarations) {
+        const now = Date.now();
+        for (const [name, type] of Object.entries(declarations)) {
+            if (typeof name !== 'string' || name.length === 0)
+                continue;
+            if (this.attributeDeclarations.get(name) === type)
+                continue; // same as before; no-op
+            this.attributeDeclarations.set(name, type);
+            this.safeHook(() => this.hooks.onAttributeDeclaration?.({ name, type, timestamp: now }));
+        }
+    }
+    /** Read the current attribute type declarations. Useful for tests + framework wrappers. */
+    getAttributeDeclarations() {
+        return Object.fromEntries(this.attributeDeclarations.entries());
+    }
+    safeHook(fn) {
+        try {
+            fn();
+        }
+        catch {
+            // Telemetry must never break eval. Silently swallow.
+        }
+    }
+}
+// ── Type inference helpers ──────────────────────────────────────────────────
+function inferType(v) {
+    if (typeof v === 'boolean')
+        return 'boolean';
+    if (typeof v === 'number')
+        return 'number';
+    if (typeof v === 'string')
+        return 'string';
+    return 'json';
+}
+/** Stable string key for an attribute sample value — used for in-process dedup
+ *  in `observedAttributeKeys`. Safe for primitives + JSON-serialisable values. */
+function canonicalSampleKey(v) {
+    if (v === undefined)
+        return '∅undef';
+    if (v === null)
+        return '∅null';
+    if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return '∅unserialisable';
+    }
+}
+function typeMatches(v, expected) {
+    if (v === undefined || v === null)
+        return false;
+    switch (expected) {
+        case 'boolean':
+            return typeof v === 'boolean';
+        case 'number':
+            return typeof v === 'number';
+        case 'string':
+            return typeof v === 'string';
+        case 'json':
+            return true;
+    }
+}
+//# sourceMappingURL=flag.js.map

package/dist/flags/flag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flag.js","sourceRoot":"","sources":["../../src/flags/flag.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,wBAAwB;AACxB,EAAE;AACF,0BAA0B;AAC1B,+CAA+C;AAC/C,qEAAqE;AACrE,0EAA0E;AAC1E,sEAAsE;AACtE,wEAAwE;AACxE,EAAE;AACF,yEAAyE;AACzE,yEAAyE;AACzE,mDAAmD;AAEnD,OAAO,EACL,YAAY,GAKb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,yBAAyB,GAE1B,MAAM,0BAA0B,CAAC;AAuHlC,MAAM,OAAO,WAAW;IACd,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IACtC,OAAO,GAAgB,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IAC1C,KAAK,GAAqB,EAAE,CAAC;IAC7B,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;IAC3C,iFAAiF;IACzE,qBAAqB,GAAG,IAAI,GAAG,EAAU,CAAC;IAC1C,qBAAqB,GAAG,IAAI,GAAG,EAAiC,CAAC;IACjE,IAAI,GAAoB,UAAU,CAAC;IACnC,qBAAqB,CAAU;IAC/B,qBAAqB,GAAG,IAAI,GAAG,EAAU,CAAC;IAClD,mFAAmF;IAC3E,aAAa,CAAyB;IAC9C;;;;;OAKG;IACc,QAAQ,GAA8B,IAAI,yBAAyB,EAAE,CAAC;IAEvF,YAAY,UAA6E,EAAE;QACzF,IAAI,OAAO,CAAC,IAAI;YAAE,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QAC3C,IAAI,OAAO,CAAC,aAAa;YAAE,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IACxE,CAAC;IAED;;;;;;OAMG;IACH,yBAAyB,CAAC,QAA2B;QACnD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED,6EAA6E;IAC7E,2BAA2B,CAAC,IAAY;QACtC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACH,4BAA4B;QAC1B,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;;OAKG;IACH,gBAAgB,CAAC,QAA2C;QAC1D,IAAI,CAAC,aAAa,GAAG,QAAQ,CAAC;IAChC,CAAC;IAED,oCAAoC;IACpC,OAAO;QACL,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;;;;OAKG;IACH,mBAAmB,CAAC,EAAU;QAC5B,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACtD,IAAI,CAAC,qBAAqB,GAAG,EAAE,CAAC;IAClC,CAAC;IAED,yEAAyE;IACzE,mBAAmB;QACjB,OAAO,IAAI,CAAC,qBAAqB,CAAC;IACpC,CAAC;IAED,yCAAyC;IACzC,UAAU,CAAC,GAAgB,EAAE,KAAK,GAAG,KAAK;QACxC,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC,OAAO,GAAG;gBACb,QAAQ,EAAE,GAAG,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ;gBAC/C,UAAU,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,GAAG,CAAC,UAAU,EAAE;aAC9D,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC;QACrB,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,UAAU;QACR,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;IACzF,CAAC;IAED,6EAA6E;IAC7E,OAAO,CAAC,KAAmB;QACzB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,8DAA8D;IAC9D,MAAM,CAAC,IAAgB;QACrB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,oCAAoC;IACpC,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,6DAA6D;IAC7D,QAAQ,CAAC,KAAuB;QAC9B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED;;;;;;;OAOG;IACH,IAAI,CAAI,GAAW,EAAE,YAAe,EAAE,OAA8B;QAClE,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,YAAY,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC;QAE7C,yEAAyE;QACzE,2DAA2D;QAC3D,6EAA6E;QAC7E,yEAAyE;QACzE,iEAAiE;QACjE,MAAM,aAAa,GACjB,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QAErE,IAAI,YAAyB,CAAC;QAC9B,IAAI,CAAC,OAAO,IAAI,CAAC,aAAa,EAAE,CAAC;YAC/B,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,YAAY,GAAG;gBACb,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ;gBACpD,UAAU,EAAE;oBACV,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC;oBACxB,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU;oBAC1B,GAAG,CAAC,OAAO,EAAE,UAAU,IAAI,EAAE,CAAC;iBAC/B;aACF,CAAC;QACJ,CAAC;QAED,sEAAsE;QACtE,qEAAqE;QACrE,wEAAwE;QACxE,0CAA0C;QAC1C,IAAI,OAAO,EAAE,UAAU,EAAE,CAAC;YACxB,KAAK,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;gBACpE,IAAI,CAAC,OAAO;oBAAE,SAAS;gBACvB,MAAM,QAAQ,GAAG,GAAG,OAAO,KAAK,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC9D,IAAI,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,QAAQ,CAAC;oBAAE,SAAS;gBACvD,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACzC,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CACjB,IAAI,CAAC,KAAK,CAAC,mBAAmB,EAAE,CAAC;oBAC/B,GAAG,EAAE,OAAO;oBACZ,WAAW,EAAE,OAAO;oBACpB,YAAY,EAAE,SAAS,CAAC,OAAO,CAAC;oBAChC,SAAS,EAAE,GAAG;iBACf,CAAC,CACH,CAAC;YACJ,CAAC;QACH,CAAC;QAED,yEAAyE;QACzE,wEAAwE;QACxE,4DAA4D;QAC5D,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,YAAY,CAAC,QAAQ,IAAI,MAAM,EAAE,KAAK,KAAK,cAAc,EAAE,CAAC;YAC1F,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzC,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACpC,IAAI,CAAC;oBACH,sCAAsC;oBACrC,UAAkB,CAAC,OAAO,EAAE,IAAI,EAAE,CACjC,kBAAkB,GAAG,oEAAoE;wBACvF,qFAAqF,CACxF,CAAC;gBACJ,CAAC;gBAAC,MAAM,CAAC;oBACP,wBAAwB;gBAC1B,CAAC;YACH,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;QAChD,CAAC;QAED,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,iEAAiE;YACjE,qEAAqE;YACrE,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAC7B,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CACjB,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;oBACtB,IAAI,EAAE,GAAG;oBACT,YAAY;oBACZ,YAAY;oBACZ,SAAS,EAAE,GAAG;iBACf,CAAC,CACH,CAAC;YACJ,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;QAChD,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACzD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAE,MAAM,CAAC,KAAW,CAAC;QAE9E,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CACjB,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YAClB,IAAI,EAAE,GAAG;YACT,KAAK;YACL,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,QAAQ,EAAE,YAAY,CAAC,QAAQ;YAC/B,SAAS,EAAE,GAAG;SACf,CAAC,CACH,CAAC;QAEF,sEAAsE;QACtE,wEAAwE;QACxE,+DAA+D;QAC/D,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,yBAAyB,EAAE,CAAC,CAAC,CAAC,CAAC;QAChF,CAAC;QAED,oEAAoE;QACpE,oEAAoE;QACpE,sEAAsE;QACtE,4DAA4D;QAC5D,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,YAAY,CAAC,EAAE,CAAC;YACtC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;QAChD,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC;IAC3C,CAAC;IAED;;OAEG;IACK,cAAc,CAAC,MAAkB,EAAE,GAAgB;QACzD,QAAQ,MAAM,CAAC,KAAK,EAAE,CAAC;YACrB,KAAK,KAAK;gBACR,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC;YAChG,KAAK,IAAI;gBACP,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC;YAC7F,KAAK,cAAc,CAAC,CAAC,CAAC;gBACpB,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;oBACjB,mEAAmE;oBACnE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC;gBAC/F,CAAC;gBACD,OAAO,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACpD,CAAC;YACD;gBACE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC;QAClG,CAAC;IACH,CAAC;IAED,4DAA4D;IAC5D,SAAS;QACP,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,0CAA0C;IAC1C,UAAU;QACR,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;IAED;;;;;;;OAOG;IACH,iBAAiB,CAAC,YAAmD;QACnE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;YACxD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAC5D,IAAI,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI;gBAAE,SAAS,CAAC,wBAAwB;YACrF,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC3C,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CACjB,IAAI,CAAC,KAAK,CAAC,sBAAsB,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CACpE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,2FAA2F;IAC3F,wBAAwB;QACtB,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,qBAAqB,CAAC,OAAO,EAAE,CAAC,CAAC;IAClE,CAAC;IAEO,QAAQ,CAAC,EAAc;QAC7B,IAAI,CAAC;YACH,EAAE,EAAE,CAAC;QACP,CAAC;QAAC,MAAM,CAAC;YACP,qDAAqD;QACvD,CAAC;IACH,CAAC;CACF;AAED,+EAA+E;AAE/E,SAAS,SAAS,CAAC,CAAU;IAC3B,IAAI,OAAO,CAAC,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC7C,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC3C,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC3C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;kFACkF;AAClF,SAAS,kBAAkB,CAAC,CAAU;IACpC,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACrC,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC;IAC/B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAC/F,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,iBAAiB,CAAC;IAC3B,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,CAAU,EAAE,QAAuB;IACtD,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAChD,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,SAAS;YACZ,OAAO,OAAO,CAAC,KAAK,SAAS,CAAC;QAChC,KAAK,QAAQ;YACX,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC;QAC/B,KAAK,QAAQ;YACX,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC;QAC/B,KAAK,MAAM;YACT,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC"}

package/dist/flags/identity.d.ts

@@ -0,0 +1,77 @@
+import type { BridgeFlags } from './flag.js';
+/** How aggressively the anon ID is persisted. */
+export type AnonymousTrackingMode = 'persistent' | 'session' | 'none';
+/**
+ * Pluggable storage for the anonymous identity. Framework SDKs implement
+ * this against the right platform API.
+ */
+export interface IdentityStorage {
+    /** Persistence flavor — informational only; storage choice itself enforces it. */
+    readonly mode: AnonymousTrackingMode;
+    /** Read the stored anon ID, or undefined if not set. */
+    read(): string | undefined;
+    /** Write the anon ID. */
+    write(id: string): void;
+    /** Drop the anon ID (e.g. on logout). */
+    clear(): void;
+}
+/** In-memory storage. Used for SSR, tests, or when `tracking: 'none'`. */
+export declare class MemoryIdentityStorage implements IdentityStorage {
+    readonly mode: AnonymousTrackingMode;
+    private value;
+    constructor(mode?: AnonymousTrackingMode);
+    read(): string | undefined;
+    write(id: string): void;
+    clear(): void;
+}
+/** RFC4122-shaped UUID v4. Uses `crypto.randomUUID` when available, falls back to Math.random. */
+export declare function generateAnonymousId(): string;
+/**
+ * Identity manager bundled with a `BridgeFlags` instance. Created via the
+ * factory below — framework SDKs call `attachIdentity(bridge, storage)`
+ * during bootstrap so anonymous ID auto-populates the eval context.
+ */
+export declare class BridgeIdentity {
+    private readonly bridge;
+    private readonly storage;
+    /** Fires when the identity transitions from anonymous → known (TBP-169). */
+    private onIdentifyHook?;
+    /** True once `identify()` has been called (or a non-anonymous identity was loaded). */
+    private knownUserId?;
+    constructor(bridge: BridgeFlags, storage: IdentityStorage);
+    /** Read the current anonymous ID, generating + persisting on first call. */
+    ensureAnonymousId(): string;
+    /**
+     * Push the anonymous ID into the BridgeFlags global eval context. Idempotent.
+     * No-op if a known userId is already set.
+     */
+    hydrateAnonymous(): string;
+    /**
+     * Promote the SDK from anonymous to known. Updates the global identity in
+     * `BridgeFlags` and fires the `onIdentify` hook so the server can link
+     * anon-id telemetry to the known user's history.
+     */
+    identify(userId: string): void;
+    /**
+     * Drop the known identity and revert to anonymous. Used on logout. The
+     * anonymous ID itself is preserved unless `dropAnonymous` is also passed.
+     */
+    logout(options?: {
+        dropAnonymous?: boolean;
+    }): void;
+    /** Register a one-time hook fired on identify(). Used by the SDK telemetry batcher. */
+    setOnIdentify(hook: (args: {
+        anonymousId?: string;
+        userId: string;
+    }) => void): void;
+    /** True when `identify()` has set a known user. */
+    isKnown(): boolean;
+    /** Read the current effective identity (known userId or anonymous ID). */
+    current(): string | undefined;
+}
+/**
+ * Factory: attach an anonymous-aware identity manager to a `BridgeFlags`
+ * instance. Pass a storage implementation appropriate for the platform.
+ */
+export declare function attachIdentity(bridge: BridgeFlags, storage: IdentityStorage): BridgeIdentity;
+//# sourceMappingURL=identity.d.ts.map

package/dist/flags/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/flags/identity.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,iDAAiD;AACjD,MAAM,MAAM,qBAAqB,GAAG,YAAY,GAAG,SAAS,GAAG,MAAM,CAAC;AAEtE;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,wDAAwD;IACxD,IAAI,IAAI,MAAM,GAAG,SAAS,CAAC;IAC3B,yBAAyB;IACzB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yCAAyC;IACzC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,0EAA0E;AAC1E,qBAAa,qBAAsB,YAAW,eAAe;IAC3D,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,OAAO,CAAC,KAAK,CAAqB;gBAEtB,IAAI,GAAE,qBAA8B;IAIhD,IAAI,IAAI,MAAM,GAAG,SAAS;IAG1B,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAGvB,KAAK,IAAI,IAAI;CAGd;AAED,kGAAkG;AAClG,wBAAgB,mBAAmB,IAAI,MAAM,CAS5C;AAED;;;;GAIG;AACH,qBAAa,cAAc;IAOvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B,4EAA4E;IAC5E,OAAO,CAAC,cAAc,CAAC,CAA2D;IAClF,uFAAuF;IACvF,OAAO,CAAC,WAAW,CAAC,CAAS;gBAGV,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,eAAe;IAG3C,4EAA4E;IAC5E,iBAAiB,IAAI,MAAM;IAQ3B;;;OAGG;IACH,gBAAgB,IAAI,MAAM;IAO1B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAc9B;;;OAGG;IACH,MAAM,CAAC,OAAO,GAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,IAAI;IAMvD,uFAAuF;IACvF,aAAa,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI;IAInF,mDAAmD;IACnD,OAAO,IAAI,OAAO;IAIlB,0EAA0E;IAC1E,OAAO,IAAI,MAAM,GAAG,SAAS;CAI9B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,eAAe,GAAG,cAAc,CAK5F"}