@cap-js/ord 1.1.0 → 1.2.0

package/lib/constants.js

@@ -1,25 +1,39 @@
-const ORD_RESOURCE_TYPE = Object.freeze(
-    {
-        "service": "service",
-        "entity": "entity",
-        "event": "event",
-        "api": "api"
-    });
-
-const COMPILER_TYPES = Object.freeze(
-    {
-        "oas3": "oas3",
-        "asyncapi2": "asyncapi2",
-        "edmx": "edmx"
-    });
+const COMPILER_TYPES = Object.freeze({
+    oas3: "oas3",
+    asyncapi2: "asyncapi2",
+    edmx: "edmx",
+});
 
 const CONTENT_MERGE_KEY = "ordId";
 
+const DESCRIPTION_PREFIX = "Description for ";
+
+const OPEN_RESOURCE_DISCOVERY_VERSION = "1.9";
+
 const ORD_EXTENSIONS_PREFIX = "@ORD.Extensions.";
 
+const ORD_RESOURCE_TYPE = Object.freeze({
+    service: "service",
+    entity: "entity",
+    event: "event",
+    api: "api",
+});
+
+const RESOURCE_VISIBILITY = Object.freeze({
+    public: "public",
+    internal: "internal",
+    private: "private",
+});
+
+const SHORT_DESCRIPTION_PREFIX = "Short description for ";
+
 module.exports = {
-    ORD_RESOURCE_TYPE,
     COMPILER_TYPES,
     CONTENT_MERGE_KEY,
-    ORD_EXTENSIONS_PREFIX
+    DESCRIPTION_PREFIX,
+    OPEN_RESOURCE_DISCOVERY_VERSION,
+    ORD_EXTENSIONS_PREFIX,
+    ORD_RESOURCE_TYPE,
+    RESOURCE_VISIBILITY,
+    SHORT_DESCRIPTION_PREFIX,
 };

package/lib/date.js

@@ -0,0 +1,22 @@
+function getRFC3339Date(includeOffset = true) {
+    const now = new Date();
+    const year = now.getUTCFullYear();
+    const month = String(now.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(now.getUTCDate()).padStart(2, '0');
+    const hours = String(now.getUTCHours()).padStart(2, '0');
+    const minutes = String(now.getUTCMinutes()).padStart(2, '0');
+    const seconds = String(now.getUTCSeconds()).padStart(2, '0');
+    
+    if (includeOffset) {
+        const offsetHours = '01';
+        const offsetMinutes = '00';
+        const offsetSign = '+';
+        return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}${offsetSign}${offsetHours}:${offsetMinutes}`;
+    } else {
+        return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}Z`;
+    }
+}
+
+module.exports = {
+    getRFC3339Date
+};

package/lib/defaults.js

@@ -1,3 +1,5 @@
+const { OPEN_RESOURCE_DISCOVERY_VERSION } = require("./constants");
+
 const regexWithRemoval = (name) => {
     if (name) {
         return name.replace(/[^a-zA-Z0-9]/g, "");
@@ -27,7 +29,7 @@ const defaultProductOrdId = (name) => `customer:product:${nameWithDot(name)}:`;
 module.exports = {
     $schema:
         "https://sap.github.io/open-resource-discovery/spec-v1/interfaces/Document.schema.json",
-    openResourceDiscovery: "1.9",
+    openResourceDiscovery: OPEN_RESOURCE_DISCOVERY_VERSION,
     policyLevel: "none",
     description: "this is an application description",
     products: (name) => [
@@ -63,10 +65,11 @@ module.exports = {
             return [createPackage(name, ":v1")];
         }
     },
-    consumptionBundles: (name) => [
+    consumptionBundles: (appConfig) => [
         {
-            ordId: `${regexWithRemoval(name)}:consumptionBundle:unknown:v1`,
+            ordId: `${regexWithRemoval(appConfig.appName)}:consumptionBundle:noAuth:v1`,
             version: "1.0.0",
+            lastUpdate: appConfig.lastUpdate,
             title: "Unprotected resources",
             shortDescription:
                 "If we have another protected API then it will be another object",

package/lib/extendOrdWithCustom.js

@@ -1,8 +1,9 @@
-const path = require("path");
+const { CONTENT_MERGE_KEY } = require("./constants");
 const cds = require("@sap/cds");
-const _ = require('lodash');
-const { CONTENT_MERGE_KEY } = require('./constants');
-
+const fs = require("fs");
+const { Logger } = require("./logger");
+const path = require("path");
+const _ = require("lodash");
 
 function cleanNullProperties(obj) {
     for (const key in obj) {
@@ -28,12 +29,13 @@ function patchGeneratedOrdResources(destinationObj, sourceObj) {
     return cleanNullProperties(Object.values(destObj));
 }
 
-function compareAndHandleCustomORDContentWithExistingContent(ordContent, customORDContent, logger) {
+function compareAndHandleCustomORDContentWithExistingContent(ordContent, customORDContent) {
     const clonedOrdContent = structuredClone(ordContent);
     for (const key in customORDContent) {
         const propertyType = typeof customORDContent[key];
         if (propertyType !== 'object' && propertyType !== 'array') {
-            logger.warn('Found ord top level primitive ord property in customOrdFile:', key, ', please define it in .cdsrc.json.');
+            Logger.warn('Found ord top level primitive ord property in customOrdFile:', key, '. Please define it in .cdsrc.json.');
+
             continue;
         }
         if (key in ordContent) {
@@ -46,20 +48,17 @@ function compareAndHandleCustomORDContentWithExistingContent(ordContent, customO
 }
 
 function getCustomORDContent(appConfig) {
-    if (appConfig.env?.customOrdContentFile) {
-        const customORDContent = require(path.join(cds.root, appConfig.env.customOrdContentFile));
-        return customORDContent;
+    if (!appConfig.env?.customOrdContentFile) return;
+    const pathToCustomORDContent = path.join(cds.root, appConfig.env?.customOrdContentFile);
+    if (fs.existsSync(pathToCustomORDContent))  {
+        Logger.error('Custom ORD content file not found at', pathToCustomORDContent);
+        return require(pathToCustomORDContent);
     }
-    return {};
 }
 
-function extendCustomORDContentIfExists(appConfig, ordContent, logger) {
+function extendCustomORDContentIfExists(appConfig, ordContent) {
     const customORDContent = getCustomORDContent(appConfig);
-
-    if (customORDContent) {
-        ordContent = compareAndHandleCustomORDContentWithExistingContent(ordContent, customORDContent, logger);
-    }
-    return ordContent;
+    return customORDContent ? compareAndHandleCustomORDContentWithExistingContent(ordContent, customORDContent) : ordContent;
 }
 
 module.exports = {

package/lib/logger.js

@@ -0,0 +1,11 @@
+const cds = require("@sap/cds");
+
+const Logger = cds.log("ord-plugin", {
+    level: cds.env.DEBUG || process.env.DEBUG
+        ? cds.log.levels?.DEBUG
+        : cds.log.levels?.WARN,
+});
+
+module.exports = {
+    Logger,
+};

package/lib/metaData.js

@@ -2,6 +2,7 @@ const cds = require('@sap/cds/lib');
 const { compile: openapi } = require('@cap-js/openapi')
 const { compile: asyncapi } = require('@cap-js/asyncapi');
 const { COMPILER_TYPES } = require('./constants');
+const { Logger } = require('./logger');
 
 module.exports = async (data) => {
     const parts = data?.split("/").pop().replace(/\.json$/, '').split(".");
@@ -16,7 +17,7 @@ module.exports = async (data) => {
             try {
                 responseFile = openapi(csn, options);
             } catch (error) {
-                console.error("OpenApi error:", error.message);
+                Logger.error('OpenApi error:', error.message);
                 throw error;
             }
             break;
@@ -24,7 +25,7 @@ module.exports = async (data) => {
             try {
                 responseFile = asyncapi(csn, options);
             } catch (error) {
-                console.error("AsyncApi error:", error.message);
+                Logger.error('AsyncApi error:', error.message);
                 throw error;
             }
             break;
@@ -32,7 +33,7 @@ module.exports = async (data) => {
             try {
                 responseFile = await cds.compile(csn).to["edmx"](options);
             } catch (error) {
-                console.error("Edmx error:", error.message);
+                Logger.error('Edmx error:', error.message);
                 throw error;
             }
     }

package/lib/ord.js

@@ -1,24 +1,23 @@
-const path = require("path");
-const cds = require("@sap/cds");
-const { exists } = cds.utils;
-const _ = require("lodash");
-const defaults = require("./defaults");
+const { ORD_RESOURCE_TYPE } = require('./constants');
 const {
     createAPIResourceTemplate,
+    createEntityTypeTemplate,
     createEventResourceTemplate,
-    createGroupsTemplateForService,
-    createEntityTypeTemplate
+    createGroupsTemplateForService
 } = require('./templates');
 const { extendCustomORDContentIfExists } = require('./extendOrdWithCustom');
-const { ORD_RESOURCE_TYPE } = require('./constants');
-
-const logger = cds.log('ord-plugin');
+const { getRFC3339Date } = require('./date');
+const { Logger } = require('./logger');
+const _ = require("lodash");
+const cds = require("@sap/cds");
+const defaults = require("./defaults");
+const path = require("path");
 
 const initializeAppConfig = (csn) => {
-    let packagejsonPath = path.join(cds.root, 'package.json')
+    let packageJsonPath = path.join(cds.root, 'package.json')
     let packageJson;
-    if (exists(packagejsonPath)) {
-        packageJson = require(packagejsonPath);
+    if (cds.utils.exists(packageJsonPath)) {
+        packageJson = require(packageJsonPath);
     } else {
         throw new Error(`package.json not found in the project root directory`);
     }
@@ -27,16 +26,15 @@ const initializeAppConfig = (csn) => {
     const modelKeys = Object.keys(csn.definitions);
     const events = [];
     const serviceNames = [];
+    const lastUpdate = getRFC3339Date();
     let odmEntity = [];
 
-    // namespace variable value if present in cdsrc.json take it there or else from package.json
-    //if cdsrc.json does not have applicationNamespace, then use just the namespace
     const vendorNamespace = "customer";
     const ordNamespace = cds.env["ord"]?.namespace || `${vendorNamespace}.${packageName.replace(/[^a-zA-Z0-9]/g, "")}`;
     const eventApplicationNamespace = cds.env?.export?.asyncapi?.applicationNamespace;
 
     if (eventApplicationNamespace && ordNamespace !== eventApplicationNamespace) {
-        console.warn("ORD and AsyncAPI namespaces should be the same.");
+        Logger.warn('ORD and AsyncAPI namespaces should be the same.');
     }
 
     for (const key of modelKeys) {
@@ -63,6 +61,7 @@ const initializeAppConfig = (csn) => {
 
     return {
         env: cds.env["ord"],
+        lastUpdate,
         appName,
         events,
         serviceNames,
@@ -97,17 +96,24 @@ const _getPackages = (policyLevel, appConfig) =>
 
 const _getAPIResources = (csn, appConfig, packageIds) => {
     return appConfig.serviceNames
-        .flatMap((serviceName) => createAPIResourceTemplate(serviceName, csn.definitions[serviceName], appConfig, packageIds) || [])
-        .filter((resource) => !!resource);
+        .flatMap((serviceName) => createAPIResourceTemplate(serviceName, csn.definitions[serviceName], appConfig, packageIds))
 };
 
 const _getEventResources = (csn, appConfig, packageIds) => {
     if (appConfig.events.length === 0) return [];
     return appConfig.serviceNames
         .filter((serviceName) => appConfig.events.some((eventName) => eventName.startsWith(serviceName)))
-        .flatMap((serviceName) => createEventResourceTemplate(serviceName, csn.definitions[serviceName], appConfig, packageIds) || []);
+        .flatMap((serviceName) => createEventResourceTemplate(serviceName, csn.definitions[serviceName], appConfig, packageIds));
 };
 
+function _getOpenResourceDiscovery(appConfig) {
+    return appConfig.env?.openResourceDiscovery || defaults.openResourceDiscovery;
+}
+
+function _getConsumptionBundles(appConfig) {
+    return appConfig.env?.consumptionBundles || defaults.consumptionBundles(appConfig);
+}
+
 function validateNamespace(appConfig) {
     const validateSystemNamespace = new RegExp(`^${appConfig.eventApplicationNamespace}\\.[^.]+\\..+$`);
     if (
@@ -117,7 +123,7 @@ function validateNamespace(appConfig) {
         let error = new Error(
             `Namespace is not defined in cdsrc.json or it is not in the format of ${appConfig.eventApplicationNamespace}.<appName>.<service>`
         );
-        console.error("Namespace error:", error.message);
+        Logger.error('Namespace error:', error.message);
         throw error;
     }
 }
@@ -125,11 +131,12 @@ function validateNamespace(appConfig) {
 function createDefaultORDDocument(linkedCsn, appConfig) {
     let ordDocument = {
         $schema: "https://sap.github.io/open-resource-discovery/spec-v1/interfaces/Document.schema.json",
-        openResourceDiscovery: "1.9",
+        openResourceDiscovery: _getOpenResourceDiscovery(appConfig),
         policyLevel: _getPolicyLevel(appConfig),
         description: _getDescription(appConfig),
         products: _getProducts(appConfig),
         groups: _getGroups(linkedCsn, appConfig),
+        consumptionBundles: _getConsumptionBundles(appConfig),
     };
 
     if (_getAPIResources(linkedCsn, appConfig).length && _getEventResources(linkedCsn, appConfig).length) {
@@ -139,9 +146,9 @@ function createDefaultORDDocument(linkedCsn, appConfig) {
 }
 
 function extractPackageIds(ordDocument) {
-    const packageIds = new Set();
+    const packageIds = [];
     if (ordDocument.packages) {
-        ordDocument.packages.map((pkg) => packageIds.add(pkg.ordId));
+        ordDocument.packages.map((pkg) => packageIds.push(pkg.ordId));
     }
     return packageIds;
 }
@@ -153,14 +160,9 @@ module.exports = (csn) => {
 
     let ordDocument = createDefaultORDDocument(linkedCsn, appConfig);
     const packageIds = extractPackageIds(ordDocument);
-    // TODO: add testcase without apiResources or event, no empty package
     ordDocument.apiResources = _getAPIResources(linkedCsn, appConfig, packageIds);
-    const eventResources = _getEventResources(linkedCsn, appConfig, packageIds);
-    if (eventResources.length) {
-        ordDocument.eventResources = eventResources;
-    }
-
-    ordDocument = extendCustomORDContentIfExists(appConfig, ordDocument, logger);
+    ordDocument.eventResources = _getEventResources(linkedCsn, appConfig, packageIds);
+    ordDocument = extendCustomORDContentIfExists(appConfig, ordDocument);
 
     return ordDocument;
 };

package/lib/plugin.js

@@ -1,5 +1,7 @@
-const { ord, getMetadata, defaults } = require("./");
 const cds = require("@sap/cds");
+const { Logger } = require("./logger");
+const { ord, getMetadata, defaults } = require("./");
+
 
 cds.on("bootstrap", (app) => {
   app.use("/.well-known/open-resource-discovery", async (req, res) => {
@@ -10,8 +12,7 @@ cds.on("bootstrap", (app) => {
         const { contentType, response } = await getMetadata(req.url);
         res.status(200).contentType(contentType).send(response);
       } catch (error) {
-        console.log(error);
-        console.log('Error while generating metadata');
+        Logger.error(error, 'Error while generating metadata');
         res.status(500).send(error.message);
       }
     }
@@ -23,8 +24,7 @@ cds.on("bootstrap", (app) => {
       const data = ord(csn);
       return res.status(200).send(data);
     } catch (error) {
-      console.log(error);
-      console.log('Error while creating ORD document');
+      Logger.error(error, 'Error while creating ORD document');
       return res.status(500).send(error.message);
     }
   });

package/lib/templates.js

@@ -1,7 +1,14 @@
-const defaults = require("./defaults");
 const cds = require("@sap/cds");
+const defaults = require("./defaults");
 const _ = require("lodash");
-const { ORD_EXTENSIONS_PREFIX } = require("./constants");
+const {
+    DESCRIPTION_PREFIX,
+    ORD_EXTENSIONS_PREFIX,
+    ORD_RESOURCE_TYPE,
+    RESOURCE_VISIBILITY,
+    SHORT_DESCRIPTION_PREFIX
+} = require("./constants");
+const { Logger } = require("./logger");
 
 function unflatten(flattedObject) {
     let result = {}
@@ -40,12 +47,12 @@ const _generatePaths = (srv, srvDefinition) => {
     //removing instances of graphql protocol from paths
     for (var index = paths.length - 1; index >= 0; index--) {
         if (paths[index].kind === "graphql") {
-            console.warn("Graphql protocol is not supported.");
+            Logger.warn('Graphql protocol is not supported.');
             paths.splice(index, 1);
         }
     }
 
-    //putting default as odata in case no supported protcol is there
+    //putting OData as default in case of non-supported protocol
     if (paths.length === 0) {
         srvDefinition["@odata"] = true;
         paths.push({ kind: "odata", path: protocols.path4(srvDefinition) });
@@ -100,7 +107,7 @@ const createGroupsTemplateForService = (serviceName, serviceDefinition, appConfi
     const ordExtensions = readORDExtensions(serviceDefinition);
 
     if (!serviceDefinition) {
-        console.warn("Unable to find service definition:", serviceName)
+        Logger.warn('Unable to find service definition:', serviceName)
         return undefined
     }
 
@@ -114,7 +121,8 @@ const createGroupsTemplateForService = (serviceName, serviceDefinition, appConfi
 
 /**
  * This is a template function to create API Resource object for API Resource Array.
- *
+ * Properties of an API resource can be overwritten by the ORD extensions. Example: visibility.
+
  * @param {string} serviceName The name of the service.
  * @param {object} serviceDefinition The definition of the service
  * @returns {Array} An array of objects for the API Resources.
@@ -150,13 +158,14 @@ const createAPIResourceTemplate = (serviceName, serviceDefinition, appConfig, pa
                 serviceDefinition["@title"] ??
                 serviceDefinition["@Common.Label"] ??
                 serviceName,
-            shortDescription: serviceName,
+            shortDescription: SHORT_DESCRIPTION_PREFIX + serviceName,
             description:
                 serviceDefinition["@Core.Description"] ??
-                serviceName,
+                DESCRIPTION_PREFIX + serviceName,
             version: "1.0.0",
-            visibility: "public",
-            partOfPackage: _getPackageID(appConfig.ordNamespace, packageIds, "api"),
+            lastUpdate: appConfig.lastUpdate,
+            visibility: RESOURCE_VISIBILITY.public,
+            partOfPackage: _getPackageID(appConfig.ordNamespace, packageIds, ORD_RESOURCE_TYPE.api),
             partOfGroups: [_getGroupID(serviceName, defaults.groupTypeId, appConfig)],
             releaseStatus: "active",
             apiProtocol:
@@ -167,33 +176,43 @@ const createAPIResourceTemplate = (serviceName, serviceDefinition, appConfig, pa
                 supported: "no",
             },
             entityTypeMappings: [{ entityTypeTargets: appConfig.odmEntity }],
-
             ...ordExtensions,
         };
 
-        apiResources.push(obj);
+        if (obj.visibility === RESOURCE_VISIBILITY.public) apiResources.push(obj);
     });
 
-    if (apiResources.length > 0) return apiResources;
+    return apiResources;
 };
 
-const createEventResourceTemplate = (serviceName, eventDefinition, appConfig, packageIds) => {
-    const ordExtensions = readORDExtensions(eventDefinition);
-    return {
+/**
+ * This is a template function to create Event Resource object for Event Resource Array.
+ * There can be only one event resource per service because all events are using the same protocol, they are always Cloud Events.
+ * Properties of an event resource can be overwritten by the ORD extensions. Example: visibility.
+ *
+ * @param {string} serviceName The name of the service.
+ * @param {object} serviceDefinition The definition of the service
+ * @returns {Array} An single-item array of objects for the Event Resources.
+ */
+const createEventResourceTemplate = (serviceName, serviceDefinition, appConfig, packageIds) => {
+    const ordExtensions = readORDExtensions(serviceDefinition);
+    if (!!ordExtensions.visibility && ordExtensions.visibility !== RESOURCE_VISIBILITY.public) return [];
+    return [{
         ordId: `${appConfig.ordNamespace}:eventResource:${serviceName}:v1`,
         title:
-            eventDefinition["@title"] ??
-            eventDefinition["@Common.Label"] ??
+            serviceDefinition["@title"] ??
+            serviceDefinition["@Common.Label"] ??
             `ODM ${appConfig.appName.replace(/[^a-zA-Z0-9]/g, "")} Events`,
         shortDescription: `${serviceName} event resource`,
         description:
-            eventDefinition['@description'] ?? eventDefinition['@Core.Description'] ??
+            serviceDefinition['@description'] ?? serviceDefinition['@Core.Description'] ??
             "CAP Event resource describing events / messages.",
         version: "1.0.0",
+        lastUpdate: appConfig.lastUpdate,
         releaseStatus: "active",
-        partOfPackage: _getPackageID(appConfig.ordNamespace, packageIds, 'event'),
+        partOfPackage: _getPackageID(appConfig.ordNamespace, packageIds, ORD_RESOURCE_TYPE.event),
         partOfGroups: [_getGroupID(serviceName, defaults.groupTypeId, appConfig)],
-        visibility: "public",
+        visibility: RESOURCE_VISIBILITY.public,
         resourceDefinitions: [
             {
                 type: "asyncapi-v2",
@@ -209,14 +228,13 @@ const createEventResourceTemplate = (serviceName, eventDefinition, appConfig, pa
         extensible: { supported: "no" },
 
         ...ordExtensions
-    };
+    }]
 };
 
 function _getPackageID(namespace, packageIds, resourceType) {
-    //TODO: without this check, it will be failed in ordPackageJson.test.js, need to check why it is failing
-    if (!(packageIds instanceof Set)) return;
-    const packageIdsArray = Array.from(packageIds);
-    return packageIdsArray.find((pkg) => pkg.includes("-" + resourceType)) || packageIdsArray.find((pkg) => pkg.includes(namespace));
+    if (!packageIds) return;
+
+    return packageIds.find((id) => id.includes("-" + resourceType)) || packageIds.find((id) => id.includes(namespace));
 }
 
 module.exports = {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cap-js/ord",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "description": "CAP Plugin for generating ORD document.",
     "repository": "cap-js/ord",
     "author": "SAP SE (https://www.sap.com)",