reactor_sdk 0.1.0

data/lib/reactor_sdk/resources/library_comparison_entry.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module ReactorSDK
+  module Resources
+    class LibraryComparisonEntry
+      attr_reader :resource_id,
+                  :resource_type,
+                  :current_library_id,
+                  :baseline_library_id,
+                  :current_resource,
+                  :baseline_resource,
+                  :current_revision_id,
+                  :baseline_revision_id,
+                  :current_comprehensive_resource,
+                  :baseline_comprehensive_resource
+
+      def initialize(
+        resource_id:,
+        resource_type:,
+        current_library_id:,
+        baseline_library_id:,
+        current_resource:,
+        baseline_resource:,
+        current_revision_id:,
+        baseline_revision_id:,
+        current_comprehensive_resource:,
+        baseline_comprehensive_resource:
+      )
+        @resource_id = resource_id
+        @resource_type = resource_type
+        @current_library_id = current_library_id
+        @baseline_library_id = baseline_library_id
+        @current_resource = current_resource
+        @baseline_resource = baseline_resource
+        @current_revision_id = current_revision_id
+        @baseline_revision_id = baseline_revision_id
+        @current_comprehensive_resource = current_comprehensive_resource
+        @baseline_comprehensive_resource = baseline_comprehensive_resource
+      end
+
+      def resource_name
+        return current_resource.name if current_resource.respond_to?(:name)
+        return baseline_resource.name if baseline_resource.respond_to?(:name)
+
+        nil
+      end
+
+      def status
+        return 'added' if added?
+        return 'removed' if removed?
+        return 'unchanged' if unchanged?
+
+        'modified'
+      end
+
+      def added?
+        present_in_current? && !present_in_baseline?
+      end
+
+      def removed?
+        !present_in_current? && present_in_baseline?
+      end
+
+      def modified?
+        present_in_current? && present_in_baseline? && !unchanged?
+      end
+
+      def unchanged?
+        return false unless present_in_current? && present_in_baseline?
+
+        same_revision? || same_normalized_payload?
+      end
+
+      def changed?
+        !unchanged?
+      end
+
+      def present_in_current?
+        !current_resource.nil?
+      end
+
+      def present_in_baseline?
+        !baseline_resource.nil?
+      end
+
+      def current_normalized_payload
+        current_comprehensive_resource&.normalized_payload
+      end
+
+      def baseline_normalized_payload
+        baseline_comprehensive_resource&.normalized_payload
+      end
+
+      def current_normalized_json
+        current_comprehensive_resource&.normalized_json.to_s
+      end
+
+      def baseline_normalized_json
+        baseline_comprehensive_resource&.normalized_json.to_s
+      end
+
+      def changeset_document(position: nil)
+        document = {
+          path: changeset_path,
+          language: 'json',
+          old_content: baseline_normalized_json,
+          new_content: current_normalized_json,
+          metadata: changeset_metadata
+        }
+        document[:position] = position unless position.nil?
+        document
+      end
+
+      private
+
+      def same_revision?
+        return false if current_revision_id.nil? || baseline_revision_id.nil?
+
+        current_revision_id == baseline_revision_id
+      end
+
+      def same_normalized_payload?
+        current_normalized_payload == baseline_normalized_payload
+      end
+
+      def changeset_path
+        "reactor/#{resource_type}/#{resource_id}.json"
+      end
+
+      def changeset_metadata
+        {
+          resource_id: resource_id,
+          resource_type: resource_type,
+          resource_name: resource_name,
+          status: status,
+          current_library_id: current_library_id,
+          baseline_library_id: baseline_library_id,
+          current_revision_id: current_revision_id,
+          baseline_revision_id: baseline_revision_id
+        }.compact
+      end
+    end
+  end
+end

data/lib/reactor_sdk/resources/library_snapshot.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module ReactorSDK
+  module Resources
+    class LibrarySnapshot
+      attr_reader :property_id,
+                  :library,
+                  :rules,
+                  :data_elements,
+                  :extensions,
+                  :rule_components,
+                  :rule_components_by_rule_id,
+                  :resource_by_id
+
+      def initialize(property_id:, library:, rule_components_by_rule_id:)
+        @property_id = property_id
+        @library = library
+        @rules = Array(library.rules)
+        @data_elements = Array(library.data_elements)
+        @extensions = Array(library.extensions)
+        @index = LibrarySnapshotIndex.new(
+          rules: @rules,
+          data_elements: @data_elements,
+          extensions: @extensions,
+          rule_components_by_rule_id: rule_components_by_rule_id
+        )
+        @rule_components_by_rule_id = @index.rule_components_by_rule_id
+        @rule_components = @index.rule_components
+        @resource_by_id = @index.resource_by_id
+      end
+
+      def top_level_resources
+        @top_level_resources ||= @rules + @data_elements + @extensions
+      end
+
+      def all_resources
+        top_level_resources + @rule_components
+      end
+
+      def find_resource(resource_id)
+        @index.find_resource(resource_id)
+      end
+
+      def rule_components_for_rule(rule_or_id)
+        @index.rule_components_for_rule(rule_or_id)
+      end
+
+      def referenced_data_elements_for(data_element_or_id)
+        @index.referenced_data_elements_for(data_element_or_id)
+      end
+
+      def impacted_rules_for(data_element_or_id)
+        @index.impacted_rules_for(data_element_or_id)
+      end
+
+      def data_elements_for_extension(extension_or_id)
+        @index.data_elements_for_extension(extension_or_id)
+      end
+
+      def rule_components_for_extension(extension_or_id)
+        @index.rule_components_for_extension(extension_or_id)
+      end
+
+      def rules_for_extension(extension_or_id)
+        @index.rules_for_extension(extension_or_id)
+      end
+
+      def resource_revision_id(resource_or_id)
+        resource_id = extract_id(resource_or_id)
+        resource = find_resource(resource_id)
+        return nil if resource.nil?
+        return resource.revision_id if resource.respond_to?(:revision_id)
+        return @library.resource_index[resource_id] if @library.resource_index.key?(resource_id)
+        return resource.relationship_id('latest_revision') if resource.respond_to?(:relationship_id)
+
+        nil
+      end
+
+      def comprehensive_resource(resource_id, resource_type: nil)
+        resource = find_resource(resource_id)
+        return nil if resource.nil?
+
+        build_comprehensive_resource(resource, resource_type || resource.type)
+      end
+
+      private
+
+      def build_comprehensive_resource(resource, resource_type)
+        case resource_type
+        when 'rules'
+          ComprehensiveRule.new(
+            resource: resource,
+            rule_components: rule_components_for_rule(resource.id)
+          )
+        when 'data_elements'
+          ComprehensiveDataElement.new(
+            resource: resource,
+            referenced_data_elements: referenced_data_elements_for(resource.id),
+            impacted_rules: impacted_rules_for(resource.id)
+          )
+        when 'extensions'
+          ComprehensiveExtension.new(
+            resource: resource,
+            data_elements: data_elements_for_extension(resource.id),
+            rule_components: rule_components_for_extension(resource.id),
+            rules: rules_for_extension(resource.id)
+          )
+        end
+      end
+
+      def extract_id(resource_or_id)
+        return resource_or_id.id if resource_or_id.respond_to?(:id)
+
+        resource_or_id
+      end
+    end
+  end
+end

data/lib/reactor_sdk/resources/library_snapshot_extension_index.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module ReactorSDK
+  module Resources
+    class LibrarySnapshotExtensionIndex
+      def initialize(data_elements:, rule_components_by_rule_id:, find_resource:, sort_rule_components:)
+        @data_elements = Array(data_elements)
+        @rule_components_by_rule_id = rule_components_by_rule_id
+        @find_resource = find_resource
+        @sort_rule_components = sort_rule_components
+        @data_elements_by_extension = build_data_elements_index
+        @rule_components_by_extension = build_rule_components_index
+        @rules_by_extension = build_rules_index
+      end
+
+      def data_elements_for(extension_id)
+        @data_elements_by_extension.fetch(extension_id, [])
+      end
+
+      def rule_components_for(extension_id)
+        @rule_components_by_extension.fetch(extension_id, [])
+      end
+
+      def rules_for(extension_id)
+        @rules_by_extension.fetch(extension_id, [])
+      end
+
+      private
+
+      def build_data_elements_index
+        group_by_relationship(@data_elements, 'extension').transform_values do |items|
+          items.sort_by { |item| [item.name.to_s, item.id] }
+        end
+      end
+
+      def build_rule_components_index
+        group_by_relationship(@rule_components_by_rule_id.values.flatten, 'extension')
+          .transform_values { |items| @sort_rule_components.call(items) }
+      end
+
+      def build_rules_index
+        rules_by_extension = @rule_components_by_rule_id.each_with_object(new_set_index) do |rule_entry, index|
+          rule_id, components = rule_entry
+          rule = @find_resource.call(rule_id)
+          next if rule.nil?
+
+          components.each do |component|
+            extension_id = component.relationship_id('extension')
+            index[extension_id] << rule unless extension_id.nil?
+          end
+        end
+
+        rules_by_extension.transform_values do |items|
+          items.to_a.sort_by { |rule| [rule.name.to_s, rule.id] }
+        end
+      end
+
+      def group_by_relationship(resources, relationship_name)
+        resources.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |resource, grouped_resources|
+          relationship_id = resource.relationship_id(relationship_name)
+          grouped_resources[relationship_id] << resource unless relationship_id.nil?
+        end
+      end
+
+      def new_set_index
+        Hash.new { |hash, key| hash[key] = Set.new }
+      end
+    end
+  end
+end

data/lib/reactor_sdk/resources/library_snapshot_index.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module ReactorSDK
+  module Resources
+    class LibrarySnapshotIndex
+      attr_reader :resource_by_id, :rule_components, :rule_components_by_rule_id
+
+      def initialize(rules:, data_elements:, extensions:, rule_components_by_rule_id:)
+        @rules = Array(rules)
+        @data_elements = Array(data_elements)
+        @extensions = Array(extensions)
+        @rule_components_by_rule_id = normalize_rule_components(rule_components_by_rule_id)
+        @rule_components = @rule_components_by_rule_id.values.flatten
+        @resource_by_id = build_resource_index
+        @data_elements_by_name = build_data_element_name_index
+        @data_element_dependency_graph = build_data_element_dependency_graph
+        @reverse_data_element_graph = invert_graph(@data_element_dependency_graph)
+        @rule_dependency_graph = build_rule_dependency_graph
+        @rules_by_data_element = invert_graph(@rule_dependency_graph)
+        @extension_index = LibrarySnapshotExtensionIndex.new(
+          data_elements: @data_elements,
+          rule_components_by_rule_id: @rule_components_by_rule_id,
+          find_resource: method(:find_resource),
+          sort_rule_components: method(:sort_rule_components)
+        )
+      end
+
+      def find_resource(resource_id)
+        @resource_by_id[extract_id(resource_id)]
+      end
+
+      def rule_components_for_rule(rule_or_id)
+        @rule_components_by_rule_id.fetch(extract_id(rule_or_id), [])
+      end
+
+      def referenced_data_elements_for(data_element_or_id)
+        referenced_resource_ids(data_element_or_id).filter_map { |resource_id| find_resource(resource_id) }
+      end
+
+      def impacted_rules_for(data_element_or_id)
+        impacted_rule_ids_for(data_element_or_id)
+          .filter_map { |resource_id| find_resource(resource_id) }
+          .sort_by { |rule| [rule.name.to_s, rule.id] }
+      end
+
+      def data_elements_for_extension(extension_or_id)
+        @extension_index.data_elements_for(extract_id(extension_or_id))
+      end
+
+      def rule_components_for_extension(extension_or_id)
+        @extension_index.rule_components_for(extract_id(extension_or_id))
+      end
+
+      def rules_for_extension(extension_or_id)
+        @extension_index.rules_for(extract_id(extension_or_id))
+      end
+
+      private
+
+      def normalize_rule_components(rule_components_by_rule_id)
+        rule_components_by_rule_id.to_h do |rule_id, components|
+          [rule_id, sort_rule_components(Array(components))]
+        end
+      end
+
+      def sort_rule_components(components)
+        components.sort_by do |component|
+          [
+            sortable_number(component.respond_to?(:rule_order) ? component.rule_order : nil),
+            sortable_number(component.respond_to?(:order) ? component.order : nil),
+            component.id
+          ]
+        end
+      end
+
+      def sortable_number(value)
+        value.nil? ? Float::INFINITY : value.to_f
+      end
+
+      def build_resource_index
+        (@rules + @data_elements + @extensions + @rule_components).each_with_object({}) do |resource, index|
+          index[resource.id] ||= resource
+        end
+      end
+
+      def build_data_element_name_index
+        @data_elements.each_with_object({}) do |data_element, index|
+          next unless data_element.respond_to?(:name)
+          next if data_element.name.nil?
+
+          index[data_element.name] = data_element
+        end
+      end
+
+      def build_data_element_dependency_graph
+        @data_elements.to_h do |data_element|
+          names = ReactorSDK::ReferenceExtractor.extract_data_element_names(data_element)
+          [data_element.id, resolve_data_element_names(names, excluding: data_element.id)]
+        end
+      end
+
+      def build_rule_dependency_graph
+        @rules.to_h do |rule|
+          component_names = rule_components_for_rule(rule.id).flat_map do |component|
+            ReactorSDK::ReferenceExtractor.extract_data_element_names(component)
+          end
+          [rule.id, resolve_data_element_names(component_names)]
+        end
+      end
+
+      def invert_graph(graph)
+        graph.each_with_object(new_set_index) do |(from_id, to_ids), inverse|
+          Array(to_ids).each { |to_id| inverse[to_id] << from_id }
+        end.transform_values(&:to_a)
+      end
+
+      def referenced_resource_ids(data_element_or_id)
+        data_element_id = extract_id(data_element_or_id)
+        Array(@data_element_dependency_graph[data_element_id])
+      end
+
+      def impacted_rule_ids_for(data_element_or_id)
+        related_data_element_ids = transitive_data_element_ids(extract_id(data_element_or_id))
+
+        related_data_element_ids.each_with_object(Set.new) do |data_element_id, impacted_rule_ids|
+          Array(@rules_by_data_element[data_element_id]).each { |rule_id| impacted_rule_ids << rule_id }
+        end.to_a
+      end
+
+      def transitive_data_element_ids(data_element_id)
+        related_data_element_ids = Set[data_element_id]
+        queue = [data_element_id]
+
+        until queue.empty?
+          current = queue.shift
+
+          Array(@reverse_data_element_graph[current]).each do |dependent_id|
+            next if related_data_element_ids.include?(dependent_id)
+
+            related_data_element_ids << dependent_id
+            queue << dependent_id
+          end
+        end
+
+        related_data_element_ids
+      end
+
+      def new_set_index
+        Hash.new { |hash, key| hash[key] = Set.new }
+      end
+
+      def resolve_data_element_names(names, excluding: nil)
+        names.each_with_object(Set.new) do |name, resolved_ids|
+          target = @data_elements_by_name[name]
+          next if target.nil?
+          next if target.id == excluding
+
+          resolved_ids << target.id
+        end.to_a.sort
+      end
+
+      def extract_id(resource_or_id)
+        return resource_or_id.id if resource_or_id.respond_to?(:id)
+
+        resource_or_id
+      end
+    end
+  end
+end

data/lib/reactor_sdk/resources/library_with_resources.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+##
+# @file resources/library_with_resources.rb
+# @description A richer Library resource returned by Libraries#find_with_resources.
+#
+#   When fetching GET /libraries/:id?include=rules,data_elements,extensions
+#   Adobe returns the library alongside all its associated resources in the
+#   JSON:API included array. Each included resource carries a relationships
+#   hash containing its current revision ID.
+#
+#   This class wraps that response and exposes:
+#     - All standard Library attributes (name, state, etc.)
+#     - rules          — Array of Rule resources with revision_id attached
+#     - data_elements  — Array of DataElement resources with revision_id attached
+#     - extensions     — Array of Extension resources with revision_id attached
+#
+#   The revision_id on each resource is the key the app uses for upstream
+#   resolution — when a resource does not exist in the target library, the
+#   app walks upstream (Development → Staging → Production) to find the
+#   nearest version and fetches that revision for comparison.
+#
+#   This class is never instantiated directly — always created via
+#   Libraries#find_with_resources which passes the full API response.
+#
+# @domain Resources
+# @see https://developer.adobe.com/experience-platform/documentation/tags/api/endpoints/libraries/
+#
+
+module ReactorSDK
+  module Resources
+    class LibraryWithResources < BaseResource
+      # @return [String] Display name of the library
+      attribute :name
+
+      # @return [String] Current workflow state
+      #   One of: "development", "submitted", "approved", "rejected", "published"
+      attribute :state
+
+      # @return [Boolean] Whether the library has been published
+      attribute :published, as: :boolean
+
+      # @return [String] ISO8601 timestamp when the library was created
+      attribute :created_at
+
+      # @return [String] ISO8601 timestamp when the library was last updated
+      attribute :updated_at
+
+      # @return [String, nil] ISO8601 timestamp when the library was published
+      attribute :published_at
+
+      # @return [Array<ReactorSDK::Resources::Rule>] Rules in this library
+      #   Each rule has a revision_id attribute attached from the relationship data
+      attr_reader :rules
+
+      # @return [Array<ReactorSDK::Resources::DataElement>] Data elements in this library
+      #   Each data element has a revision_id attribute attached
+      attr_reader :data_elements
+
+      # @return [Array<ReactorSDK::Resources::Extension>] Extensions in this library
+      #   Each extension has a revision_id attribute attached
+      attr_reader :extensions
+
+      ##
+      # Initializes the library with its included resources.
+      #
+      # Accepts the standard BaseResource arguments plus an included_resources
+      # hash that maps resource type to arrays of raw JSON:API resource hashes
+      # extracted from the API response included array.
+      #
+      # @param id                [String] Adobe library ID
+      # @param type              [String] JSON:API type ("libraries")
+      # @param attributes        [Hash]   Library attribute values
+      # @param meta              [Hash]   Optional metadata
+      # @param included_resources [Hash]  Keyed by type — raw included resource arrays
+      #   {
+      #     "rules"         => [ { "id" => "RL123", "type" => "rules",
+      #                            "attributes" => {...},
+      #                            "relationships" => { "latest_revision" => { "data" => { "id" => "RE123" } } } } ],
+      #     "data_elements" => [ ... ],
+      #     "extensions"    => [ ... ]
+      #   }
+      #
+      def initialize(
+        id:,
+        type:,
+        attributes:          {},
+        meta:                {},
+        included_resources:  {}
+      )
+        super(id: id, type: type, attributes: attributes, meta: meta)
+        @rules         = build_resources(included_resources['rules'],         Resources::Rule)
+        @data_elements = build_resources(included_resources['data_elements'], Resources::DataElement)
+        @extensions    = build_resources(included_resources['extensions'],    Resources::Extension)
+      end
+
+      ##
+      # Returns true if the library is in a state where it can be built.
+      #
+      # @return [Boolean]
+      #
+      def buildable?
+        state == 'development'
+      end
+
+      ##
+      # Returns true if the library has been successfully published.
+      #
+      # @return [Boolean]
+      #
+      def published?
+        state == 'published'
+      end
+
+      ##
+      # Returns a flat index of all resources keyed by Adobe resource ID.
+      # Maps each resource ID to its current revision ID.
+      # Covers rules, data elements, and extensions in a single lookup.
+      #
+      # Used by the app to compare two libraries — call resource_index on
+      # both the source and target library, then compare revision IDs to
+      # find what changed, what was added, and what needs upstream resolution.
+      #
+      # @return [Hash] { "RL123" => "RE456", "DE789" => "RE012", ... }
+      #
+      def resource_index
+        (@rules + @data_elements + @extensions).each_with_object({}) do |resource, index|
+          index[resource.id] = resource.revision_id if resource.revision_id
+        end
+      end
+
+      ##
+      # Returns all included resources as a flat array regardless of type.
+      #
+      # @return [Array<BaseResource>]
+      #
+      def all_resources
+        @rules + @data_elements + @extensions
+      end
+
+      ##
+      # @return [String] Human-readable representation
+      #
+      def inspect
+        '#<ReactorSDK::Resources::LibraryWithResources ' \
+          "id=#{id.inspect} " \
+          "name=#{name.inspect} " \
+          "state=#{state.inspect} " \
+          "rules=#{@rules.length} " \
+          "data_elements=#{@data_elements.length} " \
+          "extensions=#{@extensions.length}>"
+      end
+
+      private
+
+      ##
+      # Builds an array of typed resource objects from raw included resource hashes.
+      # Attaches revision_id to each resource extracted from its relationships.
+      #
+      # @param raw_resources  [Array<Hash>, nil] Raw JSON:API resource hashes
+      # @param resource_class [Class]             Resource class to instantiate
+      # @return [Array<BaseResource>] Typed resource objects with revision_id attached
+      #
+      def build_resources(raw_resources, resource_class)
+        Array(raw_resources).map do |raw|
+          resource = resource_class.new(
+            id: raw.fetch('id'),
+            type: raw.fetch('type'),
+            attributes: raw.fetch('attributes', {}),
+            meta: raw.fetch('meta', {}),
+            relationships: raw.fetch('relationships', {})
+          )
+          resource.instance_variable_set(
+            :@revision_id,
+            extract_revision_id(raw)
+          )
+          resource.singleton_class.attr_reader :revision_id
+          resource
+        end
+      end
+
+      ##
+      # Extracts the latest revision ID from a resource's relationships hash.
+      # Adobe stores it under relationships.latest_revision.data.id.
+      #
+      # @param raw [Hash] Raw JSON:API resource hash
+      # @return [String, nil] Revision ID or nil if not present
+      #
+      def extract_revision_id(raw)
+        raw.dig('relationships', 'latest_revision', 'data', 'id')
+      end
+    end
+  end
+end