reactor_sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0aa1ebc8313c5d522d17ac36860404dddb917ff6b92df673f1b6161b28a78523
+  data.tar.gz: 9ffc87d3a9413abfffdfd0b15b9e3a3d8b42721f7d80d0c2eaf481fec0ac93ee
+SHA512:
+  metadata.gz: 67970e3f8a09bd53c7654fb71b104e76ca12318f0dec8745aa4a84a0c1f62217fdd4f91f199c0218f613ffe05a25153d91f885d9c1ebb21d5fd49ce2260142b8
+  data.tar.gz: 65a4ecb927896f6bddd075916ed172b1e1653446c87c41120524614303d975646cff5416725e5828543a7f310ddc64cfa39f1a2700d5928701dfbb8f273aa156

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+## [0.1.0] - 2026-04-01
+
+- Added support for app configurations, callbacks, secrets, extension packages,
+  extension package usage authorizations, profile lookup, search, and direct
+  note lookup to align the SDK with Adobe's current Reactor endpoint families.
+- Added missing relationship and maintenance operations across properties,
+  extensions, libraries, builds, rules, rule components, and notes-bearing
+  resources.
+- Corrected audit event listing to use Adobe's current global `/audit_events`
+  endpoint while keeping `list_for_property` as a backward-compatible wrapper.
+- Added multipart extension package upload support and coverage for the new
+  endpoint surface.
+- Added contributor and security documentation for open source maintenance.
+- Added a pinned `.ruby-version` to align local development with CI.
+- Expanded CI and core infrastructure test coverage.
+- Aligned gem metadata and install documentation with the published gem name.
+- Documented current Adobe Reactor API coverage and multi-client usage patterns.
+- Added test coverage proving separate client instances keep credentials isolated.
+- Initial public release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dhairya Gabhawala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,281 @@
+<p align="center">
+  <img src=".github/assets/reactor-sdk-lockup.svg" alt="ReactorSDK" width="520">
+</p>
+
+<p align="center">
+  <a href="https://github.com/dhairyagabha/reactor_sdk/actions/workflows/main.yml">
+    <img src="https://github.com/dhairyagabha/reactor_sdk/actions/workflows/main.yml/badge.svg" alt="CI">
+  </a>
+  <a href="https://rubygems.org/gems/reactor_sdk">
+    <img src="https://img.shields.io/gem/v/reactor_sdk.svg" alt="RubyGems version">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://reactor-sdk.dhairyagabhawala.com">Documentation</a>
+  ·
+  <a href="https://github.com/dhairyagabha/reactor_sdk/blob/main/CHANGELOG.md">Changelog</a>
+  ·
+  <a href="https://rubygems.org/gems/reactor_sdk">RubyGems</a>
+  ·
+  <a href="https://github.com/dhairyagabha/reactor_sdk">GitHub</a>
+</p>
+
+# ReactorSDK
+
+`reactor_sdk` is a Ruby SDK for the Adobe Launch / Data Collection Reactor API. It handles OAuth Server-to-Server authentication, JSON:API parsing, pagination, retries, rate limiting, revision snapshots, and review-friendly comparison helpers so application code can work with typed Ruby objects instead of raw HTTP payloads.
+
+## Features
+
+- OAuth Server-to-Server authentication with automatic token refresh
+- Typed resource objects across companies, properties, rules, data elements, extensions, libraries, builds, revisions, notes, and more
+- Automatic pagination for list endpoints
+- Consistent error classes and retry behavior around Adobe API failures
+- Library-aware review helpers for rules, data elements, and extensions
+- Upstream-chain lookup for resource review across Development, Staging, and Production
+- Library-to-library comparison output with status, revision IDs, and normalized review payloads
+
+## Installation
+
+Add the gem to your application:
+
+```ruby
+gem "reactor_sdk"
+```
+
+Then install it:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install reactor_sdk
+```
+
+## Authentication and Configuration
+
+ReactorSDK uses Adobe OAuth Server-to-Server credentials. JWT / Service Account credentials are not supported.
+
+```ruby
+require "reactor_sdk"
+
+client = ReactorSDK::Client.new(
+  client_id: ENV.fetch("ADOBE_CLIENT_ID"),
+  client_secret: ENV.fetch("ADOBE_CLIENT_SECRET"),
+  org_id: ENV.fetch("ADOBE_IMS_ORG_ID")
+)
+```
+
+Optional configuration is passed to the same client constructor:
+
+```ruby
+client = ReactorSDK::Client.new(
+  client_id: "your-client-id",
+  client_secret: "your-client-secret",
+  org_id: "your-org-id@AdobeOrg",
+  base_url: "https://reactor.adobe.io",
+  ims_token_url: "https://ims-na1.adobelogin.com/ims/token/v3",
+  timeout: 30,
+  logger: Logger.new($stdout),
+  auto_refresh_token: true
+)
+```
+
+## Quick Start
+
+```ruby
+require "reactor_sdk"
+
+client = ReactorSDK::Client.new(
+  client_id: ENV.fetch("ADOBE_CLIENT_ID"),
+  client_secret: ENV.fetch("ADOBE_CLIENT_SECRET"),
+  org_id: ENV.fetch("ADOBE_IMS_ORG_ID")
+)
+
+# List companies available to the credential set.
+companies = client.companies.list
+company = companies.first
+
+# List properties inside the company.
+properties = client.properties.list_for_company(company.id)
+property = properties.first
+
+# List rules in the property.
+rules = client.rules.list_for_property(property.id)
+puts rules.first&.name
+```
+
+## Review and Promotion Workflows
+
+ReactorSDK includes higher-level helpers for review tooling and release workflows, not just CRUD wrappers.
+
+### Work with a Library Snapshot
+
+```ruby
+# LB_DEV = development library ID.
+# PR123 = property ID.
+snapshot = client.libraries.find_snapshot("LB_DEV", property_id: "PR123")
+
+# Point-in-time rule components associated with the rule inside this library snapshot.
+snapshot.rule_components_for_rule("RL123").map(&:id)
+
+# Snapshot-scoped impact analysis for a data element.
+snapshot.impacted_rules_for("DE123").map(&:name)
+```
+
+### Build Comprehensive Review Objects
+
+```ruby
+rule_review = client.rules.find_comprehensive(
+  "RL123",
+  library_id: "LB_DEV",
+  property_id: "PR123"
+)
+
+data_element_review = client.data_elements.find_comprehensive(
+  "DE123",
+  library_id: "LB_DEV",
+  property_id: "PR123"
+)
+
+extension_review = client.extensions.find_comprehensive(
+  "EX123",
+  library_id: "LB_DEV",
+  property_id: "PR123"
+)
+
+puts rule_review.normalized_json
+puts data_element_review.normalized_json
+puts extension_review.normalized_json
+```
+
+These comprehensive review objects include the resource plus the associated records a reviewer usually needs:
+
+- Rules include rule components
+- Data elements include referenced data elements and impacted rules
+- Extensions include dependent data elements, rule components, and rules
+
+### Resolve Upstream Versions
+
+```ruby
+chain = client.rules.comprehensive_upstream_chain(
+  "RL123",
+  library_id: "LB_DEV",
+  property_id: "PR123"
+)
+
+staging_entry = chain.entries.find { |entry| entry.stage == "staging" }
+
+puts chain.target_revision_id
+puts staging_entry&.revision_id
+puts staging_entry&.normalized_json
+```
+
+### Compare Two Libraries
+
+```ruby
+# Compare Development against Staging.
+comparison = client.libraries.compare(
+  "LB_DEV",
+  baseline_library_id: "LB_STG",
+  property_id: "PR123"
+)
+
+comparison.entries.each do |entry|
+  puts "#{entry.resource_type} #{entry.resource_id} #{entry.status}"
+  puts entry.current_revision_id
+  puts entry.baseline_revision_id
+end
+
+# Inspect normalized output for one entry.
+entry = comparison.entries.first
+puts entry.current_normalized_json
+puts entry.baseline_normalized_json
+```
+
+Sample comparison output:
+
+```ruby
+# Example status rows you might print from comparison.entries:
+# rules RL100 modified
+# current revision  = RE_CUR_RULE
+# baseline revision = RE_BASE_RULE
+#
+# rules RL200 added
+# current revision  = RE_ADDED
+# baseline revision = nil
+#
+# data_elements DE200 removed
+# current revision  = nil
+# baseline revision = RE_REMOVED
+#
+# extensions EX100 unchanged
+# current revision  = RE_EX
+# baseline revision = RE_EX
+```
+
+Comparison is performed across the library's top-level rules, data elements, and extensions. Rule components are still included in the comprehensive rule payload so rule diffs remain readable.
+
+## Endpoint Coverage
+
+The SDK currently exposes these endpoint families:
+
+- Companies
+- Properties
+- App configurations
+- Callbacks
+- Secrets
+- Environments
+- Hosts
+- Rules
+- Rule components
+- Data elements
+- Extensions
+- Extension packages
+- Extension package usage authorizations
+- Libraries
+- Builds
+- Revisions
+- Notes
+- Audit events
+- Profiles
+- Search
+
+## Documentation
+
+Full guides, API reference pages, example payloads, and review-workflow documentation are available at:
+
+- https://reactor-sdk.dhairyagabhawala.com
+
+## Development
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+Run RuboCop:
+
+```bash
+bundle exec rubocop
+```
+
+Build the gem:
+
+```bash
+gem build reactor_sdk.gemspec
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution and development guidance.

data/lib/reactor_sdk/authentication.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+##
+# @file authentication.rb
+# @description Handles Adobe IMS OAuth Server-to-Server authentication.
+#
+#   Fetches and caches access tokens using the client_credentials grant.
+#   Tokens are refreshed automatically when within REFRESH_BUFFER_SECONDS
+#   of expiry. Thread-safe via Mutex.
+#
+#   Adobe deprecated JWT (Service Account) authentication on January 1 2025.
+#   This implementation uses OAuth Server-to-Server only.
+#
+#   The token URL is read from config rather than hardcoded so that tests
+#   can override it via Configuration's ims_token_url parameter without
+#   any monkey-patching or global state changes.
+#
+# @domain Infrastructure
+# @depends ReactorSDK::Configuration
+#
+# @see https://developer.adobe.com/developer-console/docs/guides/authentication/ServerToServerAuthentication/
+#
+
+module ReactorSDK
+  class Authentication
+    # Adobe IMS token endpoint — single global endpoint for all regions
+    # Read by Configuration as its default value for ims_token_url
+    IMS_TOKEN_URL = 'https://ims-na1.adobelogin.com/ims/token/v3'
+
+    # Refresh the token this many seconds before actual expiry.
+    # Prevents edge cases where a token expires between check and use.
+    REFRESH_BUFFER_SECONDS = 300
+
+    # Required OAuth scopes for full Reactor API access
+    REACTOR_SCOPE = [
+      'openid',
+      'AdobeID',
+      'read_organizations',
+      'additional_info.projectedProductContext'
+    ].join(',').freeze
+
+    ##
+    # @param config [ReactorSDK::Configuration] SDK configuration instance
+    #
+    def initialize(config)
+      @config       = config
+      @token        = nil
+      @token_expiry = nil
+      @mutex        = Mutex.new
+    end
+
+    ##
+    # Returns a valid access token, fetching or refreshing if necessary.
+    # Thread-safe — uses a Mutex to prevent parallel token fetches in
+    # multi-threaded environments such as Puma.
+    #
+    # @return [String] Valid Adobe IMS Bearer access token
+    # @raise  [ReactorSDK::AuthenticationError] if the token request fails
+    #
+    def access_token
+      @mutex.synchronize do
+        fetch_token if token_expired?
+        @token
+      end
+    end
+
+    private
+
+    ##
+    # Returns true if the token is missing or within the refresh buffer window.
+    #
+    # @return [Boolean]
+    #
+    def token_expired?
+      @token.nil? ||
+        Time.now.utc >= (@token_expiry - REFRESH_BUFFER_SECONDS)
+    end
+
+    ##
+    # Fetches a fresh access token from Adobe IMS using client_credentials grant.
+    # Uses @config.ims_token_url so tests can intercept without hitting Adobe.
+    #
+    # @raise [ReactorSDK::AuthenticationError] if the IMS request fails
+    # @sideeffect Sets @token and @token_expiry
+    #
+    def fetch_token
+      response = Faraday.post(@config.ims_token_url, token_request_params)
+
+      unless response.success?
+        raise AuthenticationError.new(
+          "Adobe IMS token request failed (HTTP #{response.status}). " \
+          'Check your client_id and client_secret.',
+          status: response.status
+        )
+      end
+
+      parse_token_response(response.body)
+    rescue Faraday::Error => e
+      raise AuthenticationError.new(
+        "Network error during token fetch: #{e.message}",
+        cause: e
+      )
+    end
+
+    ##
+    # Builds the POST body parameters for the IMS token request.
+    #
+    # @return [Hash] Form-encoded parameters for the IMS endpoint
+    #
+    def token_request_params
+      {
+        grant_type: 'client_credentials',
+        client_id: @config.client_id,
+        client_secret: @config.client_secret,
+        scope: REACTOR_SCOPE
+      }
+    end
+
+    ##
+    # Parses the JSON response and stores the token and its expiry time.
+    #
+    # @param body [String] Raw JSON response body from Adobe IMS
+    # @raise [ReactorSDK::AuthenticationError] if body is not valid JSON
+    # @sideeffect Sets @token and @token_expiry
+    #
+    def parse_token_response(body)
+      data          = JSON.parse(body)
+      @token        = data.fetch('access_token')
+      @token_expiry = Time.now.utc + data.fetch('expires_in').to_i
+    rescue JSON::ParserError, KeyError => e
+      raise AuthenticationError.new(
+        'Could not parse Adobe IMS token response',
+        cause: e
+      )
+    end
+  end
+end

data/lib/reactor_sdk/client.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+##
+# @file client.rb
+# @description Main entry point for the ReactorSDK gem.
+#
+#   Instantiate one client per Adobe org. The client wires together all
+#   infrastructure and exposes every endpoint group as a named method.
+#
+# @example Basic usage
+#   client = ReactorSDK::Client.new(
+#     client_id:     ENV["ADOBE_CLIENT_ID"],
+#     client_secret: ENV["ADOBE_CLIENT_SECRET"],
+#     org_id:        ENV["ADOBE_IMS_ORG_ID"]
+#   )
+#
+#   # Fetch hosts before creating an environment
+#   hosts = client.hosts.list_for_property("PR123")
+#   client.environments.create(
+#     property_id: "PR123",
+#     name:        "jsmith-dev",
+#     stage:       "development",
+#     host_id:     hosts.first.id
+#   )
+#
+
+module ReactorSDK
+  class Client
+    ENDPOINT_CLASSES = {
+      companies: Endpoints::Companies,
+      properties: Endpoints::Properties,
+      app_configurations: Endpoints::AppConfigurations,
+      callbacks: Endpoints::Callbacks,
+      secrets: Endpoints::Secrets,
+      environments: Endpoints::Environments,
+      hosts: Endpoints::Hosts,
+      rules: Endpoints::Rules,
+      rule_components: Endpoints::RuleComponents,
+      data_elements: Endpoints::DataElements,
+      extensions: Endpoints::Extensions,
+      extension_packages: Endpoints::ExtensionPackages,
+      extension_package_usage_authorizations: Endpoints::ExtensionPackageUsageAuthorizations,
+      libraries: Endpoints::Libraries,
+      builds: Endpoints::Builds,
+      audit_events: Endpoints::AuditEvents,
+      revisions: Endpoints::Revisions,
+      profiles: Endpoints::Profiles,
+      search: Endpoints::Search,
+      notes: Endpoints::Notes
+    }.freeze
+
+    # @return [ReactorSDK::Endpoints::Companies]
+    attr_reader :companies
+
+    # @return [ReactorSDK::Endpoints::Properties]
+    attr_reader :properties
+
+    # @return [ReactorSDK::Endpoints::AppConfigurations]
+    attr_reader :app_configurations
+
+    # @return [ReactorSDK::Endpoints::Callbacks]
+    attr_reader :callbacks
+
+    # @return [ReactorSDK::Endpoints::Secrets]
+    attr_reader :secrets
+
+    # @return [ReactorSDK::Endpoints::Environments]
+    attr_reader :environments
+
+    # @return [ReactorSDK::Endpoints::Hosts]
+    attr_reader :hosts
+
+    # @return [ReactorSDK::Endpoints::Rules]
+    attr_reader :rules
+
+    # @return [ReactorSDK::Endpoints::RuleComponents]
+    attr_reader :rule_components
+
+    # @return [ReactorSDK::Endpoints::DataElements]
+    attr_reader :data_elements
+
+    # @return [ReactorSDK::Endpoints::Extensions]
+    attr_reader :extensions
+
+    # @return [ReactorSDK::Endpoints::ExtensionPackages]
+    attr_reader :extension_packages
+
+    # @return [ReactorSDK::Endpoints::ExtensionPackageUsageAuthorizations]
+    attr_reader :extension_package_usage_authorizations
+
+    # @return [ReactorSDK::Endpoints::Libraries]
+    attr_reader :libraries
+
+    # @return [ReactorSDK::Endpoints::Builds]
+    attr_reader :builds
+
+    # @return [ReactorSDK::Endpoints::AuditEvents]
+    attr_reader :audit_events
+
+    # @return [ReactorSDK::Endpoints::Revisions]
+    attr_reader :revisions
+
+    # @return [ReactorSDK::Endpoints::Profiles]
+    attr_reader :profiles
+
+    # @return [ReactorSDK::Endpoints::Search]
+    attr_reader :search
+
+    # @return [ReactorSDK::Endpoints::Notes]
+    attr_reader :notes
+
+    # @return [ReactorSDK::Configuration]
+    attr_reader :config
+
+    ##
+    # Initializes the client and all infrastructure dependencies.
+    #
+    # @param client_id          [String]  Adobe Developer Console client ID
+    # @param client_secret      [String]  Adobe Developer Console client secret
+    # @param org_id             [String]  Adobe IMS organisation ID
+    # @param base_url           [String]  Override Reactor API base URL (optional)
+    # @param ims_token_url      [String]  Override IMS token URL — for testing (optional)
+    # @param timeout            [Integer] HTTP timeout in seconds (optional)
+    # @param logger             [Logger]  Custom logger (optional)
+    # @param auto_refresh_token [Boolean] Auto-refresh token before expiry (optional)
+    # @raise [ReactorSDK::ConfigurationError] if any required credential is blank
+    #
+    def initialize(
+      client_id:,
+      client_secret:,
+      org_id:,
+      base_url:           Configuration::DEFAULT_BASE_URL,
+      ims_token_url:      Authentication::IMS_TOKEN_URL,
+      timeout:            Configuration::DEFAULT_TIMEOUT,
+      logger:             nil,
+      auto_refresh_token: true
+    )
+      @config = Configuration.new(
+        client_id: client_id,
+        client_secret: client_secret,
+        org_id: org_id,
+        base_url: base_url,
+        ims_token_url: ims_token_url,
+        timeout: timeout,
+        logger: logger,
+        auto_refresh_token: auto_refresh_token
+      )
+
+      build_infrastructure
+      build_endpoints
+    end
+
+    private
+
+    ##
+    # Instantiates all infrastructure objects in dependency order.
+    #
+    # @sideeffect Sets @auth, @rate_limiter, @connection, @paginator, @parser
+    #
+    def build_infrastructure
+      @auth         = Authentication.new(@config)
+      @rate_limiter = RateLimiter.new
+      @connection   = Connection.new(@config, @auth, @rate_limiter)
+      @paginator    = Paginator.new(@connection)
+      @parser       = ResponseParser.new
+    end
+
+    ##
+    # Instantiates all endpoint group objects.
+    # Add new endpoint groups here as they are implemented.
+    #
+    # @sideeffect Sets all endpoint attr_reader values
+    #
+    def build_endpoints
+      deps = {
+        connection: @connection,
+        paginator: @paginator,
+        parser: @parser
+      }
+
+      ENDPOINT_CLASSES.each do |name, endpoint_class|
+        instance_variable_set(:"@#{name}", endpoint_class.new(**deps))
+      end
+    end
+  end
+end