@avsbhq/node 1.2.0 → 1.6.0

package/README.md

@@ -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

@@ -40,6 +40,58 @@ 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/decisionLog.ts
 function createDecisionLog() {
   const entries = [];
@@ -415,6 +467,23 @@ 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;
+  }
   constructor(options) {
     this.sdkKey = options.sdkKey;
     this.pollingInterval = Math.max(options.pollingInterval ?? 6e4, 5e3);

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { FlagDatafile, StickyBucketService, Logger, EvaluationSource, StickyAssignment, DecideOption, Flag, TrackPayload, DecisionLog, InitResult, EvalContext } from '@avsbhq/core';
-export { DecideOption, DecisionLog, DecisionLogEntry, EvalContext, EvaluationSource, ExposureEvent, Flag, FlagDatafile, FlagEvaluationDetails, InitResult, Logger, MetricEvent, MultiContext, RuleType, SingleContext, StickyAssignment, StickyBucketService, TrackPayload, consoleLogger, consoleTransport, createLogger, noopLogger } from '@avsbhq/core';
+export { DatafileDataset, DatafileDatasetType, DecideOption, DecisionLog, DecisionLogEntry, EvalContext, EvaluationSource, ExposureEvent, Flag, FlagDatafile, FlagEvaluationDetails, InitResult, Logger, MetricEvent, MultiContext, RuleType, SingleContext, StickyAssignment, StickyBucketService, TrackPayload, consoleLogger, consoleTransport, createLogger, noopLogger } from '@avsbhq/core';
 import { AvsbUtils } from '@avsbhq/utils';
 export { AvsbUtils } from '@avsbhq/utils';
 export { StreamingClient, StreamingOptions, createStreamingClient } from '@avsbhq/utils/streaming';
@@ -89,6 +89,41 @@ 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>;
+}
+
 /**
  * A per-request scoped client with a bound EvalContext.
  *
@@ -170,6 +205,14 @@ declare class AvsbServer {
      */
     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.
+     */
+    private _datasets;
+    get datasets(): DatasetsClient;
     constructor(options: AvsbServerOptions);
     onReady(): Promise<InitResult>;
     private initializeAndReady;
@@ -262,4 +305,4 @@ declare function createDecisionLog(): DecisionLog;
 
 declare const SDK_VERSION = "0.3.0";
 
-export { AvsbServer, type AvsbServerOptions, type EventOptions, type GetAllFlagsOptions, type GetFlagOptions, InMemoryStickyBucketService, type MiddlewareConfig, type PurchaseOrder, type RedisLike, type RedisStickyBucketOptions, RedisStickyBucketService, SDK_VERSION, type UserBoundClient, createDecisionLog, expressMiddleware, fastifyPlugin };
+export { AvsbServer, type AvsbServerOptions, type DatasetGetResult, type DatasetsClient, type EventOptions, type GetAllFlagsOptions, type GetFlagOptions, InMemoryStickyBucketService, type MiddlewareConfig, type PurchaseOrder, type RedisLike, type RedisStickyBucketOptions, RedisStickyBucketService, SDK_VERSION, type UserBoundClient, createDecisionLog, expressMiddleware, fastifyPlugin };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { FlagDatafile, StickyBucketService, Logger, EvaluationSource, StickyAssignment, DecideOption, Flag, TrackPayload, DecisionLog, InitResult, EvalContext } from '@avsbhq/core';
-export { DecideOption, DecisionLog, DecisionLogEntry, EvalContext, EvaluationSource, ExposureEvent, Flag, FlagDatafile, FlagEvaluationDetails, InitResult, Logger, MetricEvent, MultiContext, RuleType, SingleContext, StickyAssignment, StickyBucketService, TrackPayload, consoleLogger, consoleTransport, createLogger, noopLogger } from '@avsbhq/core';
+export { DatafileDataset, DatafileDatasetType, DecideOption, DecisionLog, DecisionLogEntry, EvalContext, EvaluationSource, ExposureEvent, Flag, FlagDatafile, FlagEvaluationDetails, InitResult, Logger, MetricEvent, MultiContext, RuleType, SingleContext, StickyAssignment, StickyBucketService, TrackPayload, consoleLogger, consoleTransport, createLogger, noopLogger } from '@avsbhq/core';
 import { AvsbUtils } from '@avsbhq/utils';
 export { AvsbUtils } from '@avsbhq/utils';
 export { StreamingClient, StreamingOptions, createStreamingClient } from '@avsbhq/utils/streaming';
@@ -89,6 +89,41 @@ 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>;
+}
+
 /**
  * A per-request scoped client with a bound EvalContext.
  *
@@ -170,6 +205,14 @@ declare class AvsbServer {
      */
     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.
+     */
+    private _datasets;
+    get datasets(): DatasetsClient;
     constructor(options: AvsbServerOptions);
     onReady(): Promise<InitResult>;
     private initializeAndReady;
@@ -262,4 +305,4 @@ declare function createDecisionLog(): DecisionLog;
 
 declare const SDK_VERSION = "0.3.0";
 
-export { AvsbServer, type AvsbServerOptions, type EventOptions, type GetAllFlagsOptions, type GetFlagOptions, InMemoryStickyBucketService, type MiddlewareConfig, type PurchaseOrder, type RedisLike, type RedisStickyBucketOptions, RedisStickyBucketService, SDK_VERSION, type UserBoundClient, createDecisionLog, expressMiddleware, fastifyPlugin };
+export { AvsbServer, type AvsbServerOptions, type DatasetGetResult, type DatasetsClient, type EventOptions, type GetAllFlagsOptions, type GetFlagOptions, InMemoryStickyBucketService, type MiddlewareConfig, type PurchaseOrder, type RedisLike, type RedisStickyBucketOptions, RedisStickyBucketService, SDK_VERSION, type UserBoundClient, createDecisionLog, expressMiddleware, fastifyPlugin };

package/dist/index.js

@@ -13,6 +13,58 @@ 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/decisionLog.ts
 function createDecisionLog() {
   const entries = [];
@@ -391,6 +443,23 @@ 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;
+  }
   constructor(options) {
     this.sdkKey = options.sdkKey;
     this.pollingInterval = Math.max(options.pollingInterval ?? 6e4, 5e3);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avsbhq/node",
-  "version": "1.2.0",
+  "version": "1.6.0",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -33,7 +33,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@avsbhq/core": "1.1.0",
+    "@avsbhq/core": "1.3.0",
     "@avsbhq/utils": "1.0.1"
   },
   "devDependencies": {