storyblok-backup 0.4.1 → 0.6.0

package/.env.example

@@ -1,3 +1,3 @@
-STORYBLOK_OAUTH_TOKEN=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
-STORYBLOK_SPACE_ID=123456
+STORYBLOK_OAUTH_TOKEN=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
+STORYBLOK_SPACE_ID=123456
 STORYBLOK_REGION=eu

package/README.md

@@ -5,7 +5,7 @@
 
 A npx CLI tool to create a full backup of a space of the [Storyblok CMS](https://www.storyblok.com).
 
-A restore tool to restore (create or update) resources is also included.
+A limited restore tool to restore (create or update) single resources is also included. A full restore-tool is available in a separate package: [netgen/storyblok-restore](https://github.com/netgen/storyblok-restore)
 
 The backup script will fetch the following resources of a Storyblok space using the Management API and archive them in a zip file:
 
@@ -38,6 +38,8 @@ The restore script is able to individually restore the resources from the backup
 - Workflow stage changes: No update possible.
 - Access Tokens: Creating access tokens from backup makes no sense, since it will result in a new token-string.
 
+For a much more feature-rich full restore-tool see [netgen/storyblok-restore](https://github.com/netgen/storyblok-restore).
+
 ## Table of contents
 
 - [Installation](#installation)
@@ -83,51 +85,52 @@ Call `npx storyblok-backup` with the following options:
 #### Backup options
 
 ```text
---token <token>     (required) Personal OAuth access token created
-                    in the account settings of a Stoyblok user.
-                    (NOT the Access Token of a Space!)
-                    Alternatively, you can set the STORYBLOK_OAUTH_TOKEN environment variable.
---space <space_id>  (required) ID of the space to backup
-                    Alternatively, you can set the STORYBLOK_SPACE_ID environment variable.
---region <region>   Region of the space. Possible values are:
-                    - 'eu' (default): EU
-                    - 'us': US
-                    - 'ap': Australia
-                    - 'ca': Canada
-                    - 'cn': China
-                    Alternatively, you can set the STORYBLOK_REGION environment variable.
---types <types>     Comma separated list of resource-types to backup. Defaults to all.
-                    Possible values are:
-                    - 'stories'
-                    - 'collaborators'
-                    - 'components'
-                    - 'component-groups'
-                    - 'assets'
-                    - 'asset-folders'
-                    - 'internal-tags'
-                    - 'datasources'
-                    - 'space'
-                    - 'space-roles'
-                    - 'tasks'
-                    - 'activities'
-                    - 'presets'
-                    - 'field-types'
-                    - 'webhooks'
-                    - 'workflow-stages'
-                    - 'workflow-stage-changes'
-                    - 'workflows'
-                    - 'releases'
-                    - 'pipeline-branches'
-                    - 'access-tokens'
---with-asset-files  Downloads all files (assets) of the space. Defaults to false.
---output-dir <dir>  Directory to write the backup to. Defaults to ./.output
-                    (ATTENTION: Will fail if the directory already exists!)
---force             Force deletion and recreation of existing output directory.
---create-zip        Create a zip file of the backup. Defaults to false.
---zip-prefix <dir>  Prefix for the zip file. Defaults to 'backup'.
-                    (The suffix will automatically be the current date.)
---verbose           Will show detailed output for every file written.
---help              Show this help
+--token <token>       (required) Personal OAuth access token created
+                      in the account settings of a Stoyblok user.
+                      (NOT the Access Token of a Space!)
+                      Alternatively, you can set the STORYBLOK_OAUTH_TOKEN environment variable.
+--space <space_id>    (required) ID of the space to backup
+                      Alternatively, you can set the STORYBLOK_SPACE_ID environment variable.
+--region <region>     Region of the space. Possible values are:
+                      - 'eu' (default): EU
+                      - 'us': US
+                      - 'ap': Australia
+                      - 'ca': Canada
+                      - 'cn': China
+                      Alternatively, you can set the STORYBLOK_REGION environment variable.
+--types <types>       Comma separated list of resource-types to backup (default=all).
+                      Possible values are:
+                      - 'stories'
+                      - 'collaborators'
+                      - 'components'
+                      - 'component-groups'
+                      - 'assets'
+                      - 'asset-folders'
+                      - 'internal-tags'
+                      - 'datasources'
+                      - 'space'
+                      - 'space-roles'
+                      - 'tasks'
+                      - 'activities'
+                      - 'presets'
+                      - 'field-types'
+                      - 'webhooks'
+                      - 'workflow-stages'
+                      - 'workflow-stage-changes'
+                      - 'workflows'
+                      - 'releases'
+                      - 'pipeline-branches'
+                      - 'access-tokens'
+--omit-types <types>  Comma separated list of resource-types to omit.
+--with-asset-files    Downloads all files (assets) of the space (default=false).
+--output-dir <dir>    Directory to write the backup to (default=./.output)
+                      (ATTENTION: Will fail if the directory already exists!)
+--force               Force deletion and recreation of existing output directory.
+--create-zip          Create a zip file of the backup (default=false).
+--zip-prefix <dir>    Prefix for the zip file. (default='backup').
+                      (The suffix will automatically be the current date.)
+--verbose             Will show detailed output for every file written.
+--help                Show this help
 ```
 
 OAuth token, space-id and region can be set via environment variables. You can also use a `.env` file in your project root for this (see `.env.example`).
@@ -160,7 +163,7 @@ This will create the folder `./my-dir/backup`, fetch all resources (incl. the or
 
 #### Continuous backup integration examples
 
-You can use this script to create periodic backups of Storyblok spaces using GitHub Actions and artifacts, or commit each content change to a git repository usint Storyblok's webhooks.
+You can use this script to create periodic backups of Storyblok spaces using GitHub Actions and artifacts, or commit each content change to a git repository using Storyblok's webhooks.
 
 ##### Example for a GitHub workflow for a complete backup as an artifact
 
@@ -225,7 +228,7 @@ Also keep in mind, that there is a limit on artifact storage and runner minutes
 
 ##### Example for a GitHub workflow for an incremental git-commit-based backup
 
-The following workflow should run via webhook on every relevant change (e.g.publish) in Storyblok. It creates a new current backup (excl. asset files) and commits them to the current repository in the `backup` folder. This enables an incremental git-commit-based backup of all Storyblok-content.
+The following workflow should run via webhook on every relevant change (e.g.publish) in Storyblok. It creates a new current backup (excl. asset files and resources of types access-tokens, activities and workflow-stage-changes) and commits them to the current repository in the `backup` folder. This enables an incremental git-commit-based backup of all Storyblok-content.
 
 ```yaml
 name: Incremental Repository Backup
@@ -256,7 +259,7 @@ jobs:
         env:
           STORYBLOK_OAUTH_TOKEN: ${{ secrets.STORYBLOK_OAUTH_TOKEN }}
           STORYBLOK_SPACE_ID: ${{ secrets.STORYBLOK_SPACE_ID }}
-        run: npx storyblok-backup
+        run: npx storyblok-backup --omit-types "access-tokens,activities,workflow-stage-changes"
 
       - name: Copy files into repository
         run: |
@@ -281,9 +284,11 @@ A webhook to the URL `https://api.github.com/repos/{owner}/{repo}/dispatches` mu
 
 ### Restore
 
+(NOTE: The included restore functionality is limited to restoring only single documents, and not full spaces. For a much more feature-rich full restore-tool see [netgen/storyblok-restore](https://github.com/netgen/storyblok-restore).)
+
 Make sure to install the package first (see [Installation](#installation)).
 
-Call `npx storyblok-restore` with the following options:
+Call `npx storyblok-backup-restore` with the following options:
 
 #### Restore options
 
@@ -338,7 +343,7 @@ Call `npx storyblok-restore` with the following options:
 #### Minimal restore example
 
 ```shell
-npx storyblok-restore --token 1234567890abcdef --space 12345 --type story --file ./.output/backup/123456789.json
+npx storyblok-backup-restore --token 1234567890abcdef --space 12345 --type story --file ./.output/backup/123456789.json
 ```
 
 This will restore the story from the stated file by updating it.
@@ -346,7 +351,7 @@ This will restore the story from the stated file by updating it.
 #### Maximal restore example
 
 ```shell
-npx storyblok-restore \
+npx storyblok-backup-restore \
   --token 1234567890abcdef \
   --space 12345 \
   --region ap \

package/bin/{storyblok-restore.mjs → storyblok-backup-restore.mjs}

@@ -8,7 +8,7 @@ import dotenvx from '@dotenvx/dotenvx'
 
 const startTime = performance.now()
 
-dotenvx.config({ quiet: true })
+dotenvx.config({ quiet: true, ignore: ['MISSING_ENV_FILE'] })
 
 const resourceTypes = [
 	'story',
@@ -37,7 +37,7 @@ const args = minimist(process.argv.slice(2))
 
 if ('help' in args) {
 	console.log(`USAGE
-  $ npx storyblok-restore
+  $ npx storyblok-backup-restore
   
 OPTIONS
   --token <token>     (required) Personal OAuth access token created
@@ -69,10 +69,10 @@ OPTIONS
   --help              Show this help
 
 MINIMAL EXAMPLE
-  $ npx storyblok-restore --token 1234567890abcdef --space 12345 --type story --file ./.output/backup/123456789.json
+  $ npx storyblok-backup-restore --token 1234567890abcdef --space 12345 --type story --file ./.output/backup/123456789.json
 
 MAXIMAL EXAMPLE
-  $ npx storyblok-restore \\
+  $ npx storyblok-backup-restore \\
       --token 1234567890abcdef \\
       --space 12345 \\
       --region ap \\
@@ -154,6 +154,19 @@ if (propagate && args.type !== 'story') {
 	process.exit(1)
 }
 
+// Output General information
+console.log('')
+console.log(`Restoring backup in space ${spaceId}:`)
+console.log(`- resource type: ${args.type}`)
+console.log(`- file: ${args.file}`)
+if ('id' in args) {
+	console.log(`- datasource id: ${args.id}`)
+}
+console.log(`- mode: ${'create' in args ? 'create' : 'update'}`)
+console.log(`- publish: ${'publish' in args ? 'yes' : 'no'}`)
+console.log(`- propagate: ${'propagate' in args ? 'yes' : 'no'}`)
+console.log('')
+
 // Init Management API
 const StoryblokMAPI = new StoryblokClient({
 	oauthToken: oauthToken,

package/bin/storyblok-backup.mjs

@@ -11,7 +11,7 @@ import dotenvx from '@dotenvx/dotenvx'
 
 const startTime = performance.now()
 
-dotenvx.config({ quiet: true })
+dotenvx.config({ quiet: true, ignore: ['MISSING_ENV_FILE'] })
 
 let resourceTypes = [
 	'stories',
@@ -44,31 +44,32 @@ if ('help' in args) {
   $ npx storyblok-backup
   
 OPTIONS
-  --token <token>     (required) Personal OAuth access token created
-                      in the account settings of a Stoyblok user.
-                      (NOT the Access Token of a Space!)
-                      Alternatively, you can set the STORYBLOK_OAUTH_TOKEN environment variable.
-  --space <space_id>  (required) ID of the space to backup
-                      Alternatively, you can set the STORYBLOK_SPACE_ID environment variable.
-  --region <region>   Region of the space. Possible values are:
-                      - 'eu' (default): EU
-                      - 'us': US
-                      - 'ap': Australia
-                      - 'ca': Canada
-                      - 'cn': China
-                      Alternatively, you can set the STORYBLOK_REGION environment variable.
-  --types <types>     Comma separated list of resource-types to backup (default=all).
-                      Possible values are:
-                      - '${resourceTypes.join("'\n                      - '")}'
-  --with-asset-files  Downloads all files (assets) of the space (default=false).
-  --output-dir <dir>  Directory to write the backup to (default=./.output)
-                      (ATTENTION: Will fail if the directory already exists!)
-  --force             Force deletion and recreation of existing output directory.
-  --create-zip        Create a zip file of the backup (default=false).
-  --zip-prefix <dir>  Prefix for the zip file. (default='backup').
-                      (The suffix will automatically be the current date.)
-  --verbose           Will show detailed output for every file written.
-  --help              Show this help
+  --token <token>       (required) Personal OAuth access token created
+                        in the account settings of a Stoyblok user.
+                        (NOT the Access Token of a Space!)
+                        Alternatively, you can set the STORYBLOK_OAUTH_TOKEN environment variable.
+  --space <space_id>    (required) ID of the space to backup
+                        Alternatively, you can set the STORYBLOK_SPACE_ID environment variable.
+  --region <region>     Region of the space. Possible values are:
+                        - 'eu' (default): EU
+                        - 'us': US
+                        - 'ap': Australia
+                        - 'ca': Canada
+                        - 'cn': China
+                        Alternatively, you can set the STORYBLOK_REGION environment variable.
+  --types <types>       Comma separated list of resource-types to backup (default=all).
+                        Possible values are:
+                        - '${resourceTypes.join("'\n                      - '")}'
+  --omit-types <types>  Comma separated list of resource-types to omit.
+  --with-asset-files    Downloads all files (assets) of the space (default=false).
+  --output-dir <dir>    Directory to write the backup to (default=./.output)
+                        (ATTENTION: Will fail if the directory already exists!)
+  --force               Force deletion and recreation of existing output directory.
+  --create-zip          Create a zip file of the backup (default=false).
+  --zip-prefix <dir>    Prefix for the zip file. (default='backup').
+                        (The suffix will automatically be the current date.)
+  --verbose             Will show detailed output for every file written.
+  --help                Show this help
 
 MINIMAL EXAMPLE
   $ npx storyblok-backup --token 1234567890abcdef --space 12345
@@ -79,6 +80,7 @@ MAXIMAL EXAMPLE
       --space 12345 \\
       --region ap \\
       --types "stories,components" \\
+      --omit-types "activities" \\
       --with-asset-files \\
       --output-dir ./my-dir \\
       --force \\
@@ -128,6 +130,11 @@ if ('types' in args) {
 	resourceTypes = typesToBackup
 }
 
+if ('omit-types' in args) {
+	const typesToOmit = args['omit-types'].split(',')
+	resourceTypes = resourceTypes.filter((type) => !typesToOmit.includes(type))
+}
+
 const verbose = 'verbose' in args
 
 const outputDir = args['output-dir'] || './.output'
@@ -156,11 +163,17 @@ const fileName =
 
 const filePath = `${outputDir}/${fileName}`
 
+// Output General information
+console.log('')
 console.log(`Creating backup for space ${spaceId}:`)
-console.log(`Output dir: ${outputDir}`)
+console.log(`- output dir: ${outputDir}`)
 if ('create-zip' in args) {
-	console.log(`Output zip: ${filePath}`)
+	console.log(`- output zip: ${filePath}`)
 }
+console.log(`- resource types: ${resourceTypes.join(', ')}`)
+console.log(`- with asset files: ${'with-asset-files' in args ? 'yes' : 'no'}`)
+console.log(`- force output folder: ${'force' in args ? 'yes' : 'no'}`)
+console.log('')
 
 // Init Management API
 const StoryblokMAPI = new StoryblokClient({
@@ -179,6 +192,11 @@ resourceTypes.forEach(
 	(resource) => resource === 'space' || fs.mkdirSync(`${backupDir}/${resource}`)
 )
 
+// Create separate directory for asset-files
+if (resourceTypes.includes('assets') && 'with-asset-files' in args) {
+	fs.mkdirSync(`${backupDir}/asset-files`)
+}
+
 // Function to perform a default fetch
 const defaultFetch = async (endpoint, type, fileField, fileFieldObject) => {
 	if (resourceTypes.includes(type)) {
@@ -282,7 +300,7 @@ if (resourceTypes.includes('assets')) {
 				if ('with-asset-files' in args) {
 					const fileExtension = asset.filename.split('.').at(-1)
 					const fileName = asset.id + '.' + fileExtension
-					await downloadFile('assets', fileName, asset.filename)
+					await downloadFile('asset-files', fileName, asset.filename)
 				}
 			}
 		})

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "storyblok-backup",
-	"version": "0.4.1",
+	"version": "0.6.0",
 	"description": "npx CLI tool to create a full backup of a Storyblok space and restore single resources from it.",
 	"scripts": {
 		"upgrade": "npx npm-check-updates -i -u && pnpm install",
@@ -13,7 +13,7 @@
 	},
 	"bin": {
 		"storyblok-backup": "bin/storyblok-backup.mjs",
-		"storyblok-restore": "bin/storyblok-restore.mjs"
+		"storyblok-backup-restore": "bin/storyblok-backup-restore.mjs"
 	},
 	"repository": {
 		"type": "git",