@cap-js/ord 1.1.0 → 1.3.0

package/lib/templates.js

@@ -1,14 +1,30 @@
-const defaults = require("./defaults");
 const cds = require("@sap/cds");
+const defaults = require("./defaults");
 const _ = require("lodash");
-const { ORD_EXTENSIONS_PREFIX } = require("./constants");
+const {
+    AUTHENTICATION_TYPE,
+    DATA_PRODUCT_ANNOTATION,
+    DATA_PRODUCT_TYPE,
+    DESCRIPTION_PREFIX,
+    ENTITY_RELATIONSHIP_ANNOTATION,
+    LEVEL,
+    ORD_EXTENSIONS_PREFIX,
+    ORD_ODM_ENTITY_NAME_ANNOTATION,
+    ORD_RESOURCE_TYPE,
+    RESOURCE_VISIBILITY,
+    SEM_VERSION_REGEX,
+    SHORT_DESCRIPTION_PREFIX,
+    CONTENT_MERGE_KEY,
+    CDS_ELEMENT_KIND,
+} = require("./constants");
+const { Logger } = require("./logger");
 
 function unflatten(flattedObject) {
-    let result = {}
+    let result = {};
     _.keys(flattedObject).forEach(function (key) {
-        _.set(result, key, flattedObject[key])
-    })
-    return result
+        _.set(result, key, flattedObject[key]);
+    });
+    return result;
 }
 
 function readORDExtensions(model) {
@@ -29,7 +45,6 @@ function readORDExtensions(model) {
  * @param {Object} srvDefinition The service definition object.
  * @returns {Array} An array containing paths and it's kind.
  */
-
 const _generatePaths = (srv, srvDefinition) => {
     const srvObj = { name: srv, definition: srvDefinition };
     const protocols = cds.service.protocols;
@@ -40,12 +55,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) });
@@ -55,20 +70,32 @@ const _generatePaths = (srv, srvDefinition) => {
 };
 
 /**
- * This is a template function to create Entity Type object for Entity Type Array.
+ * This is a template function to create item of entityTypeMappings array.
  *
- * @param {string} entity The name of the entity.
- * @returns {Object} An object for the entity type.
+ * @param {string} entity The entity definition.
+ * @returns {Object} An entry of the entityTypeMappings array.
  */
-const createEntityTypeTemplate = (entity) => ({
-    ordId: `sap.odm:entityType:${entity["@ODM.entityName"]}:v1`,
-});
-
-function _getGroupID(
-    fullyQualifiedName,
-    groupTypeId = defaults.groupTypeId,
-    appConfig,
-) {
+const createEntityTypeMappingsItemTemplate = (entity) => {
+    if (entity[ORD_ODM_ENTITY_NAME_ANNOTATION]) {
+        return {
+            ordId: `sap.odm:entityType:${entity[ORD_ODM_ENTITY_NAME_ANNOTATION]}:v1`,
+            entityName: entity[ORD_ODM_ENTITY_NAME_ANNOTATION],
+            ...entity,
+        };
+    } else if (entity[ENTITY_RELATIONSHIP_ANNOTATION]) {
+        const ordIdParts = entity[ENTITY_RELATIONSHIP_ANNOTATION].split(":");
+        const namespace = ordIdParts[0];
+        const entityName = ordIdParts[1];
+        const version = ordIdParts[2] || "v1";
+        return {
+            ordId: `${namespace}:entityType:${entityName}:${version}`,
+            entityName,
+            ...entity,
+        };
+    }
+};
+
+function _getGroupID(fullyQualifiedName, groupTypeId = defaults.groupTypeId, appConfig) {
     return `${groupTypeId}:${appConfig.ordNamespace}:${fullyQualifiedName}`;
 }
 
@@ -88,6 +115,49 @@ function _getTitleFromServiceName(srv) {
     }
 }
 
+/**
+ * This is a function to get the version of the entity,
+ * validate it and log if it is not a valid semantical version.
+ *
+ * @param {object} entity An entity object.
+ * @returns Version of the entity with '1.0.0' as fallback value.
+ */
+function _getEntityVersion(entity) {
+    const entityVersion = entity.ordId.split(":").pop();
+    const version = entityVersion.replace("v", "") + ".0.0"; // TODO: version can be stated/overwritten by annotation
+    if (!SEM_VERSION_REGEX.test(version)) {
+        Logger.warn(`Entity version "${version}" is not a valid semantic version.`);
+    }
+    return version;
+}
+
+/**
+ * This is a function to create a resource definition object.
+ * @param {string} resourceType The type of the resource.
+ * @param {string} mediaType The media type of the resource.
+ * @param {string} ordId The ordId of the resource.
+ * @param {string} serviceName The name of the service.
+ * @param {string} fileExtension The file extension of the resource.
+ * @param {Array} accessStrategies The array of accessStrategies objects
+ * @returns {Object} A resource definition object.
+ * @private
+ */
+function _getResourceDefinition(
+    resourceType,
+    mediaType,
+    ordId,
+    serviceName,
+    fileExtension,
+    accessStrategies = [{ type: AUTHENTICATION_TYPE.Open }],
+) {
+    return {
+        type: resourceType,
+        mediaType: `application/${mediaType}`,
+        url: `/ord/v1/${ordId}/${serviceName}.${fileExtension}`,
+        accessStrategies,
+    };
+}
+
 /**
  * This is a template function to create group object of a service for groups array in ORD doc.
  *
@@ -100,128 +170,283 @@ const createGroupsTemplateForService = (serviceName, serviceDefinition, appConfi
     const ordExtensions = readORDExtensions(serviceDefinition);
 
     if (!serviceDefinition) {
-        console.warn("Unable to find service definition:", serviceName)
-        return undefined
+        Logger.warn("Unable to find service definition:", serviceName);
+        return undefined;
     }
 
     const groupId = _getGroupID(serviceName, defaults.groupTypeId, appConfig);
     return {
         groupId: groupId,
         groupTypeId: defaults.groupTypeId,
-        title: ordExtensions.title ?? _getTitleFromServiceName(serviceName)
+        title: ordExtensions.title ?? _getTitleFromServiceName(serviceName),
+    };
+};
+
+/**
+ * This is a template function to create EntityType object for EntityTypes Array.
+ * Ensures correct visibility assignment based on referenced resources.
+ *
+ * @param { object } appConfig  The configuration object.
+ * @param { Array } packageIds The available package identifiers.
+ * @param { object } entity The entity definition.
+ * @returns { object } An object for the EntityType.
+ */
+const createEntityTypeTemplate = (appConfig, packageIds, entity) => {
+    const ordExtensions = readORDExtensions(entity);
+    const visibility = ordExtensions.visibility || RESOURCE_VISIBILITY.public;
+
+    if (visibility === RESOURCE_VISIBILITY.private) {
+        return null;
+    }
+
+    const packageId = _getPackageID(appConfig.ordNamespace, packageIds, ORD_RESOURCE_TYPE.entityType, visibility);
+
+    return {
+        ordId: entity.ordId,
+        localId: entity.entityName,
+        title: entity["@title"] ?? entity["@Common.Label"] ?? entity.entityName,
+        shortDescription: SHORT_DESCRIPTION_PREFIX + entity.entityName,
+        description: DESCRIPTION_PREFIX + entity.entityName,
+        version: _getEntityVersion(entity),
+        lastUpdate: appConfig.lastUpdate,
+        visibility,
+        partOfPackage: packageId,
+        releaseStatus: "active",
+        level: entity["@ObjectModel.compositionRoot"] || entity["@ODM.root"] ? LEVEL.rootEntity : LEVEL.subEntity,
+        extensible: { supported: "no" },
+        ...ordExtensions,
     };
+};
+
+function _handleVisibility(ordExtensions, definition) {
+    let visibility;
+    if (ordExtensions.visibility) {
+        visibility = ordExtensions.visibility;
+    } else if (definition[ORD_EXTENSIONS_PREFIX + "visibility"]) {
+        visibility = definition[ORD_EXTENSIONS_PREFIX + "visibility"];
+    } else {
+        visibility = RESOURCE_VISIBILITY.public;
+    }
+    return visibility;
 }
 
 /**
  * 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.
+ * Ensures proper visibility compliance by checking associated EntityTypes.
  * @param {string} serviceName The name of the service.
  * @param {object} serviceDefinition The definition of the service
+ * @param {object} appConfig - The application configuration.
+ * @param {Array} packageIds - The available package identifiers.
+ * @param {Array} accessStrategies The array of accessStrategies objects
  * @returns {Array} An array of objects for the API Resources.
  */
-const createAPIResourceTemplate = (serviceName, serviceDefinition, appConfig, packageIds) => {
+const createAPIResourceTemplate = (serviceName, serviceDefinition, appConfig, packageIds, accessStrategies) => {
     const ordExtensions = readORDExtensions(serviceDefinition);
+    const visibility = _handleVisibility(ordExtensions, serviceDefinition);
+    const packageId = _getPackageID(appConfig.ordNamespace, packageIds, ORD_RESOURCE_TYPE.api, visibility);
+
     const paths = _generatePaths(serviceName, serviceDefinition);
     const apiResources = [];
+    const ordId = `${appConfig.ordNamespace}:apiResource:${serviceName}:v1`;
 
     paths.forEach((generatedPath) => {
         let resourceDefinitions = [
-            {
-                type: "openapi-v3",
-                mediaType: "application/json",
-                url: `/.well-known/open-resource-discovery/v1/api-metadata/${serviceName}.oas3.json`,
-                accessStrategies: [{ type: "open" }],
-            },
+            _getResourceDefinition("openapi-v3", "json", ordId, serviceName, "oas3.json", accessStrategies),
         ];
 
         if (generatedPath.kind !== "rest") {
             //edmx resource definition is not generated in case of 'rest' protocol
-            resourceDefinitions.push({
-                type: "edmx",
-                mediaType: "application/xml",
-                url: `/.well-known/open-resource-discovery/v1/api-metadata/${serviceName}.edmx`,
-                accessStrategies: [{ type: "open" }],
-            });
+            resourceDefinitions.push(
+                _getResourceDefinition("edmx", "xml", ordId, serviceName, "edmx", accessStrategies),
+            );
         }
 
+        const entityTypeMappings = _getEntityTypeMappings(serviceDefinition);
+
         let obj = {
-            ordId: `${appConfig.ordNamespace}:apiResource:${serviceName}:v1`,
-            title:
-                serviceDefinition["@title"] ??
-                serviceDefinition["@Common.Label"] ??
-                serviceName,
-            shortDescription: serviceName,
-            description:
-                serviceDefinition["@Core.Description"] ??
-                serviceName,
+            ordId,
+            title: serviceDefinition["@title"] ?? serviceDefinition["@Common.Label"] ?? serviceName,
+            shortDescription: SHORT_DESCRIPTION_PREFIX + serviceName,
+            description: serviceDefinition["@Core.Description"] ?? DESCRIPTION_PREFIX + serviceName,
             version: "1.0.0",
-            visibility: "public",
-            partOfPackage: _getPackageID(appConfig.ordNamespace, packageIds, "api"),
+            lastUpdate: appConfig.lastUpdate,
+            visibility,
+            partOfPackage: packageId,
             partOfGroups: [_getGroupID(serviceName, defaults.groupTypeId, appConfig)],
             releaseStatus: "active",
-            apiProtocol:
-                generatedPath.kind === "odata" ? "odata-v4" : generatedPath.kind,
+            apiProtocol: generatedPath.kind === "odata" ? "odata-v4" : generatedPath.kind,
             resourceDefinitions: resourceDefinitions,
             entryPoints: [generatedPath.path],
             extensible: {
                 supported: "no",
             },
-            entityTypeMappings: [{ entityTypeTargets: appConfig.odmEntity }],
-
+            ...(entityTypeMappings ? { entityTypeMappings } : {}),
             ...ordExtensions,
         };
 
-        apiResources.push(obj);
+        if (serviceDefinition[DATA_PRODUCT_ANNOTATION] === DATA_PRODUCT_TYPE.primary) {
+            obj.apiProtocol = "rest";
+            obj.visibility = RESOURCE_VISIBILITY.internal;
+            obj.direction = "outbound";
+            obj.implementationStandard = "sap.dp:data-subscription-api:v1";
+            obj.entryPoints = [];
+            obj.resourceDefinitions = [
+                _getResourceDefinition(
+                    "sap-csn-interop-effective-v1",
+                    "json",
+                    ordId,
+                    serviceName,
+                    "csn.json",
+                    accessStrategies,
+                ),
+            ];
+
+            apiResources.push(obj);
+        }
+
+        if (obj.visibility !== RESOURCE_VISIBILITY.private) {
+            apiResources.push(obj);
+        }
     });
 
-    if (apiResources.length > 0) return apiResources;
+    return apiResources;
 };
 
-const createEventResourceTemplate = (serviceName, eventDefinition, appConfig, packageIds) => {
-    const ordExtensions = readORDExtensions(eventDefinition);
-    return {
-        ordId: `${appConfig.ordNamespace}:eventResource:${serviceName}:v1`,
+/**
+ * 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.
+ * Ensures proper visibility compliance by checking associated EntityTypes.
+ *
+ * @param {string} serviceName The name of the service.
+ * @param {object} serviceDefinition The definition of the service
+ * @param {object} appConfig - The application configuration.
+ * @param {Array} packageIds - The available package identifiers.
+ * @param {Array} accessStrategies The array of accessStrategies objects
+ * @returns {Array} An single-item array of objects for the Event Resources.
+ */
+const createEventResourceTemplate = (serviceName, serviceDefinition, appConfig, packageIds, accessStrategies) => {
+    const ordExtensions = readORDExtensions(serviceDefinition);
+    const visibility = _handleVisibility(ordExtensions, serviceDefinition);
+    const packageId = _getPackageID(appConfig.ordNamespace, packageIds, ORD_RESOURCE_TYPE.event, visibility);
+    const ordId = `${appConfig.ordNamespace}:eventResource:${serviceName}:v1`;
+    const entityTypeMappings = _getEntityTypeMappings(serviceDefinition);
+
+    let obj = {
+        ordId,
         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: packageId,
         partOfGroups: [_getGroupID(serviceName, defaults.groupTypeId, appConfig)],
-        visibility: "public",
+        visibility,
         resourceDefinitions: [
-            {
-                type: "asyncapi-v2",
-                mediaType: "application/json",
-                url: `/.well-known/open-resource-discovery/v1/api-metadata/${serviceName}.asyncapi2.json`,
-                accessStrategies: [
-                    {
-                        type: "open",
-                    },
-                ],
-            },
+            _getResourceDefinition("asyncapi-v2", "json", ordId, serviceName, "asyncapi2.json", accessStrategies),
         ],
         extensible: { supported: "no" },
-
-        ...ordExtensions
+        ...(entityTypeMappings ? { entityTypeMappings } : {}),
+        ...ordExtensions,
     };
+
+    return obj.visibility === RESOURCE_VISIBILITY.public || obj.visibility === RESOURCE_VISIBILITY.internal
+        ? [obj]
+        : [];
 };
 
-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));
+function _getEntityTypeMappings(definitionObj) {
+    if (!definitionObj.entities) {
+        return;
+    }
+    const entities = Object.values(definitionObj.entities)
+        .flatMap((entity) => _flattenEntityGraph(entity))
+        .map(createEntityTypeMappingsItemTemplate);
+    const entityTypeTargets = _.uniqBy(entities, CONTENT_MERGE_KEY)
+        .filter((entity) => entity !== undefined)
+        .map(({ ordId }) => ({
+            ordId,
+        }));
+    if (entityTypeTargets.length > 0) {
+        return [{ entityTypeTargets }];
+    } else {
+        return;
+    }
+}
+
+function _flattenEntityGraph(currentEntity, processedEntities = []) {
+    if (!currentEntity.associations) {
+        return [currentEntity];
+    }
+    const entityAssociationTargets = Object.values(currentEntity.associations).map((association) => ({
+        target: association.target,
+        entity: association._target,
+    }));
+
+    const assertionsTodo = [];
+    entityAssociationTargets.forEach(({ target, entity }) => {
+        if (processedEntities.includes(target)) {
+            return;
+        }
+        processedEntities = [...processedEntities, target];
+        assertionsTodo.push(entity);
+    });
+
+    return [currentEntity, ...assertionsTodo.flatMap((entity) => _flattenEntityGraph(entity, processedEntities))];
+}
+
+function _getPackageID(namespace, packageIds, resourceType, visibility = RESOURCE_VISIBILITY.public) {
+    if (!packageIds) return;
+
+    if (resourceType) {
+        return (
+            packageIds.find((id) => {
+                if (visibility === RESOURCE_VISIBILITY.public) {
+                    return id.includes(resourceType) && !id.includes("-internal") && !id.includes("-private");
+                } else {
+                    return id.includes(`${resourceType}-${visibility}`);
+                }
+            }) || packageIds.find((id) => id.includes(namespace))
+        );
+    }
+
+    return packageIds.find((id) => id.includes(`-${resourceType}-`)) || packageIds.find((id) => id.includes(namespace));
+}
+
+function _propagateORDVisibility(model) {
+    for (const [name, def] of Object.entries(model.definitions)) {
+        if (def.kind === CDS_ELEMENT_KIND.service && def[ORD_EXTENSIONS_PREFIX + "visibility"]) {
+            const serviceName = name;
+            const serviceVisibility = def[ORD_EXTENSIONS_PREFIX + "visibility"];
+            for (const serviceChildrenDef of model.definitions) {
+                if (
+                    serviceChildrenDef.name.startsWith(serviceName + ".") &&
+                    !serviceChildrenDef[ORD_EXTENSIONS_PREFIX + "visibility"]
+                ) {
+                    serviceChildrenDef[ORD_EXTENSIONS_PREFIX + "visibility"] = serviceVisibility;
+                }
+            }
+        }
+    }
+
+    return model;
 }
 
 module.exports = {
     createEntityTypeTemplate,
+    createEntityTypeMappingsItemTemplate,
     createGroupsTemplateForService,
     createAPIResourceTemplate,
     createEventResourceTemplate,
+    _getPackageID,
+    _getEntityTypeMappings,
+    _propagateORDVisibility,
 };

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "@cap-js/ord",
-    "version": "1.1.0",
+    "version": "1.3.0",
     "description": "CAP Plugin for generating ORD document.",
     "repository": "cap-js/ord",
     "author": "SAP SE (https://www.sap.com)",
     "homepage": "https://cap.cloud.sap/",
-    "license": "SEE LICENSE IN LICENSE",
+    "license": "Apache-2.0",
     "main": "cds-plugin.js",
     "files": [
         "lib",
@@ -20,15 +20,24 @@
     },
     "devDependencies": {
         "eslint": "^8",
-        "jest": "^29.7.0"
+        "jest": "^29.7.0",
+        "prettier": "3.5.3"
     },
     "peerDependencies": {
-        "@cap-js/asyncapi": "^1.0.0",
-        "@cap-js/openapi": "^1.0.2",
         "@sap/cds": "^8.1.1",
-        "@sap/cds-compiler": "5.0.6"
+        "@sap/cds-dk": "^8.9.3"
     },
     "dependencies": {
+        "@cap-js/asyncapi": "^1.0.3",
+        "@cap-js/openapi": "^1.2.1",
+        "bcrypt": "^5.1.1",
         "lodash": "^4.17.21"
+    },
+    "cds": {
+        "requires": {
+            "SAP ORD Service": {
+                "model": "@cap-js/ord/lib/ord-service"
+            }
+        }
     }
-}
+}

package/lib/plugin.js

@@ -1,33 +0,0 @@
-const { ord, getMetadata, defaults } = require("./");
-const cds = require("@sap/cds");
-
-cds.on("bootstrap", (app) => {
-  app.use("/.well-known/open-resource-discovery", async (req, res) => {
-    if (req.url === "/") {
-      res.status(200).send(defaults.baseTemplate);
-    } else {
-      try {
-        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');
-        res.status(500).send(error.message);
-      }
-    }
-  });
-
-  app.get("/open-resource-discovery/v1/documents/1", async (req, res) => {
-    try {
-      const csn = await cds.load(cds.env.folders.srv);
-      const data = ord(csn);
-      return res.status(200).send(data);
-    } catch (error) {
-      console.log(error);
-      console.log('Error while creating ORD document');
-      return res.status(500).send(error.message);
-    }
-  });
-});
-
-module.exports = cds.server;