@contentful/optimization-core 0.1.0-alpha10 → 0.1.0-alpha12

package/README.md

@@ -1,17 +1,17 @@
 <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-alpha12/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-alpha12/CONTRIBUTING.md)
 
 </div>
 
@@ -31,22 +31,23 @@ 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)
-    - [`trackComponentClick`](#trackcomponentclick)
+    - [`trackView`](#trackview)
+    - [`trackClick`](#trackclick)
+    - [`trackHover`](#trackhover)
     - [`trackFlagView`](#trackflagview)
 - [Stateful-only Core Methods](#stateful-only-core-methods)
   - [`consent`](#consent)
@@ -54,7 +55,7 @@ other SDKs descend from the Core SDK.
   - [`flush`](#flush)
   - [`destroy`](#destroy)
   - [`registerPreviewPanel` (preview tooling only)](#registerpreviewpanel-preview-tooling-only)
-- [Stateful-only Core Properties](#stateful-only-core-properties)
+- [Core States (`CoreStateful` only)](#core-states-corestateful-only)
 - [Interceptors](#interceptors)
   - [Life-cycle Interceptors](#life-cycle-interceptors)
 
@@ -81,9 +82,11 @@ 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 requestOptions = { locale: 'de-DE' }
+
+await statelessOptimization.page({}, requestOptions)
 ```
 
 ## Working with Stateless Core
@@ -96,6 +99,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-scoped Experience options in `CoreStateless` are passed as the final argument to each
+stateless event method.
+
 ## Working with Stateful Core
 
 The `CoreStateful` class is intended to be used as the basis for SDKs that would run in stateful
@@ -114,15 +120,14 @@ exposed externally as read-only observables.
 
 ### 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 Optimization API key                                     |
-| `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               |
-| `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:
 
@@ -132,32 +137,48 @@ The following configuration options apply only in stateful environments:
 | `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 |
-| `queuePolicy`   | No        | See method signatures | Queue flush retry/backoff/circuit policy for stateful analytics          |
+| 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`
-- `queuePolicy`:
 
-  ```ts
-  {
+In stateless environments, pass `ip`, `locale`, `plainText`, and `preflight` as the final argument
+to stateless event methods 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,
@@ -166,29 +187,42 @@ Configuration method signatures:
     onFlushFailure?: (context: QueueFlushFailureContext) => void,
     onCircuitOpen?: (context: QueueFlushFailureContext) => void,
     onFlushRecovered?: (context: QueueFlushRecoveredContext) => void
-  }
-  ```
+  },
+  offlineMaxEvents?: number,
+  onOfflineDrop?: (context: ExperienceQueueDropContext) => void
+}
+```
 
-  Supporting callback payloads:
+Supporting callback payloads:
 
-  ```ts
-  type QueueFlushFailureContext = {
-    consecutiveFailures: number
-    queuedBatches: number
-    queuedEvents: number
-    retryDelayMs: number
-  }
+```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
+}
+```
 
-  type QueueFlushRecoveredContext = {
-    consecutiveFailures: number
-  }
-  ```
+Notes:
 
-  Notes:
-  - 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.
+- `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
 
@@ -236,7 +270,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.
 
@@ -258,75 +292,9 @@ Configuration method signatures:
 >
 > 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
-> and Insights API expectations; do not broaden retry status handling without an explicit API
+> API and Insights API expectations; do not broaden retry status handling without an explicit API
 > contract change.
 
-### 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 |
-
-The following configuration options apply only in stateful environments:
-
-| Option        | Required? | Default               | Description                                                                 |
-| ------------- | --------- | --------------------- | --------------------------------------------------------------------------- |
-| `queuePolicy` | No        | See method signatures | Queue and flush-retry policy for stateful personalization offline buffering |
-
-Configuration method signatures:
-
-- `queuePolicy`:
-
-  ```ts
-  {
-    maxEvents?: number,
-    onDrop?: (context: PersonalizationOfflineQueueDropContext) => void,
-    flushPolicy?: {
-      baseBackoffMs?: number,
-      maxBackoffMs?: number,
-      jitterRatio?: number,
-      maxConsecutiveFailures?: number,
-      circuitOpenMs?: number,
-      onFlushFailure?: (context: QueueFlushFailureContext) => void,
-      onCircuitOpen?: (context: QueueFlushFailureContext) => void,
-      onFlushRecovered?: (context: QueueFlushRecoveredContext) => void
-    }
-  }
-  ```
-
-  Supporting callback payloads:
-
-  ```ts
-  type PersonalizationOfflineQueueDropContext = {
-    droppedCount: number
-    droppedEvents: ExperienceEventArray
-    maxEvents: number
-    queuedEvents: number
-  }
-
-  type QueueFlushFailureContext = {
-    consecutiveFailures: number
-    queuedBatches: number
-    queuedEvents: number
-    retryDelayMs: number
-  }
-
-  type QueueFlushRecoveredContext = {
-    consecutiveFailures: number
-  }
-  ```
-
-  Notes:
-  - Default `maxEvents` is `100`.
-  - If the queue is full while offline, oldest events are dropped first.
-  - `onDrop` is best-effort; callback errors are swallowed.
-  - `flushPolicy` uses the same normalization semantics as `analytics.queuePolicy`.
-
 ## Core Methods
 
 The methods in this section are available in both stateful and stateless Core classes. However, be
@@ -335,9 +303,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.
@@ -351,15 +319,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:
 
@@ -369,18 +345,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`
 
@@ -398,7 +374,21 @@ 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
+
+In `CoreStateful`, call these methods on the root instance. In `CoreStateless`, call them on the
+root instance and pass request-scoped Experience options as the final argument when needed:
+
+```ts
+const requestOptions = {
+  locale: 'de-DE',
+}
+
+await optimization.page({ ...requestContext, profile }, requestOptions)
+```
+
+Request-scoped Experience options stay separate from the event payload. Event context data belongs
+in `payload`, while `ip`, `locale`, `plainText`, and `preflight` belong in `requestOptions`.
 
 Only the following methods may return an `OptimizationData` object:
 
@@ -406,15 +396,20 @@ Only the following methods may return an `OptimizationData` object:
 - `page`
 - `screen`
 - `track`
-- `trackComponentView` (when `payload.sticky` is `true`)
+- `trackView` (when `payload.sticky` is `true`)
 
-`trackComponentClick` and `trackFlagView` return no data. When returned, `OptimizationData`
+`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.
@@ -423,48 +418,55 @@ Arguments:
 
 - `payload`\*: Identify event builder arguments object, including an optional `profile` property
   with a `PartialProfile` value that requires only an `id`
+- `requestOptions`: Optional request-scoped Experience API options passed as the final argument
 
 #### `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`
+- `requestOptions`: Optional request-scoped Experience API options passed as the final argument
 
 #### `screen`
 
-Record a personalization screen view.
+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`
+- `requestOptions`: Optional request-scoped Experience API options passed as the final argument
 
 #### `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`
+- `requestOptions`: Optional request-scoped Experience API options passed as the final argument
 
-#### `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`
+- `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`
+- `requestOptions`: Optional request-scoped Experience API options passed as the final argument.
+  Only used when `payload.sticky` is `true`
 
-#### `trackComponentClick`
+#### `trackClick`
 
-Record an analytics component click event.
+Record an Insights API entry click event.
 
 Returns:
 
@@ -472,11 +474,29 @@ Returns:
 
 Arguments:
 
-- `payload`\*: Component click event builder arguments object
+- `payload`\*: Entry click event builder arguments object, including a required `profile` property
+  with a `PartialProfile` value that requires only an `id`
+- `requestOptions`: Optional request-scoped Experience API options accepted for signature
+  consistency; currently unused
+
+#### `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`
+- `requestOptions`: Optional request-scoped Experience API options accepted for signature
+  consistency; currently unused
 
 #### `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:
@@ -485,7 +505,10 @@ Returns:
 
 Arguments:
 
-- `payload`\*: Component view event builder arguments object
+- `payload`\*: Flag view event builder arguments object, including a required `profile` property
+  with a `PartialProfile` value that requires only an `id`
+- `requestOptions`: Optional request-scoped Experience API options accepted for signature
+  consistency; currently unused
 
 ## Stateful-only Core Methods
 
@@ -503,8 +526,8 @@ Resets all internal state _except_ consent. This method expects no arguments and
 
 ### `flush`
 
-Flushes queued analytics and personalization events. This method expects no arguments and returns a
-`Promise<void>`.
+Flushes queued Insights API and Experience API events. This method expects no arguments and returns
+a `Promise<void>`.
 
 ### `destroy`
 
@@ -552,25 +575,67 @@ const signalFns = previewBridge[PREVIEW_PANEL_SIGNAL_FNS_SYMBOL]
 > interceptors) to apply immediate local overrides without network round-trips. This coupling is
 > deliberate and necessary for preview functionality.
 
-## Stateful-only Core Properties
+## 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
+
+`current` and callback payloads are deep-cloned snapshots, so local mutations do not affect Core's
+internal signal state.
+
+Update behavior:
 
-- `states`: Returns an object mapping of observables for all internal states
-  - `consent`: The current state of user consent
-  - `blockedEventStream`: The latest blocked event payload
-  - `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
+- `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()`.
 
-The `blockedEventStream` state is updated whenever a call is blocked by consent guards. Each state
-except `consent`, `eventStream`, and `blockedEventStream` is updated internally whenever a response
-from the Experience API contains a new or updated respective state.
+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

@@ -1,4 +1,4 @@
-const OPTIMIZATION_CORE_SDK_VERSION = "0.1.0-alpha10";
+const OPTIMIZATION_CORE_SDK_VERSION = "0.1.0-alpha12";
 const OPTIMIZATION_CORE_SDK_NAME = "@contentful/optimization-core";
 const ANONYMOUS_ID_COOKIE = 'ctfl-opt-aid';
 const ANONYMOUS_ID_KEY = '__ctfl_opt_anonymous_id__';
@@ -6,9 +6,9 @@ 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 PERSONALIZATIONS_CACHE_KEY = '__ctfl_opt_personalizations__';
+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, PERSONALIZATIONS_CACHE_KEY, PROFILE_CACHE_KEY };
+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