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

.cursor/rules/dev-workflow.md

@@ -5,7 +5,7 @@ Use this as the standard workflow when contributing to the Android CDA SDK.
 ## Branches
 
 - Use feature branches for changes (e.g. `feat/...`, `fix/...`).
-- Base work off the appropriate long-lived branch (e.g. `staging`, `development`) per team norms.
+- Base work off the appropriate long-lived branch (e.g. `development`) per team norms.
 
 ## Running tests
 

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

AGENTS.md

@@ -1,54 +1,43 @@
-# Contentstack Android CDA SDK – Agent Guide
+# Contentstack Android Delivery SDK – Agent guide
 
-This document is the main entry point for AI agents working in this repository.
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
 
-## Project
+## What this repo is
 
-- **Name:** Contentstack Android CDA SDK (contentstack-android)
-- **Purpose:** Android client for the Contentstack **Content Delivery API (CDA)**. It fetches content (entries, assets, content types, sync, etc.) from Contentstack for Android apps.
-- **Repo:** [contentstack-android](https://github.com/contentstack/contentstack-android)
+| Field | Detail |
+|--------|--------|
+| **Name:** | [contentstack-android](https://github.com/contentstack/contentstack-android) (`com.contentstack.sdk:android`) |
+| **Purpose:** | Android library for the Contentstack Content Delivery API (Kotlin/Java consumers via AAR). |
+| **Out of scope:** | Not the Java-only or iOS/Swift SDKs—those live in sibling repositories. |
 
-## Tech stack
+## Tech stack (at a glance)
 
-- **Languages:** Java (primary SDK source); Kotlin may appear in tests or future code. Target **Java 8** compatibility for the library (see `contentstack/build.gradle`).
-- **Build:** Gradle (Android Gradle Plugin), single module **`contentstack`** (AAR).
-- **Testing:** JUnit 4, Robolectric (unit tests on JVM), Mockito / PowerMock where used; **androidTest** with AndroidX Test / Espresso for instrumented tests; JaCoCo for coverage (`jacocoTestReport`).
-- **HTTP:** **Volley** (`CSHttpConnection`) for much of the CDA traffic; **Retrofit 2 + OkHttp + Gson** for paths such as taxonomy (`Stack`, `APIService`). OkHttp **MockWebServer** in unit tests.
+| Area | Details |
+|------|---------|
+| Language | Kotlin/Java; **compileSdk 34**; Java **17** compile options in `contentstack/build.gradle` |
+| Build | Gradle (root `build.gradle`, `settings.gradle`, module **`contentstack/`**) |
+| Tests | JUnit, Mockito, Robolectric, AndroidX Test—unit tests under `contentstack/src/test/` |
+| Lint / coverage | JaCoCo integrated with debug unit tests (`testCoverageEnabled` on debug) |
+| CI | `.github/workflows/check-branch.yml`, `publish-release.yml`, `sca-scan.yml`, `policy-scan.yml`, `codeql-analysis.yml` |
 
-## Main entry points
+## Commands (quick reference)
 
-- **`Contentstack`** – Factory: `Contentstack.stack(Context, apiKey, deliveryToken, environment)` (and overloads with `Config`) returns a **`Stack`**.
-- **`Stack`** – Main API: content types, entries, queries, assets, sync, etc.
-- **`Config`** – Optional configuration: host, version, region, branch, proxy, connection pool, endpoint.
-- **Paths:** `contentstack/src/main/java/com/contentstack/sdk/` (production), `contentstack/src/test/java/com/contentstack/sdk/` (unit tests), `contentstack/src/androidTest/java/` (instrumented tests).
+| Command type | Command |
+|--------------|---------|
+| Unit tests (typical) | `./gradlew :contentstack:testDebugUnitTest` (from repo root) |
+| Clean | `./gradlew clean` |
 
-## Commands
+## Where the documentation lives: skills
 
-Run from the **repository root** (requires Android SDK / `local.properties` for connected tests).
+| Skill | Path | What it covers |
+|-------|------|----------------|
+| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Gradle, variants, CI, publishing |
+| **Android CDA SDK** | [`skills/contentstack-android-cda/SKILL.md`](skills/contentstack-android-cda/SKILL.md) | Library API and module boundaries |
+| **Android project layout** | [`skills/android/SKILL.md`](skills/android/SKILL.md) | `contentstack/` module, manifest, BuildConfig |
+| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | Unit vs instrumented tests, Robolectric, JaCoCo |
+| **Build & platform** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | AGP, signing placeholders, `local.properties` |
+| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist |
 
-| Goal | Command |
-|------|---------|
-| **Build library (debug)** | `./gradlew :contentstack:assembleDebug` |
-| **Run all unit tests** | `./gradlew :contentstack:testDebugUnitTest` |
-| **Run instrumented / connected tests** | `./gradlew :contentstack:connectedDebugAndroidTest` (device or emulator required) |
-| **Unit + connected (full local test pass)** | `./gradlew :contentstack:testDebugUnitTest :contentstack:connectedDebugAndroidTest` |
-| **Coverage report (unit)** | `./gradlew :contentstack:jacocoTestReport` |
-
-Instrumented tests may need **`local.properties`** entries (e.g. `APIKey`, `deliveryToken`, `environment`, `host`) for stacks that hit a real CDA endpoint—see `contentstack/build.gradle` `buildConfigField` usage.
-
-## Rules and skills
-
-- **`.cursor/rules/`** – Cursor rules for this repo:
-  - **README.md** – Index of all rules (globs / always-on).
-  - **dev-workflow.md** – Branches, tests, PR expectations.
-  - **java.mdc** – Applies to `**/*.java` and `**/*.kt`: language style, `com.contentstack.sdk` layout, logging, null-safety.
-  - **contentstack-android-cda.mdc** – SDK core: CDA patterns, Stack/Config, host/version/region/branch, retry, callbacks, CDA alignment.
-  - **testing.mdc** – `contentstack/src/test/**` and `contentstack/src/androidTest/**`: naming, unit vs instrumented, JaCoCo.
-  - **code-review.mdc** – Always applied: PR/review checklist (aligned with Java CDA SDK).
-- **`skills/`** – Reusable skill docs:
-  - **contentstack-android-cda** – Implementing or changing CDA behavior (Stack/Config, entries, assets, sync, HTTP, callbacks).
-  - **testing** – Writing or refactoring tests.
-  - **code-review** – PR review / pre-PR checklist.
-  - **framework** – Config, HTTP layer (Volley + Retrofit/OkHttp), retry/timeouts.
-
-Refer to `.cursor/rules/README.md` and `skills/README.md` for details.
+## 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,5 +1,11 @@
 # CHANGELOG
 
+## Version 4.2.2
+
+### Date: 01-Jun-2026
+
+- Fix: resolved data fetch failure for non-US regions (AZURE_NA, EU, AU, AZURE_EU, GCP_NA, GCP_EU) when connected via VPN by ensuring Stack.URL is correctly synced with the region-specific CDN host after config initialisation.
+
 ## Version 4.2.1
 
 ### Date: 20-Apr-2026

contentstack/build.gradle

@@ -7,7 +7,7 @@ plugins {
 ext {
     PUBLISH_GROUP_ID = 'com.contentstack.sdk'
     PUBLISH_ARTIFACT_ID = 'android'
-    PUBLISH_VERSION = '4.2.1'
+    PUBLISH_VERSION = '4.2.2'
 }
 
 android {

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

@@ -98,6 +98,7 @@ protected void setConfig(Config config) {
             }
         }
         String endpoint = config.PROTOCOL + config.URL;
+        URL = config.URL;
         this.config.setEndpoint(endpoint);
         client(endpoint);
 

contentstack/src/test/java/com/contentstack/sdk/TestStack.java

@@ -13,7 +13,9 @@
 import org.robolectric.annotation.Config;
 
 import java.util.Date;
+import java.util.HashMap;
 import java.util.LinkedHashMap;
+import java.util.Map;
 
 import static org.junit.Assert.*;
 
@@ -360,7 +362,7 @@ public void testStackWithCustomConfig() throws Exception {
     @Test
     public void testStackWithDifferentRegions() throws Exception {
         com.contentstack.sdk.Config.ContentstackRegion[] regions = com.contentstack.sdk.Config.ContentstackRegion.values();
-        
+
         for (com.contentstack.sdk.Config.ContentstackRegion region : regions) {
             com.contentstack.sdk.Config config = new com.contentstack.sdk.Config();
             config.setRegion(region);
@@ -369,6 +371,36 @@ public void testStackWithDifferentRegions() throws Exception {
         }
     }
 
+    @Test
+    public void testAzureNaRegionSetsCorrectURL() throws Exception {
+        com.contentstack.sdk.Config config = new com.contentstack.sdk.Config();
+        config.setRegion(com.contentstack.sdk.Config.ContentstackRegion.AZURE_NA);
+        Stack regionalStack = Contentstack.stack(mockContext, "api_key", "token", "env", config);
+        assertEquals("azure-na-cdn.contentstack.com", regionalStack.URL);
+    }
+
+    @Test
+    public void testNonUsRegionsSetsCorrectStackURL() throws Exception {
+        Map<com.contentstack.sdk.Config.ContentstackRegion, String> expectedHosts = new HashMap<>();
+        expectedHosts.put(com.contentstack.sdk.Config.ContentstackRegion.EU,       "eu-cdn.contentstack.io");
+        expectedHosts.put(com.contentstack.sdk.Config.ContentstackRegion.AU,       "au-cdn.contentstack.com");
+        expectedHosts.put(com.contentstack.sdk.Config.ContentstackRegion.AZURE_NA, "azure-na-cdn.contentstack.com");
+        expectedHosts.put(com.contentstack.sdk.Config.ContentstackRegion.AZURE_EU, "azure-eu-cdn.contentstack.com");
+        expectedHosts.put(com.contentstack.sdk.Config.ContentstackRegion.GCP_NA,   "gcp-na-cdn.contentstack.com");
+        expectedHosts.put(com.contentstack.sdk.Config.ContentstackRegion.GCP_EU,   "gcp-eu-cdn.contentstack.com");
+
+        for (Map.Entry<com.contentstack.sdk.Config.ContentstackRegion, String> entry : expectedHosts.entrySet()) {
+            com.contentstack.sdk.Config config = new com.contentstack.sdk.Config();
+            config.setRegion(entry.getKey());
+            Stack regionalStack = Contentstack.stack(mockContext, "api_key", "token", "env", config);
+            assertEquals(
+                "Stack.URL mismatch for region " + entry.getKey(),
+                entry.getValue(),
+                regionalStack.URL
+            );
+        }
+    }
+
     @Test
     public void testContentTypeEntryCreation() {
         ContentType contentType = stack.contentType("products");

skills/android/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: android
+description: Use for Android module layout, Gradle config, and Kotlin/Java conventions in contentstack-android.
+---
+
+# Android project layout – contentstack-android
+
+## When to use
+
+- Editing `contentstack/build.gradle`, manifests, or source under `contentstack/src/`
+- Adjusting `minSdk`, multidex, or packaging excludes
+
+## Instructions
+
+### Source trees
+
+- Follow standard Android library layout: **`main`**, **`test`**, **`androidTest`** under `contentstack/src/`.
+
+### Configuration
+
+- **`local.properties`** supplies machine-specific paths and optional keys—do not commit secrets; use the same keys the Gradle file expects (`host`, `APIKey`, etc. in `buildTypes`).
+
+### Java/Kotlin
+
+- Compile options target **Java 17** in the module—match language features accordingly.