diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 0000000..f5c1f87 --- /dev/null +++ b/.cursor/rules/README.md @@ -0,0 +1,5 @@ +# Cursor (optional) + +**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/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..859da6e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,48 @@ +# Contentstack Utils (Dart) – Agent guide + +**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**. + +## What this repo is + +| Field | Detail | +|-------|--------| +| **Name:** | [contentstack-utils-dart](https://github.com/contentstack/contentstack-utils-dart) — pub package **`contentstack_utils`** | +| **Purpose:** | Dart utilities to render rich text and embedded entries from Contentstack **Delivery JSON** (classic RTE, Supercharged RTE, and GraphQL-shaped SRTE). Typically used with **`package:contentstack`**. | +| **Out of scope (if any):** | **No HTTP client** — no stack calls, API keys, delivery tokens, or retries. Network and auth belong in the [Contentstack Dart SDK](https://pub.dev/packages/contentstack). | + +## Tech stack (at a glance) + +| Area | Details | +|------|---------| +| **Language** | Dart — `environment.sdk` in `pubspec.yaml` (`>=2.12.0 <4.0.0`) | +| **Build** | Pub — `pubspec.yaml`, `pubspec.lock` | +| **Tests** | `package:test` — `dart test`; files `test/*_test.dart` | +| **Lint / coverage** | `analysis_options.yaml`; coverage under `coverage/` / `lcov.info` when generated | +| **Other** | Runtime deps: `path`, `html`, `logger`, `lint` (see `pubspec.yaml`) | + +## Commands (quick reference) + +| Command type | Command | +|--------------|---------| +| **Build** | `dart pub get` | +| **Test** | `dart test` | +| **Lint** | `dart analyze .` and `dart format .` | + +**CI:** branch policy — `.github/workflows/check-branch.yml`; SCA — `.github/workflows/sca-scan.yml`; publish on tags — `.github/workflows/publish.yml`. + +## Where the documentation lives: skills + +| Skill | Path | What it covers | +|-------|------|----------------| +| **Development workflow** | `skills/dev-workflow/SKILL.md` | Branches, CI, commands, PR expectations, optional TDD | +| **Contentstack Utils API** | `skills/contentstack-utils/SKILL.md` | `Utils`, `GQL`, `Option`, RTE/embedded JSON, errors, boundaries with `package:contentstack` | +| **Dart** | `skills/dart/SKILL.md` | Dart SDK, `lib/` layout, imports, analyzer, naming | +| **Testing** | `skills/testing/SKILL.md` | `package:test`, `test/mock/`, coverage, offline-only tests | +| **Code review** | `skills/code-review/SKILL.md` | PR checklist, Blocker / Major / Minor | +| **Framework / tooling** | `skills/framework/SKILL.md` | `pubspec`, lockfile, `analysis_options.yaml`, CI security, shared deps (`html`, `logger`) | + +An index with “when to use” hints is in `skills/README.md`. + +## Using Cursor (optional) + +If you use **Cursor**, `.cursor/rules/README.md` only points to **`AGENTS.md`** — same docs as everyone else. diff --git a/CHANGELOG.md b/CHANGELOG.md index 69f8631..e978e5f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,12 @@ -# Changelog +# CHANGELOG + +### **APR-09-2026** + +#### Documentation + +## 2.0.1 + +- Add deprecation notice and migration guidance to the Content Delivery API. See [DEPRECATION.md](DEPRECATION.md). ## 2.0.0 @@ -6,7 +14,8 @@ - Improved error messages and publish workflow - Test fixes and mock data for supercharged/GQL tests - Improved error messages -___________________ + +--- ## v1.1.0 @@ -15,14 +24,16 @@ Implemented SRTE functions: :tada: - Utils.jsonToHtml() - GQL.jsonToHtml() -___________________ +--- ## v1.0.0 :tada: Initial release :tada: -___________________ + +--- ## v0.1.0 :construction: contentstack-utils beta :construction: -___________________ + +--- diff --git a/DEPRECATION.md b/DEPRECATION.md new file mode 100644 index 0000000..a55d8b3 --- /dev/null +++ b/DEPRECATION.md @@ -0,0 +1,27 @@ +# Deprecation notice: Contentstack Dart Utils (pub.dev) + +This page is for **developers using the Contentstack Dart Utils** package published on **pub.dev** as [`contentstack_utils`](https://pub.dev/packages/contentstack_utils). + +## What this means for you + +**We are deprecating this package as the recommended path for new Dart and Flutter work.** If you are **starting a new project**, use our **[Content Delivery API (CDA)](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)** and implement rich text / JSON RTE handling in your app using current product documentation. + +**If you already ship an app** that depends on `contentstack_utils`, you can **keep using it**. Your integration continues to work. Plan migration when it fits your release schedule—you do not have to change immediately. + +The **[Contentstack Dart SDK](https://github.com/contentstack/contentstack-dart)** is deprecated on the same timeline; see that repository’s **DEPRECATION.md**. + +## What to use for new projects + +| | Link | +|---|------| +| **Content Delivery API** | [Content Delivery API documentation](https://www.contentstack.com/docs/developers/apis/content-delivery-api/) | + +## Why we are making this change + +We are focusing investment on **direct API usage** and **documented integration patterns** for Dart and Flutter. This repository will remain in **maintenance**: we may address critical or security issues where we can, but **we do not plan new features** in this package. + +## Support for this package going forward + +This repository will stay in **maintenance** as described above. Feature work and new capabilities should be built against the **Content Delivery API** and your application code. + +If you need help choosing a migration path or timing, contact **[Contentstack support](https://www.contentstack.com/)** or your account team. diff --git a/README.md b/README.md index 68fb010..c0e15ef 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,10 @@ -# A Contentstack-Utils library for Dart developers +# ![Contentstack](https://www.contentstack.com/docs/static/images/contentstack.png) + +## Important: Dart Utils and pub.dev + +**We are deprecating** the **Contentstack Utils** Dart package on pub.dev as the supported path for **new** development. **New Dart or Flutter projects should use the [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)** and your own handling for rich text / JSON RTE, following current documentation. + +**Already using this package?** You can keep shipping with your current dependencies and migrate when it makes sense for your app. More detail: **[DEPRECATION.md](DEPRECATION.md)**. ![Coverage](https://github.com/contentstack/contentstack-utils-dart/blob/master/coverage_badge.svg?sanitize=true) diff --git a/pubspec.yaml b/pubspec.yaml index b88c377..6639a8b 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,6 +1,6 @@ name: contentstack_utils description: Utils package for Contentstack-dart -version: 2.0.0 +version: 2.0.1 homepage: https://www.contentstack.com environment: @@ -17,4 +17,3 @@ dev_dependencies: lints: ^2.0.0 test: ^1.24.0 # test_coverage: ^0.4.1 - \ No newline at end of file diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..2157f46 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,16 @@ +# Skills – Contentstack Utils (Dart) + +Source of truth for detailed guidance. Read **`AGENTS.md`** first, then open the skill that matches your task. + +## When to use which skill + +| Skill folder | Use when | +|--------------|----------| +| `dev-workflow` | Branches, CI expectations, build/test/lint commands, PR process, optional TDD | +| `contentstack-utils` | Public API (`Utils`, `GQL`, `Option`), RTE/embedded JSON, `FormatException` / `ErrorMessages` | +| `dart` | Dart version constraints, `lib/` layout, imports, analyzer/format, package naming | +| `testing` | Writing tests, `test/mock/` fixtures, coverage, no live credentials | +| `code-review` | Reviewing or preparing a PR — API stability, security, tests | +| `framework` | `pubspec` / lockfile, `analysis_options.yaml`, CI scans (OSV), shared runtime libraries | + +Each folder contains **`SKILL.md`** with YAML frontmatter (`name`, `description`). diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 0000000..783d110 --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,46 @@ +--- +name: code-review +description: Use when reviewing PRs or before opening a PR — API design, backward compatibility, dependencies, security, tests +--- + +# Code review – Contentstack Utils (Dart) + +## When to use + +- Reviewing a teammate’s PR or self-review before submit. +- Verifying API stability, errors, semver, SCA, and test coverage. + +## Instructions + +### API design and stability + +- [ ] **Public API:** Changes to **`Utils`**, **`GQL`**, **`Option`**, or barrel exports are documented in **`README.md`** / **`CHANGELOG.md`** when user-facing. +- [ ] **Backward compatibility:** Breaking changes require explicit semver / changelog; **`GQL`** remains importable from **`package:contentstack_utils/src/GQL.dart`** for downstream SDKs. +- [ ] **Naming:** Matches existing methods (**`jsonToHTML`**, **`render`**, **`renderContent`**). + +### Error handling + +- [ ] Invalid JSON / embedded input throws **`FormatException`** with **`ErrorMessages`** (or documented behavior); no silent failures. +- [ ] Strings use **`ErrorMessages`** in **`lib/src/constants/ErrorMessages.dart`** where the library already centralizes them. + +### Dependencies and security + +- [ ] New or upgraded deps are justified; **`pubspec.lock`** updated intentionally. +- [ ] Consider **`.github/workflows/sca-scan.yml`** (OSV, **`dart pub outdated`**) on dependency PRs. + +### Testing + +- [ ] **`dart test`** passes; new behavior covered under **`test/`** with **`test/mock/`** where appropriate. +- [ ] No flaky or network-dependent tests. + +### Severity (optional) + +- **Blocker:** Breaking public API without approval, security regression, no tests for new code. +- **Major:** Inconsistent errors, missing changelog for user-visible change. +- **Minor:** Style, small doc nits. + +## References + +- **`skills/testing/SKILL.md`** — test expectations +- **`skills/contentstack-utils/SKILL.md`** — public API surface +- **`AGENTS.md`** — lint/test commands diff --git a/skills/contentstack-utils/SKILL.md b/skills/contentstack-utils/SKILL.md new file mode 100644 index 0000000..dbf6f43 --- /dev/null +++ b/skills/contentstack-utils/SKILL.md @@ -0,0 +1,42 @@ +--- +name: contentstack-utils +description: Use when implementing or changing Utils, GQL, Option, RTE/embedded JSON, and ErrorMessages — alignment with package:contentstack +--- + +# Contentstack Utils API – Contentstack Utils (Dart) + +## When to use + +- Adding or changing **`Utils`**, **`GQL`**, **`Option`**, **`Metadata`**, **`StyleType`**, or **`Automate`** behavior. +- Defining how **`FormatException`** and **`ErrorMessages`** apply to invalid JSON or embedded input. +- Ensuring imports remain stable for **`package:contentstack`** consumers. + +## Instructions + +### Entry points + +- **Barrel:** `package:contentstack_utils/contentstack_utils.dart` — **`Utils`**, exported **`Metadata`**, **`StyleType`**. +- **Option:** `package:contentstack_utils/src/model/Option.dart` — **`renderOption(Map, Metadata)`**, **`Option.entry(Map)`**. +- **GQL:** `package:contentstack_utils/src/GQL.dart` — **`GQL.jsonToHTML`**. Not re-exported from the barrel; import explicitly. + +### Boundaries + +- This package only transforms **fetched** entry JSON (`_embedded_items`, RTE HTML). **No HTTP** — stack credentials and delivery API calls belong in the [Contentstack Dart SDK](https://pub.dev/packages/contentstack). + +### Public behavior + +- **`Utils.render`**, **`Utils.renderContent`**, **`Utils.jsonToHTML`** — walk embedded items, resolve RTE paths, render via **`Option`**; invalid input throws **`FormatException`** with **`ErrorMessages`** text. +- **`GQL.jsonToHTML`** — GraphQL-shaped SRTE (`embedded_itemsConnection`, nested `json`). +- Centralize user-facing strings in **`lib/src/constants/ErrorMessages.dart`**. +- RTE parsing uses **`package:html`**; helpers may use **`package:logger`** — stay consistent with **`lib/src/helper/Automate.dart`**. + +### Versioning and docs + +- User-visible changes: update **`README.md`** and **`CHANGELOG.md`**; follow **`jsonToHTML`** naming in code (avoid README typos like `jsonToHtml`). + +## References + +- **`skills/dart/SKILL.md`** — layout and imports +- **`skills/testing/SKILL.md`** — tests for API changes +- [Contentstack documentation](https://www.contentstack.com/docs) +- [contentstack_utils on pub.dev](https://pub.dev/packages/contentstack_utils) diff --git a/skills/dart/SKILL.md b/skills/dart/SKILL.md new file mode 100644 index 0000000..72b3c77 --- /dev/null +++ b/skills/dart/SKILL.md @@ -0,0 +1,45 @@ +--- +name: dart +description: Use when editing Dart sources — SDK constraints, lib layout, imports, analyzer, formatting, dependencies +--- + +# Dart – Contentstack Utils (Dart) + +## When to use + +- Editing any **`*.dart`** file under **`lib/`** or **`test/`**. +- Changing **`pubspec.yaml`** dependency lists (coordinate with **`skills/framework/SKILL.md`** for lockfile and CI impact). +- Fixing or discussing **`analysis_options.yaml`** behavior. + +## Instructions + +### Language and SDK + +- Honor **`environment.sdk`** in **`pubspec.yaml`** (`>=2.12.0 <4.0.0`). Do not require a newer SDK in code without updating the constraint deliberately. + +### Analyzer and formatting + +- Lints are driven by **`analysis_options.yaml`** (includes `package:pedantic/analysis_options.yaml` today — ensure the resolved package exists or fix the include with the team). +- Run **`dart format .`** before PRs. + +### Package layout and naming + +- **Barrel:** **`lib/contentstack_utils.dart`** +- **Implementation:** **`lib/src/`** — `helper/`, `model/`, `embedded/`, `constants/` +- **Files:** `PascalCase.dart` under **`lib/src/`**; **`test/*_test.dart`** use snake_case. + +### Imports + +- Prefer **`package:contentstack_utils/...`** in library code. +- Tests may import the barrel plus **`package:contentstack_utils/src/...`** (e.g. **`Automate.dart`**) to exercise internals — follow existing tests. + +### Dependencies + +- **Runtime:** `path`, `html`, `logger`, `lint` — keep the package lean; no new packages without review. +- **Typing:** JSON is often **`Map`** / dynamic; improve safety incrementally and match patterns in **`lib/src/helper/Automate.dart`** and **`lib/src/model/Option.dart`**. + +## References + +- **`skills/contentstack-utils/SKILL.md`** — public API behavior +- **`skills/framework/SKILL.md`** — lockfile, CI, analyzer policy changes +- **`AGENTS.md`** — command quick reference diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 0000000..4491cc7 --- /dev/null +++ b/skills/dev-workflow/SKILL.md @@ -0,0 +1,53 @@ +--- +name: dev-workflow +description: Use when branching, running CI-related commands, opening PRs, or deciding on TDD for this package +--- + +# Development workflow – Contentstack Utils (Dart) + +## When to use + +- Choosing a base branch or understanding merge policy into **`master`**. +- Running build, test, analyze, or format before a PR. +- Publishing (maintainers) or interpreting GitHub Actions workflows. +- Deciding whether to write tests first (TDD). + +## Instructions + +### Branches + +- Use feature branches (e.g. `feat/...`, `fix/...`). +- **`.github/workflows/check-branch.yml`** blocks PRs into **`master`** unless the head branch is **`staging`**. Prefer PRs against **`staging`** per team policy. + +### Commands + +- **Dependencies:** `dart pub get` +- **Tests:** `dart test` +- **Analyze:** `dart analyze .` +- **Format:** `dart format .` + +Run **`dart analyze .`** and **`dart test`** before requesting review. There are **no** live-stack integration tests — only JSON fixtures under **`test/mock/`**. + +### Pull requests + +- Keep public API changes backward compatible or bump semver and update **`CHANGELOG.md`**. +- Dependency changes: consider **`.github/workflows/sca-scan.yml`** (OSV on **`pubspec.lock`**, **`dart pub outdated`**). + +### Security and compliance (CI) + +- **`.github/workflows/sca-scan.yml`** — dependency / OSV signals. +- **`.github/workflows/policy-scan.yml`** — **`SECURITY.md`** and **`LICENSE`** (public repos). + +### Publishing (maintainers) + +- **`.github/workflows/publish.yml`** — publish on tags matching `v*.*.*` via **`dart pub publish`** (after dry-run in workflow). + +### Optional TDD + +If the team uses TDD: RED–GREEN–REFACTOR; fixture shapes in **`test/mock/`** should mirror Delivery / GQL payloads. Details: **`skills/testing/SKILL.md`**. + +## References + +- **`skills/testing/SKILL.md`** — test layout and fixtures +- **`skills/code-review/SKILL.md`** — PR checklist +- **`AGENTS.md`** — commands quick reference diff --git a/skills/framework/SKILL.md b/skills/framework/SKILL.md new file mode 100644 index 0000000..8e170f8 --- /dev/null +++ b/skills/framework/SKILL.md @@ -0,0 +1,45 @@ +--- +name: framework +description: Use when touching pubspec/lockfile, analysis_options, CI security workflows, or shared runtime deps (html, logger, path) +--- + +# Framework and tooling – Contentstack Utils (Dart) + +## When to use + +- Bumping or adding dependencies in **`pubspec.yaml`** / **`pubspec.lock`**. +- Changing **`analysis_options.yaml`** or lint includes. +- Editing **`.github/workflows/sca-scan.yml`**, **`.github/workflows/publish.yml`**, or policy-related CI. +- Refactoring shared library usage (**`package:html`**, **`package:logger`**, **`package:path`**) across **`lib/`**. + +This package has **no** HTTP client, retries, or native modules — only Pub, analyzer, CI, and the runtime libraries listed in **`pubspec.yaml`**. + +## Instructions + +### Pub + +- **Install:** **`dart pub get`**. +- **Lockfile:** Commit **`pubspec.lock`** for reproducible builds and OSV scanning. +- Before merging dep changes: **`dart test`** and **`dart analyze .`**. + +### Analysis and lint + +- **`analysis_options.yaml`** must resolve included packages; align **`lint`** / **`lints`** with the team before large policy changes. +- **Runtime deps:** `path`, `html`, `logger`, `lint` — keep minimal. +- **Dev:** `test`, `lints`. + +### CI security + +- **`.github/workflows/sca-scan.yml`:** **`dart pub outdated`**, OSV on **`pubspec.lock`**. +- **`.github/workflows/policy-scan.yml`:** **`SECURITY.md`**, **`LICENSE`** (public repos). + +### Publishing + +- **`.github/workflows/publish.yml`:** tag pattern **`v*.*.*`**, **`dart pub publish`** after dry-run. + +## References + +- **`skills/dart/SKILL.md`** — everyday Dart conventions +- **`skills/code-review/SKILL.md`** — dependency / security review +- **`skills/contentstack-utils/SKILL.md`** — API behavior (orthogonal to version bumps) +- **`AGENTS.md`** — workflow file pointers diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 0000000..fd1af16 --- /dev/null +++ b/skills/testing/SKILL.md @@ -0,0 +1,41 @@ +--- +name: testing +description: Use when writing or refactoring tests — dart test, *_test.dart, test/mock fixtures, coverage, offline-only +--- + +# Testing – Contentstack Utils (Dart) + +## When to use + +- Adding or changing files under **`test/`**. +- Adding JSON fixtures or updating **`test/.test_coverage.dart`**. +- Generating or interpreting coverage output. + +## Instructions + +### Runner and layout + +- **Command:** **`dart test`** from the repo root. +- **Framework:** **`package:test`** (`dev_dependency` in **`pubspec.yaml`**). +- **Files:** **`test/*_test.dart`** (e.g. `utils_test.dart`, `gql_test.dart`, `option_test.dart`). + +### Fixtures and credentials + +- JSON lives under **`test/mock/`** (`embedded_items.json`, `graphqlmock/`, `supercharged/`, etc.). +- Load with **`dart:io`** **`File`** and **`dart:convert`** as existing tests do. +- **No API keys or network** — tests are offline and deterministic. + +### Coverage + +- Optional: **`dart test --coverage=coverage`**; artifacts may include **`coverage/`**, **`coverage/lcov.info`**, **`coverage_badge.svg`**. +- **`test/.test_coverage.dart`** aggregates suites for legacy **`test_coverage`** workflows — update imports when adding suites if still used. + +### What to assert + +- **`Utils`**, **`GQL`**, **`Option`**, **`Automate.isValidJson`**, and shapes that match Delivery / GQL payloads. + +## References + +- **`skills/contentstack-utils/SKILL.md`** — behavior under test +- **`skills/dev-workflow/SKILL.md`** — when to run tests in the workflow +- **`AGENTS.md`** — `dart test` quick reference