Development

.cursor/rules/README.md

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

.cursor/rules/code-review.mdc

@@ -0,0 +1,38 @@
+---
+description: "PR review themes — API docs, compatibility, errors, security, tests (CDA SDK)"
+alwaysApply: true
+---
+
+# Code review checklist (CDA JavaScript SDK)
+
+Apply when reviewing changes to the **`contentstack`** npm package (Content Delivery API client).
+
+## Public API & documentation
+
+- **JSDoc** updated for new or changed public methods/classes (params, return shape, examples), matching style in `src/core/contentstack.js` / `src/core/stack.js`.
+- **`index.d.ts`** updated when TypeScript consumers would see different signatures or new exports.
+
+## Backward compatibility
+
+- Avoid breaking changes to exported function signatures, option objects, or default behavior without a major version rationale.
+- If behavior changes, ensure **callers inside `src/`** and tests reflect the new contract.
+
+## Errors & safety
+
+- HTTP failures should continue to reject with a predictable shape from **`src/core/lib/request.js`** where applicable (**`error_message`**, **`error_code`**, **`errors`**, **`status`**, **`statusText`**).
+- Do not log full **delivery_token**, **preview_token**, **management_token**, or **api_key** values.
+- Respect **null/undefined** edge cases for optional API fields.
+
+## Dependencies & supply chain
+
+- New **dependencies** should be justified (size, maintenance, license).
+- Lockfile and **`package.json`** version bumps should be minimal and reviewable.
+
+## Tests
+
+- **Jest** tests for new logic or regressions under **`test/`** (JS and/or **`test/typescript/`** as appropriate).
+- Live stack tests must remain compatible with **`test/config.js`** env requirements; document new env needs in **`test/README.md`** or comments near the harness — never commit credentials.
+
+## Security & privacy
+
+- No hardcoded credentials; no accidental exposure of customer content in logs or error messages.

.cursor/rules/contentstack-javascript-cda.mdc

@@ -0,0 +1,36 @@
+---
+description: "Contentstack CDA SDK patterns in src/core (Content Delivery API)"
+globs: ["src/**/*.js"]
+alwaysApply: false
+---
+
+# Contentstack CDA SDK (`src/core/`)
+
+This package implements the **Content Delivery API (CDA)** read client, not the Content Management API (CMA).
+
+## Stack & config
+
+- **`Contentstack.Stack(options)`** (`src/core/stack.js`) — **`api_key`**, **`delivery_token`**, **`environment`**; optional **`region`**, **`branch`**, **`host`**, **`live_preview`**, **`plugins`**, **`fetchOptions`** (timeout, retries, `retryCondition`, `logHandler`, etc.).
+- Default CDN paths and version come from **`config.js`** at the repo root; regional hosts follow existing `stack.js` logic (e.g. `{region}-cdn.contentstack.com`).
+
+## HTTP & errors
+
+- Requests are built in **`src/core/lib/request.js`**: query serialization, **`fetch`**, default retries on **408** / **429** (configurable), plugin hooks **`onRequest`** / **`onResponse`**.
+- Failed responses reject with objects carrying **`error_message`**, **`error_code`**, **`errors`**, **`status`**, **`statusText`** when JSON parsing succeeds — keep new code compatible with this shape.
+
+## Modules
+
+- **Entry, Query, Assets, Taxonomy, Result**, etc. live under **`src/core/modules/`** — follow neighboring patterns for chaining, parameters, and URL assembly.
+- **Cache**: policies and providers under **`src/core/cache.js`** and **`src/core/cache-provider/`**.
+
+## Live preview
+
+- When **`live_preview.enable`** is true, **`management_token`** vs **`preview_token`** affect host selection — mirror existing `stack.js` behavior and tests under **`test/live-preview/`**.
+
+## Runtime targets
+
+- **`src/runtime/node|web|react-native|nativescript/`** supply **`http`** and **`localstorage`** — changes that affect networking or storage must consider **all** bundled targets.
+
+## Docs
+
+- Align behavior with the official [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/) documentation.

.cursor/rules/dev-workflow.md

@@ -0,0 +1,31 @@
+---
+description: "Branches, tests, and PR expectations for contentstack-javascript (CDA SDK)"
+globs: ["**/*.js", "**/*.ts", "**/*.json"]
+alwaysApply: false
+---
+
+# Development workflow — Contentstack JavaScript CDA SDK
+
+## Branches
+
+- Follow team Git conventions (e.g. feature branches off the repo’s default integration branch).
+- Do not commit permanent `test.only`, `it.only`, `describe.only`, or skipped tests meant for CI.
+
+## Before opening a PR
+
+1. **`npm run lint`** — ESLint must pass on `src` and `test`.
+2. **`npm test`** — Runs **`pretest`** → **`npm run build`**, then **`test:e2e`** and **`test:typescript`**. For live stack tests, set env vars (see **`test/config.js`**: `HOST`, `API_KEY`, `DELIVERY_TOKEN`, `ENVIRONMENT`). Never commit secrets or `.env` with real tokens.
+3. **Version bump** — When the PR introduces **user-visible or release-worthy** SDK behavior (new API, bug fix shipped to npm, or a **breaking** change), update **`version`** in `package.json` per **semver** (patch / minor / major). Docs-only or test-only changes may omit a bump per team practice; match sibling PRs when unsure.
+
+## PR expectations (summary)
+
+- **User-facing changes** — JSDoc on public methods; update **`index.d.ts`** when the public TypeScript surface changes.
+- **Behavior** — Preserve backward compatibility unless the change is explicitly breaking and documented.
+- **Errors** — Keep rejection shapes consistent with **`src/core/lib/request.js`** (`error_message`, `error_code`, `errors`, `status`, `statusText` where applicable). Do not log full **delivery_token** or **management_token** / **preview_token** values in new code.
+- **Tests** — Add or adjust Jest tests under **`test/`** for new behavior; live tests require the env contract in **`test/config.js`**.
+
+## Quick links
+
+- Agent overview: repo root `AGENTS.md`
+- CDA patterns: `skills/contentstack-javascript-cda/SKILL.md`
+- HTTP / retries / plugins: `skills/framework/SKILL.md`

.cursor/rules/javascript.mdc

@@ -0,0 +1,30 @@
+---
+description: "JavaScript/TypeScript conventions for src, webpack, and index.d.ts"
+globs:
+  - "src/**/*.js"
+  - "webpack/**/*.js"
+  - "index.d.ts"
+alwaysApply: false
+---
+
+# JavaScript & types (this repo)
+
+## Runtime & modules
+
+- **Source** is **ES modules** under `src/` (`import` / `export`). Webpack resolves aliases such as **`runtime/http.js`** per target (`webpack/webpack.*.js`).
+- **`index.d.ts`** is the public TypeScript surface for npm consumers; keep it aligned with `src/core/` JSDoc and exports.
+
+## Style & tooling
+
+- **ESLint** uses **`eslint-config-standard`** and **`@babel/eslint-parser`**. This repo **requires semicolons** and related rules in **`.eslintrc.js`** — match existing `src/core/` style rather than semicolon-free Standard.
+- **Environment**: ESLint `es2020`, `node`, `browser`, `jest`.
+
+## Patterns
+
+- Use **JSDoc** (`@description`, `@param`, `@returns`, `@example`) on **public** API consistent with `src/core/contentstack.js` and `src/core/stack.js`.
+- **Dependencies**: **`@contentstack/utils`** is exposed on the main class; follow existing import paths (including `.js` suffixes where the codebase uses them in ESM files).
+
+## Logging
+
+- Avoid noisy logging in library code except via existing **`fetchOptions.logHandler`** / **`fetchOptions.debug`** patterns in `src/core/lib/request.js` and `stack.js`.
+- Never log full **delivery_token**, **preview_token**, **management_token**, or API keys.

.cursor/rules/testing.mdc

@@ -0,0 +1,36 @@
+---
+description: "Jest e2e and TypeScript tests for the CDA SDK"
+globs:
+  - "test/**/*.js"
+  - "test/**/*.ts"
+alwaysApply: false
+---
+
+# Testing — `contentstack` (CDA)
+
+## Frameworks
+
+| Suite | Runner | Notes |
+|-------|--------|--------|
+| **JS e2e / integration-style** | **Jest** (`jest.js.config.js`) | `testMatch`: `**/test/**/*.js`; ignores `test/index.js`, `test/config.js`, `test/sync_config.js`, some `utils.js` paths |
+| **TypeScript** | **Jest** + **ts-jest** (`jest.config.js`) | `npm run test:typescript`; `test/typescript/**/*.test.ts` |
+
+## Env & live stack
+
+- **Canonical required vars** for suites that `require('./config')` or `require('../config.js')`: **`HOST`**, **`API_KEY`**, **`DELIVERY_TOKEN`**, **`ENVIRONMENT`** — validated in **`test/config.js`** (loads **dotenv**). Missing any variable throws on import.
+- Use a **`.env`** file locally; do not commit secrets. **`HOST`** should match the delivery API host for your stack/region.
+- Built SDK: many tests **`require('../../dist/node/contentstack.js')`**. **`npm test`** runs **`pretest`** → **`npm run build`** first.
+
+## Layout
+
+- **Suite entry (JS):** `test/index.js` `require`s individual test files.
+- **TypeScript:** colocate under **`test/typescript/`** with `*.test.ts` naming.
+
+## Hygiene
+
+- No committed **`only`** / **`skip`** for tests that must run in CI.
+- Prefer deterministic assertions; mock or scope live tests when adding new cases so CI behavior stays predictable if env is absent.
+
+## Coverage
+
+- Jest / reporter config is in **`jest.js.config.js`** and **`jest.config.js`**; HTML reports paths are configured there.

.github/workflows/back-merge-pr.yml

@@ -0,0 +1,54 @@
+name: Back-merge master to development
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  open-back-merge-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Open back-merge PR if needed
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          BASE_BRANCH="development"
+          SOURCE_BRANCH="master"
+
+          git fetch origin "$BASE_BRANCH" "$SOURCE_BRANCH"
+
+          if ! git show-ref --verify --quiet "refs/remotes/origin/$BASE_BRANCH"; then
+            echo "Base branch '$BASE_BRANCH' does not exist on origin; skipping."
+            exit 0
+          fi
+
+          SOURCE_SHA=$(git rev-parse "origin/$SOURCE_BRANCH")
+          BASE_SHA=$(git rev-parse "origin/$BASE_BRANCH")
+
+          if [ "$SOURCE_SHA" = "$BASE_SHA" ]; then
+            echo "$SOURCE_BRANCH and $BASE_BRANCH are at the same commit; nothing to back-merge."
+            exit 0
+          fi
+
+          EXISTING=$(gh pr list --repo "${{ github.repository }}"             --base "$BASE_BRANCH"             --head "$SOURCE_BRANCH"             --state open             --json number             --jq 'length')
+
+          if [ "$EXISTING" -gt 0 ]; then
+            echo "An open PR from $SOURCE_BRANCH to $BASE_BRANCH already exists; skipping."
+            exit 0
+          fi
+
+          gh pr create --repo "${{ github.repository }}"             --base "$BASE_BRANCH"             --head "$SOURCE_BRANCH"             --title "chore: back-merge $SOURCE_BRANCH into $BASE_BRANCH"             --body "Automated back-merge after changes landed on \\`$SOURCE_BRANCH\\`. Review and merge to keep \\`$BASE_BRANCH\\` in sync."
+
+          echo "Created back-merge PR $SOURCE_BRANCH -> $BASE_BRANCH."

.github/workflows/check-version-bump.yml

@@ -0,0 +1,86 @@
+name: Check Version Bump
+
+on:
+  pull_request:
+
+jobs:
+  version-bump:
+    name: Version & Changelog bump
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Detect changed files and version bump
+        id: detect
+        run: |
+          if git rev-parse HEAD^2 >/dev/null 2>&1; then
+            FILES=$(git diff --name-only HEAD^1 HEAD^2)
+          else
+            FILES=$(git diff --name-only HEAD~1 HEAD)
+          fi
+          VERSION_FILES_CHANGED=false
+          echo "$FILES" | grep -qx 'package.json' && VERSION_FILES_CHANGED=true
+          echo "$FILES" | grep -qx 'CHANGELOG.md' && VERSION_FILES_CHANGED=true
+          echo "version_files_changed=$VERSION_FILES_CHANGED" >> $GITHUB_OUTPUT
+          # Only lib/, webpack/, dist/, package.json count as release-affecting; .github/ and test/ do not
+          CODE_CHANGED=false
+          echo "$FILES" | grep -qE '^lib/|^webpack/|^dist/' && CODE_CHANGED=true
+          echo "$FILES" | grep -qx 'package.json' && CODE_CHANGED=true
+          echo "code_changed=$CODE_CHANGED" >> $GITHUB_OUTPUT
+
+      - name: Skip when only test/docs/.github changed
+        if: steps.detect.outputs.code_changed != 'true'
+        run: |
+          echo "No release-affecting files changed (e.g. only test/docs/.github). Skipping version-bump check."
+          exit 0
+
+      - name: Fail when version bump was missed
+        if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed != 'true'
+        run: |
+          echo "::error::This PR has code changes but no version bump. Please bump the version in package.json and add an entry in CHANGELOG.md."
+          exit 1
+
+      - name: Setup Node
+        if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+
+      - name: Check version bump
+        if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed == 'true'
+        run: |
+          set -e
+          PKG_VERSION=$(node -p "require('./package.json').version.replace(/^v/, '')")
+          if [ -z "$PKG_VERSION" ]; then
+            echo "::error::Could not read version from package.json"
+            exit 1
+          fi
+          git fetch --tags --force 2>/dev/null || true
+          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || true)
+          if [ -z "$LATEST_TAG" ]; then
+            echo "No existing tags found. Skipping version-bump check (first release)."
+            exit 0
+          fi
+          LATEST_VERSION="${LATEST_TAG#v}"
+          LATEST_VERSION="${LATEST_VERSION%%-*}"
+          if [ "$(printf '%s\n' "$LATEST_VERSION" "$PKG_VERSION" | sort -V | tail -1)" != "$PKG_VERSION" ]; then
+            echo "::error::Version bump required: package.json version ($PKG_VERSION) is not greater than latest tag ($LATEST_TAG). Please bump the version in package.json."
+            exit 1
+          fi
+          if [ "$PKG_VERSION" = "$LATEST_VERSION" ]; then
+            echo "::error::Version bump required: package.json version ($PKG_VERSION) equals latest tag ($LATEST_TAG). Please bump the version in package.json."
+            exit 1
+          fi
+          CHANGELOG_VERSION=$(sed -nE 's/^## \[v?([0-9]+\.[0-9]+\.[0-9]+).*/\1/p' CHANGELOG.md | head -1)
+          if [ -z "$CHANGELOG_VERSION" ]; then
+            echo "::error::Could not find a version entry in CHANGELOG.md (expected line like '## [v1.0.0](...)')."
+            exit 1
+          fi
+          if [ "$CHANGELOG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::CHANGELOG version mismatch: CHANGELOG.md top version ($CHANGELOG_VERSION) does not match package.json version ($PKG_VERSION). Please add or update the CHANGELOG entry for $PKG_VERSION."
+            exit 1
+          fi
+          echo "Version bump check passed: package.json and CHANGELOG.md are at $PKG_VERSION (latest tag: $LATEST_TAG)."

.gitignore

@@ -13,4 +13,6 @@ coverage
 .env
 .dccache
 dist/*
-*.log
+*.log
+docs-internal/
+talisman_report