@avsbhq/node 1.0.0 → 1.5.0

package/dist/index.d.cts

@@ -1,7 +1,8 @@
 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, PurchaseHistoryAttribute, 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';
 
 interface AvsbServerOptions {
     /** SDK key for the flag environment (e.g., "env_abc123") */
@@ -62,6 +63,163 @@ interface MiddlewareConfig {
     attributesFrom?: (req: unknown) => Record<string, unknown>;
 }
 
+/**
+ * Purchase order shape for server-side purchase tracking.
+ * Mirrors the client-side snippet PurchaseOrder interface.
+ * Decimal values are forwarded as-is — no server-side currency conversion.
+ */
+interface PurchaseOrder {
+    /** Required. Unique order/transaction identifier. */
+    orderId: string;
+    /** Required. Order total as a decimal (e.g. 99.95). */
+    total: number;
+    /** ISO 4217 currency code. */
+    currency?: string;
+    subtotal?: number;
+    shipping?: number;
+    tax?: number;
+    discount?: number;
+    coupon?: string;
+    items?: Array<{
+        sku: string;
+        /**
+         * Canonical product-grain key (e-commerce suite overhaul, contract C1).
+         * Pass when known so order items join catalog/recommendation analytics
+         * without alias resolution; the ingestion worker derives it from `sku`
+         * otherwise.
+         */
+        productKey?: string;
+        name?: string;
+        price?: number;
+        quantity?: number;
+        category?: string;
+    }>;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * Server-side recommendations client (e-commerce suite overhaul, contract C3).
+ *
+ * Mirrors ./datasets.ts: resolves a recipe handle against the datafile's
+ * recipe registry (`datafile.recipes`, additive) and POSTs the standard
+ * resolve body to the edge worker:
+ *
+ *   POST {ingestionHost}/v1/recs/resolve
+ *
+ * The ingestion host is derived from the datafile's `collectEndpoint`. The
+ * worker's key cache resolves SDK keys as well as snippet keys, so the body's
+ * key field simply carries the SDK key.
+ *
+ * Attribution is OPT-IN server-side: `get()` fires a `rec:impression` (via
+ * the server tracker) only when the caller passes `attribution` — a server
+ * has no ambient variation context the way a browser harness does.
+ *
+ * Error posture matches datasets/flag evaluation: this client NEVER throws.
+ * Unknown recipe, SDK not ready, HTTP errors, timeouts and network failures
+ * all degrade to `{ items: [], served: false }`.
+ */
+interface RecProduct {
+    id: string;
+    title?: string;
+    image?: string;
+    href?: string;
+    category?: string;
+    /** MINOR units (ISO-4217). */
+    price?: number;
+    /** MINOR units. */
+    compareAtPrice?: number;
+    currency?: string;
+    availability?: 'in_stock' | 'out_of_stock' | 'removed';
+}
+interface RecsAttribution {
+    visitorId: string;
+    experimentId: string;
+    variationId: string;
+}
+interface RecsGetRequest {
+    recipe: string;
+    context?: {
+        /** Single seed product key (product page). */
+        seed?: string;
+        /** Up to 3 seed product keys (cart page). */
+        seeds?: string[];
+    };
+    maxItems?: number;
+    excludeOutOfStock?: boolean;
+    /** When present, a rec:impression is queued with these ids on success. */
+    attribution?: RecsAttribution;
+}
+interface RecsResult {
+    items: RecProduct[];
+    served: boolean;
+    recipe: string;
+    /** Slug of the chain step that served, null on a miss. */
+    source: string | null;
+    fallbackStep: number | null;
+    /** True when the resolve failed (timeout / network / HTTP / parse). */
+    degraded: boolean;
+}
+interface RecsClient {
+    /** Resolve items for a recipe. Never throws. */
+    get(req: RecsGetRequest): Promise<RecsResult>;
+    /**
+     * Queue a rec:click for a product the shopper clicked. Pass `recipe` when
+     * known — results group click-through by (variation, recipe).
+     */
+    trackClick(productId: string, opts: RecsAttribution & {
+        position?: number;
+        recipe?: string;
+    }): void;
+}
+/**
+ * One entry of the datafile recipe registry (contract C3). Additive on
+ * FlagDatafile — SDKs on older datafiles see it absent.
+ */
+interface DatafileRecipe {
+    recipe: string;
+    chain: Array<{
+        slug: string;
+        version: number;
+    }>;
+    excludeOutOfStock: boolean;
+    sessionAffinity: boolean;
+    merch?: unknown[];
+}
+
 /**
  * A per-request scoped client with a bound EvalContext.
  *
@@ -143,6 +301,23 @@ 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;
+    /**
+     * 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`.
+     */
+    private _recs;
+    get recs(): RecsClient;
     constructor(options: AvsbServerOptions);
     onReady(): Promise<InitResult>;
     private initializeAndReady;
@@ -155,6 +330,7 @@ declare class AvsbServer {
     getNumberFlag(flagKey: string, defaultValue: NoInfer<number> | number, options?: GetFlagOptions): Flag<number>;
     getJsonFlag<T>(flagKey: string, defaultValue: NoInfer<T> | T, options?: GetFlagOptions): Flag<T>;
     getAllFlags(context: EvalContext, options?: GetAllFlagsOptions): Record<string, Flag>;
+    trackPurchase(visitorId: string, order: PurchaseOrder): Promise<void>;
     track(eventKey: string, payload: TrackPayload & {
         context: EvalContext;
     }): void;
@@ -230,22 +406,8 @@ declare class RedisStickyBucketService implements StickyBucketService {
     private evictIfNeeded;
 }
 
-interface StreamingClient {
-    connect(): void;
-    disconnect(): void;
-    isConnected(): boolean;
-}
-interface StreamingOptions {
-    endpoint: string;
-    sdkKey: string;
-    onDatafileUpdated: () => void;
-    logger: Logger;
-    reconnectDelay?: number;
-}
-declare function createStreamingClient(options: StreamingOptions): StreamingClient;
-
 declare function createDecisionLog(): DecisionLog;
 
-declare const SDK_VERSION = "0.3.0";
+declare const SDK_VERSION = "0.4.0";
 
-export { AvsbServer, type AvsbServerOptions, type EventOptions, type GetAllFlagsOptions, type GetFlagOptions, InMemoryStickyBucketService, type MiddlewareConfig, type RedisLike, type RedisStickyBucketOptions, RedisStickyBucketService, SDK_VERSION, type StreamingClient, type StreamingOptions, type UserBoundClient, createDecisionLog, createStreamingClient, expressMiddleware, fastifyPlugin };
+export { AvsbServer, type AvsbServerOptions, type DatafileRecipe, type DatasetGetResult, type DatasetsClient, type EventOptions, type GetAllFlagsOptions, type GetFlagOptions, InMemoryStickyBucketService, type MiddlewareConfig, type PurchaseOrder, type RecProduct, type RecsAttribution, type RecsClient, type RecsGetRequest, type RecsResult, type RedisLike, type RedisStickyBucketOptions, RedisStickyBucketService, SDK_VERSION, type UserBoundClient, createDecisionLog, expressMiddleware, fastifyPlugin };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 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, PurchaseHistoryAttribute, 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';
 
 interface AvsbServerOptions {
     /** SDK key for the flag environment (e.g., "env_abc123") */
@@ -62,6 +63,163 @@ interface MiddlewareConfig {
     attributesFrom?: (req: unknown) => Record<string, unknown>;
 }
 
+/**
+ * Purchase order shape for server-side purchase tracking.
+ * Mirrors the client-side snippet PurchaseOrder interface.
+ * Decimal values are forwarded as-is — no server-side currency conversion.
+ */
+interface PurchaseOrder {
+    /** Required. Unique order/transaction identifier. */
+    orderId: string;
+    /** Required. Order total as a decimal (e.g. 99.95). */
+    total: number;
+    /** ISO 4217 currency code. */
+    currency?: string;
+    subtotal?: number;
+    shipping?: number;
+    tax?: number;
+    discount?: number;
+    coupon?: string;
+    items?: Array<{
+        sku: string;
+        /**
+         * Canonical product-grain key (e-commerce suite overhaul, contract C1).
+         * Pass when known so order items join catalog/recommendation analytics
+         * without alias resolution; the ingestion worker derives it from `sku`
+         * otherwise.
+         */
+        productKey?: string;
+        name?: string;
+        price?: number;
+        quantity?: number;
+        category?: string;
+    }>;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * Server-side recommendations client (e-commerce suite overhaul, contract C3).
+ *
+ * Mirrors ./datasets.ts: resolves a recipe handle against the datafile's
+ * recipe registry (`datafile.recipes`, additive) and POSTs the standard
+ * resolve body to the edge worker:
+ *
+ *   POST {ingestionHost}/v1/recs/resolve
+ *
+ * The ingestion host is derived from the datafile's `collectEndpoint`. The
+ * worker's key cache resolves SDK keys as well as snippet keys, so the body's
+ * key field simply carries the SDK key.
+ *
+ * Attribution is OPT-IN server-side: `get()` fires a `rec:impression` (via
+ * the server tracker) only when the caller passes `attribution` — a server
+ * has no ambient variation context the way a browser harness does.
+ *
+ * Error posture matches datasets/flag evaluation: this client NEVER throws.
+ * Unknown recipe, SDK not ready, HTTP errors, timeouts and network failures
+ * all degrade to `{ items: [], served: false }`.
+ */
+interface RecProduct {
+    id: string;
+    title?: string;
+    image?: string;
+    href?: string;
+    category?: string;
+    /** MINOR units (ISO-4217). */
+    price?: number;
+    /** MINOR units. */
+    compareAtPrice?: number;
+    currency?: string;
+    availability?: 'in_stock' | 'out_of_stock' | 'removed';
+}
+interface RecsAttribution {
+    visitorId: string;
+    experimentId: string;
+    variationId: string;
+}
+interface RecsGetRequest {
+    recipe: string;
+    context?: {
+        /** Single seed product key (product page). */
+        seed?: string;
+        /** Up to 3 seed product keys (cart page). */
+        seeds?: string[];
+    };
+    maxItems?: number;
+    excludeOutOfStock?: boolean;
+    /** When present, a rec:impression is queued with these ids on success. */
+    attribution?: RecsAttribution;
+}
+interface RecsResult {
+    items: RecProduct[];
+    served: boolean;
+    recipe: string;
+    /** Slug of the chain step that served, null on a miss. */
+    source: string | null;
+    fallbackStep: number | null;
+    /** True when the resolve failed (timeout / network / HTTP / parse). */
+    degraded: boolean;
+}
+interface RecsClient {
+    /** Resolve items for a recipe. Never throws. */
+    get(req: RecsGetRequest): Promise<RecsResult>;
+    /**
+     * Queue a rec:click for a product the shopper clicked. Pass `recipe` when
+     * known — results group click-through by (variation, recipe).
+     */
+    trackClick(productId: string, opts: RecsAttribution & {
+        position?: number;
+        recipe?: string;
+    }): void;
+}
+/**
+ * One entry of the datafile recipe registry (contract C3). Additive on
+ * FlagDatafile — SDKs on older datafiles see it absent.
+ */
+interface DatafileRecipe {
+    recipe: string;
+    chain: Array<{
+        slug: string;
+        version: number;
+    }>;
+    excludeOutOfStock: boolean;
+    sessionAffinity: boolean;
+    merch?: unknown[];
+}
+
 /**
  * A per-request scoped client with a bound EvalContext.
  *
@@ -143,6 +301,23 @@ 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;
+    /**
+     * 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`.
+     */
+    private _recs;
+    get recs(): RecsClient;
     constructor(options: AvsbServerOptions);
     onReady(): Promise<InitResult>;
     private initializeAndReady;
@@ -155,6 +330,7 @@ declare class AvsbServer {
     getNumberFlag(flagKey: string, defaultValue: NoInfer<number> | number, options?: GetFlagOptions): Flag<number>;
     getJsonFlag<T>(flagKey: string, defaultValue: NoInfer<T> | T, options?: GetFlagOptions): Flag<T>;
     getAllFlags(context: EvalContext, options?: GetAllFlagsOptions): Record<string, Flag>;
+    trackPurchase(visitorId: string, order: PurchaseOrder): Promise<void>;
     track(eventKey: string, payload: TrackPayload & {
         context: EvalContext;
     }): void;
@@ -230,22 +406,8 @@ declare class RedisStickyBucketService implements StickyBucketService {
     private evictIfNeeded;
 }
 
-interface StreamingClient {
-    connect(): void;
-    disconnect(): void;
-    isConnected(): boolean;
-}
-interface StreamingOptions {
-    endpoint: string;
-    sdkKey: string;
-    onDatafileUpdated: () => void;
-    logger: Logger;
-    reconnectDelay?: number;
-}
-declare function createStreamingClient(options: StreamingOptions): StreamingClient;
-
 declare function createDecisionLog(): DecisionLog;
 
-declare const SDK_VERSION = "0.3.0";
+declare const SDK_VERSION = "0.4.0";
 
-export { AvsbServer, type AvsbServerOptions, type EventOptions, type GetAllFlagsOptions, type GetFlagOptions, InMemoryStickyBucketService, type MiddlewareConfig, type RedisLike, type RedisStickyBucketOptions, RedisStickyBucketService, SDK_VERSION, type StreamingClient, type StreamingOptions, type UserBoundClient, createDecisionLog, createStreamingClient, expressMiddleware, fastifyPlugin };
+export { AvsbServer, type AvsbServerOptions, type DatafileRecipe, type DatasetGetResult, type DatasetsClient, type EventOptions, type GetAllFlagsOptions, type GetFlagOptions, InMemoryStickyBucketService, type MiddlewareConfig, type PurchaseOrder, type RecProduct, type RecsAttribution, type RecsClient, type RecsGetRequest, type RecsResult, type RedisLike, type RedisStickyBucketOptions, RedisStickyBucketService, SDK_VERSION, type UserBoundClient, createDecisionLog, expressMiddleware, fastifyPlugin };