@shelbyb/daywalker-sdk 0.1.4 → 0.3.0

package/dist/client.js

@@ -1,5 +1,5 @@
 import { resolveConfig } from "./config.js";
-import { loadSigningKey, signRequest, verifyJwtLease, maskSecret, redactSecrets, } from "./crypto/index.js";
+import { loadSigningKey, signRequest, verifyJwtLease, maskSecret, redactSecrets, sha256Base64Url, } from "./crypto/index.js";
 import { DaywalkerAuthError, DaywalkerError, DaywalkerRateLimitError, } from "./types.js";
 function parseRetryAfter(headerValue) {
     if (!headerValue)
@@ -23,6 +23,8 @@ function generateNonce() {
         bin += String.fromCharCode(b);
     return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
+/** Validation results kept in memory; the least recently used are evicted past this. */
+export const MAX_VALIDATION_CACHE_ENTRIES = 1000;
 export class Daywalker {
     _config;
     _rawConfig;
@@ -68,6 +70,11 @@ export class Daywalker {
     async fetch(path, init) {
         const authUrl = this._config.authUrl;
         const url = new URL(path, authUrl);
+        // Absolute URLs to other hosts would otherwise receive the API key and a valid signature.
+        const authOrigin = new URL(authUrl).origin;
+        if (url.origin !== authOrigin) {
+            throw new DaywalkerError(`Refusing to send Daywalker credentials to ${url.origin}; fetch() only targets ${authOrigin}`);
+        }
         const method = (init?.method ?? (init?.body !== undefined ? "POST" : "GET")).toUpperCase();
         const doFetch = this._rawConfig.fetch ?? globalThis.fetch;
         const retryOpts = {
@@ -157,9 +164,31 @@ export class Daywalker {
             return res;
         }
     }
+    _cacheGet(key) {
+        const entry = this._cache.get(key);
+        if (!entry)
+            return undefined;
+        this._cache.delete(key);
+        if (entry.expiresAt <= Date.now())
+            return undefined;
+        this._cache.set(key, entry); // most recently used goes last
+        return entry.result;
+    }
+    _cacheSet(key, result, ttlMs, notAfterMs = Infinity) {
+        const expiresAt = Math.min(Date.now() + ttlMs, notAfterMs);
+        if (expiresAt <= Date.now())
+            return;
+        this._cache.delete(key);
+        this._cache.set(key, { result, expiresAt });
+        while (this._cache.size > MAX_VALIDATION_CACHE_ENTRIES) {
+            this._cache.delete(this._cache.keys().next().value);
+        }
+    }
     /**
-     * Validates incoming bearer tokens with memory caching and discriminated union return.
+     * Validates an incoming bearer token with memory caching and discriminated union return.
      * Supports zero-egress offline verification for JWT token leases when Daywalker's public key is configured.
+     * A missing token is always rejected (401); it never falls back to this service's own API key —
+     * use `validateServiceKey()` for that.
      */
     async validateToken(tokenOrOptions, options) {
         let token;
@@ -173,7 +202,7 @@ export class Daywalker {
             offlineOnly = options?.offlineOnly ?? false;
         }
         else {
-            token = tokenOrOptions?.token ?? this._config.apiKey ?? undefined;
+            token = tokenOrOptions?.token ?? undefined;
             serviceSlug = (tokenOrOptions?.serviceSlug ?? this._config.serviceSlug ?? "").toLowerCase();
             forceRefresh = tokenOrOptions?.forceRefresh ?? false;
             offlineOnly = tokenOrOptions?.offlineOnly ?? false;
@@ -181,15 +210,16 @@ export class Daywalker {
         if (!token) {
             return {
                 ok: false,
-                error: "CONFIGURATION_ERROR",
-                status: 400,
+                error: "INVALID_TOKEN",
+                status: 401,
                 message: "Missing token to validate",
             };
         }
-        const cacheKey = `${serviceSlug || "default"}:${token}`;
-        const cached = this._cache.get(cacheKey);
-        if (!forceRefresh && cached && cached.expiresAt > Date.now()) {
-            return cached.result;
+        // Keyed by a hash so raw tokens are never held as cache keys.
+        const cacheKey = `${serviceSlug || "default"}:${await sha256Base64Url(token)}`;
+        const cached = forceRefresh ? undefined : this._cacheGet(cacheKey);
+        if (cached) {
+            return cached;
         }
         // Check for offline JWT lease verification
         if (this._config.daywalkerPublicKey && token.split(".").length === 3) {
@@ -197,6 +227,7 @@ export class Daywalker {
                 token,
                 publicKey: this._config.daywalkerPublicKey,
                 expectedServiceSlug: serviceSlug || undefined,
+                expectedIssuer: this._config.leaseIssuer ?? undefined,
             });
             if (jwtResult.valid && jwtResult.payload) {
                 const payload = jwtResult.payload;
@@ -220,7 +251,8 @@ export class Daywalker {
                     },
                 };
                 if (this._config.cacheTtlMs > 0) {
-                    this._cache.set(cacheKey, { result, expiresAt: Date.now() + this._config.cacheTtlMs });
+                    // Never cache a lease past its own expiry.
+                    this._cacheSet(cacheKey, result, this._config.cacheTtlMs, payload.exp * 1000);
                 }
                 return result;
             }
@@ -256,7 +288,7 @@ export class Daywalker {
         const negTtl = this._config.negativeCacheTtlMs;
         const fail = (result) => {
             if (negTtl > 0 && result.error !== "RATE_LIMITED" && result.error !== "NETWORK_ERROR") {
-                this._cache.set(cacheKey, { result, expiresAt: Date.now() + negTtl });
+                this._cacheSet(cacheKey, result, negTtl);
             }
             return result;
         };
@@ -288,7 +320,7 @@ export class Daywalker {
                     data,
                 };
                 if (this._config.cacheTtlMs > 0) {
-                    this._cache.set(cacheKey, { result, expiresAt: Date.now() + this._config.cacheTtlMs });
+                    this._cacheSet(cacheKey, result, this._config.cacheTtlMs);
                 }
                 return result;
             }
@@ -326,6 +358,21 @@ export class Daywalker {
             };
         }
     }
+    /**
+     * Service health check: validates this service's own configured API key (DAYWALKER_API_KEY).
+     * Never use this to authenticate an incoming request.
+     */
+    async validateServiceKey(options) {
+        if (!this._config.apiKey) {
+            return {
+                ok: false,
+                error: "CONFIGURATION_ERROR",
+                status: 500,
+                message: "DAYWALKER_API_KEY is not set",
+            };
+        }
+        return this.validateToken(this._config.apiKey, options);
+    }
     /**
      * Throws DaywalkerAuthError or DaywalkerRateLimitError if token is invalid or rate limited.
      */

package/dist/config.d.ts

@@ -8,6 +8,7 @@ export interface ResolvedConfig {
     domain: string | null;
     domainSource: string | null;
     daywalkerPublicKey: string | PublicJwk | null;
+    leaseIssuer: string | null;
     authUrl: string;
     cacheTtlMs: number;
     negativeCacheTtlMs: number;
@@ -19,4 +20,9 @@ export interface ResolvedConfig {
  * the internet (localhost, 0.0.0.0, IP addresses, single labels).
  */
 export declare function publicHostname(value: string | undefined | null): string | null;
+/**
+ * Throws unless `value` is an https: URL (http: is allowed only for localhost / 127.0.0.1 / [::1]),
+ * so API keys, SDK keys and write keys never travel in cleartext.
+ */
+export declare function assertSecureUrl(name: string, value: string): void;
 export declare function resolveConfig(options?: DaywalkerConfig): ResolvedConfig;

package/dist/config.js

@@ -45,6 +45,25 @@ export function publicHostname(value) {
     }
     return DOMAIN_PATTERN.test(host) ? host : null;
 }
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/**
+ * Throws unless `value` is an https: URL (http: is allowed only for localhost / 127.0.0.1 / [::1]),
+ * so API keys, SDK keys and write keys never travel in cleartext.
+ */
+export function assertSecureUrl(name, value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${name} must be an absolute https:// URL (got "${value}")`);
+    }
+    if (url.protocol === "https:")
+        return;
+    if (url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname))
+        return;
+    throw new Error(`${name} must use https:// (http:// is only allowed for localhost); got "${value}"`);
+}
 export function resolveConfig(options = {}) {
     const env = options.env ?? (typeof process !== "undefined" && process.env ? process.env : {});
     const problems = [];
@@ -80,7 +99,9 @@ export function resolveConfig(options = {}) {
         }
     }
     const daywalkerPublicKey = options.daywalkerPublicKey ?? (env.DAYWALKER_PUBLIC_KEY ? env.DAYWALKER_PUBLIC_KEY.trim() : null);
+    const leaseIssuer = (options.leaseIssuer ?? env.DAYWALKER_LEASE_ISSUER ?? "").trim() || null;
     const authUrl = (options.authUrl ?? env.DAYWALKER_AUTH_URL ?? "https://auth.daywalker.dev").replace(/\/+$/, "");
+    assertSecureUrl("authUrl", authUrl);
     const cacheTtlMs = options.cacheTtlMs ?? 60_000;
     const negativeCacheTtlMs = options.negativeCacheTtlMs ?? 3_000;
     const maxRetries = options.maxRetries ?? (options.retry?.maxRetries ?? 3);
@@ -93,6 +114,7 @@ export function resolveConfig(options = {}) {
         domain,
         domainSource,
         daywalkerPublicKey,
+        leaseIssuer,
         authUrl,
         cacheTtlMs,
         negativeCacheTtlMs,

package/dist/crypto/signatures.d.ts

@@ -12,14 +12,21 @@ export declare function normalizePath(rawPath: string): string;
  * Validates that an identifier (keyId, serviceSlug, etc.) contains only safe alphanumeric/hyphen characters.
  */
 export declare function assertSafeIdentifier(name: string, value: string): void;
+/** Upper bound on remembered signatures; the oldest entries are evicted past this. */
+export declare const REPLAY_CACHE_MAX_ENTRIES = 10000;
 /**
- * In-memory LRU / sliding cache for nonces / signature replay protection.
+ * In-memory replay cache, keyed on keyid + decoded signature bytes (so re-encodings of the
+ * same signature collide). Insertion-ordered, so eviction drops the oldest entries first.
  */
-declare class SignatureReplayCache {
+export declare class SignatureReplayCache {
+    private readonly maxEntries;
     private seen;
-    private readonly ttlMs;
-    constructor(ttlSeconds?: number);
-    checkAndRecord(signatureId: string): boolean;
+    constructor(maxEntries?: number);
+    get size(): number;
+    /** True when the key was recorded and has not expired yet (a replay). */
+    has(key: string, now?: number): boolean;
+    record(key: string, ttlMs: number, now?: number): void;
+    clear(): void;
 }
 export declare const globalReplayCache: SignatureReplayCache;
 export type { SignedHeaders, SignRequestParams, VerifySignatureParams, VerifySignatureResult, };
@@ -53,14 +60,20 @@ export declare function signRequest(params: SignRequestParams): Promise<SignedHe
  * Verify an incoming RFC 9421 HTTP Message Signature.
  */
 export declare function verifyRequestSignature(params: VerifySignatureParams): Promise<VerifySignatureResult>;
+/** Clock skew tolerated on JWT lease `exp` / `nbf`. */
+export declare const JWT_CLOCK_SKEW_SECONDS = 60;
 /**
  * Zero-egress offline verification for asymmetric JWT token leases.
+ * Requires a numeric `exp` and an audience (`aud` or `serviceSlug`) equal to `expectedServiceSlug`;
+ * a verifier without an expected slug rejects every lease. `iss` is checked when `expectedIssuer` is set.
  */
 export declare function verifyJwtLease(params: {
     token: string;
     publicKey: string | PublicJwk | CryptoKey;
     expectedServiceSlug?: string;
+    expectedIssuer?: string;
     currentTime?: number;
+    clockSkewSeconds?: number;
 }): Promise<{
     valid: boolean;
     payload?: Record<string, unknown>;

package/dist/crypto/signatures.js

@@ -1,6 +1,7 @@
-import { base64ToBytes, base64UrlToBytes, bytesToBase64, stringToUtf8, utf8ToString, timingSafeEqualString, } from "./encoding.js";
+import { base64ToBytes, base64UrlToBytes, bytesToBase64, bytesToHex, stringToUtf8, utf8ToString, timingSafeEqualString, } from "./encoding.js";
 import { computeContentDigest } from "./digest.js";
 import { loadPublicKey, loadSigningKey } from "./keys.js";
+import { assertSecureUrl } from "../config.js";
 export const SIGNATURE_VERSION = "rfc9421";
 export const SIGNATURE_LABEL = "sig1";
 export const SIGNATURE_ALG = "ed25519";
@@ -30,29 +31,41 @@ export function assertSafeIdentifier(name, value) {
         throw new Error(`Invalid ${name}: must be 1-128 safe characters (alphanumeric, '_', '-', '.')`);
     }
 }
+/** Upper bound on remembered signatures; the oldest entries are evicted past this. */
+export const REPLAY_CACHE_MAX_ENTRIES = 10_000;
 /**
- * In-memory LRU / sliding cache for nonces / signature replay protection.
+ * In-memory replay cache, keyed on keyid + decoded signature bytes (so re-encodings of the
+ * same signature collide). Insertion-ordered, so eviction drops the oldest entries first.
  */
-class SignatureReplayCache {
+export class SignatureReplayCache {
+    maxEntries;
     seen = new Map();
-    ttlMs;
-    constructor(ttlSeconds = 360) {
-        this.ttlMs = ttlSeconds * 1000;
-    }
-    checkAndRecord(signatureId) {
-        const now = Date.now();
-        if (this.seen.size > 5000) {
-            for (const [k, exp] of this.seen.entries()) {
-                if (exp <= now)
-                    this.seen.delete(k);
-            }
+    constructor(maxEntries = REPLAY_CACHE_MAX_ENTRIES) {
+        this.maxEntries = maxEntries;
+    }
+    get size() {
+        return this.seen.size;
+    }
+    /** True when the key was recorded and has not expired yet (a replay). */
+    has(key, now = Date.now()) {
+        const expiresAt = this.seen.get(key);
+        return expiresAt !== undefined && expiresAt > now;
+    }
+    record(key, ttlMs, now = Date.now()) {
+        this.seen.delete(key);
+        this.seen.set(key, now + ttlMs);
+        if (this.seen.size <= this.maxEntries)
+            return;
+        for (const [k, exp] of this.seen) {
+            if (exp <= now)
+                this.seen.delete(k);
         }
-        const expiresAt = this.seen.get(signatureId);
-        if (expiresAt && expiresAt > now) {
-            return false; // Replay detected
+        while (this.seen.size > this.maxEntries) {
+            this.seen.delete(this.seen.keys().next().value);
         }
-        this.seen.set(signatureId, now + this.ttlMs);
-        return true;
+    }
+    clear() {
+        this.seen.clear();
     }
 }
 export const globalReplayCache = new SignatureReplayCache();
@@ -176,11 +189,16 @@ export async function verifyRequestSignature(params) {
         }
         seenComponents.add(c);
     }
-    const sigMatch = signatureHeader.match(new RegExp(`(?:^|,\\s*)${SIGNATURE_LABEL}=:([A-Za-z0-9+/=_-]+):`));
-    if (!sigMatch) {
+    // RFC 8941 byte sequence (`:base64:`), standard alphabet with padding only, so each signature
+    // has exactly one accepted encoding.
+    const sigMatch = signatureHeader.match(new RegExp(`(?:^|,\\s*)${SIGNATURE_LABEL}=:([A-Za-z0-9+/]*={0,2}):(?=\\s*(?:,|$))`));
+    if (!sigMatch || sigMatch[1].length % 4 !== 0) {
+        return { valid: false, error: `Signature header does not contain valid ${SIGNATURE_LABEL} byte sequence` };
+    }
+    const signatureBytes = base64ToBytes(sigMatch[1]);
+    if (bytesToBase64(signatureBytes) !== sigMatch[1]) {
         return { valid: false, error: `Signature header does not contain valid ${SIGNATURE_LABEL} byte sequence` };
     }
-    const signatureBase64 = sigMatch[1].trim();
     const createdMatch = signatureParams.match(/created=(\d+)/);
     if (!createdMatch) {
         return { valid: false, error: "Signature-Input missing created timestamp" };
@@ -191,12 +209,6 @@ export async function verifyRequestSignature(params) {
     if (Math.abs(now - created) > maxSkew) {
         return { valid: false, error: `Signature timestamp expired or clock skew too large (created=${created}, now=${now})` };
     }
-    if (params.replayCheck !== false) {
-        const replayKey = `${signatureBase64}:${created}`;
-        if (!globalReplayCache.checkAndRecord(replayKey)) {
-            return { valid: false, error: "Replay detected: request signature was already presented" };
-        }
-    }
     const keyidMatch = signatureParams.match(/keyid="([^"]+)"/);
     const keyid = keyidMatch ? keyidMatch[1] : undefined;
     if (keyid) {
@@ -207,6 +219,12 @@ export async function verifyRequestSignature(params) {
             return { valid: false, error: e.message };
         }
     }
+    // Entries must outlive the whole acceptance window (created ± maxSkew).
+    const replayKey = `${keyid ?? ""}:${bytesToHex(signatureBytes)}`;
+    const replayTtlMs = 2 * Math.max(maxSkew, 1) * 1000;
+    if (params.replayCheck !== false && globalReplayCache.has(replayKey)) {
+        return { valid: false, error: "Replay detected: request signature was already presented" };
+    }
     const algMatch = signatureParams.match(/alg="([^"]+)"/);
     const alg = algMatch ? algMatch[1] : undefined;
     if (alg && alg.toLowerCase() !== "ed25519" && alg.toLowerCase() !== "eddsa") {
@@ -230,21 +248,29 @@ export async function verifyRequestSignature(params) {
     });
     try {
         const { publicKey } = await loadPublicKey(params.publicKey);
-        const signatureBytes = signatureBase64.includes("-") || signatureBase64.includes("_")
-            ? base64UrlToBytes(signatureBase64)
-            : base64ToBytes(signatureBase64);
         const isValid = await globalThis.crypto.subtle.verify("Ed25519", publicKey, signatureBytes, stringToUtf8(signatureBase));
         if (!isValid) {
             return { valid: false, error: "Cryptographic signature verification failed" };
         }
+        // Record only verified signatures; re-check synchronously in case a concurrent copy won.
+        if (params.replayCheck !== false) {
+            if (globalReplayCache.has(replayKey)) {
+                return { valid: false, error: "Replay detected: request signature was already presented" };
+            }
+            globalReplayCache.record(replayKey, replayTtlMs);
+        }
         return { valid: true, keyid };
     }
     catch (err) {
         return { valid: false, error: `Verification error: ${err.message}` };
     }
 }
+/** Clock skew tolerated on JWT lease `exp` / `nbf`. */
+export const JWT_CLOCK_SKEW_SECONDS = 60;
 /**
  * Zero-egress offline verification for asymmetric JWT token leases.
+ * Requires a numeric `exp` and an audience (`aud` or `serviceSlug`) equal to `expectedServiceSlug`;
+ * a verifier without an expected slug rejects every lease. `iss` is checked when `expectedIssuer` is set.
  */
 export async function verifyJwtLease(params) {
     try {
@@ -257,9 +283,15 @@ export async function verifyJwtLease(params) {
         const payloadJson = utf8ToString(base64UrlToBytes(payloadB64));
         const header = JSON.parse(headerJson);
         const payload = JSON.parse(payloadJson);
+        if (!header || typeof header !== "object" || !payload || typeof payload !== "object" || Array.isArray(payload)) {
+            return { valid: false, error: "JWT header and payload must be JSON objects" };
+        }
         if (header.alg !== "EdDSA" && header.alg !== "ed25519") {
             return { valid: false, error: `Unsupported JWT alg: ${header.alg}` };
         }
+        if (header.typ !== undefined && String(header.typ).toUpperCase() !== "JWT") {
+            return { valid: false, error: `Unsupported JWT typ: ${header.typ}` };
+        }
         const { publicKey } = await loadPublicKey(params.publicKey);
         const signedData = stringToUtf8(`${headerB64}.${payloadB64}`);
         const signatureBytes = base64UrlToBytes(signatureB64);
@@ -268,20 +300,41 @@ export async function verifyJwtLease(params) {
             return { valid: false, error: "JWT signature verification failed" };
         }
         const now = params.currentTime ?? Math.floor(Date.now() / 1000);
-        if (payload.exp && typeof payload.exp === "number" && payload.exp < now) {
+        const skew = Math.max(0, Math.min(params.clockSkewSeconds ?? JWT_CLOCK_SKEW_SECONDS, 300));
+        if (typeof payload.exp !== "number" || !Number.isFinite(payload.exp)) {
+            return { valid: false, error: "JWT token lease has no numeric exp claim" };
+        }
+        if (payload.exp + skew <= now) {
             return { valid: false, error: "JWT token lease has expired" };
         }
-        if (payload.nbf && typeof payload.nbf === "number" && payload.nbf > now + 60) {
+        if (payload.nbf !== undefined && (typeof payload.nbf !== "number" || payload.nbf > now + skew)) {
             return { valid: false, error: "JWT token lease not active yet" };
         }
-        if (params.expectedServiceSlug) {
-            const tokenSlug = (payload.serviceSlug || payload.aud || "").toLowerCase();
-            if (tokenSlug && tokenSlug !== params.expectedServiceSlug.toLowerCase()) {
-                return {
-                    valid: false,
-                    error: `JWT audience mismatch: expected ${params.expectedServiceSlug}, got ${tokenSlug}`,
-                };
-            }
+        const expected = params.expectedServiceSlug?.trim().toLowerCase();
+        if (!expected) {
+            return { valid: false, error: "JWT audience cannot be checked: no expected service slug is configured" };
+        }
+        const audiences = [];
+        if (payload.serviceSlug !== undefined)
+            audiences.push(String(payload.serviceSlug));
+        if (Array.isArray(payload.aud))
+            audiences.push(...payload.aud.map(String));
+        else if (payload.aud !== undefined)
+            audiences.push(String(payload.aud));
+        if (audiences.length === 0) {
+            return { valid: false, error: "JWT token lease has no aud or serviceSlug claim" };
+        }
+        const serviceSlugOk = payload.serviceSlug === undefined || String(payload.serviceSlug).toLowerCase() === expected;
+        const audOk = payload.aud === undefined ||
+            (Array.isArray(payload.aud) ? payload.aud : [payload.aud]).some((a) => String(a).toLowerCase() === expected);
+        if (!serviceSlugOk || !audOk) {
+            return {
+                valid: false,
+                error: `JWT audience mismatch: expected ${expected}, got ${audiences.join(", ").toLowerCase()}`,
+            };
+        }
+        if (params.expectedIssuer && payload.iss !== params.expectedIssuer) {
+            return { valid: false, error: `JWT issuer mismatch: expected ${params.expectedIssuer}, got ${payload.iss ?? "(none)"}` };
         }
         return { valid: true, payload };
     }
@@ -294,6 +347,12 @@ export async function verifyJwtLease(params) {
  */
 export async function registerPublicKey(params) {
     const authUrl = (params.authUrl ?? "https://auth.daywalker.dev").replace(/\/+$/, "");
+    try {
+        assertSecureUrl("authUrl", authUrl);
+    }
+    catch (err) {
+        return { ok: false, status: 0, error: err.message };
+    }
     const registerUrl = `${authUrl}/api/v1/keys/register`;
     const doFetch = params.fetchFn ?? globalThis.fetch;
     if (!params.domain) {

package/dist/flags/client.d.ts

@@ -0,0 +1,102 @@
+import type { ContextInput, EvaluationReason, FlagValue } from "./engine/index.js";
+import { type Logger } from "./common/index.js";
+export type { ContextInput, EvaluationReason, FlagValue, Logger };
+export interface FlagState {
+    value: FlagValue;
+    variation: number | null;
+    version: number;
+    reason?: EvaluationReason;
+    trackEvents?: boolean;
+    trackReason?: boolean;
+}
+export type FlagSet = Record<string, FlagState>;
+export interface ClientOptions {
+    /** Base URL of your DevPulse deployment, e.g. https://flags.example.com (https required except on localhost). */
+    baseUrl: string;
+    /** Receive changes in real time over Server-Sent Events (default true). */
+    streaming?: boolean;
+    /** Initial flag values, e.g. from the Node SDK's allFlagsState() for SSR. */
+    bootstrap?: FlagSet | Record<string, FlagValue>;
+    /** Secure mode hash for the context (HMAC-SHA256 computed on your server). */
+    hash?: string;
+    /** Include evaluation reasons (for variationDetail). */
+    withReasons?: boolean;
+    sendEvents?: boolean;
+    flushIntervalMs?: number;
+    privateAttributes?: string[];
+    allAttributesPrivate?: boolean;
+    /** Cache the last flags in localStorage and use them while loading. */
+    cache?: boolean;
+    fetch?: typeof fetch;
+    logger?: Logger;
+}
+export interface EvaluationDetail<T = FlagValue> {
+    value: T;
+    variationIndex: number | null;
+    reason: EvaluationReason | null;
+}
+type Listener = (...args: unknown[]) => void;
+/**
+ * A client for one evaluation context. Fetches evaluated flags, keeps them
+ * current over SSE, and reports analytics.
+ *
+ *   const client = createClient("<client-side id>", { key: user.id }, { baseUrl });
+ *   await client.waitForInitialization();
+ *   client.on("change:new-checkout", (value) => render(value));
+ *   client.variation("new-checkout", false);
+ */
+export declare class DevPulseClient {
+    private readonly clientSideId;
+    private context;
+    private readonly options;
+    private flags;
+    private listeners;
+    private stream;
+    private events;
+    private ready;
+    private resolveReady;
+    private rejectReady;
+    private initialized;
+    private closed;
+    private readonly logger;
+    private readonly base;
+    constructor(clientSideId: string, context: ContextInput, options: ClientOptions);
+    private query;
+    private start;
+    private fetchFlags;
+    private onStreamEvent;
+    private replaceAll;
+    private flag;
+    private markReady;
+    private fail;
+    private emitChanges;
+    private cacheKey;
+    private readCache;
+    private writeCache;
+    /** Resolves once flags are loaded (or rejects on a fatal error such as an invalid client-side ID). */
+    waitForInitialization(opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    get isInitialized(): boolean;
+    variation<T extends FlagValue>(key: string, defaultValue: T): T;
+    variationDetail<T extends FlagValue>(key: string, defaultValue: T): EvaluationDetail<T>;
+    boolVariation(key: string, defaultValue: boolean): boolean;
+    stringVariation(key: string, defaultValue: string): string;
+    numberVariation(key: string, defaultValue: number): number;
+    jsonVariation<T extends FlagValue>(key: string, defaultValue: T): T;
+    /** All flag values (doesn't record evaluations). */
+    allFlags(): Record<string, FlagValue>;
+    /** Switch to a different context (e.g. after login). Resolves with the new flags. */
+    identify(context: ContextInput, opts?: {
+        hash?: string;
+    }): Promise<Record<string, FlagValue>>;
+    getContext(): ContextInput;
+    /** Record a custom event for metrics and experiments. */
+    track(key: string, data?: unknown, metricValue?: number): void;
+    on(event: "ready" | "failed" | "change" | `change:${string}`, fn: Listener): () => void;
+    off(event: string, fn: Listener): void;
+    private emit;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function createClient(clientSideId: string, context: ContextInput, options: ClientOptions): DevPulseClient;