payload-api 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66c7eb5c0125eb3e66a5800851c6e66e42ae36138a2b89516b2ae8a823cacc7d
-  data.tar.gz: 602f23d391904acdb9ddf3540990692f8f54284746d3bba5eb528827f2f802da
+  metadata.gz: 74c2fd7f99fba4cf6b0f1950d013debc81c56629a5b280e7ac79e4e4abd88838
+  data.tar.gz: abf8b305b33a0e9a5241f5664807842989b7d423781f35606607298c9297d35a
 SHA512:
-  metadata.gz: 19b0346676cab8cbd11a997fbb30f2a9ccec35eb16bfe7905da763efc6f5b7efc27002ac828ff0b14041e284bdd10d0cbc093dbb3d09350dd08bb5cd82bfa1af
-  data.tar.gz: 7abac9292dcc52fe334f4182f59d6c4253242451a5f3e4aec7997399a6469c56caadf3862b511529d08b5e65c5779764ad868b2e06134266500deedbfa0e73f4
+  metadata.gz: 0e34c4a1a585078565d876af179d8e9b3344888ca44a08f9465ac2e740f5f112990d8b7564b7c0394e21dc4eae22c9b5e0e804850c23cb39d5ffd789ad055319
+  data.tar.gz: ad8721f83c061113c6abcf4e26f7077e9c07b7a4d34b60d8cdaa9d4f61ad599443cc1e8511d46983d7acd368601b6596b42cd6cef9509dd3cc4a0a89c9492202

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2024 Payload (http://payload.com)
+Copyright (c) 2026 Payload (http://payload.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/payload/arm/attr.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Payload
+  class ARMFilter
+    attr_reader :attr, :opval, :val
+
+    def initialize(attr, val)
+      @attr = attr.to_s
+      @val = val
+      @opval = self.class.op + val.to_s
+    end
+
+    def self.op
+      ''
+    end
+
+    def |(other)
+      raise TypeError, 'invalid type' unless other.is_a?(Payload::ARMFilter)
+      raise ArgumentError, '`or` only works on the same attribute' if other.attr != @attr
+      joined = [@opval, other.opval].join('|')
+      Payload::ARMEqual.new(@attr, joined)
+    end
+  end
+
+  class ARMEqual < ARMFilter
+    def self.op
+      ''
+    end
+  end
+
+  class ARMNotEqual < ARMFilter
+    def self.op
+      '!'
+    end
+  end
+
+  class ARMGreaterThan < ARMFilter
+    def self.op
+      '>'
+    end
+  end
+
+  class ARMLessThan < ARMFilter
+    def self.op
+      '<'
+    end
+  end
+
+  class ARMGreaterThanEqual < ARMFilter
+    def self.op
+      '>='
+    end
+  end
+
+  class ARMLessThanEqual < ARMFilter
+    def self.op
+      '<='
+    end
+  end
+
+  class ARMContains < ARMFilter
+    def self.op
+      '?*'
+    end
+  end
+
+  # Root proxy for pl.attr so that pl.attr.name returns an Attr (not Class#name).
+  # Session#attr returns this instead of the Attr class to avoid Class/Module methods (e.g. .name) shadowing attribute names.
+  class AttrRoot
+    def method_missing(name, *args)
+      if args.size == 1 && args[0].is_a?(Symbol)
+        inner = Attr.new(name.to_s)
+        Attr.new(args[0].to_s, inner).call
+      else
+        Attr.new(name.to_s)
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      true
+    end
+  end
+
+  # Attribute DSL for select/group_by/order_by and filter expressions.
+  # - pl.attr.id -> "id"
+  # - pl.attr.created_at(:month) -> "month(created_at)"
+  # - pl.attr.amount(:sum) -> "sum(amount)"
+  # - pl.attr.sender.account_id -> "sender[account_id]"
+  class Attr
+    attr_reader :param, :parent
+
+    class << self
+      def method_missing(name, *args)
+        new(name.to_s)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        true
+      end
+    end
+
+    def initialize(param, parent = nil)
+      @param = param.to_s
+      @parent = parent
+      @is_method = false
+    end
+
+    def key
+      @parent ? "#{@parent.key}[#{@param}]" : @param
+    end
+
+    def to_s
+      @is_method ? "#{@param}(#{@parent.key})" : key
+    end
+
+    def strip
+      to_s.strip
+    end
+
+    def method_missing(name, *args)
+      raise "cannot get attr of method" if @is_method
+
+      if args.size == 1 && args[0].is_a?(Symbol)
+        inner = Attr.new(name.to_s, self)
+        Attr.new(args[0].to_s, inner).call
+      else
+        Attr.new(name.to_s, self)
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      true
+    end
+
+    # Mark attribute as a function call (e.g. .month(), .sum())
+    def call
+      @is_method = true
+      self
+    end
+
+    def ==(other)
+      ARMEqual.new(self, other)
+    end
+
+    def !=(other)
+      ARMNotEqual.new(self, other)
+    end
+
+    def >(other)
+      ARMGreaterThan.new(self, other)
+    end
+
+    def <(other)
+      ARMLessThan.new(self, other)
+    end
+
+    def >=(other)
+      ARMGreaterThanEqual.new(self, other)
+    end
+
+    def <=(other)
+      ARMLessThanEqual.new(self, other)
+    end
+
+    def contains(other)
+      ARMContains.new(self, other)
+    end
+  end
+end

data/lib/payload/arm/object.rb

@@ -29,11 +29,26 @@ module Payload
 		def get(id)
 			return @cls.get(id, :session => @session)
 		end
-		
+
 		def select(*args, **data)
 			@cls.select(*args, **data, session: @session)
 		end
 
+		def order_by(*args, **data)
+			@cls.order_by(*args, **data, session: @session)
+		end
+
+		def limit(n, **data)
+			@cls.limit(n, **data, session: @session)
+		end
+
+		def offset(n, **data)
+			@cls.offset(n, **data, session: @session)
+		end
+
+		def group_by(*args, **data)
+			@cls.group_by(*args, **data, session: @session)
+		end
 	end
 
 	class ARMObject
@@ -103,7 +118,7 @@ module Payload
 		end
 
 		def [](key)
-			return @data[key]
+			return @data[key.to_s]
 		end
 
 		def _get_request()
@@ -118,6 +133,22 @@ module Payload
 			return self._get_request().select(*args, **data)
 		end
 
+		def self.order_by(*args, **data)
+			self._get_request().order_by(*args, **data)
+		end
+
+		def self.limit(n, **data)
+			self._get_request().limit(n)
+		end
+
+		def self.offset(n, **data)
+			self._get_request().offset(n)
+		end
+
+		def self.group_by(*args, **data)
+			self._get_request().group_by(*args, **data)
+		end
+
 		def self.filter_by(*args, **data)
 			session = data[:session]
 			data.delete(:session)
@@ -154,6 +185,10 @@ module Payload
 			return _get_request()._request('Delete', id: self.id)
 		end
 
+		def json
+			to_json
+		end
+
 		def to_json(*args)
 			serialized = {}
 			if self.class.poly

data/lib/payload/arm/request.rb

@@ -1,5 +1,6 @@
 require "payload/exceptions"
 require "payload/utils"
+require "payload/arm/attr"
 require "net/http"
 require "uri"
 require "json"
@@ -12,21 +13,46 @@ module Payload
 			@cls = cls
 			@session = session || Payload::Session.new(Payload::api_key, Payload::api_url)
 			@filters = {}
+			@group_by = []
+			@order_by = []
+			@limit = nil
+			@offset = nil
+			@filter_objects = []
 		end
 
 		def select(*args, **data)
-			@filters['fields'] = args.map {|a| a.strip }.join(',')
-
+			@filters['fields'] = args.map { |a| a.strip }.join(',')
 			return self
 		end
 
+		def group_by(*args, **data)
+			@group_by.concat(args)
+			self
+		end
+
+		def order_by(*args, **data)
+			@order_by.concat(args)
+			self
+		end
+
+		def limit(n)
+			@limit = n
+			self
+		end
+
+		def offset(n)
+			@offset = n
+			self
+		end
+
 		def filter_by(*args, **data)
+			args.each do |f|
+				@filter_objects << f if f.respond_to?(:attr) && f.respond_to?(:opval)
+			end
 			if !@cls.nil? && @cls.poly
 				data = data.merge(@cls.poly)
 			end
-
 			@filters = @filters.merge(data)
-
 			return self
 		end
 
@@ -35,6 +61,17 @@ module Payload
 			return self._request('Get')
 		end
 
+		def [](key)
+			case key
+			when Range
+				raise ArgumentError, 'Negative slice indices not supported' if key.begin && key.begin < 0
+				raise ArgumentError, 'Negative slice indices not supported' if key.end && key.end < 0
+				offset(key.begin).limit(key.size).all()
+			else
+				raise TypeError, "invalid key or index: #{key.inspect}"
+			end
+		end
+
 		def get(id)
 			if id.nil? || id.empty?
 				throw 'id cannot be empty'
@@ -127,6 +164,16 @@ module Payload
 			http.request(request)
 		end
 
+		def request_params
+			params = @filters.dup
+			@filter_objects.each { |f| params[f.attr] = f.opval }
+			@group_by.each_with_index { |v, i| params["group_by[#{i}]"] = v.to_s }
+			@order_by.each_with_index { |v, i| params["order_by[#{i}]"] = v.to_s }
+			params['limit'] = @limit.to_s if @limit
+			params['offset'] = @offset.to_s if @offset
+			params
+		end
+
 		def _request(method, id: nil, json: nil)
 			if !@cls.nil?
 				if @cls.spec.key?("endpoint")
@@ -146,8 +193,9 @@ module Payload
 				endpoint = File.join(endpoint, id)
 			end
 
+			params = request_params
 			url = URI.join(@session.api_url, endpoint)
-			url.query = URI.encode_www_form(@filters)
+			url.query = URI.encode_www_form(params)
 
 			http = Net::HTTP.new(url.host, url.port)
 

data/lib/payload/arm/session.rb

@@ -1,15 +1,15 @@
 require 'payload/arm/request'
-
+require 'payload/arm/attr'
 
 module Payload
     class Session
         attr_accessor :api_key, :api_url, :api_version
-
+        
         def initialize(api_key = nil, api_url = nil, api_version = nil, **kwargs)
             @api_key = kwargs[:api_key] || api_key
             @api_url = kwargs[:api_url] || api_url || Payload.URL
             @api_version = kwargs[:api_version] || api_version || Payload.api_version
-        
+            
             Payload.constants.each do |c|
                 val = Payload.const_get(c)
                 if val.is_a?(Class) && val < Payload::ARMObject
@@ -17,11 +17,15 @@ module Payload
                 end
             end
         end
-
+        
         def _get_request(cls = nil)
             return Payload::ARMRequest.new(cls, self)
         end
 
+        def attr
+            Payload::AttrRoot.new
+        end
+        
         def query(cls)
             return self._get_request(cls)
         end

data/lib/payload/exceptions.rb

@@ -18,6 +18,21 @@ module Payload
 		@code='400'
 	end
 
+	class TransactionDeclined < BadRequest
+		attr_reader :transaction
+
+		def initialize(msg, data = nil)
+			super(msg, data)
+			@transaction = if data && data['details'].is_a?(Hash)
+				cls = Payload.get_cls(data['details'])
+				cls = Payload::Transaction if cls.nil?
+				cls.new(data['details'], nil)
+			else
+				nil
+			end
+		end
+	end
+
 	class InvalidAttributes < PayloadError
 		@code='400'
 	end

data/lib/payload/objects.rb

@@ -62,10 +62,18 @@ module Payload
 		@spec = { 'object' => 'invoice' }
 	end
 
+	class InvoiceAttachment < ARMObject
+		@spec = { 'object' => 'invoice_attachment' }
+	end
+
 	class PaymentActivation < ARMObject
 		@spec = { 'object' => 'payment_activation' }
 	end
 
+	class ProcessingSettings < ARMObject
+		@spec = { 'object' => 'processing_settings' }
+	end
+
 	class Webhook < ARMObject
 		@spec = { 'object' => 'webhook' }
 	end
@@ -96,7 +104,7 @@ module Payload
 	class ProcessingAccount < ARMObject
 		@spec = { 'object' => 'processing_account' }
 	end
-	
+
 	class Org < ARMObject
 		@spec = { 'object' => 'org', 'endpoint' => '/account/orgs' }
 	end
@@ -123,7 +131,7 @@ module Payload
 	end
 
 	class Entity < ARMObject
-		@spec = { 'object' => 'entity' }
+		@spec = { 'object' => 'entity', 'endpoint' => 'entities' }
 	end
 
 	class Stakeholder < ARMObject

data/lib/payload/version.rb

@@ -1,3 +1,3 @@
 module Payload
-    VERSION = '0.5.0'
-end
+    VERSION = '0.6.0'
+end

data/spec/payload/arm/arm_request_query_spec.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "payload"
+require "payload/arm/object"
+
+RSpec.describe Payload::ARMRequest do
+  describe "#group_by" do
+    let(:instance) { described_class.new(Payload::Invoice, nil) }
+
+    it "appends to group_by and returns self" do
+      year_attr = Payload::Attr.new("year", Payload::Attr.new("created_at"))
+      year_attr.call
+      result = instance.group_by(year_attr, Payload::Attr.status)
+      expect(result).to be(instance)
+      expect(instance.instance_variable_get(:@group_by).map(&:to_s)).to eq(["year(created_at)", "status"])
+    end
+
+    it "includes group_by in request params when all() is called" do
+      Payload::api_key = "test_key"
+      instance.instance_variable_set(:@cls, Payload::Invoice)
+
+      expect(instance).to receive(:_execute_request) do |_http, request|
+        query = request.path.split("?")[1]
+        expect(query).to include("group_by%5B0%5D=") # group_by[0]=
+        expect(query).to include("group_by%5B1%5D=") # group_by[1]=
+        QuerySpecMockResponse.new('{"object":"list","values":[]}')
+      end
+
+      instance.group_by("year(created_at)", "status").all()
+    end
+  end
+
+  describe "#order_by" do
+    let(:instance) { described_class.new(Payload::Account, nil) }
+
+    it "appends to order_by and returns self" do
+      result = instance.order_by("created_at", "desc(id)")
+      expect(result).to be(instance)
+      expect(instance.instance_variable_get(:@order_by)).to eq(["created_at", "desc(id)"])
+    end
+
+    it "includes order_by in request params when all() is called" do
+      Payload::api_key = "test_key"
+      instance.instance_variable_set(:@cls, Payload::Account)
+
+      expect(instance).to receive(:_execute_request) do |_http, request|
+        query = request.path.split("?")[1]
+        expect(query).to include("order_by%5B0%5D=created_at")
+        expect(query).to include("order_by%5B1%5D=desc%28id%29")
+        QuerySpecMockResponse.new('{"object":"list","values":[]}')
+      end
+
+      instance.order_by("created_at", "desc(id)").all()
+    end
+  end
+
+  describe "#limit and #offset" do
+    let(:instance) { described_class.new(Payload::Account, nil) }
+
+    it "sets limit and offset and returns self" do
+      result = instance.limit(10).offset(20)
+      expect(result).to be(instance)
+      expect(instance.instance_variable_get(:@limit)).to eq(10)
+      expect(instance.instance_variable_get(:@offset)).to eq(20)
+    end
+
+    it "includes limit and offset in request params when all() is called" do
+      Payload::api_key = "test_key"
+      instance.instance_variable_set(:@cls, Payload::Account)
+
+      expect(instance).to receive(:_execute_request) do |_http, request|
+        query = request.path.split("?")[1]
+        expect(query).to include("limit=10")
+        expect(query).to include("offset=20")
+        QuerySpecMockResponse.new('{"object":"list","values":[]}')
+      end
+
+      instance.limit(10).offset(20).all()
+    end
+  end
+
+  describe "#request_params" do
+    it "merges filters, filter_objects, group_by, order_by, limit, offset into query params" do
+      instance = described_class.new(Payload::Transaction, nil)
+      instance.instance_variable_set(:@filters, { "fields" => "id,amount" })
+      instance.instance_variable_set(:@group_by, ["status"])
+      instance.instance_variable_set(:@order_by, ["desc(created_at)"])
+      instance.instance_variable_set(:@limit, 5)
+      instance.instance_variable_set(:@offset, 10)
+
+      filter_obj = Payload::ARMGreaterThan.new(Payload::Attr.amount, 100)
+      instance.instance_variable_set(:@filter_objects, [filter_obj])
+
+      params = instance.request_params
+
+      expect(params["fields"]).to eq("id,amount")
+      expect(params["group_by[0]"]).to eq("status")
+      expect(params["order_by[0]"]).to eq("desc(created_at)")
+      expect(params["limit"]).to eq("5")
+      expect(params["offset"]).to eq("10")
+      expect(params[filter_obj.attr]).to eq(filter_obj.opval)
+    end
+
+    it "is encoded as URL query string in _request (url.query = URI.encode_www_form(params))" do
+      Payload::api_key = "test_key"
+      session = Payload::Session.new("test_key", "https://api.test.com", "v2")
+      instance = described_class.new(Payload::Invoice, session)
+      instance.select("id", "status").filter_by(session.attr.status == "open").order_by("created_at").limit(5).offset(1)
+
+      expected_params = instance.request_params.dup
+
+      expect(instance).to receive(:_execute_request) do |_http, request|
+        query_str = request.path.split("?", 2)[1]
+        expect(query_str).not_to be_nil
+        decoded = URI.decode_www_form(query_str || "").to_h
+        expected_params.each do |key, value|
+          expect(decoded[key]).to eq(value.to_s)
+        end
+        expect(decoded).to include("fields" => "id,status", "limit" => "5", "offset" => "1")
+        expect(decoded.keys).to include("status", "order_by[0]")
+        QuerySpecMockResponse.new('{"object":"list","values":[]}')
+      end
+
+      instance.all()
+    end
+  end
+
+  describe "#[] (slice)" do
+    let(:instance) { described_class.new(Payload::Account, nil) }
+
+    it "raises TypeError for non-Range key" do
+      expect { instance["foo"] }.to raise_error(TypeError, /invalid key or index/)
+      expect { instance[5] }.to raise_error(TypeError, /invalid key or index/)
+    end
+
+    it "raises ArgumentError for negative begin" do
+      expect { instance[-1..10] }.to raise_error(ArgumentError, /Negative slice indices not supported/)
+    end
+
+    it "raises ArgumentError for negative end" do
+      expect { instance[0..-5] }.to raise_error(ArgumentError, /Negative slice indices not supported/)
+    end
+
+    it "calls offset(begin).limit(size).all() for a range and returns result" do
+      Payload::api_key = "test_key"
+      instance.instance_variable_set(:@cls, Payload::Account)
+
+      expect(instance).to receive(:_execute_request) do |_http, request|
+        query = request.path.split("?")[1]
+        expect(query).to include("offset=10")
+        expect(query).to include("limit=10")
+        QuerySpecMockResponse.new('{"object":"list","values":[{"id":"acct_1","object":"customer"}]}')
+      end
+
+      result = instance[10..19]
+      expect(result).to be_an(Array)
+      expect(result.size).to eq(1)
+      expect(result[0].id).to eq("acct_1")
+    end
+  end
+
+  describe "#filter_by with pl.attr filter objects" do
+    it "extracts ARM filter objects and merges their attr/opval into request params" do
+      session = Payload::Session.new("test_key", "https://api.test.com", "v2")
+      instance = described_class.new(Payload::Transaction, session)
+      pl = session
+      filter_expr = (pl.attr.amount > 100) | (pl.attr.amount < 200)
+
+      instance.filter_by(filter_expr)
+
+      expect(instance.instance_variable_get(:@filter_objects)).to include(be_a(Payload::ARMFilter))
+      params = instance.request_params
+      expect(params.keys).to include(filter_expr.attr)
+      expect(params[filter_expr.attr]).to eq(filter_expr.opval)
+    end
+
+    it "builds GET request with filter object serialized in query string" do
+      Payload::api_key = "test_key"
+      session = Payload::Session.new("test_key", "https://api.test.com", "v2")
+      instance = described_class.new(Payload::Transaction, session)
+      filter_expr = session.attr.amount > 100
+
+      instance.filter_by(filter_expr)
+
+      expect(instance).to receive(:_execute_request) do |_http, request|
+        query = request.path.split("?")[1]
+        expect(query).to include("amount=")
+        expect(query).to include("%3E100") # URL-encoded ">100"
+        QuerySpecMockResponse.new('{"object":"list","values":[]}')
+      end
+
+      instance.all()
+    end
+  end
+
+  describe "#filter_by with multiple filters" do
+    it "accumulates multiple filter objects and merges keyword filters into @filters" do
+      instance = described_class.new(Payload::Invoice, nil)
+      f1 = Payload::ARMEqual.new(Payload::Attr.status, "open")
+      f2 = Payload::ARMGreaterThan.new(Payload::Attr.amount, 50)
+
+      instance.filter_by(f1).filter_by(f2).filter_by(custom_key: "value")
+
+      fo = instance.instance_variable_get(:@filter_objects)
+      expect(fo).to include(f1, f2)
+      params = instance.request_params
+      expect(params["status"]).to eq("open")
+      expect(params["amount"]).to eq(">50")
+      expect(instance.instance_variable_get(:@filters)[:custom_key]).to eq("value")
+    end
+  end
+end
+
+class QuerySpecMockResponse
+  def initialize(body = '{"object":"list","values":[]}')
+    @body = body
+  end
+
+  def code
+    "200"
+  end
+
+  def body
+    @body
+  end
+end

data/spec/payload/arm/attr_spec.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "payload"
+require "payload/arm/attr"
+
+RSpec.describe Payload::AttrRoot do
+  let(:root) { described_class.new }
+
+  describe "attribute access" do
+    it "returns an Attr for any method name" do
+      expect(root.id).to be_a(Payload::Attr)
+      expect(root.id.to_s).to eq("id")
+      expect(root.created_at).to be_a(Payload::Attr)
+      expect(root.created_at.to_s).to eq("created_at")
+    end
+
+    it "returns an Attr for chained property access (non-callable names stay as nested key)" do
+      chained = root.sender.account_id
+      expect(chained).to be_a(Payload::Attr)
+      expect(chained.to_s).to eq("sender[account_id]")
+    end
+
+    it "treats no-arg access as nested attribute" do
+      expect(root.created_at.month.to_s).to eq("created_at[month]")
+      expect(root.created_at.year.to_s).to eq("created_at[year]")
+    end
+
+    it "supports pl.attr.created_at(:month) style (function as symbol arg)" do
+      expect(root.created_at(:month).to_s).to eq("month(created_at)")
+      expect(root.created_at(:year).to_s).to eq("year(created_at)")
+      expect(root.amount(:sum).to_s).to eq("sum(amount)")
+    end
+
+    it "supports nested attr with symbol: pl.attr.totals.total(:sum) => sum(totals[total])" do
+      expect(root.totals.total(:sum).to_s).to eq("sum(totals[total])")
+    end
+  end
+end
+
+RSpec.describe Payload::Attr do
+  describe "simple attribute" do
+    it "has key and to_s as the param when no parent" do
+      attr = Payload::Attr.new("amount")
+      expect(attr.key).to eq("amount")
+      expect(attr.to_s).to eq("amount")
+    end
+  end
+
+  describe "nested attribute" do
+    it "builds key and to_s as parent[param]" do
+      parent = Payload::Attr.new("totals")
+      attr = Payload::Attr.new("total", parent)
+      expect(attr.key).to eq("totals[total]")
+      expect(attr.to_s).to eq("totals[total]")
+    end
+  end
+
+  describe "function form (after .call)" do
+    it "serializes as name(parent_key) when marked as method" do
+      parent = Payload::Attr.new("created_at")
+      attr = Payload::Attr.new("month", parent)
+      attr.call
+      expect(attr.to_s).to eq("month(created_at)")
+    end
+
+    it "serializes nested path in function form" do
+      parent = Payload::Attr.new("total", Payload::Attr.new("totals"))
+      attr = Payload::Attr.new("sum", parent)
+      attr.call
+      expect(attr.to_s).to eq("sum(totals[total])")
+    end
+
+    it "raises when chaining after a method" do
+      parent = Payload::Attr.new("created_at")
+      attr = Payload::Attr.new("month", parent)
+      attr.call
+      expect { attr.day }.to raise_error(RuntimeError, /cannot get attr of method/)
+    end
+  end
+
+  describe "#strip" do
+    it "returns to_s.strip so Attr works with request.select(*args, **data) and args.map(&:strip)" do
+      inner = Payload::Attr.new("created_at")
+      year_attr = Payload::Attr.new("year", inner)
+      year_attr.call
+      expect(year_attr.strip).to eq("year(created_at)")
+    end
+  end
+
+  describe "comparisons (return ARMFilter subclasses)" do
+    let(:attr_amount) { Payload::Attr.new("amount") }
+    let(:attr_status) { Payload::Attr.new("status") }
+
+    it "== returns ARMEqual with correct attr and opval" do
+      f = attr_status == "processed"
+      expect(f).to be_a(Payload::ARMEqual)
+      expect(f.attr).to eq("status")
+      expect(f.opval).to eq("processed")
+    end
+
+    it "!= returns ARMNotEqual with ! prefix" do
+      f = attr_status != "draft"
+      expect(f).to be_a(Payload::ARMNotEqual)
+      expect(f.attr).to eq("status")
+      expect(f.opval).to eq("!draft")
+    end
+
+    it "> returns ARMGreaterThan" do
+      f = attr_amount > 100
+      expect(f).to be_a(Payload::ARMGreaterThan)
+      expect(f.attr).to eq("amount")
+      expect(f.opval).to eq(">100")
+    end
+
+    it "< returns ARMLessThan" do
+      f = attr_amount < 500
+      expect(f).to be_a(Payload::ARMLessThan)
+      expect(f.opval).to eq("<500")
+    end
+
+    it ">= returns ARMGreaterThanEqual" do
+      f = attr_amount >= 100
+      expect(f).to be_a(Payload::ARMGreaterThanEqual)
+      expect(f.opval).to eq(">=100")
+    end
+
+    it "<= returns ARMLessThanEqual" do
+      f = attr_amount <= 100
+      expect(f).to be_a(Payload::ARMLessThanEqual)
+      expect(f.opval).to eq("<=100")
+    end
+
+    it "contains returns ARMContains with ?* op" do
+      attr = Payload::Attr.new("description")
+      f = attr.contains("INV -")
+      expect(f).to be_a(Payload::ARMContains)
+      expect(f.attr).to eq("description")
+      expect(f.opval).to eq("?*INV -")
+    end
+
+    it "comparisons use Attr key for nested paths" do
+      nested = Payload::Attr.new("total", Payload::Attr.new("totals"))
+      f = nested > 0
+      expect(f.attr).to eq("totals[total]")
+      expect(f.opval).to eq(">0")
+    end
+  end
+
+  describe "Attr class-level (Payload::Attr.name)" do
+    it "returns Attr via method_missing" do
+      expect(Payload::Attr.created_at).to be_a(Payload::Attr)
+      expect(Payload::Attr.created_at.to_s).to eq("created_at")
+    end
+  end
+end
+
+RSpec.describe Payload::ARMFilter do
+  describe "#| (OR)" do
+    it "combines two filters on the same attribute and returns ARMEqual with joined opval" do
+      left = Payload::ARMGreaterThan.new(Payload::Attr.amount, 100)
+      right = Payload::ARMLessThan.new(Payload::Attr.amount, 50)
+      combined = left | right
+      expect(combined).to be_a(Payload::ARMEqual)
+      expect(combined.attr).to eq("amount")
+      expect(combined.opval).to eq(">100|<50")
+    end
+
+    it "raises TypeError when other is not an ARMFilter" do
+      f = Payload::ARMEqual.new(Payload::Attr.status, "active")
+      expect { f | "invalid" }.to raise_error(TypeError, /invalid type/)
+    end
+
+    it "raises ArgumentError when attributes differ" do
+      f1 = Payload::ARMEqual.new(Payload::Attr.status, "active")
+      f2 = Payload::ARMEqual.new(Payload::Attr.type, "payment")
+      expect { f1 | f2 }.to raise_error(ArgumentError, /only works on the same attribute/)
+    end
+  end
+
+  describe "filter subclasses op values" do
+    it "ARMEqual has empty op" do
+      f = Payload::ARMEqual.new("status", "active")
+      expect(f.opval).to eq("active")
+    end
+
+    it "ARMNotEqual has ! prefix" do
+      f = Payload::ARMNotEqual.new("status", "draft")
+      expect(f.opval).to eq("!draft")
+    end
+
+    it "ARMGreaterThan has > prefix" do
+      f = Payload::ARMGreaterThan.new("amount", 100)
+      expect(f.opval).to eq(">100")
+    end
+
+    it "ARMLessThan has < prefix" do
+      f = Payload::ARMLessThan.new("amount", 200)
+      expect(f.opval).to eq("<200")
+    end
+
+    it "ARMGreaterThanEqual has >= prefix" do
+      f = Payload::ARMGreaterThanEqual.new("amount", 100)
+      expect(f.opval).to eq(">=100")
+    end
+
+    it "ARMLessThanEqual has <= prefix" do
+      f = Payload::ARMLessThanEqual.new("amount", 100)
+      expect(f.opval).to eq("<=100")
+    end
+
+    it "ARMContains has ?* prefix" do
+      f = Payload::ARMContains.new("email", "example.com")
+      expect(f.opval).to eq("?*example.com")
+    end
+  end
+end

data/spec/payload/arm/object_spec.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "payload"
+require "payload/arm/object"
+
+RSpec.describe Payload::ARMObject do
+  describe "method_missing (attribute access)" do
+    let(:session) { Payload::Session.new("test_key", "https://api.test.com", "v2") }
+
+    it "returns value for present key" do
+      obj = Payload::Invoice.new({ "id" => "inv_1", "amount" => 100 }, session)
+      expect(obj.id).to eq("inv_1")
+      expect(obj.amount).to eq(100)
+    end
+
+    it "raises NoMethodError for missing key (strict behavior preserved)" do
+      obj = Payload::Invoice.new({ "id" => "inv_1" }, session)
+      expect { obj.nonexistent_key }.to raise_error(NoMethodError, /nonexistent_key/)
+      expect { obj.amount }.to raise_error(NoMethodError, /amount/)
+    end
+
+    it "strips trailing = for setter-like names and returns value" do
+      obj = Payload::Account.new({ "name" => "Acme" }, session)
+      expect(obj.name).to eq("Acme")
+    end
+  end
+
+  describe "#json" do
+    let(:session) { Payload::Session.new("test_key", "https://api.test.com", "v2") }
+
+    it "returns same as to_json" do
+      obj = Payload::Invoice.new({ "id" => "inv_1", "object" => "invoice" }, session)
+      expect(obj.json).to eq(obj.to_json)
+      expect(obj.json).to include("inv_1")
+      expect(obj.json).to include("invoice")
+    end
+  end
+
+  describe ".order_by, .limit, .offset" do
+    it "delegates to ARMRequest and returns chainable request" do
+      req = Payload::Invoice.order_by("created_at")
+      expect(req).to be_a(Payload::ARMRequest)
+      expect(req.instance_variable_get(:@order_by)).to include("created_at")
+
+      req = Payload::Invoice.limit(10)
+      expect(req.instance_variable_get(:@limit)).to eq(10)
+
+      req = Payload::Invoice.offset(20)
+      expect(req.instance_variable_get(:@offset)).to eq(20)
+    end
+  end
+
+  describe ".select" do
+    it "delegates to ARMRequest and sets fields filter" do
+      req = Payload::Invoice.select("id", "amount")
+      expect(req).to be_a(Payload::ARMRequest)
+      expect(req.instance_variable_get(:@filters)["fields"]).to eq("id,amount")
+    end
+  end
+
+  describe "#[] (bracket access)" do
+    let(:session) { Payload::Session.new("test_key", "https://api.test.com", "v2") }
+
+    it "returns value for string key" do
+      obj = Payload::Invoice.new({ "id" => "inv_1", "status" => "open" }, session)
+      expect(obj["id"]).to eq("inv_1")
+      expect(obj["status"]).to eq("open")
+    end
+
+    it "returns value for symbol key (data keys are stored as strings)" do
+      obj = Payload::Invoice.new({ "id" => "inv_1" }, session)
+      expect(obj[:id]).to eq("inv_1")
+    end
+
+    it "returns nil for missing key" do
+      obj = Payload::Invoice.new({ "id" => "inv_1" }, session)
+      expect(obj["missing"]).to be_nil
+    end
+  end
+
+  describe "#to_json" do
+    let(:session) { Payload::Session.new("test_key", "https://api.test.com", "v2") }
+
+    it "includes @data in JSON output" do
+      obj = Payload::Invoice.new({ "id" => "inv_1", "object" => "invoice", "amount" => 99 }, session)
+      json = obj.to_json
+      expect(json).to include("inv_1")
+      expect(json).to include("invoice")
+      expect(json).to include("99")
+    end
+
+    it "merges class poly when present" do
+      obj = Payload::Payment.new({ "id" => "txn_1", "object" => "transaction", "type" => "payment" }, session)
+      json = obj.to_json
+      expect(json).to include("payment")
+      expect(json).to include("txn_1")
+    end
+  end
+
+  describe "#respond_to_missing?" do
+    let(:session) { Payload::Session.new("test_key", "https://api.test.com", "v2") }
+
+    it "returns true for key present in data" do
+      obj = Payload::Invoice.new({ "id" => "inv_1", "amount" => 100 }, session)
+      expect(obj.respond_to?(:id)).to be true
+      expect(obj.respond_to?(:amount)).to be true
+    end
+
+    it "returns false for key missing from data (so method_missing will call super)" do
+      obj = Payload::Invoice.new({ "id" => "inv_1" }, session)
+      expect(obj.respond_to?(:nonexistent_key)).to be false
+    end
+  end
+end

data/spec/payload/arm/request_format_integration_spec.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "payload"
+require "payload/arm/object"
+require_relative "../../support/helpers"
+
+RSpec.describe "confirm request format is valid" do
+  include_context "test helpers"
+
+  [1, 2].each do |api_version|
+    context "API v#{api_version}" do
+      let(:session) { Payload::Session.new(Payload.api_key, Payload.api_url, api_version) }
+      let(:pl) { session }
+
+      context "date functions" do
+        it "filter with year(attr) ==" do
+          results = pl.Transaction.filter_by(
+            pl.attr.type == "payment",
+            pl.attr.created_at(:year) == Time.now.year
+          ).limit(5).all
+          expect(results).to be_an(Array)
+        end
+
+        it "filter with month(attr) ==" do
+          results = pl.Transaction.filter_by(
+            pl.attr.created_at(:month) == Time.now.month
+          ).limit(5).all
+          expect(results).to be_an(Array)
+        end
+
+        it "select with dayname(attr)" do
+          results = pl.Transaction.select(
+            pl.attr.id,
+            pl.attr.created_at(:dayname)
+          ).limit(5).all
+          expect(results).to be_an(Array)
+        end
+
+        it "group_by year(attr) with count" do
+          yearly = pl.Transaction.select(
+            pl.attr.created_at(:year),
+            pl.attr.id(:count)
+          ).group_by(pl.attr.created_at(:year)).limit(5).all
+          expect(yearly).to be_an(Array)
+        end
+      end
+
+      context "order_by" do
+        it "order_by ascending" do
+          results = pl.Transaction.select(pl.attr.id).order_by(pl.attr.created_at).limit(5).all
+          expect(results).to be_an(Array)
+        end
+
+        it "order_by descending" do
+          results = pl.Transaction.select(pl.attr.id).order_by(pl.attr.created_at(:desc)).limit(5).all
+          expect(results).to be_an(Array)
+        end
+      end
+
+      context "limit, offset, and range" do
+        it "limit" do
+          results = pl.Transaction.select(pl.attr.id).limit(2).all
+          expect(results).to be_an(Array)
+          expect(results.length).to be <= 2
+        end
+
+        it "offset" do
+          page1 = pl.Transaction.select(pl.attr.id).limit(3).offset(0).all
+          page2 = pl.Transaction.select(pl.attr.id).limit(3).offset(3).all
+          expect(page1).to be_an(Array)
+          expect(page2).to be_an(Array)
+          expect(page1.length).to be <= 3
+          expect(page2.length).to be <= 3
+        end
+
+        it "range operator []" do
+          results = pl.Transaction.select(pl.attr.id)[0..2]
+          expect(results).to be_an(Array)
+          expect(results.length).to be <= 3
+        end
+      end
+
+      context "nested attr" do
+        it "select with nested attr (sender.account_id)" do
+          results = pl.Transaction.select(
+            pl.attr.id,
+            pl.attr.sender.account_id
+          ).filter_by(pl.attr.type == "payment").limit(5).all
+          expect(results).to be_an(Array)
+        end
+      end
+
+      context "filter operators" do
+        it "filter with >" do
+          results = pl.Transaction.filter_by(
+            pl.attr.type == "payment",
+            pl.attr.amount > 0
+          ).select(pl.attr.id, pl.attr.amount).limit(5).all
+          expect(results).to be_an(Array)
+        end
+
+        it "filter with <" do
+          results = pl.Transaction.filter_by(
+            pl.attr.type == "payment",
+            pl.attr.amount < 1_000_000
+          ).select(pl.attr.id, pl.attr.amount).limit(5).all
+          expect(results).to be_an(Array)
+        end
+
+        it "filter with !=" do
+          results = pl.Transaction.filter_by(
+            pl.attr.type != "nonexistent_type"
+          ).select(pl.attr.id, pl.attr.type).limit(5).all
+          expect(results).to be_an(Array)
+        end
+
+        it "filter with contains" do
+          results = pl.Transaction.filter_by(
+            pl.attr.type == "payment",
+            pl.attr.description.contains("")
+          ).select(pl.attr.id, pl.attr.description).limit(5).all
+          expect(results).to be_an(Array)
+        end
+      end
+
+      context "filter OR (chained conditions)" do
+        it "filter with OR (|) on same attribute" do
+          or_filter = (pl.attr.amount > 0) | (pl.attr.amount < 1_000_000)
+          results = pl.Transaction.filter_by(
+            pl.attr.type == "payment",
+            or_filter
+          ).select(pl.attr.id, pl.attr.amount).limit(5).all
+          expect(results).to be_an(Array)
+        end
+      end
+
+      context "group_by and aggregates" do
+        it "group_by with sum and count" do
+          results = pl.Transaction.select(
+            pl.attr.type,
+            pl.attr.amount(:sum),
+            pl.attr.id(:count)
+          ).filter_by(pl.attr.type == "payment").group_by(pl.attr.type).limit(5).all
+          expect(results).to be_an(Array)
+        end
+
+        it "group_by month(attr) with sum and count" do
+          results = pl.Transaction.select(
+            pl.attr.created_at(:month),
+            pl.attr.amount(:sum),
+            pl.attr.id(:count)
+          ).filter_by(pl.attr.type == "payment").group_by(pl.attr.created_at(:month)).limit(5).all
+          expect(results).to be_an(Array)
+        end
+
+        it "group_by year(attr) with count" do
+          results = pl.Transaction.select(
+            pl.attr.created_at(:year),
+            pl.attr.id(:count)
+          ).filter_by(pl.attr.type == "payment").group_by(pl.attr.created_at(:year)).limit(5).all
+          expect(results).to be_an(Array)
+        end
+      end
+    end
+  end
+end

data/spec/payload/arm/request_spec.rb

@@ -11,7 +11,7 @@ RSpec.describe Payload::ARMRequest do
 
         context "when the user selects custom fields" do
             it "selects the requested fields" do
-                instance.select(' name', 'age  ')
+                instance.select('name', 'age')
                 expect(instance.instance_variable_get(:@filters)).to eq({ "fields" => "name,age" })
                 instance.select('count(id)', 'sum(amount)')
                 expect(instance.instance_variable_get(:@filters)).to eq({ "fields" => "count(id),sum(amount)" })

data/spec/payload/arm/session_spec.rb

@@ -24,6 +24,46 @@ RSpec.describe Payload::Session do
         end
     end
 
+    describe "#attr" do
+        it "returns an AttrRoot so pl.attr.name returns an Attr (not shadowed by Class#name)" do
+            instance = described_class.new("test_key", "https://api.hello.co")
+            root = instance.attr
+
+            expect(root).to be_a(Payload::AttrRoot)
+            expect(root.id).to be_a(Payload::Attr)
+            expect(root.id.to_s).to eq("id")
+
+            expect(root.created_at(:year)).to be_a(Payload::Attr)
+            expect(root.created_at(:year).to_s).to eq("year(created_at)")
+
+            expect(root.created_at.year.to_s).to eq("created_at[year]")
+        end
+    end
+
+    describe "query chaining with session" do
+        it "passes session through query -> select -> order_by -> limit chain" do
+            instance = described_class.new("session_key", "https://api.test.com", "v2")
+            req = instance.query(Payload::Invoice).select("id", "amount").order_by("created_at").limit(5)
+
+            expect(req).to be_a(Payload::ARMRequest)
+            expect(req.instance_variable_get(:@session)).to eq(instance)
+            expect(req.instance_variable_get(:@filters)["fields"]).to eq("id,amount")
+            expect(req.instance_variable_get(:@order_by)).to include("created_at")
+            expect(req.instance_variable_get(:@limit)).to eq(5)
+        end
+
+        it "filter_by with session.attr uses AttrRoot from same session" do
+            instance = described_class.new("test_key", "https://api.test.com", "v2")
+            filter_expr = instance.attr.status == "processed"
+            req = instance.query(Payload::Transaction).filter_by(filter_expr)
+
+            expect(req.instance_variable_get(:@session)).to eq(instance)
+            expect(req.instance_variable_get(:@filter_objects)).to include(be_a(Payload::ARMEqual))
+            params = req.request_params
+            expect(params["status"]).to eq("processed")
+        end
+    end
+
     describe "#query" do
 
         context "when the user queries an ARMObject with a session" do

data/spec/payload/exceptions_spec.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "payload"
+
+RSpec.describe Payload::TransactionDeclined do
+  def api_error_payload(message:, details: nil)
+    {
+      "object" => "error",
+      "error_type" => "TransactionDeclined",
+      "error_description" => message,
+      "details" => details,
+    }.compact
+  end
+
+  it "inherits from BadRequest (HTTP 400)" do
+    expect(described_class.superclass).to eq(Payload::BadRequest)
+    expect(Payload::BadRequest.code).to eq("400")
+  end
+
+  it "sets message from first argument (same as request.rb: data['error_description'])" do
+    e = described_class.new("Card declined", nil)
+    expect(e.message).to eq("Card declined")
+  end
+
+  it "exposes #transaction as nil when data is nil" do
+    e = described_class.new("Declined", nil)
+    expect(e.transaction).to be_nil
+  end
+
+  it "exposes #transaction as nil when details is missing" do
+    e = described_class.new("Declined", api_error_payload(message: "Declined"))
+    expect(e.transaction).to be_nil
+  end
+
+  it "exposes #transaction as nil when details is not a Hash" do
+    e = described_class.new("Declined", api_error_payload(message: "Declined", details: "string"))
+    expect(e.transaction).to be_nil
+  end
+
+  it "builds a transaction object from data['details'] when present (API-realistic payload)" do
+    details = {
+      "id" => "txn_123",
+      "object" => "transaction",
+      "type" => "payment",
+      "status" => "declined",
+      "status_code" => "do_not_honor",
+      "amount" => 100.0,
+    }
+    data = api_error_payload(message: "Transaction was declined", details: details)
+    e = described_class.new(data["error_description"], data)
+
+    expect(e.transaction).to be_a(Payload::ARMObject)
+    expect(e.transaction.id).to eq("txn_123")
+    expect(e.transaction["status"]).to eq("declined")
+    expect(e.transaction["status_code"]).to eq("do_not_honor")
+    expect(e.transaction["amount"]).to eq(100.0)
+    expect(e.transaction).to be_a(Payload::Payment)
+  end
+
+  it "uses Transaction when get_cls returns nil for details (minimal details, no object key)" do
+    details = { "id" => "txn_456", "status" => "declined" }
+    data = api_error_payload(message: "Declined", details: details)
+    e = described_class.new(data["error_description"], data)
+
+    expect(e.transaction).to be_a(Payload::Transaction)
+    expect(e.transaction.id).to eq("txn_456")
+  end
+
+  it "matches how ARM request raises: message from error_description, data = full response" do
+    data = {
+      "object" => "error",
+      "error_type" => "TransactionDeclined",
+      "error_description" => "There was an issue processing the payment",
+      "details" => { "id" => "txn_789", "object" => "transaction", "status" => "declined" },
+    }
+    e = described_class.new(data["error_description"], data)
+
+    expect(e.message).to eq("There was an issue processing the payment")
+    expect(e.transaction).to be_a(Payload::ARMObject)
+    expect(e.transaction.id).to eq("txn_789")
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: payload-api
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Payload
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-21 00:00:00.000000000 Z
+date: 2026-02-09 00:00:00.000000000 Z
 dependencies: []
 description: A simple library to interface with the Payload API. See https://docs.payload.com
   for details.
@@ -22,6 +22,7 @@ files:
 - LICENSE
 - README.md
 - lib/payload.rb
+- lib/payload/arm/attr.rb
 - lib/payload/arm/object.rb
 - lib/payload/arm/request.rb
 - lib/payload/arm/session.rb
@@ -43,8 +44,13 @@ files:
 - spec/objects/v2/invoice_spec.rb
 - spec/objects/v2/payment_method_spec.rb
 - spec/objects/v2/transaction_spec.rb
+- spec/payload/arm/arm_request_query_spec.rb
+- spec/payload/arm/attr_spec.rb
+- spec/payload/arm/object_spec.rb
+- spec/payload/arm/request_format_integration_spec.rb
 - spec/payload/arm/request_spec.rb
 - spec/payload/arm/session_spec.rb
+- spec/payload/exceptions_spec.rb
 - spec/support/helpers.rb
 - spec/support/helpers/v1_helpers.rb
 - spec/support/helpers/v2_helpers.rb