nylas 5.17.0 → 6.0.3

data/lib/nylas/handler/http_client.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require "rest-client"
+
+require_relative "../errors"
+require_relative "../version"
+
+# Module for working with HTTP Client
+module Nylas
+  require "yajl"
+  require "base64"
+
+  # Plain HTTP client that can be used to interact with the Nylas API without any type casting.
+  module HttpClient
+    protected
+
+    attr_accessor :api_server
+    attr_writer :default_headers
+
+    # Sends a request to the Nylas API. Returns a successful response if the request succeeds, or a
+    # failed response if the request encounters a JSON parse error.
+    #
+    # @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 [Hash, nil] Body to send with the request.
+    # @param api_key [Hash, nil] API key to send with the request.
+    # @return [Object] Parsed JSON response from the API.
+    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)
+      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 RestClient::Exceptions::OpenTimeout, RestClient::Exceptions::ReadTimeout
+        raise Nylas::NylasSdkTimeoutError.new(request[:path], timeout)
+      end
+    end
+
+    # 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
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        raise Nylas::NylasSdkTimeoutError.new(request[:url], timeout)
+      end
+    end
+
+    # Builds a request sent to the Nylas API.
+    #
+    # @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.
+    # @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 [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.
+    def build_request(
+      method:, path: nil, headers: {}, query: {}, payload: nil, timeout: nil, api_key: nil
+    )
+      url = build_url(path, query)
+      resulting_headers = default_headers.merge(headers).merge(auth_header(api_key))
+      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: 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}"
+      }
+    end
+
+    # Parses the response from the Nylas API.
+    def parse_response(response)
+      return response if response.is_a?(Enumerable)
+
+      Yajl::Parser.new(symbolize_names: true).parse(response)
+    rescue Yajl::ParseError
+      raise Nylas::JsonParseError
+    end
+
+    private
+
+    # Sends a request to the Nylas REST API.
+    #
+    # @param method [Symbol] HTTP method for the API call. Either :get, :post, :delete, or :patch.
+    # @param url [String] URL for the API call.
+    # @param headers [Hash] HTTP headers to include in the payload.
+    # @param payload [String, Hash] Body to send with the request.
+    # @param timeout [Hash] Timeout value to send with the request.
+    def rest_client_execute(method:, url:, headers:, payload:, timeout:, &block)
+      ::RestClient::Request.execute(method: method, url: url, payload: payload,
+                                    headers: headers, timeout: timeout, &block)
+    end
+
+    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
+
+    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 failed responses from the Nylas API.
+    def handle_failed_response(http_code, response, path)
+      return if HTTP_SUCCESS_CODES.include?(http_code)
+
+      case response
+      when Hash
+        raise error_hash_to_exception(response, http_code, path)
+      else
+        raise NylasApiError.parse_error_response(response, http_code)
+      end
+    end
+
+    # Converts error hashes to exceptions.
+    def error_hash_to_exception(response, status_code, path)
+      return if !response || !response.key?(:error)
+
+      if %W[#{api_uri}/v3/connect/token #{api_uri}/v3/connect/revoke].include?(path)
+        NylasOAuthError.new(response[:error], response[:error_description], response[:error_uri],
+                            response[:error_code], status_code)
+      else
+        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.
+    # @param url [String] The base URL.
+    # @param query [Hash] The query parameters to add to the URL.
+    # @return [String] Processed URL, including query params.
+    def build_url(url, query = nil)
+      unless query.nil? || query.empty?
+        uri = URI.parse(url)
+        uri = build_query(uri, query)
+        url = uri.to_s
+      end
+
+      url
+    end
+
+    # Build the query string for a URI.
+    # @param uri [URI] URL to add the query to.
+    # @param query [Hash] The query params to include in the query.
+    # @return [URI] The URI object with the query parameters included.
+    def build_query(uri, query)
+      query.each do |key, value|
+        case value
+        when Array
+          value.each do |item|
+            qs = "#{URI.encode_www_form_component(key)}=#{URI.encode_www_form_component(item)}"
+            uri.query = [uri.query, qs].compact.join("&")
+          end
+        when Hash
+          value.each do |k, v|
+            qs = "#{URI.encode_www_form_component(key)}=#{URI.encode_www_form_component("#{k}:#{v}")}"
+            uri.query = [uri.query, qs].compact.join("&")
+          end
+        else
+          qs = "#{URI.encode_www_form_component(key)}=#{URI.encode_www_form_component(value)}"
+          uri.query = [uri.query, qs].compact.join("&")
+        end
+      end
+
+      uri
+    end
+
+    # Set the authorization header for an API query.
+    def auth_header(api_key)
+      { "Authorization" => "Bearer #{api_key}" }
+    end
+  end
+end

data/lib/nylas/resources/applications.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "redirect_uris"
+require_relative "../handler/api_operations"
+
+module Nylas
+  # Application
+  class Applications < Resource
+    include ApiOperations::Get
+
+    attr_reader :redirect_uris
+
+    # Initializes the application.
+    def initialize(sdk_instance)
+      super(sdk_instance)
+      @redirect_uris = RedirectUris.new(sdk_instance)
+    end
+
+    # Get application details.
+    #
+    # @return [Array(Hash, String)] Application details and API Request ID.
+    def get_details
+      get(path: "#{api_uri}/v3/applications")
+    end
+  end
+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

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "digest"
+require "base64"
+require "securerandom"
+require "ostruct"
+require "uri"
+
+require_relative "resource"
+require_relative "grants"
+require_relative "../handler/api_operations"
+
+module Nylas
+  # Auth
+  class Auth < Resource
+    include ApiOperations::Post
+    include ApiOperations::Get
+
+    # Builds the URL for authenticating users to your application with OAuth 2.0.
+    #
+    # @param config [Hash] Configuration for building the URL.
+    # @return [String] URL for hosted authentication.
+    def url_for_oauth2(config)
+      url_auth_builder(config).to_s
+    end
+
+    # Exchanges an authorization code for an access token.
+    #
+    # @param request [Hash] Code exchange request.
+    # @return [Hash] Token object.
+    def exchange_code_for_token(request)
+      request[:grant_type] = "authorization_code"
+
+      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.
+    # @return [Hash] Refreshed token object.
+    def refresh_access_token(request)
+      request[:grant_type] = "refresh_token"
+
+      execute_token_request(request)
+    end
+
+    # Builds the URL for authenticating users to your application with OAuth 2.0 and PKCE.
+    #   IMPORTANT: You must store the 'secret' returned to use it inside the CodeExchange flow.
+    #
+    # @param config [Hash] Configuration for building the URL.
+    # @return [Hash] URL for hosted authentication with the secret and the hashed secret.
+    def url_for_oauth2_pkce(config)
+      url = url_auth_builder(config)
+
+      # Generates a secret and hashes it.
+      secret = SecureRandom.uuid
+      secret_hash = hash_pkce_secret(secret)
+
+      # Adds code challenge to URL generation.
+      url.query = build_query_with_pkce(config, secret_hash)
+
+      # Returns the URL with secret and hashed secret.
+      { secret: secret, secret_hash: secret_hash, url: url.to_s }
+    end
+
+    # Builds the URL for admin consent authentication for Microsoft.
+    #
+    # @param config [Hash] Configuration for the authentication request.
+    # @return [String] URL for hosted authentication.
+    def url_for_admin_consent(config)
+      config_with_provider = config.merge("provider" => "microsoft")
+      url = url_auth_builder(config_with_provider)
+      url.query = build_query_with_admin_consent(config)
+
+      url.to_s
+    end
+
+    # Revokes a single access token.
+    #
+    # @param token [String] Access token to revoke.
+    # @return [Boolean] True if the access token was revoked successfully.
+    def revoke(token)
+      post(
+        path: "#{api_uri}/v3/connect/revoke",
+        query_params: {
+          token: token
+        }
+      )
+      true
+    end
+
+    # Detects the provider of an email address.
+    # @param params [Hash] Parameters to detect the provider.
+    # @return [Array(Hash, String)] Detected provider, if found and API Request ID.
+    def detect_provider(params)
+      post(
+        path: "#{api_uri}/v3/providers/detect",
+        query_params: params
+      )
+    end
+
+    private
+
+    # Builds the query with admin consent authentication for Microsoft.
+    #
+    # @param config [Hash] Configuration for the query.
+    # @return [String] Updated list of parameters, including those specific to admin
+    # consent.
+    def build_query_with_admin_consent(config)
+      params = build_http_query(config)
+
+      # Appends new params specific for admin consent.
+      params[:provider] = "microsoft"
+      params[:response_type] = "adminconsent"
+      params[:credential_id] = config[:credential_id] if config[:credential_id]
+
+      URI.encode_www_form(params).gsub("+", "%20")
+    end
+
+    # Builds the query with PKCE.
+    #
+    # @param config [Hash] Configuration for the query.
+    # @param secret_hash [Hash] Hashed secret.
+    # @return [String] Updated list of encoded parameters, including those specific
+    # to PKCE.
+    def build_query_with_pkce(config, secret_hash)
+      params = build_http_query(config)
+
+      # Appends new PKCE specific params.
+      params[:code_challenge_method] = "s256"
+      params[:code_challenge] = secret_hash
+
+      URI.encode_www_form(params).gsub("+", "%20")
+    end
+
+    # Builds the authentication URL.
+    #
+    # @param config [Hash] Configuration for the query.
+    # @return [URI] List of components for the authentication URL.
+    def url_auth_builder(config)
+      builder = URI.parse(api_uri)
+      builder.path = "/v3/connect/auth"
+      builder.query = URI.encode_www_form(build_http_query(config)).gsub(/\+/, "%20")
+
+      builder
+    end
+
+    # Builds the query.
+    #
+    # @param config [Hash] Configuration for the query.
+    # @return [Hash] List of parameters to encode in the query.
+    def build_http_query(config)
+      params = {
+        client_id: config[:client_id],
+        redirect_uri: config[:redirect_uri],
+        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
+    end
+
+    # Hash a plain text secret for use in PKCE.
+    #
+    # @param secret [String] The plain text secret to hash.
+    # @return [String] The hashed secret with base64 encoding (without padding).
+    def hash_pkce_secret(secret)
+      sha256_hash = Digest::SHA256.hexdigest(secret)
+      Base64.urlsafe_encode64(sha256_hash, padding: false)
+    end
+
+    # Sends the token request to the Nylas API.
+    #
+    # @param request [Hash] Code exchange request.
+    def execute_token_request(request)
+      request[:client_secret] = api_key if request[:client_secret].nil?
+
+      execute(
+        method: :post,
+        path: "#{api_uri}/v3/connect/token",
+        query: {},
+        payload: request,
+        headers: {},
+        api_key: api_key,
+        timeout: timeout
+      )
+    end
+  end
+end

data/lib/nylas/resources/calendars.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "../handler/api_operations"
+
+module Nylas
+  # Nylas Calendar API
+  class Calendars < Resource
+    include ApiOperations::Get
+    include ApiOperations::Post
+    include ApiOperations::Put
+    include ApiOperations::Delete
+
+    # Return all calendars.
+    #
+    # @param identifier [String] Grant ID or email account to query.
+    # @param query_params [Hash, nil] Query params to pass to the request.
+    # @return [Array(Array(Hash), String, String)] The list of calendars, API Request ID, and next cursor.
+    def list(identifier:, query_params: nil)
+      get_list(
+        path: "#{api_uri}/v3/grants/#{identifier}/calendars",
+        query_params: query_params
+      )
+    end
+
+    # Return a calendar.
+    #
+    # @param identifier [String] Grant ID or email account to query.
+    # @param calendar_id [String] The id of the calendar to return.
+    #   Use "primary" to refer to the primary calendar associated with grant.
+    # @return [Array(Hash, String)] The calendar and API request ID.
+    def find(identifier:, calendar_id:)
+      get(
+        path: "#{api_uri}/v3/grants/#{identifier}/calendars/#{calendar_id}"
+      )
+    end
+
+    # Create a calendar.
+    #
+    # @param identifier [String] Grant ID or email account in which to create the object.
+    # @param request_body [Hash] The values to create the calendar with.
+    # @return [Array(Hash, String)] The created calendar and API Request ID.
+    def create(identifier:, request_body:)
+      post(
+        path: "#{api_uri}/v3/grants/#{identifier}/calendars",
+        request_body: request_body
+      )
+    end
+
+    # Update a calendar.
+    #
+    # @param identifier [String] Grant ID or email account in which to update an object.
+    # @param calendar_id [String] The id of the calendar to update.
+    #   Use "primary" to refer to the primary calendar associated with grant.
+    # @param request_body [Hash] The values to update the calendar with
+    # @return [Array(Hash, String)] The updated calendar and API Request ID.
+    def update(identifier:, calendar_id:, request_body:)
+      put(
+        path: "#{api_uri}/v3/grants/#{identifier}/calendars/#{calendar_id}",
+        request_body: request_body
+      )
+    end
+
+    # Delete a calendar.
+    #
+    # @param identifier [String] Grant ID or email account from which to delete an object.
+    # @param calendar_id [String] The id of the calendar to delete.
+    #   Use "primary" to refer to the primary calendar associated with grant.
+    # @return [Array(TrueClass, String)] True and the API Request ID for the delete operation.
+    def destroy(identifier:, calendar_id:)
+      _, request_id = delete(
+        path: "#{api_uri}/v3/grants/#{identifier}/calendars/#{calendar_id}"
+      )
+
+      [true, request_id]
+    end
+
+    # Checks multiple calendars to find available time slots for a single meeting.
+    #
+    # @param request_body [Hash] Request body to pass to the request.
+    # @return [Array(Hash, String)] Availability object and API request ID.
+    def get_availability(request_body:)
+      post(
+        path: "#{api_uri}/v3/calendars/availability",
+        request_body: request_body
+      )
+    end
+
+    # Get the free/busy schedule for a list of email addresses.
+    #
+    # @param identifier [str] The identifier of the grant to act upon.
+    # @param request_body [Hash] Request body to pass to the request.
+    # @return [Array(Array(Hash), String)] The free/busy response.
+    def get_free_busy(identifier:, request_body:)
+      post(
+        path: "#{api_uri}/v3/grants/#{identifier}/calendars/free-busy",
+        request_body: request_body
+      )
+    end
+  end
+end