Merge branch 'development' into feat/taxonomy-publishing

Author: harshithad0703

.talismanrc

@@ -9,7 +9,7 @@ fileignoreconfig:
     ignore_detectors:
       - filecontent
   - filename: package-lock.json
-    checksum: bab53d56ce2609e960fdbbd1e87cc89915820e6761016ddd74ee57f931f4223d
+    checksum: 17b5bbabcc58beaa180a7fa931fc3fb407ee0e3447d47da224f60118c0a4c294
   - filename: .husky/pre-commit
     checksum: 52a664f536cf5d1be0bea19cb6031ca6e8107b45b6314fe7d47b7fad7d800632
   - filename: test/sanity-check/api/user-test.js
@@ -30,4 +30,11 @@ fileignoreconfig:
     checksum: b76ca091caa3a1b2658cd422a2d8ef3ac9996aea0aff3f982d56bb309a3d9fde
   - filename: test/unit/ContentstackClient-test.js
     checksum: 974a4f335aef025b657d139bb290233a69bed1976b947c3c674e97baffe4ce2f
+  - filename: test/unit/ContentstackHTTPClient-test.js
+    checksum: 4043efd843e24da9afd0272c55ef4b0432e3374b2ca12b913f1a6654df3f62be
+  - filename: test/unit/contentstack-test.js
+    checksum: 2597efae3c1ab8cc173d5bf205f1c76932211f8e0eb2a16444e055d83481976c
 version: "1.0"
+
+
+

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [v1.27.2](https://github.com/contentstack/contentstack-management-javascript/tree/v1.27.2) (2026-01-12)
+ - Enhancement
+   - Improved error messages
+   - params support in entry variants update
+
+## [v1.27.1](https://github.com/contentstack/contentstack-management-javascript/tree/v1.27.1) (2026-01-5)
+ - Fix
+   - Resolve qs dependency version
+
+## [v1.27.0](https://github.com/contentstack/contentstack-management-javascript/tree/v1.27.0) (2025-12-15)
+ - Enhancement
+   - Refactored region endpoint resolution to use centralized `@contentstack/utils` package
+   - Improved region handling flexibility by leveraging shared utility functions
+
+## [v1.26.0](https://github.com/contentstack/contentstack-management-javascript/tree/v1.26.0) (2025-10-20)
+ - Enhancement
+   - Added taxonomy localization support
+
 ## [v1.25.1](https://github.com/contentstack/contentstack-management-javascript/tree/v1.25.1) (2025-10-06)
  - Fix
    - Updated delay handling to use centralized external configuration in SDK interceptor

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2012-2025 Contentstack
+Copyright (c) 2012-2026 Contentstack
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

lib/contentstack.js

@@ -7,15 +7,7 @@ import clonedeep from 'lodash/cloneDeep'
 import getUserAgent from './core/Util.js'
 import contentstackClient from './contentstackClient.js'
 import httpClient from './core/contentstackHTTPClient.js'
-const regionHostMap = {
-  NA: 'api.contentstack.io',
-  EU: 'eu-api.contentstack.com',
-  AU: 'au-api.contentstack.com',
-  AZURE_NA: 'azure-na-api.contentstack.com',
-  AZURE_EU: 'azure-eu-api.contentstack.com',
-  GCP_NA: 'gcp-na-api.contentstack.com',
-  GCP_EU: 'gcp-eu-api.contentstack.com'
-}
+import { getContentstackEndpoint } from '@contentstack/utils'
 
 /**
  * Create client instance
@@ -27,7 +19,10 @@ const regionHostMap = {
  * const client = contentstack.client()
  *
  * @param {object} params - Client initialization parameters
- * @param {Object=} param.proxy -
+ * @param {Object=} params.proxy - Proxy configuration object for HTTP requests
+ * @param {string=} params.region - Region for API endpoint (NA, EU, AU, AZURE_NA, AZURE_EU, GCP_NA, GCP_EU)
+ * @param {string=} params.feature - Feature identifier for user agent
+ * @param {string=} params.refreshToken - Refresh token for OAuth authentication
  * @prop {string=} params.endpoint - API endpoint that a service will talk to
  * @example //Set the `endpoint` to 'https://api.contentstack.io:{port}/{version}'
  * import * as contentstack from '@contentstack/management'
@@ -48,7 +43,7 @@ const regionHostMap = {
  * import * as contentstack from '@contentstack/management'
  * const client = contentstack.client({ authtoken: 'value' })
  *
- * @prop {string=} params.early_access - Optional early_access is a token used for early access of new features in CMA requests.
+ * @prop {Array<string>=} params.early_access - Optional array of early access tokens used for early access of new features in CMA requests.
  * @example //Set the `early_access`
  * import * as contentstack from '@contentstack/management'
  * const client = contentstack.client({ early_access: ['ea1', 'ea2'] })
@@ -127,7 +122,7 @@ const regionHostMap = {
  * 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}`)
+        console.error(`An error occurred due to ${title}. Review the details and try again.`)
         return
       }
       console.log(`[${level}] ${data}`)
@@ -167,21 +162,44 @@ const regionHostMap = {
  *
  * @prop {string=} params.application - Application name and version e.g myApp/version
  * @prop {string=} params.integration - Integration name and version e.g react/version
- * @returns Contentstack.Client
+ * @prop {string=} params.region - API region. Valid values: 'na', 'eu', 'au', 'azure_na', 'azure_eu', 'gcp_na', 'gcp_eu' (default: 'na')
+ * @example //Set the `region` to 'eu'
+ * import * as contentstack from '@contentstack/management'
+ * const client = contentstack.client({ region: 'eu' })
+ *
+ * @prop {string=} params.feature - Feature identifier for user agent header
+ * @prop {Array<Object>=} params.plugins - Optional array of plugin objects. Each plugin must have `onRequest` and `onResponse` methods.
+ * @example //Set plugins to intercept and modify requests/responses
+ * import * as contentstack from '@contentstack/management'
+ * const client = contentstack.client({
+ *   plugins: [
+ *     {
+ *       onRequest: (request) => {
+ *         // Return modified request
+ *         return {
+ *           ...request,
+ *           headers: {
+ *             ...request.headers,
+ *             'X-Custom-Header': 'value'
+ *           }
+ *         }
+ *       },
+ *       onResponse: (response) => {
+ *         // Return modified response
+ *         return response
+ *       }
+ *     }
+ *   ]
+ * })
+ * @returns {ContentstackClient} Instance of ContentstackClient
  */
 export function client (params = {}) {
-  let defaultHostName
+  let defaultHostName = params.region
+    ? getContentstackEndpoint(params.region.toUpperCase(), 'contentManagement', true)
+    : getContentstackEndpoint('NA', 'contentManagement', true)
 
-  if (params.region) {
-    const region = params.region.toUpperCase()
-    if (!regionHostMap[region]) {
-      throw new Error(`Invalid region '${params.region}' provided. Allowed regions are: ${Object.keys(regionHostMap).join(', ')}`)
-    }
-    defaultHostName = regionHostMap[region]
-  } else if (params.host) {
+  if (params.host) {
     defaultHostName = params.host
-  } else {
-    defaultHostName = regionHostMap['NA']
   }
 
   const defaultParameter = {

lib/contentstackClient.js

@@ -19,21 +19,22 @@ export default function contentstackClient ({ http }) {
    * @prop {string} parameters.password - password for user to login
    * @prop {string} parameters.tfa_token - tfa token for user to login (2FA token)
    * @prop {string} parameters.mfaSecret - TOTP secret key for generating 2FA token
-   * @returns {Promise}
+   * @param {Object=} params - Optional request parameters
+   * @returns {Promise<Object>} Promise for login response
    * @example
    * import * as contentstack from '@contentstack/management'
    * const client = contentstack.client()
    *
    * client.login({ email: <emailid>, password: <password> })
-   * .then(() => console.log('Logged in successfully'))
+   * .then(() => console.log('Login successful.'))
    *
    * @example
    * client.login({ email: <emailid>, password: <password>, tfa_token: <tfa_token> })
-   * .then(() => console.log('Logged in successfully'))
+   * .then(() => console.log('Login successful.'))
    *
    * @example
    * client.login({ email: <emailid>, password: <password>, mfaSecret: <mfa_secret> })
-   * .then(() => console.log('Logged in successfully'))
+   * .then(() => console.log('Login successful.'))
    */
   function login (requestBody = {}, params = {}) {
     http.defaults.versioningStrategy = 'path'
@@ -59,7 +60,8 @@ export default function contentstackClient ({ http }) {
    * The information returned includes details of the stacks owned by and shared with the specified user account.
    * @memberof ContentstackClient
    * @func getUser
-   * @returns {Promise}
+   * @param {Object=} params - Optional request parameters
+   * @returns {Promise<Object>} Promise for User instance
    * @example
    * import * as contentstack from '@contentstack/management'
    * const client = contentstack.client()
@@ -78,10 +80,11 @@ export default function contentstackClient ({ http }) {
    * @description Get Stack instance. A stack is a space that stores the content of a project.
    * @memberof ContentstackClient
    * @func stack
-   * @param {String} api_key - Stack API Key
-   * @param {String} management_token - Management token for Stack.
-   * @param {String} branch_name - Branch name or alias to access specific branch. Default is master.
-   * @returns {Stack} Instance of Stack
+   * @param {Object=} params - Stack initialization parameters
+   * @prop {String} params.api_key - Stack API Key
+   * @prop {String} params.management_token - Management token for Stack.
+   * @prop {String} params.branch_uid - Branch UID or alias to access specific branch. Default is master.
+   * @returns {Stack} Instance of Stack.
    *
    * @example
    * import * as contentstack from '@contentstack/management'
@@ -121,7 +124,7 @@ export default function contentstackClient ({ http }) {
    * @description Organization is the top-level entity in the hierarchy of Contentstack, consisting of stacks and stack resources, and users.
    * @memberof ContentstackClient
    * @func organization
-   * @param {String} uid - Organization UID.
+   * @param {String=} uid - Organization UID. If not provided, returns organization instance for querying all organizations.
    * @returns {Organization} Instance of Organization.
    *
    * @example
@@ -152,7 +155,7 @@ export default function contentstackClient ({ http }) {
    * @memberof ContentstackClient
    * @param {String} authtoken - Authtoken to logout from.
    * @func logout
-   * @returns {Object} Response object.
+   * @returns {Promise<Object>} Promise for response object.
    *
    * @example
    * import * as contentstack from '@contentstack/management'
@@ -195,19 +198,19 @@ export default function contentstackClient ({ http }) {
    * @memberof ContentstackClient
    * @func oauth
    * @param {Object} parameters - oauth parameters
-   * @prop {string} parameters.appId - appId of the application
-   * @prop {string} parameters.clientId - clientId of the application
-   * @prop {string} parameters.clientId - clientId of the application
-   * @prop {string} parameters.responseType - responseType
-   * @prop {string} parameters.scope - scope
-   * @prop {string} parameters.clientSecret - clientSecret of the application
-   * @returns {OAuthHandler} Instance of OAuthHandler
+   * @prop {string=} parameters.appId - appId of the application (default: '6400aa06db64de001a31c8a9')
+   * @prop {string=} parameters.clientId - clientId of the application (default: 'Ie0FEfTzlfAHL4xM')
+   * @prop {string=} parameters.redirectUri - redirect URI for OAuth callback (default: 'http://localhost:8184')
+   * @prop {string=} parameters.responseType - responseType (default: 'code')
+   * @prop {string=} parameters.scope - scope
+   * @prop {string=} parameters.clientSecret - clientSecret of the application
+   * @returns {OAuthHandler} Instance of OAuthHandler.
    * @example
    * import * as contentstack from '@contentstack/management'
    * const client = contentstack.client()
    *
    * client.oauth({ appId: <appId>, clientId: <clientId>, redirectUri: <redirectUri>, clientSecret: <clientSecret>, responseType: <responseType>, scope: <scope> })
-   * .then(() => console.log('Logged in successfully'))
+   * .then(() => console.log('Login successful.'))
    *
    */
   function oauth (params = {}) {

lib/contentstackCollection.js

@@ -2,6 +2,13 @@
  * @namespace ContentstackCollection
  */
 export default class ContentstackCollection {
+  /**
+   * Creates a ContentstackCollection instance.
+   * @param {Object} response - HTTP response object.
+   * @param {Object} http - HTTP client instance.
+   * @param {Object=} stackHeaders - Stack headers to include in data.
+   * @param {Function=} wrapperCollection - Collection wrapper function to transform items.
+   */
   constructor (response, http, stackHeaders = null, wrapperCollection) {
     const data = response.data || {}
     if (stackHeaders) {

lib/core/Util.js

@@ -1,4 +1,6 @@
 import { platform, release } from 'os'
+import { ERROR_MESSAGES } from './errorMessages'
+
 const HOST_REGEX = /^(?!(?:(?:https?|ftp):\/\/|internal|localhost|(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)))(?:[\w-]+\.contentstack\.(?:io|com)(?::[^\/\s:]+)?|[\w-]+(?:\.[\w-]+)*(?::[^\/\s:]+)?)(?![\/?#])$/  // eslint-disable-line
 
 export function isHost (host) {
@@ -217,7 +219,7 @@ const isAllowedHost = (hostname) => {
 
 export const validateAndSanitizeConfig = (config) => {
   if (!config?.url || typeof config?.url !== 'string') {
-    throw new Error('Invalid request configuration: missing or invalid URL')
+    throw new Error(ERROR_MESSAGES.INVALID_URL_CONFIG)
   }
 
   // Validate the URL to prevent SSRF attacks
@@ -235,3 +237,26 @@ export const validateAndSanitizeConfig = (config) => {
     url: config.url.trim() // Sanitize URL by removing whitespace
   }
 }
+
+/**
+ * Normalizes and validates plugin array
+ * @param {Array|undefined} plugins - Array of plugin objects
+ * @returns {Array} Normalized array of plugins
+ */
+export function normalizePlugins (plugins) {
+  if (!plugins) {
+    return []
+  }
+
+  if (!Array.isArray(plugins)) {
+    return []
+  }
+
+  return plugins.filter(plugin => {
+    if (!plugin || typeof plugin !== 'object') {
+      return false
+    }
+    // Plugin must have both onRequest and onResponse methods
+    return typeof plugin.onRequest === 'function' && typeof plugin.onResponse === 'function'
+  })
+}