contentful-export 8.3.0 → 8.5.0

package/README.md

@@ -186,7 +186,7 @@ Content Delivery API.
 
 #### `includeArchived` [boolean] [default: false]
 
-Include archived entries in the exported entries
+Include archived entries and assets in the exported data. This option does not include archived Releases.
 
 #### `skipContentModel` [boolean] [default: false]
 
@@ -212,6 +212,10 @@ Skip exporting tags
 
 Skip exporting webhooks
 
+#### `skipReleases` [boolean] [default: false]
+
+Skip exporting [Releases](https://www.contentful.com/help/releases/). See the "Releases" section below for what's exported when this is on.
+
 #### `stripTags` [boolean] [default: false]
 
 Untag assets and entries
@@ -339,6 +343,7 @@ This is an overview of the exported data:
   "webhooks": [],
   "roles": [],
   "editorInterfaces": [],
+  "releases": [],
   "designTokens": [],
   "components": [],
   "experienceTemplates": [],
@@ -365,6 +370,8 @@ _Note:_ Tags feature is not available for all users. If you do not have access t
 
 _Note:_ `designTokens`, `components`, `experienceTemplates`, `dataAssemblies`, `experienceFragments`, and `experiences` are Experience Orchestration (ExO) entities — present by default; absent only if you explicitly set `includeExperienceOrchestration: false` — see the "Experience Orchestration (ExO) entities" section below.
 
+_Note:_ `releases` is present by default; absent only if you explicitly set `skipReleases: true` — see the "Releases" section below. It's a separate, GA Contentful feature, not part of ExO.
+
 ## :test_tube: Experience Orchestration (ExO) entities
 
 Experience Orchestration (ExO) is Contentful's system for composing and rendering structured page experiences. It sits above the traditional entry/content-type layer and provides six dedicated entity types — Design Tokens, Components, Experience Templates, Data Assemblies, Experience Fragments, and Experiences — that together describe how content is fetched, assembled, and laid out.
@@ -389,10 +396,41 @@ 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: Releases
+
+[Releases](https://www.contentful.com/help/releases/) (Timeline) is a separate, GA Contentful feature — not part of Experience Orchestration, and gated by its own organization entitlement rather than `exoM1`.
+
+Releases export is on by default (`skipReleases: false`) — for the CLI and the module API alike. Pass `skipReleases: true` (`--skip-releases` on the CLI) to opt out.
+
+Only releases with `sys.schemaVersion: "Release.v2"` ("Releases") are fetched. `Release.v1` ("Launch") releases are excluded by the export query itself, since [`contentful-import`](https://github.com/contentful/contentful-import) only supports `Release.v2` on the import side.
+
+Only active Releases are exported. Archived Releases are omitted, regardless of `includeArchived`, because that option currently applies only to entries and assets.
+
+If the source space's organization lacks the Releases entitlement, or the fetch otherwise fails, a `Skipping Releases export` warning is logged and `releases` exports as an empty array — it does not fail the export.
+
+Round-trips into [`contentful-import`](https://github.com/contentful/contentful-import), which imports each release found in the exported data. See `contentful-import`'s README "Releases" section for the import-side details, including a real limitation worth knowing before you rely on this for repeated imports: Releases have no ID-preserving create, so re-importing the same export creates additional releases rather than updating existing ones.
+
 ## :warning: Limitations
 
 - This tool currently does **not** support the export of space memberships.

package/dist/index.js

@@ -80,8 +80,10 @@ function runContentfulExport(params) {
         skipWebhooks: options.skipWebhooks,
         skipRoles: options.skipRoles,
         skipTags: options.skipTags,
+        skipReleases: options.skipReleases,
         stripTags: options.stripTags,
         includeExperienceOrchestration: options.includeExperienceOrchestration,
+        includeExoVariants: options.includeExoVariants,
         listrOptions,
         queryEntries: options.queryEntries,
         queryAssets: options.queryAssets
@@ -131,6 +133,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 +142,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

@@ -29,9 +29,11 @@ function parseOptions(params) {
     skipAssets: false,
     skipWebhooks: false,
     skipTags: false,
+    skipReleases: false,
     stripTags: false,
     maxAllowedLimit: 1000,
     includeExperienceOrchestration: true,
+    includeExoVariants: false,
     saveFile: true,
     useVerboseRenderer: false,
     rawProxy: false
@@ -87,6 +89,7 @@ function parseOptions(params) {
     options.skipRoles = true;
     options.skipContentModel = true;
     options.skipWebhooks = true;
+    options.skipReleases = true;
   }
   options.application = options.managementApplication || `contentful.export/${_package.version}`;
   options.feature = options.managementFeature || 'library-export';

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

@@ -33,11 +33,13 @@ function getFullSourceSpace({
   skipRoles,
   skipEditorInterfaces,
   skipTags,
+  skipReleases,
   stripTags,
   includeDrafts,
   includeArchived,
   maxAllowedLimit,
   includeExperienceOrchestration,
+  includeExoVariants,
   listrOptions,
   queryEntries,
   queryAssets
@@ -170,6 +172,29 @@ function getFullSourceSpace({
       });
     }),
     skip: () => skipRoles || environmentId !== 'master' && 'Roles can only be exported from master environment'
+  }, {
+    title: 'Fetching Releases data',
+    task: (0, _contentfulBatchLibs.wrapTask)(async ctx => {
+      try {
+        // Excludes releases created internally by other Contentful features (rather than by a
+        // user directly), so they don't leak into a customer's export as if they were
+        // user-authored Releases.
+        const releases = await cursorPagedGet(query => client.release.query({
+          environmentId,
+          spaceId,
+          query: _objectSpread({
+            'metadata.annotations.Contentful:Timeline.type[nin]': 'Staging,Hidden',
+            'sys.schemaVersion': 'Release.v2',
+            'sys.status[in]': 'active'
+          }, query)
+        }));
+        ctx.data.releases = releases;
+      } catch (err) {
+        _contentfulBatchLibs.logEmitter.emit('warning', `Skipping Releases export: ${err.message}`);
+        ctx.data.releases = [];
+      }
+    }),
+    skip: () => skipReleases
   }, {
     title: 'Fetching Design Tokens data',
     task: (0, _contentfulBatchLibs.wrapTask)(async ctx => {
@@ -260,6 +285,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 +364,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

@@ -57,6 +57,10 @@ var _default = exports.default = _yargs.default.version(_package.default.version
   describe: 'Skip exporting webhooks',
   type: 'boolean',
   default: false
+}).option('skip-releases', {
+  describe: 'Skip exporting Releases',
+  type: 'boolean',
+  default: false
 }).options('strip-tags', {
   describe: 'Untag assets and entries',
   type: 'boolean',
@@ -111,6 +115,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.5.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",