Resource objects

ReactorSDK materializes Reactor API responses as typed Ruby resource objects instead of leaving application code to work with anonymous hashes. This page documents the common resource contract, the helper methods attached to specific resource classes, and the wrapper objects used for search and library inspection workflows.

Base resource contract

Every typed resource inherits from ReactorSDK::Resources::BaseResource and exposes a stable API for identifiers, raw attributes, metadata, and serialization.

Equality is based on resource id and type, not on object identity or the exact attribute payload currently loaded.

Typed helpers

Many resource classes add domain-specific helpers so service objects, background jobs, and CLI tooling can express behavior directly instead of repeatedly branching on raw string values.

These helpers are intentionally small, but they matter in production code because they remove repetitive conditional logic from orchestration layers.

Parsed settings

RuleComponent, DataElement, and Extension expose the raw settings field, but they also provide parsed_settings so callers can treat structured configuration consistently.

# RC123 = rule component ID.
# DE123 = data element ID.
# EX123 = extension ID.
# Load one rule component so you can inspect its raw and parsed settings.
component = client.rule_components.find("RC123")
# Load one data element for the same reason.
element   = client.data_elements.find("DE123")
# Load one extension instance.
extension = client.extensions.find("EX123")

# Raw settings are returned exactly as Adobe stored them.
puts component.settings
# parsed_settings normalizes the value to a Ruby hash when possible.
puts component.parsed_settings.inspect

# Access one parsed setting field directly from the data element hash.
puts element.parsed_settings["source"]
# Inspect the full parsed extension settings hash.
puts extension.parsed_settings.inspect

The behavior is intentionally forgiving:

• If settings is already a hash, parsed_settings returns it.
• If settings is a JSON string, parsed_settings parses it.
• If settings is blank or malformed, parsed_settings returns {} instead of raising.

Special wrappers

Several SDK return types are richer than a standard resource instance because they support specific higher-level workflows.

SearchResults

client.search.perform returns SearchResults, which wraps a heterogeneous collection of typed resources and top-level metadata such as total hit count.

LibraryWithResources

client.libraries.find_with_resources returns a richer library object that includes rules, data elements, and extensions from the JSON:API included array. Each included resource also exposes a gem-added revision_id reader sourced from relationships.latest_revision.data.id, so diffing, audit, and promotion workflows can operate against a single in-memory object graph.

# LB123 = library ID.
# Load a library together with included rules, data elements, and extensions.
library = client.libraries.find_with_resources("LB123")

# Read the latest revision ID attached to the first included rule.
puts library.rules.first.revision_id
# Print a flat resource_id => revision_id lookup hash.
puts library.resource_index.inspect
# Print all included resource IDs regardless of resource type.
puts library.all_resources.map(&:id).inspect

LibrarySnapshot

client.libraries.find_snapshot returns LibrarySnapshot, which is the SDK's review-oriented library wrapper. It keeps the library comparison context but enriches it with the associated records developers usually need during diff and code-review workflows.

# LB_DEV = library ID.
# PR123 = property ID.
# Load the snapshot-aware wrapper for one library.
snapshot = client.libraries.find_snapshot("LB_DEV", property_id: "PR123")

# Rule components are resolved for each rule in the library snapshot.
# When the rule revision includes `rule_components` linkage, the SDK uses that
# point-in-time membership to determine which components belong in the review object.
puts snapshot.rule_components_for_rule("RL123").map(&:id).inspect

# Direct data element dependencies inside the snapshot.
puts snapshot.referenced_data_elements_for("DE123").map(&:name).inspect

# Snapshot-scoped impacted rules, including transitive data element usage.
puts snapshot.impacted_rules_for("DE123").map(&:name).inspect

Comprehensive review wrappers

The additive comprehensive helpers return typed wrappers that keep the original Launch resource under resource, add associated records, and expose diff-ready normalized_payload and normalized_json.

# RL123 = rule ID.
# LB_DEV = library ID.
# PR123 = property ID.
rule = client.rules.find_comprehensive(
  "RL123",
  library_id: "LB_DEV",
  property_id: "PR123"
)

# Original Launch rule resource.
puts rule.resource.name
# Associated rule components from the same library snapshot.
puts rule.rule_components.map(&:name).inspect
# Pretty JSON intended for review and diff workflows.
puts rule.normalized_json

UpstreamChain

client.rules.upstream_chain, client.data_elements.upstream_chain, client.extensions.upstream_chain, and client.libraries.upstream_chain_for_resource return UpstreamChain. This wrapper packages the target library context, the target revision, and the ordered upstream entries into one object so applications do not have to hand-roll traversal loops.

# RL123 = rule ID.
# LB_DEV = development library ID.
# PR123 = property ID.
# Resolve the full upstream chain for one rule.
chain = client.rules.upstream_chain(
  "RL123",
  library_id: "LB_DEV",
  property_id: "PR123"
)

# Print the rule revision currently present in the target library.
puts chain.target_revision_id

# nearest_match is the first upstream library where the rule exists.
puts chain.nearest_match&.library&.id
puts chain.nearest_match&.stage
puts chain.nearest_match&.revision_id

# Iterate over every inspected upstream library.
chain.each do |entry|
  puts "#{entry.library.id} -> #{entry.present?}"
end

ComprehensiveUpstreamChain

client.rules.comprehensive_upstream_chain, client.data_elements.comprehensive_upstream_chain, client.extensions.comprehensive_upstream_chain, and client.libraries.comprehensive_upstream_chain_for_resource return ComprehensiveUpstreamChain.

Upstream comparison data

The upstream comparison model is represented in layers rather than as one composite object.

Chain layer

client.libraries.upstream_libraries(...) returns Array<Library>, ordered nearest upstream first. Those are plain Library resources, so the array gives you traversal order, not embedded comparison state.

Resolved chain layer

client.rules.upstream_chain(...), client.data_elements.upstream_chain(...), client.extensions.upstream_chain(...), and client.libraries.upstream_chain_for_resource(...) return UpstreamChain, which is the SDK's resource-centric upstream wrapper.

Comprehensive chain layer

client.rules.comprehensive_upstream_chain(...), client.data_elements.comprehensive_upstream_chain(...), client.extensions.comprehensive_upstream_chain(...), and client.libraries.comprehensive_upstream_chain_for_resource(...) return ComprehensiveUpstreamChain, which adds snapshot-aware associated records and normalized review payloads on top of the lean chain model.

Resource layer

client.libraries.find_with_resources(...) returns LibraryWithResources, which is the resource-level comparison shape for one library.

Snapshot layer

client.libraries.find_snapshot(...) returns LibrarySnapshot, which extends the library-level view with the associated records needed to understand behavioral impact.

Entry layer

Each UpstreamChainEntry describes one inspected upstream library.

Each ComprehensiveUpstreamChainEntry keeps the lean fields above and adds:

• comprehensive_resource
• normalized_payload
• normalized_json

Revision layer

When you pick a revision ID from resource_index, client.revisions.find(revision_id) returns a Revision object exposing:

• entity_id
• entity_type
• entity_snapshot
• entity_relationships

That final entity_snapshot hash is the point-in-time payload most apps compare once they have resolved the nearest upstream revision.