TimeTree APIs client

About

These client libraries are created for TimeTree APIs.

Installation

Add this line to your application's Gemfile:

gem 'timetree'

And then execute:

$ bundle

Or install it yourself as:

$ gem install timetree

Usage for Calendar App

The APIs client for Calendar App needs installation_id, application_id and private key.

# set token by TimeTree.configure methods.
TimeTree.configure do |config|
  config.calendar_app_application_id = '<YOUR_APPLICATION_ID>'
  config.calendar_app_private_key = File.read('<YOUR_PATH_TO_PEM>')
end
client = TimeTree::CalendarApp::Client.new('<INSTALLATION_ID>')

# set token by TimeTree::CalendarApp::Client initializer.
client = TimeTree::CalendarApp::Client.new('<INSTALLATION_ID>', '<YOUR_APPLICATION_ID>', '<YOUR_PRIVATE_KEY_CONTENT>')

# get connected calendar's information.
cal = client.calendar
# => #<TimeTree::Calendar id:xxx_cal001>

# get upcoming events on the calendar.
evs = cal.upcoming_events
# => [#<TimeTree::Event id:xxx_ev001>, #<TimeTree::Event id:xxx_ev002>, ...]
ev = evs.first.title
# => "Event Title"

Usage for OAuth App

The APIs client for OAuth App needs access token.

# set token by TimeTree.configure methods.
TimeTree.configure do |config|
  config.oauth_app_token = '<YOUR_ACCESS_TOKEN>'
end
client = TimeTree::OAuthApp::Client.new

# set token by TimeTree::OAuthApp::Client initializer.
client = TimeTree::OAuthApp::Client.new('<YOUR_ACCESS_TOKEN>')

# get a current user's information.
user = client.current_user
# => #<TimeTree::User id:xxx_u001>
user.name
# => "USER Name"

# get current user's calendars.
cals = client.calendars
# => [#<TimeTree::Calendar id:xxx_cal001>, #<TimeTree::Calendar id:xxx_cal002>, ...]
cal = cals.first
cal.name
# => "Calendar Name"

# get upcoming events on the calendar.
evs = cal.upcoming_events
# => [#<TimeTree::Event id:xxx_ev001>, #<TimeTree::Event id:xxx_ev002>, ...]
ev = evs.first
ev.title
# => "Event Title"

# updates an event.
ev.title += ' Updated'
ev.start_at = Time.parse('2020-06-20 09:00 +09:00')
ev.end_at = Time.parse('2020-06-20 10:00 +09:00')
ev.update
# => #<TimeTree::Event id:xxx_ev001>

# creates an event.
copy_ev = ev.dup
new_ev = copy_ev.create
# => #<TimeTree::Event id:xxx_new_ev001>

# deletes an event.
ev.delete
# => true

# creates a comment to an event.
ev.create_comment 'Hi there!'
# => #<TimeTree::Activity id:xxx_act001>

# handles APIs error.
begin
  ev.delete
  ev.delete # 404 Error occured.
rescue TimeTree::ApiError => e
  e
  => #<TimeTree::ApiError title:Not Found, status:404>
  e.response
  => #<Faraday::Response>
end

Logging

# if the log level set :debug, you can get the request/response information.
TimeTree.configuration.logger.level = :debug
=> #<TimeTree::Event id:event_id_001_not_found>
>> client.event 'cal_id_001', 'event_id_001_not_found'
I, [2020-06-24T10:05:07.294807]  INFO -- : GET https://timetreeapis.com/calendars/cal_id_001/events/event_id_001_not_found?include=creator%2Clabel%2Cattendees
D, [2020-06-24T10:05:07.562038] DEBUG -- : Response status:404, body:{:type=>"https://developers.timetreeapp.com/en/docs/api#client-failure", :title=>"Not Found", :status=>404, :errors=>"Event not found"}

More in-depth method documentation can be found at RubyDoc.info.

Contributing

Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the TimeTree Api Client project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.