contentstack_utils 1.2.3 → 1.3.0

data/skills/code-review/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: code-review
+description: Use when reviewing or preparing a PR for this gem—behavior, tests, API compatibility, and release notes.
+---
+
+# Code review – Contentstack Utils Ruby
+
+## When to use
+
+- Authoring a pull request that changes rendering, models, or dependencies
+- Reviewing someone else’s PR before merge
+- Checking release readiness (version + changelog)
+
+## Instructions
+
+### Blockers (fix before merge)
+
+- **Tests:** `bundle exec rake` (or `bundle exec rspec`) passes locally
+- **Breaking API:** unintended removal or signature change of public methods on **`ContentstackUtils`**, **`ContentstackUtils::GQL`**, or **`ContentstackUtils::Model::Options`** without version bump and changelog entry
+- **Security:** no secrets in code, fixtures, or logs; HTML output changes reviewed for injection or XSS risk when embedding untrusted fields
+
+### Major (should address)
+
+- **CHANGELOG.md** updated for user-visible behavior fixes or features
+- **`lib/contentstack_utils/version.rb`** updated when publishing a release (if this PR is release-bound)
+- New JSON/RTE node types or GQL shapes covered by **`spec/lib/utils_spec.rb`** (or focused new spec files)
+- Dependency range changes in **`contentstack_utils.gemspec`** justified and compatible with Ruby **≥ 3.1**
+
+### Minor (nice to have)
+
+- **README.md** examples match actual class names (**`Options`**, not a non-existent **`Option`** unless aliased)
+- YARD or comments only where they clarify non-obvious RTE or GQL mapping
+
+### Process
+
+- Respect **CODEOWNERS** and branch policy (**feature/fix -> `development`**, release PRs **`development` -> `master`**) described in [dev-workflow](../dev-workflow/SKILL.md)
+
+## References
+
+- [AGENTS.md](../../AGENTS.md)
+- [Development workflow](../dev-workflow/SKILL.md)
+- [Contentstack Utils SDK](../contentstack-utils/SKILL.md)
+- [Framework & packaging](../framework/SKILL.md)
+- [Testing](../testing/SKILL.md)

data/skills/contentstack-utils/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: contentstack-utils
+description: Use when changing the public Ruby API, RTE rendering (HTML string or JSON), GQL payloads, Model::Options/Metadata, or integration boundaries with the delivery client.
+---
+
+# Contentstack Utils SDK – Contentstack Utils Ruby
+
+## When to use
+
+- Implementing or fixing HTML output for rich text / JSON RTE
+- Extending or subclassing rendering options (`ContentstackUtils::Model::Options`)
+- Parsing GraphQL-shaped RTE (`ContentstackUtils::GQL`)
+- Changing load paths or public entry points under `lib/` (gemspec and dependency ranges: see [framework](../framework/SKILL.md))
+
+## Instructions
+
+### Entry points
+
+- **`lib/contentstack_utils.rb`** — requires version and `utils`
+- **`lib/contentstack_utils/utils.rb`** — main module **`ContentstackUtils`** with class methods:
+  - **`render_content(content, options)`** — legacy HTML string RTE (array of strings or single string); uses Nokogiri and `_embedded_items` on the entry passed via options
+  - **`json_to_html(content, options)`** — JSON RTE document tree (Hash/Array) for CDA-style payloads with embedded items on the entry
+  - Internal helpers such as **`json_doc_to_html`** (used by GQL path)
+- **`ContentstackUtils::GQL`** — **`json_to_html(content, options)`** for GraphQL responses: expects keys like `json` and optional `embedded_itemsConnection.edges`; reuses `ContentstackUtils.json_doc_to_html` with a GQL-specific reference resolver
+
+### Models and extension points
+
+- **`ContentstackUtils::Model::Options`** (`lib/contentstack_utils/model/options.rb`) — default **`render_option`**, **`render_mark`**, **`render_node`**; subclass for custom HTML (see tests under `spec/mock/custom_render_option.rb`)
+- **`ContentstackUtils::Model::Metadata`** — built from DOM nodes (HTML path) or JSON reference nodes
+- **`ContentstackUtils::Interface::Rendarable`** (`lib/contentstack_utils/interface/renderable.rb`) — base for options; implement **`render_option`** in subclasses
+
+### Data contracts
+
+- **CDA / delivery JSON path:** options may carry an **`entry`** hash with **`_embedded_items`** keyed by field UIDs
+- **GQL path:** payload uses **`embedded_itemsConnection.edges`** with **`node`** objects; reference resolution matches **`metadata.item_uid`** to **`node.system.uid`**
+
+### Boundaries
+
+- HTTP and stack access belong to the separate **Contentstack Ruby** client; this gem only renders given content + embedded metadata
+
+### Versioning
+
+- Public API and behavior changes should be reflected in `CHANGELOG.md` and `lib/contentstack_utils/version.rb`
+
+## References
+
+- Product overview: [README.md](../../README.md)
+- [Framework & packaging](../framework/SKILL.md)
+- [Testing](../testing/SKILL.md)
+- [Ruby style and layout](../ruby-style/SKILL.md)
+- [Contentstack documentation](https://www.contentstack.com/docs/)

data/skills/dev-workflow/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: dev-workflow
+description: Use when setting up the dev environment, running build/test/docs, or understanding CI, branches, and gem release for this repo.
+---
+
+# Development workflow – Contentstack Utils Ruby
+
+## When to use
+
+- Cloning the repo or onboarding a new contributor
+- Running tests, generating docs, or building the gem locally
+- Understanding branch rules and GitHub Actions for this repository
+
+## Instructions
+
+### Prerequisites
+
+- Ruby **≥ 3.1** (matches `s.required_ruby_version` in `contentstack_utils.gemspec`)
+- Bundler; install gems with `bundle install`
+
+### Everyday commands
+
+- **Run tests (default Rake task):** `bundle exec rake` or `bundle exec rake spec`
+- **RSpec directly:** `bundle exec rspec` (pattern `spec/**/*_spec.rb` is configured in `Rakefile`)
+- **YARD API docs:** `bundle exec rake yard` (see `.yardopts` for included paths)
+- **Build gem artifact:** `gem build contentstack_utils.gemspec` (also used in `.github/workflows/release-gem.yml`)
+
+### Version and changelog
+
+- Gem version lives in `lib/contentstack_utils/version.rb` as `ContentstackUtils::VERSION`
+- Document user-visible changes in `CHANGELOG.md` when releasing
+
+### Branches and PRs
+
+- 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 (`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`
+
+### Optional housekeeping
+
+- `.talismanrc` is used for secret scanning hooks in some environments; do not commit credentials or tokens
+
+## References
+
+- [AGENTS.md](../../AGENTS.md)
+- [Contentstack Utils SDK](../contentstack-utils/SKILL.md)
+- [Framework & packaging](../framework/SKILL.md)
+- [Testing](../testing/SKILL.md)

data/skills/framework/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: framework
+description: Use when changing the gemspec, Bundler setup, Ruby/runtime constraints, or runtime dependencies (activesupport, nokogiri) and native extension implications.
+---
+
+# Framework & packaging – Contentstack Utils Ruby
+
+## When to use
+
+- Editing **`contentstack_utils.gemspec`** (dependencies, `required_ruby_version`, files list)
+- Changing **`Gemfile`** / **`Gemfile.lock`** workflow or documenting install for contributors
+- Evaluating impact of **nokogiri** (native extension) or **activesupport** version ranges on consumers
+
+## Instructions
+
+### Gem definition
+
+- **`contentstack_utils.gemspec`** — canonical metadata: `s.files` from `git ls-files`, `spec/` as test files, `lib` as `require_paths`
+- **`Gemfile`** — `gemspec` only; runtime and development dependencies are declared in the gemspec
+
+### Runtime dependencies (as shipped)
+
+- **activesupport** `>= 7.0`, `< 8`
+- **nokogiri** `>= 1.13`, `< 1.19` — HTML/XML parsing for legacy string RTE paths; consumers need a compatible platform build
+
+### Development dependencies
+
+- **rake**, **rspec**, **webmock**, **simplecov**, **yard** — see gemspec; used for tasks in `Rakefile` and CI-style local checks
+
+### Ruby version
+
+- **`s.required_ruby_version`** is **>= 3.1**; `.ruby-version` pins a team default for local dev
+- **Release workflow** (`.github/workflows/release-gem.yml`) uses its own Ruby pin for `gem build` / `gem push`; keep it aligned with gemspec when updating
+
+### Build and publish
+
+- Local artifact: `gem build contentstack_utils.gemspec`
+- Publishing runs when a GitHub **Release** is created (`release: types: [created]`) for tag **`v*`** (draft releases skipped); see `release-gem.yml`.
+
+## References
+
+- [Development workflow](../dev-workflow/SKILL.md)
+- [Contentstack Utils SDK](../contentstack-utils/SKILL.md)
+- [Ruby style and layout](../ruby-style/SKILL.md)

data/skills/ruby-style/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: ruby-style
+description: Use when editing Ruby in this repo—module layout, require paths, and staying consistent with existing style (not introducing a new linter config).
+---
+
+# Ruby style and layout – Contentstack Utils Ruby
+
+## When to use
+
+- Adding new `.rb` files under `lib/` or `spec/`
+- Refactoring while keeping diffs readable for reviewers
+- Deciding where a new helper or model class should live
+
+## Instructions
+
+### Layout
+
+- **Library code:** `lib/contentstack_utils/` with nested folders `model/`, `interface/`, `support/`
+- **Top-level require:** `lib/contentstack_utils.rb` should stay a thin loader
+- **Specs:** mirror behavior under `spec/lib/` and `spec/mock/` / `spec/support/` as in existing examples
+
+### Conventions in this codebase
+
+- **`ContentstackUtils`** as the root module; nested **`Model`**, **`Interface`**, **`GQL`** as already used
+- **`require_relative`** for internal lib files (see `utils.rb`, `options.rb`)
+- Existing files use a mix of spacing and `def self.` patterns; **prefer matching the surrounding file** over wholesale reformatting
+- Typo in base class name **`Rendarable`** is historical; new code should remain compatible unless a dedicated rename is approved project-wide
+
+### Linting and format
+
+- There is **no RuboCop or Standard** configuration in this repository; do not add large style-only churn unless the team adopts a formatter
+- Run **`bundle exec rake spec`** before pushing substantive changes
+
+### Documentation
+
+- YARD can document public APIs; keep user-facing usage examples in `README.md` accurate (e.g. class name **`Options`** vs informal “Option” in prose)
+
+## References
+
+- [Contentstack Utils SDK](../contentstack-utils/SKILL.md)
+- [Framework & packaging](../framework/SKILL.md)
+- [Development workflow](../dev-workflow/SKILL.md)

data/skills/testing/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: testing
+description: Use when writing or fixing RSpec tests, mocks, fixtures, SimpleCov filters, or WebMock usage in this repo.
+---
+
+# Testing – Contentstack Utils Ruby
+
+## When to use
+
+- Adding coverage for a new code path in `lib/`
+- Debugging a failing spec in `spec/`
+- Adjusting SimpleCov scope or shared test helpers
+
+## Instructions
+
+### Runner and config
+
+- **RSpec** is the test framework; **`spec/spec_helper.rb`** loads SimpleCov, then `contentstack_utils`, mocks, and support files
+- **Default task:** `bundle exec rake` runs **`spec`** with `--format documentation` (see `Rakefile`)
+
+### Layout
+
+- **`spec/lib/`** — primary examples (`utils_spec.rb`, `model/option_spec.rb`, `model/metadata_spec.rb`)
+- **`spec/mock/`** — constants and custom option subclasses used across examples
+- **`spec/support/`** — helpers (e.g. XML/JSON fixture builders like `getGQLJSONRTE`)
+
+### Coverage
+
+- **SimpleCov** starts in `spec_helper.rb` and **filters** `spec/` and `lib/contentstack_utils/support` from coverage metrics
+- Aim to cover both **HTML `render_content`** paths and **JSON / GQL `json_to_html`** branches when changing `utils.rb`
+
+### HTTP and external I/O
+
+- **webmock** is a development dependency; stub outbound HTTP if future tests introduce network calls (current suite is largely pure parsing/rendering)
+
+### Credentials
+
+- Do not add real API keys, delivery tokens, or stack secrets to the repo; use fixture hashes and constants as in `spec/mock/` and `spec/support/constant.rb`
+
+## References
+
+- [Development workflow](../dev-workflow/SKILL.md)
+- [Contentstack Utils SDK](../contentstack-utils/SKILL.md)
+- [RSpec](https://rspec.info/)
+- [SimpleCov](https://github.com/simplecov-ruby/simplecov)

data/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