faithteams-api 2.0.1

data/lib/faithteams/api/v2/entity/contribution.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module FaithTeams
+  module API
+    module V2
+      module Entity
+        # Wraps a faithteams contribution object.
+        class Contribution < Base
+          # @return [Array<ContributionRecord>] the contribution records
+          def records
+            attributes.map do |record|
+              FaithTeams::API::V2::Entity::ContributionRecord.new(attributes: record)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/faithteams/api/v2/entity/contribution_record.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module FaithTeams
+  module API
+    module V2
+      module Entity
+        # Wraps a faithteams contribution_record object.
+        class ContributionRecord < Base
+          # @return [Float, nil]
+          def amount
+            read_attribute(:amount)
+          end
+
+          # @return [Integer, nil]
+          def batch_id
+            read_attribute(:batchId)
+          end
+
+          # @return [String, nil]
+          def check_number
+            read_attribute(:checkNumber).presence
+          end
+
+          # @return [Integer, nil]
+          def contribution_id
+            read_attribute(:contributionId)
+          end
+
+          # @return [Integer, nil]
+          def contribution_type_id
+            read_attribute(:contributionTypeId)
+          end
+
+          # @return [String, nil]
+          def contribution_type_name
+            read_attribute(:contributionTypeName).presence
+          end
+
+          # @return [String, nil]
+          def created_datetime
+            read_attribute(:createdDtm).presence
+          end
+
+          # @return [Integer, nil]
+          def created_user_id
+            read_attribute(:createdUser)
+          end
+
+          # @return [Float, nil]
+          def fee
+            read_attribute(:fee)
+          end
+
+          # @return [Integer, nil]
+          def fund_id
+            read_attribute(:fundId)
+          end
+
+          # @return [String, nil]
+          def fund_name
+            read_attribute(:fundName).presence
+          end
+
+          # @return [String, nil]
+          def give_datetime
+            read_attribute(:giveDtm).presence
+          end
+
+          # @return [Float, nil]
+          def net_amount
+            read_attribute(:netAmount)
+          end
+
+          # @return [String, nil]
+          def note
+            read_attribute(:note).presence
+          end
+
+          # @return [Integer, nil]
+          def org_id
+            read_attribute(:orgId)
+          end
+
+          # @return [Integer, nil]
+          def parent_id
+            read_attribute(:parentId)
+          end
+
+          # @return [Integer, nil]
+          def person_id
+            read_attribute(:personId)
+          end
+
+          # @return [Integer, nil]
+          def person_id_2
+            read_attribute(:personId2)
+          end
+
+          # @return [String, nil] "H" for header, "D" for detail
+          def record_type
+            read_attribute(:recordType).presence
+          end
+
+          # @return [String, nil] "A" for active?
+          def status
+            read_attribute(:status).presence
+          end
+
+          # @return [Float, nil]
+          def total_amount
+            read_attribute(:totalAmount)
+          end
+
+          # @return [String, nil]
+          def updated_datetime
+            read_attribute(:updatedDtm).presence
+          end
+
+          # @return [Integer, nil]
+          def updated_user_id
+            read_attribute(:updatedUser)
+          end
+
+          # @return [Boolean]
+          def header?
+            record_type&.upcase == "H"
+          end
+
+          # @return [Boolean]
+          def detail?
+            record_type&.upcase == "D"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/faithteams/api/v2/entity/contribution_type.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module FaithTeams
+  module API
+    module V2
+      module Entity
+        # Wraps a faithteams contribution type object.
+        class ContributionType < Base
+          # @return [Integer, nil]
+          def id
+            read_attribute(:contributionTypeId)
+          end
+
+          # @return [String, nil]
+          def name
+            read_attribute(:name).presence
+          end
+
+          # @return [String, nil] "A" for active, "I" for inactive
+          def status
+            read_attribute(:status).presence
+          end
+
+          # @return [Boolean]
+          def tithely?
+            (name || "").strip.downcase == "tithely"
+          end
+
+          # @return [Boolean]
+          def active?
+            (status || "I").strip.upcase == "A"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/faithteams/api/v2/entity/fund.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module FaithTeams
+  module API
+    module V2
+      module Entity
+        # Wraps a faithteams fund object.
+        class Fund < Base
+          # @return [String, nil] "N" for no, "Y" for yes
+          def default
+            read_attribute(:isDefault).presence
+          end
+
+          # @return [String, nil]
+          def description
+            read_attribute(:description).presence
+          end
+
+          # @return [Integer, nil]
+          def fund_id
+            read_attribute(:fundId)
+          end
+
+          # @return [String, nil]
+          def name
+            read_attribute(:name).presence
+          end
+
+          # @return [String, nil] "A" for active, "I" for inactive
+          def online_status
+            read_attribute(:onlineStatus).presence
+          end
+
+          # @return [Integer, nil]
+          def org_id
+            read_attribute(:orgId)
+          end
+
+          # @return [String, nil] "A" for active, "I" for inactive
+          def status
+            read_attribute(:status).presence
+          end
+
+          # @return [String, nil] "T" for true?, "Y" for yes?
+          def tax_deductible
+            read_attribute(:taxDeductible).presence
+          end
+        end
+      end
+    end
+  end
+end

data/lib/faithteams/api/v2/entity/person.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module FaithTeams
+  module API
+    module V2
+      module Entity
+        # Wraps an faithteams person object
+        class Person < Base
+          # @return [String, nil]
+          def email
+            read_attribute(:homeEmail).presence
+          end
+
+          # @return [String, nil]
+          def first_name
+            read_attribute(:firstName).presence
+          end
+
+          # @return [String, nil]
+          def home_address_city
+            read_attribute(:homeAddressCity).presence
+          end
+
+          # @return [String, nil]
+          def home_address_country
+            read_attribute(:homeAddressCountry).presence
+          end
+
+          # @return [String, nil]
+          def home_address_state
+            read_attribute(:homeAddressState).presence
+          end
+
+          # @return [String, nil]
+          def home_address_street_line1
+            read_attribute(:homeAddressStreetLine1).presence
+          end
+
+          # @return [String, nil]
+          def home_address_street_line2
+            read_attribute(:homeAddressStreetLine2).presence
+          end
+
+          # @return [String, nil]
+          def home_address_zip
+            read_attribute(:homeAddressZip).presence
+          end
+
+          # @return [String, nil]
+          def home_phone_number
+            read_attribute(:homePhoneNumber).presence
+          end
+
+          # @return [Integer, nil]
+          def id
+            read_attribute(:personId)
+          end
+
+          # @return [String, nil]
+          def last_name
+            read_attribute(:lastName).presence
+          end
+
+          # @return [Integer, nil]
+          def org_id
+            read_attribute(:orgId)
+          end
+
+          # @return [String, nil] "A" for active, "I" for inactive
+          def status
+            read_attribute(:status).presence
+          end
+        end
+      end
+    end
+  end
+end

data/lib/faithteams/api/v2/entity.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "entity/base"
+require_relative "entity/batch"
+require_relative "entity/contribution"
+require_relative "entity/contribution_record"
+require_relative "entity/contribution_type"
+require_relative "entity/fund"
+require_relative "entity/person"
+
+module FaithTeams
+  module API
+    module V2
+      module Entity; end
+    end
+  end
+end

data/lib/faithteams/api/v2/error/no_search_parameter_provided.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module FaithTeams
+  module API
+    module V2
+      module Error
+        # Thrown when a parameter is not given but should have been
+        class NoSearchParameterProvided < StandardError; end
+      end
+    end
+  end
+end

data/lib/faithteams/api/v2/error/request.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module FaithTeams
+  module API
+    module V2
+      module Error
+        # A request failed to complete successfully.
+        class Request < StandardError
+          attr_reader :response
+
+          # Custom faithteams error about invalid API key
+          UNAUTHORIZED_ERROR_MESSAGE = "Unauthorized"
+
+          # Custom faithteams error when a resource is not found
+          NOT_FOUND_ERROR_MESSAGE = "Not Found"
+
+          # @param response [HTTP::Response]
+          # @param message [String]
+          def initialize(response:, message: "Request failed", skip_failure_message: false)
+            @response = response
+            message += ": #{failure_message}" unless failure_message.blank? || skip_failure_message
+            super(message)
+          end
+
+          # @return [String]
+          def failure_message
+            @failure_message ||= response.parse(:json).dig("message") rescue ""
+          rescue JSON::ParserError => e
+            e.capture
+            response.to_s
+          end
+
+          # @return [Boolean]
+          def unauthorized?
+            failure_message == UNAUTHORIZED_ERROR_MESSAGE
+          end
+
+          # @return [Boolean]
+          def not_found?
+            failure_message == NOT_FOUND_ERROR_MESSAGE
+          end
+        end
+      end
+    end
+  end
+end

data/lib/faithteams/api/v2/error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "error/no_search_parameter_provided"
+require_relative "error/request"
+
+module FaithTeams
+  module API
+    module V2
+      # FaithTeams API error
+      module Error; end
+    end
+  end
+end

data/lib/faithteams/api/v2/gateway.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "gateway_base"
+
+module FaithTeams
+  module API
+    module V2
+      # Central gateway for all API resources
+      class Gateway < GatewayBase
+        # @param connection [FaithTeams::API::V2::Connection]
+        def initialize(connection:)
+          @connection = connection
+        end
+
+        # @return [Resource::Batch]
+        def batch
+          @batch ||= Resource::Batch.new(connection: connection)
+        end
+
+        # @return [Resource::Fund]
+        def fund
+          @fund ||= Resource::Fund.new(connection: connection)
+        end
+
+        # @return [Resource::Person]
+        def person
+          @person ||= Resource::Person.new(connection: connection)
+        end
+
+        # @return [Resource::Contribution]
+        def contribution
+          @contribution ||= Resource::Contribution.new(connection: connection)
+        end
+
+        # @return [Resource::User]
+        def user
+          @user ||= Resource::User.new(connection: connection)
+        end
+
+        # @return [Resource::ContributionType]
+        def contribution_type
+          @contribution_type ||= Resource::ContributionType.new(connection: connection)
+        end
+
+        def valid_connection?
+          connection.valid?
+        end
+      end
+    end
+  end
+end

data/lib/faithteams/api/v2/gateway_base.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module FaithTeams
+  module API
+    module V2
+      # A base class for all FaithTeam API versions
+      class GatewayBase
+        # @param connection [Integrations::API::Connection]
+        def initialize(connection:)
+          @connection = connection
+        end
+
+        # Required by integrations-gem
+        # @return [Boolean]
+        def valid_connection?
+          connection.valid?
+        end
+
+        protected
+
+        attr_reader :connection
+      end
+    end
+  end
+end

data/lib/faithteams/api/v2/resource/base.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/keys"
+require "active_support/core_ext/object/blank"
+
+module FaithTeams
+  module API
+    module V2
+      module Resource
+        # Common Resource functionality
+        # Additional methods can be added but the following methods should not be missing
+        class Base < GatewayBase
+          # @param id [Integer] The contribution payment_id.
+          # @return [Entity::Base, nil]
+          def find(id:)
+            raise NotImplementedError
+          end
+
+          # @param args [Hash] Key values to search with
+          # @return [Array<Entity::Base>]
+          def search(**args)
+            raise NotImplementedError
+          end
+
+          # @param entity [Entity::Base]
+          # @return [Entity::Base, false]
+          def create(entity:)
+            raise NotImplementedError
+          end
+
+          # @param entity [Entity::Base]
+          # @return [Entity::Base, false]
+          def update(entity:)
+            raise NotImplementedError
+          end
+
+          # @param id [#to_s] ID of the entity to delete
+          # @return [Boolean]
+          def delete(id:)
+            raise NotImplementedError
+          end
+        end
+      end
+    end
+  end
+end

data/lib/faithteams/api/v2/resource/batch.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module FaithTeams
+  module API
+    module V2
+      module Resource
+        # Batch resource
+        class Batch < Base
+          # @param args [Hash] Keyword args
+          # @return [Array<Entity::Batch>]
+          def search(**args)
+            found = connection.get(path: "/batches", params: args)["data"]
+            return [] unless found.present?
+
+            found.map { |b| Entity::Batch.new(attributes: b) }
+          end
+
+          # @param id [Integer]
+          # @return [Entity::Batch, nil] containing all batch details
+          # @raise [Error::Request]
+          def find(id:)
+            raise FaithTeams::API::V2::Error::NoSearchParameterProvided if id.nil?
+
+            data = connection.get(path: "/batches/#{id}")["data"]
+            return nil unless data
+
+            Entity::Batch.new(attributes: data)
+          rescue Error::Request => e
+            return nil if e.response.code == 404
+            raise
+          end
+
+          # Searches for a  batch by `dtm` and `title`
+          # @note The batches endpoint does not actually filter by title so we do the filtering here.
+          # @param batch [Entity::Batch]
+          # @return [Entity::Batch, nil]
+          def find_by_batch(batch:)
+            found = search(sort: "dtm", sortDirection: "desc", dtm: batch.created_datetime)
+            found.find { |b| !b.deleted? && b.title == batch.title }
+          end
+
+          # The response sends back the created batch in the `data` object.
+          # @param entity [Entity::Batch]
+          # @return [Entity::Batch]
+          # @raise [Error::Request]
+          def create(entity:)
+            data = connection.post(path: "/batches", body: entity.to_h)["data"]
+
+            Entity::Batch.new(attributes: data)
+          rescue Error::Request => e
+            raise Error::Request.new(response: e.response, message: "Request Unsuccessful: The batch #{entity.inspect} could not be created. FaithTeams API failure message: #{e.message}}") if e.response.status.success?
+            raise
+          end
+        end
+      end
+    end
+  end
+end

data/lib/faithteams/api/v2/resource/contribution.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module FaithTeams
+  module API
+    module V2
+      module Resource
+        # A transaction in faithteams
+        class Contribution < Base
+          # @param entity [Entity::Contribution]
+          # @return [Entity::Contribution]
+          # @raise [Error::Request]
+          def create(entity:)
+            data = connection.post(path: "/contributions", body: entity.to_h)["data"]
+
+            Entity::Contribution.new(attributes: data)
+          rescue Error::Request => e
+            raise Error::Request.new(response: e.response, message: "Request Unsuccessful: The contribution #{entity.inspect} could not be created. FaithTeams API failure message: #{e.message}}") if e.response.status.success?
+            raise
+          end
+
+          # @param id [Integer] The contributions `parent_id`
+          # @return [Entity::Contribution, nil]
+          # @raise [Error::Request]
+          def find(id:)
+            raise FaithTeams::API::V2::Error::NoSearchParameterProvided if id.nil?
+
+            data = connection.get(path: "/contributions/#{id}")["data"]
+            return nil unless data.present?
+
+            Entity::Contribution.new(attributes: data)
+          rescue Error::Request => e
+            raise Error::Request.new(response: e.response, message: "Request Unsuccessful: The contribution with parent_id #{id} could not be found. FaithTeams API failure message: #{e.message}}") if e.response.status.success?
+            raise
+          end
+        end
+      end
+    end
+  end
+end

data/lib/faithteams/api/v2/resource/contribution_type.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module FaithTeams
+  module API
+    module V2
+      module Resource
+        # The contribution type resource
+        class ContributionType < Base
+          # @param args [Hash] These are ignored as no filters are available for this endpoint
+          # @return [Entity::ContributionType]
+          def search(**args)
+            data = connection.get(path: "/contributiontypes", params: {}).fetch("data")
+
+            return nil unless data.present?
+
+            data.map do |record|
+              Entity::ContributionType.new(attributes: record)
+            end
+          end
+
+          # @param id [Integer]
+          # @return [Entity::ContributionType]
+          def find(id:)
+            return nil if id.blank?
+
+            data = connection.get(path: "/contributiontypes/#{id}", params: {}).fetch("data")
+
+            return nil unless data.present?
+
+            Entity::ContributionType.new(attributes: data)
+          rescue Error::Request => e
+            e.response.code == 404 ? nil : raise
+          end
+        end
+      end
+    end
+  end
+end