contentstack · sunil-lakshman · Mar 25, 2026 · Mar 25, 2026
@@ -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)
@@ -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.
@@ -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/)
@@ -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)
@@ -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).
@@ -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.
@@ -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/).
@@ -0,0 +1,10 @@
+# Project skills — `@contentstack/delivery-sdk`
+
+| Skill | When to use |
+|-------|-------------|
+| [`code-review/`](code-review/SKILL.md) | PR review, semver, core dependency bumps |
+| [`testing/`](testing/SKILL.md) | Unit vs API vs browser vs Playwright |
+| [`contentstack-delivery-typescript/`](contentstack-delivery-typescript/SKILL.md) | **stack**, Stack class, queries, sync, cache |
+| [`framework/`](framework/SKILL.md) | **@contentstack/core** HTTP + retries on the stack |
+
+**Overview:** [`AGENTS.md`](../AGENTS.md) · **Rules:** [`.cursor/rules/README.md`](../.cursor/rules/README.md)
@@ -0,0 +1,19 @@
+---
+name: code-review
+description: PR review for @contentstack/delivery-sdk — public API, StackConfig, core alignment, tests.
+---
+
+# Code review — `@contentstack/delivery-sdk`
+
+## Checklist
+
+- [ ] **API:** New or changed **`stack()`** / **Stack** / query methods documented; exports updated in **`src/index.ts`**.
+- [ ] **Types:** **StackConfig** and public interfaces remain consistent with **`dist/modern/*.d.ts`** after build.
+- [ ] **@contentstack/core:** Version or API changes validated in **`src/stack/contentstack.ts`** (interceptors, **httpClient** options).
+- [ ] **Tests:** **`test:unit`** passes; add/extend **`test/api`** when integration behavior changes; browser/e2e if relevant.
+- [ ] **Secrets:** No tokens in repo; **stack-instance** env vars only for local CI secrets store.
+
+## References
+
+- `.cursor/rules/code-review.mdc`
+- `.cursor/rules/dev-workflow.md`
@@ -0,0 +1,35 @@
+---
+name: contentstack-delivery-typescript
+description: @contentstack/delivery-sdk — TypeScript CDA client, stack factory, queries, sync, cache, live preview.
+---
+
+# Contentstack TypeScript Delivery SDK skill
+
+## Entry
+
+- **`contentstack.stack(config)`** — **`src/stack/contentstack.ts`**: merges **StackConfig**, resolves **Region** → host, attaches **@contentstack/core** **`httpClient`** with retry handlers, returns **`Stack`**.
+
+## Structure
+
+- **`Stack`** — **`src/stack/stack.ts`**: content types, entries, assets, sync, taxonomy helpers.
+- **Queries** — **`src/query/`**: **BaseQuery**, **Query**, **AssetQuery**, **TaxonomyQuery**, **ContentTypeQuery**, **GlobalFieldQuery**, **EntryQueryable**, etc.
+- **Sync** — **`src/sync/`**
+- **Cache** — **`src/cache/`** + **Policy** enum in types.
+
+## Extending
+
+- Add query methods on the appropriate class; keep param names aligned with **CDA** query docs.
+- Prefer delegating transport concerns to **core** rather than duplicating Axios logic.
+
+## Consumer packages
+
+- **`@contentstack/core`** — HTTP + retries
+- **`@contentstack/utils`** — utilities; re-exported where documented.
+
+## Docs
+
+- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)
+
+## Rule shortcut
+
+- `.cursor/rules/contentstack-delivery-typescript.mdc`
@@ -0,0 +1,23 @@
+---
+name: framework
+description: HTTP and retry integration — @contentstack/core with httpClient on the Delivery SDK stack.
+---
+
+# Framework skill — `@contentstack/core` + Delivery SDK
+
+## Integration point
+
+- **`src/stack/contentstack.ts`** imports **`httpClient`**, **`retryRequestHandler`**, **`retryResponseErrorHandler`**, **`retryResponseHandler`** from **`@contentstack/core`** and composes them with stack-specific **headers**, **live_preview**, and **cache**-related request handling (**`handleRequest`**).
+
+## When to change
+
+- **Retry behavior** shared across Contentstack TS clients → prefer **`@contentstack/core`** (**contentstack-js-core** repo) if appropriate; otherwise document SDK-only overrides here.
+- **Base URL / region** — **`getHostforRegion`** and **StackConfig.host** in **`src/common/utils.ts`** (verify imports from current **`contentstack.ts`**).
+
+## Testing
+
+- **Unit** — mock HTTP layers; **API** — full stack via **`stackInstance()`**.
+
+## Rule shortcut
+
+- `.cursor/rules/contentstack-delivery-typescript.mdc`
@@ -0,0 +1,34 @@
+---
+name: testing
+description: Jest unit/api/browser and Playwright e2e for @contentstack/delivery-sdk.
+---
+
+# Testing — `@contentstack/delivery-sdk`
+
+## Commands
+
+| Goal | Command |
+|------|---------|
+| Unit | `npm run test:unit` |
+| API (live stack) | `npm run test:api` |
+| Browser | `npm run test:browser` |
+| All three | `npm run test:all` |
+| E2E | `npm run test:e2e` |
+| CI-style matrix | `npm run test:cicd` (includes reports + browser tests) |
+
+## Environment
+
+See **`test/utils/stack-instance.ts`**:
+
+- **Required:** `HOST`, `API_KEY`, `DELIVERY_TOKEN`, `ENVIRONMENT`
+- **Optional:** `PREVIEW_TOKEN`, `LIVE_PREVIEW_HOST`
+
+Use a **`.env`** at repo root for local API runs.
+
+## Setup
+
+- **`jest.setup.ts`** — global hooks and expected-error suppression; read before changing console behavior.
+
+## References
+
+- `.cursor/rules/testing.mdc`