@contentful/optimization-node 0.1.0-alpha17 → 0.1.0-alpha18

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-alpha17/contentful-icon.png" width="150">
+    <img alt="Contentful Logo" title="Contentful" src="https://raw.githubusercontent.com/contentful/optimization/v0.1.0-alpha18/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-alpha17/CONTRIBUTING.md)
+[Reference](https://contentful.github.io/optimization) · [Contributing](https://github.com/contentful/optimization/blob/v0.1.0-alpha18/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-alpha17/packages/universal/core-sdk/README.md). Use it for server rendering, server
+[Optimization Core SDK](https://github.com/contentful/optimization/blob/v0.1.0-alpha18/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
@@ -54,6 +54,9 @@ Install using an NPM-compatible package manager, pnpm for example:
 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
@@ -105,7 +108,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-alpha17/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-alpha18/documentation/concepts/consent-management-in-the-optimization-sdk-suite.md).
 
 | Option              | Required? | Default                | Description                                                 |
 | ------------------- | --------- | ---------------------- | ----------------------------------------------------------- |
@@ -113,6 +116,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     |
+| `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 |
@@ -222,22 +226,41 @@ to `forRequest()`.
 
 ### Content resolution
 
-Fetch Contentful entries in your application layer, then resolve variants with returned optimization
-data:
+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`.
+
+```ts
+const optimization = new ContentfulOptimization({
+  clientId: 'client-id',
+  contentful: { client: contentfulClient },
+  environment: 'main',
+  locale: appLocale,
+})
+
+const requestOptimization = optimization.forRequest({ consent: true, profile })
+await requestOptimization.page()
+const { baselineEntry, entry } = await requestOptimization.fetchOptimizedEntry('hero-entry')
+```
+
+If your application already fetched the baseline entry, keep using the manual resolver:
 
 ```ts
+const pageResult = await requestOptimization.page()
 const resolvedEntry = optimization.resolveOptimizedEntry(
   baselineEntry,
-  optimizationData?.selectedOptimizations,
+  pageResult.accepted ? pageResult.data.selectedOptimizations : undefined,
 )
 ```
 
-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
+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)
@@ -250,12 +273,13 @@ stateless, so `getFlag()` does not automatically emit flag-view tracking.
 
 ### Caching guidance
 
-Cache raw Contentful delivery payloads in your application layer, not profile-evaluated SDK event
-results.
+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                                     | Yes                    | They are content snapshots and can be resolved per request           |
+| 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                                 |
@@ -284,9 +308,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-alpha17/implementations/node-sdk/README.md) - server-rendered
+- [Node reference implementation](https://github.com/contentful/optimization/blob/v0.1.0-alpha18/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-alpha17/implementations/node-sdk+web-sdk/README.md) -
+- [Node + Web reference implementation](https://github.com/contentful/optimization/blob/v0.1.0-alpha18/implementations/node-sdk+web-sdk/README.md) -
   hybrid SSR and browser implementation
-- [Optimization Web SDK](https://github.com/contentful/optimization/blob/v0.1.0-alpha17/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-alpha18/packages/web/web-sdk/README.md) - browser SDK used when the same application
   also needs client-side consent, persistence, tracking, or live updates

package/dist/260.mjs

@@ -1,4 +1,4 @@
-const OPTIMIZATION_NODE_SDK_VERSION = "0.1.0-alpha17";
+const OPTIMIZATION_NODE_SDK_VERSION = "0.1.0-alpha18";
 const OPTIMIZATION_NODE_SDK_NAME = "@contentful/optimization-node";
 export { ANONYMOUS_ID_COOKIE, ANONYMOUS_ID_KEY } from "@contentful/optimization-core/constants";
 export { OPTIMIZATION_NODE_SDK_NAME, OPTIMIZATION_NODE_SDK_VERSION };

package/dist/constants.cjs

@@ -30,7 +30,7 @@ __webpack_require__.d(__webpack_exports__, {
     OPTIMIZATION_NODE_SDK_VERSION: ()=>OPTIMIZATION_NODE_SDK_VERSION
 });
 const constants_namespaceObject = require("@contentful/optimization-core/constants");
-const OPTIMIZATION_NODE_SDK_VERSION = "0.1.0-alpha17";
+const OPTIMIZATION_NODE_SDK_VERSION = "0.1.0-alpha18";
 const OPTIMIZATION_NODE_SDK_NAME = "@contentful/optimization-node";
 exports.ANONYMOUS_ID_COOKIE = __webpack_exports__.ANONYMOUS_ID_COOKIE;
 exports.ANONYMOUS_ID_KEY = __webpack_exports__.ANONYMOUS_ID_KEY;

package/dist/core-sdk.cjs

@@ -2,6 +2,9 @@
 var __webpack_modules__ = {
     "@contentful/optimization-core" (module) {
         module.exports = require("@contentful/optimization-core");
+    },
+    "@contentful/optimization-core/entry-source" (module) {
+        module.exports = require("@contentful/optimization-core/entry-source");
     }
 };
 var __webpack_module_cache__ = {};
@@ -47,12 +50,22 @@ function __webpack_require__(moduleId) {
 var __webpack_exports__ = {};
 (()=>{
     __webpack_require__.r(__webpack_exports__);
+    __webpack_require__.d(__webpack_exports__, {
+        prefetchOptimizedEntries: ()=>_contentful_optimization_core_entry_source__rspack_import_1.prefetchOptimizedEntries
+    });
     var _contentful_optimization_core__rspack_import_0 = __webpack_require__("@contentful/optimization-core");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _contentful_optimization_core__rspack_import_0)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_contentful_optimization_core__rspack_import_0[__rspack_import_key];
+    for(const __rspack_import_key in _contentful_optimization_core__rspack_import_0)if ([
+        "prefetchOptimizedEntries",
+        "default"
+    ].indexOf(__rspack_import_key) < 0) __rspack_reexport[__rspack_import_key] = ()=>_contentful_optimization_core__rspack_import_0[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
+    var _contentful_optimization_core_entry_source__rspack_import_1 = __webpack_require__("@contentful/optimization-core/entry-source");
 })();
-for(var __rspack_i in __webpack_exports__)exports[__rspack_i] = __webpack_exports__[__rspack_i];
+exports.prefetchOptimizedEntries = __webpack_exports__.prefetchOptimizedEntries;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "prefetchOptimizedEntries"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
 Object.defineProperty(exports, '__esModule', {
     value: true
 });

package/dist/core-sdk.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"core-sdk.cjs","sources":["webpack/runtime/compat_get_default_export","webpack/runtime/define_property_getters","webpack/runtime/has_own_property","webpack/runtime/make_namespace_object"],"sourcesContent":["// getDefaultExport function for compatibility with non-ESM modules\n__webpack_require__.n = (module) => {\n\tvar getter = module && module.__esModule ?\n\t\t() => (module['default']) :\n\t\t() => (module);\n\t__webpack_require__.d(getter, { a: getter });\n\treturn getter;\n};\n","__webpack_require__.d = (exports, definition) => {\n\tfor(var key in definition) {\n        if(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {\n            Object.defineProperty(exports, key, { enumerable: true, get: definition[key] });\n        }\n    }\n};","__webpack_require__.o = (obj, prop) => (Object.prototype.hasOwnProperty.call(obj, prop))","// define __esModule on exports\n__webpack_require__.r = (exports) => {\n\tif(typeof Symbol !== 'undefined' && Symbol.toStringTag) {\n\t\tObject.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });\n\t}\n\tObject.defineProperty(exports, '__esModule', { value: true });\n};"],"names":["__webpack_require__","module","getter","definition","key","Object","obj","prop","Symbol"],"mappings":";;;;;;;;;;;;;;;;;IACAA,oBAAoB,CAAC,GAAG,CAACC;QACxB,IAAIC,SAASD,UAAUA,OAAO,UAAU,GACvC,IAAOA,MAAM,CAAC,UAAU,GACxB,IAAOA;QACRD,oBAAoB,CAAC,CAACE,QAAQ;YAAE,GAAGA;QAAO;QAC1C,OAAOA;IACR;;;ICPAF,oBAAoB,CAAC,GAAG,CAAC,UAASG;QACjC,IAAI,IAAIC,OAAOD,WACR,IAAGH,oBAAoB,CAAC,CAACG,YAAYC,QAAQ,CAACJ,oBAAoB,CAAC,CAAC,UAASI,MACzEC,OAAO,cAAc,CAAC,UAASD,KAAK;YAAE,YAAY;YAAM,KAAKD,UAAU,CAACC,IAAI;QAAC;IAGzF;;;ICNAJ,oBAAoB,CAAC,GAAG,CAACM,KAAKC,OAAUF,OAAO,SAAS,CAAC,cAAc,CAAC,IAAI,CAACC,KAAKC;;;ICClFP,oBAAoB,CAAC,GAAG,CAAC;QACxB,IAAG,AAAkB,MAAlB,OAAOQ,UAA0BA,OAAO,WAAW,EACrDH,OAAO,cAAc,CAAC,UAASG,OAAO,WAAW,EAAE;YAAE,OAAO;QAAS;QAEtEH,OAAO,cAAc,CAAC,UAAS,cAAc;YAAE,OAAO;QAAK;IAC5D"}
+{"version":3,"file":"core-sdk.cjs","sources":["webpack/runtime/compat_get_default_export","webpack/runtime/define_property_getters","webpack/runtime/has_own_property","webpack/runtime/make_namespace_object"],"sourcesContent":["// getDefaultExport function for compatibility with non-ESM modules\n__webpack_require__.n = (module) => {\n\tvar getter = module && module.__esModule ?\n\t\t() => (module['default']) :\n\t\t() => (module);\n\t__webpack_require__.d(getter, { a: getter });\n\treturn getter;\n};\n","__webpack_require__.d = (exports, definition) => {\n\tfor(var key in definition) {\n        if(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {\n            Object.defineProperty(exports, key, { enumerable: true, get: definition[key] });\n        }\n    }\n};","__webpack_require__.o = (obj, prop) => (Object.prototype.hasOwnProperty.call(obj, prop))","// define __esModule on exports\n__webpack_require__.r = (exports) => {\n\tif(typeof Symbol !== 'undefined' && Symbol.toStringTag) {\n\t\tObject.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });\n\t}\n\tObject.defineProperty(exports, '__esModule', { value: true });\n};"],"names":["__webpack_require__","module","getter","definition","key","Object","obj","prop","Symbol"],"mappings":";;;;;;;;;;;;;;;;;;;;IACAA,oBAAoB,CAAC,GAAG,CAACC;QACxB,IAAIC,SAASD,UAAUA,OAAO,UAAU,GACvC,IAAOA,MAAM,CAAC,UAAU,GACxB,IAAOA;QACRD,oBAAoB,CAAC,CAACE,QAAQ;YAAE,GAAGA;QAAO;QAC1C,OAAOA;IACR;;;ICPAF,oBAAoB,CAAC,GAAG,CAAC,UAASG;QACjC,IAAI,IAAIC,OAAOD,WACR,IAAGH,oBAAoB,CAAC,CAACG,YAAYC,QAAQ,CAACJ,oBAAoB,CAAC,CAAC,UAASI,MACzEC,OAAO,cAAc,CAAC,UAASD,KAAK;YAAE,YAAY;YAAM,KAAKD,UAAU,CAACC,IAAI;QAAC;IAGzF;;;ICNAJ,oBAAoB,CAAC,GAAG,CAACM,KAAKC,OAAUF,OAAO,SAAS,CAAC,cAAc,CAAC,IAAI,CAACC,KAAKC;;;ICClFP,oBAAoB,CAAC,GAAG,CAAC;QACxB,IAAG,AAAkB,MAAlB,OAAOQ,UAA0BA,OAAO,WAAW,EACrDH,OAAO,cAAc,CAAC,UAASG,OAAO,WAAW,EAAE;YAAE,OAAO;QAAS;QAEtEH,OAAO,cAAc,CAAC,UAAS,cAAc;YAAE,OAAO;QAAK;IAC5D"}

package/dist/core-sdk.d.cts

@@ -1,3 +1,16 @@
+import { OptimizedEntryPrefetchDescriptor } from '@contentful/optimization-core/entry-source';
+import { OptimizedEntryPrefetchRuntime } from '@contentful/optimization-core/entry-source';
+import { prefetchOptimizedEntries } from '@contentful/optimization-core/entry-source';
+import { ServerOptimizedEntryHandoff } from '@contentful/optimization-core/entry-source';
+
+export { OptimizedEntryPrefetchDescriptor }
+
+export { OptimizedEntryPrefetchRuntime }
+
+export { prefetchOptimizedEntries }
+
+export { ServerOptimizedEntryHandoff }
+
 
 export * from "@contentful/optimization-core";
 

package/dist/core-sdk.d.mts

@@ -1,3 +1,16 @@
+import { OptimizedEntryPrefetchDescriptor } from '@contentful/optimization-core/entry-source';
+import { OptimizedEntryPrefetchRuntime } from '@contentful/optimization-core/entry-source';
+import { prefetchOptimizedEntries } from '@contentful/optimization-core/entry-source';
+import { ServerOptimizedEntryHandoff } from '@contentful/optimization-core/entry-source';
+
+export { OptimizedEntryPrefetchDescriptor }
+
+export { OptimizedEntryPrefetchRuntime }
+
+export { prefetchOptimizedEntries }
+
+export { ServerOptimizedEntryHandoff }
+
 
 export * from "@contentful/optimization-core";
 

package/dist/core-sdk.d.ts

@@ -1,3 +1,16 @@
+import { OptimizedEntryPrefetchDescriptor } from '@contentful/optimization-core/entry-source';
+import { OptimizedEntryPrefetchRuntime } from '@contentful/optimization-core/entry-source';
+import { prefetchOptimizedEntries } from '@contentful/optimization-core/entry-source';
+import { ServerOptimizedEntryHandoff } from '@contentful/optimization-core/entry-source';
+
+export { OptimizedEntryPrefetchDescriptor }
+
+export { OptimizedEntryPrefetchRuntime }
+
+export { prefetchOptimizedEntries }
+
+export { ServerOptimizedEntryHandoff }
+
 
 export * from "@contentful/optimization-core";
 

package/dist/core-sdk.mjs

@@ -1,2 +1,3 @@
 import "./987.mjs";
 export * from "@contentful/optimization-core";
+export { prefetchOptimizedEntries } from "@contentful/optimization-core/entry-source";

package/dist/index.cjs

@@ -6,7 +6,7 @@ var __webpack_modules__ = {
             OPTIMIZATION_NODE_SDK_VERSION: ()=>OPTIMIZATION_NODE_SDK_VERSION
         });
         require("@contentful/optimization-core/constants");
-        const OPTIMIZATION_NODE_SDK_VERSION = "0.1.0-alpha17";
+        const OPTIMIZATION_NODE_SDK_VERSION = "0.1.0-alpha18";
         const OPTIMIZATION_NODE_SDK_NAME = "@contentful/optimization-node";
     }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/optimization-node",
-  "version": "0.1.0-alpha17",
+  "version": "0.1.0-alpha18",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -87,6 +87,6 @@
     }
   },
   "dependencies": {
-    "@contentful/optimization-core": "0.1.0-alpha17"
+    "@contentful/optimization-core": "0.1.0-alpha18"
   }
 }