@avsbhq/node 1.7.2 → 1.8.0

package/README.md

@@ -35,8 +35,8 @@ if (!result.success) {
 // Bind the context once per request.
 const user = server.forUser({ kind: 'user', key: 'u_123', plan: 'pro' });
 
-const flag = user.getBoolFlag('new-checkout-flow', false);
-const checkoutTemplate = flag.isEnabled() ? 'checkout-v2' : 'checkout-v1';
+const flag = user.getBoolFlag('new_checkout_flow', false);
+const checkoutTemplate = flag.isEnabled() ? 'checkout_v2' : 'checkout_v1';
 
 user.track('checkout_started', { revenue: 99.0 });
 ```
@@ -139,7 +139,7 @@ const user = server.forUser({
   country: req.user.country,
 });
 
-const flag = user.getBoolFlag('checkout-v2', false);
+const flag = user.getBoolFlag('checkout_v2', false);
 user.track('page_viewed');
 ```
 
@@ -150,7 +150,7 @@ user.track('page_viewed');
 Context is the THIRD POSITIONAL argument on every evaluation call, matching `@avsbhq/edge`:
 
 ```ts
-const flag = server.getBoolFlag('checkout-v2', false, {
+const flag = server.getBoolFlag('checkout_v2', false, {
   kind: 'user',
   key: 'u_123',
   plan: 'pro',
@@ -175,7 +175,7 @@ const user = server.forUser({
 Audiences built with the commerce condition types (cart value, products viewed, purchase history) read fixed attribute names off the context:
 
 ```ts
-const flag = server.getBoolFlag('big-cart-banner', false, {
+const flag = server.getBoolFlag('big_cart_banner', false, {
   kind: 'user',
   key: 'u_123',
   cartValue: 120.5, // decimal MAJOR units of the project currency
@@ -290,7 +290,7 @@ interface Flag<T = unknown> {
 ```ts
 import { DecideOption } from '@avsbhq/node';
 
-user.getBoolFlag('checkout-v2', false, {
+user.getBoolFlag('checkout_v2', false, {
   decideOptions: [DecideOption.DISABLE_EXPOSURE],
 });
 ```
@@ -314,12 +314,12 @@ Called without a context, or before the datafile loads, it returns `{}` AND warn
 ### Overrides, for QA and testing
 
 ```ts
-server.setOverrideForUser('checkout-v2', 'u_qa', 'on');
-server.setOverrideForUser('checkout-v2', 'acme', 'on', 'organization'); // explicit kind
-server.setGlobalOverride('checkout-v2', 'on');
+server.setOverrideForUser('checkout_v2', 'u_qa', 'on');
+server.setOverrideForUser('checkout_v2', 'acme', 'on', 'organization'); // explicit kind
+server.setGlobalOverride('checkout_v2', 'on');
 
-server.clearOverrideForUser('checkout-v2', 'u_qa');
-server.clearGlobalOverride('checkout-v2');
+server.clearOverrideForUser('checkout_v2', 'u_qa');
+server.clearGlobalOverride('checkout_v2');
 server.clearAllOverrides();
 ```
 
@@ -327,8 +327,8 @@ Per-request forced decisions, which never touch the shared state above:
 
 ```ts
 const user = server.forUser({ kind: 'user', key: 'u_qa' });
-user.setForcedDecision('checkout-v2', { variationKey: 'on' });
-user.clearForcedDecision('checkout-v2');
+user.setForcedDecision('checkout_v2', { variationKey: 'on' });
+user.clearForcedDecision('checkout_v2');
 ```
 
 ---
@@ -380,12 +380,12 @@ Purchases are queued before ready exactly like `track`. They used to be dropped
 ### Manual exposure
 
 ```ts
-const flag = user.getBoolFlag('checkout-v2', false, {
+const flag = user.getBoolFlag('checkout_v2', false, {
   decideOptions: [DecideOption.DISABLE_EXPOSURE],
 });
 
 // Later, at the point the visitor actually sees the variation:
-user.manualExposure('checkout-v2');
+user.manualExposure('checkout_v2');
 ```
 
 ---
@@ -474,7 +474,7 @@ actually being served.
 - **Where it shows up**: Environments in the project sidebar, in the dashboard. Each
   environment shows Connected, Stale, or Not connected, plus the `sdkType` and
   `sdkVersion` that last reported, which is how you see "production is running
-  @avsbhq/node 1.6.2". An environment goes Stale after five minutes without a
+  @avsbhq/node 1.8.0". An environment goes Stale after five minutes without a
   heartbeat.
 - **Turning it off**: publish a datafile with no `heartbeatEndpoint`. The SDK
   never guesses a host, so an absent field simply means no heartbeats.
@@ -587,7 +587,7 @@ import { createMockServer, flagsFromTestData, TestData } from '@avsbhq/test';
 
 const server = createMockServer(
   flagsFromTestData([
-    TestData.flag('checkout-v2')
+    TestData.flag('checkout_v2')
       .booleanFlag()
       .variationForUser('u_paying', true)
       .fallthroughVariation(false)
@@ -596,7 +596,7 @@ const server = createMockServer(
 );
 
 const user = server.forUser({ kind: 'user', key: 'u_paying' });
-expect(user.getBoolFlag('checkout-v2', false).value).toBe(true);
+expect(user.getBoolFlag('checkout_v2', false).value).toBe(true);
 expect(server._evaluations()).toHaveLength(1);
 ```
 
@@ -630,7 +630,7 @@ app.use(
 
 // Deep inside a service, with no `req` in scope:
 function pricingService() {
-  return getRequestClient()?.getBoolFlag('new-pricing', false).value ?? false;
+  return getRequestClient()?.getBoolFlag('new_pricing', false).value ?? false;
 }
 ```
 
@@ -640,8 +640,8 @@ Every route then reads flags off `req.avsb`:
 // docs-example: not typechecked here, because express is not a dependency of the A vs B repository, so a route handler's Request and Response types cannot be resolved
 
 app.get('/checkout', (req, res) => {
-  const flag = req.avsb.getBoolFlag('new-checkout-flow', false);
-  res.render(flag.isEnabled() ? 'checkout-v2' : 'checkout-v1');
+  const flag = req.avsb.getBoolFlag('new_checkout_flow', false);
+  res.render(flag.isEnabled() ? 'checkout_v2' : 'checkout_v1');
 });
 ```
 
@@ -682,7 +682,7 @@ await app.register(fastifyPlugin, {
 });
 
 app.get('/features', (req, reply) => {
-  reply.send({ enabled: req.avsb.getBoolFlag('new-feature', false).isEnabled() });
+  reply.send({ enabled: req.avsb.getBoolFlag('new_feature', false).isEnabled() });
 });
 ```
 
@@ -716,7 +716,7 @@ The Redis service keeps evaluation synchronous: a lookup is a cache hit or null,
 
 ```ts
 const user = server.forUser({ kind: 'user', key: 'u_123' });
-user.getBoolFlag('checkout-v2', false);
+user.getBoolFlag('checkout_v2', false);
 
 const entries = user.getDecisionLog().entries;
 // [{ flagKey, value, variationKey, source, ruleId, ruleType, reasons,

package/dist/index.cjs

@@ -482,8 +482,15 @@ async function fetchDatafile(input) {
       );
       return { status: "failed" };
     }
-    const datafile = await response.json();
-    return { status: "ok", datafile, etag: response.headers.get("etag") };
+    const body = await response.json();
+    const problem = (0, import_core3.datafileShapeProblem)(body);
+    if (problem) {
+      input.logger.error(
+        `AvsB datafile from ${url} is not a datafile the SDK can read: ${problem}. The SDK keeps serving whatever datafile it already has and retries on the polling interval.`
+      );
+      return { status: "failed" };
+    }
+    return { status: "ok", datafile: body, etag: response.headers.get("etag") };
   } catch (error) {
     if (input.signal.aborted) return { status: "aborted" };
     input.logger.error(
@@ -492,6 +499,14 @@ async function fetchDatafile(input) {
     return { status: "failed" };
   }
 }
+function acceptDatafile(candidate, origin, logger) {
+  const problem = (0, import_core3.datafileShapeProblem)(candidate);
+  if (problem === null) return candidate;
+  logger.error(
+    origin === "bootstrap" ? `AvsB ignored the bootstrap datafile passed to new AvsbServer(): ${problem}. Flags return the default you passed, with source "not_ready", until a datafile loads from the CDN. Pass the datafile JSON exactly as the CDN serves it for this SDK key.` : `AvsB ignored the datafile passed to applyDatafileBootstrap(): ${problem}. The SDK keeps serving the datafile it already has, if any. Pass the datafile JSON exactly as the CDN serves it for this SDK key.`
+  );
+  return null;
+}
 function sendHeartbeat(input) {
   const endpoint = (0, import_core3.resolveHeartbeatEndpoint)(input.datafileHeartbeatEndpoint);
   if (!endpoint) return null;
@@ -701,7 +716,8 @@ function createServerTracker(options) {
 var import_streaming = require("@avsbhq/utils/streaming");
 
 // src/version.ts
-var SDK_VERSION = "1.7.1";
+var SDK_VERSION = "1.8.0";
+var SDK_TYPE = "@avsbhq/node";
 
 // src/UserBoundClient.ts
 var import_core6 = require("@avsbhq/core");
@@ -811,6 +827,23 @@ function buildServerUtils(server) {
   return (0, import_utils.createUtils)(adapter);
 }
 
+// src/initTimeout.ts
+async function raceInitTimeout(work, timeoutMs) {
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve({ timedOut: true }), timeoutMs);
+    if (typeof timer === "object" && timer !== null && "unref" in timer) timer.unref();
+  });
+  try {
+    return await Promise.race([
+      work.then((value) => ({ timedOut: false, value })),
+      timeout
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // src/AvsbServer.ts
 var DEFAULT_EVENTS = {
   flushInterval: 2e3,
@@ -818,7 +851,6 @@ var DEFAULT_EVENTS = {
   maxQueueSize: 1e4,
   retryAttempts: 3
 };
-var SDK_TYPE = "@avsbhq/node";
 var HEARTBEAT_MIN_INTERVAL_MS = 12e4;
 var AvsbServer = class {
   sdkKey;
@@ -915,8 +947,8 @@ var AvsbServer = class {
     this.eventOptions = { ...DEFAULT_EVENTS, ...options.events };
     this.streamingEnabled = options.streaming !== false;
     this.streamingEndpointOption = options.streamingEndpoint ?? null;
-    this.datafile = options.bootstrap ?? null;
-    this.ready = !!options.bootstrap;
+    this.datafile = options.bootstrap ? acceptDatafile(options.bootstrap, "bootstrap", this.logger) : null;
+    this.ready = this.datafile !== null;
     this.destroyed = false;
     this.tracker = null;
     this.streamingClient = null;
@@ -950,21 +982,13 @@ var AvsbServer = class {
       return { success: true, source: "bootstrap" };
     }
     try {
-      const outcome = await Promise.race([
+      const outcome = await raceInitTimeout(
         // At init there is no stored etag, so 'unchanged' cannot happen here;
         // it is folded in anyway so a future caching layer cannot make init
         // silently report failure.
-        this.loadDatafile().then((result) => ({
-          applied: result !== "failed",
-          timedOut: false
-        })),
-        new Promise(
-          (resolve) => setTimeout(
-            () => resolve({ applied: false, timedOut: true }),
-            this.initTimeout
-          )
-        )
-      ]);
+        this.loadDatafile().then((result) => result !== "failed"),
+        this.initTimeout
+      );
       if (outcome.timedOut) {
         this.startPolling();
         const error2 = new Error(
@@ -973,7 +997,7 @@ var AvsbServer = class {
         this.emit("error", error2);
         return { success: false, source: "timeout", error: error2 };
       }
-      if (outcome.applied) {
+      if (outcome.value) {
         this.onDatafileReadable();
         return { success: true, source: "network" };
       }
@@ -1051,6 +1075,7 @@ var AvsbServer = class {
    */
   applyDatafileBootstrap(datafile) {
     if (this.destroyed) return;
+    if (!acceptDatafile(datafile, "applyDatafileBootstrap", this.logger)) return;
     const changed = this.datafile?.publishedAt !== datafile.publishedAt;
     this.datafile = datafile;
     this.datafileEtag = null;
@@ -1146,6 +1171,9 @@ var AvsbServer = class {
   evaluateAndBuild(flagKey, defaultValue, context, decide, options) {
     const legacyCtx = this.buildLegacyContext(context, decide.suppressExposure);
     const result = this.evaluate(flagKey, legacyCtx, defaultValue);
+    if (result.source === "not_found") {
+      this.warnOnce(`missing:${flagKey}`, (0, import_core8.flagNotFoundMessage)(flagKey));
+    }
     const typeMismatch = this.checkType(flagKey, options?.expectedType, result);
     if (typeMismatch) {
       this.logger.warn(

package/dist/index.d.cts

@@ -676,6 +676,7 @@ type WebhookVerifyResult = {
  */
 declare function verifyWebhookSignature(payload: string | Buffer, headers: WebhookHeaders, secret: string, options?: VerifyWebhookOptions): WebhookVerifyResult;
 
-declare const SDK_VERSION = "1.7.1";
+/** This package's version, reported on every liveness heartbeat as `sdkVersion`. */
+declare const SDK_VERSION = "1.8.0";
 
 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 };

package/dist/index.d.ts

@@ -676,6 +676,7 @@ type WebhookVerifyResult = {
  */
 declare function verifyWebhookSignature(payload: string | Buffer, headers: WebhookHeaders, secret: string, options?: VerifyWebhookOptions): WebhookVerifyResult;
 
-declare const SDK_VERSION = "1.7.1";
+/** This package's version, reported on every liveness heartbeat as `sdkVersion`. */
+declare const SDK_VERSION = "1.8.0";
 
 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 };

package/dist/index.js

@@ -12,7 +12,8 @@ import {
   contextSummary,
   privateAttributesFrom,
   bucketingKey as bucketingKey2,
-  resolveStreamEndpoint
+  resolveStreamEndpoint,
+  flagNotFoundMessage
 } from "@avsbhq/core";
 import { validateSdkKeyShape } from "@avsbhq/utils/sdkKey";
 import { jitteredInterval } from "@avsbhq/utils/backoff";
@@ -427,7 +428,7 @@ function createOverrideStore() {
 }
 
 // src/datafileSource.ts
-import { datafileUrl, resolveHeartbeatEndpoint } from "@avsbhq/core";
+import { datafileShapeProblem, datafileUrl, resolveHeartbeatEndpoint } from "@avsbhq/core";
 async function fetchDatafile(input) {
   const url = datafileUrl(input.sdkKey, input.cdnHost);
   const headers = {};
@@ -441,8 +442,15 @@ async function fetchDatafile(input) {
       );
       return { status: "failed" };
     }
-    const datafile = await response.json();
-    return { status: "ok", datafile, etag: response.headers.get("etag") };
+    const body = await response.json();
+    const problem = datafileShapeProblem(body);
+    if (problem) {
+      input.logger.error(
+        `AvsB datafile from ${url} is not a datafile the SDK can read: ${problem}. The SDK keeps serving whatever datafile it already has and retries on the polling interval.`
+      );
+      return { status: "failed" };
+    }
+    return { status: "ok", datafile: body, etag: response.headers.get("etag") };
   } catch (error) {
     if (input.signal.aborted) return { status: "aborted" };
     input.logger.error(
@@ -451,6 +459,14 @@ async function fetchDatafile(input) {
     return { status: "failed" };
   }
 }
+function acceptDatafile(candidate, origin, logger) {
+  const problem = datafileShapeProblem(candidate);
+  if (problem === null) return candidate;
+  logger.error(
+    origin === "bootstrap" ? `AvsB ignored the bootstrap datafile passed to new AvsbServer(): ${problem}. Flags return the default you passed, with source "not_ready", until a datafile loads from the CDN. Pass the datafile JSON exactly as the CDN serves it for this SDK key.` : `AvsB ignored the datafile passed to applyDatafileBootstrap(): ${problem}. The SDK keeps serving the datafile it already has, if any. Pass the datafile JSON exactly as the CDN serves it for this SDK key.`
+  );
+  return null;
+}
 function sendHeartbeat(input) {
   const endpoint = resolveHeartbeatEndpoint(input.datafileHeartbeatEndpoint);
   if (!endpoint) return null;
@@ -667,7 +683,8 @@ import {
 } from "@avsbhq/utils/streaming";
 
 // src/version.ts
-var SDK_VERSION = "1.7.1";
+var SDK_VERSION = "1.8.0";
+var SDK_TYPE = "@avsbhq/node";
 
 // src/UserBoundClient.ts
 import { bucketingKey } from "@avsbhq/core";
@@ -777,6 +794,23 @@ function buildServerUtils(server) {
   return createUtils(adapter);
 }
 
+// src/initTimeout.ts
+async function raceInitTimeout(work, timeoutMs) {
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve({ timedOut: true }), timeoutMs);
+    if (typeof timer === "object" && timer !== null && "unref" in timer) timer.unref();
+  });
+  try {
+    return await Promise.race([
+      work.then((value) => ({ timedOut: false, value })),
+      timeout
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // src/AvsbServer.ts
 var DEFAULT_EVENTS = {
   flushInterval: 2e3,
@@ -784,7 +818,6 @@ var DEFAULT_EVENTS = {
   maxQueueSize: 1e4,
   retryAttempts: 3
 };
-var SDK_TYPE = "@avsbhq/node";
 var HEARTBEAT_MIN_INTERVAL_MS = 12e4;
 var AvsbServer = class {
   sdkKey;
@@ -881,8 +914,8 @@ var AvsbServer = class {
     this.eventOptions = { ...DEFAULT_EVENTS, ...options.events };
     this.streamingEnabled = options.streaming !== false;
     this.streamingEndpointOption = options.streamingEndpoint ?? null;
-    this.datafile = options.bootstrap ?? null;
-    this.ready = !!options.bootstrap;
+    this.datafile = options.bootstrap ? acceptDatafile(options.bootstrap, "bootstrap", this.logger) : null;
+    this.ready = this.datafile !== null;
     this.destroyed = false;
     this.tracker = null;
     this.streamingClient = null;
@@ -916,21 +949,13 @@ var AvsbServer = class {
       return { success: true, source: "bootstrap" };
     }
     try {
-      const outcome = await Promise.race([
+      const outcome = await raceInitTimeout(
         // At init there is no stored etag, so 'unchanged' cannot happen here;
         // it is folded in anyway so a future caching layer cannot make init
         // silently report failure.
-        this.loadDatafile().then((result) => ({
-          applied: result !== "failed",
-          timedOut: false
-        })),
-        new Promise(
-          (resolve) => setTimeout(
-            () => resolve({ applied: false, timedOut: true }),
-            this.initTimeout
-          )
-        )
-      ]);
+        this.loadDatafile().then((result) => result !== "failed"),
+        this.initTimeout
+      );
       if (outcome.timedOut) {
         this.startPolling();
         const error2 = new Error(
@@ -939,7 +964,7 @@ var AvsbServer = class {
         this.emit("error", error2);
         return { success: false, source: "timeout", error: error2 };
       }
-      if (outcome.applied) {
+      if (outcome.value) {
         this.onDatafileReadable();
         return { success: true, source: "network" };
       }
@@ -1017,6 +1042,7 @@ var AvsbServer = class {
    */
   applyDatafileBootstrap(datafile) {
     if (this.destroyed) return;
+    if (!acceptDatafile(datafile, "applyDatafileBootstrap", this.logger)) return;
     const changed = this.datafile?.publishedAt !== datafile.publishedAt;
     this.datafile = datafile;
     this.datafileEtag = null;
@@ -1112,6 +1138,9 @@ var AvsbServer = class {
   evaluateAndBuild(flagKey, defaultValue, context, decide, options) {
     const legacyCtx = this.buildLegacyContext(context, decide.suppressExposure);
     const result = this.evaluate(flagKey, legacyCtx, defaultValue);
+    if (result.source === "not_found") {
+      this.warnOnce(`missing:${flagKey}`, flagNotFoundMessage(flagKey));
+    }
     const typeMismatch = this.checkType(flagKey, options?.expectedType, result);
     if (typeMismatch) {
       this.logger.warn(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avsbhq/node",
-  "version": "1.7.2",
+  "version": "1.8.0",
   "description": "Node.js server SDK for A vs B feature flags and experiments: per-request contexts, sticky bucketing, decision logs, and batched event delivery.",
   "keywords": [
     "avsb",
@@ -49,14 +49,15 @@
     "url": "https://github.com/avsbhq/a-vs-b/issues"
   },
   "scripts": {
+    "prebuild": "node ../avsb-core/scripts/writeSdkVersion.mjs",
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "vitest run",
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@avsbhq/core": "^1.4.0",
-    "@avsbhq/utils": "^1.0.2"
+    "@avsbhq/core": "^1.6.0",
+    "@avsbhq/utils": "^1.2.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",