contentstack 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 130b38df3188d221dee98e6b81fd722182dec955c3a2135495e7287aafb30126
-  data.tar.gz: 4102aec44b79853e3922ceadb2f26948b0ab06f7cfa3efabfdc36abd79e032ee
+  metadata.gz: 7e776d17a2fda85c9e2451aac3c798418b63a0866e0dbff1f6a45ecf35a881af
+  data.tar.gz: 55df7efc6ec43bfb3a1e500a2c28ecda534bbe7e9211f1cad62e419f509c35cf
 SHA512:
-  metadata.gz: 3d54445ed056163eb5c89c205c83a7b89a2bc750aed8b4b9a97e023b70af5f0350b75fd20e5ccf275dc7c075a0cd3a0f87636133d6319e14d844278d3ae5a896
-  data.tar.gz: fbe828d45cac3276ae8ee494775673d849bd60e214c8139338232a8be6f7b0508a60b850a9fde73c14ff311236162fb7d9d8e737672a17dd5fbc9105fe0f55e5
+  metadata.gz: 0b19d4521e9d5451bf87f2c6ac385c477a3dcdab171b25c5f1047896f324e64c4bc60085c6cdf8e6cc006d46b4f752351aaf1b42518ae8285b2ed0725987a49a
+  data.tar.gz: 057fa0d575a8ae98de2d28f5ce382c1913e0099e3adc128ba2c36cb895d88c9651932f1df06cea8a3bddf158f31d6fc243656d2cbac3fbe4ab36bba2156a55c8

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## CHANGELOG
 
+## Version 0.10.0
+### Date: 27th-July-2026
+ ### Features
+ - Added `variants(variant_uids, branch_name)` on `Contentstack::Entry` and `Contentstack::Query` to fetch entry variants with optional per-request branch scoping. Requests send the `x-cs-variant-uid` header (comma-separated UIDs) and respect stack-level or per-call branch.
+
+------------------------------------------------
+
+## Version 0.9.2
+### Date: 6th-July-2026
+ ### Fix
+ -  - Snyk fixes `json >= 2.19.9`.
+
+------------------------------------------------
+
 ## Version 0.9.1
 ### Date: 29th-June-2026
  ### Fix

data/Gemfile

@@ -4,6 +4,9 @@ source "https://rubygems.org"
 # Transitive via contentstack_utils; pin until upstream requires >= 1.19.1 (SNYK-RUBY-NOKOGIRI-15315717).
 gem "nokogiri", ">= 1.19.1"
 
+# Transitive via activesupport; pin until upstream requires >= 2.19.9 (SNYK-RUBY-JSON-17739957).
+gem "json", ">= 2.19.9"
+
 # Ruby 4.0.x on recent macOS often segfaults in OpenSSL during `bundle` (not fixable in-app). Use Ruby 3.3+ (see .ruby-version).
 
 gemspec

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    contentstack (0.9.1)
+    contentstack (0.10.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.8)
+    json (2.20.0)
     logger (1.7.0)
     minitest (6.0.6)
       drb (~> 2.0)
@@ -105,6 +105,7 @@ PLATFORMS
 
 DEPENDENCIES
   contentstack!
+  json (>= 2.19.9)
   nokogiri (>= 1.19.1)
   rspec (~> 3.13.0)
   simplecov (~> 0.22.0)
@@ -118,7 +119,7 @@ CHECKSUMS
   bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
   concurrent-ruby (1.3.7) sha256=4412caec3a5ea2e5fdc52076724c071a81f2c0593d83b2ac8cbb8ca63b3151b0
   connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a
-  contentstack (0.9.1)
+  contentstack (0.10.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.8) sha256=6354310fd76ef69b87d5bd1f38b40d730613baf90b6803d2d0a48f618d32dfaa
+  json (2.20.0) sha256=9362bc6e55a952b056abf9167cf053358181c904cb70cd6eee0808ea830fc32b
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1
   nokogiri (1.19.3-aarch64-linux-gnu) sha256=46b89e5d7b9e844c2ee360794240c6ea2a4e6fa0c5892a4ed487db621224b639

data/lib/contentstack/api.rb

@@ -73,7 +73,51 @@ module Contentstack
       fetch_retry(path, query)
     end
 
+    def self.validate_variant_uids!(variant_uids)
+      if variant_uids.nil? || (variant_uids.respond_to?(:empty?) && variant_uids.empty?)
+        raise Contentstack::Error.new("Variant UID(s) are required. Provide a variant UID or an array of variant UIDs.")
+      end
+      unless variant_uids.is_a?(String) || variant_uids.is_a?(Array)
+        raise Contentstack::Error.new("Variant UID(s) must be a String or Array of Strings.")
+      end
+      if variant_uids.is_a?(Array) && variant_uids.any? { |uid| !uid.is_a?(String) || uid.empty? }
+        raise Contentstack::Error.new("Variant UID(s) must be a String or Array of Strings.")
+      end
+    end
+
     private
+    def self.prepare_query(q)
+      q = (q || {}).dup
+      variant_uids = q.delete(:variant_uids)
+      branch_override = q.delete(:branch)
+      [q, variant_uids, branch_override]
+    end
+
+    def self.format_variant_uids(variant_uids)
+      return nil if variant_uids.nil?
+
+      case variant_uids
+      when String
+        variant_uids.strip
+      when Array
+        variant_uids.map(&:to_s).reject(&:empty?).join(', ')
+      end
+    end
+
+    def self.resolve_branch(branch_override)
+      branch = branch_override
+      branch = @branch if branch.nil? || branch.to_s.empty?
+      branch
+    end
+
+    def self.apply_variant_headers(params, variant_uids, branch_override)
+      formatted = format_variant_uids(variant_uids)
+      params["x-cs-variant-uid"] = formatted if formatted && !formatted.empty?
+
+      branch = resolve_branch(branch_override)
+      params["branch"] = branch if !branch.nil? && !branch.empty?
+      params
+    end
     def self.fetch_retry(path, query=nil, count=0)
       response = send_request(path, query)
       if @errorRetry.include?(response["status_code"].to_i)
@@ -90,7 +134,7 @@ module Contentstack
     end
 
     def self.send_request(path, q=nil)
-      q ||= {}
+      q, variant_uids, branch_override = prepare_query(q)
 
       q.merge!(@headers)
 
@@ -103,9 +147,7 @@ module Contentstack
         "x-user-agent" => "ruby-sdk/#{Contentstack::VERSION}",
         "read_timeout" => @timeout
       }
-      if !@branch.nil? && !@branch.empty?
-        params["branch"] = @branch
-      end
+      apply_variant_headers(params, variant_uids, branch_override)
 
       if @proxy_details.present? && @proxy_details[:url].present? && @proxy_details[:port].present? && @proxy_details[:username].empty? && @proxy_details[:password].empty?
         params["proxy"] = URI.parse("http://#{@proxy_details[:url]}:#{@proxy_details[:port]}/").to_s
@@ -130,7 +172,7 @@ module Contentstack
     end
 
     def self.send_preview_request(path, q=nil)
-      q ||= {}
+      q, variant_uids, branch_override = prepare_query(q)
 
       q.merge!({live_preview: (!@live_preview.key?(:live_preview) ? 'init' : @live_preview[:live_preview]),})
 
@@ -143,9 +185,7 @@ module Contentstack
         "x-user-agent" => "ruby-sdk/#{Contentstack::VERSION}",
         "read_timeout" => @timeout
       }
-      if !@branch.nil? && !@branch.empty?
-        params["branch"] = @branch
-      end
+      apply_variant_headers(params, variant_uids, branch_override)
 
       if @proxy_details.present? && @proxy_details[:url].present? && @proxy_details[:port].present? && @proxy_details[:username].empty? && @proxy_details[:password].empty?
         params["proxy"] = URI.parse("http://#{@proxy_details[:url]}:#{@proxy_details[:port]}/").to_s

data/lib/contentstack/entry.rb

@@ -180,6 +180,26 @@ module Contentstack
       self
     end
 
+    # Scope the entry request to one or more entry variants, optionally on a branch.
+    #
+    # @param [String, Array<String>] variant_uids A variant UID, or an array of variant UIDs
+    # @param [String] branch_name Branch name to scope the request (overrides stack-level branch)
+    #
+    # Example
+    #
+    #    @entry = @stack.content_type('home_page').entry(entry_uid)
+    #    @entry.variants('xyz', 'branch_name').fetch
+    #
+    #    @entry = @stack.content_type('home_page').entry(entry_uid)
+    #    @entry.variants(['variant1', 'variant2'], 'branch_name').fetch
+    #
+    # @return [Contentstack::Entry]
+    def variants(variant_uids, branch_name = nil)
+      API.validate_variant_uids!(variant_uids)
+      @query[:variant_uids] = variant_uids
+      @query[:branch] = branch_name if branch_name.is_a?(String) && !branch_name.empty?
+      self
+    end
 
     # Include Embedded Objects (Entries and Assets) along with entry/entries details.
     #

data/lib/contentstack/query.rb

@@ -552,6 +552,27 @@ module Contentstack
       self
     end
 
+    # Scope the entries request to one or more entry variants, optionally on a branch.
+    #
+    # @param [String, Array<String>] variant_uids A variant UID, or an array of variant UIDs
+    # @param [String] branch_name Branch name to scope the request (overrides stack-level branch)
+    #
+    # Example
+    #
+    #    @query = @stack.content_type('home_page').query
+    #    @query.variants('xyz', 'branch_name').fetch
+    #
+    #    @query = @stack.content_type('home_page').query
+    #    @query.variants(['variant1', 'variant2'], 'branch_name').fetch
+    #
+    # @return [Contentstack::Query]
+    def variants(variant_uids, branch_name = nil)
+      API.validate_variant_uids!(variant_uids)
+      @query[:variant_uids] = variant_uids
+      @query[:branch] = branch_name if branch_name.is_a?(String) && !branch_name.empty?
+      self
+    end
+
     # Include Embedded Objects (Entries and Assets) along with entry/entries details.
     #
     # Example

data/lib/contentstack/version.rb

@@ -1,3 +1,3 @@
 module Contentstack
-  VERSION = "0.9.1"
+  VERSION = "0.10.0"
 end

data/spec/variants_spec.rb

@@ -0,0 +1,97 @@
+require 'spec_helper'
+
+describe 'entry variants' do
+  let(:client) { create_client }
+  let(:branch_client) { create_client(ENV['DELIVERY_TOKEN'], ENV['API_KEY'], ENV['ENVIRONMENT'], { branch: 'stack_branch' }) }
+  let(:entry_uid) { 'uid' }
+  let(:category_entry) { client.content_type('category').entry(entry_uid) }
+  let(:category_query) { client.content_type('category').query }
+
+  describe Contentstack::Entry do
+    it 'stores variant UID and branch on the query' do
+      entry = category_entry.variants('variant1', 'branch_name')
+      expect(entry.query[:variant_uids]).to eq 'variant1'
+      expect(entry.query[:branch]).to eq 'branch_name'
+    end
+
+    it 'stores multiple variant UIDs' do
+      entry = category_entry.variants(['variant1', 'variant2'], 'branch_name')
+      expect(entry.query[:variant_uids]).to eq ['variant1', 'variant2']
+    end
+
+    it 'raises when variant UIDs are missing' do
+      expect { category_entry.variants(nil) }.to raise_error(Contentstack::Error, /Variant UID/)
+      expect { category_entry.variants([]) }.to raise_error(Contentstack::Error, /Variant UID/)
+    end
+
+    it 'raises when variant UIDs are invalid' do
+      expect { category_entry.variants(123) }.to raise_error(Contentstack::Error, /String or Array/)
+      expect { category_entry.variants(['']) }.to raise_error(Contentstack::Error, /String or Array/)
+    end
+  end
+
+  describe Contentstack::Query do
+    it 'stores variant UID and branch on the query' do
+      query = category_query.variants('variant1', 'branch_name')
+      expect(query.query[:variant_uids]).to eq 'variant1'
+      expect(query.query[:branch]).to eq 'branch_name'
+    end
+  end
+
+  describe 'HTTP headers' do
+    it 'sends x-cs-variant-uid and branch for a single entry fetch' do
+      stub = stub_request(:get, /cdn\.contentstack\.io\/v3\/content_types\/category\/entries\/uid/).
+        with { |req|
+          req.headers['X-Cs-Variant-Uid'] == 'variant1' &&
+            req.headers['Branch'] == 'branch_name'
+        }.
+        to_return(status: 200, body: File.read(File.dirname(__FILE__) + '/fixtures/category_entry.json'), headers: {})
+
+      category_entry.variants('variant1', 'branch_name').fetch
+      expect(stub).to have_been_requested
+    end
+
+    it 'sends comma-separated variant UIDs for multiple variants' do
+      stub = stub_request(:get, /cdn\.contentstack\.io\/v3\/content_types\/category\/entries\/uid/).
+        with { |req| req.headers['X-Cs-Variant-Uid'] == 'variant1, variant2' }.
+        to_return(status: 200, body: File.read(File.dirname(__FILE__) + '/fixtures/category_entry.json'), headers: {})
+
+      category_entry.variants(['variant1', 'variant2'], 'branch_name').fetch
+      expect(stub).to have_been_requested
+    end
+
+    it 'sends x-cs-variant-uid and branch for an entries query' do
+      stub = stub_request(:get, /cdn\.contentstack\.io\/v3\/content_types\/category\/entries/).
+        with { |req|
+          !req.uri.path.include?('/entries/uid') &&
+            req.headers['X-Cs-Variant-Uid'] == 'variant1' &&
+            req.headers['Branch'] == 'branch_name'
+        }.
+        to_return(status: 200, body: File.read(File.dirname(__FILE__) + '/fixtures/category_entry_collection_without_count.json'), headers: {})
+
+      category_query.variants('variant1', 'branch_name').fetch
+      expect(stub).to have_been_requested
+    end
+
+    it 'uses stack-level branch when variants branch is omitted' do
+      stub = stub_request(:get, /cdn\.contentstack\.io\/v3\/content_types\/category\/entries\/uid/).
+        with { |req|
+          req.headers['X-Cs-Variant-Uid'] == 'variant1' &&
+            req.headers['Branch'] == 'stack_branch'
+        }.
+        to_return(status: 200, body: File.read(File.dirname(__FILE__) + '/fixtures/category_entry.json'), headers: {})
+
+      branch_client.content_type('category').entry(entry_uid).variants('variant1').fetch
+      expect(stub).to have_been_requested
+    end
+
+    it 'does not add variant headers when variants is not chained' do
+      stub = stub_request(:get, /cdn\.contentstack\.io\/v3\/content_types\/category\/entries\/uid/).
+        with { |req| req.headers['X-Cs-Variant-Uid'].nil? }.
+        to_return(status: 200, body: File.read(File.dirname(__FILE__) + '/fixtures/category_entry.json'), headers: {})
+
+      category_entry.fetch
+      expect(stub).to have_been_requested
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: contentstack
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.10.0
 platform: ruby
 authors:
 - Contentstack
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-29 00:00:00.000000000 Z
+date: 2026-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -106,7 +106,6 @@ files:
 - ".github/workflows/back-merge-pr.yml"
 - ".github/workflows/check-version-bump.yml"
 - ".github/workflows/codeql-analysis.yml"
-- ".github/workflows/issues-jira.yml"
 - ".github/workflows/policy-scan.yml"
 - ".github/workflows/release-gem.yml"
 - ".github/workflows/sca-scan.yml"
@@ -168,6 +167,7 @@ files:
 - spec/spec_helper.rb
 - spec/support/load_test_env.rb
 - spec/sync_spec.rb
+- spec/variants_spec.rb
 homepage: https://github.com/contentstack/contentstack-ruby
 licenses:
 - MIT

data/.github/workflows/issues-jira.yml

@@ -1,118 +0,0 @@
-name: Create Jira Ticket for Github Issue
-
-on:
-  issues:
-    types: [opened, reopened]
-
-jobs:
-  issue-jira:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Create Jira Issue
-        id: create_jira
-        uses: actions/github-script@v9
-        with:
-          script: |
-            const baseUrl = process.env.JIRA_BASE_URL;
-            const userEmail = process.env.JIRA_USER_EMAIL;
-            const jiraToken = process.env.JIRA_API_TOKEN;
-            const jiraProject = process.env.JIRA_PROJECT;
-            const jiraIssueType = process.env.JIRA_ISSUE_TYPE;
-            const jiraFields = JSON.parse(process.env.ISSUES_JIRA_FIELDS);
-
-            let requestBody = JSON.stringify({
-                fields: {
-                    ...jiraFields,
-                    "project": {
-                        "key": jiraProject
-                    },
-                    "issuetype": {
-                        "name": jiraIssueType
-                    },
-                    "summary": "Github | Issue | ${{ github.event.repository.name }} | ${{ github.event.issue.title }}",
-                    "description": {
-                        "version": 1,
-                        "type": "doc",
-                        "content": [
-                            {
-                                "type": "paragraph",
-                                "content": [
-                                    {
-                                        "type": "text",
-                                        "text": "Github Issue",
-                                        "marks": [
-                                            {
-                                                "type": "strong"
-                                            }
-                                        ]
-                                    },
-                                    {
-                                        "type": "text",
-                                        "text": ":   "
-                                    },
-                                    {
-                                        "type": "text",
-                                        "text": "${{ github.event.issue.html_url }}",
-                                        "marks": [
-                                            {
-                                                "type": "link",
-                                                "attrs": {
-                                                    "href": "${{ github.event.issue.html_url }}"
-                                                }
-                                            }
-                                        ]
-                                    }
-                                ]
-                            },
-                            {
-                                "type": "paragraph",
-                                "content": [
-                                    {
-                                        "type": "text",
-                                        "text": "Description",
-                                        "marks": [
-                                            {
-                                                "type": "strong"
-                                            }
-                                        ]
-                                    },
-                                    {
-                                        "type": "text",
-                                        "text": ":"
-                                    }
-                                ]
-                            },
-                            {
-                                "type": "codeBlock",
-                                "content": [
-                                    {
-                                        "type": "text",
-                                        "text": `${{ github.event.issue.body }}`
-                                    }
-                                ]
-                            }
-                        ]
-                    }
-                }
-            });
-
-            const response = await fetch(`${baseUrl}/rest/api/3/issue`, {
-              method: 'POST',
-              headers: {
-                'Content-Type': 'application/json',
-                'Authorization': `Basic ${btoa(userEmail + ":" + jiraToken)}`
-              },
-              body: requestBody
-            });
-            if (!response.ok) {
-              throw new Error(`JIRA API error! Status: ${response.status}`);
-            }
-            const data = await response.json();
-            console.log('Jira Issue Created:', data.key);
-        env:
-          JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }}
-          JIRA_USER_EMAIL: ${{ secrets.JIRA_USER_EMAIL }}
-          JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
-          JIRA_PROJECT: ${{ secrets.JIRA_PROJECT }}
-          JIRA_ISSUE_TYPE: ${{ secrets.JIRA_ISSUE_TYPE }}
-          ISSUES_JIRA_FIELDS: "${{ secrets.ISSUES_JIRA_FIELDS }}"