nylas_v2 5.14.2

data/lib/nylas_v2/errors.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module NylasV2
+  Error = Class.new(::StandardError)
+
+  class ModelActionError < Error; end
+  class ModelNotFilterableError < ModelActionError; end
+  class ModelNotCreatableError < ModelActionError; end
+  class ModelNotShowableError < ModelActionError; end
+  class ModelNotAvailableAsRawError < ModelActionError; end
+  class ModelNotListableError < ModelActionError; end
+  class ModelNotFilterableError < ModelActionError; end
+  class ModelNotSearchableError < ModelActionError; end
+  class ModelNotUpdatableError < ModelActionError; end
+  class ModelNotDestroyableError < ModelActionError; end
+
+  class JsonParseError < Error; end
+
+  # Raised when attempting to set a field that is not on a model with mass assignment
+  class ModelMissingFieldError < ModelActionError
+    def initialize(field, model)
+      super("#{field} is not a valid attribute for #{model.class.name}")
+    end
+  end
+
+  # 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
+
+    def self.parse_error_response(response)
+      new(
+        response["type"],
+        response["message"],
+        response["server_error"]
+      )
+    end
+  end
+
+  # Error class representing a 429 error response, with details on the rate limit
+  class RateLimitError < APIError
+    attr_accessor :rate_limit
+    attr_accessor :rate_limit_reset
+
+    RATE_LIMIT_LIMIT_HEADER = "x_ratelimit_limit"
+    RATE_LIMIT_RESET_HEADER = "x_ratelimit_reset"
+
+    def initialize(type, message, server_error = nil, rate_limit = nil, rate_limit_reset = nil)
+      super(type, message, server_error)
+      self.rate_limit = rate_limit
+      self.rate_limit_reset = rate_limit_reset
+    end
+
+    def self.parse_error_response(response)
+      rate_limit, rate_limit_rest = extract_rate_limit_details(response)
+
+      new(
+        response["type"],
+        response["message"],
+        response["server_error"],
+        rate_limit,
+        rate_limit_rest
+      )
+    end
+
+    def self.extract_rate_limit_details(response)
+      return nil, nil unless response.respond_to?(:headers)
+
+      rate_limit = response.headers[RATE_LIMIT_LIMIT_HEADER.to_sym].to_i
+      rate_limit_rest = response.headers[RATE_LIMIT_RESET_HEADER.to_sym].to_i
+
+      [rate_limit, rate_limit_rest]
+    end
+
+    private_class_method :extract_rate_limit_details
+  end
+
+  AccessDenied = Class.new(APIError)
+  ResourceNotFound = Class.new(APIError)
+  MethodNotAllowed = Class.new(APIError)
+  InvalidRequest = Class.new(APIError)
+  UnauthorizedRequest = Class.new(APIError)
+  ResourceRemoved = Class.new(APIError)
+  TeapotError = Class.new(APIError)
+  RequestTimedOut = Class.new(APIError)
+  MessageRejected = Class.new(APIError)
+  SendingQuotaExceeded = Class.new(RateLimitError)
+  ServiceUnavailable = Class.new(APIError)
+  BadGateway = Class.new(APIError)
+  InternalError = Class.new(APIError)
+  EndpointNotYetImplemented = Class.new(APIError)
+  MailProviderError = Class.new(APIError)
+end

data/lib/nylas_v2/event.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # Structure to represent a the Event Schema.
+  # @see https://docs.nylas.com/reference#events
+  class Event
+    include Model
+    self.resources_path = "/events"
+    self.creatable = true
+    self.listable = true
+    self.showable = true
+    self.filterable = true
+    self.updatable = true
+    self.destroyable = true
+    self.id_listable = true
+    self.countable = true
+
+    attribute :id, :string, read_only: true
+    attribute :object, :string, read_only: true
+    attribute :account_id, :string, read_only: true
+    attribute :calendar_id, :string
+    attribute :master_event_id, :string
+    attribute :message_id, :string
+    attribute :ical_uid, :string
+    attribute :event_collection_id, :string
+
+    attribute :capacity, :integer
+    attribute :busy, :boolean
+    attribute :description, :string
+    attribute :location, :string
+    attribute :owner, :string
+    attribute :recurrence, :recurrence
+    has_n_of_attribute :participants, :participant
+    attribute :read_only, :boolean
+    attribute :status, :string
+    attribute :title, :string
+    attribute :when, :when
+    attribute :metadata, :hash
+    attribute :conferencing, :event_conferencing
+    has_n_of_attribute :notifications, :event_notification
+    has_n_of_attribute :round_robin_order, :string
+    attribute :original_start_time, :unix_timestamp
+    attribute :reminder_minutes, :string
+    attribute :reminder_method, :string
+    attribute :job_status_id, :string, read_only: true
+    attribute :visibility, :string
+
+    attr_accessor :notify_participants
+
+    def busy?
+      busy
+    end
+
+    def read_only?
+      read_only
+    end
+
+    def save
+      validate
+      format_reminder_minutes
+
+      super
+    end
+
+    def rsvp(status, notify_participants:)
+      rsvp = Rsvp.new(api: api, status: status, notify_participants: notify_participants,
+                      event_id: id, account_id: account_id)
+      rsvp.save
+    end
+
+    # Generate an ICS file server-side, from an Event
+    # @param ical_uid [String] Unique identifier used events across calendaring systems
+    # @param method [String] Description of invitation and response methods for attendees
+    # @param prodid [String] Company-specific unique product identifier
+    # @return [String] String for writing directly into an ICS file
+    def generate_ics(ical_uid: nil, method: nil, prodid: nil)
+      raise ArgumentError, "Cannot generate an ICS file for an event without a Calendar ID or when set" unless
+        calendar_id && self.when
+
+      payload = build_ics_event_payload(ical_uid, method, prodid)
+      response = api.execute(
+        method: :post,
+        path: "#{resources_path}/to-ics",
+        payload: JSON.dump(payload)
+      )
+
+      response[:ics]
+    end
+
+    private
+
+    def validate
+      if conferencing
+        body = to_h
+        if body.dig(:conferencing, :details) && body.dig(:conferencing, :autocreate)
+          raise ArgumentError, "Cannot set both 'details' and 'autocreate' in conferencing object."
+        end
+      end
+      return unless capacity && capacity != -1 && participants && participants.length > capacity
+
+      raise ArgumentError, "The number of participants in the event exceeds the set capacity."
+    end
+
+    def build_ics_event_payload(ical_uid, method, prodid)
+      payload = {}
+      if id
+        payload[:event_id] = id
+      else
+        payload = to_h(enforce_read_only: true)
+      end
+      ics_options = build_ics_options_payload(ical_uid, method, prodid)
+      payload["ics_options"] = ics_options unless ics_options.empty?
+      payload
+    end
+
+    def build_ics_options_payload(ical_uid, method, prodid)
+      payload = {}
+      payload["ical_uid"] = ical_uid if ical_uid
+      payload["method"] = method if method
+      payload["prodid"] = prodid if prodid
+      payload
+    end
+
+    # Formats the reminder minute field to match the API format: "[%d]"
+    def format_reminder_minutes
+      return if reminder_minutes.nil? || reminder_minutes.empty? || reminder_minutes.match(/\[\d+\]/)
+
+      self.reminder_minutes = "[#{reminder_minutes}]"
+    end
+
+    def query_params
+      if notify_participants.nil?
+        {}
+      else
+        {
+          notify_participants: notify_participants
+        }
+      end
+    end
+  end
+end

data/lib/nylas_v2/event_collection.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # Syntactical sugar methods for some of the Event's filters
+  # @see https://docs.nylas.com/reference#get-events
+  class EventCollection < Collection
+    def expand_recurring
+      where(expand_recurring: true)
+    end
+
+    def show_cancelled
+      where(show_cancelled: true)
+    end
+  end
+end

data/lib/nylas_v2/event_conferencing.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # Structure to represent the Event Conferencing object
+  # @see https://developer.nylas.com/docs/connectivity/calendar/conference-sync-beta
+  class EventConferencing
+    include Model::Attributable
+    attribute :provider, :string
+    attribute :details, :event_conferencing_details
+    attribute :autocreate, :event_conferencing_autocreate
+  end
+end

data/lib/nylas_v2/event_conferencing_autocreate.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # Structure to represent the autocreate object within the Event Conferencing object
+  # @see https://developer.nylas.com/docs/connectivity/calendar/conference-sync-beta
+  class EventConferencingAutocreate
+    include Model::Attributable
+    attribute :settings, :hash, default: {}
+  end
+end

data/lib/nylas_v2/event_conferencing_details.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # Structure to represent the details object within the Event Conferencing object
+  # @see https://developer.nylas.com/docs/connectivity/calendar/conference-sync-beta
+  class EventConferencingDetails
+    include Model::Attributable
+    attribute :meeting_code, :string
+    attribute :password, :string
+    attribute :pin, :string
+    attribute :url, :string
+    has_n_of_attribute :phone, :string
+  end
+end

data/lib/nylas_v2/event_notification.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # Structure to represent the Event Notification object
+  # @see https://developer.nylas.com/docs/connectivity/calendar/event-notifications
+  class EventNotification
+    include Model::Attributable
+
+    attribute :type, :string
+    attribute :minutes_before_event, :integer
+    attribute :url, :string
+    attribute :payload, :string
+    attribute :subject, :string
+    attribute :body, :string
+    attribute :message, :string
+  end
+end

data/lib/nylas_v2/file.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # Structure to represent a the File Schema.
+  # @see https://docs.nylas.com/reference#events
+  class File
+    include Model
+    self.resources_path = "/files"
+    self.creatable = true
+    self.listable = true
+    self.showable = true
+    self.filterable = true
+    self.destroyable = true
+    self.id_listable = true
+    self.countable = true
+
+    attribute :id, :string
+    attribute :account_id, :string
+    attribute :content_id, :string
+    has_n_of_attribute :message_ids, :string
+
+    attribute :object, :string
+
+    attribute :content_type, :string
+    attribute :filename, :string
+    attribute :size, :integer
+    attribute :content_disposition, :string
+
+    attr_accessor :file
+
+    # Downloads and caches a local copy of the file.
+    # @return [Tempfile] - Local copy of the file
+    def download
+      return file if file
+
+      self.file = retrieve_file
+    end
+
+    # Redownloads a file even if it's been cached. Closes and unlinks the tempfile to help memory usage.
+    def download!
+      return download if file.nil?
+
+      file.close
+      file.unlink
+      self.file = nil
+      download
+    end
+
+    def create
+      save
+    end
+
+    def save
+      raise ModelNotUpdatableError if persisted?
+
+      response = api.execute(path: "/files", method: :post, headers: { multipart: true },
+                             payload: { file: file })
+      attributes.merge(response.first)
+      true
+    end
+
+    private
+
+    def retrieve_file
+      response = api.get(path: "#{resource_path}/download")
+      filename = response.headers.fetch(:content_disposition, "").gsub("attachment; filename=", "")
+      # The returned filename can be longer than 256 chars which isn't supported by rb_sysopen.
+      # 128 chars here is more than enough given that TempFile ensure the filename will be unique.
+      temp_file = Tempfile.new(filename[0..127], encoding: "ascii-8bit")
+      temp_file.write(response.body)
+      temp_file.seek(0)
+      temp_file
+    end
+  end
+end

data/lib/nylas_v2/filter_attributes.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # Methods to check and raise error if extra attributes are present
+  class FilterAttributes
+    def initialize(attributes:, allowed_attributes:)
+      @attributes = attributes
+      @allowed_attributes = allowed_attributes
+    end
+
+    def check
+      return if extra_attributes.empty?
+
+      raise ArgumentError, "Only #{allowed_attributes} are allowed to be sent"
+    end
+
+    private
+
+    attr_reader :attributes, :allowed_attributes
+
+    def extra_attributes
+      attributes - allowed_attributes
+    end
+  end
+end

data/lib/nylas_v2/folder.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # Structure to represent the Folder Schema
+  # @see https://docs.nylas.com/reference#folders
+  class Folder
+    include Model
+    self.resources_path = "/folders"
+    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, read_only: true
+    attribute :account_id, :string, read_only: true
+    attribute :object, :string, read_only: true
+
+    attribute :name, :string
+    attribute :display_name, :string
+    attribute :job_status_id, :string, read_only: true
+  end
+end

data/lib/nylas_v2/free_busy.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # Query free/busy information for a calendar during a certain time period
+  # @see https://docs.nylas.com/reference#calendars-free-busy
+  class FreeBusy
+    include Model::Attributable
+
+    attribute :email, :string
+    attribute :object, :string
+    has_n_of_attribute :time_slots, :time_slot
+  end
+end

data/lib/nylas_v2/free_busy_collection.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module NylasV2
+  # Helper to get and build `FreeBusy` objects
+  class FreeBusyCollection
+    extend Forwardable
+    def_delegators :each, :map, :select, :reject, :to_a, :take
+    def_delegators :to_a, :first, :last, :[]
+
+    def initialize(emails:, start_time:, end_time:, api:)
+      @api = api
+      @emails = emails
+      @start_time = start_time
+      @end_time = end_time
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      execute.each do |result|
+        yield(FreeBusy.new(**result))
+      end
+    end
+
+    private
+
+    attr_reader :api, :emails, :start_time, :end_time
+
+    PATH = "/calendars/free-busy"
+    private_constant :PATH
+
+    def execute
+      api.execute(
+        method: :post,
+        path: PATH,
+        payload: payload
+      )
+    end
+
+    def payload
+      JSON.dump(
+        emails: emails,
+        start_time: start_time,
+        end_time: end_time
+      )
+    end
+  end
+end