calendly 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a6dc0f127f4092b13891a3e4515f513973f23fc287ed6ee5b4b2cfd76f46f68
-  data.tar.gz: bc724082ae45976974c064899a63080a2ab1b9fea521fa301706c7e732efd9e3
+  metadata.gz: 3656dc7886aad2a35932152a25f601d2160bed7f53b4ead91e67eb4cb82bb433
+  data.tar.gz: 337d5637a69e30e1dcc943ac1332f38b1675e3d55e0c09049d9308661b4edbe3
 SHA512:
-  metadata.gz: 885928fabc15c7a08c6a670255b5da769a5e59637d2832e863dd7b54a2146217544a3fdfd2461714ce4e9819adbbcc95deb12eaece81fa45167893b97f0101d1
-  data.tar.gz: 1a010d94d5feaa3c2103dc10608cb20364fadcaddc0cfa51f5b7e39ed062bbd218d6c40e1d86e84f384035230500f7141b30cc9cfd95006abe5160f05f6039d1
+  metadata.gz: 32d0c18ebb375a99fb1b23b4365f99ba5957ebbbfed497690ef7d6db8bb0e0ada413853a927892963af62cc21afe39ad6f8d5740831af2e4e881fcc8e9bb5017
+  data.tar.gz: 81a59436778d27892dd325496bc234bea9380fba303b872a2d04ba6ea4b18d73b94d3a13133f7b90f2a68f19a994263ef464a60332239df3f61e064a6d116841

data/{.rubocom.yml → .rubocop.yml}

@@ -23,12 +23,11 @@ Metrics/BlockNesting:
   Max: 2
 
 Layout/LineLength:
- AllowURI: true
- Enabled: false
+  Max: 120
 
 Metrics/MethodLength:
   CountComments: false
-  Max: 15
+  Max: 20
 
 Metrics/ParameterLists:
   Max: 4
@@ -39,10 +38,10 @@ Metrics/AbcSize:
 
 Style/CollectionMethods:
   PreferredMethods:
-    map:      'collect'
-    reduce:   'inject'
-    find:     'detect'
-    find_all: 'select'
+    map: "collect"
+    reduce: "inject"
+    find: "detect"
+    find_all: "select"
 
 Style/Documentation:
   Enabled: false
@@ -60,10 +59,13 @@ Style/ExpandPathArguments:
   Enabled: false
 
 Style/HashSyntax:
-  EnforcedStyle: hash_rockets
+  EnforcedStyle: ruby19
 
 Style/Lambda:
   Enabled: false
 
 Style/RaiseArgs:
-  EnforcedStyle: compact
+  EnforcedStyle: compact
+
+Style/AsciiComments:
+  Enabled: false

data/CHANGELOG.md

@@ -1,23 +1,49 @@
-# 0.1.0
+# CHANGELOG
+
+## 0.3.0
+
+- remove zeitwerk dependency. (refs #16)
+
+## 0.2.0
+
+- save fetched data in cache. (refs #14)
+
+## 0.1.3
+
+- support webhook APIs (refs #9)
+  - `GET /webhook_subscriptions`
+  - `GET /webhook_subscriptions/{webhook_uuid}`
+  - `POST /webhook_subscriptions`
+  - `DELETE /webhook_subscriptions/{webhook_uuid}`
+
+## 0.1.2
+
+- fix rubocop warnings.
+
+## 0.1.1
+
+- add tests to make coverage 100%.
+
+## 0.1.0
 
 - define methods to access associated resources with each model.
 - rename methods:
   - `Calendly::Client#events` to `Calendly::Client#scheduled_events`
 
-# 0.0.7.alpha
+## 0.0.7.alpha
 
 - support APIs
   - `POST /organizations/{uuid}/invitations`
   - `DELETE /organizations/{org_uuid}/invitations/{invitation_uuid}`
   - `DELETE /organization_memberships/{uuid}`
 
-# 0.0.6.alpha
+## 0.0.6.alpha
 
 - support APIs
   - `GET /organizations/{uuid}/invitations`
   - `GET /organizations/{organization_uuid}/invitations/{invitation_uuid}`
 
-# 0.0.5.alpha
+## 0.0.5.alpha
 
 - support APIs
   - `GET /organization_memberships`
@@ -26,24 +52,24 @@
   - Invitee#event to Invitee#event_uri
   - Event#event_type to Event#event_type_uri
 
-# 0.0.4.alpha
+## 0.0.4.alpha
 
 - support APIs
   - `GET /scheduled_events/{event_uuid}/invitees`
   - `GET /scheduled_events/{event_uuid}/invitees/{invitee_uuid}`
 
-# 0.0.3.alpha
+## 0.0.3.alpha
 
 - support APIs
   - `GET /scheduled_events`
   - `GET /scheduled_events/{uuid}`
 
-# 0.0.2.alpha
+## 0.0.2.alpha
 
 - support APIs
   - `GET /event_types`
 
-# 0.0.1.alpha
+## 0.0.1.alpha
 
 - Initial release
 - support APIs

data/README.md

@@ -5,37 +5,7 @@
 [![Gem Version](https://badge.fury.io/rb/calendly.svg)](http://badge.fury.io/rb/calendly)
 [![license](https://img.shields.io/github/license/koshilife/calendly-api-ruby-client)](https://github.com/koshilife/calendly-api-ruby-client/blob/master/LICENSE.txt)
 
-## About
-
-These client libraries are created for [Calendly v2 APIs](https://calendly.stoplight.io/docs/gh/calendly/api-docs).
-
-As of August 2020, Calendly v2 API is currently undergoing an upgrade.
-This library is trying to follow and support for the upgrade.
-
-As of now the supported statuses each Calendly API are as below.
-
-## Supported statuses each Calendly API
-
-- User
-  - [x] Get basic information about a user
-- EventType
-  - [ ] Get Event Type (This endpoint hasn't been released yet.)
-  - [x] User Event Types
-- Organization
-  - [x] Get Organization Invitation
-  - [x] Get Organization Invitations
-  - [x] Get Organization Membership
-  - [x] Get a list of Organization Memberships
-  - [x] Invite a person to Organization
-  - [x] Remove a User from an Organization
-  - [x] Revoke Organization Invitation
-- ScheduledEvent
-  - [x] Get Event
-  - [x] Get Invitee of an Event
-  - [x] Get List of Event Invitees
-  - [x] Get List of User Events
-- Webhook V2
-  - These endpoints havn't been released yet.
+These client libraries are created for [Calendly v2 APIs](https://calendly.stoplight.io/).
 
 ## Installation
 
@@ -55,6 +25,8 @@ Or install it yourself as:
 
 ## Usage
 
+### Basic
+
 The APIs client needs access token.
 This client setup step is below.
 
@@ -116,7 +88,50 @@ invitation.status
 
 # cancel the invitation
 invitation.delete
+```
+
+### Webhook
+
+The webhook usage is below.
+
+```ruby
+events = ['invitee.created', 'invitee.canceled']
+own_member = client.me.organization_membership
+org = own_member.organization
+
+# create user scope webhook
+url = 'https://example.com/received_event'
+user_webhook = own_member.create_user_scope_webhook(url, events)
+# => #<Calendly::WebhookSubscription uuid:USER_WEBHOOK_001>
+
+# list of user scope webhooks
+own_member.user_scope_webhooks
+# => [#<Calendly::WebhookSubscription uuid:USER_WEBHOOK_001>]
+
+# delete the webhook
+user_webhook.delete
+# => true
 
+
+# create organization scope webhook
+url = 'https://example.com/received_event'
+org_webhook = org.create_webhook(url, events)
+# => #<Calendly::WebhookSubscription uuid:ORG_WEBHOOK_001>
+
+# list of organization scope webhooks
+org.webhooks
+# => [#<Calendly::WebhookSubscription uuid:ORG_WEBHOOK_001>]
+
+# delete the webhook
+org_webhook.delete
+# => true
+```
+
+### Logging
+
+This library supports a configurable logger.
+
+```ruby
 # if the log level set :debug, you can get the request/response information.
 Calendly.configuration.logger.level = :debug
 invitation = my_org.create_invitation('foobar@example.com')
@@ -124,6 +139,8 @@ invitation = my_org.create_invitation('foobar@example.com')
 # D, [2020-08-10T10:48:16] DEBUG -- : Response status:201, body:{"resource":{"created_at":"2020-08-10T10:48:16.051159Z","email":"foobar@example.com","last_sent_at":"2020-08-10T10:48:16.096518Z","organization":"https://api.calendly.com/organizations/ORG001","status":"pending","updated_at":"2020-08-10T10:48:16.051159Z","uri":"https://api.calendly.com/organizations/ORG001/invitations/INV001"}}
 ```
 
+More in-depth method documentation can be found at [RubyDoc.info](https://www.rubydoc.info/gems/calendly/).
+
 ## Contributing
 
 Bug reports and pull requests are welcome on [GitHub](https://github.com/koshilife/calendly-api-ruby-client). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

data/Rakefile

@@ -1,10 +1,12 @@
-require "bundler/gem_tasks"
-require "rake/testtask"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
 end
 
-task :default => :test
+task default: :test

data/calendly.gemspec

@@ -29,7 +29,6 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_runtime_dependency 'oauth2', '>= 1.4.4'
-  spec.add_runtime_dependency 'zeitwerk', '>= 2.3.0'
 
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'codecov'

data/lib/calendly.rb

@@ -1,9 +1,17 @@
 # frozen_string_literal: true
 
-require 'zeitwerk'
-loader = Zeitwerk::Loader.for_gem
-loader.collapse('**/models')
-loader.setup
+Dir[
+  File.join(
+    File.dirname(__FILE__),
+    'calendly',
+    '**',
+    '*'
+  )
+].sort.each do |f|
+  next if File.directory? f
+
+  require f
+end
 
 # module for Calendly apis client
 module Calendly

data/lib/calendly/api_error.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require 'calendly/error'
+
 module Calendly
   # Calendly apis client error object.
-  class ApiError < Calendly::Error
+  class ApiError < Error
     # @return [Faraday::Response]
     attr_reader :response
     # @return [Integer]
@@ -25,9 +27,9 @@ module Calendly
       "\#<#{self.class}:#{object_id} title:#{title}, status:#{status}>"
     end
 
-    private
+  private
 
-    def set_attributes_from_response
+    def set_attributes_from_response # rubocop:disable Metrics/CyclomaticComplexity
       return unless response
       return unless response.respond_to? :body
 

data/lib/calendly/client.rb

@@ -4,14 +4,15 @@ require 'oauth2'
 
 module Calendly
   # Calendly apis client.
-  class Client
+  class Client # rubocop:disable Metrics/ClassLength
+    include Loggable
     API_HOST = 'https://api.calendly.com'
     AUTH_API_HOST = 'https://auth.calendly.com'
 
     # @param [String] token a Calendly's access token.
+    # @raise [Calendly::Error] if the token is empty.
     def initialize(token = nil)
       @config = Calendly.configuration
-      @logger = @config.logger
       @token = token || Calendly.configuration.token
 
       check_not_empty @token, 'token'
@@ -38,8 +39,8 @@ module Calendly
     #
     # Refresh access token.
     #
-    # @raise [Calendly::Error] if the client_id is empty.
-    # @raise [Calendly::Error] if the client_secret is empty.
+    # @raise [Calendly::Error] if Calendly.configuration.client_id is empty.
+    # @raise [Calendly::Error] if Calendly.configuration.client_secret is empty.
     # @raise [Calendly::ApiError] if the api returns error code.
     # @since 0.0.7
     def refresh!
@@ -58,11 +59,21 @@ module Calendly
     # @raise [Calendly::ApiError] if the api returns error code.
     # @since 0.0.1
     def current_user
-      user
+      return @cached_current_user if @cached_current_user
+
+      @cached_current_user = user
     end
 
     alias me current_user
 
+    # @since 0.2.0
+    def current_user!
+      @cached_current_user = nil
+      current_user
+    end
+
+    alias me! current_user!
+
     #
     # Get basic information about a user
     #
@@ -95,7 +106,7 @@ module Calendly
       check_not_empty user_uri, 'user_uri'
 
       opts_keys = %i[count page_token sort]
-      params = { user: user_uri }
+      params = {user: user_uri}
       params = merge_options opts, opts_keys, params
       body = request :get, 'event_types', params: params
 
@@ -124,12 +135,12 @@ module Calendly
     # @param [String] user_uri the specified user (user's uri).
     # @param [Hash] opts the optional request parameters.
     # @option opts [Integer] :count Number of rows to return.
-    # @option opts [String] :invitee_email Return events scheduled with the specified invitee email
+    # @option opts [String] :invitee_email Return events scheduled with the specified invitee email.
     # @option opts [String] :max_start_time Upper bound (inclusive) for an event's start time to filter by.
     # @option opts [String] :min_start_time Lower bound (inclusive) for an event's start time to filter by.
     # @option opts [String] :page_token Pass this to get the next portion of collection.
     # @option opts [String] :sort Order results by the specified field and directin. Accepts comma-separated list of {field}:{direction} values.
-    # @option opts [String] :status Whether the scheduled event is active or canceled
+    # @option opts [String] :status Whether the scheduled event is active or canceled.
     # @return [Array<Array<Calendly::Event>, Hash>]
     #  - [Array<Calendly::Event>] events
     #  - [Hash] next_params the parameters to get next data. if thre is no next it returns nil.
@@ -140,7 +151,7 @@ module Calendly
       check_not_empty user_uri, 'user_uri'
 
       opts_keys = %i[count invitee_email max_start_time min_start_time page_token sort status]
-      params = { user: user_uri }
+      params = {user: user_uri}
       params = merge_options opts, opts_keys, params
       body = request :get, 'scheduled_events', params: params
 
@@ -227,7 +238,7 @@ module Calendly
       check_not_empty org_uri, 'org_uri'
 
       opts_keys = %i[count email page_token]
-      params = { organization: org_uri }
+      params = {organization: org_uri}
       params = merge_options opts, opts_keys, params
       body = request :get, 'organization_memberships', params: params
 
@@ -254,7 +265,7 @@ module Calendly
       check_not_empty user_uri, 'user_uri'
 
       opts_keys = %i[count email page_token]
-      params = { user: user_uri }
+      params = {user: user_uri}
       params = merge_options opts, opts_keys, params
       body = request :get, 'organization_memberships', params: params
 
@@ -273,15 +284,15 @@ module Calendly
     # @since 0.0.7
     def delete_membership(uuid)
       check_not_empty uuid, 'uuid'
-      request :delete, "organization_memberships/#{uuid}", expected_status: 204
+      request :delete, "organization_memberships/#{uuid}"
       true
     end
 
     #
     # Returns an Organization Invitation.
     #
-    # @param [String] org_uuid the specified organization (organization's uri).
-    # @param [String] inv_uuid the specified invitation (organization invitation's uri).
+    # @param [String] org_uuid the specified organization (organization's uuid).
+    # @param [String] inv_uuid the specified invitation (organization invitation's uuid).
     # @return [Calendly::OrganizationInvitation]
     # @raise [Calendly::Error] if the org_uuid arg is empty.
     # @raise [Calendly::Error] if the inv_uuid arg is empty.
@@ -298,7 +309,7 @@ module Calendly
     #
     # Get Organization Invitations.
     #
-    # @param [String] uuid the specified organization (organization's uri).
+    # @param [String] uuid the specified organization (organization's uuid).
     # @param [Hash] opts the optional request parameters.
     # @option opts [Integer] :count Number of rows to return.
     # @option opts [String] :email Filter by email.
@@ -326,7 +337,7 @@ module Calendly
     #
     # Invite a person to an Organization.
     #
-    # @param [String] uuid the specified organization (organization's uri).
+    # @param [String] uuid the specified organization (organization's uuid).
     # @param [String] email Email of the person being invited.
     # @return [Calendly::OrganizationInvitation]
     # @raise [Calendly::Error] if the uuid arg is empty.
@@ -339,8 +350,7 @@ module Calendly
       body = request(
         :post,
         "organizations/#{uuid}/invitations",
-        body: { email: email },
-        expected_status: 201
+        body: {email: email}
       )
       OrganizationInvitation.new body[:resource], self
     end
@@ -348,8 +358,8 @@ module Calendly
     #
     # Revoke Organization Invitation.
     #
-    # @param [String] org_uuid the specified organization (organization's uri).
-    # @param [String] inv_uuid the specified invitation (organization invitation's uri).
+    # @param [String] org_uuid the specified organization (organization's uuid).
+    # @param [String] inv_uuid the specified invitation (organization invitation's uuid).
     # @return [true]
     # @raise [Calendly::Error] if the org_uuid arg is empty.
     # @raise [Calendly::Error] if the inv_uuid arg is empty.
@@ -358,40 +368,134 @@ module Calendly
     def delete_invitation(org_uuid, inv_uuid)
       check_not_empty org_uuid, 'org_uuid'
       check_not_empty inv_uuid, 'inv_uuid'
-      request(
-        :delete,
-        "organizations/#{org_uuid}/invitations/#{inv_uuid}",
-        expected_status: 204
-      )
+      request :delete, "organizations/#{org_uuid}/invitations/#{inv_uuid}"
       true
     end
 
-    private
+    #
+    # Get a webhook subscription for an organization or user with a specified UUID.
+    #
+    # @param [String] uuid the specified webhook (webhook's uuid).
+    # @return [Calendly::WebhookSubscription]
+    # @raise [Calendly::Error] if the uuid arg is empty.
+    # @raise [Calendly::ApiError] if the api returns error code.
+    # @since 0.1.3
+    def webhook(uuid)
+      check_not_empty uuid, 'uuid'
+      body = request :get, "webhook_subscriptions/#{uuid}"
+      WebhookSubscription.new body[:resource], self
+    end
 
-    def debug_log(msg)
-      return unless @logger
+    #
+    # Get List of organization scope Webhooks.
+    #
+    # @param [String] org_uri the specified organization (organization's uri).
+    # @param [Hash] opts the optional request parameters.
+    # @option opts [Integer] :count Number of rows to return.
+    # @option opts [String] :page_token Pass this to get the next portion of collection.
+    # @option opts [String] :sort Order results by the specified field and directin. Accepts comma-separated list of {field}:{direction} values.
+    # @return [Array<Array<Calendly::WebhookSubscription>, Hash>]
+    #  - [Array<Calendly::WebhookSubscription>] webhooks
+    #  - [Hash] next_params the parameters to get next data. if thre is no next it returns nil.
+    # @raise [Calendly::Error] if the org_uri arg is empty.
+    # @raise [Calendly::ApiError] if the api returns error code.
+    # @since 0.1.3
+    def webhooks(org_uri, opts = {})
+      check_not_empty org_uri, 'org_uri'
 
-      @logger.debug msg
+      opts_keys = %i[count page_token sort]
+      params = {organization: org_uri, scope: 'organization'}
+      params = merge_options opts, opts_keys, params
+      body = request :get, 'webhook_subscriptions', params: params
+      items = body[:collection] || []
+      evs = items.map { |item| WebhookSubscription.new item, self }
+      [evs, next_page_params(body)]
     end
 
-    def request(method, path, params: nil, body: nil, expected_status: nil)
+    #
+    # Get List of user scope Webhooks.
+    #
+    # @param [String] org_uri the specified organization (organization's uri).
+    # @param [String] user_uri the specified user (user's uri).
+    # @param [Hash] opts the optional request parameters.
+    # @option opts [Integer] :count Number of rows to return.
+    # @option opts [String] :page_token Pass this to get the next portion of collection.
+    # @option opts [String] :sort Order results by the specified field and directin. Accepts comma-separated list of {field}:{direction} values.
+    # @return [Array<Array<Calendly::WebhookSubscription>, Hash>]
+    #  - [Array<Calendly::WebhookSubscription>] webhooks
+    #  - [Hash] next_params the parameters to get next data. if thre is no next it returns nil.
+    # @raise [Calendly::Error] if the org_uri arg is empty.
+    # @raise [Calendly::Error] if the user_uri arg is empty.
+    # @raise [Calendly::ApiError] if the api returns error code.
+    # @since 0.1.3
+    def user_scope_webhooks(org_uri, user_uri, opts = {})
+      check_not_empty org_uri, 'org_uri'
+      check_not_empty user_uri, 'user_uri'
+
+      opts_keys = %i[count page_token sort]
+      params = {organization: org_uri, user: user_uri, scope: 'user'}
+      params = merge_options opts, opts_keys, params
+      body = request :get, 'webhook_subscriptions', params: params
+      items = body[:collection] || []
+      evs = items.map { |item| WebhookSubscription.new item, self }
+      [evs, next_page_params(body)]
+    end
+
+    #
+    # Create a webhook subscription for an organization or user.
+    #
+    # @param [String] url Canonical reference (unique identifier) for the resource.
+    # @param [Array<String>] events List of user events to subscribe to. options: invitee.created or invitee.canceled
+    # @param [String] org_uri The unique reference to the organization that the webhook will be tied to.
+    # @param [String] user_uri The unique reference to the user that the webhook will be tied to.
+    # @return [Calendly::WebhookSubscription]
+    # @raise [Calendly::Error] if the url arg is empty.
+    # @raise [Calendly::Error] if the events arg is empty.
+    # @raise [Calendly::Error] if the org_uri arg is empty.
+    # @raise [Calendly::ApiError] if the api returns error code.
+    # @since 0.1.3
+    def create_webhook(url, events, org_uri, user_uri = nil)
+      check_not_empty url, 'url'
+      check_not_empty events, 'events'
+      check_not_empty org_uri, 'org_uri'
+
+      params = {url: url, events: events, organization: org_uri}
+      if user_uri
+        params[:scope] = 'user'
+        params[:user] = user_uri
+      else
+        params[:scope] = 'organization'
+      end
+      body = request(:post, 'webhook_subscriptions', body: params)
+      WebhookSubscription.new body[:resource], self
+    end
+
+    #
+    # Delete a webhook subscription for an organization or user with a specified UUID.
+    #
+    # @param [String] uuid the specified webhook (webhook's uuid).
+    # @return [true]
+    # @raise [Calendly::Error] if the uuid arg is empty.
+    # @raise [Calendly::ApiError] if the api returns error code.
+    # @since 0.1.3
+    def delete_webhook(uuid)
+      check_not_empty uuid, 'uuid'
+      request :delete, "webhook_subscriptions/#{uuid}"
+      true
+    end
+
+  private
+
+    def request(method, path, params: nil, body: nil)
       debug_log "Request #{method.to_s.upcase} #{API_HOST}/#{path} params:#{params}, body:#{body}"
       res = access_token.request(method, path, params: params, body: body)
       debug_log "Response status:#{res.status}, body:#{res.body}"
-      validate_status_code res, expected_status
       parse_as_json res
     rescue OAuth2::Error => e
       res = e.response.response
       raise ApiError.new res, e
     end
 
-    def validate_status_code(res, expected_status)
-      return unless expected_status
-      return if expected_status == res.status
-
-      raise ApiError.new res, message: 'unexpected http status returned.'
-    end
-
     def parse_as_json(res)
       return if blank? res.body
 
@@ -401,12 +505,13 @@ module Calendly
     end
 
     def check_not_empty(value, name)
-      raise Calendly::Error, "#{name} is required." if blank? value
+      raise Error.new("#{name} is required.") if blank? value
     end
 
     def blank?(value)
       return true if value.nil?
       return true if value.to_s.empty?
+      return true if value.is_a?(Array) && value.empty?
 
       false
     end