timetree 0.3.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b5824494b234019afe3260508db4d161c874771a65b041f005cda5e3d75ed3e
-  data.tar.gz: ef00a0a5c959255e10550c606a463fa9c4914aa95cd6f1dd864de5bbe990f697
+  metadata.gz: '08f576804646a18cf1c980d7649f3cf621f7e98871d291bec881ba8232e69e6a'
+  data.tar.gz: 3740f58f68f0f6514b59295a7c3e8f57321fc10b4b5ca3fd6515da7b67a48c50
 SHA512:
-  metadata.gz: aedb1c5f57d57426aad408626ee6b47adffeb1db0114a36679b5ef2958acd95308e7fd631dc93a2eb4fcf054ec7bed9eaeb1add8725086402a29439674ee15f2
-  data.tar.gz: 8587334f92c73d0247e19f44543af05d9a2bfdd7ecca7125f4d0f828ed53e51ec8bf5d9cc1b0b7f0816d4a70c0de7484614473a411141a54469d1229fb962e0d
+  metadata.gz: 5cd3358940be41c9e441ab348249b65628cb489df329687df949ff3f4a48a2749642f31f0cde56170d895acf35f63bd90c30c00d3491efb74ec8323eb501bd29
+  data.tar.gz: 8888d348d25e8c67645a50084443c79cba8a6d14c7aa7fbb43ae743abd2be8092b3a5ea5815edd35c115268c60bac1933438177c31f0e5ae0b27821e3b3d02b3

data/.rubocop.yml

@@ -1,4 +1,5 @@
 AllCops:
+  NewCops: enable
   TargetRubyVersion: 2.6
 
 Layout/AccessModifierIndentation:

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## 1.0.0
+
+- add Calendar App Client. (refs #28)
+- rename `TimeTree::OAuthApp::Client` from `TimeTree::Client`.
+
 ## 0.3.2
 
 - remove zeitwerk dependency. (refs #29)

data/README.md

@@ -25,60 +25,85 @@ Or install it yourself as:
 
     $ gem install timetree
 
-## Usage
+## Usage for Calendar App
 
-The APIs client needs access token.
-Set a `token` variable to the value you got by above:
+The APIs client for Calendar App needs installation_id, application_id and private key.
 
 ```ruby
 # set token by TimeTree.configure methods.
 TimeTree.configure do |config|
-  config.token = '<YOUR_ACCESS_TOKEN>'
+  config.calendar_app_application_id = '<YOUR_APPLICATION_ID>'
+  config.calendar_app_private_key = File.read('<YOUR_PATH_TO_PEM>')
 end
-client = TimeTree::Client.new
+client = TimeTree::CalendarApp::Client.new('<INSTALLATION_ID>')
 
-# set token by TimeTree::Client initializer.
-client = TimeTree::Client.new('<YOUR_ACCESS_TOKEN>')
+# 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.
+
+```ruby
+# 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>
+# => #<TimeTree::User id:xxx_u001>
 user.name
-=> "USER Name"
+# => "USER Name"
 
 # get current user's calendars.
 cals = client.calendars
-=> [#<TimeTree::Calendar id:xxx_cal001>, #<TimeTree::Calendar id:xxx_cal002>, ...]
+# => [#<TimeTree::Calendar id:xxx_cal001>, #<TimeTree::Calendar id:xxx_cal002>, ...]
 cal = cals.first
 cal.name
-=> "Calendar Name"
+# => "Calendar Name"
 
 # get upcoming events on the calendar.
 evs = cal.upcoming_events
-=> [#<TimeTree::Event id:xxx_ev001>, #<TimeTree::Event id:xxx_ev002>, ...]
+# => [#<TimeTree::Event id:xxx_ev001>, #<TimeTree::Event id:xxx_ev002>, ...]
 ev = evs.first
 ev.title
-=> "Event 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>
+# => #<TimeTree::Event id:xxx_ev001>
 
 # creates an event.
 copy_ev = ev.dup
 new_ev = copy_ev.create
-=> #<TimeTree::Event id:xxx_new_ev001>
+# => #<TimeTree::Event id:xxx_new_ev001>
 
 # deletes an event.
 ev.delete
-=> true
+# => true
 
 # creates a comment to an event.
 ev.create_comment 'Hi there!'
-=> #<TimeTree::Activity id:xxx_act001>
+# => #<TimeTree::Activity id:xxx_act001>
 
 # handles APIs error.
 begin
@@ -90,7 +115,11 @@ rescue TimeTree::ApiError => e
   e.response
   => #<Faraday::Response>
 end
+```
 
+## Logging
+
+```ruby
 # 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>

data/lib/timetree/base_client.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module TimeTree
+  class BaseClient
+    API_HOST = 'https://timetreeapis.com'
+    # @return [Integer]
+    attr_reader :ratelimit_limit
+    # @return [Integer]
+    attr_reader :ratelimit_remaining
+    # @return [Time]
+    attr_reader :ratelimit_reset_at
+
+    #
+    # update ratelimit properties
+    #
+    # @param res [Faraday::Response]
+    # apis http response.
+    def update_ratelimit(res)
+      limit = res.headers['x-ratelimit-limit']
+      remaining = res.headers['x-ratelimit-remaining']
+      reset = res.headers['x-ratelimit-reset']
+      @ratelimit_limit = limit.to_i if limit
+      @ratelimit_remaining = remaining.to_i if remaining
+      @ratelimit_reset_at = Time.at reset.to_i if reset
+    end
+
+  private
+
+    def check_event_id(value)
+      check_required_property(value, 'event_id')
+    end
+
+    def check_required_property(value, name)
+      err = Error.new "#{name} is required."
+      raise err if value.nil?
+      raise err if value.to_s.empty?
+
+      true
+    end
+
+    def to_model(data, included: nil)
+      TimeTree::BaseModel.to_model data, client: self, included: included
+    end
+
+    def relationships_params(relationships, default)
+      params = {}
+      relationships ||= default
+      params[:include] = relationships.join ',' if relationships.is_a? Array
+      params
+    end
+  end
+end

data/lib/timetree/calendar_app/access_token.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module TimeTree
+  module CalendarApp
+    class AccessToken
+      # @return [String]
+      attr_reader :token
+      # @return [Integer]
+      attr_reader :expire_at
+
+      def initialize(token, expire_at)
+        @token = token
+        @expire_at = expire_at
+      end
+
+      #
+      # Returns the access token is expired or not.
+      #
+      # @return [Boolean]
+      def expired?
+        Time.now.to_i > expire_at
+      end
+    end
+  end
+end

data/lib/timetree/calendar_app/client.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'jwt'
+
+module TimeTree
+  module CalendarApp
+    # TimeTree API CalendarApp client.
+    class Client < BaseClient
+      # @return [Integer]
+      attr_reader :installation_id
+      # @return [String]
+      attr_reader :application_id
+      # @return [String]
+      attr_reader :private_key
+      # @return [String]
+      attr_reader :token
+
+      # @param installation_id [Integer] CalendarApp's installation id
+      # @param application_id [String] CalendarApp id
+      # @param private_key [String] RSA private key for CalendarApp
+      def initialize(installation_id, application_id = nil, private_key = nil)
+        @installation_id = installation_id
+        @application_id = application_id || TimeTree.configuration.calendar_app_application_id
+        @private_key = OpenSSL::PKey::RSA.new((private_key || TimeTree.configuration.calendar_app_private_key).to_s)
+        check_client_requirement
+        @http_cmd = HttpCommand.new(API_HOST, self)
+      rescue OpenSSL::PKey::RSAError
+        raise Error.new 'private_key must be RSA private key.'
+      end
+
+      #
+      # Get a calendar information related to CalendarApp
+      #
+      # @param include_relationships [Array<symbol>]
+      # includes association's object in the response.
+      # @return [TimeTree::Calendar]
+      # @raise [TimeTree::ApiError] if the http response status will not success.
+      # @since 1.0.0
+      def calendar(include_relationships: nil)
+        check_access_token
+        params = relationships_params(include_relationships, Calendar::RELATIONSHIPS)
+        res = http_cmd.get('/calendar', params)
+        raise ApiError.new(res) if res.status != 200
+
+        to_model(res.body[:data], included: res.body[:included])
+      end
+
+      #
+      # Get a calendar's member information.
+      #
+      # @return [Array<TimeTree::User>]
+      # @raise [TimeTree::ApiError] if the http response status will not success.
+      # @since 1.0.0
+      def calendar_members
+        check_access_token
+        res = http_cmd.get('/calendar/members')
+        raise ApiError.new(res) if res.status != 200
+
+        res.body[:data].map { |item| to_model(item) }
+      end
+
+      #
+      # Get an event's information.
+      #
+      # @param event_id [String] event's id.
+      # @param include_relationships [Array<symbol>]
+      # includes association's object in the response.
+      # @return [TimeTree::Event]
+      # @raise [TimeTree::Error] if the event_id arg is empty.
+      # @raise [TimeTree::ApiError] if the http response status will not success.
+      # @since 1.0.0
+      def event(event_id, include_relationships: nil)
+        check_event_id event_id
+        check_access_token
+        params = relationships_params(include_relationships, Event::RELATIONSHIPS)
+        res = http_cmd.get("/calendar/events/#{event_id}", params)
+        raise ApiError.new(res) if res.status != 200
+
+        to_model(res.body[:data], included: res.body[:included])
+      end
+
+      #
+      # Get events' information after a request date.
+      #
+      # @param days [Integer] The number of days to get.
+      # @param timezone [String] Timezone.
+      # @param include_relationships [Array<symbol>]
+      # includes association's object in the response.
+      # @return [Array<TimeTree::Event>]
+      # @raise [TimeTree::ApiError] if the http response status will not success.
+      # @since 1.0.0
+      def upcoming_events(days: 7, timezone: 'UTC', include_relationships: nil)
+        check_access_token
+        params = relationships_params(include_relationships, Event::RELATIONSHIPS)
+        params.merge!(days: days, timezone: timezone)
+        res = http_cmd.get('/calendar/upcoming_events', params)
+        raise ApiError.new(res) if res.status != 200
+
+        included = res.body[:included]
+        res.body[:data].map { |item| to_model(item, included: included) }
+      end
+
+      #
+      # Creates an event.
+      #
+      # @param params [Hash] TimeTree request body format.
+      # @return [TimeTree::Event]
+      # @raise [TimeTree::Error] if the cal_id arg is empty.
+      # @raise [TimeTree::ApiError] if the http response status will not success.
+      # @since 1.0.0
+      def create_event(params)
+        check_access_token
+        res = http_cmd.post('/calendar/events', params)
+        raise ApiError.new(res) if res.status != 201
+
+        to_model(res.body[:data])
+      end
+
+      #
+      # Updates an event.
+      #
+      # @param event_id [String] event's id.
+      # @param params [Hash]
+      # event's information specified in TimeTree request body format.
+      # @return [TimeTree::Event]
+      # @raise [TimeTree::Error] if the event_id arg is empty.
+      # @raise [TimeTree::ApiError] if the http response status will not success.
+      # @since 1.0.0
+      def update_event(event_id, params)
+        check_event_id event_id
+        check_access_token
+        res = http_cmd.put("/calendar/events/#{event_id}", params)
+        raise ApiError.new(res) if res.status != 200
+
+        to_model(res.body[:data])
+      end
+
+      #
+      # Deletes an event.
+      #
+      # @param event_id [String] event's id.
+      # @return [true] if the operation succeeded.
+      # @raise [TimeTree::Error] if the event_id arg is empty.
+      # @raise [TimeTree::ApiError] if the http response status will not success.
+      # @since 1.0.0
+      def delete_event(event_id)
+        check_event_id event_id
+        check_access_token
+        res = http_cmd.delete("/calendar/events/#{event_id}")
+        raise ApiError.new(res) if res.status != 204
+
+        true
+      end
+
+      #
+      # Creates a comment.
+      #
+      # @param event_id [String] event's id.
+      # @param params [Hash]
+      # comment's information specified in TimeTree request body format.
+      # @return [TimeTree::Activity]
+      # @raise [TimeTree::Error] if the event_id arg is empty.
+      # @raise [TimeTree::ApiError] if the http response status is not success.
+      # @since 1.0.0
+      def create_activity(event_id, params)
+        check_event_id event_id
+        check_access_token
+        res = http_cmd.post("/calendar/events/#{event_id}/activities", params)
+        raise ApiError.new(res) if res.status != 201
+
+        activity = to_model(res.body[:data])
+        activity.event_id = event_id
+        activity
+      end
+
+      def inspect
+        limit_info = nil
+        if defined?(@ratelimit_limit) && @ratelimit_limit
+          limit_info = " ratelimit:#{ratelimit_remaining}/#{ratelimit_limit}"
+        end
+        if defined?(@ratelimit_reset_at) && @ratelimit_reset_at
+          limit_info = "#{limit_info}, reset_at:#{ratelimit_reset_at.strftime('%m/%d %R')}"
+        end
+        "\#<#{self.class}:#{object_id}#{limit_info}>"
+      end
+
+    private
+
+      attr_reader :http_cmd, :access_token
+
+      def check_client_requirement
+        check_required_property(installation_id, 'installation_id')
+        check_required_property(application_id, 'application_id')
+      end
+
+      def check_access_token
+        return if access_token?
+
+        get_access_token
+      end
+
+      def access_token?
+        access_token && !access_token.expired?
+      end
+
+      def get_access_token
+        res = http_cmd.post("/installations/#{installation_id}/access_tokens") do |req|
+          req.headers['Authorization'] = "Bearer #{jwt}"
+        end
+        raise ApiError.new(res) if res.status != 200
+
+        @access_token = AccessToken.new(res.body[:access_token], res.body[:expire_at])
+        @token = access_token.token
+      end
+
+      def jwt
+        now = Time.now.to_i
+        payload = {
+          iat: now,
+          exp: now + (10 * 60), # JWT expires in 10 minutes
+          iss: application_id
+        }
+        JWT.encode(payload, private_key, 'RS256')
+      end
+    end
+  end
+end