your_membership 1.0.0

data/lib/your_membership/profile.rb

@@ -0,0 +1,85 @@
+module YourMembership
+  # The Profile object provides a convenient abstraction that encapsulates a person's profile allowing clear and concise
+  # access to both the core fields provided by YourMembership and the custom fields added by site administrators
+  #
+  # A new profile for a new person should be instantiated through the create_new method
+  #
+  # A profile can be loaded by passing a hash directly to the initializer (Profile.new) method this can be useful in
+  # creating a profile object from an API response
+  #
+  # A profile can be created empty or by passing a hash for standard and/or custom fields. This is useful for
+  # updating an existing profile without changing unnecessary records.
+  #
+  # @attr_reader [Hash] data These are fields that are part of the core YourMembership profile implementation
+  # @attr_reader [Hash] custom_data These are fields that are the ones added as Custom Fields to a YourMembership
+  #  Community
+  class Profile
+    attr_accessor :data, :custom_data
+
+    # @param [Hash] options Initial Values for the profile.
+    def initialize(options = {})
+      @data = {}
+      @custom_data = {}
+
+      options.each do |k, v|
+        if k == 'CustomFieldResponses'
+          @custom_data = parse_custom_field_responses(v)
+        else
+          @data[k] = v
+        end
+      end
+    end
+
+    # Returns the full contents of the profile in a Hash without items that have a Nil value
+    # @return [Hash]
+    def to_h
+      temp_data = clean @data
+      temp_custom_data = clean @custom_data
+      temp_data['CustomFieldResponses'] = temp_custom_data
+      temp_data
+    end
+
+    # @param [String] last_name
+    # @param [String] member_type_code
+    # @param [String] email
+    # @param [String] username
+    # @param [String] password
+    # @param [Hash] options
+    # @return [YourMembership::Profile] Builds a new profile with required and optional fields
+    # @note: It has been found that for some users you must also specify a 'Membership' field as well as the
+    #  'MemberTypeCode' The official documentation does not say this field is required but many times the user
+    #  cannot log in if no membership is provided. This means that the system cannot masquerade as this user until a
+    #  membership is specified.
+    def self.create_new(first_name, last_name, member_type_code, email, username, password, options = {})
+      options['FirstName'] = first_name
+      options['LastName'] = last_name
+      options['MemberTypeCode'] = member_type_code
+      options['EmailAddr'] = email
+      options['Username'] = username
+      options['Password'] = password
+      new(options)
+    end
+
+    private
+
+    # @param [Hash] custom_fields The 'CustomFieldResponses' Hash
+    # @return [Hash] Single dimension hash containing keys and values as strings or arrays
+    def parse_custom_field_responses(custom_fields)
+      output_hash = {}
+      custom_fields['CustomFieldResponse'].each do |field|
+        output_hash[field['FieldCode']] = field['Values']['Value'] if field['Values']
+      end
+      output_hash
+    end
+
+    # Removes nil values
+    def clean(data_hash)
+      clean_hash = {}
+      # Remove Nils
+      data_hash.each do |k, v|
+        clean_hash[k] = v if v
+      end
+      clean_hash
+    end
+  end
+end

data/lib/your_membership/sa.rb

@@ -0,0 +1,6 @@
+module YourMembership
+  # The SA Namespace encapsulates System Administrator functions of the API. These functions are a special case that
+  # do not usually require a session or user scope.
+  module Sa
+  end
+end

data/lib/your_membership/sa_auth.rb

@@ -0,0 +1,34 @@
+module YourMembership
+  module Sa
+    # YourMembership System Administrator Member Authentication
+    class Auth < YourMembership::Base
+      # Authenticates a member's username and password and binds them to the current API session.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Auth_Authenticate.htm
+      #
+      # @param [YourMembership::Session] session
+      # @param [String] user_name The Username of the user the session should be bound to.
+      # @param [String] password The Password (Optional) pf the specified user.
+      # @param [String] password_hash The Password Hash for the specified user which allows the system to perform
+      #  actions on behalf of a user as if they were signed in without knowing the user's cleartext password.
+      # @return [YourMembership::Member] Returns a Member object for the authenticated session.
+      def self.authenticate(session, user_name, password = nil, password_hash = nil)
+        options = {}
+        options[:Username] = user_name
+        options[:Password] = password if password
+        options[:PasswordHash] = password_hash if password_hash
+
+        response = post('/', :body => build_XML_request('Sa.Auth.Authenticate', session, options))
+
+        response_valid? response
+        if response['YourMembership_Response']['Sa.Auth.Authenticate']
+          session.get_authenticated_user
+        else
+          return false
+        end
+
+        YourMembership::Member.create_from_session(session)
+      end
+    end
+  end
+end

data/lib/your_membership/sa_certifications.rb

@@ -0,0 +1,22 @@
+module YourMembership
+  module Sa
+    # YourMembership System Administrator Certifications Namespace
+    class Certifications < YourMembership::Base
+      # Return a list of all certification records for the community.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Certifications_All_Get.htm
+      #
+      # @param [Boolean] is_active Include active certification records in the returned result. Default: True
+      # @return [Array] Returns an Array of Hashes representing Certification Records
+      def self.all_get(is_active = true)
+        options = {}
+        options[:IsActive] = is_active
+
+        response = post('/', :body => build_XML_request('Sa.Certifications.All.Get', nil, options))
+
+        response_valid? response
+        response_to_array_of_hashes response['YourMembership_Response']['Sa.Certifications.All.Get'], ['Certification']
+      end
+    end
+  end
+end

data/lib/your_membership/sa_commerce.rb

@@ -0,0 +1,22 @@
+module YourMembership
+  module Sa
+    # YourMembership System Administrator Commerce Namespace
+    class Commerce < YourMembership::Base
+      # Returns the order details, including line items and products ordered, of a store order.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Commerce_Store_Order_Get.htm
+      #
+      # @param [String] invoice_id The Invoice ID of the store order to be returned.
+      # @return [Hash] Returns a Hash representing a store order
+      def self.store_order_get(invoice_id)
+        options = {}
+        options[:InvoiceID] = invoice_id
+
+        response = post('/', :body => build_XML_request('Sa.Commerce.Store.Order.Get', nil, options))
+
+        response_valid? response
+        response['YourMembership_Response']['Sa.Commerce.Store.Order.Get']
+      end
+    end
+  end
+end

data/lib/your_membership/sa_events.rb

@@ -0,0 +1,66 @@
+module YourMembership
+  module Sa
+    # YourMembership System Administrator Events Namespace
+    class Events < YourMembership::Base
+      # Returns a list of Events for the community optionally filtered by date or event name.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Events_All_GetIDs.htm
+      #
+      # @param [Hash] options
+      # @option options [DateTime] :StartDate Starting date to filter the Event Start Date.
+      # @option options [DateTime] :EndDate Ending date to filter the Event Start Date.
+      # @option options [String] :Name Filter the returned events by Event Name.
+      # @return [Array] Returns an Array of Event IDs
+      def self.all_getIDs(options = {}) # rubocop:disable Style/MethodName
+        response = post('/', :body => build_XML_request('Sa.Events.All.GetIDs', nil, options))
+
+        response_valid? response
+        if response['YourMembership_Response']['Sa.Events.All.GetIDs']
+          response['YourMembership_Response']['Sa.Events.All.GetIDs']['EventID']
+        else
+          return[]
+        end
+      end
+
+      # Returns Event Registration details for the provided Event and Event Registration ID. If the Event Registration
+      # contains a related Custom Form, the form data will be included in the <DataSet> element as it is stored in our
+      # database.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Events_Event_Registration_Get.htm
+      #
+      # @param [Integer] event_id The ID number for the Event from which you wish to retrieve the Event Registration.
+      # @param [Hash] options Either RegistrationID or Badge Number are required.
+      # @option options [String] :RegistrationID RegistrationID of the Registration data to return.
+      # @option options [Integer] :BadgeNumber The Badge Number / Registration Number for an Event Registration record.
+      # @return [Hash] Returns a Hash representing an event registration
+      def self.event_registration_get(event_id, options = {})
+        options[:EventID] = event_id
+
+        response = post('/', :body => build_XML_request('Sa.Events.Event.Registration.Get', nil, options))
+
+        response_valid? response
+        response['YourMembership_Response']['Sa.Events.Event.Registration.Get']
+      end
+
+      # Returns a list of Registration IDs for the specified Event ID.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Events_Event_Registrations_GetIDs.htm
+      #
+      # @param [Integer] event_id The ID number for the Event from which you wish to retrieve the Event Registration.
+      # @return [Array] Returns an Array of registration IDs for a specific event.
+      def self.event_registrations_getIDs(event_id) # rubocop:disable Style/MethodName
+        options = {}
+        options[:EventID] = event_id
+
+        response = post('/', :body => build_XML_request('Sa.Events.Event.Registrations.GetIDs', nil, options))
+
+        response_valid? response
+        if response['YourMembership_Response']['Sa.Events.Event.Registrations.GetIDs']
+          response['YourMembership_Response']['Sa.Events.Event.Registrations.GetIDs']['RegistrationID']
+        else
+          return []
+        end
+      end
+    end
+  end
+end

data/lib/your_membership/sa_export.rb

@@ -0,0 +1,195 @@
+module YourMembership
+  module Sa
+    # The Export object provides a convenient abstraction that encapsulates the export process
+    #
+    # @attr_reader [String] export_id The unique ID assigned by the API when an export is initiated
+    # @attr_reader [Symbol] status The status of the current export request
+    # @attr_reader [String] export_uri The uri from which to download the requested report once the status is :complete
+    class Export < YourMembership::Base
+      attr_reader :export_id, :status, :export_uri
+
+      # Export Initializer - Use any of the public class methods to create objects of this type.
+      #
+      # @note There is not yet a compelling reason to call Export.new() directly, however it can be done.
+      #
+      # @param [String] export_id The ID of the export job for which to create the object.
+      def initialize(export_id)
+        @export_id = export_id
+        @status = nil
+        @export_uri = nil
+      end
+
+      # Instance implementation of the Sa::Export.status method that also sets the export_uri if the status is :complete
+      # @return [Symbol] Returns the symbol for the current status state.
+      def status
+        unless @status == :complete || @status == :error || @status == :failure
+          status_response = self.class.status(@export_id)
+          @status = convert_status(status_response['Status'])
+          update_export_uri(status_response) if @status == :complete
+        end
+        @status
+      end
+
+      # Returns the status of an export by ExportID. This method should be called until a status of either
+      # FAILURE or COMPLETE is returned.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Status.htm
+      #
+      # @param [String] export_id ID of the Export on which to check status.
+      # @return [Hash] Returns a hash with the status code for the current export as well as the URI of the exported
+      #  data if available
+      def self.status(export_id)
+        options = {}
+        options[:ExportID] = export_id
+
+        response = post('/', :body => build_XML_request('Sa.Export.Status', nil, options))
+
+        response_valid? response
+        response['YourMembership_Response']['Sa.Export.Status']
+      end
+
+      # Starts an export of all invoice items.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Export_All_InvoiceItems.htm
+      #
+      # @param [DateTime] date Date to export records from.
+      # @param [Boolean] unicode Export format.
+      # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
+      def self.all_invoiceItems(date, unicode) # rubocop:disable Style/MethodName
+        generic_export('Sa.Export.All.InvoiceItems', date, unicode)
+      end
+
+      # Starts an export of career openings.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Career_Openings.htm
+      #
+      # @param [DateTime] date Date to export records from.
+      # @param [Boolean] unicode Export format.
+      # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
+      def self.career_openings(date, unicode)
+        generic_export('Sa.Export.Career.Openings', date, unicode)
+      end
+
+      # Starts an export of donation transactions.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Donations_Transactions.htm
+      #
+      # @param [DateTime] date Date to export records from.
+      # @param [Boolean] unicode Export format.
+      # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
+      def self.donations_transactions(date, unicode)
+        generic_export('Sa.Export.Donations.Transactions', date, unicode)
+      end
+
+      # Starts an export of donation invoice items.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Donations_InvoiceItems.htm
+      #
+      # @param [DateTime] date Date to export records from.
+      # @param [Boolean] unicode Export format.
+      # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
+      def self.donations_invoiceItems(date, unicode) # rubocop:disable Style/MethodName
+        generic_export('Sa.Export.Donations.InvoiceItems', date, unicode)
+      end
+
+      # Starts an export of dues transactions.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Dues_Transactions.htm
+      #
+      # @param [DateTime] date Date to export records from.
+      # @param [Boolean] unicode Export format.
+      # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
+      def self.dues_transactions(date, unicode)
+        generic_export('Sa.Export.Dues.Transactions', date, unicode)
+      end
+
+      # Starts an export of dues invoice items.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Dues_InvoiceItems.htm
+      #
+      # @param [DateTime] date Date to export records from.
+      # @param [Boolean] unicode Export format.
+      # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
+      def self.dues_invoiceItems(date, unicode)  # rubocop:disable Style/MethodName
+        generic_export('Sa.Export.Dues.InvoiceItems', date, unicode)
+      end
+
+      # Starts an export of store orders.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Store_Orders.htm
+      #
+      # @param [DateTime] date Date to export records from.
+      # @param [Boolean] unicode Export format.
+      # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
+      def self.store_orders(date, unicode)
+        generic_export('Sa.Export.Store.Orders', date, unicode)
+      end
+
+      # Starts an export of store order invoice items.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Store_InvoiceItems.htm
+      #
+      # @param [DateTime] date Date to export records from.
+      # @param [Boolean] unicode Export format.
+      # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
+      def self.store_invoiceItems(date, unicode) # rubocop:disable Style/MethodName
+        generic_export('Sa.Export.Store.InvoiceItems', date, unicode)
+      end
+
+      # Starts an export of registration records for an event
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Event_Registrations.htm
+      #
+      # @param [Integer] event_id Event ID of the event to view registrations.
+      # @param [Boolean] unicode Export format.
+      # @param [Hash] options
+      # @option options [String] :SessionIDs Comma Delimited List of Session IDs to filter the results. ex: "1234,9876"
+      # @option options [Integer] :ProductID Filter the results to only those that have purchased supplied Product ID.
+      # @option options [Integer] :Processed Filter the results by their Process Status.
+      #  Options: 0 = All, 1 = Open Records, 2 = Processed Records
+      # @option options [String] :LastName Filter registrations by the supplied Last Name.
+      # @option options [Boolean] :AttendedEvent Filter registrations check in status.
+      # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
+      def self.event_registrations(event_id, unicode, options = {})  # rubocop:disable Style/MethodName
+        options[:EventID] = event_id
+        generic_export('Sa.Export.Event.Registrations', nil, unicode, options)
+      end
+
+      private
+
+      def self.generic_export(api_method, date, unicode, options = {})
+        options[:Unicode] = unicode
+        options[:Date] = date
+
+        response = post('/', :body => build_XML_request(api_method, nil, options))
+        response_valid? response
+        new(response['YourMembership_Response'][api_method]['ExportID'])
+      end
+
+      def update_export_uri(status_response)
+        @export_uri = status_response['ExportURI']
+      end
+
+      # Convert YourMembership API codes to readable symbols
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Status.htm
+      #
+      # @param [Integer] status The status code
+      # @return [Symbol] The status as a Symbol
+      def convert_status(status)
+        case status
+        when '-1'
+          return :failure
+        when '0'
+          return :unknown
+        when '1'
+          return :working
+        when '2'
+          return :complete
+        else
+          return :error
+        end
+      end
+    end
+  end
+end

data/lib/your_membership/sa_groups.rb

@@ -0,0 +1,30 @@
+module YourMembership
+  module Sa
+    # YourMembership System Administrator Groups Namespace
+    class Groups < YourMembership::Base
+      # Returns a list of group membership log entries by Group ID that may be optionally filtered by timestamp.
+      # This method will return a maximum of 1,000 results.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Groups_Group_GetMembershipLog.htm
+      #
+      # @param [Integer] group_id The Group ID of the Membership Log records to be returned.
+      # @param [Hash] options
+      # @option options [DateTime] :StartDate Filter the returned results by date/time. Only those membership log items which
+      #  have been created or updated after the supplied date/time will be returned.
+      # @option options [Integer] :ItemID Filter the returned results by sequential ItemID. Only those membership log items
+      #  which have a ItemID greater than the supplied integer will be returned. A typical usage scenario for this
+      #  parameter would be to supply it when making additional calls while 1,000 records are being returned. You would
+      #  supply the last record's ItemID to retrieve the next batch of up to 1,000 records, repeating the process until
+      #  no records are returned.
+      # @return [Hash] Returns an Hash representing a group's membership Log
+      def self.group_getMembershipLog(group_id, options = {}) # rubocop:disable Style/MethodName
+        options[:GroupID] = group_id
+
+        response = post('/', :body => build_XML_request('Sa.Groups.Group.GetMembershipLog', nil, options))
+
+        response_valid? response
+        response['YourMembership_Response']['Sa.Groups.Group.GetMembershipLog']
+      end
+    end
+  end
+end

data/lib/your_membership/sa_member.rb

@@ -0,0 +1,49 @@
+module YourMembership
+  module Sa
+    # YourMembership System Administrator Member Namespace
+    class Member < YourMembership::Base
+      # Returns a list of Certifications for the specified user.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Member_Certifications_Get.htm
+      #
+      # @param [Integer] member_id ID of the person whose certifications to return.
+      # @param [Hash] options
+      # @option options [Boolean] :IsArchived Include archived certification records in the returned result. Def: True
+      # @return [Array] Returns an array of Hashes representing a member's certifications
+      def self.certifications_get(member_id, options = {})
+        options[:ID] = member_id
+
+        response = post('/', :body => build_XML_request('Sa.Member.Certifications.Get', nil, options))
+
+        response_valid? response
+        response_to_array_of_hashes response['YourMembership_Response']['Sa.Member.Certifications.Get'], ['Certification']
+      end
+
+      # Returns a list of Certification Journal Entries for the specified user that may be optionally filtered by
+      # date, expiration, and paging.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Member_Certifications_Journal_Get.htm
+      #
+      # @param [Integer] member_id ID of the person whose certifications to return.
+      # @param [Hash] options
+      # @option options [Boolean] :ShowExpired Include expired journal entries in the returned result.
+      # @option options [DateTime] :StartDate Only include Journal Entries that are newer that the supplied date.
+      # @option options [Integer] :EntryID Filter the returned results by sequential EntryID. Only those Certification
+      #  Journals which have an EntryID greater than the supplied integer will be returned.
+      # @option options [String] :CertificationID Filter the Journal Entries returned by the specified Certification ID.
+      # @option options [Integer] :PageSize The number of items that are returned per call of this method.
+      #  Default is 200 entries.
+      # @option options [Integer] :PageNumber PageNumber can be used to retrieve multiple result sets.
+      #  Page 1 is returned by default.
+      # @return [Array] Returns an array of Hashes representing a member's certification journal entries.
+      def self.certifications_journal_get(member_id, options = {})
+        options[:ID] = member_id
+
+        response = post('/', :body => build_XML_request('Sa.Member.Certifications.Journal.Get', nil, options))
+
+        response_valid? response
+        response_to_array_of_hashes response['YourMembership_Response']['Sa.Member.Certifications.Journal.Get'], ['Entry']
+      end
+    end
+  end
+end