Restore functionality and TS setup

storyblok-assets-backup/package.json

@@ -1,25 +1,40 @@
 {
   "name": "storyblok-assets-backup",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Tool for differential backups of the assets of any Storyblok space.",
-  "main": "src/backup.js",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/backup.d.ts",
+  "files": [
+    "dist/**/*"
+  ],
   "type": "module",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsc",
+    "start": "ts-node src/index.ts"
   },
   "author": "Christian Zoppi",
   "contributors": [
     {
-      "name" : "Gerrit Plehn",
-      "email" : "[email protected]"
+      "name": "Gerrit Plehn",
+      "email": "[email protected]"
     }
   ],
   "license": "MIT",
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.916.0",
     "async": "^3.2.1",
-    "aws-sdk": "^2.974.0",
-    "axios": "^0.21.1",
+    "axios": "^0.27.2",
+    "chalk": "^5.6.2",
     "glob": "^7.1.7",
-    "storyblok-js-client": "^4.1.3"
+    "storyblok-js-client": "^7.1.5"
+  },
+  "devDependencies": {
+    "@types/async": "^3.2.25",
+    "@types/form-data": "^2.2.1",
+    "@types/glob": "^8.1.0",
+    "@types/node": "^24.9.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
   }
 }

storyblok-assets-backup/readme.md

@@ -1,10 +1,10 @@
 Name | Description | Author
 ------------ | ------------- | -------------
-Storyblok Assets Backup | Tool for differential backups of the assets of any Storyblok space | [Christian Zoppi](https://github.com/christianzoppi), [Gerrit Plehn](https://github.com/GerritPlehn) 
+| Storyblok Assets Backup | Tool for differential backups of the assets from any Storyblok space | [Christian Zoppi](https://github.com/christianzoppi), [Gerrit Plehn](https://github.com/GerritPlehn) |
 
 <div align="center">
 	<h1 align="center">Storyblok Assets Backup</h1>
-	<p align="center">This is the script to perform incremental backups of assets uploaded in <a href="http://www.storyblok.com?utm_source=github.com&utm_medium=readme&utm_campaign=assets-backup" target="_blank">Storyblok</a> to your local machine or an S3 bucket.</p>
+	<p align="center">A script for performing incremental backups of assets uploaded to <a href="http://www.storyblok.com?utm_source=github.com&utm_medium=readme&utm_campaign=assets-backup" target="_blank">Storyblok</a>, either locally or to an S3 bucket.</p>
 </div>
 
 <p align="center">
@@ -21,10 +21,11 @@ Storyblok Assets Backup | Tool for differential backups of the assets of any Sto
 
 ## 🚀 Usage
 
-Backup all the assets of your spaces. You can perform the backup for specific spaces or for all of them. The backup is incremental, so it will save just what is missing from your current backup. Backups can be performed locally or on an S3 bucket.
+Backup all assets from your Storyblok spaces. You can back up specific spaces or all of them. The process is incremental — it only saves files missing from your current backup. Backups can be stored locally or in an S3 bucket.
 
 ### Getting Started
-You need to place the package on your machine or on your server and you can install it with `npm i <folder>`. This is an example of how you can use this package. 
+
+Place the package on your machine or server, then install it using `npm i <folder>`. Here’s an example of how to use it:
 
 ```js
 import SbBackup from 'storyblok-assets-backup'
@@ -44,57 +45,92 @@ sbBackup.backupAllSpaces()
 ```
 
 ### Settings
-The settings of the constructor of the class `SbBackup` are:
-- **token**: the oauth token of your Storyblok account. You can retrieve it [here](https://app.storyblok.com/#!/me/account);  
-- **storage**: the value can be `local` or `s3`. `local` will make the script store files on a local folder. You can [read more here](#data-structure) about the folders and the data structure;
-- **basePath**: optional, defaults to `./backups` - this is the path of the backup folder in case you are performing a local backup;
-- **s3Settings.accessKeyId**: optional - this is the IAM access key id for authentication on your S3 bucket;  
-- **s3Settings.secretAccessKey**: optional - this is the IAM secret access key for authentication on your S3 bucket.
-- **metadata**: optional, defaults to `true` - indicates if metadata should be checked for updates. If metadata changed the asset will be backed up again.
+
+Constructor options for the `SbBackup` class:
+
+* **token**: Your Storyblok account OAuth token. Retrieve it [here](https://app.storyblok.com/#!/me/account).
+* **storage**: Either `local` or `s3`. The `local` option stores files in a local folder. See [Data structure](#data-structure) for more details.
+* **basePath**: Optional. Defaults to `./backups`. The local folder path for backups.
+* **s3Settings.accessKeyId**: Optional. Your IAM access key ID for S3 authentication.
+* **s3Settings.secretAccessKey**: Optional. Your IAM secret access key for S3 authentication.
+* **metadata**: Optional. Defaults to `true`. When enabled, the script checks for metadata changes and re-backs up assets if needed.
 
 ### Methods
-All instances of the `SbBackup` class can perform 2 actions: backup a space or backup all the spaces.
+
+Instances of the `SbBackup` class can perform two actions: backing up a space or backing up all spaces.
 
 #### SbBackup.backupSpace(spaceId)
-This method can backup a single space. You have to provide the space id as an argument.
 
-**Example**:
+Backs up a single space. Provide the space ID as an argument.
+
+**Example:**
+
 ```
 sbBackup.backupSpace(123456)
 ```
 
 #### SbBackup.backupAllSpaces()
-This method can backup all the spaces in your account.
 
-**Example**:
+Backs up all spaces in your account.
+
+**Example:**
+
 ```
 sbBackup.backupAllSpaces()
 ```
 
+#### SbBackup.restoreAssets(spaceId, assetsIds)
+
+Restores one or more assets to your space. Currently available only for `local` backups (not S3).
+If your backup is in S3, download it to `backup/{SPACE_ID}` in your project root before running the script locally.
+Each asset folder should follow this structure: `backup/{SPACE_ID}/{ASSET_ID}`. Once stored locally, run the script using the `local` storage type to restore your assets.
+
+Restoration directly from S3 is not yet planned.
+
+`spaceId`: The ID of your Storyblok space.
+`assetsIds`: (Optional) An array of asset IDs to restore, e.g. `[12345, 12346, 393089]`. If empty, all assets will be restored.
+
+**Example:**
+
+```js
+// Restore only 2 assets
+sbBackup.restoreAssets(1234, [78789, 3332])
+// Restore all assets
+sbBackup.restoreAssets(1234) 
+```
+
 ### Data structure
-The script will store and organise the content by creating a folder for each space, the folder will have the id of the space. Inside the folder of the space there will be a folder with the id of each asset. Inside the folder of each asset there will be the asset itself and a file called `sb_asset_data_[TIMESTAMP].json` with the [Asset Object](https://www.storyblok.com/docs/api/management#core-resources/assets/the-asset-object) from the Storyblok MAPI. The structure will be the same for both the `local` and the `s3` backups.
 
-When performing the S3 backup the script will create a `./temp` folder to store the files temporarily before sending them to the bucket.
+The script organizes backups into folders by space ID.
+Inside each space folder, there’s a folder for every asset (named by asset ID).
+Each asset folder contains:
+
+* The asset file itself
+* A `sb_asset_data_[TIMESTAMP].json` file with the [Asset Object](https://www.storyblok.com/docs/api/management#core-resources/assets/the-asset-object) from the Storyblok MAPI
+
+The structure is identical for both `local` and `s3` backups.
+
+When using S3, the script creates a temporary `./temp` folder before uploading files to the bucket.
 
 ## 🔗 Related Links
 
-* **[Storyblok & Javascript on GitHub](https://github.com/search?q=org%3Astoryblok+topic%3Ajavascript)**: Check all of our Javascript open source repos;
-* **[Technology Hub](https://www.storyblok.com/technologies?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-js-client)**: We prepared technology hubs so that you can find selected beginner tutorials, videos, boilerplates, and even cheatsheets all in one place;
-* **[Storyblok CLI](https://github.com/storyblok/storyblok)**: A simple CLI for scaffolding Storyblok projects and fieldtypes.
+* **[Storyblok & JavaScript on GitHub](https://github.com/search?q=org%3Astoryblok+topic%3Ajavascript)** – Explore all our open-source JavaScript repositories.
+* **[Technology Hub](https://www.storyblok.com/technologies?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-js-client)** – Find curated tutorials, videos, boilerplates, and cheatsheets for various technologies.
+* **[Storyblok CLI](https://github.com/storyblok/storyblok)** – A simple CLI for scaffolding Storyblok projects and field types.
 
 ## ℹ️ More Resources
 
 ### Support
 
-* Bugs or Feature Requests? [Submit an issue](../../../issues/new);
-
-* Do you have questions about Storyblok or you need help? [Join our Discord Community](https://discord.gg/jKrbAMz).
+* Found a bug or want to request a feature? [Open an issue](../../../issues/new).
+* Need help or have questions? [Join our Discord Community](https://discord.gg/jKrbAMz).
 
 ### Contributing
 
-Please see our [contributing guidelines](https://github.com/storyblok/.github/blob/master/contributing.md) and our [code of conduct](https://www.storyblok.com/trust-center#code-of-conduct?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-js-client).
-This project use [semantic-release](https://semantic-release.gitbook.io/semantic-release/) for generate new versions by using commit messages and we use the Angular Convention to naming the commits. Check [this question](https://semantic-release.gitbook.io/semantic-release/support/faq#how-can-i-change-the-type-of-commits-that-trigger-a-release) about it in semantic-release FAQ.
+Please see our [contributing guidelines](https://github.com/storyblok/.github/blob/master/contributing.md) and [code of conduct](https://www.storyblok.com/trust-center#code-of-conduct?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-js-client).
+This project uses [semantic-release](https://semantic-release.gitbook.io/semantic-release/) to generate new versions based on commit messages.
+We follow the Angular commit convention — see [this FAQ entry](https://semantic-release.gitbook.io/semantic-release/support/faq#how-can-i-change-the-type-of-commits-that-trigger-a-release) for details.
 
-### License  
+### License
 
 This repository is published under the [MIT license](LICENSE).