Skip to content

Commit 194d0f7

Browse files
Merge pull request #386 from contentstack/development
DX | 01-06-2026 | Release
2 parents 1143032 + e43c5ee commit 194d0f7

74 files changed

Lines changed: 21129 additions & 6785 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

.cursor/rules/README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Cursor (optional)
2+
3+
**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
4+
5+
This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.

.cursor/rules/code-review.mdc

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
description: "PR review themes — API docs, compatibility, errors, security, tests (CDA SDK)"
3+
alwaysApply: true
4+
---
5+
6+
# Code review checklist (CDA JavaScript SDK)
7+
8+
Apply when reviewing changes to the **`contentstack`** npm package (Content Delivery API client).
9+
10+
## Public API & documentation
11+
12+
- **JSDoc** updated for new or changed public methods/classes (params, return shape, examples), matching style in `src/core/contentstack.js` / `src/core/stack.js`.
13+
- **`index.d.ts`** updated when TypeScript consumers would see different signatures or new exports.
14+
15+
## Backward compatibility
16+
17+
- Avoid breaking changes to exported function signatures, option objects, or default behavior without a major version rationale.
18+
- If behavior changes, ensure **callers inside `src/`** and tests reflect the new contract.
19+
20+
## Errors & safety
21+
22+
- 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`**).
23+
- Do not log full **delivery_token**, **preview_token**, **management_token**, or **api_key** values.
24+
- Respect **null/undefined** edge cases for optional API fields.
25+
26+
## Dependencies & supply chain
27+
28+
- New **dependencies** should be justified (size, maintenance, license).
29+
- Lockfile and **`package.json`** version bumps should be minimal and reviewable.
30+
31+
## Tests
32+
33+
- **Jest** tests for new logic or regressions under **`test/`** (JS and/or **`test/typescript/`** as appropriate).
34+
- 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.
35+
36+
## Security & privacy
37+
38+
- No hardcoded credentials; no accidental exposure of customer content in logs or error messages.
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
description: "Contentstack CDA SDK patterns in src/core (Content Delivery API)"
3+
globs: ["src/**/*.js"]
4+
alwaysApply: false
5+
---
6+
7+
# Contentstack CDA SDK (`src/core/`)
8+
9+
This package implements the **Content Delivery API (CDA)** read client, not the Content Management API (CMA).
10+
11+
## Stack & config
12+
13+
- **`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.).
14+
- 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`).
15+
16+
## HTTP & errors
17+
18+
- Requests are built in **`src/core/lib/request.js`**: query serialization, **`fetch`**, default retries on **408** / **429** (configurable), plugin hooks **`onRequest`** / **`onResponse`**.
19+
- Failed responses reject with objects carrying **`error_message`**, **`error_code`**, **`errors`**, **`status`**, **`statusText`** when JSON parsing succeeds — keep new code compatible with this shape.
20+
21+
## Modules
22+
23+
- **Entry, Query, Assets, Taxonomy, Result**, etc. live under **`src/core/modules/`** — follow neighboring patterns for chaining, parameters, and URL assembly.
24+
- **Cache**: policies and providers under **`src/core/cache.js`** and **`src/core/cache-provider/`**.
25+
26+
## Live preview
27+
28+
- 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/`**.
29+
30+
## Runtime targets
31+
32+
- **`src/runtime/node|web|react-native|nativescript/`** supply **`http`** and **`localstorage`** — changes that affect networking or storage must consider **all** bundled targets.
33+
34+
## Docs
35+
36+
- Align behavior with the official [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/) documentation.

.cursor/rules/dev-workflow.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
description: "Branches, tests, and PR expectations for contentstack-javascript (CDA SDK)"
3+
globs: ["**/*.js", "**/*.ts", "**/*.json"]
4+
alwaysApply: false
5+
---
6+
7+
# Development workflow — Contentstack JavaScript CDA SDK
8+
9+
## Branches
10+
11+
- Follow team Git conventions (e.g. feature branches off the repo’s default integration branch).
12+
- Do not commit permanent `test.only`, `it.only`, `describe.only`, or skipped tests meant for CI.
13+
14+
## Before opening a PR
15+
16+
1. **`npm run lint`** — ESLint must pass on `src` and `test`.
17+
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.
18+
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.
19+
20+
## PR expectations (summary)
21+
22+
- **User-facing changes** — JSDoc on public methods; update **`index.d.ts`** when the public TypeScript surface changes.
23+
- **Behavior** — Preserve backward compatibility unless the change is explicitly breaking and documented.
24+
- **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.
25+
- **Tests** — Add or adjust Jest tests under **`test/`** for new behavior; live tests require the env contract in **`test/config.js`**.
26+
27+
## Quick links
28+
29+
- Agent overview: repo root `AGENTS.md`
30+
- CDA patterns: `skills/contentstack-javascript-cda/SKILL.md`
31+
- HTTP / retries / plugins: `skills/framework/SKILL.md`

.cursor/rules/javascript.mdc

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
description: "JavaScript/TypeScript conventions for src, webpack, and index.d.ts"
3+
globs:
4+
- "src/**/*.js"
5+
- "webpack/**/*.js"
6+
- "index.d.ts"
7+
alwaysApply: false
8+
---
9+
10+
# JavaScript & types (this repo)
11+
12+
## Runtime & modules
13+
14+
- **Source** is **ES modules** under `src/` (`import` / `export`). Webpack resolves aliases such as **`runtime/http.js`** per target (`webpack/webpack.*.js`).
15+
- **`index.d.ts`** is the public TypeScript surface for npm consumers; keep it aligned with `src/core/` JSDoc and exports.
16+
17+
## Style & tooling
18+
19+
- **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.
20+
- **Environment**: ESLint `es2020`, `node`, `browser`, `jest`.
21+
22+
## Patterns
23+
24+
- Use **JSDoc** (`@description`, `@param`, `@returns`, `@example`) on **public** API consistent with `src/core/contentstack.js` and `src/core/stack.js`.
25+
- **Dependencies**: **`@contentstack/utils`** is exposed on the main class; follow existing import paths (including `.js` suffixes where the codebase uses them in ESM files).
26+
27+
## Logging
28+
29+
- Avoid noisy logging in library code except via existing **`fetchOptions.logHandler`** / **`fetchOptions.debug`** patterns in `src/core/lib/request.js` and `stack.js`.
30+
- Never log full **delivery_token**, **preview_token**, **management_token**, or API keys.

.cursor/rules/testing.mdc

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
description: "Jest e2e and TypeScript tests for the CDA SDK"
3+
globs:
4+
- "test/**/*.js"
5+
- "test/**/*.ts"
6+
alwaysApply: false
7+
---
8+
9+
# Testing — `contentstack` (CDA)
10+
11+
## Frameworks
12+
13+
| Suite | Runner | Notes |
14+
|-------|--------|--------|
15+
| **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 |
16+
| **TypeScript** | **Jest** + **ts-jest** (`jest.config.js`) | `npm run test:typescript`; `test/typescript/**/*.test.ts` |
17+
18+
## Env & live stack
19+
20+
- **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.
21+
- Use a **`.env`** file locally; do not commit secrets. **`HOST`** should match the delivery API host for your stack/region.
22+
- Built SDK: many tests **`require('../../dist/node/contentstack.js')`**. **`npm test`** runs **`pretest`** → **`npm run build`** first.
23+
24+
## Layout
25+
26+
- **Suite entry (JS):** `test/index.js` `require`s individual test files.
27+
- **TypeScript:** colocate under **`test/typescript/`** with `*.test.ts` naming.
28+
29+
## Hygiene
30+
31+
- No committed **`only`** / **`skip`** for tests that must run in CI.
32+
- Prefer deterministic assertions; mock or scope live tests when adding new cases so CI behavior stays predictable if env is absent.
33+
34+
## Coverage
35+
36+
- Jest / reporter config is in **`jest.js.config.js`** and **`jest.config.js`**; HTML reports paths are configured there.
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
name: Back-merge master to development
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pull-requests: write
12+
13+
jobs:
14+
open-back-merge-pr:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: Checkout
18+
uses: actions/checkout@v4
19+
with:
20+
fetch-depth: 0
21+
22+
- name: Open back-merge PR if needed
23+
env:
24+
GH_TOKEN: ${{ github.token }}
25+
run: |
26+
set -euo pipefail
27+
BASE_BRANCH="development"
28+
SOURCE_BRANCH="master"
29+
30+
git fetch origin "$BASE_BRANCH" "$SOURCE_BRANCH"
31+
32+
if ! git show-ref --verify --quiet "refs/remotes/origin/$BASE_BRANCH"; then
33+
echo "Base branch '$BASE_BRANCH' does not exist on origin; skipping."
34+
exit 0
35+
fi
36+
37+
SOURCE_SHA=$(git rev-parse "origin/$SOURCE_BRANCH")
38+
BASE_SHA=$(git rev-parse "origin/$BASE_BRANCH")
39+
40+
if [ "$SOURCE_SHA" = "$BASE_SHA" ]; then
41+
echo "$SOURCE_BRANCH and $BASE_BRANCH are at the same commit; nothing to back-merge."
42+
exit 0
43+
fi
44+
45+
EXISTING=$(gh pr list --repo "${{ github.repository }}" --base "$BASE_BRANCH" --head "$SOURCE_BRANCH" --state open --json number --jq 'length')
46+
47+
if [ "$EXISTING" -gt 0 ]; then
48+
echo "An open PR from $SOURCE_BRANCH to $BASE_BRANCH already exists; skipping."
49+
exit 0
50+
fi
51+
52+
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."
53+
54+
echo "Created back-merge PR $SOURCE_BRANCH -> $BASE_BRANCH."

.github/workflows/check-branch.yml

Lines changed: 0 additions & 20 deletions
This file was deleted.
Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
name: Check Version Bump
2+
3+
on:
4+
pull_request:
5+
6+
jobs:
7+
version-bump:
8+
name: Version & Changelog bump
9+
runs-on: ubuntu-latest
10+
steps:
11+
- name: Checkout
12+
uses: actions/checkout@v4
13+
with:
14+
fetch-depth: 0
15+
16+
- name: Detect changed files and version bump
17+
id: detect
18+
run: |
19+
if git rev-parse HEAD^2 >/dev/null 2>&1; then
20+
FILES=$(git diff --name-only HEAD^1 HEAD^2)
21+
else
22+
FILES=$(git diff --name-only HEAD~1 HEAD)
23+
fi
24+
VERSION_FILES_CHANGED=false
25+
echo "$FILES" | grep -qx 'package.json' && VERSION_FILES_CHANGED=true
26+
echo "$FILES" | grep -qx 'CHANGELOG.md' && VERSION_FILES_CHANGED=true
27+
echo "version_files_changed=$VERSION_FILES_CHANGED" >> $GITHUB_OUTPUT
28+
# Only lib/, webpack/, dist/, package.json count as release-affecting; .github/ and test/ do not
29+
CODE_CHANGED=false
30+
echo "$FILES" | grep -qE '^lib/|^webpack/|^dist/' && CODE_CHANGED=true
31+
echo "$FILES" | grep -qx 'package.json' && CODE_CHANGED=true
32+
echo "code_changed=$CODE_CHANGED" >> $GITHUB_OUTPUT
33+
34+
- name: Skip when only test/docs/.github changed
35+
if: steps.detect.outputs.code_changed != 'true'
36+
run: |
37+
echo "No release-affecting files changed (e.g. only test/docs/.github). Skipping version-bump check."
38+
exit 0
39+
40+
- name: Fail when version bump was missed
41+
if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed != 'true'
42+
run: |
43+
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."
44+
exit 1
45+
46+
- name: Setup Node
47+
if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed == 'true'
48+
uses: actions/setup-node@v4
49+
with:
50+
node-version: '22.x'
51+
52+
- name: Check version bump
53+
if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed == 'true'
54+
run: |
55+
set -e
56+
PKG_VERSION=$(node -p "require('./package.json').version.replace(/^v/, '')")
57+
if [ -z "$PKG_VERSION" ]; then
58+
echo "::error::Could not read version from package.json"
59+
exit 1
60+
fi
61+
git fetch --tags --force 2>/dev/null || true
62+
LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || true)
63+
if [ -z "$LATEST_TAG" ]; then
64+
echo "No existing tags found. Skipping version-bump check (first release)."
65+
exit 0
66+
fi
67+
LATEST_VERSION="${LATEST_TAG#v}"
68+
LATEST_VERSION="${LATEST_VERSION%%-*}"
69+
if [ "$(printf '%s\n' "$LATEST_VERSION" "$PKG_VERSION" | sort -V | tail -1)" != "$PKG_VERSION" ]; then
70+
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."
71+
exit 1
72+
fi
73+
if [ "$PKG_VERSION" = "$LATEST_VERSION" ]; then
74+
echo "::error::Version bump required: package.json version ($PKG_VERSION) equals latest tag ($LATEST_TAG). Please bump the version in package.json."
75+
exit 1
76+
fi
77+
CHANGELOG_VERSION=$(sed -nE 's/^## \[v?([0-9]+\.[0-9]+\.[0-9]+).*/\1/p' CHANGELOG.md | head -1)
78+
if [ -z "$CHANGELOG_VERSION" ]; then
79+
echo "::error::Could not find a version entry in CHANGELOG.md (expected line like '## [v1.0.0](...)')."
80+
exit 1
81+
fi
82+
if [ "$CHANGELOG_VERSION" != "$PKG_VERSION" ]; then
83+
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."
84+
exit 1
85+
fi
86+
echo "Version bump check passed: package.json and CHANGELOG.md are at $PKG_VERSION (latest tag: $LATEST_TAG)."

.gitignore

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,6 @@ coverage
1313
.env
1414
.dccache
1515
dist/*
16-
*.log
16+
*.log
17+
docs-internal/
18+
talisman_report

0 commit comments

Comments
 (0)