Merge pull request #146 from contentstack/development

Added Security fixes, cursor rules and skill files

Author: cs-raj

.cursor/rules/README.md

@@ -0,0 +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).
+
+This folder only points contributors here so nothing editor-specific duplicates the canonical docs.

AGENTS.md

@@ -0,0 +1,72 @@
+# 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.
+
+## 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) |
+
+## Tech stack
+
+| 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) |
+
+## Source layout
+
+| Path | Role |
+|------|------|
+| `contentstack_management/contentstack.py` | **`Client`**, **`Region`**, endpoint construction, **`user_agents`**, optional **OAuth** wiring |
+| `contentstack_management/_api_client.py` | **`_APIClient`** — HTTP calls, retries, optional **OAuth** interceptor |
+| `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 |
+
+## Commands (quick reference)
+
+```bash
+pip install -e ".[dev]"
+# or: pip install -r requirements.txt && pip install pytest pytest-cov
+
+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 (API / integration tests)
+
+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.
+
+Do not commit secrets.
+
+## Where the real documentation lives: skills
+
+Read these **`SKILL.md` files** for full conventions—**this is the source of truth** for implementation and review:
+
+| Skill | Path | What it covers |
+|-------|------|----------------|
+| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Install, pytest suites, packaging version, pylint, hooks, PR baseline |
+| **Contentstack Management (SDK)** | [`skills/contentstack-management/SKILL.md`](skills/contentstack-management/SKILL.md) | **`Client`**, **`Stack`**, **`_APIClient`**, CMA resources, OAuth, CMA docs |
+| **Python style & repo layout** | [`skills/python-style/SKILL.md`](skills/python-style/SKILL.md) | Package layout, naming, imports via **`_APIClient`**, secrets in logs |
+| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | pytest unit / API / mock, **`tests/cred.py`**, env hygiene |
+| **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).
+
+## Using Cursor
+
+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.
+
+Product docs: [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/).

CHANGELOG.md

@@ -1,6 +1,13 @@
 # CHANGELOG
 
 ## Content Management SDK For Python
+---
+## v1.8.1
+
+#### Date:  15 April 2026
+
+- Fixed Security issues
+
 ---
 ## v1.8.0
 

contentstack_management/__init__.py

@@ -82,7 +82,7 @@
 __author__ = 'dev-ex'
 __status__ = 'debug'
 __region__ = 'na'
-__version__ = '1.8.0'
+__version__ = '1.8.1'
 __host__ = 'api.contentstack.io'
 __protocol__ = 'https://'
 __api_version__ = 'v3'

requirements.txt

@@ -1,9 +1,10 @@
 python-dotenv>=1.0.0,<2.0.0
 # <82: pkg_resources (used by coverage-badge and similar tools) was removed in setuptools 82+
 setuptools>=80.0.0,<82.0.0
-requests>=2.32.4,<3.0.0
+requests>=2.33.0,<3.0.0
 urllib3>=2.6.3,<3.0.0
 pylint>=2.0.0
 bson>=0.5.9,<1.0.0
 requests-toolbelt>=1.0.0,<2.0.0
 pyotp==2.9.0
+packaging>=24.0

setup.py

@@ -56,7 +56,7 @@ def get_author_email(package):
         "urllib3 >= 2.6.3",
     ],
     extras_require={
-        "dev": ["pytest>=7.0", "twine>=4.0.2", "dotenv>=0.0.5"],
+        "dev": ["pytest>=7.0", "twine>=4.0.2", "packaging>=24.0", "dotenv>=0.0.5"],
     },
     python_requires=">=3.9",
 )

skills/README.md

@@ -0,0 +1,19 @@
+# Skills — Contentstack Management Python
+
+**This directory is the source of truth** for conventions (workflow, SDK API, style, tests, review, HTTP layer). Read **`AGENTS.md`** at the repo root for the index and quick commands; each skill is a folder with **`SKILL.md`** (YAML frontmatter: `name`, `description`).
+
+## When to use which skill
+
+| Skill folder | Use when |
+|--------------|----------|
+| **dev-workflow** | Install, **`pytest`** (unit / API / mock), **`__version__`**, pylint, Talisman/Snyk, before PR |
+| **contentstack-management** | **`Client`**, **`Stack`**, **`_APIClient`**, domain modules, OAuth, CMA paths and payloads |
+| **python-style** | Editing **`contentstack_management/`** or **`setup.py`** / **`requirements.txt`**—layout, style, imports |
+| **testing** | Adding or changing tests under **`tests/`**, **`tests/cred.py`**, env for API runs |
+| **code-review** | PR checklist, API semver, HTTP regressions, secrets |
+| **framework** | Changing **`_APIClient`**, retries, **`requests`** usage, OAuth interceptor wiring |
+
+## How to use these docs
+
+- **Humans / any AI tool:** Start at **`AGENTS.md`**, then open the relevant **`skills/<name>/SKILL.md`**.
+- **Cursor users:** **`.cursor/rules/README.md`** only points to **`AGENTS.md`** so guidance stays universal—no duplicate `.mdc` rule sets.

skills/code-review/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: code-review
+description: PR checklist—public API, Client/Stack, _APIClient/OAuth, tests, secrets; align with README and exports.
+---
+
+# Code review — Contentstack Management Python
+
+## When to use
+
+- Reviewing a PR, self-review before submit, or automated review prompts.
+
+## Instructions
+
+Work through the checklist below. Optionally tag findings: **Blocker**, **Major**, **Minor**.
+
+### Public API
+
+- [ ] **Exported** **`Client`**, **`Region`**, stack and resource helpers match **README** and **`contentstack_management.__all__`** / **`__init__.py`**.
+- [ ] **Docstrings** on **`Client`** and changed public methods when behavior or parameters change.
+
+### Compatibility
+
+- [ ] Avoid breaking **`Client`** constructor or stack method chains without a semver strategy; document migration for breaking changes.
+
+### HTTP / auth
+
+- [ ] Changes to **`_APIClient`** or **OAuth** paths: verify retries, headers, and interceptor behavior with unit tests; no regressions for **authtoken** / **management_token** headers.
+
+### Testing
+
+- [ ] **Unit** coverage for new logic; **API** updates when live CMA request/response behavior changes; **mock** when contract-style tests are appropriate.
+- [ ] **`pytest tests/unit/`** passes.
+
+### Security
+
+- [ ] No hardcoded tokens; no logging secrets in new code.
+
+### Severity (optional)
+
+| Level | Examples |
+|-------|----------|
+| **Blocker** | Breaking public API without approval; security issue; no tests for new logic where tests are practical |
+| **Major** | Inconsistent HTTP/auth behavior; README examples that do not match code |
+| **Minor** | Style; minor docs |
+
+## References
+
+- **`skills/testing/SKILL.md`**
+- **`skills/contentstack-management/SKILL.md`**
+- **`skills/dev-workflow/SKILL.md`**

skills/contentstack-management/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: contentstack-management
+description: Public CMA surface—Client, Stack, _APIClient, domain resources, OAuth; align with CMA docs and semver.
+---
+
+# Contentstack Management — SDK skill
+
+## When to use
+
+- Implementing or changing **`Client`**, **Stack**, or resource modules (entries, assets, webhooks, …).
+- Updating **`README.md`** or public exports for user-visible behavior.
+- Assessing semver impact of constructor, method, or export changes.
+
+## Main entry (consumer API)
+
+- **`contentstack_management.Client`** in **`contentstack.py`**: builds CMA **endpoint** from **region** / **host** / **scheme**, merges **headers** (**authtoken**, **management_token**, **early_access**), constructs **`_APIClient`**, optional **`oauth_config`** with **`OAuthHandler`**.
+
+## Structure
+
+- **`Stack`** — **`contentstack_management/stack/stack.py`**: stack-scoped resources (content types, entries, assets, branches, webhooks, …).
+- **Org / user** — **`organizations/`**, **`users/`**, **`user_session/`** as applicable.
+- **Resources** — packages under **`contentstack_management/`** following existing patterns.
+- **OAuth** — **`oauth/oauth_handler.py`**, **`oauth/oauth_interceptor.py`**; keep aligned with **`_APIClient`** request path.
+
+## HTTP layer
+
+- **`_APIClient._call_request`** — central place for method, URL, JSON, files; respect **timeout** and **max_retries**.
+
+## Extending
+
+- Add methods on the appropriate resource class; align path and payload shapes with **CMA** docs.
+- Prefer routing HTTP through **`_APIClient`** for consistent retries and OAuth handling.
+
+## Docs and versioning
+
+- Exported **`Client`**, **`Region`**, and stack helpers should match **README** and **`contentstack_management.__init__.py`**.
+- Document migration for intentional breaking changes.
+
+## References
+
+- [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/)
+- **`skills/framework/SKILL.md`**
+- **`skills/python-style/SKILL.md`**

skills/dev-workflow/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: dev-workflow
+description: Install, pytest unit/API/mock, versioning, pylint, hooks—standard workflow for this SDK repo.
+---
+
+# Development workflow — Contentstack Management Python
+
+## When to use
+
+- Setting up locally, opening a PR, or matching CI expectations.
+- Answering “how do we run tests?” or “what runs in CI?”
+
+## Before a PR
+
+1. **Install** — `pip install -e ".[dev]"` or install **`requirements.txt`** plus **pytest** / **pytest-cov** as needed.
+2. **`pytest tests/unit/`** — required baseline (matches CI **`coverage run -m pytest tests/unit/`**).
+3. **API tests** — `pytest tests/api/` when your change affects live CMA behavior; configure **`.env`** per **`tests/cred.py`**. Never commit tokens.
+4. **Mock tests** — `pytest tests/mock/` when extending mocked HTTP or fixtures.
+
+## Packaging
+
+- Bump **`contentstack_management/__init__.py`** **`__version__`** and align **`setup.py`** versioning if release-facing.
+
+## Tooling
+
+- **pylint** is listed in **`requirements.txt`**; follow existing style in touched files.
+- **Husky / Talisman / Snyk** — see **README.md** for local hook setup.
+
+## Pull requests
+
+- Build passes: **`pytest tests/unit/`** at minimum; run **API** / **mock** when your change touches those layers.
+- Follow **`skills/code-review/SKILL.md`** before merge.
+- Prefer backward-compatible public API; call out breaking changes and semver.
+
+## References
+
+- **`AGENTS.md`**
+- **`skills/contentstack-management/SKILL.md`**
+- **`skills/testing/SKILL.md`**