@contentful/optimization-core 0.1.0-alpha7 → 0.1.0-alpha8

package/dist/index.d.mts

@@ -0,0 +1,1999 @@
+import { ApiClient } from '@contentful/optimization-api-client';
+import { ApiClientConfig } from '@contentful/optimization-api-client';
+import { batch } from '@preact/signals-core';
+import type { ChainModifiers } from 'contentful';
+import { ChangeArray } from '@contentful/optimization-api-client';
+import { ComponentViewBuilderArgs } from '@contentful/optimization-api-client';
+import { computed } from '@preact/signals-core';
+import { effect } from '@preact/signals-core';
+import type { Entry } from 'contentful';
+import { EntryReplacementVariant } from '@contentful/optimization-api-schemas';
+import { EntryReplacementVariant as EntryReplacementVariant_2 } from '@contentful/optimization-api-client';
+import type { EntrySkeletonType } from 'contentful';
+import { EventBuilder } from '@contentful/optimization-api-client';
+import { EventBuilderConfig } from '@contentful/optimization-api-client';
+import { ExperienceApiClientConfig } from '@contentful/optimization-api-client';
+import { ExperienceEvent } from '@contentful/optimization-api-client';
+import type { ExperienceEventType } from '@contentful/optimization-api-client';
+import { Flags } from '@contentful/optimization-api-client';
+import { Flags as Flags_2 } from '@contentful/optimization-api-schemas';
+import { GlobalApiConfigProperties } from '@contentful/optimization-api-client';
+import { IdentifyBuilderArgs } from '@contentful/optimization-api-client';
+import { InsightsApiClientConfig } from '@contentful/optimization-api-client';
+import { InsightsEvent } from '@contentful/optimization-api-client';
+import type { InsightsEventType } from '@contentful/optimization-api-client';
+import { Json } from '@contentful/optimization-api-client';
+import type { LocaleCode } from 'contentful';
+import type { LogEvent } from 'diary';
+import type { LogLevels } from 'diary';
+import { MergeTagEntry } from '@contentful/optimization-api-client';
+import { OptimizationData } from '@contentful/optimization-api-client';
+import { PageViewBuilderArgs } from '@contentful/optimization-api-client';
+import { PartialProfile } from '@contentful/optimization-api-client';
+import { PersonalizationEntry } from '@contentful/optimization-api-schemas';
+import { PersonalizationEntry as PersonalizationEntry_2 } from '@contentful/optimization-api-client';
+import { PersonalizedEntry } from '@contentful/optimization-api-schemas';
+import { PersonalizedEntry as PersonalizedEntry_2 } from '@contentful/optimization-api-client';
+import { Profile } from '@contentful/optimization-api-client';
+import { ReadonlySignal } from '@preact/signals-core';
+import { ScreenViewBuilderArgs } from '@contentful/optimization-api-client';
+import { SelectedPersonalization } from '@contentful/optimization-api-client';
+import { SelectedPersonalization as SelectedPersonalization_2 } from '@contentful/optimization-api-schemas';
+import { SelectedPersonalizationArray } from '@contentful/optimization-api-client';
+import { Signal } from '@preact/signals-core';
+import { TrackBuilderArgs } from '@contentful/optimization-api-client';
+import { untracked } from '@preact/signals-core';
+
+/**
+ * Base class for analytics implementations (internal).
+ *
+ * @internal
+ * @remarks
+ * Concrete analytics classes should implement the component/flag view tracking
+ * methods below. This base is not part of the public API.
+ */
+declare abstract class AnalyticsBase extends ProductBase {
+    /**
+     * Track a UI component view event.
+     *
+     * @param payload - Component view builder arguments.
+     * @param duplicationScope - Optional string used to scope duplication used in Stateful
+     * implementations.
+     * @privateRemarks
+     * Duplication prevention should be handled in Stateful implementations
+     */
+    abstract trackComponentView(payload: ComponentViewBuilderArgs, duplicationScope?: string): Promise<void> | void;
+    /**
+     * Track a flag (feature) view event.
+     *
+     * @param payload - Flag view builder arguments.
+     * @param duplicationScope - Optional string used to scope duplication used in Stateful
+     * implementations.
+     * @returns A promise that resolves when processing is complete (or `void`).
+     * @privateRemarks
+     * Duplication prevention should be handled in Stateful implementations
+     */
+    abstract trackFlagView(payload: ComponentViewBuilderArgs, duplicationScope?: string): Promise<void> | void;
+}
+
+/**
+ * Configuration for the stateful analytics implementation.
+ *
+ * @public
+ */
+export declare interface AnalyticsProductConfig extends ProductConfig {
+    /**
+     * Default signal values applied on initialization.
+     */
+    defaults?: AnalyticsProductConfigDefaults;
+}
+
+/**
+ * Default analytics state values applied at construction time.
+ *
+ * @public
+ */
+export declare interface AnalyticsProductConfigDefaults {
+    /** Whether analytics collection is allowed by default. */
+    consent?: boolean;
+    /** Default profile to associate with events. */
+    profile?: Profile;
+}
+
+/**
+ * Analytics implementation that maintains local state (consent, profile) and
+ * queues events until flushed or the queue reaches a maximum size.
+ *
+ * @public
+ */
+export declare class AnalyticsStateful extends AnalyticsBase implements ConsentGuard {
+    /** In‑memory queue keyed by profile. */
+    private readonly queue;
+    /** Exposed observable state references. */
+    readonly states: AnalyticsStates;
+    /**
+     * Create a new stateful analytics instance.
+     *
+     * @param options - Options to configure the analytics product for stateful environments.
+     */
+    constructor(options: AnalyticsStatefulOptions);
+    /**
+     * Reset analytics‑related signals and the last emitted event.
+     */
+    reset(): void;
+    /**
+     * Determine whether the named operation is permitted based on consent and
+     * allowed event type configuration.
+     *
+     * @param name - The method name; `'trackComponentView'` is normalized
+     * to `'component'` for allow‑list checks.
+     * @returns `true` if the operation is permitted; otherwise `false`.
+     */
+    hasConsent(name: string): boolean;
+    /**
+     * Hook invoked when an operation is blocked due to missing consent.
+     *
+     * @param name - The blocked operation name.
+     * @param payload - The original arguments supplied to the operation.
+     */
+    onBlockedByConsent(name: string, payload: unknown[]): void;
+    /**
+     * Guard used to suppress duplicate component/flag view events based on a
+     * duplication key and the component identifier.
+     *
+     * @param _name - The operation name (unused).
+     * @param payload - Tuple of [builderArgs, duplicationScope].
+     * @returns `true` if the event is NOT a duplicate and should proceed.
+     */
+    isNotDuplicated(_name: string, payload: [ComponentViewBuilderArgs, string]): boolean;
+    /**
+     * Hook invoked when an operation is blocked by the duplication guard.
+     *
+     * @param name - The blocked operation name.
+     * @param payload - The original arguments supplied to the operation.
+     */
+    onBlockedByDuplication(name: string, payload: unknown[]): void;
+    /**
+     * Queue a component view event for the active profile.
+     *
+     * @param payload - Component view builder arguments.
+     * @param _duplicationScope - Optional string used to scope duplication (used
+     * by guards); an empty string `''` is converted to the `undefined` scope
+     */
+    trackComponentView(payload: ComponentViewBuilderArgs, _duplicationScope?: string): Promise<void>;
+    /**
+     * Queue a flag view event for the active profile.
+     *
+     * @param payload - Flag view builder arguments.
+     * @param _duplicationScope - Optional string used to scope duplication (used
+     * by guards); an empty string `''` is converted to the `undefined` scope
+     */
+    trackFlagView(payload: ComponentViewBuilderArgs, _duplicationScope?: string): Promise<void>;
+    /**
+     * Intercept, validate, and place an event into the profile‑scoped queue; then
+     * trigger a size‑based flush if necessary.
+     *
+     * @param event - The event to enqueue.
+     */
+    private enqueueEvent;
+    /**
+     * Flush the queue automatically when the total number of queued events
+     * reaches {@link MAX_QUEUED_EVENTS}.
+     */
+    private flushMaxEvents;
+    /**
+     * Send all queued events grouped by profile and clear the queue.
+     * @remarks Only under rare circumstances should there be more than one
+     * profile in a stateful application.
+     */
+    flush(): Promise<void>;
+}
+
+/**
+ * Options for configuring {@link AnalyticsStateful} functionality.
+ *
+ * @public
+ * @see {@link ProductBaseOptions}
+ */
+export declare type AnalyticsStatefulOptions = ProductBaseOptions & {
+    /** Configuration specific to the Analytics product */
+    config?: AnalyticsProductConfig;
+};
+
+/**
+ * Stateless analytics implementation that sends each event immediately in a
+ * single‑event batch.
+ *
+ * @public
+ */
+export declare class AnalyticsStateless extends AnalyticsBase {
+    /**
+     * Build, intercept, validate, and send a component view event.
+     *
+     * @param args - {@link TrackViewArgs} used to build the event. Includes an
+     * optional partial profile.
+     * @returns A promise that resolves once the batch has been sent.
+     */
+    trackComponentView(args: TrackViewArgs): Promise<void>;
+    /**
+     * Build, intercept, validate, and send a flag view event.
+     *
+     * @param args - {@link TrackViewArgs} used to build the event. Includes an
+     * optional partial profile.
+     * @returns A promise that resolves once the batch has been sent.
+     */
+    trackFlagView(args: TrackViewArgs): Promise<void>;
+    /**
+     * Send a single {@link InsightsEvent} wrapped in a one‑item batch.
+     *
+     * @param event - The event to send.
+     * @param profile - Optional partial profile to attach to the batch.
+     * @returns A promise that resolves when the API call completes.
+     * @internal
+     */
+    private sendBatchEvent;
+}
+
+/**
+ * Observables exposed by the stateful analytics product.
+ *
+ * @public
+ */
+export declare interface AnalyticsStates {
+    /** Observable stream of the latest {@link AnalyticsEvent} or {@link PersonalizationEvent} (or `undefined`). */
+    eventStream: Observable<InsightsEvent | ExperienceEvent | undefined>;
+    /** Observable stream of the active {@link Profile} (or `undefined`). */
+    profile: Observable<Profile | undefined>;
+}
+
+/**
+ * Anonymous-ID cookie name used by the Optimization Core.
+ *
+ * @public
+ * @remarks
+ * This constant represents the cookie key used by the Optimization Framework
+ * to persist an anonymous identifier for tracking personalization and analytics
+ * events when no explicit profile is known.
+ *
+ * @example
+ * ```ts
+ * import { ANONYMOUS_ID_COOKIE } from '@contentful/optimization-core'
+ * const profileId = request.cookies[ANONYMOUS_ID_COOKIE]
+ * ```
+ */
+export declare const ANONYMOUS_ID_COOKIE = "ctfl-opt-aid";
+
+/**
+ * Legacy anoynmous ID cookie key for migration from experience.js
+ *
+ * @internal
+ */
+export declare const ANONYMOUS_ID_COOKIE_LEGACY = "ntaid";
+
+/**
+ * Storage key for the anonymous identifier.
+ *
+ * @internal
+ */
+export declare const ANONYMOUS_ID_KEY = "__ctfl_opt_anonymous_id__";
+
+/**
+ * Legacy anoynmous ID storage key for migration from experience.js
+ *
+ * @internal
+ */
+export declare const ANONYMOUS_ID_KEY_LEGACY = "__nt_anonymous_id__";
+
+export { batch }
+
+/**
+ * A callback invoked when a method call is blocked by {@link guardedBy}.
+ *
+ * @param methodName - The name of the method that was attempted.
+ * @param args - The readonly array of arguments supplied to the blocked call.
+ * @returns Nothing.
+ *
+ * @public
+ */
+declare type BlockHandler = (methodName: string, args: readonly unknown[]) => void;
+
+declare const changes: Signal<ChangeArray | undefined>;
+
+/**
+ * Storage key for cached Custom Flags.
+ *
+ * @internal
+ */
+export declare const CHANGES_CACHE_KEY = "__ctfl_opt_changes__";
+
+declare const consent: Signal<boolean | undefined>;
+
+/**
+ * Storage key for the persisted consent status.
+ *
+ * @internal
+ */
+export declare const CONSENT_KEY = "__ctfl_opt_consent__";
+
+/**
+ * Controller for updating the current consent state.
+ *
+ * @internal
+ * @remarks
+ * Intended for internal wiring between Core classes and the consent signal/store.
+ */
+declare interface ConsentController {
+    /**
+     * Update the runtime consent state.
+     *
+     * @param accept - `true` when the user has granted consent; `false` otherwise.
+     */
+    consent: (accept: boolean) => void;
+}
+
+/**
+ * Contract implemented by classes that gate operations based on consent.
+ *
+ * @internal
+ * @remarks
+ * These methods are consumed by the `@guardedBy` decorator to decide whether to
+ * proceed with an operation and how to report blocked calls.
+ */
+declare interface ConsentGuard {
+    /**
+     * Determine whether the named operation is permitted given current consent and
+     * any allow‑list configuration.
+     *
+     * @param name - Logical operation/method name (e.g., `'track'`, `'page'`).
+     * @returns `true` if the operation may proceed; otherwise `false`.
+     * @remarks
+     * The mapping between method names and event type strings may be product‑specific.
+     */
+    hasConsent: (name: string) => boolean;
+    /**
+     * Hook invoked when an operation is blocked due to missing consent.
+     *
+     * @param name - The blocked operation/method name.
+     * @param args - The original call arguments, provided for diagnostics/telemetry.
+     * @returns Nothing. Implementations typically log and/or emit diagnostics.
+     */
+    onBlockedByConsent: (name: string, args: unknown[]) => void;
+}
+
+export declare class ConsoleLogSink extends LogSink {
+    name: string;
+    readonly verbosity: LogLevels;
+    constructor(verbosity?: LogLevels);
+    ingest(event: LogEvent): void;
+}
+
+/**
+ * Internal base that wires the API client, event builder, and logging.
+ *
+ * @internal
+ */
+declare abstract class CoreBase {
+    /** Product implementation for analytics. */
+    abstract readonly analytics: AnalyticsBase;
+    /** Product implementation for personalization. */
+    abstract readonly personalization: PersonalizationBase;
+    /** Shared Optimization API client instance. */
+    readonly api: ApiClient;
+    /** Shared event builder instance. */
+    readonly eventBuilder: EventBuilder;
+    /** Resolved core configuration (minus any name metadata). */
+    readonly config: Omit<CoreConfig, 'name'>;
+    readonly interceptors: LifecycleInterceptors;
+    /**
+     * Create the core with API client and logging preconfigured.
+     *
+     * @param config - Core configuration including API and builder options.
+     * @example
+     * ```ts
+     * const sdk = new CoreStateless({ clientId: 'abc123', environment: 'prod' })
+     * ```
+     */
+    constructor(config: CoreConfig);
+    /**
+     * Get the value of a custom flag derived from a set of optimization changes.
+     *
+     * @param name - The flag key to resolve.
+     * @param changes - Optional change list to resolve from
+     * @returns The resolved JSON value for the flag if available.
+     * @remarks
+     * This is a convenience wrapper around personalization’s flag resolution.
+     */
+    getCustomFlag(name: string, changes?: ChangeArray): Json;
+    /**
+     * Resolve a Contentful entry to the appropriate personalized variant (or
+     * return the baseline entry if no matching variant is selected).
+     *
+     * @typeParam S - Entry skeleton type.
+     * @typeParam M - Chain modifiers.
+     * @typeParam L - Locale code.
+     * @param entry - The baseline entry to resolve.
+     * @param personalizations - Optional selection array for the current profile.
+     * @returns {@link ResolvedData} containing the resolved entry and
+         *   personalization metadata (if any).
+         */
+     personalizeEntry<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = LocaleCode>(entry: Entry<S, M, L>, personalizations?: SelectedPersonalizationArray): ResolvedData<S, M, L>;
+     /**
+      * Resolve a merge-tag value from the given entry node and profile.
+      *
+      * @param embeddedEntryNodeTarget - The merge-tag entry node to resolve.
+      * @param profile - Optional profile used for value lookup.
+      * @returns The resolved value (typically a string) or `undefined` if not found.
+      */
+     getMergeTagValue(embeddedEntryNodeTarget: MergeTagEntry, profile?: Profile): unknown;
+     /**
+      * Convenience wrapper for sending an `identify` event via personalization.
+      *
+      * @param payload - Identify builder arguments.
+      * @returns The resulting {@link OptimizationData} for the identified user.
+      */
+     identify(payload: IdentifyBuilderArgs & {
+         profile?: PartialProfile;
+     }): Promise<OptimizationData | undefined>;
+     /**
+      * Convenience wrapper for sending a `page` event via personalization.
+      *
+      * @param payload - Page view builder arguments.
+      * @returns The evaluated {@link OptimizationData} for this page view.
+      */
+     page(payload: PageViewBuilderArgs & {
+         profile?: PartialProfile;
+     }): Promise<OptimizationData | undefined>;
+     /**
+      * Convenience wrapper for sending a `screen` event via personalization.
+      *
+      * @param payload - Screen view builder arguments.
+      * @returns The evaluated {@link OptimizationData} for this screen view.
+      */
+     screen(payload: ScreenViewBuilderArgs & {
+         profile?: PartialProfile;
+     }): Promise<OptimizationData | undefined>;
+     /**
+      * Convenience wrapper for sending a custom `track` event via personalization.
+      *
+      * @param payload - Track builder arguments.
+      * @returns The evaluated {@link OptimizationData} for this event.
+      */
+     track(payload: TrackBuilderArgs & {
+         profile?: PartialProfile;
+     }): Promise<OptimizationData | undefined>;
+     /**
+      * Track a component view in both personalization and analytics.
+      *
+      * @param payload - Component view builder arguments. When `payload.sticky` is
+      *   `true`, the event will also be sent via personalization as a sticky
+      *   component view.
+      * @param duplicationScope - Optional string used to scope duplication used in Stateful
+      * implementations
+      * @returns A promise that resolves when all delegated calls complete.
+      * @remarks
+      * The sticky behavior is delegated to personalization; analytics is always
+      * invoked regardless of `sticky`.
+      */
+     trackComponentView(payload: ComponentViewBuilderArgs & {
+         profile?: PartialProfile;
+     }, duplicationScope?: string): Promise<OptimizationData | undefined>;
+     /**
+      * Track a feature flag view via analytics.
+      *
+      * @param payload - Component view builder arguments used to build the flag view event.
+      * @param duplicationScope - Optional string used to scope duplication used in Stateful
+      * implementations
+      * @returns A promise that resolves when processing completes.
+      */
+     trackFlagView(payload: ComponentViewBuilderArgs, duplicationScope?: string): Promise<void>;
+    }
+
+    /**
+     * Options for configuring the {@link CoreBase} runtime and underlying clients.
+     *
+     * @public
+     */
+    export declare interface CoreConfig extends Pick<ApiClientConfig, GlobalApiConfigProperties> {
+        /**
+         * Configuration for the personalization (Experience) API client.
+         */
+        personalization?: Omit<ExperienceApiClientConfig, GlobalApiConfigProperties>;
+        /**
+         * Configuration for the analytics (Insights) API client.
+         */
+        analytics?: Omit<InsightsApiClientConfig, GlobalApiConfigProperties>;
+        /**
+         * Event builder configuration (channel/library metadata, etc.).
+         */
+        eventBuilder?: EventBuilderConfig;
+        /** Minimum log level for the default console sink. */
+        logLevel?: LogLevels;
+    }
+
+    /**
+     * Default values used to preconfigure the stateful core and products.
+     *
+     * @public
+     */
+    export declare interface CoreConfigDefaults {
+        /** Global consent default applied at construction time. */
+        consent?: boolean;
+        /** Default active profile used for personalization and analytics. */
+        profile?: Profile;
+        /** Initial diff of changes produced by the service. */
+        changes?: ChangeArray;
+        /** Preselected personalization variants (e.g., winning treatments). */
+        personalizations?: SelectedPersonalizationArray;
+    }
+
+    /**
+     * Core runtime that constructs stateful product instances and exposes shared
+     * states, including consent and the event stream.
+     *
+     * @public
+     * @remarks
+     * @see {@link CoreBase}
+     * @see {@link ConsentController}
+     */
+    export declare class CoreStateful extends CoreBase implements ConsentController {
+        /** Stateful analytics product. */
+        readonly analytics: AnalyticsStateful;
+        /** Stateful personalization product. */
+        readonly personalization: PersonalizationStateful;
+        /**
+         * Create a stateful core with optional default consent and product defaults.
+         *
+         * @param config - Core and defaults configuration.
+         * @example
+         * ```ts
+         * const core = new CoreStateful({
+         *   clientId: 'app',
+         *   environment: 'prod',
+         *   defaults: { consent: true }
+         * })
+         * core.consent(true)
+         * ```
+         */
+        constructor(config: CoreStatefulConfig);
+        /**
+         * Expose merged observable state for consumers.
+         */
+        get states(): CoreStates;
+        /**
+         * Reset internal state. Consent is intentionally preserved.
+         *
+         * @remarks
+         * Resetting personalization also resets analytics dependencies as a
+         * consequence of the current shared-state design.
+         */
+        reset(): void;
+        /**
+         * Flush the queues for both the analytics and personalization products.
+         * @remarks
+         * The personalization queue is only populated if events have been triggered
+         * while a device is offline.
+         */
+        flush(): Promise<void>;
+        /**
+         * Update consent state
+         *
+         * @param accept - `true` if the user has granted consent; `false` otherwise.
+         */
+        consent(accept: boolean): void;
+        /**
+         * Update online state
+         *
+         * @param isOnline - `true` if the browser is online; `false` otherwise.
+         */
+        protected online(isOnline: boolean): void;
+        /**
+         * Register a preview panel compatible object to receive direct signal access.
+         * This enables the preview panel to modify SDK state for testing and simulation.
+         *
+         * @param previewPanel - An object implementing PreviewPanelSignalObject
+         * @remarks
+         * This method is intended for use by the Preview Panel component.
+         * Direct signal access allows immediate state updates without API calls.
+         */
+        registerPreviewPanel(previewPanel?: PreviewPanelSignalObject): PreviewPanelSignalObject;
+    }
+
+    /**
+     * Configuration for {@link CoreStateful}.
+     *
+     * @public
+     * @see {@link CoreConfig}
+     */
+    export declare interface CoreStatefulConfig extends CoreConfig {
+        /**
+         * Allow-listed event type strings permitted when consent is not set.
+         *
+         * @see {@link ProductConfig.allowedEventTypes}
+         */
+        allowedEventTypes?: ProductConfig['allowedEventTypes'];
+        /** Optional set of default values applied on initialization. */
+        defaults?: CoreConfigDefaults;
+        /** Function used to obtain an anonymous user identifier. */
+        getAnonymousId?: PersonalizationProductConfig['getAnonymousId'];
+        /**
+         * Initial duplication prevention configuration for component events.
+         *
+         * @see {@link ProductConfig.preventedComponentEvents}
+         */
+        preventedComponentEvents?: ProductConfig['preventedComponentEvents'];
+    }
+
+    /**
+     * Core runtime that constructs product instances for stateless environments.
+     *
+     * @public
+     * @see {@link CoreBase}
+     */
+    export declare class CoreStateless extends CoreBase {
+        /** Stateless analytics product. */
+        readonly analytics: AnalyticsStateless;
+        /** Stateless personalization product. */
+        readonly personalization: PersonalizationStateless;
+        /**
+         * Create a stateless core. Product instances share the same API client and
+         * event builder configured in {@link CoreBase}.
+         *
+         * @param config - Stateless Core configuration.
+         * @example
+         * ```ts
+         * const sdk = new CoreStateless({ clientId: 'app', environment: 'prod' })
+         * core.analytics.trackFlagView({ componentId: 'hero' })
+         * // or
+         * core.trackFlagView({ componentId: 'hero' })
+         * ```
+         */
+        constructor(config: CoreStatelessConfig);
+    }
+
+    /**
+     * Configuration for the Node-specific Optimization SDK.
+     *
+     * @public
+     * @remarks
+     * This configuration extends {@link CoreConfig} but allows partial overrides
+     * of the event-builder configuration. SDKs commonly inject their own library
+     * metadata or channel definitions.
+     */
+    export declare interface CoreStatelessConfig extends CoreConfig {
+        /**
+         * Override configuration for the analytics (Insights) API client. Omits
+         * `beaconHandler`.
+         */
+        analytics?: Omit<CoreConfig['analytics'], 'beaconHandler'>;
+        /**
+         * Overrides for the event builder configuration. Omits methods that are only
+         * useful in stateful environments.
+         */
+        eventBuilder?: Omit<EventBuilderConfig, 'getLocale' | 'getPageProperties' | 'getUserAgent'>;
+    }
+
+    /**
+     * Combined observable state exposed by the stateful core.
+     *
+     * @public
+     * @see {@link AnalyticsStates}
+     * @see {@link PersonalizationStates}
+     */
+    export declare interface CoreStates extends AnalyticsStates, PersonalizationStates {
+        /** Current consent value (if any). */
+        consent: Observable<boolean | undefined>;
+        /** Stream of the most recent event emitted (analytics or personalization). */
+        eventStream: Observable<InsightsEvent | ExperienceEvent | undefined>;
+    }
+
+    export declare function createScopedLogger(location: string): ScopedLogger;
+
+    /**
+     * Storage key for the debug flag toggle.
+     *
+     * @internal
+     */
+    export declare const DEBUG_FLAG_KEY = "__ctfl_opt_debug__";
+
+    export { effect }
+
+    declare const event_2: Signal<InsightsEvent | ExperienceEvent | undefined>;
+
+    /**
+     * Union of all event {@link AnalyticsEventType | type keys} that this package may emit.
+     *
+     * @public
+     */
+    declare type EventType = InsightsEventType | ExperienceEventType;
+
+    declare const flags: ReadonlySignal<Flags | undefined>;
+
+    /**
+     * Resolves a {@link Flags} map from a list of optimization changes.
+     *
+     * @public
+     * @remarks
+     * Given an Optimization {@link ChangeArray}, this utility flattens the list into a
+     * simple key–value object suitable for quick lookups in client code. When `changes`
+     * is `undefined`, an empty object is returned. If a change value is wrapped in an
+     * object like `{ value: { ... } }`, this resolver unwraps it to the underlying object.
+     */
+    export declare const FlagsResolver: {
+        /**
+         * Build a flattened map of flag keys to values from a change list.
+         *
+         * @param changes - The change list returned by the optimization service.
+         * @returns A map of flag keys to their resolved values.
+         * @example
+         * ```ts
+         * const flags = FlagsResolver.resolve(data.changes)
+         * if (flags['theme'] === 'dark') enableDarkMode()
+         * ```
+         * @example
+         * // Handles wrapped values produced by the API
+         * ```ts
+         * const flags = FlagsResolver.resolve([
+         *   { type: 'Variable', key: 'price', value: { value: { amount: 10, currency: 'USD' } } }
+         * ])
+         * console.log(flags.price.amount) // 10
+         * ```
+         */
+        resolve(changes?: ChangeArray): Flags;
+    };
+
+    /**
+     * Decorator factory that **guards** class methods behind a synchronous predicate.
+     *
+     * When a decorated method is invoked:
+     * - If the predicate returns a value that evaluates to **allowed** (see `invert`), the original
+     *   method is executed and its result is returned.
+     * - If the call is **blocked**, the optional `onBlocked` hook is invoked (if configured) and:
+     *   - `undefined` is returned for sync methods; or
+     *   - `Promise<undefined>` is returned for async methods (to preserve `await` compatibility).
+     *
+     * @typeParam T - The instance type that owns both the predicate and the decorated method.
+     *
+     * @param predicateName - The name (string or symbol) of a **synchronous** instance method on `this`
+     * that acts as the predicate. It is called as `this[predicateName](methodName, argsArray)`.
+     * @param opts - Optional {@link GuardedByOptions | options} to configure inversion and `onBlocked`.
+     *
+     * @returns A methods-only class decorator compatible with Stage-3 decorators that wraps the method.
+     *
+     * @throws TypeError
+     * Thrown at initialization time (first instance construction) if `predicateName` does not resolve
+     * to a **synchronous function** on the instance.
+     *
+     * @remarks
+     * - This is a **methods-only** decorator; applying it to accessors/fields is a no-op.
+     * - The decorator preserves the original method's sync/async shape.
+     * - The predicate is invoked with `(decoratedMethodName, argsArray)` to support context-aware checks.
+     *
+     * @example
+     * Here, `canRun` allows the call when it returns truthy:
+     * ```ts
+     * class Runner {
+     *   canRun(method: string, _args: readonly unknown[]) { return method !== 'stop'; }
+     *
+     *   @guardedBy<Runner>('canRun')
+     *   go() { console.log('running'); }
+     * }
+     * ```
+     *
+     * @example
+     * Invert the predicate and call a handler on block:
+     * ```ts
+     * class Door {
+     *   isLocked() { return true } // truthy means "locked"
+     *   onBlocked(method: string) { console.warn(`${method} blocked`) }
+     *
+     *   @guardedBy<Door>('isLocked', { invert: true, onBlocked: 'onBlocked' })
+     *   open() { /* ... *\/ }
+     * }
+     * ```
+     *
+     * @public
+     */
+    export declare function guardedBy<T extends object>(predicateName: keyof T & (string | symbol), opts?: GuardedByOptions<T>): GuardedByFunction<T>;
+
+    /**
+     * The original method implementation.
+     *
+     * @typeParam A - The parameter tuple of the original method.
+     * @typeParam R - The return type of the original method.
+     * @param value - The method being decorated.
+     * @param context - The Stage-3 decorator context for a class method.
+     * @returns Nothing.
+     *
+     * @remarks
+     * Users do not call this directly; it's returned by {@link guardedBy}.
+     */
+    declare type GuardedByFunction<T extends object> = <A extends readonly unknown[], R>(value: (...args: A) => R, context: ClassMethodDecoratorContext<T, (...args: A) => R>) => void;
+
+    /**
+     * Options that tweak the behavior of {@link guardedBy}.
+     *
+     * @typeParam T - The instance type on which the decorator is applied.
+     *
+     * @public
+     */
+    declare interface GuardedByOptions<T extends object> {
+        /**
+         * Inverts the predicate result.
+         *
+         * When `true`, a truthy predicate result **blocks** the method.
+         * When `false` (default) or omitted, a truthy predicate result **allows** the method.
+         *
+         * @defaultValue `false`
+         * @remarks
+         * This option is useful when the predicate expresses a *forbid* condition
+         * (e.g. "isLocked" or "isDestroyed") rather than an *allow* condition.
+         */
+        readonly invert?: boolean;
+        /**
+         * Either a function to call when a method is blocked, or the name/symbol of
+         * an instance method on `this` to call when blocked.
+         *
+         * Both forms are **synchronous** and receive `(methodName, argsArray)`.
+         * If omitted, blocked calls fail silently (i.e., return `undefined` or
+         * `Promise<undefined>` for async methods).
+         *
+         * @remarks
+         * - If a property key is supplied and the instance does not have a callable at that key,
+         *   the hook is ignored.
+         * - The hook **must not** be `async`; any async work should be scheduled manually.
+         */
+        readonly onBlocked?: BlockHandler | (keyof T & (string | symbol));
+    }
+
+    /**
+     * A function that receives a value of type `T` and returns a (possibly async)
+     * value of the same type `T`. The input is marked as `readonly` to discourage
+     * mutation of the original object.
+     *
+     * @typeParam T - The value type intercepted and returned.
+     * @param value - The current (readonly) value in the interception chain.
+     * @returns The next value for the chain, either directly or via a promise.
+     * @remarks Implementations SHOULD avoid mutating `value` and instead return a
+     * new or safely-updated instance.
+     * @see {@link InterceptorManager}
+     * @public
+     */
+    export declare type Interceptor<T> = (value: Readonly<T>) => MaybePromise<T>;
+
+    /**
+     * Manages a list of interceptors and provides a way to run them in sequence.
+     *
+     * Interceptors are executed in insertion order. Each interceptor receives the
+     * result of the previous interceptor (or the initial input for the first one)
+     * and may return a new value synchronously or asynchronously.
+     *
+     * @typeParam T - The value type processed by the interceptors.
+     * @remarks This class snapshots the current interceptor list at invocation time
+     * so additions/removals during `run` do not affect the in-flight execution.
+     * @example
+     * ```ts
+     * const mgr = new InterceptorManager<number>();
+     * const id = mgr.add((n) => n + 1);
+     * const final = await mgr.run(1); // 2
+     * mgr.remove(id);
+     * ```
+     * @public
+     */
+    export declare class InterceptorManager<T> {
+        /**
+         * The registry of interceptors keyed by their insertion id.
+         *
+         * @privateRemarks Internal storage; use {@link add}, {@link remove}, and
+         * {@link clear} to manage contents.
+         * @readonly
+         * @defaultValue `new Map()`
+         */
+        private readonly interceptors;
+        /**
+         * The next numeric id to assign to an added interceptor.
+         *
+         * @privateRemarks Used only to generate unique, monotonically increasing ids.
+         * @defaultValue `0`
+         */
+        private nextId;
+        /**
+         * Add an interceptor and return its identifier.
+         *
+         * @param interceptor - The interceptor function to register.
+         * @returns The numeric id that can later be used with {@link remove}.
+         * @remarks Interceptors are executed in the order they are added.
+         * @example
+         * ```ts
+         * const id = manager.add(async (value) => transform(value));
+         * ```
+         * @public
+         */
+        add(interceptor: Interceptor<T>): number;
+        /**
+         * Remove an interceptor by its identifier.
+         *
+         * @param id - The id previously returned by {@link add}.
+         * @returns `true` if an interceptor was removed; otherwise `false`.
+         * @example
+         * ```ts
+         * const removed = manager.remove(id);
+         * ```
+         * @public
+         */
+        remove(id: number): boolean;
+        /**
+         * Remove all registered interceptors.
+         *
+         * @returns Nothing.
+         * @remarks After calling this, {@link count} will return `0`.
+         * @example
+         * ```ts
+         * manager.clear();
+         * ```
+         * @public
+         */
+        clear(): void;
+        /**
+         * Get the number of currently registered interceptors.
+         *
+         * @returns The count of interceptors.
+         * @example
+         * ```ts
+         * if (manager.count() === 0) { /* ... *\/ }
+         * ```
+         * @public
+         */
+        count(): number;
+        /**
+         * Run all interceptors in sequence on an input value and return the final result.
+         *
+         * Supports both sync and async interceptors; the return type is always `Promise<T>`
+         * for consistency.
+         *
+         * @param input - The initial value to pass to the first interceptor.
+         * @returns A promise resolving to the final value after all interceptors have run.
+         * @throws May rethrow any error thrown by an interceptor. <!-- Intentionally vague: error type depends on interceptor implementation -->
+         * @remarks The interceptor list is snapshotted at invocation time; changes to
+         * the registry during execution do not affect the running sequence.
+         * @example
+         * ```ts
+         * const result = await manager.run(initial);
+         * ```
+         * @public
+         */
+        run(input: T): Promise<T>;
+    }
+
+    /**
+     * Lifecycle container for event and state interceptors.
+     *
+     * @public
+     */
+    export declare interface LifecycleInterceptors {
+        /** Interceptors invoked for individual events prior to validation/sending. */
+        event: InterceptorManager<InsightsEvent | ExperienceEvent>;
+        /** Interceptors invoked before optimization state updates. */
+        state: InterceptorManager<OptimizationData>;
+    }
+
+    export { LogEvent }
+
+    export declare class Logger {
+        readonly name = "@contentful/optimization";
+        private readonly PREFIX_PARTS;
+        private readonly DELIMITER;
+        private readonly diary;
+        private sinks;
+        constructor();
+        private assembleLocationPrefix;
+        addSink(sink: LogSink): void;
+        removeSink(name: string): void;
+        removeSinks(): void;
+        debug(logLocation: string, message: string, ...args: unknown[]): void;
+        info(logLocation: string, message: string, ...args: unknown[]): void;
+        log(logLocation: string, message: string, ...args: unknown[]): void;
+        warn(logLocation: string, message: string, ...args: unknown[]): void;
+        error(logLocation: string, message: string | Error, ...args: unknown[]): void;
+        fatal(logLocation: string, message: string | Error, ...args: unknown[]): void;
+        private onLogEvent;
+    }
+
+    export declare const logger: Logger;
+
+    export { LogLevels }
+
+    export declare abstract class LogSink {
+        abstract name: string;
+        abstract ingest(event: LogEvent): void;
+    }
+
+    /**
+     * A utility type representing a value that may be synchronously available or
+     * produced asynchronously.
+     *
+     * @typeParam T - The resolved value type.
+     * @public
+     */
+    declare type MaybePromise<T> = T | Promise<T>;
+
+    /**
+     * Resolves merge tag values from a {@link Profile}.
+     *
+     * @public
+     * @remarks
+     * *Merge tags* are references to user profile data that may be embedded in content
+     * and expanded at runtime. This resolver normalizes the merge-tag identifier into
+     * a set of candidate selectors and searches the profile for a matching value.
+     * Result values are returned as strings; numeric/boolean primitives are stringified.
+     */
+    export declare const MergeTagValueResolver: {
+        /**
+         * Type guard to ensure the input is a {@link MergeTagEntry}.
+         *
+         * @param embeddedEntryNodeTarget - Unknown value to validate.
+         * @returns `true` if the input is a valid merge-tag entry.
+         * @example
+         * ```ts
+         * if (MergeTagValueResolver.isMergeTagEntry(node)) {
+         *   // safe to read fields
+         * }
+         * ```
+         */
+        isMergeTagEntry(embeddedEntryNodeTarget: unknown): embeddedEntryNodeTarget is MergeTagEntry;
+        /**
+         * Generate a list of candidate selectors for a merge-tag ID.
+         *
+         * @param id - Merge-tag identifier (segments separated by `_`).
+         * @returns Array of dot-path selectors to try against a profile.
+         * @example
+         * ```ts
+         * // "profile_name_first" -> [
+         * //   'profile',
+         * //   'profile.name',
+         * //   'profile.name.first'
+         * // ]
+         * const selectors = MergeTagValueResolver.normalizeSelectors('profile_name_first')
+         * ```
+         */
+        normalizeSelectors(id: string): string[];
+        /**
+         * Look up a merge-tag value from a profile using normalized selectors.
+         *
+         * @param id - Merge-tag identifier.
+         * @param profile - Profile from which to resolve the value.
+         * @returns A stringified primitive if found; otherwise `undefined`.
+         * @example
+         * ```ts
+         * const value = MergeTagValueResolver.getValueFromProfile('user_email', profile)
+         * if (value) sendEmailTo(value)
+         * ```
+         * @remarks
+         * Only string/number/boolean primitives are returned; objects/arrays are ignored.
+         */
+        getValueFromProfile(id: string, profile?: Profile): string | undefined;
+        /**
+         * Resolve the display value for a merge-tag entry using the provided profile,
+         * falling back to the entry's configured `nt_fallback` when necessary.
+         *
+         * @param mergeTagEntry - The merge-tag entry to resolve.
+         * @param profile - Optional profile used for lookup.
+         * @returns The resolved string, or `undefined` if the entry is invalid and no
+         * fallback is available.
+         * @example
+         * ```ts
+         * const text = MergeTagValueResolver.resolve(entry, profile)
+         * render(text ?? 'Guest')
+         * ```
+         */
+        resolve(mergeTagEntry: MergeTagEntry | undefined, profile?: Profile): string | undefined;
+    };
+
+    declare interface Observable<T> {
+        subscribe: (next: (v: T) => void) => Subscription;
+    }
+
+    declare const online: Signal<boolean | undefined>;
+
+    export declare const OPTIMIZATION_CORE_SDK_NAME: string;
+
+    export declare const OPTIMIZATION_CORE_SDK_VERSION: string;
+
+    /**
+     * Internal base for personalization products.
+     *
+     * @internal
+     * @remarks
+     * Concrete implementations should extend this class to expose public methods for
+     * identify, page, and track events. This base wires in shared singleton
+     * resolvers used to fetch/resolve personalized data.
+     */
+    declare abstract class PersonalizationBase extends ProductBase implements ResolverMethods {
+        /**
+         * Static {@link FlagsResolver | resolver} for evaluating personalized
+         * custom flags.
+         */
+        readonly flagsResolver: {
+            resolve(changes?: ChangeArray): Flags_2;
+        };
+        /**
+         * Static {@link MergeTagValueResolver | resolver} that returns values
+         * sourced from a user profile based on a Contentful Merge Tag entry.
+         */
+        readonly mergeTagValueResolver: {
+            isMergeTagEntry(embeddedEntryNodeTarget: unknown): embeddedEntryNodeTarget is MergeTagEntry;
+            normalizeSelectors(id: string): string[];
+            getValueFromProfile(id: string, profile?: Profile): string | undefined;
+            resolve(mergeTagEntry: MergeTagEntry | undefined, profile?: Profile): string | undefined;
+        };
+        /**
+         * Static {@link PersonalizedEntryResolver | resolver } for personalized
+         * Contentful entries (e.g., entry variants targeted to a profile audience).
+         *
+         * @remarks
+         * Used by higher-level personalization flows to materialize entry content
+         * prior to event emission.
+         */
+        readonly personalizedEntryResolver: {
+            getPersonalizationEntry({ personalizedEntry, selectedPersonalizations, }: {
+                personalizedEntry: PersonalizedEntry;
+                selectedPersonalizations: SelectedPersonalizationArray;
+            }, skipValidation?: boolean): PersonalizationEntry | undefined;
+            getSelectedPersonalization({ personalizationEntry, selectedPersonalizations, }: {
+                personalizationEntry: PersonalizationEntry;
+                selectedPersonalizations: SelectedPersonalizationArray;
+            }, skipValidation?: boolean): SelectedPersonalization_2 | undefined;
+            getSelectedVariant({ personalizedEntry, personalizationEntry, selectedVariantIndex, }: {
+                personalizedEntry: PersonalizedEntry;
+                personalizationEntry: PersonalizationEntry;
+                selectedVariantIndex: number;
+            }, skipValidation?: boolean): EntryReplacementVariant | undefined;
+            getSelectedVariantEntry<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = string>({ personalizationEntry, selectedVariant, }: {
+                personalizationEntry: PersonalizationEntry;
+                selectedVariant: EntryReplacementVariant;
+            }, skipValidation?: boolean): Entry<S, M, L> | undefined;
+            resolve<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = string>(entry: Entry<S, M, L>, selectedPersonalizations?: SelectedPersonalizationArray): ResolvedData<S, M, L>;
+        };
+        /**
+         * Get the specified Custom Flag's value from the supplied changes.
+         * @param name - The name/key of the Custom Flag.
+         * @param changes - Optional changes array.
+         * @returns The current value of the Custom Flag if found.
+         * @remarks
+         * The changes array can be sourced from the data returned when emitting any
+         * personalization event.
+         * */
+        getCustomFlag(name: string, changes?: ChangeArray): Json;
+        /**
+         * Resolve a Contentful entry to a personalized variant using the current
+         * or provided selected personalizations.
+         *
+         * @typeParam S - Entry skeleton type.
+         * @typeParam M - Chain modifiers.
+         * @typeParam L - Locale code.
+         * @param entry - The entry to personalize.
+         * @param personalizations - Optional selected personalizations.
+         * @returns The resolved entry data.
+         * @remarks
+         * Selected personalizations can be sourced from the data returned when emitting any
+         * personalization event.
+         */
+        personalizeEntry<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = LocaleCode>(entry: Entry<S, M, L>, personalizations?: SelectedPersonalizationArray): ResolvedData<S, M, L>;
+        /**
+         * Resolve a merge tag to a value based on the current (or provided) profile.
+         *
+         * @param embeddedEntryNodeTarget - The merge tag entry node to resolve.
+         * @param profile - Optional profile.
+         * @returns The resolved value (type depends on the tag).
+         * @remarks
+         * Merge tags are references to profile data that can be substituted into content. The
+         * profile can be sourced from the data returned when emitting any personalization event.
+         */
+        getMergeTagValue(embeddedEntryNodeTarget: MergeTagEntry, profile?: Profile): unknown;
+        /**
+         * Identify the current profile/visitor to associate traits with a profile.
+         *
+         * @param payload - Identify builder payload.
+         * @returns The resulting {@link OptimizationData} for the identified user if the device is online.
+         */
+        abstract identify(payload: IdentifyBuilderArgs): Promise<OptimizationData | undefined>;
+        /**
+         * Record a page view.
+         *
+         * @param payload - Page view builder payload.
+         * @returns The evaluated {@link OptimizationData} for this page view if the device is online.
+         */
+        abstract page(payload: PageViewBuilderArgs): Promise<OptimizationData | undefined>;
+        /**
+         * Record a screen view.
+         *
+         * @param payload - Screen view builder payload.
+         * @returns The evaluated {@link OptimizationData} for this screen view if the device is online.
+         */
+        abstract screen(payload: ScreenViewBuilderArgs): Promise<OptimizationData | undefined>;
+        /**
+         * Record a custom track event.
+         *
+         * @param payload - Track builder payload.
+         * @returns The evaluated {@link OptimizationData} for this event if the device is online.
+         */
+        abstract track(payload: TrackBuilderArgs): Promise<OptimizationData | undefined>;
+        /**
+         * Record a "sticky" component view.
+         *
+         * @param payload - "Sticky" component view builder payload.
+         * @returns The evaluated {@link OptimizationData} for this component view if the device is online.
+         * @remarks
+         * This method is intended to be called only when a component is considered
+         * "sticky".
+         * @privateRemarks
+         * Duplication prevention should be handled in Stateful implementations.
+         */
+        abstract trackComponentView(payload: ComponentViewBuilderArgs, duplicationScope?: string): Promise<OptimizationData | undefined>;
+    }
+
+    /**
+     * Configuration for {@link PersonalizationStateful}.
+     *
+     * @public
+     */
+    export declare interface PersonalizationProductConfig extends ProductConfig {
+        /** Default signal values applied during initialization. */
+        defaults?: PersonalizationProductConfigDefaults;
+        /**
+         * Function used to obtain an anonymous user identifier.
+         *
+         * @remarks
+         * If a `getAnonymousId` function has been provided, the returned value will
+         * take precedence over the `id` property of the current {@link Profile}
+         * signal value
+         *
+         * @returns A string identifier, or `undefined` if no anonymous ID is available.
+         */
+        getAnonymousId?: () => string | undefined;
+    }
+
+    /**
+     * Default state values for {@link PersonalizationStateful} applied at construction time.
+     *
+     * @public
+     */
+    export declare interface PersonalizationProductConfigDefaults {
+        /** Whether personalization is allowed by default. */
+        consent?: boolean;
+        /** Initial diff of changes produced by the service. */
+        changes?: ChangeArray;
+        /** Default active profile used for personalization. */
+        profile?: Profile;
+        /** Preselected personalization variants (e.g., winning treatments). */
+        personalizations?: SelectedPersonalizationArray;
+    }
+
+    declare const personalizations: Signal<{
+        experienceId: string;
+        variantIndex: number;
+        variants: Record<string, string>;
+        sticky?: boolean | undefined;
+    }[] | undefined>;
+
+    /**
+     * Storage key for cached selected personalizations.
+     *
+     * @internal
+     */
+    export declare const PERSONALIZATIONS_CACHE_KEY = "__ctfl_opt_personalizations__";
+
+    /**
+     * Stateful personalization product that manages consent, profile, flags, and
+     * selected variants while emitting Experience events and updating state.
+     *
+     * @public
+     * @remarks
+     * The class maintains reactive signals and exposes read‑only observables via
+     * {@link PersonalizationStateful.states}. Events are validated via schema parsers and
+     * run through interceptors before being submitted. Resulting state is merged
+     * back into signals.
+     */
+    export declare class PersonalizationStateful extends PersonalizationBase implements ConsentGuard {
+        /** In‑memory queue for offline events keyed by profile. */
+        private readonly offlineQueue;
+        /** Exposed observable state references. */
+        readonly states: PersonalizationStates;
+        /**
+         * Function that provides an anonymous ID when available.
+         *
+         * @internal
+         */
+        getAnonymousId: () => string | undefined;
+        /**
+         * Create a new stateful personalization instance.
+         *
+         * @param options - Options to configure the personalization product for stateful environments.
+         */
+        constructor(options: PersonalizationStatefulOptions);
+        /**
+         * Reset stateful signals managed by this product.
+         *
+         * @remarks
+         * Clears `changes`, `profile`, and selected `personalizations`.
+         */
+        reset(): void;
+        /**
+         * Get the specified Custom Flag's value (derived from the signal).
+         * @param name - The name or key of the Custom Flag.
+         * @returns The current value of the Custom Flag if found.
+         * */
+        getCustomFlag(name: string, changes?: ChangeArray | undefined): Json;
+        /**
+         * Resolve a Contentful entry to a personalized variant using the current
+         * or provided selections.
+         *
+         * @typeParam S - Entry skeleton type.
+         * @typeParam M - Chain modifiers.
+         * @typeParam L - Locale code.
+         * @param entry - The entry to personalize.
+         * @param personalizations - Optional selections; defaults to the current signal value.
+         * @returns The resolved entry data.
+         */
+        personalizeEntry<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = LocaleCode>(entry: Entry<S, M, L>, personalizations?: SelectedPersonalizationArray | undefined): ResolvedData<S, M, L>;
+        /**
+         * Resolve a merge tag to a value based on the current (or provided) profile.
+         *
+         * @param embeddedEntryNodeTarget - The merge‑tag entry node to resolve.
+         * @param profile - Optional profile; defaults to the current signal value.
+         * @returns The resolved value (type depends on the tag).
+         * @remarks
+         * Merge tags are references to profile data that can be substituted into content.
+         */
+        getMergeTagValue(embeddedEntryNodeTarget: MergeTagEntry, profile?: Profile | undefined): unknown;
+        /**
+         * Determine whether the named operation is permitted based on consent and
+         * allowed event type configuration.
+         *
+         * @param name - Method name; `trackComponentView` is normalized to
+         * `'component'` for allow‑list checks.
+         * @returns `true` if the operation is permitted; otherwise `false`.
+         */
+        hasConsent(name: string): boolean;
+        /**
+         * Hook invoked when an operation is blocked due to missing consent.
+         *
+         * @param name - The blocked operation name.
+         * @param payload - The original arguments supplied to the operation.
+         */
+        onBlockedByConsent(name: string, payload: unknown[]): void;
+        /**
+         * Guard used to suppress duplicate component view events for the same
+         * component based on a duplication key and the component identifier.
+         *
+         * @param _name - Operation name (unused).
+         * @param payload - Tuple `[builderArgs, duplicationScope]`.
+         * @returns `true` if the event is NOT a duplicate and should proceed.
+         */
+        isNotDuplicated(_name: string, payload: [ComponentViewBuilderArgs, string]): boolean;
+        /**
+         * Hook invoked when an operation is blocked by the duplication guard.
+         *
+         * @param _name - The blocked operation name (unused).
+         * @param payload - The original arguments supplied to the operation.
+         */
+        onBlockedByDuplication(_name: string, payload: unknown[]): void;
+        /**
+         * Identify the current profile/visitor to associate traits with a profile
+         * and update optimization state.
+         *
+         * @param payload - Identify builder payload.
+         * @returns The resulting {@link OptimizationData} for the identified user.
+         */
+        identify(payload: IdentifyBuilderArgs): Promise<OptimizationData | undefined>;
+        /**
+         * Record a page view and update optimization state.
+         *
+         * @param payload - Page view builder payload.
+         * @returns The evaluated {@link OptimizationData} for this page view.
+         */
+        page(payload: PageViewBuilderArgs): Promise<OptimizationData | undefined>;
+        /**
+         * Record a screen view and update optimization state.
+         *
+         * @param payload - Screen view builder payload.
+         * @returns The evaluated {@link OptimizationData} for this screen view.
+         */
+        screen(payload: ScreenViewBuilderArgs): Promise<OptimizationData | undefined>;
+        /**
+         * Record a custom track event and update optimization state.
+         *
+         * @param payload - Track builder payload.
+         * @returns The evaluated {@link OptimizationData} for this event.
+         */
+        track(payload: TrackBuilderArgs): Promise<OptimizationData | undefined>;
+        trackComponentView(payload: ComponentViewBuilderArgs, _duplicationScope?: string): Promise<OptimizationData | undefined>;
+        /**
+         * Intercept, validate, and place an event into the offline eventd queue; then
+         * trigger a size‑based flush if necessary.
+         *
+         * @param event - The event to enqueue.
+         */
+        private sendOrEnqueueEvent;
+        /**
+         * Flush the offline queue
+         */
+        flush(): Promise<void>;
+        /**
+         * Submit events to the Experience API, updating output signals with the
+         * returned state.
+         *
+         * @param events - The events to submit.
+         * @returns The {@link OptimizationData} returned by the service.
+         * @internal
+         * @privateRemarks
+         * If a `getAnonymousId` function has been provided, the returned value will
+         * take precedence over the `id` property of the current {@link Profile}
+         * signal value
+         */
+        private upsertProfile;
+        /**
+         * Apply returned optimization state to local signals after interceptor processing.
+         *
+         * @param data - Optimization state returned by the service.
+         * @internal
+         */
+        private updateOutputSignals;
+    }
+
+    /**
+     * Options for configuring {@link PersonalizationStateful} functionality.
+     *
+     * @public
+     * @see {@link ProductBaseOptions}
+     */
+    export declare type PersonalizationStatefulOptions = ProductBaseOptions & {
+        /** Configuration specific to the Personalization product */
+        config?: PersonalizationProductConfig;
+    };
+
+    /**
+     * Stateless personalization implementation that immediately validates and sends
+     * a single event to the Experience API, upserting the profile as needed.
+     *
+     * @public
+     * @remarks
+     * Each public method constructs a strongly-typed event via the shared builder,
+     * runs it through event interceptors, and performs a profile upsert using the
+     * Experience API. If an anonymous ID is available from the builder, it will be
+     * preferred as the `profileId` unless an explicit profile is provided.
+     */
+    export declare class PersonalizationStateless extends PersonalizationBase {
+        /**
+         * Identify the current profile/visitor to associate traits with a profile.
+         *
+         * @param payload - Identify builder arguments with an optional partial
+         * profile to attach to the upsert request.
+         * @returns The resulting {@link OptimizationData} for the identified user.
+         */
+        identify(payload: IdentifyBuilderArgs & {
+            profile?: PartialProfile;
+        }): Promise<OptimizationData>;
+        /**
+         * Record a page view.
+         *
+         * @param payload - Page view builder arguments with an optional partial profile.
+         * @returns The evaluated {@link OptimizationData} for this page view.
+         */
+        page(payload: PageViewBuilderArgs & {
+            profile?: PartialProfile;
+        }): Promise<OptimizationData>;
+        /**
+         * Record a screen view.
+         *
+         * @param payload - Screen view builder arguments with an optional partial profile.
+         * @returns The evaluated {@link OptimizationData} for this screen view.
+         */
+        screen(payload: ScreenViewBuilderArgs & {
+            profile?: PartialProfile;
+        }): Promise<OptimizationData>;
+        /**
+         * Record a custom track event.
+         *
+         * @param payload - Track builder arguments with an optional partial profile.
+         * @returns The evaluated {@link OptimizationData} for this event.
+         */
+        track(payload: TrackBuilderArgs & {
+            profile?: PartialProfile;
+        }): Promise<OptimizationData>;
+        /**
+         * Record a "sticky" component view.
+         *
+         * @param payload - Component view builder arguments with an optional partial profile.
+         * @returns The evaluated {@link OptimizationData} for this component view.
+         */
+        trackComponentView(payload: ComponentViewBuilderArgs & {
+            profile?: PartialProfile;
+        }): Promise<OptimizationData>;
+        /**
+         * Intercept, validate, and upsert the profile with a single personalization
+         * event.
+         *
+         * @param event - The {@link PersonalizationEvent} to submit.
+         * @param profile - Optional partial profile. If omitted, the anonymous ID from
+         * the builder (when present) is used as the `profileId`.
+         * @returns The {@link OptimizationData} returned by the Experience API.
+         * @internal
+         */
+        private upsertProfile;
+    }
+
+    /**
+     * Observables exposed by {@link PersonalizationStateful} that mirror internal signals.
+     *
+     * @public
+     */
+    export declare interface PersonalizationStates {
+        /** Observable stream of the latest {@link AnalyticsEvent} or {@link PersonalizationEvent} (or `undefined`). */
+        eventStream: Observable<InsightsEvent | ExperienceEvent | undefined>;
+        /** Live view of effective flags for the current profile (if available). */
+        flags: Observable<Flags | undefined>;
+        /** Live view of the current profile. */
+        profile: Observable<Profile | undefined>;
+        /** Live view of selected personalizations (variants). */
+        personalizations: Observable<SelectedPersonalizationArray | undefined>;
+    }
+
+    /**
+     * Resolve a personalized Contentful entry to the correct variant for the current
+     * selections.
+     *
+     * @public
+     * @remarks
+     * Given a baseline {@link PersonalizedEntry} and a set of selected personalizations
+     * (variants per experience), this resolver finds the matching replacement variant
+     * for the component configured against the baseline entry.
+     *
+     * **Variant indexing**: `variantIndex` in {@link SelectedPersonalization} is treated as
+     * 1‑based (index 1 = first variant). A value of `0` indicates baseline.
+     */
+    export declare const PersonalizedEntryResolver: {
+        /**
+         * Find the personalization entry corresponding to one of the selected experiences.
+         *
+         * @param params - Object containing the baseline personalized entry and the selections.
+         * @param skipValidation - When `true`, skip type/shape validation for perf.
+         * @returns The matching {@link PersonalizationEntry}, or `undefined` if not found/invalid.
+         * @example
+         * ```ts
+         * const personalizationEntry = PersonalizedEntryResolver.getPersonalizationEntry({
+         *   personalizedEntry: entry,
+         *   selectedPersonalizations
+         * })
+         * ```
+         * @remarks
+         * A personalization entry is a personalization configuration object supplied in a
+         * `PersonalizedEntry.nt_experiences` array. A personalized entry may relate to
+         * multiple personalizations.
+         */
+        getPersonalizationEntry({ personalizedEntry, selectedPersonalizations, }: {
+            personalizedEntry: PersonalizedEntry_2;
+            selectedPersonalizations: SelectedPersonalizationArray;
+        }, skipValidation?: boolean): PersonalizationEntry_2 | undefined;
+        /**
+         * Look up the selection metadata for a specific personalization entry.
+         *
+         * @param params - Object with the target personalization entry and selections.
+         * @param skipValidation - When `true`, skip type checks.
+         * @returns The matching {@link SelectedPersonalization}, if present.
+         * @example
+         * ```ts
+         * const selectedPersonalization = PersonalizedEntryResolver.getSelectedPersonalization({
+         *   personalizationEntry,
+         *   selectedPersonalizations
+         * })
+         * ```
+         * @remarks
+         * Selected personalizations are supplied by the Experience API in the
+         * `experiences` response data property.
+         */
+        getSelectedPersonalization({ personalizationEntry, selectedPersonalizations, }: {
+            personalizationEntry: PersonalizationEntry_2;
+            selectedPersonalizations: SelectedPersonalizationArray;
+        }, skipValidation?: boolean): SelectedPersonalization | undefined;
+        /**
+         * Get the replacement variant config for the given selection index.
+         *
+         * @param params - Baseline entry, personalization entry, and 1‑based variant index.
+         * @param skipValidation - When `true`, skip type checks.
+         * @returns The {@link EntryReplacementVariant} for the component, if any.
+         * @example
+         * ```ts
+         * const selectedVariant = PersonalizedEntryResolver.getSelectedVariant({
+         *   personalizedEntry: entry,
+         *   personalizationEntry,
+         *   selectedVariantIndex: 2 // second variant (1‑based)
+         * })
+         * ```
+         * @remarks
+         * Entry replacement variants are variant configurations specified in a
+         * personalization configuration component's `variants` array supplied by the
+         * personalized entry via its `nt_config` field.
+         */
+        getSelectedVariant({ personalizedEntry, personalizationEntry, selectedVariantIndex, }: {
+            personalizedEntry: PersonalizedEntry_2;
+            personalizationEntry: PersonalizationEntry_2;
+            selectedVariantIndex: number;
+        }, skipValidation?: boolean): EntryReplacementVariant_2 | undefined;
+        /**
+         * Resolve the concrete Contentful entry that corresponds to a selected variant.
+         *
+         * @typeParam S - Entry skeleton type.
+         * @typeParam M - Chain modifiers.
+         * @typeParam L - Locale code.
+         * @param params - Personalization entry and selected variant.
+         * @param skipValidation - When `true`, skip type checks.
+         * @returns The resolved entry typed as {@link Entry} or `undefined`.
+         * @example
+         * ```ts
+         * const selectedVariantEntry = PersonalizedEntryResolver.getSelectedVariantEntry<{ fields: unknown }>({
+         *   personalizationEntry,
+         *   selectedVariant
+         * })
+         * ```
+         * @remarks
+         * A personalized entry will resolve either to the baseline (the entry
+         * supplied as `personalizedEntry`) or the selected variant.
+         */
+        getSelectedVariantEntry<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = string>({ personalizationEntry, selectedVariant, }: {
+            personalizationEntry: PersonalizationEntry_2;
+            selectedVariant: EntryReplacementVariant_2;
+        }, skipValidation?: boolean): Entry<S, M, L> | undefined;
+        /**
+         * Resolve the selected entry (baseline or variant) for a personalized entry
+         * and optional selected personalizations, returning both the entry and the
+         * personalization metadata.
+         *
+         * @typeParam S - Entry skeleton type.
+         * @typeParam M - Chain modifiers.
+         * @typeParam L - Locale code.
+         * @param entry - The baseline personalized entry.
+         * @param selectedPersonalizations - Optional selections for the current profile.
+         * @returns An object containing the resolved entry and (if chosen) the selection.
+         * @example
+         * ```ts
+         * const { entry: personalizedEntry, personalization } = PersonalizedEntryResolver.resolve(entry, selections)
+         * if (personalization) console.log('Variant index', personalization.variantIndex)
+         * ```
+         */
+        resolve<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = string>(entry: Entry<S, M, L>, selectedPersonalizations?: SelectedPersonalizationArray): ResolvedData<S, M, L>;
+    };
+
+    /**
+     * Interface for objects that can be registered with the preview panel system.
+     * When registered, the object receives direct access to SDK signals for state manipulation.
+     *
+     * @public
+     */
+    export declare interface PreviewPanelSignalObject {
+        /** Signals instance that will be populated by registerPreviewPanel */
+        signals: Signals | null | undefined;
+        /** Signal functions that can be used across micro-frontend barriers */
+        signalFns: SignalFns | null | undefined;
+    }
+
+    /**
+     * Shared base for all product implementations.
+     *
+     * @internal
+     * @remarks
+     * This abstract class is not exported as part of the public API surface.
+     * Concrete implementations (e.g., analytics) should extend this class and
+     * expose their own public methods.
+     */
+    declare abstract class ProductBase {
+        /**
+         * Allow‑list of event {@link AnalyticsEventType | type keys} permitted when consent is not present.
+         */
+        protected readonly allowedEventTypes?: string[];
+        /** Event builder used to construct strongly‑typed events. */
+        protected readonly builder: EventBuilder;
+        /** Optimization API client used to send events to the Experience and Insights APIs. */
+        protected readonly api: ApiClient;
+        /**
+         * Deduplication helper used to track previously seen values within optional
+         * scopes
+         */
+        readonly duplicationDetector: ValuePresence;
+        /** Interceptors that can mutate/augment outgoing events or optimization state. */
+        readonly interceptors: LifecycleInterceptors;
+        /**
+         * Creates a new product base instance.
+         *
+         * @param options - Options for configuring the functionality common among products.
+         */
+        constructor(options: ProductBaseOptions);
+    }
+
+    /**
+     * Options for configuring the common functionality of {@link ProductBase} descendents.
+     *
+     * @public
+     */
+    declare interface ProductBaseOptions {
+        /** Optimization API client. */
+        api: ApiClient;
+        /** Event builder for constructing events. */
+        builder: EventBuilder;
+        /** Optional configuration for allow‑lists and duplication prevention. */
+        config?: ProductConfig;
+        /** Lifecycle container for event and state interceptors. */
+        interceptors: LifecycleInterceptors;
+    }
+
+    /**
+     * Common configuration for all product implementations.
+     *
+     * @public
+     */
+    declare interface ProductConfig {
+        /**
+         * The set of event type strings that are allowed to be sent even if consent is
+         * not granted.
+         *
+         * @defaultValue `['page', 'identify']`
+         * @remarks These types are compared against the `type` property of events.
+         */
+        allowedEventTypes?: EventType[];
+        /**
+         * A map of duplication keys to a list of component IDs that should be
+         * considered duplicates and therefore suppressed.
+         *
+         * @remarks
+         * The actual duplication check is performed by {@link ValuePresence}. The
+         * keys of this record are used as duplication scopes. An empty string `''`
+         * is converted to an `indefined` scope when specific scopes are not required.
+         */
+        preventedComponentEvents?: Record<string, string[]>;
+    }
+
+    declare const profile: Signal<Profile | undefined>;
+
+    /**
+     * Storage key for cached profile data.
+     *
+     * @internal
+     */
+    export declare const PROFILE_CACHE_KEY = "__ctfl_opt_profile__";
+
+    /**
+     * Result returned by {@link PersonalizedEntryResolver.resolve}.
+     *
+     * @typeParam S - Entry skeleton type.
+     * @typeParam M - Chain modifiers.
+     * @typeParam L - Locale code.
+     * @public
+     */
+    export declare interface ResolvedData<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = LocaleCode> {
+        /** The baseline or resolved variant entry. */
+        entry: Entry<S, M, L>;
+        /** The selected personalization metadata, if a non‑baseline variant was chosen. */
+        personalization?: SelectedPersonalization;
+    }
+
+    /**
+     * These methods assist in resolving values via Resolvers
+     *
+     * @internal
+     * @privateRemarks
+     * This interface exists to document that the included methods should not be
+     * considered static.
+     */
+    declare interface ResolverMethods {
+        /**
+         * Get the specified Custom Flag's value from the supplied changes.
+         * @param name - The name or key of the Custom Flag.
+         * @param changes - Optional changes array.
+         * @returns The current value of the Custom Flag if found.
+         * @remarks
+         * The changes array can be sourced from the data returned when emitting any
+         * personalization event.
+         * */
+        getCustomFlag: (name: string, changes?: ChangeArray) => Json;
+        /**
+         * Resolve a Contentful entry to a personalized variant using the current
+         * or provided selected personalizations.
+         *
+         * @typeParam S - Entry skeleton type.
+         * @typeParam M - Chain modifiers.
+         * @typeParam L - Locale code.
+         * @param entry - The entry to personalize.
+         * @param personalizations - Optional selections.
+         * @returns The resolved entry data.
+         * @remarks
+         * Selected personalizations can be sourced from the data returned when emitting any
+         * personalization event.
+         */
+        personalizeEntry: <S extends EntrySkeletonType, M extends ChainModifiers, L extends LocaleCode>(entry: Entry<S, M, L>, personalizations?: SelectedPersonalizationArray) => ResolvedData<S, M, L>;
+        /**
+         * Resolve a merge tag to a value based on the current (or provided) profile.
+         *
+         * @param embeddedEntryNodeTarget - The merge‑tag entry node to resolve.
+         * @param profile - Optional profile.
+         * @returns The resolved value (type depends on the tag).
+         * @remarks
+         * Merge tags are references to profile data that can be substituted into content. The
+         * profile can be sourced from the data returned when emitting any personalization event.
+         */
+        getMergeTagValue: (embeddedEntryNodeTarget: MergeTagEntry, profile?: Profile) => unknown;
+    }
+
+    export declare interface ScopedLogger {
+        debug: (message: string, ...args: unknown[]) => void;
+        info: (message: string, ...args: unknown[]) => void;
+        log: (message: string, ...args: unknown[]) => void;
+        warn: (message: string, ...args: unknown[]) => void;
+        error: (message: string | Error, ...args: unknown[]) => void;
+        fatal: (message: string | Error, ...args: unknown[]) => void;
+    }
+
+    export { Signal }
+
+    export declare interface SignalFns {
+        batch: typeof batch;
+        computed: typeof computed;
+        effect: typeof effect;
+        untracked: typeof untracked;
+    }
+
+    export declare const signalFns: SignalFns;
+
+    export declare interface Signals {
+        changes: typeof changes;
+        consent: typeof consent;
+        event: typeof event_2;
+        flags: typeof flags;
+        online: typeof online;
+        personalizations: typeof personalizations;
+        profile: typeof profile;
+    }
+
+    export declare const signals: Signals;
+
+    declare interface Subscription {
+        unsubscribe: () => void;
+    }
+
+    /**
+     * Arguments for tracking a component/flag view in stateless mode.
+     *
+     * @public
+     * @remarks
+     * The `profile` is optional; when omitted, the APIs may infer identity via
+     * other means.
+     */
+    export declare type TrackViewArgs = ComponentViewBuilderArgs & {
+        profile?: PartialProfile;
+    };
+
+    /**
+     * Tracks whether a given value is present within one or more logical scopes.
+     *
+     * @remarks
+     * - Scope names are case-sensitive.
+     * - Presence is based on `Set.has` reference equality for objects and
+     *   value equality for primitives.
+     *
+     * @example
+     * ```ts
+     * const presence = new ValuePresence({ default: ['a', 'b'] })
+     * presence.isPresent('default', 'a') // true
+     * presence.addValue('default', 'c')
+     * presence.removeValue('default', 'b')
+     * presence.reset('default')
+     * ```
+     *
+     * @see {@link ValuePresenceScope}
+     * @public
+     */
+    export declare class ValuePresence {
+        #private;
+        /**
+         * Create a new {@link ValuePresence}.
+         *
+         * @param defaultMap - Optional initial data. Keys are scope names; values are arrays of items to seed.
+         * Empty-string keys are normalized to the default scope (`undefined`).
+         *
+         * @remarks
+         * - If `defaultMap` contains duplicate items for a scope, duplicates are collapsed by the `Set`.
+         */
+        constructor(defaultMap?: Record<string, unknown[]>);
+        /**
+         * Check whether a value is present within a given scope.
+         *
+         * @param scope - The scope to check. Use `undefined` for the default scope.
+         * @param value - The value to test for presence.
+         * @returns `true` if the value is present in the specified scope; otherwise `false`.
+         *
+         * @remarks
+         * Presence testing uses `Set.prototype.has` semantics.
+         *
+         * @example
+         * ```ts
+         * presence.isPresent(undefined, 42) // e.g., true or false
+         * ```
+         *
+         * @public
+         */
+        isPresent(scope: ValuePresenceScope, value: unknown): boolean;
+        /**
+         * Add a value to a scope, creating the scope if it does not exist.
+         *
+         * @param scope - Scope to add the value to. Use `undefined` for the default scope.
+         * @param value - The value to add.
+         * @returns void
+         *
+         * @remarks
+         * - No-op if the value is already present (due to `Set` semantics).
+         *
+         * @example
+         * ```ts
+         * presence.addValue('users', userId)
+         * ```
+         *
+         * @public
+         */
+        addValue(scope: ValuePresenceScope, value: unknown): void;
+        /**
+         * Remove a value from a scope.
+         *
+         * @param scope - Scope to remove from. Use `undefined` for the default scope.
+         * @param value - The value to remove.
+         * @returns void
+         *
+         * @remarks
+         * If the scope does not exist or the value is not present, this is a no-op.
+         *
+         * @example
+         * ```ts
+         * presence.removeValue('users', userId)
+         * ```
+         *
+         * @public
+         */
+        removeValue(scope: ValuePresenceScope, value: unknown): void;
+        /**
+         * Clear values from a single scope, or from all scopes.
+         *
+         * @param scope - If provided, clears only that scope. If omitted, clears all scopes.
+         * @returns void
+         *
+         * @remarks
+         * - When called with a specific scope that does not exist, this is a no-op.
+         * - When called with no arguments, all scopes and values are removed.
+         * - Clearing a non-existent scope will not create the scope.
+         *
+         * @example
+         * ```ts
+         * // Clear one scope
+         * presence.reset('users')
+         *
+         * // Clear all scopes
+         * presence.reset()
+         * ```
+         *
+         * @public
+         */
+        reset(scope?: ValuePresenceScope): void;
+    }
+
+    /**
+     * A scope identifier for grouping values.
+     *
+     * @remarks
+     * Use a non-empty string for a named scope. Use `undefined` for the
+     * "global/default" scope. An empty string (`""`) passed to the constructor
+     * initializer is normalized to `undefined`.
+     *
+     * @public
+     */
+    declare type ValuePresenceScope = string | undefined;
+
+
+    export * from "@contentful/optimization-api-client";
+
+    export { }