cronofy 0.0.5 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1be096b17b4eb2b3422337a2d168b7f27559493c
-  data.tar.gz: e696a6175e17d0465912d7810342cfd1352b7191
+  metadata.gz: bfa7415b5d284a6c099d6c2247430cb63a4e6241
+  data.tar.gz: 83c8cfe7ed6decaef9e78fce9c2eab83560434a1
 SHA512:
-  metadata.gz: 5ea577cd0076d2aa66cdf8c7ecd6791aa1d80ef216a51535d51a46b351b586ef7fcb4456ce8cb4be78c010f8bcf82f6b12239f82d2948131324c6ae746696f9b
-  data.tar.gz: 0071814777c83e679d6b704595b756c6aa709c4540430fff18a2b29caefcbbeca8309390931259fd9b5c5159fb1e82c34920e2f9c65aebe11ee6490919223d74
+  metadata.gz: 9d86d15864c20933b9ed7e992e020d104163cbff810b8aded419eff2b4cc6f81b266af138b272dec5baa043d8dc5cefc976d4e04d11c94893bf450a104419b53
+  data.tar.gz: ae77c0ca26eec4bb3838ae014746f6ad90a0e018f07f4a8a6d349e818befa682d59556045e571195af21f469308a8b64d8cbcef704d057dcaa15ad36d30e069c

data/README.md

@@ -4,7 +4,7 @@
 [![Gem Version](https://badge.fury.io/rb/cronofy.svg)](http://badge.fury.io/rb/cronofy)
 [![Join the chat at https://gitter.im/cronofy/cronofy-ruby](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/cronofy/cronofy-ruby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-[Cronofy](http://www.cronofy.com) - one API for all the calendars (Google, Outlook, iCloud, Exchange). This gem is an interface for easy use of [Cronofy API](http://www.cronofy.com/developers/api) with Ruby.
+[Cronofy](http://www.cronofy.com) - one API for all the calendars (Google, Outlook, iCloud, Exchange).
 
 ## Installation
 
@@ -24,69 +24,97 @@ Or install it yourself as:
 
 ## Usage
 
-You have to register on cronofy website and create an application there. You will get a client id and client secret which you will have to pass to initializer. You can also pass a token and refresh token that you will get later, or leave it blank in case if you don't have it now:
+You have to register on the Cronofy website and create an application there. You will then get a client id and client secret.
+
+You can either set them as the enviroment variables `CRONOFY_CLIENT_ID` and `CRONOFY_CLIENT_SECRET` and have them picked up automatically when creating a new `Cronofy::Client`:
+
 ```ruby
-cronofy = Cronofy::Client.new('CLIENT_ID', 'CLIENT_SECRET', 'TOKEN', 'REFRESH_TOKEN')
+cronofy = Cronofy::Client.new
 ```
 
-Generate a link for a user to grant access for his calendars:
+Or you can specify them explicitly:
+
+```ruby
+cronofy = Cronofy::Client.new(client_id: 'CLIENT_ID', client_secret: 'CLIENT_SECRET')
+```
+
+You can also pass an existing access token and refresh token if you already have a pair for the user:
+
+```ruby
+cronofy = Cronofy::Client.new(access_token: 'ACCESS_TOKEN', refresh_token: 'REFRESH_TOKEN')
+```
+
+### Authorization
+
+Generate a link for a user to grant access for their calendars:
+
 ```ruby
 cronofy.user_auth_link('http://localhost:3000/oauth2/callback')
 ```
 
-The specified url is a page on your website that will handle callback and get a code parameter out of it. On a callback you will have a param[:code] that you will need in order to get a token:
+The returned URL is a page on your website that will handle the OAuth 2.0 callback and receive a code parameter. You can then use that code to retrieve an OAuth token granting access to the user's Cronofy account:
+
 ```ruby
 token = cronofy.get_token_from_code(code, 'http://localhost:3000/oauth2/callback')
 ```
-You can now save a token to pass it later to initializer.
+
+You should save the `access_token` and `refresh_token` for later use.
+
+### List calendars
 
 Get a list of all the user calendars:
+
 ```ruby
 cronofy.list_calendars
 ```
 
-You will get a list of user's calendars in a json format. The example of such a response:
+You will get a list of the user's calendars with each entry being a wrapped
+version of the following JSON structure:
+
 ```json
 {
-   "calendars":[
-      {
-         "provider_name":"google",
-         "profile_name":"YYYYYYYY@gmail.com",
-         "calendar_id":"cal_YYYYYYYY-UNIQUE_CAL_ID_HERE-YYYYYYYY",
-         "calendar_name":"Office Calendar",
-         "calendar_readonly":false,
-         "calendar_deleted":false
-      },
-      {
-         "provider_name":"google",
-         "profile_name":"XXXXXXX@gmail.com",
-         "calendar_id":"cal_XXXXXXXX-UNIQUE_CAL_ID_HERE-XXXXXXXXX",
-         "calendar_name":"Home Calendar",
-         "calendar_readonly":false,
-         "calendar_deleted":false
-      }
-   ]
+   "provider_name": "google",
+   "profile_name": "YYYYYYYY@gmail.com",
+   "calendar_id": "cal_YYYYYYYY-UNIQUE_CAL_ID_HERE-YYYYYYYY",
+   "calendar_name": "Office Calendar",
+   "calendar_readonly": false,
+   "calendar_deleted": false
 }
 ```
 
-To create/update an event in user's calendar:
+The properties can be accessed like so:
+
+```ruby
+calendar = cronofy.list_calendars.first
+calendar.calendar_id
+# => "cal_YYYYYYYY-UNIQUE_CAL_ID_HERE-YYYYYYYY"
+```
+
+### Create or update events
+
+To create/update an event in the user's calendar:
+
 ```ruby
 event_data = {
-  event_id: 'uniq-id', # uniq id of event
+  event_id: 'uniq-id',
   summary: 'Event summary',
   description: 'Event description',
-  start: Time.now + 60 * 60 * 24, # will be converted to .utc.iso8601 internally,
-  end: Time.now + 60 * 60 * 25, # the same convertion here
+  start: Time.now + 60 * 60 * 24,
+  end: Time.now + 60 * 60 * 25,
   location: {
     description: "Meeting room"
   }
 }
-cronofy.upsert(calendar_id, event_data)
+
+cronofy.upsert_event(calendar_id, event_data)
 ```
 
+### Delete events
+
 To delete an event from user's calendar:
+
 ```ruby
-cronofy.delete_event(calendar_id, event_id)
+cronofy.delete_event(calendar_id, 'uniq-id')
 ```
 
 ## Links

data/cronofy.gemspec

@@ -1,24 +1,27 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'cronofy/version'
+require File.expand_path('../lib/cronofy/version', __FILE__)
 
 Gem::Specification.new do |spec|
   spec.name          = "cronofy"
   spec.version       = Cronofy::VERSION
-  spec.authors       = ["Sergii Paryzhskyi"]
-  spec.email         = ["parizhskiy@gmail.com"]
+  spec.authors       = ["Sergii Paryzhskyi", "Garry Shutler"]
+  spec.email         = ["parizhskiy@gmail.com", "garry@cronofy.com"]
   spec.summary       = %q{Cronofy - one API for all the calendars}
+  spec.description   = %q{Ruby wrapper for Cronofy's unified calendar API}
   spec.homepage      = "https://github.com/cronofy/cronofy-ruby"
   spec.license       = "MIT"
 
-  spec.files         = `git ls-files -z`.split("\x0")
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.7"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.2"
+  spec.files         = %w{Gemfile LICENSE.txt README.md Rakefile cronofy.gemspec}
+  spec.files        += Dir['lib/**/*.rb']
+  spec.files        += Dir['spec/**/*.rb']
+  spec.test_files    = Dir['spec/**/*.rb']
+
   spec.add_runtime_dependency "oauth2", "~> 1.0"
+  spec.add_runtime_dependency "hashie", "~> 3.0"
+
+  spec.add_development_dependency "bundler", "~>  1.6"
+  spec.add_development_dependency "rake",    "~> 10.0"
+  spec.add_development_dependency "rspec",   "~>  3.2"
+  spec.add_development_dependency "webmock", "~>  1.21"
 end

data/lib/cronofy.rb

@@ -1,12 +1,12 @@
 require "cronofy/version"
 require "cronofy/errors"
+require "cronofy/types"
 require "cronofy/auth"
 require "cronofy/client"
 require "cronofy/response_parser"
 require 'json'
 
 module Cronofy
-
   def self.api_url
     @api_url ||= (ENV['CRONOFY_API_URL'] || "https://api.cronofy.com")
   end
@@ -22,5 +22,4 @@ module Cronofy
   def self.app_url=(value)
     @app_url = value
   end
-
 end

data/lib/cronofy/auth.rb

@@ -1,36 +1,13 @@
 require "oauth2"
 
 module Cronofy
+  # Internal: Class for dealing with authentication and authorization issues.
   class Auth
-    class Credentials
-
-      attr_reader :access_token,
-                  :expires_at,
-                  :expires_in,
-                  :refresh_token
-
-      def initialize(oauth_token)
-        @access_token = oauth_token.token
-        @expires_at = oauth_token.expires_at
-        @expires_in = oauth_token.expires_in
-        @refresh_token = oauth_token.refresh_token
-      end
-
-      def to_hash
-        {
-          access_token: access_token,
-          refresh_token: refresh_token,
-          expires_in: expires_in,
-          expires_at: expires_at
-        }
-      end
-    end
-
     attr_reader :access_token
 
-    def initialize(client_id, client_secret, token=nil, refresh_token=nil)
-      @auth_client = OAuth2::Client.new(client_id, client_secret, site: ::Cronofy.app_url)
-      @api_client = OAuth2::Client.new(client_id, client_secret, site: ::Cronofy.api_url)
+    def initialize(client_id, client_secret, token = nil, refresh_token = nil)
+      @auth_client = OAuth2::Client.new(client_id, client_secret, site: ::Cronofy.app_url, connection_opts: { headers: { "User-Agent" => "Cronofy Ruby #{::Cronofy::VERSION}" } })
+      @api_client = OAuth2::Client.new(client_id, client_secret, site: ::Cronofy.api_url, connection_opts: { headers: { "User-Agent" => "Cronofy Ruby #{::Cronofy::VERSION}" } })
 
       set_access_token(token, refresh_token) if token
     end
@@ -39,28 +16,28 @@ module Cronofy
     #
     # redirect_uri    String, the URI to return to after authorization
     # scope           Array of String, the scope requested
-    #                 Default: [read_account, list_calendars, read_events, create_event, delete_event]
-    #                 see: http://www.cronofy.com/developers/api#authorization
     #
-    # Returns String URL
-    def user_auth_link(redirect_uri, scope=nil)
-      scope ||= %w{read_account list_calendars read_events create_event delete_event}
-
-      @auth_client.auth_code.authorize_url(:redirect_uri => redirect_uri, :response_type => 'code', :scope => scope.join(' '))
+    # See http://www.cronofy.com/developers/api#authorization for reference.
+    #
+    # Returns the URL as a String.
+    def user_auth_link(redirect_uri, scope)
+      @auth_client.auth_code.authorize_url(redirect_uri: redirect_uri, response_type: 'code', scope: scope.join(' '))
     end
 
     def get_token_from_code(code, redirect_uri)
-      auth_token = @auth_client.auth_code.get_token(code, :redirect_uri => redirect_uri)
-      set_access_token_from_auth_token(auth_token)
-      Credentials.new(@access_token)
+      do_request do
+        @access_token = @auth_client.auth_code.get_token(code, redirect_uri: redirect_uri)
+        Credentials.new(@access_token)
+      end
     end
 
     # Public: Refreshes the access token
     # Returns Hash of token elements to allow client to update in local store for user
     def refresh!
-      auth_token = access_token.refresh!
-      set_access_token_from_auth_token(auth_token)
-      Credentials.new(@access_token)
+      do_request do
+        @access_token = access_token.refresh!
+        Credentials.new(@access_token)
+      end
     end
 
     def set_access_token_from_auth_token(auth_token)
@@ -68,8 +45,15 @@ module Cronofy
     end
 
     def set_access_token(token, refresh_token)
-      @access_token = OAuth2::AccessToken.new(@api_client, token, { refresh_token: refresh_token })
+      @access_token = OAuth2::AccessToken.new(@api_client, token, refresh_token: refresh_token)
     end
 
+    private
+
+    def do_request(&block)
+      block.call
+    rescue OAuth2::Error => e
+      raise Errors.map_error(e)
+    end
   end
-end
+end

data/lib/cronofy/client.rb

@@ -1,119 +1,439 @@
 module Cronofy
-
+  # Public: Primary class for interacting with the Cronofy API.
   class Client
+    # Public: The scope to request if none is explicitly specified by the
+    # caller.
+    DEFAULT_OAUTH_SCOPE = %w{
+      read_account
+      list_calendars
+      read_events
+      create_event
+      delete_event
+    }.freeze
 
-    def initialize(client_id, client_secret, token=nil, refresh_token=nil)
-      @auth = Auth.new(client_id, client_secret, token, refresh_token)
-    end
+    # Public: Initialize a new Cronofy::Client.
+    #
+    # options - A Hash of options used to initialize the client (default: {}):
+    #           :access_token  - An existing access token String for the user's
+    #                            account (optional).
+    #           :client_id     - The client ID String of your Cronofy OAuth
+    #                            application (default:
+    #                            ENV["CRONOFY_CLIENT_ID"]).
+    #           :client_secret - The client secret String of your Cronofy OAuth
+    #                            application (default:
+    #                            ENV["CRONOFY_CLIENT_SECRET"]).
+    #           :refresh_token - An existing refresh token String for the user's
+    #                            account (optional).
+    def initialize(options = {})
+      access_token  = options[:access_token]
+      client_id     = options.fetch(:client_id, ENV["CRONOFY_CLIENT_ID"])
+      client_secret = options.fetch(:client_secret, ENV["CRONOFY_CLIENT_SECRET"])
+      refresh_token = options[:refresh_token]
 
-    def access_token!
-      raise CredentialsMissingError.new unless @auth.access_token
-      @auth.access_token
+      @auth = Auth.new(client_id, client_secret, access_token, refresh_token)
     end
 
-    # Public : Lists the calendars or the user across all of the calendar accounts
-    #          see http://www.cronofy.com/developers/api#calendars
+    # Public: Lists all the calendars for the account.
     #
-    # Returns Hash of calendars
+    # See http://www.cronofy.com/developers/api#calendars for reference.
+    #
+    # Returns an Array of Calendars
+    #
+    # Raises Cronofy::CredentialsMissingError if no credentials available.
+    # Raises Cronofy::AuthenticationFailureError if the access token is no
+    # longer valid.
+    # Raises Cronofy::AuthorizationFailureError if the access token does not
+    # include the required scope.
+    # Raises Cronofy::TooManyRequestsError if the request exceeds the rate
+    # limits for the application.
     def list_calendars
-      response = do_request { access_token!.get("/v1/calendars")  }
-      ResponseParser.new(response).parse_json
+      response = get("/v1/calendars")
+      parse_collection(Calendar, "calendars", response)
     end
 
-    # Public : Creates or updates an existing event that matches the event_id, in the calendar
-    #          see: http://www.cronofy.com/developers/api#upsert-event
-    #          aliased as upsert_event
+    # Public: Creates or updates an event for the event_id in the calendar
+    # relating to the given calendar_id.
+    #
+    # calendar_id - The String Cronofy ID for the calendar to upsert the event
+    #               to.
+    # event       - A Hash describing the event with symbolized keys:
+    #               :event_id    - A String uniquely identifying the event for
+    #                              your application (note: this is NOT an ID
+    #                              generated by Cronofy).
+    #               :summary     - A String to use as the summary, sometimes
+    #                              referred to as the name or title, of the
+    #                              event.
+    #               :description - A String to use as the description, sometimes
+    #                              referred to as the notes or body, of the
+    #                              event.
+    #               :start       - The Time the event starts.
+    #               :end         - The Time the event ends.
+    #               :location    - A Hash describing the location of the event
+    #                              with symbolized keys (optional):
+    #                              :description - A String describing the
+    #                                             location.
+    #
+    # Examples
+    #
+    #   client.upsert_event(
+    #     "cal_n23kjnwrw2_jsdfjksn234",
+    #     event_id: "qTtZdczOccgaPncGJaCiLg",
+    #     summary: "Board meeting",
+    #     description: "Discuss plans for the next quarter.",
+    #     start: Time.utc(2014, 8, 5, 15, 30),
+    #     end:   Time.utc(2014, 8, 5, 17, 30),
+    #     location: {
+    #       description: "Board room"
+    #     })
+    #
+    # See http://www.cronofy.com/developers/api#upsert-event for reference.
     #
-    # calendar_id   - String Cronofy ID for the the calendar to contain the event
-    # event         - Hash describing the event with symbolized keys.
-    #                 :event_id String client identifier for event NOT Cronofy's
-    #                 :summary String
-    #                 :start Time
-    #                 :end Time
+    # Returns nothing.
     #
-    # Returns nothing
-    def create_or_update_event(calendar_id, event)
+    # Raises Cronofy::CredentialsMissingError if no credentials available.
+    # Raises Cronofy::AuthenticationFailureError if the access token is no
+    # longer valid.
+    # Raises Cronofy::AuthorizationFailureError if the access token does not
+    # include the required scope.
+    # Raises Cronofy::NotFoundError if the calendar does not exist.
+    # Raises Cronofy::InvalidRequestError if the request contains invalid
+    # parameters.
+    # Raises Cronofy::TooManyRequestsError if the request exceeds the rate
+    # limits for the application.
+    def upsert_event(calendar_id, event)
       body = event.dup
-      body[:start] = event[:start].utc.iso8601
-      body[:end] = event[:end].utc.iso8601
 
-      headers = {
-        'Content-Type' => 'application/json'
-      }
+      body[:start] = to_iso8601(body[:start])
+      body[:end] = to_iso8601(body[:end])
 
-      do_request { access_token!.post("/v1/calendars/#{calendar_id}/events", { body: JSON.generate(body), headers: headers }) }
+      post("/v1/calendars/#{calendar_id}/events", body)
+      nil
     end
-    alias_method :upsert_event, :create_or_update_event
 
-    # Public : Deletes an event from the specified calendar
-    #          see http://www.cronofy.com/developers/api#delete-event
+    # Public: Alias for #upsert_event
+    alias_method :create_or_update_event, :upsert_event
+
+    # Public: Returns a lazily-evaluated Enumerable of Events that satisfy the
+    # given query criteria.
+    #
+    # options - The Hash options used to refine the selection (default: {}):
+    #           :from            - The minimum Date from which to return events
+    #                              (optional).
+    #           :to              - The Date to return events up until (optional).
+    #           :tzid            - A String representing a known time zone
+    #                              identifier from the IANA Time Zone Database
+    #                              (default: Etc/UTC).
+    #           :include_deleted - A Boolean specifying whether events that have
+    #                              been deleted should included or excluded from
+    #                              the results (optional).
+    #           :include_moved   - A Boolean specifying whether events that have
+    #                              ever existed within the given window should
+    #                              be included or excluded from the results
+    #                              (optional).
+    #           :last_modified   - The Time that events must be modified on or
+    #                              after in order to be returned (optional).
+    #
+    # See http://www.cronofy.com/developers/api#read-events for reference.
+    #
+    # Returns a lazily-evaluated Enumerable of Events
+    #
+    # Raises Cronofy::CredentialsMissingError if no credentials available.
+    # Raises Cronofy::AuthenticationFailureError if the access token is no
+    # longer valid.
+    # Raises Cronofy::AuthorizationFailureError if the access token does not
+    # include the required scope.
+    # Raises Cronofy::InvalidRequestError if the request contains invalid
+    # parameters.
+    # Raises Cronofy::TooManyRequestsError if the request exceeds the rate
+    # limits for the application.
+    def read_events(options = {})
+      params = READ_EVENTS_DEFAULT_PARAMS.merge(options)
+
+      READ_EVENTS_TIME_PARAMS.select { |tp| params.key?(tp) }.each do |tp|
+        params[tp] = to_iso8601(params[tp])
+      end
+
+      url = ::Cronofy.api_url + "/v1/events"
+      ReadEventsIterator.new(access_token!, url, params)
+    end
+
+    # Public: Deletes an event from the specified calendar
+    #
+    # calendar_id - The String Cronofy ID for the calendar to delete the event
+    #               from.
+    # event_id    - A String uniquely identifying the event for your application
+    #               (note: this is NOT an ID generated by Cronofy).
     #
-    # calendar_id   - String Cronofy ID for the calendar containing the event
-    # event_id      - String client ID for the event
+    # See http://www.cronofy.com/developers/api#delete-event for reference.
     #
-    # Returns nothing
+    # Returns nothing.
+    #
+    # Raises Cronofy::CredentialsMissingError if no credentials available.
+    # Raises Cronofy::AuthenticationFailureError if the access token is no
+    # longer valid.
+    # Raises Cronofy::AuthorizationFailureError if the access token does not
+    # include the required scope.
+    # Raises Cronofy::NotFoundError if the calendar does not exist.
+    # Raises Cronofy::InvalidRequestError if the request contains invalid
+    # parameters.
+    # Raises Cronofy::TooManyRequestsError if the request exceeds the rate
+    # limits for the application.
     def delete_event(calendar_id, event_id)
-      params = { event_id: event_id }
+      delete("/v1/calendars/#{calendar_id}/events", event_id: event_id)
+      nil
+    end
 
-      do_request { access_token!.delete("/v1/calendars/#{calendar_id}/events", { params: params }) }
+    # Public: Creates a notification channel with a callback URL
+    #
+    # callback_url - A String specifing the callback URL for the channel.
+    #
+    # See http://www.cronofy.com/developers/api/alpha#create-channel for
+    # reference.
+    #
+    # Returns a Channel.
+    #
+    # Raises Cronofy::CredentialsMissingError if no credentials available.
+    # Raises Cronofy::AuthenticationFailureError if the access token is no
+    # longer valid.
+    # Raises Cronofy::AuthorizationFailureError if the access token does not
+    # include the required scope.
+    # Raises Cronofy::InvalidRequestError if the request contains invalid
+    # parameters.
+    # Raises Cronofy::TooManyRequestsError if the request exceeds the rate
+    # limits for the application.
+    def create_channel(callback_url)
+      response = post("/v1/channels", callback_url: callback_url)
+      parse_json(Channel, "channel", response)
     end
 
-    # Public : Generate the authorization URL to send the user to in order to generate
-    #          and authorization code in order for an access_token to be issued
-    #          see http://www.cronofy.com/developers/api#authorization
+    # Public: Lists all the notification channels for the account.
     #
-    # redirect_uri  - String URI to return the user to once authorization process completed
-    # scope         - Array of scopes describing access required to the users calendars (default: all scopes)
+    # See http://www.cronofy.com/developers/api/alpha#list-channels for
+    # reference.
     #
-    # Returns String
-    def user_auth_link(redirect_uri, scope=nil)
-      @auth.user_auth_link(redirect_uri, scope)
+    # Returns an Array of Channels.
+    #
+    # Raises Cronofy::CredentialsMissingError if no credentials available.
+    # Raises Cronofy::AuthenticationFailureError if the access token is no
+    # longer valid.
+    # Raises Cronofy::AuthorizationFailureError if the access token does not
+    # include the required scope.
+    # Raises Cronofy::TooManyRequestsError if the request exceeds the rate
+    # limits for the application.
+    def list_channels
+      response = get("/v1/channels")
+      parse_collection(Channel, "channels", response)
     end
 
-    # Public : Returns the access_token for a given code and redirect_uri pair
-    #          see http://www.cronofy.com/developers/api#token-issue
+    # Public: Closes a notification channel.
+    #
+    # channel_id - The String Cronofy ID for the channel to close.
     #
-    # code          - String code returned to redirect_uri after authorization
-    # redirect_uri  - String URI returned to
+    # Returns nothing.
     #
-    # Returns Cronofy::Credentials
-    def get_token_from_code(code, redirect_uri)
-      @auth.get_token_from_code(code, redirect_uri)
+    # Raises Cronofy::CredentialsMissingError if no credentials available.
+    # Raises Cronofy::AuthenticationFailureError if the access token is no
+    # longer valid.
+    # Raises Cronofy::AuthorizationFailureError if the access token does not
+    # include the required scope.
+    # Raises Cronofy::NotFoundError if the channel does not exist.
+    # Raises Cronofy::TooManyRequestsError if the request exceeds the rate
+    # limits for the application.
+    def close_channel(channel_id)
+      delete("/v1/channels/#{channel_id}")
+      nil
     end
 
-    # Public : Refreshes the access_token and periodically the refresh_token for authorization
-    #          see http://www.cronofy.com/developers/api#token-refresh
+    # Public: Retrieves the details of the account.
+    #
+    # See http://www.cronofy.com/developers/api#account for reference.
     #
-    # Returns Cronofy::Credentials
+    # Returns an Account.
+    #
+    # Raises Cronofy::CredentialsMissingError if no credentials available.
+    # Raises Cronofy::AuthenticationFailureError if the access token is no
+    # longer valid.
+    # Raises Cronofy::AuthorizationFailureError if the access token does not
+    # include the required scope.
+    # Raises Cronofy::TooManyRequestsError if the request exceeds the rate
+    # limits for the application.
+    def account
+      response = get("/v1/account")
+      parse_json(Account, "account", response)
+    end
+
+    # Public: Generates a URL to send the user to in order to perform the OAuth
+    # 2.0 authorization process.
+    #
+    # redirect_url - A String specifing the URL to return the user to once they
+    #                have completed the authorization steps.
+    # scope        - Array of scopes describing the access to request from the
+    #                user to the users calendars (default:
+    #                DEFAULT_OAUTH_SCOPE).
+    #
+    # See http://www.cronofy.com/developers/api#authorization for reference.
+    #
+    # Returns the URL as a String.
+    def user_auth_link(redirect_url, scope = DEFAULT_OAUTH_SCOPE)
+      @auth.user_auth_link(redirect_url, scope)
+    end
+
+    # Public: Retrieves the OAuth credentials authorized for the given code and
+    # redirect URL pair.
+    #
+    # code         - String code returned to redirect_url after authorization.
+    # redirect_url - A String specifing the URL the user returned to once they
+    #                had completed the authorization steps.
+    #
+    # See http://www.cronofy.com/developers/api#token-issue for reference.
+    #
+    # Returns a set of Cronofy::Credentials for the account.
+    #
+    # Raises Cronofy::BadRequestError if the code is unknown, has been revoked,
+    # or the code and redirect URL do not match.
+    # Raises Cronofy::AuthenticationFailureError if the client ID and secret are
+    # not valid.
+    def get_token_from_code(code, redirect_url)
+      @auth.get_token_from_code(code, redirect_url)
+    end
+
+    # Public: Refreshes the credentials for the account's access token.
+    #
+    # Usually called in response to a Cronofy::AuthenticationFailureError as
+    # these usually occur when the access token has expired and needs
+    # refreshing.
+    #
+    # See http://www.cronofy.com/developers/api#token-refresh for reference.
+    #
+    # Returns a set of Cronofy::Credentials for the account.
+    #
+    # Raises Cronofy::BadRequestError if refresh token code is unknown or has
+    # been revoked.
+    # Raises Cronofy::AuthenticationFailureError if the client ID and secret are
+    # not valid.
     def refresh_access_token
       @auth.refresh!
     end
 
-  private
+    private
+
+    READ_EVENTS_DEFAULT_PARAMS = { tzid: "Etc/UTC" }.freeze
+
+    READ_EVENTS_TIME_PARAMS = %i{
+      from
+      to
+      last_modified
+    }.freeze
 
-    ERROR_MAP = {
-      401 => ::Cronofy::AuthenticationFailureError,
-      403 => ::Cronofy::AuthorizationFailureError,
-      404 => ::Cronofy::NotFoundError,
-      422 => ::Cronofy::InvalidRequestError,
-      429 => ::Cronofy::TooManyRequestsError
-    }
+    def access_token!
+      raise CredentialsMissingError.new unless @auth.access_token
+      @auth.access_token
+    end
+
+    def get(url, opts = {})
+      wrapped_request { access_token!.get(url, opts) }
+    end
 
-    def do_request(&block)
-      begin
-        block.call
-      rescue OAuth2::Error => e
-        error_class = ERROR_MAP.fetch(e.response.status, UnknownError)
-        raise error_class.new(e.response.headers['status'], e.response)
+    def post(url, body)
+      wrapped_request { access_token!.post(url, json_request_args(body)) }
+    end
+
+    def delete(url, body = nil)
+      wrapped_request { access_token!.delete(url, json_request_args(body)) }
+    end
+
+    def wrapped_request
+      yield
+    rescue OAuth2::Error => e
+      raise Errors.map_error(e)
+    end
+
+    def parse_collection(type, attr, response)
+      ResponseParser.new(response).parse_collection(type, attr)
+    end
+
+    def parse_json(type, attr = nil, response)
+      ResponseParser.new(response).parse_json(type, attr)
+    end
+
+    def json_request_args(body_hash)
+      if body_hash
+        {
+          body: JSON.generate(body_hash),
+          headers: { "Content-Type" => "application/json; charset=utf-8" },
+        }
+      else
+        {}
       end
     end
 
-  end
+    def to_iso8601(value)
+      case value
+      when NilClass
+        nil
+      when Time
+        value.getutc.iso8601
+      else
+        value.iso8601
+      end
+    end
 
-  # Alias for backwards compatibility
-  # depcrectated will be removed
-  class Cronofy < Client
+    class ReadEventsIterator
+      include Enumerable
+
+      def initialize(access_token, url, params)
+        @access_token = access_token
+        @url = url
+        @params = params
+      end
+
+      def each
+        page = get_page(url, params)
+
+        page.events.each do |event|
+          yield event
+        end
+
+        while page.pages.next_page?
+          page = get_page(page.pages.next_page)
+
+          page.events.each do |event|
+            yield event
+          end
+        end
+      end
+
+      private
 
+      attr_reader :access_token
+      attr_reader :params
+      attr_reader :url
+
+      def get_page(url, params = {})
+        response = http_get(url, params)
+        parse_page(response)
+      end
+
+      def http_get(url, params = {})
+        response = Faraday.get(url, params, oauth_headers)
+        Errors.raise_if_error(response)
+        response
+      end
+
+      def oauth_headers
+        {
+          "Authorization" => "Bearer #{access_token.token}",
+          "User-Agent" => "Cronofy Ruby #{::Cronofy::VERSION}",
+        }
+      end
+
+      def parse_page(response)
+        ResponseParser.new(response).parse_json(PagedEventsResult)
+      end
+    end
   end
 
-end
+  # Deprecated: Alias for Client for backwards compatibility.
+  class Cronofy < Client
+  end
+end