nylas 3.2.0 → 4.0.0.rc2

data/lib/nylas/collection.rb

@@ -0,0 +1,110 @@
+module Nylas
+  # An enumerable for working with index and search endpoints
+  class Collection
+    attr_accessor :model, :api, :constraints
+    def initialize(model:, api:, constraints: nil)
+      self.constraints = Constraints.from_constraints(constraints)
+      self.model = model
+      self.api = api
+    end
+
+    def new(**attributes)
+      model.from_hash(attributes, api: api)
+    end
+
+    def create(**attributes)
+      model.raise_if_read_only
+      instance = model.from_hash(attributes, api: api)
+      instance.save
+      instance
+    end
+
+    def where(filters)
+      raise NotImplementedError, "#{model} does not support search" unless model.searchable?
+      self.class.new(model: model, api: api, constraints: constraints.merge(where: filters))
+    end
+
+    def count
+      self.class.new(model: model, api: api, constraints: constraints.merge(view: "count")).execute[:count]
+    end
+
+    def first
+      model.from_hash(execute.first, api: api)
+    end
+
+    def[](index)
+      model.from_hash(execute(index), api: api)
+    end
+
+    # Iterates over a single page of results based upon current pagination settings
+    def each
+      return enum_for(:each) unless block_given?
+      execute.each do |result|
+        yield(model.from_hash(result, api: api))
+      end
+    end
+
+    def to_a
+      each.to_a
+    end
+
+    def map(&block)
+      each.map(&block)
+    end
+
+    def limit(quantity)
+      self.class.new(model: model, api: api, constraints: constraints.merge(limit: quantity))
+    end
+
+    def offset(start)
+      self.class.new(model: model, api: api, constraints: constraints.merge(offset: start))
+    end
+
+    # Iterates over every result that meets the filters, retrieving a page at a time
+    def find_each
+      return enum_for(:find_each) unless block_given?
+      query = self
+      accumulated = 0
+
+      while query
+        results = query.each do |instance|
+          yield(instance)
+        end
+
+        accumulated += results.length
+        query = query.next_page(accumulated: accumulated, current_page: results)
+      end
+    end
+
+    def next_page(accumulated: nil, current_page: nil)
+      return nil unless more_pages?(accumulated, current_page)
+      self.class.new(model: model, api: api, constraints: constraints.next_page)
+    end
+
+    def more_pages?(accumulated, current_page)
+      return false if current_page.empty?
+      return false if constraints.limit && accumulated >= constraints.limit
+      return false if constraints.per_page && current_page.length < constraints.per_page
+      true
+    end
+
+    # Retrieves a record. Nylas doesn't support where filters on GET so this will not take into
+    # consideration other query constraints, such as where clauses.
+    def find(id)
+      instance = model.from_hash({ id: id }, api: api)
+      instance.reload
+      instance
+    end
+
+    # @return [Hash] Specification for request to be passed to {API#execute}
+    def to_be_executed
+      { method: :get, path: model.resources_path, query: constraints.to_query }
+    end
+
+    # Retrieves the data from the API for the particular constraints
+    # @return [Hash,Array]
+    def execute
+      api.execute(to_be_executed)
+    end
+  end
+end

data/lib/nylas/constraints.rb

@@ -0,0 +1,46 @@
+module Nylas
+  # The constraints a particular GET request will include in their query params
+  class Constraints
+    attr_accessor :where, :limit, :offset, :view, :per_page
+    def initialize(where: {}, limit: nil, offset: 0, view: nil, per_page: 100)
+      self.where = where
+      self.limit = limit
+      self.offset = offset
+      self.view = view
+      self.per_page = per_page
+    end
+
+    def merge(where: {}, limit: nil, offset: nil, view: nil, per_page: nil)
+      Constraints.new(where: where.merge(where),
+                      limit: limit || self.limit,
+                      per_page: per_page || self.per_page,
+                      offset: offset || self.offset,
+                      view: view || self.view)
+    end
+
+    def next_page
+      merge(offset: offset + per_page)
+    end
+
+    def to_query
+      query = where.each_with_object({}) do |(name, value), result|
+        result[name] = value
+      end
+      query[:limit] = limit_for_query
+      query[:offset] = offset unless offset.nil?
+      query[:view] = view unless view.nil?
+      query
+    end
+
+    def limit_for_query
+      !limit.nil? && limit < per_page ? limit : per_page
+    end
+
+    def self.from_constraints(constraints = Constraints.new)
+      return constraints if constraints.is_a?(Constraints)
+      return new(**constraints) if constraints.respond_to?(:key?)
+      return new if constraints.nil?
+      raise TypeError, "passed in constraints #{constraints} cannot be cast to a set of constraints"
+    end
+  end
+end

data/lib/nylas/contact.rb

@@ -0,0 +1,30 @@
+module Nylas
+  # ActiveModel compliant interface for interacting with the Contacts API
+  # @see https://docs.nylas.com/reference#contacts
+  class Contact
+    include Model
+    self.resources_path = "/contacts"
+
+    attribute :id, :string, exclude_when: %i(creating updating)
+    attribute :object, :string, default: "contact"
+    attribute :account_id, :string, exclude_when: %i(creating updating)
+    attribute :given_name, :string
+    attribute :middle_name, :string
+    attribute :surname, :string
+    attribute :birthday, :nylas_date
+    attribute :suffix, :string
+    attribute :nickname, :string
+    attribute :company_name, :string
+    attribute :job_title, :string
+    attribute :manager_name, :string
+    attribute :office_location, :string
+    attribute :notes, :string
+    attribute :web_page, :web_page
+
+    has_n_of_attribute :email_addresses, :email_address
+    has_n_of_attribute :im_addresses, :im_address
+    has_n_of_attribute :physical_addresses, :physical_address
+    has_n_of_attribute :phone_numbers, :phone_number
+    has_n_of_attribute :web_pages, :web_page
+  end
+end

data/lib/nylas/current_account.rb

@@ -0,0 +1,23 @@
+module Nylas
+  # Ruby representation of the Nylas /account API
+  # @see https://docs.nylas.com/reference#account
+  class CurrentAccount
+    include Model
+
+    self.read_only = true
+    self.searchable = false
+    self.collectionable = false
+
+    self.resources_path = "/account"
+
+    attribute :id, :string
+    attribute :object, :string, default: "account"
+
+    attribute :account_id, :string
+    attribute :email_address, :string
+    attribute :name, :string
+    attribute :organization_unit, :string
+    attribute :provider, :string
+    attribute :sync_state, :string
+  end
+end

data/lib/nylas/email_address.rb

@@ -0,0 +1,14 @@
+module Nylas
+  # Structure to represent the Email Address Schema
+  # @see https://docs.nylas.com/reference#contactsid
+  class EmailAddress
+    include Model::Attributable
+    attribute :type, :string
+    attribute :email, :string
+  end
+
+  # Serializes, Deserializes between {EmailAddress} objects and a {Hash}
+  class EmailAddressType < Types::HashType
+    casts_to EmailAddress
+  end
+end

data/lib/nylas/errors.rb

@@ -0,0 +1,36 @@
+module Nylas
+  Error = Class.new(::StandardError)
+
+  # Indicates that a given method needs an access token to work.
+  class NoAuthToken < Error
+    def initialize(method_name)
+      super "No access token was provided and the #{method_name} method requires one"
+    end
+  end
+
+  UnexpectedAccountAction = Class.new(Error)
+  UnexpectedResponse = Class.new(Error)
+
+  # Base class to inflate the standard errors returned from the Nylas API
+  class APIError < Error
+    attr_accessor :type
+    attr_accessor :message
+    attr_accessor :server_error
+
+    def initialize(type, message, server_error = nil)
+      super(message)
+      self.type = type
+      self.message = message
+      self.server_error = server_error
+    end
+  end
+  AccessDenied = Class.new(APIError)
+  ResourceNotFound = Class.new(APIError)
+  InvalidRequest = Class.new(APIError)
+  MessageRejected = Class.new(APIError)
+  SendingQuotaExceeded = Class.new(APIError)
+  ServiceUnavailable = Class.new(APIError)
+  BadGateway = Class.new(APIError)
+  InternalError = Class.new(APIError)
+  MailProviderError = Class.new(APIError)
+end

data/lib/nylas/http_client.rb

@@ -0,0 +1,135 @@
+module Nylas
+  # Plain HTTP client that can be used to interact with the Nylas API sans any type casting.
+  class HttpClient
+    HTTP_CODE_TO_EXCEPTIONS = {
+      400 => InvalidRequest,
+      402 => MessageRejected,
+      403 => AccessDenied,
+      404 => ResourceNotFound,
+      422 => MailProviderError,
+      429 => SendingQuotaExceeded,
+      500 => InternalError,
+      502 => BadGateway,
+      503 => ServiceUnavailable
+    }.freeze
+
+    include Logging
+    attr_accessor :api_server, :default_headers
+    attr_reader :access_token
+    attr_reader :app_id
+    attr_reader :app_secret
+
+    # @param app_id [String] Your application id from the Nylas Dashboard
+    # @param app_secret [String] Your application secret from the Nylas Dashboard
+    # @param access_token [String] (Optional) Your users access token.
+    # @param api_server [String] (Optional) Which Nylas API Server to connect to. Only change this if
+    #                            you're using a self-hosted Nylas instance.
+    # @param service_domain [String] (Optional) Host you are authenticating OAuth against.
+    # @return [Nylas::API]
+    def initialize(app_id:, app_secret:, access_token: nil, api_server: "https://api.nylas.com",
+                   service_domain: "api.nylas.com")
+      unless api_server.include?("://")
+        raise "When overriding the Nylas API server address, you must include https://"
+      end
+      @api_server = api_server
+      @access_token = access_token
+      @app_secret = app_secret
+      @app_id = app_id
+      @service_domain = service_domain
+    end
+
+    # Sends a request to the Nylas API and rai
+    # @param method [Symbol] HTTP method for the API call. Either :get, :post, :delete, or :patch
+    # @param url [String] (Optional, defaults to nil) - Full URL to access. Deprecated and will be removed in
+    #                     5.0.
+    # @param path [String] (Optional, defaults to nil) - Relative path from the API Base. Preferred way to
+    #                      execute arbitrary or-not-yet-SDK-ified API commands.
+    # @param headers [Hash] (Optional, defaults to {}) - Additional HTTP headers to include in the payload.
+    # @param query [Hash] (Optional, defaults to {}) - Hash of names and values to include in the query
+    #                      section of the URI fragment
+    # @param payload [String,Hash] (Optional, defaults to nil) - Body to send with the request.
+    # @return [Array Hash Stringn]
+    # rubocop:disable Metrics/ParameterLists
+    def execute(method:, url: nil, path: nil, headers: {}, query: {}, payload: nil)
+      headers[:params] = query
+      url ||= url_for_path(path)
+      resulting_headers = default_headers.merge(headers)
+      rest_client_execute(method: method, url: url, payload: payload,
+                          headers: resulting_headers) do |response, _request, result|
+
+        response = parse_response(response)
+        handle_failed_response(result: result, response: response)
+        response
+      end
+    end
+    # rubocop:enable Metrics/ParameterLists
+    inform_on :execute, level: :debug,
+                        also_log: { result: true, values: %i(method url path headers query payload) }
+
+    # Syntactical sugar for making GET requests via the API.
+    # @see #execute
+    def get(path: nil, url: nil, headers: {}, query: {})
+      execute(method: :get, path: path, query: query, url: url, headers: headers)
+    end
+
+    # Syntactical sugar for making POST requests via the API.
+    # @see #execute
+    def post(path: nil, url: nil, payload: nil, headers: {}, query: {})
+      execute(method: :post, path: path, url: url, headers: headers, query: query, payload: payload)
+    end
+
+    # Syntactical sugar for making PUT requests via the API.
+    # @see #execute
+    def put(path: nil, url: nil, payload:, headers: {}, query: {})
+      execute(method: :put, path: path, url: url, headers: headers, query: query, payload: payload)
+    end
+
+    # Syntactical sugar for making DELETE requests via the API.
+    # @see #execute
+    def delete(path: nil, url: nil, payload: nil, headers: {}, query: {})
+      execute(method: :delete, path: path, url: url, headers: headers, query: query, payload: payload)
+    end
+    # rubocop:enable Metrics/ParameterList
+
+    private def rest_client_execute(method:, url:, headers:, payload:, &block)
+      ::RestClient::Request.execute(method: method, url: url, payload: payload,
+                                    headers: headers, &block)
+    end
+    inform_on :rest_client_execute, level: :debug,
+                                    also_log: { result: true, values: %i(method url headers payload) }
+
+    def default_headers
+      @default_headers ||= {
+        "X-Nylas-API-Wrapper" => "ruby",
+        "User-Agent" => "Nylas Ruby SDK #{Nylas::VERSION} - #{RUBY_VERSION}",
+        "Content-types" => "application/json"
+      }
+    end
+
+    private def parse_response(response)
+      response.is_a?(Enumerable) ? response : JSON.parse(response, symbolize_names: true)
+    rescue JSON::ParserError
+      response
+    end
+
+    private def url_for_path(path)
+      raise NoAuthToken if @access_token.nil? && (!@app_secret.nil? || !@app_id.nil?)
+      protocol, domain = @api_server.split("//")
+      "#{protocol}//#{@access_token}:@#{domain}#{path}"
+    end
+
+    private def handle_failed_response(result:, response:)
+      http_code = result.code.to_i
+
+      handle_anticipated_failure_mode(http_code: http_code, response: response)
+      raise UnexpectedResponse, result.msg if result.is_a?(Net::HTTPClientError)
+    end
+
+    private def handle_anticipated_failure_mode(http_code:, response:)
+      return if http_code == 200
+      return unless response.is_a?(Hash)
+      exception = HTTP_CODE_TO_EXCEPTIONS.fetch(http_code, APIError)
+      raise exception.new(response["type"], response["message"], response.fetch("server_error", nil))
+    end
+  end
+end

data/lib/nylas/im_address.rb

@@ -0,0 +1,14 @@
+module Nylas
+  # Structure to represent the IM Address Schema
+  # @see https://docs.nylas.com/reference#contactsid
+  class IMAddress
+    include Model::Attributable
+    attribute :type, :string
+    attribute :im_address, :string
+  end
+
+  # Serializes, Deserializes between {IMAddress} objects and their JSON representation
+  class IMAddressType < Types::HashType
+    casts_to IMAddress
+  end
+end

data/lib/nylas/logging.rb

@@ -0,0 +1,41 @@
+# We are explicitely choosing to allow clients to use or not use informed at their discretion
+# rubocop:disable Lint/HandleExceptions
+begin
+  require "informed"
+rescue LoadError
+end
+# rubocop:enable Lint/HandleExceptions
+
+module Nylas
+  # Exposes a shared logger for debugging purposes
+  module Logging
+    def self.included(object)
+      if const_defined? :Informed
+        object.include Informed
+        Informed.logger = logger
+      else
+        object.extend NoOpInformOn
+      end
+    end
+
+    def self.logger
+      return @logger if @logger
+      @logger = Logger.new(STDOUT)
+      @logger.level = level
+      @logger
+    end
+
+    def self.level
+      Logger.const_get(ENV["NYLAS_LOG_LEVEL"] || :WARN)
+    end
+
+    def self.logger=(logger)
+      @logger = logger
+    end
+
+    # No op for inform_on if user does not have the informed gem installed.
+    module NoOpInformOn
+      def inform_on(method, level: :debug, also_log: {}); end
+    end
+  end
+end