reactor_sdk 0.1.0

data/lib/reactor_sdk/endpoints/base_endpoint.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+##
+# @file endpoints/base_endpoint.rb
+# @description Base class for all Reactor API endpoint groups.
+#
+#   Provides three shared dependencies to every endpoint subclass:
+#     - connection   for making authenticated HTTP calls
+#     - paginator    for fetching all pages of list endpoints
+#     - parser       for converting JSON:API hashes into typed resources
+#
+#   Also provides two protected helper methods used by every endpoint:
+#     - build_payload            builds a JSON:API write payload (POST/PATCH)
+#     - build_relationship_payload builds a JSON:API relationship payload
+#
+#   Every endpoint class inherits from this and focuses only on its
+#   own resource domain — it never touches HTTP or pagination directly.
+#
+# @domain Endpoints
+#
+
+module ReactorSDK
+  module Endpoints
+    class BaseEndpoint
+      ##
+      # @param connection [ReactorSDK::Connection]      Authenticated HTTP client
+      # @param paginator  [ReactorSDK::Paginator]       Handles cursor pagination
+      # @param parser     [ReactorSDK::ResponseParser]  Converts JSON:API to resources
+      #
+      def initialize(connection:, paginator:, parser:)
+        @connection = connection
+        @paginator  = paginator
+        @parser     = parser
+      end
+
+      protected
+
+      ##
+      # Builds a JSON:API compliant request payload for create and update requests.
+      #
+      # POST (create) — omit the id parameter:
+      #   build_payload("properties", { name: "My Site", platform: "web" })
+      #   => { data: { type: "properties", attributes: { name: "My Site", platform: "web" } } }
+      #
+      # PATCH (update) — include the id parameter:
+      #   build_payload("properties", { name: "New Name" }, id: "PR123")
+      #   => { data: { id: "PR123", type: "properties", attributes: { name: "New Name" } } }
+      #
+      # @param type          [String]      JSON:API resource type (e.g. "properties")
+      # @param attributes    [Hash]        Resource attribute values to send
+      # @param id            [String, nil] Resource ID — required for PATCH, omit for POST
+      # @param relationships [Hash, nil]   JSON:API relationships payload
+      # @param meta          [Hash, nil]   JSON:API meta payload
+      # @return [Hash] Correctly structured JSON:API payload
+      #
+      def build_payload(type, attributes, id: nil, relationships: nil, meta: nil)
+        data = { type: type, attributes: attributes }
+        data[:id] = id if id
+        data[:relationships] = relationships if relationships
+        data[:meta] = meta if meta
+        { data: data }
+      end
+
+      ##
+      # Builds a JSON:API relationship payload for associating resources.
+      # Used when adding rules, data elements, or extensions to a library.
+      #
+      # @example Add two rules to a library
+      #   build_relationship_payload("rules", ["RL123", "RL456"])
+      #   => { data: [{ id: "RL123", type: "rules" }, { id: "RL456", type: "rules" }] }
+      #
+      # @param type [String]        JSON:API resource type
+      # @param ids  [Array<String>] Array of Adobe resource IDs to associate
+      # @return [Hash] JSON:API relationship payload
+      #
+      def build_relationship_payload(type, ids)
+        {
+          data: Array(ids).map { |id| { id: id, type: type } }
+        }
+      end
+
+      ##
+      # Fetches and parses a single related resource.
+      #
+      # @param path           [String]
+      # @param resource_class [Class]
+      # @param params         [Hash]
+      # @return [Object]
+      #
+      def fetch_resource(path, resource_class, params: {})
+        response = @connection.get(path, params: params)
+        @parser.parse(response['data'], resource_class, response: response)
+      end
+
+      ##
+      # Fetches and parses a related resource collection.
+      #
+      # @param path           [String]
+      # @param resource_class [Class]
+      # @param params         [Hash]
+      # @return [Array<Object>]
+      #
+      def list_resources(path, resource_class, params: {})
+        records = @paginator.all(path, params: params)
+        @parser.parse_many(records, resource_class)
+      end
+
+      ##
+      # Fetches and parses a heterogeneous resource collection using
+      # each record's JSON:API type to choose the SDK class.
+      #
+      # @param path [String]
+      # @param params [Hash]
+      # @return [Array<ReactorSDK::Resources::BaseResource>]
+      #
+      def list_resources_auto(path, params: {})
+        records = @paginator.all(path, params: params)
+        @parser.parse_many_auto(records)
+      end
+
+      ##
+      # Creates and parses a single resource.
+      #
+      # @param path           [String]
+      # @param type           [String]
+      # @param resource_class [Class]
+      # @param attributes     [Hash]
+      # @param relationships  [Hash, nil]
+      # @param meta           [Hash, nil]
+      # @return [Object]
+      #
+      def create_resource(path, type, resource_class, attributes:, relationships: nil, meta: nil)
+        payload = build_payload(type, attributes, relationships: relationships, meta: meta)
+        response = @connection.post(path, payload)
+        @parser.parse(response['data'], resource_class, response: response)
+      end
+
+      ##
+      # Updates and parses a single resource.
+      #
+      # @param path           [String]
+      # @param id             [String]
+      # @param type           [String]
+      # @param resource_class [Class]
+      # @param attributes     [Hash]
+      # @param relationships  [Hash, nil]
+      # @param meta           [Hash, nil]
+      # @return [Object]
+      #
+      def update_resource(path, id, type, resource_class, attributes:, relationships: nil, meta: nil)
+        payload = build_payload(
+          type,
+          attributes,
+          id: id,
+          relationships: relationships,
+          meta: meta
+        )
+        response = @connection.patch(path, payload)
+        @parser.parse(response['data'], resource_class, response: response)
+      end
+
+      ##
+      # Deletes a resource and normalizes the nil return value.
+      #
+      # @param path [String]
+      # @return [nil]
+      #
+      def delete_resource(path)
+        @connection.delete(path)
+        nil
+      end
+
+      ##
+      # Fetches raw relationship linkage data.
+      #
+      # @param path   [String]
+      # @param params [Hash]
+      # @return [Hash, Array<Hash>, nil]
+      #
+      def fetch_relationship(path, params: {})
+        response = @connection.get(path, params: params)
+        response['data']
+      end
+
+      ##
+      # Creates a note under a notable resource.
+      #
+      # @param path [String]
+      # @param text [String]
+      # @return [ReactorSDK::Resources::Note]
+      #
+      def create_note_for_path(path, text)
+        create_resource(path, 'notes', Resources::Note, attributes: { text: text })
+      end
+
+      ##
+      # Lists note resources for a notable resource path.
+      #
+      # @param path [String]
+      # @return [Array<ReactorSDK::Resources::Note>]
+      #
+      def list_notes_for_path(path)
+        list_resources(path, Resources::Note)
+      end
+    end
+  end
+end

data/lib/reactor_sdk/endpoints/builds.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+##
+# @file endpoints/builds.rb
+# @description Endpoint group for Adobe Launch Build resources.
+#
+#   Builds are the compiled output of a library — the JavaScript bundle
+#   deployed to an environment. LaunchGuard polls build status after
+#   triggering a build to detect success or failure before notifying users.
+#
+# @domain Endpoints
+# @see https://developer.adobe.com/experience-platform/documentation/tags/api/endpoints/builds/
+#
+
+module ReactorSDK
+  module Endpoints
+    class Builds < BaseEndpoint
+      ##
+      # Retrieves a single build by its Adobe ID.
+      # Used to poll build status after a build is triggered.
+      #
+      # @param build_id [String] Adobe build ID (format: "BL" + hex string)
+      # @return [ReactorSDK::Resources::Build]
+      # @raise [ReactorSDK::ResourceNotFoundError] if the build does not exist
+      #
+      def find(build_id)
+        response = @connection.get("/builds/#{build_id}")
+        @parser.parse(response['data'], Resources::Build)
+      end
+
+      ##
+      # Lists all builds for a given library.
+      # Follows pagination automatically — returns all builds.
+      #
+      # @param library_id [String] Adobe library ID
+      # @return [Array<ReactorSDK::Resources::Build>]
+      # @raise [ReactorSDK::ResourceNotFoundError] if the library does not exist
+      #
+      def list_for_library(library_id)
+        records = @paginator.all("/libraries/#{library_id}/builds")
+        records.map { |r| @parser.parse(r, Resources::Build) }
+      end
+
+      ##
+      # Republishes an existing build.
+      #
+      # @param build_id [String]
+      # @return [ReactorSDK::Resources::Build]
+      #
+      def republish(build_id)
+        update_resource(
+          "/builds/#{build_id}",
+          build_id,
+          'builds',
+          Resources::Build,
+          attributes: {},
+          meta: { action: 'republish' }
+        )
+      end
+    end
+  end
+end

data/lib/reactor_sdk/endpoints/callbacks.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ReactorSDK
+  module Endpoints
+    class Callbacks < BaseEndpoint
+      def list_for_property(property_id)
+        list_resources("/properties/#{property_id}/callbacks", Resources::Callback)
+      end
+
+      def find(callback_id)
+        fetch_resource("/callbacks/#{callback_id}", Resources::Callback)
+      end
+
+      def create(property_id:, attributes:)
+        create_resource(
+          "/properties/#{property_id}/callbacks",
+          'callbacks',
+          Resources::Callback,
+          attributes: attributes
+        )
+      end
+
+      def update(callback_id, attributes)
+        update_resource(
+          "/callbacks/#{callback_id}",
+          callback_id,
+          'callbacks',
+          Resources::Callback,
+          attributes: attributes
+        )
+      end
+
+      def delete(callback_id)
+        delete_resource("/callbacks/#{callback_id}")
+      end
+    end
+  end
+end

data/lib/reactor_sdk/endpoints/companies.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+##
+# @file endpoints/companies.rb
+# @description Endpoint group for Adobe Launch Company resources.
+#
+#   A Company maps to an Adobe IMS Organisation and is the top-level
+#   container for all properties. Most orgs have exactly one company.
+#
+# @domain Endpoints
+# @see https://developer.adobe.com/experience-platform/documentation/tags/api/endpoints/companies/
+#
+
+module ReactorSDK
+  module Endpoints
+    class Companies < BaseEndpoint
+      ##
+      # Lists all companies accessible to the authenticated token.
+      # Follows pagination automatically — returns all companies.
+      #
+      # @return [Array<ReactorSDK::Resources::Company>]
+      # @raise [ReactorSDK::AuthorizationError] if the token lacks access
+      #
+      def list
+        records = @paginator.all('/companies')
+        records.map { |r| @parser.parse(r, Resources::Company) }
+      end
+
+      ##
+      # Retrieves a single company by its Adobe ID.
+      #
+      # @param company_id [String] Adobe company ID (format: "CO" + hex string)
+      # @return [ReactorSDK::Resources::Company]
+      # @raise [ReactorSDK::ResourceNotFoundError] if the company does not exist
+      #
+      def find(company_id)
+        response = @connection.get("/companies/#{company_id}")
+        @parser.parse(response['data'], Resources::Company)
+      end
+    end
+  end
+end

data/lib/reactor_sdk/endpoints/data_elements.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+##
+# @file endpoints/data_elements.rb
+# @description Endpoint group for Adobe Launch Data Element resources.
+#
+#   Data elements are reusable values that can be referenced throughout
+#   rules and other data elements. They form the data layer of Adobe Launch.
+#
+#   Creating a data element requires an extension relationship in the payload.
+#   Fetch the property's extensions first to obtain the extension_id.
+#
+#   Important: data elements must be revised before they can be added to
+#   a library. Call revise(data_element_id) before libraries.add_data_elements.
+#
+# @domain Endpoints
+# @see https://developer.adobe.com/experience-platform/documentation/tags/api/endpoints/data-elements/
+#
+
+module ReactorSDK
+  module Endpoints
+    class DataElements < BaseEndpoint
+      ##
+      # Lists all data elements for a given property.
+      # Follows pagination automatically — returns all data elements.
+      #
+      # @param property_id [String] Adobe property ID
+      # @return [Array<ReactorSDK::Resources::DataElement>]
+      # @raise [ReactorSDK::ResourceNotFoundError] if the property does not exist
+      #
+      def list_for_property(property_id)
+        records = @paginator.all("/properties/#{property_id}/data_elements")
+        records.map { |r| @parser.parse(r, Resources::DataElement) }
+      end
+
+      ##
+      # Retrieves a single data element by its Adobe ID.
+      #
+      # @param data_element_id [String] Adobe data element ID (format: "DE" + hex)
+      # @return [ReactorSDK::Resources::DataElement]
+      # @raise [ReactorSDK::ResourceNotFoundError] if the data element does not exist
+      #
+      def find(data_element_id)
+        response = @connection.get("/data_elements/#{data_element_id}")
+        @parser.parse(response['data'], Resources::DataElement)
+      end
+
+      ##
+      # Creates a new data element within a property.
+      #
+      # Requires an extension_id — fetch the property's extensions first:
+      #   extensions  = client.extensions.list_for_property(property_id)
+      #   extension_id = extensions.find { |e| e.delegate_descriptor_id.start_with?("core::") }.id
+      #
+      # The settings field must be a JSON-encoded string matching the delegate
+      # schema. For Core custom code the settings schema only allows "source" —
+      # do NOT include "language":
+      #   settings: JSON.generate({ source: "return document.title;" })
+      #
+      # @param property_id            [String]  Adobe property ID
+      # @param name                   [String]  Display name
+      # @param delegate_descriptor_id [String]  Extension delegate identifier
+      # @param settings               [String]  JSON-encoded settings string
+      # @param extension_id           [String]  Adobe extension ID
+      # @param enabled                [Boolean] Whether enabled (default: true)
+      # @return [ReactorSDK::Resources::DataElement]
+      # @raise [ReactorSDK::UnprocessableEntityError] if attributes are invalid
+      #
+      def create(
+        property_id:,
+        name:,
+        delegate_descriptor_id:,
+        settings:,
+        extension_id:,
+        enabled: true
+      )
+        payload  = build_data_element_payload(
+          name, delegate_descriptor_id, settings, extension_id, enabled
+        )
+        response = @connection.post("/properties/#{property_id}/data_elements", payload)
+        @parser.parse(response['data'], Resources::DataElement)
+      end
+
+      ##
+      # Updates an existing data element.
+      #
+      # @param data_element_id [String] Adobe data element ID
+      # @param attributes      [Hash]   Fields to update
+      # @return [ReactorSDK::Resources::DataElement]
+      # @raise [ReactorSDK::ResourceNotFoundError] if the data element does not exist
+      #
+      def update(data_element_id, attributes)
+        payload  = build_payload('data_elements', attributes, id: data_element_id)
+        response = @connection.patch("/data_elements/#{data_element_id}", payload)
+        @parser.parse(response['data'], Resources::DataElement)
+      end
+
+      ##
+      # Revises a data element 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.
+      #
+      # Always call revise after create or update, before libraries.add_data_elements.
+      #
+      # @param data_element_id [String] Adobe data element ID
+      # @return [ReactorSDK::Resources::DataElement] The revised data element
+      # @raise [ReactorSDK::ResourceNotFoundError] if the data element does not exist
+      #
+      def revise(data_element_id)
+        payload = {
+          data: {
+            id: data_element_id,
+            type: 'data_elements',
+            meta: { action: 'revise' }
+          }
+        }
+        response = @connection.patch("/data_elements/#{data_element_id}", payload)
+        @parser.parse(response['data'], Resources::DataElement)
+      end
+
+      ##
+      # Deletes a data element permanently.
+      #
+      # @param data_element_id [String] Adobe data element ID
+      # @return [nil]
+      # @raise [ReactorSDK::ResourceNotFoundError] if the data element does not exist
+      #
+      def delete(data_element_id)
+        @connection.delete("/data_elements/#{data_element_id}")
+        nil
+      end
+
+      ##
+      # Resolves the data element across the ordered upstream library chain.
+      #
+      # @param data_element_or_id [String, ReactorSDK::Resources::DataElement]
+      # @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(data_element_or_id, library_id:, property_id:)
+        libraries_endpoint.upstream_chain_for_resource(
+          data_element_or_id,
+          library_id: library_id,
+          property_id: property_id,
+          resource_type: 'data_elements'
+        )
+      end
+
+      ##
+      # Fetches the data element from a library-context review snapshot
+      # together with impact analysis and normalized review payload.
+      #
+      # @param data_element_id [String]
+      # @param library_id [String]
+      # @param property_id [String]
+      # @return [ReactorSDK::Resources::ComprehensiveDataElement]
+      #
+      def find_comprehensive(data_element_id, library_id:, property_id:)
+        snapshot = libraries_endpoint.find_snapshot(library_id, property_id: property_id)
+        comprehensive = snapshot.comprehensive_resource(data_element_id, resource_type: 'data_elements')
+        unless comprehensive
+          raise ReactorSDK::ResourceNotFoundError,
+                "Data element #{data_element_id} was not found in library #{library_id}"
+        end
+
+        comprehensive
+      end
+
+      ##
+      # Resolves the data element across the ordered upstream chain using
+      # snapshot-aware comprehensive review objects.
+      #
+      # @param data_element_or_id [String, ReactorSDK::Resources::DataElement]
+      # @param library_id [String]
+      # @param property_id [String]
+      # @return [ReactorSDK::Resources::ComprehensiveUpstreamChain]
+      #
+      def comprehensive_upstream_chain(data_element_or_id, library_id:, property_id:)
+        libraries_endpoint.comprehensive_upstream_chain_for_resource(
+          data_element_or_id,
+          library_id: library_id,
+          property_id: property_id,
+          resource_type: 'data_elements'
+        )
+      end
+
+      ##
+      # Lists notes attached to a data element.
+      #
+      # @param data_element_id [String]
+      # @return [Array<ReactorSDK::Resources::Note>]
+      #
+      def list_notes(data_element_id)
+        list_notes_for_path("/data_elements/#{data_element_id}/notes")
+      end
+
+      ##
+      # Creates a note on a data element.
+      #
+      # @param data_element_id [String]
+      # @param text [String]
+      # @return [ReactorSDK::Resources::Note]
+      #
+      def create_note(data_element_id, text)
+        create_note_for_path("/data_elements/#{data_element_id}/notes", text)
+      end
+
+      private
+
+      ##
+      # Builds the JSON:API payload for data element creation.
+      # Includes the required extension relationship.
+      #
+      # @param name                   [String]  Display name
+      # @param delegate_descriptor_id [String]  Delegate identifier
+      # @param settings               [String]  JSON-encoded settings
+      # @param extension_id           [String]  Extension providing the delegate
+      # @param enabled                [Boolean] Whether enabled
+      # @return [Hash] JSON:API compliant payload
+      #
+      def build_data_element_payload(name, delegate_descriptor_id, settings, extension_id, enabled)
+        {
+          data: {
+            type: 'data_elements',
+            attributes: {
+              name: name,
+              delegate_descriptor_id: delegate_descriptor_id,
+              settings: settings,
+              enabled: enabled
+            },
+            relationships: {
+              extension: {
+                data: { id: extension_id, type: 'extensions' }
+              }
+            }
+          }
+        }
+      end
+
+      def libraries_endpoint
+        @libraries_endpoint ||= Endpoints::Libraries.new(
+          connection: @connection,
+          paginator: @paginator,
+          parser: @parser
+        )
+      end
+    end
+  end
+end