Refactor logging and error handling in Contentstack client

lib/assets/regions.json

@@ -9,7 +9,11 @@
         "na",
         "us",
         "aws-na",
-        "aws_na"
+        "aws_na",
+        "NA",
+        "US",
+        "AWS-NA",
+        "AWS_NA"
       ],
       "isDefault": true,
       "endpoints": {
@@ -27,7 +31,7 @@
         "developerHub": "https://developerhub-api.contentstack.com",
         "brandKit": "https://brand-kits-api.contentstack.com",
         "genAI": "https://ai.contentstack.com",
-        "personalize": "https://personalize-api.contentstack.com",
+        "personalizeManagement": "https://personalize-api.contentstack.com",
         "personalizeEdge": "https://personalize-edge.contentstack.com"
       }
     },
@@ -39,7 +43,10 @@
       "alias": [
         "eu",
         "aws-eu",
-        "aws_eu"
+        "aws_eu",
+        "EU",
+        "AWS-EU",
+        "AWS_EU"
       ],
       "isDefault": false,
       "endpoints": {
@@ -57,7 +64,7 @@
         "developerHub": "https://eu-developerhub-api.contentstack.com",
         "brandKit": "https://eu-brand-kits-api.contentstack.com",
         "genAI": "https://eu-ai.contentstack.com",
-        "personalize": "https://eu-personalize-api.contentstack.com",
+        "personalizeManagement": "https://eu-personalize-api.contentstack.com",
         "personalizeEdge": "https://eu-personalize-edge.contentstack.com"
       }
     },
@@ -69,7 +76,10 @@
       "alias": [
         "au",
         "aws-au",
-        "aws_au"
+        "aws_au",
+        "AU",
+        "AWS-AU",
+        "AWS_AU"
       ],
       "isDefault": false,
       "endpoints": {
@@ -87,7 +97,7 @@
         "developerHub": "https://au-developerhub-api.contentstack.com",
         "brandKit": "https://au-brand-kits-api.contentstack.com",
         "genAI": "https://au-ai.contentstack.com",
-        "personalize": "https://au-personalize-api.contentstack.com",
+        "personalizeManagement": "https://au-personalize-api.contentstack.com",
         "personalizeEdge": "https://au-personalize-edge.contentstack.com"
       }
     },
@@ -98,7 +108,9 @@
       "location": "North America",
       "alias": [
         "azure-na",
-        "azure_na"
+        "azure_na",
+        "AZURE-NA",
+        "AZURE_NA"
       ],
       "isDefault": false,
       "endpoints": {
@@ -116,7 +128,7 @@
         "developerHub": "https://azure-na-developerhub-api.contentstack.com",
         "brandKit": "https://azure-na-brand-kits-api.contentstack.com",
         "genAI": "https://azure-na-ai.contentstack.com",
-        "personalize": "https://azure-na-personalize-api.contentstack.com",
+        "personalizeManagement": "https://azure-na-personalize-api.contentstack.com",
         "personalizeEdge": "https://azure-na-personalize-edge.contentstack.com"
       }
     },
@@ -127,7 +139,9 @@
       "location": "Europe",
       "alias": [
         "azure-eu",
-        "azure_eu"
+        "azure_eu",
+        "AZURE-EU",
+        "AZURE_EU"
       ],
       "isDefault": false,
       "endpoints": {
@@ -145,7 +159,7 @@
         "developerHub": "https://azure-eu-developerhub-api.contentstack.com",
         "brandKit": "https://azure-eu-brand-kits-api.contentstack.com",
         "genAI": "https://azure-eu-ai.contentstack.com",
-        "personalize": "https://azure-eu-personalize-api.contentstack.com",
+        "personalizeManagement": "https://azure-eu-personalize-api.contentstack.com",
         "personalizeEdge": "https://azure-eu-personalize-edge.contentstack.com"
       }
     },
@@ -156,7 +170,9 @@
       "location": "North America",
       "alias": [
         "gcp-na",
-        "gcp_na"
+        "gcp_na",
+        "GCP-NA",
+        "GCP_NA"
       ],
       "isDefault": false,
       "endpoints": {
@@ -174,7 +190,7 @@
         "developerHub": "https://gcp-na-developerhub-api.contentstack.com",
         "brandKit": "https://gcp-na-brand-kits-api.contentstack.com",
         "genAI": "https://gcp-na-brand-kits-api.contentstack.com",
-        "personalize": "https://gcp-na-personalize-api.contentstack.com",
+        "personalizeManagement": "https://gcp-na-personalize-api.contentstack.com",
         "personalizeEdge": "https://gcp-na-personalize-edge.contentstack.com"
       }
     },
@@ -185,7 +201,9 @@
       "location": "Europe",
       "alias": [
         "gcp-eu",
-        "gcp_eu"
+        "gcp_eu",
+        "GCP-EU",
+        "GCP_EU"
       ],
       "isDefault": false,
       "endpoints": {
@@ -203,9 +221,9 @@
         "developerHub": "https://gcp-eu-developerhub-api.contentstack.com",
         "brandKit": "https://gcp-eu-brand-kits-api.contentstack.com",
         "genAI": "https://gcp-eu-brand-kits-api.contentstack.com",
-        "personalize": "https://gcp-eu-personalize-api.contentstack.com",
+        "personalizeManagement": "https://gcp-eu-personalize-api.contentstack.com",
         "personalizeEdge": "https://gcp-eu-personalize-edge.contentstack.com"
       }
     }
   ]
-}
+}

lib/contentstack.js

@@ -111,14 +111,8 @@ import Region from './core/region.js'
  * @prop {function=} params.logHandler - A log handler function to process given log messages & errors.
  * @example //Set the `logHandler`
  * import * as contentstack from '@contentstack/management'
- * const client = contentstack.client({ logHandler: (level, data) => {
-      if (level === 'error' && data) {
-        const title = [data.name, data.message].filter((a) => a).join(' - ')
-        console.error(`[error] ${title}`)
-        return
-      }
-      console.log(`[${level}] ${data}`)
-    } })
+ * import { logHandler } from '@contentstack/management/core/messageHandler'
+ * const client = contentstack.client({ logHandler: logHandler })
  *
  * @prop {function=} params.refreshToken - Optional function used to refresh token.
  * @example // OAuth example

lib/contentstackClient.js

@@ -5,6 +5,7 @@
 import error from './core/contentstackError'
 import { Marketplace } from './marketplace/index.js'
 import { Region } from './contentstack.js'
+import { MESSAGES } from './core/messageHandler.js'
 
 export default function contentstackClient ({ http }) {
   /**
@@ -20,8 +21,8 @@ export default function contentstackClient ({ http }) {
    * import * as contentstack from '@contentstack/management'
    * const client = contentstack.client()
    *
-   * client.login({ email: <emailid>, password: <password> })
-   * .then(() => console.log('Logged in successfully'))
+ * client.login({ email: <emailid>, password: <password> })
+ * .then(() => console.log(MESSAGES.LOGIN_SUCCESS))
    *
    * client.marketplace()
    */
@@ -59,8 +60,8 @@ export default function contentstackClient ({ http }) {
    * import * as contentstack from '@contentstack/management'
    * const client = contentstack.client()
    *
-   * client.organization().findAll()
-   * .then((organization) => console.log(organization))
+ * client.organization().findAll()
+ * .then((organization) => console.log(MESSAGES.ORGANIZATION_LOADED))
    *
    * @example
    * import * as contentstack from '@contentstack/management'
@@ -84,14 +85,14 @@ export default function contentstackClient ({ http }) {
    * @example
    * import * as contentstack from '@contentstack/management'
    * const client = contentstack.client()
-   * client.logout()
-   * .then((response) => console.log(response))
+ * client.logout()
+ * .then((response) => console.log(MESSAGES.API_RESPONSE_SUCCESS))
    *
    * @example
    * import * as contentstack from '@contentstack/management'
    * const client = contentstack.client()
-   * client.logout('AUTHTOKEN')
-   * .then((response) => console.log(response))
+ * client.logout('AUTHTOKEN')
+ * .then((response) => console.log(MESSAGES.API_RESPONSE_SUCCESS))
    *   */
   function logout (authtoken) {
     http.defaults.versioningStrategy = 'path'

lib/core/contentstackHTTPClient.js

@@ -3,19 +3,13 @@ import clonedeep from 'lodash/cloneDeep'
 import Qs from 'qs'
 import { ConcurrencyQueue } from './concurrency-queue'
 import { isHost } from './Util'
+import { httpLogHandler } from './messageHandler.js'
 
 export default function contentstackHttpClient (options) {
   const defaultConfig = {
     insecure: false,
     retryOnError: true,
-    logHandler: (level, data) => {
-      if (level === 'error' && data) {
-        const title = [data.name, data.message].filter((a) => a).join(' - ')
-        console.error(`[error] ${title}`)
-        return
-      }
-      console.log(`[${level}] ${data}`)
-    },
+    logHandler: httpLogHandler,
     retryCondition: (error) => {
       if (error.response && error.response.status === 429) {
         return true

lib/core/messageHandler.js

@@ -0,0 +1,136 @@
+/**
+ * Centralized message handler for all console logs and error messages
+ * @namespace MessageHandler
+ */
+
+/**
+ * Success messages catalog
+ */
+export const MESSAGES = {
+  // Authentication
+  LOGIN_SUCCESS: 'Login successful.',
+
+  // Organization - Includes org UID, name, metadata
+  ORGANIZATION_LOADED: 'Organization details loaded successfully.',
+
+  // API Responses
+  API_RESPONSE_SUCCESS: 'API response received successfully.',
+  API_RESPONSE_APP_OPERATION: 'API response received for app operation.',
+
+  // Marketplace
+  MARKETPLACE_API_RESPONSE: 'Marketplace API response received.',
+  MARKETPLACE_ROLES_LOADED: 'Marketplace roles loaded successfully.',
+
+  // Apps - Includes UID, name, description, config
+  APP_LOADED: 'App details loaded successfully.',
+  APP_COLLECTION_LOADED: 'App collection loaded successfully.',
+  APP_REQUEST_RESPONSE: 'App request response received successfully.',
+
+  // Installations - Includes installation UID, app UID, status, config
+  INSTALLATION_LOADED: 'App installation details loaded successfully.',
+  INSTALLATIONS_LOADED: 'App installation details loaded successfully.',
+  INSTALLATION_RESPONSE: 'Installation response received.',
+  INSTALLATION_COLLECTION_LOADED: 'Installation collection loaded successfully.',
+  INSTALLATION_WEBHOOK_LOADED: 'Installation webhook details loaded successfully.',
+
+  // Authorization - Includes redirect URIs, auth codes (no tokens for security)
+  AUTHORIZATION_RESPONSE: 'Authorization response received.',
+
+  // OAuth - WARNING: May contain sensitive values (client_secret)
+  OAUTH_CONFIG_LOADED: 'OAuth configuration loaded successfully.',
+  OAUTH_SCOPES_LOADED: 'OAuth scopes loaded successfully.',
+
+  // Slack
+  SLACK_MESSAGE_SENT: 'Slack message sent successfully.'
+}
+
+/**
+ * Error messages catalog
+ * All errors include: status, statusText, errorMessage, errorCode, errors object, request details
+ */
+export const ERROR_MESSAGES = {
+  // General Request Errors
+  REQUEST_FAILED: (title) => `Request failed: ${title}. Review the error details and try again.`,
+  HTTP_REQUEST_FAILED: (title) => `HTTP request failed: ${title}. Verify your request and try again.`,
+
+  // App Request Errors - Operations: create, update, fetch, delete, install
+  APP_REQUEST_PROCESS_FAILED: 'App request process failed. Check the response details and try again.',
+  APP_REQUEST_ERROR: 'App request failed. Check the error details and try again.',
+  APP_REQUEST_REVIEW: 'App request failed. Review the error details and try again.',
+  APP_REQUEST_FAILED: 'Failed to process app request. Check the response details and try again.',
+  APP_OPERATION_ERROR: 'App operation error. Review the error details and try again.',
+  APP_REQUEST_RESPONSE_RECEIVED: 'App request response received.',
+
+  // Authorization Errors - Common causes: invalid client_id, unauthorized redirect_uri, expired codes
+  AUTHORIZATION_FAILED: 'Failed to process authorization request. Check the response details and try again.',
+  AUTHORIZATION_ERROR: 'Authorization failed. Check the error details and try again.',
+  AUTHORIZATION_REVIEW: 'Authorization failed. Review the error details and try again.',
+  AUTHORIZATION_RESPONSE_RECEIVED: 'Authorization response received.',
+
+  // Deployment Errors - Common causes: build failures, config issues, timeouts
+  DEPLOYMENT_FAILED: 'Deployment failed. Check the response details for errors and try again.',
+  DEPLOYMENT_ERROR: 'Deployment error occurred. Review the error details and try again.',
+
+  // Hosting Errors - Common causes: invalid config, timeouts, deployment failures
+  HOSTING_REQUEST_FAILED: 'Hosting request failed. Check the response details and try again.',
+  HOSTING_ERROR: 'Hosting error occurred. Review the error details and try again.',
+  HOSTING_REQUEST_ERROR: 'Hosting request error. Review the error details and try again.',
+
+  // OAuth Errors - Common causes: invalid credentials, expired tokens, scope errors
+  OAUTH_REQUEST_FAILED: 'OAuth request failed. Check the response details and try again.',
+  OAUTH_ERROR: 'OAuth error occurred. Review the error details and try again.',
+
+  // Installation Errors - Operations: fetch, update, uninstall, config
+  INSTALLATION_REQUEST_FAILED: 'Installation request failed. Check the response details and try again.',
+  INSTALLATION_ERROR: 'Installation error occurred. Review the error details and try again.',
+  INSTALLATION_WEBHOOK_FAILED: 'Installation webhook request failed. Check the response details and try again.',
+  INSTALLATION_WEBHOOK_ERROR: 'Installation webhook error occurred. Review the error details and try again.',
+
+  // Entity Errors - Operations: create, read, update, delete
+  ENTITY_REQUEST_FAILED: 'Entity request failed. Check the response details and try again.',
+  ENTITY_ERROR: 'Entity error occurred. Review the error details and try again.',
+
+  // Marketplace Errors
+  MARKETPLACE_REQUEST_FAILED: 'Marketplace request failed. Review the error details and try again.',
+
+  // Generic Errors
+  GENERIC_ERROR: 'An error occurred. Check the details and try again.'
+}
+
+/**
+ * Log level constants
+ */
+export const LOG_LEVELS = {
+  ERROR: 'error',
+  INFO: 'info',
+  WARN: 'warn'
+}
+
+/**
+ * Log handler for general operations
+ * @param {string} level - Log level (error, info, warn)
+ * @param {*} data - Data to log
+ */
+export const logHandler = (level, data) => {
+  if (level === LOG_LEVELS.ERROR && data) {
+    const title = [data.name, data.message].filter((a) => a).join(' - ')
+    console.error(`${ERROR_MESSAGES.REQUEST_FAILED(title)}`)
+    return
+  }
+  console.log(`${level}: ${data}. Check the details for troubleshooting.`)
+}
+
+/**
+ * Log handler for HTTP client operations
+ * @param {string} level - Log level (error, info, warn)
+ * @param {*} data - Data to log
+ */
+export const httpLogHandler = (level, data) => {
+  if (level === LOG_LEVELS.ERROR && data) {
+    const title = [data.name, data.message].filter((a) => a).join(' - ')
+    console.error(`${ERROR_MESSAGES.HTTP_REQUEST_FAILED(title)}`)
+    return
+  }
+  console.log(`${level}: ${data}. Check the HTTP client logs for more information.`)
+}
+

lib/entity.js

@@ -1,6 +1,7 @@
 import error from './core/contentstackError'
 import cloneDeep from 'lodash/cloneDeep'
 import ContentstackCollection from './contentstackCollection'
+import { ERROR_MESSAGES } from './core/messageHandler.js'
 
 export const create = ({ http, params }) => {
   return async function (data, param) {

lib/marketplace/app/hosting/deployment.js

@@ -1,6 +1,7 @@
 import cloneDeep from 'lodash/cloneDeep'
 import ContentstackCollection from '../../../contentstackCollection'
 import error from '../../../core/contentstackError'
+import { ERROR_MESSAGES } from '../../../core/messageHandler.js'
 
 /**
  *

lib/marketplace/app/hosting/index.js

@@ -1,6 +1,7 @@
 import cloneDeep from 'lodash/cloneDeep'
 import error from '../../../core/contentstackError'
 import { Deployment } from './deployment'
+import { ERROR_MESSAGES } from '../../../core/messageHandler.js'
 
 /**
  *