thecity 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7e558202d2137889f1d2d101f981d0530ce7ba51
+  data.tar.gz: c0fa317f5e9b9a4df29c4c13c04befd2057917ce
+SHA512:
+  metadata.gz: 1526b289a4e20a8b9010cc2ee5d6b8cbf01890a817715881285aa8b1f432cb7400bb214e531dfdba30b2fd38af0a6152c40e7d2c72218be19074b939ff81faaf
+  data.tar.gz: 4fccefc74465b71e3eccd26ab290f149a08b4afe5df92c97dda35677a391be31e45f9583c18944c1c480b2e9f5e72f186dc18aa3aa94a10b099ccfec79a69473

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+0.0.1
+-----
+* [Initial release](https://github.com/robertleib/thecity/commit/cd7aecde450157ae2ec0c07a2171d7149bebb74a)

data/LICENSE.md

@@ -0,0 +1,45 @@
+Copyright (c) 2013 Robert Leib
+
+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.
+
+
+Portions of this software were inspired by, modeled after, or just plain copied from:
+https://github.com/sferik/twitter
+
+Copyright (c) 2006-2013 Erik Michaels-Ober, John Nunemaker, Wynn Netherland, Steve Richert, Steve Agalloco
+
+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,170 @@
+# The City Ruby Gem
+
+A Ruby interface to the The City API. For more information about The City platform, see [http://api.onthecity.org][api info]
+
+[api info]: http://api.onthecity.org
+
+## Installation
+    gem install thecity
+
+## Configuration
+The City API requires you to authenticate via OAuth, so you'll need to
+register your application with The City under the Admin | API panel.
+
+Your new application will be assigned a key/secret pair (app_id/app_secret). You'll need
+to configure these values before you make a request or else you'll get the
+error:
+
+    Bad Authentication data
+
+You can pass configuration options as a block to `TheCity::API::Client.new`.
+
+```ruby
+client = TheCity::API::Client.new do |config|
+  config.app_id        = "YOUR_APP_ID"
+  config.app_secret    = "YOUR_APP_SECRET"
+  config.access_token  = "OAUTH_ACCESS_TOKEN"
+end
+```
+
+or
+
+```ruby
+client = TheCity::API::Client.new
+client.app_id        = "YOUR_APP_ID"
+client.app_secret    = "YOUR_APP_SECRET"
+client.access_token  = "OAUTH_ACCESS_TOKEN"
+```
+
+Alternately, you can set the following environment variables:
+
+    THECITY_APP_ID
+    THECITY_APP_SECRET
+    THECITY_ACCESS_TOKEN
+    THECITY_SUBDOMAIN
+
+After configuration, requests can be made like so:
+
+```ruby
+client.current_user
+```
+
+or
+
+```ruby
+client.my_groups
+```
+
+## Usage Examples
+All examples require an authenticated TheCity client with a valid access_token. See the section on <a
+href="#configuration">configuration</a>.
+
+**Get the authenticated user (current user)**
+
+```ruby
+client.me
+```
+**Post a topic**
+
+```ruby
+client.post_topic(:group_id => 1234567, :title => 'Mr. Watson, come here', :body => 'I want to see you.')
+```
+**Fetch the groups the current user belongs to**
+
+```ruby
+client.my_groups
+```
+**Retrieve the list of permissions associated with the current user**
+
+```ruby
+client.followers("gem")
+client.followers(213747670)
+client.followers
+```
+**Fetch a cursored list of friends with profile details (by screen name or user ID, or by implict authenticated user)**
+
+```ruby
+client.friends("gem")
+client.friends(213747670)
+client.friends
+```
+For more usage examples, please see the full [documentation][].
+
+## Documentation
+[http://rdoc.info/gems/thecity][documentation]
+
+[documentation]: http://rdoc.info/gems/thecity
+
+## Announcements
+You should [follow @thecity][follow] [and @thecity_status][follow_status] on Twitter for announcements and updates about
+this library.
+
+[follow]: https://twitter.com/thecity
+[follow_status]: https://twitter.com/thecity_status
+
+## The City Builder API Developer Group
+For more in depth discussiong regarding The City app platform and APIs, please join [the 'API' group on Builders][builders group].
+
+[builders group]: https://builders.onthecity.org/groups/api
+
+## Apps Wiki
+Does your church or organization use this gem? Add it to the [apps
+wiki][apps]!
+
+[apps]: https://github.com/robertleib/thecity/wiki/apps
+
+## Advanced Configuration
+
+### Middleware
+The Faraday middleware stack is fully configurable and is exposed as a
+`Faraday::Builder` object. You can modify the default middleware in-place:
+
+```ruby
+client.middleware.insert_after TheCity::Response::RaiseError, CustomMiddleware
+```
+
+A custom adapter may be set as part of a custom middleware stack:
+
+```ruby
+client.middleware = Faraday::Builder.new(
+  &Proc.new do |builder|
+    # Specify a middleware stack here
+    builder.adapter :some_other_adapter
+  end
+)
+```
+
+## Contributing to thecity gem
+
+### Submitting an Issue
+We use the [GitHub issue tracker][issues] to track bugs and features. Before
+submitting a bug report or feature request, check to make sure it hasn't
+already been submitted. When submitting a bug report, please include a [Gist][]
+that includes a stack trace and any details that may be necessary to reproduce
+the bug, including your gem version, Ruby version, and operating system.
+Ideally, a bug report should include a pull request with failing specs.
+
+[issues]: https://github.com/robertleib/thecity/issues
+[gist]: https://gist.github.com/
+
+### Submitting a Pull Request
+1. [Fork the repository.][fork]
+2. [Create a topic branch.][branch]
+3. Preferably, add specs for your unimplemented feature or bug fix.
+4. Run `bundle exec rake spec`. If your specs pass, return to step 3.
+5. Implement your feature or bug fix.
+6. Run `bundle exec rake spec`. If your specs fail, return to step 5.
+7. Add documentation for your feature or bug fix.
+8. Run `bundle exec rake yard`.
+9. Commit and push your changes.
+10. [Submit a pull request.][pr]
+
+[fork]: http://help.github.com/fork-a-repo/
+[branch]: http://learn.github.com/p/branching.html
+[pr]: http://help.github.com/send-pull-requests/
+
+## Copyright
+Copyright (c) 2013 Robert Leib.
+See [LICENSE][] for details.
+
+[license]: LICENSE.md

data/Rakefile

@@ -0,0 +1,11 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :test => :spec
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/lib/the_city/account.rb

@@ -0,0 +1,32 @@
+module TheCity
+  # The City church account
+  #
+  # @!attribute [r] name
+  #   @return [String] The name of the church, 'Grace Church'.
+  # @!attribute [r] subdomain
+  #   @return [String] The subdomain used to access this account, subdomain.onthecity.org
+  # @!attribute [r] id
+  #   @return [Integer] The id associated with the church account
+
+  class Account < TheCity::Base
+    attr_reader :name, :id, :subdomain
+    object_attr_reader :Terminology, :terminology
+
+    def initialize(attrs={}, options={})
+      super(attrs,options)
+      @campuses = Array(attrs.delete(:campuses)).map {|g| TheCity::Group.new(g,options)}
+    end
+
+    # Return campuses that belong to a multisite church
+    #
+    # @return [Array<TheCity::Group>]
+    def campuses
+      @campuses
+    end
+
+    def label_for(thecity_primitive)
+      terminology.send(thecity_primitive.downcase.to_sym)
+    end
+
+  end
+end

data/lib/the_city/api/accounts.rb

@@ -0,0 +1,34 @@
+require 'the_city/arguments'
+require 'the_city/api/utils'
+require 'the_city/account'
+
+module TheCity
+  module API
+    module Accounts
+      include TheCity::API::Utils
+      
+      # Returns the current City account associated with the current user
+      #
+      # @req_scope none
+      # @return [TheCity::Account]
+      # @param options [Hash] A customizable set of options.
+      def church_account(options={})
+        @church_account = nil if options.delete(:force_download)
+        @church_account ||= object_from_response(TheCity::Account, :get, "/church_account", options)
+      end
+      alias current_account church_account
+      alias current_church church_account
+
+      # Returns an array of all the City accounts associated with the current user
+      #
+      # @req_scope none
+      # @return [Array<TheCity::Account>] 
+      # @param options [Hash] A customizable set of options.
+      def my_accounts(options={})
+        @my_accounts = nil if options.delete(:force_download)
+        @my_accounts ||= objects_from_response(TheCity::Account, :get, "/me/accounts", options)
+      end
+
+    end
+  end
+end

data/lib/the_city/api/client.rb

@@ -0,0 +1,136 @@
+require 'base64'
+require 'faraday'
+require 'faraday/request/multipart'
+require 'json'
+require 'the_city/client'
+require 'the_city/error'
+require 'the_city/error/configuration_error'
+require 'the_city/api/request/multipart_with_file'
+require 'the_city/api/response/parse_json'
+require 'the_city/api/response/raise_error'
+
+#require 'the_city/api/oauth'
+require 'the_city/api/users'
+require 'the_city/api/accounts'
+require 'the_city/api/groups'
+require 'the_city/api/topics'
+require 'the_city/api/events'
+require 'the_city/api/prayers'
+require 'the_city/api/needs'
+
+module TheCity
+  module API
+    # Wrapper for the TheCity REST API
+    #
+    # @see http://api.onthecity.com/docs
+    class Client < TheCity::Client
+      #include TheCity::API::OAuth
+      include TheCity::API::Users
+      include TheCity::API::Accounts
+      include TheCity::API::Groups
+      include TheCity::API::Topics
+      include TheCity::API::Events
+      include TheCity::API::Prayers
+      include TheCity::API::Needs
+
+      attr_writer :bearer_token, :connection_options, :middleware
+
+      ENDPOINT = ENV['THECITY_API_ENDPOINT'] || 'https://api.onthecity.org'
+
+      def connection_options
+        {
+          :builder => middleware,
+          :headers => {
+            :accept => "application/vnd.thecity.v#{version}+json",
+            'X-THECITY-SUBDOMAIN' => subdomain,
+            'X-THECITY-ACCESS-TOKEN' => access_token,
+          },
+          :request => {
+            :open_timeout => 5,
+            :timeout => 60,
+          },
+        }
+      end
+
+      # @note Faraday's middleware stack implementation is comparable to that of Rack middleware.  The order of middleware is important: the first middleware on the list wraps all others, while the last middleware is the innermost one.
+      # @see https://github.com/technoweenie/faraday#advanced-middleware-usage
+      # @see http://mislav.uniqpath.com/2011/07/faraday-advanced-http/
+      # @return [Faraday::Builder]
+      def middleware
+        @middleware ||= Faraday::Builder.new do |builder|
+          # Convert file uploads to Faraday::UploadIO objects
+          builder.use TheCity::API::Request::MultipartWithFile
+          # Checks for files in the payload
+          builder.use Faraday::Request::Multipart
+          # Convert request params to "www-form-urlencoded"
+          builder.use Faraday::Request::UrlEncoded
+          # Handle error responses
+          builder.use TheCity::API::Response::RaiseError
+          # Parse JSON response bodies
+          builder.use TheCity::API::Response::ParseJson
+          # Set Faraday's HTTP adapter
+          builder.adapter Faraday.default_adapter
+        end
+      end
+
+      # Perform an HTTP DELETE request
+      def delete(path, params={})
+        request(:delete, path, params)
+      end
+
+      # Perform an HTTP GET request
+      def get(path, params={})
+        request(:get, path, params)
+      end
+
+      # Perform an HTTP POST request
+      def post(path, params={})
+        signature_params = params.values.any?{|value| value.respond_to?(:to_io)} ? {} : params
+        request(:post, path, params, signature_params)
+      end
+
+      # Perform an HTTP PUT request
+      def put(path, params={})
+        request(:put, path, params)
+      end
+
+
+    private
+
+      # Returns a proc that can be used to setup the Faraday::Request headers
+      #
+      # @param method [Symbol]
+      # @param path [String]
+      # @param params [Hash]
+      # @return [Proc]
+      def request_setup(method, path, params, signature_params)
+        Proc.new do |request|
+          request.headers[:authorization] = bearer_auth_header
+        end
+      end
+
+      def request(method, path, params={}, signature_params=params)
+        validate_credentials!
+        request_setup = request_setup(method, path, params, signature_params)
+        connection.send(method.to_sym, path, params, &request_setup).env
+      rescue Faraday::Error::ClientError, JSON::ParserError
+        raise TheCity::Error
+      end
+
+      # Returns a Faraday::Connection object
+      #
+      # @return [Faraday::Connection]
+      def connection
+        @connection ||= Faraday.new(ENDPOINT, connection_options)
+      end
+
+      # Generates authentication header for api request
+      #
+      # @return [String]
+      def bearer_auth_header
+        "Bearer #{access_token}"
+      end
+
+    end
+  end
+end

data/lib/the_city/api/events.rb

@@ -0,0 +1,55 @@
+require 'the_city/arguments'
+require 'the_city/api/utils'
+require 'the_city/event'
+
+module TheCity
+  module API
+    module Events
+      include TheCity::API::Utils
+  
+      # Posts an Event to The City
+      #
+      # @see https://api.onthecity.org/docs
+      #
+      # @req_scope group_content
+      # @return [TheCity::Event]
+      # @param options [Hash] A customizable set of options.
+      # @option options [Integer] :group_id The id of the group you will be posting to.
+      # @option options [String] :title The title of the event.
+      # @option options [String] :body The body text of the event.
+      # @option options [Time] :starting_at The body text of the event.
+      # @option options [Time] :ending_at The body text of the event.
+      def post_event(options)
+        raise(Error::ArgumentError, "Must supply a options[:group_id] for the events's originating group") unless options[:group_id]
+        raise(Error::ArgumentError, "Title (options[:title]) required") unless options[:title]
+        raise(Error::ArgumentError, "Body (options[:body]) required") unless options[:body]
+        raise(Error::ArgumentError, "Starting At (options[:starting_at]) required") unless options[:starting_at]
+        raise(Error::ArgumentError, "Ending At (options[:ending_at]) required") unless options[:ending_at]
+        gid = options[:group_id] || 0
+        object_from_response(TheCity::Event, :post, "/groups/#{gid}/events/", options, {:client => self})
+      end
+
+      # Returns an Event by id
+      #
+      # @see https://api.onthecity.org/docs
+      #
+      # @req_scope group_content
+      # @return [TheCity::Event]
+      # @raise [TheCity::Error::NotFound] Error raised when the event cannot be found.
+      # @overload event(id)
+      #   @param id [Integer] The id of the event.
+      # @overload event(id, options={})
+      #   @param id [Integer] The id of the event.
+      #   @param options [Hash] A customizable set of options.
+      #   @option options [Boolean] :force_download Forces the request to hit the server and flush the cached response
+      def event(*args)
+        @events ||= {}
+        arguments = TheCity::Arguments.new(args)
+        eid = args.shift
+        @events[eid] = nil if arguments.options.delete(:force_download)
+        @events[eid] ||= object_from_response(TheCity::Event, :get, "/events/#{eid}", arguments.options, {:client => self})
+      end
+
+    end
+  end
+end

data/lib/the_city/api/groups.rb

@@ -0,0 +1,41 @@
+require 'the_city/arguments'
+require 'the_city/api/utils'
+
+module TheCity
+  module API
+    module Groups
+      include TheCity::API::Utils
+  
+      # Returns all the groups that the current user has an active role in
+      #
+      # @req_scope group_contont or user_groups
+      # @param options [Hash] A customizable set of options.
+      # @option options [Boolean] :force_download Forces the request to hit the server and flush the cached response
+      # @return [Array<TheCity::Group>]
+      def my_groups(options={})
+        @my_groups = nil if options.delete(:force_download)
+        @my_groups ||= objects_from_response(TheCity::Group, :get, "/me/groups", options)
+      end
+
+      # Returns a group by id
+      #
+      # @req_scope group_trusted
+      # @return [TheCity::Group]
+      # @raise [TheCity::Error::NotFound] Error raised when the group cannot be found.
+      # @overload group(id)
+      #   @param id [Integer] The id of the group.
+      # @overload group(id, options={})
+      #   @param id [Integer] The id of the group.
+      #   @param options [Hash] A customizable set of options.
+      #   @option options [Boolean] :force_download Forces the request to hit the server and flush the cached response
+      def group(*args)
+        @groups ||= {}
+        arguments = TheCity::Arguments.new(args)
+        gid = args.shift
+        @groups[tid] = nil if arguments.options.delete(:force_download)
+        @groups[tid] ||= object_from_response(TheCity::Group, :get, "/groups/#{gid}", arguments.options)
+      end
+
+    end
+  end
+end

data/lib/the_city/api/needs.rb

@@ -0,0 +1,51 @@
+require 'the_city/arguments'
+require 'the_city/api/utils'
+require 'the_city/need'
+
+module TheCity
+  module API
+    module needs
+      include TheCity::API::Utils
+  
+      # Posts a need to The City
+      #
+      # @see https://api.onthecity.org/docs
+      #
+      # @req_scope group_content
+      # @return [TheCity::Need]
+      # @param options [Hash] A customizable set of options.
+      # @option options [Integer] :group_id The id of the group you will be posting to.
+      # @option options [String] :title The title of the need.
+      # @option options [String] :body The body text of the need.
+      def post_need(options)
+        raise(Error::ArgumentError, "Must supply a options[:group_id] for the needs's originating group") unless options[:group_id]
+        raise(Error::ArgumentError, "Title (options[:title]) required") unless options[:title]
+        raise(Error::ArgumentError, "Body (options[:body]) required") unless options[:body]
+        gid = options[:group_id] || 0
+        object_from_response(TheCity::Need, :post, "/groups/#{gid}/needs/", options, {:client => self})
+      end
+
+      # Returns a need by id
+      #
+      # @see https://api.onthecity.org/docs
+      #
+      # @req_scope group_content
+      # @return [TheCity::Need]
+      # @raise [TheCity::Error::NotFound] Error raised when the need cannot be found.
+      # @overload need(id)
+      #   @param id [Integer] The id of the need.
+      # @overload need(id, options={})
+      #   @param id [Integer] The id of the need.
+      #   @param options [Hash] A customizable set of options.
+      #   @option options [Boolean] :force_download Forces the request to hit the server and flush the cached response
+      def need(*args)
+        @needs ||= {}
+        arguments = TheCity::Arguments.new(args)
+        nid = args.shift
+        @needs[nid] = nil if arguments.options.delete(:force_download)
+        @needs[nid] ||= object_from_response(TheCity::Need, :get, "/needs/#{nid}", arguments.options, {:client => self})
+      end
+
+    end
+  end
+end

data/lib/the_city/api/oauth.rb

@@ -0,0 +1,50 @@
+require 'the_city/api/utils'
+require 'the_city/token'
+
+module TheCity
+  module API
+    module OAuth
+      include TheCity::API::Utils
+
+      def authentication_url
+        "https://authentication.onthecity.org/oauth/authorize?#{authentication_headers}"
+      end
+
+      def authentication_headers
+
+      end
+
+      def authentication_params
+        "scope=user_basic&app_id="
+      end
+
+      def authorization_url(code)
+      end
+
+      # Allows a registered application to obtain an OAuth 2 Bearear Token, which can be used to make API requests
+      # on an application's own behalf, without a user context.
+      #
+      # Only one bearer token may exist outstanding for an application, and repeated requests to this method
+      # will yield the same already-existent token until it has been invalidated.
+      #
+      # @return [TheCity::Token] The Bearer Token. token_type should be 'bearer'.
+      # @example Generate a Bearer Token
+      #   client = TheCity::API::Client.new(:consumer_key => "abc", :consumer_secret => 'def')
+      #   bearer_token = client.token
+      def token
+        object_from_response(TheCity::Token, :post, "/oauth2/token", :grant_type => "client_credentials", :bearer_token_request => true)
+      end
+      alias bearer_token token
+
+      # Allows a registered application to revoke an issued OAuth 2 Bearer Token by presenting its client credentials.
+      #
+      # @param access_token [String, TheCity::Token] The bearer token to revoke.
+      # @return [TheCity::Token] The invalidated token. token_type should be nil.
+      def invalidate_token(access_token)
+        access_token = access_token.access_token if access_token.is_a?(TheCity::Token)
+        object_from_response(TheCity::Token, :post, "/oauth2/invalidate_token", :access_token => access_token)
+      end
+
+    end
+  end
+end