contentstack 0.8.5 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c608b1247b89cb28b9519fbf9e0814879aab951953ca8a82902df4dcf4a38b7b
-  data.tar.gz: 0cf04ec05622ffbbb963fb94794da5a80eec6d66fda8609747d2d11312e4808f
+  metadata.gz: 9caea6c14fd2fce3388e9ca3f1fb9be0a1e9f00cfd8fb044ec2e86e82198710f
+  data.tar.gz: cf9d266384581fe938dc6951315ee0ed974b4fc5207ed620c81f7ef03d066e97
 SHA512:
-  metadata.gz: e423a49545eae6ce37d39857877a6fcbf2ba65cbba41a6fb3cd9ec7520d7a3d64cae7ba5d660b0b2726bd53050ea566559d392145bf00413a1c2d7055b345969
-  data.tar.gz: e27142598452a529289a8d63e51387ad8f0d89295540fa146651bb623f5bda88962088a9d53cde1fd958f4c8674062bac95fdf5783fac7046a374ac8b445371e
+  metadata.gz: d19ca8388e4a1b12afea51497706ca3e23b19e66a9cebbf9bc6a82b36190bc48fe444c1dfd1858ae090d007ab389df34d70f0f6adb5bcf9c2506e2844fc3bfaa
+  data.tar.gz: a5958d88bffbed5682d6a73c92583d1488b79aeb2a8ca5ebe82b43adfa3065eb1d496eb3bd790c37940c65b6c005d53aa90657cd648895b046acc00783197d99

data/.gitignore

@@ -10,4 +10,5 @@ spec/.env.test
 .bundle/
 **/rspec_results.html
 vendor/
-.dccache
+.dccache
+lib/data/regions.json

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## CHANGELOG
 
+## Version 0.9.0
+### Date: 15th-June-2026
+ ### Enhancement
+ - Introduced centralized endpoint resolution via `Contentstack::Endpoint.get_contentstack_endpoint(region, service)`, eliminating all hardcoded Contentstack hostnames from the SDK.
+ - Added `Contentstack.get_contentstack_endpoint` as a backward-compatible module-level proxy, aligned with the `ContentstackUtils` endpoint resolution API.
+ - Added `Contentstack::Service` class with `CDA`, `CMA`, and `PREVIEW` constants.
+ - Added `Contentstack::Region::GCP_EU` region constant.
+ - Endpoint URLs are driven by a local `lib/data/regions.json` file with automatic runtime fallback to the Contentstack registry when the file is absent.
+ - Added `bundle exec rake refresh_regions` task to manually update region metadata from the registry.
+
+------------------------------------------------
+
 ## Version 0.8.5
 ### Date: 5th-June-2026
  ### Deprecated

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    contentstack (0.8.5)
+    contentstack (0.9.0)
       activesupport (>= 3.2)
       contentstack_utils (~> 1.2)
 
@@ -39,7 +39,7 @@ GEM
     hashdiff (1.2.1)
     i18n (1.14.8)
       concurrent-ruby (~> 1.0)
-    json (2.19.7)
+    json (2.19.8)
     logger (1.7.0)
     minitest (6.0.6)
       drb (~> 2.0)
@@ -116,9 +116,10 @@ CHECKSUMS
   addressable (2.9.0) sha256=7fdf6ac3660f7f4e867a0838be3f6cf722ace541dd97767fa42bc6cfa980c7af
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
   bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
+  bundler (4.0.11) sha256=5bcec0fb78302e48d02ee46f10ee6e6942be647ba5b44a6d1ddfda9a240ce785
   concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
   connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a
-  contentstack (0.8.5)
+  contentstack (0.9.0)
   contentstack_utils (1.2.3) sha256=cf2f5f996eb487559fd2d7d48a99262710f53dec62c84c6e325b9a598cd31ba7
   crack (1.0.1) sha256=ff4a10390cd31d66440b7524eb1841874db86201d5b70032028553130b6d4c7e
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
@@ -126,7 +127,7 @@ CHECKSUMS
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
   hashdiff (1.2.1) sha256=9c079dbc513dfc8833ab59c0c2d8f230fa28499cc5efb4b8dd276cf931457cd1
   i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5
-  json (2.19.7) sha256=fe432c8639f6efff69f9d73b518a3705d9581ab93156f981ea72806e1e5bcc3e
+  json (2.19.8) sha256=6354310fd76ef69b87d5bd1f38b40d730613baf90b6803d2d0a48f618d32dfaa
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1
   nokogiri (1.19.3-aarch64-linux-gnu) sha256=46b89e5d7b9e844c2ee360794240c6ea2a4e6fa0c5892a4ed487db621224b639

data/contentstack.gemspec

@@ -18,7 +18,9 @@ Gem::Specification.new do |s|
   s.summary = %q{Contentstack Ruby client for the Content Delivery API}
   s.description = %q{Contentstack Ruby client for the Content Delivery API}
 
-  s.files = `git ls-files`.split("\n")
+  s.files         = `git ls-files`.split("\n") +
+                    Dir['ext/**/*'].select { |f| File.file?(f) }
+  s.extensions    = ['ext/download_regions/extconf.rb']
   s.require_paths = ["lib"]
 
   s.add_dependency 'activesupport', '>= 3.2'

data/ext/download_regions/extconf.rb

@@ -0,0 +1,29 @@
+require 'net/http'
+require 'uri'
+require 'json'
+require 'fileutils'
+
+REGISTRY_URL = 'https://artifacts.contentstack.com/regions.json'
+
+gem_root  = File.expand_path('../..', __dir__)
+data_dir  = File.join(gem_root, 'lib', 'data')
+dest_file = File.join(data_dir, 'regions.json')
+
+FileUtils.mkdir_p(data_dir)
+
+begin
+  uri      = URI.parse(REGISTRY_URL)
+  response = Net::HTTP.get_response(uri)
+  if response.is_a?(Net::HTTPSuccess)
+    File.write(dest_file, JSON.pretty_generate(JSON.parse(response.body)))
+    $stdout.puts "[Contentstack] regions.json downloaded successfully."
+  else
+    $stdout.puts "[Contentstack] Warning: Could not download regions.json (HTTP #{response.code}). Runtime fallback will be used."
+  end
+rescue => e
+  $stdout.puts "[Contentstack] Warning: Could not download regions.json — #{e.message}. Runtime fallback will be used."
+end
+
+# RubyGems requires a Makefile to exist after extconf.rb runs.
+# We create a no-op one since this extension has no C code to compile.
+File.write('Makefile', "all:\n\ninstall:\n\nclean:\n\n")

data/lib/contentstack/client.rb

@@ -2,6 +2,7 @@ require 'contentstack/api'
 require 'contentstack/content_type'
 require 'contentstack/asset_collection'
 require 'contentstack/sync_result'
+require 'contentstack/endpoint'
 require 'util'
 require 'contentstack/error'
 module Contentstack
@@ -80,47 +81,14 @@ module Contentstack
     end
 
     private
-    def get_default_region_hosts(region='us')
-      host = "#{Contentstack::Host::PROTOCOL}#{Contentstack::Host::DEFAULT_HOST}" #set default host if region is nil
-      case region
-      when "us"
-        host = "#{Contentstack::Host::PROTOCOL}#{Contentstack::Host::DEFAULT_HOST}"
-      when "eu"
-        host = "#{Contentstack::Host::PROTOCOL}eu-cdn.#{Contentstack::Host::HOST}"
-      when "azure-na"
-        host = "#{Contentstack::Host::PROTOCOL}azure-na-cdn.#{Contentstack::Host::HOST}"
-      when "azure-eu"
-        host = "#{Contentstack::Host::PROTOCOL}azure-eu-cdn.#{Contentstack::Host::HOST}"
-      when "gcp-na"
-        host = "#{Contentstack::Host::PROTOCOL}gcp-na-cdn.#{Contentstack::Host::HOST}"
-      end
-      host
-    end
 
     def get_host_by_region(region, options)
-      if options[:host].nil? && region.present?
-        host = get_default_region_hosts(region)
-      elsif options[:host].present? && region.present?
-        custom_host = options[:host]
-        case region
-        when "us"
-        host = "#{Contentstack::Host::PROTOCOL}cdn.#{custom_host}"
-        when "eu"
-          host = "#{Contentstack::Host::PROTOCOL}eu-cdn.#{custom_host}"
-        when "azure-na"
-          host = "#{Contentstack::Host::PROTOCOL}azure-na-cdn.#{custom_host}"
-        when "azure-eu"
-          host = "#{Contentstack::Host::PROTOCOL}azure-eu-cdn.#{custom_host}"
-        when "gcp-na"
-          host = "#{Contentstack::Host::PROTOCOL}gcp-na-cdn.#{custom_host}"
-        end
-      elsif options[:host].present? && region.empty?
-        custom_host = options[:host]
-        host = "#{Contentstack::Host::PROTOCOL}cdn.#{custom_host}"
-      else
-        host = "#{Contentstack::Host::PROTOCOL}#{Contentstack::Host::DEFAULT_HOST}" #set default host if region and host is empty
-      end
-      host
+      custom_host = options[:host]
+      Contentstack::Endpoint.get_contentstack_endpoint(
+        region.present? ? region : Contentstack::Region::US,
+        Contentstack::Service::CDA,
+        custom_host.present? ? custom_host : nil
+      )
     end
 
   end

data/lib/contentstack/endpoint.rb

@@ -0,0 +1,133 @@
+require 'json'
+require 'net/http'
+require 'uri'
+require 'fileutils'
+require 'contentstack/error'
+
+module Contentstack
+  # Centralised endpoint resolver. Reads region metadata from the local
+  # regions.json (downloaded from https://artifacts.contentstack.com/regions.json
+  # at gem install time) and falls back to a live fetch when the file is absent.
+  #
+  # Delegates to ContentstackUtils.get_contentstack_endpoint when that gem
+  # ships the method (contentstack-utils-ruby PR #41).
+  class Endpoint
+    REGISTRY_URL   = 'https://artifacts.contentstack.com/regions.json'
+    DATA_FILE_PATH = File.join(File.dirname(File.dirname(__FILE__)), 'data', 'regions.json')
+
+    # Maps the SDK's short service keys to the camelCase keys used in regions.json,
+    # preserving backward compatibility for callers using Service::CDA / Service::CMA.
+    SERVICE_MAP = {
+      'cda'     => 'contentDelivery',
+      'cma'     => 'contentManagement',
+      'preview' => 'preview'
+    }.freeze
+
+    DEFAULT_SERVICE = 'contentDelivery'
+
+    # Resolve a Contentstack service URL for the given region and service.
+    #
+    #   Contentstack::Endpoint.get_contentstack_endpoint('eu')
+    #   # => "https://eu-cdn.contentstack.com"
+    #
+    #   Contentstack::Endpoint.get_contentstack_endpoint('us', 'contentManagement')
+    #   # => "https://api.contentstack.io"
+    #
+    #   Contentstack::Endpoint.get_contentstack_endpoint('eu', 'cda')   # short alias
+    #   # => "https://eu-cdn.contentstack.com"
+    #
+    # When +custom_host+ is supplied the region CDN prefix is derived from
+    # regions.json and prepended to the custom domain.
+    def self.get_contentstack_endpoint(region, service = DEFAULT_SERVICE, custom_host = nil)
+      region_key  = region.to_s.downcase
+      service_key = SERVICE_MAP.fetch(service.to_s, service.to_s)
+
+      if custom_host.nil? || custom_host.to_s.empty?
+        if defined?(ContentstackUtils) && ContentstackUtils.respond_to?(:get_contentstack_endpoint)
+          return ContentstackUtils.get_contentstack_endpoint(region_key, service_key)
+        end
+        resolve_standard(region_key, service_key)
+      else
+        resolve_custom_host(region_key, service_key, custom_host)
+      end
+    end
+
+    # Download the latest regions.json from https://artifacts.contentstack.com/regions.json
+    # and persist it locally. Called automatically by ext/download_regions/extconf.rb
+    # during bundle install / bundle update, and by `bundle exec rake refresh_regions`.
+    def self.refresh_regions
+      data = fetch_from_registry
+      FileUtils.mkdir_p(File.dirname(DATA_FILE_PATH))
+      File.write(DATA_FILE_PATH, JSON.pretty_generate(data))
+      data
+    end
+
+    private
+
+    def self.resolve_standard(region_key, service_key)
+      region_data = find_region(region_key)
+      unless region_data
+        raise Contentstack::Error.new(
+          Contentstack::ErrorMessages.region_invalid(region_key, all_region_ids)
+        )
+      end
+      unless region_data['endpoints'].key?(service_key)
+        raise Contentstack::Error.new(
+          Contentstack::ErrorMessages.service_invalid(service_key, region_data['endpoints'].keys)
+        )
+      end
+      region_data['endpoints'][service_key]
+    end
+
+    def self.resolve_custom_host(region_key, service_key, custom_host)
+      region_data = find_region(region_key)
+      if region_data && region_data['endpoints'].key?(service_key)
+        standard_url = region_data['endpoints'][service_key]
+        prefix = URI.parse(standard_url).host.split('.').first
+        "https://#{prefix}.#{custom_host}"
+      else
+        "https://cdn.#{custom_host}"
+      end
+    end
+
+    # Find a region by its canonical id or any of its declared aliases.
+    def self.find_region(region_key)
+      load_regions['regions'].find do |r|
+        r['id'] == region_key ||
+          r['alias'].any? { |a| a.downcase == region_key }
+      end
+    end
+
+    def self.all_region_ids
+      load_regions['regions'].map { |r| r['id'] }
+    end
+
+    def self.load_regions
+      if File.exist?(DATA_FILE_PATH)
+        JSON.parse(File.read(DATA_FILE_PATH))
+      else
+        warn '[Contentstack] regions.json not found locally — fetching from registry...'
+        data = fetch_from_registry
+        begin
+          FileUtils.mkdir_p(File.dirname(DATA_FILE_PATH))
+          File.write(DATA_FILE_PATH, JSON.pretty_generate(data))
+        rescue => e
+          warn "[Contentstack] Could not cache regions.json: #{e.message}"
+        end
+        data
+      end
+    end
+
+    def self.fetch_from_registry
+      uri      = URI.parse(REGISTRY_URL)
+      response = Net::HTTP.get_response(uri)
+      unless response.is_a?(Net::HTTPSuccess)
+        raise Contentstack::Error.new(
+          "Failed to fetch region metadata from registry (HTTP #{response.code}). " \
+          'Ensure network access and try again.'
+        )
+      end
+      JSON.parse(response.body)
+    end
+  end
+end

data/lib/contentstack/error.rb

@@ -17,6 +17,14 @@ module Contentstack
     def self.request_error(error)
       "The request encountered an issue due to #{error}. Review the details and try again."
     end
+
+    def self.region_invalid(region, supported)
+      "Unknown region '#{region}'. Supported regions: #{supported.join(', ')}."
+    end
+
+    def self.service_invalid(service, supported)
+      "Unknown service '#{service}'. Supported services: #{supported.join(', ')}."
+    end
   end
 
   class Error < StandardError

data/lib/contentstack/region.rb

@@ -1,15 +1,43 @@
 module Contentstack
   class Region
-    EU='eu'
-    US='us'
-    AZURE_NA='azure-na'
-    AZURE_EU='azure-eu'
-    GCP_NA='gcp-na'
+    EU       = 'eu'
+    US       = 'us'       # alias for the 'na' region in regions.json
+    AZURE_NA = 'azure-na'
+    AZURE_EU = 'azure-eu'
+    GCP_NA   = 'gcp-na'
+    GCP_EU   = 'gcp-eu'
+    AU       = 'au'
+  end
+
+  class Service
+    # Full camelCase keys matching regions.json
+    CONTENT_DELIVERY   = 'contentDelivery'
+    CONTENT_MANAGEMENT = 'contentManagement'
+    PREVIEW            = 'preview'
+    AUTH               = 'auth'
+    GRAPHQL_DELIVERY   = 'graphqlDelivery'
+    GRAPHQL_PREVIEW    = 'graphqlPreview'
+    IMAGES             = 'images'
+    ASSETS             = 'assets'
+    AUTOMATE           = 'automate'
+    LAUNCH             = 'launch'
+    DEVELOPER_HUB      = 'developerHub'
+    BRAND_KIT          = 'brandKit'
+    GEN_AI             = 'genAI'
+    PERSONALIZE_MGMT   = 'personalizeManagement'
+    PERSONALIZE_EDGE   = 'personalizeEdge'
+    COMPOSABLE_STUDIO  = 'composableStudio'
+    ASSET_MANAGEMENT   = 'assetManagement'
+    APPLICATION        = 'application'
+
+    # Short aliases kept for backward compatibility
+    CDA = CONTENT_DELIVERY
+    CMA = CONTENT_MANAGEMENT
   end
 
   class Host
-    PROTOCOL='https://'
-    DEFAULT_HOST='cdn.contentstack.io'
-    HOST='contentstack.com'
+    PROTOCOL     = 'https://'
+    DEFAULT_HOST = 'cdn.contentstack.io'
+    HOST         = 'contentstack.com'
   end
 end

data/lib/contentstack/version.rb

@@ -1,3 +1,3 @@
 module Contentstack
-  VERSION = "0.8.5"
+  VERSION = "0.9.0"
 end

data/lib/contentstack.rb

@@ -3,6 +3,7 @@ $LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
 require "contentstack/version"
 require "contentstack/client"
 require "contentstack/region"
+require "contentstack/endpoint"
 require "contentstack_utils"
 
 # == Contentstack - Ruby SDK
@@ -23,10 +24,24 @@ require "contentstack_utils"
 # ==== Query entries
 #   @stack.content_type('blog').query.regex('title', '.*hello.*').fetch
 module Contentstack
-    def self.render_content(content, options)
-        ContentstackUtils.render_content(content, options)
-    end
-    def self.json_to_html(content, options)
-        ContentstackUtils.json_to_html(content, options)
-    end
+  def self.render_content(content, options)
+    ContentstackUtils.render_content(content, options)
+  end
+
+  def self.json_to_html(content, options)
+    ContentstackUtils.json_to_html(content, options)
+  end
+
+  # Backward-compatible proxy for endpoint resolution.
+  # Delegates to ContentstackUtils.get_contentstack_endpoint when available,
+  # otherwise resolves via Contentstack::Endpoint.
+  #
+  #   Contentstack.get_contentstack_endpoint('eu')
+  #   # => "https://eu-cdn.contentstack.com"
+  #
+  #   Contentstack.get_contentstack_endpoint('us', 'cma')
+  #   # => "https://api.contentstack.io"
+  def self.get_contentstack_endpoint(region, service = Contentstack::Service::CDA)
+    Contentstack::Endpoint.get_contentstack_endpoint(region, service)
+  end
 end

data/rakefile.rb

@@ -1,4 +1,13 @@
 require 'yard'
 YARD::Rake::YardocTask.new do |t|
- t.files   = ["README.rdoc", 'lib/contentstack/*.rb', 'lib/contentstack.rb']   # optional
+  t.files = ["README.rdoc", 'lib/contentstack/*.rb', 'lib/contentstack.rb']
+end
+
+desc 'Download the latest region metadata from the Contentstack registry and update lib/data/regions.json'
+task :refresh_regions do
+  require_relative 'lib/contentstack/endpoint'
+  require_relative 'lib/contentstack/error'
+  puts 'Fetching latest region metadata from registry...'
+  Contentstack::Endpoint.refresh_regions
+  puts "regions.json updated at: #{Contentstack::Endpoint::DATA_FILE_PATH}"
 end

data/spec/endpoint_spec.rb

@@ -0,0 +1,232 @@
+require 'spec_helper'
+require_relative '../lib/contentstack'
+
+describe Contentstack::Endpoint do
+  let(:regions_data) do
+    JSON.parse(File.read(Contentstack::Endpoint::DATA_FILE_PATH))
+  end
+
+  # ---------------------------------------------------------------------------
+  # contentDelivery (CDA) endpoints — default service
+  # ---------------------------------------------------------------------------
+  describe '.get_contentstack_endpoint - contentDelivery (default)' do
+    {
+      'us'       => 'https://cdn.contentstack.io',
+      '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|
+      it "resolves #{region} => #{expected}" do
+        expect(described_class.get_contentstack_endpoint(region)).to eq expected
+      end
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Short alias 'cda' backward-compat via SERVICE_MAP
+  # ---------------------------------------------------------------------------
+  describe '.get_contentstack_endpoint - short alias cda' do
+    it "maps 'cda' to contentDelivery" do
+      expect(described_class.get_contentstack_endpoint('eu', 'cda'))
+        .to eq 'https://eu-cdn.contentstack.com'
+    end
+
+    it "maps 'cma' to contentManagement" do
+      expect(described_class.get_contentstack_endpoint('eu', 'cma'))
+        .to eq 'https://eu-api.contentstack.com'
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # contentManagement (CMA) endpoints
+  # ---------------------------------------------------------------------------
+  describe '.get_contentstack_endpoint - contentManagement' do
+    {
+      'us'       => '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|
+      it "resolves #{region} CMA => #{expected}" do
+        expect(described_class.get_contentstack_endpoint(region, 'contentManagement')).to eq expected
+      end
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # All other services for a representative region (EU)
+  # ---------------------------------------------------------------------------
+  describe '.get_contentstack_endpoint - all services for EU' do
+    {
+      'auth'                 => 'https://eu-auth-api.contentstack.com',
+      'graphqlDelivery'      => 'https://eu-graphql.contentstack.com',
+      'preview'              => 'https://eu-rest-preview.contentstack.com',
+      'graphqlPreview'       => 'https://eu-graphql-preview.contentstack.com',
+      'images'               => 'https://eu-images.contentstack.com',
+      'assets'               => 'https://eu-assets.contentstack.com',
+      'automate'             => 'https://eu-prod-automations-api.contentstack.com',
+      'launch'               => 'https://eu-launch-api.contentstack.com',
+      'developerHub'         => 'https://eu-developerhub-api.contentstack.com',
+      'brandKit'             => 'https://eu-brand-kits-api.contentstack.com',
+      'genAI'                => 'https://eu-ai.contentstack.com/brand-kits',
+      'personalizeManagement'=> 'https://eu-personalize-api.contentstack.com',
+      'personalizeEdge'      => 'https://eu-personalize-edge.contentstack.com',
+      'composableStudio'     => 'https://eu-composable-studio-api.contentstack.com',
+      'application'          => 'https://eu-app.contentstack.com'
+    }.each do |service, expected|
+      it "resolves EU #{service} => #{expected}" do
+        expect(described_class.get_contentstack_endpoint('eu', service)).to eq expected
+      end
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Region::Service constants
+  # ---------------------------------------------------------------------------
+  describe 'Contentstack::Service constants' do
+    it 'CDA aliases to contentDelivery'   do expect(Contentstack::Service::CDA).to eq 'contentDelivery'   end
+    it 'CMA aliases to contentManagement' do expect(Contentstack::Service::CMA).to eq 'contentManagement' end
+    it 'defines PREVIEW'                  do expect(Contentstack::Service::PREVIEW).to eq 'preview'        end
+    it 'defines AUTH'                     do expect(Contentstack::Service::AUTH).to eq 'auth'               end
+    it 'defines GRAPHQL_DELIVERY'         do expect(Contentstack::Service::GRAPHQL_DELIVERY).to eq 'graphqlDelivery' end
+    it 'defines IMAGES'                   do expect(Contentstack::Service::IMAGES).to eq 'images'           end
+    it 'defines ASSETS'                   do expect(Contentstack::Service::ASSETS).to eq 'assets'           end
+    it 'defines DEVELOPER_HUB'            do expect(Contentstack::Service::DEVELOPER_HUB).to eq 'developerHub' end
+    it 'defines GEN_AI'                   do expect(Contentstack::Service::GEN_AI).to eq 'genAI'            end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Region constants
+  # ---------------------------------------------------------------------------
+  describe 'Contentstack::Region constants' do
+    it 'includes AU'     do expect(Contentstack::Region::AU).to eq 'au'       end
+    it 'includes GCP_EU' do expect(Contentstack::Region::GCP_EU).to eq 'gcp-eu' end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Alias resolution (aliases come from regions.json itself)
+  # ---------------------------------------------------------------------------
+  describe '.get_contentstack_endpoint - region aliases from regions.json' do
+    it "resolves 'aws-na' (alias) to the NA CDN" do
+      expect(described_class.get_contentstack_endpoint('aws-na')).to eq 'https://cdn.contentstack.io'
+    end
+
+    it "resolves 'aws-eu' (alias) to the EU CDN" do
+      expect(described_class.get_contentstack_endpoint('aws-eu')).to eq 'https://eu-cdn.contentstack.com'
+    end
+
+    it "resolves 'aws-au' (alias) to the AU CDN" do
+      expect(described_class.get_contentstack_endpoint('aws-au')).to eq 'https://au-cdn.contentstack.com'
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Custom host resolution
+  # ---------------------------------------------------------------------------
+  describe '.get_contentstack_endpoint - custom host' do
+    it 'prepends eu-cdn prefix for eu + custom host' do
+      expect(described_class.get_contentstack_endpoint('eu', 'contentDelivery', 'example.com'))
+        .to eq 'https://eu-cdn.example.com'
+    end
+
+    it 'prepends azure-na-cdn prefix for azure-na + custom host' do
+      expect(described_class.get_contentstack_endpoint('azure-na', 'contentDelivery', 'example.com'))
+        .to eq 'https://azure-na-cdn.example.com'
+    end
+
+    it 'prepends au-cdn prefix for au + custom host' do
+      expect(described_class.get_contentstack_endpoint('au', 'contentDelivery', 'example.com'))
+        .to eq 'https://au-cdn.example.com'
+    end
+
+    it 'falls back to cdn. prefix for an unknown region + custom host' do
+      expect(described_class.get_contentstack_endpoint('unknown', 'contentDelivery', 'example.com'))
+        .to eq 'https://cdn.example.com'
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Error handling
+  # ---------------------------------------------------------------------------
+  describe '.get_contentstack_endpoint - error handling' do
+    it 'raises Contentstack::Error for an unknown region (no custom host)' do
+      expect { described_class.get_contentstack_endpoint('mars') }
+        .to raise_error(Contentstack::Error, /Unknown region 'mars'/)
+    end
+
+    it 'raises Contentstack::Error for an unknown service' do
+      expect { described_class.get_contentstack_endpoint('us', 'invalidService') }
+        .to raise_error(Contentstack::Error, /Unknown service 'invalidService'/)
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Runtime fallback when regions.json is absent
+  # ---------------------------------------------------------------------------
+  describe '.get_contentstack_endpoint - runtime fallback' do
+    it 'fetches from registry when regions.json is absent' do
+      stub_request(:get, Contentstack::Endpoint::REGISTRY_URL)
+        .to_return(status: 200, body: regions_data.to_json, headers: {})
+
+      allow(File).to receive(:exist?).and_call_original
+      allow(File).to receive(:exist?).with(Contentstack::Endpoint::DATA_FILE_PATH).and_return(false)
+      allow(File).to receive(:write).and_call_original
+
+      result = described_class.get_contentstack_endpoint('eu')
+      expect(result).to eq 'https://eu-cdn.contentstack.com'
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # refresh_regions
+  # ---------------------------------------------------------------------------
+  describe '.refresh_regions' do
+    it 'writes updated region data to DATA_FILE_PATH' do
+      stub_request(:get, Contentstack::Endpoint::REGISTRY_URL)
+        .to_return(status: 200, body: regions_data.to_json, headers: {})
+
+      allow(FileUtils).to receive(:mkdir_p)
+      expect(File).to receive(:write).with(
+        Contentstack::Endpoint::DATA_FILE_PATH,
+        JSON.pretty_generate(regions_data)
+      )
+
+      result = described_class.refresh_regions
+      expect(result).to eq regions_data
+    end
+
+    it 'raises Contentstack::Error when registry returns non-200' do
+      stub_request(:get, Contentstack::Endpoint::REGISTRY_URL)
+        .to_return(status: 503, body: 'Service Unavailable')
+
+      expect { described_class.refresh_regions }
+        .to raise_error(Contentstack::Error, /HTTP 503/)
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # Module-level proxy: Contentstack.get_contentstack_endpoint
+  # ---------------------------------------------------------------------------
+  describe 'Contentstack.get_contentstack_endpoint' do
+    it 'returns the NA CDN URL for us' do
+      expect(Contentstack.get_contentstack_endpoint('us')).to eq 'https://cdn.contentstack.io'
+    end
+
+    it 'returns the EU CMA URL' do
+      expect(Contentstack.get_contentstack_endpoint('eu', 'contentManagement'))
+        .to eq 'https://eu-api.contentstack.com'
+    end
+
+    it 'accepts Service::CDA constant' do
+      expect(Contentstack.get_contentstack_endpoint('au', Contentstack::Service::CDA))
+        .to eq 'https://au-cdn.contentstack.com'
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: contentstack
 version: !ruby/object:Gem::Version
-  version: 0.8.5
+  version: 0.9.0
 platform: ruby
 authors:
 - Contentstack
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-01 00:00:00.000000000 Z
+date: 2026-06-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -98,7 +98,8 @@ description: Contentstack Ruby client for the Content Delivery API
 email:
 - support@contentstack.com
 executables: []
-extensions: []
+extensions:
+- ext/download_regions/extconf.rb
 extra_rdoc_files: []
 files:
 - ".cursor/rules/README.md"
@@ -122,12 +123,14 @@ files:
 - README.md
 - SECURITY.md
 - contentstack.gemspec
+- ext/download_regions/extconf.rb
 - lib/contentstack.rb
 - lib/contentstack/api.rb
 - lib/contentstack/asset.rb
 - lib/contentstack/asset_collection.rb
 - lib/contentstack/client.rb
 - lib/contentstack/content_type.rb
+- lib/contentstack/endpoint.rb
 - lib/contentstack/entry.rb
 - lib/contentstack/entry_collection.rb
 - lib/contentstack/error.rb
@@ -148,6 +151,7 @@ files:
 - spec/asset_spec.rb
 - spec/content_type_spec.rb
 - spec/contentstack_spec.rb
+- spec/endpoint_spec.rb
 - spec/entry_collection_spec.rb
 - spec/entry_spec.rb
 - spec/fixtures/asset.json