zubbl-sdk 1.1.16 → 1.1.19

package/dist/zubbl-sdk.umd.js

@@ -1,8 +1,8 @@
 (function (global, factory) {
     typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('crypto')) :
     typeof define === 'function' && define.amd ? define(['exports', 'crypto'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.ZubblSdk = {}, global.crypto));
-})(this, (function (exports, crypto) { 'use strict';
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.ZubblSdk = {}));
+})(this, (function (exports) { 'use strict';
 
     // src/core/config.ts
     // -----------------------------------------------------------
@@ -15,21 +15,9 @@
     const isWorker = typeof self !== "undefined" &&
         typeof self.importScripts === "function" &&
         !isNode;
-    let config = {
-        apiKey: null,
-        tenantId: null,
-        appId: null,
-        baseUrl: "https://api.zubbl.com/api",
-        injectWorkerHeaders: false,
-        workerSecret: null,
-    };
-    // -----------------------------------------------------------
-    // Browser safety check
-    // -----------------------------------------------------------
-    function assertBrowserSafety(config) {
+    function assertBrowserSafety(cfg) {
         if (isBrowser || isWorker) {
-            const key = config.apiKey ?? "";
-            // Simple rule: if the key looks like a secret (sk_ or very long)
+            const key = cfg.apiKey ?? "";
             const looksSecret = key.startsWith("sk_") || key.length > 40;
             if (looksSecret) {
                 throw new Error("[Zubbl SDK] Secret or server key detected in browser environment. " +
@@ -37,290 +25,40 @@
             }
         }
     }
-    // -----------------------------------------------------------
-    // Public API
-    // -----------------------------------------------------------
-    function init$1(partial) {
-        config = { ...config, ...partial };
-        assertBrowserSafety(config); // 🔒 check that key is safe in browser
-    }
-    function getConfig() {
-        return config;
-    }
-    // -----------------------------------------------------------
-    // Header builder (used by HTTP layer)
-    // -----------------------------------------------------------
-    function buildHeaders(extra = {}) {
-        if (!config.apiKey || !config.tenantId || !config.appId) {
-            throw new Error("[Zubbl SDK] Not initialized – call init() first.");
-        }
-        return {
-            Authorization: `Bearer ${config.apiKey}`,
-            "X-Tenant-Id": config.tenantId,
-            "X-App-Id": config.appId,
-            "Content-Type": "application/json",
-            ...extra,
+    /**
+     * Creates an isolated configuration store.
+     * Each ZubblClient instance owns its own store.
+     */
+    function createConfigStore(initial) {
+        let current = {
+            apiKey: null,
+            tenantId: null,
+            appId: null,
+            baseUrl: "https://api.zubbl.com/api",
+            injectWorkerHeaders: false,
+            workerSecret: null,
+            ...initial,
         };
-    }
-
-    // src/core/context.ts
-    // -----------------------------------------------------------
-    // Adaptive Context Engine — Geo + Stability Enrichment + Persistence
-    // -----------------------------------------------------------
-    const MAX_HISTORY = 100;
-    const CACHE_KEY = "zubbl-stability";
-    let state = loadStability() ?? {
-        routes: [],
-        geo: "unknown",
-        stability: 1.0,
-        lastGeoChange: Date.now(),
-    };
-    // -----------------------------------------------------------
-    // 💾 Persistence Helpers
-    // -----------------------------------------------------------
-    function loadStability() {
-        if (!isBrowser || typeof localStorage === "undefined")
-            return null;
-        try {
-            const raw = localStorage.getItem(CACHE_KEY);
-            if (!raw)
-                return null;
-            const parsed = JSON.parse(raw);
-            if (!parsed.geo || !parsed.stability)
-                return null;
-            return { ...parsed, routes: [] };
+        function init(partial) {
+            current = { ...current, ...partial };
+            assertBrowserSafety(current);
         }
-        catch {
-            return null;
+        function get() {
+            return current;
         }
-    }
-    function saveStability() {
-        if (!isBrowser || typeof localStorage === "undefined")
-            return;
-        try {
-            const payload = {
-                geo: state.geo,
-                stability: state.stability,
-                lastGeoChange: state.lastGeoChange,
-            };
-            localStorage.setItem(CACHE_KEY, JSON.stringify(payload));
-        }
-        catch {
-            /* ignore */
-        }
-    }
-    // -----------------------------------------------------------
-    // 🌍 Geo Detection (Node, Browser, Worker)
-    // -----------------------------------------------------------
-    function detectGeo() {
-        try {
-            if (isBrowser && typeof window !== "undefined" && window.navigator?.language) {
-                return window.navigator.language.split("-")[1] || "unknown";
-            }
-            if (isWorker && typeof self !== "undefined" && self.navigator?.language) {
-                return self.navigator.language.split("-")[1] || "unknown";
+        function buildHeaders(extra = {}) {
+            if (!current.apiKey || !current.tenantId || !current.appId) {
+                throw new Error("[Zubbl SDK] Not initialized – call init() first.");
             }
-            if (isNode && typeof process !== "undefined") {
-                const envGeo = process.env.ZUBBL_GEO || process.env.GEO;
-                if (envGeo && /^[A-Z]{2}$/i.test(envGeo))
-                    return envGeo.toUpperCase();
-                return "GB";
-            }
-            return "unknown";
-        }
-        catch (err) {
-            console.warn("[Zubbl SDK][Geo Detect] Failed:", err);
-            return "unknown";
-        }
-    }
-    // -----------------------------------------------------------
-    // 🧭 Update Geo & Stability (with persistence)
-    // -----------------------------------------------------------
-    function updateGeo(geoHint) {
-        const newGeo = geoHint || detectGeo();
-        if (newGeo !== state.geo) {
-            const now = Date.now();
-            const elapsed = (now - state.lastGeoChange) / 1000;
-            state.stability = Math.max(0.5, Math.min(1.0, elapsed / 3600));
-            state.geo = newGeo;
-            state.lastGeoChange = now;
-            saveStability();
-        }
-        else {
-            state.stability = Math.min(1.0, state.stability + 0.01);
-            saveStability();
-        }
-    }
-    // -----------------------------------------------------------
-    // 🧮 Record Context Samples
-    // -----------------------------------------------------------
-    function recordContextSample(path, method, status, latency) {
-        state.routes.push({ path, method, ts: Date.now(), status, latency });
-        if (state.routes.length > MAX_HISTORY)
-            state.routes.shift();
-        updateGeo(); // auto-refresh geo info
-    }
-    // -----------------------------------------------------------
-    // 📦 Get Adaptive Headers
-    // -----------------------------------------------------------
-    function getAdaptiveHeaders() {
-        const currentGeo = detectGeo();
-        updateGeo(currentGeo);
-        const summary = btoa(JSON.stringify({
-            env: isNode ? "node" : isBrowser ? "browser" : "worker",
-            routeCount: state.routes.length,
-            lastGeo: state.geo,
-            avgLatency: state.routes.reduce((a, b) => a + b.latency, 0) /
-                Math.max(1, state.routes.length),
-        }));
-        return {
-            "X-Zubbl-Context-Summary": summary,
-            "X-Zubbl-Geo-Stability": `${state.geo}/${state.stability.toFixed(2)}`,
-        };
-    }
-    // -----------------------------------------------------------
-    // 🌍 Initialize Geo Context Immediately
-    // -----------------------------------------------------------
-    updateGeo(process.env.ZUBBL_GEO);
-
-    // -----------------------------------------------------------
-    // 🔐 Secure Signing & Nonce Generator
-    // -----------------------------------------------------------
-    // -----------------------------------------------------------
-    // Generate UUIDv4 Nonce
-    // -----------------------------------------------------------
-    function generateNonce() {
-        return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, c => {
-            const r = (Math.random() * 16) | 0;
-            const v = c === "x" ? r : (r & 0x3) | 0x8;
-            return v.toString(16);
-        });
-    }
-    // -----------------------------------------------------------
-    // Compute SHA256 HMAC signature
-    // -----------------------------------------------------------
-    async function signPayload(payload, secret) {
-        if (isNode) {
-            // ✅ Node.js native HMAC
-            return crypto.createHmac("sha256", secret).update(payload).digest("hex");
-        }
-        // ✅ Browser / Worker using WebCrypto
-        if (typeof window !== "undefined" && window.crypto?.subtle) {
-            const key = await window.crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
-            const sig = await window.crypto.subtle.sign("HMAC", key, new TextEncoder().encode(payload));
-            return Array.from(new Uint8Array(sig))
-                .map(b => b.toString(16).padStart(2, "0"))
-                .join("");
-        }
-        throw new Error("No crypto implementation available in this environment");
-    }
-    // -----------------------------------------------------------
-    // Attach signing headers to a request
-    // -----------------------------------------------------------
-    async function attachSigningHeaders(method, url, body, secretKey) {
-        const nonce = generateNonce();
-        // Compute canonical string (deterministic)
-        const bodyHash = body
-            ? crypto.createHash("sha256").update(body).digest("hex")
-            : "";
-        const canonical = `${method.toUpperCase()}\n${url}\n${nonce}\n${bodyHash}`;
-        // ⚙️ Always include nonce even if secret is missing
-        if (!secretKey) {
-            return { "X-Zubbl-Nonce": nonce };
-        }
-        const signature = await signPayload(canonical, secretKey);
-        return {
-            "X-Zubbl-Nonce": nonce,
-            "X-Zubbl-Signature": signature,
-        };
-    }
-
-    // src/core/http.ts
-    // -----------------------------------------------------------
-    // Isomorphic HTTP transport for Node, Browser, and Workers
-    // Includes adaptive context, telemetry, signing & safety timeout
-    // -----------------------------------------------------------
-    async function httpRequest(url, options = {}) {
-        // 🔧 Default timeout lowered for SDK-12 hardening
-        const { timeoutMs = 250, ...fetchOpts } = options;
-        // ---------------------------------------------------------
-        // Polyfill fetch for Node
-        // ---------------------------------------------------------
-        let fetchImpl;
-        if (isNode) {
-            const { fetch } = await import('undici');
-            // @ts-expect-error Node native fetch lacks duplex definition in undici types
-            fetchImpl = fetch;
-        }
-        else if (isBrowser || isWorker) {
-            fetchImpl = fetch;
-        }
-        else {
-            console.warn("[Zubbl SDK][HTTP] Unsupported runtime environment");
-            return null;
-        }
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), timeoutMs);
-        const start = performance.now();
-        try {
-            const config = getConfig();
-            const bodyText = fetchOpts.body && typeof fetchOpts.body === "string"
-                ? fetchOpts.body
-                : fetchOpts.body
-                    ? JSON.stringify(fetchOpts.body)
-                    : "";
-            // ---------------------------------------------------------
-            // 🔐 Signing headers (adds X-Zubbl-Nonce and X-Zubbl-Signature)
-            // ---------------------------------------------------------
-            const signingHeaders = await attachSigningHeaders(fetchOpts.method ?? "GET", url, bodyText, config.workerSecret ?? null);
-            // ---------------------------------------------------------
-            // 🧠 Adaptive context headers
-            // ---------------------------------------------------------
-            const adaptiveHeaders = getAdaptiveHeaders();
-            // ✅ Merge headers cleanly — final order matters
-            fetchOpts.headers = {
-                ...(fetchOpts.headers || {}),
-                ...adaptiveHeaders,
-                ...signingHeaders,
+            return {
+                Authorization: `Bearer ${current.apiKey}`,
+                "X-Tenant-Id": current.tenantId,
+                "X-App-Id": current.appId,
+                "Content-Type": "application/json",
+                ...extra,
             };
-            // ---------------------------------------------------------
-            // Perform request
-            // ---------------------------------------------------------
-            const response = await fetchImpl(url, { ...fetchOpts, signal: controller.signal });
-            const latencyMs = performance.now() - start;
-            const status = response?.status ?? 0;
-            // -----------------------------------------------------
-            // Telemetry hook — record runtime discovery + metrics
-            // -----------------------------------------------------
-            await Promise.resolve().then(function () { return telemetry; }).then(({ recordRequestTelemetry, logRuntimeDiscovery }) => {
-                logRuntimeDiscovery(url);
-                recordRequestTelemetry(url, fetchOpts.method ?? "GET", status, latencyMs);
-            });
-            // -----------------------------------------------------
-            // Adaptive context sample recording
-            // -----------------------------------------------------
-            recordContextSample(url, fetchOpts.method ?? "GET", status, latencyMs);
-            // -----------------------------------------------------
-            // Error handling / Soft fail behaviour
-            // -----------------------------------------------------
-            if (!response.ok) {
-                const text = await response.text().catch(() => "");
-                console.warn(`[Zubbl SDK][HTTP] Non-OK response ${status}: ${text}`);
-                return response; // still return so host can inspect
-            }
-            return response;
-        }
-        catch (err) {
-            const latencyMs = performance.now() - start;
-            const reason = err?.name === "AbortError"
-                ? `timeout (${timeoutMs}ms)`
-                : err?.message || "unknown network error";
-            console.warn(`[Zubbl SDK][HTTP] Request failed: ${reason}`, { url, latencyMs });
-            return null; // 🧩 Never throw to host app
-        }
-        finally {
-            clearTimeout(timeout);
         }
+        return { init, get, buildHeaders };
     }
 
     // src/core/storage.ts
@@ -521,202 +259,408 @@
         };
     }
 
-    // ---------------------------------------------------------
-    // Zubbl SDK — Unified Bootstrap (Adaptive + GEO Aware)
-    // ---------------------------------------------------------
-    // ---------------------------------------------------------
-    // Initialization
-    // ---------------------------------------------------------
-    async function init({ apiKey, tenantId, appId, baseUrl = "https://api.zubbl.com/api", injectWorkerHeaders = false, workerSecret = null, }) {
-        // Initialize core configuration
-        init$1({ apiKey, tenantId, appId, baseUrl, injectWorkerHeaders, workerSecret });
-        // Prime GEO context cache
+    // src/core/context.ts
+    // -----------------------------------------------------------
+    // Adaptive Context Engine — Geo + Stability Enrichment + Persistence
+    // -----------------------------------------------------------
+    const MAX_HISTORY = 100;
+    const CACHE_KEY = "zubbl-stability";
+    let state = loadStability() ?? {
+        routes: [],
+        geo: "unknown",
+        stability: 1.0,
+        lastGeoChange: Date.now(),
+    };
+    // -----------------------------------------------------------
+    // 💾 Persistence Helpers
+    // -----------------------------------------------------------
+    function loadStability() {
+        if (!isBrowser || typeof localStorage === "undefined")
+            return null;
         try {
-            const geo = await getGeoInfo();
-            console.log(`[Zubbl SDK] 🌍 GEO detected: ${geo.country} (ASN ${geo.asn || "?"})`);
+            const raw = localStorage.getItem(CACHE_KEY);
+            if (!raw)
+                return null;
+            const parsed = JSON.parse(raw);
+            if (!parsed.geo || !parsed.stability)
+                return null;
+            return { ...parsed, routes: [] };
         }
-        catch (err) {
-            console.warn("[Zubbl SDK] GEO init failed:", err?.message);
+        catch {
+            return null;
         }
     }
-    // ---------------------------------------------------------
-    // Identify User
-    // ---------------------------------------------------------
-    async function identifyUser({ email, name }) {
-        const config = getConfig();
-        if (!config.apiKey || !config.tenantId || !config.appId) {
-            throw new Error("Zubbl SDK not initialized");
+    function saveStability() {
+        if (!isBrowser || typeof localStorage === "undefined")
+            return;
+        try {
+            const payload = {
+                geo: state.geo,
+                stability: state.stability,
+                lastGeoChange: state.lastGeoChange,
+            };
+            localStorage.setItem(CACHE_KEY, JSON.stringify(payload));
         }
-        const adaptiveHeaders = getAdaptiveHeaders();
-        const geoHeaders = await getGeoHeaders();
-        const headers = buildHeaders({
-            "Content-Type": "application/json",
-            ...adaptiveHeaders,
-            ...geoHeaders,
-        });
-        const body = JSON.stringify({ email, name });
-        const resp = await httpRequest(`${config.baseUrl}/sdk/identify`, {
-            method: "POST",
-            headers,
-            body,
-        });
-        const data = await resp.json().catch(() => ({}));
-        if (!data.external_user_id) {
-            console.warn("[Zubbl SDK] identifyUser: missing external_user_id");
+        catch {
+            /* ignore */
         }
-        return data;
     }
-    // ---------------------------------------------------------
-    // Fetch Effective Tiles
-    // ---------------------------------------------------------
-    async function getTiles({ external_user_id, app_id = null, }) {
-        const config = getConfig();
-        if (!config.apiKey || !config.tenantId || !config.appId) {
-            throw new Error("Zubbl SDK not initialized");
+    // -----------------------------------------------------------
+    // 🌍 Geo Detection (Node, Browser, Worker)
+    // -----------------------------------------------------------
+    function detectGeo() {
+        try {
+            if (isBrowser && typeof window !== "undefined" && window.navigator?.language) {
+                return window.navigator.language.split("-")[1] || "unknown";
+            }
+            if (isWorker && typeof self !== "undefined" && self.navigator?.language) {
+                return self.navigator.language.split("-")[1] || "unknown";
+            }
+            if (isNode && typeof process !== "undefined") {
+                const envGeo = process.env.ZUBBL_GEO || process.env.GEO;
+                if (envGeo && /^[A-Z]{2}$/i.test(envGeo))
+                    return envGeo.toUpperCase();
+                return "GB";
+            }
+            return "unknown";
+        }
+        catch (err) {
+            console.warn("[Zubbl SDK][Geo Detect] Failed:", err);
+            return "unknown";
         }
-        if (!external_user_id)
-            throw new Error("external_user_id is required");
-        const adaptiveHeaders = getAdaptiveHeaders();
-        const geoHeaders = await getGeoHeaders();
-        const headers = buildHeaders({
-            "X-External-User-Id": external_user_id,
-            ...adaptiveHeaders,
-            ...geoHeaders,
-        });
-        const params = new URLSearchParams({ external_user_id });
-        params.set("app_id", app_id || config.appId);
-        const resp = await httpRequest(`${config.baseUrl.replace(/\/$/, "")}/tiles/effective?${params.toString()}`, { method: "GET", headers });
-        return resp.json();
     }
-    // ---------------------------------------------------------
-    // Policy Enforcement
-    // ---------------------------------------------------------
-    async function enforce({ external_user_id, app_id = null, }) {
-        const config = getConfig();
-        if (!config.apiKey || !config.tenantId || !config.appId) {
-            throw new Error("Zubbl SDK not initialized");
+    // -----------------------------------------------------------
+    // 🧭 Update Geo & Stability (with persistence)
+    // -----------------------------------------------------------
+    function updateGeo(geoHint) {
+        const newGeo = geoHint || detectGeo();
+        if (newGeo !== state.geo) {
+            const now = Date.now();
+            const elapsed = (now - state.lastGeoChange) / 1000;
+            state.stability = Math.max(0.5, Math.min(1.0, elapsed / 3600));
+            state.geo = newGeo;
+            state.lastGeoChange = now;
+            saveStability();
+        }
+        else {
+            state.stability = Math.min(1.0, state.stability + 0.01);
+            saveStability();
         }
-        const adaptiveHeaders = getAdaptiveHeaders();
-        const geoHeaders = await getGeoHeaders();
-        const headers = buildHeaders({
-            "X-External-User-Id": external_user_id,
-            ...adaptiveHeaders,
-            ...geoHeaders,
-        });
-        const resp = await httpRequest(`${config.baseUrl.replace(/\/$/, "")}/sdk/test-enforcement`, { method: "POST", headers });
-        const json = await resp.json().catch(() => ({}));
-        return { decision: "allow", status: resp.status, data: json };
     }
-    // ---------------------------------------------------------
-    // Exposed Helpers
-    // ---------------------------------------------------------
-    const storage = createStorage();
-
     // -----------------------------------------------------------
-    // Zubbl Telemetry Core (Endpoint Discovery)
+    // 🧮 Record Context Samples
     // -----------------------------------------------------------
-    // Local telemetry buffer
-    let sampleRatio = 0.1; // 1 in 10 by default
-    let buffer = [];
-    let debounceTimer = null;
-    function shouldSample() {
-        return Math.random() < sampleRatio;
+    function recordContextSample(path, method, status, latency) {
+        state.routes.push({ path, method, ts: Date.now(), status, latency });
+        if (state.routes.length > MAX_HISTORY)
+            state.routes.shift();
+        updateGeo(); // auto-refresh geo info
     }
     // -----------------------------------------------------------
-    // Emit telemetry events
+    // 📦 Get Adaptive Headers
     // -----------------------------------------------------------
-    function emitEndpoint(payload) {
-        if (!shouldSample())
-            return;
-        const enriched = {
-            ...payload,
-            ts: Date.now(),
-            source: isBrowser ? "browser" : isNode ? "node" : "worker",
+    function getAdaptiveHeaders() {
+        const currentGeo = detectGeo();
+        updateGeo(currentGeo);
+        const summary = btoa(JSON.stringify({
+            env: isNode ? "node" : isBrowser ? "browser" : "worker",
+            routeCount: state.routes.length,
+            lastGeo: state.geo,
+            avgLatency: state.routes.reduce((a, b) => a + b.latency, 0) /
+                Math.max(1, state.routes.length),
+        }));
+        return {
+            "X-Zubbl-Context-Summary": summary,
+            "X-Zubbl-Geo-Stability": `${state.geo}/${state.stability.toFixed(2)}`,
         };
-        buffer.push(enriched);
-        if (!debounceTimer) {
-            debounceTimer = setTimeout(flushBuffer, 200);
-        }
     }
     // -----------------------------------------------------------
-    // Flush logic (batch send)
+    // 🌍 Initialize Geo Context Immediately
     // -----------------------------------------------------------
-    async function flushBuffer() {
-        if (buffer.length === 0) {
-            debounceTimer = null;
-            return;
+    updateGeo(process.env.ZUBBL_GEO);
+
+    // -----------------------------------------------------------
+    // 🔐 Secure Signing & Nonce Generator
+    // -----------------------------------------------------------
+    // -----------------------------------------------------------
+    // Generate UUIDv4 Nonce
+    // -----------------------------------------------------------
+    function generateNonce() {
+        return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, c => {
+            const r = (Math.random() * 16) | 0;
+            const v = c === "x" ? r : (r & 0x3) | 0x8;
+            return v.toString(16);
+        });
+    }
+    // -----------------------------------------------------------
+    // Attach signing headers to a request
+    // -----------------------------------------------------------
+    async function attachSigningHeaders(method, url, body, secretKey) {
+        const nonce = generateNonce();
+        // Compute canonical string (deterministic)
+        const bodyHash = "";
+        `${method.toUpperCase()}\n${url}\n${nonce}\n${bodyHash}`;
+        // ⚙️ Always include nonce even if secret is missing
+        {
+            return { "X-Zubbl-Nonce": nonce };
         }
-        const batch = [...buffer];
-        buffer = [];
-        debounceTimer = null;
-        const config = getConfig();
-        const url = `${config.baseUrl.replace(/\/$/, "")}/sdk/log`;
-        const headers = {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${config.apiKey}`,
-            "X-Tenant-Id": config.tenantId ?? "",
-            "X-App-Id": config.appId ?? "",
-        };
+    }
+
+    // src/core/http.ts
+    // -----------------------------------------------------------
+    // HTTP utility (instance-safe)
+    // -----------------------------------------------------------
+    /**
+     * Performs a safe HTTP request with adaptive + signing headers.
+     * NOTE: no global getConfig() dependency — caller must provide fully resolved URL + headers.
+     */
+    async function httpRequest(url, options = {}) {
+        // 🔧 Default timeout lowered for SDK-12 hardening
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 8000);
         try {
-            const resp = await fetch(url, {
-                method: "POST",
-                headers,
-                body: JSON.stringify(batch),
-            });
-            const text = await resp.text();
-            console.log("[Zubbl SDK][Telemetry] Flushed", batch.length, "events →", resp.status, text);
+            const finalOptions = {
+                ...options,
+                headers: {
+                    ...options.headers,
+                    ...getAdaptiveHeaders(),
+                },
+                signal: controller.signal,
+            };
+            attachSigningHeaders(finalOptions.headers);
+            // Record adaptive context sample
+            recordContextSample();
+            const response = await fetch(url, finalOptions);
+            if (!response.ok) {
+                console.warn(`[Zubbl SDK][HTTP] ${response.status} on ${url}`);
+            }
+            return response;
         }
         catch (err) {
-            console.warn("[Zubbl SDK][Telemetry] Failed to send batch:", err.message);
+            console.error("[Zubbl SDK][HTTP] Request failed:", err?.message);
+            throw err;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+
+    // src/features/identifyUser.ts
+    // -----------------------------------------------------------
+    // Zubbl SDK — Instance-safe identifyUser feature
+    // -----------------------------------------------------------
+    const USER_CACHE_KEY = "external_user_id";
+    const USER_TTL = 24 * 60 * 60; // 24h in seconds
+    /**
+     * Identify or auto-create a user by email/name.
+     * Instance-safe: requires store (from createConfigStore()) passed in.
+     * Idempotent: returns cached UUID if available.
+     */
+    async function identifyUserFeature(store, { email, name }) {
+        if (!email)
+            throw new Error("email is required");
+        const config = store.get();
+        const storage = createStorage();
+        // ⚡ Step 1 — Check cache
+        const cached = storage.get(USER_CACHE_KEY);
+        if (cached?.id) {
+            return { external_user_id: cached.id, cached: true };
+        }
+        // ⚙️ Step 2 — Prepare headers and request backend
+        const adaptiveHeaders = getAdaptiveHeaders();
+        const geoHeaders = await getGeoHeaders();
+        const headers = store.buildHeaders({
+            "Content-Type": "application/json",
+            ...adaptiveHeaders,
+            ...geoHeaders,
+        });
+        const resp = await httpRequest(`${config.baseUrl}/sdk/identify`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ email, name }),
+        });
+        const data = await resp.json().catch(() => ({}));
+        const { external_user_id } = data;
+        if (!external_user_id) {
+            throw new Error("Backend did not return external_user_id");
         }
+        // 🗃️ Step 3 — Cache for 24 h
+        storage.set(USER_CACHE_KEY, { id: external_user_id }, USER_TTL);
+        return { external_user_id, cached: false };
     }
+
+    // src/features/getTiles.ts
     // -----------------------------------------------------------
-    // Helper for HTTP wrapping
+    // Zubbl SDK — Instance-safe getTiles feature
     // -----------------------------------------------------------
-    async function recordRequestTelemetry(url, method, status, latency, extra = {}) {
+    const TILE_CACHE_KEY = "tiles_cache";
+    const TILE_TTL_DEFAULT = 10 * 60; // 10 min in seconds
+    /**
+     * Fetch effective tiles with caching, ETag, and background refresh.
+     * Instance-safe: requires store (from createConfigStore()) passed in.
+     */
+    async function getTilesFeature(store, { external_user_id, app_id = null, ttlSeconds = TILE_TTL_DEFAULT, }) {
+        if (!external_user_id)
+            throw new Error("external_user_id is required");
+        const config = store.get();
+        const storage = createStorage();
+        const cached = storage.get(TILE_CACHE_KEY);
+        const isFresh = cached && cached.expiresAt > Date.now();
+        // ⚡ Return cached data immediately if valid
+        if (isFresh) {
+            backgroundRefresh(store, external_user_id, app_id, ttlSeconds);
+            return { data: cached.data, fromCache: true };
+        }
         try {
-            const path = new URL(url).pathname;
-            emitEndpoint({
-                path,
-                method,
-                status,
-                latency,
-                ...extra,
+            const adaptiveHeaders = getAdaptiveHeaders();
+            const geoHeaders = await getGeoHeaders();
+            const headers = store.buildHeaders({
+                "X-External-User-Id": external_user_id,
+                ...adaptiveHeaders,
+                ...geoHeaders,
             });
+            if (cached?.etag)
+                headers["If-None-Match"] = cached.etag;
+            const params = new URLSearchParams({ external_user_id });
+            params.set("app_id", app_id || config.appId);
+            const url = `${config.baseUrl.replace(/\/$/, "")}/tiles/effective?${params.toString()}`;
+            const resp = await httpRequest(url, { headers });
+            if (resp.status === 304 && cached?.data) {
+                cached.expiresAt = Date.now() + ttlSeconds * 1000;
+                storage.set(TILE_CACHE_KEY, cached, ttlSeconds);
+                return { data: cached.data, fromCache: true, status: 304 };
+            }
+            const data = await resp.json();
+            const etag = resp.headers.get("ETag") || undefined;
+            const entry = {
+                data,
+                etag,
+                expiresAt: Date.now() + ttlSeconds * 1000,
+            };
+            storage.set(TILE_CACHE_KEY, entry, ttlSeconds);
+            return { data, fromCache: false, status: resp.status };
         }
         catch (err) {
-            console.warn("[Zubbl SDK][Telemetry] Failed to record telemetry", err);
+            if (cached?.data) {
+                return { data: cached.data, fromCache: true, error: String(err) };
+            }
+            throw err;
         }
     }
-    // -----------------------------------------------------------
-    // Runtime Endpoint Discovery
-    // -----------------------------------------------------------
-    let hasLoggedDiscovery = false;
-    function logRuntimeDiscovery(url) {
-        if (hasLoggedDiscovery)
-            return; // only once per runtime
-        hasLoggedDiscovery = true;
-        const runtime = isNode ? "Node" : isBrowser ? "Browser" : isWorker ? "Worker" : "Unknown";
-        const time = new Date().toISOString();
-        console.log(`[Zubbl SDK][Discovery] Runtime: ${runtime}`);
-        console.log(`[Zubbl SDK][Discovery] Timestamp: ${time}`);
-        console.log(`[Zubbl SDK][Discovery] Initial endpoint: ${url}`);
+    /**
+     * Background refresh (non-blocking).
+     */
+    async function backgroundRefresh(store, external_user_id, app_id, ttlSeconds) {
+        try {
+            await getTilesFeature(store, { external_user_id, app_id, ttlSeconds });
+        }
+        catch {
+            // Silently ignore background refresh errors
+        }
+    }
+
+    // src/client.ts
+    // -----------------------------------------------------------
+    // Zubbl SDK — Final Instance-based Client (Feature Delegation)
+    // -----------------------------------------------------------
+    /**
+     * Creates a self-contained, instance-based Zubbl client.
+     * Each instance owns its own config store and initialization state.
+     */
+    function createZubblClient(cfg) {
+        const store = createConfigStore();
+        const storage = createStorage();
+        let initialized = false;
+        // ---------------------------------------------------------
+        // Initialization
+        // ---------------------------------------------------------
+        async function init() {
+            if (initialized)
+                return;
+            // Initialize per-client config
+            store.init(cfg);
+            // Optional: GEO bootstrap
+            try {
+                const geo = await getGeoInfo();
+                console.log(`[Zubbl SDK] 🌍 GEO detected: ${geo.country} (ASN ${geo.asn || "?"})`);
+            }
+            catch (err) {
+                console.warn("[Zubbl SDK] GEO init failed:", err?.message);
+            }
+            initialized = true;
+        }
+        function assertInitialized() {
+            if (!initialized) {
+                throw new Error("Zubbl client not initialized — call client.init() first");
+            }
+        }
+        // ---------------------------------------------------------
+        // User + Tile Operations (delegated to feature modules)
+        // ---------------------------------------------------------
+        async function identifyUser({ email, name }) {
+            assertInitialized();
+            return identifyUserFeature(store, { email, name });
+        }
+        async function getTiles({ external_user_id, app_id = null, ttlSeconds, }) {
+            assertInitialized();
+            return getTilesFeature(store, { external_user_id, app_id, ttlSeconds });
+        }
+        // ---------------------------------------------------------
+        // Enforcement API (kept inline)
+        // ---------------------------------------------------------
+        async function enforce({ external_user_id, app_id = null, }) {
+            assertInitialized();
+            const config = store.get();
+            const headers = store.buildHeaders({
+                "X-External-User-Id": external_user_id,
+            });
+            const resp = await fetch(`${config.baseUrl?.replace(/\/$/, "")}/sdk/test-enforcement`, {
+                method: "POST",
+                headers,
+            });
+            const json = await resp.json().catch(() => ({}));
+            return { decision: "allow", status: resp.status, data: json };
+        }
+        // ---------------------------------------------------------
+        // Public API
+        // ---------------------------------------------------------
+        return {
+            init,
+            identifyUser,
+            getTiles,
+            enforce,
+            storage,
+        };
     }
 
-    var telemetry = /*#__PURE__*/Object.freeze({
-        __proto__: null,
-        emitEndpoint: emitEndpoint,
-        logRuntimeDiscovery: logRuntimeDiscovery,
-        recordRequestTelemetry: recordRequestTelemetry
-    });
+    // src/index.ts — Backward-compatible singleton API
+    let defaultClient = null;
+    async function init(config) {
+        if (!defaultClient)
+            defaultClient = createZubblClient(config);
+        return defaultClient.init();
+    }
+    async function identifyUser(...args) {
+        if (!defaultClient)
+            throw new Error("Zubbl SDK not initialized — call init() first");
+        return defaultClient.identifyUser(...args);
+    }
+    async function getTiles(...args) {
+        if (!defaultClient)
+            throw new Error("Zubbl SDK not initialized — call init() first");
+        return defaultClient.getTiles(...args);
+    }
+    async function enforce(...args) {
+        if (!defaultClient)
+            throw new Error("Zubbl SDK not initialized — call init() first");
+        return defaultClient.enforce(...args);
+    }
 
+    exports.createZubblClient = createZubblClient;
     exports.enforce = enforce;
-    exports.getConfig = getConfig;
     exports.getTiles = getTiles;
-    exports.httpRequest = httpRequest;
     exports.identifyUser = identifyUser;
     exports.init = init;
-    exports.storage = storage;
 
 }));
 //# sourceMappingURL=zubbl-sdk.umd.js.map