DX | 15-06-2026 | Release

.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.

.github/workflows/back-merge-pr.yml

@@ -0,0 +1,54 @@
+name: Back-merge master to development
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  open-back-merge-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Open back-merge PR if needed
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          BASE_BRANCH="development"
+          SOURCE_BRANCH="master"
+
+          git fetch origin "$BASE_BRANCH" "$SOURCE_BRANCH"
+
+          if ! git show-ref --verify --quiet "refs/remotes/origin/$BASE_BRANCH"; then
+            echo "Base branch '$BASE_BRANCH' does not exist on origin; skipping."
+            exit 0
+          fi
+
+          SOURCE_SHA=$(git rev-parse "origin/$SOURCE_BRANCH")
+          BASE_SHA=$(git rev-parse "origin/$BASE_BRANCH")
+
+          if [ "$SOURCE_SHA" = "$BASE_SHA" ]; then
+            echo "$SOURCE_BRANCH and $BASE_BRANCH are at the same commit; nothing to back-merge."
+            exit 0
+          fi
+
+          EXISTING=$(gh pr list --repo "${{ github.repository }}"             --base "$BASE_BRANCH"             --head "$SOURCE_BRANCH"             --state open             --json number             --jq 'length')
+
+          if [ "$EXISTING" -gt 0 ]; then
+            echo "An open PR from $SOURCE_BRANCH to $BASE_BRANCH already exists; skipping."
+            exit 0
+          fi
+
+          gh pr create --repo "${{ github.repository }}"             --base "$BASE_BRANCH"             --head "$SOURCE_BRANCH"             --title "chore: back-merge $SOURCE_BRANCH into $BASE_BRANCH"             --body "Automated back-merge after changes landed on \\`$SOURCE_BRANCH\\`. Review and merge to keep \\`$BASE_BRANCH\\` in sync."
+
+          echo "Created back-merge PR $SOURCE_BRANCH -> $BASE_BRANCH."

.github/workflows/check-version-bump.yml

@@ -0,0 +1,86 @@
+name: Check Version Bump
+
+on:
+  pull_request:
+
+jobs:
+  version-bump:
+    name: Version & Changelog bump
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Detect changed files and version bump
+        id: detect
+        run: |
+          if git rev-parse HEAD^2 >/dev/null 2>&1; then
+            FILES=$(git diff --name-only HEAD^1 HEAD^2)
+          else
+            FILES=$(git diff --name-only HEAD~1 HEAD)
+          fi
+          VERSION_FILES_CHANGED=false
+          echo "$FILES" | grep -qx 'package.json' && VERSION_FILES_CHANGED=true
+          echo "$FILES" | grep -qx 'CHANGELOG.md' && VERSION_FILES_CHANGED=true
+          echo "version_files_changed=$VERSION_FILES_CHANGED" >> $GITHUB_OUTPUT
+          # Only lib/, webpack/, dist/, package.json count as release-affecting; .github/ and test/ do not
+          CODE_CHANGED=false
+          echo "$FILES" | grep -qE '^lib/|^webpack/|^dist/' && CODE_CHANGED=true
+          echo "$FILES" | grep -qx 'package.json' && CODE_CHANGED=true
+          echo "code_changed=$CODE_CHANGED" >> $GITHUB_OUTPUT
+
+      - name: Skip when only test/docs/.github changed
+        if: steps.detect.outputs.code_changed != 'true'
+        run: |
+          echo "No release-affecting files changed (e.g. only test/docs/.github). Skipping version-bump check."
+          exit 0
+
+      - name: Fail when version bump was missed
+        if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed != 'true'
+        run: |
+          echo "::error::This PR has code changes but no version bump. Please bump the version in package.json and add an entry in CHANGELOG.md."
+          exit 1
+
+      - name: Setup Node
+        if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+
+      - name: Check version bump
+        if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_changed == 'true'
+        run: |
+          set -e
+          PKG_VERSION=$(node -p "require('./package.json').version.replace(/^v/, '')")
+          if [ -z "$PKG_VERSION" ]; then
+            echo "::error::Could not read version from package.json"
+            exit 1
+          fi
+          git fetch --tags --force 2>/dev/null || true
+          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || true)
+          if [ -z "$LATEST_TAG" ]; then
+            echo "No existing tags found. Skipping version-bump check (first release)."
+            exit 0
+          fi
+          LATEST_VERSION="${LATEST_TAG#v}"
+          LATEST_VERSION="${LATEST_VERSION%%-*}"
+          if [ "$(printf '%s\n' "$LATEST_VERSION" "$PKG_VERSION" | sort -V | tail -1)" != "$PKG_VERSION" ]; then
+            echo "::error::Version bump required: package.json version ($PKG_VERSION) is not greater than latest tag ($LATEST_TAG). Please bump the version in package.json."
+            exit 1
+          fi
+          if [ "$PKG_VERSION" = "$LATEST_VERSION" ]; then
+            echo "::error::Version bump required: package.json version ($PKG_VERSION) equals latest tag ($LATEST_TAG). Please bump the version in package.json."
+            exit 1
+          fi
+          CHANGELOG_VERSION=$(sed -nE 's/^## \[v?([0-9]+\.[0-9]+\.[0-9]+).*/\1/p' CHANGELOG.md | head -1)
+          if [ -z "$CHANGELOG_VERSION" ]; then
+            echo "::error::Could not find a version entry in CHANGELOG.md (expected line like '## [v1.0.0](...)')."
+            exit 1
+          fi
+          if [ "$CHANGELOG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::CHANGELOG version mismatch: CHANGELOG.md top version ($CHANGELOG_VERSION) does not match package.json version ($PKG_VERSION). Please add or update the CHANGELOG entry for $PKG_VERSION."
+            exit 1
+          fi
+          echo "Version bump check passed: package.json and CHANGELOG.md are at $PKG_VERSION (latest tag: $LATEST_TAG)."

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
 
     - name: Cache Composer packages
       id: composer-cache
-      uses: actions/cache@v2
+      uses: actions/cache@v4
       with:
         path: vendor
         key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}

.gitignore

@@ -2,4 +2,5 @@ build
 vendor
 phpcs.xml
 .phpunit.result.cache
-*/.DS_Store
+*/.DS_Store
+src/assets/regions.json

AGENTS.md

@@ -0,0 +1,48 @@
+# Contentstack Utils PHP – 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](https://packagist.org/packages/contentstack/utils) · [GitHub](https://github.com/contentstack/contentstack-utils-php) |
+| **Purpose:** | PHP library for rendering Contentstack Rich Text (RTE) content and GraphQL-shaped JSON to HTML, including embedded entries and custom render options. |
+| **Out of scope (if any):** | Not an HTTP client or full Contentstack Delivery SDK; it focuses on parsing/rendering utilities used alongside other Contentstack PHP packages. |
+
+## Tech stack (at a glance)
+
+| Area | Details |
+| --- | --- |
+| Language | PHP `>=7.2` (Composer); CI runs on PHP 8.3. `declare(strict_types=1);` in source files. |
+| Build | [Composer](https://getcomposer.org/) — `composer.json`, `composer.lock`. No compile step; autoload PSR-4 `Contentstack\Utils\` → `src/`. |
+| Tests | PHPUnit 9.x via `composer test` / `phpunit`; suite in `tests/`, config `phpunit.xml`. |
+| Lint / coverage | PHP_CodeSniffer (PSR-2 ruleset) — `composer check-style` / `composer fix-style`; config `phpcs.xml.dist`. Coverage/logging paths under `build/` when generated. |
+| Other | Dev dependency `marc-mabe/php-enum` for enums. |
+
+## Commands (quick reference)
+
+| Command type | Command |
+| --- | --- |
+| Install deps | `composer install` |
+| Test | `composer test` |
+| Lint | `composer check-style` |
+| Format (fix) | `composer fix-style` |
+
+**CI:** [`.github/workflows/ci.yml`](.github/workflows/ci.yml) — validates `composer.json` / lockfile, installs dependencies, runs `composer run-script test`. Other workflows: `sca-scan.yml`, `policy-scan.yml`, `issues-jira.yml`, `check-branch.yml`.
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+| --- | --- | --- |
+| Dev workflow | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI, Composer scripts, PR expectations |
+| Contentstack Utils API | [`skills/contentstack-utils/SKILL.md`](skills/contentstack-utils/SKILL.md) | Public API, namespaces, extension points (`Option`, `RenderableInterface`) |
+| PHP style & layout | [`skills/php-style/SKILL.md`](skills/php-style/SKILL.md) | PSR-2, PHPCS, file layout under `src/` |
+| Testing | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | PHPUnit layout, mocks, coverage output |
+| Code review | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist aligned with this repo |
+
+An index with “when to use” hints is in [`skills/README.md`](skills/README.md).
+
+## Using Cursor (optional)
+
+If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.

CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog
-## [1.2.1](https://github.com/contentstack/contentstack-utils-php/tree/v1.2.1) (2024-03-02)
-  - Support for the fragment tag in nested list 
+## [1.3.0](https://github.com/contentstack/contentstack-utils-php/tree/v1.3.0) (2026-06-15)
+  - Added `Endpoint::getContentstackEndpoint()` for dynamic region-aware URL resolution
+  - Added `Utils::getContentstackEndpoint()` proxy for backward-compatible access
+  - Bundled `regions.json` is now downloaded at `composer install` / `composer update` via `post-install-cmd`; the file is not committed to the repository
+  - Added runtime fallback in `Endpoint::loadRegions()` — downloads `regions.json` on first use when the file is absent (e.g. when the package is installed as a dependency)
+  - Added `composer refresh-regions` script to manually pull the latest regions from Contentstack
+  - Supports 7 regions (AWS NA/EU/AU, Azure NA/EU, GCP NA/EU) and 18 service endpoint keys
+
 ## [1.2.0](https://github.com/contentstack/contentstack-utils-php/tree/v1.2.0) (2023-06-27)
   - Support for the br tag and support for nested assets in the the image
 ## [1.1.0](https://github.com/contentstack/contentstack-utils-php/tree/v1.1.0) (2021-07-16)

LICENSE.md

@@ -1,7 +1,7 @@
 The MIT License (MIT)
 
 
-Copyright (c) 2016-2024 Contentstack
+Copyright (c) 2016-2026 Contentstack
 
 > Permission is hereby granted, free of charge, to any person obtaining a copy
 > of this software and associated documentation files (the "Software"), to deal