styra-js 1.5.2

package/dist/client.d.ts

@@ -0,0 +1,141 @@
+export type StyraMode = "cs" | "ss";
+export interface StyraConfig {
+    apiKey: string;
+    mode: StyraMode;
+    /**
+     * Cache TTL in milliseconds. Only applies in CS mode.
+     * Defaults to 5 minutes (300_000 ms).
+     * Ignored silently in SS mode.
+     */
+    cacheTTL?: number;
+}
+/** One entry in the status-code error handler registry */
+type StatusHandler = (statusCode: number, url: string) => void;
+export declare class StyraAB {
+    private readonly apiKey;
+    private readonly mode;
+    private readonly cacheTTL;
+    private readonly baseURL;
+    private readonly getSid;
+    constructor(apiKey: string, mode: StyraMode, cacheTTL: number, baseURL: string, getSid: () => string);
+    /**
+     * Fetch the version assigned to this user for a named A/B test.
+     *
+     * @param abTestName   — the test identifier sent to the backend as a query param
+     * @param defaultValue — returned on any error or when paused without cache
+     * @param revokeAfter  — ms before the request is aborted (default 3000)
+     *
+     * CS mode: lazy validity-expiry sweep → pause check → cache check.
+     *          If cache is FRESH (within cacheTTL) → return it directly,
+     *          NO API call is made at all.
+     *          Only when cache is stale or absent do we actually call the
+     *          API — and only then do we send `isCachedLS` (true = a stale
+     *          entry existed, false = nothing existed at all) so backend
+     *          can tell a "re-fetch of an expired assignment" apart from a
+     *          genuinely new user/request for abversion counting.
+     * SS mode: always fetches fresh (isCachedLS always false)
+     */
+    getVersion<T = unknown>(abTestName: string, defaultValue?: T, revokeAfter?: number): Promise<T | null>;
+    /**
+     * Track an event against a named A/B test.
+     * Always unique per user — fires at most once per abTestName, ever
+     * (until that test's validity window + grace period expires).
+     *
+     * @param abTestName — the test identifier sent as a query param.
+     *                     No `revokeAfter` here — this method does not
+     *                     accept a custom timeout, only the test name.
+     *
+     * Decision order:
+     *   1. Lazy validity sweep (clears stale cache + tracked key if expired)
+     *   2. AB-cache presence check — we must already have a known/assigned
+     *      variant value (e.g. "dark_theme") stored for this test. If the
+     *      cache entry is ABSENT, we don't track at all — tracking a test
+     *      the user was never actually assigned a cached variant for would
+     *      pollute/degrade the numbers.
+     *   3. Already-tracked check — if the tracked-event key is already
+     *      present, skip (always-unique, no API call).
+     *   4. Pause check → API call, mark tracked-key on success.
+     *
+     * Both (2) AND (3) must pass — cache present AND not-yet-tracked —
+     * before any network call is made.
+     */
+    track(abTestName: string): Promise<"OK" | "NOT OK">;
+}
+export declare class StyraEvent {
+    private readonly apiKey;
+    private readonly mode;
+    private readonly baseURL;
+    private readonly getSid;
+    constructor(apiKey: string, mode: StyraMode, baseURL: string, getSid: () => string);
+    /**
+     * Fire a named custom event — not tied to any A/B test.
+     *
+     * @param eventName — sent as a query param to /track-custom-event
+     * @param unique    — if true, only fires once per session per eventName
+     *
+     * Decision order: unique check → pause check → API call
+     */
+    track(eventName: string, unique?: boolean): Promise<"OK" | "NOT OK">;
+}
+export declare class Styra {
+    private readonly apiKey;
+    private readonly mode;
+    private readonly cacheTTL;
+    private readonly baseURL;
+    /** styra.ab.getVersion() · styra.ab.track() */
+    readonly ab: StyraAB;
+    /** styra.event.track() */
+    readonly event: StyraEvent;
+    /** Override or extend status-code handlers at runtime */
+    readonly statusHandlers: Record<number, StatusHandler>;
+    private static readonly DEFAULT_BASE_URL;
+    constructor(config: StyraConfig);
+    private runInitChecks;
+    private getSid;
+    /**
+     * Fetch a remote config variable by key.
+     * Returns defaultValue (or null) on any error — never throws.
+     *
+     * @param key          — variable identifier, sent as query param
+     * @param defaultValue — returned on error, pause without cache, or missing value
+     * @param revokeAfter  — ms before the request is aborted (default 3000)
+     *
+     * CS mode: pause check → cache check → fetch → cache write
+     * SS mode: always fetches fresh
+     *
+     * Note: unlike ab.getVersion, this does NOT send isCachedLS and is not
+     * subject to AB validity-expiry — that logic is AB-specific.
+     */
+    getVariable<T = unknown>(key: string, defaultValue?: T, revokeAfter?: number): Promise<T | null>;
+    /**
+     * Evict a single variable key from the cache.
+     * No-op in SS mode.
+     */
+    evictCache(key: string): void;
+    /**
+     * Clear all Styra variable and A/B cache entries.
+     * Does NOT touch sid, events, paused, or meta.
+     * No-op in SS mode.
+     */
+    clearAllCache(): void;
+    /**
+     * Clear the stored SID.
+     * Next request will send sid: "none" and receive a fresh SID from the backend.
+     * Useful for logout flows.
+     * No-op in SS mode.
+     */
+    clearSID(): void;
+    /**
+     * Clear the unique events registry.
+     * After this, all unique events (ab.track + event.track) can fire again.
+     * No-op in SS mode.
+     */
+    clearEvents(): void;
+    /**
+     * Manually remove a specific endpoint from the paused registry.
+     * The next call to that endpoint will go through to the API immediately.
+     * No-op in SS mode.
+     */
+    unpause(endpoint: string): void;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,895 @@
+"use strict";
+// =============================================================================
+// Styra SDK v1.5.2
+// Supports Client-Side (cs) and Server-Side (ss) modes.
+//
+// CS mode : localStorage cache, XOR encoded with (apiKey + hostname),
+//           SID via header, pause registry, unique event tracking,
+//           15-day auto-renewal, server-instruction handling,
+//           per-abTest validity-based cache expiry
+//
+// SS mode : no cache, no localStorage, no SID — pure stateless fetch
+//
+// Public API surface:
+//   styra.getVariable(key, default?, revokeAfter?)              — remote config value
+//   styra.ab.getVersion(abTestName, default?, revokeAfter?)      — assigned A/B version
+//   styra.ab.track(abTestName)                                   — track an A/B event (always unique per user)
+//   styra.event.track(eventName, unique?)                       — track a custom event
+//
+// All methods are silent on errors — devs get [Styra] console logs,
+// end users never see a crash or an undefined.
+//
+// ── v1.5.2 changes ───────────────────────────────────────────────────────────
+// 1. ab.getVersion: if a FRESH cache entry exists (within cacheTTL), it is
+//    returned directly — NO API call is made at all. Only when the cache is
+//    stale or absent does the SDK actually call the backend, and only then
+//    does it send `isCachedLS: true/false` — true = a stale entry existed
+//    locally (re-fetch of an expired assignment), false = nothing existed at
+//    all (genuinely new request — backend should count a new "abversion").
+// 2. ab.getVersion now stores the backend-provided `validity` (timestamp)
+//    alongside the cached AB value. Both ab.getVersion and ab.track lazily
+//    check this validity (+2 day grace) before touching that test's stored
+//    data, and wipe it out (cache + tracked-event key) if expired.
+// 3. ab.track no longer accepts a `unique` flag — it is now ALWAYS unique
+//    per user (tracked-event key check is unconditional). It also now takes
+//    a SINGLE parameter (abTestName only, no revokeAfter) and additionally
+//    requires a fresh/known AB-cache entry to exist for that test before it
+//    will track at all — tracking without a known assigned variant would
+//    pollute the numbers, so it's skipped silently in that case.
+// 4. getVariable and ab.getVersion now accept a `revokeAfter` ms param
+//    (default 3000ms) — the underlying HTTP request is aborted if it takes
+//    longer than this. ab.track does NOT have a revokeAfter param.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Styra = exports.StyraEvent = exports.StyraAB = void 0;
+// ─────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────
+const SDK_VERSION = "3.2.0";
+const CACHE_FORMAT_VERSION = 1;
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const RENEWAL_TTL_MS = 15 * 24 * 60 * 60 * 1000; // 15 days
+const PAUSE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const VALIDITY_GRACE_MS = 2 * 24 * 60 * 60 * 1000; // 2 days grace after validity
+const DEFAULT_REVOKE_AFTER = 3000; // 3s default request timeout
+const LOG_PREFIX = "[Styra]";
+const SID_ABSENT = "none";
+// ─────────────────────────────────────────────
+// localStorage key map
+// Every styra:: key lives here — no magic strings elsewhere.
+// ─────────────────────────────────────────────
+const LS = {
+    META: "styra::meta",
+    SID: "styra::sid",
+    EVENTS: "styra::events",
+    PAUSED: "styra::paused",
+    AB: (abTestName) => `styra::ab::${abTestName}`,
+    CACHE: (key) => `styra::cache::${key}`,
+};
+// ─────────────────────────────────────────────
+// Logger
+// ─────────────────────────────────────────────
+const log = {
+    info: (msg, ...a) => console.info(`${LOG_PREFIX} ${msg}`, ...a),
+    warn: (msg, ...a) => console.warn(`${LOG_PREFIX} ⚠️  ${msg}`, ...a),
+    error: (msg, ...a) => console.error(`${LOG_PREFIX} ❌ ${msg}`, ...a),
+    debug: (msg, ...a) => console.debug(`${LOG_PREFIX} 🔍 ${msg}`, ...a),
+};
+// ─────────────────────────────────────────────
+// XOR encode / decode
+//
+// XOR key = apiKey + hostname (concatenated).
+// A stolen apiKey alone cannot decode anything stored in localStorage
+// because the hostname half of the key is not in the bundle — it comes
+// from the runtime environment.
+// ─────────────────────────────────────────────
+function buildXorKey(apiKey) {
+    const hostname = typeof window !== "undefined" ? window.location.hostname : "";
+    return apiKey + hostname;
+}
+function xorEncode(xorKey, payload) {
+    const json = JSON.stringify(payload);
+    let out = "";
+    for (let i = 0; i < json.length; i++) {
+        const xored = json.charCodeAt(i) ^ xorKey.charCodeAt(i % xorKey.length);
+        out += xored.toString(16).padStart(4, "0");
+    }
+    return out;
+}
+function xorDecode(xorKey, encoded) {
+    try {
+        let out = "";
+        for (let i = 0; i < encoded.length; i += 4) {
+            const charCode = parseInt(encoded.slice(i, i + 4), 16) ^
+                xorKey.charCodeAt((i / 4) % xorKey.length);
+            out += String.fromCharCode(charCode);
+        }
+        return JSON.parse(out);
+    }
+    catch {
+        return null;
+    }
+}
+// ─────────────────────────────────────────────
+// Status-code error handler registry
+// Advanced users can add / override via styra.statusHandlers[code] = fn
+// ─────────────────────────────────────────────
+const STATUS_HANDLERS = {
+    400: (c, u) => log.error(`Bad request (${c}) — check query params. URL: ${u}`),
+    401: (c, u) => log.error(`Unauthorized (${c}) — API key may be invalid. URL: ${u}`),
+    403: (c, u) => log.error(`Forbidden (${c}) — API key lacks access. URL: ${u}`),
+    404: (c, u) => log.warn(`Not found (${c}) — resource doesn't exist. URL: ${u}`),
+    411: (c, u) => log.error(`Length required (${c}) — missing Content-Length. URL: ${u}`),
+    429: (c, u) => log.warn(`Rate limited (${c}) — consider increasing cacheTTL. URL: ${u}`),
+    500: (c, u) => log.error(`Internal server error (${c}) — Styra backend issue. URL: ${u}`),
+    502: (c, u) => log.error(`Bad gateway (${c}) — Styra may be down. URL: ${u}`),
+    503: (c, u) => log.error(`Service unavailable (${c}) — Styra temporarily down. URL: ${u}`),
+};
+function dispatchStatusError(statusCode, url) {
+    const handler = STATUS_HANDLERS[statusCode];
+    if (handler) {
+        handler(statusCode, url);
+    }
+    else {
+        log.error(`Unexpected HTTP ${statusCode} from ${url}`);
+    }
+}
+// ─────────────────────────────────────────────
+// localStorage primitives
+// ─────────────────────────────────────────────
+function lsGet(key) {
+    try {
+        return localStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+function lsSet(key, value) {
+    try {
+        localStorage.setItem(key, value);
+    }
+    catch (err) {
+        log.warn(`localStorage write failed for "${key}": ${err}`);
+    }
+}
+function lsRemove(key) {
+    try {
+        localStorage.removeItem(key);
+    }
+    catch { /* silent */ }
+}
+function lsGetJson(key) {
+    const raw = lsGet(key);
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function lsSetJson(key, value) {
+    try {
+        lsSet(key, JSON.stringify(value));
+    }
+    catch (err) {
+        log.warn(`JSON stringify failed for "${key}": ${err}`);
+    }
+}
+// ─────────────────────────────────────────────
+// Meta — global session clock + encoded domain
+// ─────────────────────────────────────────────
+function readMeta() {
+    return lsGetJson(LS.META);
+}
+function writeMeta(apiKey) {
+    const hostname = typeof window !== "undefined" ? window.location.hostname : "";
+    const entry = {
+        issuedAt: Date.now(),
+        _d: xorEncode(buildXorKey(apiKey), hostname),
+    };
+    lsSetJson(LS.META, entry);
+}
+function decodedDomain(apiKey, encoded) {
+    const v = xorDecode(buildXorKey(apiKey), encoded);
+    return typeof v === "string" ? v : null;
+}
+// ─────────────────────────────────────────────
+// SID
+// ─────────────────────────────────────────────
+function readSid(apiKey) {
+    const entry = lsGetJson(LS.SID);
+    if (!entry)
+        return SID_ABSENT;
+    if (entry.validity && Date.now() > new Date(entry.validity).getTime()) {
+        lsRemove(LS.SID);
+        log.debug("SID validity date passed — requesting a new one.");
+        return SID_ABSENT;
+    }
+    const v = xorDecode(buildXorKey(apiKey), entry._v);
+    return typeof v === "string" ? v : SID_ABSENT;
+}
+function writeSid(apiKey, sid, validity) {
+    const entry = {
+        _v: xorEncode(buildXorKey(apiKey), sid),
+        issuedAt: Date.now(),
+        validity: validity !== null && validity !== void 0 ? validity : "",
+    };
+    lsSetJson(LS.SID, entry);
+    log.debug("SID stored.");
+}
+// ─────────────────────────────────────────────
+// Pause registry
+// ─────────────────────────────────────────────
+function isPaused(endpoint) {
+    var _a;
+    const reg = (_a = lsGetJson(LS.PAUSED)) !== null && _a !== void 0 ? _a : {};
+    const entry = reg[endpoint];
+    if (!entry)
+        return false;
+    return Date.now() - entry.pausedAt < PAUSE_TTL_MS;
+}
+function setPaused(endpoint) {
+    var _a;
+    const reg = (_a = lsGetJson(LS.PAUSED)) !== null && _a !== void 0 ? _a : {};
+    reg[endpoint] = { pausedAt: Date.now() };
+    lsSetJson(LS.PAUSED, reg);
+    log.debug(`Endpoint "${endpoint}" paused for 24 hr.`);
+}
+function clearPausedEntry(endpoint) {
+    var _a;
+    const reg = (_a = lsGetJson(LS.PAUSED)) !== null && _a !== void 0 ? _a : {};
+    if (reg[endpoint]) {
+        delete reg[endpoint];
+        lsSetJson(LS.PAUSED, reg);
+        log.debug(`Endpoint "${endpoint}" unpaused.`);
+    }
+}
+// ─────────────────────────────────────────────
+// Unique event registry
+// ─────────────────────────────────────────────
+function hasEventFired(eventName) {
+    var _a;
+    const reg = (_a = lsGetJson(LS.EVENTS)) !== null && _a !== void 0 ? _a : {};
+    return reg[eventName] === true;
+}
+function markEventFired(eventName) {
+    var _a;
+    const reg = (_a = lsGetJson(LS.EVENTS)) !== null && _a !== void 0 ? _a : {};
+    reg[eventName] = true;
+    lsSetJson(LS.EVENTS, reg);
+    log.debug(`Unique event "${eventName}" marked as fired.`);
+}
+function clearEventKey(eventName) {
+    var _a;
+    const reg = (_a = lsGetJson(LS.EVENTS)) !== null && _a !== void 0 ? _a : {};
+    if (reg[eventName] !== undefined) {
+        delete reg[eventName];
+        lsSetJson(LS.EVENTS, reg);
+        log.debug(`Tracked-event key "${eventName}" cleared.`);
+    }
+}
+// ─────────────────────────────────────────────
+// Cache (plain getVariable cache — no validity concept)
+// ─────────────────────────────────────────────
+function readCache(apiKey, lsKey, ttl) {
+    const raw = lsGet(lsKey);
+    if (!raw)
+        return null;
+    try {
+        const entry = JSON.parse(raw);
+        if (!entry || entry.v !== CACHE_FORMAT_VERSION) {
+            lsRemove(lsKey);
+            return null;
+        }
+        if (Date.now() - entry.ts > ttl) {
+            lsRemove(lsKey);
+            log.debug(`Cache expired for "${lsKey}"`);
+            return null;
+        }
+        log.debug(`Cache hit for "${lsKey}"`);
+        return xorDecode(buildXorKey(apiKey), entry.data);
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(apiKey, lsKey, data) {
+    const entry = {
+        v: CACHE_FORMAT_VERSION,
+        ts: Date.now(),
+        data: xorEncode(buildXorKey(apiKey), data),
+    };
+    lsSetJson(lsKey, entry);
+}
+// ─────────────────────────────────────────────
+// AB cache (validity-aware — separate from plain cache above)
+// ─────────────────────────────────────────────
+/**
+ * Read the raw AB cache entry without any TTL/validity filtering.
+ * Used internally to check existence (for isCachedLS) before deciding
+ * whether to treat this as a fresh request.
+ */
+function readAbCacheRaw(lsKey) {
+    const raw = lsGet(lsKey);
+    if (!raw)
+        return null;
+    try {
+        const entry = JSON.parse(raw);
+        if (!entry || entry.v !== CACHE_FORMAT_VERSION) {
+            lsRemove(lsKey);
+            return null;
+        }
+        return entry;
+    }
+    catch {
+        return null;
+    }
+}
+/** Decode + TTL-check an AB cache entry. Returns null if missing/expired by TTL. */
+function readAbCache(apiKey, lsKey, ttl) {
+    const entry = readAbCacheRaw(lsKey);
+    if (!entry)
+        return null;
+    if (Date.now() - entry.ts > ttl) {
+        log.debug(`AB cache TTL-expired for "${lsKey}"`);
+        return null;
+    }
+    log.debug(`AB cache hit for "${lsKey}"`);
+    return xorDecode(buildXorKey(apiKey), entry.data);
+}
+function writeAbCache(apiKey, lsKey, data, validity) {
+    const entry = {
+        v: CACHE_FORMAT_VERSION,
+        ts: Date.now(),
+        data: xorEncode(buildXorKey(apiKey), data),
+        validity,
+    };
+    lsSetJson(lsKey, entry);
+}
+/**
+ * Lazily check whether this abTestName's stored data (cache entry +
+ * tracked-event key) has passed its backend-issued validity date
+ * (+ grace period). If so, wipe both so the test is treated as fresh.
+ *
+ * Called at the top of both ab.getVersion and ab.track before touching
+ * any stored state for that abTestName.
+ */
+function expireAbTestIfStale(abTestName) {
+    const lsKey = LS.AB(abTestName);
+    const entry = readAbCacheRaw(lsKey);
+    if (!entry || !entry.validity)
+        return;
+    const validityMs = new Date(entry.validity).getTime();
+    if (Number.isNaN(validityMs))
+        return;
+    const expiresAt = validityMs + VALIDITY_GRACE_MS;
+    if (Date.now() <= expiresAt)
+        return;
+    // Past validity + grace — wipe cache and tracked-event key for this test.
+    lsRemove(lsKey);
+    clearEventKey(`ab::${abTestName}`);
+    log.debug(`AB test "${abTestName}" past validity (+2d grace) — cache & tracked key cleared.`);
+}
+// ─────────────────────────────────────────────
+// Reset helpers
+// ─────────────────────────────────────────────
+/**
+ * Renewal reset — clears everything EXCEPT styra::paused.
+ * Used for 15-day renewal and domain change.
+ */
+function renewalReset(apiKey, reason) {
+    try {
+        Object.keys(localStorage)
+            .filter((k) => k.startsWith("styra::") && k !== LS.PAUSED)
+            .forEach(lsRemove);
+    }
+    catch { /* localStorage inaccessible */ }
+    writeMeta(apiKey);
+    log.info(`Session reset — ${reason}. Paused registry preserved.`);
+}
+/**
+ * Full reset — clears everything including styra::paused.
+ * Only triggered by act: "clcLocal" from the backend.
+ */
+function fullReset(apiKey) {
+    try {
+        Object.keys(localStorage)
+            .filter((k) => k.startsWith("styra::"))
+            .forEach(lsRemove);
+    }
+    catch { /* silent */ }
+    writeMeta(apiKey);
+    log.debug("Full session reset by server instruction (act: clcLocal).");
+}
+// ─────────────────────────────────────────────
+// Core HTTP helper
+//
+// Supports an abortable timeout (`revokeAfter` ms). If the request hasn't
+// resolved within that window, it's aborted and treated as a network
+// failure (same silent-failure contract as any other network error).
+// ─────────────────────────────────────────────
+async function httpGet(url, apiKey, sid, params, revokeAfter = DEFAULT_REVOKE_AFTER) {
+    const fullURL = params
+        ? `${url}?${new URLSearchParams(params).toString()}`
+        : url;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), revokeAfter);
+    try {
+        const res = await globalThis.fetch(fullURL, {
+            method: "GET",
+            headers: { "x-api-key": apiKey, "sid": sid },
+            signal: controller.signal,
+        });
+        let data = null;
+        try {
+            data = (await res.json());
+        }
+        catch { /* non-JSON body */ }
+        if (!res.ok)
+            dispatchStatusError(res.status, fullURL);
+        return { ok: res.ok, status: res.status, data };
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            log.warn(`Request to ${fullURL} aborted — exceeded revokeAfter (${revokeAfter}ms).`);
+        }
+        else {
+            log.error(`Network error fetching ${fullURL}: ${err}`);
+        }
+        return { ok: false, status: 0, data: null };
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+// ─────────────────────────────────────────────
+// Response processor — strict execution order
+//
+// Order matters:
+//   1. act: clcLocal  → wipe everything first so nothing written after gets cleared
+//   2. sid            → store new SID
+//   3. p              → update pause registry
+//   4. cache write    → only on success, CS mode (plain getVariable cache)
+//   5. ab cache write → only on success, CS mode (validity-aware AB cache)
+//   6. unique event   → only on success
+// ─────────────────────────────────────────────
+function processResponse(data, apiKey, mode, opts) {
+    // 1. Server-instructed full reset
+    if (data.act === "clcLocal") {
+        fullReset(apiKey);
+    }
+    // 2. New SID from backend
+    if (data.sid) {
+        writeSid(apiKey, data.sid);
+    }
+    // 3. Pause signal
+    if (data.p === true) {
+        setPaused(opts.endpoint);
+    }
+    else if (data.p === false) {
+        clearPausedEntry(opts.endpoint);
+    }
+    // p absent → no change
+    // 4/5. Cache write (CS mode, success only)
+    if (data.success &&
+        mode === "cs" &&
+        opts.cacheKey !== undefined &&
+        opts.cacheTTL !== undefined &&
+        data.value !== undefined &&
+        data.value !== null) {
+        if (opts.isAbCache) {
+            writeAbCache(apiKey, opts.cacheKey, data.value, data.validity);
+        }
+        else {
+            writeCache(apiKey, opts.cacheKey, data.value);
+        }
+    }
+    // 6. Mark unique event as fired (success only)
+    if (data.success && opts.unique && opts.eventName) {
+        markEventFired(opts.eventName);
+    }
+}
+// ─────────────────────────────────────────────
+// StyraAB — styra.ab namespace
+// ─────────────────────────────────────────────
+class StyraAB {
+    constructor(apiKey, mode, cacheTTL, baseURL, getSid) {
+        this.apiKey = apiKey;
+        this.mode = mode;
+        this.cacheTTL = cacheTTL;
+        this.baseURL = baseURL;
+        this.getSid = getSid;
+    }
+    /**
+     * Fetch the version assigned to this user for a named A/B test.
+     *
+     * @param abTestName   — the test identifier sent to the backend as a query param
+     * @param defaultValue — returned on any error or when paused without cache
+     * @param revokeAfter  — ms before the request is aborted (default 3000)
+     *
+     * CS mode: lazy validity-expiry sweep → pause check → cache check.
+     *          If cache is FRESH (within cacheTTL) → return it directly,
+     *          NO API call is made at all.
+     *          Only when cache is stale or absent do we actually call the
+     *          API — and only then do we send `isCachedLS` (true = a stale
+     *          entry existed, false = nothing existed at all) so backend
+     *          can tell a "re-fetch of an expired assignment" apart from a
+     *          genuinely new user/request for abversion counting.
+     * SS mode: always fetches fresh (isCachedLS always false)
+     */
+    async getVersion(abTestName, defaultValue, revokeAfter = DEFAULT_REVOKE_AFTER) {
+        var _a, _b;
+        if (!this.apiKey)
+            return defaultValue !== null && defaultValue !== void 0 ? defaultValue : null;
+        const endpoint = "ab-test";
+        const cacheKey = LS.AB(abTestName);
+        // Lazy expiry sweep for this specific test before doing anything else
+        if (this.mode === "cs") {
+            expireAbTestIfStale(abTestName);
+        }
+        // Pause check (CS only) — still respects existing cache if present
+        if (this.mode === "cs" && isPaused(endpoint)) {
+            log.debug(`ab.getVersion("${abTestName}") skipped — endpoint paused.`);
+            const cached = readAbCache(this.apiKey, cacheKey, this.cacheTTL);
+            return (_b = (_a = cached) !== null && _a !== void 0 ? _a : defaultValue) !== null && _b !== void 0 ? _b : null;
+        }
+        // Cache check (CS only) — fresh cache short-circuits, no API call at all.
+        let isCachedLS = false;
+        if (this.mode === "cs") {
+            const cached = readAbCache(this.apiKey, cacheKey, this.cacheTTL);
+            if (cached !== null) {
+                // Fresh hit — return immediately, never touch the network.
+                return cached;
+            }
+            // Cache was either stale (TTL passed) or never existed at all.
+            // Presence check tells us which, for the isCachedLS flag below.
+            isCachedLS = readAbCacheRaw(cacheKey) !== null;
+        }
+        // Fetch — only reached when cache is stale or absent.
+        // isCachedLS tells backend whether this is a re-fetch of an existing
+        // (now-expired) assignment vs. a brand new request.
+        const { ok, data } = await httpGet(`${this.baseURL}/${endpoint}`, this.apiKey, this.getSid(), { abTestName, isCachedLS: String(isCachedLS) }, revokeAfter);
+        if (!ok || !data)
+            return defaultValue !== null && defaultValue !== void 0 ? defaultValue : null;
+        processResponse(data, this.apiKey, this.mode, {
+            endpoint,
+            cacheKey,
+            cacheTTL: this.cacheTTL,
+            isAbCache: true,
+        });
+        if (!data.success || data.value == null)
+            return defaultValue !== null && defaultValue !== void 0 ? defaultValue : null;
+        return data.value;
+    }
+    /**
+     * Track an event against a named A/B test.
+     * Always unique per user — fires at most once per abTestName, ever
+     * (until that test's validity window + grace period expires).
+     *
+     * @param abTestName — the test identifier sent as a query param.
+     *                     No `revokeAfter` here — this method does not
+     *                     accept a custom timeout, only the test name.
+     *
+     * Decision order:
+     *   1. Lazy validity sweep (clears stale cache + tracked key if expired)
+     *   2. AB-cache presence check — we must already have a known/assigned
+     *      variant value (e.g. "dark_theme") stored for this test. If the
+     *      cache entry is ABSENT, we don't track at all — tracking a test
+     *      the user was never actually assigned a cached variant for would
+     *      pollute/degrade the numbers.
+     *   3. Already-tracked check — if the tracked-event key is already
+     *      present, skip (always-unique, no API call).
+     *   4. Pause check → API call, mark tracked-key on success.
+     *
+     * Both (2) AND (3) must pass — cache present AND not-yet-tracked —
+     * before any network call is made.
+     */
+    async track(abTestName) {
+        if (!this.apiKey)
+            return "NOT OK";
+        const endpoint = "track-event";
+        const eventKey = `ab::${abTestName}`; // namespaced in events registry
+        const cacheKey = LS.AB(abTestName);
+        // Lazy expiry sweep — if this test's validity window has lapsed,
+        // both the AB cache and tracked-key are cleared so it can fire again
+        // for the new cycle (and correctly fail the cache-presence check below
+        // until a fresh getVersion() call repopulates it).
+        if (this.mode === "cs") {
+            expireAbTestIfStale(abTestName);
+        }
+        // AB-cache presence check — must have a known assigned variant cached
+        // for this test, otherwise tracking is skipped entirely.
+        if (readAbCacheRaw(cacheKey) === null) {
+            log.debug(`ab.track("${abTestName}") skipped — no cached AB assignment present.`);
+            return "NOT OK";
+        }
+        // Already-tracked check — always enforced now, no opt-out.
+        if (hasEventFired(eventKey)) {
+            log.debug(`ab.track("${abTestName}") skipped — already fired (always-unique).`);
+            return "NOT OK";
+        }
+        // Pause check
+        if (this.mode === "cs" && isPaused(endpoint)) {
+            log.debug(`ab.track("${abTestName}") skipped — endpoint paused.`);
+            return "NOT OK";
+        }
+        // Fetch
+        const { ok, data } = await httpGet(`${this.baseURL}/${endpoint}`, this.apiKey, this.getSid(), { abTestName, unique: "true" });
+        if (!ok || !data)
+            return "NOT OK";
+        processResponse(data, this.apiKey, this.mode, {
+            endpoint,
+            eventName: eventKey,
+            unique: true,
+        });
+        return data.success ? "OK" : "NOT OK";
+    }
+}
+exports.StyraAB = StyraAB;
+// ─────────────────────────────────────────────
+// StyraEvent — styra.event namespace
+// (unchanged in v1.6.0 — keeps the unique flag, no revokeAfter)
+// ─────────────────────────────────────────────
+class StyraEvent {
+    constructor(apiKey, mode, baseURL, getSid) {
+        this.apiKey = apiKey;
+        this.mode = mode;
+        this.baseURL = baseURL;
+        this.getSid = getSid;
+    }
+    /**
+     * Fire a named custom event — not tied to any A/B test.
+     *
+     * @param eventName — sent as a query param to /track-custom-event
+     * @param unique    — if true, only fires once per session per eventName
+     *
+     * Decision order: unique check → pause check → API call
+     */
+    async track(eventName, unique = false) {
+        if (!this.apiKey)
+            return "NOT OK";
+        const endpoint = "track-custom-event";
+        const eventKey = `custom::${eventName}`; // namespaced in events registry
+        // Unique check
+        if (unique && hasEventFired(eventKey)) {
+            log.debug(`event.track("${eventName}") skipped — already fired (unique=true).`);
+            return "NOT OK";
+        }
+        // Pause check
+        if (this.mode === "cs" && isPaused(endpoint)) {
+            log.debug(`event.track("${eventName}") skipped — endpoint paused.`);
+            return "NOT OK";
+        }
+        // Fetch
+        const { ok, data } = await httpGet(`${this.baseURL}/${endpoint}`, this.apiKey, this.getSid(), { eventName, unique: String(unique) });
+        if (!ok || !data)
+            return "NOT OK";
+        processResponse(data, this.apiKey, this.mode, {
+            endpoint,
+            eventName: eventKey,
+            unique,
+        });
+        return data.success ? "OK" : "NOT OK";
+    }
+}
+exports.StyraEvent = StyraEvent;
+// ─────────────────────────────────────────────
+// Main Styra class
+// ─────────────────────────────────────────────
+class Styra {
+    constructor(config) {
+        var _a;
+        /** Override or extend status-code handlers at runtime */
+        this.statusHandlers = STATUS_HANDLERS;
+        // ── Critical config guards ──────────────────────────────────────────────
+        if (!config.apiKey || typeof config.apiKey !== "string") {
+            log.error("apiKey is required and must be a string. SDK is non-functional.");
+            this.apiKey = "";
+            this.mode = "ss";
+            this.cacheTTL = 0;
+            this.baseURL = Styra.DEFAULT_BASE_URL;
+            this.ab = new StyraAB("", "ss", 0, this.baseURL, () => SID_ABSENT);
+            this.event = new StyraEvent("", "ss", this.baseURL, () => SID_ABSENT);
+            return;
+        }
+        if (!["cs", "ss"].includes(config.mode)) {
+            log.error(`mode must be "cs" or "ss". Received: "${config.mode}". SDK is non-functional.`);
+            this.apiKey = "";
+            this.mode = "ss";
+            this.cacheTTL = 0;
+            this.baseURL = Styra.DEFAULT_BASE_URL;
+            this.ab = new StyraAB("", "ss", 0, this.baseURL, () => SID_ABSENT);
+            this.event = new StyraEvent("", "ss", this.baseURL, () => SID_ABSENT);
+            return;
+        }
+        this.apiKey = config.apiKey;
+        this.mode = config.mode;
+        this.baseURL = Styra.DEFAULT_BASE_URL;
+        // ── Mode-specific setup ─────────────────────────────────────────────────
+        if (this.mode === "ss") {
+            if (config.cacheTTL !== undefined) {
+                log.warn("cacheTTL is ignored in SS mode.");
+            }
+            this.cacheTTL = 0;
+            if (typeof window !== "undefined") {
+                log.warn('mode is "ss" but a browser window was detected. Use mode: "cs" in browser environments.');
+            }
+            log.info(`Initialised in SS (server-side) mode. SDK v${SDK_VERSION}`);
+        }
+        else {
+            if (typeof window === "undefined") {
+                log.warn('mode is "cs" but no browser window detected. Use mode: "ss" on the server.');
+            }
+            this.cacheTTL = (_a = config.cacheTTL) !== null && _a !== void 0 ? _a : DEFAULT_TTL_MS;
+            this.runInitChecks();
+            log.info(`Initialised in CS (client-side) mode. Cache TTL: ${this.cacheTTL / 1000}s. SDK v${SDK_VERSION}`);
+        }
+        // ── Sub-namespaces ──────────────────────────────────────────────────────
+        // Bind getSid so sub-classes always read from this instance's state
+        const getSid = () => this.getSid();
+        this.ab = new StyraAB(this.apiKey, this.mode, this.cacheTTL, this.baseURL, getSid);
+        this.event = new StyraEvent(this.apiKey, this.mode, this.baseURL, getSid);
+    }
+    // ─────────────────────────────────────────────
+    // Init checks (CS mode only, runs once on construction)
+    // ─────────────────────────────────────────────
+    runInitChecks() {
+        const meta = readMeta();
+        if (!meta) {
+            writeMeta(this.apiKey);
+            log.debug("First visit — meta initialised.");
+            return;
+        }
+        // Domain change check
+        const stored = decodedDomain(this.apiKey, meta._d);
+        const current = typeof window !== "undefined" ? window.location.hostname : "";
+        if (stored !== null && stored !== current) {
+            renewalReset(this.apiKey, `domain changed from "${stored}" to "${current}"`);
+            return;
+        }
+        // 15-day renewal check
+        if (Date.now() - meta.issuedAt > RENEWAL_TTL_MS) {
+            renewalReset(this.apiKey, "15-day renewal");
+            return;
+        }
+        log.debug("Session valid — no reset needed.");
+    }
+    // ─────────────────────────────────────────────
+    // SID reader — shared by this class and sub-namespaces
+    // ─────────────────────────────────────────────
+    getSid() {
+        if (this.mode === "ss")
+            return SID_ABSENT;
+        return readSid(this.apiKey);
+    }
+    // ─────────────────────────────────────────────
+    // Public: getVariable
+    // ─────────────────────────────────────────────
+    /**
+     * Fetch a remote config variable by key.
+     * Returns defaultValue (or null) on any error — never throws.
+     *
+     * @param key          — variable identifier, sent as query param
+     * @param defaultValue — returned on error, pause without cache, or missing value
+     * @param revokeAfter  — ms before the request is aborted (default 3000)
+     *
+     * CS mode: pause check → cache check → fetch → cache write
+     * SS mode: always fetches fresh
+     *
+     * Note: unlike ab.getVersion, this does NOT send isCachedLS and is not
+     * subject to AB validity-expiry — that logic is AB-specific.
+     */
+    async getVariable(key, defaultValue, revokeAfter = DEFAULT_REVOKE_AFTER) {
+        var _a, _b;
+        if (!this.apiKey)
+            return defaultValue !== null && defaultValue !== void 0 ? defaultValue : null;
+        const endpoint = "get-variable";
+        const cacheKey = LS.CACHE(key);
+        // Pause check (CS only)
+        if (this.mode === "cs" && isPaused(endpoint)) {
+            log.debug(`getVariable("${key}") skipped — endpoint paused.`);
+            const cached = readCache(this.apiKey, cacheKey, this.cacheTTL);
+            return (_b = (_a = cached) !== null && _a !== void 0 ? _a : defaultValue) !== null && _b !== void 0 ? _b : null;
+        }
+        // Cache check (CS only)
+        if (this.mode === "cs") {
+            const cached = readCache(this.apiKey, cacheKey, this.cacheTTL);
+            if (cached !== null)
+                return cached;
+        }
+        // Fetch
+        const { ok, data } = await httpGet(`${this.baseURL}/${endpoint}`, this.apiKey, this.getSid(), { query: key }, revokeAfter);
+        if (!ok || !data)
+            return defaultValue !== null && defaultValue !== void 0 ? defaultValue : null;
+        processResponse(data, this.apiKey, this.mode, {
+            endpoint,
+            cacheKey,
+            cacheTTL: this.cacheTTL,
+        });
+        if (!data.success || data.value == null)
+            return defaultValue !== null && defaultValue !== void 0 ? defaultValue : null;
+        return data.value;
+    }
+    // ─────────────────────────────────────────────
+    // Public: cache utilities (CS mode only)
+    // ─────────────────────────────────────────────
+    /**
+     * Evict a single variable key from the cache.
+     * No-op in SS mode.
+     */
+    evictCache(key) {
+        if (this.mode === "ss") {
+            log.warn("evictCache() has no effect in SS mode.");
+            return;
+        }
+        lsRemove(LS.CACHE(key));
+        log.debug(`Cache evicted for key "${key}"`);
+    }
+    /**
+     * Clear all Styra variable and A/B cache entries.
+     * Does NOT touch sid, events, paused, or meta.
+     * No-op in SS mode.
+     */
+    clearAllCache() {
+        if (this.mode === "ss") {
+            log.warn("clearAllCache() has no effect in SS mode.");
+            return;
+        }
+        try {
+            Object.keys(localStorage)
+                .filter((k) => k.startsWith("styra::cache::") || k.startsWith("styra::ab::"))
+                .forEach(lsRemove);
+            log.info("All Styra cache cleared.");
+        }
+        catch (err) {
+            log.warn(`clearAllCache() failed: ${err}`);
+        }
+    }
+    // ─────────────────────────────────────────────
+    // Public: session utilities
+    // ─────────────────────────────────────────────
+    /**
+     * Clear the stored SID.
+     * Next request will send sid: "none" and receive a fresh SID from the backend.
+     * Useful for logout flows.
+     * No-op in SS mode.
+     */
+    clearSID() {
+        if (this.mode === "ss") {
+            log.warn("clearSID() has no effect in SS mode.");
+            return;
+        }
+        lsRemove(LS.SID);
+        log.debug("SID cleared — next request will fetch a new one.");
+    }
+    /**
+     * Clear the unique events registry.
+     * After this, all unique events (ab.track + event.track) can fire again.
+     * No-op in SS mode.
+     */
+    clearEvents() {
+        if (this.mode === "ss") {
+            log.warn("clearEvents() has no effect in SS mode.");
+            return;
+        }
+        lsRemove(LS.EVENTS);
+        log.debug("Events registry cleared.");
+    }
+    /**
+     * Manually remove a specific endpoint from the paused registry.
+     * The next call to that endpoint will go through to the API immediately.
+     * No-op in SS mode.
+     */
+    unpause(endpoint) {
+        if (this.mode === "ss") {
+            log.warn("unpause() has no effect in SS mode.");
+            return;
+        }
+        clearPausedEntry(endpoint);
+    }
+}
+exports.Styra = Styra;
+Styra.DEFAULT_BASE_URL = "https://styra-service-backend.onrender.com/web-config/api/v1.0";

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./client";

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./client"), exports);

package/package.json

@@ -0,0 +1,19 @@
+  {
+    "name": "styra-js",
+    "version": "1.5.2",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+      "dist"
+    ],
+    "scripts": {
+      "build": "tsc"
+    },
+    "dependencies": {
+      "axios": "^1.6.0"
+    },
+    "devDependencies": {
+      "typescript": "^5.9.3"
+    }
+  }