reactor_sdk 0.1.0

data/lib/reactor_sdk/rate_limiter.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+##
+# @file rate_limiter.rb
+# @description Token bucket rate limiter for Reactor API requests.
+#
+#   Adobe enforces a limit of 120 requests per minute per access token.
+#   This class implements a token bucket algorithm — the bucket starts
+#   full and refills proportionally over time. When empty, the caller
+#   blocks until a token is available.
+#
+#   One RateLimiter instance is created per ReactorSDK::Client so that
+#   different client instances do not share a limit.
+#
+# @domain Infrastructure
+#
+
+module ReactorSDK
+  class RateLimiter
+    # Adobe's documented rate limit per access token
+    MAX_REQUESTS_PER_MINUTE = 120
+
+    # The window over which the limit applies
+    INTERVAL_SECONDS = 60.0
+
+    ##
+    # Initializes a full token bucket.
+    # The first MAX_REQUESTS_PER_MINUTE calls proceed without any delay.
+    #
+    def initialize
+      @mutex     = Mutex.new
+      @tokens    = MAX_REQUESTS_PER_MINUTE
+      @last_tick = Time.now.utc
+    end
+
+    ##
+    # Acquires one token from the bucket, blocking if the bucket is empty.
+    # Refills the bucket based on elapsed time before checking availability.
+    #
+    # @return [void]
+    #
+    def acquire
+      @mutex.synchronize do
+        refill
+        if @tokens >= 1
+          @tokens -= 1
+        else
+          sleep(seconds_per_token)
+          refill
+          @tokens -= 1
+        end
+      end
+    end
+
+    ##
+    # Returns the number of tokens currently available.
+    # Useful for monitoring and testing — not used internally by acquire.
+    #
+    # @return [Integer] Current token count
+    #
+    def available_tokens
+      @mutex.synchronize do
+        refill
+        @tokens.floor
+      end
+    end
+
+    private
+
+    ##
+    # Adds tokens proportional to time elapsed since the last tick.
+    # Never exceeds MAX_REQUESTS_PER_MINUTE.
+    #
+    # @sideeffect Updates @tokens and @last_tick
+    #
+    def refill
+      now        = Time.now.utc
+      elapsed    = now - @last_tick
+      new_tokens = (elapsed / INTERVAL_SECONDS) * MAX_REQUESTS_PER_MINUTE
+
+      return unless new_tokens >= 1
+
+      @tokens    = [@tokens + new_tokens.floor, MAX_REQUESTS_PER_MINUTE].min
+      @last_tick = now
+    end
+
+    ##
+    # Calculates how long to wait for a single token to become available.
+    #
+    # @return [Float] Seconds to sleep
+    #
+    def seconds_per_token
+      INTERVAL_SECONDS / MAX_REQUESTS_PER_MINUTE
+    end
+  end
+end

data/lib/reactor_sdk/reference_extractor.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ReactorSDK
+  module ReferenceExtractor
+    DATA_ELEMENT_TOKEN_PATTERN = /%([^%\r\n]+)%/
+    GET_VAR_PATTERN = /_satellite\.getVar\(\s*(['"])(.*?)\1\s*\)/
+
+    module_function
+
+    def extract_data_element_names(resource)
+      names = Set.new
+
+      collect_string_references(resource.parsed_settings, names) if resource.respond_to?(:parsed_settings)
+
+      raw_settings = resource.respond_to?(:settings) ? resource.settings : nil
+      collect_string_references(raw_settings, names) if raw_settings.is_a?(String)
+
+      names.to_a
+    end
+
+    def collect_string_references(value, names)
+      case value
+      when String
+        value.scan(DATA_ELEMENT_TOKEN_PATTERN) { |match| names << match.first }
+        value.scan(GET_VAR_PATTERN) { |match| names << match.last }
+      when Array
+        value.each { |item| collect_string_references(item, names) }
+      when Hash
+        value.each_value { |item| collect_string_references(item, names) }
+      end
+    end
+    private_class_method :collect_string_references
+  end
+end

data/lib/reactor_sdk/resource_metadata.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ReactorSDK
+  module ResourceMetadata
+    module_function
+
+    def summary(resource)
+      decorate!(
+        {
+          'id' => resource.id,
+          'type' => resource.type
+        },
+        resource
+      )
+    end
+
+    def base_payload(resource, kind:, attributes:, launch_raw:)
+      decorate!(
+        {
+          'kind' => kind,
+          'id' => resource.id,
+          'attributes' => attributes,
+          'launch_raw' => launch_raw
+        },
+        resource,
+        include_position: false,
+        include_revision: false
+      )
+    end
+
+    def delegate_descriptor(resource)
+      return '' unless resource.respond_to?(:delegate_descriptor_id)
+
+      resource.delegate_descriptor_id.to_s
+    end
+
+    def revision_id_for(resource)
+      return resource.revision_id if resource.respond_to?(:revision_id)
+      return resource.relationship_id('latest_revision') if resource.respond_to?(:relationship_id)
+
+      nil
+    end
+
+    def decorate!(payload, resource, include_position: true, include_revision: true)
+      add_name(payload, resource)
+      add_delegate_descriptor(payload, resource)
+      add_position_fields(payload, resource) if include_position
+      add_revision_id(payload, resource) if include_revision
+
+      payload
+    end
+
+    def add_name(payload, resource)
+      payload['name'] = resource.name if resource.respond_to?(:name)
+    end
+
+    def add_delegate_descriptor(payload, resource)
+      return unless resource.respond_to?(:delegate_descriptor_id)
+
+      payload['delegate_descriptor_id'] = resource.delegate_descriptor_id
+    end
+
+    def add_position_fields(payload, resource)
+      payload['order'] = resource.order if resource.respond_to?(:order) && !resource.order.nil?
+      payload['rule_order'] = resource.rule_order if resource.respond_to?(:rule_order) && !resource.rule_order.nil?
+    end
+
+    def add_revision_id(payload, resource)
+      revision_id = revision_id_for(resource)
+      payload['revision_id'] = revision_id if revision_id
+    end
+  end
+end

data/lib/reactor_sdk/resource_normalizer.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module ReactorSDK
+  module ResourceNormalizer
+    CUSTOM_CODE_PATTERN = /::custom-code\z/i
+    ADOBE_ALLOY_PATTERN = /\Aadobe-alloy::/i
+    ADOBE_ANALYTICS_PATTERN = /\Aadobe-analytics::/i
+
+    module_function
+
+    def normalize_resource(resource)
+      configuration, status = normalize_configuration(resource)
+
+      ReactorSDK::ResourceMetadata.base_payload(
+        resource,
+        kind: kind_for(resource),
+        attributes: resource.attributes.except('settings'),
+        launch_raw: resource.to_h
+      ).merge(
+        'configuration' => configuration,
+        'normalization_status' => status
+      )
+    end
+
+    def summary(resource)
+      ReactorSDK::ResourceMetadata.summary(resource)
+    end
+
+    def to_json(payload)
+      JSON.pretty_generate(payload)
+    end
+
+    def kind_for(resource)
+      case resource.type
+      when 'data_elements' then 'data_element'
+      when 'rule_components' then 'rule_component'
+      else
+        resource.type.sub(/s\z/, '')
+      end
+    end
+
+    def normalize_configuration(resource)
+      return [nil, 'none'] unless resource.respond_to?(:settings)
+
+      parsed = resource.respond_to?(:parsed_settings) ? resource.parsed_settings : {}
+      return [nil, 'none'] if parsed.empty? && blank_settings?(resource.settings)
+
+      normalize_delegate_configuration(
+        ReactorSDK::ResourceMetadata.delegate_descriptor(resource),
+        parsed,
+        resource
+      )
+    rescue JSON::ParserError
+      [resource.settings, 'raw']
+    end
+
+    def normalize_custom_code(parsed, resource)
+      language = parsed['language']
+      language = 'javascript' if language.nil? && resource.type == 'data_elements'
+
+      normalized = {}
+      normalized['language'] = language if language
+      normalized['source'] = parsed['source'] if parsed.key?('source')
+
+      parsed.each do |key, value|
+        next if %w[language source].include?(key)
+
+        normalized[key] = value
+      end
+
+      normalized
+    end
+
+    def blank_settings?(settings)
+      settings.nil? || settings == ''
+    end
+
+    def normalize_delegate_configuration(delegate, parsed, resource)
+      return [normalize_custom_code(parsed, resource), 'normalized'] if delegate.match?(CUSTOM_CODE_PATTERN)
+      return [parsed, 'normalized'] if delegate.match?(ADOBE_ALLOY_PATTERN)
+      return [parsed, 'normalized'] if delegate.match?(ADOBE_ANALYTICS_PATTERN)
+      return [parsed, 'parsed'] unless parsed.empty?
+
+      [resource.settings, 'raw']
+    end
+
+    private_class_method :kind_for, :normalize_configuration, :normalize_custom_code, :blank_settings?,
+                         :normalize_delegate_configuration
+  end
+end

data/lib/reactor_sdk/resources/app_configuration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ReactorSDK
+  module Resources
+    class AppConfiguration < BaseResource
+      attribute :name
+      attribute :app_id
+      attribute :platform
+      attribute :messaging_service
+      attribute :key_type
+      attribute :push_credential, default: {}
+      attribute :created_at
+      attribute :updated_at
+
+      def inspect
+        "#<ReactorSDK::Resources::AppConfiguration id=#{id.inspect} name=#{name.inspect}>"
+      end
+    end
+  end
+end

data/lib/reactor_sdk/resources/audit_event.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+##
+# @file resources/audit_event.rb
+# @description Represents an Adobe Launch Audit Event resource.
+#
+#   Audit events record every significant action taken within Adobe Launch —
+#   creates, updates, deletes, publishes, and state transitions.
+#   LaunchGuard syncs these events into its own audit log to provide a
+#   complete cross-platform activity record.
+#
+# @domain Resources
+# @see https://developer.adobe.com/experience-platform/documentation/tags/api/endpoints/audit-events/
+#
+
+module ReactorSDK
+  module Resources
+    class AuditEvent < BaseResource
+      # @return [String] The type of action that occurred
+      attribute :type_of
+
+      # @return [String] Human-readable name of the affected resource
+      attribute :entity_display_name
+
+      # @return [String] ISO8601 timestamp when the event occurred
+      attribute :created_at
+
+      # @return [Hash, nil] Snapshot of the resource before the action
+      attribute :previous_attributes
+
+      # @return [Hash, nil] Snapshot of the resource after the action
+      attribute :updated_attributes
+
+      ##
+      # @return [String] Human-readable representation
+      #
+      def inspect
+        '#<ReactorSDK::Resources::AuditEvent ' \
+          "id=#{id.inspect} " \
+          "type=#{type_of.inspect} " \
+          "entity=#{entity_display_name.inspect}>"
+      end
+    end
+  end
+end

data/lib/reactor_sdk/resources/base_resource.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+##
+# @file resources/base_resource.rb
+# @description Base class for all Adobe Launch resource objects.
+#
+#   Provides a class-level `attribute` macro that subclasses use to declare
+#   which JSON:API attributes should be exposed as first-class Ruby methods.
+#
+#   Instead of accessing raw hash values like:
+#     property.attributes["name"]
+#     property["platform"]
+#
+#   Subclasses declare their fields and callers use clean dot notation:
+#     property.name
+#     property.platform
+#     property.enabled?   # boolean fields get a ? alias automatically
+#
+#   Usage in a subclass:
+#     class Property < BaseResource
+#       attribute :name
+#       attribute :platform
+#       attribute :enabled,  as: :boolean
+#       attribute :domains,  default: []
+#       attribute :created_at
+#     end
+#
+# @domain Resources
+#
+
+module ReactorSDK
+  module Resources
+    class BaseResource
+      # @return [String] Adobe resource ID (e.g. "PR1234abcd...")
+      attr_reader :id
+
+      # @return [String] JSON:API resource type (e.g. "rules", "properties")
+      attr_reader :type
+
+      # @return [Hash] Full raw attributes hash from the JSON:API response
+      #   Available for accessing fields not declared with the attribute macro
+      attr_reader :attributes
+
+      # @return [Hash] Meta hash from the JSON:API response
+      attr_reader :meta
+
+      # @return [Hash] Relationships hash from the JSON:API response
+      attr_reader :relationships
+
+      ##
+      # Class-level macro for declaring typed attribute readers.
+      # Called in subclass bodies to define which JSON:API attributes
+      # are exposed as Ruby methods on the resource object.
+      #
+      # @param name    [Symbol]  Attribute name — must match the JSON:API field name
+      # @param as      [Symbol]  Type cast — :boolean adds a ? method alias (optional)
+      # @param default [Object]  Default value when the attribute is nil (optional)
+      #
+      # @example Declare a plain string attribute
+      #   attribute :name
+      #
+      # @example Declare a boolean attribute (adds enabled? alias)
+      #   attribute :enabled, as: :boolean
+      #
+      # @example Declare an array attribute with a default
+      #   attribute :domains, default: []
+      #
+      def self.attribute(name, as: nil, default: nil)
+        # Define the reader method that pulls from the attributes hash
+        define_method(name) do
+          value = @attributes[name.to_s]
+          value.nil? ? default : value
+        end
+
+        # Boolean fields get a ? alias automatically
+        # e.g. attribute :enabled, as: :boolean
+        #      generates both enabled and enabled?
+        define_method(:"#{name}?") { !!public_send(name) } if as == :boolean
+      end
+
+      ##
+      # @param id         [String] Adobe resource ID
+      # @param type       [String] JSON:API resource type
+      # @param attributes [Hash]   Resource attribute values from the API response
+      # @param meta       [Hash]   Optional metadata from the API response
+      # @param relationships [Hash] Optional relationships from the API response
+      #
+      def initialize(id:, type:, attributes: {}, meta: {}, relationships: {})
+        @id         = id
+        @type       = type
+        @attributes = attributes
+        @meta       = meta
+        @relationships = relationships
+      end
+
+      ##
+      # Provides fallback access to any attribute by name.
+      # Use this for attributes not declared with the attribute macro,
+      # or for dynamic access patterns.
+      #
+      # @param key [String, Symbol] Attribute name
+      # @return [Object, nil] Attribute value or nil if not present
+      #
+      def [](key)
+        @attributes[key.to_s]
+      end
+
+      ##
+      # Returns the raw relationship object for a given relationship name.
+      #
+      # @param name [String, Symbol]
+      # @return [Hash, nil]
+      #
+      def relationship_data(name)
+        @relationships[name.to_s]
+      end
+
+      ##
+      # Returns the related resource ID when the relationship contains a single linkage.
+      #
+      # @param name [String, Symbol]
+      # @return [String, nil]
+      #
+      def relationship_id(name)
+        relationship_data(name)&.dig('data', 'id')
+      end
+
+      ##
+      # Returns related resource IDs when the relationship contains collection linkage.
+      #
+      # @param name [String, Symbol]
+      # @return [Array<String>]
+      #
+      def relationship_ids(name)
+        data = relationship_data(name)&.fetch('data', nil)
+        return [] unless data.is_a?(Array)
+
+        data.filter_map { |item| item['id'] }
+      end
+
+      ##
+      # Returns a readable string representation for debugging.
+      # Subclasses override this to include their most useful fields.
+      #
+      # @return [String]
+      #
+      def inspect
+        "#<#{self.class.name} id=#{@id.inspect} type=#{@type.inspect}>"
+      end
+
+      ##
+      # Two resources are equal if they represent the same Adobe resource —
+      # same id and same type, regardless of which attributes were loaded.
+      #
+      # @param other [Object] Object to compare with
+      # @return [Boolean]
+      #
+      def ==(other)
+        other.is_a?(BaseResource) &&
+          other.id == id &&
+          other.type == type
+      end
+
+      ##
+      # Returns a plain hash representation of the resource.
+      # Useful for serialisation, logging, and debugging.
+      #
+      # @return [Hash]
+      #
+      def to_h
+        {
+          id: @id,
+          type: @type,
+          attributes: @attributes,
+          meta: @meta,
+          relationships: @relationships
+        }
+      end
+    end
+  end
+end

data/lib/reactor_sdk/resources/build.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+##
+# @file resources/build.rb
+# @description Represents an Adobe Launch Build resource.
+#
+#   A build is the compiled output of a library — the JavaScript bundle
+#   that gets deployed to an environment. Builds are created by triggering
+#   a library build and move through statuses: pending -> processing ->
+#   succeeded or failed.
+#
+# @domain Resources
+# @see https://developer.adobe.com/experience-platform/documentation/tags/api/endpoints/builds/
+#
+
+module ReactorSDK
+  module Resources
+    class Build < BaseResource
+      # @return [String] Current build status
+      #   One of: "pending", "processing", "succeeded", "failed", "rejected"
+      attribute :status
+
+      # @return [String] ISO8601 timestamp when the build was created
+      attribute :created_at
+
+      # @return [String] ISO8601 timestamp when the build was last updated
+      attribute :updated_at
+
+      ##
+      # Returns true if the build completed successfully.
+      #
+      # @return [Boolean]
+      #
+      def succeeded?
+        status == 'succeeded'
+      end
+
+      ##
+      # Returns true if the build is still in progress.
+      #
+      # @return [Boolean]
+      #
+      def pending?
+        %w[pending processing].include?(status)
+      end
+
+      ##
+      # Returns true if the build failed.
+      #
+      # @return [Boolean]
+      #
+      def failed?
+        status == 'failed'
+      end
+
+      ##
+      # @return [String] Human-readable representation
+      #
+      def inspect
+        "#<ReactorSDK::Resources::Build id=#{id.inspect} status=#{status.inspect}>"
+      end
+    end
+  end
+end

data/lib/reactor_sdk/resources/callback.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ReactorSDK
+  module Resources
+    class Callback < BaseResource
+      attribute :url
+      attribute :subscriptions, default: []
+      attribute :created_at
+      attribute :updated_at
+
+      def inspect
+        "#<ReactorSDK::Resources::Callback id=#{id.inspect} url=#{url.inspect}>"
+      end
+    end
+  end
+end

data/lib/reactor_sdk/resources/company.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+##
+# @file resources/company.rb
+# @description Represents an Adobe Launch Company resource.
+#
+#   A Company maps directly to an Adobe IMS Organisation. It is the
+#   top-level container — all properties belong to a company.
+#   Most orgs have exactly one company.
+#
+# @domain Resources
+# @see https://developer.adobe.com/experience-platform/documentation/tags/api/endpoints/companies/
+#
+
+module ReactorSDK
+  module Resources
+    class Company < BaseResource
+      # @return [String] Display name of the company
+      attribute :name
+
+      # @return [String] Adobe IMS organisation ID
+      attribute :org_id
+
+      # @return [String] ISO8601 timestamp when the company was created
+      attribute :created_at
+
+      # @return [String] ISO8601 timestamp when the company was last updated
+      attribute :updated_at
+
+      ##
+      # @return [String] Human-readable representation
+      #
+      def inspect
+        "#<ReactorSDK::Resources::Company id=#{id.inspect} name=#{name.inspect}>"
+      end
+    end
+  end
+end

data/lib/reactor_sdk/resources/comprehensive_data_element.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ReactorSDK
+  module Resources
+    class ComprehensiveDataElement < ComprehensiveResource
+      attr_reader :referenced_data_elements, :impacted_rules
+
+      def initialize(resource:, referenced_data_elements:, impacted_rules:)
+        super(resource: resource)
+        @referenced_data_elements = Array(referenced_data_elements)
+        @impacted_rules = Array(impacted_rules)
+      end
+
+      def associated_records
+        (@referenced_data_elements + @impacted_rules).uniq
+      end
+
+      def normalized_payload
+        payload = normalized_resource_payload
+        payload['associations'] = {
+          'referenced_data_elements' => summaries_for(@referenced_data_elements),
+          'impacted_rules' => summaries_for(@impacted_rules)
+        }
+        payload
+      end
+    end
+  end
+end