reactor_sdk 0.1.0

data/lib/reactor_sdk/endpoints/rules.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+##
+# @file endpoints/rules.rb
+# @description Endpoint group for Adobe Launch Rule resources.
+#
+#   Rules define the logic Adobe Launch executes. They consist of
+#   conditions (when to run) and actions (what to do). Rules belong
+#   to a property and are versioned — the revisions endpoint provides
+#   point-in-time snapshots used by the diff engine.
+#
+#   Important: rules must be revised before they can be added to a library.
+#   Call revise(rule_id) after creating or updating a rule.
+#
+# @domain Endpoints
+# @see https://developer.adobe.com/experience-platform/documentation/tags/api/endpoints/rules/
+#
+
+module ReactorSDK
+  module Endpoints
+    class Rules < BaseEndpoint
+      ##
+      # Lists all rules for a given property.
+      # Follows pagination automatically — returns all rules.
+      #
+      # @param property_id [String] Adobe property ID
+      # @return [Array<ReactorSDK::Resources::Rule>]
+      # @raise [ReactorSDK::ResourceNotFoundError] if the property does not exist
+      #
+      def list_for_property(property_id)
+        list_resources("/properties/#{property_id}/rules", Resources::Rule)
+      end
+
+      ##
+      # Retrieves a single rule by its Adobe ID.
+      #
+      # @param rule_id [String] Adobe rule ID (format: "RL" + hex string)
+      # @return [ReactorSDK::Resources::Rule]
+      # @raise [ReactorSDK::ResourceNotFoundError] if the rule does not exist
+      #
+      def find(rule_id)
+        fetch_resource("/rules/#{rule_id}", Resources::Rule)
+      end
+
+      ##
+      # Retrieves the property that owns a rule.
+      #
+      # @param rule_id [String] Adobe rule ID
+      # @return [ReactorSDK::Resources::Property]
+      #
+      def property(rule_id)
+        fetch_resource("/rules/#{rule_id}/property", Resources::Property)
+      end
+
+      ##
+      # Lists the libraries containing a rule.
+      #
+      # @param rule_id [String] Adobe rule ID
+      # @return [Array<ReactorSDK::Resources::Library>]
+      #
+      def libraries(rule_id)
+        list_resources("/rules/#{rule_id}/libraries", Resources::Library)
+      end
+
+      ##
+      # Resolves the rule across the ordered upstream library chain.
+      #
+      # This is a convenience wrapper around Libraries#upstream_chain_for_resource
+      # so rule workflows can stay resource-centric at the call site.
+      #
+      # @param rule_or_id [String, ReactorSDK::Resources::Rule]
+      # @param library_id [String] Adobe library ID used as the comparison root
+      # @param property_id [String] Adobe property ID containing the library chain
+      # @return [ReactorSDK::Resources::UpstreamChain]
+      #
+      def upstream_chain(rule_or_id, library_id:, property_id:)
+        libraries_endpoint.upstream_chain_for_resource(
+          rule_or_id,
+          library_id: library_id,
+          property_id: property_id,
+          resource_type: 'rules'
+        )
+      end
+
+      ##
+      # Fetches the rule from a library-context review snapshot together with
+      # its associated rule components and normalized review payload.
+      #
+      # @param rule_id [String]
+      # @param library_id [String]
+      # @param property_id [String]
+      # @return [ReactorSDK::Resources::ComprehensiveRule]
+      #
+      def find_comprehensive(rule_id, library_id:, property_id:)
+        snapshot = libraries_endpoint.find_snapshot(library_id, property_id: property_id)
+        comprehensive = snapshot.comprehensive_resource(rule_id, resource_type: 'rules')
+        unless comprehensive
+          raise ReactorSDK::ResourceNotFoundError,
+                "Rule #{rule_id} was not found in library #{library_id}"
+        end
+
+        comprehensive
+      end
+
+      ##
+      # Resolves the rule across the ordered upstream chain and returns
+      # comprehensive review objects for the target and upstream entries.
+      #
+      # @param rule_or_id [String, ReactorSDK::Resources::Rule]
+      # @param library_id [String]
+      # @param property_id [String]
+      # @return [ReactorSDK::Resources::ComprehensiveUpstreamChain]
+      #
+      def comprehensive_upstream_chain(rule_or_id, library_id:, property_id:)
+        libraries_endpoint.comprehensive_upstream_chain_for_resource(
+          rule_or_id,
+          library_id: library_id,
+          property_id: property_id,
+          resource_type: 'rules'
+        )
+      end
+
+      ##
+      # Retrieves the origin revision head for a rule.
+      #
+      # @param rule_id [String] Adobe rule ID
+      # @return [ReactorSDK::Resources::Rule]
+      #
+      def origin(rule_id)
+        fetch_resource("/rules/#{rule_id}/origin", Resources::Rule)
+      end
+
+      ##
+      # Creates a new rule within a property.
+      #
+      # @param property_id [String]  Adobe property ID
+      # @param name        [String]  Display name for the rule
+      # @param enabled     [Boolean] Whether the rule is enabled (default: true)
+      # @return [ReactorSDK::Resources::Rule] The newly created rule
+      # @raise [ReactorSDK::UnprocessableEntityError] if attributes are invalid
+      #
+      def create(property_id:, name:, enabled: true)
+        create_resource(
+          "/properties/#{property_id}/rules",
+          'rules',
+          Resources::Rule,
+          attributes: { name: name, enabled: enabled }
+        )
+      end
+
+      ##
+      # Updates an existing rule.
+      #
+      # @param rule_id    [String] Adobe rule ID
+      # @param attributes [Hash]   Fields to update (e.g. { name: "New Name" })
+      # @return [ReactorSDK::Resources::Rule] The updated rule
+      # @raise [ReactorSDK::ResourceNotFoundError] if the rule does not exist
+      #
+      def update(rule_id, attributes)
+        update_resource("/rules/#{rule_id}", rule_id, 'rules', Resources::Rule, attributes: attributes)
+      end
+
+      ##
+      # Revises a rule so it can be added to a library.
+      #
+      # Adobe Launch requires every resource to be explicitly revised before
+      # it can be added to a library. A newly created or updated rule cannot
+      # be added to a library until revised.
+      #
+      # Always call revise after create or update, before libraries.add_rules.
+      #
+      # @param rule_id [String] Adobe rule ID
+      # @return [ReactorSDK::Resources::Rule] The revised rule
+      # @raise [ReactorSDK::ResourceNotFoundError] if the rule does not exist
+      #
+      def revise(rule_id)
+        update_resource(
+          "/rules/#{rule_id}",
+          rule_id,
+          'rules',
+          Resources::Rule,
+          attributes: {},
+          meta: { action: 'revise' }
+        )
+      end
+
+      ##
+      # Deletes a rule permanently.
+      #
+      # @param rule_id [String] Adobe rule ID
+      # @return [nil]
+      # @raise [ReactorSDK::ResourceNotFoundError] if the rule does not exist
+      #
+      def delete(rule_id)
+        delete_resource("/rules/#{rule_id}")
+      end
+
+      ##
+      # Creates a note on a rule.
+      #
+      # @param rule_id [String] Adobe rule ID
+      # @param text    [String] Note body text
+      # @return [ReactorSDK::Resources::Note]
+      #
+      def create_note(rule_id, text)
+        create_note_for_path("/rules/#{rule_id}/notes", text)
+      end
+
+      ##
+      # Lists notes attached directly to a rule.
+      #
+      # @param rule_id [String]
+      # @return [Array<ReactorSDK::Resources::Note>]
+      #
+      def list_notes(rule_id)
+        list_notes_for_path("/rules/#{rule_id}/notes")
+      end
+
+      ##
+      # Lists rule components associated with the rule's component notes route.
+      #
+      # @param rule_id [String]
+      # @return [Array<ReactorSDK::Resources::RuleComponent>]
+      #
+      def rule_component_notes(rule_id)
+        list_resources("/rules/#{rule_id}/rule_component_notes", Resources::RuleComponent)
+      end
+
+      private
+
+      def libraries_endpoint
+        @libraries_endpoint ||= Endpoints::Libraries.new(
+          connection: @connection,
+          paginator: @paginator,
+          parser: @parser
+        )
+      end
+    end
+  end
+end

data/lib/reactor_sdk/endpoints/search.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ReactorSDK
+  module Endpoints
+    class Search < BaseEndpoint
+      def perform(query:, from: nil, size: nil, sort: nil, resource_types: nil)
+        payload = { query: query }
+        payload[:from] = from unless from.nil?
+        payload[:size] = size unless size.nil?
+        payload[:sort] = sort unless sort.nil?
+        payload[:resource_types] = resource_types unless resource_types.nil?
+
+        response = @connection.post('/search', payload)
+        Resources::SearchResults.new(
+          results: @parser.parse_many_auto(response['data']),
+          meta: response.fetch('meta', {})
+        )
+      end
+
+      alias query perform
+    end
+  end
+end

data/lib/reactor_sdk/endpoints/secrets.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module ReactorSDK
+  module Endpoints
+    class Secrets < BaseEndpoint
+      def list_for_property(property_id)
+        list_resources("/properties/#{property_id}/secrets", Resources::Secret)
+      end
+
+      def list_for_environment(environment_id)
+        list_resources("/environments/#{environment_id}/secrets", Resources::Secret)
+      end
+
+      def find(secret_id)
+        fetch_resource("/secrets/#{secret_id}", Resources::Secret)
+      end
+
+      def create(property_id:, environment_id:, attributes:)
+        create_resource(
+          "/properties/#{property_id}/secrets",
+          'secrets',
+          Resources::Secret,
+          attributes: attributes,
+          relationships: {
+            environment: {
+              data: { id: environment_id, type: 'environments' }
+            }
+          }
+        )
+      end
+
+      def test_or_retry(secret_id, type_of:, action:)
+        update_resource(
+          "/secrets/#{secret_id}",
+          secret_id,
+          'secrets',
+          Resources::Secret,
+          attributes: { type_of: type_of },
+          meta: { action: action }
+        )
+      end
+
+      def test(secret_id, type_of:)
+        test_or_retry(secret_id, type_of: type_of, action: 'test')
+      end
+
+      def retry(secret_id, type_of:)
+        test_or_retry(secret_id, type_of: type_of, action: 'retry')
+      end
+
+      def delete(secret_id)
+        delete_resource("/secrets/#{secret_id}")
+      end
+
+      def data_elements(secret_id)
+        list_resources("/secrets/#{secret_id}/data_elements", Resources::DataElement)
+      end
+
+      def environment(secret_id)
+        fetch_resource("/secrets/#{secret_id}/environment", Resources::Environment)
+      end
+
+      def property(secret_id)
+        fetch_resource("/secrets/#{secret_id}/property", Resources::Property)
+      end
+
+      def list_notes(secret_id)
+        list_notes_for_path("/secrets/#{secret_id}/notes")
+      end
+
+      def create_note(secret_id, text)
+        create_note_for_path("/secrets/#{secret_id}/notes", text)
+      end
+    end
+  end
+end

data/lib/reactor_sdk/error.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+##
+# @file error.rb
+# @description Typed error hierarchy for the ReactorSDK gem.
+#
+#   All errors inherit from ReactorSDK::Error so callers can rescue
+#   broadly or narrowly depending on their needs.
+#
+#   Rescue broadly:
+#     rescue ReactorSDK::Error => e
+#
+#   Rescue specifically:
+#     rescue ReactorSDK::RateLimitError => e
+#       sleep e.retry_after
+#       retry
+#
+# @domain Infrastructure
+#
+
+module ReactorSDK
+  ##
+  # Base class for all ReactorSDK errors.
+  # Every other error in this file inherits from this class.
+  #
+  class Error < StandardError
+    # @return [Integer, nil] HTTP status code from the API response
+    attr_reader :status
+
+    # @return [Exception, nil] The original exception that caused this one
+    attr_reader :cause
+
+    ##
+    # @param message [String]        Human-readable description of what went wrong
+    # @param status  [Integer, nil]  HTTP status code from the API response
+    # @param cause   [Exception, nil] Underlying exception if this wraps another error
+    #
+    def initialize(message, status: nil, cause: nil)
+      super(message)
+      @status = status
+      @cause  = cause
+    end
+  end
+
+  ##
+  # Raised when Adobe IMS token fetch or refresh fails.
+  # Most commonly caused by an incorrect client_id or client_secret.
+  #
+  class AuthenticationError < Error; end
+
+  ##
+  # Raised when the token is valid but lacks permission for the resource.
+  # Most commonly caused by the org not having access to a property.
+  #
+  class AuthorizationError < Error; end
+
+  ##
+  # Raised when the requested Adobe resource does not exist (HTTP 404).
+  #
+  class ResourceNotFoundError < Error; end
+
+  ##
+  # Raised when a request payload fails Adobe's validation (HTTP 422).
+  # Check validation_errors for field-level details returned by Adobe.
+  #
+  class UnprocessableEntityError < Error
+    # @return [Array<Hash>] Validation error objects returned by the Adobe API
+    attr_reader :validation_errors
+
+    ##
+    # @param message           [String]      Error description
+    # @param validation_errors [Array<Hash>] Adobe API validation error objects
+    # @param opts              [Hash]        Passed through to ReactorSDK::Error
+    #
+    def initialize(message, validation_errors: [], **)
+      super(message, **)
+      @validation_errors = validation_errors
+    end
+  end
+
+  ##
+  # Raised when the rate limit is hit after all retries are exhausted (HTTP 429).
+  # The retry_after value is taken from Adobe's Retry-After response header.
+  #
+  class RateLimitError < Error
+    # @return [Integer, nil] Seconds to wait before the next request
+    attr_reader :retry_after
+
+    ##
+    # @param message     [String]       Error description
+    # @param retry_after [Integer, nil] Seconds until rate limit resets
+    # @param opts        [Hash]         Passed through to ReactorSDK::Error
+    #
+    def initialize(message, retry_after: nil, **)
+      super(message, **)
+      @retry_after = retry_after
+    end
+  end
+
+  ##
+  # Raised when Adobe returns a 5xx server error after all retries exhausted.
+  #
+  class ServerError < Error; end
+
+  ##
+  # Raised when an HTTP response body cannot be parsed as valid JSON.
+  #
+  class ParseError < Error; end
+
+  ##
+  # Raised when a required configuration value is missing or blank.
+  # Caught at client initialization time — never mid-request.
+  #
+  class ConfigurationError < Error; end
+end

data/lib/reactor_sdk/library_comparison_builder.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module ReactorSDK
+  class LibraryComparisonBuilder
+    RESOURCE_TYPE_ORDER = {
+      'rules' => 0,
+      'data_elements' => 1,
+      'extensions' => 2
+    }.freeze
+
+    def initialize(snapshot_loader:)
+      @snapshot_loader = snapshot_loader
+    end
+
+    def build(current_library_id, baseline_library_id:, property_id:)
+      current_snapshot = @snapshot_loader.call(current_library_id, property_id: property_id)
+      baseline_snapshot = @snapshot_loader.call(baseline_library_id, property_id: property_id)
+
+      Resources::LibraryComparison.new(
+        current_library_id: current_library_id,
+        baseline_library_id: baseline_library_id,
+        property_id: property_id,
+        current_snapshot: current_snapshot,
+        baseline_snapshot: baseline_snapshot,
+        entries: build_entries(current_snapshot, baseline_snapshot)
+      )
+    end
+
+    private
+
+    def build_entries(current_snapshot, baseline_snapshot)
+      comparable_resource_ids(current_snapshot, baseline_snapshot)
+        .map { |resource_id| build_entry(current_snapshot, baseline_snapshot, resource_id) }
+        .sort_by { |entry| entry_sort_key(entry) }
+    end
+
+    def comparable_resource_ids(current_snapshot, baseline_snapshot)
+      (current_snapshot.top_level_resources.map(&:id) + baseline_snapshot.top_level_resources.map(&:id)).uniq
+    end
+
+    def build_entry(current_snapshot, baseline_snapshot, resource_id)
+      current_resource = current_snapshot.find_resource(resource_id)
+      baseline_resource = baseline_snapshot.find_resource(resource_id)
+      resource_type = current_resource&.type || baseline_resource&.type
+
+      Resources::LibraryComparisonEntry.new(
+        resource_id: resource_id,
+        resource_type: resource_type,
+        current_library_id: current_snapshot.library.id,
+        baseline_library_id: baseline_snapshot.library.id,
+        current_resource: current_resource,
+        baseline_resource: baseline_resource,
+        current_revision_id: current_snapshot.resource_revision_id(resource_id),
+        baseline_revision_id: baseline_snapshot.resource_revision_id(resource_id),
+        current_comprehensive_resource: comprehensive_resource_for(current_snapshot, resource_id, resource_type),
+        baseline_comprehensive_resource: comprehensive_resource_for(baseline_snapshot, resource_id, resource_type)
+      )
+    end
+
+    def comprehensive_resource_for(snapshot, resource_id, resource_type)
+      return nil if resource_type.nil?
+
+      snapshot.comprehensive_resource(resource_id, resource_type: resource_type)
+    end
+
+    def entry_sort_key(entry)
+      [
+        RESOURCE_TYPE_ORDER.fetch(entry.resource_type, RESOURCE_TYPE_ORDER.length),
+        entry.resource_name.to_s,
+        entry.resource_id
+      ]
+    end
+  end
+end

data/lib/reactor_sdk/library_snapshot_builder.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module ReactorSDK
+  class LibrarySnapshotBuilder
+    def initialize(library_loader:, revisions_endpoint:, rule_components_endpoint:)
+      @library_loader = library_loader
+      @revisions_endpoint = revisions_endpoint
+      @rule_components_endpoint = rule_components_endpoint
+    end
+
+    def build(library_id, property_id:)
+      library = @library_loader.call(library_id)
+
+      Resources::LibrarySnapshot.new(
+        property_id: property_id,
+        library: library,
+        rule_components_by_rule_id: build_rule_components_index(library)
+      )
+    end
+
+    private
+
+    def build_rule_components_index(library)
+      Array(library.rules).to_h do |rule|
+        [rule.id, build_rule_components_snapshot(rule)]
+      end
+    end
+
+    def build_rule_components_snapshot(rule)
+      current_components = @rule_components_endpoint.list_for_rule(rule.id)
+      rule_component_ids = point_in_time_rule_component_ids(rule)
+      return current_components if rule_component_ids.empty?
+
+      current_components_by_id = current_components.to_h do |component|
+        [component.id, component]
+      end
+
+      rule_component_ids.filter_map do |component_id|
+        current_components_by_id[component_id] || find_rule_component(component_id)
+      end.uniq
+    end
+
+    def point_in_time_rule_component_ids(rule)
+      revision_id = current_revision_id_for(rule)
+      return [] if revision_id.nil?
+
+      revision = @revisions_endpoint.find(revision_id)
+      Array(revision.entity_relationships.dig('rule_components', 'data')).filter_map { |item| item['id'] }.uniq
+    rescue ReactorSDK::Error
+      []
+    end
+
+    def current_revision_id_for(rule)
+      return rule.revision_id if rule.respond_to?(:revision_id)
+      return rule.relationship_id('latest_revision') if rule.respond_to?(:relationship_id)
+
+      nil
+    end
+
+    def find_rule_component(rule_component_id)
+      @rule_components_endpoint.find(rule_component_id)
+    rescue ReactorSDK::ResourceNotFoundError
+      nil
+    end
+  end
+end

data/lib/reactor_sdk/paginator.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+##
+# @file paginator.rb
+# @description Handles cursor-based pagination for Reactor API list endpoints.
+#
+#   The Reactor API paginates all list responses using JSON:API cursor links.
+#   Each response includes a `links` object with a `next` URL. This class
+#   follows that cursor until it is absent, collecting all records into a
+#   single flat array.
+#
+#   IMPORTANT: Always use this paginator for list endpoints.
+#   Never make a single GET to a list endpoint — Adobe defaults to 25 records
+#   per page and silently truncates results without any warning or error.
+#   A property with 100 rules will return only 25 without pagination.
+#
+# @domain Infrastructure
+# @depends ReactorSDK::Connection
+#
+# @example Fetch all rules for a property
+#   paginator = ReactorSDK::Paginator.new(connection)
+#   records = paginator.all("/properties/PR123/rules")
+#   # => Array of all rule hashes across every page
+#
+
+module ReactorSDK
+  class Paginator
+    # Number of records to request per page.
+    # Adobe's maximum is 100 — always request the maximum to minimise
+    # the number of API calls made.
+    DEFAULT_PAGE_SIZE = 100
+
+    ##
+    # @param connection [ReactorSDK::Connection] Authenticated HTTP connection
+    #
+    def initialize(connection)
+      @connection = connection
+    end
+
+    ##
+    # Fetches every record from a paginated list endpoint.
+    #
+    # Follows the `links.next` cursor in each response until it is absent,
+    # then returns all collected records as a single flat array.
+    #
+    # An optional block can be provided to process each record as it arrives
+    # rather than waiting for all pages to complete — useful for large datasets.
+    #
+    # @param path   [String] Relative API path (e.g. "/properties/PR123/rules")
+    # @param params [Hash]   Additional query parameters to merge into the request
+    # @yield  [Hash] Each raw JSON:API record hash as it is fetched (optional)
+    # @return [Array<Hash>] All records across every page as a flat array
+    # @raise  [ReactorSDK::Error] on any non-2xx response during pagination
+    #
+    def all(path, params: {})
+      records  = []
+      next_url = build_initial_url(path, params)
+
+      while next_url
+        response = @connection.get(next_url)
+        data     = Array(response&.fetch('data', []))
+
+        data.each do |record|
+          yield record if block_given?
+          records << record
+        end
+
+        next_url = response&.dig('links', 'next')
+      end
+
+      records
+    end
+
+    private
+
+    ##
+    # Builds the initial request URL with the page size parameter appended.
+    # Merges any caller-supplied params so they are included on every page.
+    #
+    # @param path   [String] Base API path without query string
+    # @param params [Hash]   Caller-supplied query parameters
+    # @return [String] Full path with query string
+    #
+    def build_initial_url(path, params)
+      query_params = { 'page[size]' => DEFAULT_PAGE_SIZE }
+                     .merge(params.transform_keys(&:to_s))
+
+      query_string = URI.encode_www_form(query_params)
+      "#{path}?#{query_string}"
+    end
+  end
+end