@sap/cds-dk 8.2.3 → 8.3.0

package/lib/init/projectReader.js

@@ -89,10 +89,12 @@ module.exports = new class ProjectReader {
      * @property {boolean} hasApprouter Indicates if the project uses the SAP Application Router.
      * @property {boolean} hasHtml5Repo Indicates if the project uses the SAP BTP HTML5 Application Repository.
      * @property {boolean} hasPortal Indicates if the project uses the SAP Cloud Portal service.
+     * @property {boolean} hasWorkzone Indicates if the project uses the SAP Build Work Zone service.
      * @property {boolean} hasDestination Indicates if the project uses the SAP BTP Destination service.
      * @property {boolean} hasMTXRoute Indicates if the approuter should have a multitenant route.
      * @property {boolean} hasMTXRouteJava Indicates if the approuter should have a multitenant subscription route (java).
      * @property {boolean} hasMalwareScanner Indicates if the project uses the SAP Malware Scanning service.
+     * @property {boolean} hasDynatrace Indicates if the project uses Dynatrace.
      *
      */
 

package/lib/init/registries/xs-app.js

@@ -0,0 +1,10 @@
+
+
+const odataApi = {
+  in: 'routes',
+  where: { target: '/odata/$1' }
+}
+
+module.exports = {
+  odataApi
+}

package/lib/init/template/cf-manifest/index.js

@@ -3,6 +3,7 @@ const cds = require('../../../cds')
 const { exists } = require('../../../cds').utils
 const { readProject } = require('../../projectReader')
 const { renderAndCopy } = require('../../template')
+const mvn = require('../../mvn')
 const MANIFEST_FILE = 'manifest.yml'
 const SERVICES_MANIFEST_FILE = 'services-manifest.yml'
 
@@ -29,5 +30,6 @@ module.exports = class CfManifestTemplate extends require('../../plugin') {
     async run() {
         const project = readProject()
         await renderAndCopy(join(__dirname, 'files'), cds.root, project)
+        if (project.isJava) await mvn.add('CF')
     }
 }

package/lib/init/template/cloud-logging/files/mta.yaml.hbs

@@ -3,6 +3,17 @@ modules:
   - name: {{appName}}-srv
     type: {{language}}
     path: {{& srvPath}}
+    {{#isJava}}
+    properties:
+      JBP_CONFIG_JAVA_OPTS:
+        from_environment: false
+        java_opts: >
+          -javaagent:META-INF/.sap_java_buildpack/otel_agent/opentelemetry-javaagent.jar
+          -Dotel.javaagent.extensions=META-INF/.sap_java_buildpack/otel_agent_extension/otel-agent-ext-java.jar
+      OTEL_METRICS_EXPORTER: cloud-logging
+      OTEL_TRACES_EXPORTER: cloud-logging
+      OTEL_LOGS_EXPORTER: none
+    {{/isJava}}
     requires:
       - name: {{appName}}-cloud-logging
   - name: {{appName}}-mtx
@@ -21,5 +32,5 @@ resources:
       service: cloud-logging
       service-plan: {{cloudLoggingServicePlan}}
       config:
-      ingest_otlp:
-        enabled: true
+        ingest_otlp:
+          enabled: true

package/lib/init/template/cloud-logging/files/{package.json → package.json.hbs}

@@ -8,7 +8,11 @@
   },
   "cds": {
     "requires": {
-      "telemetry": "to-cloud-logging"
+      "[{{profile}}]": {
+        "telemetry": {
+          "kind": "to-cloud-logging"
+        }
+      }
     }
   }
 }

package/lib/init/template/cloud-logging/index.js

@@ -30,9 +30,10 @@ module.exports = class extends require('../../plugin') {
   }
 
   async run() {
-    const { hasTelemetry } = readProject()
-    if (cds.cli.options['with-telemetry'] || hasTelemetry) {
-      await merge(__dirname, 'files/package.json').into('package.json')
+    const project = readProject(), { hasTelemetry, isNodejs } = project
+    if (isNodejs && (cds.cli.options['with-telemetry'] || hasTelemetry)) {
+      project.profile ??= 'production'
+      await merge(__dirname, 'files/package.json.hbs').into('package.json', { with: project })
       await sort('package.json', 'dependencies')
     }
   }

package/lib/init/template/data/as-csv.js

@@ -39,6 +39,12 @@ module.exports = async (data={}, csn, { headerOnly=false, separator=',' }={}) =>
             }
             record.push(...Object.values(value))
           }
+          else if (element.is_struct) {
+            if (i === 0) {
+              header.push(...Object.keys(value).map(structField => name + '_' + structField))
+            }
+            record.push(...Object.values(value))
+          }
           else {
             if (i === 0)  header.push(name)
             if (Array.isArray(value)) { // `array of` / `many`

package/lib/init/template/data/as-json.js

@@ -121,9 +121,16 @@ function dataForField(element, entity, csn, record, data, parentEntity, depth, r
   else if (element.items?.type) // `array of` / `many` with simple type
     return [ dataForField(element.items, entity, csn, record, data, null, depth+1, referenceData) ]
 
+  if (element.is_struct) {
+    let struct = {}
+    for (const el of element.elements) {
+      struct[el.name] = dataForField(el, entity, csn, record, data, null, depth+1, referenceData)
+    }
+    return struct
+  }
+
   const type = element._type || element.type
   switch (type) {
-    case undefined: return
     case 'cds.Time':
       return '22:59:53'
 

package/lib/init/template/data/index.js

@@ -67,7 +67,7 @@ module.exports = class DataTemplate extends require('../../plugin') {
       : getDefaultTargetFolder(env)
     dest = resolve(cds.root, dest)
 
-    let csn = await cds.load(cds.env.roots) // normal CSN
+    let csn = await cds.load([cds.env.roots, join(`${cds.env.folders.srv}`, `external`) ]) // normal CSN. Default paths and models imported with `cds import`
     // Skip of unused reuse entities like Language, Country, Currency
     csn = cds.minify(csn)
     csn = cds.reflect(csn) // reflected model (adds additional helper functions)

package/lib/init/template/destination/files/mta.yaml.hbs

@@ -31,14 +31,14 @@ resources:
             destinations:
               - Name: {{appName}}-srv-api
                 URL: ~{srv-api/srv-url}
-                Authentication: OAuth2UserTokenExchange
+                Authentication: NoAuthentication
                 Type: HTTP
                 ProxyType: Internet
                 HTML5.ForwardAuthToken: true
                 HTML5.DynamicDestination: true
-              - Authentication: NoAuthentication
-                Name: ui5
-                ProxyType: Internet
-                Type: HTTP
+              - Name: ui5
                 URL: https://ui5.sap.com
+                Authentication: NoAuthentication
+                Type: HTTP
+                ProxyType: Internet
         {{/hasHtml5Repo}}

package/lib/init/template/dynatrace/files/mta.yaml.hbs

@@ -3,8 +3,28 @@ modules:
   - name: {{appName}}-srv
     type: {{language}}
     path: {{& srvPath}}
+    {{#isJava}}
+    properties:
+      JBP_CONFIG_JAVA_OPTS:
+        from_environment: false
+        java_opts: >
+          -javaagent:META-INF/.sap_java_buildpack/otel_agent/opentelemetry-javaagent.jar
+          -Dotel.javaagent.extensions=META-INF/.sap_java_buildpack/otel_agent_extension/otel-agent-ext-java.jar
+          -Dotel.javaagent.extension.sap.cf.binding.dynatrace.metrics.token-name=ingest_apitoken
+      OTEL_METRICS_EXPORTER: dynatrace
+      OTEL_TRACES_EXPORTER: none
+      OTEL_LOGS_EXPORTER: none
+    {{/isJava}}
     requires:
       - name: {{appName}}-dynatrace
+        parameters:
+          config:
+            tokens:
+              - name: ingest_apitoken
+                scopes:
+                  - openTelemetryTrace.ingest
+                  - metrics.ingest
+
   - name: {{appName}}-mtx
     type: nodejs
     path: {{#isNodejs}}gen/{{/isNodejs}}mtx/sidecar
@@ -15,10 +35,6 @@ resources:
     type: org.cloudfoundry.managed-service
     parameters:
       service: dynatrace
-      service-plan: standard
+      service-plan: environment
       config:
-        tokens:
-          - name: ingest_apitoken
-            scopes:
-              - openTelemetryTrace.ingest
-              - metrics.ingest
+        environment_name: {{appName}}

package/lib/init/template/dynatrace/files/package.json.hbs

@@ -2,13 +2,16 @@
   "dependencies": {
     "@cap-js/telemetry": ">=0",
     "@opentelemetry/exporter-metrics-otlp-proto": "^0"{{#hasHelm}},
-    "@opentelemetry/exporter-trace-otlp-proto": "^0",
     "@opentelemetry/host-metrics": "^0"
     {{/hasHelm}}
   },
   "cds": {
     "requires": {
-      "telemetry": "to-dynatrace"
+      "[{{profile}}]": {
+        "telemetry": {
+          "kind": "to-dynatrace"
+        }
+      }
     }
   }
 }

package/lib/init/template/dynatrace/files/values.yaml

@@ -0,0 +1,15 @@
+srv:
+  bindings:
+    dynatrace:
+      serviceInstanceName: dynatrace
+      parameters:
+        tokens:
+          - name: ingest_apitoken
+            scopes:
+              - openTelemetryTrace.ingest
+              - metrics.ingest
+dynatrace:
+  serviceOfferingName: dynatrace
+  servicePlanName: environment
+  parameters:
+    environment_name: DYNATRACE # (Mandatory) maximum of 16 characters and can only comprise of uppercase letters and digits.

package/lib/init/template/dynatrace/index.js

@@ -10,20 +10,21 @@ module.exports = class extends require('../../plugin') {
   }
 
   async canRun() {
-    const { hasMta, hasHelm, hasHelmUnifiedRuntime } = readProject()
-    if ((hasHelmUnifiedRuntime || hasHelm) && !hasMta) throw `'cds add dynatrace' is not available for Kyma yet`
     return true
   }
 
   async run() {
     const project = readProject()
-    await merge(__dirname, 'files/package.json.hbs').into('package.json', { with: project })
-    await sort('package.json', 'dependencies')
+    if (project.isNodejs) {
+      project.profile ??= 'production'
+      await merge(__dirname, 'files/package.json.hbs').into('package.json', { with: project })
+      await sort('package.json', 'dependencies')
+    }
   }
 
   async combine() {
     const project = readProject()
-    const { hasMta, isJava, hasMultitenancy, srvPath } = project
+    const { hasMta, hasHelm, hasHelmUnifiedRuntime, isJava, hasMultitenancy, srvPath } = project
 
     if (hasMta) {
       const dynatrace = {
@@ -51,5 +52,9 @@ module.exports = class extends require('../../plugin') {
         with: project, additions, relationships
       })
     }
+
+    if (hasHelm || hasHelmUnifiedRuntime) {
+      await merge(__dirname, 'files', 'values.yaml').into('chart/values.yaml')
+    }
   }
 }

package/lib/init/template/handler/index.js

@@ -5,7 +5,22 @@ const mvn = require('../../mvn')
 module.exports = class Handler extends require('../../plugin') {
 
   static help() {
-    return 'add handler stubs' 
+    return 'add handler stubs for actions and functions (Java)' 
+  }
+
+  options() {
+    return {
+      'filter': {
+        type: 'string',
+        short: 'f',
+        help: `Filter actions or functions by name prefix. Regular expressions are not supported.`
+      },
+      'out': {
+        type: 'string',
+        short: 'o',
+        help: 'Specify a custom output directory inside the `handlers` directory. The default is `handlers`.'
+      }
+    }
   }
 
   canRun() {

package/lib/init/template/helm/files/values.yaml.hbs

@@ -26,6 +26,6 @@ srv:
       memory: {{#isJava}}1G{{/isJava}}{{^isJava}}500M{{/isJava}}
   health:
     liveness:
-      path: {{#isJava}}/actuator/health{{/isJava}}{{^isJava}}/health{{/isJava}}
+      path: {{#isJava}}/actuator/health/liveness{{/isJava}}{{^isJava}}/health{{/isJava}}
     readiness:
-      path: {{#isJava}}/actuator/health{{/isJava}}{{^isJava}}/health{{/isJava}}
+      path: {{#isJava}}/actuator/health/readiness{{/isJava}}{{^isJava}}/health{{/isJava}}

package/lib/init/template/helm/index.js

@@ -5,6 +5,7 @@ const { readProject } = require('../../projectReader')
 const { merge } = require('../../merge')
 const { ask4 } = require('../../../util/question')
 const { execSync } = require('child_process')
+const { mvn } = require('../../add')
 
 module.exports = class HelmTemplate extends require('../../plugin') {
 
@@ -90,10 +91,11 @@ module.exports = class HelmTemplate extends require('../../plugin') {
         await merge(__dirname, 'files/Chart.yaml.hbs').into('chart/Chart.yaml', { with: project })
         await merge(__dirname, 'files/values.yaml.hbs').into('chart/values.yaml', { with: project })
         await this._mergeDependency('web-application', 'srv')
+        if (project.isJava) await mvn.add('k8s')
     }
 
     async combine() {
-        const { hasDestination, hasEnterpriseMessaging, hasEnterpriseMessagingShared, hasHana, hasMultitenancy, hasXsuaa, hasHtml5Repo, hasApprouter, hasKafka, hasAttachments, hasPortal, hasMalwareScanner } = readProject()
+        const { hasDestination, hasEnterpriseMessaging, hasEnterpriseMessagingShared, hasHana, hasMultitenancy, hasXsuaa, hasHtml5Repo, hasApprouter, hasKafka, hasAttachments, hasPortal, hasMalwareScanner, hasDynatrace } = readProject()
 
         if (hasApprouter) {
             await this._mergeDependency('web-application', 'approuter')
@@ -140,6 +142,9 @@ module.exports = class HelmTemplate extends require('../../plugin') {
         if (hasMalwareScanner) {
             await this._mergeDependency('service-instance', 'malware-scanner')
         }
+        if (hasDynatrace) {
+            await this._mergeDependency('service-instance', 'dynatrace')
+        }
     }
 
     async _mergeDependency(name, alias) {

package/lib/init/template/html5-repo/files/app-package.json.hbs

@@ -8,11 +8,13 @@
     "start": "ui5 serve"
   },
   "devDependencies": {
-    "@ui5/cli": "^3",
+    {{#hasWorkzone}}"@sap/ui5-builder-webide-extension": "^1.1.9",{{/hasWorkzone}}
+    "@ui5/cli": "^4",
     "ui5-task-zipper": "^3"
   },
   "ui5": {
     "dependencies": [
+      {{#hasWorkzone}}"@sap/ui5-builder-webide-extension",{{/hasWorkzone}}
       "ui5-task-zipper"
     ]
   }

package/lib/init/template/html5-repo/files/ui5-deploy.yaml.hbs

@@ -13,6 +13,13 @@ builder:
       - "/test/**"
       - "/localService/**"
   customTasks:
+    {{#hasWorkzone}}
+    - name: webide-extension-task-updateManifestJson
+      afterTask: replaceVersion
+      configuration:
+        appFolder: webapp
+        destDir: dist
+    {{/hasWorkzone}}
     - name: ui5-task-zipper
       afterTask: generateVersionInfo
       configuration:

package/lib/init/template/html5-repo/index.js

@@ -2,6 +2,7 @@ const { join } = require('path')
 const { readProject } = require('../../projectReader')
 const { merge } = require('../../merge')
 const { srv4, html5RepoHost, html5Runtime, appDeployer, approuter, mtxSidecar4 } = require('../../registries/mta')
+const { odataApi } = require('../../registries/xs-app')
 
 module.exports = class Html5RepoTemplate extends require('../../plugin') {
 
@@ -52,7 +53,8 @@ module.exports = class Html5RepoTemplate extends require('../../plugin') {
 
         await Promise.all(apps.map(async ({app}) => {
             project.app = app
-            await merge(__dirname, 'files/xs-app.json.hbs').into(join(appPath, app, 'xs-app.json'), { project })
+            const additions = [odataApi]
+            await merge(__dirname, 'files/xs-app.json.hbs').into(join(appPath, app, 'xs-app.json'), { with: project, additions })
         }))
 
         if (hasMultitenancy) {

package/lib/init/template/mta/files/mta.yaml.hbs

@@ -29,7 +29,7 @@ modules:
     parameters:
       buildpack: sap_java_buildpack_jakarta
       readiness-health-check-type: http
-      readiness-health-check-http-endpoint: /actuator/health
+      readiness-health-check-http-endpoint: /actuator/health/readiness
     properties:
       SPRING_PROFILES_ACTIVE: cloud,sandbox
       JBP_CONFIG_COMPONENTS: "jres: ['com.sap.xs.java.buildpack.jre.SAPMachineJRE']"

package/lib/init/template/mta/index.js

@@ -5,6 +5,7 @@ const { bold } = require('../../../util/term')
 const { copyRenderedYAML } = require('../../../util/fs')
 const { readProject } = require('../../projectReader')
 const { merge, sort } = require('../../merge')
+const { mvn } = require('../../add')
 
 module.exports = class MtaTemplate extends require('../../plugin') {
 
@@ -23,6 +24,7 @@ module.exports = class MtaTemplate extends require('../../plugin') {
         }
         await merge(__dirname, 'files/package.json').into('package.json')
         await sort('package.json', 'devDependencies')
+        if (project.isJava) await mvn.add('cf')
     }
 
     async finalize() {

package/lib/init/template/typer/index.js

@@ -1,7 +1,7 @@
 const { join } = require('path')
 const { readProject } = require('../../projectReader')
 const { merge, mergeGitignore } = require('../../merge')
-const { warn, dim } = require('../../../util/term')
+const { warn, dim, bold } = require('../../../util/term')
 const { TYPER } = require('../../constants').OPTIONS
 const { exists, read } = require('../../../cds').utils
 
@@ -30,6 +30,7 @@ module.exports = class TyperTemplate extends require('../../plugin') {
     await merge(template('package.json')).into('package.json')
     await mergeGitignore('.gitignore', template('gitignore'))
     console.log(dim(`  Adding '@cds-models' to .gitignore to ignore generated types`)) // REVISIT: other facets are silent wrt. what they change
+    console.log(dim('  Added new dependencies to the project. Run ') + bold('npm i') + dim(' to install.'))
     try {
       await merge(source).into(target)
     } catch (e) {

package/lib/init/template/workzone-standard/files/manifest.json.hbs

@@ -1,6 +1,20 @@
 {
+  "sap.app": {
+    "crossNavigation": {
+      "inbounds": {
+        "{{uiApp}}-display": {
+          "semanticObject": "{{uiApp}}",
+          "action": "display",
+          "signature": {
+            "parameters": {},
+            "additionalParameters": "allowed"
+          }
+        }
+      }
+    }
+  },
   "sap.cloud": {
     "public": true,
-    "service": "{{appName}}.service"
+    "service": "{{strippedAppName}}.service"
   }
 }

package/lib/init/template/workzone-standard/files/mta.yaml.hbs

@@ -1,5 +1,13 @@
 ---
 modules:
+  - name: {{appName}}-srv
+    type: {{language}}
+    path: {{& srvPath}}
+    provides:
+      - name: srv-api # required by consumers of CAP services (e.g. approuter)
+        properties:
+          srv-url: ${default-url}
+
   - name: {{appName}}-destinations
     type: com.sap.application.content
     requires:
@@ -25,13 +33,14 @@ modules:
             - Name: {{appName}}-html5-repository
               ServiceInstanceName: {{appName}}-html5-repo-host
               ServiceKeyName: {{appName}}-html5-repo-host-key
-              sap.cloud.service: {{appName}}.service
+              sap.cloud.service: {{strippedAppName}}.service
             - Name: {{appName}}-auth
               Authentication: OAuth2UserTokenExchange
               ServiceInstanceName: {{appName}}-auth
               ServiceKeyName: {{appName}}-auth-key
-              sap.cloud.service: {{appName}}.service
+              sap.cloud.service: {{strippedAppName}}.service
 
+resources:
   - name: {{appName}}-destination
     type: org.cloudfoundry.managed-service
     parameters:

package/lib/init/template/workzone-standard/files/xs-app.json.hbs

@@ -0,0 +1,18 @@
+{
+  "authenticationMethod": "route",
+  "routes": [
+    {
+      "source": "^/?odata/(.*)$",
+      "target": "/odata/$1",
+      "destination": "{{appName}}-srv-api",
+      {{#hasXsuaa}}"authenticationType": "xsuaa",{{/hasXsuaa}}
+      "csrfProtection": true
+    },
+    {
+      "source": "^(.*)$",
+      "target": "$1",
+      "service": "html5-apps-repo-rt"{{#hasXsuaa}},
+      "authenticationType": "xsuaa"{{/hasXsuaa}}
+    }
+  ]
+}

package/lib/init/template/workzone-standard/index.js

@@ -2,7 +2,8 @@ const cds = require('../../../cds')
 const { readProject } = require('../../projectReader')
 const { merge } = require('../../merge')
 const { join } = require('path')
-const { destination, destinations } = require('../../registries/mta')
+const { destination, destinations, srv4 } = require('../../registries/mta')
+const { odataApi } = require('../../registries/xs-app')
 
 module.exports = class extends require('../../plugin') {
 
@@ -28,19 +29,36 @@ module.exports = class extends require('../../plugin') {
     async run() {
       const project = readProject()
       const { appUIPaths, appPath } = project
-      await Promise.all(appUIPaths.map(p =>
-        merge(__dirname, 'files/manifest.json.hbs').into(join(appPath, p, 'webapp/manifest.json'), { project })
-      ))
+      await Promise.all(appUIPaths.map(p => {
+        project.uiApp = p
+        return merge(__dirname, 'files/manifest.json.hbs').into(join(appPath, p, 'webapp/manifest.json'), { project })
+      }))
       await merge({ cds: { requires: { workzone: true } } }).into('package.json')
     }
 
     async combine() {
       const project = readProject()
-      const { hasMta } = project
+      const { hasMta, srvPath, apps, appPath } = project
+
+      await Promise.all(apps.map(async ({app}) => {
+        const additions = [odataApi]
+        const overwrites = [{
+          item: [odataApi, 'destination'],
+          withValue: `${project.appName}-srv-api`
+        }]
+        project.app = app
+        await merge(__dirname, 'files/xs-app.json.hbs').into(join(appPath, app, 'xs-app.json'), { with: project, additions, overwrites })
+      }))
 
       if (hasMta) {
-          const additions = [destinations, destination]
-          await merge(__dirname, 'files/mta.yaml.hbs').into('mta.yaml', { with: project, additions })
+        const srv = srv4(srvPath)
+        const additions = [srv, destinations, destination,
+          {
+            in: [destination, 'requires'],
+            where: { name: 'srv-api' }
+          }
+        ]
+        await merge(__dirname, 'files/mta.yaml.hbs').into('mta.yaml', { with: project, additions })
       }
   }
 }

package/lib/mtx/auth_manager.js

@@ -67,7 +67,7 @@ function reqParams(method, params) {
 }
 
 async function fetchToken(params) {
-    if (params.has('token') || !(params.has('refreshToken') || params.has('passcode') || !params.has('passcodeUrl'))) {
+    if (params.has('token') || !(params.has('refreshToken') || params.has('passcode') || params.has('clientid') || !params.has('passcodeUrl'))) {
         return;
     }
 
@@ -99,18 +99,20 @@ async function fetchToken(params) {
     if (error) {
         let message;
         if (REASONS.invalid_scope.test(error.message)) {
-            message = 'token has invalid scope. Check if your user has the required roles';
+            message = 'token has invalid scope. Ensure your user has the required roles';
         } else if (error.status === 404) {
-            message = 'token endpoint not found. Check if MTX is running with extensibility enabled';
+            message = 'token endpoint not found. Ensure that MTX is running with extensibility enabled';
         } else if (error.message.includes('<html')) { // should already be caught when fetching passcode URL
-            message = 'HTML response received. Check if route to MTX is configured correctly in App Router';
+            message = 'HTML response received. Ensure the route to MTX is configured correctly in App Router';
         } else if (error.status === 401) {
             message = `invalid credentials`;
             if (params.has('passcode')) {
-                message += `. Check if passcode is correct`;
+                message += `. Ensure the passcode is correct`;
                 if (params.has('passcodeUrl')) {
                     message += `. Passcode URL: ${params.get('passcodeUrl')}`;
                 }
+            } else if (params.has('clientid')) {
+                message += `. Ensure the client credentials are correct`;
             }
         } else {
             message = 'error on token request';

package/lib/mtx/util/errors.js

@@ -5,11 +5,11 @@ function handleHttpError(error, params, { url, command } = {}) {
     const prefix = `Request to ${url} failed`;
     switch (error.status) {
         case 401:
-            throw getMessage(`${prefix}: invalid authentication.\nRetry with valid passcode${
-                params.has('passcodeUrl') ? ` from ${params.get('passcodeUrl')}` : ''
-            } or username/password (required if SaaS app is configured with mocked-auth).`, { error, command });
+            throw getMessage(`${prefix}: invalid authentication` + (
+                params.has('username') ? `. Ensure that username and password are correct` : ''
+            ), { error, command });
         case 403:
-            throw getMessage(prefix + ': insufficient authorization. Ensure client has all necessary roles.', { error, command });
+            throw getMessage(prefix + ': insufficient authorization. Ensure the user has all necessary roles.', { error, command });
         case 404:
             throw getMessage(prefix + ': resource not found.', { error, command });
         case 422: