@contentful/optimization-node 0.1.0-alpha14 → 0.1.0-alpha15

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <a href="https://www.contentful.com/developers/docs/personalization/">
-    <img alt="Contentful Logo" title="Contentful" src="https://raw.githubusercontent.com/contentful/optimization/v0.1.0-alpha14/contentful-icon.png" width="150">
+    <img alt="Contentful Logo" title="Contentful" src="https://raw.githubusercontent.com/contentful/optimization/v0.1.0-alpha15/contentful-icon.png" width="150">
   </a>
 </p>
 
@@ -11,7 +11,7 @@
 <div align="center">
 
 [Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
-[Reference](https://contentful.github.io/optimization) · [Contributing](https://github.com/contentful/optimization/blob/v0.1.0-alpha14/CONTRIBUTING.md)
+[Reference](https://contentful.github.io/optimization) · [Contributing](https://github.com/contentful/optimization/blob/v0.1.0-alpha15/CONTRIBUTING.md)
 
 </div>
 
@@ -20,7 +20,7 @@
 > The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time.
 
 The Optimization Node SDK implements stateless server-side optimization behavior on top of the
-[Optimization Core SDK](https://github.com/contentful/optimization/blob/v0.1.0-alpha14/packages/universal/core-sdk/README.md). Use it for server rendering, server
+[Optimization Core SDK](https://github.com/contentful/optimization/blob/v0.1.0-alpha15/packages/universal/core-sdk/README.md). Use it for server rendering, server
 functions, and Node services that need request-scoped profile evaluation or event emission.
 
 If you are integrating a Node application, start with [Getting Started](#getting-started), then use
@@ -66,9 +66,7 @@ Create the SDK once per module or process, then bind consent and request context
 const optimization = new ContentfulOptimization({
   clientId: 'your-client-id',
   environment: 'main',
-  contentfulLocales: {
-    default: 'en-US',
-  },
+  locale: 'en-US',
 })
 
 function appPolicyAllowsOptimizationEvent(req: { cookies?: Record<string, string> }): boolean {
@@ -79,18 +77,20 @@ async function renderRequest(
   req: { cookies?: Record<string, string>; headers: { 'accept-language'?: string } },
   profileId: string,
 ) {
-  const { contentfulLocale, eventLocale } = optimization.resolveRequestLocale(req)
+  const appLocale = getAppLocale(req)
   const requestOptimization = optimization.forRequest({
     consent: {
       events: appPolicyAllowsOptimizationEvent(req),
       persistence: appPolicyAllowsOptimizationEvent(req),
     },
-    eventContext: { locale: eventLocale },
-    experienceOptions: contentfulLocale ? { locale: contentfulLocale } : undefined,
+    locale: appLocale,
+    eventContext: { locale: appLocale },
     profile: { id: profileId },
   })
 
-  return await requestOptimization.page()
+  const { accepted, data } = await requestOptimization.page()
+
+  return accepted ? data : undefined
 }
 ```
 
@@ -105,7 +105,7 @@ are part of the same application.
 
 The Node SDK is stateless. It does not maintain consent, profile, or browser persistence state
 between requests. For cross-SDK consent guidance, see
-[Consent management in the Optimization SDK Suite](https://github.com/contentful/optimization/blob/v0.1.0-alpha14/documentation/concepts/consent-management-in-the-optimization-sdk-suite.md).
+[Consent management in the Optimization SDK Suite](https://github.com/contentful/optimization/blob/v0.1.0-alpha15/documentation/concepts/consent-management-in-the-optimization-sdk-suite.md).
 
 | Option              | Required? | Default                | Description                                                 |
 | ------------------- | --------- | ---------------------- | ----------------------------------------------------------- |
@@ -113,7 +113,7 @@ between requests. For cross-SDK consent guidance, see
 | `environment`       | No        | `'main'`               | Contentful environment identifier                           |
 | `api`               | No        | See API options below  | Experience API and Insights API endpoint options            |
 | `app`               | No        | `undefined`            | Application metadata attached to outgoing event context     |
-| `contentfulLocales` | No        | `undefined`            | Contentful locale codes used by `resolveRequestLocale()`    |
+| `locale`            | No        | `undefined`            | Default SDK Experience API and event locale                 |
 | `fetchOptions`      | No        | SDK defaults           | Fetch timeout and retry behavior                            |
 | `allowedEventTypes` | No        | `['identify', 'page']` | Event types allowed before request event consent is granted |
 | `eventBuilder`      | No        | Node SDK defaults      | Event metadata overrides for SDK-layer authors              |
@@ -137,30 +137,26 @@ client:
 | `plainText` | Sends performance-critical Experience API endpoints as text   |
 | `preflight` | Aggregates a new profile state without storing it             |
 
+Request-scoped Insights options belong in `insightsOptions`:
+
+| Option          | Description                                         |
+| --------------- | --------------------------------------------------- |
+| `beaconHandler` | Custom handler for enqueueing Insights API batches. |
+
+Use the request-scoped top-level `locale` on `forRequest()` as the promoted path for localized
+Experience API responses and default event context. `experienceOptions.locale` remains available as
+an advanced low-level pass-through when `locale` is not supplied. If both are provided, request
+`locale` wins.
+
 Common `fetchOptions` are `fetchMethod`, `requestTimeout`, `retries`, `intervalTimeout`,
 `onFailedAttempt`, and `onRequestTimeout`. Default retries intentionally apply only to HTTP `503`
 responses.
 
-Use `contentfulLocales.default` for single-locale apps. For apps that match request locale input to
-multiple Contentful locales, keep `default` as the fallback and list the supported Contentful locale
-codes:
-
-```ts
-const optimization = new ContentfulOptimization({
-  clientId: 'your-client-id',
-  contentfulLocales: {
-    default: 'en-US',
-    supported: ['en-US', 'de-DE', 'fr-FR'],
-  },
-})
-```
-
-Copy `contentfulLocales.default` and optional `contentfulLocales.supported` from Contentful locale
-settings or the CMA locale list. The returned `contentfulLocale`, when present, is the configured
-Contentful locale code to use for CDA fetches and the Experience API request option. Use
-`eventLocale` separately in event context. Merge tags that reference localized profile fields such
-as `location.city` and `location.country` then resolve in a language consistent with the rendered
-content. See
+Choose the application Contentful locale in your router, i18n layer, or request policy. Pass that
+value directly to Contentful CDA requests, and pass the same value to
+`forRequest({ locale: appLocale })` when Experience API responses and event context should use the
+same language. Merge tags that reference localized profile fields such as `location.city` and
+`location.country` then resolve in a language consistent with the rendered content. See
 [Locale handling in the Optimization SDK Suite](https://contentful.github.io/optimization/documents/Documentation.Concepts.Locale_handling_in_the_Optimization_SDK_Suite.html)
 for the full locale model.
 
@@ -179,23 +175,23 @@ the returned request object:
 import type { Request } from 'express'
 
 app.get('/products/:slug', async (req, res) => {
-  const { contentfulLocale, eventLocale } = optimization.resolveRequestLocale(req)
+  const appLocale = getAppLocale(req)
   const requestOptimization = optimization.forRequest({
     consent: {
       events: appPolicyAllowsOptimizationEvent(req),
       persistence: appPolicyAllowsOptimizationEvent(req),
     },
+    locale: appLocale,
     eventContext: {
-      locale: eventLocale,
+      locale: appLocale,
     },
-    experienceOptions: contentfulLocale ? { locale: contentfulLocale } : undefined,
     profile: { id: req.cookies.profileId },
   })
-  const optimizationData = await requestOptimization.page({
+  const { accepted, data: optimizationData } = await requestOptimization.page({
     properties: { path: req.path },
   })
 
-  if (requestOptimization.canPersistProfile && optimizationData?.profile.id) {
+  if (accepted && requestOptimization.canPersistProfile && optimizationData?.profile.id) {
     persistProfileId(res, optimizationData.profile.id)
   }
 
@@ -209,7 +205,8 @@ request-specific consent lookup with accepted consent:
 ```ts
 const requestOptimization = optimization.forRequest({
   consent: { events: true, persistence: true },
-  eventContext: { locale: eventLocale },
+  locale: appLocale,
+  eventContext: { locale: appLocale },
   profile,
 })
 ```
@@ -235,13 +232,12 @@ const resolvedEntry = optimization.resolveOptimizedEntry(
 )
 ```
 
-Fetch entries with one CDA locale in the app layer. For localized apps, configure
-`contentfulLocales`, then use the `contentfulLocale` returned by `resolveRequestLocale()` for CDA
-fetches and the per-call `{ locale }` request option so MergeTags that read localized profile fields
-match the entry language. When `contentfulLocale` is absent because no `contentfulLocales` config is
-present, omit the CDA and Experience API locale options intentionally. Do not pass all-locale CDA
-responses from `withAllLocales` or `locale=*` into `resolveOptimizedEntry()`; the resolver expects
-direct single-locale field values. See
+Fetch entries with one CDA locale in the app layer. For localized apps, configure your application
+locale and pass it directly to Contentful CDA requests. Pass the same value to
+`forRequest({ locale: appLocale })` when MergeTags that read localized profile fields should match
+the rendered entry language. Do not pass all-locale CDA responses from `withAllLocales` or
+`locale=*` into `resolveOptimizedEntry()`; the resolver expects direct single-locale field values.
+See
 [Entry personalization and variant resolution](https://contentful.github.io/optimization/documents/Documentation.Concepts.Entry_personalization_and_variant_resolution.html#single-locale-cda-entry-contract)
 for the entry contract and
 [Locale handling in the Optimization SDK Suite](https://contentful.github.io/optimization/documents/Documentation.Concepts.Locale_handling_in_the_Optimization_SDK_Suite.html)
@@ -288,9 +284,9 @@ package directory.
   step-by-step server-side integration guide
 - [Node SDK generated reference](https://contentful.github.io/optimization/modules/_contentful_optimization-node.html) -
   exported API reference
-- [Node reference implementation](https://github.com/contentful/optimization/blob/v0.1.0-alpha14/implementations/node-sdk/README.md) - server-rendered
+- [Node reference implementation](https://github.com/contentful/optimization/blob/v0.1.0-alpha15/implementations/node-sdk/README.md) - server-rendered
   implementation using request-scoped SDK calls
-- [Node + Web reference implementation](https://github.com/contentful/optimization/blob/v0.1.0-alpha14/implementations/node-sdk+web-sdk/README.md) -
+- [Node + Web reference implementation](https://github.com/contentful/optimization/blob/v0.1.0-alpha15/implementations/node-sdk+web-sdk/README.md) -
   hybrid SSR and browser implementation
-- [Optimization Web SDK](https://github.com/contentful/optimization/blob/v0.1.0-alpha14/packages/web/web-sdk/README.md) - browser SDK used when the same application
+- [Optimization Web SDK](https://github.com/contentful/optimization/blob/v0.1.0-alpha15/packages/web/web-sdk/README.md) - browser SDK used when the same application
   also needs client-side consent, persistence, tracking, or live updates