docs: clarify embargoed asset migration [AIS-179]

docs/space/export/README.md

@@ -66,6 +66,28 @@ Options:
 contentful space export
 ```
 
+### Embargoed assets
+
+When moving content from a space with [embargoed assets](https://www.contentful.com/help/media/embargoed-assets/), download the asset files during export. The corresponding import must upload those local files into the destination environment instead of asking the destination to fetch the source URLs.
+
+```sh
+contentful space export \
+  --space-id "$SPACE_ID" \
+  --environment-id "$SOURCE_ENVIRONMENT_ID" \
+  --download-assets \
+  --export-dir ./contentful-export \
+  --content-file content.json
+
+contentful space import \
+  --space-id "$SPACE_ID" \
+  --environment-id "$TARGET_ENVIRONMENT_ID" \
+  --content-file ./contentful-export/content.json \
+  --upload-assets \
+  --assets-directory ./contentful-export
+```
+
+The `--assets-directory` value must be the directory generated by `--export-dir`. If an existing export contains embargoed asset URLs but no downloaded files, create the export again with `--download-assets`.
+
 ## Exported data
 
 ```js
@@ -84,4 +106,3 @@ contentful space export
 - This tool currently does **not** support the export of space memberships.
 - Exported webhooks with credentials will be exported as normal webhooks. Credentials should be added manually afterwards.
 - UI extensions will not be exported
-- If a space is configured to use the [embargoed assets feature](https://www.contentful.com/help/media/embargoed-assets/), certain options will need to be set to use the space export/import tooling. When exporting content, the `downloadAssets` option must be set to `true`. This will download the asset files to your local machine. Then, when importing content, the `uploadAssets` option must be set to `true` and the `assetsDirectory` must be set to the directory that contains all of the exported asset folders.

docs/space/import/README.md

@@ -51,10 +51,24 @@ contentful space import \
   --content-file exported-file.json \
 ```
 
+### Embargoed assets
+
+When importing content from a space with [embargoed assets](https://www.contentful.com/help/media/embargoed-assets/), the export must have been created with `--download-assets`. Pass both `--upload-assets` and `--assets-directory` so the importer uploads the local files into the destination environment.
+
+```sh
+contentful space import \
+  --space-id "$SPACE_ID" \
+  --environment-id "$TARGET_ENVIRONMENT_ID" \
+  --content-file ./contentful-export/content.json \
+  --upload-assets \
+  --assets-directory ./contentful-export
+```
+
+Without the downloaded files, the destination cannot process the source embargoed URLs and the import will fail before it starts with guidance for creating a portable export.
+
 ## Limitations
 
 - This tool currently does **not** support the import of roles or space memberships.
 - This tool is expecting the target space to have the same default locale as your previously exported space.
 - Imported webhooks with credentials will be imported as normal webhooks. Credentials should be added manually afterwards.
 - If you have custom UI extensions, you need to reinstall them manually in the new space. Check this [link](https://www.contentful.com/blog/2016/07/06/ui-extensions-sdk/) on how to install them
-- If a space is configured to use the [embargoed assets feature](https://www.contentful.com/help/media/embargoed-assets/), certain options will need to be set to use the space export/import tooling. When exporting content, the `downloadAssets` option must be set to `true`. This will download the asset files to your local machine. Then, when importing content, the `uploadAssets` option must be set to `true` and the `assetsDirectory` must be set to the directory that contains all of the exported asset folders.

lib/cmds/space_cmds/import.ts

@@ -104,13 +104,13 @@ export const builder = (yargs: Argv) => {
     })
     .option('upload-assets', {
       describe:
-        'Upload local asset files downloaded via the --downloadAssets option of the export. Requires `assetsDirectory`',
+        'Upload local asset files downloaded via the --download-assets option of `contentful space export`. Requires `--assets-directory`',
       type: 'boolean',
       default: false
     })
     .option('assets-directory', {
       describe:
-        'Path to a directory with an asset export made using the --downloadAssets option of the export. Requires `uploadAssets`',
+        'Path to a directory with an asset export made using the --download-assets option of `contentful space export`. Requires `--upload-assets`',
       type: 'string'
     })
     .config(

package.json

@@ -92,7 +92,7 @@
     "contentful-batch-libs": "^11.0.0",
     "contentful-collection": "^0.0.4",
     "contentful-export": "^8.2.0",
-    "contentful-import": "^10.1.2",
+    "contentful-import": "^10.2.2",
     "contentful-management": "^12.13.0",
     "contentful-migration": "^5.0.0",
     "emojic": "^1.1.11",

test/integration/cmds/space/__snapshots__/import.test.js.snap

@@ -44,13 +44,14 @@ Options:
                                       operation fails     [number] [default: 10]
   --header, -H                        Pass an additional HTTP Header    [string]
   --upload-assets                     Upload local asset files downloaded via
-                                      the --downloadAssets option of the export.
-                                      Requires \`assetsDirectory\`
+                                      the --download-assets option of
+                                      \`contentful space export\`. Requires
+                                      \`--assets-directory\`
                                                       [boolean] [default: false]
   --assets-directory                  Path to a directory with an asset export
-                                      made using the --downloadAssets option of
-                                      the export. Requires \`uploadAssets\`
-                                                                        [string]
+                                      made using the --download-assets option of
+                                      \`contentful space export\`. Requires
+                                      \`--upload-assets\`                 [string]
   --config                            An optional configuration JSON file
                                       containing all the options for a single
                                       run
@@ -103,13 +104,14 @@ Options:
                                       operation fails     [number] [default: 10]
   --header, -H                        Pass an additional HTTP Header    [string]
   --upload-assets                     Upload local asset files downloaded via
-                                      the --downloadAssets option of the export.
-                                      Requires \`assetsDirectory\`
+                                      the --download-assets option of
+                                      \`contentful space export\`. Requires
+                                      \`--assets-directory\`
                                                       [boolean] [default: false]
   --assets-directory                  Path to a directory with an asset export
-                                      made using the --downloadAssets option of
-                                      the export. Requires \`uploadAssets\`
-                                                                        [string]
+                                      made using the --download-assets option of
+                                      \`contentful space export\`. Requires
+                                      \`--upload-assets\`                 [string]
   --config                            An optional configuration JSON file
                                       containing all the options for a single
                                       run