nylas 5.17.0 → 6.0.0.beta.1

data/lib/nylas/handler/http_client.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "rest-client"
+
+require_relative "../errors"
+require_relative "../version"
+
+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 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 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)
+      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
+        end
+
+        begin
+          response = parse_response(response) if content_type == "application/json"
+        rescue Nylas::JsonParseError
+          handle_failed_response(result, response, path)
+          raise
+        end
+
+        handle_failed_response(result, response, path)
+        return response
+      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 [String, Hash, nil] Body to send with the request.
+    # @param timeout [Hash, 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 = 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
+
+      { method: method, url: url, payload: serialized_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"
+      }
+    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
+
+    # Handles failed responses from the Nylas API.
+    def handle_failed_response(result, response, path)
+      http_code = result.code.to_i
+
+      handle_anticipated_failure_mode(http_code, response, path)
+    end
+
+    # Handles anticipated failure states in the Nylas API.
+    def handle_anticipated_failure_mode(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
+        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
+    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?
+        uri = URI.parse(url)
+        query = custom_params(query)
+        params = URI.decode_www_form(uri.query || "") + query.to_a
+        uri.query = URI.encode_www_form(params)
+        url = uri.to_s
+      end
+
+      url
+    end
+
+    # Defines custom parameters for a metadata_pair query.
+    #
+    # @return [String] Custom parameter in "<key>:<value>" format.
+    def custom_params(query)
+      # Convert hash to "<key>:<value>" form for metadata_pair query.
+      if query.key?(:metadata_pair)
+        pairs = query[:metadata_pair].map do |key, value|
+          "#{key}:#{value}"
+        end
+        query[:metadata_pair] = pairs
+      end
+
+      query
+    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("applications", sdk_instance)
+      @redirect_uris = RedirectUris.new(sdk_instance)
+    end
+
+    # Gets the application object.
+    #
+    # @return [Array(Hash, String)] Application object and API Request ID.
+    def info
+      get(path: "#{api_uri}/v3/applications")
+    end
+  end
+end

data/lib/nylas/resources/auth.rb

@@ -0,0 +1,197 @@
+# 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
+
+    # 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.
+    # @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
+
+    # 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 [OpenStruct] 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.
+      OpenStruct.new(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)
+
+      query_params = build_query_with_admin_consent(config)
+      url.query = URI.encode_www_form(query_params)
+
+      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
+
+    private
+
+    # Builds the query with admin consent authentication for Microsoft.
+    #
+    # @param config [Hash] Configuration for the query.
+    # @return [Array(Hash, String)] Updated list of parameters, including those specific to admin
+    # consent.
+    def build_query_with_admin_consent(config)
+      params = build_query(config)
+
+      # Appends new params specific for admin consent.
+      params["response_type"] = "adminconsent"
+      params["credential_id"] = config["credentialId"]
+
+      params
+    end
+
+    # Builds the query with PKCE.
+    #
+    # @param config [Hash] Configuration for the query.
+    # @param secret_hash [Hash] Hashed secret.
+    # @return [Array(Hash, String)] Updated list of encoded parameters, including those specific
+    # to PKCE.
+    def build_query_with_pkce(config, secret_hash)
+      params = build_query(config)
+
+      # Appends new PKCE specific params.
+      params["code_challenge_method"] = "s256"
+      params["code_challenge"] = secret_hash
+
+      URI.encode_www_form(params)
+    end
+
+    # Builds the authentication URL.
+    #
+    # @param config [Hash] Configuration for the query.
+    # @return [Array(Hash, String)] List of components for the authentication URL.
+    def url_auth_builder(config)
+      builder = URI.parse(api_uri)
+      builder.path = "/v3/connect/auth"
+      builder.query = build_query(config)
+
+      builder
+    end
+
+    # Builds the query.
+    #
+    # @param config [Hash] Configuration for the query.
+    # @return [Array(Hash, String)] List of encoded parameters for the query.
+    def build_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]
+      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
+
+    # Hashes the secret for PKCE authentication.
+    #
+    # @param secret [String] Randomly-generated authentication secret.
+    # @return [Hash] Hashed authentication secret.
+    def hash_pkce_secret(secret)
+      Digest::SHA256.digest(secret).unpack1("H*")
+      Base64.strict_encode64(Digest::SHA256.digest(secret))
+    end
+
+    # Sends the token request to the Nylas API.
+    #
+    # @param request [Hash] Code exchange request.
+    def execute_token_request(request)
+      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,31 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "../handler/grants_api_operations"
+
+module Nylas
+  # Calendars
+  class Calendars < Resource
+    include GrantsApiOperations::Create
+    include GrantsApiOperations::Update
+    include GrantsApiOperations::List
+    include GrantsApiOperations::Destroy
+    include GrantsApiOperations::Find
+
+    # Initializes Calendars.
+    def initialize(sdk_instance)
+      super("calendars", sdk_instance)
+    end
+
+    # Checks multiple calendars to find available time slots for a single meeting.
+    #
+    # @param request_body [Hash, nil] Request body to pass to the request.
+    # @return [Array(Hash, String)] Availability object and API request ID.
+    def get_availability(request_body: nil)
+      post(
+        path: "#{api_uri}/v3/calendars/availability",
+        request_body: request_body
+      )
+    end
+  end
+end

data/lib/nylas/resources/events.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "../handler/grants_api_operations"
+
+module Nylas
+  # Events
+  class Events < Resource
+    include GrantsApiOperations::Create
+    include GrantsApiOperations::Update
+    include GrantsApiOperations::List
+    include GrantsApiOperations::Destroy
+    include GrantsApiOperations::Find
+
+    # Initializes Events.
+    def initialize(sdk_instance)
+      super("events", sdk_instance)
+    end
+  end
+end

data/lib/nylas/resources/grants.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "../handler/admin_api_operations"
+
+module Nylas
+  # Grants
+  class Grants < Resource
+    include AdminApiOperations::Create
+    include AdminApiOperations::Update
+    include AdminApiOperations::List
+    include AdminApiOperations::Destroy
+    include AdminApiOperations::Find
+
+    # Initializes Grants.
+    def initialize(sdk_instance)
+      super("grants", sdk_instance)
+    end
+  end
+end

data/lib/nylas/resources/redirect_uris.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "../handler/admin_api_operations"
+
+module Nylas
+  # Redirect URIs
+  class RedirectUris < Resource
+    include AdminApiOperations::Create
+    include AdminApiOperations::Update
+    include AdminApiOperations::List
+    include AdminApiOperations::Destroy
+    include AdminApiOperations::Find
+
+    # Initializes redirect URIs.
+    def initialize(sdk_instance)
+      super("applications/redirect-uris", sdk_instance)
+    end
+  end
+end

data/lib/nylas/resources/resource.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Nylas
+  # NOTE: BaseResource is the base class for all Nylas API resources.
+  class Resource
+    # Initializes a resource.
+    def initialize(resource_name, sdk_instance)
+      @resource_name = resource_name
+      @api_key = sdk_instance.api_key
+      @api_uri = sdk_instance.api_uri
+      @timeout = sdk_instance.timeout
+    end
+
+    private
+
+    attr_reader :resource_name, :api_key, :api_uri, :timeout
+  end
+end

data/lib/nylas/resources/webhooks.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "../handler/grants_api_operations"
+
+module Nylas
+  # Module representing the possible 'trigger' values in a Webhook.
+  # @see https://developer.nylas.com/docs/api#post/a/client_id/webhooks
+  module WebhookTrigger
+    CALENDAR_CREATED = "calendar.created"
+    CALENDAR_UPDATED = "calendar.updated"
+    CALENDAR_DELETED = "calendar.deleted"
+    EVENT_CREATED = "event.created"
+    EVENT_UPDATED = "event.updated"
+    EVENT_DELETED = "event.deleted"
+    GRANT_CREATED = "grant.created"
+    GRANT_UPDATED = "grant.updated"
+    GRANT_DELETED = "grant.deleted"
+    GRANT_EXPIRED = "grant.expired"
+    MESSAGE_SEND_SUCCESS = "message.send_success"
+    MESSAGE_SEND_FAILED = "message.send_failed"
+  end
+
+  # Webhooks
+  class Webhooks < Resource
+    include GrantsApiOperations::Create
+    include GrantsApiOperations::Update
+    include GrantsApiOperations::List
+    include GrantsApiOperations::Destroy
+    include GrantsApiOperations::Find
+
+    # Initializes webhooks.
+    def initialize(parent)
+      super("webhooks", parent)
+    end
+  end
+end

data/lib/nylas/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Nylas
-  VERSION = "5.17.0"
+  VERSION = "6.0.0.beta.1"
 end