cronofy 0.5.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2b042634f429bc12cf929f77ab3736bea099b155
-  data.tar.gz: 46301a97a1d85dd7477d3d63a43c8be5ec675051
+  metadata.gz: bc7139bd209e180668455e51a5973e065bedd6b2
+  data.tar.gz: 830ebcf54b85a0aba2150e30ca5e0b2d5d0f1ae4
 SHA512:
-  metadata.gz: 3d3ecec788a50f3195af14120ff3e23c157903d721f68fa3fdbf435357516ea779d5cf08443c0e86de91169f0297697a561319efbb69b648b5fd6778b286c0f8
-  data.tar.gz: 1ed2f31caf7e1f5670c5e24ee5dc58a5af46738622b240ac0e886e2af6286fe41f712a8e6f3c03ea536cb1ade3fcde3c5664b3b27e7bd611d0556af0fbeadebf
+  metadata.gz: d93493fd9c16426323f15d9ffeb0b726bcb2bfaf341f838687b360807ef1cea427a05dbffb5b010694ff30b40ea1f43579711e30c96e6c32c4c0f181a6cd6060
+  data.tar.gz: 49c9dd164f765ca56629514bfa6ef07f69d7859b3f77a8162b7912a07429e4fa5b94a65e4daedec6f32ee241d653aef129789078267aead1ab2d2d86734cc5f3

data/README.md

@@ -2,9 +2,8 @@
 
 [![Build Status](https://travis-ci.org/cronofy/cronofy-ruby.svg?branch=master)](https://travis-ci.org/cronofy/cronofy-ruby)
 [![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).
+[Cronofy](https://www.cronofy.com) - one API for all the calendars (Google, iCloud, Exchange, Office 365, Outlook.com)
 
 ## Installation
 
@@ -14,92 +13,98 @@ Add this line to your application's Gemfile:
 gem 'cronofy'
 ```
 
-And then execute:
+And then at your command prompt run:
 
-    $ bundle
+```
+bundle install
+```
 
-Or install it yourself as:
+## Usage
 
-    $ gem install cronofy
+In order to use the Cronofy API you will need to [create a developer account](https://app.cronofy.com/sign_up/new).
 
-## Usage
+From there you can [create personal access tokens](https://app.cronofy.com/oauth/applications/5447ae289bd94726da00000f/tokens)
+to access your own calendars, or you can [create an OAuth application](https://app.cronofy.com/oauth/applications/new)
+to obtain an OAuth `client_id` and `client_secret` to be able to use the full
+API.
 
-You have to register on the Cronofy website and create an application there. You will then get a client id and client secret.
+## Creating a client
 
-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`:
+To make calls to the Cronofy API you must create a `Cronofy::Client`. This takes
+four keyword arguments, all of which are optional:
 
 ```ruby
-cronofy = Cronofy::Client.new
+cronofy = Cronofy::Client.new(
+  client_id:     'CLIENT_ID',
+  client_secret: 'CLIENT_SECRET',
+  access_token:  'ACCESS_TOKEN',
+  refresh_token: 'REFRESH_TOKEN'
+)
 ```
 
-Or you can specify them explicitly:
+When using a [personal access token](https://app.cronofy.com/oauth/applications/5447ae289bd94726da00000f/tokens)
+you only need to provide the `access_token` argument.
 
-```ruby
-cronofy = Cronofy::Client.new(client_id: 'CLIENT_ID', client_secret: 'CLIENT_SECRET')
-```
+When working against your own OAuth application you will need to provide the
+`client_id` and `client_secret` when [going through the authorization process](https://www.cronofy.com/developers/api/#authorization)
+for a user, and when [refreshing an access token](https://www.cronofy.com/developers/api/#token-refresh).
 
-You can also pass an existing access token and refresh token if you already have a pair for the user:
+If `client_id` and `client_secret` are not specified explicitly the values from
+the environment variables `CRONOFY_CLIENT_ID` and `CRONOFY_CLIENT_SECRET` will
+be used if present.
 
-```ruby
-cronofy = Cronofy::Client.new(access_token: 'ACCESS_TOKEN', refresh_token: 'REFRESH_TOKEN')
-```
+## Authorization
 
-### Authorization
+[API documentation](https://www.cronofy.com/developers/api/#authorization)
 
-Generate a link for a user to grant access for their calendars:
+Generate a link for a user to grant access to their calendars:
 
 ```ruby
-cronofy.user_auth_link('http://localhost:3000/oauth2/callback')
+authorization_url = cronofy.user_auth_link('http://yoursite.dev/oauth2/callback')
 ```
 
-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:
+The callback 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')
+response = cronofy.get_token_from_code(code, 'http://yoursite.dev/oauth2/callback')
 ```
 
-You should save the `access_token` and `refresh_token` for later use.
+You should save the response's `access_token` and `refresh_token` for later use.
 
-### List calendars
+Note that the **exact same** callback URL must be passed to both methods for
+access to be granted.
 
-Get a list of all the user calendars:
+If you use the [omniauth gem](https://rubygems.org/gems/omniauth), you can use
+our [omniauth-cronofy strategy gem](https://rubygems.org/gems/omniauth-cronofy)
+to perform this process.
 
-```ruby
-cronofy.list_calendars
-```
+## List calendars
 
-You will get a list of the user's calendars with each entry being a wrapped
-version of the following JSON structure:
-
-```json
-{
-   "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
-}
-```
+[API documentation](https://www.cronofy.com/developers/api/#calendars)
 
-The properties can be accessed like so:
+Get a list of all the user's calendars:
 
 ```ruby
-calendar = cronofy.list_calendars.first
-calendar.calendar_id
-# => "cal_YYYYYYYY-UNIQUE_CAL_ID_HERE-YYYYYYYY"
+calendars = cronofy.list_calendars
 ```
 
-### Read events
+## Read events
+
+[API documentation](https://www.cronofy.com/developers/api/#read-events)
+
+Get a list of events from the user's calendars:
 
 ```ruby
 events = cronofy.read_events
-events.first
-# => {"calendar_id" => ....}
 ```
 
+Note that the gem handles iterating through the pages on your behalf.
 
-### Create or update events
+## Create or update events
+
+[API documentation](https://www.cronofy.com/developers/api/#upsert-event)
 
 To create/update an event in the user's calendar:
 
@@ -118,7 +123,9 @@ event_data = {
 cronofy.upsert_event(calendar_id, event_data)
 ```
 
-### Delete events
+## Delete events
+
+[API documentation](https://www.cronofy.com/developers/api/#delete-event)
 
 To delete an event from user's calendar:
 
@@ -128,6 +135,6 @@ cronofy.delete_event(calendar_id, 'uniq-id')
 
 ## Links
 
- * [API Docs](http://www.cronofy.com/developers/api)
+ * [API documentation](https://www.cronofy.com/developers/api)
  * [API mailing list](https://groups.google.com/d/forum/cronofy-api)
 

data/lib/cronofy/client.rb

@@ -177,7 +177,49 @@ module Cronofy
       end
 
       url = ::Cronofy.api_url + "/v1/events"
-      ReadEventsIterator.new(access_token!, url, params)
+      PagedResultIterator.new(PagedEventsResult, :events, access_token!, url, params)
+    end
+
+    # Public: Returns a lazily-evaluated Enumerable of FreeBusy 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_managed - A Boolean specifying whether events that you
+    #                              are managing for the account should be
+    #                              included or excluded from the results
+    #                              (optional).
+    #
+    # The first page will be retrieved eagerly so that common errors will happen
+    # inline. However, subsequent pages (if any) will be requested lazily.
+    #
+    # See http://www.cronofy.com/developers/api/alpha#free-busy for reference.
+    #
+    # Returns a lazily-evaluated Enumerable of FreeBusy
+    #
+    # 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 free_busy(options = {})
+      params = FREE_BUSY_DEFAULT_PARAMS.merge(options)
+
+      FREE_BUSY_TIME_PARAMS.select { |tp| params.key?(tp) }.each do |tp|
+        params[tp] = to_iso8601(params[tp])
+      end
+
+      url = ::Cronofy.api_url + "/v1/free_busy"
+      PagedResultIterator.new(PagedFreeBusyResult, :free_busy, access_token!, url, params)
     end
 
     # Public: Deletes an event from the specified calendar
@@ -399,8 +441,13 @@ module Cronofy
 
     private
 
-    READ_EVENTS_DEFAULT_PARAMS = { tzid: "Etc/UTC" }.freeze
+    FREE_BUSY_DEFAULT_PARAMS = { tzid: "Etc/UTC" }.freeze
+    FREE_BUSY_TIME_PARAMS = %i{
+      from
+      to
+    }.freeze
 
+    READ_EVENTS_DEFAULT_PARAMS = { tzid: "Etc/UTC" }.freeze
     READ_EVENTS_TIME_PARAMS = %i{
       from
       to
@@ -460,10 +507,12 @@ module Cronofy
       end
     end
 
-    class ReadEventsIterator
+    class PagedResultIterator
       include Enumerable
 
-      def initialize(access_token, url, params)
+      def initialize(page_parser, items_key, access_token, url, params)
+        @page_parser = page_parser
+        @items_key = items_key
         @access_token = access_token
         @url = url
         @params = params
@@ -473,15 +522,15 @@ module Cronofy
       def each
         page = @first_page
 
-        page.events.each do |event|
-          yield event
+        page[@items_key].each do |item|
+          yield item
         end
 
         while page.pages.next_page?
           page = get_page(page.pages.next_page)
 
-          page.events.each do |event|
-            yield event
+          page[@items_key].each do |item|
+            yield item
           end
         end
       end
@@ -511,7 +560,7 @@ module Cronofy
       end
 
       def parse_page(response)
-        ResponseParser.new(response).parse_json(PagedEventsResult)
+        ResponseParser.new(response).parse_json(@page_parser)
       end
     end
   end

data/lib/cronofy/types.rb

@@ -197,6 +197,25 @@ module Cronofy
     coerce_key :events, Events
   end
 
+  class FreeBusy < Hashie::Mash
+    include Hashie::Extensions::Coercion
+
+    coerce_key :start, EventTime
+    coerce_key :end, EventTime
+  end
+
+  module FreeBusyEnumerable
+    def self.coerce(values)
+      values.map { |v| FreeBusy.new(v) }
+    end
+  end
+
+  class PagedFreeBusyResult < Hashie::Mash
+    include Hashie::Extensions::Coercion
+
+    coerce_key :free_busy, FreeBusyEnumerable
+  end
+
   class Profile < Hashie::Mash
   end
 end

data/lib/cronofy/version.rb

@@ -1,3 +1,3 @@
 module Cronofy
-  VERSION = "0.5.3".freeze
+  VERSION = "0.6.0".freeze
 end

data/spec/lib/cronofy/client_spec.rb

@@ -606,4 +606,192 @@ describe Cronofy::Client do
       it_behaves_like 'a Cronofy request with mapped return value'
     end
   end
+
+  describe 'Free busy' do
+    describe '#free_busy' do
+      before do
+        stub_request(method, request_url)
+          .with(headers: request_headers,
+                body: request_body)
+          .to_return(status: correct_response_code,
+                     headers: correct_response_headers,
+                     body: correct_response_body.to_json)
+
+        stub_request(:get, next_page_url)
+          .with(headers: request_headers)
+          .to_return(status: correct_response_code,
+            headers: correct_response_headers,
+            body: next_page_body.to_json)
+      end
+
+
+      let(:request_url_prefix) { 'https://api.cronofy.com/v1/free_busy' }
+      let(:method) { :get }
+      let(:correct_response_code) { 200 }
+      let(:next_page_url) do
+        "https://next.page.com/08a07b034306679e"
+      end
+
+      let(:params) { Hash.new }
+      let(:request_url) { request_url_prefix + "?tzid=Etc/UTC" }
+
+      let(:correct_response_body) do
+        {
+          'pages' => {
+            'current' => 1,
+            'total' => 2,
+            'next_page' => next_page_url
+          },
+          'free_busy' => [
+                       {
+                         'calendar_id' => 'cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw',
+                         'start' => '2014-09-06',
+                         'end' => '2014-09-08',
+                         'free_busy_status' => 'busy',
+                       },
+                       {
+                         'calendar_id' => 'cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw',
+                         'start' => '2014-09-13T19:00:00Z',
+                         'end' => '2014-09-13T21:00:00Z',
+                         'free_busy_status' => 'tentative',
+                       }
+                      ]
+        }
+      end
+
+      let(:next_page_body) do
+        {
+          'pages' => {
+            'current' => 2,
+            'total' => 2,
+          },
+          'free_busy' => [
+                       {
+                         'calendar_id' => 'cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw',
+                         'start' => '2014-09-07',
+                         'end' => '2014-09-09',
+                         'free_busy_status' => 'busy',
+                       },
+                       {
+                         'calendar_id' => 'cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw',
+                         'start' => '2014-09-14T19:00:00Z',
+                         'end' => '2014-09-14T21:00:00Z',
+                         'free_busy_status' => 'tentative',
+                       }
+                      ]
+        }
+      end
+
+      let(:correct_mapped_result) do
+        first_page_items = correct_response_body['free_busy'].map { |period| Cronofy::FreeBusy.new(period) }
+        second_page_items = next_page_body['free_busy'].map { |period| Cronofy::FreeBusy.new(period) }
+
+        first_page_items + second_page_items
+      end
+
+      subject do
+        # By default force evaluation
+        client.free_busy(params).to_a
+      end
+
+      context 'when all params are passed' do
+        let(:params) do
+          {
+            from: Time.new(2014, 9, 1, 0, 0, 1, '+00:00'),
+            to: Time.new(2014, 10, 1, 0, 0, 1, '+00:00'),
+            tzid: 'Etc/UTC',
+            include_managed: true,
+          }
+        end
+        let(:request_url) do
+          "#{request_url_prefix}?from=2014-09-01T00:00:01Z" \
+          "&to=2014-10-01T00:00:01Z&tzid=Etc/UTC&include_managed=true"
+        end
+
+        it_behaves_like 'a Cronofy request'
+        it_behaves_like 'a Cronofy request with mapped return value'
+      end
+
+      context 'when some params are passed' do
+        let(:params) do
+          {
+            from: Time.new(2014, 9, 1, 0, 0, 1, '+00:00'),
+          }
+        end
+        let(:request_url) do
+          "#{request_url_prefix}?from=2014-09-01T00:00:01Z" \
+          "&tzid=Etc/UTC"
+        end
+
+        it_behaves_like 'a Cronofy request'
+        it_behaves_like 'a Cronofy request with mapped return value'
+      end
+
+      context "when unknown flags are passed" do
+        let(:params) do
+          {
+            unknown_bool: true,
+            unknown_number: 5,
+            unknown_string: "foo-bar-baz",
+          }
+        end
+
+        let(:request_url) do
+          "#{request_url_prefix}?tzid=Etc/UTC" \
+          "&unknown_bool=true" \
+          "&unknown_number=5" \
+          "&unknown_string=foo-bar-baz"
+        end
+
+        it_behaves_like 'a Cronofy request'
+        it_behaves_like 'a Cronofy request with mapped return value'
+      end
+
+      context "next page not found" do
+        before do
+          stub_request(:get, next_page_url)
+            .with(headers: request_headers)
+            .to_return(status: 404,
+              headers: correct_response_headers)
+        end
+
+        it "raises an error" do
+          expect{ subject }.to raise_error(::Cronofy::NotFoundError)
+        end
+      end
+
+      context "only first period" do
+        before do
+          # Ensure an error if second page is requested
+          stub_request(:get, next_page_url)
+            .with(headers: request_headers)
+            .to_return(status: 404,
+              headers: correct_response_headers)
+        end
+
+        let(:first_period) do
+          Cronofy::FreeBusy.new(correct_response_body["free_busy"].first)
+        end
+
+        subject do
+          client.free_busy(params).first
+        end
+
+        it "returns the first period from the first page" do
+          expect(subject).to eq(first_period)
+        end
+      end
+
+      context "without calling #to_a to force full evaluation" do
+        subject { client.free_busy(params) }
+
+        it_behaves_like 'a Cronofy request'
+
+        # We expect it to behave like a Cronofy request as the first page is
+        # requested eagerly so that the majority of errors will happen inline
+        # rather than lazily happening wherever the iterator may have been
+        # passed.
+      end
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cronofy
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.6.0
 platform: ruby
 authors:
 - Sergii Paryzhskyi
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-09 00:00:00.000000000 Z
+date: 2015-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oauth2