@nebulr-group/bridge-svelte 0.3.2 → 0.4.0-beta.0

package/dist/core/use-bridge.js

@@ -0,0 +1,46 @@
+/**
+ * Phase 4 (TBP-288/320) — `useBridge()` Svelte context hook.
+ *
+ * Default behavior: returns the module-level singleton `bridge` (from
+ * `bridge.ts`). Works from any context — components, regular .ts modules,
+ * tests — because the singleton is always available.
+ *
+ * Component-scoped override: a parent `<BridgeProvider>` may set a different
+ * bridge instance into Svelte context. Useful for SSR, multi-tenant test
+ * harnesses, or storybook fixtures that need isolated bridge state.
+ *
+ * Naming collision with auth-core's `useBridge` (billing/quota factory):
+ * bridge-svelte's `useBridge()` SHADOWS the auth-core import. Consumers
+ * who explicitly want the auth-core factory should import it as
+ * `useBillingBridge` (alias added in auth-core re-exports in TBP-324).
+ */
+import { getContext, hasContext, setContext } from 'svelte';
+import { bridge as _singleton } from './bridge.js';
+const BRIDGE_CONTEXT_KEY = Symbol('bridge-svelte:bridge');
+/**
+ * Set a bridge instance into Svelte context. Called by `<BridgeProvider>`
+ * during component initialization. Calling this outside a component
+ * initialization phase will throw (Svelte's `setContext` contract).
+ */
+export function setBridgeContext(b) {
+    setContext(BRIDGE_CONTEXT_KEY, b);
+}
+/**
+ * Return the bridge surface for the current component scope, falling back
+ * to the module-level singleton outside components (or when no provider
+ * has been mounted). Safe to call from any code path.
+ */
+export function useBridge() {
+    try {
+        if (hasContext(BRIDGE_CONTEXT_KEY)) {
+            const fromCtx = getContext(BRIDGE_CONTEXT_KEY);
+            if (fromCtx)
+                return fromCtx;
+        }
+    }
+    catch {
+        // `getContext`/`hasContext` throw outside a component init phase —
+        // fall through to the singleton, which is the right answer there.
+    }
+    return _singleton;
+}

package/dist/core/use-bridge.test.d.ts

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

package/dist/core/use-bridge.test.js

@@ -0,0 +1,24 @@
+// Phase 4 (TBP-288/320) — useBridge hook tests.
+//
+// Verifies:
+//   1. Outside a component (regular .ts module / vitest test), useBridge()
+//      returns the singleton without throwing.
+//   2. setBridgeContext outside a component scope throws (Svelte contract);
+//      useBridge() catches and falls back to the singleton.
+//   3. Provided override via Svelte context wins over the singleton —
+//      covered by integration in BridgeProvider.test.ts where a real
+//      component mount sets context.
+import { describe, expect, it } from 'vitest';
+import { useBridge } from './use-bridge.js';
+import { bridge as singleton } from './bridge.js';
+describe('useBridge() — outside component scope (Phase 4, TBP-320)', () => {
+    it('returns the singleton when called from regular .ts code', () => {
+        expect(useBridge()).toBe(singleton);
+    });
+    it('does not throw even when no Svelte context is available', () => {
+        expect(() => useBridge()).not.toThrow();
+    });
+    it('returns a stable reference across calls', () => {
+        expect(useBridge()).toBe(useBridge());
+    });
+});

package/dist/flags/FeatureFlag.svelte

@@ -0,0 +1,57 @@
+<!--
+  bridge-svelte/flags — declarative component for Bridge feature flags.
+
+  Two snippets:
+    - `children` — rendered when Bridge's rule passed (flag is on for this user)
+    - `fallback` — rendered when the flag is off or no rule matched
+
+  Both snippets receive the Bridge-decided value so you can use it directly.
+
+  Usage:
+    <FeatureFlag key="new-dashboard" defaultValue={false}>
+      {#snippet children()}<NewDashboard />{/snippet}
+    </FeatureFlag>
+
+    <FeatureFlag key="ui-theme" defaultValue="light-mode">
+      {#snippet children(value)}<App theme={value} />{/snippet}
+      {#snippet fallback(value)}<App theme={value} />{/snippet}
+    </FeatureFlag>
+-->
+<script lang="ts" generics="T = boolean">
+  import type { Snippet } from 'svelte';
+  import type { EvalContext } from '@nebulr-group/bridge-auth-core';
+  import { evaluateFlag } from './registry.js';
+  import { _flagVersionsRune } from './flag.svelte.js';
+
+  let {
+    key,
+    defaultValue,
+    context,
+    children,
+    fallback,
+  }: {
+    key: string;
+    defaultValue: T;
+    /**
+     * Optional per-call EvalContext. Use when a flag's rule targets
+     * dev-supplied attributes (e.g. `{ attributes: { plan } }`). Per-call
+     * attributes win on key collision over Bridge-managed providers.
+     */
+    context?: Partial<EvalContext>;
+    children?: Snippet<[T]>;
+    fallback?: Snippet<[T]>;
+  } = $props();
+
+  const result = $derived.by(() => {
+    // Reactive dependency: read the per-key version so the derived re-runs
+    // whenever this flag changes in the cache.
+    _flagVersionsRune().get(key);
+    return evaluateFlag<T>(key, defaultValue, context);
+  });
+</script>
+
+{#if result.passed}
+  {#if children}{@render children(result.value)}{/if}
+{:else if fallback}
+  {@render fallback(result.value)}
+{/if}

package/dist/flags/FeatureFlag.svelte.d.ts

@@ -0,0 +1,37 @@
+import type { Snippet } from 'svelte';
+import type { EvalContext } from '@nebulr-group/bridge-auth-core';
+declare function $$render<T = boolean>(): {
+    props: {
+        key: string;
+        defaultValue: T;
+        /**
+         * Optional per-call EvalContext. Use when a flag's rule targets
+         * dev-supplied attributes (e.g. `{ attributes: { plan } }`). Per-call
+         * attributes win on key collision over Bridge-managed providers.
+         */
+        context?: Partial<EvalContext>;
+        children?: Snippet<[T]>;
+        fallback?: Snippet<[T]>;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T = boolean> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T = boolean>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T = boolean>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const FeatureFlag: $$IsomorphicComponent;
+type FeatureFlag<T = boolean> = InstanceType<typeof FeatureFlag<T>>;
+export default FeatureFlag;

package/dist/flags/bootstrap.d.ts

@@ -0,0 +1,72 @@
+import { BridgeFlags, type BridgeFlagsMode, type BridgeFlagsHooks, type BridgeIdentity, type IdentityStorage, type AnonymousTrackingMode, TelemetryBatcher, type TelemetryBatcherConfig, AuthAttributeProvider, BillingAttributeProvider } from '@nebulr-group/bridge-auth-core';
+/** A storage implementation that uses `localStorage` (persistent) or `sessionStorage` (per-tab). */
+export declare class BrowserIdentityStorage implements IdentityStorage {
+    readonly mode: AnonymousTrackingMode;
+    private readonly storage;
+    private readonly key;
+    constructor(mode: 'persistent' | 'session', key?: string);
+    read(): string | undefined;
+    write(id: string): void;
+    clear(): void;
+}
+export interface CreateBridgeFlagsConfig {
+    /**
+     * Bridge API base URL. Optional — defaults to the value stored by
+     * `bridgeConfig.initConfig({...})` (which itself defaults to
+     * `https://api.thebridge.dev`). Bridge developers override this for
+     * local / stage envs; product consumers never set it.
+     */
+    apiBaseUrl?: string;
+    /**
+     * JWT-shaped workspace API key — sent as `x-api-key`. Optional — defaults
+     * to `appId` from `bridgeConfig.initConfig({...})`. The two values are the
+     * same thing (the workspace identity) under different names; the auth
+     * config call is the single source of truth.
+     */
+    apiKey?: string;
+    /** Frontend (default) or backend. Use 'backend' in SSR-load() functions. */
+    mode?: BridgeFlagsMode;
+    /** Anonymous identity options. Persistent (localStorage) by default in browsers. */
+    identity?: {
+        /** 'persistent' (localStorage), 'session' (sessionStorage), 'none' (memory only). Default 'persistent'. */
+        tracking?: AnonymousTrackingMode;
+        /** Override storage entirely (e.g. cookie-backed). */
+        storage?: IdentityStorage;
+        /** localStorage key when using the default browser storage. Default 'bridge.anon_id'. */
+        storageKey?: string;
+    };
+    /** Telemetry opts — set `enabled: false` to skip. */
+    telemetry?: Partial<Omit<TelemetryBatcherConfig, 'apiBaseUrl' | 'apiKey'>>;
+    /**
+     * If false, this bootstrap won't register itself as the global Svelte
+     * instance used by `useFlag` / `<FeatureFlag>`. Useful when multiple
+     * BridgeFlags are needed in the same app. Defaults to true.
+     */
+    registerGlobal?: boolean;
+    /**
+     * Optional extra hooks the consumer wants chained on top of the
+     * built-in (telemetry + reactivity) hooks. Errors in user hooks are
+     * caught — they will never break flag eval.
+     */
+    hooks?: BridgeFlagsHooks;
+}
+export interface BridgeFlagsBundle {
+    bridge: BridgeFlags;
+    identity: BridgeIdentity;
+    telemetry: TelemetryBatcher;
+    authAttributeProvider: AuthAttributeProvider;
+    billingAttributeProvider: BillingAttributeProvider;
+    /** Stop telemetry + unsubscribe from auth events. Idempotent. */
+    stop: () => Promise<void>;
+}
+/**
+ * Build a fully wired BridgeFlags bundle. Bootstraps the flag-specific
+ * runtime ON TOP OF the core Bridge runtime — meaning `startBridgeRuntime()`
+ * must already have run (typically from `<BridgeBootstrap />`). The shared
+ * RealtimeClient is read via `getBridgeRealtime()` and re-used; no second
+ * websocket is opened.
+ *
+ * The returned instance is also registered as the global instance used by
+ * `useFlag` and `<FeatureFlag>` unless `registerGlobal` is explicitly false.
+ */
+export declare function createBridgeFlags(config?: CreateBridgeFlagsConfig): BridgeFlagsBundle;

package/dist/flags/bootstrap.js

@@ -0,0 +1,323 @@
+// bridge-svelte/flags — bootstrap (TBP-200, hoisted in TBP-Live-Channel-Unification)
+//
+// Auth-free entry point for Feature Flags 2.0. After the runtime hoist, this
+// module is ONLY about flag-specific wiring: the BridgeFlags eval cache,
+// attribute providers, the telemetry batcher, hydrate, Svelte reactivity, and
+// the auth-token subscription that drives flag eval context. The realtime
+// client, billing-store binding, session.snapshot fanout, billing-family
+// event dispatch, and token-driven channel scoping all live in
+// `core/bridge-runtime.ts` and are mounted by `<BridgeBootstrap />`.
+//
+// Consumers don't call this directly anymore — `<BridgeBootstrap />` does it
+// for them when `@nebulr-group/bridge-svelte/flags` is on the dependency
+// graph. `createBridgeFlags(...)` stays exported as an advanced API for tests
+// + standalone-SDK use, but its `apiBaseUrl` / `apiKey` args are now optional
+// and default to the values stored by `bridgeConfig.initConfig({...})`.
+import { BridgeFlags, attachIdentity, MemoryIdentityStorage, TelemetryBatcher, AuthAttributeProvider, BillingAttributeProvider, useBridge, } from '@nebulr-group/bridge-auth-core';
+import { setBridgeFlagsInstance, notifyFlagChanged, notifyAllFlagsChanged } from './registry.js';
+import { tokenStore, getBridgeAuth } from '../core/bridge-instance.js';
+import { _getDevAttributeProvider } from '../core/bridge.js';
+import { getBridgeRealtime, onBridgeRealtimeOpen, } from '../core/bridge-runtime.js';
+import { getConfig } from '../client/stores/config.store.js';
+/** A storage implementation that uses `localStorage` (persistent) or `sessionStorage` (per-tab). */
+export class BrowserIdentityStorage {
+    mode;
+    storage;
+    key;
+    constructor(mode, key = 'bridge.anon_id') {
+        this.mode = mode;
+        this.key = key;
+        if (typeof globalThis === 'undefined' || !globalThis.window) {
+            throw new Error('BrowserIdentityStorage requires a window — use MemoryIdentityStorage on the server');
+        }
+        const w = globalThis.window;
+        this.storage = mode === 'persistent' ? w.localStorage : w.sessionStorage;
+    }
+    read() {
+        try {
+            return this.storage.getItem(this.key) ?? undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    write(id) {
+        try {
+            this.storage.setItem(this.key, id);
+        }
+        catch {
+            // Quota / privacy mode — silently degrade.
+        }
+    }
+    clear() {
+        try {
+            this.storage.removeItem(this.key);
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+function pickIdentityStorage(cfg) {
+    if (cfg?.storage)
+        return cfg.storage;
+    const tracking = cfg?.tracking ?? 'persistent';
+    if (tracking === 'none')
+        return new MemoryIdentityStorage('none');
+    // SSR path — no `window`. Fall back to memory; the browser-side bootstrap
+    // (re-running with `window` present) will install the real storage.
+    if (typeof globalThis === 'undefined' || !globalThis.window) {
+        return new MemoryIdentityStorage(tracking);
+    }
+    return new BrowserIdentityStorage(tracking === 'session' ? 'session' : 'persistent', cfg?.storageKey);
+}
+/** Decode a JWT payload without signature verification (client-side context only). */
+function decodeJwtPayload(token) {
+    try {
+        const part = token.split('.')[1];
+        if (!part)
+            return null;
+        const json = atob(part.replace(/-/g, '+').replace(/_/g, '/'));
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build a fully wired BridgeFlags bundle. Bootstraps the flag-specific
+ * runtime ON TOP OF the core Bridge runtime — meaning `startBridgeRuntime()`
+ * must already have run (typically from `<BridgeBootstrap />`). The shared
+ * RealtimeClient is read via `getBridgeRealtime()` and re-used; no second
+ * websocket is opened.
+ *
+ * The returned instance is also registered as the global instance used by
+ * `useFlag` and `<FeatureFlag>` unless `registerGlobal` is explicitly false.
+ */
+export function createBridgeFlags(config = {}) {
+    // Resolve config from the auth config store when the consumer doesn't pass
+    // explicit values. `bridgeConfig.initConfig({...})` is the single source of
+    // truth — consumers never plumb apiBaseUrl / apiKey through twice.
+    let resolvedApiBaseUrl = config.apiBaseUrl;
+    let resolvedApiKey = config.apiKey;
+    try {
+        const stored = getConfig();
+        resolvedApiBaseUrl ??= stored.apiBaseUrl ?? 'https://api.thebridge.dev';
+        resolvedApiKey ??= stored.appId;
+    }
+    catch {
+        // No initConfig call — only OK when the caller passed everything.
+    }
+    if (!resolvedApiBaseUrl)
+        resolvedApiBaseUrl = 'https://api.thebridge.dev';
+    if (!resolvedApiKey) {
+        throw new Error('createBridgeFlags: apiKey/appId could not be resolved. Call bridgeConfig.initConfig({ appId }) first or pass apiKey explicitly.');
+    }
+    const bridge = new BridgeFlags({ mode: config.mode });
+    // Billing 2.0 US-11 — self-report `bridge.flag_evaluations` to the usage
+    // pipeline. Best-effort: in SSR test harnesses without BridgeAuth, skip.
+    try {
+        const auth = getBridgeAuth();
+        bridge.setUsageReporter(auth.usage);
+    }
+    catch {
+        // No BridgeAuth instance yet — flags can still operate without usage reporting.
+    }
+    // US-11 — wire the QuotaStore HTTP options so `useBridge().quota(metric)`
+    // can hydrate on first access. Core's tokenStore subscription refreshes the
+    // accessToken on login/logout/refresh; here we snapshot the initial value.
+    try {
+        const auth = getBridgeAuth();
+        useBridge().quotas.configure({
+            apiBaseUrl: resolvedApiBaseUrl,
+            appId: auth.getApiContext().appId,
+            accessToken: auth.getApiContext().accessToken,
+        });
+    }
+    catch {
+        // No BridgeAuth — quota hydration falls back to live pushes only.
+    }
+    const identity = attachIdentity(bridge, pickIdentityStorage(config.identity));
+    // Phase 1 / US-13 (TBP-295) — current decoded JWT claims. The
+    // AuthAttributeProvider's `getClaims()` returns this on every flag eval so
+    // `user.role`, `user.email`, `tenant.id`, `tenant.plan`, `privileges` flow
+    // through the registry instead of via direct `bridge.setContext()` calls.
+    let _currentClaims;
+    // Patch upsert/remove on the bridge so realtime mutations re-notify the
+    // Svelte reactivity layer. We use prototype-style monkey-patching on the
+    // instance so we don't touch auth-core itself. This is intentionally a
+    // narrow seam — the public API surface (upsert / remove / hydrate) is
+    // explicitly the cache write path.
+    const originalUpsert = bridge.upsert.bind(bridge);
+    bridge.upsert = (flag) => {
+        originalUpsert(flag);
+        notifyFlagChanged(flag.key, _BUMP_SENTINEL);
+    };
+    const originalRemove = bridge.remove.bind(bridge);
+    bridge.remove = (key) => {
+        originalRemove(key);
+        notifyFlagChanged(key, _BUMP_SENTINEL);
+    };
+    const originalHydrate = bridge.hydrate.bind(bridge);
+    bridge.hydrate = (flags) => {
+        originalHydrate(flags);
+        notifyAllFlagsChanged();
+    };
+    // Attach the flag cache to the SHARED RealtimeClient owned by core. Calling
+    // attach() on a started client is safe — the realtime client tolerates
+    // post-start cache binding (it just registers an upsert/remove dispatcher).
+    // If core hasn't started yet (e.g. standalone-SDK harness), skip the attach
+    // — the consumer can wire it manually on `getBridgeRealtime()` once started.
+    const realtime = getBridgeRealtime();
+    if (realtime) {
+        realtime.attach(bridge);
+    }
+    // Phase 1 / US-13 (TBP-296) — bridge-managed AttributeProviders. Both are
+    // auto-registered below; consumers never wire these by hand.
+    const billingAttributeProvider = new BillingAttributeProvider();
+    billingAttributeProvider.bindStores({
+        subscription: useBridge().subscription,
+        quotas: useBridge().quotas,
+        entitlements: useBridge().entitlementsStore,
+    });
+    const authAttributeProvider = new AuthAttributeProvider({
+        getClaims: () => _currentClaims,
+    });
+    bridge.registerAttributeProvider(authAttributeProvider);
+    bridge.registerAttributeProvider(billingAttributeProvider);
+    // Phase 5 (TBP-328) — register the dev-managed provider LAST so its
+    // set/bind/bindMany keys win on collision with framework providers.
+    bridge.registerAttributeProvider(_getDevAttributeProvider());
+    const telemetry = new TelemetryBatcher({
+        apiBaseUrl: resolvedApiBaseUrl,
+        apiKey: resolvedApiKey,
+        ...config.telemetry,
+    });
+    // Compose hooks: telemetry (baseline) + reactivity (eval-driven bumps) +
+    // user-supplied.
+    attachWithCompositeHooks(bridge, telemetry, config.hooks ?? {});
+    // Hydrate the flag cache so the first `bridge.flag()` call returns the right
+    // value instead of the developer-supplied default. Best-effort.
+    const hydrateFlagsCache = async () => {
+        try {
+            const res = await fetch(`${resolvedApiBaseUrl.replace(/\/+$/, '')}/admin/flags-internal/flags-cache/${encodeURIComponent(resolvedApiKey)}`);
+            if (!res.ok)
+                return;
+            const flags = (await res.json());
+            if (Array.isArray(flags) && flags.length > 0) {
+                bridge.hydrate(flags);
+            }
+        }
+        catch {
+            // Hydration is best-effort.
+        }
+    };
+    // Re-hydrate every time the shared realtime client (re)opens. Covers
+    // initial-hydrate-failed and flag-mutations-during-offline gaps.
+    const unsubscribeOpen = onBridgeRealtimeOpen(() => {
+        void hydrateFlagsCache();
+    });
+    // Initial hydrate fires here too — covers the case where realtime is
+    // disabled and onOpen never fires.
+    void hydrateFlagsCache();
+    if (config.registerGlobal !== false) {
+        setBridgeFlagsInstance(bridge);
+    }
+    // Flag-context concerns on token change: setContext identity + claims +
+    // re-eval. Core handles channel scoping + quotas + reauthorize separately;
+    // two subscribers is fine (idempotent and cheap).
+    const unsubscribeAuth = tokenStore.subscribe((tokens) => {
+        if (!tokens?.accessToken) {
+            _currentClaims = undefined;
+            bridge.setContext({ identity: undefined, attributes: {} });
+            notifyAllFlagsChanged();
+            return;
+        }
+        const claims = decodeJwtPayload(tokens.accessToken);
+        if (!claims)
+            return;
+        _currentClaims = claims;
+        bridge.setContext({
+            identity: typeof claims.sub === 'string' ? claims.sub : undefined,
+            attributes: {},
+        });
+        notifyAllFlagsChanged();
+    });
+    const stop = async () => {
+        unsubscribeAuth();
+        unsubscribeOpen();
+        await telemetry.stop();
+    };
+    return {
+        bridge,
+        identity,
+        telemetry,
+        authAttributeProvider,
+        billingAttributeProvider,
+        stop,
+    };
+}
+// ── helpers ─────────────────────────────────────────────────────────────────
+const _BUMP_SENTINEL = Symbol('bridge.flags.bump');
+/**
+ * Telemetry's `attach` calls `bridge.setHooks` and overwrites whatever was
+ * there. We capture the batcher's onEval/onDiscover/onAttributeDeclaration
+ * by snooping via a one-shot setHooks override, then re-install a composite
+ * that calls them + our reactivity bump + the user's hooks.
+ */
+function attachWithCompositeHooks(bridge, telemetry, userHooks) {
+    let captured = {};
+    const originalSetHooks = bridge.setHooks.bind(bridge);
+    bridge.setHooks = (hooks) => {
+        captured = hooks ?? {};
+    };
+    try {
+        telemetry.attach(bridge);
+    }
+    finally {
+        bridge.setHooks = originalSetHooks;
+    }
+    bridge.setHooks({
+        onEval: (ev) => {
+            try {
+                captured.onEval?.(ev);
+            }
+            catch { /* telemetry hook errors swallowed */ }
+            try {
+                userHooks.onEval?.(ev);
+            }
+            catch { /* user hook errors swallowed */ }
+            notifyFlagChanged(ev.flag, ev.value);
+        },
+        onDiscover: (ev) => {
+            try {
+                captured.onDiscover?.(ev);
+            }
+            catch { /* ignore */ }
+            try {
+                userHooks.onDiscover?.(ev);
+            }
+            catch { /* ignore */ }
+        },
+        onAttributeDeclaration: (decl) => {
+            try {
+                captured.onAttributeDeclaration?.(decl);
+            }
+            catch { /* ignore */ }
+            try {
+                userHooks.onAttributeDeclaration?.(decl);
+            }
+            catch { /* ignore */ }
+        },
+        onAttributeObserved: (obs) => {
+            try {
+                captured.onAttributeObserved?.(obs);
+            }
+            catch { /* ignore */ }
+            try {
+                userHooks.onAttributeObserved?.(obs);
+            }
+            catch { /* ignore */ }
+        },
+    });
+}

package/dist/flags/bootstrap.test.d.ts

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