@avsbhq/node 1.0.0 → 1.5.0

package/README.md

@@ -49,13 +49,13 @@ Instantiate `AvsbServer` once at app boot. The server holds the datafile in memo
 
 ## 3. SDK keys
 
-Use a **server** SDK key (prefix `sdk-server-`). Get it from your A vs B project's Environments page.
+Get the SDK key for the environment you want to target from your A vs B project's Environments page. The key format is `sdk_<environment>_<id>` (e.g. `sdk_production_clp1a2b3c4d5e6`).
 
 ```bash
-AVSB_SDK_KEY=sdk-server-...
+AVSB_SDK_KEY=sdk_production_...
 ```
 
-Server SDK keys grant full flag-read access. Store them in environment variables only — never in source code, client bundles, or browser-accessible config.
+When used server-side, the SDK key only ever needs to leave the server to hit the datafile CDN — it should never end up in client-rendered HTML, browser bundles, or browser-accessible config. Store it in environment variables only.
 
 Server SDK keys cannot be rotated without a process restart; the new key must be set in the environment before the server boots (or trigger a rolling restart in your orchestrator).
 
@@ -93,6 +93,35 @@ const flag = server.getBoolFlag('checkout-v2', false, {
 })
 ```
 
+### Commerce targeting attributes
+
+Audiences built with the commerce condition types (cart value, products viewed, purchase history) evaluate from attributes you supply on the context. The attribute names are fixed:
+
+```ts
+const flag = server.getBoolFlag('big-cart-banner', false, {
+  context: {
+    kind: 'user',
+    key: 'u_123',
+    cartValue: 120.5, // decimal MAJOR units of the project currency
+    viewedSkus: ['SKU-1', 'SKU-2'], // for "products viewed" matching on SKU
+    viewedCategories: ['trainers'], // for "products viewed" matching on category
+    purchaseHistory: {
+      // PurchaseHistoryAttribute — exported for your own declarations
+      hasPurchased: true,
+      lastPurchaseAt: 1765500000000, // epoch milliseconds (optional)
+      lifetimeSpend: 540.0, // decimal MAJOR units (optional)
+      orderCount: 7, // optional
+    },
+  },
+})
+```
+
+Server-side semantics to be aware of:
+
+- **All money is decimal major units.** Condition values are stored in minor units and converted using the project currency exponent from the datafile (default 2) — you never pass minor units.
+- **Missing or mistyped attributes evaluate the condition to `false`.** A completely absent `purchaseHistory` makes ALL purchase-history operators false — including `has_not_purchased`. On the server, absence means "not provided", not "never purchased" (this deliberately diverges from the browser snippet, where a profile miss is authoritative).
+- **Dataset-backed "products viewed" conditions evaluate `false` on the server.** Dataset view windows live in the browser; server callers use literal SKU/category lists. The session/30-day window distinction is also browser-only — supply whatever view list you consider current.
+
 ### `alias(previousContext, newContext)`
 
 Send an alias event linking two identities in the analytics pipeline. Typically called server-side when a user signs up or links an anonymous session to an account:
@@ -104,6 +133,10 @@ await server.alias(
 )
 ```
 
+### Sharing identity with the web snippet
+
+To measure one metric across both the A vs B web snippet and this SDK (the setup behind cross-project metrics), the context `key` must equal the browser snippet's visitor id — the `_avsb_visitor` cookie UUID returned by `avsb.getVisitorId()`. Results join on raw id equality, so a different key means the two surfaces never line up. Forward the snippet id from the browser and use it as the key here, or link an internal account id to it with `alias()`. Full guide: [Shared Visitor Identity](https://avsb.cloud/docs/developer-reference/shared-visitor-identity).
+
 ---
 
 ## 5. Multi-context

package/dist/index.cjs

@@ -29,7 +29,7 @@ __export(index_exports, {
   consoleTransport: () => import_core3.consoleTransport,
   createDecisionLog: () => createDecisionLog,
   createLogger: () => import_core3.createLogger,
-  createStreamingClient: () => createStreamingClient,
+  createStreamingClient: () => import_streaming.createStreamingClient,
   expressMiddleware: () => expressMiddleware,
   fastifyPlugin: () => fastifyPlugin,
   noopLogger: () => import_core3.noopLogger
@@ -40,12 +40,266 @@ module.exports = __toCommonJS(index_exports);
 var import_engine = require("@avsbhq/core/engine");
 var import_core2 = require("@avsbhq/core");
 
+// src/datasets.ts
+var DEFAULT_REQUEST_TIMEOUT = 1e4;
+function miss(slug, version) {
+  return { found: false, meta: { slug, version } };
+}
+function createDatasetsClient(options) {
+  const { sdkKey, getDatafile, logger } = options;
+  const requestTimeout = options.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT;
+  async function get(slug, key) {
+    if (!slug || !key) {
+      logger.warn("datasets.get called with an empty slug or key \u2014 returning not found");
+      return miss(slug, null);
+    }
+    const datafile = getDatafile();
+    if (!datafile) {
+      logger.debug(`SDK not ready, returning not found for dataset "${slug}"`);
+      return miss(slug, null);
+    }
+    const dataset = datafile.datasets?.find((d) => d.slug === slug);
+    if (!dataset) {
+      logger.debug(`Dataset "${slug}" not present in datafile \u2014 returning not found`);
+      return miss(slug, null);
+    }
+    if (!dataset.liveVersion) {
+      logger.debug(`Dataset "${slug}" has no live version \u2014 returning not found`);
+      return miss(slug, null);
+    }
+    const base = datafile.collectEndpoint.replace(/\/+$/, "");
+    const url = `${base}/v1/ds/${encodeURIComponent(sdkKey)}/${encodeURIComponent(slug)}/${dataset.liveVersion}/${encodeURIComponent(key)}`;
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(requestTimeout) });
+      if (!res.ok) {
+        logger.warn("Dataset lookup failed", { slug, key, status: res.status });
+        return miss(slug, dataset.liveVersion);
+      }
+      const body = await res.json();
+      if (!body || body.found !== true) {
+        return miss(slug, dataset.liveVersion);
+      }
+      return {
+        found: true,
+        value: body.value,
+        meta: { slug, version: dataset.liveVersion }
+      };
+    } catch (e) {
+      logger.warn("Dataset lookup error", { slug, key, error: String(e) });
+      return miss(slug, dataset.liveVersion);
+    }
+  }
+  return { get };
+}
+
+// src/recs.ts
+var DEFAULT_REQUEST_TIMEOUT2 = 1e4;
+var MAX_SEED_CHARS = 256;
+var MAX_SEEDS = 3;
+var MAX_ITEMS_CAP = 24;
+var DEFAULT_MAX_ITEMS = 8;
+var MAX_ID_CHARS = 64;
+var MAX_ATTR_VALUE_CHARS = 512;
+var GLOBAL_SEED = "_global";
+function clampMaxItems(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) return DEFAULT_MAX_ITEMS;
+  return Math.min(Math.floor(value), MAX_ITEMS_CAP);
+}
+function asText(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return "";
+}
+function joinIds(ids) {
+  let out = "";
+  for (const id of ids) {
+    const next = out === "" ? id : `${out},${id}`;
+    if (next.length > MAX_ATTR_VALUE_CHARS) break;
+    out = next;
+  }
+  return out;
+}
+function toRecProducts(items, cap) {
+  const out = [];
+  for (const item of items) {
+    if (out.length >= cap) break;
+    if (item === null || typeof item !== "object") continue;
+    const fields = item;
+    const id = (asText(fields.id) || asText(fields.sku)).slice(0, MAX_ID_CHARS);
+    if (id === "") continue;
+    const product = { id };
+    const title = asText(fields.title);
+    if (title) product.title = title;
+    const image = asText(fields.image);
+    if (image) product.image = image;
+    const href = asText(fields.href) || asText(fields.url);
+    if (href && !/^\s*javascript:/i.test(href)) product.href = href;
+    const category = asText(fields.category);
+    if (category) product.category = category;
+    if (typeof fields.price === "number" && Number.isFinite(fields.price)) {
+      product.price = Math.round(fields.price);
+    }
+    if (typeof fields.compareAtPrice === "number" && Number.isFinite(fields.compareAtPrice)) {
+      product.compareAtPrice = Math.round(fields.compareAtPrice);
+    }
+    if (typeof fields.currency === "string" && fields.currency !== "") {
+      product.currency = fields.currency;
+    }
+    const availability = fields.availability;
+    if (availability === "in_stock" || availability === "out_of_stock" || availability === "removed") {
+      product.availability = availability;
+    }
+    out.push(product);
+  }
+  return out;
+}
+function miss2(recipe, degraded) {
+  return { items: [], served: false, recipe, source: null, fallbackStep: null, degraded };
+}
+function createRecsClient(options) {
+  const { sdkKey, getDatafile, getTracker, logger } = options;
+  const requestTimeout = options.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT2;
+  function resolveSeeds(context) {
+    const clip = (s) => s.slice(0, MAX_SEED_CHARS);
+    if (Array.isArray(context?.seeds)) {
+      const seeds = context.seeds.filter((s) => typeof s === "string" && s !== "").slice(0, MAX_SEEDS).map(clip);
+      if (seeds.length > 0) return seeds;
+    }
+    if (typeof context?.seed === "string" && context.seed !== "") return [clip(context.seed)];
+    return [GLOBAL_SEED];
+  }
+  async function get(req) {
+    try {
+      const recipeHandle = typeof req?.recipe === "string" ? req.recipe : "";
+      if (recipeHandle === "") {
+        logger.warn("recs.get called with an empty recipe \u2014 returning served:false");
+        return miss2("", false);
+      }
+      const datafile = getDatafile();
+      if (!datafile) {
+        logger.debug(`SDK not ready, returning served:false for recipe "${recipeHandle}"`);
+        return miss2(recipeHandle, false);
+      }
+      const recipes = datafile.recipes;
+      const entry = recipes?.find((r) => r.recipe === recipeHandle) ?? null;
+      if (!entry) {
+        logger.debug(`Recipe "${recipeHandle}" not present in datafile \u2014 returning served:false`);
+        return miss2(recipeHandle, false);
+      }
+      const seeds = resolveSeeds(req.context);
+      const maxItems = clampMaxItems(req.maxItems);
+      const excludeOutOfStock = typeof req.excludeOutOfStock === "boolean" ? req.excludeOutOfStock : entry.excludeOutOfStock;
+      const body = {
+        snippetKey: sdkKey,
+        assigned: 0,
+        sources: [{ chain: entry.chain }],
+        maxItems,
+        excludeOutOfStock,
+        merch: entry.merch ?? [],
+        sessionAffinity: entry.sessionAffinity
+      };
+      if (seeds.length === 1) body.seedKey = seeds[0];
+      else body.seedKeys = seeds;
+      const base = datafile.collectEndpoint.replace(/\/+$/, "").replace("/v1/collect/batch", "");
+      const res = await fetch(`${base}/v1/recs/resolve`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(requestTimeout)
+      });
+      if (!res.ok) {
+        logger.warn("Recs resolve failed", { recipe: recipeHandle, status: res.status });
+        return miss2(recipeHandle, true);
+      }
+      const parsed = await res.json();
+      const data = parsed?.data;
+      if (!data || typeof data !== "object") return miss2(recipeHandle, true);
+      const items = toRecProducts(Array.isArray(data.items) ? data.items : [], maxItems);
+      const servedStep = data.served ?? null;
+      const served = servedStep !== null && items.length > 0;
+      if (req.attribution) {
+        const tracker = getTracker();
+        if (tracker) {
+          tracker.queue({
+            visitorId: req.attribution.visitorId,
+            experimentId: req.attribution.experimentId,
+            variationId: req.attribution.variationId,
+            eventName: "rec:impression",
+            revenue: null,
+            timestamp: Date.now(),
+            pageUrl: "",
+            attributes: {
+              recipe: entry.recipe,
+              seed: joinIds(seeds),
+              slug: servedStep?.slug ?? "",
+              version: servedStep ? String(servedStep.version) : "",
+              step: servedStep ? String(servedStep.step) : "",
+              served: served ? "true" : "false",
+              items: joinIds(items.map((i) => i.id))
+            }
+          });
+        } else {
+          logger.warn("recs.get attribution supplied before tracker is ready; impression dropped");
+        }
+      }
+      return {
+        items,
+        served,
+        recipe: entry.recipe,
+        source: servedStep?.slug ?? null,
+        fallbackStep: servedStep?.step ?? null,
+        degraded: false
+      };
+    } catch (e) {
+      logger.warn("Recs resolve error", {
+        recipe: typeof req?.recipe === "string" ? req.recipe : "",
+        error: String(e)
+      });
+      return miss2(typeof req?.recipe === "string" ? req.recipe : "", true);
+    }
+  }
+  function trackClick(productId, opts) {
+    if (typeof productId !== "string" || productId === "") {
+      logger.warn("recs.trackClick called with an empty productId \u2014 dropped");
+      return;
+    }
+    if (!opts || !opts.visitorId || !opts.experimentId || !opts.variationId) {
+      logger.warn("recs.trackClick requires visitorId/experimentId/variationId \u2014 dropped");
+      return;
+    }
+    const tracker = getTracker();
+    if (!tracker) {
+      logger.warn("recs.trackClick called before tracker is ready; click dropped");
+      return;
+    }
+    const position = typeof opts.position === "number" && Number.isInteger(opts.position) && opts.position >= 1 ? String(opts.position) : "";
+    tracker.queue({
+      visitorId: opts.visitorId,
+      experimentId: opts.experimentId,
+      variationId: opts.variationId,
+      eventName: "rec:click",
+      revenue: null,
+      timestamp: Date.now(),
+      pageUrl: "",
+      attributes: {
+        recipe: typeof opts.recipe === "string" ? opts.recipe : "",
+        item: productId.slice(0, MAX_ID_CHARS),
+        position
+      }
+    });
+  }
+  return { get, trackClick };
+}
+
 // src/decisionLog.ts
 function createDecisionLog() {
   const entries = [];
   return { entries };
 }
 
+// src/serverTracker.ts
+var import_node_crypto = require("crypto");
+
 // src/reconnectBackoff.ts
 var BASE_DELAY_MS = 1e3;
 var MAX_DELAY_MS = 6e4;
@@ -74,6 +328,12 @@ function parseRetryAfter(headerValue) {
 }
 
 // src/serverTracker.ts
+function stampExposure(event) {
+  return event.eventId ? event : { ...event, eventId: (0, import_node_crypto.randomUUID)() };
+}
+function stampMetric(event) {
+  return event.eventId ? event : { ...event, eventId: (0, import_node_crypto.randomUUID)() };
+}
 function createServerTracker(options) {
   const {
     sdkKey,
@@ -86,6 +346,7 @@ function createServerTracker(options) {
   } = options;
   const batchEndpoint = collectEndpoint.replace(/\/?$/, "/v1/collect/batch");
   const metricEndpoint = collectEndpoint.replace(/\/?$/, "/v1/collect/metric-batch");
+  const ordersEndpoint = collectEndpoint.replace(/\/?$/, "/v1/collect/orders");
   let exposureQueue = [];
   let metricQueue = [];
   let flushTimer = null;
@@ -97,7 +358,7 @@ function createServerTracker(options) {
   }, flushInterval);
   function queue(event) {
     if (destroyed) return;
-    exposureQueue.push(event);
+    exposureQueue.push(stampExposure(event));
     if (exposureQueue.length > maxQueueSize) {
       const dropped = exposureQueue.length - maxQueueSize;
       exposureQueue = exposureQueue.slice(-maxQueueSize);
@@ -111,7 +372,7 @@ function createServerTracker(options) {
   }
   function queueMetric(event) {
     if (destroyed) return;
-    metricQueue.push(event);
+    metricQueue.push(stampMetric(event));
     if (metricQueue.length > maxQueueSize) {
       const dropped = metricQueue.length - maxQueueSize;
       metricQueue = metricQueue.slice(-maxQueueSize);
@@ -173,6 +434,47 @@ function createServerTracker(options) {
       }
     }
   }
+  async function trackPurchase(visitorId, order) {
+    if (destroyed) return;
+    const payload = {
+      ...order,
+      eventId: (0, import_node_crypto.randomUUID)(),
+      visitorId,
+      timestamp: Date.now(),
+      pageUrl: ""
+    };
+    const body = JSON.stringify({ sdkKey, orders: [payload] });
+    let backoff = resetBackoff();
+    let pendingRetryAfterMs = void 0;
+    for (let attempt = 0; attempt <= retryAttempts; attempt++) {
+      try {
+        const response = await fetch(ordersEndpoint, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body,
+          signal: AbortSignal.timeout(1e4)
+        });
+        if (!response.ok) {
+          const parsed = parseRetryAfter(response.headers.get("retry-after"));
+          if (parsed !== null) pendingRetryAfterMs = parsed;
+          throw new Error(`HTTP ${response.status}`);
+        }
+        logger.debug(`Purchase order ${order.orderId} sent for visitor ${visitorId}`);
+        return;
+      } catch (e) {
+        if (attempt < retryAttempts) {
+          backoff = nextBackoff(backoff, pendingRetryAfterMs);
+          pendingRetryAfterMs = void 0;
+          await new Promise((r) => setTimeout(r, backoff.delayMs));
+        } else {
+          logger.error(
+            `Failed to send purchase order ${order.orderId} after ${retryAttempts} retries`,
+            { endpoint: ordersEndpoint, error: String(e) }
+          );
+        }
+      }
+    }
+  }
   async function destroy() {
     destroyed = true;
     if (flushTimer) {
@@ -181,186 +483,14 @@ function createServerTracker(options) {
     }
     await flush();
   }
-  return { queue, queueMetric, flush, destroy };
+  return { queue, queueMetric, trackPurchase, flush, destroy };
 }
 
 // src/streaming.ts
-function createStreamingClient(options) {
-  const {
-    endpoint,
-    sdkKey,
-    onDatafileUpdated,
-    logger,
-    reconnectDelay
-  } = options;
-  let connected = false;
-  let abortController = null;
-  let reconnectTimer = null;
-  let backoff = resetBackoff();
-  let pendingRetryAfterMs = void 0;
-  function connect() {
-    if (connected) return;
-    void startConnection();
-  }
-  function disconnect() {
-    connected = false;
-    if (abortController) {
-      abortController.abort();
-      abortController = null;
-    }
-    if (reconnectTimer) {
-      clearTimeout(reconnectTimer);
-      reconnectTimer = null;
-    }
-  }
-  function isConnected() {
-    return connected;
-  }
-  async function fetchTicket(signal) {
-    const ticketUrl = `${endpoint}?sdkKey=${encodeURIComponent(sdkKey)}`;
-    try {
-      const res = await fetch(ticketUrl, { signal });
-      if (!res.ok) {
-        logger.warn("SSE ticket fetch failed", { status: res.status, url: ticketUrl });
-        return null;
-      }
-      const body = await res.json();
-      if (!body?.url || !body?.token) {
-        logger.warn("SSE ticket response missing fields");
-        return null;
-      }
-      return body;
-    } catch (e) {
-      if (signal.aborted) return null;
-      logger.warn("SSE ticket fetch error", { error: String(e) });
-      return null;
-    }
-  }
-  async function startConnection() {
-    abortController = new AbortController();
-    const signal = abortController.signal;
-    const ticket = await fetchTicket(signal);
-    if (!ticket || signal.aborted) {
-      if (!signal.aborted) scheduleReconnect();
-      return;
-    }
-    const streamUrl = `${ticket.url}?sdkKey=${encodeURIComponent(sdkKey)}&token=${encodeURIComponent(ticket.token)}`;
-    try {
-      const response = await fetch(streamUrl, {
-        headers: { Accept: "text/event-stream" },
-        signal
-      });
-      if (response.status === 401) {
-        logger.warn("SSE stream rejected token; refetching ticket");
-        const next = await fetchTicket(signal);
-        if (!next || signal.aborted) {
-          if (!signal.aborted) scheduleReconnect();
-          return;
-        }
-        const retryUrl = `${next.url}?sdkKey=${encodeURIComponent(sdkKey)}&token=${encodeURIComponent(next.token)}`;
-        const retry = await fetch(retryUrl, {
-          headers: { Accept: "text/event-stream" },
-          signal
-        });
-        if (!retry.ok || !retry.body) {
-          logger.warn("SSE retry failed", { status: retry.status });
-          recordRetryAfter(retry.headers.get("retry-after"));
-          scheduleReconnect();
-          return;
-        }
-        await pumpFrames(retry, signal);
-        return;
-      }
-      if (response.status === 429) {
-        recordRetryAfter(response.headers.get("retry-after"));
-        logger.warn("SSE rate-limited", { status: 429 });
-        scheduleReconnect();
-        return;
-      }
-      if (!response.ok) {
-        logger.warn("SSE connection failed", { status: response.status, url: streamUrl });
-        recordRetryAfter(response.headers.get("retry-after"));
-        scheduleReconnect();
-        return;
-      }
-      if (!response.body) {
-        logger.warn("SSE response has no body");
-        scheduleReconnect();
-        return;
-      }
-      await pumpFrames(response, signal);
-    } catch (e) {
-      if (signal.aborted) return;
-      logger.warn("SSE connection error", { error: String(e) });
-      connected = false;
-      scheduleReconnect();
-    }
-  }
-  function recordRetryAfter(headerValue) {
-    const parsed = parseRetryAfter(headerValue);
-    if (parsed !== null) pendingRetryAfterMs = parsed;
-  }
-  async function pumpFrames(response, signal) {
-    connected = true;
-    backoff = resetBackoff();
-    pendingRetryAfterMs = void 0;
-    logger.info(`SSE connected to ${endpoint}`);
-    const reader = response.body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buffer += decoder.decode(value, { stream: true });
-        const lines = buffer.split("\n");
-        buffer = lines.pop() ?? "";
-        for (const line of lines) {
-          if (line.startsWith("data: ")) {
-            const data = line.slice(6).trim();
-            if (!data) continue;
-            try {
-              const parsed = JSON.parse(data);
-              if (parsed.type === "datafile_updated") {
-                onDatafileUpdated();
-              }
-            } catch {
-              logger.warn("Failed to parse SSE data", { data });
-            }
-          }
-        }
-      }
-    } catch (e) {
-      if (signal.aborted) return;
-      logger.warn("SSE stream read error", { error: String(e) });
-    }
-    connected = false;
-    scheduleReconnect();
-  }
-  function scheduleReconnect() {
-    if (reconnectTimer) return;
-    if (typeof reconnectDelay === "number") {
-      reconnectTimer = setTimeout(() => {
-        reconnectTimer = null;
-        void startConnection();
-      }, reconnectDelay);
-      return;
-    }
-    backoff = nextBackoff(backoff, pendingRetryAfterMs);
-    pendingRetryAfterMs = void 0;
-    logger.warn(
-      `SSE reconnect attempt ${backoff.attempt} in ${backoff.delayMs}ms`
-    );
-    reconnectTimer = setTimeout(() => {
-      reconnectTimer = null;
-      void startConnection();
-    }, backoff.delayMs);
-  }
-  return { connect, disconnect, isConnected };
-}
+var import_streaming = require("@avsbhq/utils/streaming");
 
 // src/version.ts
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.4.0";
 
 // src/UserBoundClient.ts
 function createUserBoundClient(server, context) {
@@ -536,6 +666,42 @@ var AvsbServer = class {
     }
     return this._utils;
   }
+  /**
+   * 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.
+   */
+  _datasets = null;
+  get datasets() {
+    if (!this._datasets) {
+      this._datasets = createDatasetsClient({
+        sdkKey: this.sdkKey,
+        getDatafile: () => this.datafile,
+        logger: this.logger
+      });
+    }
+    return this._datasets;
+  }
+  /**
+   * 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`.
+   */
+  _recs = null;
+  get recs() {
+    if (!this._recs) {
+      this._recs = createRecsClient({
+        sdkKey: this.sdkKey,
+        getDatafile: () => this.datafile,
+        getTracker: () => this.tracker,
+        logger: this.logger
+      });
+    }
+    return this._recs;
+  }
   constructor(options) {
     this.sdkKey = options.sdkKey;
     this.pollingInterval = Math.max(options.pollingInterval ?? 6e4, 5e3);
@@ -720,6 +886,16 @@ var AvsbServer = class {
     return out;
   }
   // ---------------------------------------------------------------------------
+  // Purchase tracking — fires immediately to /v1/collect/orders
+  // ---------------------------------------------------------------------------
+  async trackPurchase(visitorId, order) {
+    if (!this.tracker) {
+      this.logger.warn("trackPurchase called before tracker is ready; order dropped");
+      return;
+    }
+    return this.tracker.trackPurchase(visitorId, order);
+  }
+  // ---------------------------------------------------------------------------
   // §5.6 Unified track — context required
   // ---------------------------------------------------------------------------
   track(eventKey, payload) {
@@ -1101,7 +1277,7 @@ var AvsbServer = class {
   }
   startStreamingIfEnabled() {
     if (!this.streamingEnabled || this.streamingClient || this.destroyed) return;
-    this.streamingClient = createStreamingClient({
+    this.streamingClient = (0, import_streaming.createStreamingClient)({
       endpoint: this.streamingEndpoint,
       sdkKey: this.sdkKey,
       onDatafileUpdated: () => {