@cap-js/ord 1.8.0 → 1.9.0

package/lib/templates/integration-dependency.js

@@ -0,0 +1,98 @@
+const { createPackages } = require("./package");
+const placeholders = require("../common/placeholders");
+const { readORDExtensions, isExternalDataProduct } = require("../common/utils");
+const { RESOURCE_VISIBILITY, EXTERNAL_DP_ORD_ID_ANNOTATION } = require("../constants");
+const _ = require("lodash");
+
+const RESOLVERS = Object.freeze({
+    ordId: (appConfig) => {
+        const major = RESOLVERS.version(appConfig).split(".")[0];
+
+        return (
+            placeholders.replace(appConfig.env?.integrationDependency?.ordId, {
+                type: "integrationDependency",
+                namespace: appConfig.ordNamespace,
+            }) ?? `${appConfig.ordNamespace}:integrationDependency:externalDependencies:v${major}`
+        );
+    },
+    version: (appConfig) => {
+        return appConfig.env?.integrationDependency?.version || "1.0.0";
+    },
+    aspects: (appConfig) => {
+        return (
+            appConfig.env?.integrationDependency?.aspects ??
+            Object.values(appConfig.csn.definitions)
+                .filter((definition) => isExternalDataProduct(definition))
+                .filter((service) => "apiResource" === service[EXTERNAL_DP_ORD_ID_ANNOTATION].split(":")[1])
+                .map((service) => {
+                    const version = service[EXTERNAL_DP_ORD_ID_ANNOTATION].split(":")[3] ?? "v1";
+
+                    return {
+                        title: service.name,
+                        mandatory: false,
+                        apiResources: [
+                            {
+                                ordId: service[EXTERNAL_DP_ORD_ID_ANNOTATION],
+                                minVersion: version.replace("v", "") + ".0.0",
+                            },
+                        ],
+
+                        ...readORDExtensions(service), // Allow customization via @ORD.Extensions on the service
+                    };
+                })
+        );
+    },
+    visibility: (appConfig) => {
+        return appConfig.env?.integrationDependency?.visibility || RESOURCE_VISIBILITY.public;
+    },
+    partOfPackage: (appConfig) => {
+        const visibility = RESOLVERS.visibility(appConfig);
+        const name = appConfig.appName?.replace(/[^a-zA-Z0-9]/g, "");
+        const packages = createPackages(appConfig).map((pkg) => pkg.ordId);
+        const suffix = visibility === RESOURCE_VISIBILITY.public ? "" : `-${visibility}`;
+
+        return (
+            placeholders.replace(appConfig.env?.integrationDependency?.partOfPackage, {
+                type: "package",
+                namespace: appConfig.ordNamespace,
+            }) ??
+            [
+                `${appConfig.ordNamespace}:package:${name}-integrationDependency${suffix}:v1`,
+                `${appConfig.ordNamespace}:package:${name}:v1`,
+            ].find((candidate) => packages.includes(candidate))
+        );
+    },
+});
+
+/**
+ * Creates a single IntegrationDependency with one aspect per external service.
+ * @param {Object} appConfig - The application configuration
+ * @returns {Object} IntegrationDependency object
+ */
+function createIntegrationDependency(appConfig) {
+    return {
+        mandatory: false,
+        releaseStatus: "active",
+        title: "External Dependencies",
+
+        ordId: RESOLVERS.ordId(appConfig),
+        version: RESOLVERS.version(appConfig),
+        aspects: RESOLVERS.aspects(appConfig),
+        visibility: RESOLVERS.visibility(appConfig),
+        partOfPackage: RESOLVERS.partOfPackage(appConfig),
+
+        // Allow customization via cdsrc
+        ..._.omit(appConfig.env?.integrationDependency ?? {}, Object.keys(RESOLVERS)),
+    };
+}
+
+function createIntegrationDependencies(appConfig) {
+    return [createIntegrationDependency(appConfig)] //
+        .filter((dependency) => dependency.aspects?.length > 0);
+}
+
+module.exports = {
+    createIntegrationDependencies,
+    createIntegrationDependency,
+    RESOLVERS,
+};

package/lib/templates/package.js

@@ -0,0 +1,91 @@
+const _ = require("lodash");
+
+const { prune } = require("../common/utils");
+const { createProducts } = require("./product");
+const placeholders = require("../common/placeholders");
+const { ORD_RESOURCE_TYPE, RESOURCE_VISIBILITY } = require("../constants");
+
+const RESOLVERS = Object.freeze({
+    title: (appConfig) => {
+        return appConfig?.env?.packages?.[0]?.title ?? appConfig.appName.replace(/[^a-zA-Z0-9]/g, " ").trim();
+    },
+    vendor: (appConfig) => {
+        return appConfig?.env?.packages?.[0]?.vendor ?? "customer:vendor:Customer:";
+    },
+    version: (appConfig) => {
+        return appConfig?.env?.packages?.[0]?.version ?? "1.0.0";
+    },
+    partOfProducts: (appConfig, products) => {
+        return appConfig?.env?.packages?.[0]?.partOfProducts ?? products;
+    },
+    description: (appConfig, label, visibility) => {
+        return (
+            appConfig?.env?.packages?.[0]?.description ??
+            `This package contains ${visibility} ${label} for ${RESOLVERS.title(appConfig)}.`
+        );
+    },
+    shortDescription: (appConfig, label, visibility) => {
+        return appConfig?.env?.packages?.[0]?.shortDescription ?? `Package containing ${visibility} ${label}`;
+    },
+    ordId: (appConfig, label, visibility, resourceType) => {
+        const tag = !resourceType ? "" : `-${resourceType}`;
+        const technicalName = appConfig.appName.replace(/[^a-zA-Z0-9]/g, "");
+        const suffix = visibility === RESOURCE_VISIBILITY.public ? "" : `-${visibility}`;
+
+        return (
+            placeholders.replace(appConfig?.env?.packages?.[0]?.ordId, {
+                type: "package",
+                namespace: appConfig.ordNamespace,
+            }) ?? `${appConfig.ordNamespace}:package:${technicalName}${tag}${suffix}:v1`
+        );
+    },
+});
+
+function createPackage(appConfig, { label, visibility, products, resourceType }) {
+    return prune({
+        title: RESOLVERS.title(appConfig),
+        vendor: RESOLVERS.vendor(appConfig),
+        version: RESOLVERS.version(appConfig),
+        partOfProducts: RESOLVERS.partOfProducts(appConfig, products),
+        description: RESOLVERS.description(appConfig, label, visibility),
+        ordId: RESOLVERS.ordId(appConfig, label, visibility, resourceType),
+        shortDescription: RESOLVERS.shortDescription(appConfig, label, visibility),
+
+        ..._.omit(appConfig?.env?.packages?.[0], Object.keys(RESOLVERS)),
+    });
+}
+
+function createPackages(appConfig) {
+    const products = appConfig.existingProductORDId
+        ? [appConfig.existingProductORDId]
+        : createProducts(appConfig)?.map((p) => p.ordId);
+    const visibilities = !appConfig.hasSAPPolicyLevel
+        ? [RESOURCE_VISIBILITY.public]
+        : Object.values(RESOURCE_VISIBILITY);
+    const packageTypes = !appConfig.hasSAPPolicyLevel
+        ? [{ label: "General" }]
+        : [
+              { label: "APIs", resourceType: ORD_RESOURCE_TYPE.api },
+              { label: "Events", resourceType: ORD_RESOURCE_TYPE.event },
+              { label: "Entity Types", resourceType: ORD_RESOURCE_TYPE.entityType },
+              { label: "Data Products", resourceType: ORD_RESOURCE_TYPE.dataProduct },
+              { label: "Integration Dependencies", resourceType: ORD_RESOURCE_TYPE.integrationDependency },
+          ];
+
+    return packageTypes.flatMap(({ label, resourceType }) =>
+        visibilities.map((visibility) =>
+            createPackage(appConfig, {
+                label,
+                visibility,
+                products,
+                resourceType,
+            }),
+        ),
+    );
+}
+
+module.exports = {
+    createPackages,
+    createPackage,
+    RESOLVERS,
+};

package/lib/templates/product.js

@@ -0,0 +1,57 @@
+const _ = require("lodash");
+
+const Logger = require("../logger");
+const placeholders = require("../common/placeholders");
+
+const RESOLVERS = Object.freeze({
+    ordId: (appConfig, overrides) => {
+        const name = appConfig.packageName
+            .split(/[^a-zA-Z0-9]/)
+            .filter(Boolean)
+            .join(".");
+
+        return (
+            placeholders.replace(overrides?.ordId, { type: "product", namespace: appConfig.ordNamespace }) ??
+            `customer:product:${name}:`
+        );
+    },
+    title: (appConfig, overrides) => {
+        return overrides?.title ?? appConfig.packageName.replace(/[^a-zA-Z0-9]/g, " ").trim();
+    },
+    vendor: (appConfig, overrides) => {
+        return overrides?.vendor ?? "customer:vendor:Customer:";
+    },
+    shortDescription: (appConfig, overrides) => {
+        return overrides?.shortDescription ?? `Short description of ${RESOLVERS.title(appConfig, overrides)}`;
+    },
+});
+
+function createProduct(appConfig) {
+    let overrides = appConfig?.env?.products?.[0] ?? {};
+
+    if (overrides?.ordId?.toLowerCase().startsWith("sap")) {
+        overrides = {}; // disable overrides, misconfiguration detected
+        Logger.error(
+            "Detected sap product ordId, which should not be defined for custom products, use default value instead. Please check ORD global registry.",
+        );
+    }
+
+    return {
+        title: RESOLVERS.title(appConfig, overrides),
+        ordId: RESOLVERS.ordId(appConfig, overrides),
+        vendor: RESOLVERS.vendor(appConfig, overrides),
+        shortDescription: RESOLVERS.shortDescription(appConfig, overrides),
+
+        ..._.omit(overrides, Object.keys(RESOLVERS)),
+    };
+}
+
+function createProducts(appConfig) {
+    return appConfig.existingProductORDId ? [] : [createProduct(appConfig)];
+}
+
+module.exports = {
+    createProducts,
+    createProduct,
+    RESOLVERS,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cap-js/ord",
-    "version": "1.8.0",
+    "version": "1.9.0",
     "description": "CAP Plugin for generating ORD document.",
     "repository": "cap-js/ord",
     "author": "SAP SE (https://www.sap.com)",
@@ -22,20 +22,22 @@
         "lint": "npx eslint .",
         "test": "jest __tests__/unit --ci --collectCoverage",
         "test:integration:basic": "jest __tests__/integration/basic-auth.test.js --testPathIgnorePatterns=/node_modules/ --forceExit",
-        "test:integration:mtls": "jest __tests__/integration/mtls-auth.test.js --testPathIgnorePatterns=/node_modules/ --forceExit",
+        "test:integration:mtls": "jest __tests__/integration/mtls-auth-*.test.js --testPathIgnorePatterns=/node_modules/ --forceExit",
         "test:integration:build": "jest __tests__/integration/cds-build.test.js --testPathIgnorePatterns=/node_modules/ --forceExit",
         "update-snapshot": "jest --ci --updateSnapshot",
         "cds:version": "cds v -i",
         "test:all": "npm run test && npm run test:integration:basic && npm run test:integration:mtls && npm run test:integration:build"
     },
     "devDependencies": {
+        "@cap-js/cds-test": "0.4.1",
         "@cap-js/graphql": "^0.14.0",
         "@cap-js/sqlite": "^2",
+        "@open-resource-discovery/specification": "1.16.1",
         "@sap/cds-dk": ">=8.9.5",
         "eslint": "^10.0.0",
         "express": "^5.0.0",
         "jest": "^30.0.0",
-        "prettier": "3.8.3",
+        "prettier": "3.8.4",
         "supertest": "^7.0.0"
     },
     "peerDependencies": {
@@ -53,7 +55,7 @@
         "node": ">=20 <25"
     },
     "overrides": {
-        "@sap/cds-compiler": "6.9.2"
+        "@sap/cds-compiler": "6.9.3"
     },
     "cds": {
         "requires": {

package/data/well-known.json

@@ -1,14 +0,0 @@
-{
-    "openResourceDiscoveryV1": {
-        "documents": [
-            {
-                "url": "/ord/v1/documents/ord-document",
-                "accessStrategies": [
-                    {
-                        "type": "open"
-                    }
-                ]
-            }
-        ]
-    }
-}

package/lib/access-strategies.js

@@ -1,172 +0,0 @@
-const cds = require("@sap/cds");
-const { AUTHENTICATION_TYPE, ORD_ACCESS_STRATEGY } = require("./constants");
-const Logger = require("./logger");
-
-/**
- * Mapping from internal authentication types to ORD access strategy values.
- * This is the single source of truth for auth type to ORD document mapping.
- *
- * @private
- */
-const AUTH_TYPE_ORD_ACCESS_STRATEGY_MAP = Object.freeze({
-    [AUTHENTICATION_TYPE.Open]: ORD_ACCESS_STRATEGY.Open,
-    [AUTHENTICATION_TYPE.Basic]: ORD_ACCESS_STRATEGY.Basic,
-    [AUTHENTICATION_TYPE.CfMtls]: ORD_ACCESS_STRATEGY.CfMtls,
-});
-
-/**
- * Derives ORD access strategies from authentication configuration.
- * This function is the main entry point for converting auth config to ORD document format.
- *
- * @param {Object} authConfig - Authentication configuration object
- * @param {string[]} authConfig.types - Array of authentication types (from AUTHENTICATION_TYPE)
- * @returns {Array<{type: string}>} Array of access strategy objects for ORD document
- *
- * @example
- * // With Basic auth configured
- * const authConfig = { types: ['basic'] };
- * const strategies = getAccessStrategiesFromAuthConfig(authConfig);
- * // Returns: [{ type: 'basic-auth' }]
- *
- * @example
- * // With multiple auth types
- * const authConfig = { types: ['basic', 'cf-mtls'] };
- * const strategies = getAccessStrategiesFromAuthConfig(authConfig);
- * // Returns: [{ type: 'basic-auth' }, { type: 'sap:cmp-mtls:v1' }]
- */
-function getAccessStrategiesFromAuthConfig(authConfig) {
-    if (!authConfig || !Array.isArray(authConfig.types)) {
-        Logger.warn("getAccessStrategiesFromAuthConfig:", "Invalid authConfig, defaulting to 'open'");
-        return [{ type: ORD_ACCESS_STRATEGY.Open }];
-    }
-
-    const strategies = authConfig.types
-        .map((type) => {
-            const ordType = AUTH_TYPE_ORD_ACCESS_STRATEGY_MAP[type];
-            if (!ordType) {
-                Logger.warn("getAccessStrategiesFromAuthConfig:", `Unknown auth type '${type}', skipping`);
-                return null;
-            }
-            return { type: ordType };
-        })
-        .filter(Boolean); // Remove null entries
-
-    // If no valid strategies found, default to open
-    if (strategies.length === 0) {
-        return [{ type: ORD_ACCESS_STRATEGY.Open }];
-    }
-
-    return strategies;
-}
-
-/**
- * Checks if access strategies contain any non-open strategies.
- *
- * @param {Array<{type: string}>} accessStrategies - Array of access strategy objects
- * @returns {boolean} True if any non-open strategy is present
- */
-function hasNonOpenStrategies(accessStrategies) {
-    if (!Array.isArray(accessStrategies)) {
-        return false;
-    }
-    return accessStrategies.some((s) => s.type !== ORD_ACCESS_STRATEGY.Open);
-}
-
-/**
- * Validates that 'open' strategy does not coexist with non-open strategies.
- * According to ORD specification, 'open' should not be mixed with authenticated strategies.
- *
- * @param {Array<{type: string}>} accessStrategies - Array of access strategy objects
- * @throws {Error} If 'open' coexists with non-open strategies
- */
-function ensureNoOpenWhenNonOpenPresent(accessStrategies) {
-    if (!Array.isArray(accessStrategies) || accessStrategies.length === 0) {
-        return;
-    }
-
-    const hasOpen = accessStrategies.some((s) => s.type === ORD_ACCESS_STRATEGY.Open);
-    const hasNonOpen = hasNonOpenStrategies(accessStrategies);
-
-    if (hasOpen && hasNonOpen) {
-        throw new Error(
-            "Invalid access strategies: 'open' cannot coexist with authenticated strategies (basic-auth, sap:cmp-mtls:v1)",
-        );
-    }
-}
-
-/**
- * Ensures access strategies are valid and present, with configurable strict mode.
- * In non-strict mode (default), missing/empty strategies fallback to 'open' with error log.
- * In strict mode, missing/empty strategies throw an error.
- *
- * @param {Array<{type: string}>|undefined} accessStrategies - Array of access strategy objects
- * @param {Object} options - Validation options
- * @param {string} [options.resourceName] - Name of the resource (for error messages)
- * @param {boolean} [options.strict] - If true, throw error instead of fallback (default: reads from cds.env.ord.strictAccessStrategies)
- * @returns {Array<{type: string}>} Validated access strategies array
- * @throws {Error} In strict mode, if accessStrategies is missing or empty
- *
- * @example
- * // Non-strict mode (default) - fallback to open
- * const strategies = ensureAccessStrategies(undefined, { resourceName: 'MyAPI' });
- * // Logs error and returns: [{ type: 'open' }]
- *
- * @example
- * // Strict mode - throws error
- * const strategies = ensureAccessStrategies(undefined, {
- *   resourceName: 'MyAPI',
- *   strict: true
- * });
- * // Throws: Error with message about missing accessStrategies
- */
-function ensureAccessStrategies(accessStrategies, options = {}) {
-    const { resourceName = "unknown resource", strict } = options;
-
-    // Determine strict mode: explicit parameter > config > default false
-    const isStrict = strict !== undefined ? strict : cds.env.ord?.strictAccessStrategies === true;
-
-    if (!Array.isArray(accessStrategies) || accessStrategies.length === 0) {
-        const message = `[ORD] accessStrategies missing or empty for resource "${resourceName}"`;
-
-        if (isStrict) {
-            throw new Error(`${message}. Strict mode is enabled.`);
-        } else {
-            Logger.error("ensureAccessStrategies:", `${message}. Falling back to 'open'.`);
-            return [{ type: ORD_ACCESS_STRATEGY.Open }];
-        }
-    }
-
-    // Validate no mixing of 'open' with non-open strategies
-    ensureNoOpenWhenNonOpenPresent(accessStrategies);
-
-    return accessStrategies;
-}
-
-/**
- * Validates that access strategies array contains only known ORD access strategy types.
- *
- * @param {Array<{type: string}>} accessStrategies - Array of access strategy objects
- * @returns {boolean} True if all strategies are valid
- */
-function isValidAccessStrategies(accessStrategies) {
-    if (!Array.isArray(accessStrategies) || accessStrategies.length === 0) {
-        return false;
-    }
-
-    const validTypes = Object.values(ORD_ACCESS_STRATEGY);
-    return accessStrategies.every((s) => s.type && validTypes.includes(s.type));
-}
-
-module.exports = {
-    // Main API
-    getAccessStrategiesFromAuthConfig,
-    ensureAccessStrategies,
-
-    // Helper functions
-    hasNonOpenStrategies,
-    ensureNoOpenWhenNonOpenPresent,
-    isValidAccessStrategies,
-
-    // Constants (re-exported for convenience)
-    AUTH_TYPE_ORD_ACCESS_STRATEGY_MAP,
-};

package/lib/date.js

@@ -1,17 +0,0 @@
-function getRFC3339Date() {
-    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");
-    const offsetHours = "01";
-    const offsetMinutes = "00";
-    const offsetSign = "+";
-    return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}${offsetSign}${offsetHours}:${offsetMinutes}`;
-}
-
-module.exports = {
-    getRFC3339Date,
-};

package/lib/integration-dependency.js

@@ -1,126 +0,0 @@
-const {
-    DATA_PRODUCT_SIMPLE_ANNOTATION,
-    EXTERNAL_DP_ORD_ID_ANNOTATION,
-    EXTERNAL_SERVICE_ANNOTATION,
-    INTEGRATION_DEPENDENCY_RESOURCE_NAME,
-    ORD_RESOURCE_TYPE,
-    RESOURCE_VISIBILITY,
-} = require("./constants");
-const { readORDExtensions, _getPackageID } = require("./templates");
-
-/**
- * Parses @cds.dp.ordId annotation to extract resource information.
- * @param {string} ordId - e.g., "sap.sai:apiResource:Supplier:v1"
- * @returns {Object} { namespace, resourceType, resourceName, version }
- */
-function parseDataProductOrdId(ordId) {
-    const [namespace, resourceType, resourceName, version = "v1"] = ordId.split(":");
-    return { namespace, resourceType, resourceName, version };
-}
-
-/**
- * Checks if a CSN definition is an external Data Product.
- * @param {Object} definition - CSN definition object
- * @returns {boolean}
- */
-function isExternalDataProduct(definition) {
-    return !!(
-        definition.kind === "service" &&
-        definition[EXTERNAL_SERVICE_ANNOTATION] &&
-        definition[DATA_PRODUCT_SIMPLE_ANNOTATION] &&
-        definition[EXTERNAL_DP_ORD_ID_ANNOTATION]
-    );
-}
-
-/**
- * Collects external services from CSN definitions.
- * Returns a flat list of external services (one per service, no namespace grouping).
- * @param {Object} csn - The CSN definitions object
- * @returns {Array} Array of external service objects
- */
-function collectExternalServices(csn) {
-    const externalServices = [];
-
-    for (const [serviceName, definition] of Object.entries(csn.definitions)) {
-        if (!isExternalDataProduct(definition)) continue;
-
-        const dpOrdId = definition[EXTERNAL_DP_ORD_ID_ANNOTATION];
-        const { resourceType, version } = parseDataProductOrdId(dpOrdId);
-
-        // Only support apiResource for now
-        if (resourceType !== "apiResource") continue;
-
-        externalServices.push({
-            serviceName,
-            ordId: dpOrdId,
-            minVersion: version.replace("v", "") + ".0.0",
-            definition,
-        });
-    }
-
-    return externalServices;
-}
-
-/**
- * Creates a single IntegrationDependency with one aspect per external service.
- * @param {Array} externalServices - Array of external service objects
- * @param {Object} appConfig - The application configuration
- * @param {Array} packageIds - The available package identifiers
- * @returns {Object} IntegrationDependency object
- */
-function createIntegrationDependency(externalServices, appConfig, packageIds) {
-    const packageId = _getPackageID(
-        appConfig.ordNamespace,
-        packageIds,
-        ORD_RESOURCE_TYPE.integrationDependency,
-        RESOURCE_VISIBILITY.public,
-    );
-
-    // Create one aspect per external service
-    const aspects = externalServices.map((service) => {
-        const ordExtensions = readORDExtensions(service.definition || {});
-        return {
-            title: service.serviceName,
-            mandatory: false,
-            apiResources: [{ ordId: service.ordId, minVersion: service.minVersion }],
-            ...ordExtensions, // Allow customization via @ORD.Extensions on the service
-        };
-    });
-
-    // Read IntegrationDependency level config from cdsrc
-    const integrationDepConfig = appConfig.env?.integrationDependency || {};
-    const version = integrationDepConfig.version || "1.0.0";
-
-    return {
-        ordId: `${appConfig.ordNamespace}:${ORD_RESOURCE_TYPE.integrationDependency}:${INTEGRATION_DEPENDENCY_RESOURCE_NAME}:v${version.split(".")[0]}`,
-        title: "External Dependencies",
-        version: version,
-        releaseStatus: "active",
-        visibility: RESOURCE_VISIBILITY.public,
-        mandatory: false,
-        partOfPackage: packageId,
-        aspects,
-        ...integrationDepConfig, // Allow customization via cdsrc
-    };
-}
-
-/**
- * Generates a single IntegrationDependency for all external services.
- * @param {Object} csn - The CSN definitions object
- * @param {Object} appConfig - The application configuration
- * @param {Array} packageIds - The available package identifiers
- * @returns {Array} Array containing single IntegrationDependency or empty array
- */
-function getIntegrationDependencies(csn, appConfig, packageIds) {
-    const externalServices = collectExternalServices(csn);
-    if (externalServices.length === 0) return [];
-
-    return [createIntegrationDependency(externalServices, appConfig, packageIds)];
-}
-
-module.exports = {
-    getIntegrationDependencies,
-    // Exported for testing
-    collectExternalServices,
-    createIntegrationDependency,
-};