@contentful/optimization-core 0.1.0-alpha → 0.1.0-alpha11

package/README.md

@@ -1,23 +1,23 @@
 <p align="center">
   <a href="https://www.contentful.com/developers/docs/personalization/">
-    <img alt="Contentful Logo" title="Contentful" src="../../contentful-icon.png" width="150">
+    <img alt="Contentful Logo" title="Contentful" src="https://raw.githubusercontent.com/contentful/optimization/v0.1.0-alpha11/contentful-icon.png" width="150">
   </a>
 </p>
 
-<h1 align="center">Contentful Personalization & Analytics</h1>
+<h1 align="center">Contentful Optimization Core SDK</h1>
 
 <h3 align="center">Optimization Core SDK</h3>
 
 <div align="center">
 
-[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
-[Contributing](/CONTRIBUTING.md)
+[Guides](https://contentful.github.io/optimization/documents/Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](https://github.com/contentful/optimization/blob/v0.1.0-alpha11/CONTRIBUTING.md)
 
 </div>
 
 > [!WARNING]
 >
-> The Optimization SDK Suite is currently ALPHA! Breaking changes may be published at any time.
+> The Optimization SDK Suite is pre-release (alpha). Breaking changes may be published at any time.
 
 The Optimization Core SDK encapsulates all platform-agnostic functionality and business logic. All
 other SDKs descend from the Core SDK.
@@ -31,25 +31,31 @@ other SDKs descend from the Core SDK.
 - [Working with Stateful Core](#working-with-stateful-core)
 - [Configuration](#configuration)
   - [Top-level Configuration Options](#top-level-configuration-options)
-  - [Analytics Options](#analytics-options)
+  - [API Options](#api-options)
   - [Event Builder Options](#event-builder-options)
   - [Fetch Options](#fetch-options)
-  - [Personalization Options](#personalization-options)
+  - [Queue Policy Options](#queue-policy-options)
 - [Core Methods](#core-methods)
-  - [Personalization Data Resolution Methods](#personalization-data-resolution-methods)
-    - [`getCustomFlag`](#getcustomflag)
-    - [`personalizeEntry`](#personalizeentry)
+  - [Optimization Data Resolution Methods](#optimization-data-resolution-methods)
+    - [`getFlag`](#getflag)
+    - [`resolveOptimizedEntry`](#resolveoptimizedentry)
     - [`getMergeTagValue`](#getmergetagvalue)
-  - [Personalization and Analytics Event Methods](#personalization-and-analytics-event-methods)
+  - [Event Methods](#event-methods)
     - [`identify`](#identify)
     - [`page`](#page)
+    - [`screen`](#screen)
     - [`track`](#track)
-    - [`trackComponentView`](#trackcomponentview)
+    - [`trackView`](#trackview)
+    - [`trackClick`](#trackclick)
+    - [`trackHover`](#trackhover)
     - [`trackFlagView`](#trackflagview)
 - [Stateful-only Core Methods](#stateful-only-core-methods)
   - [`consent`](#consent)
   - [`reset`](#reset)
-- [Stateful-only Core Properties](#stateful-only-core-properties)
+  - [`flush`](#flush)
+  - [`destroy`](#destroy)
+  - [`registerPreviewPanel` (preview tooling only)](#registerpreviewpanel-preview-tooling-only)
+- [Core States (`CoreStateful` only)](#core-states-corestateful-only)
 - [Interceptors](#interceptors)
   - [Life-cycle Interceptors](#life-cycle-interceptors)
 
@@ -76,9 +82,9 @@ import { CoreStateless } from '@contentful/optimization-core'
 Configure and initialize the Core SDK:
 
 ```ts
-const optimization = new CoreStateful({ clientId: 'abc123' })
-// or
-const optimization = new CoreStateless({ clientId: 'abc123' })
+const statefulOptimization = new CoreStateful({ clientId: 'abc123' })
+const statelessOptimization = new CoreStateless({ clientId: 'abc123' })
+const requestOptimization = statelessOptimization.forRequest()
 ```
 
 ## Working with Stateless Core
@@ -91,6 +97,9 @@ In stateless environments, Core will not maintain any internal state, which incl
 These concerns should be handled by consumers to fit their specific architectural and design
 specifications.
 
+Request-emitting methods in `CoreStateless` are bound per request via
+`optimization.forRequest(...)`.
+
 ## Working with Stateful Core
 
 The `CoreStateful` class is intended to be used as the basis for SDKs that would run in stateful
@@ -100,49 +109,119 @@ In stateful environments, Core maintains state internally for consent, an event
 profile-related data that is commonly obtained from requests to the Experience API. These states are
 exposed externally as read-only observables.
 
+> [!IMPORTANT]
+>
+> `CoreStateful` uses module-global state by design. Initialize exactly one stateful instance per
+> JavaScript runtime and reuse it.
+
 ## Configuration
 
 ### Top-level Configuration Options
 
-| Option            | Required? | Default                       | Description                                                           |
-| ----------------- | --------- | ----------------------------- | --------------------------------------------------------------------- |
-| `analytics`       | No        | See "Analytics Options"       | Configuration specific to the Analytics/Insights API                  |
-| `clientId`        | Yes       | N/A                           | The Ninetailed API Key which can be found in the Ninetailed Admin app |
-| `environment`     | No        | `'main'`                      | The Ninetailed environment configured in the Ninetailed Admin app     |
-| `eventBuilder`    | No        | See "Event Builder Options"   | Event builder configuration (channel/library metadata, etc.)          |
-| `fetchOptions`    | No        | See "Fetch Options"           | Configuration for Fetch timeout and retry functionality               |
-| `logLevel`        | No        | `'error'`                     | Minimum log level for the default console sin                         |
-| `personalization` | No        | See "Personalization Options" | Configuration specific to the Personalization/Experience API          |
+| Option         | Required? | Default                     | Description                                                             |
+| -------------- | --------- | --------------------------- | ----------------------------------------------------------------------- |
+| `api`          | No        | See "API Options"           | Unified configuration for the Experience API and Insights API endpoints |
+| `clientId`     | Yes       | N/A                         | Shared API key for Experience API and Insights API requests             |
+| `environment`  | No        | `'main'`                    | The environment identifier                                              |
+| `eventBuilder` | No        | See "Event Builder Options" | Event builder configuration (channel/library metadata, etc.)            |
+| `fetchOptions` | No        | See "Fetch Options"         | Configuration for Fetch timeout and retry functionality                 |
+| `logLevel`     | No        | `'error'`                   | Minimum log level for the default console sink                          |
 
 The following configuration options apply only in stateful environments:
 
-| Option                     | Required? | Default                | Description                                                       |
-| -------------------------- | --------- | ---------------------- | ----------------------------------------------------------------- |
-| `allowedEventTypes`        | No        | `['identify', 'page']` | Allow-listed event types permitted when consent is not set        |
-| `defaults`                 | No        | `undefined`            | Set of default state values applied on initialization             |
-| `getAnonymousId`           | No        | `undefined`            | Function used to obtain an anonymous user identifier              |
-| `preventedComponentEvents` | No        | `undefined`            | Initial duplication prevention configuration for component events |
+| Option              | Required? | Default                          | Description                                                |
+| ------------------- | --------- | -------------------------------- | ---------------------------------------------------------- |
+| `allowedEventTypes` | No        | `['identify', 'page', 'screen']` | Allow-listed event types permitted when consent is not set |
+| `defaults`          | No        | `undefined`                      | Set of default state values applied on initialization      |
+| `getAnonymousId`    | No        | `undefined`                      | Function used to obtain an anonymous user identifier       |
+| `onEventBlocked`    | No        | `undefined`                      | Callback invoked when an event call is blocked by guards   |
+| `queuePolicy`       | No        | See "Queue Policy Options"       | Shared queue and retry configuration for stateful delivery |
 
 Configuration method signatures:
 
 - `getAnonymousId`: `() => string | undefined`
+- `onEventBlocked`: `(event: BlockedEvent) => void`
 
-### Analytics Options
+### API Options
 
-| Option    | Required? | Default                                    | Description                   |
-| --------- | --------- | ------------------------------------------ | ----------------------------- |
-| `baseUrl` | No        | `'https://ingest.insights.ninetailed.co/'` | Base URL for the Insights API |
+| Option              | Required? | Default                                    | Description                                                  |
+| ------------------- | --------- | ------------------------------------------ | ------------------------------------------------------------ |
+| `experienceBaseUrl` | No        | `'https://experience.ninetailed.co/'`      | Base URL for the Experience API                              |
+| `insightsBaseUrl`   | No        | `'https://ingest.insights.ninetailed.co/'` | Base URL for the Insights API                                |
+| `enabledFeatures`   | No        | `['ip-enrichment', 'location']`            | Enabled features the Experience API may use for each request |
 
-The following configuration options apply only in stateful environments:
+The following configuration option applies only in stateful environments:
 
-| Option          | Required? | Default     | Description                                                              |
-| --------------- | --------- | ----------- | ------------------------------------------------------------------------ |
-| `beaconHandler` | No        | `undefined` | Handler used to enqueue events via the Beacon API or a similar mechanism |
+| Option          | Required? | Default     | Description                                                                    |
+| --------------- | --------- | ----------- | ------------------------------------------------------------------------------ |
+| `beaconHandler` | No        | `undefined` | Handler used to enqueue Insights API events via the Beacon API or equivalent   |
+| `ip`            | No        | `undefined` | IP address override used by the Experience API for location analysis           |
+| `locale`        | No        | `'en-US'`   | Locale used to translate `location.city` and `location.country`                |
+| `plainText`     | No        | `false`     | Sends performance-critical Experience API endpoints in plain text              |
+| `preflight`     | No        | `false`     | Instructs the Experience API to aggregate a new profile state but not store it |
 
 Configuration method signatures:
 
 - `beaconHandler`: `(url: string | URL, data: BatchInsightsEventArray) => boolean`
 
+In stateless environments, bind `ip`, `locale`, `plainText`, and `preflight` per request with
+`optimization.forRequest(...)` instead of constructor config.
+
+### Queue Policy Options
+
+`queuePolicy` is available only in `CoreStateful` and combines shared flush retry settings with
+Experience API offline buffering controls.
+
+Configuration shape:
+
+```ts
+{
+  flush?: {
+    baseBackoffMs?: number,
+    maxBackoffMs?: number,
+    jitterRatio?: number,
+    maxConsecutiveFailures?: number,
+    circuitOpenMs?: number,
+    onFlushFailure?: (context: QueueFlushFailureContext) => void,
+    onCircuitOpen?: (context: QueueFlushFailureContext) => void,
+    onFlushRecovered?: (context: QueueFlushRecoveredContext) => void
+  },
+  offlineMaxEvents?: number,
+  onOfflineDrop?: (context: ExperienceQueueDropContext) => void
+}
+```
+
+Supporting callback payloads:
+
+```ts
+type ExperienceQueueDropContext = {
+  droppedCount: number
+  droppedEvents: ExperienceEventArray
+  maxEvents: number
+  queuedEvents: number
+}
+
+type QueueFlushFailureContext = {
+  consecutiveFailures: number
+  queuedBatches: number
+  queuedEvents: number
+  retryDelayMs: number
+}
+
+type QueueFlushRecoveredContext = {
+  consecutiveFailures: number
+}
+```
+
+Notes:
+
+- `flush` applies the same retry/backoff/circuit policy to both Insights API flushing and Experience
+  API offline replay.
+- Invalid numeric values fall back to defaults.
+- `jitterRatio` is clamped to `[0, 1]`.
+- `maxBackoffMs` is normalized to be at least `baseBackoffMs`.
+- Failed flush attempts include both `false` responses and thrown send errors.
+
 ### Event Builder Options
 
 Event builder options should only be supplied when building an SDK on top of Core or any of its
@@ -189,7 +268,7 @@ Configuration method signatures:
 ### Fetch Options
 
 Fetch options allow for configuration of a Fetch API-compatible fetch method and the retry/timeout
-logic integrated into the Optimization API Client. Specify the `fetchMethod` when the host
+logic integrated into the SDK's bundled API clients. Specify the `fetchMethod` when the host
 application environment does not offer a `fetch` method that is compatible with the standard Fetch
 API in its global scope.
 
@@ -207,16 +286,12 @@ Configuration method signatures:
 - `fetchMethod`: `(url: string | URL, init: RequestInit) => Promise<Response>`
 - `onFailedAttempt` and `onRequestTimeout`: `(options: FetchMethodCallbackOptions) => void`
 
-### Personalization Options
-
-| Option            | Required? | Default                               | Description                                                         |
-| ----------------- | --------- | ------------------------------------- | ------------------------------------------------------------------- |
-| `baseUrl`         | No        | `'https://experience.ninetailed.co/'` | Base URL for the Experience API                                     |
-| `enabledFeatures` | No        | `['ip-enrichment', 'location']`       | Enabled features which the API may use for each request             |
-| `ip`              | No        | `undefined`                           | IP address to override the API behavior for IP analysis             |
-| `locale`          | No        | `'en-US'` (in API)                    | Locale used to translate `location.city` and `location.country`     |
-| `plainText`       | No        | `false`                               | Sends performance-critical endpoints in plain text                  |
-| `preflight`       | No        | `false`                               | Instructs the API to aggregate a new profile state but not store it |
+> [!NOTE]
+>
+> Core inherits the API Client retry contract: default retries intentionally apply only to HTTP
+> `503` responses (`Service Unavailable`). This is deliberate and aligned with current Experience
+> API and Insights API expectations; do not broaden retry status handling without an explicit API
+> contract change.
 
 ## Core Methods
 
@@ -226,9 +301,9 @@ implementations.
 
 Arguments marked with an asterisk (\*) are always required.
 
-### Personalization Data Resolution Methods
+### Optimization Data Resolution Methods
 
-#### `getCustomFlag`
+#### `getFlag`
 
 Get the specified Custom Flag's value from the provided changes array, or from the current internal
 state in stateful implementations.
@@ -242,15 +317,23 @@ Returns:
 
 - The resolved value for the specified Custom Flag, or `undefined` if it cannot be found.
 
+Behavior notes:
+
+- In `CoreStateful`, calling `getFlag(...)` automatically emits a flag view event via
+  `trackFlagView`.
+- In `CoreStateless`, `getFlag(...)` does not auto-emit a flag view event.
+- If full map resolution is needed for advanced use cases, use
+  `optimization.flagsResolver.resolve(changes)`.
+
 > [!NOTE]
 >
 > If the `changes` argument is omitted in stateless implementations, the method will return
 > `undefined`.
 
-#### `personalizeEntry`
+#### `resolveOptimizedEntry`
 
-Resolve a baseline Contentful entry to a personalized variant using the provided selected
-personalizations, or from the current internal state in stateful implementations.
+Resolve a baseline Contentful entry to an optimized variant using the provided selected
+optimizations, or from the current internal state in stateful implementations.
 
 Type arguments:
 
@@ -260,18 +343,18 @@ Type arguments:
 
 Arguments:
 
-- `entry`\*: The entry to personalize
-- `personalizations`: Selected personalizations
+- `entry`\*: The baseline entry to resolve
+- `selectedOptimizations`: Selected optimizations
 
 Returns:
 
-- The resolved personalized entry variant, or the supplied baseline entry if baseline is the
-  selected variant or a variant cannot be found.
+- The resolved optimized entry variant, or the supplied baseline entry if baseline is the selected
+  variant or a variant cannot be found.
 
 > [!NOTE]
 >
-> If the `personalizations` argument is omitted in stateless implementations, the method will return
-> the baseline entry.
+> If the `selectedOptimizations` argument is omitted in stateless implementations, the method will
+> return the baseline entry.
 
 #### `getMergeTagValue`
 
@@ -289,14 +372,37 @@ Arguments:
 > If the `profile` argument is omitted in stateless implementations, the method will return the
 > merge tag's fallback value.
 
-### Personalization and Analytics Event Methods
+### Event Methods
 
-Each method except `trackFlagView` may return an `OptimizationData` object containing:
+In `CoreStateful`, call these methods on the root instance. In `CoreStateless`, call them on the
+request scope returned by `optimization.forRequest(...)`:
+
+```ts
+const requestOptimization = optimization.forRequest({
+  locale: 'de-DE',
+})
+```
+
+Only the following methods may return an `OptimizationData` object:
+
+- `identify`
+- `page`
+- `screen`
+- `track`
+- `trackView` (when `payload.sticky` is `true`)
+
+`trackClick`, `trackHover`, and `trackFlagView` return no data. When returned, `OptimizationData`
+contains:
 
 - `changes`: Currently used for Custom Flags
-- `personalizations`: Selected personalizations for the profile
+- `selectedOptimizations`: Selected optimizations for the profile
 - `profile`: Profile associated with the evaluated events
 
+In stateless runtimes, Insights-backed methods require a profile for delivery. Non-sticky
+`trackView`, `trackClick`, `trackHover`, and `trackFlagView` require `payload.profile.id`. Sticky
+`trackView` may omit `profile`, because the returned Experience profile is reused for the paired
+Insights event.
+
 #### `identify`
 
 Identify the current profile/visitor to associate traits with a profile.
@@ -308,46 +414,82 @@ Arguments:
 
 #### `page`
 
-Record a personalization page view.
+Record an Experience API page view.
 
 Arguments:
 
 - `payload`\*: Page view event builder arguments object, including an optional `profile` property
   with a `PartialProfile` value that requires only an `id`
 
+#### `screen`
+
+Record an Experience API screen view.
+
+Arguments:
+
+- `payload`\*: Screen view event builder arguments object, including an optional `profile` property
+  with a `PartialProfile` value that requires only an `id`
+
 #### `track`
 
-Record a personalization custom track event.
+Record an Experience API custom track event.
 
 Arguments:
 
 - `payload`\*: Track event builder arguments object, including an optional `profile` property with a
   `PartialProfile` value that requires only an `id`
 
-#### `trackComponentView`
+#### `trackView`
 
-Record an analytics component view event. When the payload marks the component as "sticky", an
-additional personalization component view is recorded. This method only returns `OptimizationData`
-when the component is marked as "sticky".
+Record an Insights API entry view event. When the payload marks the entry as "sticky", an additional
+Experience API entry view is recorded. This method only returns `OptimizationData` when the entry is
+marked as "sticky".
 
 Arguments:
 
-- `payload`\*: Component view event builder arguments object, including an optional `profile`
-  property with a `PartialProfile` value that requires only an `id`
-- `duplicationScope`: Arbitrary string that may be used to scope component view duplication; used in
-  Stateful implementations
+- `payload`\*: Entry view event builder arguments object. When `payload.sticky` is `true`, `profile`
+  is optional and the returned Experience profile is reused for Insights delivery. Otherwise,
+  `profile` is required and must contain at least an `id`
+
+#### `trackClick`
+
+Record an Insights API entry click event.
+
+Returns:
+
+- `void`
+
+Arguments:
+
+- `payload`\*: Entry click event builder arguments object, including a required `profile` property
+  with a `PartialProfile` value that requires only an `id`
+
+#### `trackHover`
+
+Record an Insights API entry hover event.
+
+Returns:
+
+- `void`
+
+Arguments:
+
+- `payload`\*: Entry hover event builder arguments object, including a required `profile` property
+  with a `PartialProfile` value that requires only an `id`
 
 #### `trackFlagView`
 
-Track a feature flag view via analytics. This is functionally the same as a non-sticky component
+Track a feature flag view via the Insights API. This is functionally the same as a non-sticky flag
 view event.
 
+Returns:
+
+- `void`
+
 Arguments:
 
-- `payload`\*: Component view event builder arguments object, including an optional `profile`
-  property with a `PartialProfile` value that requires only an `id`
-- `duplicationScope`: Arbitrary string that may be used to scope component view duplication; used in
-  Stateful implementations
+- `payload`\*: Flag view event builder arguments object, including a required `profile` property
+  with a `PartialProfile` value that requires only an `id`
 
 ## Stateful-only Core Methods
 
@@ -357,30 +499,124 @@ Updates the user consent state.
 
 Arguments:
 
-- `accept`: A boolean value specifying whether the user has accepted (`true`) or denied (`false`). A
-  value of `undefined` implies that the user has not yet explicitly chosen whether to consent.
+- `accept`: A boolean value specifying whether the user has accepted (`true`) or denied (`false`)
 
 ### `reset`
 
 Resets all internal state _except_ consent. This method expects no arguments and returns no value.
 
-## Stateful-only Core Properties
+### `flush`
+
+Flushes queued Insights API and Experience API events. This method expects no arguments and returns
+a `Promise<void>`.
+
+### `destroy`
+
+Releases singleton ownership for stateful runtime usage. This is intended for explicit teardown
+paths, such as tests or hot-reload workflows. This method expects no arguments and returns no value.
+
+### `registerPreviewPanel` (preview tooling only)
+
+Registers a preview consumer object and exposes internal signal references used by first-party
+preview tooling.
+
+Arguments:
+
+- `previewPanel`: Required object that receives symbol-keyed signal bridge values
+
+Returns:
+
+- `void`
+
+Bridge symbols:
+
+- `PREVIEW_PANEL_SIGNALS_SYMBOL`: key used to expose internal `signals`
+- `PREVIEW_PANEL_SIGNAL_FNS_SYMBOL`: key used to expose internal `signalFns`
+
+Example:
 
-- `states`: Returns an object mapping of observables for all internal states
-  - `consent`: The current state of user consent
-  - `eventStream`: The latest event to be queued
-  - `flags`: All current resolved Custom Flags
-  - `profile`: The current user profile
-  - `personalizations`: The current collection of selected personalizations
+```ts
+import {
+  PREVIEW_PANEL_SIGNAL_FNS_SYMBOL,
+  PREVIEW_PANEL_SIGNALS_SYMBOL,
+  type PreviewPanelSignalObject,
+} from '@contentful/optimization-core'
+
+const previewBridge: PreviewPanelSignalObject = {}
+optimization.registerPreviewPanel(previewBridge)
+
+const signals = previewBridge[PREVIEW_PANEL_SIGNALS_SYMBOL]
+const signalFns = previewBridge[PREVIEW_PANEL_SIGNAL_FNS_SYMBOL]
+```
+
+> [!IMPORTANT]
+>
+> This method intentionally exposes mutable internal signals for preview tooling. The Web and React
+> Native preview panels are tightly coupled by design and rely on this bridge (plus state
+> interceptors) to apply immediate local overrides without network round-trips. This coupling is
+> deliberate and necessary for preview functionality.
+
+## Core States (`CoreStateful` only)
+
+`states` is available on `CoreStateful` and exposes signal-backed observables for runtime state.
+
+Available state streams:
+
+- `consent`: Current consent state (`boolean | undefined`)
+- `blockedEventStream`: Latest blocked-call metadata (`BlockedEvent | undefined`)
+- `eventStream`: Latest emitted Insights API or Experience API event
+  (`InsightsEvent | ExperienceEvent | undefined`)
+- `flag(name)`: Key-scoped flag observable (`Observable<Json>`)
+- `canOptimize`: Whether optimization selections are available (`boolean`;
+  `selectedOptimizations !== undefined`)
+- `profile`: Current profile (`Profile | undefined`)
+- `selectedOptimizations`: Current selected optimizations (`SelectedOptimizationArray | undefined`)
+- `previewPanelAttached`: Preview panel attachment state (`boolean`)
+- `previewPanelOpen`: Preview panel open state (`boolean`)
+
+Each observable provides:
+
+- `current`: Deep-cloned snapshot of the latest value
+- `subscribe(next)`: Immediately emits `current`, then emits future updates
+- `subscribeOnce(next)`: Emits the first non-nullish value, then auto-unsubscribes
 
-Each state except `consent` and `eventStream` is updated internally whenever a response from the
-Experience API contains a new or updated respective state.
+`current` and callback payloads are deep-cloned snapshots, so local mutations do not affect Core's
+internal signal state.
+
+Update behavior:
+
+- `blockedEventStream` updates whenever a call is blocked by consent guards.
+- `eventStream` updates when a valid event is accepted for send/queue.
+- `flag(name)` updates when the resolved value for that key changes.
+- `canOptimize` updates whenever `selectedOptimizations` becomes defined or `undefined`.
+- `consent` updates from defaults and `optimization.consent(...)`.
+- `previewPanelAttached` and `previewPanelOpen` are controlled by preview tooling and are preserved
+  across `reset()`.
+
+Example: read the latest snapshot synchronously:
+
+```ts
+const profile = optimization.states.profile.current
+if (profile) console.log(`Current profile: ${profile.id}`)
+```
+
+Example: subscribe and clean up:
+
+```ts
+const sub = optimization.states.profile.subscribe((profile) => {
+  if (!profile) return
+  console.log(`Profile ${profile.id} updated`)
+})
+
+// later (component unmount / teardown)
+sub.unsubscribe()
+```
 
-Example `states` observable usage:
+Example: wait for first available profile:
 
 ```ts
-optimization.states.profile.subscribe((profile) => {
-  console.log(`Profile ${profile.id} updated!`)
+optimization.states.profile.subscribeOnce((profile) => {
+  console.log(`Profile ${profile.id} loaded`)
 })
 ```
 

package/dist/160.mjs

@@ -0,0 +1,3 @@
+import * as __rspack_external__contentful_optimization_api_client_api_schemas_4192893e from "@contentful/optimization-api-client/api-schemas";
+var PartialProfile = __rspack_external__contentful_optimization_api_client_api_schemas_4192893e.PartialProfile;
+export { PartialProfile, __rspack_external__contentful_optimization_api_client_api_schemas_4192893e };

package/dist/260.mjs

@@ -0,0 +1,14 @@
+const OPTIMIZATION_CORE_SDK_VERSION = "0.1.0-alpha11";
+const OPTIMIZATION_CORE_SDK_NAME = "@contentful/optimization-core";
+const ANONYMOUS_ID_COOKIE = 'ctfl-opt-aid';
+const ANONYMOUS_ID_KEY = '__ctfl_opt_anonymous_id__';
+const CONSENT_KEY = '__ctfl_opt_consent__';
+const CHANGES_CACHE_KEY = '__ctfl_opt_changes__';
+const DEBUG_FLAG_KEY = '__ctfl_opt_debug__';
+const PROFILE_CACHE_KEY = '__ctfl_opt_profile__';
+const SELECTED_OPTIMIZATIONS_CACHE_KEY = '__ctfl_opt_selected-optimizations__';
+const ANONYMOUS_ID_COOKIE_LEGACY = 'ntaid';
+const ANONYMOUS_ID_KEY_LEGACY = '__nt_anonymous_id__';
+export { ANONYMOUS_ID_COOKIE, ANONYMOUS_ID_COOKIE_LEGACY, ANONYMOUS_ID_KEY, ANONYMOUS_ID_KEY_LEGACY, CHANGES_CACHE_KEY, CONSENT_KEY, DEBUG_FLAG_KEY, OPTIMIZATION_CORE_SDK_NAME, OPTIMIZATION_CORE_SDK_VERSION, PROFILE_CACHE_KEY, SELECTED_OPTIMIZATIONS_CACHE_KEY };
+
+//# sourceMappingURL=260.mjs.map

package/dist/260.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"260.mjs","sources":["../src/constants.ts"],"sourcesContent":["// eslint-disable-next-line @typescript-eslint/naming-convention -- Replaced at build-time\ndeclare const __OPTIMIZATION_VERSION__: string | undefined\n// eslint-disable-next-line @typescript-eslint/naming-convention -- Replaced at build-time\ndeclare const __OPTIMIZATION_PACKAGE_NAME__: string | undefined\n\n/**\n * The current version of the Optimization Core SDK, injected at build time.\n *\n * @public\n */\nexport const OPTIMIZATION_CORE_SDK_VERSION =\n  typeof __OPTIMIZATION_VERSION__ === 'string' ? __OPTIMIZATION_VERSION__ : '0.0.0'\n/**\n * The package name of the Optimization Core SDK, injected at build time.\n *\n * @public\n */\nexport const OPTIMIZATION_CORE_SDK_NAME =\n  typeof __OPTIMIZATION_PACKAGE_NAME__ === 'string'\n    ? __OPTIMIZATION_PACKAGE_NAME__\n    : '@contentful/optimization-core'\n\n/**\n * Anonymous-ID cookie name used by the Optimization Core.\n *\n * @public\n * @remarks\n * This constant represents the cookie key used by the Optimization Framework\n * to persist an anonymous identifier for tracking optimization and insights\n * events when no explicit profile is known.\n *\n * @example\n * ```ts\n * import { ANONYMOUS_ID_COOKIE } from '@contentful/optimization-core/constants'\n * const profileId = request.cookies[ANONYMOUS_ID_COOKIE]\n * ```\n */\nexport const ANONYMOUS_ID_COOKIE = 'ctfl-opt-aid'\n\n/**\n * Storage key for the anonymous identifier.\n *\n * @internal\n */\nexport const ANONYMOUS_ID_KEY = '__ctfl_opt_anonymous_id__'\n\n/**\n * Storage key for the persisted consent status.\n *\n * @internal\n */\nexport const CONSENT_KEY = '__ctfl_opt_consent__'\n\n/**\n * Storage key for cached Custom Flags.\n *\n * @internal\n */\nexport const CHANGES_CACHE_KEY = '__ctfl_opt_changes__'\n\n/**\n * Storage key for the debug flag toggle.\n *\n * @internal\n */\nexport const DEBUG_FLAG_KEY = '__ctfl_opt_debug__'\n\n/**\n * Storage key for cached profile data.\n *\n * @internal\n */\nexport const PROFILE_CACHE_KEY = '__ctfl_opt_profile__'\n\n/**\n * Storage key for cached selected optimizations.\n *\n * @internal\n */\nexport const SELECTED_OPTIMIZATIONS_CACHE_KEY = '__ctfl_opt_selected-optimizations__'\n\n/**\n * Legacy anoynmous ID cookie key for migration from experience.js\n *\n * @internal\n */\nexport const ANONYMOUS_ID_COOKIE_LEGACY = 'ntaid'\n\n/**\n * Legacy anoynmous ID storage key for migration from experience.js\n *\n * @internal\n */\nexport const ANONYMOUS_ID_KEY_LEGACY = '__nt_anonymous_id__'\n"],"names":["OPTIMIZATION_CORE_SDK_VERSION","__OPTIMIZATION_VERSION__","OPTIMIZATION_CORE_SDK_NAME","__OPTIMIZATION_PACKAGE_NAME__","ANONYMOUS_ID_COOKIE","ANONYMOUS_ID_KEY","CONSENT_KEY","CHANGES_CACHE_KEY","DEBUG_FLAG_KEY","PROFILE_CACHE_KEY","SELECTED_OPTIMIZATIONS_CACHE_KEY","ANONYMOUS_ID_COOKIE_LEGACY","ANONYMOUS_ID_KEY_LEGACY"],"mappings":"AAUO,MAAMA,gCACoCC;AAM1C,MAAMC,6BAEPC;AAkBC,MAAMC,sBAAsB;AAO5B,MAAMC,mBAAmB;AAOzB,MAAMC,cAAc;AAOpB,MAAMC,oBAAoB;AAO1B,MAAMC,iBAAiB;AAOvB,MAAMC,oBAAoB;AAO1B,MAAMC,mCAAmC;AAOzC,MAAMC,6BAA6B;AAOnC,MAAMC,0BAA0B"}

package/dist/499.mjs

@@ -0,0 +1,4 @@
+import * as __rspack_external__contentful_optimization_api_client_logger_f0d05f82 from "@contentful/optimization-api-client/logger";
+var default_0 = __rspack_external__contentful_optimization_api_client_logger_f0d05f82["default"];
+export default default_0;
+export { __rspack_external__contentful_optimization_api_client_logger_f0d05f82 };

package/dist/632.mjs

@@ -0,0 +1,5 @@
+const PREVIEW_PANEL_SIGNALS_SYMBOL = Symbol.for('ctfl.optimization.preview.signals');
+const PREVIEW_PANEL_SIGNAL_FNS_SYMBOL = Symbol.for('ctfl.optimization.preview.signalFns');
+export { PREVIEW_PANEL_SIGNALS_SYMBOL, PREVIEW_PANEL_SIGNAL_FNS_SYMBOL };
+
+//# sourceMappingURL=632.mjs.map

package/dist/632.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"632.mjs","sources":["../src/symbols.ts"],"sourcesContent":["/**\n * Well-known symbols used by the preview panel bridge.\n *\n * @public\n */\nexport const PREVIEW_PANEL_SIGNALS_SYMBOL = Symbol.for('ctfl.optimization.preview.signals')\nexport const PREVIEW_PANEL_SIGNAL_FNS_SYMBOL = Symbol.for('ctfl.optimization.preview.signalFns')\n"],"names":["PREVIEW_PANEL_SIGNALS_SYMBOL","Symbol","PREVIEW_PANEL_SIGNAL_FNS_SYMBOL"],"mappings":"AAKO,MAAMA,+BAA+BC,OAAO,GAAG,CAAC;AAChD,MAAMC,kCAAkCD,OAAO,GAAG,CAAC"}

package/dist/942.mjs

@@ -0,0 +1,2 @@
+import * as __rspack_external__contentful_optimization_api_client_cba5a7ee from "@contentful/optimization-api-client";
+export { __rspack_external__contentful_optimization_api_client_cba5a7ee };