From 0d7f8dfb1d8a3393b465f8c98f675978a3d51cbf Mon Sep 17 00:00:00 2001
From: raj pandey <raj.pandey@contentstack.com>
Date: Wed, 29 Apr 2026 16:13:44 +0530
Subject: [PATCH 1/5] chore: standardize ruby release flow with back-merge and
 strict version checks

---
 .github/workflows/back-merge-pr.yml      | 59 +++++++++++++++++
 .github/workflows/check-branch.yml       | 20 ------
 .github/workflows/check-version-bump.yml | 82 ++++++++++++++++++++++++
 .github/workflows/release-gem.yml        |  3 +
 skills/code-review/SKILL.md              |  2 +-
 skills/dev-workflow/SKILL.md             |  4 +-
 skills/framework/SKILL.md                |  2 +-
 7 files changed, 148 insertions(+), 24 deletions(-)
 create mode 100644 .github/workflows/back-merge-pr.yml
 delete mode 100644 .github/workflows/check-branch.yml
 create mode 100644 .github/workflows/check-version-bump.yml

diff --git a/.github/workflows/back-merge-pr.yml b/.github/workflows/back-merge-pr.yml
new file mode 100644
index 0000000..cec0f26
--- /dev/null
+++ b/.github/workflows/back-merge-pr.yml
@@ -0,0 +1,59 @@
+# Opens a PR from master → development after changes land on master (back-merge).
+#
+# Org/repo Settings → Actions → General → Workflow permissions: read and write
+# (so GITHUB_TOKEN can create pull requests). Or use a PAT in secret GH_TOKEN.
+
+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: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          git fetch origin development master
+
+          MASTER_SHA=$(git rev-parse origin/master)
+          DEV_SHA=$(git rev-parse origin/development)
+
+          if [ "$MASTER_SHA" = "$DEV_SHA" ]; then
+            echo "master and development are at the same commit; nothing to back-merge."
+            exit 0
+          fi
+
+          EXISTING=$(gh pr list --repo "${{ github.repository }}" \
+            --base development \
+            --head master \
+            --state open \
+            --json number \
+            --jq 'length')
+
+          if [ "$EXISTING" -gt 0 ]; then
+            echo "An open PR from master to development already exists; skipping."
+            exit 0
+          fi
+
+          gh pr create --repo "${{ github.repository }}" \
+            --base development \
+            --head master \
+            --title "chore: back-merge master into development" \
+            --body "Automated back-merge after changes landed on \`master\`. Review and merge to keep \`development\` in sync."
+
+          echo "Created back-merge PR master → development."
diff --git a/.github/workflows/check-branch.yml b/.github/workflows/check-branch.yml
deleted file mode 100644
index e79864e..0000000
--- a/.github/workflows/check-branch.yml
+++ /dev/null
@@ -1,20 +0,0 @@
-name: 'Check Branch'
-
-on:
-  pull_request:
-
-jobs:
-  check_branch:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Comment PR
-        if: github.base_ref == 'master' && github.head_ref != 'staging'
-        uses: thollander/actions-comment-pull-request@v2
-        with:
-          message: |
-            We regret to inform you that you are currently not able to merge your changes into the master branch due to restrictions applied by our SRE team. To proceed with merging your changes, we kindly request that you create a pull request from the next branch. Our team will then review the changes and work with you to ensure a successful merge into the master branch.
-      - name: Check branch
-        if: github.base_ref == 'master' && github.head_ref != 'staging'
-        run: |
-          echo "ERROR: We regret to inform you that you are currently not able to merge your changes into the master branch due to restrictions applied by our SRE team. To proceed with merging your changes, we kindly request that you create a pull request from the next branch. Our team will then review the changes and work with you to ensure a successful merge into the master branch."
-          exit 1
\ No newline at end of file
diff --git a/.github/workflows/check-version-bump.yml b/.github/workflows/check-version-bump.yml
new file mode 100644
index 0000000..fe068ae
--- /dev/null
+++ b/.github/workflows/check-version-bump.yml
@@ -0,0 +1,82 @@
+name: Check Version Bump
+
+on:
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  check-version-bump:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Validate version and changelog updates
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          VERSION_FILE="lib/contentstack_utils/version.rb"
+          CHANGELOG_FILE="CHANGELOG.md"
+          BASE_SHA="${{ github.event.pull_request.base.sha }}"
+          HEAD_SHA="${{ github.event.pull_request.head.sha }}"
+
+          mapfile -t CHANGED_FILES < <(git diff --name-only "$BASE_SHA" "$HEAD_SHA")
+          if [ "${#CHANGED_FILES[@]}" -eq 0 ]; then
+            echo "No changed files detected."
+            exit 0
+          fi
+
+          is_ignored_change() {
+            local f="$1"
+            [[ "$f" =~ ^docs/ ]] && return 0
+            [[ "$f" =~ ^\.github/ ]] && return 0
+            [[ "$f" =~ (^|/)tests?/ ]] && return 0
+            [[ "$f" =~ (^|/)spec/ ]] && return 0
+            [[ "$f" =~ \.md$ ]] && [[ ! "$f" =~ (^|/)CHANGELOG\.md$ ]] && return 0
+            return 1
+          }
+
+          has_release_impact=false
+          for file in "${CHANGED_FILES[@]}"; do
+            if ! is_ignored_change "$file"; then
+              has_release_impact=true
+              break
+            fi
+          done
+
+          if [ "$has_release_impact" = false ]; then
+            echo "Skipping docs/test-only PR."
+            exit 0
+          fi
+
+          changed_file() {
+            local target="$1"
+            for file in "${CHANGED_FILES[@]}"; do
+              if [ "$file" = "$target" ]; then
+                return 0
+              fi
+            done
+            return 1
+          }
+
+          changed_file "$VERSION_FILE" || { echo "Version bump required in $VERSION_FILE."; exit 1; }
+          changed_file "$CHANGELOG_FILE" || { echo "Matching changelog update required in $CHANGELOG_FILE."; exit 1; }
+
+          head_version=$(sed -nE 's/.*VERSION\s*=\s*["'"'"']([^"'"'"']+)["'"'"'].*/\1/p' "$VERSION_FILE" | sed -n '1p')
+          CHANGELOG_HEAD=$(sed -nE 's/^## v?([^[:space:]]+).*/\1/p' "$CHANGELOG_FILE" | head -1)
+
+          [ -n "$CHANGELOG_HEAD" ] || { echo "::error::Could not find a top changelog heading like '## vX.Y.Z' in $CHANGELOG_FILE."; exit 1; }
+          [ "$CHANGELOG_HEAD" = "$head_version" ] || { echo "::error::$CHANGELOG_FILE top version ($CHANGELOG_HEAD) does not match project version ($head_version)."; exit 1; }
+
+          base_version=$(git show "$BASE_SHA:$VERSION_FILE" | sed -nE 's/.*VERSION\s*=\s*["'"'"']([^"'"'"']+)["'"'"'].*/\1/p' | sed -n '1p')
+          latest_tag=$(git tag --list 'v*' --sort=-version:refname | sed -n '1p')
+          latest_version="${latest_tag#v}"
+          [ -n "$latest_version" ] || latest_version="0.0.0"
+
+          version_gt() {
+            python3 -c 'import sys;v=lambda s:[int(x) if x.isdigit() else 0 for x in (s.strip().lstrip("v").split("-",1)[0].split("+",1)[0].split(".")+["0","0","0"])[:3]];print("true" if v(sys.argv[1])>v(sys.argv[2]) else "false")' "$1" "$2"
+          }
+
+          [ "$(version_gt "$head_version" "$base_version")" = "true" ] || { echo "Version must be greater than base version ($base_version). Found $head_version."; exit 1; }
+          [ "$(version_gt "$head_version" "$latest_version")" = "true" ] || { echo "Version must be greater than latest tag version ($latest_version). Found $head_version."; exit 1; }
diff --git a/.github/workflows/release-gem.yml b/.github/workflows/release-gem.yml
index 46473cb..1e388ee 100644
--- a/.github/workflows/release-gem.yml
+++ b/.github/workflows/release-gem.yml
@@ -6,6 +6,7 @@ on:
 
 jobs:
   build:
+    if: ${{ startsWith(github.event.release.tag_name, 'v') && !github.event.release.draft }}
     name: Build + Publish
     runs-on: ubuntu-latest
     permissions:
@@ -14,6 +15,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
+      with:
+        ref: ${{ github.event.release.tag_name }}
     - name: Set up Ruby 2.7
       uses: ruby/setup-ruby@v1
       with:
diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md
index 2634370..b67a8b7 100644
--- a/skills/code-review/SKILL.md
+++ b/skills/code-review/SKILL.md
@@ -33,7 +33,7 @@ description: Use when reviewing or preparing a PR for this gem—behavior, tests
 
 ### Process
 
-- Respect **CODEOWNERS** and branch policy (**`master`** vs **`staging`**) described in [dev-workflow](../dev-workflow/SKILL.md)
+- Respect **CODEOWNERS** and branch policy (**feature/fix -> `development`**, release PRs **`development` -> `master`**) described in [dev-workflow](../dev-workflow/SKILL.md)
 
 ## References
 
diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md
index fdd7813..c8810f8 100644
--- a/skills/dev-workflow/SKILL.md
+++ b/skills/dev-workflow/SKILL.md
@@ -32,12 +32,12 @@ description: Use when setting up the dev environment, running build/test/docs, o
 
 ### Branches and PRs
 
-- `.github/workflows/check-branch.yml` blocks merging into **`master`** unless the head branch is **`staging`** (organizational policy). Prefer PRs that follow team conventions for `master` / `staging`.
+- Feature/fix PRs should target **`development`**. Release PRs are raised directly from **`development`** to **`master`**.
 - Use `CODEOWNERS` for required reviewers when applicable
 
 ### CI and automation (no RSpec workflow today)
 
-- **Release:** `.github/workflows/release-gem.yml` — on GitHub **release created**, builds and pushes to RubyGems (note: workflow pins Ruby 2.7 for publish; align with gemspec minimum when changing)
+- **Release:** `.github/workflows/release-gem.yml` — on GitHub **Release** created (`release: types: [created]`) for tag **`v*`** (draft releases skipped), checks out the tag, then builds and pushes to RubyGems (note: workflow pins Ruby 2.7 for publish; align with gemspec minimum when changing)
 - **Security / compliance:** CodeQL, policy scan, SCA scan — see `.github/workflows/`
 - **Issues:** Jira integration workflow in `.github/workflows/issues-jira.yml`
 
diff --git a/skills/framework/SKILL.md b/skills/framework/SKILL.md
index d102ad6..758effc 100644
--- a/skills/framework/SKILL.md
+++ b/skills/framework/SKILL.md
@@ -35,7 +35,7 @@ description: Use when changing the gemspec, Bundler setup, Ruby/runtime constrai
 ### Build and publish
 
 - Local artifact: `gem build contentstack_utils.gemspec`
-- Publishing is triggered by GitHub **release** per `release-gem.yml`
+- Publishing runs when a GitHub **Release** is created (`release: types: [created]`) for tag **`v*`** (draft releases skipped); see `release-gem.yml`.
 
 ## References
 

From 505d08765ee517a7e0cba35ef5f71df9a77434dd Mon Sep 17 00:00:00 2001
From: raj pandey <raj.pandey@contentstack.com>
Date: Thu, 30 Apr 2026 11:58:55 +0530
Subject: [PATCH 2/5] fix: check-version bump triggered for all the PR

---
 .github/workflows/check-version-bump.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/workflows/check-version-bump.yml b/.github/workflows/check-version-bump.yml
index fe068ae..3002390 100644
--- a/.github/workflows/check-version-bump.yml
+++ b/.github/workflows/check-version-bump.yml
@@ -2,7 +2,6 @@ name: Check Version Bump
 
 on:
   pull_request:
-    branches: [main, master]
 
 jobs:
   check-version-bump:

From 23bc113c4a2a2dd65f23ddfe763465316ab0a104 Mon Sep 17 00:00:00 2001
From: raj pandey <raj.pandey@contentstack.com>
Date: Thu, 30 Apr 2026 15:10:48 +0530
Subject: [PATCH 3/5] ci: gate version-bump on src paths; validate semver vs
 latest tag only

---
 .github/workflows/check-version-bump.yml | 23 +++++++++--------------
 1 file changed, 9 insertions(+), 14 deletions(-)

diff --git a/.github/workflows/check-version-bump.yml b/.github/workflows/check-version-bump.yml
index 3002390..676b3cf 100644
--- a/.github/workflows/check-version-bump.yml
+++ b/.github/workflows/check-version-bump.yml
@@ -1,3 +1,5 @@
+# Runs only when production code under lib/ changes. Version must be > latest v* tag (not vs base branch).
+
 name: Check Version Bump
 
 on:
@@ -26,26 +28,21 @@ jobs:
             exit 0
           fi
 
-          is_ignored_change() {
+          is_production_source_change() {
             local f="$1"
-            [[ "$f" =~ ^docs/ ]] && return 0
-            [[ "$f" =~ ^\.github/ ]] && return 0
-            [[ "$f" =~ (^|/)tests?/ ]] && return 0
-            [[ "$f" =~ (^|/)spec/ ]] && return 0
-            [[ "$f" =~ \.md$ ]] && [[ ! "$f" =~ (^|/)CHANGELOG\.md$ ]] && return 0
-            return 1
+            [[ "$f" == lib/* ]]
           }
 
-          has_release_impact=false
+          has_source_changes=false
           for file in "${CHANGED_FILES[@]}"; do
-            if ! is_ignored_change "$file"; then
-              has_release_impact=true
+            if is_production_source_change "$file"; then
+              has_source_changes=true
               break
             fi
           done
 
-          if [ "$has_release_impact" = false ]; then
-            echo "Skipping docs/test-only PR."
+          if [ "$has_source_changes" = false ]; then
+            echo "Skipping: no lib/ production code changes."
             exit 0
           fi
 
@@ -68,7 +65,6 @@ jobs:
           [ -n "$CHANGELOG_HEAD" ] || { echo "::error::Could not find a top changelog heading like '## vX.Y.Z' in $CHANGELOG_FILE."; exit 1; }
           [ "$CHANGELOG_HEAD" = "$head_version" ] || { echo "::error::$CHANGELOG_FILE top version ($CHANGELOG_HEAD) does not match project version ($head_version)."; exit 1; }
 
-          base_version=$(git show "$BASE_SHA:$VERSION_FILE" | sed -nE 's/.*VERSION\s*=\s*["'"'"']([^"'"'"']+)["'"'"'].*/\1/p' | sed -n '1p')
           latest_tag=$(git tag --list 'v*' --sort=-version:refname | sed -n '1p')
           latest_version="${latest_tag#v}"
           [ -n "$latest_version" ] || latest_version="0.0.0"
@@ -77,5 +73,4 @@ jobs:
             python3 -c 'import sys;v=lambda s:[int(x) if x.isdigit() else 0 for x in (s.strip().lstrip("v").split("-",1)[0].split("+",1)[0].split(".")+["0","0","0"])[:3]];print("true" if v(sys.argv[1])>v(sys.argv[2]) else "false")' "$1" "$2"
           }
 
-          [ "$(version_gt "$head_version" "$base_version")" = "true" ] || { echo "Version must be greater than base version ($base_version). Found $head_version."; exit 1; }
           [ "$(version_gt "$head_version" "$latest_version")" = "true" ] || { echo "Version must be greater than latest tag version ($latest_version). Found $head_version."; exit 1; }

From a8890af1b6f47550766e155653c8a2ec9ac1225d Mon Sep 17 00:00:00 2001
From: sunil-lakshman <104969541+sunil-lakshman@users.noreply.github.com>
Date: Mon, 8 Jun 2026 15:09:03 +0530
Subject: [PATCH 4/5] Added url endpoint support  in ruby utils SDK.

---
 .gitignore                         |   4 +-
 .ruby-version                      |   2 +-
 Gemfile.lock                       |  20 +--
 lib/contentstack_utils/endpoint.rb |  96 +++++++++++
 lib/contentstack_utils/utils.rb    |   5 +
 spec/lib/endpoint_spec.rb          | 268 +++++++++++++++++++++++++++++
 6 files changed, 383 insertions(+), 12 deletions(-)
 create mode 100644 lib/contentstack_utils/endpoint.rb
 create mode 100644 spec/lib/endpoint_spec.rb

diff --git a/.gitignore b/.gitignore
index 0df012b..dfb3f6a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,4 +8,6 @@ coverage
 .DS_Store
 .bundle/
 **/rspec_results.html
-.dccache
\ No newline at end of file
+.dccache
+vendor/
+lib/contentstack_utils/assets/regions.json
\ No newline at end of file
diff --git a/.ruby-version b/.ruby-version
index 0aec50e..b9b3b0d 100644
--- a/.ruby-version
+++ b/.ruby-version
@@ -1 +1 @@
-3.1.4
+3.3.11
diff --git a/Gemfile.lock b/Gemfile.lock
index 934e413..cee5d4c 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -24,7 +24,7 @@ GEM
       public_suffix (>= 2.0.2, < 8.0)
     base64 (0.3.0)
     benchmark (0.5.0)
-    bigdecimal (4.1.1)
+    bigdecimal (4.1.2)
     concurrent-ruby (1.3.6)
     connection_pool (3.0.2)
     crack (1.0.1)
@@ -38,21 +38,21 @@ GEM
       concurrent-ruby (~> 1.0)
     logger (1.7.0)
     minitest (5.27.0)
-    nokogiri (1.19.2-aarch64-linux-gnu)
+    nokogiri (1.19.3-aarch64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.19.2-aarch64-linux-musl)
+    nokogiri (1.19.3-aarch64-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.19.2-arm-linux-gnu)
+    nokogiri (1.19.3-arm-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.19.2-arm-linux-musl)
+    nokogiri (1.19.3-arm-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.19.2-arm64-darwin)
+    nokogiri (1.19.3-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.19.2-x86_64-darwin)
+    nokogiri (1.19.3-x86_64-darwin)
       racc (~> 1.4)
-    nokogiri (1.19.2-x86_64-linux-gnu)
+    nokogiri (1.19.3-x86_64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.19.2-x86_64-linux-musl)
+    nokogiri (1.19.3-x86_64-linux-musl)
       racc (~> 1.4)
     public_suffix (7.0.5)
     racc (1.8.1)
@@ -84,7 +84,7 @@ GEM
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
-    yard (0.9.42)
+    yard (0.9.44)
 
 PLATFORMS
   aarch64-linux-gnu
diff --git a/lib/contentstack_utils/endpoint.rb b/lib/contentstack_utils/endpoint.rb
new file mode 100644
index 0000000..822020c
--- /dev/null
+++ b/lib/contentstack_utils/endpoint.rb
@@ -0,0 +1,96 @@
+require 'json'
+require 'net/http'
+require 'uri'
+
+module ContentstackUtils
+  module Endpoint
+    REGIONS_URL = 'https://artifacts.contentstack.com/regions.json'
+    REGIONS_FILE = File.expand_path('../assets/regions.json', __FILE__)
+
+    @regions_data = nil
+
+    class << self
+      def get_contentstack_endpoint(region: 'us', service: '', omit_https: false)
+        raise ArgumentError, 'Empty region provided' if region.nil? || region.to_s.strip.empty?
+
+        normalized = region.to_s.strip.downcase
+        regions = load_regions
+
+        region_row = find_region_by_id_or_alias(regions, normalized)
+        raise ArgumentError, "Invalid region: #{region}" if region_row.nil?
+
+        endpoints = region_row['endpoints']
+
+        if service.nil? || service.to_s.strip.empty?
+          return omit_https ? strip_https_from_map(endpoints) : endpoints.dup
+        end
+
+        url = endpoints[service.to_s]
+        raise ArgumentError, "Service \"#{service}\" not found for region \"#{region}\"" if url.nil?
+
+        omit_https ? strip_https(url) : url
+      end
+
+      def refresh_regions
+        download_and_save(REGIONS_FILE)
+        @regions_data = nil
+        load_regions
+        true
+      end
+
+      def reset_cache
+        @regions_data = nil
+      end
+
+      private
+
+      def load_regions
+        return @regions_data if @regions_data
+
+        unless File.exist?(REGIONS_FILE)
+          download_and_save(REGIONS_FILE)
+        end
+
+        raw = File.read(REGIONS_FILE)
+        parsed = JSON.parse(raw)
+        raise RuntimeError, 'Invalid regions data: missing "regions" key' unless parsed.is_a?(Hash) && parsed['regions']
+
+        @regions_data = parsed['regions']
+      rescue JSON::ParserError => e
+        raise RuntimeError, "Failed to parse regions data: #{e.message}"
+      rescue Errno::ENOENT => e
+        raise RuntimeError, "Failed to read regions file: #{e.message}"
+      end
+
+      def download_and_save(dest)
+        uri = URI.parse(REGIONS_URL)
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', open_timeout: 30, read_timeout: 30) do |http|
+          http.get(uri.request_uri)
+        end
+
+        raise RuntimeError, "Failed to download regions: HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+        parsed = JSON.parse(response.body)
+        raise RuntimeError, 'Downloaded regions data is invalid' unless parsed.is_a?(Hash) && parsed['regions']
+
+        FileUtils.mkdir_p(File.dirname(dest))
+        File.write(dest, JSON.pretty_generate(parsed))
+      rescue StandardError => e
+        raise RuntimeError, "Failed to fetch region metadata: #{e.message}"
+      end
+
+      def find_region_by_id_or_alias(regions, input)
+        regions.find { |r| r['id'] == input } ||
+          regions.find { |r| r['alias']&.any? { |a| a.downcase == input } }
+      end
+
+      def strip_https(url)
+        url.sub(%r{\Ahttps?://}, '')
+      end
+
+      def strip_https_from_map(endpoints)
+        endpoints.transform_values { |url| strip_https(url) }
+      end
+    end
+  end
+end
diff --git a/lib/contentstack_utils/utils.rb b/lib/contentstack_utils/utils.rb
index 7eec6ba..a2d7594 100644
--- a/lib/contentstack_utils/utils.rb
+++ b/lib/contentstack_utils/utils.rb
@@ -1,6 +1,7 @@
 require_relative './model/options.rb'
 require_relative './model/metadata.rb'
 require_relative './support/helper.rb'
+require_relative './endpoint.rb'
 require 'nokogiri'
 
 module ContentstackUtils
@@ -136,6 +137,10 @@ def self.json_doc_to_html(node, options, callback)
         return nil
     end
 
+    def self.get_contentstack_endpoint(region: 'us', service: '', omit_https: false)
+        Endpoint.get_contentstack_endpoint(region: region, service: service, omit_https: omit_https)
+    end
+
     module GQL
         include ContentstackUtils
         def self.json_to_html(content, options)
diff --git a/spec/lib/endpoint_spec.rb b/spec/lib/endpoint_spec.rb
new file mode 100644
index 0000000..c1b5bca
--- /dev/null
+++ b/spec/lib/endpoint_spec.rb
@@ -0,0 +1,268 @@
+require 'spec_helper'
+
+RSpec.describe ContentstackUtils::Endpoint do
+  before(:each) do
+    described_class.reset_cache
+  end
+
+  # ── Default region ──────────────────────────────────────────────────────────
+
+  describe '.get_contentstack_endpoint with defaults' do
+    it 'returns a hash when no service is given' do
+      result = described_class.get_contentstack_endpoint
+      expect(result).to be_a(Hash)
+    end
+
+    it 'default region includes contentDelivery and contentManagement' do
+      result = described_class.get_contentstack_endpoint
+      expect(result).to have_key('contentDelivery')
+      expect(result).to have_key('contentManagement')
+    end
+
+    it 'default region contentDelivery is NA CDN' do
+      result = described_class.get_contentstack_endpoint
+      expect(result['contentDelivery']).to eq('https://cdn.contentstack.io')
+    end
+  end
+
+  # ── NA aliases ──────────────────────────────────────────────────────────────
+
+  describe 'NA region aliases' do
+    %w[na us aws-na aws_na NA US AWS-NA AWS_NA].each do |alias_val|
+      it "alias \"#{alias_val}\" resolves contentDelivery to NA CDN" do
+        result = described_class.get_contentstack_endpoint(region: alias_val, service: 'contentDelivery')
+        expect(result).to eq('https://cdn.contentstack.io')
+      end
+    end
+  end
+
+  # ── All 7 regions – contentDelivery ─────────────────────────────────────────
+
+  describe 'contentDelivery endpoints per region' do
+    {
+      'na'       => 'https://cdn.contentstack.io',
+      'eu'       => 'https://eu-cdn.contentstack.com',
+      'au'       => 'https://au-cdn.contentstack.com',
+      'azure-na' => 'https://azure-na-cdn.contentstack.com',
+      'azure-eu' => 'https://azure-eu-cdn.contentstack.com',
+      'gcp-na'   => 'https://gcp-na-cdn.contentstack.com',
+      'gcp-eu'   => 'https://gcp-eu-cdn.contentstack.com'
+    }.each do |region, expected_url|
+      it "region \"#{region}\" resolves contentDelivery to #{expected_url}" do
+        result = described_class.get_contentstack_endpoint(region: region, service: 'contentDelivery')
+        expect(result).to eq(expected_url)
+      end
+    end
+  end
+
+  # ── All 7 regions – contentManagement ───────────────────────────────────────
+
+  describe 'contentManagement endpoints per region' do
+    {
+      'na'       => 'https://api.contentstack.io',
+      'eu'       => 'https://eu-api.contentstack.com',
+      'au'       => 'https://au-api.contentstack.com',
+      'azure-na' => 'https://azure-na-api.contentstack.com',
+      'azure-eu' => 'https://azure-eu-api.contentstack.com',
+      'gcp-na'   => 'https://gcp-na-api.contentstack.com',
+      'gcp-eu'   => 'https://gcp-eu-api.contentstack.com'
+    }.each do |region, expected_url|
+      it "region \"#{region}\" resolves contentManagement to #{expected_url}" do
+        result = described_class.get_contentstack_endpoint(region: region, service: 'contentManagement')
+        expect(result).to eq(expected_url)
+      end
+    end
+  end
+
+  # ── Service keys present ─────────────────────────────────────────────────────
+
+  describe 'all service keys present' do
+    let(:expected_services) do
+      %w[
+        application contentDelivery contentManagement auth
+        graphqlDelivery preview graphqlPreview images assets
+        automate launch developerHub brandKit genAI
+        personalizeManagement personalizeEdge composableStudio
+      ]
+    end
+
+    it 'EU region returns all expected service keys' do
+      result = described_class.get_contentstack_endpoint(region: 'eu')
+      expected_services.each do |svc|
+        expect(result).to have_key(svc), "expected key #{svc} to be present"
+      end
+    end
+
+    it 'NA region additionally includes assetManagement' do
+      result = described_class.get_contentstack_endpoint(region: 'na')
+      expect(result).to have_key('assetManagement')
+    end
+  end
+
+  # ── omit_https flag ──────────────────────────────────────────────────────────
+
+  describe 'omit_https option' do
+    it 'strips https:// from a single service URL' do
+      result = described_class.get_contentstack_endpoint(region: 'na', service: 'contentDelivery', omit_https: true)
+      expect(result).to eq('cdn.contentstack.io')
+    end
+
+    it 'strips https:// from all endpoints when no service given' do
+      result = described_class.get_contentstack_endpoint(region: 'na', omit_https: true)
+      result.each_value do |url|
+        expect(url).not_to start_with('https://')
+        expect(url).not_to start_with('http://')
+      end
+    end
+
+    it 'retains https:// when omit_https is false (default)' do
+      result = described_class.get_contentstack_endpoint(region: 'na', service: 'contentDelivery', omit_https: false)
+      expect(result).to start_with('https://')
+    end
+
+    it 'strips https:// from EU contentManagement' do
+      result = described_class.get_contentstack_endpoint(region: 'eu', service: 'contentManagement', omit_https: true)
+      expect(result).to eq('eu-api.contentstack.com')
+    end
+  end
+
+  # ── Case-insensitive aliases ─────────────────────────────────────────────────
+
+  describe 'case-insensitive alias resolution' do
+    it 'resolves uppercase AWS-NA alias' do
+      result = described_class.get_contentstack_endpoint(region: 'AWS-NA', service: 'contentDelivery')
+      expect(result).to eq('https://azure-na-cdn.contentstack.com').or eq('https://cdn.contentstack.io')
+    end
+
+    it 'resolves azure_na alias' do
+      result = described_class.get_contentstack_endpoint(region: 'azure_na', service: 'contentDelivery')
+      expect(result).to eq('https://azure-na-cdn.contentstack.com')
+    end
+
+    it 'resolves gcp_eu alias' do
+      result = described_class.get_contentstack_endpoint(region: 'gcp_eu', service: 'contentDelivery')
+      expect(result).to eq('https://gcp-eu-cdn.contentstack.com')
+    end
+
+    it 'resolves AZURE-EU alias' do
+      result = described_class.get_contentstack_endpoint(region: 'AZURE-EU', service: 'contentDelivery')
+      expect(result).to eq('https://azure-eu-cdn.contentstack.com')
+    end
+
+    it 'resolves GCP-NA alias' do
+      result = described_class.get_contentstack_endpoint(region: 'GCP-NA', service: 'contentDelivery')
+      expect(result).to eq('https://gcp-na-cdn.contentstack.com')
+    end
+  end
+
+  # ── No-service returns full endpoints hash ───────────────────────────────────
+
+  describe 'full endpoints map returned when no service specified' do
+    it 'AU returns a hash with more than 1 entry' do
+      result = described_class.get_contentstack_endpoint(region: 'au')
+      expect(result).to be_a(Hash)
+      expect(result.size).to be > 1
+    end
+
+    it 'AU contentDelivery is correct in the map' do
+      result = described_class.get_contentstack_endpoint(region: 'au')
+      expect(result['contentDelivery']).to eq('https://au-cdn.contentstack.com')
+    end
+
+    it 'returns a copy — mutations do not affect cached data' do
+      result = described_class.get_contentstack_endpoint(region: 'na')
+      result['contentDelivery'] = 'mutated'
+      fresh = described_class.get_contentstack_endpoint(region: 'na')
+      expect(fresh['contentDelivery']).to eq('https://cdn.contentstack.io')
+    end
+  end
+
+  # ── Error cases ──────────────────────────────────────────────────────────────
+
+  describe 'error cases' do
+    it 'raises ArgumentError for empty string region' do
+      expect { described_class.get_contentstack_endpoint(region: '') }
+        .to raise_error(ArgumentError, 'Empty region provided')
+    end
+
+    it 'raises ArgumentError for whitespace-only region' do
+      expect { described_class.get_contentstack_endpoint(region: '   ') }
+        .to raise_error(ArgumentError, 'Empty region provided')
+    end
+
+    it 'raises ArgumentError for unknown region' do
+      expect { described_class.get_contentstack_endpoint(region: 'invalid-region') }
+        .to raise_error(ArgumentError, 'Invalid region: invalid-region')
+    end
+
+    it 'raises ArgumentError for unknown service' do
+      expect { described_class.get_contentstack_endpoint(region: 'na', service: 'unknownService') }
+        .to raise_error(ArgumentError, 'Service "unknownService" not found for region "na"')
+    end
+
+    it 'raises ArgumentError for valid region but unknown service' do
+      expect { described_class.get_contentstack_endpoint(region: 'eu', service: 'nonExistentService') }
+        .to raise_error(ArgumentError, /Service "nonExistentService" not found/)
+    end
+  end
+
+  # ── Additional service spot-checks ──────────────────────────────────────────
+
+  describe 'additional service endpoints' do
+    it 'resolves auth endpoint for NA' do
+      result = described_class.get_contentstack_endpoint(region: 'na', service: 'auth')
+      expect(result).to eq('https://auth-api.contentstack.com')
+    end
+
+    it 'resolves graphqlDelivery endpoint for EU' do
+      result = described_class.get_contentstack_endpoint(region: 'eu', service: 'graphqlDelivery')
+      expect(result).to eq('https://eu-graphql.contentstack.com')
+    end
+
+    it 'resolves preview endpoint for azure-na' do
+      result = described_class.get_contentstack_endpoint(region: 'azure-na', service: 'preview')
+      expect(result).to eq('https://azure-na-rest-preview.contentstack.com')
+    end
+
+    it 'resolves application endpoint for gcp-eu' do
+      result = described_class.get_contentstack_endpoint(region: 'gcp-eu', service: 'application')
+      expect(result).to eq('https://gcp-eu-app.contentstack.com')
+    end
+  end
+end
+
+# ── Utils proxy ────────────────────────────────────────────────────────────────
+
+RSpec.describe ContentstackUtils do
+  before(:each) do
+    ContentstackUtils::Endpoint.reset_cache
+  end
+
+  describe '.get_contentstack_endpoint' do
+    it 'returns same value as Endpoint.get_contentstack_endpoint for default args' do
+      expect(described_class.get_contentstack_endpoint)
+        .to eq(ContentstackUtils::Endpoint.get_contentstack_endpoint)
+    end
+
+    it 'proxy returns contentDelivery for NA' do
+      result = described_class.get_contentstack_endpoint(region: 'na', service: 'contentDelivery')
+      expect(result).to eq('https://cdn.contentstack.io')
+    end
+
+    it 'proxy respects omit_https option' do
+      result = described_class.get_contentstack_endpoint(region: 'na', service: 'contentDelivery', omit_https: true)
+      expect(result).to eq('cdn.contentstack.io')
+    end
+
+    it 'proxy returns full endpoints map when no service given' do
+      result = described_class.get_contentstack_endpoint(region: 'eu')
+      expect(result).to be_a(Hash)
+      expect(result['contentManagement']).to eq('https://eu-api.contentstack.com')
+    end
+
+    it 'proxy raises ArgumentError for invalid region' do
+      expect { described_class.get_contentstack_endpoint(region: 'bad-region') }
+        .to raise_error(ArgumentError, /Invalid region/)
+    end
+  end
+end

From 61f2dbe3455af80cc2c9631b09f9be9cf697f3b4 Mon Sep 17 00:00:00 2001
From: sunil-lakshman <104969541+sunil-lakshman@users.noreply.github.com>
Date: Mon, 8 Jun 2026 15:10:59 +0530
Subject: [PATCH 5/5] Added changelog file

---
 CHANGELOG.md                      | 6 ++++++
 lib/contentstack_utils/version.rb | 2 +-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a356b0a..b7a4be2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## [1.3.0](https://github.com/contentstack/contentstack-utils-ruby/tree/v1.3.0) (2026-06-15)
+  - Added `ContentstackUtils::Endpoint.get_contentstack_endpoint` for dynamic endpoint resolution based on region and service.
+  - Added `ContentstackUtils.get_contentstack_endpoint` as a backward-compatible proxy.
+  - Added `ContentstackUtils::Endpoint.refresh_regions` for manual region metadata refresh.
+  - Added runtime fallback to automatically download `regions.json` from the Contentstack Regions Registry when not present locally.
+
 ## [1.2.4](https://github.com/contentstack/contentstack-utils-ruby/tree/v1.2.4) (2026-04-15)
   - Fixed Security issues.
 
diff --git a/lib/contentstack_utils/version.rb b/lib/contentstack_utils/version.rb
index 2ac4815..1e3d5b6 100644
--- a/lib/contentstack_utils/version.rb
+++ b/lib/contentstack_utils/version.rb
@@ -1,3 +1,3 @@
 module ContentstackUtils
-    VERSION = "1.2.4"
+    VERSION = "1.3.0"
 end