@nanoflags/sdk 0.0.0-stage → 0.4.0

package/dist/index-D5qa8ji-.d.cts

@@ -0,0 +1,302 @@
+type FlagType = "boolean" | "string" | "number" | "json";
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [k: string]: JsonValue;
+};
+type Operator = "eq" | "neq" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | "gt" | "gte" | "lt" | "lte" | "exists" | "not_exists" | "segment" | "not_segment";
+interface Condition {
+  /** Context attribute name, e.g. "region". Ignored for segment operators. */
+  attribute: string;
+  op: Operator;
+  /** Comparison value. Array for in/not_in; segment key for segment operators. */
+  value?: JsonValue;
+}
+type Serve = {
+  type: "fixed";
+  value: JsonValue;
+} | {
+  type: "rollout";
+  /** 0–100, up to two decimals. */
+  percentage: number;
+  /** Value for contexts inside the allocation. */
+  value: JsonValue;
+  /** Value for matching contexts outside the allocation. */
+  otherwise: JsonValue;
+  /** Context attribute used for bucketing. Defaults to "key". */
+  bucketBy?: string;
+  /** Documented seed. Defaults to the flag key, so allocations are independent per flag. */
+  seed?: string;
+};
+interface Rule {
+  id: string;
+  description?: string;
+  match: "all" | "any";
+  conditions: Condition[];
+  serve: Serve;
+}
+interface FlagConfig {
+  type: FlagType;
+  /** When false the flag short-circuits to `off`. */
+  enabled: boolean;
+  rules: Rule[];
+  /** Served when the flag is enabled and no rule matches. */
+  default: JsonValue;
+  /** Served when the flag is disabled. */
+  off: JsonValue;
+  /** Only client-exposed flags are included in bundles served to browser keys. */
+  clientExposed?: boolean;
+}
+interface Segment {
+  match: "all" | "any";
+  conditions: Condition[];
+}
+interface Bundle {
+  schema: 1;
+  /**
+   * Engine version the bundle was produced for (`ENGINE_VERSION` of the publisher). Absent in bundles from before it
+   * existed (treated as 1). SDKs refuse a bundle whose `engine` is newer than the engine they ship.
+   */
+  engine?: number;
+  project: string;
+  environment: string;
+  /** Published revision number. 0 means "draft / never published". */
+  revision: number;
+  flags: Record<string, FlagConfig>;
+  segments: Record<string, Segment>;
+}
+/** Attributes supplied by the application. `key` is the stable identity used for bucketing. */
+type Context = {
+  key?: string;
+} & Record<string, JsonValue | undefined>;
+type Reason = "rule_match" | "default" | "off" | "flag_not_found" | "error";
+interface TraceStep {
+  kind: "config" | "rule" | "allocation" | "result";
+  title: string;
+  detail: string;
+  matched?: boolean;
+}
+interface Evaluation<T = JsonValue> {
+  flagKey: string;
+  value: T;
+  reason: Reason;
+  /** Zero-based index of the matching rule. */
+  ruleIndex?: number;
+  ruleId?: string;
+  /** For rollout rules: whether the context fell inside the allocation, and its bucket (0–99.99). */
+  inRollout?: boolean;
+  bucket?: number;
+  revision: number;
+  trace: TraceStep[];
+  error?: string;
+}
+/** Persistence for the last bundle. Values are opaque strings owned by the SDK. */
+interface Store {
+  get(): Promise<string | null>;
+  set(value: string): Promise<void>;
+}
+/**
+ * Bundle signature verification (Ed25519 over a canonical string, WebCrypto only).
+ *
+ * canonical = "nanoflags-bundle-v1\n<environment_id>\n<revision>\n<checksum>\n<sha256 hex of the bundle JSON text>"
+ *
+ * Only PUBLIC keys are handled here. Private and admin keys never enter the SDK.
+ */
+interface VerifyOptions {
+  /**
+   * Public Ed25519 keys as JWK (`{ kty: "OKP", crv: "Ed25519", x, kid? }`), or `"fetch"` to load them
+   * once from `GET /v1/keys` on the configured edge (again, at most once a minute, when a bundle names an unknown
+   * key id). Pinning keys in your build is stronger than `"fetch"`: fetched keys are only as trustworthy as the
+   * connection they arrived over. Omitted: the embedded production keys for `https://edge.nanoflags.io`, `"fetch"`
+   * for any other edge.
+   */
+  publicKeys?: readonly JsonWebKey[] | "fetch";
+  /**
+   * Also reject bundles that carry no signature (the edge's unsigned fallback, `X-NanoFlags-Signed: false`): the SDK
+   * keeps its bundle and fetches again shortly instead. Default true for `https://edge.nanoflags.io`, false otherwise.
+   */
+  require?: boolean;
+}
+/**
+ * The hosted NanoFlags edge and the public halves of its bundle-signing keys (Ed25519, safe to embed).
+ *
+ * With `baseUrl` equal to `OFFICIAL_EDGE_URL` the SDK verifies every bundle against these keys by default
+ * (`verify.require` defaults to true there). A bundle signed with a key id that is not listed here — a rotation that
+ * happened after this SDK version was built — makes the SDK load `GET /v1/keys` from the edge once and verify against
+ * the keys it lists as well. Rotation procedure: RUNTIME.md, "Signing-key rotation".
+ */
+declare const OFFICIAL_EDGE_URL = "https://edge.nanoflags.io";
+declare const OFFICIAL_SIGNING_KEYS: readonly (JsonWebKey & {
+  kid: string;
+})[];
+declare const SDK_VERSION = "0.4.0";
+/** Newest bundle format (`bundle.engine`) this SDK can evaluate. Newer bundles are refused; the previous one stays in use. */
+declare const SUPPORTED_ENGINE_VERSION = 1;
+/** WebSocket close code of the edge for an environment that was deleted: the SDK stops reconnecting. */
+declare const CLOSE_ENVIRONMENT_DELETED = 4004;
+/** Header that carries a test-session token between services. */
+declare const SESSION_HEADER = "x-nanoflags-session";
+type ClientStatus = "not-ready" | "ready" | "stale";
+/** How updates currently reach the client: pushed over the live WebSocket, announced over SSE, or polled. */
+type Transport = "live" | "stream" | "poll";
+/** WebSocket subprotocol of `/v1/live`. The key travels as a second protocol entry, never in the URL. */
+declare const LIVE_PROTOCOL = "nanoflags.v1";
+/** The part of the WHATWG WebSocket the SDK uses (browsers, Node ≥ 22, Deno, Bun, the `ws` package). */
+interface WebSocketLike {
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  onopen: ((event: any) => any) | null;
+  onmessage: ((event: any) => any) | null;
+  onclose: ((event: any) => any) | null;
+  onerror: ((event: any) => any) | null;
+}
+type WebSocketConstructor = new (url: string, protocols?: string | string[]) => WebSocketLike;
+interface EventsOptions {
+  /** Default true. */
+  enabled?: boolean;
+  /** Fraction of evaluations reported, 0–1. Default 0.1. */
+  sampleRate?: number;
+  /** Default 10000. How often queued events are sent. */
+  flushIntervalMs?: number;
+  /**
+   * Default 60000. While no events are queued, the service report ("this service runs revision N")
+   * goes out at this interval instead of on every flush interval.
+   */
+  reportIntervalMs?: number;
+  /**
+   * Decides what part of the evaluation context leaves the process with a sampled event.
+   * Default: no attribute VALUES are sent — only the names of the attributes that the flag's
+   * rules reference and that were present, mapped to the value's type (e.g. `{ region: "string" }`).
+   */
+  redact?: (ctx: Context) => Record<string, JsonValue | undefined>;
+  /** Random source for sampling; injectable for tests. */
+  random?: () => number;
+}
+interface ClientOptions {
+  /** `nf_srv_…` on servers, `nf_pub_…` in browsers. Never ship a server key to a browser. */
+  sdkKey: string;
+  /** Base URL of the NanoFlags edge, e.g. `https://flags.example.com`. */
+  baseUrl: string;
+  /** Name shown in "which revision is this service running". */
+  service?: string;
+  /** Default 30000. `0` disables polling. */
+  pollIntervalMs?: number;
+  /**
+   * Default true. Receive updates without polling: over the live WebSocket when the runtime has
+   * one, otherwise (or when the socket cannot be established) over SSE. `false` disables both.
+   */
+  streaming?: boolean;
+  /** Default true. `false` skips the live WebSocket and uses SSE + polling as SDK 0.2 did. */
+  live?: boolean;
+  /** Default 300000. Safety-poll interval while the live socket is healthy (`pollIntervalMs` applies otherwise; `pollIntervalMs: 0` disables both). */
+  livePollIntervalMs?: number;
+  /** WebSocket implementation. Default: the global `WebSocket` (browsers, Node ≥ 22). Without one the SDK uses SSE + polling. */
+  webSocket?: WebSocketConstructor;
+  /** A bundle obtained elsewhere (e.g. embedded at build time or passed from the server). */
+  bootstrap?: Bundle;
+  /** Persistence. Default: IndexedDB in browsers, none elsewhere. `false` disables it. */
+  store?: Store | false;
+  events?: EventsOptions | false;
+  /**
+   * Verify bundle signatures before a new bundle replaces the current one. A bundle whose signature
+   * does not verify is rejected: the previous bundle stays in use and an `error` (`code: "signature"`)
+   * is emitted. Without `require`, bundles the edge marks as unsigned are still accepted.
+   *
+   * Default: with `baseUrl` = `https://edge.nanoflags.io` the SDK verifies against the embedded production keys
+   * (`OFFICIAL_SIGNING_KEYS`, plus `GET /v1/keys` once when a bundle names an unknown key id) with `require: true`;
+   * with any other `baseUrl` nothing is verified unless configured. `false` turns verification off explicitly.
+   */
+  verify?: VerifyOptions | false;
+  fetch?: typeof fetch;
+}
+/** The flag accessors shared by the client and by session-scoped evaluators. */
+interface FlagEvaluator {
+  boolean(key: string, fallback: boolean, ctx?: Context): boolean;
+  string(key: string, fallback: string, ctx?: Context): string;
+  number(key: string, fallback: number, ctx?: Context): number;
+  json<T extends JsonValue = JsonValue>(key: string, fallback: T, ctx?: Context): T;
+  /** Full engine result (value, reason, matched rule, trace). No type check is applied. */
+  evaluate<T extends JsonValue = JsonValue>(key: string, fallback: T, ctx?: Context): Evaluation<T>;
+}
+/**
+ * Evaluator bound to one test session. While `active`, flags are evaluated against the session's
+ * pinned bundle with the context `{ ...session.context, ...ctx }` and sampled events carry the
+ * session id. When the session is unknown, not permitted for this service, or expired, it evaluates
+ * exactly like the client (`active` is false). It never throws.
+ */
+interface SessionEvaluator extends FlagEvaluator {
+  /** True while the session is known and has not expired. Re-evaluated on every read. */
+  readonly active: boolean;
+  /** Session id, or null when the session could not be resolved. */
+  readonly id: string | null;
+  /** ISO timestamp, or null when the session could not be resolved. */
+  readonly expiresAt: string | null;
+  /** Revision evaluations currently run against (the pinned one while active, otherwise the client's). */
+  readonly revision: number | null;
+}
+interface SessionOptions {
+  /** Service name sent as `X-NanoFlags-Service`. Defaults to the client's `service`. */
+  service?: string;
+}
+interface UpdateEvent {
+  revision: number;
+  previousRevision: number | null;
+  checksum: string | null;
+  source: "network" | "store" | "bootstrap";
+  /**
+   * Milliseconds from the commit of the revision in the database to this event — only for revisions
+   * pushed over the live socket (`transport: "live"`) that carry the commit time; otherwise null.
+   * It compares the database's clock with this machine's, so it is as accurate as their clocks agree.
+   */
+  latencyMs: number | null;
+  /** How this bundle arrived: pushed (`live`), fetched after an SSE notification (`stream`), or anything else (`poll`). */
+  transport: Transport;
+}
+interface NanoFlagsClient {
+  /** Resolves once a usable bundle is loaded, or once the first load attempt has finished without one. Never rejects. */
+  ready(): Promise<void>;
+  readonly status: ClientStatus;
+  /** Revision of the bundle in use, or null when none is loaded. */
+  readonly revision: number | null;
+  /** How updates reach this client right now: `live` while the WebSocket is open, `stream` while SSE is in use, else `poll`. */
+  readonly transport: Transport;
+  boolean(key: string, fallback: boolean, ctx?: Context): boolean;
+  string(key: string, fallback: string, ctx?: Context): string;
+  number(key: string, fallback: number, ctx?: Context): number;
+  json<T extends JsonValue = JsonValue>(key: string, fallback: T, ctx?: Context): T;
+  /** Full engine result (value, reason, matched rule, trace). No type check is applied. */
+  evaluate<T extends JsonValue = JsonValue>(key: string, fallback: T, ctx?: Context): Evaluation<T>;
+  /**
+   * Resolve a test session (`GET /v1/session`, once per token until it expires) and return an
+   * evaluator scoped to it. Never rejects: an unknown or expired session yields an evaluator
+   * whose `active` is false and that behaves like the client.
+   */
+  session(token: string | null | undefined, options?: SessionOptions): Promise<SessionEvaluator>;
+  /**
+   * Browser only. Remember `token` for this page session (sessionStorage) and route this client's
+   * own accessors through the session while it is active. `null` leaves the session.
+   * On servers use `session()` or `@nanoflags/sdk/node` instead: one client serves many requests.
+   */
+  useSession(token: string | null): Promise<SessionEvaluator>;
+  /** Browser only. `{ "x-nanoflags-session": token }` while a page session is set, otherwise `{}`. */
+  sessionHeaders(): Record<string, string>;
+  on(event: "update", cb: (e: UpdateEvent) => void): () => void;
+  on(event: "error", cb: (e: Error) => void): () => void;
+  /** Force a revalidation now. Resolves when it finished (successfully or not). */
+  refresh(): Promise<void>;
+  /** Send queued telemetry now. */
+  flush(): Promise<void>;
+  /** Stops timers, the stream and telemetry. Evaluations keep working on the last bundle. */
+  close(): void;
+  /** For external-store bindings (React): called on every bundle or status change. */
+  subscribe(listener: () => void): () => void;
+  /** Monotonic counter that changes whenever `subscribe` listeners fire. */
+  readonly version: number;
+}
+declare class NanoFlagsError extends Error {
+  readonly code: "network" | "unauthorized" | "http" | "invalid_bundle" | "store" | "config" | "signature" | "session" | "engine" | "environment_deleted";
+  readonly httpStatus?: number | undefined;
+  constructor(message: string, code: "network" | "unauthorized" | "http" | "invalid_bundle" | "store" | "config" | "signature" | "session" | "engine" | "environment_deleted", httpStatus?: number | undefined);
+}
+/** A session token is opaque; it only has to be safe to put in a header. */
+declare function isSessionToken(v: unknown): v is string;
+declare function createClient(options: ClientOptions): NanoFlagsClient;
+export { Store as C, JsonValue as D, Evaluation as E, Reason as O, VerifyOptions as S, Context as T, WebSocketLike as _, FlagEvaluator as a, OFFICIAL_EDGE_URL as b, NanoFlagsError as c, SUPPORTED_ENGINE_VERSION as d, SessionEvaluator as f, WebSocketConstructor as g, UpdateEvent as h, EventsOptions as i, SDK_VERSION as l, Transport as m, ClientOptions as n, LIVE_PROTOCOL as o, SessionOptions as p, ClientStatus as r, NanoFlagsClient as s, CLOSE_ENVIRONMENT_DELETED as t, SESSION_HEADER as u, createClient as v, Bundle as w, OFFICIAL_SIGNING_KEYS as x, isSessionToken as y };

package/dist/index-D5qa8ji-.d.ts

@@ -0,0 +1,302 @@
+type FlagType = "boolean" | "string" | "number" | "json";
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [k: string]: JsonValue;
+};
+type Operator = "eq" | "neq" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | "gt" | "gte" | "lt" | "lte" | "exists" | "not_exists" | "segment" | "not_segment";
+interface Condition {
+  /** Context attribute name, e.g. "region". Ignored for segment operators. */
+  attribute: string;
+  op: Operator;
+  /** Comparison value. Array for in/not_in; segment key for segment operators. */
+  value?: JsonValue;
+}
+type Serve = {
+  type: "fixed";
+  value: JsonValue;
+} | {
+  type: "rollout";
+  /** 0–100, up to two decimals. */
+  percentage: number;
+  /** Value for contexts inside the allocation. */
+  value: JsonValue;
+  /** Value for matching contexts outside the allocation. */
+  otherwise: JsonValue;
+  /** Context attribute used for bucketing. Defaults to "key". */
+  bucketBy?: string;
+  /** Documented seed. Defaults to the flag key, so allocations are independent per flag. */
+  seed?: string;
+};
+interface Rule {
+  id: string;
+  description?: string;
+  match: "all" | "any";
+  conditions: Condition[];
+  serve: Serve;
+}
+interface FlagConfig {
+  type: FlagType;
+  /** When false the flag short-circuits to `off`. */
+  enabled: boolean;
+  rules: Rule[];
+  /** Served when the flag is enabled and no rule matches. */
+  default: JsonValue;
+  /** Served when the flag is disabled. */
+  off: JsonValue;
+  /** Only client-exposed flags are included in bundles served to browser keys. */
+  clientExposed?: boolean;
+}
+interface Segment {
+  match: "all" | "any";
+  conditions: Condition[];
+}
+interface Bundle {
+  schema: 1;
+  /**
+   * Engine version the bundle was produced for (`ENGINE_VERSION` of the publisher). Absent in bundles from before it
+   * existed (treated as 1). SDKs refuse a bundle whose `engine` is newer than the engine they ship.
+   */
+  engine?: number;
+  project: string;
+  environment: string;
+  /** Published revision number. 0 means "draft / never published". */
+  revision: number;
+  flags: Record<string, FlagConfig>;
+  segments: Record<string, Segment>;
+}
+/** Attributes supplied by the application. `key` is the stable identity used for bucketing. */
+type Context = {
+  key?: string;
+} & Record<string, JsonValue | undefined>;
+type Reason = "rule_match" | "default" | "off" | "flag_not_found" | "error";
+interface TraceStep {
+  kind: "config" | "rule" | "allocation" | "result";
+  title: string;
+  detail: string;
+  matched?: boolean;
+}
+interface Evaluation<T = JsonValue> {
+  flagKey: string;
+  value: T;
+  reason: Reason;
+  /** Zero-based index of the matching rule. */
+  ruleIndex?: number;
+  ruleId?: string;
+  /** For rollout rules: whether the context fell inside the allocation, and its bucket (0–99.99). */
+  inRollout?: boolean;
+  bucket?: number;
+  revision: number;
+  trace: TraceStep[];
+  error?: string;
+}
+/** Persistence for the last bundle. Values are opaque strings owned by the SDK. */
+interface Store {
+  get(): Promise<string | null>;
+  set(value: string): Promise<void>;
+}
+/**
+ * Bundle signature verification (Ed25519 over a canonical string, WebCrypto only).
+ *
+ * canonical = "nanoflags-bundle-v1\n<environment_id>\n<revision>\n<checksum>\n<sha256 hex of the bundle JSON text>"
+ *
+ * Only PUBLIC keys are handled here. Private and admin keys never enter the SDK.
+ */
+interface VerifyOptions {
+  /**
+   * Public Ed25519 keys as JWK (`{ kty: "OKP", crv: "Ed25519", x, kid? }`), or `"fetch"` to load them
+   * once from `GET /v1/keys` on the configured edge (again, at most once a minute, when a bundle names an unknown
+   * key id). Pinning keys in your build is stronger than `"fetch"`: fetched keys are only as trustworthy as the
+   * connection they arrived over. Omitted: the embedded production keys for `https://edge.nanoflags.io`, `"fetch"`
+   * for any other edge.
+   */
+  publicKeys?: readonly JsonWebKey[] | "fetch";
+  /**
+   * Also reject bundles that carry no signature (the edge's unsigned fallback, `X-NanoFlags-Signed: false`): the SDK
+   * keeps its bundle and fetches again shortly instead. Default true for `https://edge.nanoflags.io`, false otherwise.
+   */
+  require?: boolean;
+}
+/**
+ * The hosted NanoFlags edge and the public halves of its bundle-signing keys (Ed25519, safe to embed).
+ *
+ * With `baseUrl` equal to `OFFICIAL_EDGE_URL` the SDK verifies every bundle against these keys by default
+ * (`verify.require` defaults to true there). A bundle signed with a key id that is not listed here — a rotation that
+ * happened after this SDK version was built — makes the SDK load `GET /v1/keys` from the edge once and verify against
+ * the keys it lists as well. Rotation procedure: RUNTIME.md, "Signing-key rotation".
+ */
+declare const OFFICIAL_EDGE_URL = "https://edge.nanoflags.io";
+declare const OFFICIAL_SIGNING_KEYS: readonly (JsonWebKey & {
+  kid: string;
+})[];
+declare const SDK_VERSION = "0.4.0";
+/** Newest bundle format (`bundle.engine`) this SDK can evaluate. Newer bundles are refused; the previous one stays in use. */
+declare const SUPPORTED_ENGINE_VERSION = 1;
+/** WebSocket close code of the edge for an environment that was deleted: the SDK stops reconnecting. */
+declare const CLOSE_ENVIRONMENT_DELETED = 4004;
+/** Header that carries a test-session token between services. */
+declare const SESSION_HEADER = "x-nanoflags-session";
+type ClientStatus = "not-ready" | "ready" | "stale";
+/** How updates currently reach the client: pushed over the live WebSocket, announced over SSE, or polled. */
+type Transport = "live" | "stream" | "poll";
+/** WebSocket subprotocol of `/v1/live`. The key travels as a second protocol entry, never in the URL. */
+declare const LIVE_PROTOCOL = "nanoflags.v1";
+/** The part of the WHATWG WebSocket the SDK uses (browsers, Node ≥ 22, Deno, Bun, the `ws` package). */
+interface WebSocketLike {
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  onopen: ((event: any) => any) | null;
+  onmessage: ((event: any) => any) | null;
+  onclose: ((event: any) => any) | null;
+  onerror: ((event: any) => any) | null;
+}
+type WebSocketConstructor = new (url: string, protocols?: string | string[]) => WebSocketLike;
+interface EventsOptions {
+  /** Default true. */
+  enabled?: boolean;
+  /** Fraction of evaluations reported, 0–1. Default 0.1. */
+  sampleRate?: number;
+  /** Default 10000. How often queued events are sent. */
+  flushIntervalMs?: number;
+  /**
+   * Default 60000. While no events are queued, the service report ("this service runs revision N")
+   * goes out at this interval instead of on every flush interval.
+   */
+  reportIntervalMs?: number;
+  /**
+   * Decides what part of the evaluation context leaves the process with a sampled event.
+   * Default: no attribute VALUES are sent — only the names of the attributes that the flag's
+   * rules reference and that were present, mapped to the value's type (e.g. `{ region: "string" }`).
+   */
+  redact?: (ctx: Context) => Record<string, JsonValue | undefined>;
+  /** Random source for sampling; injectable for tests. */
+  random?: () => number;
+}
+interface ClientOptions {
+  /** `nf_srv_…` on servers, `nf_pub_…` in browsers. Never ship a server key to a browser. */
+  sdkKey: string;
+  /** Base URL of the NanoFlags edge, e.g. `https://flags.example.com`. */
+  baseUrl: string;
+  /** Name shown in "which revision is this service running". */
+  service?: string;
+  /** Default 30000. `0` disables polling. */
+  pollIntervalMs?: number;
+  /**
+   * Default true. Receive updates without polling: over the live WebSocket when the runtime has
+   * one, otherwise (or when the socket cannot be established) over SSE. `false` disables both.
+   */
+  streaming?: boolean;
+  /** Default true. `false` skips the live WebSocket and uses SSE + polling as SDK 0.2 did. */
+  live?: boolean;
+  /** Default 300000. Safety-poll interval while the live socket is healthy (`pollIntervalMs` applies otherwise; `pollIntervalMs: 0` disables both). */
+  livePollIntervalMs?: number;
+  /** WebSocket implementation. Default: the global `WebSocket` (browsers, Node ≥ 22). Without one the SDK uses SSE + polling. */
+  webSocket?: WebSocketConstructor;
+  /** A bundle obtained elsewhere (e.g. embedded at build time or passed from the server). */
+  bootstrap?: Bundle;
+  /** Persistence. Default: IndexedDB in browsers, none elsewhere. `false` disables it. */
+  store?: Store | false;
+  events?: EventsOptions | false;
+  /**
+   * Verify bundle signatures before a new bundle replaces the current one. A bundle whose signature
+   * does not verify is rejected: the previous bundle stays in use and an `error` (`code: "signature"`)
+   * is emitted. Without `require`, bundles the edge marks as unsigned are still accepted.
+   *
+   * Default: with `baseUrl` = `https://edge.nanoflags.io` the SDK verifies against the embedded production keys
+   * (`OFFICIAL_SIGNING_KEYS`, plus `GET /v1/keys` once when a bundle names an unknown key id) with `require: true`;
+   * with any other `baseUrl` nothing is verified unless configured. `false` turns verification off explicitly.
+   */
+  verify?: VerifyOptions | false;
+  fetch?: typeof fetch;
+}
+/** The flag accessors shared by the client and by session-scoped evaluators. */
+interface FlagEvaluator {
+  boolean(key: string, fallback: boolean, ctx?: Context): boolean;
+  string(key: string, fallback: string, ctx?: Context): string;
+  number(key: string, fallback: number, ctx?: Context): number;
+  json<T extends JsonValue = JsonValue>(key: string, fallback: T, ctx?: Context): T;
+  /** Full engine result (value, reason, matched rule, trace). No type check is applied. */
+  evaluate<T extends JsonValue = JsonValue>(key: string, fallback: T, ctx?: Context): Evaluation<T>;
+}
+/**
+ * Evaluator bound to one test session. While `active`, flags are evaluated against the session's
+ * pinned bundle with the context `{ ...session.context, ...ctx }` and sampled events carry the
+ * session id. When the session is unknown, not permitted for this service, or expired, it evaluates
+ * exactly like the client (`active` is false). It never throws.
+ */
+interface SessionEvaluator extends FlagEvaluator {
+  /** True while the session is known and has not expired. Re-evaluated on every read. */
+  readonly active: boolean;
+  /** Session id, or null when the session could not be resolved. */
+  readonly id: string | null;
+  /** ISO timestamp, or null when the session could not be resolved. */
+  readonly expiresAt: string | null;
+  /** Revision evaluations currently run against (the pinned one while active, otherwise the client's). */
+  readonly revision: number | null;
+}
+interface SessionOptions {
+  /** Service name sent as `X-NanoFlags-Service`. Defaults to the client's `service`. */
+  service?: string;
+}
+interface UpdateEvent {
+  revision: number;
+  previousRevision: number | null;
+  checksum: string | null;
+  source: "network" | "store" | "bootstrap";
+  /**
+   * Milliseconds from the commit of the revision in the database to this event — only for revisions
+   * pushed over the live socket (`transport: "live"`) that carry the commit time; otherwise null.
+   * It compares the database's clock with this machine's, so it is as accurate as their clocks agree.
+   */
+  latencyMs: number | null;
+  /** How this bundle arrived: pushed (`live`), fetched after an SSE notification (`stream`), or anything else (`poll`). */
+  transport: Transport;
+}
+interface NanoFlagsClient {
+  /** Resolves once a usable bundle is loaded, or once the first load attempt has finished without one. Never rejects. */
+  ready(): Promise<void>;
+  readonly status: ClientStatus;
+  /** Revision of the bundle in use, or null when none is loaded. */
+  readonly revision: number | null;
+  /** How updates reach this client right now: `live` while the WebSocket is open, `stream` while SSE is in use, else `poll`. */
+  readonly transport: Transport;
+  boolean(key: string, fallback: boolean, ctx?: Context): boolean;
+  string(key: string, fallback: string, ctx?: Context): string;
+  number(key: string, fallback: number, ctx?: Context): number;
+  json<T extends JsonValue = JsonValue>(key: string, fallback: T, ctx?: Context): T;
+  /** Full engine result (value, reason, matched rule, trace). No type check is applied. */
+  evaluate<T extends JsonValue = JsonValue>(key: string, fallback: T, ctx?: Context): Evaluation<T>;
+  /**
+   * Resolve a test session (`GET /v1/session`, once per token until it expires) and return an
+   * evaluator scoped to it. Never rejects: an unknown or expired session yields an evaluator
+   * whose `active` is false and that behaves like the client.
+   */
+  session(token: string | null | undefined, options?: SessionOptions): Promise<SessionEvaluator>;
+  /**
+   * Browser only. Remember `token` for this page session (sessionStorage) and route this client's
+   * own accessors through the session while it is active. `null` leaves the session.
+   * On servers use `session()` or `@nanoflags/sdk/node` instead: one client serves many requests.
+   */
+  useSession(token: string | null): Promise<SessionEvaluator>;
+  /** Browser only. `{ "x-nanoflags-session": token }` while a page session is set, otherwise `{}`. */
+  sessionHeaders(): Record<string, string>;
+  on(event: "update", cb: (e: UpdateEvent) => void): () => void;
+  on(event: "error", cb: (e: Error) => void): () => void;
+  /** Force a revalidation now. Resolves when it finished (successfully or not). */
+  refresh(): Promise<void>;
+  /** Send queued telemetry now. */
+  flush(): Promise<void>;
+  /** Stops timers, the stream and telemetry. Evaluations keep working on the last bundle. */
+  close(): void;
+  /** For external-store bindings (React): called on every bundle or status change. */
+  subscribe(listener: () => void): () => void;
+  /** Monotonic counter that changes whenever `subscribe` listeners fire. */
+  readonly version: number;
+}
+declare class NanoFlagsError extends Error {
+  readonly code: "network" | "unauthorized" | "http" | "invalid_bundle" | "store" | "config" | "signature" | "session" | "engine" | "environment_deleted";
+  readonly httpStatus?: number | undefined;
+  constructor(message: string, code: "network" | "unauthorized" | "http" | "invalid_bundle" | "store" | "config" | "signature" | "session" | "engine" | "environment_deleted", httpStatus?: number | undefined);
+}
+/** A session token is opaque; it only has to be safe to put in a header. */
+declare function isSessionToken(v: unknown): v is string;
+declare function createClient(options: ClientOptions): NanoFlagsClient;
+export { Store as C, JsonValue as D, Evaluation as E, Reason as O, VerifyOptions as S, Context as T, WebSocketLike as _, FlagEvaluator as a, OFFICIAL_EDGE_URL as b, NanoFlagsError as c, SUPPORTED_ENGINE_VERSION as d, SessionEvaluator as f, WebSocketConstructor as g, UpdateEvent as h, EventsOptions as i, SDK_VERSION as l, Transport as m, ClientOptions as n, LIVE_PROTOCOL as o, SessionOptions as p, ClientStatus as r, NanoFlagsClient as s, CLOSE_ENVIRONMENT_DELETED as t, SESSION_HEADER as u, createClient as v, Bundle as w, OFFICIAL_SIGNING_KEYS as x, isSessionToken as y };

package/dist/index.cjs

@@ -0,0 +1,12 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_src = require("./src-IVd-Wps4.cjs");
+exports.CLOSE_ENVIRONMENT_DELETED = require_src.CLOSE_ENVIRONMENT_DELETED;
+exports.LIVE_PROTOCOL = require_src.LIVE_PROTOCOL;
+exports.NanoFlagsError = require_src.NanoFlagsError;
+exports.OFFICIAL_EDGE_URL = require_src.OFFICIAL_EDGE_URL;
+exports.OFFICIAL_SIGNING_KEYS = require_src.OFFICIAL_SIGNING_KEYS;
+exports.SDK_VERSION = require_src.SDK_VERSION;
+exports.SESSION_HEADER = require_src.SESSION_HEADER;
+exports.SUPPORTED_ENGINE_VERSION = require_src.SUPPORTED_ENGINE_VERSION;
+exports.createClient = require_src.createClient;
+exports.isSessionToken = require_src.isSessionToken;

package/dist/index.d.cts

@@ -0,0 +1,13 @@
+/**
+ * @nanoflags/sdk — isomorphic core.
+ *
+ * Flags are evaluated locally and synchronously against an in-memory bundle. The network is only
+ * used in the background: to load the bundle, to learn about new revisions, and to send sampled
+ * telemetry. A flag accessor never performs I/O and never throws.
+ *
+ * New revisions arrive over one of three transports, best first: the live WebSocket (`/v1/live`,
+ * the edge pushes the signed bundle itself — no request follows), the SSE stream (`/v1/stream`,
+ * a notification followed by a conditional fetch), and polling (`/v1/bundle`).
+ */
+import { C as Store, D as JsonValue, E as Evaluation, O as Reason, S as VerifyOptions, T as Context, _ as WebSocketLike, a as FlagEvaluator, b as OFFICIAL_EDGE_URL, c as NanoFlagsError, d as SUPPORTED_ENGINE_VERSION, f as SessionEvaluator, g as WebSocketConstructor, h as UpdateEvent, i as EventsOptions, l as SDK_VERSION, m as Transport, n as ClientOptions, o as LIVE_PROTOCOL, p as SessionOptions, r as ClientStatus, s as NanoFlagsClient, t as CLOSE_ENVIRONMENT_DELETED, u as SESSION_HEADER, v as createClient, w as Bundle, x as OFFICIAL_SIGNING_KEYS, y as isSessionToken } from "./index-D5qa8ji-.cjs";
+export { type Bundle, CLOSE_ENVIRONMENT_DELETED, ClientOptions, ClientStatus, type Context, type Evaluation, EventsOptions, FlagEvaluator, type JsonValue, LIVE_PROTOCOL, NanoFlagsClient, NanoFlagsError, OFFICIAL_EDGE_URL, OFFICIAL_SIGNING_KEYS, type Reason, SDK_VERSION, SESSION_HEADER, SUPPORTED_ENGINE_VERSION, SessionEvaluator, SessionOptions, type Store, Transport, UpdateEvent, type VerifyOptions, WebSocketConstructor, WebSocketLike, createClient, isSessionToken };

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @nanoflags/sdk — isomorphic core.
+ *
+ * Flags are evaluated locally and synchronously against an in-memory bundle. The network is only
+ * used in the background: to load the bundle, to learn about new revisions, and to send sampled
+ * telemetry. A flag accessor never performs I/O and never throws.
+ *
+ * New revisions arrive over one of three transports, best first: the live WebSocket (`/v1/live`,
+ * the edge pushes the signed bundle itself — no request follows), the SSE stream (`/v1/stream`,
+ * a notification followed by a conditional fetch), and polling (`/v1/bundle`).
+ */
+import { C as Store, D as JsonValue, E as Evaluation, O as Reason, S as VerifyOptions, T as Context, _ as WebSocketLike, a as FlagEvaluator, b as OFFICIAL_EDGE_URL, c as NanoFlagsError, d as SUPPORTED_ENGINE_VERSION, f as SessionEvaluator, g as WebSocketConstructor, h as UpdateEvent, i as EventsOptions, l as SDK_VERSION, m as Transport, n as ClientOptions, o as LIVE_PROTOCOL, p as SessionOptions, r as ClientStatus, s as NanoFlagsClient, t as CLOSE_ENVIRONMENT_DELETED, u as SESSION_HEADER, v as createClient, w as Bundle, x as OFFICIAL_SIGNING_KEYS, y as isSessionToken } from "./index-D5qa8ji-.js";
+export { type Bundle, CLOSE_ENVIRONMENT_DELETED, ClientOptions, ClientStatus, type Context, type Evaluation, EventsOptions, FlagEvaluator, type JsonValue, LIVE_PROTOCOL, NanoFlagsClient, NanoFlagsError, OFFICIAL_EDGE_URL, OFFICIAL_SIGNING_KEYS, type Reason, SDK_VERSION, SESSION_HEADER, SUPPORTED_ENGINE_VERSION, SessionEvaluator, SessionOptions, type Store, Transport, UpdateEvent, type VerifyOptions, WebSocketConstructor, WebSocketLike, createClient, isSessionToken };

package/dist/index.js

@@ -0,0 +1 @@
+export { t as CLOSE_ENVIRONMENT_DELETED, n as LIVE_PROTOCOL, r as NanoFlagsError, l as OFFICIAL_EDGE_URL, u as OFFICIAL_SIGNING_KEYS, i as SDK_VERSION, a as SESSION_HEADER, o as SUPPORTED_ENGINE_VERSION, s as createClient, c as isSessionToken } from "./src-CVTvEKbT.js";