DX | 13-04-2026 | Release

.cursor/rules/README.md

@@ -0,0 +1,37 @@
+# Cursor Rules — `@contentstack/delivery-sdk`
+
+Rules for **contentstack-typescript**: TypeScript **CDA** SDK built on **`@contentstack/core`**.
+
+## Rules overview
+
+| Rule | Role |
+|------|------|
+| [`dev-workflow.md`](dev-workflow.md) | Branch/PR, build, tests (`unit` / `api` / `browser`), e2e |
+| [`typescript.mdc`](typescript.mdc) | TS conventions, `src/`, `config/` |
+| [`contentstack-delivery-typescript.mdc`](contentstack-delivery-typescript.mdc) | **stack**, queries, cache, live preview, **core** integration |
+| [`testing.mdc`](testing.mdc) | Jest suites, **jest.setup.ts**, env, Playwright |
+| [`code-review.mdc`](code-review.mdc) | PR checklist (**always applied**) |
+
+## Rule application
+
+| Context | Typical rules |
+|---------|----------------|
+| **Every session** | `code-review.mdc` |
+| **Most files** | `dev-workflow.md` |
+| **`src/`** | `typescript.mdc` + `contentstack-delivery-typescript.mdc` |
+| **`test/**`** | `testing.mdc` |
+| **Rollup / TS config** | `typescript.mdc` |
+
+## Quick reference
+
+| File | `alwaysApply` | Globs (summary) |
+|------|---------------|-----------------|
+| `dev-workflow.md` | no | `**/*.ts`, `**/*.mjs`, `**/*.json` |
+| `typescript.mdc` | no | `src/**/*.ts`, `config/**/*.ts`, `jest.config.ts`, `jest.config.browser.ts`, `jest.setup.ts` |
+| `contentstack-delivery-typescript.mdc` | no | `src/**/*.ts` |
+| `testing.mdc` | no | `test/**/*.ts`, `playwright.config.ts` |
+| `code-review.mdc` | **yes** | — |
+
+## Skills
+
+- [`skills/README.md`](../../skills/README.md) · [`AGENTS.md`](../../AGENTS.md)

.cursor/rules/code-review.mdc

@@ -0,0 +1,27 @@
+---
+description: "PR checklist for @contentstack/delivery-sdk — API, types, core bump, tests"
+alwaysApply: true
+---
+
+# Code review — `@contentstack/delivery-sdk`
+
+## Public API
+
+- **Exported** `stack`, **Stack**, query/entry/asset types match **README** and **`.d.ts`** output in **`dist/modern/`**.
+- **JSDoc** on **`stack()`** and key public methods when behavior or options change.
+
+## Compatibility
+
+- Avoid breaking **StackConfig** or method chains without semver strategy; document migration for breaking changes.
+
+## Core / deps
+
+- **`@contentstack/core`** version changes: verify interceptors, errors, and **httpClient** options in **`contentstack.ts`**.
+
+## Tests
+
+- **Unit** coverage for new logic; **API** updates when CDA request/response behavior changes; **browser** if bundling or globals affected.
+
+## Security
+
+- No hardcoded tokens; no logging secrets in new code.

.cursor/rules/contentstack-delivery-typescript.mdc

@@ -0,0 +1,33 @@
+---
+description: "CDA Delivery SDK — stack, queries, cache, live preview, @contentstack/core"
+globs: ["src/**/*.ts"]
+alwaysApply: false
+---
+
+# Contentstack TypeScript Delivery SDK (`src/`)
+
+## Stack entry
+
+- **`stack(config: StackConfig)`** in **`src/stack/contentstack.ts`** resolves **region → host** (`getHostforRegion`), merges **live_preview**, builds the Axios stack via **`httpClient`** + **`retryRequestHandler`** / **`retryResponseHandler`** / **`retryResponseErrorHandler`**, and returns **`Stack`**.
+
+## Features
+
+- **Queries** — **`src/query/*`**: base query, entry/asset/taxonomy/content-type/global-field queryables; chain methods match CDA query parameters.
+- **Cache** — **`src/cache`** + **`Policy`** on **StackConfig**; persistence plugins may be documented as optional packages in JSDoc.
+- **Sync** — **`src/sync/synchronization.ts`** for sync token workflows.
+
+## Live preview
+
+- **StackConfig.live_preview** — **enable**, **preview_token**, **host**, etc.; keep behavior aligned with tests under **`test/api/live-preview*.spec.ts`**.
+
+## Plugins
+
+- **ContentstackPlugin** interceptors should follow existing **preRequest**/**onData** patterns in **Stack** if extending.
+
+## Core alignment
+
+- HTTP defaults (**timeout**, retries, headers) must stay consistent with **`@contentstack/core`** capabilities; avoid duplicating retry logic that belongs in **core**.
+
+## Docs
+
+- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)

.cursor/rules/dev-workflow.md

@@ -0,0 +1,26 @@
+---
+description: "Branches, build, and test matrix for contentstack-typescript"
+globs: ["**/*.ts", "**/*.mjs", "**/*.json"]
+alwaysApply: false
+---
+
+# Development workflow — `@contentstack/delivery-sdk`
+
+## Before a PR
+
+1. **`npm run build`** — Rollup + type declarations succeed.
+2. **`npm run test:unit`** — required baseline.
+3. **API tests** — `npm run test:api` when your change affects live CDA behavior; configure **`.env`** per **`test/utils/stack-instance.ts`**. Never commit tokens.
+4. **Browser / e2e** — run when changing bundling, globals, or browser-specific code (`npm run test:browser`, `npm run test:e2e` as needed).
+
+## Dependency on core
+
+- Bumps to **`@contentstack/core`** may require alignment of **httpClient** options, interceptors, or error types. Verify **`stack/contentstack.ts`** and retry/plugin code after core upgrades.
+
+## Versioning
+
+- Update **`package.json` `version`** per semver for user-visible SDK changes.
+
+## Links
+
+- [`AGENTS.md`](../../AGENTS.md) · [`skills/contentstack-delivery-typescript/SKILL.md`](../../skills/contentstack-delivery-typescript/SKILL.md)

.cursor/rules/testing.mdc

@@ -0,0 +1,37 @@
+---
+description: "Jest unit/api/browser tests and Playwright e2e for delivery-sdk"
+globs:
+  - "test/**/*.ts"
+  - "playwright.config.ts"
+alwaysApply: false
+---
+
+# Testing — `@contentstack/delivery-sdk`
+
+## Jest
+
+| Suite | Path | Notes |
+|-------|------|--------|
+| **Unit** | `test/unit/**/*.spec.ts` | Mocked / fast; `npm run test:unit` |
+| **API** | `test/api/**/*.spec.ts` | Real stack — **`.env`** via **`test/utils/stack-instance.ts`** |
+| **Browser** | `test/browser/**/*.spec.ts` | `jest.config.browser.ts` |
+
+- **`jest.setup.ts`** — console capture, suppression of **expected** validation error noise; do not weaken checks for real failures.
+
+## Env (`test/api` and helpers)
+
+Required for **`stackInstance()`**:
+
+- **`HOST`**, **`API_KEY`**, **`DELIVERY_TOKEN`**, **`ENVIRONMENT`**
+
+Optional:
+
+- **`PREVIEW_TOKEN`**, **`LIVE_PREVIEW_HOST`**
+
+## E2E
+
+- **`npm run test:e2e`** — builds browser bundle then **Playwright** (`test/e2e`, `playwright.config.ts`).
+
+## Hygiene
+
+- No permanent **`test.only`** in CI paths; long-running API suites may use **`testTimeout`** in Jest config (`maxWorkers: 1` is intentional).

.cursor/rules/typescript.mdc

@@ -0,0 +1,34 @@
+---
+description: "TypeScript conventions for the Delivery SDK src and tooling"
+globs:
+  - "src/**/*.ts"
+  - "config/**/*.ts"
+  - "jest.config.ts"
+  - "jest.config.browser.ts"
+  - "jest.setup.ts"
+  - "jest.setup.browser.ts"
+  - "rollup.config.js"
+alwaysApply: false
+---
+
+# TypeScript — `@contentstack/delivery-sdk`
+
+## Layout
+
+- **`src/stack/`** — **`stack()`** factory and **Stack** implementation.
+- **`src/query/`**, **`src/entries/`**, **`src/assets/`**, **`src/sync/`**, **`src/cache/`** — feature modules.
+- **`src/common/types.ts`** — **`StackConfig`**, **Region**, plugins, cache policies, etc.
+
+## Style
+
+- Follow **`.eslintrc.json`** and existing naming (including eslint disables only where already established, e.g. **stack** factory export).
+
+## Imports
+
+- **`@contentstack/core`** — **`httpClient`**, retry handlers.
+- **`@contentstack/utils`** — re-exported from **`contentstack.ts`** where applicable.
+- **`axios`** types for headers where needed.
+
+## Security
+
+- Do not log **delivery tokens**, **preview tokens**, or **api keys**; use existing error and debug patterns.

AGENTS.md

@@ -0,0 +1,59 @@
+# AGENTS.md — AI / automation context
+
+## Project
+
+| | |
+|---|---|
+| **Name** | **`@contentstack/delivery-sdk`** (npm) — **Contentstack TypeScript Content Delivery SDK** |
+| **Purpose** | TypeScript client for the **Content Delivery API (CDA)**: stacks, entries, assets, queries, sync, live preview, cache. Built on **`@contentstack/core`** (**Axios** HTTP + retry helpers) and **`@contentstack/utils`**. |
+| **Repository** | [contentstack/contentstack-typescript](https://github.com/contentstack/contentstack-typescript.git) |
+
+## Tech stack
+
+| Area | Details |
+|------|---------|
+| **Language** | **TypeScript**, **ES modules** (`"type": "module"`) |
+| **Runtime** | Node **>= 18** (`package.json` `engines`) |
+| **Build** | **Rollup** (`npm run build:rollup`) + **`tsc`** declarations (`config/tsconfig.decl-esm.json`) → **`dist/modern/`** |
+| **Tests** | **Jest** + **ts-jest**: **`test/unit`**, **`test/api`**, **`test/browser`**; **Playwright** e2e (`test/e2e`, `npm run test:e2e`) |
+| **Lint** | **ESLint** (`.eslintrc.json`) |
+
+## Source layout
+
+| Path | Role |
+|------|------|
+| `src/stack/contentstack.ts` | **`stack(config)`** factory — wires **`httpClient`** from **`@contentstack/core`**, region/host, live preview |
+| `src/stack/stack.ts` | **Stack** class |
+| `src/query/**` | Queries (entry, asset, taxonomy, content type, …) |
+| `src/entries/**`, `src/assets/**`, `src/sync/**`, `src/cache/**` | Domain modules |
+| `src/common/**` | Types, utils, errors, pagination |
+| `src/index.ts` | Public package exports |
+| `test/utils/stack-instance.ts` | **`stackInstance()`** — loads **dotenv**, **`HOST`**, **`API_KEY`**, **`DELIVERY_TOKEN`**, **`ENVIRONMENT`**, optional live-preview vars |
+
+## Common commands
+
+```bash
+npm install
+npm run build
+npm run test:unit      # jest ./test/unit
+npm run test:api       # live API — needs .env (see stack-instance)
+npm run test:browser
+npm run test:e2e       # Playwright (builds browser bundle first)
+npm run test:all       # unit + browser + api
+```
+
+## Environment variables (API / integration tests)
+
+Loaded via **`dotenv`** in **`test/utils/stack-instance.ts`**:
+
+- **`HOST`**, **`API_KEY`**, **`DELIVERY_TOKEN`**, **`ENVIRONMENT`** — stack connection
+- Optional: **`PREVIEW_TOKEN`**, **`LIVE_PREVIEW_HOST`** for live preview tests
+
+Do not commit secrets.
+
+## Further guidance
+
+- **Cursor rules:** [`.cursor/rules/README.md`](.cursor/rules/README.md)
+- **Skills:** [`skills/README.md`](skills/README.md)
+
+Product docs: [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/).

CHANGELOG.md

@@ -1,3 +1,7 @@
+### Version: 5.2.0
+#### Date: Apr-09-2026
+Enhancement: `ContentTypeQuery` extends `BaseQuery` so `stack.contentType()` supports `paginate`, `skip`, `limit`, and related query helpers without mutating `_queryParams`; `includeGlobalFieldSchema()` and `find()` stay backward compatible. Expanded unit tests for `ContentTypeQuery`.
+
 ### Version: 5.1.2
 #### Date: Mar-16-2026
 Fix: Added security issues