@emit-vision/sdk-js 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,15 +1,15 @@
-export type EmitVisionUser = {
+type EmitVisionUser = {
     id?: string;
     email?: string;
     username?: string;
 };
-export type EmitVisionTraits = Omit<EmitVisionUser, "id">;
-export type DeploymentContext = {
+type EmitVisionTraits = Omit<EmitVisionUser, "id">;
+type DeploymentContext = {
     deploymentId?: string;
     buildId?: string;
 };
-export type FeatureFlagsContext = Record<string, string | number | boolean | null>;
-export type FlagEvaluationOptions = {
+type FeatureFlagsContext = Record<string, string | number | boolean | null>;
+type FlagEvaluationOptions = {
     /** Opaque key used to bucket the caller. Must be provided explicitly — the SDK never reads email or username automatically. */
     evaluationKey: string;
     /** Overrides the environment set at init time for this evaluation request. */
@@ -19,13 +19,19 @@ export type FlagEvaluationOptions = {
     /** Limit evaluation to specific flag keys. Omit to evaluate all active flags. */
     flagKeys?: string[];
 };
-export type AutoCaptureOptions = {
+type AutoCaptureOptions = {
     errors?: boolean;
     unhandledRejections?: boolean;
     /** Automatically fire a `$flag_exposure` event for each flag after evaluation. Default: true. */
     flagExposures?: boolean;
+    /**
+     * Automatically fire a `$page_view` event on init and on browser navigation
+     * (popstate + history.pushState/replaceState). Default: false.
+     * The event includes `{ page: window.location.pathname }` in properties.
+     */
+    pageViews?: boolean;
 };
-export type CaptureOptions = {
+type CaptureOptions = {
     eventId?: string;
     timestamp?: string;
     environment?: string;
@@ -37,7 +43,7 @@ export type CaptureOptions = {
     featureFlags?: FeatureFlagsContext;
     tags?: Record<string, string>;
 };
-export type EmitVisionOptions = {
+type EmitVisionOptions = {
     apiKey?: string;
     dsn?: string;
     endpoint?: string;
@@ -56,10 +62,18 @@ export type EmitVisionOptions = {
     fetchImpl?: typeof fetch;
     /** TTL in milliseconds for in-memory flag evaluation cache. Default: 60 000 (1 minute). */
     flagEvalTtlMs?: number;
+    /** Initial delay (ms) before retrying after a flush failure. Default: 1000. Doubles each consecutive failure up to {@link retryBackoffMaxMs}. Set to 0 to retry immediately on every tick. */
+    retryBackoffInitialMs?: number;
+    /** Maximum delay (ms) between flush retries. Default: 30000. */
+    retryBackoffMaxMs?: number;
+    /** Disable the SDK after this many consecutive flush failures: the queue is dropped, future captures become no-ops, and a single warning is logged. Default: 20. Set to 0 to disable the cap and retry forever. */
+    maxConsecutiveFlushFailures?: number;
 };
-type RequiredEmitVisionOptions = Required<Pick<EmitVisionOptions, "apiKey" | "endpoint" | "flushIntervalMs" | "batchSize" | "fetchImpl" | "flushOnCapture" | "flagEvalTtlMs">> & Pick<EmitVisionOptions, "environment" | "release" | "sessionId" | "label" | "deployment" | "featureFlags" | "debug"> & {
+
+type RequiredEmitVisionOptions = Required<Pick<EmitVisionOptions, "apiKey" | "endpoint" | "flushIntervalMs" | "batchSize" | "fetchImpl" | "flushOnCapture" | "flagEvalTtlMs" | "retryBackoffInitialMs" | "retryBackoffMaxMs" | "maxConsecutiveFlushFailures">> & Pick<EmitVisionOptions, "environment" | "release" | "sessionId" | "label" | "deployment" | "featureFlags" | "debug"> & {
     autoCapture: Required<AutoCaptureOptions> & {
         flagExposures: boolean;
+        pageViews: boolean;
     };
 };
 declare class EmitVisionClient {
@@ -73,7 +87,8 @@ declare class EmitVisionClient {
     private timer;
     private flushScheduled;
     private readonly fetchImpl;
-    private readonly flagCache;
+    private readonly flagEval;
+    private readonly retry;
     constructor(options: RequiredEmitVisionOptions);
     captureEvent(name: string, properties?: Record<string, unknown>, options?: CaptureOptions): void;
     captureError(error: unknown, options?: CaptureOptions): void;
@@ -81,49 +96,45 @@ declare class EmitVisionClient {
     setContext(context: Record<string, unknown>): void;
     setDeploymentContext(context: DeploymentContext): void;
     setFeatureFlags(featureFlags: FeatureFlagsContext): void;
-    /**
-     * Fetch and evaluate all active flags for the given evaluation key.
-     * Results are cached for `ttlMs` (defaults to `flagEvalTtlMs` from init options).
-     * On network failure returns an empty object and does not throw.
-     * Evaluated variants are automatically merged into the SDK's feature-flag context.
-     */
     evaluateFlags(opts: FlagEvaluationOptions): Promise<FeatureFlagsContext>;
-    /**
-     * Return a single flag's value, evaluated for the given key.
-     * Returns `fallback` on network failure or when the flag is not found — never throws.
-     */
     getFlag<T extends string | number | boolean | null>(flagKey: string, fallback: T, opts: FlagEvaluationOptions): Promise<T>;
-    /**
-     * Bypass the cache and re-fetch evaluations for the given key.
-     * Useful after a flag change in the dashboard that should apply immediately.
-     */
     refreshFlags(opts: FlagEvaluationOptions): Promise<FeatureFlagsContext>;
+    capturePageView(path?: string): void;
     captureExposure(flagKey: string, variantKey: string, variantValue?: string | number | boolean | null, reason?: string, environment?: string): void;
-    private fetchAndCacheFlags;
     setTags(tags: Record<string, string>): void;
     flush(): Promise<void>;
+    private flushChunk;
+    private handleFlushFailure;
+    private stopBackgroundWork;
     close(): void;
+    private enqueueMetaEvent;
     private enqueue;
     private scheduleFlush;
     private withDefaults;
     private mergeDeployment;
     private mergeFeatureFlags;
     private readonly handleWindowError;
+    private readonly handlePopState;
+    private patchHistoryMethod;
+    private restoreHistoryMethod;
     private readonly handleUnhandledRejection;
     private debug;
 }
-export declare function init(options: EmitVisionOptions): EmitVisionClient;
-export declare function captureEvent(name: string, properties?: Record<string, unknown>, options?: CaptureOptions): void;
-export declare function captureError(error: unknown, options?: CaptureOptions): void;
-export declare function identify(user: EmitVisionUser): void;
-export declare function identify(userId: string, traits?: EmitVisionTraits): void;
-export declare function setContext(context: Record<string, unknown>): void;
-export declare function setDeploymentContext(context: DeploymentContext): void;
-export declare function setFeatureFlags(featureFlags: FeatureFlagsContext): void;
-export declare function setTags(tags: Record<string, string>): void;
-export declare function flush(): Promise<void>;
-export declare function evaluateFlags(options: FlagEvaluationOptions): Promise<FeatureFlagsContext>;
-export declare function getFlag<T extends string | number | boolean | null>(flagKey: string, fallback: T, options: FlagEvaluationOptions): Promise<T>;
-export declare function refreshFlags(options: FlagEvaluationOptions): Promise<FeatureFlagsContext>;
-export declare function captureExposure(flagKey: string, variantKey: string, variantValue?: string | number | boolean | null, reason?: string, environment?: string): void;
-export {};
+
+declare function init(options: EmitVisionOptions): EmitVisionClient;
+declare function captureEvent(name: string, properties?: Record<string, unknown>, options?: CaptureOptions): void;
+declare function captureError(error: unknown, options?: CaptureOptions): void;
+declare function capturePageView(path?: string): void;
+declare function identify(user: EmitVisionUser): void;
+declare function identify(userId: string, traits?: EmitVisionTraits): void;
+declare function setContext(context: Record<string, unknown>): void;
+declare function setDeploymentContext(context: DeploymentContext): void;
+declare function setFeatureFlags(featureFlags: FeatureFlagsContext): void;
+declare function setTags(tags: Record<string, string>): void;
+declare function flush(): Promise<void>;
+declare function evaluateFlags(options: FlagEvaluationOptions): Promise<FeatureFlagsContext>;
+declare function getFlag<T extends string | number | boolean | null>(flagKey: string, fallback: T, options: FlagEvaluationOptions): Promise<T>;
+declare function refreshFlags(options: FlagEvaluationOptions): Promise<FeatureFlagsContext>;
+declare function captureExposure(flagKey: string, variantKey: string, variantValue?: string | number | boolean | null, reason?: string, environment?: string): void;
+
+export { type AutoCaptureOptions, type CaptureOptions, type DeploymentContext, type EmitVisionOptions, type EmitVisionTraits, type EmitVisionUser, type FeatureFlagsContext, type FlagEvaluationOptions, captureError, captureEvent, captureExposure, capturePageView, evaluateFlags, flush, getFlag, identify, init, refreshFlags, setContext, setDeploymentContext, setFeatureFlags, setTags };