Merge branch 'development' into enh/dx-7265

Author: OMpawar-21

.cursor/rules/README.md

@@ -1,5 +1,5 @@
 # Cursor (optional)
 
-**Cursor** users: start at the repo root **[`AGENTS.md`](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`** (universal for any editor or tool).
+**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
 
-This folder only points contributors here so nothing editor-specific duplicates the canonical docs.
+This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.

.github/workflows/issues-jira.yml

@@ -133,8 +133,17 @@ tests/config/default.yml
 .vscode/settings.json
 run.py
 tests/resources/.DS_Store
-.talismanrc
 tests/.DS_Store
-tests/resources/.DS_Store
 .DS_Store
-.talismanrc
+*/data/regions.json
+# Local backup of legacy tests (do not commit)
+
+# --- CMA integration suite: do not track ---
+docs/
+tests_backup_legacy/
+tests/integration/report/
+tests/integration/.env
+tests/integration/.env.example
+# Timestamped reports written at repo root
+cma-python-report-*.html
+api-requests-*.txt

.gitignore

@@ -406,3 +406,7 @@ fileignoreconfig:
 - filename: tests/mock/assets/test_assets_mock.py
   checksum: 12c9091bb88c0c12712f046b29fb4a9dce3b95ecc45f4ea46bbc3fd4529742a0
 version: "1.0"
+fileignoreconfig:
+- filename: tests/integration/framework/capture.py
+  checksum: c9680c4ee3e1def0765fd89767fa1383aee5d195222fa021a19618607373047c
+version: "1.0"

.talismanrc

@@ -1,24 +1,24 @@
-# Contentstack Management Python — Agent guide
+# Contentstack Management Python – Agent guide
 
-**Universal entry point** for anyone automating or assisting work in this repo—AI agents (Cursor, Copilot, CLI tools), reviewers, and contributors. Conventions and detailed guidance live in **`skills/*/SKILL.md`**, not in editor-specific config, so the same instructions apply whether or not you use Cursor.
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
 
 ## What this repo is
 
-| | |
-|---|---|
-| **Name** | **`contentstack-management`** (PyPI) — **Contentstack Management Python SDK** |
-| **Purpose** | Python client for the **Content Management API (CMA)**: organizations, stacks, content types, entries, assets, webhooks, workflows, OAuth, and related resources. Uses **`requests`** via **`_APIClient`**. |
-| **Repository** | [contentstack/contentstack-management-python](https://github.com/contentstack/contentstack-management-python.git) |
+| Field | Detail |
+|--------|--------|
+| **Name:** | **`contentstack-management`** (PyPI) — [contentstack/contentstack-management-python](https://github.com/contentstack/contentstack-management-python) |
+| **Purpose:** | Python client for the **Content Management API (CMA)**: organizations, stacks, content types, entries, assets, webhooks, workflows, OAuth, and related resources. Uses **`requests`** via **`_APIClient`**. |
 
-## Tech stack
+## Tech stack (at a glance)
 
 | Area | Details |
 |------|---------|
-| **Language** | **Python** ≥ 3.9 (`setup.py` `python_requires`) |
-| **HTTP** | **`requests`**, **`requests-toolbelt`**, **`urllib3`** |
-| **Tests** | **pytest** — **`tests/unit`**, **`tests/api`**, **`tests/mock`** |
-| **Lint** | **pylint** (see `requirements.txt`) |
-| **Secrets / hooks** | **Talisman**, **Snyk** (see **README.md** development setup) |
+| Language | Python ≥ 3.9 (`setup.py` `python_requires`) |
+| Build | `setuptools` / `setup.py`; package `contentstack_management` |
+| HTTP | `requests`, `requests-toolbelt`, `urllib3` |
+| Tests | `pytest` — `tests/integration` (live e2e / sanity, dynamic stack), `tests/unit`, `tests/mock`, `tests/api` (legacy, superseded by `tests/integration`) |
+| Lint / coverage | `pylint`, `coverage` (see `requirements.txt`) |
+| Secrets / hooks | Talisman, Snyk (see `README.md` development setup) |
 
 ## Source layout
 
@@ -29,30 +29,44 @@
 | `contentstack_management/stack/stack.py` | **Stack**-scoped CMA operations |
 | `contentstack_management/*/` | Domain modules (entries, assets, webhooks, taxonomies, …) |
 | `contentstack_management/__init__.py` | Public exports |
-| `tests/cred.py` | **`get_credentials()`** — **dotenv** + env vars for API/mock tests |
+| `tests/integration/` | **Live e2e / sanity suite** (pytest). Self-contained: creates a fresh stack per run, exercises every SDK method (positive/negative/edge), tears it down. Own `framework/` + `data/`; config in `tests/integration/.env`. |
+| `tests/cred.py` | **`get_credentials()`** — **dotenv** + env vars for the legacy `tests/api` / `tests/mock` suites |
 
 ## Commands (quick reference)
 
-```bash
-pip install -e ".[dev]"
-# or: pip install -r requirements.txt && pip install pytest pytest-cov
+| Command Type | Command |
+|---|---|
+| Install | `pip install -e ".[dev]"` |
+| **Sanity / e2e (live)** | `pytest tests/integration` — dynamically creates a stack, runs the full suite, tears it down. Needs `tests/integration/.env` (`EMAIL`, `PASSWORD`, `HOST`, `ORGANIZATION`). Writes a timestamped HTML report + cURL log to the repo root. |
+| Sanity, keep stack | `DELETE_DYNAMIC_RESOURCES=false pytest tests/integration` (preserve the created stack for debugging) |
+| Sanity, one resource | `pytest tests/integration/api/test_12_content_type.py` |
+| Test (unit) | `pytest tests/unit/ -v` |
+| Test (mock) | `pytest tests/mock/ -v` |
+| Test (legacy API, live) | `pytest tests/api/ -v` (needs `.env` — see `tests/cred.py`) |
+| Coverage (CI) | `coverage run -m pytest tests/unit/` |
+| Lint | `pylint contentstack_management/` |
+
+> **CI note:** `.github/workflows/unit-test.yml` runs **only `tests/unit/`** (no credentials). The `tests/integration` sanity suite is run manually (or via a credential-gated job) because it provisions real stacks.
 
-pytest tests/unit/ -v
-pytest tests/api/ -v      # live CMA — needs .env (see tests/cred.py)
-pytest tests/mock/ -v
-pytest tests/ -v
-coverage run -m pytest tests/unit/
-```
+## Environment variables
 
-## Environment variables (API / integration tests)
+**Sanity / e2e suite** (`tests/integration`) — configured via **`tests/integration/.env`** (gitignored). No pre-existing stack/UIDs needed; the suite creates everything at runtime.
 
-Loaded via **`tests/cred.py`** (`load_dotenv()`). Examples include **`HOST`**, **`APIKEY`**, **`AUTHTOKEN`**, **`MANAGEMENT_TOKEN`**, **`ORG_UID`**, and resource UIDs (**`CONTENT_TYPE_UID`**, **`ENTRY_UID`**, …). See that file for the full list.
+| Var | Required | Purpose |
+|-----|----------|---------|
+| `EMAIL`, `PASSWORD` | ✅ | Login for the run (a **non-2FA** account) |
+| `HOST` | ✅ | API host (e.g. `api.contentstack.io`) |
+| `ORGANIZATION` | ✅ | Org the dynamic test stack is created in |
+| `MFA_SECRET` | — | TOTP secret (for the OAuth/2FA account, not the primary login) |
+| `DELETE_DYNAMIC_RESOURCES` | — | `false` keeps the created stack for debugging (default deletes) |
+| `CLIENT_ID`, `APP_ID`, `REDIRECT_URI` | — | OAuth tests |
+| `PERSONALIZE_HOST` | — | Personalize project for variant tests |
 
-Do not commit secrets.
+**Legacy `tests/api` / `tests/mock`** — loaded via **`tests/cred.py`** (`load_dotenv()`): `HOST`, `APIKEY`, `AUTHTOKEN`, `MANAGEMENT_TOKEN`, `ORG_UID`, and resource UIDs. See that file for the full list.
 
-## Where the real documentation lives: skills
+Do not commit secrets. `tests/integration/.env`, `docs/`, and the repo-root `cma-python-report-*.html` / `api-requests-*.txt` are gitignored.
 
-Read these **`SKILL.md` files** for full conventions—**this is the source of truth** for implementation and review:
+## Where the documentation lives: skills
 
 | Skill | Path | What it covers |
 |-------|------|----------------|
@@ -63,10 +77,10 @@ Read these **`SKILL.md` files** for full conventions—**this is the source of t
 | **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist—public API, HTTP/auth, tests, security |
 | **Framework / HTTP** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | **`requests`**, retries, OAuth interceptor, where to change transport |
 
-An index with short “when to use” hints is in [`skills/README.md`](skills/README.md).
+An index with “when to use” hints is in [`skills/README.md`](skills/README.md).
 
-## Using Cursor
+## Using Cursor (optional)
 
-If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same source of truth as everyone else; no separate `.mdc` rule files.
+If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.
 
 Product docs: [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/).

AGENTS.md

@@ -2,13 +2,51 @@
 
 ## Content Management SDK For Python
 ---
-## v1.9.0
+## v1.11.0
 
-#### Date:  18 May 2026
+#### Date:  20 July 2026
 
 - Entry variants: added `publish` and `unpublish` for the entry publish/unpublish endpoints; documented payloads including `entry.variants` and optional `entry.variant_rules` on publish.
 - Entry variants: optional stack branch via the `branch` request header; `Entry.variants()` accepts no arguments, a branch UID only, or `(variant_uid, branch)` (use `variants(variant_uid, None)` when targeting a variant without a branch).
 
+---
+## v1.10.2
+
+#### Date: 13 July 2026
+
+- Removed hardcoded password literals in unit tests to resolve Snyk CWE-798 (Use of Hardcoded Passwords) findings.
+
+---
+## v1.10.1
+
+#### Date: 26 June 2026
+
+- Fixed `Asset.update()` to send the JSON body with `Content-Type: application/json` instead of an invalid bare `multipart/form-data`, which the API rejected with 422.
+- Fixed `Asset.replace()` to let the HTTP layer set `multipart/form-data` with a proper boundary (a bare `multipart/form-data` header without a boundary previously caused a 422). Both fixes also remove a side effect that leaked the wrong `Content-Type` onto subsequent requests.
+
+---
+## v1.10.0
+
+#### Date: 22 June 2026
+
+- Dynamic region endpoint resolution via the Contentstack Regions Registry (`regions.json`).
+- Added `Endpoint` class with 3-tier resolution: in-memory cache → bundled `data/regions.json` → live CDN download.
+- Exposed `contentstack_management.get_contentstack_endpoint(region, service, omit_https)` module-level proxy.
+- `Client` now resolves the `contentManagement` endpoint from the registry instead of a hardcoded host pattern.
+- Bundled `contentstack_management/data/regions.json` included in `package_data` — always present after `pip install`.
+- `setup.py` auto-refreshes `regions.json` at build time via a custom `BuildPyWithRegions` command; network failures warn but never block the build.
+- Runtime fallback: if `regions.json` is absent, the SDK downloads it live on the first `Endpoint` call.
+- New regions and services require no SDK code changes — registry update is sufficient.
+- Added `refresh_regions()` utility to programmatically download the latest regions manifest from the Contentstack CDN and overwrite the bundled `data/regions.json` (`from contentstack_management import refresh_regions`).
+- Added `python3 -m contentstack_management.region_refresh` CLI command for refreshing the registry after `pip install` (source-tree script `scripts/download_regions.py` is for contributors only).
+
+---
+## v1.9.0
+
+#### Date:  01 June 2026
+
+- Removed unused `bson` dependency so the package installs on Python 3.12+ and 3.14 (the standalone `bson` 0.5.x package fails to build on newer Python versions).
+
 ---
 ## v1.8.1
 

CHANGELOG.md

@@ -18,6 +18,7 @@
 from .entries.entry import Entry
 from .entry_variants.entry_variants import EntryVariants
 from .contentstack import Client, Region
+from .endpoint import Endpoint
 from ._api_client import _APIClient
 from .common import Parameter
 from ._errors import ArgumentException
@@ -36,11 +37,13 @@
 from .variants.variants import Variants
 from .oauth.oauth_handler import OAuthHandler
 from .oauth.oauth_interceptor import OAuthInterceptor
+from .region_refresh import refresh_regions
 
 
 __all__ = (
 "Client",
 "Region",
+"Endpoint",
 "_APIClient",
 "Parameter",
 "ArgumentException",
@@ -75,14 +78,31 @@
 "VariantGroup",
 "Variants",
 "OAuthHandler",
-"OAuthInterceptor"
+"OAuthInterceptor",
+"refresh_regions",
 )
 
+def get_contentstack_endpoint(region='us', service='', omit_https=False):
+    """
+    Resolve a Contentstack service endpoint URL for a given region.
+
+    Proxy to :class:`Endpoint.get_contentstack_endpoint` for convenience —
+    mirrors ``Contentstack::getContentstackEndpoint()`` in the PHP SDK.
+
+    :param region: Region ID or alias ('us', 'eu', 'azure-na', 'gcp-eu', ...).
+    :param service: Service key ('contentDelivery', 'contentManagement', ...).
+                    When empty, returns a dict of all endpoints for the region.
+    :param omit_https: When True, strips 'https://' from the returned URL(s).
+    :returns: str when service is provided, dict[str,str] otherwise.
+    """
+    return Endpoint.get_contentstack_endpoint(region, service, omit_https)
+
+
 __title__ = 'contentstack-management-python'
 __author__ = 'dev-ex'
 __status__ = 'debug'
 __region__ = 'na'
-__version__ = '1.9.0'
+__version__ = '1.10.2'
 __host__ = 'api.contentstack.io'
 __protocol__ = 'https://'
 __api_version__ = 'v3'

contentstack_management/__init__.py

@@ -174,9 +174,17 @@ def replace(self, file_path):
         """
 
         url = f"assets/{self.asset_uid}"
-        Parameter.add_header(self, "Content-Type", "multipart/form-data")
-        files = {"asset": open(f"{file_path}",'rb')}
-        return self.client.put(url, headers = self.client.headers, params = self.params, files = files)
+        # _api_client._call_request does headers.update(self.headers) so a per-request
+        # copy is overwritten before the request is sent. The only way to suppress
+        # Content-Type is to temporarily remove it from the shared dict so requests can
+        # set multipart/form-data with the correct boundary automatically.
+        saved_ct = self.client.headers.pop("Content-Type", None)
+        try:
+            with open(file_path, 'rb') as fh:
+                return self.client.put(url, headers=self.client.headers, params=self.params, files={"asset": fh})
+        finally:
+            if saved_ct is not None:
+                self.client.headers["Content-Type"] = saved_ct
 
     def generate(self, data):
         """
@@ -407,8 +415,11 @@ def update(self, data):
         if self.asset_uid is None or '':
             raise Exception(ASSET_UID_REQUIRED)
         url = f"assets/{self.asset_uid}"
-        Parameter.add_header(self, "Content-Type", "multipart/form-data")
-        return self.client.put(url, headers = self.client.headers, params = self.params, data = data)
+        # Use a per-request header copy with Content-Type explicitly set to application/json
+        # so this call is not affected by whatever a preceding upload/replace left in
+        # the shared headers dict.
+        request_headers = {**self.client.headers, "Content-Type": "application/json"}
+        return self.client.put(url, headers=request_headers, params=self.params, data=data)
 
     def publish(self, data):
         """

contentstack_management/assets/assets.py

@@ -2,6 +2,7 @@
 import os
 import pyotp
 from ._api_client import _APIClient
+from .endpoint import Endpoint
 from contentstack_management.organizations import organization
 from contentstack_management.stack import stack
 from contentstack_management.user_session import user_session
@@ -37,16 +38,25 @@ def __init__(self, host: str = 'api.contentstack.io', scheme: str = 'https://',
                  authtoken: str = None , management_token=None, headers: dict = None,
                  region: Region = Region.US.value, version='v3', timeout=2, max_retries: int = 18, early_access: list = None,
                  oauth_config: dict = None, **kwargs):
-        self.endpoint = 'https://api.contentstack.io/v3/'
-        
-        if region is not None and region is not Region.US.value:
-            if host is not None and host != 'api.contentstack.io':
+        _DEFAULT_HOST = 'api.contentstack.io'
+        self.endpoint = f'{scheme}{_DEFAULT_HOST}/{version}/'
+
+        if host is None or host == _DEFAULT_HOST:
+            # No custom host — resolve via Endpoint (regions.json-driven)
+            try:
+                base = Endpoint.get_contentstack_endpoint(
+                    region or 'us', 'contentManagement', omit_https=True)
+                self.endpoint = f'{scheme}{base}/{version}/'
+            except (ValueError, RuntimeError):
+                # Unknown/custom region string — fall back to legacy pattern
+                if region and region != Region.US.value:
+                    self.endpoint = f'{scheme}{region}-api.contentstack.com/{version}/'
+        else:
+            # Explicit custom host always wins; apply region prefix when non-US
+            if region and region != Region.US.value:
                 self.endpoint = f'{scheme}{region}-api.{host}/{version}/'
             else:
-                host = 'api.contentstack.com'
-                self.endpoint = f'{scheme}{region}-{host}/{version}/'
-        elif host is not None and host != 'api.contentstack.io':
-            self.endpoint = f'{scheme}{host}/{version}/'
+                self.endpoint = f'{scheme}{host}/{version}/'
         if headers is None:
             headers = {}
         if early_access is not None: