@guidelytech/flags 0.0.0-stage → 0.8.0

package/dist/index.d.cts

@@ -0,0 +1,355 @@
+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.8.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, then the bootstrap. `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;
+    /**
+     * Read dev overrides from outside the code (default `true`): `GUIDELY_FLAG_OVERRIDES`,
+     * `GUIDELY_FLAG_OVERRIDES_FILE` and `GUIDELY_FLAG_OVERRIDE_BEHAVIOUR` environment variables, and
+     * the `__GUIDELY_FLAG_OVERRIDES__` / `__GUIDELY_FLAG_OVERRIDE_BEHAVIOUR__` globals (browser tests).
+     * They win over `overrides`, and their behaviour over `overrideBehaviour`.
+     */
+    devOverrides?: boolean;
+    /** 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 devOverrides;
+    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). Dev and 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;
+
+/**
+ * Dev overrides (docs/feature-flags-spec.md §4.1): flag values pinned from outside the code, so CI
+ * and tests can switch flags without editing the app. Read once, when a client is created.
+ * Runtime-neutral: environment variables via `process.env` (Node, Bun, Next.js server) or
+ * `Deno.env`, files via `process.getBuiltinModule("node:fs")` or `Deno`, and a global that test
+ * runners set in the page (`page.addInitScript`).
+ */
+
+declare const OVERRIDES_ENV = "GUIDELY_FLAG_OVERRIDES";
+declare const OVERRIDES_FILE_ENV = "GUIDELY_FLAG_OVERRIDES_FILE";
+declare const OVERRIDE_BEHAVIOUR_ENV = "GUIDELY_FLAG_OVERRIDE_BEHAVIOUR";
+declare const OVERRIDES_GLOBAL = "__GUIDELY_FLAG_OVERRIDES__";
+declare const OVERRIDE_BEHAVIOUR_GLOBAL = "__GUIDELY_FLAG_OVERRIDE_BEHAVIOUR__";
+interface DevOverrides {
+    /** Merged values: file, then environment variable, then global (later wins per key). */
+    values: Record<string, JsonValue>;
+    /** Replaces the configured `overrideBehaviour` when set. */
+    behaviour?: OverrideBehaviour;
+    /** Where values or the behaviour came from, for the start-up notice. */
+    sources: string[];
+    /** Unreadable or malformed sources (ignored). */
+    errors: string[];
+}
+/** Reads every dev-override source. Never throws: problems land in `errors`. */
+declare function readDevOverrides(): DevOverrides;
+
+/** 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 (text as in {@link parseOverrides}; invalid text gives none). */
+declare function parseUrlOverrides(search: string, param?: string): Record<string, JsonValue>;
+/**
+ * Overrides text (docs/feature-flags-spec.md §4.1), as held by `GUIDELY_FLAG_OVERRIDES`, an
+ * overrides file or `?guidely_flags=`: a JSON object (`{"new-checkout":true}`) or a list
+ * `key:value` separated by commas or newlines (`new-checkout:true,limit:5,theme:"dark"`), where each
+ * value is JSON when it parses and text otherwise. `null` when the text is a malformed JSON object.
+ */
+declare function parseOverrides(text: string): Record<string, JsonValue> | null;
+
+export { Attributes, DEFAULT_FLAGS_API_URL, type DevOverrides, 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, OVERRIDES_ENV, OVERRIDES_FILE_ENV, OVERRIDES_GLOBAL, OVERRIDE_BEHAVIOUR_ENV, OVERRIDE_BEHAVIOUR_GLOBAL, type OverrideBehaviour, type PollingMode, RemoteEvaluationResponse, type StaticFlagsInput, StickyAssignments, StickyBucketStore, createFlagsClient, createStaticFlags, isEncryptedPayload, isFlagsPayload, isRemoteResults, parseOverrides, parseUrlOverrides, readDevOverrides, stableStringify };