payload-api 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a72aa2a2c6c68a340271b1d4253fb5cc6aac1d929cc93ef31cda38905dd44873
-  data.tar.gz: 7be911861bb6e88d4101f3e0c04300130febc948259949f99a4c683c09872697
+  metadata.gz: 74c2fd7f99fba4cf6b0f1950d013debc81c56629a5b280e7ac79e4e4abd88838
+  data.tar.gz: abf8b305b33a0e9a5241f5664807842989b7d423781f35606607298c9297d35a
 SHA512:
-  metadata.gz: 9b4bad0cda115b4fb98f748113dcf274848d33f3db46564b192cb348e752f7aba7ecdb3be115beb8956a5a962a46a76c963fe8ed87cebbdaefd9b099bbeae0ad
-  data.tar.gz: 0d5dddcf16f20e56d2fcdad6ae05449f2de331d5e9fb1191565845cae002535c2d380941b5b5418956b3de0feaa4c5de6c25492ae2d0a9322f67af9dc3b25571
+  metadata.gz: 0e34c4a1a585078565d876af179d8e9b3344888ca44a08f9465ac2e740f5f112990d8b7564b7c0394e21dc4eae22c9b5e0e804850c23cb39d5ffd789ad055319
+  data.tar.gz: ad8721f83c061113c6abcf4e26f7077e9c07b7a4d34b60d8cdaa9d4f61ad599443cc1e8511d46983d7acd368601b6596b42cd6cef9509dd3cc4a0a89c9492202

data/.github/workflows/test.yml

@@ -20,6 +20,8 @@ jobs:
         ruby-version: 3.0.1
 
     - name: Run RSpec tests
+      env:
+        TEST_SECRET_KEY: ${{ secrets.API_KEY }}
       run: |
         gem install rspec
         rspec spec

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/README.md

@@ -7,13 +7,13 @@ A RubyGem for integrating [Payload](https://payload.com).
 To install using [Bundler](https://bundler.io):
 
 ```ruby
-gem 'payload-api', '~> 0.2.4'
+gem 'payload-api', '~> 0.5.0'
 ```
 
 To install using gem:
 
 ```bash
-gem install payload
+gem install payload-api
 ```
 
 ## Get Started
@@ -34,6 +34,27 @@ require 'payload'
 Payload.api_key = 'secret_key_3bW9JMZtPVDOfFNzwRdfE'
 ```
 
+### API Versioning
+
+The Payload API supports multiple versions. You can specify which version to use when making requests:
+
+```ruby
+require 'payload'
+Payload.api_key = 'secret_key_3bW9JMZtPVDOfFNzwRdfE'
+Payload.api_version = 'v2'  # Use API v2
+```
+
+Or with sessions:
+
+```ruby
+pl = Payload::Session.new(
+    'secret_key_3bW9JMZtPVDOfFNzwRdfE', 
+    api_version: 'v2'
+)
+```
+
+API v2 introduces new objects including `Profile`, `Intent`, `Entity`, `Transfer`, `ProcessingAgreement`, and more. See the [Payload API Documentation](https://docs.payload.com) for details on API versions.
+
 ### Creating an Object
 
 Interfacing with the Payload API is done primarily through Payload Objects. Below is an example of

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

@@ -30,6 +30,25 @@ module Payload
 			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
@@ -99,7 +118,7 @@ module Payload
 		end
 
 		def [](key)
-			return @data[key]
+			return @data[key.to_s]
 		end
 
 		def _get_request()
@@ -114,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)
@@ -150,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
@@ -158,5 +197,9 @@ module Payload
 			serialized.merge!(@data)
 			return serialized.to_json(*args)
 		end
+
+		def respond_to_missing?(name, include_private = false)
+			@data && @data.key?(name.to_s) || super
+		end
 	end
 end

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,28 +13,65 @@ 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
 
 		def all()
+			# TODO: I don't think this applies the @poly variable as intended?
 			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'
@@ -126,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")
@@ -145,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)
 
@@ -162,6 +211,10 @@ module Payload
 				request.add_field('Content-Type', 'application/json')
 			end
 
+			if @session.api_version
+				request.add_field('X-API-Version', @session.api_version)
+			end
+
 			response = self._execute_request(http, request)
 
 			begin
@@ -178,6 +231,7 @@ module Payload
 				if data['object'] == 'list'
 					return data['values'].map do |obj|
 						cls = Payload::get_cls(obj)
+						cls = @cls if cls.nil? && !@cls.nil?
 						if cls.nil?
 							obj
 						else
@@ -186,7 +240,13 @@ module Payload
 						end
 					end
 				else
-					return Payload::get_cls(data).new(data, @session)
+					cls = Payload::get_cls(data)
+					cls = @cls if cls.nil? && !@cls.nil?
+					if cls.nil?
+						return data
+					else
+						return cls.new(data, @session)
+					end
 				end
 			else
 				for error in Payload::subclasses(Payload::PayloadError)

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
-
-        def initialize(api_key, api_url=nil)
-            @api_key = api_key
-            @api_url = api_url || Payload.URL
-
+        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

@@ -18,18 +18,6 @@ module Payload
 		@spec = { 'object' => 'account' }
 	end
 
-	class Customer < ARMObject
-		@spec = { 'object' => 'customer' }
-	end
-
-	class ProcessingAccount < ARMObject
-		@spec = { 'object' => 'processing_account' }
-	end
-
-	class Org < ARMObject
-		@spec = { 'object' => 'org', 'endpoint' => '/account/orgs' }
-	end
-
 	class Transaction < ARMObject
 		@spec = { 'object' => 'transaction' }
 	end
@@ -74,6 +62,27 @@ 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
+
+	class PaymentLink < ARMObject
+		@spec = { 'object' => 'payment_link' }
+	end
+
+	# V1 objects
 	class LineItem < ARMObject
 		@spec = { 'object' => 'line_item' }
 	end
@@ -88,15 +97,69 @@ module Payload
 		@poly = { 'entry_type' => 'payment' }
 	end
 
-	class PaymentActivation < ARMObject
-		@spec = { 'object' => 'payment_activation' }
+	class Customer < ARMObject
+		@spec = { 'object' => 'customer' }
 	end
 
-	class Webhook < ARMObject
-		@spec = { 'object' => 'webhook' }
+	class ProcessingAccount < ARMObject
+		@spec = { 'object' => 'processing_account' }
 	end
 
-	class PaymentLink < ARMObject
-		@spec = { 'object' => 'payment_link' }
+	class Org < ARMObject
+		@spec = { 'object' => 'org', 'endpoint' => '/account/orgs' }
+	end
+
+	# V2 objects
+	class InvoiceItem < ARMObject
+		@spec = { 'object' => 'invoice_item' }
 	end
+
+	class PaymentAllocation < ARMObject
+		@spec = { 'object' => 'payment_allocation' }
+	end
+
+	class Profile < ARMObject
+		@spec = { 'object' => 'profile' }
+	end
+
+	class BillingItem < ARMObject
+		@spec = { 'object' => 'billing_item' }
+	end
+
+	class Intent < ARMObject
+		@spec = { 'object' => 'intent' }
+	end
+
+	class Entity < ARMObject
+		@spec = { 'object' => 'entity', 'endpoint' => 'entities' }
+	end
+
+	class Stakeholder < ARMObject
+		@spec = { 'object' => 'stakeholder' }
+	end
+
+	class ProcessingAgreement < ARMObject
+		@spec = { 'object' => 'processing_agreement' }
+	end
+
+	class Transfer < ARMObject
+		@spec = { 'object' => 'transfer' }
+	end
+
+	class TransactionOperation < ARMObject
+		@spec = { 'object' => 'transaction_operation' }
+	end
+
+	class CheckFront < ARMObject
+		@spec = { 'object' => 'check_front' }
+	end
+
+	class CheckBack < ARMObject
+		@spec = { 'object' => 'check_back' }
+	end
+
+	class ProcessingRule < ARMObject
+		@spec = { 'object' => 'processing_rule' }
+	end
+
 end

data/lib/payload/version.rb

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

data/lib/payload.rb

@@ -3,8 +3,8 @@ require "payload/objects"
 require "payload/arm/session"
 
 module Payload
-	@URL = "https://api.payload.com"
-
+  @URL = "https://api.payload.com"
+	
 	class << self
 		def api_key=(value)
 			session.api_key = value
@@ -22,15 +22,24 @@ module Payload
 			session.api_url
 		end
 
+    def api_version=(version)
+      @api_version = version
+      @session = nil
+    end
+    
+    def api_version
+      @api_version
+    end
+    
 		def URL
 			@URL
 		end
 
 		private
 
-		def session
-			@session ||= Payload::Session.new(nil, @URL)
-		end
+    def session
+      @session ||= Payload::Session.new(nil, @URL)
+    end
 	end
 
 	def self.create(objects)
@@ -44,4 +53,5 @@ module Payload
 	def self.delete(objects)
 		return Payload::ARMRequest.new().delete_all(objects)
 	end
+
 end