@contentful/optimization-node 0.1.0-alpha8 → 1.0.0

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="../../../contentful-icon.png" width="150">
+    <img alt="Contentful Logo" title="Contentful" src="https://raw.githubusercontent.com/contentful/optimization/optimization-node-v1.0.0/contentful-icon.png" width="150">
   </a>
 </p>
 
@@ -10,280 +10,311 @@
 
 <div align="center">
 
-[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
-[Contributing](/CONTRIBUTING.md)
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](https://github.com/contentful/optimization/blob/optimization-node-v1.0.0/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 can be published at any time.
 
-The Optimization Node SDK implements functionality specific to Node environments, based on the
-[Optimization Core Library](/universal/core/README.md). This SDK is part of the
-[Contentful Optimization SDK Suite](/README.md).
+The Optimization Node SDK implements stateless server-side optimization behavior on top of the
+[Optimization Core SDK](https://github.com/contentful/optimization/blob/optimization-node-v1.0.0/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
+[Integrating the Optimization Node SDK in a Node app](https://contentful.github.io/optimization/documents/Documentation.Guides.integrating-the-node-sdk-in-a-node-app.html)
+for the step-by-step flow. This README keeps the package orientation and common setup options close
+at hand; generated [reference documentation](https://contentful.github.io/optimization) remains the
+source of truth for exported API signatures.
 
 <details>
   <summary>Table of Contents</summary>
 <!-- mtoc-start -->
 
-- [Getting Started](#getting-started)
-- [Reference Implementations](#reference-implementations)
-- [Configuration](#configuration)
-  - [Top-level Configuration Options](#top-level-configuration-options)
-  - [Analytics Options](#analytics-options)
-  - [Event Builder Options](#event-builder-options)
-  - [Fetch Options](#fetch-options)
-  - [Personalization Options](#personalization-options)
-- [Optimization Methods](#optimization-methods)
-  - [Personalization Data Resolution Methods](#personalization-data-resolution-methods)
-    - [`getCustomFlag`](#getcustomflag)
-    - [`personalizeEntry`](#personalizeentry)
-    - [`getMergeTagValue`](#getmergetagvalue)
-  - [Personalization and Analytics Event Methods](#personalization-and-analytics-event-methods)
-    - [`identify`](#identify)
-    - [`page`](#page)
-    - [`track`](#track)
-    - [`trackComponentView`](#trackcomponentview)
-    - [`trackFlagView`](#trackflagview)
-- [Interceptors](#interceptors)
-  - [Life-cycle Interceptors](#life-cycle-interceptors)
+- [Getting started](#getting-started)
+- [When to use this package](#when-to-use-this-package)
+- [Common configuration](#common-configuration)
+- [Core workflows](#core-workflows)
+  - [Request-scoped events](#request-scoped-events)
+  - [Content resolution](#content-resolution)
+  - [Caching guidance](#caching-guidance)
+- [Development harness](#development-harness)
+- [Related](#related)
 
 <!-- mtoc-end -->
 </details>
 
-## Getting Started
+## Getting started
 
 Install using an NPM-compatible package manager, pnpm for example:
 
 ```sh
-pnpm install @contentful/optimization-node
+pnpm add @contentful/optimization-node
 ```
 
+Add `contentful` too when the SDK will use your app-owned `contentful.js` client for managed entry
+fetching.
+
 Import the Optimization class; both CJS and ESM module systems are supported, ESM preferred:
 
 ```ts
-import Optimization from '@contentful/optimization-node'
+import ContentfulOptimization from '@contentful/optimization-node'
 ```
 
-Configure and initialize the Optimization Node SDK:
+Create the SDK once per module or process, then bind consent and request context in each route:
 
 ```ts
-const optimization = new Optimization({ clientId: 'abc123' })
-```
-
-## Reference Implementations
-
-Reference implementations illustrate how the SDK may be used under common scenarios, as well as
-select less-common scenarios, with the most basic example solution possible.
-
-- [Node SSR Only](/implementations/node-ssr-only/README.md): Example application that uses the Node
-  SDK to render a personalized Web page
-- [Node SSR + Web Vanilla](/implementations/node-ssr-web-vanilla/README.md): Example application
-  demonstrating simple profile synchronization between the Node and [Web](../web/README.md) SDKs via
-  cookie
-
-## Configuration
-
-### Top-level Configuration Options
-
-| Option            | Required? | Default                       | Description                                                                    |
-| ----------------- | --------- | ----------------------------- | ------------------------------------------------------------------------------ |
-| `analytics`       | No        | See "Analytics Options"       | Configuration specific to the Analytics/Insights API                           |
-| `app`             | No        | `undefined`                   | The application definition used to attribute events to a specific consumer app |
-| `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                   |
-
-### Analytics Options
-
-| Option    | Required? | Default                                    | Description                   |
-| --------- | --------- | ------------------------------------------ | ----------------------------- |
-| `baseUrl` | No        | `'https://ingest.insights.ninetailed.co/'` | Base URL for the Insights API |
-
-### Event Builder Options
-
-Event builder options should only be supplied when building an SDK on top of the Optimization Node
-SDK or any of its descendent SDKs.
-
-| Option    | Required? | Default                                               | Description                                                                        |
-| --------- | --------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `channel` | No        | `'server'`                                            | The channel that identifies where events originate from (e.g. `'web'`, `'mobile'`) |
-| `library` | No        | `{ name: 'Optimization Node API', version: '0.0.0' }` | The client library metadata that is attached to all events                         |
-
-### 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
-application environment does not offer a `fetch` method that is compatible with the standard Fetch
-API in its global scope.
-
-| Option             | Required? | Default     | Description                                                           |
-| ------------------ | --------- | ----------- | --------------------------------------------------------------------- |
-| `fetchMethod`      | No        | `undefined` | Signature of a fetch method used by the API clients                   |
-| `intervalTimeout`  | No        | `0`         | Delay (in milliseconds) between retry attempts                        |
-| `onFailedAttempt`  | No        | `undefined` | Callback invoked whenever a retry attempt fails                       |
-| `onRequestTimeout` | No        | `undefined` | Callback invoked when a request exceeds the configured timeout        |
-| `requestTimeout`   | No        | `3000`      | Maximum time (in milliseconds) to wait for a response before aborting |
-| `retries`          | No        | `1`         | Maximum number of retry attempts                                      |
-
-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 |
-
-## Optimization Methods
-
-Arguments marked with an asterisk (\*) are always required.
-
-### Personalization Data Resolution Methods
-
-#### `getCustomFlag`
-
-Get the specified Custom Flag's value from the provided changes array.
-
-Arguments:
-
-- `name`\*: The name/key of the Custom Flag
-- `changes`: Changes array
-
-Returns:
-
-- The resolved value for the specified Custom Flag, or `undefined` if it cannot be found.
-
-> [!NOTE]
->
-> If the `changes` argument is omitted, the method will return `undefined`.
-
-#### `personalizeEntry`
-
-Resolve a baseline Contentful entry to a personalized variant using the provided selected
-personalizations.
-
-Type arguments:
-
-- `S`: Entry skeleton type
-- `M`: Chain modifiers
-- `L`: Locale code
-
-Arguments:
-
-- `entry`\*: The entry to personalize
-- `personalizations`: Selected personalizations
-
-Returns:
-
-- The resolved personalized 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, the method will return the baseline entry.
-
-#### `getMergeTagValue`
-
-Resolve a "Merge Tag" to a value based on the provided profile. A "Merge Tag" is a special Rich Text
-fragment supported by Contentful that specifies a profile data member to be injected into the Rich
-Text when rendered.
-
-Arguments:
+const optimization = new ContentfulOptimization({
+  clientId: 'your-client-id',
+  environment: 'main',
+  locale: 'en-US',
+})
 
-- `embeddedNodeEntryTarget`\*: The merge tag entry node to resolve
-- `profile`: The user profile
+function appPolicyAllowsOptimizationEvent(req: { cookies?: Record<string, string> }): boolean {
+  return req.cookies?.['app-personalization-consent'] === 'granted'
+}
+
+async function renderRequest(
+  req: { cookies?: Record<string, string>; headers: { 'accept-language'?: string } },
+  profileId: string,
+) {
+  const appLocale = getAppLocale(req)
+  const requestOptimization = optimization.forRequest({
+    consent: {
+      events: appPolicyAllowsOptimizationEvent(req),
+      persistence: appPolicyAllowsOptimizationEvent(req),
+    },
+    locale: appLocale,
+    eventContext: { locale: appLocale },
+    profile: { id: profileId },
+  })
+
+  const { accepted, data } = await requestOptimization.page()
+
+  return accepted ? data : undefined
+}
+```
 
-> [!NOTE]
->
-> If the `profile` argument is omitted, the method will return the merge tag's fallback value.
+## When to use this package
 
-### Personalization and Analytics Event Methods
+Use `@contentful/optimization-node` for server-side rendering, server functions, and Node services
+that need stateless profile evaluation or event emission. Use the Web or React Web SDK alongside it
+when browser-side consent, anonymous ID persistence, automatic interaction tracking, or live updates
+are part of the same application.
 
-Each method except `trackFlagView` may return an `OptimizationData` object containing:
+## Common configuration
 
-- `changes`: Currently used for Custom Flags
-- `personalizations`: Selected personalizations for the profile
-- `profile`: Profile associated with the evaluated events
+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/optimization-node-v1.0.0/documentation/concepts/consent-management-in-the-optimization-sdk-suite.md).
 
-#### `identify`
+| Option              | Required? | Default                | Description                                                 |
+| ------------------- | --------- | ---------------------- | ----------------------------------------------------------- |
+| `clientId`          | Yes       | N/A                    | Shared API key for Experience API and Insights API requests |
+| `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     |
+| `contentful`        | No        | `undefined`            | App-owned `contentful.js` client, default query, and cache  |
+| `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              |
+| `logLevel`          | No        | `'error'`              | Minimum log level for the default console sink              |
 
-Identify the current profile/visitor to associate traits with a profile.
+Common `api` options:
 
-Arguments:
+| 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']`            | Experience API features to apply to each request |
 
-- `payload`\*: Identify event builder arguments object, including an optional `profile` property
-  with a `PartialProfile` value that requires only an `id`
+Request-scoped Experience options belong in `experienceOptions` when creating the request-bound
+client:
 
-#### `page`
+| Option      | Description                                                   |
+| ----------- | ------------------------------------------------------------- |
+| `ip`        | IP address override used by the Experience API                |
+| `locale`    | Locale query parameter for localized Experience API responses |
+| `plainText` | Sends performance-critical Experience API endpoints as text   |
+| `preflight` | Aggregates a new profile state without storing it             |
 
-Record a personalization page view.
+Request-scoped Insights options belong in `insightsOptions`:
 
-Arguments:
+| Option   | Description                                                       |
+| -------- | ----------------------------------------------------------------- |
+| `beacon` | Last-chance sender for serialized Insights API batches if needed. |
 
-- `payload`\*: Page view event builder arguments object, including an optional `profile` property
-  with a `PartialProfile` value that requires only an `id`
+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.
 
-#### `track`
+Common `fetchOptions` are `fetchMethod`, `requestTimeout`, `retries`, `intervalTimeout`,
+`onFailedAttempt`, and `onRequestTimeout`. Default retries intentionally apply only to HTTP `503`
+responses.
 
-Record a personalization custom track event.
+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.
 
-Arguments:
+For every option, callback payload, and exported type, use the generated
+[Node SDK reference](https://contentful.github.io/optimization/modules/_contentful_optimization-node.html).
 
-- `payload`\*: Track event builder arguments object, including an optional `profile` property with a
-  `PartialProfile` value that requires only an `id`
+## Core workflows
 
-#### `trackComponentView`
+### Request-scoped events
 
-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".
+Build event context from the incoming request, bind application-owned consent state with
+`forRequest()`, then call `page()`, `identify()`, `screen()`, `track()`, or sticky `trackView()` on
+the returned request object:
 
-Arguments:
+```ts
+import type { Request } from 'express'
+
+app.get('/products/:slug', async (req, res) => {
+  const appLocale = getAppLocale(req)
+  const requestOptimization = optimization.forRequest({
+    consent: {
+      events: appPolicyAllowsOptimizationEvent(req),
+      persistence: appPolicyAllowsOptimizationEvent(req),
+    },
+    locale: appLocale,
+    eventContext: {
+      locale: appLocale,
+    },
+    profile: { id: req.cookies.profileId },
+  })
+  const { accepted, data: optimizationData } = await requestOptimization.page({
+    properties: { path: req.path },
+  })
+
+  if (accepted && requestOptimization.canPersistProfile && optimizationData?.profile.id) {
+    persistProfileId(res, optimizationData.profile.id)
+  }
+
+  res.render('product', { optimizationData })
+})
+```
 
-- `payload`\*: Component view event builder arguments object, including an optional `profile`
-  property with a `PartialProfile` value that requires only an `id`
+For default-on application policies that do not render an end-user consent UI, replace the
+request-specific consent lookup with accepted consent:
 
-#### `trackFlagView`
+```ts
+const requestOptimization = optimization.forRequest({
+  consent: { events: true, persistence: true },
+  locale: appLocale,
+  eventContext: { locale: appLocale },
+  profile,
+})
+```
 
-Track a feature flag view via analytics. This is functionally the same as a non-sticky component
-view event.
+Node SDK event calls fail closed except for the default pre-consent allowlist, `identify` and
+`page`. Those allowlisted events are sent with `context.gdpr.isConsentGiven: false` when request
+event consent is not granted. Pass `allowedEventTypes: []` to require strict opt-in for all
+stateless event methods.
 
-Arguments:
+In stateless runtimes, Insights-backed methods require a request-bound profile for delivery.
+Non-sticky `trackView`, `trackClick`, `trackHover`, and `trackFlagView` require a profile ID passed
+to `forRequest()`.
 
-- `payload`\*: Component view event builder arguments object, including an optional `profile`
-  property with a `PartialProfile` value that requires only an `id`
+### Content resolution
 
-## Interceptors
+When a `contentful.js` client is available, prefer SDK-managed fetching by entry ID. Configure the
+client once, then call `fetchOptimizedEntry()` on a request-bound client after an accepted
+Experience API call. `forRequest()` clients use the latest selected optimizations when omitted;
+singleton calls require explicit `selectedOptimizations`.
 
-Interceptors may be used to read and/or modify data flowing through the Core SDK.
+```ts
+const optimization = new ContentfulOptimization({
+  clientId: 'client-id',
+  contentful: { client: contentfulClient },
+  environment: 'main',
+  locale: appLocale,
+})
 
-### Life-cycle Interceptors
+const requestOptimization = optimization.forRequest({ consent: true, profile })
+await requestOptimization.page()
+const { baselineEntry, entry } = await requestOptimization.fetchOptimizedEntry('hero-entry')
+```
 
-- `event`: Intercepts an event's data _before_ it is queued and/or emitted
-- `state`: Intercepts state data retrieved from an Experience API call _before_ updating the SDK's
-  internal state
+Use `fetchContentfulEntries()` or `prefetchManagedEntries()` when a route knows several managed
+entry IDs. Entries with the same normalized query share one `getEntries()` call; same-tick
+single-entry calls can join that batch. Large `getEntries()` fetches are split into 100-ID chunks.
 
-Example interceptor usage:
+If your application already fetched the baseline entry, keep using the manual resolver:
 
 ```ts
-optimization.interceptors.event((event) => {
-  event.properties.timestamp = new Date().toISOString()
-})
+const pageResult = await requestOptimization.page()
+const resolvedEntry = optimization.resolveOptimizedEntry(
+  baselineEntry,
+  pageResult.accepted ? pageResult.data.selectedOptimizations : undefined,
+)
 ```
 
-> [!WARNING]
->
-> Interceptors are intended to enable low-level interoperability; to simply read and react to
-> Optimization SDK events, use the `states` observables.
+Use one CDA locale in either path. For localized apps, configure your application locale. A
+request-bound client uses `forRequest({ locale: appLocale })` as the managed Contentful query locale
+when neither `contentful.defaultQuery` nor the per-call query sets `locale`. Pass the same value to
+app-owned Contentful CDA requests and to `forRequest({ locale: appLocale })` when MergeTags that
+read localized profile fields match the rendered entry language. Do not pass all-locale CDA
+responses from `withAllLocales` or `locale=*`; 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)
+for request locale behavior.
+
+Use `getMergeTagValue()` for Contentful Rich Text merge tags and `getFlag()` for Custom Flags. If a
+merge tag references localized profile fields such as `location.city` or `location.country`, its
+resolved value follows the localized profile data returned by the Experience API. The Node SDK is
+stateless, so `getFlag()` does not automatically emit flag-view tracking.
+
+### Caching guidance
+
+Cache raw Contentful delivery payloads in your application layer or with the SDK-managed entry
+cache, not profile-evaluated SDK event results. Use `clearContentfulEntryCache()` when an SDK
+instance must drop cached CDA entries.
+
+| Data or call                                                                | Cache across requests? | Reason                                                               |
+| --------------------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------- |
+| Raw Contentful entries fetched from CDA or the SDK-managed entry cache      | Yes                    | They are content snapshots and can be resolved per request           |
+| `resolveOptimizedEntry()` and `getMergeTagValue()` results                  | Request-local only     | Results depend on the current profile and optimization data          |
+| `page()`, `identify()`, `screen()`, `track()`, and sticky `trackView()`     | No                     | These calls perform side effects and return request-specific profile |
+| Non-sticky `trackView()`, `trackClick()`, `trackHover()`, `trackFlagView()` | No                     | These calls emit Insights API events                                 |
+
+The
+[Node SDK integration guide](https://contentful.github.io/optimization/documents/Documentation.Guides.integrating-the-node-sdk-in-a-node-app.html)
+covers request context, profile persistence, Contentful entry resolution, and hybrid Node + browser
+setups in detail.
+
+## Development harness
+
+The package-local dev harness runs from `packages/node/node-sdk/dev/` and reads `.env` from this
+package directory.
+
+1. Start from `.env.example` and create or update `packages/node/node-sdk/.env`.
+2. Prefer the repo-standard `PUBLIC_...` variable names shown in `.env.example`.
+3. Start the harness from the repo root:
+
+   ```sh
+   pnpm --filter @contentful/optimization-node dev
+   ```
+
+## Related
+
+- [Integrating the Optimization Node SDK in a Node app](https://contentful.github.io/optimization/documents/Documentation.Guides.integrating-the-node-sdk-in-a-node-app.html) -
+  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/optimization-node-v1.0.0/implementations/node-sdk/README.md) - server-rendered
+  implementation using request-scoped SDK calls
+- [Node + Web reference implementation](https://github.com/contentful/optimization/blob/optimization-node-v1.0.0/implementations/node-sdk+web-sdk/README.md) -
+  hybrid SSR and browser implementation
+- [Optimization Web SDK](https://github.com/contentful/optimization/blob/optimization-node-v1.0.0/packages/web/web-sdk/README.md) - browser SDK used when the same application
+  also needs client-side consent, persistence, tracking, or live updates