@adobe/helix-config 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.2.0](https://github.com/adobe/helix-config/compare/v1.1.0...v1.2.0) (2024-03-08)
+
+
+### Features
+
+* add json schemas and restructure content and code config ([#26](https://github.com/adobe/helix-config/issues/26)) ([b38af40](https://github.com/adobe/helix-config/commit/b38af40c8ee0812d946032ac6958c9debc30600b))
+
 # [1.1.0](https://github.com/adobe/helix-config/compare/v1.0.3...v1.1.0) (2024-03-04)
 
 

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@adobe/helix-config",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Helix Config",
   "main": "src/index.js",
   "type": "module",
   "scripts": {
     "test": "c8 mocha",
     "lint": "eslint .",
+    "docs:types": "node ./test/dev/generate-types.js",
     "semantic-release": "semantic-release",
     "semantic-release-dry": "semantic-release --dry-run --branches $CI_BRANCH",
     "prepare": "husky install"
@@ -35,6 +36,7 @@
     "c8": "9.1.0",
     "eslint": "8.57.0",
     "husky": "9.0.11",
+    "json-schema-to-typescript": "13.1.2",
     "junit-report-builder": "3.2.1",
     "lint-staged": "15.2.2",
     "mocha": "10.3.0",

package/src/config-legacy.js

@@ -75,18 +75,22 @@ async function fetchConfigAll(ctx, contentBusId, partition) {
  */
 export async function resolveLegacyConfig(ctx, rso, scope) {
   // set owner==org and repo==site and fetch from helix-config for now
-  const config = {
-    version: 1,
-    ...rso,
-    owner: rso.org,
-    repo: rso.site,
-  };
   const helixConfig = await fetchHelixConfig(ctx, rso);
   if (!helixConfig) {
     return null;
   }
-  config.contentBusId = helixConfig.content.data['/'].contentBusId;
-
+  const { contentBusId, ...source } = helixConfig.content.data['/'];
+  const config = {
+    version: 1,
+    code: {
+      owner: rso.org,
+      repo: rso.site,
+    },
+    content: {
+      contentBusId,
+      source,
+    },
+  };
   const configAllPreview = await fetchConfigAll(ctx, config.contentBusId, 'preview');
   const { access } = configAllPreview?.config?.data || {};
   if (access) {

package/src/config-view.js

@@ -69,14 +69,19 @@ export function getAccessConfig(access, partition) {
 }
 
 /**
- * Loads the metadata from the config-bus
+ * Load metadata from the given path
+ * @param ctx the context
+ * @param config the config
+ * @param partition the partition
+ * @returns {Promise<{data: ModifierMap}|{}>} the metadata
  */
 async function loadMetadata(ctx, config, partition) {
   const contentBus = ctx.storage.contentBus();
-  const paths = config.metadata ?? [];
+  const paths = config.metadata?.source ?? [];
   if (!paths.length) {
     paths.push(METADATA_JSON);
   }
+
   // generate the metadata-all.json first
   const metadata = [];
   for (const path of paths) {
@@ -102,9 +107,9 @@ async function loadMetadata(ctx, config, partition) {
   };
 }
 
-async function loadHeadHtml(ctx, config) {
+async function loadHeadHtml(ctx, config, ref) {
   const codeBus = ctx.storage.codeBus();
-  const key = `${config.owner}/${config.repo}/${config.ref}/head.html`;
+  const key = `${config.owner}/${config.repo}/${ref}/head.html`;
   const buf = await codeBus.get(key);
   if (buf) {
     return {
@@ -114,13 +119,13 @@ async function loadHeadHtml(ctx, config) {
   return {};
 }
 
-function clean(obj, prop) {
+function retainProperty(obj, prop) {
   if (!obj) {
     return;
   }
   for (const key of Object.keys(obj)) {
     if (typeof obj[key] === 'object') {
-      clean(obj[key], prop);
+      retainProperty(obj[key], prop);
     } else if (key !== prop) {
       // eslint-disable-next-line no-param-reassign
       delete obj[key];
@@ -148,14 +153,12 @@ async function resolveConfig(ctx, rso, scope) {
     }
   }
   const config = JSON.parse(buf.toString('utf-8'));
-  config.ref = rso.ref;
-
   if (scope === SCOPE_PIPELINE) {
     config.metadata = {
       preview: await loadMetadata(ctx, config, 'preview'),
       live: await loadMetadata(ctx, config, 'live'),
     };
-    config.head = await loadHeadHtml(ctx, config);
+    config.head = await loadHeadHtml(ctx, config, rso.ref);
   }
 
   return config;
@@ -194,27 +197,65 @@ export async function getConfigResponse(ctx, opts) {
   };
 
   if (opts.scope === SCOPE_DELIVERY) {
-    headers['x-hlx-contentbus-id'] = config.contentBusId;
-    headers['x-hlx-owner'] = config.owner;
-    headers['x-hlx-repo'] = config.repo;
-    headers['x-hlx-auth-allow-preview'] = canonicalArrayString(config.access, 'preview', 'allow');
-    headers['x-hlx-auth-apikey-preview'] = canonicalArrayString(config.access, 'preview', 'apiKeyId');
-    headers['x-hlx-auth-clientdn-preview'] = canonicalArrayString(config.access, 'preview', 'clientCertDN');
-    headers['x-hlx-auth-allow-live'] = canonicalArrayString(config.access, 'live', 'allow');
-    headers['x-hlx-auth-apikey-live'] = canonicalArrayString(config.access, 'live', 'apiKeyId');
-    headers['x-hlx-auth-clientdn-live'] = canonicalArrayString(config.access, 'live', 'clientCertDN');
-    // remove unused properties
-    delete config.access;
-    delete config.cdn;
-    delete config.headers;
+    return new PipelineResponse('', {
+      headers: {
+        'x-hlx-contentbus-id': config.content.contentBusId,
+        'x-hlx-owner': config.code.owner,
+        'x-hlx-repo': config.code.repo,
+        'x-hlx-auth-allow-preview': canonicalArrayString(config.access, 'preview', 'allow'),
+        'x-hlx-auth-apikey-preview': canonicalArrayString(config.access, 'preview', 'apiKeyId'),
+        'x-hlx-auth-clientdn-preview': canonicalArrayString(config.access, 'preview', 'clientCertDN'),
+        'x-hlx-auth-allow-live': canonicalArrayString(config.access, 'live', 'allow'),
+        'x-hlx-auth-apikey-live': canonicalArrayString(config.access, 'live', 'apiKeyId'),
+        'x-hlx-auth-clientdn-live': canonicalArrayString(config.access, 'live', 'clientCertDN'),
+      },
+    });
   }
-  if (opts.scope !== SCOPE_ADMIN) {
-    delete config.content;
-    delete config.code;
-    clean(config.cdn, 'host');
+
+  if (opts.scope === SCOPE_ADMIN) {
+    const adminConfig = {
+      ...rso,
+      ...config,
+      // todo: delete after admin uses new structure
+      contentBusId: config.content.contentBusId,
+      content: {
+        ...config.content,
+        ...config.content.source,
+      },
+    };
+    return new PipelineResponse(JSON.stringify(adminConfig, null, 2), {
+      headers,
+    });
   }
 
-  return new PipelineResponse(JSON.stringify(config, null, 2), {
+  if (opts.scope === SCOPE_PIPELINE) {
+    // remove all properties except `host`. pipeline doesn't need the others.
+    retainProperty(config.cdn, 'host');
+    const pipelineConfig = {
+      version: 1,
+      owner: config.code.owner,
+      repo: config.code.repo,
+      ...rso,
+      contentBusId: config.content.contentBusId,
+      access: config.access,
+      headers: config.headers,
+      head: config.head,
+      metadata: config.metadata,
+      cdn: config.cdn,
+      folders: config.folders,
+    };
+    return new PipelineResponse(JSON.stringify(pipelineConfig, null, 2), {
+      headers,
+    });
+  }
+
+  // else opts.scope === SCOPE_PUBLIC
+  const publicConfig = {
+    version: 1,
+    ...rso,
+    public: {},
+  };
+  return new PipelineResponse(JSON.stringify(publicConfig, null, 2), {
     headers,
   });
 }

package/src/index.d.ts

@@ -13,7 +13,7 @@ import { PipelineResponse } from './PipelineResponse';
 import { ConfigContext, ConfigScope } from "./ConfigContext";
 
 export declare class ConfigRequestOptions {
-  scope: ConfigScope,
+  scope: ConfigScope;
   org: string;
   site: string;
   ref: string;

package/src/schemas/access-config.schema.json

@@ -0,0 +1,41 @@
+{
+  "meta:license": [
+    "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."
+  ],
+  "$id": "https://ns.adobe.com/helix/config/access/site",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Site Access Config",
+  "type": "object",
+  "properties": {
+    "allow": {
+      "description": "The email glob of the users that are allowed.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "apiKeyId": {
+      "description": "IDs of the api keys that are allowed.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "clientCertDN": {
+      "description": "the DNs of the client certificates that are allowed.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/src/schemas/admin-access-config.schema.json

@@ -0,0 +1,56 @@
+{
+  "meta:license": [
+    "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."
+  ],
+  "$id": "https://ns.adobe.com/helix/config/access/admin",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Admin Access Config",
+  "type": "object",
+  "properties": {
+    "role": {
+      "title": "Role",
+      "type": "object",
+      "patternProperties": {
+        "^(?:author|publish|admin)$": {
+          "description": "The email glob of the users with respective role.",
+          "type": "array",
+          "items": {"type": "string"}
+        }
+      },
+      "required": ["role"],
+      "additionalProperties": false
+    },
+    "requireAuth": {
+      "description": "Enforce authentication if set to true. If set to 'auto' it will enforce authentication if a role mapping is defined. defaults to 'auto'.",
+      "default": "auto",
+      "oneOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "string",
+          "enum": ["auto"]
+        }
+      ]
+    },
+    "defaultRole": {
+      "description": "the default roles assigned to the users. defaults to `basic_publish` for unauthenticated setups.",
+      "type": "array",
+      "items": {"type": "string"}
+    },
+    "apiKeyId": {
+      "description": "the id of the API key(s). this is used to validate the API KEYS and allows to invalidate them.",
+      "type": "array",
+      "items": {"type": "string"}
+    }
+  },
+  "additionalProperties": false
+}

package/src/schemas/cdn-config.schema.json

@@ -0,0 +1,154 @@
+{
+  "meta:license": [
+    "Copyright 2023 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."
+  ],
+  "$id": "https://ns.adobe.com/helix/config/cdn",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$defs": {
+    "stringOrArray": {
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ]
+    }
+  },
+  "title": "CDN Config",
+  "type": "object",
+  "properties": {
+    "prod": {
+      "oneOf": [{
+        "type": "object",
+        "title": "FastlyConfig",
+        "description": "Production CDN configuration for Fastly",
+        "properties": {
+          "type": {
+            "type": "string",
+            "const": "fastly"
+          },
+          "host": {
+            "description": "production host",
+            "type": "string"
+          },
+          "serviceId": {
+            "description": "The Fastly Service ID",
+            "type": "string"
+          },
+          "authToken": {
+            "description": "A Fastly token for purging",
+            "type": "string"
+          }
+        },
+        "required": ["type", "host", "route", "serviceId", "authToken"],
+        "additionalProperties": false
+      }, {
+        "type": "object",
+        "title": "AkamaiConfig",
+        "properties": {
+          "type": {
+            "type": "string",
+            "const": "akamai"
+          },
+          "host": {
+            "description": "production host",
+            "type": "string"
+          },
+          "endpoint": {
+            "type": "string"
+          },
+          "clientSecret": {
+            "type": "string"
+          },
+          "clientToken": {
+            "type": "string"
+          },
+          "accessToken": {
+            "type": "string"
+          }
+        },
+        "required": ["type", "host", "route", "endpoint", "clientSecret", "clientToken", "accessToken"],
+        "additionalProperties": false
+      }, {
+        "type": "object",
+        "title": "CloudflareConfig",
+        "properties": {
+          "type": {
+            "type": "string",
+            "const": "cloudflare"
+          },
+          "host": {
+            "description": "production host",
+            "type": "string"
+          },
+          "origin": {
+            "type": "string"
+          },
+          "plan": {
+            "type": "string"
+          },
+          "zoneId": {
+            "type": "string"
+          },
+          "apiToken": {
+            "type": "string"
+          }
+        },
+        "required": ["type", "host", "route", "origin", "plan", "zoneId", "apiToken"],
+        "additionalProperties": false
+      }, {
+        "type": "object",
+        "title": "ManagedConfig",
+        "properties": {
+          "type": {
+            "type": "string",
+            "const": "managed"
+          },
+          "host": {
+            "description": "production host",
+            "type": "string"
+          }
+        },
+        "required": [ "type", "host", "route"],
+        "additionalProperties": false
+      }]
+    },
+    "live": {
+      "properties": {
+        "host": {
+          "description": "Sidekick config to override the default preview host. it supports parameters $owner and $repo",
+          "examples": ["main--$repo--page.example.com"],
+          "type": "string"
+        }
+      },
+      "required": ["host"],
+      "additionalProperties": false
+    },
+    "preview": {
+      "properties": {
+        "host": {
+          "description": "Sidekick config to override the default live host. it supports parameters $owner and $repo",
+          "examples": ["main--$repo--live.example.com\""],
+          "type": "string"
+        }
+      },
+      "required": ["host"],
+      "additionalProperties": false
+    }
+  },
+  "required": ["prod"],
+  "additionalProperties": false
+}

package/src/schemas/common.schema.json

@@ -0,0 +1,49 @@
+{
+  "meta:license": [
+    "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."
+  ],
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://ns.adobe.com/helix/config/common",
+  "$defs": {
+    "title": {
+      "type": "string",
+      "description": "human readable title. has no influence on the configuration."
+    },
+    "description": {
+      "type": "string",
+      "description": "description for clarity. has no influence on the configuration."
+    },
+    "keyValuePair": {
+      "type": "object",
+      "properties": {
+        "key": {"type": "string"},
+        "value": {"type": "string"}
+      },
+      "required": [
+        "key",
+        "value"
+      ],
+      "additionalProperties": false
+    },
+    "modifier-map": {
+      "type": "object",
+      "patternProperties": {
+        "^/[a-zA-Z0-9-/.]+[*]{0,2}$": {
+          "type": "array",
+          "items": [
+            { "$ref": "#/$defs/keyValuePair" }
+          ]
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/src/schemas/content-google.schema.json

@@ -0,0 +1,36 @@
+{
+  "meta:license": [
+    "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."
+  ],
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://ns.adobe.com/helix/config/content-source/google",
+  "title": "Google Content Source",
+  "type": "object",
+  "properties": {
+    "type": {
+      "const": "google"
+    },
+    "url": {
+      "type": "string",
+      "format": "uri"
+    },
+    "id": {
+      "description": "Google drive ID of the root folder; updated automatically when updating the url.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "type",
+    "url",
+    "id"
+  ],
+  "additionalProperties": false
+}

package/src/schemas/content-markup.schema.json

@@ -0,0 +1,34 @@
+{
+  "meta:license": [
+    "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."
+  ],
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://ns.adobe.com/helix/config/content-source/markup",
+  "title": "Markup Content Source",
+  "type": "object",
+  "properties": {
+    "type": {
+      "const": "markup"
+    },
+    "url": {
+      "type": "string",
+      "format": "uri"
+    },
+    "suffix": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "type",
+    "url"
+  ],
+  "additionalProperties": false
+}

package/src/schemas/content-onedrive.schema.json

@@ -0,0 +1,38 @@
+{
+  "meta:license": [
+    "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."
+  ],
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://ns.adobe.com/helix/config/content-source/onedrive",
+  "title": "Onedrive Content Source",
+  "type": "object",
+  "properties": {
+    "type": {
+      "const": "onedrive"
+    },
+    "url": {
+      "type": "string",
+      "format": "uri"
+    },
+    "tenantId": {
+      "type": "string"
+    },
+    "itemId": {
+      "description": "onedrive item ID of the root folder; currently not required as we don't know how setup will work.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "type",
+    "url"
+  ],
+  "additionalProperties": false
+}

package/src/schemas/sidekick-config.schema.json

@@ -0,0 +1,44 @@
+{
+  "meta:license": [
+    "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."
+  ],
+  "$id": "https://ns.adobe.com/helix/config/sidekick",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$defs": {
+    "sidekickPlugin": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "title",
+        "url"
+      ]
+    }
+  },
+  "title": "Sidekick Config",
+  "type": "object",
+  "properties": {
+    "plugins": {
+      "type": "array",
+      "items": [{"$ref": "#/$defs/sidekickPlugin"}]
+    }
+  }
+}

package/src/schemas/site-config.schema.json

@@ -0,0 +1,146 @@
+{
+  "meta:license": [
+    "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."
+  ],
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://ns.adobe.com/helix/config/site",
+  "title": "Helix Site Config",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "integer",
+      "enum": [1]
+    },
+    "name": {
+      "type": "string",
+      "description": "Site name; part of the hostname",
+      "format": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "title": { "$ref": "common.schema.json#/$defs/title" },
+    "description": { "$ref": "common.schema.json#/$defs/description" },
+
+    "content": {
+      "type": "object",
+      "title": "Content Bus",
+      "description": "Defines the content bus location and source.",
+      "properties": {
+        "title": { "$ref": "common.schema.json#/$defs/title" },
+        "description": { "$ref": "common.schema.json#/$defs/description" },
+        "contentBusId": {"type": "string" },
+        "source": {
+          "oneOf": [
+            { "$ref": "content-google.schema.json" },
+            { "$ref": "content-onedrive.schema.json" },
+            { "$ref": "content-markup.schema.json" }
+          ]
+        }
+      },
+      "required": [
+        "contentBusId",
+        "source"
+      ],
+      "additionalProperties": false
+    },
+    "code": {
+      "type": "object",
+      "title": "Code Bus",
+      "description": "Defines the code bus location and source.",
+      "properties": {
+        "title": { "$ref": "common.schema.json#/$defs/title" },
+        "description": { "$ref": "common.schema.json#/$defs/description" },
+        "owner": {
+          "$comment": "Note, that owner/repo are no longer part of the hostname and can therefor have more allowed characters than in helix4",
+          "type": "string",
+          "format": "[a-zA-Z0-9_-]+"
+        },
+        "repo": {
+          "type": "string",
+          "format": "[a-zA-Z0-9_-]+"
+        },
+        "source": {
+          "type": "object",
+          "properties": {
+            "type": {
+              "const": "github"
+            },
+            "url": {
+              "type":  "string",
+              "format": "uri"
+            }
+          },
+          "required": [
+            "type",
+            "url"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "owner",
+        "repo",
+        "source"
+      ]
+    },
+    "folders": {
+      "type": "object",
+      "patternProperties": {
+        "^/[a-zA-Z0-9-/.]+$": {
+          "type": "array",
+          "items": [
+            { "type": "string" }
+          ]
+        }
+      }
+    },
+    "headers": {
+      "$ref": "common.schema.json#/$defs/modifier-map"
+    },
+    "cdn": {
+      "$ref": "cdn-config.schema.json"
+    },
+    "access": {
+      "type": "object",
+      "properties": {
+        "admin": {
+          "$ref": "admin-access-config.schema.json"
+        },
+        "preview": {
+          "$ref": "access-config.schema.json"
+        },
+        "live": {
+          "$ref": "access-config.schema.json"
+        }
+      },
+      "additionalProperties": false
+    },
+    "sidekick": {
+      "$ref": "sidekick-config.schema.json"
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "source": {
+          "type": "array",
+          "items": [
+            { "type": "string" }
+          ]
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "version",
+    "content",
+    "code"
+  ],
+  "additionalProperties": false
+}

package/types/site-config.d.ts

@@ -0,0 +1,227 @@
+/*
+ * 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.
+ */
+
+// NOTE: this file is autogenerated via 'npm run docs:types'
+
+export interface HelixSiteConfig {
+  version: 1;
+  /**
+   * Site name; part of the hostname
+   */
+  name?: string;
+  /**
+   * human readable title. has no influence on the configuration.
+   */
+  title?: string;
+  /**
+   * description for clarity. has no influence on the configuration.
+   */
+  description?: string;
+  content: ContentBus;
+  code: CodeBus;
+  folders?: {
+    /**
+     * This interface was referenced by `undefined`'s JSON-Schema definition
+     * via the `patternProperty` "^/[a-zA-Z0-9-/.]+$".
+     */
+    [k: string]: [] | [string];
+  };
+  headers?: ModifierMap;
+  cdn?: CDNConfig;
+  access?: {
+    admin?: AdminAccessConfig;
+    preview?: SiteAccessConfig;
+    live?: SiteAccessConfig;
+  };
+  sidekick?: SidekickConfig;
+  metadata?: {
+    source?: [] | [string];
+  };
+}
+/**
+ * Defines the content bus location and source.
+ */
+export interface ContentBus {
+  /**
+   * human readable title. has no influence on the configuration.
+   */
+  title?: string;
+  /**
+   * description for clarity. has no influence on the configuration.
+   */
+  description?: string;
+  contentBusId: string;
+  source: GoogleContentSource | OnedriveContentSource | MarkupContentSource;
+}
+export interface GoogleContentSource {
+  type: 'google';
+  url: string;
+  /**
+   * Google drive ID of the root folder; updated automatically when updating the url.
+   */
+  id: string;
+}
+export interface OnedriveContentSource {
+  type: 'onedrive';
+  url: string;
+  tenantId?: string;
+  /**
+   * onedrive item ID of the root folder; currently not required as we don't know how setup will work.
+   */
+  itemId?: string;
+}
+export interface MarkupContentSource {
+  type: 'markup';
+  url: string;
+  suffix?: string;
+}
+/**
+ * Defines the code bus location and source.
+ */
+export interface CodeBus {
+  /**
+   * human readable title. has no influence on the configuration.
+   */
+  title?: string;
+  /**
+   * description for clarity. has no influence on the configuration.
+   */
+  description?: string;
+  owner: string;
+  repo: string;
+  source: {
+    type: 'github';
+    url: string;
+  };
+  [k: string]: unknown;
+}
+export interface ModifierMap {
+  /**
+   * This interface was referenced by `ModifierMap`'s JSON-Schema definition
+   * via the `patternProperty` "^/[a-zA-Z0-9-/.]+[*]{0,2}$".
+   */
+  [k: string]: [] | [KeyValuePair];
+}
+export interface KeyValuePair {
+  key: string;
+  value: string;
+}
+export interface CDNConfig {
+  prod: FastlyConfig | AkamaiConfig | CloudflareConfig | ManagedConfig;
+  live?: {
+    /**
+     * Sidekick config to override the default preview host. it supports parameters $owner and $repo
+     */
+    host: string;
+  };
+  preview?: {
+    /**
+     * Sidekick config to override the default live host. it supports parameters $owner and $repo
+     */
+    host: string;
+  };
+}
+/**
+ * Production CDN configuration for Fastly
+ */
+export interface FastlyConfig {
+  type: 'fastly';
+  /**
+   * production host
+   */
+  host: string;
+  /**
+   * The Fastly Service ID
+   */
+  serviceId: string;
+  /**
+   * A Fastly token for purging
+   */
+  authToken: string;
+}
+export interface AkamaiConfig {
+  type: 'akamai';
+  /**
+   * production host
+   */
+  host: string;
+  endpoint: string;
+  clientSecret: string;
+  clientToken: string;
+  accessToken: string;
+}
+export interface CloudflareConfig {
+  type: 'cloudflare';
+  /**
+   * production host
+   */
+  host: string;
+  origin: string;
+  plan: string;
+  zoneId: string;
+  apiToken: string;
+}
+export interface ManagedConfig {
+  type: 'managed';
+  /**
+   * production host
+   */
+  host: string;
+}
+export interface AdminAccessConfig {
+  role?: Role;
+  /**
+   * Enforce authentication if set to true. If set to 'auto' it will enforce authentication if a role mapping is defined. defaults to 'auto'.
+   */
+  requireAuth?: boolean | 'auto';
+  /**
+   * the default roles assigned to the users. defaults to `basic_publish` for unauthenticated setups.
+   */
+  defaultRole?: string[];
+  /**
+   * the id of the API key(s). this is used to validate the API KEYS and allows to invalidate them.
+   */
+  apiKeyId?: string[];
+}
+export interface Role {
+  /**
+   * The email glob of the users with respective role.
+   *
+   * This interface was referenced by `Role`'s JSON-Schema definition
+   * via the `patternProperty` "^(?:author|publish|admin)$".
+   */
+  [k: string]: string[];
+}
+export interface SiteAccessConfig {
+  /**
+   * The email glob of the users that are allowed.
+   */
+  allow?: string[];
+  /**
+   * IDs of the api keys that are allowed.
+   */
+  apiKeyId?: string[];
+  /**
+   * the DNs of the client certificates that are allowed.
+   */
+  clientCertDN?: string[];
+}
+export interface SidekickConfig {
+  plugins?: [] | [SidekickPlugin];
+  [k: string]: unknown;
+}
+export interface SidekickPlugin {
+  id: string;
+  title: string;
+  url: string;
+  [k: string]: unknown;
+}