Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
f0bdbde
docs: add AGENTS.md, skills, and Cursor rules entry
harshithad0703 Apr 17, 2026
45c37de
Added skills and cursor rules
sunil-lakshman Mar 24, 2026
aee227d
chore: align release workflows with new development-to-main process
harshithad0703 Apr 29, 2026
e700469
chore: migrate asset/entry tests to integration suite and remove lega…
maheshmotkar-cs May 27, 2026
baef999
issues-jira.yml
Aravind-Kumar-cstk Jun 19, 2026
932ee62
test: add 2x retry with 4s delay to performance and concurrent reques…
aniket-shikhare-cstk Jun 28, 2026
9ac4e5e
fix: raise UserAgent perf threshold and add retry to VersionUtility t…
aniket-shikhare-cstk Jun 29, 2026
b670ab4
fix: raise Perf_VersionRead_Fast threshold to 500ms for dev11 CI stab…
aniket-shikhare-cstk Jun 29, 2026
e72e9e3
chore: remove internal environment name from test comments
aniket-shikhare-cstk Jun 29, 2026
a9a4733
fix: add comments to ignore deepcode warnings for hardcoded test API …
reeshika-h Jul 22, 2026
1af7be4
Merge pull request #395 from contentstack/fix/snyk
reeshika-h Jul 22, 2026
2f15245
sca-scan.yml
Aravind-Kumar-cstk Aug 2, 2026
7009f5f
Updated codeowners
Aravind-Kumar-cstk Sep 8, 2026
873382a
Updated codeowners
Aravind-Kumar-cstk Sep 10, 2026
a56e967
Updated codeowners
Aravind-Kumar-cstk Oct 6, 2026
fcea616
Fix: use approved placeholder in retry test
reeshika-h Oct 26, 2026
455d2d1
Merge branch 'master' into fix/snyk-hardcoded-secrets-tests
reeshika-h Nov 2, 2026
f30025e
Merge pull request #397 from contentstack/fix/snyk-hardcoded-secrets-…
reeshika-h Nov 2, 2026
466e00f
Merge branch 'master' into feature/comprehensive-integration-tests
aniket-shikhare-cstk Nov 16, 2026
45a5af5
test: replace WAF-triggering payloads with URL-encoding edge cases
aniket-shikhare-cstk Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 47 additions & 3 deletions .cursor/rules/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,49 @@
# Cursor (optional)
# Cursor Rules Documentation

**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
This directory contains **Cursor AI rules** for the **Contentstack JavaScript Content Delivery SDK** (`contentstack` on npm) — CDA client development in this repository.

This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.
## Rules overview

| Rule | Role |
|------|------|
| [`dev-workflow.md`](dev-workflow.md) | Branches, lint/tests before PR, build + version bump guidance, links to skills |
| [`javascript.mdc`](javascript.mdc) | JavaScript / TypeScript declaration style: `src/`, `webpack/`, root `index.d.ts` |
| [`contentstack-javascript-cda.mdc`](contentstack-javascript-cda.mdc) | CDA SDK patterns: `Stack`, delivery token, host/region, request/cache/live preview |
| [`testing.mdc`](testing.mdc) | Jest e2e (`test/**/*.js`) and TypeScript tests; `test/config.js` env |
| [`code-review.mdc`](code-review.mdc) | PR checklist: JSDoc, `index.d.ts`, compat, errors, tests, CDA semantics (**always applied**) |

## Rule application

Rules load from **globs** and **`alwaysApply`** in each file's frontmatter.

| Context | Typical rules |
|---------|----------------|
| **Every chat / session** | [`code-review.mdc`](code-review.mdc) (`alwaysApply: true`) |
| **Most project files** | [`dev-workflow.md`](dev-workflow.md) — `**/*.js`, `**/*.ts`, `**/*.json` |
| **SDK implementation** | [`javascript.mdc`](javascript.mdc) + [`contentstack-javascript-cda.mdc`](contentstack-javascript-cda.mdc) for `src/**/*.js` |
| **Build config** | [`javascript.mdc`](javascript.mdc) for `webpack/**/*.js` |
| **Public types** | [`javascript.mdc`](javascript.mdc) for `index.d.ts` |
| **Tests** | [`testing.mdc`](testing.mdc) for `test/**/*.js`, `test/**/*.ts` |

Overlaps are expected (e.g. editing `src/core/stack.js` can match `dev-workflow`, `javascript`, and `contentstack-javascript-cda`).

## Usage

- Rules load automatically when opened files match their globs (`code-review` is always in context).
- You can **@ mention** rule files in chat when supported.

## Quick reference table

| File | `alwaysApply` | Globs (summary) |
|------|---------------|-----------------|
| `dev-workflow.md` | no | `**/*.js`, `**/*.ts`, `**/*.json` |
| `javascript.mdc` | no | `src/**/*.js`, `webpack/**/*.js`, `index.d.ts` |
| `contentstack-javascript-cda.mdc` | no | `src/**/*.js` |
| `testing.mdc` | no | `test/**/*.js`, `test/**/*.ts` |
| `code-review.mdc` | **yes** | — |

## Skills & maintenance

- Deeper playbooks: [`skills/README.md`](../../skills/README.md).
- Repo agent entry: [`AGENTS.md`](../../AGENTS.md).
- When directories change, update **globs** in rule frontmatter; keep rules short and put detail in `skills/*/SKILL.md`.
3 changes: 3 additions & 0 deletions .github/workflows/sca-scan.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ on:
jobs:
security-sca:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@master
- name: Run Snyk to check for vulnerabilities
Expand Down
4 changes: 2 additions & 2 deletions .talismanrc
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ fileignoreconfig:
- filename: test/integration/GlobalFieldsTests/NestedGlobalField.test.js
checksum: 1ba81e7a400fd02c5d66170bdd5b2419a8932963dd00c5635d754c89ab5daeba
- filename: test/integration/NetworkResilienceTests/RetryLogic.test.js
checksum: 3b5fe23398bdc2327848b3caa95339e51a0aed059c1eb299e78d3dd215ecbd30
checksum: 83e60d29f762c4b018f79019766d6edb9653b314085f53891d531f425a50480d
- filename: test/integration/QueryTests/ExistsSearchOperators.test.js
checksum: 9b1cec59275ba72fe4b753e956c5b24b237d24d12819434ab65109075cf50f86
- filename: index.d.ts
Expand All @@ -24,7 +24,7 @@ fileignoreconfig:
- filename: .github/workflows/secrets-scan.yml
checksum: d79ec3f3288964f7d117b9ad319a54c0ebc152e35f69be8fde95522034fdfb2a
- filename: package-lock.json
checksum: 3d18d543ed9c7b87bcfca8f7af99bb3058ffa67b84a1ff888623686a84d06672
checksum: 808b543b347ac557957bc1de1a5a94e40f6be9856f24cb049e761f2ec81a77eb
- filename: src/core/modules/assets.js
checksum: 00f19d659b830b0f145b4db0ccf3211a4048d9488f30a224fe3c31cacca6dcd2
- filename: .husky/pre-commit
Expand Down
92 changes: 55 additions & 37 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,43 +1,61 @@
# Contentstack JavaScript Delivery SDK – Agent guide
# AGENTS.md — AI / automation context

**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
## Project

## What this repo is
| | |
|---|---|
| **Name** | **`contentstack`** (npm) — **Contentstack JavaScript Content Delivery SDK** |
| **Purpose** | Client for the **Content Delivery API (CDA)**: read published content, assets, taxonomies, sync, and live preview from a stack. *(This is not the Content Management API / CMA client — see `@contentstack/management`.)* |
| **Repository** | [contentstack/contentstack-javascript](https://github.com/contentstack/contentstack-javascript.git) |

| Field | Detail |
|--------|--------|
| **Name:** | [contentstack-javascript](https://github.com/contentstack/contentstack-javascript) (npm package **`contentstack`**) |
| **Purpose:** | Legacy **JavaScript** Content Delivery SDK for browsers, Node.js, React Native, and NativeScript—stack initialization, queries, entries, assets. |
| **Out of scope:** | Not the TypeScript-first **`@contentstack/delivery-sdk`** (`contentstack-typescript`); new TypeScript projects should prefer that package when appropriate. |

## Tech stack (at a glance)
## Tech stack

| Area | Details |
|------|---------|
| Language | JavaScript in **`src/`**; TypeScript tests via Jest (`test/typescript`) |
| Build | Webpack configs under **`webpack/`**; outputs under **`dist/`** per target (`npm run build`) |
| Tests | Jest: **`test:e2e`** (`jest.js.config.js`) and **`test:typescript`** (`jest.config.js`); **`pretest`** runs **`build`** first |
| Lint / coverage | ESLint on `src` and `test` (`npm run lint`) |
| CI | `.github/workflows/check-branch.yml`, `npm-publish.yml`, `sca-scan.yml`, `policy-scan.yml`, `codeql-analysis.yml`, `link-check.yml`, `issues-jira.yml` |

## Commands (quick reference)

| Command type | Command |
|--------------|---------|
| Build | `npm run build` |
| Test | `npm test` (build via `pretest`, then e2e + TypeScript Jest suites) |
| Lint | `npm run lint` |

## Where the documentation lives: skills

| Skill | Path | What it covers |
|-------|------|----------------|
| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, npm scripts, Husky, CI |
| **JavaScript SDK** | [`skills/contentstack-javascript-sdk/SKILL.md`](skills/contentstack-javascript-sdk/SKILL.md) | Public API (`Stack`, regions), `@contentstack/utils` |
| **JavaScript tooling** | [`skills/javascript/SKILL.md`](skills/javascript/SKILL.md) | Webpack targets, `dist/` layout, Babel |
| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | Jest configs, e2e vs TypeScript tests |
| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist |

## Using Cursor (optional)

If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.
| **Language** | JavaScript **ES modules** in `src/core/` and `src/runtime/`; public types in root **`index.d.ts`** |
| **Runtime** | Node `>= 10.14.2` per `package.json` `engines` |
| **Build** | **Webpack** bundles for `node`, `web`, `react-native`, `nativescript` → `dist/` (`npm run build`) |
| **Lint / style** | **ESLint** with `eslint-config-standard`, **`@babel/eslint-parser`**; **semicolons required** (see `.eslintrc.js`) |
| **Tests** | **Jest**: JS e2e-style suite (`jest.js.config.js`, `test/**/*.js`) and **TypeScript** tests (`jest.config.js`, `test/typescript/**/*.test.ts`) |
| **HTTP** | Platform **`fetch`** via webpack alias `runtime/http.js` and `runtime/localstorage.js` (Node / web / React Native / NativeScript) |
| **Helpers** | **`@contentstack/utils`** re-exported on the `Contentstack` instance |

## Source layout & public entrypoints

| Path | Role |
|------|------|
| `src/core/contentstack.js` | Package facade: `Stack()`, `CachePolicy`, `Region`, `Utils` |
| `src/core/stack.js` | `Stack` class: delivery config, queries, sync, plugins, `fetchOptions` |
| `src/core/lib/request.js` | CDA requests: query serialization, retries, plugins `onRequest` / `onResponse` |
| `src/core/lib/utils.js` | Shared helpers |
| `src/core/modules/*` | Entry, Query, Assets, Taxonomy, Result, etc. |
| `src/core/cache*.js`, `src/core/cache-provider/` | Cache policies and providers |
| `src/runtime/**` | Per-platform `http` and `localstorage` implementations |
| `config.js` | Default CDN host, API version, URL paths (imported by `stack.js`) |
| `webpack/` | Build configs per target |
| `dist/**` | Built artifacts (`package.json` `main` / `browser` / `react-native`) |

## Common commands

```bash
npm install
npm run build # all webpack targets (also runs on prepare / pretest)
npm run lint # eslint src test
npm run format # eslint src test --fix
npm run test # test:e2e + test:typescript (pretest runs build)
npm run test:e2e # Jest JS tests under test/ (see jest.js.config.js)
npm run test:typescript # Jest + ts-jest for test/typescript
npm run generate-docs # JSDoc (docs-config.json)
```

**Live API tests**

- **`test/config.js`** loads **`.env`** and **requires** `HOST`, `API_KEY`, `DELIVERY_TOKEN`, `ENVIRONMENT`. Without them, importing `test/config.js` throws.
- Jest e2e tests use **`dist/node/contentstack.js`** (built output). Run **`npm run build`** (or `npm test`, which runs `pretest`) before relying on fresh `src/` changes.

## Further guidance

- **Cursor rules:** [`.cursor/rules/README.md`](.cursor/rules/README.md)
- **Deeper playbooks:** [`skills/README.md`](skills/README.md)

When unsure about API behavior, prefer the official [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/) documentation and existing JSDoc in `src/core/`.
14 changes: 4 additions & 10 deletions CODEOWNERS
Original file line number Diff line number Diff line change
@@ -1,11 +1,5 @@
* @contentstack/devex-pr-reviewers

.github/workflows/sca-scan.yml @contentstack/security-admin

.github/workflows/codeql-anaylsis.yml @contentstack/security-admin

* @contentstack/developer-ecosystem-pr-reviewers
.github/workflows/ @contentstack/security-admin
**/.snyk @contentstack/security-admin

.github/workflows/policy-scan.yml @contentstack/security-admin

.github/workflows/issues-jira.yml @contentstack/security-admin
**/CODEOWNERS @contentstack/security-admin
**/.gitguardian.yaml @contentstack/security-admin
63 changes: 49 additions & 14 deletions skills/code-review/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,62 @@
---
name: code-review
description: Use when reviewing PRs for contentstack-javascript—API compatibility, bundles, Jest, and npm/CDN impact.
description: Use when reviewing PRs or before opening a PR — API design, errors, backward compatibility, dependencies, security, and test quality for the CDA SDK.
---

# Code review – contentstack-javascript
# Code review — Contentstack JavaScript CDA SDK

Use this skill for pull request review or self-review of the **`contentstack`** package (**Content Delivery API** client — not `@contentstack/management` / CMA).

## When to use

- Reviewing SDK or Webpack changes
- Assessing dependency bumps (`@contentstack/utils`, Babel, Webpack, Jest)
- Reviewing someone else's PR.
- Self-reviewing before submission.
- Checking API, error, compatibility, tests, and security expectations.

## Instructions

### Checklist
Work through the checklist. Optionally tag severity: **Blocker**, **Major**, **Minor**.

### 1. API design and stability

- [ ] **Public API:** New or changed exports are documented with **JSDoc**, consistent with `src/core/contentstack.js` and `src/core/stack.js`.
- [ ] **TypeScript surface:** **`index.d.ts`** updated when consumers would see new or changed signatures.
- [ ] **Backward compatibility:** No breaking changes to public signatures, option objects, or defaults without an agreed major bump.
- [ ] **Naming:** Consistent with **CDA** concepts (stack, entry, query, asset, taxonomy, sync, environment).

**Severity:** Breaking public API without approval = **Blocker**. Missing JSDoc or types on new public API = **Major**.

### 2. Error handling and robustness

- [ ] **Errors:** Rejections align with **`src/core/lib/request.js`** patterns (`error_message`, `error_code`, `errors`, `status`, `statusText` when JSON is available).
- [ ] **Null safety:** Guard optional nested fields from API responses.
- [ ] **Secrets:** No logging of full **delivery_token**, **preview_token**, **management_token**, or **api_key**.

**Severity:** Missing or inconsistent error handling on new paths = **Major**.

### 3. Dependencies and security

- [ ] **Dependencies:** New or upgraded packages are justified; lockfile changes are intentional.
- [ ] **SCA:** Address or explicitly track security findings from org tooling (Snyk, Dependabot, etc.).

**Severity:** Unaddressed critical/high issues in scope = **Blocker**.

### 4. Testing

- [ ] **Jest:** New or changed behavior has coverage under **`test/`** (JS and/or **`test/typescript/`**).
- [ ] **Live tests:** If tests hit the network, they respect **`test/config.js`** (`HOST`, `API_KEY`, `DELIVERY_TOKEN`, `ENVIRONMENT`); no committed secrets.
- [ ] **Build:** Fresh `src/` changes are validated against **`dist/node/contentstack.js`** after **`npm run build`** when tests import dist.

**Severity:** No tests for new behavior = **Blocker** (unless truly docs-only). Flaky tests = **Major**.

### 5. Optional severity summary

- **Semver**: Breaking changes for npm and **jsDelivr** consumers called out with major bump and release notes.
- **Bundles**: Each target still builds; `package.json` entry points remain valid.
- **Tests**: `npm test` and `npm run lint` succeed for the change set.
- **Docs**: README or JSDoc updated for user-visible behavior.
- **Security**: No API keys in tests or docs.
- **Blocker:** Must fix before merge.
- **Major:** Should fix before or soon after merge.
- **Minor:** Nice to fix.

### Severity hints
## References

- **Blocker**: Broken `dist/` layout, failing CI, or regression in core `Stack` flow.
- **Major**: Missing tests for new API surface or cross-environment behavior.
- **Minor**: Internal refactors with full green tests.
- `.cursor/rules/code-review.mdc`
- `.cursor/rules/dev-workflow.md`
- `skills/testing/SKILL.md`
49 changes: 36 additions & 13 deletions skills/testing/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,26 +1,49 @@
---
name: testing
description: Use for Jest e2e and TypeScript test suites, jest configs, and test layout in contentstack-javascript.
description: How to run and extend tests — Jest e2e (test/*.js), TypeScript tests, test/config.js env, dist build.
---

# Testing – contentstack-javascript
# Testing skill — `contentstack` (CDA)

## When to use
## Commands (from `package.json`)

- Adding tests under **`test/`** or adjusting **`jest.js.config.js`** / **`jest.config.js`**
- Debugging failures that only appear after **`pretest` / build**
| Goal | Command |
|------|---------|
| Lint | `npm run lint` |
| Full test (includes build) | `npm test` — runs **`pretest`** → **`npm run build`**, then **`test:e2e`** + **`test:typescript`** |
| JS Jest suite only | `npm run test:e2e` — config: **`jest.js.config.js`** |
| TypeScript / Jest | `npm run test:typescript` — config: **`jest.config.js`** |
| Build | `npm run build` — required before trusting **`dist/`** against updated `src/` |

## Instructions
## JS tests (`test/**/*.js`)

### Suites
- Wired from **`test/index.js`** via `require(...)`.
- **`jest.js.config.js`** sets `testEnvironment: node`, HTML reporters, and **ignore patterns** for `test/index.js`, `test/config.js`, `test/sync_config.js`, and certain `utils.js` paths — check the config when adding files.

- **`npm run test:e2e`** — Jest with **`jest.js.config.js`**.
- **`npm run test:typescript`** — Jest with **`jest.config.js`**, limited to **`test/typescript`** paths.
## Environment variables (live stack)

### Order
**Authoritative validation:** **`test/config.js`** (uses **dotenv**).

- Full **`npm test`** runs e2e then TypeScript tests; both assume a fresh **`build`** (via **`pretest`**).
**Required** when importing `test/config.js` (used by tests that need stack credentials):

### Hygiene
- **`HOST`** — delivery API host for your region/stack
- **`API_KEY`**
- **`DELIVERY_TOKEN`**
- **`ENVIRONMENT`**

- Do not commit stack secrets; use fixtures or env patterns documented for this repo.
If any are missing, the process throws on import. Use a local **`.env`**; never commit real tokens.

## TypeScript tests (`test/typescript/`)

- **`jest.config.js`**: **ts-jest**, transforms for TS/JS; HTML report under **`typescript-html-report/`** per config.
- Use for type-level and behavioral checks against the public SDK shape; keep assertions aligned with **`index.d.ts`**.

## Hygiene

- No committed **`only`** / **`skip`** for CI-mandatory tests.
- Prefer stable ordering and avoid time-dependent assertions unless unavoidable.

## References

- `.cursor/rules/testing.mdc`
- `test/README.md`
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,12 @@ const config = TestDataHelper.getConfig();
let Stack;

describe('Concurrent Requests - Comprehensive Tests', () => {
// Retry up to 2 times with a ~4s pause between attempts to tolerate server load spikes in shared CI environments
jest.retryTimes(2, { logErrorsBeforeRetry: true });
afterEach(async () => {
await new Promise(resolve => setTimeout(resolve, 4000));
});

beforeAll(() => {
Stack = Contentstack.Stack(config.stack);
Stack.setHost(config.host);
Expand Down
4 changes: 2 additions & 2 deletions test/integration/NetworkResilienceTests/RetryLogic.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -270,7 +270,7 @@ describe('Retry Logic & Network Resilience - Comprehensive Tests', () => {
describe('Error Scenarios', () => {
test('Error_InvalidAPIKey_FailsWithoutRetry', async () => {
const localStack = Contentstack.Stack({
api_key: 'invalid_api_key_12345',
api_key: 'INVALID_API_KEY',
delivery_token: config.stack.delivery_token,
environment: config.stack.environment,
fetchOptions: {
Expand Down Expand Up @@ -436,7 +436,7 @@ describe('Retry Logic & Network Resilience - Comprehensive Tests', () => {
const RETRY_LIMIT = 5;

const localStack = Contentstack.Stack({
api_key: 'invalid_api_key_for_timing_test',
api_key: 'INVALID_API_KEY',
delivery_token: config.stack.delivery_token,
environment: config.stack.environment,
fetchOptions: {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,12 @@ const config = TestDataHelper.getConfig();
let Stack;

describe('Performance Benchmarking - Comprehensive Tests (Phase 4)', () => {
// Retry up to 2 times with a ~4s pause between attempts to tolerate server load spikes in shared CI environments
jest.retryTimes(2, { logErrorsBeforeRetry: true });
afterEach(async () => {
await new Promise(resolve => setTimeout(resolve, 4000));
});

beforeAll(() => {
Stack = Contentstack.Stack(config.stack);
Stack.setHost(config.host);
Expand Down
6 changes: 6 additions & 0 deletions test/integration/PerformanceTests/StressTesting.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,12 @@ const config = TestDataHelper.getConfig();
let Stack;

describe('Stress Testing - High Load Scenarios (Phase 4)', () => {
// Retry up to 2 times with a ~4s pause between attempts to tolerate server load spikes in shared CI environments
jest.retryTimes(2, { logErrorsBeforeRetry: true });
afterEach(async () => {
await new Promise(resolve => setTimeout(resolve, 4000));
});

beforeAll(() => {
Stack = Contentstack.Stack(config.stack);
Stack.setHost(config.host);
Expand Down
Loading
Loading
⌂ Proxy