Merge pull request #56 from koshilife/feature/#55-support-routing-forms

support Routing Form APIs

CHANGELOG.md

@@ -1,5 +1,24 @@
 # CHANGELOG
 
+## 0.12.0 - 2022-07-16
+
+- supported Routing Form APIs. (#55)
+  - `GET /routing_forms`
+  - `GET /routing_forms/{uuid}`
+  - `GET /routing_form_submissions`
+  - `GET /routing_form_submissions/{uuid}`
+  - changed were followings:
+    - Client
+      - (Add method) routing_form
+      - (Add method) routing_forms
+      - (Add method) routing_form_submission
+      - (Add method) routing_form_submissions
+    - Organization model
+      - (Add method) routing_forms
+      - (Add method) routing_forms!
+    - Invitee model
+      - (Add field) routing_form_submission
+
 ## 0.11.1 - 2022-06-29
 
 - specified dependencies:
@@ -9,7 +28,7 @@
 ## 0.11.0 - 2022-05-02
 
 - supported a API `POST /scheduled_events/{uuid}/cancellation`. (#48)
-  - changed files:
+  - changed were followings:
     - Client
       - (Add method) cancel_event
     - Event
@@ -19,7 +38,7 @@
 ## 0.10.0 - 2022-04-15
 
 - supported a API `POST /data_compliance/deletion/invitees`. (#28)
-  - changed files:
+  - changed were followings:
     - Client
       - (Add method) delete_invitee_data
 
@@ -29,7 +48,7 @@
   - `GET /invitee_no_shows/{no_show_uuid}`
   - `POST /invitee_no_shows`
   - `DELETE /invitee_no_shows/{no_show_uuid}`
-  - changed files:
+  - changed were followings:
     - Client
       - (Add method) invitee_no_show
       - (Add method) create_invitee_no_show
@@ -56,7 +75,7 @@
 ## 0.8.0 - 2021-06-03
 
 - used keyword arguments for optional parameters, to be friendly for programmer.
-- changed methods are followings:
+- changed methods were followings:
   - Client
     - event_types
     - event_types_by_user

README.md

@@ -104,14 +104,15 @@ invitation.delete
 The webhook usage is below.
 
 ```ruby
-events = ['invitee.created', 'invitee.canceled']
 url = 'https://example.com/received_event'
+subscribable_user_events = ['invitee.created', 'invitee.canceled']
+subscribable_org_events = ['invitee.created', 'invitee.canceled', 'routing_form_submission.created']
 
 #
 # create a user scope webhook
 #
 me = client.me
-user_webhook = me.create_webhook(url, events)
+user_webhook = me.create_webhook(url, subscribable_user_events)
 # => #<Calendly::WebhookSubscription uuid="USER_WEBHOOK_001", state="active", scope="user", events=["invitee.created", "invitee.canceled"], callback_url="https://example.com/received_event", ..>
 
 # list of user scope webhooks
@@ -126,8 +127,8 @@ user_webhook.delete
 # create an organization scope webhook
 #
 org = client.me.current_organization
-org_webhook = org.create_webhook(url, events)
-# => #<Calendly::WebhookSubscription uuid="ORG_WEBHOOK_001", state="active", scope="organization", events=["invitee.created", "invitee.canceled"], callback_url="https://example.com/received_event", ..>
+org_webhook = org.create_webhook(url, subscribable_org_events)
+# => #<Calendly::WebhookSubscription uuid="ORG_WEBHOOK_001", state="active", scope="organization", events=["invitee.created", "invitee.canceled", "routing_form_submission.created"], callback_url="https://example.com/received_event", ..>
 
 # list of organization scope webhooks
 org.webhooks

calendly.gemspec

@@ -28,8 +28,8 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_runtime_dependency 'oauth2', '~> 1.4', '>= 1.4.4'
   spec.add_runtime_dependency 'faraday', '>= 1.0.0', '< 3.0.0'
+  spec.add_runtime_dependency 'oauth2', '~> 1.4', '>= 1.4.4'
 
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'codecov'

lib/calendly.rb

@@ -2,6 +2,7 @@
 
 require 'calendly/client'
 require 'calendly/models/model_utils'
+require 'calendly/models/tracking_fields'
 Dir[
   File.join(
     File.dirname(__FILE__),

lib/calendly/client.rb

@@ -113,7 +113,7 @@ def event_type(uuid)
     # @option options [String] :page_token Pass this to get the next portion of collection.
     # @option options [String] :sort Order results by the specified field and direction. Accepts comma-separated list of {field}:{direction} values.
     # @return [Array<Array<Calendly::EventType>, Hash>]
-    #  - [Array<Calendly::EventType>] event_types
+    #  - [Array<Calendly::EventType>] event types
     #  - [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.
@@ -141,7 +141,7 @@ def event_types(org_uri, options: nil)
     # @option options [String] :page_token Pass this to get the next portion of collection.
     # @option options [String] :sort Order results by the specified field and direction. Accepts comma-separated list of {field}:{direction} values.
     # @return [Array<Array<Calendly::EventType>, Hash>]
-    #  - [Array<Calendly::EventType>] event_types
+    #  - [Array<Calendly::EventType>] event types
     #  - [Hash] next_params the parameters to get next data. if thre is no next it returns nil.
     # @raise [Calendly::Error] if the user_uri arg is empty.
     # @raise [Calendly::ApiError] if the api returns error code.
@@ -210,7 +210,7 @@ def scheduled_events(org_uri, options: nil)
     # @param [String] uuid the event's unique indentifier.
     # @param [Hash] options the optional request parameters. Optional.
     # @option options [String] :reason reason for cancellation.
-    # @return [InviteeCancellation]
+    # @return [Calendly::InviteeCancellation]
     # @raise [Calendly::Error] if the uuid arg is empty.
     # @raise [Calendly::ApiError] if the api returns error code.
     # @since 0.11.0
@@ -609,7 +609,7 @@ def user_scope_webhooks(org_uri, user_uri, options: nil)
     # 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 [Array<String>] events List of user events to subscribe to. options: invitee.created or invitee.canceled or routing_form_submission.created
     # @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. Optional.
     # @param [String] signing_key secret key shared between your application and Calendly. Optional.
@@ -651,6 +651,88 @@ def delete_webhook(uuid)
       true
     end
 
+    #
+    # Get a specified Routing Form.
+    #
+    # @param [String] uuid the specified routing form (routing form's uuid).
+    # @return [Calendly::RoutingForm]
+    # @raise [Calendly::Error] if the uuid arg is empty.
+    # @raise [Calendly::ApiError] if the api returns error code.
+    # @since 0.12.0
+    def routing_form(uuid)
+      check_not_empty uuid, 'uuid'
+      body = request :get, "routing_forms/#{uuid}"
+      RoutingForm.new body[:resource], self
+    end
+
+    #
+    # Get a list of Routing Forms for a specified Organization.
+    #
+    # @param [String] org_uri the specified organization (organization's uri).
+    # @param [Hash] options the optional request parameters. Optional.
+    # @option options [Integer] :count Number of rows to return.
+    # @option options [String] :page_token Pass this to get the next portion of collection.
+    # @option options [String] :sort Order results by the specified field and direction. Accepts comma-separated list of {field}:{direction} values.
+    # @return [Array<Array<Calendly::RoutingForm>, Hash>]
+    #  - [Array<Calendly::RoutingForm>] routing forms
+    #  - [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.12.0
+    def routing_forms(org_uri, options: nil)
+      check_not_empty org_uri, 'org_uri'
+
+      opts_keys = %i[count page_token sort]
+      params = {organization: org_uri}
+      params = merge_options options, opts_keys, params
+      body = request :get, 'routing_forms', params: params
+
+      items = body[:collection] || []
+      forms = items.map { |item| RoutingForm.new item, self }
+      [forms, next_page_params(body)]
+    end
+
+    #
+    # Get a specified Routing Form Submission.
+    #
+    # @param [String] uuid the specified routing form submission (routing form submission's uuid).
+    # @return [Calendly::RoutingFormSubmission]
+    # @raise [Calendly::Error] if the uuid arg is empty.
+    # @raise [Calendly::ApiError] if the api returns error code.
+    # @since 0.12.0
+    def routing_form_submission(uuid)
+      check_not_empty uuid, 'uuid'
+      body = request :get, "routing_form_submissions/#{uuid}"
+      RoutingFormSubmission.new body[:resource], self
+    end
+
+    #
+    # Get a list of Routing Form Submissions for a specified Routing Form.
+    #
+    # @param [String] form_uri the specified organization (routing form's uri).
+    # @param [Hash] options the optional request parameters. Optional.
+    # @option options [Integer] :count Number of rows to return.
+    # @option options [String] :page_token Pass this to get the next portion of collection.
+    # @option options [String] :sort Order results by the specified field and direction. Accepts comma-separated list of {field}:{direction} values.
+    # @return [Array<Array<Calendly::RoutingFormSubmission>, Hash>]
+    #  - [Array<Calendly::RoutingFormSubmission>] routing form submissions
+    #  - [Hash] next_params the parameters to get next data. if thre is no next it returns nil.
+    # @raise [Calendly::Error] if the form_uri arg is empty.
+    # @raise [Calendly::ApiError] if the api returns error code.
+    # @since 0.12.0
+    def routing_form_submissions(form_uri, options: nil)
+      check_not_empty form_uri, 'form_uri'
+
+      opts_keys = %i[count page_token sort]
+      params = {form: form_uri}
+      params = merge_options options, opts_keys, params
+      body = request :get, 'routing_form_submissions', params: params
+
+      items = body[:collection] || []
+      submissions = items.map { |item| RoutingFormSubmission.new item, self }
+      [submissions, next_page_params(body)]
+    end
+
     #
     # Create a scheduling link.
     #

lib/calendly/models/event.rb

@@ -50,27 +50,27 @@ def self.association
     # Moment when user record was last updated.
     attr_accessor :updated_at
 
-    # @return [EventType]
+    # @return [Calendly::EventType]
     # Reference to Event Type associated with this event.
     attr_accessor :event_type
 
-    # @return [InviteeCancellation]
+    # @return [Calendly::InviteeCancellation]
     # Provides data pertaining to the cancellation of the Invitee.
     attr_accessor :cancellation
 
-    # @return [InviteesCounter]
+    # @return [Calendly::InviteesCounter]
     # invitees counter.
     attr_accessor :invitees_counter
 
     # @return [Calendly::Location]
     # location in this event.
     attr_accessor :location
 
-    # @return [Array<User>]
+    # @return [Array<Calendly::User>]
     # Event membership list.
     attr_accessor :event_memberships
 
-    # @return [Array<Guest>]
+    # @return [Array<Calendly::Guest>]
     # Additional people added to an event by an invitee.
     attr_accessor :event_guests
 
@@ -90,7 +90,7 @@ def fetch
     #
     # @param [Hash] options the optional request parameters. Optional.
     # @option options [String] :reason reason for cancellation.
-    # @return [InviteeCancellation]
+    # @return [Calendly::InviteeCancellation]
     # @raise [Calendly::Error] if the uuid is empty.
     # @raise [Calendly::ApiError] if the api returns error code.
     # @since 0.11.0
@@ -104,11 +104,9 @@ def cancel(options: nil)
     # @param [Hash] options the optional request parameters. Optional.
     # @option options [Integer] :count Number of rows to return.
     # @option options [String] :email Filter by email.
-    # @option options [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 options [String] :page_token Pass this to get the next portion of collection.
+    # @option options [String] :sort Order results by the specified field and directin. Accepts comma-separated list of {field}:{direction} values.
+    # @option options [String] :status Whether the scheduled event is active or canceled.
     # @return [Array<Calendly::Invitee>]
     # @raise [Calendly::Error] if the uuid is empty.
     # @raise [Calendly::ApiError] if the api returns error code.

lib/calendly/models/event_type.rb

@@ -85,23 +85,23 @@ def self.association
     # Moment when event type was last updated.
     attr_accessor :updated_at
 
-    # @return [EventTypeProfile]
+    # @return [Calendly::EventTypeProfile]
     # The profile of the User that's associated with the Event Type.
     attr_accessor :profile
 
-    # @return [Array<EventTypeCustomQuestion>]
+    # @return [Array<Calendly::EventTypeCustomQuestion>]
     # A collection of custom questions.
     attr_accessor :custom_questions
 
     # The owner user if the profile belongs to a "user" (individual).
-    # @return [User]
+    # @return [Calendly::User]
     # @since 0.6.0
     def owner_user
       profile&.owner_user
     end
 
     # The owner team if the profile belongs to a "team".
-    # @return [Team]
+    # @return [Calendly::Team]
     # @since 0.6.0
     def owner_team
       profile&.owner_team

lib/calendly/models/event_type_profile.rb

@@ -17,11 +17,11 @@ class EventTypeProfile
     # The unique reference to the user associated with the profile
     attr_accessor :owner
 
-    # @return [User]
+    # @return [Calendly::User]
     # The owner user if the profile belongs to a "user" (individual).
     attr_accessor :owner_user
 
-    # @return [Team]
+    # @return [Calendly::Team]
     # The owner team if the profile belongs to a "team".
     attr_accessor :owner_team
 

lib/calendly/models/invitee.rb

@@ -16,7 +16,8 @@ def self.association
         payment: InviteePayment,
         no_show: InviteeNoShow,
         questions_and_answers: InviteeQuestionAndAnswer,
-        tracking: InviteeTracking
+        tracking: InviteeTracking,
+        routing_form_submission: RoutingFormSubmission
       }
     end
 
@@ -94,13 +95,13 @@ def self.extract_event_uuid(str)
     # Moment when user record was last updated.
     attr_accessor :updated_at
 
-    # @return [InviteeCancellation] Provides data pertaining to the cancellation of the Invitee.
+    # @return [Calendly::InviteeCancellation] Provides data pertaining to the cancellation of the Invitee.
     attr_accessor :cancellation
 
-    # @return [InviteePayment] Invitee payment.
+    # @return [Calendly::InviteePayment] Invitee payment.
     attr_accessor :payment
 
-    # @return [InviteeNoShow, nil]
+    # @return [Calendly::InviteeNoShow, nil]
     # Provides data pertaining to the associated no show for the Invitee.
     attr_accessor :no_show
 
@@ -115,6 +116,9 @@ def self.extract_event_uuid(str)
     # @return [Calendly::InviteeTracking]
     attr_accessor :tracking
 
+    # @return [Calendly::RoutingFormSubmission, nil]
+    attr_accessor :routing_form_submission
+
     #
     # Get Event Invitee associated with self.
     #

lib/calendly/models/invitee_no_show.rb

@@ -25,7 +25,7 @@ def self.association
     # The moment when the no show was created.
     attr_accessor :created_at
 
-    # @return [Invitee, nil]
+    # @return [Calendly::Invitee, nil]
     # The associated Invitee.
     attr_accessor :invitee