class Calendly::Client
Calendly
apis client.
Constants
- API_HOST
- AUTH_API_HOST
Public Class Methods
@param [String] token a Calendly's access token. @raise [Calendly::Error] if the token is empty.
# File lib/calendly/client.rb, line 14 def initialize(token = nil) @config = Calendly.configuration @token = token || Calendly.configuration.token check_not_empty @token, 'token' check_token end
Public Instance Methods
Get access token object.
@return [OAuth2::AccessToken] @since 0.0.1
# File lib/calendly/client.rb, line 27 def access_token return @access_token if defined?(@access_token) && @access_token client = OAuth2::Client.new(@config.client_id, @config.client_secret, client_options) @access_token = OAuth2::AccessToken.new( client, @token, refresh_token: @config.refresh_token, expires_at: @config.token_expires_at ) end
Invite a person to an Organization
.
@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. @raise [Calendly::Error] if the email arg is empty. @raise [Calendly::ApiError] if the api returns error code. @since 0.0.7
# File lib/calendly/client.rb, line 420 def create_invitation(uuid, email) check_not_empty uuid, 'uuid' check_not_empty email, 'email' body = request( :post, "organizations/#{uuid}/invitations", body: {email: email} ) OrganizationInvitation.new body[:resource], self end
Create a scheduling link.
@param [String] uri A link to the resource that owns this scheduling Link. @param [String] max_event_count The max number of events that can be scheduled using this scheduling link. @param [String] owner_type Resource type. @return [Hash] e.g. {
booking_url: "https://calendly.com/s/FOO-BAR-SLUG", owner: "https://api.calendly.com/event_types/GBGBDCAADAEDCRZ2", owner_type: "EventType"
} @raise [Calendly::Error] if the uri arg is empty. @raise [Calendly::Error] if the max_event_count arg is empty. @raise [Calendly::Error] if the owner_type arg is empty. @raise [Calendly::ApiError] if the api returns error code. @since 0.5.2
# File lib/calendly/client.rb, line 581 def create_schedule_link(uri, max_event_count: 1, owner_type: 'EventType') check_not_empty uri, 'uri' check_not_empty max_event_count, 'max_event_count' check_not_empty owner_type, 'owner_type' params = { max_event_count: max_event_count, owner: uri, owner_type: owner_type } body = request :post, 'scheduling_links', body: params body[:resource] 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. Optional. @param [String] signing_key secret key shared between your application and Calendly
. Optional. @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
# File lib/calendly/client.rb, line 531 def create_webhook(url, events, org_uri, user_uri: nil, signing_key: nil) # rubocop:disable Metrics/ParameterLists 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} params[:signing_key] = signing_key if signing_key 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
Get basic information about current user.
@return [Calendly::User] @raise [Calendly::ApiError] if the api returns error code. @since 0.0.1
# File lib/calendly/client.rb, line 61 def current_user return @cached_current_user if defined?(@cached_current_user) && @cached_current_user @cached_current_user = user end
@since 0.2.0
# File lib/calendly/client.rb, line 70 def current_user! @cached_current_user = nil current_user end
Revoke Organization
Invitation.
@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. @raise [Calendly::ApiError] if the api returns error code. @since 0.0.7
# File lib/calendly/client.rb, line 441 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}" true end
Remove a User
from an Organization
.
@param [String] uuid the specified memberhip (organization memberhips's uuid). @return [true] @raise [Calendly::Error] if the uuid arg is empty. @raise [Calendly::ApiError] if the api returns error code. @since 0.0.7
# File lib/calendly/client.rb, line 358 def delete_membership(uuid) check_not_empty uuid, 'uuid' request :delete, "organization_memberships/#{uuid}" true 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
# File lib/calendly/client.rb, line 557 def delete_webhook(uuid) check_not_empty uuid, 'uuid' request :delete, "webhook_subscriptions/#{uuid}" true end
Get Invitee
of an Event
Returns a single Invitee
by their URI.
@param [String] ev_uuid the specified event (event's uuid). @param [String] inv_uuid the specified invitee (invitee's uuid). @return [Calendly::Invitee] @raise [Calendly::Error] if the ev_uuid arg is empty. @raise [Calendly::Error] if the inv_uuid arg is empty. @raise [Calendly::ApiError] if the api returns error code. @since 0.0.4
# File lib/calendly/client.rb, line 247 def event_invitee(ev_uuid, inv_uuid) check_not_empty ev_uuid, 'ev_uuid' check_not_empty inv_uuid, 'inv_uuid' body = request :get, "scheduled_events/#{ev_uuid}/invitees/#{inv_uuid}" Invitee.new body[:resource], self end
Get List of Event
Invitees.
@param [String] uuid the specified event (event's uuid). @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 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<Array<Calendly::Invitee>, Hash>]
- [Array<Calendly::Invitee>] invitees - [Hash] next_params the parameters to get next data. if thre is no next it returns nil.
@raise [Calendly::Error] if the uuid arg is empty. @raise [Calendly::ApiError] if the api returns error code. @since 0.0.4
# File lib/calendly/client.rb, line 270 def event_invitees(uuid, options: nil) check_not_empty uuid, 'uuid' opts_keys = %i[count email page_token sort status] params = merge_options options, opts_keys body = request :get, "scheduled_events/#{uuid}/invitees", params: params items = body[:collection] || [] evs = items.map { |item| Invitee.new item, self } [evs, next_page_params(body)] end
Returns a single Event
Type by its UUID.
@param [String] uuid the specified event type (event type's uuid). @return [Calendly::EventType] @raise [Calendly::Error] if the uuid arg is empty. @raise [Calendly::ApiError] if the api returns error code. @since 0.4.1
# File lib/calendly/client.rb, line 99 def event_type(uuid) check_not_empty uuid, 'uuid' body = request :get, "event_types/#{uuid}" EventType.new body[:resource], self end
Returns all Event
Types associated with 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::EventType>, Hash>]
- [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. @since 0.6.0
# File lib/calendly/client.rb, line 119 def event_types(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, 'event_types', params: params items = body[:collection] || [] ev_types = items.map { |item| EventType.new item, self } [ev_types, next_page_params(body)] end
Returns all Event
Types associated with a specified user.
@param [String] user_uri the specified user (user'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::EventType>, Hash>]
- [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. @since 0.0.2
# File lib/calendly/client.rb, line 146 def event_types_by_user(user_uri, options: nil) check_not_empty user_uri, 'user_uri' opts_keys = %i[count page_token sort] params = {user: user_uri} params = merge_options options, opts_keys, params body = request :get, 'event_types', params: params items = body[:collection] || [] ev_types = items.map { |item| EventType.new item, self } [ev_types, next_page_params(body)] end
Returns an Organization
Invitation.
@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. @raise [Calendly::ApiError] if the api returns error code. @since 0.0.6
# File lib/calendly/client.rb, line 374 def invitation(org_uuid, inv_uuid) check_not_empty org_uuid, 'org_uuid' check_not_empty inv_uuid, 'inv_uuid' body = request :get, "organizations/#{org_uuid}/invitations/#{inv_uuid}" OrganizationInvitation.new body[:resource], self end
Get Organization
Invitations.
@param [String] uuid the specified organization (organization's uuid). @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 options [String] :sort Order results by the specified field and directin. Accepts comma-separated list of {field}:{direction} values. @option options [String] :status Filter by status. @return [<Array<Array<Calendly::OrganizationInvitation>, Hash>]
- [Array<Calendly::OrganizationInvitation>] organizations - [Hash] next_params the parameters to get next data. if thre is no next it returns nil.
@raise [Calendly::Error] if the uuid arg is empty. @raise [Calendly::ApiError] if the api returns error code. @since 0.0.6
# File lib/calendly/client.rb, line 398 def invitations(uuid, options: nil) check_not_empty uuid, 'uuid' opts_keys = %i[count email page_token sort status] params = merge_options options, opts_keys body = request :get, "organizations/#{uuid}/invitations", params: params items = body[:collection] || [] evs = items.map { |item| OrganizationInvitation.new item, self } [evs, next_page_params(body)] end
Returns information about a user's organization membership
@param [String] uuid the specified membership (organization membership's uuid). @return [Calendly::OrganizationMembership] @raise [Calendly::Error] if the uuid arg is empty. @raise [Calendly::ApiError] if the api returns error code. @since 0.0.5
# File lib/calendly/client.rb, line 290 def membership(uuid) check_not_empty uuid, 'uuid' body = request :get, "organization_memberships/#{uuid}" OrganizationMembership.new body[:resource], self end
Get List of memberships belonging to specific an 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] :email Filter by email. @option options [String] :page_token Pass this to get the next portion of collection. @return [Array<Array<Calendly::OrganizationMembership>, Hash>]
- [Array<Calendly::OrganizationMembership>] memberships - [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.0.5
# File lib/calendly/client.rb, line 310 def memberships(org_uri, options: nil) check_not_empty org_uri, 'org_uri' opts_keys = %i[count email page_token] params = {organization: org_uri} params = merge_options options, opts_keys, params body = request :get, 'organization_memberships', params: params items = body[:collection] || [] memberships = items.map { |item| OrganizationMembership.new item, self } [memberships, next_page_params(body)] end
Get List of memberships belonging to specific a user.
@param [String] user_uri the specified user (user's uri). @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. @return [Array<Array<Calendly::OrganizationMembership>, Hash>]
- [Array<Calendly::OrganizationMembership>] memberships - [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. @since 0.0.5
# File lib/calendly/client.rb, line 337 def memberships_by_user(user_uri, options: nil) check_not_empty user_uri, 'user_uri' opts_keys = %i[count email page_token] params = {user: user_uri} params = merge_options options, opts_keys, params body = request :get, 'organization_memberships', params: params items = body[:collection] || [] memberships = items.map { |item| OrganizationMembership.new item, self } [memberships, next_page_params(body)] end
Refresh access token.
@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
# File lib/calendly/client.rb, line 46 def refresh! check_not_empty @config.client_id, 'client_id' check_not_empty @config.client_secret, 'client_secret' @access_token = access_token.refresh! rescue OAuth2::Error => e res = e.response.response raise ApiError.new res, e end
Returns a single Event
by its URI.
@param [String] uuid the specified event (event's uuid). @return [Calendly::Event] @raise [Calendly::Error] if the uuid arg is empty. @raise [Calendly::ApiError] if the api returns error code. @since 0.0.3
# File lib/calendly/client.rb, line 167 def scheduled_event(uuid) check_not_empty uuid, 'uuid' body = request :get, "scheduled_events/#{uuid}" Event.new body[:resource], self end
Get List of scheduled events belonging to a specific 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] :invitee_email Return events scheduled with the specified invitee email. @option options [String] :max_start_time Upper bound (inclusive) for an event's start time to filter by. @option options [String] :min_start_time Lower bound (inclusive) for an event's start time to filter by. @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<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.
@raise [Calendly::Error] if the org_uri arg is empty. @raise [Calendly::ApiError] if the api returns error code. @since 0.5.0
# File lib/calendly/client.rb, line 191 def scheduled_events(org_uri, options: nil) check_not_empty org_uri, 'org_uri' opts_keys = %i[count invitee_email max_start_time min_start_time page_token sort status] params = {organization: org_uri} params = merge_options options, opts_keys, params body = request :get, 'scheduled_events', params: params items = body[:collection] || [] evs = items.map { |item| Event.new item, self } [evs, next_page_params(body)] end
Get List of scheduled events belonging to a specific user.
@param [String] user_uri the specified user (user's uri). @param [Hash] options the optional request parameters. Optional. @option options [String] :organization the specified organization (organization's uri). @option options [Integer] :count Number of rows to return. @option options [String] :invitee_email Return events scheduled with the specified invitee email. @option options [String] :max_start_time Upper bound (inclusive) for an event's start time to filter by. @option options [String] :min_start_time Lower bound (inclusive) for an event's start time to filter by. @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<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.
@raise [Calendly::Error] if the user_uri arg is empty. @raise [Calendly::ApiError] if the api returns error code. @since 0.0.3
# File lib/calendly/client.rb, line 223 def scheduled_events_by_user(user_uri, options: nil) check_not_empty user_uri, 'user_uri' opts_keys = %i[organization count invitee_email max_start_time min_start_time page_token sort status] params = {user: user_uri} params = merge_options options, opts_keys, params body = request :get, 'scheduled_events', params: params items = body[:collection] || [] evs = items.map { |item| Event.new item, self } [evs, next_page_params(body)] end
Get basic information about a user
@param [String] uuid User
unique identifier, or the constant “me” to reference the caller @return [Calendly::User] @raise [Calendly::Error] if the uuid arg is empty. @raise [Calendly::ApiError] if the api returns error code. @since 0.0.1
# File lib/calendly/client.rb, line 85 def user(uuid = 'me') check_not_empty uuid, 'uuid' body = request :get, "users/#{uuid}" User.new body[:resource], self end
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] 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 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
# File lib/calendly/client.rb, line 504 def user_scope_webhooks(org_uri, user_uri, options: nil) 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 options, 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
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
# File lib/calendly/client.rb, line 456 def webhook(uuid) check_not_empty uuid, 'uuid' body = request :get, "webhook_subscriptions/#{uuid}" WebhookSubscription.new body[:resource], self end
Get List of organization scope Webhooks.
@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 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
# File lib/calendly/client.rb, line 476 def webhooks(org_uri, options: nil) check_not_empty org_uri, 'org_uri' opts_keys = %i[count page_token sort] params = {organization: org_uri, scope: 'organization'} params = merge_options options, 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
Private Instance Methods
# File lib/calendly/client.rb, line 618 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
# File lib/calendly/client.rb, line 614 def check_not_empty(value, name) raise Error.new("#{name} is required.") if blank? value end
# File lib/calendly/client.rb, line 626 def check_token refresh! if access_token.expired? end
# File lib/calendly/client.rb, line 630 def client_options { site: API_HOST, authorize_url: "#{AUTH_API_HOST}/oauth/authorize", token_url: "#{AUTH_API_HOST}/oauth/token" } end
# File lib/calendly/client.rb, line 638 def merge_options(opts, filters, params = {}) return params unless opts.is_a? Hash permitted_opts = opts.transform_keys(&:to_sym).slice(*filters) params.merge permitted_opts end
# File lib/calendly/client.rb, line 645 def next_page_params(body) return unless body[:pagination] return unless body[:pagination][:next_page] uri = URI.parse body[:pagination][:next_page] params = Hash[URI.decode_www_form(uri.query)] params.transform_keys(&:to_sym) end
# File lib/calendly/client.rb, line 606 def parse_as_json(res) return if blank? res.body JSON.parse res.body, symbolize_names: true rescue JSON::ParserError => e raise ApiError.new res, e end
# File lib/calendly/client.rb, line 596 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.dup&.force_encoding(Encoding::UTF_8)}" parse_as_json res rescue OAuth2::Error => e res = e.response.response raise ApiError.new res, e end