@avsbhq/node 1.0.0 → 1.5.0

package/dist/index.js

@@ -13,12 +13,266 @@ import {
   noopLogger
 } from "@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
+import { randomUUID } from "crypto";
+
 // src/reconnectBackoff.ts
 var BASE_DELAY_MS = 1e3;
 var MAX_DELAY_MS = 6e4;
@@ -47,6 +301,12 @@ function parseRetryAfter(headerValue) {
 }
 
 // src/serverTracker.ts
+function stampExposure(event) {
+  return event.eventId ? event : { ...event, eventId: randomUUID() };
+}
+function stampMetric(event) {
+  return event.eventId ? event : { ...event, eventId: randomUUID() };
+}
 function createServerTracker(options) {
   const {
     sdkKey,
@@ -59,6 +319,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;
@@ -70,7 +331,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);
@@ -84,7 +345,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);
@@ -146,6 +407,47 @@ function createServerTracker(options) {
       }
     }
   }
+  async function trackPurchase(visitorId, order) {
+    if (destroyed) return;
+    const payload = {
+      ...order,
+      eventId: 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) {
@@ -154,186 +456,17 @@ 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 };
-}
+import {
+  createStreamingClient,
+  createBrowserStreamingClient
+} from "@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) {
@@ -509,6 +642,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);
@@ -693,6 +862,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) {

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "@avsbhq/node",
-  "version": "1.0.0",
+  "version": "1.5.0",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
-    ".": { "import": "./dist/index.js", "require": "./dist/index.cjs" }
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "engines": {
     "node": ">=18.0.0"
   },
@@ -28,8 +33,8 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@avsbhq/core": "1.0.0",
-    "@avsbhq/utils": "1.0.0"
+    "@avsbhq/core": "1.3.0",
+    "@avsbhq/utils": "1.0.1"
   },
   "devDependencies": {
     "tsup": "^8.0.0",
@@ -37,4 +42,4 @@
     "vitest": "^3.0.0",
     "@types/node": "^20.0.0"
   }
-}
+}