zubbl-sdk 1.1.16 → 1.1.19

package/dist/zubbl-sdk.esm.js

@@ -1,4 +1,4 @@
-import crypto from 'crypto';
+import 'crypto';
 
 // src/core/config.ts
 // -----------------------------------------------------------
@@ -11,21 +11,9 @@ const isNode = typeof process !== "undefined" &&
 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. " +
@@ -33,290 +21,40 @@ function assertBrowserSafety(config) {
         }
     }
 }
-// -----------------------------------------------------------
-// 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
@@ -517,194 +255,402 @@ async function getGeoHeaders() {
     };
 }
 
-// ---------------------------------------------------------
-// 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);
+}
 
-export { enforce, getConfig, getTiles, httpRequest, identifyUser, init, storage };
+export { createZubblClient, enforce, getTiles, identifyUser, init };
 //# sourceMappingURL=zubbl-sdk.esm.js.map