contentful-export 8.3.0 → 8.4.0

package/README.md

@@ -389,6 +389,23 @@ If the source space has no ExO entities, or lacks the `exoM1` entitlement, each
 
 Requires the `exoM1` entitlement on the source space's organization. [contentful-cli](https://github.com/contentful/contentful-cli)'s `space export` command doesn't expose this option at all yet, so ExO export isn't reachable through that separate CLI regardless of default.
 
+### Optimization Variants
+
+Experiences and Experience Fragments each support **Optimization Variants** — alternate versions used for personalization. Variants are a separate opt-in on top of `includeExperienceOrchestration`, defaulting to `false`:
+
+```javascript
+const options = {
+  spaceId: '<space_id>',
+  managementToken: '<content_management_api_key>',
+  includeExperienceOrchestration: true,
+  includeExoVariants: true
+}
+
+await contentfulExport(options)
+```
+
+Unlike the six entity types above, variants are **not** exported as a seventh top-level array — they're nested onto their parent as `experience.optimizationVariants` / `experienceFragment.optimizationVariants`, because a variant has no globally-unique `sys.id` of its own (the API's variant response reuses the parent's `sys.id`; the variant is identified by `sys.variant`/`sys.variantType`/`sys.variantDimension` instead). When `includeExoVariants` is omitted or `false`, the `optimizationVariants` field is absent entirely — not an empty array — so default export output is unaffected. See [`docs/exo-export.md`](./docs/exo-export.md#optimization-variants) for the full shape, the ADR behind the nested-storage decision, and the corresponding `contentful-import` behavior.
+
 ### Round-tripping into `contentful-import`
 
 The ExO entities exported here are designed to be fed directly into [`contentful-import`](https://github.com/contentful/contentful-import), which preserves source IDs, applies dependency ordering (a topological sort for Components and Experience Fragments, since either can reference others of the same type), and upgrades entities from older, pre-rename export files automatically. See `contentful-import`'s README "Experience Orchestration (ExO) entities" section for the import-side details.

package/dist/index.js

@@ -82,6 +82,7 @@ function runContentfulExport(params) {
         skipTags: options.skipTags,
         stripTags: options.stripTags,
         includeExperienceOrchestration: options.includeExperienceOrchestration,
+        includeExoVariants: options.includeExoVariants,
         listrOptions,
         queryEntries: options.queryEntries,
         queryAssets: options.queryAssets
@@ -131,6 +132,7 @@ function runContentfulExport(params) {
   }).then(ctx => {
     const resultTypes = Object.keys(ctx.data);
     if (resultTypes.length) {
+      var _ctx$data$experiences, _ctx$optimizationVari, _ctx$data$experienceF, _ctx$optimizationVari2;
       const resultTable = new _cliTable.default(tableOptions);
       resultTable.push([{
         colSpan: 2,
@@ -139,6 +141,33 @@ function runContentfulExport(params) {
       resultTypes.forEach(type => {
         resultTable.push([(0, _lodash.default)(type), ctx.data[type].length]);
       });
+
+      // Optimization Variants are nested onto their parent Experience/Experience
+      // Fragment rather than exported as their own top-level field, so their count
+      // isn't free from resultTypes above and is computed here instead. A per-parent
+      // fetch failure falls back to an empty optimizationVariants array, which is
+      // indistinguishable from a parent that genuinely has none -- so failures are
+      // surfaced as their own row rather than folded silently into the count.
+      if ((_ctx$data$experiences = ctx.data.experiences) !== null && _ctx$data$experiences !== void 0 && _ctx$data$experiences.some(experience => experience.optimizationVariants)) {
+        const count = ctx.data.experiences.reduce((sum, experience) => {
+          var _experience$optimizat, _experience$optimizat2;
+          return sum + ((_experience$optimizat = (_experience$optimizat2 = experience.optimizationVariants) === null || _experience$optimizat2 === void 0 ? void 0 : _experience$optimizat2.length) !== null && _experience$optimizat !== void 0 ? _experience$optimizat : 0);
+        }, 0);
+        resultTable.push(['Experience Optimization Variants', count]);
+      }
+      if ((_ctx$optimizationVari = ctx.optimizationVariantFailures) !== null && _ctx$optimizationVari !== void 0 && _ctx$optimizationVari.experiences) {
+        resultTable.push(['Experience Optimization Variant Fetch Failures', ctx.optimizationVariantFailures.experiences]);
+      }
+      if ((_ctx$data$experienceF = ctx.data.experienceFragments) !== null && _ctx$data$experienceF !== void 0 && _ctx$data$experienceF.some(experienceFragment => experienceFragment.optimizationVariants)) {
+        const count = ctx.data.experienceFragments.reduce((sum, experienceFragment) => {
+          var _experienceFragment$o, _experienceFragment$o2;
+          return sum + ((_experienceFragment$o = (_experienceFragment$o2 = experienceFragment.optimizationVariants) === null || _experienceFragment$o2 === void 0 ? void 0 : _experienceFragment$o2.length) !== null && _experienceFragment$o !== void 0 ? _experienceFragment$o : 0);
+        }, 0);
+        resultTable.push(['Experience Fragment Optimization Variants', count]);
+      }
+      if ((_ctx$optimizationVari2 = ctx.optimizationVariantFailures) !== null && _ctx$optimizationVari2 !== void 0 && _ctx$optimizationVari2.experienceFragments) {
+        resultTable.push(['Experience Fragment Optimization Variant Fetch Failures', ctx.optimizationVariantFailures.experienceFragments]);
+      }
       console.log(resultTable.toString());
     } else {
       console.log('No data was exported');

package/dist/parseOptions.js

@@ -32,6 +32,7 @@ function parseOptions(params) {
     stripTags: false,
     maxAllowedLimit: 1000,
     includeExperienceOrchestration: true,
+    includeExoVariants: false,
     saveFile: true,
     useVerboseRenderer: false,
     rawProxy: false

package/dist/tasks/get-space-data.js

@@ -38,6 +38,7 @@ function getFullSourceSpace({
   includeArchived,
   maxAllowedLimit,
   includeExperienceOrchestration,
+  includeExoVariants,
   listrOptions,
   queryEntries,
   queryAssets
@@ -260,6 +261,40 @@ function getFullSourceSpace({
       }
     }),
     skip: () => !includeExperienceOrchestration
+  }, {
+    title: 'Fetching Experience Optimization Variants data',
+    task: (0, _contentfulBatchLibs.wrapTask)(async ctx => {
+      const experienceFailureCount = await attachOptimizationVariants({
+        parents: ctx.data.experiences,
+        fetchFn: (parentId, query) => client.experienceVariant.getMany({
+          spaceId,
+          environmentId,
+          experienceId: parentId,
+          query
+        }),
+        entityLabel: 'Experience Optimization Variants'
+      });
+      ctx.optimizationVariantFailures = ctx.optimizationVariantFailures || {};
+      ctx.optimizationVariantFailures.experiences = experienceFailureCount;
+    }),
+    skip: () => !includeExperienceOrchestration || !includeExoVariants
+  }, {
+    title: 'Fetching Experience Fragment Optimization Variants data',
+    task: (0, _contentfulBatchLibs.wrapTask)(async ctx => {
+      const experienceFragmentFailureCount = await attachOptimizationVariants({
+        parents: ctx.data.experienceFragments,
+        fetchFn: (parentId, query) => client.experienceFragmentVariant.getMany({
+          spaceId,
+          environmentId,
+          experienceFragmentId: parentId,
+          query
+        }),
+        entityLabel: 'Experience Fragment Optimization Variants'
+      });
+      ctx.optimizationVariantFailures = ctx.optimizationVariantFailures || {};
+      ctx.optimizationVariantFailures.experienceFragments = experienceFragmentFailureCount;
+    }),
+    skip: () => !includeExperienceOrchestration || !includeExoVariants
   }], listrOptions);
 }
 function getEditorInterfaces(client, spaceId, environmentId, contentTypes) {
@@ -305,6 +340,59 @@ async function cursorPagedGet(fetchFn, entityLabel) {
   return allItems;
 }
 
+/**
+ * Fetches and attaches Optimization Variants onto each of a parent entity type's
+ * items (Experience or ExperienceFragment), mutating them in place as
+ * `parent.optimizationVariants`. Variants are nested onto their parent rather than
+ * exported as their own top-level field because a variant's `sys.id` is borrowed
+ * from its parent (not unique to the variant), so a flat array would collide the
+ * way none of the other ExO entity types do.
+ *
+ * Unlike the top-level ExO entities, the optimization_variants list endpoint is NOT
+ * cursor-paginated — it takes no limit/pageNext query params and its response has no
+ * total/pages fields, just { sys: { type: 'Array' }, items }. So this is a single
+ * request per parent, not a paging loop.
+ *
+ * The API always leads the list with a `sys.variantType: 'default'` item representing
+ * the parent's own base view (either a real record, or the baseline Experience/Fragment
+ * itself if none exists) — not a real personalization variant. That entity is already
+ * exported as its own top-level Experience/ExperienceFragment, so it's filtered out here
+ * to avoid double-counting it as a variant.
+ *
+ * Runs with bounded concurrency (mirrors getEditorInterfaces' pattern) since this
+ * issues one request per parent entity (N+1).
+ *
+ * Returns the count of parents whose variant fetch failed, so callers can
+ * surface that distinctly from a parent that genuinely has zero variants
+ * (both look identical as an empty `optimizationVariants` array otherwise).
+ */
+async function attachOptimizationVariants({
+  parents,
+  fetchFn,
+  entityLabel
+}) {
+  if (!(parents !== null && parents !== void 0 && parents.length)) {
+    return 0;
+  }
+  let totalFetched = 0;
+  let failureCount = 0;
+  await _bluebird.default.map(parents, async parent => {
+    try {
+      const response = await fetchFn(parent.sys.id, {});
+      parent.optimizationVariants = response.items.filter(item => item.sys.variantType !== 'default');
+      totalFetched += parent.optimizationVariants.length;
+      _contentfulBatchLibs.logEmitter.emit('info', `Fetched ${totalFetched} ${entityLabel} items`);
+    } catch (err) {
+      _contentfulBatchLibs.logEmitter.emit('warning', `Skipping ${entityLabel} export for ${parent.sys.id}: ${err.message}`);
+      parent.optimizationVariants = [];
+      failureCount++;
+    }
+  }, {
+    concurrency: 6
+  });
+  return failureCount;
+}
+
 /**
  * Gets all roles. Roles are scheduled to switch from skip/limit to
  * cursor-based (pages.next/pagePrev) pagination on Feb 15, 2027:

package/dist/usageParams.js

@@ -111,6 +111,10 @@ var _default = exports.default = _yargs.default.version(_package.default.version
   describe: 'Include Experience Orchestration entities (Components, Experience Templates, Data Assemblies, Experience Fragments, Experiences, Design Tokens). Requires exo_m1 entitlement on the source space.',
   type: 'boolean',
   default: true
+}).option('include-exo-variants', {
+  describe: 'Include Optimization Variants, nested onto their parent Experience/Experience Fragment as `optimizationVariants`. Requires include-experience-orchestration. Only has an effect if the Contentful Personalization app is installed on the source space.',
+  type: 'boolean',
+  default: false
 }).option('header', {
   alias: 'H',
   type: 'string',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contentful-export",
-  "version": "8.3.0",
+  "version": "8.4.0",
   "description": "this tool allows you to export a space to a JSON dump",
   "main": "dist/index.js",
   "types": "types.d.ts",
@@ -52,7 +52,7 @@
     "cli-table3": "^0.6.0",
     "contentful": "^11.5.10",
     "contentful-batch-libs": "^12.0.0",
-    "contentful-management": "^12.14.0",
+    "contentful-management": "^12.17.0",
     "date-fns": "^4.1.0",
     "figures": "^3.2.0",
     "jsonwebtoken": "^9.0.0",