DX | 15-06-2026 | Release

.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/unit-testing.yml

@@ -4,7 +4,6 @@ on:
   pull_request:
     branches:
       - development
-      - staging
       - master
 
 jobs:

CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## v2.7.0
+
+### Jun 15, 2026
+- Enhancement: Endpoint integration
+
 ## v2.6.0
 
 ### Feb 23, 2026

pom.xml

@@ -5,7 +5,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.contentstack.sdk</groupId>
     <artifactId>java</artifactId>
-    <version>2.6.0</version>
+    <version>2.7.0</version>
     <packaging>jar</packaging>
     <name>contentstack-java</name>
     <description>Java SDK for Contentstack Content Delivery API</description>
@@ -462,6 +462,34 @@
                 <artifactId>maven-jxr-plugin</artifactId>
                 <version>2.3</version>
             </plugin>
+
+            <!--
+                Refresh the bundled regions.json from the Contentstack artifact registry.
+                Run whenever Contentstack adds new regions or service keys, then commit
+                the updated src/main/resources/assets/regions.json.
+
+                Usage:
+                    mvn exec:exec@refresh-regions
+            -->
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>exec-maven-plugin</artifactId>
+                <version>3.1.0</version>
+                <executions>
+                    <execution>
+                        <id>refresh-regions</id>
+                        <goals>
+                            <goal>exec</goal>
+                        </goals>
+                        <configuration>
+                            <executable>bash</executable>
+                            <arguments>
+                                <argument>${project.basedir}/scripts/download-regions.sh</argument>
+                            </arguments>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
         </plugins>
     </build>
 

scripts/download-regions.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Download the latest regions.json from the Contentstack artifacts registry and
+# write it to src/main/resources/assets/regions.json so it gets bundled into
+# the SDK jar on the next build.
+#
+# Usage:
+#   ./scripts/download-regions.sh
+#   mvn exec:exec@refresh-regions
+#
+# Run this whenever Contentstack announces new regions or service keys, then
+# commit the updated file:
+#   git add src/main/resources/assets/regions.json
+#   git commit -m "chore: refresh regions.json"
+
+set -euo pipefail
+
+REGIONS_URL="https://artifacts.contentstack.com/regions.json"
+DEST="$(dirname "$0")/../src/main/resources/assets/regions.json"
+DEST="$(cd "$(dirname "$DEST")" && pwd)/$(basename "$DEST")"
+
+echo "Downloading regions.json from ${REGIONS_URL} ..."
+
+if command -v curl &>/dev/null; then
+    curl --silent --show-error --fail --location \
+         --retry 3 --retry-delay 2 \
+         -o "${DEST}" "${REGIONS_URL}"
+elif command -v wget &>/dev/null; then
+    wget --quiet --tries=3 --waitretry=2 -O "${DEST}" "${REGIONS_URL}"
+else
+    echo "Error: neither curl nor wget found. Install one and retry." >&2
+    exit 1
+fi
+
+# Validate the downloaded file contains a "regions" array
+if ! python3 -c "import sys, json; d=json.load(open('${DEST}')); assert 'regions' in d and len(d['regions']) > 0" 2>/dev/null &&
+   ! python  -c "import sys, json; d=json.load(open('${DEST}')); assert 'regions' in d and len(d['regions']) > 0" 2>/dev/null; then
+    # Fallback validation without Python — just check the key exists
+    if ! grep -q '"regions"' "${DEST}"; then
+        echo "Error: downloaded file does not look like a valid regions.json" >&2
+        rm -f "${DEST}"
+        exit 1
+    fi
+fi
+
+REGION_COUNT=$(grep -o '"id"' "${DEST}" | wc -l | tr -d ' ')
+echo "contentstack-java: regions.json updated (${REGION_COUNT} regions) → ${DEST}"

skills/dev-workflow/SKILL.md

@@ -14,7 +14,7 @@ description: Use for Maven lifecycle, CI, JaCoCo, and branch expectations in con
 
 ### Branches
 
-- Integration branches include **`development`**, **`staging`**, and **`master`**—confirm target branch for your PR against team policy.
+- Integration/release flow is **`development` -> `master`** (direct release PRs; no `staging` branch in release flow).
 
 ### Commands
 

src/main/java/com/contentstack/sdk/Config.java

@@ -18,6 +18,7 @@ public class Config {
     protected String livePreviewContentType = null;
     protected String livePreviewEntryUid = null;
     protected String host = "cdn.contentstack.io";
+    protected boolean hostOverridden = false;
     protected String version = "v3";
     protected String scheme = "https://";
     protected String endpoint;
@@ -167,6 +168,7 @@ public String getHost() {
     public void setHost(String hostName) {
         if (hostName != null && !hostName.isEmpty()) {
             host = hostName;
+            hostOverridden = true;
         }
     }
 

src/main/java/com/contentstack/sdk/Contentstack.java

@@ -1,5 +1,6 @@
 package com.contentstack.sdk;
 
+import java.util.Map;
 import java.util.Objects;
 
 /**
@@ -98,6 +99,60 @@ private static void validateCredentials(String stackApiKey, String deliveryToken
         }
     }
 
+    /**
+     * Returns the Contentstack API URL for the given region and service.
+     *
+     * <p>Delegates to {@link Endpoint#getContentstackEndpoint(String, String)} — provided as a
+     * convenience so callers can reach endpoint resolution through the same top-level class they
+     * use to create stacks.
+     *
+     * @param region  region ID or alias (e.g. {@code "na"}, {@code "eu"}, {@code "azure-na"})
+     * @param service service key (e.g. {@code "contentDelivery"}, {@code "contentManagement"})
+     * @return full URL including {@code https://} scheme
+     * @throws IllegalArgumentException if the region or service is not recognised
+     */
+    public static String getContentstackEndpoint(String region, String service) {
+        return Endpoint.getContentstackEndpoint(region, service);
+    }
+
+    /**
+     * Returns the Contentstack API URL for the given region and service, optionally stripping
+     * the {@code https://} scheme.
+     *
+     * @param region      region ID or alias
+     * @param service     service key
+     * @param omitHttps   when {@code true}, returns the bare host without {@code https://}
+     * @return URL or bare host
+     * @throws IllegalArgumentException if the region or service is not recognised
+     */
+    public static String getContentstackEndpoint(String region, String service, boolean omitHttps) {
+        return Endpoint.getContentstackEndpoint(region, service, omitHttps);
+    }
+
+    /**
+     * Returns all service endpoints for the given region as an ordered map of service key to URL.
+     *
+     * @param region region ID or alias
+     * @return map of service key → full URL
+     * @throws IllegalArgumentException if the region is not recognised
+     */
+    public static Map<String, String> getContentstackEndpoints(String region) {
+        return Endpoint.getAllEndpoints(region);
+    }
+
+    /**
+     * Returns all service endpoints for the given region, optionally stripping the
+     * {@code https://} scheme from every URL.
+     *
+     * @param region    region ID or alias
+     * @param omitHttps when {@code true}, returns bare hosts without {@code https://}
+     * @return map of service key → URL or bare host
+     * @throws IllegalArgumentException if the region is not recognised
+     */
+    public static Map<String, String> getContentstackEndpoints(String region, boolean omitHttps) {
+        return Endpoint.getAllEndpoints(region, omitHttps);
+    }
+
     private static Stack initializeStack(String stackApiKey, String deliveryToken, String environment, Config config) {
         Stack stack = new Stack(stackApiKey.trim());
         stack.setHeader("api_key", stackApiKey);