wcc-arena 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 847a7b9b46ead985eb00221fb3ce685215671746
+  data.tar.gz: 7ce4cea280b3de3c7761e64619d5d3af2083caab
+SHA512:
+  metadata.gz: 23dda6c3fc79b84e9934f985c73ebc1d64dff57244b5780c24e05c8bbebb0d0a995dbf955398f5f941afc9dc7f9d1898b408d80b18cd0e3ee3cbd3861fe81d72
+  data.tar.gz: 5b504562dd6e74c74fec426714500952a07a6410facf94f41765df9b7753487502aebe295efa6622daf75f1cb7154b2ee46e240079bf1934c00f8988e8d35839

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.arena-creds
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in wcc-arena.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Watermark Community Church
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,71 @@
+# WCC::Arena
+
+This gem provides wrappers to the Arena church management system's API.
+This is an early version of the library, and has had limited testing in
+real world environments. Use at your own risk!
+
+There are also bound to be a few things that are specific to our
+configuration and version of Arena. This isn't intentional and we
+consider that a bug that we would like to fix. We would love for this to
+be a fully featured way to interact with Arena's API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'wcc-arena'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install wcc-arena
+
+## Configuration
+
+You can configure the wcc-arena gem using the `WCC::Arena.configure`
+method.
+
+Here is an example configuration block:
+
+```ruby
+WCC::Arena.configure do |arena|
+  arena.username = 'username'
+  arena.password = 'password'
+  arena.api_key = 'api_key'
+  arena.api_secret = 'api_secret'
+  arena.api_url = 'https://arena-domain/api.svc/'
+end
+```end
+
+## Usage
+
+The library is currently a very thin layer over the Arena API. We plan
+to add a higher level interface layer that provides a better experience
+for the most common use cases.
+
+The library consists of Query classes and Mapper classes. The Query
+classes handle calling the respective services and the Mapper classes
+handle binding the XML to Ruby objects. For full details on all
+available endpoints please see the code. Below are a few examples of
+some common queries.
+
+```ruby
+query = WCC::Arena::PersonQuery.new.where(first_name: "Travis")
+people = query.call
+people.each do |person|
+  puts person.full_name
+end
+```
+This will print the full names of all person records with the first name
+"Travis".
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,45 @@
+require "bundler/gem_tasks"
+require "json"
+
+PROJECT_PATH = File.dirname(__FILE__)
+LIB_PATH = File.join(PROJECT_PATH, "lib")
+CREDENTIALS_PATH = File.join(PROJECT_PATH, ".arena-creds")
+
+task :default => :test
+
+desc 'set load path and require the gem'
+task :environment do
+  $LOAD_PATH.unshift(LIB_PATH)
+  require 'wcc/arena'
+end
+
+desc 'run test examples'
+task :test do
+  exec 'rspec .'
+end
+
+desc 'open an IRB session with environment loaded'
+task :irb => :environment do
+  require 'irb'
+  ARGV.clear
+  IRB.start
+end
+
+desc 'point the library at the instance of Arena described in .arena-creds and launch irb'
+task :arena => :environment do
+  creds = JSON.parse(File.open(CREDENTIALS_PATH).read)
+  WCC::Arena.configure do |arena|
+    arena.username = creds['username']
+    arena.password = creds['password']
+    arena.api_key = creds['api_key']
+    arena.api_secret = creds['api_secret']
+    arena.api_url = creds['api_url']
+  end
+  $session = WCC::Arena::Session.new(
+    username: WCC::Arena.config.username,
+    password: WCC::Arena.config.password,
+    api_key: WCC::Arena.config.api_key,
+    api_secret: WCC::Arena.config.api_secret,
+  )
+  Rake::Task['irb'].invoke
+end

data/lib/wcc/arena.rb

@@ -0,0 +1,15 @@
+require "wcc/arena/version"
+
+require 'faraday'
+require 'nokogiri'
+
+require "wcc/arena/config"
+require "wcc/arena/mappers"
+require 'wcc/arena/modify_result'
+require "wcc/arena/response"
+require "wcc/arena/session"
+require "wcc/arena/signed_path"
+
+require "wcc/arena/group"
+require "wcc/arena/person"
+require "wcc/arena/profile"

data/lib/wcc/arena/address.rb

@@ -0,0 +1,21 @@
+module WCC::Arena
+
+  class Address
+    include WCC::Arena::Mappers::XML
+
+    attribute :id, xpath: "AddressID", type: :integer
+    attribute :type_id, xpath: "AddressTypeID", type: :integer
+    attribute :type_value, xpath: "AddressTypeValue"
+    attribute :city, xpath: "City"
+    attribute :country, xpath: "Country"
+    attribute :latitude, xpath: "Latitude"
+    attribute :longitude, xpath: "Longitude"
+    attribute :postal_code, xpath: "PostalCode"
+    attribute :primary, xpath: "Primary", type: :boolean
+    attribute :state, xpath: "State"
+    attribute :street1, xpath: "StreetLine1"
+    attribute :street2, xpath: "StreetLine2"
+
+  end
+
+end

data/lib/wcc/arena/config.rb

@@ -0,0 +1,39 @@
+module WCC::Arena
+  class Config
+    attr_accessor :username, :password, :api_key, :api_secret
+    attr_accessor :api_url
+    attr_accessor :logger, :connection
+
+    def connection
+      @connection ||= default_connection
+    end
+
+    def session
+      @session ||= WCC::Arena::Session.new(
+        connection: connection,
+        username: username,
+        password: password,
+        api_key: api_key,
+        api_secret: api_secret
+      )
+    end
+
+    private
+
+    def default_connection
+      Faraday.new(url: api_url) do |faraday|
+        faraday.request :url_encoded
+        faraday.response :logger
+        faraday.adapter Faraday.default_adapter
+      end
+    end
+  end
+
+  def self.config
+    @config ||= Config.new
+  end
+
+  def self.configure
+    yield config
+  end
+end

data/lib/wcc/arena/email.rb

@@ -0,0 +1,10 @@
+module WCC::Arena
+
+  class Email
+    include WCC::Arena::Mappers::XML
+
+    attribute :address, xpath: "Address"
+
+  end
+
+end

data/lib/wcc/arena/group.rb

@@ -0,0 +1,29 @@
+require 'wcc/arena/group_query'
+
+require 'wcc/arena/address'
+require 'wcc/arena/group_member'
+
+module WCC::Arena
+  class Group
+    include WCC::Arena::Mappers::XML
+
+    attribute :id, xpath: "GroupID", type: :integer
+    attribute :guid, xpath: "Guid"
+
+    attribute :name, xpath: "Name"
+    attribute :active, xpath: "Active", type: :boolean
+    attribute :area_name, xpath: "AreaName"
+    attribute :area_id, xpath: "AreaID", type: :integer
+    attribute :type, xpath: "GroupTypeValue"
+    attribute :type_id, xpath: "GroupTypeID", type: :integer
+    attribute :leader_id, xpath: "LeaderID", type: :integer
+
+    has_one :address, xpath: "TargetLocation", klass: Address
+
+    alias :active? :active
+
+    def members
+      @members ||= GroupMemberQuery.new(group_id: id).()
+    end
+  end
+end

data/lib/wcc/arena/group_member.rb

@@ -0,0 +1,35 @@
+require 'wcc/arena/group_member_query'
+
+require 'wcc/arena/person'
+
+module WCC::Arena
+
+  class GroupMember
+    include WCC::Arena::Mappers::XML
+
+    attribute :group_id, xpath: "GroupID", type: :integer
+    attribute :person_id, xpath: "PersonID", type: :integer
+
+    attribute :active, xpath: "Active", type: :boolean
+    attribute :joined_at, xpath: "DateJoined", type: :time
+    attribute :role, xpath: "RoleValue"
+    attribute :role_id, xpath: "RoleID", type: :integer
+    attribute :person_link, xpath: "PersonLink"
+
+    has_one :person, xpath: "PersonInformation", klass: Person
+
+    def person_guid
+      person_link.split("/").last
+    end
+
+    def full_name
+      person.full_name ||
+        [
+          person.first_name,
+          person.last_name
+        ].join(" ")
+    end
+
+  end
+
+end

data/lib/wcc/arena/group_member_query.rb

@@ -0,0 +1,32 @@
+module WCC::Arena
+
+  class GroupMemberQuery
+    attr_reader :session
+    attr_reader :group_id
+
+    def initialize(args={})
+      @session = args.fetch(:session) { WCC::Arena.config.session }
+      @group_id = args.fetch(:group_id)
+    end
+
+    def call
+      members_xml.collect do |member_xml|
+        GroupMember.new(member_xml)
+      end
+    end
+
+    private
+
+    def members_xml
+      query_response.xml.root.xpath("Members/GroupMember")
+    end
+
+    def query_response
+      @response ||= session.get(
+        "group/#{group_id}/member/list"
+      )
+    end
+
+  end
+
+end

data/lib/wcc/arena/group_query.rb

@@ -0,0 +1,36 @@
+module WCC::Arena
+
+  class GroupQuery
+    attr_reader :session
+    attr_reader :person_id
+    attr_reader :category_id
+
+    def initialize(args={})
+      @session = args.fetch(:session) { WCC::Arena.config.session }
+      @person_id = args.fetch(:person_id)
+      @category_id = args.fetch(:category_id)
+    end
+
+    def call
+      response_groups_xml.collect do |person_xml|
+        Group.new(person_xml)
+      end
+    end
+
+    private
+
+    def response_groups_xml
+      query_response.xml.root.xpath("Groups/Group")
+    end
+
+    def query_response
+      @response ||= session.get(
+        "person/#{person_id}/group/list",
+        categoryid: category_id
+      )
+    end
+
+
+  end
+
+end

data/lib/wcc/arena/mappers.rb

@@ -0,0 +1,6 @@
+module WCC::Arena
+  module Mappers
+  end
+end
+
+require 'wcc/arena/mappers/xml'

data/lib/wcc/arena/mappers/xml.rb

@@ -0,0 +1,131 @@
+require 'date'
+require 'time'
+
+module WCC::Arena::Mappers
+
+  module XML
+
+    attr_reader :document
+
+    def initialize(document)
+      @document = document
+    end
+
+    def [](attribute)
+      if self.class.attributes[attribute]
+        load_attribute(attribute)
+      else
+        raise KeyError, "Attribute #{attribute} is not defined"
+      end
+    end
+
+    def attributes
+      self.class.attributes.each_with_object({}) do |(name, options), hash|
+        hash[name] = self[name]
+      end
+    end
+
+    def inspect
+      "<#{self.class.name} " \
+      "#{attributes.collect { |(name, value)| [name, value.inspect].join("=") }.join(" ")}>"
+    end
+
+    def load_association(name)
+      if config = self.class.associations[name]
+        list = document.xpath(config[:xpath]).collect do |node|
+          config[:klass].new(node)
+        end
+        case config[:type]
+        when :many
+          list
+        when :one
+          list.first
+        end
+      end
+    end
+    private :load_association
+
+    def load_attribute(attribute)
+      config = self.class.attributes[attribute]
+      node = document.xpath(config[:xpath])
+      cast_attribute(node.text, config[:type])
+    end
+
+    def cast_attribute(text, type)
+      return nil if text.empty?
+
+      case type
+      when :integer
+        Integer(text)
+      when :date
+        Date.strptime(text.split("T").first, "%Y-%m-%d")
+      when :time
+        Time.parse(text)
+      when :boolean
+        text.downcase == "true"
+      else
+        text
+      end
+    end
+
+    module ClassMethods
+
+      def attribute(name, options)
+        options.fetch(:xpath) {
+          raise ArgumentError, ":xpath is a required argument to the `attribute' method"
+        }
+        attributes[name] = options.freeze
+        define_method(name) { self[name] }
+      end
+
+      def attributes
+        @attributes ||= {}
+      end
+
+      def associations
+        @associations ||= {}
+      end
+
+      def has_one(name, options)
+        add_association(name, options.merge(type: :one)) do
+          @association_cache ||= {}
+          @association_cache[name] ||= load_association(name)
+        end
+      end
+
+      def has_many(name, options)
+        add_association(name, options.merge(type: :many)) do
+          @association_cache ||= {}
+          @association_cache[name] ||= load_association(name)
+        end
+      end
+
+      def add_association(name, options, &block)
+        options.fetch(:xpath) {
+          raise ArgumentError, ":xpath is a required argument"
+        }
+        options.fetch(:klass) {
+          raise ArgumentError, ":klass is a required argument"
+        }
+        options.fetch(:type) {
+          raise ArgumentError, ":type is a required argument"
+        }
+        associations[name] = options.freeze
+        define_method(name, &block) if block_given?
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@attributes, attributes.dup)
+        subclass.instance_variable_set(:@associations, associations.dup)
+      end
+
+    end
+
+    def self.included(receiver)
+      receiver.extend ClassMethods
+    end
+
+  end
+
+end