nylas_v2 5.14.2

data/lib/nylas_v2/http_client.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+module NylasV2
+  require "yajl"
+  require "base64"
+
+  # Plain HTTP client that can be used to interact with the Nylas API sans any type casting.
+  class HttpClient
+    module AuthMethod
+      BEARER = 1
+      BASIC = 2
+    end
+
+    HTTP_SUCCESS_CODES = [200, 201, 202, 302].freeze
+
+    HTTP_CODE_TO_EXCEPTIONS = {
+      400 => InvalidRequest,
+      401 => UnauthorizedRequest,
+      402 => MessageRejected,
+      403 => AccessDenied,
+      404 => ResourceNotFound,
+      405 => MethodNotAllowed,
+      410 => ResourceRemoved,
+      418 => TeapotError,
+      422 => MailProviderError,
+      429 => SendingQuotaExceeded,
+      500 => InternalError,
+      501 => EndpointNotYetImplemented,
+      502 => BadGateway,
+      503 => ServiceUnavailable,
+      504 => RequestTimedOut
+    }.freeze
+
+    ENDPOINT_TIMEOUTS = {
+      "/oauth/authorize" => 345,
+      "/messages/search" => 350,
+      "/threads/search" => 350,
+      "/delta" => 3650,
+      "/delta/longpoll" => 3650,
+      "/delta/streaming" => 3650
+    }.freeze
+
+    SUPPORTED_API_VERSION = "2.5"
+
+    include Logging
+    attr_accessor :api_server
+    attr_writer :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.
+    # @return [NylasV2::HttpClient]
+    def initialize(app_id:, app_secret:, access_token: nil, api_server: "https://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
+    end
+
+    # @return [NylasV2::HttpClient[]
+    def as(access_token)
+      HttpClient.new(app_id: app_id, access_token: access_token,
+                     app_secret: app_secret, api_server: api_server)
+    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 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.
+    # @param auth_method [AuthMethod] (Optional, defaults to BEARER) - The authentication method.
+    # @return [Array Hash Stringn]
+    # rubocop:disable Metrics/MethodLength
+    def execute(method:, path: nil, headers: {}, query: {}, payload: nil, auth_method: nil)
+      timeout = ENDPOINT_TIMEOUTS.fetch(path, 230)
+      request = build_request(
+        method: method,
+        path: path,
+        headers: headers,
+        query: query,
+        payload: payload,
+        timeout: timeout,
+        auth_method: auth_method || AuthMethod::BEARER
+      )
+      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 NylasV2::JsonParseError
+          handle_failed_response(result: result, response: response)
+          raise
+        end
+
+        handle_failed_response(result: result, response: response)
+        response
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+    inform_on :execute, level: :debug,
+                        also_log: { result: true, values: %i[method url path headers query payload] }
+
+    def build_request(
+      method:,
+      path: nil,
+      headers: {},
+      query: {},
+      payload: nil,
+      timeout: nil,
+      auth_method: nil
+    )
+      url ||= url_for_path(path)
+      url = add_query_params_to_url(url, query)
+      resulting_headers = default_headers.merge(headers).merge(auth_header(auth_method))
+      { method: method, url: url, payload: payload, headers: resulting_headers, timeout: timeout }
+    end
+
+    # Syntactical sugar for making GET requests via the API.
+    # @see #execute
+    def get(path: nil, headers: {}, query: {}, auth_method: nil)
+      execute(method: :get, path: path, query: query, headers: headers, auth_method: auth_method)
+    end
+
+    # Syntactical sugar for making POST requests via the API.
+    # @see #execute
+    def post(path: nil, payload: nil, headers: {}, query: {}, auth_method: nil)
+      execute(
+        method: :post,
+        path: path,
+        headers: headers,
+        query: query,
+        payload: payload,
+        auth_method: auth_method
+      )
+    end
+
+    # Syntactical sugar for making PUT requests via the API.
+    # @see #execute
+    def put(path: nil, payload:, headers: {}, query: {}, auth_method: nil)
+      execute(
+        method: :put,
+        path: path,
+        headers: headers,
+        query: query,
+        payload: payload,
+        auth_method: auth_method
+      )
+    end
+
+    # Syntactical sugar for making DELETE requests via the API.
+    # @see #execute
+    def delete(path: nil, payload: nil, headers: {}, query: {}, auth_method: nil)
+      execute(
+        method: :delete,
+        path: path,
+        headers: headers,
+        query: query,
+        payload: payload,
+        auth_method: auth_method
+      )
+    end
+
+    def default_headers
+      @default_headers ||= {
+        "X-Nylas-API-Wrapper" => "ruby",
+        "X-Nylas-Client-Id" => @app_id,
+        "Nylas-API-Version" => SUPPORTED_API_VERSION,
+        "User-Agent" => "Nylas Ruby SDK #{NylasV2::VERSION} - #{RUBY_VERSION}",
+        "Content-type" => "application/json"
+      }
+    end
+
+    def parse_response(response)
+      return response if response.is_a?(Enumerable)
+
+      Yajl::Parser.new(symbolize_names: true).parse(response)
+    rescue Yajl::ParseError
+      raise NylasV2::JsonParseError
+    end
+    inform_on :parse_response, level: :debug, also_log: { result: true }
+
+    def url_for_path(path)
+      protocol, domain = api_server.split("//")
+      "#{protocol}//#{access_token}:@#{domain}#{path}"
+    end
+
+    private
+
+    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
+
+    inform_on :rest_client_execute, level: :debug,
+                                    also_log: { result: true, values: %i[method url headers payload] }
+
+    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
+
+    def handle_anticipated_failure_mode(http_code:, response:)
+      return if HTTP_SUCCESS_CODES.include?(http_code)
+
+      exception = HTTP_CODE_TO_EXCEPTIONS.fetch(http_code, APIError)
+      case response
+      when Hash
+        raise error_hash_to_exception(exception, response)
+      when RestClient::Response
+        raise exception.parse_error_response(response)
+      else
+        raise exception.new(http_code, response)
+      end
+    end
+
+    def error_hash_to_exception(exception, response)
+      exception.new(
+        response[:type],
+        response[:message],
+        response.fetch(:server_error, nil)
+      )
+    end
+
+    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
+
+    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
+
+    def auth_header(auth_method)
+      authorization_string = case auth_method
+                             when AuthMethod::BEARER
+                               "Bearer #{access_token}"
+                             when AuthMethod::BASIC
+                               "Basic #{Base64.encode64("#{access_token}:")}"
+                             else
+                               "Bearer #{access_token}"
+                             end
+
+      { "Authorization" => authorization_string }
+    end
+  end
+end

data/lib/nylas_v2/im_address.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # 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
+end

data/lib/nylas_v2/job_status.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # Ruby representation of a Nylas Job Status object
+  # @see https://developer.nylas.com/docs/api/#tag--Job-Status
+  class JobStatus
+    include Model
+    self.resources_path = "/job-statuses"
+    self.listable = true
+
+    attribute :id, :string, read_only: true
+    attribute :account_id, :string, read_only: true
+    attribute :job_status_id, :string, read_only: true
+    attribute :action, :string, read_only: true
+    attribute :object, :string, read_only: true
+    attribute :status, :string, read_only: true
+    attribute :created_at, :unix_timestamp, read_only: true
+    attribute :reason, :string, read_only: true
+    attribute :metadata, :hash, read_only: true
+
+    # Returns the status of a job as a boolean
+    # @return [Boolean] If the job was successful
+    def successful?
+      status == "successful"
+    end
+  end
+end

data/lib/nylas_v2/job_status_collection.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # Additional methods for some of Calendar's other functionality
+  # @see https://developer.nylas.com/docs/connectivity/calendar
+  class JobStatusCollection < Collection
+    def find_model(id)
+      response = api.execute(
+        **to_be_executed.merge(
+          path: "#{resources_path}/#{id}",
+          query: view_query
+        )
+      )
+
+      object_type = response[:object]
+      return OutboxJobStatus.from_hash(response, api: api) if object_type == "message"
+
+      model.from_hash(response, api: api)
+    end
+  end
+end

data/lib/nylas_v2/label.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # Structure to represent the Label Schema
+  # @see https://docs.nylas.com/reference#labels
+  class Label
+    include Model
+    self.resources_path = "/labels"
+    self.creatable = true
+    self.listable = true
+    self.showable = true
+    self.filterable = false
+    self.updatable = true
+    self.destroyable = true
+    self.id_listable = true
+    self.countable = true
+
+    attribute :id, :string
+    attribute :account_id, :string
+
+    attribute :object, :string
+
+    attribute :name, :string
+    attribute :display_name, :string
+    attribute :job_status_id, :string, read_only: true
+  end
+end

data/lib/nylas_v2/logging.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+begin
+  require "informed"
+rescue LoadError
+end
+
+module NylasV2
+  # 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

data/lib/nylas_v2/message.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # Ruby representatin of a Nylas Message object
+  # @see https://docs.nylas.com/reference#messages
+  class Message
+    include Model
+    self.raw_mime_type = "message/rfc822"
+    self.resources_path = "/messages"
+    self.listable = true
+    self.showable = true
+    self.filterable = true
+    self.updatable = true
+    self.searchable = true
+    self.id_listable = true
+    self.countable = true
+    UPDATABLE_ATTRIBUTES = %i[label_ids folder_id starred unread metadata].freeze
+
+    attribute :id, :string
+    attribute :object, :string
+    attribute :account_id, :string
+    attribute :thread_id, :string
+
+    attribute :headers, :message_headers
+
+    has_n_of_attribute :to, :email_address
+    has_n_of_attribute :from, :email_address
+    has_n_of_attribute :cc, :email_address
+    has_n_of_attribute :bcc, :email_address
+    has_n_of_attribute :reply_to, :email_address
+
+    attribute :date, :unix_timestamp
+    # This is only used when receiving a message received notification via a webhook
+    attribute :received_date, :unix_timestamp
+    attribute :subject, :string
+    attribute :snippet, :string
+    attribute :body, :string
+    attribute :starred, :boolean
+    attribute :unread, :boolean
+
+    has_n_of_attribute :events, :event
+    has_n_of_attribute :files, :file
+    attribute :folder, :folder
+    attribute :folder_id, :string
+    attribute :metadata, :hash
+    attribute :reply_to_message_id, :string, read_only: true
+    attribute :job_status_id, :string, read_only: true
+
+    has_n_of_attribute :labels, :label, read_only: true
+    has_n_of_attribute :label_ids, :string
+
+    transfer :api, to: %i[events files folder labels]
+
+    def starred?
+      starred
+    end
+
+    def unread?
+      unread
+    end
+
+    def update(payload)
+      FilterAttributes.new(
+        attributes: payload.keys,
+        allowed_attributes: UPDATABLE_ATTRIBUTES
+      ).check
+
+      super(**payload)
+    end
+
+    def update_folder(folder_id)
+      update(folder_id: folder_id)
+    end
+
+    def expanded
+      return self unless headers.nil?
+
+      assign(**api.execute(method: :get, path: resource_path, query: { view: "expanded" }))
+      # Transfer reference to the API to attributes that need it
+      transfer_attributes
+      self
+    end
+
+    def save
+      handle_folder
+
+      super
+    end
+
+    def handle_folder
+      return if folder.nil?
+
+      self.folder_id = folder.id if folder_id.nil? && !self.to_h.dig(:folder, :id).nil?
+
+      self.folder = nil
+    end
+  end
+end

data/lib/nylas_v2/message_headers.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # Translates message headers into a Ruby object
+  # @see https://docs.nylas.com/reference#section-message-views
+  class MessageHeaders
+    include Model::Attributable
+    attribute :in_reply_to, :string
+    attribute :message_id, :string
+    has_n_of_attribute :references, :string
+  end
+
+  # Serializes, Deserializes between {MessageHeaders} objects and a Hash
+  class MessageHeadersType < Types::ModelType
+    def initialize
+      super(model: MessageHeaders)
+    end
+    RUBY_KEY_TO_JSON_KEY_MAP = {
+      in_reply_to: :"In-Reply-To",
+      message_id: :"Message-Id",
+      references: :References
+    }.freeze
+    def json_key_from_attribute_name(attribute_name)
+      RUBY_KEY_TO_JSON_KEY_MAP.fetch(attribute_name)
+    end
+  end
+end

data/lib/nylas_v2/message_tracking.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # Message tracking features
+  # @see https://docs.nylas.com/reference#message-tracking-overview
+  class MessageTracking
+    include Model::Attributable
+    attribute :links, :boolean
+    attribute :opens, :boolean
+    attribute :thread_replies, :boolean
+    attribute :payload, :string
+  end
+end

data/lib/nylas_v2/model/attributable.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module NylasV2
+  module Model
+    # Allows defining of typecastable attributes on a model
+    module Attributable
+      def self.included(model)
+        model.extend(ClassMethods)
+      end
+
+      def initialize(**initial_data)
+        assign(**initial_data)
+      end
+
+      def attributes
+        @attributes ||= Attributes.new(self.class.attribute_definitions)
+      end
+
+      # @return [Hash] Representation of the model with values serialized into primitives based on their Type
+      def to_h(enforce_read_only: false)
+        attributes.to_h(enforce_read_only: enforce_read_only)
+      end
+
+      protected
+
+      def assign(**data)
+        data.each do |attribute_name, value|
+          next if value.nil?
+
+          if respond_to?(:"#{attribute_name}=")
+            send(:"#{attribute_name}=", value)
+          end
+        end
+      end
+
+      # Methods to call when tweaking Attributable classes
+      module ClassMethods
+        # rubocop:disable Naming/PredicateName
+        def has_n_of_attribute(name, type_name, read_only: false, default: [])
+          attribute_definitions[name] = ListAttributeDefinition.new(
+            type_name: type_name,
+            read_only: read_only,
+            default: default
+          )
+          define_accessors(name)
+        end
+        # rubocop:enable Naming/PredicateName
+
+        def attribute(name, type_name, read_only: false, default: nil)
+          attribute_definitions[name] = AttributeDefinition.new(
+            type_name: type_name,
+            read_only: read_only,
+            default: default
+          )
+          define_accessors(name)
+        end
+
+        def define_accessors(name)
+          define_method :"#{name}" do
+            attributes[name]
+          end
+
+          define_method :"#{name}=" do |value|
+            attributes[name] = value
+          end
+        end
+
+        # Allows a class to inherit parent's attributes
+        def inherit_attributes
+          return if superclass.nil?
+
+          parent_attributes = superclass.attribute_definitions
+          parent_attributes.each do |parent_attribute|
+            name = parent_attribute[0]
+            attr = parent_attribute[1]
+            next if attribute_definitions.key?(name)
+
+            attribute_definitions[name] = attr
+            define_accessors(name)
+          end
+        end
+
+        def attribute_definitions
+          @attribute_definitions ||= Registry.new
+        end
+      end
+    end
+  end
+end

data/lib/nylas_v2/model/attribute_definition.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module NylasV2
+  module Model
+    # Define a particular attribute for a given model
+    class AttributeDefinition
+      extend Forwardable
+      def_delegators :type, :cast, :serialize, :serialize_for_api
+      attr_accessor :type_name, :read_only, :default
+
+      def initialize(type_name:, read_only:, default:)
+        self.type_name = type_name
+        self.read_only = read_only
+        self.default = default
+      end
+
+      private
+
+      def type
+        Types.registry[type_name]
+      end
+    end
+  end
+end