Skip to content

Commit a1b7443

Browse files
sunil-lakshmansunil-lakshman
committed
Added cursor rules & skills
1 parent 41f98cb commit a1b7443

12 files changed

Lines changed: 374 additions & 0 deletions

File tree

‎.cursor/rules/README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Cursor Rules — `@contentstack/delivery-sdk`
2+
3+
Rules for **contentstack-typescript**: TypeScript **CDA** SDK built on **`@contentstack/core`**.
4+
5+
## Rules overview
6+
7+
| Rule | Role |
8+
|------|------|
9+
| [`dev-workflow.md`](dev-workflow.md) | Branch/PR, build, tests (`unit` / `api` / `browser`), e2e |
10+
| [`typescript.mdc`](typescript.mdc) | TS conventions, `src/`, `config/` |
11+
| [`contentstack-delivery-typescript.mdc`](contentstack-delivery-typescript.mdc) | **stack**, queries, cache, live preview, **core** integration |
12+
| [`testing.mdc`](testing.mdc) | Jest suites, **jest.setup.ts**, env, Playwright |
13+
| [`code-review.mdc`](code-review.mdc) | PR checklist (**always applied**) |
14+
15+
## Rule application
16+
17+
| Context | Typical rules |
18+
|---------|----------------|
19+
| **Every session** | `code-review.mdc` |
20+
| **Most files** | `dev-workflow.md` |
21+
| **`src/`** | `typescript.mdc` + `contentstack-delivery-typescript.mdc` |
22+
| **`test/**`** | `testing.mdc` |
23+
| **Rollup / TS config** | `typescript.mdc` |
24+
25+
## Quick reference
26+
27+
| File | `alwaysApply` | Globs (summary) |
28+
|------|---------------|-----------------|
29+
| `dev-workflow.md` | no | `**/*.ts`, `**/*.mjs`, `**/*.json` |
30+
| `typescript.mdc` | no | `src/**/*.ts`, `config/**/*.ts`, `jest.config.ts`, `jest.config.browser.ts`, `jest.setup.ts` |
31+
| `contentstack-delivery-typescript.mdc` | no | `src/**/*.ts` |
32+
| `testing.mdc` | no | `test/**/*.ts`, `playwright.config.ts` |
33+
| `code-review.mdc` | **yes** | — |
34+
35+
## Skills
36+
37+
- [`skills/README.md`](../../skills/README.md) · [`AGENTS.md`](../../AGENTS.md)

‎.cursor/rules/code-review.mdc‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
description: "PR checklist for @contentstack/delivery-sdk — API, types, core bump, tests"
3+
alwaysApply: true
4+
---
5+
6+
# Code review — `@contentstack/delivery-sdk`
7+
8+
## Public API
9+
10+
- **Exported** `stack`, **Stack**, query/entry/asset types match **README** and **`.d.ts`** output in **`dist/modern/`**.
11+
- **JSDoc** on **`stack()`** and key public methods when behavior or options change.
12+
13+
## Compatibility
14+
15+
- Avoid breaking **StackConfig** or method chains without semver strategy; document migration for breaking changes.
16+
17+
## Core / deps
18+
19+
- **`@contentstack/core`** version changes: verify interceptors, errors, and **httpClient** options in **`contentstack.ts`**.
20+
21+
## Tests
22+
23+
- **Unit** coverage for new logic; **API** updates when CDA request/response behavior changes; **browser** if bundling or globals affected.
24+
25+
## Security
26+
27+
- No hardcoded tokens; no logging secrets in new code.

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
description: "CDA Delivery SDK — stack, queries, cache, live preview, @contentstack/core"
3+
globs: ["src/**/*.ts"]
4+
alwaysApply: false
5+
---
6+
7+
# Contentstack TypeScript Delivery SDK (`src/`)
8+
9+
## Stack entry
10+
11+
- **`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`**.
12+
13+
## Features
14+
15+
- **Queries** — **`src/query/*`**: base query, entry/asset/taxonomy/content-type/global-field queryables; chain methods match CDA query parameters.
16+
- **Cache** — **`src/cache`** + **`Policy`** on **StackConfig**; persistence plugins may be documented as optional packages in JSDoc.
17+
- **Sync** — **`src/sync/synchronization.ts`** for sync token workflows.
18+
19+
## Live preview
20+
21+
- **StackConfig.live_preview** — **enable**, **preview_token**, **host**, etc.; keep behavior aligned with tests under **`test/api/live-preview*.spec.ts`**.
22+
23+
## Plugins
24+
25+
- **ContentstackPlugin** interceptors should follow existing **preRequest**/**onData** patterns in **Stack** if extending.
26+
27+
## Core alignment
28+
29+
- HTTP defaults (**timeout**, retries, headers) must stay consistent with **`@contentstack/core`** capabilities; avoid duplicating retry logic that belongs in **core**.
30+
31+
## Docs
32+
33+
- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)

‎.cursor/rules/dev-workflow.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
description: "Branches, build, and test matrix for contentstack-typescript"
3+
globs: ["**/*.ts", "**/*.mjs", "**/*.json"]
4+
alwaysApply: false
5+
---
6+
7+
# Development workflow — `@contentstack/delivery-sdk`
8+
9+
## Before a PR
10+
11+
1. **`npm run build`** — Rollup + type declarations succeed.
12+
2. **`npm run test:unit`** — required baseline.
13+
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.
14+
4. **Browser / e2e** — run when changing bundling, globals, or browser-specific code (`npm run test:browser`, `npm run test:e2e` as needed).
15+
16+
## Dependency on core
17+
18+
- 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.
19+
20+
## Versioning
21+
22+
- Update **`package.json` `version`** per semver for user-visible SDK changes.
23+
24+
## Links
25+
26+
- [`AGENTS.md`](../../AGENTS.md) · [`skills/contentstack-delivery-typescript/SKILL.md`](../../skills/contentstack-delivery-typescript/SKILL.md)

‎.cursor/rules/testing.mdc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
description: "Jest unit/api/browser tests and Playwright e2e for delivery-sdk"
3+
globs:
4+
- "test/**/*.ts"
5+
- "playwright.config.ts"
6+
alwaysApply: false
7+
---
8+
9+
# Testing — `@contentstack/delivery-sdk`
10+
11+
## Jest
12+
13+
| Suite | Path | Notes |
14+
|-------|------|--------|
15+
| **Unit** | `test/unit/**/*.spec.ts` | Mocked / fast; `npm run test:unit` |
16+
| **API** | `test/api/**/*.spec.ts` | Real stack — **`.env`** via **`test/utils/stack-instance.ts`** |
17+
| **Browser** | `test/browser/**/*.spec.ts` | `jest.config.browser.ts` |
18+
19+
- **`jest.setup.ts`** — console capture, suppression of **expected** validation error noise; do not weaken checks for real failures.
20+
21+
## Env (`test/api` and helpers)
22+
23+
Required for **`stackInstance()`**:
24+
25+
- **`HOST`**, **`API_KEY`**, **`DELIVERY_TOKEN`**, **`ENVIRONMENT`**
26+
27+
Optional:
28+
29+
- **`PREVIEW_TOKEN`**, **`LIVE_PREVIEW_HOST`**
30+
31+
## E2E
32+
33+
- **`npm run test:e2e`** — builds browser bundle then **Playwright** (`test/e2e`, `playwright.config.ts`).
34+
35+
## Hygiene
36+
37+
- 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‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
description: "TypeScript conventions for the Delivery SDK src and tooling"
3+
globs:
4+
- "src/**/*.ts"
5+
- "config/**/*.ts"
6+
- "jest.config.ts"
7+
- "jest.config.browser.ts"
8+
- "jest.setup.ts"
9+
- "jest.setup.browser.ts"
10+
- "rollup.config.js"
11+
alwaysApply: false
12+
---
13+
14+
# TypeScript — `@contentstack/delivery-sdk`
15+
16+
## Layout
17+
18+
- **`src/stack/`** — **`stack()`** factory and **Stack** implementation.
19+
- **`src/query/`**, **`src/entries/`**, **`src/assets/`**, **`src/sync/`**, **`src/cache/`** — feature modules.
20+
- **`src/common/types.ts`** — **`StackConfig`**, **Region**, plugins, cache policies, etc.
21+
22+
## Style
23+
24+
- Follow **`.eslintrc.json`** and existing naming (including eslint disables only where already established, e.g. **stack** factory export).
25+
26+
## Imports
27+
28+
- **`@contentstack/core`** — **`httpClient`**, retry handlers.
29+
- **`@contentstack/utils`** — re-exported from **`contentstack.ts`** where applicable.
30+
- **`axios`** types for headers where needed.
31+
32+
## Security
33+
34+
- Do not log **delivery tokens**, **preview tokens**, or **api keys**; use existing error and debug patterns.

‎AGENTS.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# AGENTS.md — AI / automation context
2+
3+
## Project
4+
5+
| | |
6+
|---|---|
7+
| **Name** | **`@contentstack/delivery-sdk`** (npm) — **Contentstack TypeScript Content Delivery SDK** |
8+
| **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`**. |
9+
| **Repository** | [contentstack/contentstack-typescript](https://github.com/contentstack/contentstack-typescript.git) |
10+
11+
## Tech stack
12+
13+
| Area | Details |
14+
|------|---------|
15+
| **Language** | **TypeScript**, **ES modules** (`"type": "module"`) |
16+
| **Runtime** | Node **>= 18** (`package.json` `engines`) |
17+
| **Build** | **Rollup** (`npm run build:rollup`) + **`tsc`** declarations (`config/tsconfig.decl-esm.json`) → **`dist/modern/`** |
18+
| **Tests** | **Jest** + **ts-jest**: **`test/unit`**, **`test/api`**, **`test/browser`**; **Playwright** e2e (`test/e2e`, `npm run test:e2e`) |
19+
| **Lint** | **ESLint** (`.eslintrc.json`) |
20+
21+
## Source layout
22+
23+
| Path | Role |
24+
|------|------|
25+
| `src/stack/contentstack.ts` | **`stack(config)`** factory — wires **`httpClient`** from **`@contentstack/core`**, region/host, live preview |
26+
| `src/stack/stack.ts` | **Stack** class |
27+
| `src/query/**` | Queries (entry, asset, taxonomy, content type, …) |
28+
| `src/entries/**`, `src/assets/**`, `src/sync/**`, `src/cache/**` | Domain modules |
29+
| `src/common/**` | Types, utils, errors, pagination |
30+
| `src/index.ts` | Public package exports |
31+
| `test/utils/stack-instance.ts` | **`stackInstance()`** — loads **dotenv**, **`HOST`**, **`API_KEY`**, **`DELIVERY_TOKEN`**, **`ENVIRONMENT`**, optional live-preview vars |
32+
33+
## Common commands
34+
35+
```bash
36+
npm install
37+
npm run build
38+
npm run test:unit # jest ./test/unit
39+
npm run test:api # live API — needs .env (see stack-instance)
40+
npm run test:browser
41+
npm run test:e2e # Playwright (builds browser bundle first)
42+
npm run test:all # unit + browser + api
43+
```
44+
45+
## Environment variables (API / integration tests)
46+
47+
Loaded via **`dotenv`** in **`test/utils/stack-instance.ts`**:
48+
49+
- **`HOST`**, **`API_KEY`**, **`DELIVERY_TOKEN`**, **`ENVIRONMENT`** — stack connection
50+
- Optional: **`PREVIEW_TOKEN`**, **`LIVE_PREVIEW_HOST`** for live preview tests
51+
52+
Do not commit secrets.
53+
54+
## Further guidance
55+
56+
- **Cursor rules:** [`.cursor/rules/README.md`](.cursor/rules/README.md)
57+
- **Skills:** [`skills/README.md`](skills/README.md)
58+
59+
Product docs: [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/).

‎skills/README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Project skills — `@contentstack/delivery-sdk`
2+
3+
| Skill | When to use |
4+
|-------|-------------|
5+
| [`code-review/`](code-review/SKILL.md) | PR review, semver, core dependency bumps |
6+
| [`testing/`](testing/SKILL.md) | Unit vs API vs browser vs Playwright |
7+
| [`contentstack-delivery-typescript/`](contentstack-delivery-typescript/SKILL.md) | **stack**, Stack class, queries, sync, cache |
8+
| [`framework/`](framework/SKILL.md) | **@contentstack/core** HTTP + retries on the stack |
9+
10+
**Overview:** [`AGENTS.md`](../AGENTS.md) · **Rules:** [`.cursor/rules/README.md`](../.cursor/rules/README.md)

‎skills/code-review/SKILL.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
name: code-review
3+
description: PR review for @contentstack/delivery-sdk — public API, StackConfig, core alignment, tests.
4+
---
5+
6+
# Code review — `@contentstack/delivery-sdk`
7+
8+
## Checklist
9+
10+
- [ ] **API:** New or changed **`stack()`** / **Stack** / query methods documented; exports updated in **`src/index.ts`**.
11+
- [ ] **Types:** **StackConfig** and public interfaces remain consistent with **`dist/modern/*.d.ts`** after build.
12+
- [ ] **@contentstack/core:** Version or API changes validated in **`src/stack/contentstack.ts`** (interceptors, **httpClient** options).
13+
- [ ] **Tests:** **`test:unit`** passes; add/extend **`test/api`** when integration behavior changes; browser/e2e if relevant.
14+
- [ ] **Secrets:** No tokens in repo; **stack-instance** env vars only for local CI secrets store.
15+
16+
## References
17+
18+
- `.cursor/rules/code-review.mdc`
19+
- `.cursor/rules/dev-workflow.md`

‎skills/contentstack-delivery-typescript/SKILL.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
name: contentstack-delivery-typescript
3+
description: @contentstack/delivery-sdk — TypeScript CDA client, stack factory, queries, sync, cache, live preview.
4+
---
5+
6+
# Contentstack TypeScript Delivery SDK skill
7+
8+
## Entry
9+
10+
- **`contentstack.stack(config)`** — **`src/stack/contentstack.ts`**: merges **StackConfig**, resolves **Region** → host, attaches **@contentstack/core** **`httpClient`** with retry handlers, returns **`Stack`**.
11+
12+
## Structure
13+
14+
- **`Stack`** — **`src/stack/stack.ts`**: content types, entries, assets, sync, taxonomy helpers.
15+
- **Queries** — **`src/query/`**: **BaseQuery**, **Query**, **AssetQuery**, **TaxonomyQuery**, **ContentTypeQuery**, **GlobalFieldQuery**, **EntryQueryable**, etc.
16+
- **Sync** — **`src/sync/`**
17+
- **Cache** — **`src/cache/`** + **Policy** enum in types.
18+
19+
## Extending
20+
21+
- Add query methods on the appropriate class; keep param names aligned with **CDA** query docs.
22+
- Prefer delegating transport concerns to **core** rather than duplicating Axios logic.
23+
24+
## Consumer packages
25+
26+
- **`@contentstack/core`** — HTTP + retries
27+
- **`@contentstack/utils`** — utilities; re-exported where documented.
28+
29+
## Docs
30+
31+
- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)
32+
33+
## Rule shortcut
34+
35+
- `.cursor/rules/contentstack-delivery-typescript.mdc`

0 commit comments

Comments
 (0)