@avsbhq/node 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,246 @@
+import { FlagDatafile } from '@avsbhq/js';
+export { ExposureEvent, FlagDatafile, FlagEvaluationDetails, MetricEvent } from '@avsbhq/js';
+
+interface AvsBServerOptions {
+    /** SDK key for the flag environment (e.g., "env_abc123") */
+    sdkKey: string;
+    /** Datafile polling interval in ms. Default: 60_000 (60s). Min: 5_000. */
+    pollingInterval?: number;
+    /** CDN host for datafile fetches. Default: "https://cdn.avsb.app" */
+    cdnHost?: string;
+    /** Max ms to wait for initial datafile fetch in onReady(). Default: 10_000. */
+    initTimeout?: number;
+    /** Pre-fetched datafile to skip initial network request. */
+    bootstrap?: FlagDatafile;
+    /** Enable SSE streaming for real-time datafile updates. Default: false. */
+    streaming?: boolean;
+    /** Custom SSE endpoint URL. Default: derived from app URL. */
+    streamingEndpoint?: string;
+    /** Event tracking configuration. */
+    events?: EventOptions;
+    /** Pluggable sticky bucketing service. */
+    stickyBucketService?: StickyBucketService;
+    /** Custom logger. Default: silent (no output). */
+    logger?: Logger;
+}
+interface EventOptions {
+    /** Ms between automatic event flushes. Default: 2000. */
+    flushInterval?: number;
+    /** Max events per HTTP request. Default: 10. */
+    batchSize?: number;
+    /** Max events in queue. Oldest dropped when exceeded. Default: 10_000. */
+    maxQueueSize?: number;
+    /** Retry attempts on flush failure. Default: 3. */
+    retryAttempts?: number;
+}
+interface UserContext {
+    /** User identifier for bucketing. Required. */
+    userId: string;
+    /** Targeting attributes (plan, country, device, etc.). */
+    attributes?: Record<string, unknown>;
+    /** When true, evaluate without firing an exposure event. Default: false. */
+    suppressExposure?: boolean;
+    /** Collect evaluation details into this log. */
+    decisionLog?: DecisionLog;
+    /** Attribute keys to strip from event payloads (used for targeting, not sent to analytics). */
+    privateAttributes?: string[];
+}
+interface TrackContext {
+    /** User identifier. Required. */
+    userId: string;
+    /** Revenue value for conversion tracking. */
+    revenue?: number;
+    /** Custom event properties. */
+    properties?: Record<string, unknown>;
+}
+interface DecisionLog {
+    readonly entries: DecisionLogEntry[];
+}
+interface DecisionLogEntry {
+    flagKey: string;
+    value: unknown;
+    variationKey: string | null;
+    source: EvaluationSource;
+    ruleId: string | null;
+    ruleType: 'targeted_delivery' | 'ab_test' | null;
+    reasons: string[];
+    evaluatedAt: number;
+    durationMs: number;
+}
+type EvaluationSource = 'override' | 'sticky' | 'rule' | 'default' | 'not_found' | 'disabled' | 'runtime_override';
+interface ServerFlagEvaluationDetails {
+    value: unknown;
+    variationKey: string | null;
+    source: EvaluationSource;
+    ruleId: string | null;
+    ruleType: 'targeted_delivery' | 'ab_test' | null;
+    flagKey: string;
+    reasons: string[];
+}
+interface InitResult {
+    success: boolean;
+    source: 'network' | 'bootstrap' | 'cache' | 'timeout' | 'error';
+    error?: Error;
+}
+interface StickyBucketService {
+    /** Look up stored variation for a user+flag. Return variationId or null. Synchronous. */
+    lookup(userId: string, flagKey: string): string | null;
+    /** Persist a variation assignment. Fire-and-forget (may be async internally). */
+    save(userId: string, flagKey: string, variationId: string): void;
+}
+interface Logger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+type ServerEventMap = {
+    ready: () => void;
+    configUpdate: (data: {
+        publishedAt: string;
+    }) => void;
+    evaluation: (data: {
+        flagKey: string;
+        value: unknown;
+        userId: string;
+        source: EvaluationSource;
+    }) => void;
+    error: (error: Error) => void;
+};
+type ServerEventName = keyof ServerEventMap;
+interface MiddlewareConfig {
+    /** Extract userId from the request. Return undefined to skip AvsB for this request. */
+    userIdFrom: (req: unknown) => string | undefined;
+    /** Extract targeting attributes from the request. */
+    attributesFrom?: (req: unknown) => Record<string, unknown>;
+}
+interface RequestAvsB {
+    /** Evaluate a flag for the request's user. */
+    getFlag<T = unknown>(flagKey: string, defaultValue?: T): T;
+    /** Get full evaluation details for the request's user. */
+    getFlagDetails(flagKey: string): ServerFlagEvaluationDetails;
+    /** Get all flag values for the request's user. */
+    getAllFlags(): Record<string, unknown>;
+    /** Track a conversion event for the request's user. */
+    track(eventKey: string, properties?: {
+        revenue?: number;
+        [key: string]: unknown;
+    }): void;
+}
+interface OverrideEntry {
+    flagKey: string;
+    variationKey: string;
+    userId?: string;
+}
+
+declare class AvsBServer {
+    private sdkKey;
+    private pollingInterval;
+    private cdnHost;
+    private initTimeout;
+    private logger;
+    private stickyBucketService;
+    private eventOptions;
+    private datafile;
+    private ready;
+    private destroyed;
+    private tracker;
+    private pollingId;
+    private overrides;
+    private listeners;
+    private readyPromise;
+    constructor(options: AvsBServerOptions);
+    onReady(): Promise<InitResult>;
+    private initializeAndReady;
+    close(): Promise<void>;
+    flush(): Promise<void>;
+    refreshDatafile(): Promise<void>;
+    getFlag<T = unknown>(flagKey: string, userContext: UserContext, defaultValue?: T): T;
+    getFlagDetails(flagKey: string, userContext: UserContext): ServerFlagEvaluationDetails;
+    getAllFlags(userContext: UserContext): Record<string, unknown>;
+    track(eventKey: string, context: TrackContext): void;
+    logExposure(flagKey: string, userContext: {
+        userId: string;
+    }): void;
+    setOverride(flagKey: string, variationKey: string, userId?: string): void;
+    clearOverride(flagKey: string, userId?: string): void;
+    clearAllOverrides(): void;
+    createDecisionLog(): DecisionLog;
+    on<E extends ServerEventName>(event: E, cb: ServerEventMap[E]): void;
+    off<E extends ServerEventName>(event: E, cb: ServerEventMap[E]): void;
+    private evaluate;
+    private emit;
+    private initTracker;
+    private fetchDatafile;
+    private startPolling;
+    private sendHeartbeat;
+    private resolveRuntimeOverride;
+    private resolveStickyBucket;
+    private findVariation;
+    private fireExposureForVariation;
+    private recordDecisionLog;
+    private emitEvaluation;
+}
+
+declare function expressMiddleware(client: AvsBServer, config: MiddlewareConfig): (req: unknown, res: unknown, next: () => void) => void;
+declare function fastifyPlugin(instance: unknown, opts: {
+    client: AvsBServer;
+} & MiddlewareConfig, done: () => void): void;
+
+declare class InMemoryStickyBucketService implements StickyBucketService {
+    private cache;
+    private key;
+    lookup(userId: string, flagKey: string): string | null;
+    save(userId: string, flagKey: string, variationId: string): void;
+}
+interface RedisLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: {
+        EX?: number;
+    }): Promise<unknown>;
+}
+interface RedisStickyBucketOptions {
+    redis: RedisLike;
+    prefix?: string;
+    ttl?: number;
+    cacheSize?: number;
+    logger?: Logger;
+}
+declare class RedisStickyBucketService implements StickyBucketService {
+    private redis;
+    private prefix;
+    private ttl;
+    private maxCacheSize;
+    private logger;
+    private cache;
+    constructor(options: RedisStickyBucketOptions);
+    private redisKey;
+    private cacheKey;
+    lookup(userId: string, flagKey: string): string | null;
+    save(userId: string, flagKey: string, variationId: string): void;
+    private backgroundFetch;
+    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;
+
+/** No-op logger — used when no custom logger is provided. */
+declare const noopLogger: Logger;
+
+declare const SDK_VERSION = "0.1.0";
+
+export { AvsBServer, type AvsBServerOptions, type DecisionLog, type DecisionLogEntry, type EvaluationSource, type EventOptions, InMemoryStickyBucketService, type InitResult, type Logger, type MiddlewareConfig, type OverrideEntry, type RedisLike, type RedisStickyBucketOptions, RedisStickyBucketService, type RequestAvsB, SDK_VERSION, type ServerEventMap, type ServerEventName, type ServerFlagEvaluationDetails, type StickyBucketService, type StreamingClient, type StreamingOptions, type TrackContext, type UserContext, createDecisionLog, createStreamingClient, expressMiddleware, fastifyPlugin, noopLogger };

package/dist/index.d.ts

@@ -0,0 +1,246 @@
+import { FlagDatafile } from '@avsbhq/js';
+export { ExposureEvent, FlagDatafile, FlagEvaluationDetails, MetricEvent } from '@avsbhq/js';
+
+interface AvsBServerOptions {
+    /** SDK key for the flag environment (e.g., "env_abc123") */
+    sdkKey: string;
+    /** Datafile polling interval in ms. Default: 60_000 (60s). Min: 5_000. */
+    pollingInterval?: number;
+    /** CDN host for datafile fetches. Default: "https://cdn.avsb.app" */
+    cdnHost?: string;
+    /** Max ms to wait for initial datafile fetch in onReady(). Default: 10_000. */
+    initTimeout?: number;
+    /** Pre-fetched datafile to skip initial network request. */
+    bootstrap?: FlagDatafile;
+    /** Enable SSE streaming for real-time datafile updates. Default: false. */
+    streaming?: boolean;
+    /** Custom SSE endpoint URL. Default: derived from app URL. */
+    streamingEndpoint?: string;
+    /** Event tracking configuration. */
+    events?: EventOptions;
+    /** Pluggable sticky bucketing service. */
+    stickyBucketService?: StickyBucketService;
+    /** Custom logger. Default: silent (no output). */
+    logger?: Logger;
+}
+interface EventOptions {
+    /** Ms between automatic event flushes. Default: 2000. */
+    flushInterval?: number;
+    /** Max events per HTTP request. Default: 10. */
+    batchSize?: number;
+    /** Max events in queue. Oldest dropped when exceeded. Default: 10_000. */
+    maxQueueSize?: number;
+    /** Retry attempts on flush failure. Default: 3. */
+    retryAttempts?: number;
+}
+interface UserContext {
+    /** User identifier for bucketing. Required. */
+    userId: string;
+    /** Targeting attributes (plan, country, device, etc.). */
+    attributes?: Record<string, unknown>;
+    /** When true, evaluate without firing an exposure event. Default: false. */
+    suppressExposure?: boolean;
+    /** Collect evaluation details into this log. */
+    decisionLog?: DecisionLog;
+    /** Attribute keys to strip from event payloads (used for targeting, not sent to analytics). */
+    privateAttributes?: string[];
+}
+interface TrackContext {
+    /** User identifier. Required. */
+    userId: string;
+    /** Revenue value for conversion tracking. */
+    revenue?: number;
+    /** Custom event properties. */
+    properties?: Record<string, unknown>;
+}
+interface DecisionLog {
+    readonly entries: DecisionLogEntry[];
+}
+interface DecisionLogEntry {
+    flagKey: string;
+    value: unknown;
+    variationKey: string | null;
+    source: EvaluationSource;
+    ruleId: string | null;
+    ruleType: 'targeted_delivery' | 'ab_test' | null;
+    reasons: string[];
+    evaluatedAt: number;
+    durationMs: number;
+}
+type EvaluationSource = 'override' | 'sticky' | 'rule' | 'default' | 'not_found' | 'disabled' | 'runtime_override';
+interface ServerFlagEvaluationDetails {
+    value: unknown;
+    variationKey: string | null;
+    source: EvaluationSource;
+    ruleId: string | null;
+    ruleType: 'targeted_delivery' | 'ab_test' | null;
+    flagKey: string;
+    reasons: string[];
+}
+interface InitResult {
+    success: boolean;
+    source: 'network' | 'bootstrap' | 'cache' | 'timeout' | 'error';
+    error?: Error;
+}
+interface StickyBucketService {
+    /** Look up stored variation for a user+flag. Return variationId or null. Synchronous. */
+    lookup(userId: string, flagKey: string): string | null;
+    /** Persist a variation assignment. Fire-and-forget (may be async internally). */
+    save(userId: string, flagKey: string, variationId: string): void;
+}
+interface Logger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+type ServerEventMap = {
+    ready: () => void;
+    configUpdate: (data: {
+        publishedAt: string;
+    }) => void;
+    evaluation: (data: {
+        flagKey: string;
+        value: unknown;
+        userId: string;
+        source: EvaluationSource;
+    }) => void;
+    error: (error: Error) => void;
+};
+type ServerEventName = keyof ServerEventMap;
+interface MiddlewareConfig {
+    /** Extract userId from the request. Return undefined to skip AvsB for this request. */
+    userIdFrom: (req: unknown) => string | undefined;
+    /** Extract targeting attributes from the request. */
+    attributesFrom?: (req: unknown) => Record<string, unknown>;
+}
+interface RequestAvsB {
+    /** Evaluate a flag for the request's user. */
+    getFlag<T = unknown>(flagKey: string, defaultValue?: T): T;
+    /** Get full evaluation details for the request's user. */
+    getFlagDetails(flagKey: string): ServerFlagEvaluationDetails;
+    /** Get all flag values for the request's user. */
+    getAllFlags(): Record<string, unknown>;
+    /** Track a conversion event for the request's user. */
+    track(eventKey: string, properties?: {
+        revenue?: number;
+        [key: string]: unknown;
+    }): void;
+}
+interface OverrideEntry {
+    flagKey: string;
+    variationKey: string;
+    userId?: string;
+}
+
+declare class AvsBServer {
+    private sdkKey;
+    private pollingInterval;
+    private cdnHost;
+    private initTimeout;
+    private logger;
+    private stickyBucketService;
+    private eventOptions;
+    private datafile;
+    private ready;
+    private destroyed;
+    private tracker;
+    private pollingId;
+    private overrides;
+    private listeners;
+    private readyPromise;
+    constructor(options: AvsBServerOptions);
+    onReady(): Promise<InitResult>;
+    private initializeAndReady;
+    close(): Promise<void>;
+    flush(): Promise<void>;
+    refreshDatafile(): Promise<void>;
+    getFlag<T = unknown>(flagKey: string, userContext: UserContext, defaultValue?: T): T;
+    getFlagDetails(flagKey: string, userContext: UserContext): ServerFlagEvaluationDetails;
+    getAllFlags(userContext: UserContext): Record<string, unknown>;
+    track(eventKey: string, context: TrackContext): void;
+    logExposure(flagKey: string, userContext: {
+        userId: string;
+    }): void;
+    setOverride(flagKey: string, variationKey: string, userId?: string): void;
+    clearOverride(flagKey: string, userId?: string): void;
+    clearAllOverrides(): void;
+    createDecisionLog(): DecisionLog;
+    on<E extends ServerEventName>(event: E, cb: ServerEventMap[E]): void;
+    off<E extends ServerEventName>(event: E, cb: ServerEventMap[E]): void;
+    private evaluate;
+    private emit;
+    private initTracker;
+    private fetchDatafile;
+    private startPolling;
+    private sendHeartbeat;
+    private resolveRuntimeOverride;
+    private resolveStickyBucket;
+    private findVariation;
+    private fireExposureForVariation;
+    private recordDecisionLog;
+    private emitEvaluation;
+}
+
+declare function expressMiddleware(client: AvsBServer, config: MiddlewareConfig): (req: unknown, res: unknown, next: () => void) => void;
+declare function fastifyPlugin(instance: unknown, opts: {
+    client: AvsBServer;
+} & MiddlewareConfig, done: () => void): void;
+
+declare class InMemoryStickyBucketService implements StickyBucketService {
+    private cache;
+    private key;
+    lookup(userId: string, flagKey: string): string | null;
+    save(userId: string, flagKey: string, variationId: string): void;
+}
+interface RedisLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: {
+        EX?: number;
+    }): Promise<unknown>;
+}
+interface RedisStickyBucketOptions {
+    redis: RedisLike;
+    prefix?: string;
+    ttl?: number;
+    cacheSize?: number;
+    logger?: Logger;
+}
+declare class RedisStickyBucketService implements StickyBucketService {
+    private redis;
+    private prefix;
+    private ttl;
+    private maxCacheSize;
+    private logger;
+    private cache;
+    constructor(options: RedisStickyBucketOptions);
+    private redisKey;
+    private cacheKey;
+    lookup(userId: string, flagKey: string): string | null;
+    save(userId: string, flagKey: string, variationId: string): void;
+    private backgroundFetch;
+    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;
+
+/** No-op logger — used when no custom logger is provided. */
+declare const noopLogger: Logger;
+
+declare const SDK_VERSION = "0.1.0";
+
+export { AvsBServer, type AvsBServerOptions, type DecisionLog, type DecisionLogEntry, type EvaluationSource, type EventOptions, InMemoryStickyBucketService, type InitResult, type Logger, type MiddlewareConfig, type OverrideEntry, type RedisLike, type RedisStickyBucketOptions, RedisStickyBucketService, type RequestAvsB, SDK_VERSION, type ServerEventMap, type ServerEventName, type ServerFlagEvaluationDetails, type StickyBucketService, type StreamingClient, type StreamingOptions, type TrackContext, type UserContext, createDecisionLog, createStreamingClient, expressMiddleware, fastifyPlugin, noopLogger };