@avsbhq/node 1.6.2 → 1.7.1

package/dist/index.d.ts

@@ -1,54 +1,172 @@
-import { FlagDatafile, StickyBucketService, Logger, EvaluationSource, StickyAssignment, DecideOption, Flag, TrackPayload, DecisionLog, InitResult, EvalContext } from '@avsbhq/core';
+import { LogLevel, Logger, FlagDatafile, StickyBucketService, DecideOption, DecisionLog, Flag, ExposureEvent, StickyAssignment, TrackPayload, EvalContext, InitResult } from '@avsbhq/core';
 export { DatafileDataset, DatafileDatasetType, DecideOption, DecisionLog, DecisionLogEntry, EvalContext, EvaluationSource, ExposureEvent, Flag, FlagDatafile, FlagEvaluationDetails, InitResult, Logger, MetricEvent, MultiContext, PurchaseHistoryAttribute, RuleType, SingleContext, StickyAssignment, StickyBucketService, TrackPayload, consoleLogger, consoleTransport, createLogger, noopLogger } from '@avsbhq/core';
 import { AvsbUtils } from '@avsbhq/utils';
 export { AvsbUtils } from '@avsbhq/utils';
+export { ExpressAvsbServer, ExpressMiddlewareOptions, expressMiddleware } from '@avsbhq/utils/middleware/express';
+export { FastifyAvsbServer, FastifyPluginOptions, fastifyPlugin } from '@avsbhq/utils/middleware/fastify';
 export { StreamingClient, StreamingOptions, createStreamingClient } from '@avsbhq/utils/streaming';
 
+/**
+ * Server-side datasets read client (e-commerce suite Phase 2).
+ *
+ * Resolves the live version of a dataset from the SDK's datafile
+ * (`datasets` field) and fetches a single key from the edge worker:
+ *
+ *   GET {ingestionHost}/v1/ds/{sdkKey}/{slug}/{versionShortId}/{key}
+ *
+ * The ingestion host is derived from the datafile's `collectEndpoint`,
+ * exactly like the server tracker derives `/v1/collect/*`. The worker's
+ * key cache resolves SDK keys as well as snippet keys in the first path
+ * segment.
+ *
+ * Error posture matches flag evaluation: this client NEVER throws.
+ * Unknown slug, missing live version, SDK not ready, HTTP errors and
+ * network failures all degrade to `{ found: false }`.
+ */
+interface DatasetGetResult {
+    found: boolean;
+    /** Parsed row for TABLE/FEED datasets; `true` for LIST membership hits. */
+    value?: unknown;
+    meta: {
+        slug: string;
+        /** Live version short id used for the lookup; null when unresolvable. */
+        version: number | null;
+    };
+}
+interface DatasetsClient {
+    /**
+     * Look up `key` in the live version of dataset `slug`.
+     * Resolves the version from the current datafile and never throws.
+     */
+    get(slug: string, key: string): Promise<DatasetGetResult>;
+}
+
+/** `logLevel` option values. 'silent' selects the noop logger. */
+type ServerLogLevel = LogLevel | 'silent';
+/**
+ * True when this process looks like a development environment. Exported so
+ * the behaviour is directly testable and so a caller can mirror the decision.
+ */
+declare function isDevEnvironment(): boolean;
+/**
+ * The logger used when the caller passed neither `logger` nor `logLevel`:
+ * console at warn level in development, noop otherwise.
+ */
+declare function defaultLogger(): Logger;
+/** Resolve the constructor's logging options into one Logger. */
+declare function resolveServerLogger(options: {
+    logger?: Logger;
+    logLevel?: ServerLogLevel;
+}): Logger;
+
 interface AvsbServerOptions {
-    /** SDK key for the flag environment (e.g., "env_abc123") */
+    /**
+     * SDK key for the environment, shaped `sdk_<environment>_<id>`, for example
+     * `sdk_production_ttqm0eaj4vth1krcb2xn`. Copy it from app.avsb.cloud, then
+     * Settings, then Environments. The shape is checked at construction and an
+     * unrecognisable value is logged (never thrown) with what looked wrong.
+     */
     sdkKey: string;
     /** Datafile polling interval in ms. Default: 60_000 (60s). Min: 5_000. */
     pollingInterval?: number;
     /** CDN host for datafile fetches. Default: "https://cdn.avsb.cloud" */
     cdnHost?: string;
-    /** Max ms to wait for initial datafile fetch in onReady(). Default: 10_000. */
+    /** Max ms to wait for the initial datafile fetch in onReady(). Default: 10_000. */
     initTimeout?: number;
-    /** Pre-fetched datafile to skip initial network request. */
+    /** Pre-fetched datafile, so onReady() resolves without a network request. */
     bootstrap?: FlagDatafile;
-    /** Enable SSE streaming for real-time datafile updates. Default: false. */
+    /**
+     * Real-time datafile updates over SSE. Default: TRUE on the server
+     * (breaking change B12): server connection counts are low, one SSE stream
+     * per process is cheaper than polling, and flag changes then land instantly.
+     *
+     * Falling back is invisible: if the datafile carries no `streamEndpoint` and
+     * no `streamingEndpoint` option was passed, or the stream cannot be opened,
+     * the SDK keeps polling and says so at debug level. Flags still update, just
+     * on the polling interval. Pass `false` to force polling only.
+     */
     streaming?: boolean;
-    /** Custom SSE endpoint URL. Default: derived from app URL. */
+    /**
+     * Stream TICKET endpoint. Overrides the datafile's `streamEndpoint` field.
+     * Only needed for a self-hosted or proxied deployment whose publisher does
+     * not set the field; nothing is ever guessed from another host.
+     */
     streamingEndpoint?: string;
     /** Event tracking configuration. */
     events?: EventOptions;
     /** Pluggable sticky bucketing service. */
     stickyBucketService?: StickyBucketService;
-    /** Custom logger. Default: silent (no output). */
+    /**
+     * Custom logger. Default: console at warn level when NODE_ENV is neither
+     * 'production' nor 'test', noop otherwise.
+     */
     logger?: Logger;
+    /**
+     * Shorthand for the default logger's level. `'silent'` restores the old
+     * no-output behaviour. Ignored when `logger` is passed.
+     */
+    logLevel?: ServerLogLevel;
 }
 interface EventOptions {
     /** Ms between automatic event flushes. Default: 2000. */
     flushInterval?: number;
     /** Max events per HTTP request. Default: 10. */
     batchSize?: number;
-    /** Max events in queue. Oldest dropped when exceeded. Default: 10_000. */
+    /**
+     * Max events held in a queue. Oldest dropped when exceeded, with a warning.
+     * Applies to the tracker's queues AND to the pre-ready queue that holds
+     * events tracked before the first datafile arrives. Default: 10_000.
+     */
     maxQueueSize?: number;
     /** Retry attempts on flush failure. Default: 3. */
     retryAttempts?: number;
 }
+
+/**
+ * Options for a single evaluation. The CONTEXT is not in here: it is the third
+ * positional argument of every evaluation call (breaking change B3), matching
+ * `@avsbhq/edge`, so one shape reads the same in every server SDK.
+ */
+interface ServerGetFlagOptions {
+    /** Per-call decide options. See ./decideOptions.ts for the two members. */
+    decideOptions?: DecideOption[];
+    /** Append this evaluation to a decision log. */
+    decisionLog?: DecisionLog;
+}
+interface GetAllFlagsOptions {
+    /**
+     * Record an exposure for every flag evaluated. Default FALSE: reading the
+     * whole flag set is a diagnostic or an SSR bootstrap, not a decision a
+     * visitor saw, and firing hundreds of exposures per request would corrupt
+     * every experiment in the project.
+     */
+    fireExposures?: boolean;
+    decideOptions?: DecideOption[];
+    /** Append every evaluation to a decision log. */
+    decisionLog?: DecisionLog;
+}
 type ServerEventMap = {
     ready: () => void;
+    /** A newly published datafile was applied, and how it arrived. */
     configUpdate: (data: {
         publishedAt: string;
+        reason: 'poll' | 'stream' | 'manual';
     }) => void;
+    /** One flag was evaluated. Fires whether or not an exposure was recorded. */
     evaluation: (data: {
         flagKey: string;
-        value: unknown;
-        userId: string;
-        source: EvaluationSource;
+        flag: Flag;
+        contextKeys: string[];
     }) => void;
+    /**
+     * An exposure was recorded and queued for delivery. This is the server-side
+     * seam for forwarding decisions to your own analytics: it carries the SAME
+     * `eventId` the ingestion pipeline receives, so rows reconcile across
+     * systems.
+     */
+    exposure: (event: ExposureEvent) => void;
     error: (error: Error) => void;
-    /** Fired when a sticky assignment references a rule that no longer matches the datafile. */
+    /** A sticky assignment references a rule that no longer matches the datafile. */
     stickyOrphan: (data: {
         flagKey: string;
         userId: string;
@@ -56,12 +174,6 @@ type ServerEventMap = {
     }) => void;
 };
 type ServerEventName = keyof ServerEventMap;
-interface MiddlewareConfig {
-    /** Extract userId from the request. Return undefined to skip AvsB for this request. */
-    userIdFrom: (req: unknown) => string | undefined;
-    /** Extract targeting attributes from the request. */
-    attributesFrom?: (req: unknown) => Record<string, unknown>;
-}
 
 /**
  * Purchase order shape for server-side purchase tracking.
@@ -100,41 +212,6 @@ interface PurchaseOrder {
     }>;
 }
 
-/**
- * Server-side datasets read client (e-commerce suite Phase 2).
- *
- * Resolves the live version of a dataset from the SDK's datafile
- * (`datasets` field) and fetches a single key from the edge worker:
- *
- *   GET {ingestionHost}/v1/ds/{sdkKey}/{slug}/{versionShortId}/{key}
- *
- * The ingestion host is derived from the datafile's `collectEndpoint`,
- * exactly like the server tracker derives `/v1/collect/*`. The worker's
- * key cache resolves SDK keys as well as snippet keys in the first path
- * segment.
- *
- * Error posture matches flag evaluation: this client NEVER throws.
- * Unknown slug, missing live version, SDK not ready, HTTP errors and
- * network failures all degrade to `{ found: false }`.
- */
-interface DatasetGetResult {
-    found: boolean;
-    /** Parsed row for TABLE/FEED datasets; `true` for LIST membership hits. */
-    value?: unknown;
-    meta: {
-        slug: string;
-        /** Live version short id used for the lookup; null when unresolvable. */
-        version: number | null;
-    };
-}
-interface DatasetsClient {
-    /**
-     * Look up `key` in the live version of dataset `slug`.
-     * Resolves the version from the current datafile and never throws.
-     */
-    get(slug: string, key: string): Promise<DatasetGetResult>;
-}
-
 /**
  * Server-side recommendations client (e-commerce suite overhaul, contract C3).
  *
@@ -225,156 +302,289 @@ interface DatafileRecipe {
 }
 
 /**
- * A per-request scoped client with a bound EvalContext.
+ * A per-request client with a bound `EvalContext`. THE primary server pattern:
+ * bind the context once at the edge of the request, then read flags anywhere
+ * inside it without threading identity through every signature.
  *
  * Created via `server.forUser(ctx)` or the `server.createUserContext(ctx)`
- * alias. All flag evaluations and track calls use the bound context.
+ * alias. Every flag and track call uses the bound context, and the instance
+ * carries its own decision log.
  *
- * Forced decisions set on a UserBoundClient survive only for the lifetime
- * of the instance; they do not affect the shared AvsbServer override state.
- * This makes them safe for test middleware and per-request debugging.
- *
- * Spec §5.8.
+ * Forced decisions set here live only for the lifetime of this instance; they
+ * never touch the shared `AvsbServer` override state, which is what makes them
+ * safe in test middleware and per-request debugging.
  */
 interface UserBoundClient {
-    getFlag<T>(flagKey: string, defaultValue: T, options?: {
-        decideOptions?: DecideOption[];
-    }): Flag<T>;
-    getBoolFlag(flagKey: string, defaultValue: boolean, options?: {
-        decideOptions?: DecideOption[];
-    }): Flag<boolean>;
-    getStringFlag(flagKey: string, defaultValue: string, options?: {
-        decideOptions?: DecideOption[];
-    }): Flag<string>;
-    getNumberFlag(flagKey: string, defaultValue: number, options?: {
-        decideOptions?: DecideOption[];
-    }): Flag<number>;
-    getJsonFlag<T>(flagKey: string, defaultValue: T, options?: {
-        decideOptions?: DecideOption[];
-    }): Flag<T>;
+    /** Evaluate against the bound context. Returns `Flag<T>`, never a raw value. */
+    getFlag<T>(flagKey: string, defaultValue: T, options?: ServerGetFlagOptions): Flag<T>;
+    /** Type-checked against the datafile's declared flag type; falls back to the default on a mismatch. */
+    getBoolFlag(flagKey: string, defaultValue: boolean, options?: ServerGetFlagOptions): Flag<boolean>;
+    getStringFlag(flagKey: string, defaultValue: string, options?: ServerGetFlagOptions): Flag<string>;
+    getNumberFlag(flagKey: string, defaultValue: number, options?: ServerGetFlagOptions): Flag<number>;
+    getJsonFlag<T>(flagKey: string, defaultValue: T, options?: ServerGetFlagOptions): Flag<T>;
+    /** Every flag in the environment for the bound context. Exposures off by default. */
     getAllFlags(options?: GetAllFlagsOptions): Record<string, Flag>;
+    /** Queue a metric event attributed to the bound context. */
     track(eventKey: string, payload?: Omit<TrackPayload, 'context'>): void;
+    /** Send a purchase attributed to the bound context's bucketing key. */
+    trackPurchase(order: PurchaseOrder): Promise<void>;
+    /** Record an exposure for a decision the visitor has now actually seen. */
+    manualExposure(flagKey: string): void;
+    /** The context this client is bound to. */
+    getContext(): EvalContext;
     setForcedDecision(flagKey: string, opts: {
         ruleId?: string;
         variationKey: string;
     }): void;
     clearForcedDecision(flagKey: string): void;
+    /** Every decision this request made, redacted per the context's private attributes. */
     getDecisionLog(): DecisionLog;
 }
 
-interface GetFlagOptions {
-    context?: EvalContext;
-    decideOptions?: DecideOption[];
-    decisionLog?: DecisionLog;
-    /** Internal: UserBoundClient forced decision override. */
+/**
+ * @internal Superset of the public per-call options, carrying the two things
+ * only this package may set. Not exported from the package entry.
+ */
+interface InternalGetFlagOptions extends ServerGetFlagOptions {
+    /** Forced decision from a UserBoundClient, applied before evaluation. */
     forcedVariationKey?: string;
-}
-interface GetAllFlagsOptions {
-    fireExposures?: boolean;
-    decideOptions?: DecideOption[];
+    /** Runtime type check to apply, from a typed getter. */
+    expectedType?: 'boolean' | 'string' | 'number' | 'json';
 }
 declare class AvsbServer {
-    private sdkKey;
-    private pollingInterval;
-    private cdnHost;
-    private initTimeout;
-    private logger;
-    private stickyBucketService;
-    private eventOptions;
-    private streamingEnabled;
-    private streamingEndpoint;
+    private readonly sdkKey;
+    private readonly cdnHost;
+    private readonly pollingInterval;
+    private readonly initTimeout;
+    private readonly logger;
+    private readonly stickyBucketService;
+    private readonly eventOptions;
+    private readonly streamingEnabled;
+    private readonly streamingEndpointOption;
+    private readonly overrides;
+    private readonly resolveDecideOptions;
     private datafile;
+    private datafileEtag;
     private ready;
     private destroyed;
     private tracker;
     private streamingClient;
-    private pollingId;
+    private pollingTimer;
     private abortController;
-    private overrides;
     private listeners;
     private readyPromise;
     private pendingEvents;
+    private pendingPurchases;
     /**
-     * §6: `client.utils.*` surface. Constructed lazily on first access so
-     * the utils package is only imported when actually consumed.
-     *
-     * The server's event surface (`ServerEventMap`) is a subset of the
-     * shared `ClientEventMap`; the utils-adapter `on` here ignores events
-     * the server doesn't emit (e.g. `flagChange`). Workstream 5 (CoW 6)
-     * harmonises the two maps when the streaming evaluator lands.
+     * Exposures produced before the tracker existed. Third member of the
+     * pre-ready family alongside `pendingEvents` and `pendingPurchases`; it used
+     * to be missing, and exposures were dropped on the floor instead.
+     */
+    private pendingExposures;
+    /** ms-epoch of the last liveness heartbeat, for the throttle. */
+    private lastHeartbeatAt;
+    /** Keys of one-time warnings, so a request loop cannot flood a log. */
+    private readonly warnedOnce;
+    /**
+     * `client.utils.*` surface, constructed lazily on first access so the utils
+     * package is only imported when actually consumed.
      */
     private _utils;
     get utils(): AvsbUtils;
     /**
-     * Server-side datasets read surface (e-commerce suite Phase 2).
-     * Constructed lazily on first access, mirroring the `utils` getter.
-     * `client.datasets.get(slug, key)` resolves the live version from the
-     * current datafile and never throws; see ./datasets.ts.
+     * Server-side datasets read surface. `client.datasets.get(slug, key)`
+     * resolves the live version from the current datafile and never throws.
      */
     private _datasets;
     get datasets(): DatasetsClient;
     /**
-     * Server-side recommendations surface (e-commerce suite overhaul, C3).
-     * Constructed lazily on first access, mirroring the `datasets` getter.
-     * `client.recs.get({ recipe, … })` resolves the recipe registry from the
-     * current datafile and never throws; impressions/clicks ride the server
-     * tracker's queue and revenue attaches via the existing `trackPurchase`.
+     * Server-side recommendations surface. `client.recs.get({ recipe, … })`
+     * resolves the recipe registry from the current datafile and never throws;
+     * impressions and clicks ride the server tracker's queue and revenue
+     * attaches via `trackPurchase`.
      */
     private _recs;
     get recs(): RecsClient;
     constructor(options: AvsbServerOptions);
+    /**
+     * Await the init attempt. Never rejects; always resolves to an InitResult.
+     * Calling it twice returns the same promise.
+     */
     onReady(): Promise<InitResult>;
+    /** True when a datafile is loaded and flags are answerable right now. */
+    isReady(): boolean;
     private initializeAndReady;
+    /** Wiring that runs once a datafile is readable, however it arrived. */
+    private onDatafileReadable;
     close(): Promise<void>;
     flush(): Promise<void>;
+    /**
+     * Fetch the datafile now and apply it if it changed.
+     *
+     * A 304 is not a problem and is not warned about: it means the datafile in
+     * memory IS the published one.
+     */
     refreshDatafile(): Promise<void>;
-    getFlag<T>(flagKey: string, defaultValue: NoInfer<T> | T, options?: GetFlagOptions): Flag<T>;
-    getBoolFlag(flagKey: string, defaultValue: NoInfer<boolean> | boolean, options?: GetFlagOptions): Flag<boolean>;
-    getStringFlag(flagKey: string, defaultValue: NoInfer<string> | string, options?: GetFlagOptions): Flag<string>;
-    getNumberFlag(flagKey: string, defaultValue: NoInfer<number> | number, options?: GetFlagOptions): Flag<number>;
-    getJsonFlag<T>(flagKey: string, defaultValue: NoInfer<T> | T, options?: GetFlagOptions): Flag<T>;
-    getAllFlags(context: EvalContext, options?: GetAllFlagsOptions): Record<string, Flag>;
-    trackPurchase(visitorId: string, order: PurchaseOrder): Promise<void>;
+    /**
+     * Adopt a datafile received out of band: a bootstrap blob from
+     * `client.utils.hydrateBootstrap`, a file on disk, a KV read at cold start.
+     *
+     * Marks the SDK ready, drains anything queued before it, and starts polling
+     * and streaming exactly as a network arrival would. This used to be a no-op
+     * comment inside the utils adapter, which made the documented bootstrap
+     * handoff silently do nothing.
+     */
+    applyDatafileBootstrap(datafile: FlagDatafile): void;
+    /** The datafile currently in memory, or null before init completes. */
+    getDatafile(): FlagDatafile | null;
+    getFlag<T>(flagKey: string, defaultValue: NoInfer<T> | T, context?: EvalContext, options?: ServerGetFlagOptions): Flag<T>;
+    getBoolFlag(flagKey: string, defaultValue: NoInfer<boolean> | boolean, context?: EvalContext, options?: ServerGetFlagOptions): Flag<boolean>;
+    getStringFlag(flagKey: string, defaultValue: NoInfer<string> | string, context?: EvalContext, options?: ServerGetFlagOptions): Flag<string>;
+    getNumberFlag(flagKey: string, defaultValue: NoInfer<number> | number, context?: EvalContext, options?: ServerGetFlagOptions): Flag<number>;
+    getJsonFlag<T>(flagKey: string, defaultValue: NoInfer<T> | T, context?: EvalContext, options?: ServerGetFlagOptions): Flag<T>;
+    /**
+     * @internal Single evaluation entry point for this package. `UserBoundClient`
+     * calls it with a bound context and forced decisions. Not part of the
+     * published API: its options bag carries package-internal fields.
+     */
+    evaluateInternal<T>(flagKey: string, defaultValue: NoInfer<T> | T, context?: EvalContext, options?: InternalGetFlagOptions): Flag<T>;
+    private evaluateAndBuild;
+    private checkType;
+    /**
+     * Every flag in the environment, evaluated against one context.
+     *
+     * Positional context (B3). Note the deliberate difference from
+     * `@avsbhq/browser`, which keeps an options bag (`getAllFlags({context})`)
+     * because it is context-bound and the bag disambiguates its optional
+     * arguments.
+     */
+    getAllFlags(context?: EvalContext, options?: GetAllFlagsOptions): Record<string, Flag>;
+    /**
+     * Queue a metric (conversion) event. Synchronous: it returns as soon as the
+     * event is queued, and the tracker batches it.
+     *
+     * The context rides in the payload rather than positionally because it is
+     * OPTIONAL vocabulary on the shared `TrackPayload` type and required only on
+     * the server; see the README for why the two runtimes read differently here.
+     */
     track(eventKey: string, payload: TrackPayload & {
         context: EvalContext;
     }): void;
+    /**
+     * Send a purchase to `/v1/collect/orders`.
+     *
+     * Queued before the tracker exists, exactly like `track` (they used to
+     * disagree: one queued, the other warned and dropped the order).
+     */
+    trackPurchase(visitorId: string, order: PurchaseOrder): Promise<void>;
+    /**
+     * Mark the moment a signup or login claimed an anonymous session. Same shape
+     * and same honesty as the browser client's `alias`.
+     *
+     * WHAT IT DOES: queues one `avsb_alias` event attributed to the NEW
+     * identity's key.
+     *
+     * WHAT IT DOES NOT DO, precisely:
+     *   - It does not rewrite sticky assignments or move past exposures. Nothing
+     *     already decided for either identity changes.
+     *   - It does not store the PREVIOUS key. The conversion wire
+     *     (`/v1/collect/metric-batch`) carries no properties column, so a
+     *     retroactive session join is not available yet.
+     *
+     * To keep one visitor's bucketing across a login, evaluate with the SAME
+     * context key on both sides. See "Sharing identity with the web snippet" in
+     * the README for the cross-surface version of the same rule.
+     */
+    alias(previousContext: EvalContext, newContext: EvalContext): void;
+    /**
+     * Record an exposure for a flag without re-serving its value. Use it when
+     * the decision was read earlier with exposures suppressed and the visitor has
+     * now actually seen the result.
+     */
     manualExposure(flagKey: string, context: EvalContext): void;
+    /** A client with the context bound. The primary server pattern. */
     forUser(context: EvalContext): UserBoundClient;
+    /** Ergonomic alias for `forUser`. */
     createUserContext(context: EvalContext): UserBoundClient;
     setOverrideForUser(flagKey: string, contextKey: string, variationKey: string, contextKind?: string): void;
     setGlobalOverride(flagKey: string, variationKey: string): void;
     clearOverrideForUser(flagKey: string, contextKey: string, contextKind?: string): void;
     clearGlobalOverride(flagKey: string): void;
     clearAllOverrides(): void;
+    /** A fresh decision log to pass per call. `forUser` carries its own. */
     createDecisionLog(): DecisionLog;
     on<E extends ServerEventName>(event: E, cb: ServerEventMap[E]): () => void;
     off<E extends ServerEventName>(event: E, cb: ServerEventMap[E]): void;
+    /**
+     * `on` for the shared `ClientEventMap` names the utils layer speaks. The
+     * server emits every one of them except `flagChange`, which needs per-flag
+     * diffing the server does not do; subscribing to it warns and hands back a
+     * no-op disposer instead of pretending.
+     */
+    private onSharedEvent;
+    private emit;
+    private warnOnce;
     private evaluate;
-    private getTypedFlag;
+    /**
+     * One exposure, delivered everywhere: queued for ingestion AND emitted on
+     * the event bus with the SAME `eventId`, so a customer forwarding decisions
+     * to their own analytics can reconcile rows with A vs B results.
+     */
+    private deliverExposure;
     private toFlag;
-    /** toFlag variant that never writes a decision log (used by getAllFlags suppressed path). */
-    private toFlagNoLog;
-    /** Build a Flag<T> from a forced variation key (per-request override). */
-    private buildFlagFromVariationKey;
+    /** Build a Flag from a forced variation key (per-request forced decision). */
+    private buildForcedFlag;
+    /** Emit the evaluation event and append to a decision log if one was passed. */
+    private recordDecision;
     private buildLegacyContext;
-    private resolveRuntimeOverride;
     private resolveStickyBucket;
     private findVariation;
     private fireExposureForStickyAssignment;
-    private emit;
-    private emitEvaluation;
     private initTracker;
-    private startStreamingIfEnabled;
-    private fetchDatafile;
+    private enqueuePendingExposure;
+    private enqueuePending;
+    /**
+     * Fetch and apply the datafile.
+     *
+     * Three outcomes, not two, because a conditional request has three:
+     *   'applied'   a datafile came back and is now in memory
+     *   'unchanged' the CDN answered 304: what we hold IS current
+     *   'failed'    nothing usable came back; the error is already logged
+     *
+     * 'unchanged' is a success. Collapsing it into 'failed' made
+     * `refreshDatafile()` warn that a refresh "did not apply a new datafile"
+     * every time the datafile was simply up to date.
+     */
+    private loadDatafile;
+    /**
+     * Poll on a JITTERED interval. Without the jitter every process that
+     * deployed together polls the CDN on the same tick forever.
+     */
     private startPolling;
+    /**
+     * Open the SSE stream when one is available, and fall back to polling in
+     * silence when it is not (B12). The endpoint comes from the datafile's
+     * `streamEndpoint` field, or an explicit option; it is never guessed from
+     * another host, which is what gave one port an infinite reconnect loop
+     * against DNS that does not resolve.
+     */
+    private startStreamingIfEnabled;
+    /**
+     * Report liveness, throttled.
+     *
+     * Called on every successful datafile load, not just at init: the dashboard
+     * marks an environment Stale after five minutes without a heartbeat, so an
+     * init-only heartbeat made every long-running process look dead a few
+     * minutes after it started. The throttle keeps a fast polling interval (or a
+     * burst of stream-triggered refreshes) from turning liveness into traffic.
+     *
+     * Fire and forget: a failed heartbeat never affects evaluation, and the
+     * throttle clock is stamped by the synchronous send below, so a hanging
+     * request cannot queue a second one.
+     */
     private sendHeartbeat;
 }
 
-declare function expressMiddleware(client: AvsbServer, config: MiddlewareConfig): (req: unknown, res: unknown, next: () => void) => void;
-declare function fastifyPlugin(instance: unknown, opts: {
-    client: AvsbServer;
-} & MiddlewareConfig, done: () => void): void;
-
 declare class InMemoryStickyBucketService implements StickyBucketService {
     private cache;
     private key;
@@ -412,6 +622,60 @@ declare class RedisStickyBucketService implements StickyBucketService {
 
 declare function createDecisionLog(): DecisionLog;
 
-declare const SDK_VERSION = "1.6.2";
+/** Default replay window: a delivery more than 5 minutes old is rejected. */
+declare const DEFAULT_TOLERANCE_SECONDS = 300;
+/**
+ * Header bag shapes this accepts, so it works with Node's `IncomingHttpHeaders`,
+ * a plain object, or a `Headers` instance (via `Object.fromEntries(headers)`).
+ */
+type WebhookHeaders = Record<string, string | string[] | undefined> | {
+    get(name: string): string | null;
+};
+interface VerifyWebhookOptions {
+    /**
+     * How old a delivery may be, in seconds. Defaults to 300 (5 minutes). Set to 0 to
+     * skip the age check entirely — only do that when you dedupe on the delivery id and
+     * accept replays.
+     */
+    toleranceSeconds?: number;
+    /** Injectable clock, in ms since the epoch. Exists for tests. */
+    now?: () => number;
+}
+/** Why verification failed. `ok: false` always carries one of these. */
+type WebhookVerifyFailure = 'missing_headers' | 'malformed_signature' | 'malformed_timestamp' | 'timestamp_out_of_tolerance' | 'signature_mismatch';
+type WebhookVerifyResult = {
+    ok: true;
+    deliveryId: string;
+    timestamp: string;
+} | {
+    ok: false;
+    reason: WebhookVerifyFailure;
+    message: string;
+};
+/**
+ * Verify one webhook delivery.
+ *
+ * @param payload The RAW request body, exactly as received (string or Buffer). Never
+ *   a parsed-and-re-serialised object.
+ * @param headers The request headers.
+ * @param secret The webhook's signing secret, from the create or rotate response.
+ *
+ * @example
+ * ```ts
+ * import express from 'express'
+ * import { verifyWebhookSignature } from '@avsbhq/node'
+ *
+ * app.post('/avsb-webhook', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const result = verifyWebhookSignature(req.body, req.headers, process.env.AVSB_WEBHOOK_SECRET!)
+ *   if (!result.ok) return res.status(401).send(result.reason)
+ *   const event = JSON.parse(req.body.toString('utf8'))
+ *   // ... handle event, deduped on result.deliveryId
+ *   res.sendStatus(200)
+ * })
+ * ```
+ */
+declare function verifyWebhookSignature(payload: string | Buffer, headers: WebhookHeaders, secret: string, options?: VerifyWebhookOptions): WebhookVerifyResult;
+
+declare const SDK_VERSION = "1.7.1";
 
-export { AvsbServer, type AvsbServerOptions, type DatafileRecipe, type DatasetGetResult, type DatasetsClient, type EventOptions, type GetAllFlagsOptions, type GetFlagOptions, InMemoryStickyBucketService, type MiddlewareConfig, type PurchaseOrder, type RecProduct, type RecsAttribution, type RecsClient, type RecsGetRequest, type RecsResult, type RedisLike, type RedisStickyBucketOptions, RedisStickyBucketService, SDK_VERSION, type UserBoundClient, createDecisionLog, expressMiddleware, fastifyPlugin };
+export { AvsbServer, type AvsbServerOptions, DEFAULT_TOLERANCE_SECONDS, type DatafileRecipe, type DatasetGetResult, type DatasetsClient, type EventOptions, type GetAllFlagsOptions, InMemoryStickyBucketService, type PurchaseOrder, type RecProduct, type RecsAttribution, type RecsClient, type RecsGetRequest, type RecsResult, type RedisLike, type RedisStickyBucketOptions, RedisStickyBucketService, SDK_VERSION, type ServerEventMap, type ServerEventName, type ServerGetFlagOptions, type ServerLogLevel, type UserBoundClient, type VerifyWebhookOptions, type WebhookHeaders, type WebhookVerifyFailure, type WebhookVerifyResult, createDecisionLog, defaultLogger, isDevEnvironment, resolveServerLogger, verifyWebhookSignature };