@cap-js/ord 1.4.3 → 1.4.4

package/lib/constants.js

@@ -117,6 +117,39 @@ const SEM_VERSION_REGEX =
 
 const MCP_CUSTOM_TYPE = "sap:mcp-server-card:v0";
 
+// ORD apiProtocol values
+const ORD_API_PROTOCOL = Object.freeze({
+    ODATA_V4: "odata-v4",
+    ODATA_V2: "odata-v2",
+    REST: "rest",
+    GRAPHQL: "graphql",
+    SAP_INA: "sap-ina-api-v1",
+    SAP_DATA_SUBSCRIPTION: "sap.dp:data-subscription-api:v1",
+});
+
+// Mapping from CAP protocol kind to ORD apiProtocol
+// CAP may return 'odata', 'odata-v4', 'rest', etc.
+const CAP_TO_ORD_PROTOCOL_MAP = Object.freeze({
+    "odata": ORD_API_PROTOCOL.ODATA_V4,
+    "odata-v4": ORD_API_PROTOCOL.ODATA_V4,
+    "odata-v2": ORD_API_PROTOCOL.ODATA_V2,
+    "rest": ORD_API_PROTOCOL.REST,
+});
+
+// Protocols that ORD supports but CAP doesn't recognize (endpoints4 returns [])
+// These need special handling in the ORD plugin
+const ORD_ONLY_PROTOCOLS = Object.freeze({
+    "ina": {
+        apiProtocol: ORD_API_PROTOCOL.SAP_INA,
+        hasEntryPoints: false,
+        hasResourceDefinitions: false,
+    },
+});
+
+// Protocols that the ORD plugin cannot currently generate definitions for
+// GraphQL is supported by ORD spec, but plugin can't emit graphql-sdl yet
+const PLUGIN_UNSUPPORTED_PROTOCOLS = Object.freeze(["graphql"]);
+
 // CF mTLS Error Reasons
 const CF_MTLS_ERROR_REASON = Object.freeze({
     NO_HEADERS: "NO_HEADERS",
@@ -146,6 +179,7 @@ module.exports = {
     BASIC_AUTH_HEADER_KEY,
     BUILD_DEFAULT_PATH,
     BLOCKED_SERVICE_NAME,
+    CAP_TO_ORD_PROTOCOL_MAP,
     CDS_ELEMENT_KIND,
     CF_MTLS_HEADERS,
     COMPILER_TYPES,
@@ -160,12 +194,15 @@ module.exports = {
     OPEN_RESOURCE_DISCOVERY_VERSION,
     OPENAPI_SERVERS_ANNOTATION,
     ORD_ACCESS_STRATEGY,
+    ORD_API_PROTOCOL,
     ORD_DOCUMENT_FILE_NAME,
     ORD_EXTENSIONS_PREFIX,
     ORD_ODM_ENTITY_NAME_ANNOTATION,
     ORD_EXISTING_PRODUCT_PROPERTY,
+    ORD_ONLY_PROTOCOLS,
     ORD_RESOURCE_TYPE,
     ORD_SERVICE_NAME,
+    PLUGIN_UNSUPPORTED_PROTOCOLS,
     RESOURCE_VISIBILITY,
     ALLOWED_VISIBILITY,
     IMPLEMENTATIONSTANDARD_VERSIONS,

package/lib/protocol-resolver.js

@@ -0,0 +1,134 @@
+const cds = require("@sap/cds");
+const {
+    CAP_TO_ORD_PROTOCOL_MAP,
+    ORD_ONLY_PROTOCOLS,
+    ORD_API_PROTOCOL,
+    PLUGIN_UNSUPPORTED_PROTOCOLS,
+} = require("./constants");
+const Logger = require("./logger");
+
+/**
+ * Gets CAP endpoints for a service using CDS endpoints4().
+ *
+ * @param {string} serviceName The service name.
+ * @param {Object} srvDefinition The service definition object.
+ * @returns {Array} Raw endpoints from CDS.
+ */
+function _getCapEndpoints(serviceName, srvDefinition) {
+    const srvObj = { name: serviceName, definition: srvDefinition };
+    return cds.service.protocols.endpoints4(srvObj);
+}
+
+/**
+ * Reads the explicit @protocol annotation from service definition.
+ *
+ * @param {Object} srvDefinition The service definition object.
+ * @returns {string|null} Protocol name, or null if not explicitly set.
+ */
+function _getExplicitProtocol(srvDefinition) {
+    const protocol = srvDefinition["@protocol"];
+    if (!protocol) {
+        return null;
+    }
+    return Array.isArray(protocol) ? protocol[0] : protocol;
+}
+
+/**
+ * Resolves protocol for ORD API Resource generation.
+ *
+ * Design Principles:
+ * - explicit protocol is the "master switch" for all decisions
+ * - Rule A: Explicit protocol + empty endpoints → don't fallback to OData
+ * - Rule B: Only fallback to OData when no explicit protocol
+ * - Rule C: Never produce [null] in entryPoints
+ *
+ * @param {string} serviceName The service name.
+ * @param {Object} srvDefinition The service definition object.
+ * @param {Object} options Configuration options.
+ * @param {Function} options.isPrimaryDataProduct Strategy function to check if service is primary data product.
+ * @returns {Array} Array with single {apiProtocol, entryPoints, hasResourceDefinitions} object, or empty array.
+ */
+function resolveApiResourceProtocol(serviceName, srvDefinition, options = {}) {
+    const { isPrimaryDataProduct = () => false } = options;
+
+    // 1. Primary Data Product - early return
+    if (isPrimaryDataProduct(srvDefinition)) {
+        return [
+            {
+                apiProtocol: ORD_API_PROTOCOL.SAP_DATA_SUBSCRIPTION,
+                entryPoints: [],
+                hasResourceDefinitions: true,
+            },
+        ];
+    }
+
+    const explicit = _getExplicitProtocol(srvDefinition);
+
+    // 2. Handle explicit protocol
+    if (explicit) {
+        // 2a. Check if it's an ORD-only protocol (e.g., INA)
+        if (ORD_ONLY_PROTOCOLS[explicit]) {
+            const config = ORD_ONLY_PROTOCOLS[explicit];
+            const path = config.hasEntryPoints ? cds.service.protocols.path4(srvDefinition) : null;
+            return [
+                {
+                    apiProtocol: config.apiProtocol,
+                    entryPoints: path ? [path] : [],
+                    hasResourceDefinitions: config.hasResourceDefinitions,
+                },
+            ];
+        }
+
+        // 2b. Check if it's a plugin-unsupported protocol
+        if (PLUGIN_UNSUPPORTED_PROTOCOLS.includes(explicit)) {
+            Logger.warn(
+                `Protocol '${explicit}' is supported by ORD but this plugin cannot generate its resource definitions yet.`,
+            );
+            return [];
+        }
+    }
+
+    // 3. Try to resolve from CAP endpoints
+    const capEndpoints = _getCapEndpoints(serviceName, srvDefinition);
+    for (const endpoint of capEndpoints) {
+        if (PLUGIN_UNSUPPORTED_PROTOCOLS.includes(endpoint.kind)) {
+            Logger.warn(
+                `Protocol '${endpoint.kind}' is supported by ORD but this plugin cannot generate its resource definitions yet.`,
+            );
+            continue;
+        }
+
+        const apiProtocol = CAP_TO_ORD_PROTOCOL_MAP[endpoint.kind] ?? endpoint.kind;
+        if (apiProtocol) {
+            return [
+                {
+                    apiProtocol,
+                    entryPoints: endpoint.path ? [endpoint.path] : [],
+                    hasResourceDefinitions: true,
+                },
+            ];
+        }
+    }
+
+    // 4. Handle explicit protocol with no CAP endpoint (Rule A)
+    if (explicit) {
+        Logger.warn(`Unknown protocol '${explicit}' is not supported, skipping service '${serviceName}'.`);
+        return [];
+    }
+
+    // 5. No explicit protocol and no CAP endpoint - fallback to OData (Rule B)
+    const path = cds.service.protocols.path4(srvDefinition);
+    return [
+        {
+            apiProtocol: ORD_API_PROTOCOL.ODATA_V4,
+            entryPoints: path ? [path] : [],
+            hasResourceDefinitions: true,
+        },
+    ];
+}
+
+module.exports = {
+    resolveApiResourceProtocol,
+    // Exported for testing
+    _getExplicitProtocol,
+};

package/lib/templates.js

@@ -1,4 +1,3 @@
-const cds = require("@sap/cds");
 const { hasSAPPolicyLevel } = require("./utils");
 const { isMCPPluginReady } = require("./mcpAdapter");
 const defaults = require("./defaults");
@@ -21,9 +20,11 @@ const {
     SHORT_DESCRIPTION_PREFIX,
     CONTENT_MERGE_KEY,
     CDS_ELEMENT_KIND,
+    ORD_API_PROTOCOL,
 } = require("./constants");
 const Logger = require("./logger");
 const { ensureAccessStrategies } = require("./access-strategies");
+const { resolveApiResourceProtocol } = require("./protocol-resolver");
 
 function unflatten(flattedObject) {
     let result = {};
@@ -44,42 +45,6 @@ function readORDExtensions(model) {
     return unflatten(ordExtensions);
 }
 
-/**
- * Reads the service definition and returns an array of entryPoint paths.
- *
- * @param {string} srv The service definition name.
- * @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;
-
-    const paths = protocols.endpoints4(srvObj);
-
-    //TODO: check graphql replication in paths object and re-visit logic
-    //removing instances of graphql protocol from paths
-    for (var index = paths.length - 1; index >= 0; index--) {
-        if (paths[index].kind === "graphql") {
-            Logger.warn("Graphql protocol is not supported.");
-            paths.splice(index, 1);
-        }
-    }
-
-    //putting OData as default in case of non-supported protocol
-    if (paths.length === 0) {
-        if (isPrimaryDataProductService(srvDefinition)) {
-            // Data product services use REST protocol, not OData
-            paths.push({ kind: "rest", path: protocols.path4(srvDefinition) });
-        } else {
-            srvDefinition["@odata"] = true;
-            paths.push({ kind: "odata", path: protocols.path4(srvDefinition) });
-        }
-    }
-
-    return paths;
-};
-
 /**
  * This is a template function to create item of entityTypeMappings array.
  *
@@ -321,9 +286,17 @@ const createAPIResourceTemplate = (serviceName, serviceDefinition, appConfig, pa
     const visibility = _handleVisibility(ordExtensions, serviceDefinition, appConfig.env?.defaultVisibility);
     const packageId = _getPackageID(appConfig.ordNamespace, packageIds, ORD_RESOURCE_TYPE.api, visibility);
 
-    const paths = _generatePaths(serviceName, serviceDefinition);
+    const protocolResults = resolveApiResourceProtocol(serviceName, serviceDefinition, {
+        isPrimaryDataProduct: isPrimaryDataProductService,
+    });
     const apiResources = [];
 
+    // If no protocols were generated, skip this service
+    if (protocolResults.length === 0) {
+        Logger.info(`No supported protocols for service '${serviceName}', skipping API resource generation.`);
+        return apiResources;
+    }
+
     // Handle version suffix extraction for primary data product services
     let cleanServiceName,
         version,
@@ -352,16 +325,36 @@ const createAPIResourceTemplate = (serviceName, serviceDefinition, appConfig, pa
 
     const ordId = `${appConfig.ordNamespace}:apiResource:${cleanServiceName}:${version}`;
 
-    paths.forEach((generatedPath) => {
-        let resourceDefinitions = [
-            _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(
-                _getResourceDefinition("edmx", "xml", ordId, serviceName, "edmx", accessStrategies),
-            );
+    protocolResults.forEach((protocolResult) => {
+        const { apiProtocol, entryPoints, hasResourceDefinitions } = protocolResult;
+
+        // Build resource definitions based on protocol
+        let resourceDefinitions = [];
+        if (hasResourceDefinitions) {
+            if (apiProtocol === ORD_API_PROTOCOL.SAP_DATA_SUBSCRIPTION) {
+                // Data product services use CSN
+                resourceDefinitions = [
+                    _getResourceDefinition(
+                        "sap-csn-interop-effective-v1",
+                        "json",
+                        ordId,
+                        serviceName,
+                        "csn.json",
+                        accessStrategies,
+                    ),
+                ];
+            } else if (apiProtocol === ORD_API_PROTOCOL.REST) {
+                // REST only has OpenAPI, no EDMX
+                resourceDefinitions = [
+                    _getResourceDefinition("openapi-v3", "json", ordId, serviceName, "oas3.json", accessStrategies),
+                ];
+            } else {
+                // OData and others have both OpenAPI and EDMX
+                resourceDefinitions = [
+                    _getResourceDefinition("openapi-v3", "json", ordId, serviceName, "oas3.json", accessStrategies),
+                    _getResourceDefinition("edmx", "xml", ordId, serviceName, "edmx", accessStrategies),
+                ];
+            }
         }
 
         const entityTypeMappings = _getEntityTypeMappings(serviceDefinition);
@@ -378,9 +371,9 @@ const createAPIResourceTemplate = (serviceName, serviceDefinition, appConfig, pa
             partOfPackage: packageId,
             partOfGroups: [_getGroupID(serviceDefinition, defaults.groupTypeId, appConfig)],
             releaseStatus: "active",
-            apiProtocol: generatedPath.kind === "odata" ? "odata-v4" : generatedPath.kind,
-            resourceDefinitions: resourceDefinitions,
-            entryPoints: [generatedPath.path],
+            apiProtocol,
+            resourceDefinitions,
+            entryPoints,
             extensible: {
                 supported: "no",
             },
@@ -389,24 +382,13 @@ const createAPIResourceTemplate = (serviceName, serviceDefinition, appConfig, pa
             ...ordExtensions,
         };
 
+        // Special handling for data product services
         if (isPrimaryDataProductService(serviceDefinition)) {
-            obj.apiProtocol = "sap.dp:data-subscription-api:v1";
             obj.direction = "outbound";
-            obj.entryPoints = [];
             if (extracted) {
                 // Overwrite partOfGroups
                 obj.partOfGroups = [`${defaults.groupTypeId}:${appConfig.ordNamespace}:${cleanServiceName}`];
             }
-            obj.resourceDefinitions = [
-                _getResourceDefinition(
-                    "sap-csn-interop-effective-v1",
-                    "json",
-                    ordId,
-                    serviceName,
-                    "csn.json",
-                    accessStrategies,
-                ),
-            ];
         }
 
         if (obj.visibility !== RESOURCE_VISIBILITY.private) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cap-js/ord",
-    "version": "1.4.3",
+    "version": "1.4.4",
     "description": "CAP Plugin for generating ORD document.",
     "repository": "cap-js/ord",
     "author": "SAP SE (https://www.sap.com)",
@@ -49,6 +49,9 @@
     "engines": {
         "node": ">=18 <23"
     },
+    "overrides": {
+        "@sap/cds-compiler": "6.6.2"
+    },
     "cds": {
         "requires": {
             "SAP ORD Service": {