@adobe/helix-config-storage 2.5.2 → 2.8.1

package/CHANGELOG.md

@@ -1,3 +1,73 @@
+## [2.8.1](https://github.com/adobe/helix-config-storage/compare/v2.8.0...v2.8.1) (2025-08-22)
+
+
+### Bug Fixes
+
+* back to adobe npm org ([#170](https://github.com/adobe/helix-config-storage/issues/170)) ([092be53](https://github.com/adobe/helix-config-storage/commit/092be5397d19ad2e7151f5def3412ffebd4d5e1f))
+
+# [2.8.0](https://github.com/adobe/helix-config-storage/compare/v2.7.6...v2.8.0) (2025-08-21)
+
+
+### Features
+
+* use POST for restore version ([#169](https://github.com/adobe/helix-config-storage/issues/169)) ([0723da3](https://github.com/adobe/helix-config-storage/commit/0723da321920eb1b4ebd86fc7dc27049e302e30c))
+
+## [2.7.6](https://github.com/adobe/helix-config-storage/compare/v2.7.5...v2.7.6) (2025-08-19)
+
+
+### Bug Fixes
+
+* add status code when initial validation fails ([#167](https://github.com/adobe/helix-config-storage/issues/167)) ([64705e9](https://github.com/adobe/helix-config-storage/commit/64705e9cf90b1fbde3ee3b1ff7faf55da1d715dc))
+
+## [2.7.5](https://github.com/adobe/helix-config-storage/compare/v2.7.4...v2.7.5) (2025-08-14)
+
+
+### Bug Fixes
+
+* **deps:** update dependency @adobe/helix-shared-storage to v1.4.1 ([#166](https://github.com/adobe/helix-config-storage/issues/166)) ([9d3f510](https://github.com/adobe/helix-config-storage/commit/9d3f510a9d8e702582e843b9f4be30ff920375bc))
+
+## [2.7.4](https://github.com/adobe/helix-config-storage/compare/v2.7.3...v2.7.4) (2025-08-13)
+
+
+### Bug Fixes
+
+* proper list sites and profiles ([#165](https://github.com/adobe/helix-config-storage/issues/165)) ([1017a91](https://github.com/adobe/helix-config-storage/commit/1017a91773fd29bcc498f2f20c9b63e06c142dd9))
+
+## [2.7.3](https://github.com/adobe/helix-config-storage/compare/v2.7.2...v2.7.3) (2025-08-12)
+
+
+### Bug Fixes
+
+* **deps:** update adobe fixes ([#164](https://github.com/adobe/helix-config-storage/issues/164)) ([c688e5d](https://github.com/adobe/helix-config-storage/commit/c688e5dc6375f14be529967c4650ab7d60e2e63e))
+
+## [2.7.2](https://github.com/adobe/helix-config-storage/compare/v2.7.1...v2.7.2) (2025-08-12)
+
+
+### Bug Fixes
+
+* update npm package ([77e5607](https://github.com/adobe/helix-config-storage/commit/77e56079a3842ac39cbf71dfcb9eb0531d0086b2))
+
+## [2.7.1](https://github.com/adobe/helix-config-storage/compare/v2.7.0...v2.7.1) (2025-08-12)
+
+
+### Bug Fixes
+
+* **deps:** update adobe fixes ([#163](https://github.com/adobe/helix-config-storage/issues/163)) ([0af5fc4](https://github.com/adobe/helix-config-storage/commit/0af5fc4953a7d106c6f16ac7877dde3dc2d9c090))
+
+# [2.7.0](https://github.com/adobe/helix-config-storage/compare/v2.6.0...v2.7.0) (2025-08-11)
+
+
+### Features
+
+* add versioning apis ([#160](https://github.com/adobe/helix-config-storage/issues/160)) ([1eca459](https://github.com/adobe/helix-config-storage/commit/1eca459d781c3a9f1ed03c539022d55f1146e7c5))
+
+# [2.6.0](https://github.com/adobe/helix-config-storage/compare/v2.5.2...v2.6.0) (2025-08-05)
+
+
+### Features
+
+* include wordSaveDelay in sidekick schema ([0ad3d04](https://github.com/adobe/helix-config-storage/commit/0ad3d048a5b3ee8ee5dbe621b3638ce352d0fc6c))
+
 ## [2.5.2](https://github.com/adobe/helix-config-storage/compare/v2.5.1...v2.5.2) (2025-07-23)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/helix-config-storage",
-  "version": "2.5.2",
+  "version": "2.8.1",
   "description": "Helix Config Storage",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -36,8 +36,8 @@
     "reporter-options": "configFile=.mocha-multi.json"
   },
   "devDependencies": {
-    "@adobe/eslint-config-helix": "3.0.8",
-    "@eslint/config-helpers": "0.3.0",
+    "@adobe/eslint-config-helix": "3.0.9",
+    "@eslint/config-helpers": "0.3.1",
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/git": "10.0.1",
     "@semantic-release/npm": "12.0.2",
@@ -47,7 +47,7 @@
     "husky": "9.1.7",
     "json-schema-to-typescript": "15.0.4",
     "junit-report-builder": "5.1.1",
-    "lint-staged": "16.1.2",
+    "lint-staged": "16.1.5",
     "mocha": "11.7.1",
     "mocha-multi-reporters": "1.5.1",
     "mocha-suppress-logs": "0.6.0",
@@ -64,7 +64,7 @@
     "@adobe/helix-shared-config": "^11.1.4",
     "@adobe/helix-shared-git": "^3.0.18",
     "@adobe/helix-shared-process-queue": "3.1.3",
-    "@adobe/helix-shared-storage": "^1.3.0",
+    "@adobe/helix-shared-storage": "^1.4.0",
     "@adobe/helix-shared-string": "^2.1.0",
     "@adobe/helix-shared-utils": "^3.0.2",
     "ajv": "8.17.1",

package/src/config-store.js

@@ -25,6 +25,7 @@ import {
 import { validate as validateSchema } from './config-validator.js';
 import { getMergedConfig } from './config-merge.js';
 import { ValidationError } from './ValidationError.js';
+import { ConfigVersioning } from './config-versioning.js';
 
 const FRAGMENTS_COMMON = {
   content: 'object',
@@ -324,6 +325,11 @@ export class ConfigStore {
    */
   #profiles = {};
 
+  /**
+   * @member {ConfigVersioning} versioning the versioning manager
+   */
+  #versioning;
+
   /**
    * @param {string} org the org id
    * @param {string} type store type (org, sites, profiles, secrets, users)
@@ -331,27 +337,28 @@ export class ConfigStore {
    */
   constructor(org, type = 'org', name = '') {
     if (!org) {
-      throw new Error('org required');
+      throw new StatusCodeError(400, 'org required');
     }
     if (org.includes('/') || type.includes('/') || name.includes('/')) {
-      throw new Error('orgId, type and name must not contain slashes');
+      throw new StatusCodeError(400, 'orgId, type and name must not contain slashes');
     }
     if (org.toLowerCase() !== org) {
-      throw new Error('orgId must be lowercase');
+      throw new StatusCodeError(400, 'orgId must be lowercase');
     }
     if (type === 'sites' && name.toLowerCase() !== name) {
-      throw new Error('site must be lowercase');
+      throw new StatusCodeError(400, 'site must be lowercase');
     }
     this.org = org;
     this.type = type;
     this.name = name;
     this.key = type === 'org'
-      ? `/orgs/${org}/${name || 'config'}.json`
+      ? `/orgs/${org}/config.json`
       : `/orgs/${org}/${type}/${name}.json`;
     this.now = new Date();
     this.isAdmin = false;
     this.isOps = false;
     this.listDetails = false;
+    this.#versioning = new ConfigVersioning(org, type, name);
   }
 
   /**
@@ -399,7 +406,7 @@ export class ConfigStore {
   async #list(ctx) {
     const storage = HelixStorage.fromContext(ctx).configBus();
     const key = `orgs/${this.org}/${this.type}/`;
-    const list = await storage.list(key);
+    const list = await storage.list(key, true);
     let entries = list.map((entry) => {
       const siteKey = entry.key;
       if (siteKey.endsWith('.json')) {
@@ -523,6 +530,7 @@ export class ConfigStore {
       throw new StatusCodeError(409, 'create not supported on substructures.');
     }
     const storage = HelixStorage.fromContext(ctx).configBus();
+
     if (await storage.head(this.key)) {
       throw new StatusCodeError(409, 'config already exists.');
     }
@@ -544,13 +552,14 @@ export class ConfigStore {
       }
       data.users = users;
     }
-
     if (this.type !== 'org') {
       updateContentSource(ctx, data.content);
       updateCodeSource(ctx, data.code);
     }
+
     // we don't allow to define created
     delete data.created;
+
     this.#updateTimeStamps(data);
     let oldConfig = {};
     if (this.type === 'sites') {
@@ -561,6 +570,9 @@ export class ConfigStore {
     const config = await this.getAggregatedConfig(ctx, data);
     await this.validate(ctx, config);
     await this.validatePermissions(ctx, oldConfig, config);
+
+    // Create a new version before saving
+    await this.#versioning.createVersion(ctx, data, 'initial');
     await storage.put(this.key, JSON.stringify(data), 'application/json');
     await this.purge(ctx, null, config);
   }
@@ -569,6 +581,12 @@ export class ConfigStore {
     if (this.name === '' && (this.type === 'sites' || this.type === 'profiles')) {
       return this.#list(ctx);
     }
+    if (relPath === 'versions') {
+      return this.listVersions(ctx);
+    }
+    if (relPath.startsWith('versions/')) {
+      return this.getVersion(ctx, Number.parseInt(relPath.substring('versions/'.length), 10));
+    }
 
     const storage = HelixStorage.fromContext(ctx).configBus();
     const buf = await storage.get(this.key);
@@ -584,10 +602,25 @@ export class ConfigStore {
   }
 
   async update(ctx, data, relPath = '') {
+    if (relPath.startsWith('versions/')) {
+      return this.#versioning.updateVersion(ctx, Number.parseInt(relPath.substring('versions/'.length), 10), data.name);
+    }
+    const frag = getFragmentInfo(this.type, relPath);
+    const { restoreVersion } = data ?? {};
+    if (restoreVersion && frag) {
+      throw new StatusCodeError(400, 'restoreVersion not allowed with object path.');
+    }
     const storage = HelixStorage.fromContext(ctx).configBus();
     const buf = await storage.get(this.key);
     let old = buf ? JSON.parse(buf) : null;
-    const frag = getFragmentInfo(this.type, relPath);
+    let { versionName } = data ?? {};
+    delete data?.versionName;
+    if (restoreVersion) {
+      ctx.log.info(`restoring ${this.org}/${this.name} config from version ${restoreVersion}...`);
+      data = await this.#versioning.getVersion(ctx, restoreVersion, true);
+      versionName = `restored from version ${restoreVersion}`;
+    }
+
     let config = data;
     // set config to null if empty object
     if (isDeepEqual(config, {})) {
@@ -761,8 +794,21 @@ export class ConfigStore {
       updateCodeSource(ctx, config.code);
     }
 
-    let oldConfig = buf ? JSON.parse(buf) : null;
-    config.created = oldConfig?.created;
+    let oldConfig = null;
+    let modified = true;
+    if (buf) {
+      oldConfig = JSON.parse(buf);
+      modified = !isDeepEqual({
+        ...oldConfig,
+        lastModified: 'ignore',
+      }, {
+        ...config,
+        lastModified: 'ignore',
+      });
+      config.created = oldConfig.created;
+    } else if (!restoreVersion) {
+      delete config.created; // don't allow to set created on new config
+    }
     this.#updateTimeStamps(config);
     let newConfig = config;
     let purgeConfig = oldConfig;
@@ -776,12 +822,22 @@ export class ConfigStore {
 
     await this.validate(ctx, newConfig);
     await this.validatePermissions(ctx, oldConfig, newConfig);
+
+    if (modified) {
+      // Create a new version before saving only when modified
+      await this.#versioning.createVersion(ctx, config, versionName);
+    }
     await storage.put(this.key, JSON.stringify(config), 'application/json');
     await this.purge(ctx, purgeConfig, newConfig);
     return ret ?? redact(data, frag);
   }
 
   async remove(ctx, relPath) {
+    if (relPath.startsWith('versions/')) {
+      await this.deleteVersion(ctx, Number.parseInt(relPath.substring('versions/'.length), 10));
+      return;
+    }
+
     const storage = HelixStorage.fromContext(ctx).configBus();
     const buf = await storage.get(this.key);
     if (!buf) {
@@ -808,6 +864,35 @@ export class ConfigStore {
     await this.purge(ctx, oldConfig, null);
   }
 
+  /**
+   * List all versions for this config
+   * @param {Object} ctx - Context object
+   * @returns {Promise<Array>} Array of version information
+   */
+  async listVersions(ctx) {
+    return this.#versioning.listVersions(ctx);
+  }
+
+  /**
+   * Get a specific version of the config
+   * @param {Object} ctx - Context object
+   * @param {number} version - Version number to retrieve
+   * @returns {Promise<Object>} The versioned config data
+   */
+  async getVersion(ctx, version) {
+    return this.#versioning.getVersion(ctx, version);
+  }
+
+  /**
+   * Delete a specific version
+   * @param {Object} ctx - Context object
+   * @param {number} version - Version number to delete
+   * @returns {Promise<void>}
+   */
+  async deleteVersion(ctx, version) {
+    return this.#versioning.deleteVersion(ctx, version);
+  }
+
   // eslint-disable-next-line class-methods-use-this,no-unused-vars
   async purge(ctx, oldConfig, newConfig) {
     // override in subclass

package/src/config-versioning.js

@@ -0,0 +1,188 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { HelixStorage } from '@adobe/helix-shared-storage';
+import { StatusCodeError } from './status-code-error.js';
+
+/**
+ * Version metadata structure
+ * @typedef {Object} VersionMetadata
+ * @property {number} version - Version number (auto-incrementing)
+ * @property {string} timestamp - ISO timestamp when version was created
+ * @property {string} [name] - Optional name/comment for the version
+ */
+
+/**
+ * Version information returned by listVersions
+ * @typedef {Object} VersionInfo
+ * @property {number} version - Version number
+ * @property {string} timestamp - ISO timestamp when version was created
+ * @property {string} [name] - Optional name/comment for the version
+ * @property {boolean} isCurrent - Whether this is the current version
+ */
+
+/**
+ * Config versioning manager
+ */
+export class ConfigVersioning {
+  /**
+   * Create a new ConfigVersioning instance
+   * @param {string} org - Organization name
+   * @param {string} type - Config type (sites, profiles, org)
+   * @param {string} name - Config name
+   */
+  constructor(org, type = 'org', name = '') {
+    this.org = org;
+    this.type = type;
+    this.name = name;
+    this.prefix = type === 'org'
+      ? `orgs/${org}/versions`
+      : `orgs/${org}/${type}/${name}/versions`;
+  }
+
+  /**
+   * Create a new version of the config
+   * @param {Object} ctx - Context object
+   * @param {Object} config - The config data to version
+   * @param {string} [name] - Optional name for the version
+   * @returns {Promise<VersionMetadata>} Version metadata
+   */
+  async createVersion(ctx, config, name) {
+    const storage = HelixStorage.fromContext(ctx).configBus();
+
+    // Get current version number
+    const metadata = await this.getVersionMetadata(ctx);
+    const nextVersion = metadata.versions
+      .reduce((acc, current) => Math.max(acc, current.version), 0) + 1;
+
+    // eslint-disable-next-line no-param-reassign
+    config.version = nextVersion;
+
+    // Create version metadata
+    const versionMetadata = {
+      version: nextVersion,
+      created: new Date().toISOString(),
+    };
+    const meta = {
+      'x-version': String(nextVersion),
+    };
+    if (name) {
+      versionMetadata.name = name;
+      meta['x-version-name'] = name;
+    }
+
+    // Store the versioned config
+    await storage.put(`${this.prefix}/${nextVersion}.json`, JSON.stringify(config, null, 2), 'application/json', meta, true);
+
+    // Update metadata
+    metadata.current = nextVersion;
+    metadata.versions.push(versionMetadata);
+
+    // Keep only the last 100 versions to prevent storage bloat
+    if (metadata.versions.length > 100) {
+      metadata.versions = metadata.versions.slice(-100);
+    }
+    await storage.put(`${this.prefix}.json`, JSON.stringify(metadata, null, 2), 'application/json');
+    return versionMetadata;
+  }
+
+  /**
+   * Update the name of a specific version
+   * @param ctx
+   * @param version
+   * @param name
+   * @returns {Promise<*>}
+   */
+  async updateVersion(ctx, version, name) {
+    const storage = HelixStorage.fromContext(ctx).configBus();
+    const metadata = await this.getVersionMetadata(ctx);
+    const versionInfo = metadata.versions.find((v) => v.version === version);
+    if (!versionInfo) {
+      throw new StatusCodeError(404, `Version ${version} not found.`);
+    }
+    versionInfo.name = name;
+    await storage.put(`${this.prefix}.json`, JSON.stringify(metadata, null, 2), 'application/json');
+    return versionInfo;
+  }
+
+  /**
+   * List all versions for this config
+   * @param {Object} ctx - Context object
+   * @returns {Promise<VersionInfo[]>} Array of version information
+   */
+  async listVersions(ctx) {
+    return this.getVersionMetadata(ctx);
+  }
+
+  /**
+   * Get a specific version of the config
+   * @param {Object} ctx - Context object
+   * @param {number} version - Version number to retrieve
+   * @param {boolean} [direct=false] - If true, fetch directly from storage without metadata
+   * @returns {Promise<Object>} The versioned config data
+   */
+  async getVersion(ctx, version, direct) {
+    const storage = HelixStorage.fromContext(ctx).configBus();
+    const versionKey = `${this.prefix}/${version}.json`;
+    const buf = await storage.get(versionKey);
+    if (!buf) {
+      throw new StatusCodeError(404, `Version ${version} not found.`);
+    }
+    if (direct) {
+      return JSON.parse(buf);
+    }
+
+    const metadata = await this.getVersionMetadata(ctx);
+    const versionInfo = metadata.versions.find((v) => v.version === version) || {};
+    return {
+      ...versionInfo,
+      data: JSON.parse(buf),
+    };
+  }
+
+  /**
+   * Delete a specific version
+   * @param {Object} ctx - Context object
+   * @param {number} version - Version number to delete
+   * @returns {Promise<void>}
+   */
+  async deleteVersion(ctx, version) {
+    const storage = HelixStorage.fromContext(ctx).configBus();
+
+    // Get metadata to check if this is the current version
+    const metadata = await this.getVersionMetadata(ctx);
+    if (version === metadata.current) {
+      throw new StatusCodeError(400, 'Cannot delete the current version.');
+    }
+
+    // Remove version from metadata
+    metadata.versions = metadata.versions.filter((v) => v.version !== version);
+    await storage.put(`${this.prefix}.json`, JSON.stringify(metadata, null, 2), 'application/json');
+
+    // Delete the versioned config
+    await storage.remove(`${this.prefix}/${version}.json`);
+  }
+
+  /**
+   * Get version metadata
+   * @param {Object} ctx - Context object
+   * @returns {Promise<Object>} Version metadata
+   */
+  async getVersionMetadata(ctx) {
+    const storage = HelixStorage.fromContext(ctx).configBus();
+    const buf = await storage.get(`${this.prefix}.json`);
+    if (!buf) {
+      return { current: 0, versions: [] };
+    }
+    return JSON.parse(buf);
+  }
+}

package/src/index.js

@@ -10,6 +10,7 @@
  * governing permissions and limitations under the License.
  */
 export { ConfigStore } from './config-store.js';
+export { ConfigVersioning } from './config-versioning.js';
 export { SCHEMAS } from './config-validator.js';
 export * from './ValidationError.js';
 export * from './config-merge.js';

package/src/schemas/org.schema.json

@@ -7,7 +7,6 @@
   "properties": {
     "version": {
       "type": "integer",
-      "enum": [1],
       "default": 1
     },
     "created": { "$ref": "https://ns.adobe.com/helix/config/common#/definitions/created" },

package/src/schemas/profile.schema.json

@@ -7,7 +7,6 @@
   "properties": {
     "version": {
       "type": "integer",
-      "enum": [1],
       "default": 1
     },
     "title": { "$ref": "https://ns.adobe.com/helix/config/common#/definitions/title" },

package/src/schemas/sidekick.schema.json

@@ -250,6 +250,10 @@
         "type": "string"
       },
       "description": "Additional hosts that are trusted to use the sidekick authentication"
+    },
+    "wordSaveDelay": {
+      "type": "number",
+      "description": "The delay to wait for Word to save the document before previewing (defaults to 1500)"
     }
   },
   "additionalProperties": false

package/src/schemas/site.schema.json

@@ -7,7 +7,6 @@
   "properties": {
     "version": {
       "type": "integer",
-      "enum": [1],
       "default": 1
     },
     "name": {