Skip to content

Commit 98a69cd

Browse files
harshitha-cstkharshitha-cstk
authored
Merge branch 'development' into fix/dx-6049-update-cursor-rules-skills
2 parents d268062 + 402adba commit 98a69cd

File tree

8 files changed

+253
-0
lines changed

8 files changed

+253
-0
lines changed

‎.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.

‎.cursor/rules/contentstack-javascript-cda.mdc‎

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.

‎skills/README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Project skills
2+
3+
Short playbooks for agents and maintainers. Prefer these when you need depth beyond `.cursor/rules/*.mdc`.
4+
5+
| Skill | When to use |
6+
|-------|-------------|
7+
| [`code-review/`](code-review/SKILL.md) | Structured PR review, release readiness, API/doc alignment |
8+
| [`testing/`](testing/SKILL.md) | Jest e2e vs TypeScript tests, `test/config.js` env, dist build |
9+
| [`contentstack-javascript-cda/`](contentstack-javascript-cda/SKILL.md) | CDA usage: `Stack`, delivery token, regions, queries, sync, live preview |
10+
| [`framework/`](framework/SKILL.md) | Request layer: `fetch`, retries, plugins, runtime adapters |
11+
12+
**Repo overview:** see root [`AGENTS.md`](../AGENTS.md). **Rule index:** [`.cursor/rules/README.md`](../.cursor/rules/README.md).

‎skills/contentstack-javascript-cda/SKILL.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
name: contentstack-js-cda
3+
description: Contentstack Content Delivery (CDA) JavaScript SDK — Stack, tokens, regions, queries, sync, live preview in src/core/.
4+
---
5+
6+
# Contentstack JavaScript CDA SDK skill
7+
8+
This repository ships **`contentstack`**, the **Content Delivery API** read client. It is **not** the Content Management API client (`@contentstack/management`).
9+
10+
## Mental model
11+
12+
1. **`Contentstack.Stack(options)`** (`src/core/stack.js`) configures the stack (**`api_key`**, **`delivery_token`**, **`environment`**, optional **`region`**, **`branch`**, **`host`**, **`live_preview`**, **`plugins`**, **`fetchOptions`**).
13+
2. **Modules** under **`src/core/modules/`** implement **entries**, **assets**, **queries**, **taxonomy**, **results**, etc., composed from the stack instance.
14+
3. **`src/core/lib/request.js`** performs **`fetch`**, query string building, retries, and **plugin** hooks.
15+
4. **`src/runtime/*`** provides platform-specific **`http`** and **localstorage** implementations selected at build time.
16+
17+
## Configuration (see JSDoc on `Stack`)
18+
19+
- **`region`** / **`host`** — CDN / API host selection (see `stack.js` and **`config.js`** defaults).
20+
- **`fetchOptions`** — **`timeout`**, **`retryLimit`**, **`retryDelay`**, **`retryCondition`** (defaults include **408** / **429**), **`retryDelayOptions`**, **`debug`**, **`logHandler`**.
21+
- **`live_preview`** — enable flag, **`host`**, **`management_token`** or **`preview_token`**; affects which host serves preview vs delivery.
22+
- **`plugins`** — `{ onRequest, onResponse }` hooks invoked from `request.js`.
23+
24+
## Implementing features
25+
26+
- Follow neighbors in **`src/core/modules/`** for method chaining, URL construction, and parameter passing into **`Request`**.
27+
- Consider **cache policy** and **sync** behaviors when changing read paths.
28+
- Multi-platform: verify **webpack** entries for **node**, **web**, **react-native**, **nativescript** if adding runtime dependencies.
29+
30+
## Docs
31+
32+
- Product: [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)
33+
- Types: root **`index.d.ts`**
34+
35+
## Rule shortcut
36+
37+
- `.cursor/rules/contentstack-javascript-cda.mdc` when editing `src/**/*.js`

‎skills/framework/SKILL.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
name: framework
3+
description: HTTP and cross-cutting behavior for the CDA SDK — request.js, fetch retries, plugins, runtime http/localstorage.
4+
---
5+
6+
# Framework skill — HTTP / transport / runtime
7+
8+
The SDK isolates networking and retries in **`src/core/lib/request.js`**, with platform-specific **`fetch`** and storage under **`src/runtime/`**.
9+
10+
## Key modules
11+
12+
| File / area | Responsibility |
13+
|-------------|----------------|
14+
| **`src/core/lib/request.js`** | Builds query string from stack **`requestParams`**, sets headers (**`X-User-Agent`**, content type), **`fetchRetry`**, integrates **`stack.plugins`** (`onRequest` / `onResponse`), parses JSON, maps HTTP errors to rejection objects |
15+
| **`src/core/lib/utils.js`** | Merge/deep helpers and shared utilities used by stack and modules |
16+
| **`src/core/stack.js`** | Default **`fetchOptions`** (retry policy, **`logHandler`**), merges user options, constructs **`requestParams`** for calls |
17+
| **`src/runtime/node/http.js`**, **`web/http.js`**, etc. | Platform **`fetch`** implementation wired via webpack alias **`runtime/http.js`** |
18+
| **`src/runtime/*/localstorage.js`** | Cache provider storage for each target |
19+
20+
## When to change this layer
21+
22+
- **Retry policy**, status-based retry, timeout defaults → **`request.js`** / **`stack.js`** (`fetchOptions`) and JSDoc on **`Stack`**.
23+
- **Headers**, user-agent format, query serialization → **`request.js`** (keep backward compatible for CDN query shapes).
24+
- **New global hook** → extend **plugin** contract consistently in **`request.js`**.
25+
- **New platform** → add **`src/runtime/<platform>/`**, webpack config, and package **entry** fields if needed.
26+
27+
## Tests
28+
29+
- Extend **`test/`** or **`test/typescript/`** when changing request behavior; many suites load **`dist/node/contentstack.js`** — run **`npm run build`** after `src/` edits.
30+
31+
## Rule shortcut
32+
33+
- `.cursor/rules/javascript.mdc` for style; CDA semantics in `.cursor/rules/contentstack-javascript-cda.mdc`

0 commit comments

Comments
 (0)