From 90713b5e93418dda4f49a8d3c4896e184aa10dec Mon Sep 17 00:00:00 2001 From: Pritesh Jain Date: Wed, 4 Nov 2026 08:30:43 +0530 Subject: [PATCH 1/3] docs: add CLAUDE.md (API contract, review rules, DoD) and CONTRIBUTING.md (MKT-22132) Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 16 ++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 CLAUDE.md create mode 100644 CONTRIBUTING.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..4349128 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,55 @@ +# app-sdk + +`@contentstack/app-sdk`: the public npm library every Marketplace app loads inside its UI-location iframe. It does the `init` handshake with the Contentstack host (`app-extension-component`) over post-robot and exposes the per-location API (custom field, sidebars, dashboard, app config, full page, field modifier, RTE plugins, `stack`, `api()`). + +## Developer Ecosystem workflow (read first) + +This repo belongs to a Developer Ecosystem pod (DevEx: MCP, CLI, SDK, Starters including the SAP connector; Marketplace; Mkt Apps; Developer Hub). +New features and changes go through the deveco workflow before any code is written here: + +1. Find the work's DSCDX idea and where it is in the flow. No idea yet: write one with the `brief` skill in `contentstack/product-wiki`. +2. The PRD, TRD, test cases, tickets and code come from your own routines (PM, Architect, QA agent, Dev), gate by gate. Do not plan, draft or build them in this session. No routine for a step yet: set it up with the `deveco-aisdlc-onboarding` skill in `contentstack/agent-skills`. +3. The order, gates and intake: https://github.com/contentstack/agent-skills/blob/main/skills/deveco-aisdlc-onboarding/references/run-protocol.md + +Bug fixes and support cases keep this repo's usual path. Not sure which applies? Ask before building. + +**Stack:** TypeScript 4 · webpack 5 (UMD bundle `dist/index.js`, typings `dist/src/**/*.d.ts`) · Jest 27 (jsdom) · post-robot 8 · npm · Node from `.nvmrc` when present +**Commands:** `npm ci` (its `prepare` script builds) · `npm run build` · `npm test` · `npm run test:coverage` · `npm run lint` · `npx tsc --noEmit -p .` +**Env:** the library reads no environment variables, so there is no env sample. + +## Public API contract (hard rules) +- This package is public and runs in every Marketplace app. No breaking change: exported names, types and method signatures, the `init` handshake, post-robot channel names and payload shapes stay as they are. +- Change runtime behaviour only for a confirmed bug fix, and say in the PR exactly what consumers will see differ. Every other PR says it changes nothing for consumers; prove it by building `main` and the branch and diffing `dist/src/**/*.d.ts`. +- Host-to-app listeners (`postRobot.on`) accept messages from `window.parent` only. +- Never log tokens, request headers or bodies; `console.error` gets the error, nothing else. +- A version bump, release or `npm publish` is the release process's job, never part of a feature or fix PR. + +## Layout +| Path | Purpose | +|------|---------| +| `src/index.ts` | `ContentstackAppSDK.init()` entry, post-robot config | +| `src/uiLocation.ts` | per-location object, host event routing (`extensionEvent`), `api()` | +| `src/*.ts`, `src/fieldModifierLocation/` | location classes (field, entry, sidebars, frame, modal, store, metadata) | +| `src/stack/` | `stack` queries (content types, entries, assets) | +| `src/RTE/`, `src/rtePlugin.ts` | JSON RTE plugin API | +| `src/types/` | exported types (public contract) | +| `__test__/` | Jest tests (post-robot mocked) | +| `docs/` | API reference and v2 migration guide | + +## Known traps +See the product-wiki pages under `developer-hub/gotchas/`: `app-sdk-event-registration-never-batches`, `set-installation-data-replaces-not-merges`, `app-sdk-dead-import-under-ts-nocheck`, `unit-test-workflow-triggers-on-master`. + +## Review rules (from the `main` ruleset) +The ruleset "Default branch protection rules for releases branch" covers `main`: +- Changes land by pull request only; no force push, no branch deletion. +- 1 approving review, including a code owner (`.github/CODEOWNERS`: `@contentstack/developer-ecosystem-pr-reviewers`; workflows, `.snyk`, `CODEOWNERS` and `.gitguardian.yaml` need `@contentstack/security-admin`). +- The last push needs approval from someone other than its pusher; new pushes dismiss stale approvals; all review threads must be resolved. +- Required checks: `GitGuardian Security Checks`, `security-sca`, `security-license`, `security-policy`, `security/snyk`, `code/snyk`, `license/snyk` (contentstack-developer-ecosystem). The unit-test workflow is not a required check: run `npm test` yourself and read its PR run. +- Merge, squash or rebase are all allowed. Release tags are protected by a separate ruleset. + +## Definition of Done +- `npm test` is green, with a test for every public method the change adds or changes, written from the docs, not from the code's output. +- `npm run build` and `npx tsc --noEmit -p .` pass; `npm run lint` adds no new warning. +- The PR states the consumer impact (none, or exactly what changes) with the `dist` typings diff. +- Docs updated: `docs/api-reference.md` for public API changes, and the Developer Hub pages in `contentstack/product-wiki`. +- No secrets in code, commits or logs. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1e3d11c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,16 @@ +# Contributing to the Contentstack App SDK + +Thanks for helping. This package is public and runs inside every Contentstack Marketplace app, so changes are held to a strict compatibility bar. + +## Reporting +- Bugs and feature requests: open a GitHub issue with the SDK version, the UI location, and steps to reproduce. +- Security issues: do not open an issue; follow [SECURITY.md](SECURITY.md). + +## Pull requests +1. Fork, branch from `main`, and run `npm ci`. +2. Keep the public API stable: no change to exported names, types or method signatures, and no runtime change unless it fixes a bug. Say in the PR what consumers will see differ, or that nothing changes. +3. Add or update tests in `__test__/`, then run `npm test`, `npm run build` and `npm run lint`. +4. Update `docs/api-reference.md` when the public API changes. +5. Open the pull request against `main`. A code owner reviews it, and the security checks must pass. + +By contributing you agree that your contribution is licensed under the [MIT License](LICENSE). From 2f2bf4142b8b498b0c69dbf1da35925fa7d5aa97 Mon Sep 17 00:00:00 2001 From: Pritesh Jain Date: Wed, 4 Nov 2026 08:40:15 +0530 Subject: [PATCH 2/3] docs: host-only listener rule applies after #193 merges (MKT-22132) Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4349128..968ec6a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,7 +20,7 @@ Bug fixes and support cases keep this repo's usual path. Not sure which applies? ## Public API contract (hard rules) - This package is public and runs in every Marketplace app. No breaking change: exported names, types and method signatures, the `init` handshake, post-robot channel names and payload shapes stay as they are. - Change runtime behaviour only for a confirmed bug fix, and say in the PR exactly what consumers will see differ. Every other PR says it changes nothing for consumers; prove it by building `main` and the branch and diffing `dist/src/**/*.d.ts`. -- Host-to-app listeners (`postRobot.on`) accept messages from `window.parent` only. +- Host-to-app listeners (`postRobot.on`) accept messages from `window.parent` only, after #193 (MKT-22128) merges; until then `main` still accepts any window, and new listeners must pass `{ window: window.parent }`. - Never log tokens, request headers or bodies; `console.error` gets the error, nothing else. - A version bump, release or `npm publish` is the release process's job, never part of a feature or fix PR. From 48ba87c6ff69e54da55b9f01c3b207b873a9d517 Mon Sep 17 00:00:00 2001 From: Pritesh Jain Date: Wed, 4 Nov 2026 09:45:43 +0530 Subject: [PATCH 3/3] docs: keep CLAUDE.md public-safe (MKT-22132) Drop the internal workflow block, internal wiki links and Jira keys; known traps stated inline; listener rule links PR #193. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 968ec6a..4e1ffcf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,17 +2,6 @@ `@contentstack/app-sdk`: the public npm library every Marketplace app loads inside its UI-location iframe. It does the `init` handshake with the Contentstack host (`app-extension-component`) over post-robot and exposes the per-location API (custom field, sidebars, dashboard, app config, full page, field modifier, RTE plugins, `stack`, `api()`). -## Developer Ecosystem workflow (read first) - -This repo belongs to a Developer Ecosystem pod (DevEx: MCP, CLI, SDK, Starters including the SAP connector; Marketplace; Mkt Apps; Developer Hub). -New features and changes go through the deveco workflow before any code is written here: - -1. Find the work's DSCDX idea and where it is in the flow. No idea yet: write one with the `brief` skill in `contentstack/product-wiki`. -2. The PRD, TRD, test cases, tickets and code come from your own routines (PM, Architect, QA agent, Dev), gate by gate. Do not plan, draft or build them in this session. No routine for a step yet: set it up with the `deveco-aisdlc-onboarding` skill in `contentstack/agent-skills`. -3. The order, gates and intake: https://github.com/contentstack/agent-skills/blob/main/skills/deveco-aisdlc-onboarding/references/run-protocol.md - -Bug fixes and support cases keep this repo's usual path. Not sure which applies? Ask before building. - **Stack:** TypeScript 4 · webpack 5 (UMD bundle `dist/index.js`, typings `dist/src/**/*.d.ts`) · Jest 27 (jsdom) · post-robot 8 · npm · Node from `.nvmrc` when present **Commands:** `npm ci` (its `prepare` script builds) · `npm run build` · `npm test` · `npm run test:coverage` · `npm run lint` · `npx tsc --noEmit -p .` **Env:** the library reads no environment variables, so there is no env sample. @@ -20,7 +9,7 @@ Bug fixes and support cases keep this repo's usual path. Not sure which applies? ## Public API contract (hard rules) - This package is public and runs in every Marketplace app. No breaking change: exported names, types and method signatures, the `init` handshake, post-robot channel names and payload shapes stay as they are. - Change runtime behaviour only for a confirmed bug fix, and say in the PR exactly what consumers will see differ. Every other PR says it changes nothing for consumers; prove it by building `main` and the branch and diffing `dist/src/**/*.d.ts`. -- Host-to-app listeners (`postRobot.on`) accept messages from `window.parent` only, after #193 (MKT-22128) merges; until then `main` still accepts any window, and new listeners must pass `{ window: window.parent }`. +- Host-to-app listeners (`postRobot.on`) accept messages from `window.parent` only, after https://github.com/contentstack/app-sdk/pull/193 merges; until then `main` still accepts any window, and new listeners must pass `{ window: window.parent }`. - Never log tokens, request headers or bodies; `console.error` gets the error, nothing else. - A version bump, release or `npm publish` is the release process's job, never part of a feature or fix PR. @@ -37,7 +26,9 @@ Bug fixes and support cases keep this repo's usual path. Not sure which applies? | `docs/` | API reference and v2 migration guide | ## Known traps -See the product-wiki pages under `developer-hub/gotchas/`: `app-sdk-event-registration-never-batches`, `set-installation-data-replaces-not-merges`, `app-sdk-dead-import-under-ts-nocheck`, `unit-test-workflow-triggers-on-master`. +- `EventRegistry` debounces, but each `on*` call builds its own registry, so every `eventRegistration` message carries one event. +- `setInstallationData` replaces the stored configuration; it never merges. Omit `serverConfiguration` unless a secret is being set or removed. +- `src/stack/api/base.ts` is under `@ts-nocheck` and imports `dispatchPostRobotRequest`, which does not exist; delete the import before editing that file. ## Review rules (from the `main` ruleset) The ruleset "Default branch protection rules for releases branch" covers `main`: @@ -51,5 +42,5 @@ The ruleset "Default branch protection rules for releases branch" covers `main`: - `npm test` is green, with a test for every public method the change adds or changes, written from the docs, not from the code's output. - `npm run build` and `npx tsc --noEmit -p .` pass; `npm run lint` adds no new warning. - The PR states the consumer impact (none, or exactly what changes) with the `dist` typings diff. -- Docs updated: `docs/api-reference.md` for public API changes, and the Developer Hub pages in `contentstack/product-wiki`. +- Docs updated: `docs/api-reference.md` for public API changes. - No secrets in code, commits or logs.