@guidelytech/flags 0.0.0-stage → 0.7.0

package/dist/index.d.cts

@@ -0,0 +1,314 @@
+import { JsonValue, EvaluationResult, Attributes, FlagsPayload, RemoteEvaluationResponse, EncryptedFlagsPayload, StickyBucketStore, ExperimentAssignment, StickyAssignments } from './evaluate.cjs';
+export { ARRAY_OPERATORS, ATTRIBUTE_OPERATORS, AttributeCondition, AttributeOperator, BOOLEAN_OPERATORS, Condition, ConditionSegment, DATE_OPERATORS, EvaluateOptions, EvaluationReason, ExperimentNamespace, ExperimentRule, ExperimentVariation, FlagComparisonOperator, FlagCondition, FlagDefinition, FlagEventsBatch, FlagRule, FlagRuleType, FlagValueType, ForceRule, GroupCondition, HASHED_OPERATORS, HoldoutDefinition, ListSegment, NUMBER_OPERATORS, PRESENCE_OPERATORS, Prerequisite, RampStep, RolloutRule, RuleSchedule, SEMVER_OPERATORS, SegmentCondition, SegmentDefinition, SplitBucket, SplitRule, TEXT_OPERATORS, compareSemver, effectiveCoverage, evaluateAllFlags, evaluateFlag, fnv1a32, hashBucket, hashConfidential, hashConfidentialAffix, instantOf, isOn, isScheduleActive, jsonEquals, lookupAttribute, numberOf, parseSemver, sha256Hex, textOf } from './evaluate.cjs';
+
+/** The value type a getter returns for a fallback: literals widen (`"blue"` → `string`), JSON types stay. */
+type FlagValue<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
+/** An evaluation result whose `value` is the caller's fallback when the flag is missing, null or of another type. */
+interface FlagDetails<T = JsonValue> extends Omit<EvaluationResult, "value"> {
+    value: T;
+    /** The fallback was served (flag missing, value null or of the wrong type). */
+    usedFallback: boolean;
+}
+/** Synchronous flag getters. They never throw: problems give the fallback. */
+interface FlagsEvaluator {
+    /** Boolean flag value; `fallback` (default `false`) when missing or not a boolean. */
+    isEnabled(key: string, fallback?: boolean): boolean;
+    /** Flag value; `fallback` when missing, null or of a different JSON type than `fallback`. */
+    getValue<T extends JsonValue>(key: string, fallback: T): FlagValue<T>;
+    getString(key: string, fallback: string): string;
+    getNumber(key: string, fallback: number): number;
+    getBoolean(key: string, fallback: boolean): boolean;
+    /** Object or array value. */
+    getJson<T = JsonValue>(key: string, fallback: T): T;
+    /** Value plus why it was served (reason, rule, variation, experiment). */
+    getDetails<T extends JsonValue>(key: string, fallback: T): FlagDetails<FlagValue<T>>;
+    /** Every flag's value for these attributes (no exposures or usage are recorded). */
+    getAll(): Record<string, JsonValue>;
+    /** The attributes these getters evaluate with. */
+    getAttributes(): Attributes;
+}
+/** What framework bindings read from: an evaluator that can say whether it has loaded and notify changes. */
+interface FlagsReader extends FlagsEvaluator {
+    isReady(): boolean;
+    /** Calls `listener` whenever values may have changed. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+}
+interface StaticFlagsInput {
+    /** A payload (or remote-evaluation results) from `client.getPayload()` on the server. */
+    payload?: FlagsPayload | RemoteEvaluationResponse | unknown;
+    attributes?: Attributes;
+    now?: Date | number;
+}
+/**
+ * A network-free, read-only snapshot over a bootstrap payload. Framework bindings render with it
+ * on the server and during hydration so the HTML matches; it records no exposures or usage.
+ * Encrypted payloads cannot be read synchronously and give fallbacks.
+ */
+declare function createStaticFlags(input?: StaticFlagsInput): FlagsReader;
+
+declare const FLAGS_SDK_NAME = "@guidelytech/flags";
+declare const FLAGS_SDK_VERSION = "0.7.0";
+declare const DEFAULT_FLAGS_API_URL = "https://guidelytech.com";
+/**
+ * - `auto` — fetch at start, then every `pollIntervalSeconds`.
+ * - `lazy` — fetch when a flag is read and the cache is older than `cacheTtlSeconds` (serverless, edge).
+ * - `manual` — only `refresh()` fetches.
+ * - `stream` — server-sent events push changes; polls while the stream is down.
+ */
+type PollingMode = "auto" | "lazy" | "manual" | "stream";
+/** `localOnly`: never fetch, serve overrides only. `localOverRemote`: overrides win. `remoteOverLocal`: overrides fill in flags missing remotely. */
+type OverrideBehaviour = "localOnly" | "localOverRemote" | "remoteOverLocal";
+/** Key/value storage for the last payload: `localStorage`-like or AsyncStorage-like (sync or async). */
+interface FlagsStorage {
+    getItem(key: string): string | null | undefined | Promise<string | null | undefined>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem?(key: string): void | Promise<void>;
+}
+interface FlagsLogger {
+    debug?(...args: unknown[]): void;
+    warn?(...args: unknown[]): void;
+    error?(...args: unknown[]): void;
+}
+/** What a bootstrap / `getPayload()` can hold. */
+type FlagsBootstrap = FlagsPayload | EncryptedFlagsPayload | RemoteEvaluationResponse;
+interface FlagsClientOptions {
+    /** Environment public key `pk_…` (the `projectId` used for tracking) or, on servers only, a secret `gly_sk_…` key. */
+    sdkKey?: string;
+    /** Alias of `sdkKey`. */
+    projectId?: string;
+    /** Base URL of your Guidely deployment (default `https://guidelytech.com`). */
+    apiUrl?: string;
+    /** `development` | `staging` | `production`. Required with a `gly_sk_` key. */
+    environment?: string;
+    /** Default attributes, merged under per-call (`forUser`) attributes. */
+    attributes?: Attributes;
+    /**
+     * Attributes supplied by a Guidely SDK integration (identity, page, device). App attributes
+     * (`attributes`, `setAttributes`) are merged over them.
+     */
+    contextAttributes?: Attributes;
+    pollingMode?: PollingMode;
+    /** `auto` / `stream` fallback polling interval (default 60). */
+    pollIntervalSeconds?: number;
+    /** `lazy` cache lifetime (default 60). */
+    cacheTtlSeconds?: number;
+    /** Bootstrap: a payload (plain or encrypted) or remote-evaluation results, used immediately. */
+    payload?: FlagsBootstrap | null;
+    /** Bootstrap for remote evaluation: `{ version, flags }` or a map of results. */
+    remoteResults?: RemoteEvaluationResponse | Record<string, EvaluationResult> | null;
+    /** Base64 AES-256 key for environments that encrypt their payload. */
+    decryptionKey?: string;
+    /** Ask the server to evaluate (`POST /flags/evaluate`) instead of downloading rules. Needed when the environment hides rules. */
+    remoteEval?: boolean;
+    /** Debounce for re-evaluating remotely after attribute changes (default 50 ms). */
+    remoteEvalDebounceMs?: number;
+    /** Local flag values (tests, QA, kill switches) applied per `overrideBehaviour`. */
+    overrides?: Record<string, JsonValue> | null;
+    overrideBehaviour?: OverrideBehaviour;
+    /** Keeps experiment assignments stable (`InMemoryStickyBucketStore`, `LocalStorageStickyBucketStore`). */
+    stickyBucketService?: StickyBucketStore;
+    /** Persists the last payload. Default: `localStorage` in browsers, none elsewhere. `false` disables. */
+    storage?: FlagsStorage | null | false;
+    /** Browser only: read `?guidely_flags=key:value,key2:"text"` from the URL as overrides (QA). */
+    enableUrlOverrides?: boolean;
+    /** Called once per (experiment, user, variation) when a user is bucketed into an experiment. */
+    trackingCallback?: (experiment: ExperimentAssignment, result: EvaluationResult) => void;
+    /** Send experiment exposures to Guidely (`POST /flags/events`). Default: `true` unless `trackingCallback` is set. */
+    trackExposures?: boolean;
+    /** Send aggregated evaluation counts to Guidely at most every 60 s (default `true`). */
+    reportUsage?: boolean;
+    onReady?: () => void;
+    /** New payload (or remote results) applied. */
+    onChange?: (data: FlagsPayload | RemoteEvaluationResponse) => void;
+    onFlagEvaluated?: (result: EvaluationResult) => void;
+    onError?: (error: Error) => void;
+    /** Start without network activity (cached / bootstrapped data keeps serving). */
+    offline?: boolean;
+    fetch?: typeof fetch;
+    /**
+     * Defaults to `console`: `error` for failed requests (once per streak), `warn` for misuse and,
+     * in development, reads of flags that do not exist. `null` silences the client.
+     */
+    logger?: FlagsLogger | null;
+    /** Evaluation clock (tests). */
+    now?: () => Date | number;
+    /** Reported with usage (set by Guidely SDK integrations). */
+    sdk?: {
+        name: string;
+        version: string;
+    };
+}
+/**
+ * Feature flags for one environment. Create with {@link createFlagsClient}; one per app (browser)
+ * or per process (server — use {@link FlagsClient.forUser} per request).
+ */
+declare class FlagsClient implements FlagsReader {
+    readonly sdkKey: string;
+    readonly apiUrl: string;
+    readonly environment: string | undefined;
+    private readonly o;
+    private readonly cfg;
+    private readonly secret;
+    private readonly log;
+    private readonly storage;
+    private readonly storageKey;
+    private readonly getters;
+    private payload;
+    /** The payload as received (possibly encrypted): what `getPayload()` hands to browsers. */
+    private raw;
+    private etag;
+    private remote;
+    private results;
+    private resultsKey;
+    private readonly resultCache;
+    private context;
+    private attributes;
+    private overrides;
+    private readonly urlOverrides;
+    private offline;
+    private destroyed;
+    private ready_;
+    private resolveReady;
+    private readonly readyPromise;
+    private readonly listeners;
+    private inflight;
+    private lastFetchAt;
+    private failures;
+    private retryAt;
+    private pollTimer;
+    private remoteTimer;
+    private flushTimer;
+    private flushDue;
+    private stream;
+    private streamConnected;
+    private streamFailures;
+    private reconnectTimer;
+    private readonly exposed;
+    private readonly usage;
+    private exposures;
+    private readonly warned;
+    private cleanups;
+    private lastError;
+    constructor(options: FlagsClientOptions);
+    /** Boolean flag value; `fallback` (default `false`) when missing or not a boolean. */
+    isEnabled(key: string, fallback?: boolean): boolean;
+    /** Flag value; `fallback` when missing, null or of a different JSON type than `fallback`. */
+    getValue<T extends JsonValue>(key: string, fallback: T): FlagValue<T>;
+    getString(key: string, fallback: string): string;
+    getNumber(key: string, fallback: number): number;
+    getBoolean(key: string, fallback: boolean): boolean;
+    getJson<T = JsonValue>(key: string, fallback: T): T;
+    /** Value plus reason, rule, variation and experiment assignment. */
+    getDetails<T extends JsonValue>(key: string, fallback: T): FlagDetails<FlagValue<T>>;
+    /** Every flag's value for the current attributes (records no exposures or usage). */
+    getAll(): Record<string, JsonValue>;
+    /**
+     * Getters bound to other attributes (merged over the client's), without changing the client:
+     * the per-request pattern on servers. With remote evaluation they serve results already cached
+     * for these attributes, else fallbacks.
+     */
+    forUser(attributes: Attributes): FlagsEvaluator;
+    /** Replaces the app attributes. */
+    setAttributes(attributes: Attributes): void;
+    /** Merges into the app attributes. */
+    updateAttributes(partial: Attributes): void;
+    /** Replaces the integration-supplied attributes (see `contextAttributes`). */
+    setContextAttributes(attributes: Attributes): void;
+    /** Context attributes with app attributes merged over them. */
+    getAttributes(): Attributes;
+    /** Replaces the overrides (`null` clears them). URL overrides stay. */
+    setOverrides(overrides: Record<string, JsonValue> | null): void;
+    private changeAttributes;
+    /** Resolves once the first load settled (bootstrap, network success or failure). Never rejects. */
+    ready(): Promise<void>;
+    isReady(): boolean;
+    /** Calls `listener` whenever values may have changed (payload, attributes, overrides, readiness). */
+    subscribe: (listener: () => void) => (() => void);
+    /** `true` stops all network activity; cached data keeps serving. `false` resumes and refreshes. */
+    setOffline(offline: boolean): void;
+    /** Fetches now (payload, or remote evaluation). Resolves when done; never rejects. */
+    refresh(): Promise<void>;
+    /**
+     * The current data for server-side rendering: pass it as `payload` to the browser client (or
+     * framework provider) to render the same values without a flash. Encrypted payloads stay
+     * encrypted; with remote evaluation it returns the results. `null` before anything loaded.
+     */
+    getPayload(): FlagsBootstrap | null;
+    /** Sends pending usage counts and exposures now. */
+    flush(): Promise<void>;
+    /** Stops timers and streams and sends pending usage. The client keeps serving cached values. */
+    destroy(): void;
+    private overrideFor;
+    private resolve;
+    private evaluateRemoteOrLocal;
+    private all;
+    private now;
+    private record;
+    private warnOnce;
+    private setPayload;
+    private setResults;
+    /** Decrypts when needed and applies. Returns false (keeping the previous payload) when unusable. */
+    private applyRaw;
+    private loadStored;
+    private persist;
+    private url;
+    private headers;
+    private get fetcher();
+    private request;
+    private fetchNow;
+    private fetchPayload;
+    private fetchRemote;
+    private scheduleRemote;
+    private lazyRefresh;
+    private start;
+    private settle;
+    /** Arms the poll timer / stream for the current mode. */
+    private schedule;
+    private schedulePoll;
+    private stopNetwork;
+    private onStreamEvent;
+    private openStream;
+    /** The stream dropped: poll meanwhile and reconnect with backoff (`permanent`: never retry). */
+    private streamDown;
+    private scheduleFlush;
+    private takeBatch;
+    private requeue;
+    /** Page hide / destroy: `sendBeacon` for public keys, else a `keepalive` fetch. */
+    private flushOnExit;
+    private wireBrowser;
+    private notify;
+    private reportError;
+}
+/** Creates a flags client and starts loading (per `pollingMode`). */
+declare function createFlagsClient(options: FlagsClientOptions): FlagsClient;
+
+/** Sticky bucket stores (docs/feature-flags-spec.md §3.5): keep a user's experiment variation across config changes. */
+
+/** Keeps assignments in memory for the life of the process (servers, tests). */
+declare class InMemoryStickyBucketStore implements StickyBucketStore {
+    private readonly docs;
+    get(docKey: string): StickyAssignments | null;
+    set(docKey: string, assignments: StickyAssignments): void;
+}
+/** Persists assignments in `localStorage` (browsers). Falls back to memory when storage is unavailable. */
+declare class LocalStorageStickyBucketStore implements StickyBucketStore {
+    private readonly prefix;
+    private readonly memory;
+    constructor(prefix?: string);
+    private get storage();
+    get(docKey: string): StickyAssignments | null;
+    set(docKey: string, assignments: StickyAssignments): void;
+}
+
+/** Small runtime-neutral helpers shared by the flags client. No Node built-ins, no DOM at module scope. */
+
+/** JSON with object keys sorted: equal attribute sets give equal strings (remote-eval cache keys). */
+declare function stableStringify(value: unknown): string;
+declare function isEncryptedPayload(x: unknown): x is EncryptedFlagsPayload;
+/** A remote-evaluation response (`{ version, flags: { key: EvaluationResult } }`) rather than a payload. */
+declare function isRemoteResults(x: unknown): x is RemoteEvaluationResponse;
+declare function isFlagsPayload(x: unknown): x is FlagsPayload;
+/** `?guidely_flags=key:value,key2:"str"` → overrides. Values are JSON when they parse, strings otherwise. */
+declare function parseUrlOverrides(search: string, param?: string): Record<string, JsonValue>;
+
+export { Attributes, DEFAULT_FLAGS_API_URL, EncryptedFlagsPayload, EvaluationResult, ExperimentAssignment, FLAGS_SDK_NAME, FLAGS_SDK_VERSION, type FlagDetails, type FlagValue, type FlagsBootstrap, FlagsClient, type FlagsClientOptions, type FlagsEvaluator, type FlagsLogger, FlagsPayload, type FlagsReader, type FlagsStorage, InMemoryStickyBucketStore, JsonValue, LocalStorageStickyBucketStore, type OverrideBehaviour, type PollingMode, RemoteEvaluationResponse, type StaticFlagsInput, StickyAssignments, StickyBucketStore, createFlagsClient, createStaticFlags, isEncryptedPayload, isFlagsPayload, isRemoteResults, parseUrlOverrides, stableStringify };

package/dist/index.d.ts

@@ -0,0 +1,314 @@
+import { JsonValue, EvaluationResult, Attributes, FlagsPayload, RemoteEvaluationResponse, EncryptedFlagsPayload, StickyBucketStore, ExperimentAssignment, StickyAssignments } from './evaluate.js';
+export { ARRAY_OPERATORS, ATTRIBUTE_OPERATORS, AttributeCondition, AttributeOperator, BOOLEAN_OPERATORS, Condition, ConditionSegment, DATE_OPERATORS, EvaluateOptions, EvaluationReason, ExperimentNamespace, ExperimentRule, ExperimentVariation, FlagComparisonOperator, FlagCondition, FlagDefinition, FlagEventsBatch, FlagRule, FlagRuleType, FlagValueType, ForceRule, GroupCondition, HASHED_OPERATORS, HoldoutDefinition, ListSegment, NUMBER_OPERATORS, PRESENCE_OPERATORS, Prerequisite, RampStep, RolloutRule, RuleSchedule, SEMVER_OPERATORS, SegmentCondition, SegmentDefinition, SplitBucket, SplitRule, TEXT_OPERATORS, compareSemver, effectiveCoverage, evaluateAllFlags, evaluateFlag, fnv1a32, hashBucket, hashConfidential, hashConfidentialAffix, instantOf, isOn, isScheduleActive, jsonEquals, lookupAttribute, numberOf, parseSemver, sha256Hex, textOf } from './evaluate.js';
+
+/** The value type a getter returns for a fallback: literals widen (`"blue"` → `string`), JSON types stay. */
+type FlagValue<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
+/** An evaluation result whose `value` is the caller's fallback when the flag is missing, null or of another type. */
+interface FlagDetails<T = JsonValue> extends Omit<EvaluationResult, "value"> {
+    value: T;
+    /** The fallback was served (flag missing, value null or of the wrong type). */
+    usedFallback: boolean;
+}
+/** Synchronous flag getters. They never throw: problems give the fallback. */
+interface FlagsEvaluator {
+    /** Boolean flag value; `fallback` (default `false`) when missing or not a boolean. */
+    isEnabled(key: string, fallback?: boolean): boolean;
+    /** Flag value; `fallback` when missing, null or of a different JSON type than `fallback`. */
+    getValue<T extends JsonValue>(key: string, fallback: T): FlagValue<T>;
+    getString(key: string, fallback: string): string;
+    getNumber(key: string, fallback: number): number;
+    getBoolean(key: string, fallback: boolean): boolean;
+    /** Object or array value. */
+    getJson<T = JsonValue>(key: string, fallback: T): T;
+    /** Value plus why it was served (reason, rule, variation, experiment). */
+    getDetails<T extends JsonValue>(key: string, fallback: T): FlagDetails<FlagValue<T>>;
+    /** Every flag's value for these attributes (no exposures or usage are recorded). */
+    getAll(): Record<string, JsonValue>;
+    /** The attributes these getters evaluate with. */
+    getAttributes(): Attributes;
+}
+/** What framework bindings read from: an evaluator that can say whether it has loaded and notify changes. */
+interface FlagsReader extends FlagsEvaluator {
+    isReady(): boolean;
+    /** Calls `listener` whenever values may have changed. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+}
+interface StaticFlagsInput {
+    /** A payload (or remote-evaluation results) from `client.getPayload()` on the server. */
+    payload?: FlagsPayload | RemoteEvaluationResponse | unknown;
+    attributes?: Attributes;
+    now?: Date | number;
+}
+/**
+ * A network-free, read-only snapshot over a bootstrap payload. Framework bindings render with it
+ * on the server and during hydration so the HTML matches; it records no exposures or usage.
+ * Encrypted payloads cannot be read synchronously and give fallbacks.
+ */
+declare function createStaticFlags(input?: StaticFlagsInput): FlagsReader;
+
+declare const FLAGS_SDK_NAME = "@guidelytech/flags";
+declare const FLAGS_SDK_VERSION = "0.7.0";
+declare const DEFAULT_FLAGS_API_URL = "https://guidelytech.com";
+/**
+ * - `auto` — fetch at start, then every `pollIntervalSeconds`.
+ * - `lazy` — fetch when a flag is read and the cache is older than `cacheTtlSeconds` (serverless, edge).
+ * - `manual` — only `refresh()` fetches.
+ * - `stream` — server-sent events push changes; polls while the stream is down.
+ */
+type PollingMode = "auto" | "lazy" | "manual" | "stream";
+/** `localOnly`: never fetch, serve overrides only. `localOverRemote`: overrides win. `remoteOverLocal`: overrides fill in flags missing remotely. */
+type OverrideBehaviour = "localOnly" | "localOverRemote" | "remoteOverLocal";
+/** Key/value storage for the last payload: `localStorage`-like or AsyncStorage-like (sync or async). */
+interface FlagsStorage {
+    getItem(key: string): string | null | undefined | Promise<string | null | undefined>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem?(key: string): void | Promise<void>;
+}
+interface FlagsLogger {
+    debug?(...args: unknown[]): void;
+    warn?(...args: unknown[]): void;
+    error?(...args: unknown[]): void;
+}
+/** What a bootstrap / `getPayload()` can hold. */
+type FlagsBootstrap = FlagsPayload | EncryptedFlagsPayload | RemoteEvaluationResponse;
+interface FlagsClientOptions {
+    /** Environment public key `pk_…` (the `projectId` used for tracking) or, on servers only, a secret `gly_sk_…` key. */
+    sdkKey?: string;
+    /** Alias of `sdkKey`. */
+    projectId?: string;
+    /** Base URL of your Guidely deployment (default `https://guidelytech.com`). */
+    apiUrl?: string;
+    /** `development` | `staging` | `production`. Required with a `gly_sk_` key. */
+    environment?: string;
+    /** Default attributes, merged under per-call (`forUser`) attributes. */
+    attributes?: Attributes;
+    /**
+     * Attributes supplied by a Guidely SDK integration (identity, page, device). App attributes
+     * (`attributes`, `setAttributes`) are merged over them.
+     */
+    contextAttributes?: Attributes;
+    pollingMode?: PollingMode;
+    /** `auto` / `stream` fallback polling interval (default 60). */
+    pollIntervalSeconds?: number;
+    /** `lazy` cache lifetime (default 60). */
+    cacheTtlSeconds?: number;
+    /** Bootstrap: a payload (plain or encrypted) or remote-evaluation results, used immediately. */
+    payload?: FlagsBootstrap | null;
+    /** Bootstrap for remote evaluation: `{ version, flags }` or a map of results. */
+    remoteResults?: RemoteEvaluationResponse | Record<string, EvaluationResult> | null;
+    /** Base64 AES-256 key for environments that encrypt their payload. */
+    decryptionKey?: string;
+    /** Ask the server to evaluate (`POST /flags/evaluate`) instead of downloading rules. Needed when the environment hides rules. */
+    remoteEval?: boolean;
+    /** Debounce for re-evaluating remotely after attribute changes (default 50 ms). */
+    remoteEvalDebounceMs?: number;
+    /** Local flag values (tests, QA, kill switches) applied per `overrideBehaviour`. */
+    overrides?: Record<string, JsonValue> | null;
+    overrideBehaviour?: OverrideBehaviour;
+    /** Keeps experiment assignments stable (`InMemoryStickyBucketStore`, `LocalStorageStickyBucketStore`). */
+    stickyBucketService?: StickyBucketStore;
+    /** Persists the last payload. Default: `localStorage` in browsers, none elsewhere. `false` disables. */
+    storage?: FlagsStorage | null | false;
+    /** Browser only: read `?guidely_flags=key:value,key2:"text"` from the URL as overrides (QA). */
+    enableUrlOverrides?: boolean;
+    /** Called once per (experiment, user, variation) when a user is bucketed into an experiment. */
+    trackingCallback?: (experiment: ExperimentAssignment, result: EvaluationResult) => void;
+    /** Send experiment exposures to Guidely (`POST /flags/events`). Default: `true` unless `trackingCallback` is set. */
+    trackExposures?: boolean;
+    /** Send aggregated evaluation counts to Guidely at most every 60 s (default `true`). */
+    reportUsage?: boolean;
+    onReady?: () => void;
+    /** New payload (or remote results) applied. */
+    onChange?: (data: FlagsPayload | RemoteEvaluationResponse) => void;
+    onFlagEvaluated?: (result: EvaluationResult) => void;
+    onError?: (error: Error) => void;
+    /** Start without network activity (cached / bootstrapped data keeps serving). */
+    offline?: boolean;
+    fetch?: typeof fetch;
+    /**
+     * Defaults to `console`: `error` for failed requests (once per streak), `warn` for misuse and,
+     * in development, reads of flags that do not exist. `null` silences the client.
+     */
+    logger?: FlagsLogger | null;
+    /** Evaluation clock (tests). */
+    now?: () => Date | number;
+    /** Reported with usage (set by Guidely SDK integrations). */
+    sdk?: {
+        name: string;
+        version: string;
+    };
+}
+/**
+ * Feature flags for one environment. Create with {@link createFlagsClient}; one per app (browser)
+ * or per process (server — use {@link FlagsClient.forUser} per request).
+ */
+declare class FlagsClient implements FlagsReader {
+    readonly sdkKey: string;
+    readonly apiUrl: string;
+    readonly environment: string | undefined;
+    private readonly o;
+    private readonly cfg;
+    private readonly secret;
+    private readonly log;
+    private readonly storage;
+    private readonly storageKey;
+    private readonly getters;
+    private payload;
+    /** The payload as received (possibly encrypted): what `getPayload()` hands to browsers. */
+    private raw;
+    private etag;
+    private remote;
+    private results;
+    private resultsKey;
+    private readonly resultCache;
+    private context;
+    private attributes;
+    private overrides;
+    private readonly urlOverrides;
+    private offline;
+    private destroyed;
+    private ready_;
+    private resolveReady;
+    private readonly readyPromise;
+    private readonly listeners;
+    private inflight;
+    private lastFetchAt;
+    private failures;
+    private retryAt;
+    private pollTimer;
+    private remoteTimer;
+    private flushTimer;
+    private flushDue;
+    private stream;
+    private streamConnected;
+    private streamFailures;
+    private reconnectTimer;
+    private readonly exposed;
+    private readonly usage;
+    private exposures;
+    private readonly warned;
+    private cleanups;
+    private lastError;
+    constructor(options: FlagsClientOptions);
+    /** Boolean flag value; `fallback` (default `false`) when missing or not a boolean. */
+    isEnabled(key: string, fallback?: boolean): boolean;
+    /** Flag value; `fallback` when missing, null or of a different JSON type than `fallback`. */
+    getValue<T extends JsonValue>(key: string, fallback: T): FlagValue<T>;
+    getString(key: string, fallback: string): string;
+    getNumber(key: string, fallback: number): number;
+    getBoolean(key: string, fallback: boolean): boolean;
+    getJson<T = JsonValue>(key: string, fallback: T): T;
+    /** Value plus reason, rule, variation and experiment assignment. */
+    getDetails<T extends JsonValue>(key: string, fallback: T): FlagDetails<FlagValue<T>>;
+    /** Every flag's value for the current attributes (records no exposures or usage). */
+    getAll(): Record<string, JsonValue>;
+    /**
+     * Getters bound to other attributes (merged over the client's), without changing the client:
+     * the per-request pattern on servers. With remote evaluation they serve results already cached
+     * for these attributes, else fallbacks.
+     */
+    forUser(attributes: Attributes): FlagsEvaluator;
+    /** Replaces the app attributes. */
+    setAttributes(attributes: Attributes): void;
+    /** Merges into the app attributes. */
+    updateAttributes(partial: Attributes): void;
+    /** Replaces the integration-supplied attributes (see `contextAttributes`). */
+    setContextAttributes(attributes: Attributes): void;
+    /** Context attributes with app attributes merged over them. */
+    getAttributes(): Attributes;
+    /** Replaces the overrides (`null` clears them). URL overrides stay. */
+    setOverrides(overrides: Record<string, JsonValue> | null): void;
+    private changeAttributes;
+    /** Resolves once the first load settled (bootstrap, network success or failure). Never rejects. */
+    ready(): Promise<void>;
+    isReady(): boolean;
+    /** Calls `listener` whenever values may have changed (payload, attributes, overrides, readiness). */
+    subscribe: (listener: () => void) => (() => void);
+    /** `true` stops all network activity; cached data keeps serving. `false` resumes and refreshes. */
+    setOffline(offline: boolean): void;
+    /** Fetches now (payload, or remote evaluation). Resolves when done; never rejects. */
+    refresh(): Promise<void>;
+    /**
+     * The current data for server-side rendering: pass it as `payload` to the browser client (or
+     * framework provider) to render the same values without a flash. Encrypted payloads stay
+     * encrypted; with remote evaluation it returns the results. `null` before anything loaded.
+     */
+    getPayload(): FlagsBootstrap | null;
+    /** Sends pending usage counts and exposures now. */
+    flush(): Promise<void>;
+    /** Stops timers and streams and sends pending usage. The client keeps serving cached values. */
+    destroy(): void;
+    private overrideFor;
+    private resolve;
+    private evaluateRemoteOrLocal;
+    private all;
+    private now;
+    private record;
+    private warnOnce;
+    private setPayload;
+    private setResults;
+    /** Decrypts when needed and applies. Returns false (keeping the previous payload) when unusable. */
+    private applyRaw;
+    private loadStored;
+    private persist;
+    private url;
+    private headers;
+    private get fetcher();
+    private request;
+    private fetchNow;
+    private fetchPayload;
+    private fetchRemote;
+    private scheduleRemote;
+    private lazyRefresh;
+    private start;
+    private settle;
+    /** Arms the poll timer / stream for the current mode. */
+    private schedule;
+    private schedulePoll;
+    private stopNetwork;
+    private onStreamEvent;
+    private openStream;
+    /** The stream dropped: poll meanwhile and reconnect with backoff (`permanent`: never retry). */
+    private streamDown;
+    private scheduleFlush;
+    private takeBatch;
+    private requeue;
+    /** Page hide / destroy: `sendBeacon` for public keys, else a `keepalive` fetch. */
+    private flushOnExit;
+    private wireBrowser;
+    private notify;
+    private reportError;
+}
+/** Creates a flags client and starts loading (per `pollingMode`). */
+declare function createFlagsClient(options: FlagsClientOptions): FlagsClient;
+
+/** Sticky bucket stores (docs/feature-flags-spec.md §3.5): keep a user's experiment variation across config changes. */
+
+/** Keeps assignments in memory for the life of the process (servers, tests). */
+declare class InMemoryStickyBucketStore implements StickyBucketStore {
+    private readonly docs;
+    get(docKey: string): StickyAssignments | null;
+    set(docKey: string, assignments: StickyAssignments): void;
+}
+/** Persists assignments in `localStorage` (browsers). Falls back to memory when storage is unavailable. */
+declare class LocalStorageStickyBucketStore implements StickyBucketStore {
+    private readonly prefix;
+    private readonly memory;
+    constructor(prefix?: string);
+    private get storage();
+    get(docKey: string): StickyAssignments | null;
+    set(docKey: string, assignments: StickyAssignments): void;
+}
+
+/** Small runtime-neutral helpers shared by the flags client. No Node built-ins, no DOM at module scope. */
+
+/** JSON with object keys sorted: equal attribute sets give equal strings (remote-eval cache keys). */
+declare function stableStringify(value: unknown): string;
+declare function isEncryptedPayload(x: unknown): x is EncryptedFlagsPayload;
+/** A remote-evaluation response (`{ version, flags: { key: EvaluationResult } }`) rather than a payload. */
+declare function isRemoteResults(x: unknown): x is RemoteEvaluationResponse;
+declare function isFlagsPayload(x: unknown): x is FlagsPayload;
+/** `?guidely_flags=key:value,key2:"str"` → overrides. Values are JSON when they parse, strings otherwise. */
+declare function parseUrlOverrides(search: string, param?: string): Record<string, JsonValue>;
+
+export { Attributes, DEFAULT_FLAGS_API_URL, EncryptedFlagsPayload, EvaluationResult, ExperimentAssignment, FLAGS_SDK_NAME, FLAGS_SDK_VERSION, type FlagDetails, type FlagValue, type FlagsBootstrap, FlagsClient, type FlagsClientOptions, type FlagsEvaluator, type FlagsLogger, FlagsPayload, type FlagsReader, type FlagsStorage, InMemoryStickyBucketStore, JsonValue, LocalStorageStickyBucketStore, type OverrideBehaviour, type PollingMode, RemoteEvaluationResponse, type StaticFlagsInput, StickyAssignments, StickyBucketStore, createFlagsClient, createStaticFlags, isEncryptedPayload, isFlagsPayload, isRemoteResults, parseUrlOverrides, stableStringify };