your_membership 1.0.0

data/lib/your_membership/sa_members.rb

@@ -0,0 +1,179 @@
+module YourMembership
+  module Sa
+    # YourMembership System Administrator Members Namespace
+    class Members < YourMembership::Base
+      # Returns a list of member IDs that may be optionally filtered by timestamp, and/or group membership. This
+      # method is provided for data synchronization purposes and will return a maximum of 10,000 results. It would
+      # typically be used in conjunction with subsequent calls to Sa.People.Profile.Get for each <ID> returned.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Members_All_GetIDs.htm
+      #
+      # @param [Hash] options
+      # @option options [DateTime] :Timestamp Only accounts created after the this time will be returned
+      # @option options [String] :WebsiteID Filter the returned results by sequential WebsiteID.
+      # @option options [Array] :Groups Filter the returned results by group membership. [key, value] will translate to
+      #  <key>value</key>
+      #
+      # @return [Array] A list of API IDs for members in your community.
+      def self.all_getIDs(options = {}) # rubocop:disable Style/MethodName
+        response = post('/', :body => build_XML_request('Sa.Members.All.GetIDs', nil, options))
+        response_valid? response
+        response['YourMembership_Response']['Sa.Members.All.GetIDs']['Members']['ID']
+      end
+
+      # Returns a Hash of recent member activity on your YourMembership Site
+      # Returns member community activity information for the purpose of creating a navigation control.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Members_All_RecentActivity.htm
+      #
+      # @return [Hash] A subset of data is returned for each of the following:
+      #
+      #  * Newest member
+      #  * Latest post
+      #  * Latest comment on a post
+      #  * Latest photo
+      def self.all_recentActivity # rubocop:disable Style/MethodName
+        response = post('/', :body => build_XML_request('Sa.Members.All.RecentActivity'))
+        response_valid? response
+        response['YourMembership_Response']['Sa.Members.All.RecentActivity'].to_h
+      end
+
+      # Returns a list of order IDs for a specified member that may be optionally filtered by timestamp and status.
+      # This method will return a maximum of 1,000 results.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Members_Commerce_Store_GetOrderIDs.htm
+      #
+      # @param member_id [String] The id of the person for whom you want to retrieve data
+      # @param [Hash] options
+      # @option options [DateTime] :Timestamp Filter the returned results by date/time. Only those orders which were
+      #  placed after the supplied date/time will be returned.
+      # @option options [Symbol, Integer] :Status Filter the returned results by Status.
+      #  (-1 = :Cancelled; 0 = :open; 1 = :processed; 2 = :shipped or :closed)
+      #
+      # @return [Array] A list of Invoice Id Strings
+      def self.commerce_store_getOrderIDs(member_id, options = {}) # rubocop:disable Style/MethodName
+        options[:ID] = member_id
+        if options[:Status]
+          options[:Status] = YourMembership::Commerce.convert_order_status(options[:Status])
+        end
+        response = post('/', :body => build_XML_request('Sa.Members.Commerce.Store.GetOrderIDs', nil, options))
+        response_valid? response
+        response_to_array response['YourMembership_Response']['Sa.Members.Commerce.Store.GetOrderIDs']['Orders'], ['Order'], 'InvoiceID'
+      end
+
+      # Returns Event Registration details for the provided Event and Member ID. Includes all Event Registration details
+      # for Primary Registrant and Additional Registrants. 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_Members_Events_Event_Registration_Get.htm
+      #
+      # @param event_id [Integer] The ID number for the Event you wish to retrieve Event Registration from.
+      # @param member_id [Integer] Member's API ID
+      #
+      # @return [Array] Returns an Array of Hashes that represent registrations by a specific user for a specific event.
+      def self.events_event_registration_get(event_id, member_id) # rubocop:disable Style/MethodName
+        options = {}
+        options[:EventID] = event_id
+        options[:ID] = member_id
+
+        response = post('/', :body => build_XML_request('Sa.Members.Events.Event.Registration.Get', nil, options))
+
+        response_valid? response
+        response_to_array_of_hashes response['YourMembership_Response']['Sa.Members.Events.Event.Registration.Get'], ['Registrations', 'Registration']
+      end
+
+      # Returns a list of a member's referrals.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Members_Referrals_Get.htm
+      #
+      # @param member_id [String] ID of the person whose referrals to return.
+      # @param [Hash] options
+      # @option options [DateTime] :Timestamp Filter the returned results by date/time. Only those referred members who
+      #  registered after the supplied date/time will be returned.
+      #
+      # @return [Array] Returns an Array of Hashes that represent a Member's referrals
+      def self.referrals_get(member_id, options = {})
+        options[:ID] = member_id
+
+        response = post('/', :body => build_XML_request('Sa.Members.Referrals.Get', nil, options))
+
+        response_valid? response
+        response_to_array_of_hashes response['YourMembership_Response']['Sa.Members.Referrals.Get'], ['Member']
+      end
+
+      # Returns a list of a member's sub-accounts.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Members_SubAccounts_Get.htm
+      #
+      # @param member_id [String] ID of the person whose sub-accounts to return.
+      # @param options [Hash]
+      # @option options [Datetime] :Timestamp Filter the returned results by date/time. Only those members who
+      #  registered after the supplied date/time will be returned.
+      #
+      # @return [Array] Returns an Array of Hashes that represent a Member's Subaccounts
+      def self.subAccounts_get(member_id, options = {}) # rubocop:disable Style/MethodName
+        options[:ID] = member_id
+
+        response = post('/', :body => build_XML_request('Sa.Members.SubAccounts.Get', nil, options))
+
+        response_valid? response
+        response_to_array_of_hashes response['YourMembership_Response']['Sa.Members.SubAccounts.Get'], ['Member']
+      end
+
+      # Create a CEU Journal Entry.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Members_Certifications_JournalEntry_Create.htm
+      #
+      # @param member_id [String] ID of the person who owns this certification journal entry.
+      # @param ceus_earned [Integer] The number of CEU Credits earned for this journal entry.
+      # @param ceus_expire_date [DateTime] The ODBC Date the CEU Credits Expire.
+      # @param description [String] Description of this journal entry.
+      # @param entry_date [DateTime] Date and time of this journal entry.
+      # @param options [Hash]
+      # @option options [String] :CertificationId The ID of the certification this journal entry is a part of. If
+      #  neither CertificationName nor CertificationID are supplied, the journal entry will not be attached to a
+      #  specific certification.
+      # @option options [String] :CertificationName For Self-Awarded certification journal entries that are not linked
+      #  an existing certification record. This is the same behavior as choosing "Other Certification" and entering a
+      #  Self-Awarded journal entry. If neither CertificationName nor CertificationID are supplied, the journal entry
+      #  will not be attached to a specific certification.
+      # @option options [Decimal] :ScorePercent The decimal representation of a percentage score.
+      #  For example, 90% would be 0.90.
+      # @option options [String] :CreditTypeCode Unique code for this new Journal Entry's Credit Type.
+      #  If absent, the default Credit Type Code will be used.
+      #
+      # @return [Boolean] Returns true or raises exception.
+      def self.certifications_journalEntry_create(member_id, ceus_earned, ceus_expire_date, description, entry_date, options = {}) # rubocop:disable Style/MethodName
+        options['ID'] = member_id
+        options['CEUsEarned'] = ceus_earned
+        options['CEUsExpireDate'] = ceus_expire_date
+        options['Description'] = description
+        options['EntryDate'] = entry_date
+
+        response = post('/', :body => build_XML_request('Sa.Members.Certifications.JournalEntry.Create', nil, options))
+        response_valid? response
+      end
+
+      # Creates a new member profile and returns a member object.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_Members_Profile_Create.htm
+      #
+      # @param profile [YourMembership::Profile]
+      #
+      # @return [YourMembership::Member] A Member object for the member that was just created.
+      # @todo: This currently returns an authenticated session for each created user. This may not be the desired
+      #  permanent operation of this function.
+      def self.profile_create(profile)
+        options = {}
+        options['profile'] = profile
+        response = post('/', :body => build_XML_request('Sa.Members.Profile.Create', nil, options))
+        response_valid? response
+        YourMembership::Sa::Auth.authenticate(
+          YourMembership::Session.new,
+          profile.data['Username'],
+          profile.data['Password']
+        )
+      end
+    end
+  end
+end

data/lib/your_membership/sa_nonmembers.rb

@@ -0,0 +1,41 @@
+module YourMembership
+  module Sa
+    # YourMembership System Administrator Members Namespace
+    class NonMembers < YourMembership::Base
+      # Returns a list of non-member IDs that may be optionally filtered by timestamp. This method is provided for data
+      # synchronization purposes and will return a maximum of 10,000 results. It would typically be used in conjunction
+      # with subsequent calls to Sa.People.Profile.Get for each ID returned.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_NonMembers_All_GetIDs.htm
+      #
+      # @param [Hash] options
+      # @option options [DateTime] :Timestamp Only accounts created after the this time will be returned
+      # @option options [String] :WebsiteID Filter the returned results by sequential WebsiteID.
+      # @option options [Array] :Groups Filter the returned results by group membership. [key, value] will translate to
+      #  <key>value</key>
+      #
+      # @return [Array] A list of API IDs for non-members in your community.
+      def self.all_getIDs(options = {}) # rubocop:disable Style/MethodName
+        response = post('/', :body => build_XML_request('Sa.NonMembers.All.GetIDs', nil, options))
+        response_valid? response
+        response['YourMembership_Response']['Sa.NonMembers.All.GetIDs']['NonMembers']['ID']
+      end
+
+      # Creates a new non-member profile and returns the new non-member's ID and WebsiteID. The returned ID must be
+      # supplied when performing future updates to the non-member's profile. The returned WebsiteID represents the
+      # numeric identifier used by the YourMembership.com application for navigation purposes.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_NonMembers_Profile_Create.htm
+      #
+      # @param [YourMembership::Profile] profile
+      # @return [Hash] The ID and WebsiteID of the nonmember created
+      def self.profile_create(profile)
+        options = {}
+        options['profile'] = profile
+        response = post('/', :body => build_XML_request('Sa.NonMembers.Profile.Create', nil, options))
+        response_valid? response
+        response['YourMembership_Response']['Sa.NonMembers.Profile.Create']
+      end
+    end
+  end
+end

data/lib/your_membership/sa_people.rb

@@ -0,0 +1,92 @@
+module YourMembership
+  module Sa
+    # YourMembership System Administrator Members Namespace
+    class People < YourMembership::Base
+      # Returns a list of member and non-member IDs that may be optionally filtered by timestamp. This method is
+      # provided for data synchronization purposes and will return a maximum of 10,000 results. It would typically be
+      # used in conjunction with subsequent calls to Sa.People.Profile.Get for each ID returned
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_People_All_GetIDs.htm
+      #
+      # @param [Hash] options
+      # @option options [DateTime] :Timestamp Only accounts created after the this time will be returned
+      # @option options [String] :WebsiteID Filter the returned results by sequential WebsiteID.
+      # @option options [Array] :Groups Filter the returned results by group membership. [key, value] will translate to
+      #  <key>value</key>
+      #
+      # @return [Array] A list of API IDs for non-members in your community.
+      def self.all_getIDs(options = {}) # rubocop:disable Style/MethodName
+        response = post('/', :body => build_XML_request('Sa.People.All.GetIDs', nil, options))
+        response_valid? response
+        response['YourMembership_Response']['Sa.People.All.GetIDs']['People']['ID']
+      end
+
+      # Finds and returns a member or non-member <ID> using Import ID, Constituent ID or Website/Profile ID as criteria.
+      # If a single ID cannot be uniquely identified based on the criteria supplied then error code 406 is returned.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_People_Profile_FindID.htm
+      #
+      # @param [Hash] options
+      # @option options [String] :ImportID Import ID of the person whose ID you are trying to find.
+      # @option options [String] :ConstituentID Constituent ID of the person whose ID you are trying to find.
+      # @option options [Integer] :WebsiteID Website/Profile ID of the person whose ID you are trying to find.
+      # @option options [String] :Username Username of the person whose ID you are trying to find.
+      # @option options [String] :Email Email Address of the person whose <ID> you are trying to find.
+      #  May return multiple <ID>'s as Email Address is not unique.
+      #
+      # @return [String] if a single record is found (normal for all calls except for :Email)
+      # @return [Array] if multiple records are found (possible only for :Email searches)
+      def self.profile_findID(options = {}) # rubocop:disable Style/MethodName
+        response = post('/', :body => build_XML_request('Sa.People.Profile.FindID', nil, options))
+        response_valid? response
+        response['YourMembership_Response']['Sa.People.Profile.FindID']['ID']
+      end
+
+      # Returns a person's profile data.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_People_Profile_Get.htm
+      #
+      # @param [String] id ID of the person whose profile data to return.
+      # @return [YourMembership::Profile] Returns a Profile object that represents the person's profile
+      def self.profile_get(id)
+        options = {}
+        options[:ID] = id
+        response = post('/', :body => build_XML_request('Sa.People.Profile.Get', nil, options))
+        response_valid? response
+        YourMembership::Profile.new response['YourMembership_Response']['Sa.People.Profile.Get']
+      end
+
+      # Returns a person's group relationship data. There are three types of relationships that members may have with
+      # particular groups; "Administrator", "Member" and "Representative". Groups are listed within nodes respective
+      # of their relationship type.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_People_Profile_Groups_Get.htm
+      #
+      # @param [String] id ID of the person whose profile data to return.
+      # @return [Hash] Returns a Hash that represents the person's group relationships
+      def self.profile_groups_get(id)
+        options = {}
+        options[:ID] = id
+        response = post('/', :body => build_XML_request('Sa.People.Profile.Groups.Get', nil, options))
+
+        response_valid? response
+        response['YourMembership_Response']['Sa.People.Profile.Groups.Get']
+      end
+
+      # Updates an existing person's profile.
+      #
+      # @see https://api.yourmembership.com/reference/2_00/Sa_People_Profile_Update.htm
+      #
+      # @param [String] id ID of the person whose profile is to be updated.
+      # @param [YourMembership::Profile] profile The profile object containing the fields to be updated
+      # @return [Boolean] Will raise and exception or return TRUE
+      def self.profile_update(id, profile)
+        options = {}
+        options['ID'] = id
+        options['profile'] = profile
+        response = post('/', :body => build_XML_request('Sa.People.Profile.Update', nil, options))
+        response_valid? response
+      end
+    end
+  end
+end

data/lib/your_membership/session.rb

@@ -0,0 +1,147 @@
+module YourMembership
+  # YourMembership Session Object
+  #
+  # Session objects encapsulate the creation, storage, authentication, maintenance, and destruction of sessions in the
+  # YourMembership.com API.
+  #
+  # @note It is important to note that the Auth Namespace has been consumed by Sessions in the SDK as sessions and
+  #  authentication are inextricably linked.
+  #
+  # Sessions can be *generic* (unauthenticated), *authenticated*, or *abandoned*.
+  #
+  # * *Generic sessions* are used extensively whenever the scope of a specific user is not necessary.
+  # * *Authenticated sessions* are used when the called method requires the scope of a specific user.
+  # * *Abandoned sessions* are no longer usable and are essentially the same as logging out.
+  #
+  # @example Generic (unauthenticated) Session
+  #  session = YourMembership::Session.new # => <YourMembership::Session>
+  # @example Authenticated Session
+  #  auth_session = YourMembership::Session.new 'username', 'password' # => <YourMembership::Session>
+  #
+  # @attr_reader [String] session_id The unique session identifier provided by the API
+  # @attr_reader [String, Nil] user_id The user id of the user bound to the session, if one exists.
+  class Session < YourMembership::Base
+    attr_reader :session_id, :user_id
+
+    # @see https://api.yourmembership.com/reference/2_00/Session_Create.htm
+    # @param user_name [String] Constructor takes optional parameters of user_name and password. If supplied then the
+    #  session will be automatically authenticated upon instantiation.
+    # @param password [String]
+    def initialize(user_name = nil, password = nil)
+      @call_id = 1
+      @user_id = nil
+
+      response = self.class.post('/', :body => self.class.build_XML_request('Session.Create'))
+
+      if self.class.response_valid? response
+        @session_id = response['YourMembership_Response']['Session.Create']['SessionID']
+      end
+
+      authenticate user_name, password if user_name
+    end
+
+    # @return [Integer] Auto Increments ad returns the call_id for the session as required by the YourMembership.com API
+    def call_id
+      @call_id += 1
+    end
+
+    # @return [String] Returns the session_id
+    def to_s
+      @session_id
+    end
+
+    # Destroys an API session, thus preventing any further calls against it.
+    #
+    # @see https://api.yourmembership.com/reference/2_00/Session_Abandon.htm
+    #
+    # @return [Boolean] Returns true if the session was alive and successfully abandoned.
+    def abandon
+      response = self.class.post('/', :body => self.class.build_XML_request('Session.Abandon', self))
+      self.class.response_valid? response
+    end
+
+    # When called at intervals of less than 20 minutes, this method acts as an API session keep-alive.
+    #
+    # @see https://api.yourmembership.com/reference/2_00/Session_Ping.htm
+    #
+    # @return [Boolean] Returns true if the session is still alive.
+    def ping
+      response = self.class.post('/', :body => self.class.build_XML_request('Session.Ping', self))
+      self.class.response_valid? response
+      response['YourMembership_Response']['Session.Ping'] == '1'
+    end
+
+    # Convenience method for ping.
+    def valid?
+      ping
+    end
+
+    # Authenticates a member's username and password and binds them to the current API session.
+    #
+    # @see https://api.yourmembership.com/reference/2_00/Auth_Authenticate.htm
+    #
+    # @param user_name [String] The username of the member that is being authenticated.
+    # @param password [String] The clear text password of the member that is being authenticated.
+    #
+    # @return [Hash] Returns the member's ID and WebsiteID. The returned WebsiteID represents the numeric identifier
+    #  used by the YourMembership.com application for navigation purposes. It may be used to provide direct navigation to
+    #  a member's profile, photo gallery, personal blog, etc.
+    def authenticate(user_name, password)
+      options = {}
+      options[:Username] = user_name
+      options[:Password] = password
+
+      response = self.class.post('/', :body => self.class.build_XML_request('Auth.Authenticate', self, options))
+
+      self.class.response_valid? response
+      if response['YourMembership_Response']['Auth.Authenticate']
+        get_authenticated_user
+      else
+        false
+      end
+    end
+
+    # Creates an AuthToken that is bound to the current session. The returned token must be supplied to the Sign-In
+    # form during member authentication in order to bind a member to their API session. The sign-in URL, which will
+    # include the new AuthToken in its query-string, is returned by this method as GoToUrl. Tokens expire after a short
+    # period of time, so it is suggested that the user be immediately redirected the returned GoToUrl after creating an
+    # authentication token.
+    #
+    # @see https://api.yourmembership.com/reference/2_00/Auth_CreateToken.htm
+    #
+    # @param options [Hash]
+    # @option options [String] :RetUrl After authentication the browser will be redirected to this URL
+    # @option options [String] :Username The user can optionally be logged in automatically if :Username and :Password
+    #  are supplied in cleartext.
+    # @option options [String] :Password The user's password
+    # @option options [Boolean] :Persist Supplying this value is only necessary when also providing user credentials for
+    #  automated authentication. The purpose of enabling persistence is to extend an authenticated user's browsing
+    #  session beyond its normal inactivity threshold of 20 minutes.
+    #
+    # @return [Hash] Contains the token String and a URL that will authenticate the session based on that token.
+    def createToken(options = {}) # rubocop:disable Style/MethodName
+      # Options inlclude: :RetUrl(String), :Username(String),
+      # :Password(String), :Persist(Boolean)
+
+      response = self.class.post('/', :body => self.class.build_XML_request('Auth.CreateToken', self, options))
+
+      self.class.response_valid? response
+      response['YourMembership_Response']['Auth.CreateToken']
+    end
+
+    # Indicates whether the session is bound to a user.
+    def authenticated?
+      if valid?
+        !get_authenticated_user.nil?
+      else
+        false
+      end
+    end
+
+    # Get the ID of the currently authenticated user bound to this session.
+    # @return [String, Nil] The API ID of the currently authenticated user
+    def get_authenticated_user # rubocop:disable Style/AccessorMethodName
+      @user_id = YourMembership::Member.isAuthenticated(self)
+    end
+  end
+end

data/lib/your_membership/version.rb

@@ -0,0 +1,3 @@
+module YourMembership
+  VERSION = "1.0.0"
+end

data/lib/your_membership.rb

@@ -0,0 +1,37 @@
+require "httparty"
+require "nokogiri"
+require "yaml"
+
+require "httparty/patch"
+
+require "your_membership/error"
+require "your_membership/config"
+require "your_membership/base"
+require "your_membership/session"
+require "your_membership/profile"
+require "your_membership/member"
+require "your_membership/commerce"
+require "your_membership/members"
+require "your_membership/convert"
+require "your_membership/sa_auth"
+require "your_membership/sa_members"
+require "your_membership/sa_certifications"
+require "your_membership/sa_commerce"
+require "your_membership/sa_events"
+require "your_membership/sa_export"
+require "your_membership/sa_groups"
+require "your_membership/sa_member"
+require "your_membership/sa_nonmembers"
+require "your_membership/sa_people"
+require "your_membership/events"
+require "your_membership/feeds"
+require "your_membership/people"
+
+require "your_membership/version"
+
+# Ruby SDK for YourMembership.Com XML API
+# @author Nate Flood <nflood@echonet.org>
+# @version 2.00
+# @see http://www.yourmembership.com/company/api-reference.aspx
+module YourMembership
+end