AGENTS.md

1# Agent guidance — `@contentstack/utils`
2 
3## What this package is
4 
5**[@contentstack/utils](https://www.npmjs.com/package/@contentstack/utils)** (`contentstack-utils-javascript`) is a **JavaScript/TypeScript utilities library** for Contentstack. It is **not** the Content Delivery API (CDA) SDK or the Content Management API (CMA) SDK. It focuses on **JSON RTE / Supercharged RTE** rendering (`jsonToHTML`), **embedded entry and asset** rendering (`render`, `renderContent`), **GraphQL-oriented helpers** (`GQL`, `updateAssetURLForGQL`), **Live Preview–style editable tags** (`addEditableTags` / `addTags`), and **region endpoint lookup** (`getContentstackEndpoint`). Typical usage is **alongside** the Delivery SDK (see repository `README.md` examples with `@contentstack/delivery-sdk`).
6 
7- **Repository:** [github.com/contentstack/contentstack-utils-javascript](https://github.com/contentstack/contentstack-utils-javascript)
8 
9## Tech stack
10 
11| Area | Details |
12|------|---------|
13| Language | TypeScript **4.9** (`tsconfig.json`, `strict: true`, `strictNullChecks: false`) |
14| Build | **TypeScript** (`tsc`) → `dist/lib`; **Rollup** (`rollup -c`) → `dist/index.es.js`; types in `dist/types/` |
15| Test | **Jest 29** + **ts-jest**, **jsdom** environment (`jest.config.ts`) |
16| Lint / format | **ESLint 9** flat config (`eslint.config.js`); **Prettier 3** (`npm run format`) — there is **no** `lint` npm script; use `npx eslint` as needed |
17| Runtime HTTP / JSON for API calls | **None** in library code; `regions.json` is a **build-time** asset (see below) |
18 
19## Source layout and public API
20 
21| Role | Path |
22|------|------|
23| Public entry (sources) | `src/index.ts` |
24| Options / render types | `src/options/` |
25| RTE / node model | `src/Models/`, `src/nodes/` |
26| Helpers | `src/helper/` |
27| GQL + asset URL rewrite | `src/gql.ts`, `src/updateAssetURLForGQL.ts` |
28| Endpoints helper | `src/endpoints.ts` + `src/assets/regions.json` (generated; see build) |
29| Published bundle | `dist/` (per `package.json` `main` / `types`) |
30 
31## Common commands
32 
33| Command | Purpose |
34|---------|---------|
35| `npm run build` | Cleans `dist`, ensures `src/assets/regions.json` (download or warning), runs `tsc` + Rollup |
36| `npm test` | Runs `pretest` → **build**, then Jest with coverage; outputs under `reports/` |
37| `npm run test:debug` | Jest watch, in-band |
38| `npm run format` | Prettier on `src/**/*.ts` |
39| `npm run download-regions` | Fetches `regions.json` only (used by `prebuild`) |
40 
41**Tests:** Unit tests only, under `__test__/**/*.test.ts`, with mocks in `__test__/mock/`. There are **no** live/integration tests requiring stack credentials in this repository.
42 
43## Credentials / environment
44 
45- **Unit tests:** No API keys or `.env` required.
46- **Build:** `download-regions` calls a public URL (`artifacts.contentstack.com`); offline builds may warn and rely on an existing `src/assets/regions.json`. Note `regions.json` is listed in `.gitignore`; clones may need a successful `npm run build` (or manual file) before tests pass.
47- **Publish:** GitHub release workflow uses `NPM_TOKEN` / `GIT_TOKEN` secrets (maintainers only).
48 
49## More detail for AI / IDE rules
50 
51- [`.cursor/rules/README.md`](.cursor/rules/README.md) — Cursor rules index (`alwaysApply`, globs, when to use).
52- [`skills/README.md`](skills/README.md) — Topic skills (testing, code review, package mental model).
53