nylas 6.0.0.beta.1 → 6.0.0.beta.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8695c7d105dd1621576a1cc5dfa3bd2d7ff482d171763bf9273a3797cc320675
-  data.tar.gz: 88bda22c310af6c54061db72b6c19a5c4f8abed1e8e6a8518f4a4585d1ea6c38
+  metadata.gz: 5153fbe30a05d237c4e17da6ff51005ded6667ae710a50e349535079bfd5db91
+  data.tar.gz: 21e167b02e08cbf456ca45ffd94372fe6db8bf3fc7a1b5637ecf8bd5cde361bc
 SHA512:
-  metadata.gz: cc213a177a26c78864c48e678f6ff2d01cf9a3f29305cb2169b192018a531f3b5d106dab1fdfd350b323e1bbb69c4069ed13ec8ff5319742805c559077d52ac5
-  data.tar.gz: 2d51f8063938e335b00d9331f1beb9fb7c317c0af0954544c8ed40e3e4e14341452cdcf9be98a61ac4f9aae24d98eb0661434aea622a495fbd7f531d1293ec5c
+  metadata.gz: 232c65750e5e6027cf4414519be4e91a497c48b394d779ac2500af8bf82f3bf5317ecb1ec94261f80eb0cd46b373e88727c2aed65b036950f9d239a4276d313c
+  data.tar.gz: ccb50fddee574741f2baf36d4f44b46e246b219e0cb9d764d1ee2f1307cf8bf1a45aaec3a3bbe363f471b98ecc646fd60b79643ab730262308e9914a199b4719

data/lib/nylas/client.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 require_relative "resources/calendars"
+require_relative "resources/connectors"
+require_relative "resources/messages"
 require_relative "resources/events"
 require_relative "resources/auth"
 require_relative "resources/webhooks"
 require_relative "resources/applications"
+require_relative "resources/folders"
 
 module Nylas
   # Methods to retrieve data from the Nylas API as Ruby objects.
@@ -13,15 +16,15 @@ module Nylas
 
     # Initializes a client session.
     #
-    # @param api_key [Hash, nil] API key to use for the client session.
-    # @param api_uri [Hash] Client session's host.
-    # @param timeout [Hash, nil] Timeout value to use for the client session.
-    def initialize(api_key: nil,
+    # @param api_key [String, nil] API key to use for the client session.
+    # @param api_uri [String] Client session's host.
+    # @param timeout [String, nil] Timeout value to use for the client session.
+    def initialize(api_key:,
                    api_uri: Config::DEFAULT_REGION_URL,
                    timeout: nil)
       @api_key = api_key
       @api_uri = api_uri
-      @timeout = timeout
+      @timeout = timeout || 30
     end
 
     # The application resources for your Nylas application.
@@ -31,6 +34,20 @@ module Nylas
       Applications.new(self)
     end
 
+    # The attachments resources for your Nylas application.
+    #
+    # @return [Nylas::Attachments] Attachment resources for your Nylas application.
+    def attachments
+      Attachments.new(self)
+    end
+
+    # The auth resources for your Nylas application.
+    #
+    # @return [Nylas::Auth] Auth resources for your Nylas application.
+    def auth
+      Auth.new(self)
+    end
+
     # The calendar resources for your Nylas application.
     #
     # @return [Nylas::Calendars] Calendar resources for your Nylas application.
@@ -38,6 +55,27 @@ module Nylas
       Calendars.new(self)
     end
 
+    # The connector resources for your Nylas application.
+    #
+    # @return [Nylas::Connectors] Connector resources for your Nylas application.
+    def connectors
+      Connectors.new(self)
+    end
+
+    # The contact resources for your Nylas application.
+    #
+    # @return [Nylas::Contacts] Contact resources for your Nylas application.
+    def contacts
+      Contacts.new(self)
+    end
+
+    # The draft resources for your Nylas application.
+    #
+    # @return [Nylas::Drafts] Draft resources for your Nylas application.
+    def drafts
+      Drafts.new(self)
+    end
+
     # The event resources for your Nylas application.
     #
     # @return [Nylas::Events] Event resources for your Nylas application
@@ -45,11 +83,32 @@ module Nylas
       Events.new(self)
     end
 
-    # The auth resources for your Nylas application.
+    # The folder resources for your Nylas application.
     #
-    # @return [Nylas::Auth] Auth resources for your Nylas application.
-    def auth
-      Auth.new(self)
+    # @return [Nylas::Folder] Folder resources for your Nylas application
+    def folders
+      Folders.new(self)
+    end
+
+    # The grants resources for your Nylas application.
+    #
+    # @return [Nylas::Grants] Grant resources for your Nylas application
+    def grants
+      Grants.new(self)
+    end
+
+    # The message resources for your Nylas application.
+    #
+    # @return [Nylas::Messages] Message resources for your Nylas application
+    def messages
+      Messages.new(self)
+    end
+
+    # The thread resources for your Nylas application.
+    #
+    # @return [Nylas::Threads] Thread resources for your Nylas application.
+    def threads
+      Threads.new(self)
     end
 
     # The webhook resources for your Nylas application.

data/lib/nylas/errors.rb

@@ -3,17 +3,24 @@
 module Nylas
   Error = Class.new(::StandardError)
 
-  class JsonParseError < Error; end
+  # Base error class for API-related errors.
+  class AbstractNylasApiError < Error; end
 
-  # Base class to inflate the standard errors returned from the Nylas API.
-  class NylasApiError < Error
+  # Base error class for SDK-related errors.
+  class AbstractNylasSdkError < Error; end
+
+  # Error class representing a failed parse of a JSON response from the Nylas API.
+  class JsonParseError < AbstractNylasSdkError; end
+
+  # Error class representing a failed response from the Nylas API.
+  class NylasApiError < AbstractNylasApiError
     attr_accessor :type, :request_id, :provider_error, :status_code
 
     # Initializes an error and assigns the given attributes to it.
     #
     # @param type [Hash] Error type.
     # @param message [String] Error message.
-    # @param status_code [Hash] Error status code.
+    # @param status_code [Integer] Error status code.
     # @param provider_error [String, nil] Provider error.
     # @param request_id [Hash, nil] The ID of the request.
     def initialize(type, message, status_code, provider_error = nil, request_id = nil)
@@ -27,7 +34,7 @@ module Nylas
     # Parses the error response.
     #
     # @param response [Hash] Response from the Nylas API.
-    # @param status_code [String] Error status code.
+    # @param status_code [Integer] Error status code.
     def self.parse_error_response(response, status_code)
       new(
         response["type"],
@@ -38,17 +45,17 @@ module Nylas
     end
   end
 
-  # Base class to inflate the standard errors returned from the Nylas OAuth integration.
-  class NylasOAuthError < Error
+  # Error class representing a failed response from the Nylas OAuth integration.
+  class NylasOAuthError < AbstractNylasApiError
     attr_accessor :error, :error_description, :error_uri, :error_code, :status_code
 
     # Initializes an error and assigns the given attributes to it.
     #
-    # @param error [Hash] Error type.
+    # @param error [String] Error type.
     # @param error_description [String] Description of the error.
-    # @param error_uri [Hash] Error URI.
-    # @param error_code [Hash] Error code.
-    # @param status_code [Hash] Error status code.
+    # @param error_uri [String] Error URI.
+    # @param error_code [String] Error code.
+    # @param status_code [String] Error status code.
     def initialize(error, error_description, error_uri, error_code, status_code)
       super(error_description)
       self.error = error
@@ -59,5 +66,20 @@ module Nylas
     end
   end
 
+  # Error class representing a timeout from the Nylas SDK.
+  class NylasSdkTimeoutError < AbstractNylasSdkError
+    attr_accessor :url, :timeout
+
+    # Initializes an error and assigns the given attributes to it.
+    # @param url [String] URL that timed out.
+    # @param timeout [Integer] Timeout in seconds.
+    # @return [NylasSdkTimeoutError] The error object.
+    def initialize(url, timeout)
+      super("Nylas SDK timed out before receiving a response from the server.")
+      self.url = url
+      self.timeout = timeout
+    end
+  end
+
   HTTP_SUCCESS_CODES = [200, 201, 202, 302].freeze
 end

data/lib/nylas/handler/api_operations.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "http_client"
+
 module Nylas
   # Allows resources to perform API operations on the Nylas API endpoints without exposing the HTTP
   # client to the end user.
@@ -13,7 +15,7 @@ module Nylas
       #
       # @param path [String] Destination path for the call.
       # @param query_params [Hash, {}] Query params to pass to the call.
-      # @return [Array(Hash, String)] List of Nylas objects and API Request ID.
+      # @return Nylas data object and API Request ID.
       def get(path:, query_params: {})
         response = execute(
           method: :get,
@@ -39,7 +41,7 @@ module Nylas
       # @param query_params [Hash, {}] Query params to pass to the call.
       # @param request_body [String, Hash, nil] Request body to pass to the call.
       # @param headers [Hash, {}] Additional HTTP headers to include in the payload.
-      # @return [Array(Hash, String)] List of Nylas objects and API Request ID.
+      # @return Nylas data object and API Request ID.
       def post(path:, query_params: {}, request_body: nil, headers: {})
         response = execute(
           method: :post,
@@ -66,7 +68,7 @@ module Nylas
       # @param query_params [Hash, {}] Query params to pass to the call.
       # @param request_body [String, Hash, nil] Request body to pass to the call.
       # @param headers [Hash, {}] Additional HTTP headers to include in the payload.
-      # @return [Array(Hash, String)] List of Nylas objects and API Request ID.
+      # @return Nylas data object and API Request ID.
       def put(path:, query_params: {}, request_body: nil, headers: {})
         response = execute(
           method: :put,
@@ -93,7 +95,7 @@ module Nylas
       # @param query_params [Hash, {}] Query params to pass to the call.
       # @param request_body [String, Hash, nil] Request body to pass to the call.
       # @param headers [Hash, {}] Additional HTTP headers to include in the payload.
-      # @return [Array(Hash, String)] List of Nylas objects and API Request ID.
+      # @return Nylas data object and API Request ID.
       def patch(path:, query_params: {}, request_body: nil, headers: {})
         response = execute(
           method: :patch,
@@ -119,7 +121,7 @@ module Nylas
       # @param path [String] Destination path for the call.
       # @param query_params [Hash, {}] Query params to pass to the call.
       # @param headers [Hash, {}] Additional HTTP headers to include in the payload.
-      # @return [Array(Hash, String)] List of Nylas objects and API Request ID.
+      # @return Nylas data object and API Request ID.
       def delete(path:, query_params: {}, headers: {})
         response = execute(
           method: :delete,

data/lib/nylas/handler/http_client.rb

@@ -5,6 +5,7 @@ require "rest-client"
 require_relative "../errors"
 require_relative "../version"
 
+# Module for working with HTTP Client
 module Nylas
   require "yajl"
   require "base64"
@@ -22,32 +23,57 @@ module Nylas
     # @param method [Symbol] HTTP method for the API call. Either :get, :post, :delete, or :patch.
     # @param path [String, nil] Relative path from the API Base. This is the preferred way to execute
     # arbitrary or-not-yet-SDK-ified API commands.
+    # @param timeout [Integer, nil] Timeout value to send with the request.
     # @param headers [Hash, {}] Additional HTTP headers to include in the payload.
     # @param query [Hash, {}] Hash of names and values to include in the query section of the URI
     # fragment.
-    # @param payload [String, Hash, nil] Body to send with the request.
+    # @param payload [Hash, nil] Body to send with the request.
     # @param api_key [Hash, nil] API key to send with the request.
-    # @param timeout [Hash, nil] Timeout value to send with the request.
     # @return [Object] Parsed JSON response from the API.
-    def execute(method:, path: nil, headers: {}, query: {}, payload: nil, api_key: nil, timeout: nil)
+    def execute(method:, path:, timeout:, headers: {}, query: {}, payload: nil, api_key: nil)
       request = build_request(method: method, path: path, headers: headers,
                               query: query, payload: payload, api_key: api_key, timeout: timeout)
-      rest_client_execute(**request) do |response, _request, result|
-        content_type = nil
-
-        if response.headers && response.headers[:content_type]
-          content_type = response.headers[:content_type].downcase
+      begin
+        rest_client_execute(**request) do |response, _request, result|
+          content_type = nil
+          if response.headers && response.headers[:content_type]
+            content_type = response.headers[:content_type].downcase
+          end
+
+          parse_json_evaluate_error(result.code.to_i, response, path, content_type)
         end
+      rescue Timeout::Error => _e
+        raise Nylas::NylasSdkTimeoutError.new(request.path, timeout)
+      end
+    end
 
-        begin
-          response = parse_response(response) if content_type == "application/json"
-        rescue Nylas::JsonParseError
-          handle_failed_response(result, response, path)
-          raise
+    # Sends a request to the Nylas API, specifically for downloading data.
+    # This method supports streaming the response by passing a block, which will be executed
+    # with each chunk of the response body as it is read. If no block is provided, the entire
+    # response body is returned.
+    #
+    # @param path [String] Relative path from the API Base. This is the preferred way to execute
+    # arbitrary or-not-yet-SDK-ified API commands.
+    # @param timeout [Integer] Timeout value to send with the request.
+    # @param headers [Hash, {}] Additional HTTP headers to include in the payload.
+    # @param query [Hash, {}] Hash of names and values to include in the query section of the URI
+    # fragment.
+    # @param api_key [Hash, nil] API key to send with the request.
+    # @yieldparam chunk [String] A chunk of the response body.
+    # @return [nil, String] Returns nil when a block is given (streaming mode).
+    #     When no block is provided, the return is the entire raw response body.
+    def download_request(path:, timeout:, headers: {}, query: {}, api_key: nil, &block)
+      request, uri, http = setup_http(path, timeout, headers, query, api_key)
+
+      begin
+        http.start do |setup_http|
+          get_request = Net::HTTP::Get.new(uri)
+          request[:headers].each { |key, value| get_request[key] = value }
+
+          handle_response(setup_http, get_request, path, &block)
         end
-
-        handle_failed_response(result, response, path)
-        return response
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        raise Nylas::NylasSdkTimeoutError.new(request[:url], timeout)
       end
     end
 
@@ -58,8 +84,8 @@ module Nylas
     # @param headers [Hash, {}] Additional HTTP headers to include in the payload.
     # @param query [Hash, {}] Hash of names and values to include in the query section of the URI
     # fragment.
-    # @param payload [String, Hash, nil] Body to send with the request.
-    # @param timeout [Hash, nil] Timeout value to send with the request.
+    # @param payload [Hash, nil] Body to send with the request.
+    # @param timeout [Integer, nil] Timeout value to send with the request.
     # @param api_key [Hash, nil] API key to send with the request.
     # @return [Object] The request information after processing. This includes an updated payload
     # and headers.
@@ -69,17 +95,21 @@ module Nylas
       url = path
       url = add_query_params_to_url(url, query)
       resulting_headers = default_headers.merge(headers).merge(auth_header(api_key))
-      serialized_payload = payload&.to_json
+      if !payload.nil? && !payload["multipart"]
+        payload = payload&.to_json
+        resulting_headers["Content-type"] = "application/json"
+      elsif !payload.nil? && payload["multipart"]
+        payload.delete("multipart")
+      end
 
-      { method: method, url: url, payload: serialized_payload, headers: resulting_headers, timeout: timeout }
+      { method: method, url: url, payload: payload, headers: resulting_headers, timeout: timeout }
     end
 
     # Sets the default headers for API requests.
     def default_headers
       @default_headers ||= {
         "X-Nylas-API-Wrapper" => "ruby",
-        "User-Agent" => "Nylas Ruby SDK #{Nylas::VERSION} - #{RUBY_VERSION}",
-        "Content-type" => "application/json"
+        "User-Agent" => "Nylas Ruby SDK #{Nylas::VERSION} - #{RUBY_VERSION}"
       }
     end
 
@@ -106,15 +136,45 @@ module Nylas
                                     headers: headers, timeout: timeout, &block)
     end
 
-    # Handles failed responses from the Nylas API.
-    def handle_failed_response(result, response, path)
-      http_code = result.code.to_i
+    def setup_http(path, timeout, headers, query, api_key)
+      request = build_request(method: :get, path: path, headers: headers,
+                              query: query, api_key: api_key, timeout: timeout)
+      uri = URI(request[:url])
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.read_timeout = timeout
+      http.open_timeout = timeout
+      [request, uri, http]
+    end
 
-      handle_anticipated_failure_mode(http_code, response, path)
+    def handle_response(http, get_request, path, &block)
+      http.request(get_request) do |response|
+        if response.is_a?(Net::HTTPSuccess)
+          return response.body unless block_given?
+
+          response.read_body(&block)
+        else
+          parse_json_evaluate_error(response.code.to_i, response.body, path, response["Content-Type"])
+          break
+        end
+      end
+    end
+
+    # Parses the response from the Nylas API and evaluates for errors.
+    def parse_json_evaluate_error(http_code, response, path, content_type = nil)
+      begin
+        response = parse_response(response) if content_type == "application/json"
+      rescue Nylas::JsonParseError
+        handle_failed_response(http_code, response, path)
+        raise
+      end
+
+      handle_failed_response(http_code, response, path)
+      response
     end
 
-    # Handles anticipated failure states in the Nylas API.
-    def handle_anticipated_failure_mode(http_code, response, path)
+    # Handles failed responses from the Nylas API.
+    def handle_failed_response(http_code, response, path)
       return if HTTP_SUCCESS_CODES.include?(http_code)
 
       case response
@@ -133,19 +193,23 @@ module Nylas
         NylasOAuthError.new(response[:error], response[:error_description], response[:error_uri],
                             response[:error_code], status_code)
       else
-        error_obj = response[:error]
-        provider_error = error_obj.fetch(:provider_error, nil)
-
-        NylasApiError.new(error_obj[:type], error_obj[:message], status_code, provider_error,
-                          response[:request_id])
+        throw_error(response, status_code)
       end
     end
 
+    def throw_error(response, status_code)
+      error_obj = response[:error]
+      provider_error = error_obj.fetch(:provider_error, nil)
+
+      NylasApiError.new(error_obj[:type], error_obj[:message], status_code, provider_error,
+                        response[:request_id])
+    end
+
     # Adds query parameters to a URL.
     #
     # @return [String] Processed URL, including query params.
     def add_query_params_to_url(url, query)
-      unless query.empty?
+      unless query.nil? || query.empty?
         uri = URI.parse(url)
         query = custom_params(query)
         params = URI.decode_www_form(uri.query || "") + query.to_a

data/lib/nylas/resources/applications.rb

@@ -13,7 +13,7 @@ module Nylas
 
     # Initializes the application.
     def initialize(sdk_instance)
-      super("applications", sdk_instance)
+      super(sdk_instance)
       @redirect_uris = RedirectUris.new(sdk_instance)
     end
 

data/lib/nylas/resources/attachments.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "../handler/api_operations"
+
+module Nylas
+  # Nylas Attachment API
+  class Attachments < Resource
+    include ApiOperations::Get
+
+    # Return metadata of an attachment.
+    #
+    # @param identifier [String] Grant ID or email account to query.
+    # @param attachment_id [String] The id of the attachment to retrieve.
+    # @param query_params [Hash] The query parameters to include in the request.
+    # @return [Array(Hash, String)] The attachment and API request ID.
+    def find(identifier:, attachment_id:, query_params:)
+      get(
+        path: "#{api_uri}/v3/grants/#{identifier}/attachments/#{attachment_id}",
+        query_params: query_params
+      )
+    end
+
+    # Download the attachment data.
+    #
+    # This method supports streaming the download by passing a block, which will
+    # be called with each chunk of the response body as it is read. If no block
+    # is given, the entire response will be read into memory and returned (not recommended
+    # for large files).
+    #
+    # @param identifier [String] Grant ID or email account to query.
+    # @param attachment_id [String] The ID of the attachment to be downloaded.
+    # @param query_params [Hash] The query parameters to include in the request.
+    # @yieldparam chunk [String] A chunk of the response body.
+    # @return [nil, String] Returns nil when a block is given (streaming mode).
+    #   When no block is provided, the return is the entire raw response body.
+    def download(identifier:, attachment_id:, query_params:, &block)
+      download_request(
+        path: "#{api_uri}/v3/grants/#{identifier}/attachments/#{attachment_id}/download",
+        query: query_params,
+        api_key: api_key,
+        timeout: timeout,
+        &block
+      )
+    end
+
+    # Download the attachment as a byte array.
+    #
+    # @param identifier [String] Grant ID or email account to query.
+    # @param attachment_id [String] The ID of the attachment to be downloaded.
+    # @param query_params [Hash] The query parameters to include in the request.
+    # @return [nil, Array(Integer)] Returns nil when a block is given (streaming mode).
+    #   When no block is provided, the return is the entire raw response body.
+    def download_bytes(identifier:, attachment_id:, query_params:)
+      data = download_request(
+        path: "#{api_uri}/v3/grants/#{identifier}/attachments/#{attachment_id}/download",
+        query: query_params,
+        api_key: api_key,
+        timeout: timeout
+      )
+
+      data&.bytes
+    end
+  end
+end

data/lib/nylas/resources/auth.rb

@@ -16,15 +16,6 @@ module Nylas
     include ApiOperations::Post
     include ApiOperations::Get
 
-    # Initializes Auth.
-    def initialize(sdk_instance)
-      super("auth", sdk_instance)
-
-      @grants = Grants.new(sdk_instance)
-    end
-
-    attr_reader :grants
-
     # Builds the URL for authenticating users to your application with OAuth 2.0.
     #
     # @param config [Hash] Configuration for building the URL.
@@ -43,6 +34,17 @@ module Nylas
       execute_token_request(request)
     end
 
+    # Create a Grant via Custom Authentication.
+    #
+    # @param request_body [Hash] The values to create the Grant with.
+    # @return [Array(Hash, String)] Created grant and API Request ID.
+    def custom_authentication(request_body)
+      post(
+        path: "#{api_uri}/v3/connect/custom",
+        request_body: request_body
+      )
+    end
+
     # Refreshes an access token.
     #
     # @param request [Hash] Code exchange request.
@@ -156,16 +158,15 @@ module Nylas
         "access_type" => config[:access_type] || "online",
         "response_type" => "code"
       }
-
       params["provider"] = config[:provider] if config[:provider]
+      params["prompt"] = config[:prompt] if config[:prompt]
+      params["metadata"] = config[:metadata] if config[:metadata]
+      params["state"] = config[:state] if config[:state]
+      params["scope"] = config[:scope].join(" ") if config[:scope]
       if config[:login_hint]
         params["login_hint"] = config[:login_hint]
         params["include_grant_scopes"] = config[:include_grant_scopes].to_s if config[:include_grant_scopes]
       end
-      params["scope"] = config[:scope].join(" ") if config[:scope]
-      params["prompt"] = config[:prompt] if config[:prompt]
-      params["metadata"] = config[:metadata] if config[:metadata]
-      params["state"] = config[:state] if config[:state]
 
       URI.encode_www_form(params)
     end