Skip to content

Commit d178b32

Browse files
harshitha-cstkharshitha-cstk
authored
Merge branch 'development' into fix/dx-6043-update-cursor-rules-skills
2 parents 58c3ce9 + 46135b7 commit d178b32

File tree

8 files changed

+254
-0
lines changed

8 files changed

+254
-0
lines changed

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

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
description: PR checklist — API docs, compat, errors, tests, Marketplace vs CDA/CMA terminology
3+
alwaysApply: true
4+
---
5+
6+
# Code review checklist
7+
8+
Use this for any change touching the SDK. Severity labels are optional guidance for reviewers.
9+
10+
## API and documentation
11+
12+
- **Public surface:** New or changed `client()`, `marketplace()`, or chain methods need **JSDoc** consistent with surrounding symbols (params, return `Promise`, examples where helpful).
13+
- **Types:** Update `types/**/*.d.ts` when exports or shapes change.
14+
15+
## Product terminology
16+
17+
- This repo is **Marketplace / Developer Hub** — **not CDA** (Delivery) and not general **stack CMA content** unless the change explicitly introduces that scope. PR text and user-facing strings must not mislabel the product.
18+
19+
## Backward compatibility
20+
21+
- Avoid breaking `client()` options, method signatures, or default behavior without semver intent and migration notes.
22+
- Preserve existing header names and axios defaults unless versioned or documented.
23+
24+
## Errors
25+
26+
- HTTP failures should continue to map through **`contentstackError`** patterns (status, message body fields, header redaction)—no raw axios leaks to callers unless intentional and documented.
27+
28+
## Safety and robustness
29+
30+
- Guard null/undefined for optional nested params consistent with existing modules.
31+
- No sensitive logging of full tokens (follow redaction patterns in `contentstackError`).
32+
33+
## Dependencies and security
34+
35+
- New dependencies need justification; run/license alignment with MIT stack.
36+
- Be mindful of supply-chain risk for install scripts and pinned ranges.
37+
38+
## Tests
39+
40+
- **Unit:** Extend `test/unit/` for logic in `lib/`.
41+
- **Sanity:** Only when live API checks are required—document env vars; do not commit credentials.
42+
- TypeScript samples: update `test/typescript/` when public types warrant it.
43+
44+
## Severity (optional)
45+
46+
| Level | Examples |
47+
|-------|----------|
48+
| **Blocker** | Broken default auth, security regression of tokens, published API removed without major bump |
49+
| **Major** | Missing tests for new behavior, incorrect error mapping, wrong docs that mislead CDA vs Marketplace |
50+
| **Minor** | JSDoc nits, internal naming, non-user-facing refactor |

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

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
description: Marketplace / Developer Hub SDK — auth, host, HTTP behavior in lib/
3+
globs: lib/**
4+
alwaysApply: false
5+
---
6+
7+
# Contentstack Marketplace SDK (`lib/`)
8+
9+
This package is a **Marketplace (Developer Hub) management** client, not **CDA** and not generic **stack CMA content** APIs. Terminology and docs should say **Marketplace**, Developer Hub, apps, installations, hosting, OAuth as appropriate—avoid implying Delivery or stack entry CRUD unless adding a new surface that truly uses those APIs.
10+
11+
## Client bootstrap
12+
13+
- **`lib/contentstack.js` — `client(params)`:** Builds axios-based HTTP client via `contentstackHTTPClient`, merges `authtoken` / `authorization` into headers, sets `X-User-Agent` / `User-Agent` (includes `contentstack-marketplace-sdk/<version>`). Default hostname comes from `@contentstack/utils` `getContentstackEndpoint(region, 'developerHub', true)`.
14+
- **`Region`:** `lib/core/region.js` — `eu`, `na` (empty string), `azure-na`, `azure-eu`, `gcp-na`. Pass via `params.region` (lowercased internally).
15+
16+
## Auth patterns (actual usage)
17+
18+
- Headers: `authtoken` and/or `authorization` (e.g. OAuth bearer) on the axios instance.
19+
- **`contentstackClient.login`:** POST to `/v3/user-session` (host varies by `region` / `host`); stores returned `authtoken` on `http.defaults.headers.common`.
20+
- **`refreshToken`:** Optional callback in `client()` params (see JSDoc in `contentstack.js`) for token rotation.
21+
- **Marketplace calls:** `client.marketplace(orgUid)` → `lib/marketplace/**` (apps, installation, hosting, webhooks, OAuth helpers, authorization, app requests).
22+
23+
## HTTP layer
24+
25+
- **`lib/core/contentstackHTTPClient.js`:** Axios instance, default `timeout` 30000, `retryOnError` true, default `retryCondition` retries on **HTTP 429**. Uses `Qs` for `paramsSerializer` (including encoded `query` JSON). `versioningStrategy: 'path'`.
26+
- **Concurrency:** `lib/core/concurrency-queue.js` caps parallel requests (`maxRequests`).
27+
- **Errors:** Responses go through `lib/core/contentstackError.js` — enriches thrown `Error` with `status`, `errorMessage`, `errorCode`, `errors`, sanitized headers.
28+
29+
## Official docs alignment
30+
31+
Relate behavior to **Developer Hub / Marketplace** and **user session** documentation on [contentstack.com/docs](https://www.contentstack.com/docs), not to **CDA** delivery references unless the code explicitly integrates delivery tokens for a marketplace feature.

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
description: Branches, lint/tests, PR and release expectations for marketplace-sdk
3+
globs: "**/*"
4+
alwaysApply: false
5+
---
6+
7+
# Dev workflow
8+
9+
## Branching
10+
11+
Follow team/GitHub conventions (feature branches, PRs to default branch). Use ticket IDs in branch names when required by the team (e.g. `feat/DX-5383-...`).
12+
13+
## Local quality gate
14+
15+
1. `npm run lint` — ESLint on `lib/` and `test/`.
16+
2. `npm run test:unit` — Mocha + NYC (triggers `pretest`: cleans coverage and runs lint).
17+
3. Optional: `npm run test:typescript` for Jest TS samples.
18+
19+
CI runs `npm ci` and `npm run test:unit:report:json` (see `.github/workflows/unit-test.yml`).
20+
21+
## PR expectations
22+
23+
- Unit tests updated or added for behavioral changes in `lib/`.
24+
- No committed secrets; sanity fixtures stay out of version control if they contain tokens.
25+
- Match existing Standard JS style and JSDoc depth on public APIs.
26+
27+
## Releases
28+
29+
Version lives in `package.json`. `prepare` runs `npm run build` on install/publish—ensure the `dist/` build succeeds before tagging. Coordinate npm release process with maintainers (changelog, semver).
30+
31+
## Known script gap
32+
33+
Root `npm test` references a non-existent `test:api` script; use `npm run test:unit` until `test:api` is defined.

‎.cursor/rules/javascript.mdc‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
description: JavaScript source layout, ESLint Standard, logging for marketplace-sdk
3+
globs: "**/*.{js,ts}"
4+
alwaysApply: false
5+
---
6+
7+
# JavaScript (lib / test / types)
8+
9+
## Language and layout
10+
11+
- **Source:** `lib/` — ES modules (`import`/`export`). Built outputs in `dist/` (Webpack + Babel); do not hand-edit `dist/`.
12+
- **Tests:** Mocha + Chai in `test/unit/` and `test/sanity-check/`; Jest + TypeScript samples in `test/typescript/`.
13+
- **Types:** Hand-maintained declarations under `types/` (e.g. `types/contentstackClient.d.ts`, `types/marketplace/**`).
14+
15+
## Style
16+
17+
- **ESLint:** `extends: 'standard'` (`.eslintrc.js`), `ecmaVersion: 2020`, `sourceType: 'module'`.
18+
- Prefer explicit, readable names; avoid drive-by reformatting unrelated code.
19+
20+
## Logging
21+
22+
- HTTP logging hooks: `lib/core/messageHandler.js` (`httpLogHandler` referenced from `contentstackHTTPClient`).
23+
- When adding diagnostics, follow existing patterns—do not replace with ad-hoc `console` in core paths unless consistent with `logHandler` usage.
24+
25+
## Dependencies (declared)
26+
27+
Runtime: `axios`, `@contentstack/utils`. Keep `package.json` accurate when adding imports.

‎.cursor/rules/testing.mdc‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
description: Mocha, Jest, sanity tests, env vars for marketplace-sdk
3+
globs: test/**
4+
alwaysApply: false
5+
---
6+
7+
# Testing
8+
9+
## Unit tests (Mocha + NYC)
10+
11+
- **Entry:** `test/unit/index.js` requires individual `*-test.js` files.
12+
- **Command:** `npm run test:unit` (30s timeout, `BABEL_ENV=test`, `@babel/register`, `babel-polyfill`).
13+
- **Coverage:** NYC HTML + text; clover for `test:unit:report:json` (CI).
14+
- **Mocks:** `test/unit/mock/**`, `axios-mock-adapter`, `nock`, `sinon` as used in existing tests.
15+
16+
## TypeScript / Jest
17+
18+
- **Config:** `jest.config.js` — `ts-jest`, coverage to `coverage/`, tests under `test/typescript/` (`*.test.ts`, etc.).
19+
- **Command:** `npm run test:typescript`.
20+
21+
## Sanity / integration-style (live API)
22+
23+
- **Entry:** `test/sanity-check/sanity.js` requires API suites under `test/sanity-check/api/`.
24+
- **Command:** `npm run test:sanity-test` (or `test:sanity` which swallows failures—avoid for strict gates).
25+
- **Env:** `dotenv` loads `.env`. Examples from existing specs: `ORG_UID`, `HOST`, `DEFAULTHOST`, `ADMIN_EMAIL`, `USER_EMAIL`, `EMAIL`, `PASSWORD`. Utility client: `test/sanity-check/utility/ContentstackClient.js` (`host`, `defaultHostName` from env).
26+
- **Fixtures:** JSON read/write in `test/sanity-check/utility/fileOperations/readwrite.js` (e.g. `loggedinAdmin.json`) — treat as local secrets; never commit populated files.
27+
28+
## Naming
29+
30+
- Unit: `*-test.js` beside concepts (`marketplace-test.js`, `ContentstackHTTPClient-test.js`).
31+
- Sanity: `*-test.js` or descriptive names under `test/sanity-check/api/`.
32+
33+
## Pretest
34+
35+
`npm run test:unit` runs `pretest` (`rimraf coverage` + `npm run lint`) unless invoked with `--ignore-scripts`—account for lint when debugging failing tests.

‎skills/README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Skills — @contentstack/marketplace-sdk
2+
3+
Project-local skills for AI agents. Each folder contains a `SKILL.md` with YAML frontmatter (`name`, `description`).
4+
5+
| Skill | When to use |
6+
|-------|-------------|
7+
| [code-review](code-review/SKILL.md) | PRs, pre-merge review, risk triage |
8+
| [testing](testing/SKILL.md) | Running/fixing tests, env for sanity runs, mocks |
9+
| [contentstack-javascript-marketplace](contentstack-javascript-marketplace/SKILL.md) | Where to change client/marketplace behavior; auth and host model |
10+
| [framework](framework/SKILL.md) | Axios HTTP client, retries, concurrency queue, serializers |
11+
12+
Cursor rules index: [`.cursor/rules/README.md`](../.cursor/rules/README.md). Repo overview: [`AGENTS.md`](../AGENTS.md).

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

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
name: contentstack-javascript-marketplace
3+
description: Mental model for the Marketplace SDK — client factory, org-scoped marketplace API, auth, regions, module map
4+
---
5+
6+
# Contentstack JavaScript Marketplace SDK
7+
8+
## Mental model
9+
10+
1. **`contentstack.client(options)`** (`lib/contentstack.js`) creates an axios-based HTTP client pointed at the **Developer Hub** host (via `@contentstack/utils` + `region`), then wraps it with **`contentstackClient`** (`lib/contentstackClient.js`).
11+
2. **Auth:** Pass `authtoken` and/or `authorization`, or call **`login`** to set `authtoken` on shared axios defaults. Optional **`refreshToken`** callback supports rotation.
12+
3. **Marketplace entry:** **`client.marketplace(organization_uid)`** returns `lib/marketplace/index.js` — apps (`app()`, `findAllApps`, …), installations, hosting/deployments, webhooks, OAuth under `app/oauth`, authorization helpers, app requests.
13+
14+
## Where to change things
15+
16+
| Concern | Primary paths |
17+
|---------|----------------|
18+
| Client defaults, User-Agent, region → host | `lib/contentstack.js`, `lib/core/region.js` |
19+
| Login / logout / marketplace root | `lib/contentstackClient.js` |
20+
| Axios, retries (429), timeout, query encoding | `lib/core/contentstackHTTPClient.js` |
21+
| Request queuing | `lib/core/concurrency-queue.js` |
22+
| Error shape | `lib/core/contentstackError.js` |
23+
| Marketplace resources | `lib/marketplace/**/*.js` |
24+
| Public TypeScript types | `types/**/*.d.ts` |
25+
26+
## Docs alignment
27+
28+
Describe behavior against **Contentstack Marketplace / Developer Hub** APIs. Do not document this package as **CDA**. Mention **CMA-style tokens** only when describing authtoken / management-style auth accurately.
29+
30+
## Integration reminder
31+
32+
Downstream apps use **`@contentstack/marketplace-sdk`** with **`import contentstack from '@contentstack/marketplace-sdk'`** (see README). The built **`main`** field points to **`dist/node/...`** — edit **`lib/`** and run **`npm run build`** for distributable changes.

‎skills/framework/SKILL.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
name: framework
3+
description: HTTP stack for marketplace-sdk — Axios wrapper, retries, concurrency, params serialization, logging hook
4+
---
5+
6+
# HTTP framework (`lib/core`)
7+
8+
This repo separates **domain** (`lib/marketplace/**`) from a small **HTTP framework** in `lib/core/`. Use this skill when changing transport behavior.
9+
10+
## `contentstackHTTPClient.js`
11+
12+
- Builds an **axios** instance with `baseURL` from `endpoint` or `protocol://hostname:port` + `basePath`.
13+
- **Defaults:** `timeout` 30000, `retryOnError` true, `retryCondition` retries **429** (overridable).
14+
- **Headers:** Maps `apiKey` / `accessToken` from config if present.
15+
- **Params:** Custom `paramsSerializer` using **Qs**; nests JSON `query` with `encodeURIComponent`.
16+
- **Concurrency:** Attaches `ConcurrencyQueue` to the instance.
17+
- **Logging:** `logHandler` default from `messageHandler.js` (`httpLogHandler`).
18+
19+
## `concurrency-queue.js`
20+
21+
- Limits parallel in-flight requests (`maxRequests` from client params). Changes here affect all API modules sharing the same HTTP instance.
22+
23+
## `messageHandler.js`
24+
25+
- Central place for HTTP log/telemetry hooks. Keep implementations safe for browsers and Node bundles.
26+
27+
## When to edit
28+
29+
- Retry/backoff policy, timeout, or serializer → prefer extending **existing** options on `client()` rather than one-off axios calls in marketplace modules.
30+
- New global header behavior → `contentstack.js` + potentially `contentstackHTTPClient.js` for low-level concerns.
31+
32+
## Testing
33+
34+
- **`test/unit/ContentstackHTTPClient-test.js`** and **`concurrency-Queue-test.js`** should cover behavioral changes; use mocks rather than live HTTP when possible.

0 commit comments

Comments
 (0)