contentful-export 8.1.2 → 8.2.0

package/README.md

@@ -268,6 +268,12 @@ Full path to the error log file
 
 Display progress in new lines instead of displaying a busy spinner and the status in the same line. Useful for CI.
 
+### Experience Orchestration
+
+#### `includeExperienceOrchestration` [boolean] [default: true]
+
+Flag controlling whether Experience Orchestration (ExO) entities — Design Tokens, Components, Experience Templates, Data Assemblies, Experience Fragments, and Experiences — are exported when present in the source space. Requires the `exoM1` entitlement on the source space's organization. Set to `false` to opt out. See the "Experience Orchestration (ExO) entities" section below for what happens when the space isn't entitled.
+
 ## :rescue_worker_helmet: Troubleshooting
 
 ### Proxy
@@ -324,12 +330,48 @@ This is an overview of the exported data:
   "tags": [],
   "webhooks": [],
   "roles": [],
-  "editorInterfaces": []
+  "editorInterfaces": [],
+  "designTokens": [],
+  "components": [],
+  "experienceTemplates": [],
+  "dataAssemblies": [],
+  "experienceFragments": [],
+  "experiences": []
 }
 ```
 
 _Note:_ Tags feature is not available for all users. If you do not have access to this feature, the tags array will always be empty.
 
+_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.
+
+## :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.
+
+> **Experimental:** ExO entities (`designTokens`, `components`, `experienceTemplates`, `dataAssemblies`, `experienceFragments`, `experiences`) are `@internal` and considered experimental. Their shape and export behavior are subject to change without notice.
+
+ExO export is on by default (`includeExperienceOrchestration: true`) — for the CLI and the module API alike. Pass `includeExperienceOrchestration: false` (`--include-experience-orchestration=false` on the CLI) to opt out.
+
+```javascript
+import contentfulExport from 'contentful-export'
+
+const options = {
+  spaceId: '<space_id>',
+  managementToken: '<content_management_api_key>',
+  includeExperienceOrchestration: false // opt out; omit to export ExO entities when present (the default)
+}
+
+await contentfulExport(options)
+```
+
+If the source space has no ExO entities, or lacks the `exoM1` entitlement, each ExO entity type logs a `Skipping <Entity> export` warning and exports as an empty array — it does not fail the export. Pass `includeExperienceOrchestration: false` if you want to avoid it.
+
+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.
+
+### 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.
+
 ## :warning: Limitations
 
 - This tool currently does **not** support the export of space memberships.

package/dist/index.js

@@ -18,8 +18,9 @@ var _formatDistance = require("date-fns/formatDistance");
 var _contentfulBatchLibs = require("contentful-batch-libs");
 var _downloadAssets = _interopRequireDefault(require("./tasks/download-assets"));
 var _getSpaceData = _interopRequireDefault(require("./tasks/get-space-data"));
-var _initClient = _interopRequireDefault(require("./tasks/init-client"));
+var _initClient = _interopRequireWildcard(require("./tasks/init-client"));
 var _parseOptions = _interopRequireDefault(require("./parseOptions"));
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 const accessP = _bluebird.default.promisify(_fs.access);
 const tableOptions = {
@@ -53,6 +54,7 @@ function runContentfulExport(params) {
       try {
         // CMA client
         ctx.client = (0, _initClient.default)(options);
+        ctx.plainClient = (0, _initClient.initPlainClient)(options);
         if (options.deliveryToken && !options.includeDrafts) {
           // CDA client for fetching only public entries
           ctx.cdaClient = (0, _initClient.default)(options, true);
@@ -67,6 +69,7 @@ function runContentfulExport(params) {
     task: ctx => {
       return (0, _getSpaceData.default)({
         client: ctx.client,
+        plainClient: ctx.plainClient,
         cdaClient: ctx.cdaClient,
         spaceId: options.spaceId,
         environmentId: options.environmentId,
@@ -81,6 +84,7 @@ function runContentfulExport(params) {
         skipRoles: options.skipRoles,
         skipTags: options.skipTags,
         stripTags: options.stripTags,
+        includeExperienceOrchestration: options.includeExperienceOrchestration,
         listrOptions,
         queryEntries: options.queryEntries,
         queryAssets: options.queryAssets

package/dist/parseOptions.js

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

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

@@ -18,6 +18,7 @@ let pageLimit = MAX_ALLOWED_LIMIT;
  */
 function getFullSourceSpace({
   client,
+  plainClient,
   cdaClient,
   spaceId,
   environmentId = 'master',
@@ -32,6 +33,7 @@ function getFullSourceSpace({
   includeDrafts,
   includeArchived,
   maxAllowedLimit,
+  includeExperienceOrchestration,
   listrOptions,
   queryEntries,
   queryAssets
@@ -149,6 +151,102 @@ function getFullSourceSpace({
       });
     }),
     skip: () => skipRoles || environmentId !== 'master' && 'Roles can only be exported from master environment'
+  }, {
+    title: 'Fetching Design Tokens data',
+    task: (0, _contentfulBatchLibs.wrapTask)(async ctx => {
+      try {
+        ctx.data.designTokens = await cursorPagedGet({
+          client: plainClient,
+          spaceId,
+          environmentId,
+          method: 'designToken.getMany'
+        });
+      } catch (err) {
+        _contentfulBatchLibs.logEmitter.emit('warning', `Skipping Design Tokens export: ${err.message}`);
+        ctx.data.designTokens = [];
+      }
+    }),
+    skip: () => !includeExperienceOrchestration
+  }, {
+    title: 'Fetching Components data',
+    task: (0, _contentfulBatchLibs.wrapTask)(async ctx => {
+      try {
+        ctx.data.components = await cursorPagedGet({
+          client: plainClient,
+          spaceId,
+          environmentId,
+          method: 'component.getMany'
+        });
+      } catch (err) {
+        _contentfulBatchLibs.logEmitter.emit('warning', `Skipping Components export: ${err.message}`);
+        ctx.data.components = [];
+      }
+    }),
+    skip: () => !includeExperienceOrchestration
+  }, {
+    title: 'Fetching Experience Templates data',
+    task: (0, _contentfulBatchLibs.wrapTask)(async ctx => {
+      try {
+        ctx.data.experienceTemplates = await cursorPagedGet({
+          client: plainClient,
+          spaceId,
+          environmentId,
+          method: 'experienceTemplate.getMany'
+        });
+      } catch (err) {
+        _contentfulBatchLibs.logEmitter.emit('warning', `Skipping Experience Templates export: ${err.message}`);
+        ctx.data.experienceTemplates = [];
+      }
+    }),
+    skip: () => !includeExperienceOrchestration
+  }, {
+    title: 'Fetching Data Assemblies data',
+    task: (0, _contentfulBatchLibs.wrapTask)(async ctx => {
+      try {
+        ctx.data.dataAssemblies = await cursorPagedGet({
+          client: plainClient,
+          spaceId,
+          environmentId,
+          method: 'dataAssembly.getMany'
+        });
+      } catch (err) {
+        _contentfulBatchLibs.logEmitter.emit('warning', `Skipping Data Assemblies export: ${err.message}`);
+        ctx.data.dataAssemblies = [];
+      }
+    }),
+    skip: () => !includeExperienceOrchestration
+  }, {
+    title: 'Fetching Experience Fragments data',
+    task: (0, _contentfulBatchLibs.wrapTask)(async ctx => {
+      try {
+        ctx.data.experienceFragments = await cursorPagedGet({
+          client: plainClient,
+          spaceId,
+          environmentId,
+          method: 'experienceFragment.getMany'
+        });
+      } catch (err) {
+        _contentfulBatchLibs.logEmitter.emit('warning', `Skipping Experience Fragments export: ${err.message}`);
+        ctx.data.experienceFragments = [];
+      }
+    }),
+    skip: () => !includeExperienceOrchestration
+  }, {
+    title: 'Fetching Experiences data',
+    task: (0, _contentfulBatchLibs.wrapTask)(async ctx => {
+      try {
+        ctx.data.experiences = await cursorPagedGet({
+          client: plainClient,
+          spaceId,
+          environmentId,
+          method: 'experience.getMany'
+        });
+      } catch (err) {
+        _contentfulBatchLibs.logEmitter.emit('warning', `Skipping Experiences export: ${err.message}`);
+        ctx.data.experiences = [];
+      }
+    }),
+    skip: () => !includeExperienceOrchestration
   }], listrOptions);
 }
 function getEditorInterfaces(contentTypes) {
@@ -167,6 +265,37 @@ function getEditorInterfaces(contentTypes) {
   });
 }
 
+/**
+ * Gets all ExO entities using cursor-based pagination (pageNext/pagePrev tokens).
+ * ExO list endpoints do not support skip-based pagination or the order param.
+ */
+async function cursorPagedGet({
+  client,
+  spaceId,
+  environmentId,
+  method
+}) {
+  const [entity, operation] = method.split('.');
+  const allItems = [];
+  let pageNext = null;
+  do {
+    var _response$pages$next, _response$pages;
+    const query = {
+      spaceId,
+      environmentId,
+      limit: pageLimit
+    };
+    if (pageNext) {
+      query.pageNext = pageNext;
+    }
+    const response = await client[entity][operation](query);
+    allItems.push(...response.items);
+    _contentfulBatchLibs.logEmitter.emit('info', `Fetched ${allItems.length} ${entity} items`);
+    pageNext = (_response$pages$next = (_response$pages = response.pages) === null || _response$pages === void 0 ? void 0 : _response$pages.next) !== null && _response$pages$next !== void 0 ? _response$pages$next : null;
+  } while (pageNext);
+  return allItems;
+}
+
 /**
  * Gets all the existing entities based on pagination parameters.
  * The first call will have no aggregated response. Subsequent calls will

package/dist/tasks/init-client.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = initClient;
+exports.initPlainClient = initPlainClient;
 var _contentful = require("contentful");
 var _contentfulBatchLibs = require("contentful-batch-libs");
 var _contentfulManagement = require("contentful-management");
@@ -34,4 +35,10 @@ function initClient(opts, useCda = false) {
     type: 'legacy'
   });
 }
-module.exports = exports.default;
+function initPlainClient(opts) {
+  return (0, _contentfulManagement.createClient)({
+    accessToken: opts.managementToken,
+    host: opts.host,
+    logHandler
+  });
+}

package/dist/usageParams.js

@@ -107,6 +107,10 @@ var _default = exports.default = _yargs.default.version(_package.default.version
   describe: 'Display progress in new lines instead of displaying a busy spinner and the status in the same line. Useful for CI.',
   type: 'boolean',
   default: false
+}).option('include-experience-orchestration', {
+  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('header', {
   alias: 'H',
   type: 'string',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contentful-export",
-  "version": "8.1.2",
+  "version": "8.2.0",
   "description": "this tool allows you to export a space to a JSON dump",
   "main": "dist/index.js",
   "types": "types.d.ts",
@@ -51,7 +51,7 @@
     "cli-table3": "^0.6.0",
     "contentful": "^11.5.10",
     "contentful-batch-libs": "^12.0.0",
-    "contentful-management": "^12.10.0",
+    "contentful-management": "^12.14.0",
     "date-fns": "^4.1.0",
     "figures": "^3.2.0",
     "jsonwebtoken": "^9.0.0",
@@ -145,6 +145,6 @@
   },
   "overrides": {
     "cross-spawn": "^7.0.6",
-    "undici": "^6.27.0"
+    "undici": "^8.0.0"
   }
 }

package/types.d.ts

@@ -29,9 +29,10 @@ export interface Options {
   skipWebhooks?: boolean;
   skipTags?: boolean;
   useVerboseRenderer?: boolean;
+  includeExperienceOrchestration?: boolean;
 }
 
-type ContentfulExportField = 'contentTypes' | 'entries' | 'assets' | 'locales' | 'tags' | 'webhooks' | 'roles' | 'editorInterfaces';
+type ContentfulExportField = 'contentTypes' | 'entries' | 'assets' | 'locales' | 'tags' | 'webhooks' | 'roles' | 'editorInterfaces' | 'designTokens' | 'components' | 'experienceTemplates' | 'dataAssemblies' | 'experienceFragments' | 'experiences';
 
 declare const runContentfulExport: (params: Options) => Promise<Record<ContentfulExportField, unknown[]>>
 export default runContentfulExport