@contentful/optimization-web 0.1.0-alpha

package/dist/observers/ElementExistenceObserver.d.ts

@@ -0,0 +1,195 @@
+/**
+ * ElementExistenceObserver
+ * - Observes childList + subtree
+ * - Coalesces moves (reparent/reorder ignored)
+ * - Filters to Element (for IntersectionObserver)
+ * - Batches & chunks delivery in idle time
+ * - Two optional per-kind callbacks + one aggregate callback
+ */
+/**
+ * Default idle timeout (in milliseconds) used when scheduling processing
+ * of mutation records.
+ */
+export declare const DEFAULT_IDLE_TIMEOUT_MS = 100;
+/**
+ * Default maximum number of elements delivered in a single callback chunk.
+ */
+export declare const DEFAULT_MAX_CHUNK = 250;
+/**
+ * Lower bound for idle timeout to avoid ultra-tight loops (~1 animation frame).
+ */
+export declare const MIN_IDLE_TIMEOUT_MS = 16;
+/**
+ * Lower bound for maximum chunk size (must deliver at least one element).
+ */
+export declare const MIN_MAX_CHUNK = 1;
+/**
+ * True when the environment supports `MutationObserver` and can add listeners.
+ */
+export declare const HAS_MUTATION_OBSERVER: boolean;
+/**
+ * True when the environment supports `window.requestIdleCallback`.
+ */
+export declare const HAS_IDLE_CALLBACK: boolean;
+/**
+ * True when the environment supports `window.cancelIdleCallback`.
+ */
+export declare const HAS_CANCEL_IDLE: boolean;
+/**
+ * Aggregate description of changes observed in a batch of mutation records.
+ */
+export interface MutationChange {
+    /** Set of elements that were added. */
+    readonly added: ReadonlySet<Element>;
+    /** Set of elements that were removed. */
+    readonly removed: ReadonlySet<Element>;
+    /** Raw mutation records that produced this change. */
+    readonly records: readonly MutationRecord[];
+}
+/**
+ * Callback invoked when elements have been added.
+ */
+export type AddedCallback = (elements: readonly Element[]) => unknown;
+/**
+ * Callback invoked when elements have been removed.
+ */
+export type RemovedCallback = (elements: readonly Element[]) => unknown;
+/**
+ * Callback invoked when a batch of mutation records has been coalesced.
+ */
+export type MutationChangeCallback = (change: MutationChange) => unknown;
+/**
+ * Options for configuring {@link ElementExistenceObserver}.
+ */
+export interface ElementExistenceObserverOptions {
+    /**
+     * Root node to observe for changes. Defaults to `document` where possible.
+     */
+    readonly root?: Node;
+    /**
+     * Idle timeout in milliseconds used when scheduling processing of mutations.
+     */
+    readonly idleTimeoutMs?: number;
+    /**
+     * Maximum number of elements delivered per callback chunk.
+     */
+    readonly maxChunk?: number;
+    /**
+     * Callback invoked with the aggregate change payload (added/removed plus raw records).
+     */
+    readonly onChange?: MutationChangeCallback;
+    /**
+     * Callback invoked with per-kind additions (batched/chunked).
+     */
+    readonly onAdded?: AddedCallback;
+    /**
+     * Callback invoked with per-kind removals (batched/chunked).
+     */
+    readonly onRemoved?: RemovedCallback;
+    /**
+     * Optional error handler for callback failures.
+     */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * Observe the existence of elements under a root node and deliver coalesced
+ * add/remove notifications in idle time.
+ *
+ * @remarks
+ * In non-DOM / SSR environments, the observer becomes a safe no-op, and
+ * mutation handling is disabled.
+ */
+declare class ElementExistenceObserver {
+    private readonly observer?;
+    private readonly root;
+    private readonly idleTimeoutMs;
+    private readonly maxChunk;
+    private readonly onChange?;
+    private readonly onAdded?;
+    private readonly onRemoved?;
+    private readonly onError?;
+    private pendingRecords;
+    private scheduled;
+    private idleHandle;
+    private disconnected;
+    /**
+     * Create a new element existence observer.
+     *
+     * @param options - Optional configuration for root, callbacks, and batching.
+     */
+    constructor(options?: ElementExistenceObserverOptions);
+    /**
+     * True if the watcher is actively observing (i.e., in a browser with MutationObserver).
+     */
+    isActive(): boolean;
+    /**
+     * Stop observing and clear any pending work.
+     */
+    disconnect(): void;
+    /**
+     * Synchronously process any pending mutation records.
+     *
+     * @remarks
+     * Cancels any outstanding idle callbacks or timeouts and delivers changes immediately.
+     */
+    flush(): void;
+    /**
+     * Schedule processing of pending records using idle time or a timeout.
+     */
+    private scheduleProcess;
+    /**
+     * Process all currently pending mutation records immediately.
+     */
+    private processNow;
+    /**
+     * Narrow a value to `Node` when the DOM is available.
+     */
+    private static isNode;
+    /**
+     * Normalize a numeric option to a finite integer and enforce a minimum.
+     */
+    private static sanitizeInt;
+    /**
+     * Coalesce a set of mutation records into net added and removed nodes,
+     * ignoring transient moves.
+     */
+    private static coalesce;
+    /**
+     * Convert node-level sets into element-only sets, including descendants.
+     */
+    private static toElementSets;
+    /**
+     * Collect all elements (and descendants) from a set of nodes, optionally
+     * filtering out disconnected nodes.
+     */
+    private static flattenElements;
+    /**
+     * Cancel a previously scheduled idle callback or fallback timeout.
+     */
+    private static cancelIdle;
+    /**
+     * Drain and return the current list of pending mutation records.
+     */
+    private drainPending;
+    /**
+     * Deliver the aggregate change payload (added, removed, records) to the
+     * `onChange` callback if configured.
+     */
+    private deliverAggregate;
+    /**
+     * Deliver per-kind added/removed elements to their respective callbacks in
+     * chunks if necessary.
+     */
+    private deliverPerKind;
+    /**
+     * Dispatch element arrays in chunks to respect the configured `maxChunk`
+     * and avoid blocking the main thread.
+     */
+    private dispatchChunked;
+    /**
+     * Normalize sync/async callbacks and centralize error handling.
+     */
+    private safeCall;
+}
+export default ElementExistenceObserver;
+//# sourceMappingURL=ElementExistenceObserver.d.ts.map

package/dist/observers/ElementExistenceObserver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ElementExistenceObserver.d.ts","sourceRoot":"","sources":["../../src/observers/ElementExistenceObserver.ts"],"names":[],"mappings":"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"}

package/dist/observers/ElementView.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Shared types, tunables, environment helpers, and state utilities for ElementViewObserver.
+ */
+/**
+ * Timer handle type returned by `setTimeout`.
+ */
+export type Timer = ReturnType<typeof setTimeout>;
+/**
+ * Interval handle type returned by `setInterval`.
+ */
+export type Interval = ReturnType<typeof setInterval>;
+/**
+ * Get a high-resolution timestamp when available.
+ *
+ * @returns A timestamp in milliseconds since an arbitrary origin.
+ */
+export declare const NOW: () => number;
+/**
+ * Determine whether the current page is visible.
+ *
+ * @returns `true` if the page is visible or no document is available, otherwise `false`.
+ */
+export declare const isPageVisible: () => boolean;
+/** ---- Tunables ---- */
+/**
+ * Default tuning values for {@link ElementViewObserver}.
+ */
+export declare const DEFAULTS: {
+    /** Default dwell time in ms before firing. */
+    readonly DWELL_MS: 1000;
+    /** Default minimum intersection ratio considered visible. */
+    readonly RATIO: 0.1;
+    /** Default maximum retry attempts. */
+    readonly MAX_RETRIES: 2;
+    /** Default initial backoff delay for retries in ms. */
+    readonly BACKOFF_MS: 300;
+    /** Default exponential backoff multiplier. */
+    readonly MULTIPLIER: 2;
+    /** Divisor used to compute jitter magnitude. */
+    readonly JITTER_DIVISOR: 2;
+    /** Interval for sweeping orphaned states in ms. */
+    readonly SWEEP_INTERVAL_MS: 30000;
+};
+/**
+ * Add small random jitter to a base delay to reduce thundering herd effects.
+ *
+ * @param base - Base delay in ms.
+ * @returns Jittered delay in ms.
+ */
+export declare const withJitter: (base: number) => number;
+/** ---- Public Types ---- */
+/**
+ * Information passed to the element view callback.
+ */
+export interface ElementViewCallbackInfo {
+    /** Total number of milliseconds the element has been visible. */
+    readonly totalVisibleMs: number;
+    /** How many attempts have been made (including the current one). */
+    readonly attempts: number;
+    /** Optional user data associated with the element. */
+    readonly data?: unknown;
+}
+/**
+ * Callback invoked once per element after the dwell requirement is met,
+ * with retries on failure.
+ */
+export type ElementViewCallback = (element: Element, info: ElementViewCallbackInfo) => void | Promise<void>;
+/**
+ * Observer-level options that apply to all observed elements.
+ */
+export interface ElementViewObserverOptions {
+    /** Required visible time (in ms) before the callback is fired. */
+    readonly dwellTimeMs?: number;
+    /** Minimum intersection ratio (0-1) considered visible. */
+    readonly minVisibleRatio?: number;
+    /** IntersectionObserver root. Default: null (viewport). */
+    readonly root?: Element | Document | null;
+    /** IntersectionObserver rootMargin. Default: `"0px"`. */
+    readonly rootMargin?: string;
+    /** Max callback retry attempts on failure. */
+    readonly maxRetries?: number;
+    /** Initial backoff delay in ms for retries. */
+    readonly retryBackoffMs?: number;
+    /** Exponential backoff multiplier. */
+    readonly backoffMultiplier?: number;
+}
+/**
+ * Per-element overrides and data passed to the callback.
+ */
+export interface ElementViewElementOptions {
+    /** Per-element dwell time override in ms. */
+    readonly dwellTimeMs?: number;
+    /** Per-element optional max callback retry attempts on failures. */
+    readonly maxRetries?: number;
+    /** Per-element optional initial backoff delay in ms for retrie. */
+    readonly retryBackoffMs?: number;
+    /** Per-element optional exponential backoff multiplier. */
+    readonly backoffMultiplier?: number;
+    /** Arbitrary data to pass through to the callback for this element. */
+    readonly data?: unknown;
+}
+/** ---- Effective internal option shapes ---- */
+/**
+ * Fully-resolved observer-level options used internally.
+ */
+export type EffectiveObserverOptions = Required<Pick<ElementViewObserverOptions, 'dwellTimeMs' | 'minVisibleRatio' | 'root' | 'rootMargin' | 'maxRetries' | 'retryBackoffMs' | 'backoffMultiplier'>>;
+/**
+ * Fully-resolved per-element overrides used internally.
+ */
+export type PerElementEffectiveOptions = Required<Pick<EffectiveObserverOptions, 'dwellTimeMs' | 'maxRetries' | 'retryBackoffMs' | 'backoffMultiplier'>>;
+/**
+ * Internal per-element state tracked by the observer.
+ */
+export interface ElementState {
+    /** WeakRef path (modern browsers). */
+    ref: WeakRef<Element> | null;
+    /** Strong reference fallback if WeakRef is unavailable. */
+    strongRef: Element | null;
+    /** Effective per-element options. */
+    opts: PerElementEffectiveOptions;
+    /** User data associated with the element. */
+    data?: unknown;
+    /** Accumulated visible time in ms. */
+    accumulatedMs: number;
+    /** Timestamp when the element became visible, or null if not currently visible. */
+    visibleSince: number | null;
+    /** Timer handle for firing the callback after dwell time. */
+    fireTimer: Timer | null;
+    /** Timer handle for scheduled retry. */
+    retryTimer: Timer | null;
+    /** Timestamp when retry was scheduled. */
+    retryScheduledAt: number | null;
+    /** Delay used for the current retry. */
+    retryDelayMs: number | null;
+    /** True if a retry is pending but not yet scheduled. */
+    pendingRetry: boolean;
+    /** Number of attempts performed so far. */
+    attempts: number;
+    /** True once the callback has succeeded or retries are exhausted. */
+    done: boolean;
+    /** True while a callback attempt is in flight. */
+    inFlight: boolean;
+    /** Last known visibility state for the element. */
+    lastKnownVisible: boolean;
+}
+/**
+ * Small numeric sanitizers.
+ */
+export declare const Num: {
+    /** Use the provided number or fall back when the value is not numeric. */
+    n: (value: unknown, fallback: number) => number;
+    /** Clamp a value to the [0, 1] range. */
+    clamp01: (value: number | undefined, fallback: number) => number;
+    /** Ensure a non-negative value. */
+    nonNeg: (value: number | undefined, fallback: number) => number;
+    /** Ensure a value of at least 1. */
+    atLeast1: (value: number | undefined, fallback: number) => number;
+};
+/**
+ * Clear a scheduled fire timer, if present.
+ *
+ * @param state - Element state whose fire timer should be cleared.
+ */
+export declare const clearFireTimer: (state: ElementState) => void;
+/**
+ * Cancel a scheduled retry timer, if present.
+ *
+ * @param state - Element state whose retry timer should be cleared.
+ */
+export declare const cancelRetry: (state: ElementState) => void;
+/**
+ * Dereference the element, honoring WeakRef when available.
+ *
+ * @param state - Element state containing refs.
+ * @returns The underlying element or `null` if no longer available.
+ */
+export declare const derefElement: (state: ElementState) => Element | null;
+//# sourceMappingURL=ElementView.d.ts.map

package/dist/observers/ElementView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ElementView.d.ts","sourceRoot":"","sources":["../../src/observers/ElementView.ts"],"names":[],"mappings":"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"}

package/dist/observers/ElementViewObserver.d.ts

@@ -0,0 +1,164 @@
+/**
+ * IntersectionObserver that:
+ * - Tracks cumulative visible time per element
+ * - Fires a sync/async callback exactly once per observed element
+ * - Retries on failure with exponential backoff (retry scope is per "visibility cycle")
+ * - Pauses when the page/tab is hidden; resumes cleanly
+ * - Coalesces retries to avoid duplicate concurrent attempts
+ * - Supports per-element overrides and optional data on observe()
+ * - Periodically sweeps orphaned states to prevent memory growth
+ *
+ * Assumes DOM environment (browser).
+ */
+import { type ElementState, type ElementViewCallback, type ElementViewElementOptions, type ElementViewObserverOptions } from './ElementView';
+/**
+ * Observes elements for dwell time and triggers the callback (with retries)
+ * once per element.
+ *
+ * @remarks
+ * Uses IntersectionObserver under the hood and maintains per-element state to
+ * track visibility, accumulated dwell time, and retry scheduling.
+ */
+declare class ElementViewObserver {
+    private readonly callback;
+    private readonly opts;
+    private readonly io;
+    private readonly states;
+    private readonly activeStates;
+    private boundVisibilityHandler;
+    private sweepInterval;
+    /**
+     * Create a new element view observer.
+     *
+     * @param callback - Callback invoked once per element when dwell/visibility
+     *   requirements are met.
+     * @param options - Optional observer-level tuning options.
+     */
+    constructor(callback: ElementViewCallback, options?: ElementViewObserverOptions);
+    /**
+     * Observe an element with optional per-element overrides and data.
+     *
+     * @param element - Element to observe.
+     * @param options - Optional per-element overrides and callback data.
+     */
+    observe(element: Element, options?: ElementViewElementOptions): void;
+    /**
+     * Stop observing an element and release its state and timers.
+     *
+     * @param element - Element to stop observing.
+     */
+    unobserve(element: Element): void;
+    /**
+     * Disconnect the underlying IntersectionObserver and clear all state.
+     */
+    disconnect(): void;
+    /**
+     * Lightweight, readonly stats snapshot for a given element.
+     *
+     * @param element - Element for which to retrieve stats.
+     * @returns A subset of {@link ElementState} or `null` if no state is tracked.
+     */
+    getStats(element: Element): Readonly<Pick<ElementState, 'accumulatedMs' | 'visibleSince' | 'attempts' | 'done' | 'inFlight' | 'pendingRetry' | 'lastKnownVisible'>> | null;
+    /**
+     * Normalize high-level observer options into an effective configuration.
+     */
+    private static initOptions;
+    /**
+     * Create a new per-element state object using observer defaults and any
+     * per-element overrides.
+     */
+    private createState;
+    /**
+     * Handle page visibility changes by pausing/resuming timers and retries.
+     */
+    private onPageVisibilityChange;
+    /**
+     * Update a state in response to the page becoming hidden.
+     *
+     * @remarks
+     * Freezes dwell time accumulation and converts any active retry into a
+     * pending retry with remaining delay.
+     */
+    private static onHidden;
+    /**
+     * Update a state in response to the page becoming visible again.
+     */
+    private onResume;
+    /**
+     * Handle IntersectionObserver notifications and update per-element
+     * visibility state.
+     */
+    private onIntersect;
+    /**
+     * Mark a state as visible and schedule the callback if dwell time is met.
+     */
+    private onVisible;
+    /**
+     * Mark a state as not visible and cancel any scheduled callback or retry.
+     */
+    private static onNotVisible;
+    /**
+     * Schedule firing of the callback when the remaining dwell requirement is met,
+     * if appropriate for the current state.
+     */
+    private scheduleFireIfDue;
+    /**
+     * Schedule a retry attempt after a delay, if the element is currently visible.
+     */
+    private scheduleRetry;
+    /**
+     * Immediately attempt to fire the callback for a state and record the
+     * total dwell time used for this attempt.
+     */
+    private trigger;
+    /**
+     * Perform a single callback attempt for a state, handling success or failure.
+     *
+     * @param state - State to attempt the callback for.
+     * @param preTotal - Optional precomputed dwell time in ms.
+     */
+    private attemptCallback;
+    /**
+     * Handle a successful callback attempt by marking the state as done and
+     * unobserving the element.
+     */
+    private onAttemptSuccess;
+    /**
+     * Handle a failed callback attempt by either scheduling another retry or
+     * marking the state as exhausted.
+     */
+    private onAttemptFailure;
+    /**
+     * Handle the case where the maximum number of retries has been exceeded.
+     */
+    private onRetriesExceeded;
+    /**
+     * Finalize a state for an element that has been garbage-collected or otherwise
+     * lost, ensuring timers are cleared and state maps are cleaned up.
+     */
+    private finalizeDroppedState;
+    /**
+     * Attempt to unobserve an element and fall back to manual cleanup if an
+     * error occurs.
+     */
+    private safeAutoUnobserve;
+    /**
+     * Ensure there is an active sweeper interval to clean up orphaned states.
+     */
+    private ensureSweeper;
+    /**
+     * Stop the sweeper interval if running.
+     */
+    private stopSweeper;
+    /**
+     * Stop the sweeper interval when there are no active states left.
+     */
+    private maybeStopSweeper;
+    /**
+     * Remove state for elements that are no longer present in the document or
+     * whose references have been lost.
+     */
+    private sweepOrphans;
+}
+export default ElementViewObserver;
+//# sourceMappingURL=ElementViewObserver.d.ts.map

package/dist/observers/ElementViewObserver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ElementViewObserver.d.ts","sourceRoot":"","sources":["../../src/observers/ElementViewObserver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAUhC,MAAM,eAAe,CAAA;AAEtB;;;;;;;GAOG;AACH,cAAM,mBAAmB;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;IAC/C,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAsB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAC9D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;IACvD,OAAO,CAAC,sBAAsB,CAA4B;IAC1D,OAAO,CAAC,aAAa,CAAwB;IAE7C;;;;;;OAMG;gBACgB,QAAQ,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,0BAA0B;IAqBtF;;;;;OAKG;IACI,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,yBAAyB,GAAG,IAAI;IAW3E;;;;OAIG;IACI,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAaxC;;OAEG;IACI,UAAU,IAAI,IAAI;IAgBzB;;;;;OAKG;IACI,QAAQ,CACb,OAAO,EAAE,OAAO,GACf,QAAQ,CACT,IAAI,CACF,YAAY,EACV,eAAe,GACf,cAAc,GACd,UAAU,GACV,MAAM,GACN,UAAU,GACV,cAAc,GACd,kBAAkB,CACrB,CACF,GAAG,IAAI;IAeR;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAY1B;;;OAGG;IACH,OAAO,CAAC,WAAW;IA2BnB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAa9B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ;IAoBvB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAgBhB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAcnB;;OAEG;IACH,OAAO,CAAC,SAAS;IAiBjB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAc3B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAezB;;OAEG;IACH,OAAO,CAAC,aAAa;IAYrB;;;OAGG;IACH,OAAO,CAAC,OAAO;IAUf;;;;;OAKG;YACW,eAAe;IAqB7B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAkBxB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IASzB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAY5B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAczB;;OAEG;IACH,OAAO,CAAC,aAAa;IAOrB;;OAEG;IACH,OAAO,CAAC,WAAW;IAMnB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAIxB;;;OAGG;IACH,OAAO,CAAC,YAAY;CAgBrB;AAED,eAAe,mBAAmB,CAAA"}

package/dist/observers/index.d.ts

@@ -0,0 +1,6 @@
+export * from './ElementView';
+export * from './ElementExistenceObserver';
+export { default as ElementExistenceObserver } from './ElementExistenceObserver';
+export * from './ElementViewObserver';
+export { default as ElementViewObserver } from './ElementViewObserver';
+//# sourceMappingURL=index.d.ts.map

package/dist/observers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observers/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAE7B,cAAc,4BAA4B,CAAA;AAC1C,OAAO,EAAE,OAAO,IAAI,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AAEhF,cAAc,uBAAuB,CAAA;AACrC,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/storage/LocalStore.d.ts

@@ -0,0 +1,111 @@
+import { ChangeArray, Profile, SelectedPersonalizationArray } from '@contentful/optimization-core';
+import type { z } from 'zod/mini';
+/**
+ * LocalStorage key for the anonymous identifier used by the Web SDK.
+ *
+ * @internal
+ */
+export declare const ANONYMOUS_ID = "__ctfl_opt_anonymous_id__";
+/**
+ * LocalStorage key for the persisted consent status.
+ *
+ * @internal
+ */
+export declare const CONSENT = "__ctfl_opt_consent__";
+/**
+ * LocalStorage key for cached Custom Flags.
+ *
+ * @internal
+ */
+export declare const CHANGES_CACHE = "__ctfl_opt_changes__";
+/**
+ * LocalStorage key for the debug flag toggle.
+ *
+ * @internal
+ */
+export declare const DEBUG_FLAG = "__ctfl_opt_debug__";
+/**
+ * LocalStorage key for cached profile data.
+ *
+ * @internal
+ */
+export declare const PROFILE_CACHE = "__ctfl_opt_profile__";
+/**
+ * LocalStorage key for cached selected personalizations.
+ *
+ * @internal
+ */
+export declare const PERSONALIZATIONS_CACHE = "__ctfl_opt_personalizations__";
+/**
+ * Local storage abstraction used by the Web SDK to persist optimization state.
+ *
+ * @internal
+ * @remarks
+ * Wraps browser `localStorage` access and uses zod parsers to safely read and
+ * write typed values. All getters return `undefined` when no valid data is
+ * present.
+ */
+declare const LocalStore: {
+    /**
+     * Reset local caches used by the Web SDK.
+     *
+     * @param options - Optional flags controlling whether consent and debug keys
+     *   should also be removed.
+     * @example
+     * ```ts
+     * LocalStore.reset({ resetConsent: true, resetDebug: true })
+     * ```
+     */
+    reset(options?: {
+        resetConsent: boolean;
+        resetDebug: boolean;
+    }): void;
+    /**
+     * Anonymous identifier currently stored in localStorage, if any.
+     */
+    anonymousId: string | undefined;
+    /**
+     * Persisted consent status.
+     *
+     * @returns `true` if consent was stored as `accepted`, `false` if stored as
+     * `denied`, or `undefined` when no value is stored.
+     */
+    consent: boolean | undefined;
+    /**
+     * Persisted debug flag value.
+     *
+     * @returns `true` or `false` when stored, or `undefined` otherwise.
+     */
+    debug: boolean | undefined;
+    /**
+     * Cached Custom Flags change array, if present.
+     */
+    changes: ChangeArray | undefined;
+    /**
+     * Cached profile from the personalization service, if present.
+     */
+    profile: Profile | undefined;
+    /**
+     * Cached selected personalizations, if present.
+     */
+    personalizations: SelectedPersonalizationArray | undefined;
+    /**
+     * Safely read and parse typed data from localStorage.
+     *
+     * @typeParam T - Zod mini type describing the stored shape.
+     * @param key - LocalStorage key to read from.
+     * @param parser - Zod parser used to validate and parse the stored JSON.
+     * @returns Parsed data when present and valid, otherwise `undefined`.
+     */
+    getCache<T extends z.ZodMiniType>(key: string, parser: T): z.output<T> | undefined;
+    /**
+     * Write arbitrary data to localStorage or remove the key when `undefined`.
+     *
+     * @param key - LocalStorage key to write to.
+     * @param data - Value to store. Strings are written as-is; other values
+     * are JSON-stringified.
+     */
+    setCache(key: string, data: unknown): void;
+};
+export default LocalStore;
+//# sourceMappingURL=LocalStore.d.ts.map

package/dist/storage/LocalStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalStore.d.ts","sourceRoot":"","sources":["../../src/storage/LocalStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAA;AAClG,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,UAAU,CAAA;AAEjC;;;;GAIG;AACH,eAAO,MAAM,YAAY,8BAA8B,CAAA;AAEvD;;;;GAIG;AACH,eAAO,MAAM,OAAO,yBAAyB,CAAA;AAE7C;;;;GAIG;AACH,eAAO,MAAM,aAAa,yBAAyB,CAAA;AAEnD;;;;GAIG;AACH,eAAO,MAAM,UAAU,uBAAuB,CAAA;AAE9C;;;;GAIG;AACH,eAAO,MAAM,aAAa,yBAAyB,CAAA;AAEnD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,kCAAkC,CAAA;AAErE;;;;;;;;GAQG;AACH,QAAA,MAAM,UAAU;IACd;;;;;;;;;OASG;;;;;IAWH;;OAEG;iBACgB,MAAM,GAAG,SAAS;IAarC;;;;;OAKG;aACY,OAAO,GAAG,SAAS;IAwBlC;;;;OAIG;WACU,OAAO,GAAG,SAAS;IAehC;;OAEG;aACY,WAAW,GAAG,SAAS;IAatC;;OAEG;aACY,OAAO,GAAG,SAAS;IAalC;;OAEG;sBACqB,4BAA4B,GAAG,SAAS;IAahE;;;;;;;OAOG;aACM,CAAC,SAAS,CAAC,CAAC,WAAW,OAAO,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS;IAUlF;;;;;;OAMG;kBACW,MAAM,QAAQ,OAAO,GAAG,IAAI;CAO3C,CAAA;AAED,eAAe,UAAU,CAAA"}