@avsbhq/node 1.7.2 → 1.9.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.
@@ -520,6 +520,17 @@ server.utils.hydrateBootstrap(blob); // blob must carry `datafile`
 
 `hydrateBootstrap` THROWS on a blob that carries only a pre-evaluated snapshot: a snapshot belongs to one context, and a server evaluates a different context per request, so adopting one process-wide would serve one user's values to another. Serialize with `{ includeDatafile: true }`, or pass `bootstrap: blob.datafile`.
 
+### Fresh snapshots
+
+```ts
+const ctx = { kind: 'user', key: 'user-123' };
+
+const snap = server.utils.snapshot(ctx); // values in memory, no network call
+const fresh = await server.utils.snapshotFresh(ctx); // fetches the datafile first
+```
+
+`snapshotFresh` and `refreshAndSnapshot` call `refreshDatafile()` before they read, so the snapshot reflects the flags published right now. A failed fetch keeps the datafile already in memory, logs a warning, and the snapshot shows that datafile. Before 1.9.0 both helpers skipped the fetch and returned the in-memory values.
+
 For Next.js SSR see `@avsbhq/next`.
 
 ---
@@ -587,7 +598,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 +607,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 +641,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 +651,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 +693,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 +727,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,