From bccc9317c1990882c117f9ba43c4ff2d974cdfb0 Mon Sep 17 00:00:00 2001 From: raj pandey Date: Sun, 19 Apr 2026 05:30:37 +0530 Subject: [PATCH] update: make AGENTS.md canonical for the types library --- .cursor/rules/README.md | 20 +------ .cursor/rules/code-review.mdc | 29 ---------- .cursor/rules/contentstack-delivery-cda.mdc | 25 -------- .cursor/rules/dev-workflow.mdc | 38 ------------- .cursor/rules/testing.mdc | 18 ------ .cursor/rules/typescript.mdc | 14 ----- .talismanrc | 18 +++--- AGENTS.md | 63 +++++++++++---------- skills/README.md | 19 ++++--- skills/code-review/SKILL.md | 2 - skills/dev-workflow/SKILL.md | 36 ++++++++++++ skills/typescript-types-generator/SKILL.md | 52 ++++++++++------- 12 files changed, 124 insertions(+), 210 deletions(-) delete mode 100644 .cursor/rules/code-review.mdc delete mode 100644 .cursor/rules/contentstack-delivery-cda.mdc delete mode 100644 .cursor/rules/dev-workflow.mdc delete mode 100644 .cursor/rules/testing.mdc delete mode 100644 .cursor/rules/typescript.mdc create mode 100644 skills/dev-workflow/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md index 634bc5a..f5c1f87 100644 --- a/.cursor/rules/README.md +++ b/.cursor/rules/README.md @@ -1,19 +1,5 @@ -# Cursor rules for `@contentstack/types-generator` +# Cursor (optional) -This folder contains project-specific rules for AI assistants and developers. Each file lists its scope in YAML frontmatter (`description`, `globs`, `alwaysApply`). - - -| Rule file | `alwaysApply` | Globs | When it applies | Related skill | -| -------------------------------------------------------------- | ------------- | ------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | -| [dev-workflow.mdc](dev-workflow.mdc) | No | `package.json`, `package-lock.json`, `.github/workflows/**/*`, `jest.config.js`, `tsup.config.ts`, `AGENTS.md` | Branch strategy, build/test commands, PR and release expectations | [testing](../../skills/testing/SKILL.md), [code-review](../../skills/code-review/SKILL.md) | -| [typescript.mdc](typescript.mdc) | No | `src/**/*.ts`, `tests/**/*.ts` | Editing or adding TypeScript in this package | [typescript-types-generator](../../skills/typescript-types-generator/SKILL.md) | -| [contentstack-delivery-cda.mdc](contentstack-delivery-cda.mdc) | No | `src/sdk/**`, `src/generateTS/**`, `src/graphqlTS/**` | Delivery SDK, regions, stack config, GraphQL introspection/axios | [typescript-types-generator](../../skills/typescript-types-generator/SKILL.md) | -| [testing.mdc](testing.mdc) | No | `tests/**`, `jest.config.js` | Writing or running Jest tests, env for live tests | [testing](../../skills/testing/SKILL.md) | -| [code-review.mdc](code-review.mdc) | **Yes** | — | Every change: API docs, compatibility, errors, security, tests | [code-review](../../skills/code-review/SKILL.md) | - - -## Referencing rules in Cursor - -- Use **@** in chat and pick a rule file (e.g. `@contentstack-delivery-cda`, `@dev-workflow`) to focus the model on Delivery/GraphQL or workflow context. -- Rules with `alwaysApply: true` are included automatically; others apply when matching files are in context or when @-mentioned. +**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**. +This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs. diff --git a/.cursor/rules/code-review.mdc b/.cursor/rules/code-review.mdc deleted file mode 100644 index 5170e2a..0000000 --- a/.cursor/rules/code-review.mdc +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: PR and change review checklist for types-generator -alwaysApply: true ---- - -# Code review checklist - -Use this for every change. Severity labels are optional (**Blocker** / **Major** / **Minor**). - -## API and documentation - -- **Public API:** New or changed exports need **JSDoc** (or equivalent) where the package documents behavior; keep examples accurate. -- **Terminology:** Use **CDA / Delivery** and **GraphQL** as in this codebase. **Do not** describe this library as CMA or Management-API–centric. - -## Compatibility - -- **Backward compatibility:** Avoid breaking changes to function signatures, error shapes, and generated output format unless versioned or documented. -- **Errors:** Align with existing patterns: **`type: "validation"`** and related helpers in `generateTS` / `graphqlTS`; do not silently swallow SDK or network errors. - -## Correctness and safety - -- **Null safety:** Respect **`strictNullChecks`**; guard optional stack config (`host`, `branch`, etc.). -- **Dependencies:** New dependencies need justification; watch license and footprint. **SCA:** `.github/workflows/sca-scan.yml` runs Snyk and `contentstack/sca-policy` on PRs. - -## Tests - -- **Unit:** Add or update tests under **`tests/unit/`** for logic changes. -- **Integration / sanity:** Touch **`tests/integration/`** when behavior depends on live APIs; document required env vars. -- **Coverage:** CI uses **`test:unit:report:json`**; keep meaningful coverage for new code paths. diff --git a/.cursor/rules/contentstack-delivery-cda.mdc b/.cursor/rules/contentstack-delivery-cda.mdc deleted file mode 100644 index 11b889f..0000000 --- a/.cursor/rules/contentstack-delivery-cda.mdc +++ /dev/null @@ -1,25 +0,0 @@ ---- -description: Contentstack Delivery (CDA) SDK and GraphQL usage in types-generator -globs: - - src/sdk/** - - src/generateTS/** - - src/graphqlTS/** ---- - -# Contentstack Delivery and GraphQL (this repo) - -Scope: **SDK-facing library code only** (no separate `samples/` tree). This package is **not** a CMA (Management) client. - -## Delivery / CDA - -- **Token type:** Only **`TOKEN_TYPE.DELIVERY`** is defined ([`src/constants/index.ts`](src/constants/index.ts)). `generateTS` validates `tokenType` and uses the **Delivery SDK** for content types and global fields. -- **SDK entry:** [`initializeContentstackSdk`](src/sdk/utils.ts) wraps **`@contentstack/delivery-sdk`** (`Contentstack.stack` with `deliveryToken`, `environment`, `region` or `host`, optional `branch`). -- **Regions:** Map string constants in **`REGIONS`** to **`Region`** enum; **custom** regions require **`host`** (see `isCustomRegion` branch in [`src/sdk/utils.ts`](src/sdk/utils.ts)). -- **Errors:** Validation failures often use **`{ type: "validation", error_message: string }`** or helpers from [`generateTS/shared/utils`](src/generateTS/shared/utils.ts). Preserve stable `type` / message shapes for callers. - -## GraphQL - -- **Transport:** **`graphqlTS`** uses **`axios`** POST to region-specific GraphQL URLs or to **`https://${host}/...`** when `host` is set ([`src/graphqlTS/index.ts`](src/graphqlTS/index.ts)). -- **Schema:** Introspection query + **`@gql2ts/from-schema`** (`schemaToInterfaces`, `generateNamespace`). Align URL and headers (`access_token`, `branch`) with Contentstack GraphQL documentation for the target region. - -When unsure, prefer official **Content Delivery API** / **GraphQL** docs—not Management API patterns. diff --git a/.cursor/rules/dev-workflow.mdc b/.cursor/rules/dev-workflow.mdc deleted file mode 100644 index 1ead756..0000000 --- a/.cursor/rules/dev-workflow.mdc +++ /dev/null @@ -1,38 +0,0 @@ ---- -description: Branches, build/test commands, PR and release workflow for types-generator -alwaysApply: false -globs: - - package.json - - package-lock.json - - .github/workflows/**/* - - jest.config.js - - tsup.config.ts - - AGENTS.md ---- - -# Development workflow - -For deeper detail, see **[skills/testing](../../skills/testing/SKILL.md)** (commands, env, fixtures) and **[skills/code-review](../../skills/code-review/SKILL.md)** (PR expectations). In chat you can also @-mention those skill folders if your workspace exposes them. - -## Branches - -- **CI (Node.js workflow)** runs on **push** and **pull_request** for branches **`master`** and **`development`** (see `.github/workflows/node.js.yml`). -- **Release / publish** runs on **push** to **`main`** (see `.github/workflows/release.yml`), using Node **22.x**, autotag, npm publish, and GitHub release. - -**Maintainer note:** Default branch naming differs between CI (`master`/`development`) and release (`main`). Align branch protection and contributor docs when convenient—no change required for local development if your fork uses the upstream defaults. - -## Local commands - -- **Build:** `npm run build` (tsup; `prepare` also runs build). -- **Test (all under `tests/`):** `npm test` (sets `NODE_OPTIONS=--experimental-vm-modules`). -- **Unit tests + coverage (CI):** `npm run test:unit:report:json` (targets `tests/unit`, coverage and JSON artifacts). - -## Pull requests - -- Ensure **`npm run build`** and **`npm test`** pass before requesting review. -- CI runs **`test:unit:report:json`** with secrets for integration-related env vars; PRs from forks may not have secrets—coordinate with maintainers if integration jobs fail only on secrets. - -## Releases - -- Version in **`package.json`** is the source of truth for the published package. -- Publishing is automated from **`main`** via the release workflow (tag prefix `v`, npm publish, GitHub release). Bump version on the branch that merges to `main` per team process. diff --git a/.cursor/rules/testing.mdc b/.cursor/rules/testing.mdc deleted file mode 100644 index dd30bc3..0000000 --- a/.cursor/rules/testing.mdc +++ /dev/null @@ -1,18 +0,0 @@ ---- -description: Jest tests, layout, and env for types-generator -globs: - - tests/** - - jest.config.js ---- - -# Testing (`@contentstack/types-generator`) - -- **Runner:** **Jest** with **ts-jest** ([jest.config.js](jest.config.js)). **`setupFiles: ["dotenv/config"]`** loads environment variables for tests. -- **Match:** `**/?(*.)+(spec|test).+(ts|tsx)` and `test/**/*.test.ts`. -- **Layout:** - - **`tests/unit/`** — fast, isolated tests (including `tests/unit/tsgen/` with **`.ct.js`** content-type fixtures paired with **`.test.ts`** files). - - **`tests/integration/`** — live stack / API tests (e.g. `generateTS`, `graphqlTS`); require real credentials. -- **Commands:** - - `npm test` — all tests under `tests` (via `--testPathPattern=tests`). - - `npm run test:unit:report:json` — unit coverage + reports for CI. -- **Integration env:** Typically **`TOKEN`**, **`APIKEY`**, **`ENVIRONMENT`**, **`REGION`**, **`TOKENTYPE`**, **`BRANCH`**. Integration tests may load **`.env`** from the package root path (see test files). CI sets additional secrets such as **`TOKEN_WITH_NO_CT`** / **`APIKEY_WITH_NO_CT`** where needed. diff --git a/.cursor/rules/typescript.mdc b/.cursor/rules/typescript.mdc deleted file mode 100644 index c080b0b..0000000 --- a/.cursor/rules/typescript.mdc +++ /dev/null @@ -1,14 +0,0 @@ ---- -description: TypeScript layout, strict mode, and logging for types-generator -globs: - - src/**/*.ts - - tests/**/*.ts ---- - -# TypeScript conventions (`@contentstack/types-generator`) - -- **Compiler:** TypeScript **5.9** with **`strict`**, **`noImplicitAny`**, **`strictNullChecks`** ([tsconfig.json](tsconfig.json)). Prefer explicit types at public boundaries. -- **Layout:** Source lives under **`src/`** — `generateTS/`, `graphqlTS/`, `sdk/`, `types/`, `format/`, `logger/`, `constants/`. Tests mirror under **`tests/unit/`** and **`tests/integration/`**. -- **Logging:** Use **`createLogger`** from [`src/logger`](src/logger/index.ts); pass optional logger instances into `generateTS` / `graphqlTS` where supported. -- **Formatting output:** **`prettier`** is a **runtime** dependency used to format generated TypeScript strings—not only dev formatting. -- **Linting:** This package does **not** ship an ESLint config or `lint` script; do not assume ESLint fixes are available in CI. diff --git a/.talismanrc b/.talismanrc index f973e15..b8697c2 100644 --- a/.talismanrc +++ b/.talismanrc @@ -3,15 +3,17 @@ fileignoreconfig: ignore_detectors: - filecontent - filename: package-lock.json - checksum: d392a5bf70cad2cb90afaf284410f580e359afe4f1a0a970a6f6061aee7c821c - - filename: .cursor/rules/testing.mdc - checksum: a3768ed70d1fa61e73d1838efbc3066859dd5dfce3fbefe40fb6c23800679a43 - - filename: skills/README.md - checksum: ae09bf77a43f81f76a06f23ae2b2cbb1e81c490a66cf1b4e7df4e7142e22b5f5 + checksum: 6a45ae66e7c4c62a43e40cfec58ab3c8fff37f04b02339e8019dd1ac503da995 - filename: AGENTS.md - checksum: 6ff4b2c6957f75f85f6afd188cc09af21ac9c90f05f87e4198674302b74bb021 + checksum: 93ded6952359760204f6235b0a29de9e4f594323326971a5cae0ee07ee9a822e + - filename: skills/README.md + checksum: 33e44991db811244b3ea9abd4be5eaafada3c9e6a7f3f55542aaf1be480d19a2 + - filename: skills/dev-workflow/SKILL.md + checksum: f5b4a18948f0cec6c8a391d946670313fce7e998268677f9be12241c09e9558f - filename: skills/testing/SKILL.md - checksum: 858b4a830e74a0e90fe2f1097b4480a5eed513cdd88ba2646087399423ddee00 + checksum: 5acca5b3e5a6871237b9775f855e81f01b300d591c3b5d6677d79426021e5c7b - filename: skills/typescript-types-generator/SKILL.md - checksum: aaa97f6eb31a66221ceedc7e5e965a9b13d33358a350dbfb3034014ece0c3e6c + checksum: 141c31039cdec5f1b0ba689a979292103e84da6e4862e878ee2e1384e3ea6fcd + - filename: skills/code-review/SKILL.md + checksum: 1b65b3ed25618cfc453b167d1b149348c0900f4721da3b24c8d847b7b1885f61 version: "1.0" diff --git a/AGENTS.md b/AGENTS.md index 74b2d25..a850412 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,49 +1,50 @@ -# `@contentstack/types-generator` +# @contentstack/types-generator – Agent guide -**Purpose:** Library for generating TypeScript type definitions from Contentstack stack content types (via the Delivery SDK) and from GraphQL schema (introspection over the Contentstack GraphQL endpoint). +**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**. -- **Repository:** [github.com/contentstack/types-generator](https://github.com/contentstack/types-generator) -- **Homepage:** [https://github.com/contentstack/types-generator](https://github.com/contentstack/types-generator) +## What this repo is -## Tech stack - -| Area | Details | +| Field | Detail | | --- | --- | -| Language | TypeScript **5.9** (`strict` in [tsconfig.json](tsconfig.json)) | -| Runtime | Node (CI on **18.x** and **20.x**; release workflow uses **22.x**) | -| Build | **tsup** → `dist/` ([tsup.config.ts](tsup.config.ts)): entries `index` ([src/index.ts](src/index.ts)), `web` ([src/web.ts](src/web.ts)) | -| Tests | **Jest** + **ts-jest** ([jest.config.js](jest.config.js)); `dotenv/config` in setup | -| Main dependencies | `@contentstack/delivery-sdk`, `axios`, `@gql2ts/from-schema`, `lodash`, `async`, `prettier` | - -This package targets **Content Delivery (CDA)** and **GraphQL** only—not the Management API (CMA). +| **Name:** | [contentstack/types-generator](https://github.com/contentstack/types-generator) | +| **Purpose:** | Library that generates TypeScript types from Contentstack stack content types (Delivery SDK) and from GraphQL schema (introspection). | +| **Out of scope (if any):** | **Management API (CMA)** client behavior—this package targets **CDA** and **GraphQL** only. | -## Public API and source layout +## Tech stack (at a glance) -- **Package entry:** `main` / `module` / `types` point to `./dist/*` (see [package.json](package.json)). -- **Exports:** `generateTS`, `graphqlTS`, and related symbols from [src/index.ts](src/index.ts) (re-exports from [src/generateTS/](src/generateTS/) and [src/graphqlTS/](src/graphqlTS/)). -- **Key paths:** [src/sdk/](src/sdk/) (Delivery SDK wiring), [src/types/](src/types/), [src/format/](src/format/), [src/logger/](src/logger/), [src/constants/](src/constants/). +| Area | Details | +| --- | --- | +| **Language** | TypeScript **5.9** (`strict` in [tsconfig.json](tsconfig.json)) | +| **Build** | **tsup** → `dist/` ([tsup.config.ts](tsup.config.ts)); entries include [src/index.ts](src/index.ts), [src/web.ts](src/web.ts) | +| **Tests** | Jest + ts-jest ([jest.config.js](jest.config.js)); `dotenv/config` in setup | +| **Lint / coverage** | No ESLint script; rely on TypeScript strictness and project conventions | +| **Other** | `@contentstack/delivery-sdk`, `axios`, `@gql2ts/from-schema`, `lodash`, `async`, `prettier` | -## Common commands +## Commands (quick reference) -| Command | Purpose | +| Command type | Command | | --- | --- | -| `npm run build` | Run `tsup` (also runs on `npm run prepare`) | -| `npm test` | Jest with `--testPathPattern=tests` and `NODE_OPTIONS=--experimental-vm-modules` | -| `npm run test:unit:report:json` | Unit tests under `tests/unit` with coverage and JSON reports (used in CI) | +| **Build** | `npm run build` | +| **Test** | `npm test` | +| **Lint** | _(not configured)_ | -There is **no ESLint** script in this package; rely on TypeScript strictness and project conventions. +CI: [.github/workflows/node.js.yml](.github/workflows/node.js.yml); release: [.github/workflows/release.yml](.github/workflows/release.yml). ## Credentials and integration tests -Integration tests need a live stack. Set a **`.env`** at the repo root (see integration tests under `tests/integration/`) or export variables in your shell. Typical names: +Set a **`.env`** at the repo root or export variables (see `tests/integration/`). Typical names: `TOKEN`, `APIKEY`, `ENVIRONMENT`, `REGION`, `TOKENTYPE`, `BRANCH`. CI injects secrets including `TOKEN_WITH_NO_CT` and `APIKEY_WITH_NO_CT` where needed. -`TOKEN`, `APIKEY`, `ENVIRONMENT`, `REGION`, `TOKENTYPE`, `BRANCH` +## Where the documentation lives: skills -CI injects these from GitHub Actions secrets (see [.github/workflows/node.js.yml](.github/workflows/node.js.yml)), including `TOKEN_WITH_NO_CT` and `APIKEY_WITH_NO_CT` where tests require them. +| Skill | Path | What it covers | +| --- | --- | --- | +| Development workflow | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, CI, build/test, PRs, releases | +| TypeScript types generator | [skills/typescript-types-generator/SKILL.md](skills/typescript-types-generator/SKILL.md) | `generateTS` vs `graphqlTS`, SDK and GraphQL behavior | +| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | Jest layout, `.env`, fixtures | +| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist, terminology, semver | ---- +An index with “when to use” hints is in [skills/README.md](skills/README.md). -## AI guidance index +## Using Cursor (optional) -- [Cursor rules (overview)](.cursor/rules/README.md) — when each rule applies and how to reference it. -- [Skills index](skills/README.md) — deeper checklists and package mental model. +If you use **Cursor**, [.cursor/rules/README.md](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else. diff --git a/skills/README.md b/skills/README.md index 7480ed8..1741950 100644 --- a/skills/README.md +++ b/skills/README.md @@ -1,11 +1,16 @@ -# Skills for `@contentstack/types-generator` +# Skills – @contentstack/types-generator -Short index of deeper guidance (use alongside [AGENTS.md](../AGENTS.md) and [`.cursor/rules/`](../.cursor/rules/README.md)). +Source of truth for detailed guidance. Read [AGENTS.md](../AGENTS.md) first, then open the skill that matches your task. -| Skill | When to use | +## When to use which skill + +| Skill folder | Use when | | --- | --- | -| [code-review](code-review/SKILL.md) | Preparing or reviewing a PR: API docs, compatibility, errors, security, tests, Delivery vs Management terminology. | -| [testing](testing/SKILL.md) | Running Jest, unit vs integration layout, `.env` and CI secrets, content-type fixtures. | -| [typescript-types-generator](typescript-types-generator/SKILL.md) | Understanding `generateTS` vs `graphqlTS`, main modules, and where to change behavior. | +| [dev-workflow](dev-workflow/SKILL.md) | Branches, CI, build/test, PR and release | +| [typescript-types-generator](typescript-types-generator/SKILL.md) | `generateTS` / `graphqlTS`, Delivery SDK, GraphQL transport | +| [testing](testing/SKILL.md) | Jest, unit vs integration, `.env`, fixtures | +| [code-review](code-review/SKILL.md) | PR review: API surface, CDA/GraphQL terminology, semver | + +There is no separate **framework** skill: HTTP and Delivery/GraphQL details are covered in [typescript-types-generator](typescript-types-generator/SKILL.md). -There is no separate **framework** skill: HTTP/GraphQL details are covered in [contentstack-delivery-cda.mdc](../.cursor/rules/contentstack-delivery-cda.mdc) and the typescript skill. +Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`). diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 065ca66..ec49d16 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -5,8 +5,6 @@ description: PR review checklist for @contentstack/types-generator (API docs, co # Code review skill (`@contentstack/types-generator`) -Expanded checklist aligned with [`.cursor/rules/code-review.mdc`](../../.cursor/rules/code-review.mdc). - ## Documentation and API surface - Public exports from [`src/index.ts`](../../src/index.ts) should stay coherent and documented (JSDoc on exported functions where the package documents behavior). diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 0000000..83d3061 --- /dev/null +++ b/skills/dev-workflow/SKILL.md @@ -0,0 +1,36 @@ +--- +name: dev-workflow +description: Branches, build/test commands, PR and release workflow for @contentstack/types-generator. +--- + +# Development workflow – types-generator + +## When to use + +- Local build and test before a PR +- Understanding CI vs release branches + +## Branches and CI + +- **Node.js workflow** (`.github/workflows/node.js.yml`) runs on **push** and **pull_request** for **`master`** and **`development`**. +- **Release / publish** (`.github/workflows/release.yml`) runs on **push** to **`main`** (Node **22.x**), autotag, npm publish, GitHub release. + +CI and release default branches may differ (`master`/`development` vs `main`); follow team branch protection. + +## Local commands + +| Command | Purpose | +| --- | --- | +| `npm run build` | **tsup** (`prepare` also runs build) | +| `npm test` | Jest for `tests/` with `NODE_OPTIONS=--experimental-vm-modules` | +| `npm run test:unit:report:json` | Unit tests under `tests/unit` with coverage (CI) | + +## Pull requests + +- **`npm run build`** and **`npm test`** should pass. +- PRs from forks may lack CI secrets; integration jobs may fail only on secrets—coordinate with maintainers. + +## Releases + +- Version in **`package.json`** is the publish source of truth. +- Publishing is automated from **`main`** (tag prefix **`v`**, npm, GitHub release). diff --git a/skills/typescript-types-generator/SKILL.md b/skills/typescript-types-generator/SKILL.md index da9df6e..1725a8d 100644 --- a/skills/typescript-types-generator/SKILL.md +++ b/skills/typescript-types-generator/SKILL.md @@ -1,37 +1,47 @@ --- - -## name: typescript-types-generator -description: Mental model for @contentstack/types-generator — generateTS pipeline, graphqlTS, and where to change code. +name: typescript-types-generator +description: Mental model for @contentstack/types-generator — generateTS, graphqlTS, Delivery SDK, and where to change code. +--- # TypeScript types generator skill -Package: `**@contentstack/types-generator**`. Entry: `[src/index.ts](../../src/index.ts)` re-exports `**generateTS**` and `**graphqlTS**`. +Package **`@contentstack/types-generator`**. Entry [`src/index.ts`](../../src/index.ts) re-exports **`generateTS`** and **`graphqlTS`**. + +Scope: **SDK-facing library code** (no separate `samples/` tree). This package is **not** a CMA (Management) client. + +## Delivery (CDA) and SDK -## `generateTS` (Delivery / content types) +- **Token type:** Only **`TOKEN_TYPE.DELIVERY`** is defined ([`src/constants/index.ts`](../../src/constants/index.ts)). `generateTS` validates `tokenType` and uses the **Delivery SDK** for content types and global fields. +- **SDK entry:** [`initializeContentstackSdk`](../../src/sdk/utils.ts) wraps **`@contentstack/delivery-sdk`** (`Contentstack.stack` with `deliveryToken`, `environment`, `region` or `host`, optional `branch`). +- **Regions:** Map string constants in **`REGIONS`** to **`Region`** enum; **custom** regions require **`host`** (see `isCustomRegion` in [`src/sdk/utils.ts`](../../src/sdk/utils.ts)). +- **Errors:** Validation failures often use **`{ type: "validation", error_message: string }`** or helpers in [`generateTS/shared/utils.ts`](../../src/generateTS/shared/utils.ts). Preserve stable `type` / message shapes for callers. -1. **Validation** — Required params include `**token`**, `**tokenType**`, `**apiKey**`, `**environment**`, `**region**` (`[src/generateTS/index.ts](../../src/generateTS/index.ts)`). Only `**TOKEN_TYPE.DELIVERY**` is supported in constants. -2. **SDK** — `[initializeContentstackSdk](../../src/sdk/utils.ts)` builds a Delivery stack client; fetches content types and global fields. -3. **Generation** — `**tsgenFactory`** / `[factory.ts](../../src/generateTS/factory.ts)` drives type emission; **docgen** picks JSDoc vs null doc via `[docgen/](../../src/generateTS/docgen/)`; **builtins** in `[stack/builtins.ts](../../src/generateTS/stack/builtins.ts)`. -4. **Formatting** — `[src/format/index.ts](../../src/format/index.ts)` + **Prettier** produce the final string. -5. **Errors** — Shared helpers in `[generateTS/shared/utils.ts](../../src/generateTS/shared/utils.ts)`; validation uses `**createValidationError`** where applicable. +Prefer official **Content Delivery API** documentation—not Management API patterns—when unsure. -**Where to change:** New field types or schema handling → `**factory.ts`**, `**types/schema**`, docgen modules. Connection issues → `**sdk/utils.ts**`. +## `generateTS` (REST / content types) -## `graphqlTS` (GraphQL introspection) +1. **Validation** — Required params include token, `tokenType`, `apiKey`, `environment`, `region` ([`src/generateTS/index.ts`](../../src/generateTS/index.ts)). +2. **SDK** — [`initializeContentstackSdk`](../../src/sdk/utils.ts) fetches content types and global fields. +3. **Generation** — `tsgenFactory` / [`factory.ts`](../../src/generateTS/factory.ts); docgen under [`docgen/`](../../src/generateTS/docgen/); builtins in [`stack/builtins.ts`](../../src/generateTS/stack/builtins.ts). +4. **Formatting** — [`src/format/index.ts`](../../src/format/index.ts) + **Prettier**. +5. **Errors** — Helpers in [`generateTS/shared/utils.ts`](../../src/generateTS/shared/utils.ts). -1. **Validation** — Requires `**token`**, `**apiKey**`, `**environment**`, `**region**` (optional `**host**`, `**branch**`, `**namespace**`). -2. **HTTP** — `**axios`** POST to region GraphQL base URLs or custom `**host**` (`[src/graphqlTS/index.ts](../../src/graphqlTS/index.ts)`). -3. **Types** — Introspection query in `[queries.ts](../../src/graphqlTS/queries.ts)`; `**@gql2ts/from-schema`** builds interfaces. +**Where to change:** New field types or schema handling → `factory.ts`, schema/docgen modules. Connection issues → `sdk/utils.ts`. -**Where to change:** Endpoint or headers → `**graphqlTS/index.ts`**; introspection shape → **queries** + gql2ts usage. +## `graphqlTS` (GraphQL) + +1. **Validation** — Requires token, `apiKey`, `environment`, `region` (optional `host`, `branch`, `namespace`). +2. **HTTP** — **axios** POST to region GraphQL URLs or to `https://${host}/...` when `host` is set ([`src/graphqlTS/index.ts`](../../src/graphqlTS/index.ts)). +3. **Schema** — Introspection in [`queries.ts`](../../src/graphqlTS/queries.ts); **`@gql2ts/from-schema`** (`schemaToInterfaces`, `generateNamespace`). Align URL and headers (`access_token`, `branch`) with Contentstack GraphQL docs for the region. + +**Where to change:** Endpoint or headers → `graphqlTS/index.ts`; introspection shape → queries + gql2ts usage. ## Shared pieces -- **Constants / messages:** `[src/constants/](../../src/constants/)` -- **Logger:** `[src/logger/](../../src/logger/)` -- **Types:** `[src/types/](../../src/types/)` +- **Constants / messages:** [`src/constants/`](../../src/constants/) +- **Logger:** [`src/logger/`](../../src/logger/) +- **Types:** [`src/types/`](../../src/types/) ## Secondary entry -- `**src/web.ts`** re-exports from `**generateTS**` only (`[web` bundle in tsup](../../tsup.config.ts))—keep exports minimal and consistent with the main package story. - +- [`src/web.ts`](../../src/web.ts) re-exports from `generateTS` only (see [`tsup.config.ts`](../../tsup.config.ts)).