Class: Nylas::API

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Logging
Defined in:
lib/nylas/api.rb

Overview

Methods to retrieve data from the Nylas API as Ruby objects

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Logging

included, level, logger, logger=

Constructor Details

#initialize(client: nil, app_id: nil, app_secret: nil, access_token: nil, api_server: "https://api.nylas.com") ⇒ Nylas::API

Parameters:

  • client (HttpClient) (defaults to: nil) —

    Http Client to use for retrieving data

  • app_id (String) (defaults to: nil) —

    Your application id from the Nylas Dashboard

  • app_secret (String) (defaults to: nil) —

    Your application secret from the Nylas Dashboard

  • access_token (String) (defaults to: nil) —

    (Optional) Your users access token.

  • api_server (String) (defaults to: "https://api.nylas.com") —

    (Optional) Which Nylas API Server to connect to. Only change this if you’re using a self-hosted Nylas instance.



20
21
22
23
24
 
# File 'lib/nylas/api.rb', line 20

def initialize(client: nil, app_id: nil, app_secret: nil, access_token: nil,
               api_server: "https://api.nylas.com")
  self.client = client || HttpClient.new(app_id: app_id, app_secret: app_secret,
                                         access_token: access_token, api_server: api_server)
end

Instance Attribute Details

#client ⇒ Object

Returns the value of attribute client.



6
7
8
 
# File 'lib/nylas/api.rb', line 6

def client
  @client
end

Instance Method Details

#accounts ⇒ Collection<Account>

Returns A queryable collection of Nylas::Accounts.

Returns:



87
88
89
 
# File 'lib/nylas/api.rb', line 87

def accounts
  @accounts ||= Collection.new(model: Account, api: as(client.app_secret))
end

#application_details ⇒ ApplicationDetail

Returns the application details

Returns:



173
174
175
176
177
178
179
180
 
# File 'lib/nylas/api.rb', line 173

def application_details
  response = client.as(client.app_secret).execute(
    method: :get,
    path: "/a/#{app_id}",
    auth_method: HttpClient::AuthMethod::BASIC
  )
  ApplicationDetail.new(**response)
end

#as(access_token) ⇒ API

Allows you to get an API that acts as a different user but otherwise has the same settings

Parameters:

  • access_token (String) —

    Oauth Access token or app secret used to authenticate with the API

Returns:



214
215
216
 
# File 'lib/nylas/api.rb', line 214

def as(access_token)
  API.new(client: client.as(access_token))
end

#authenticate(name:, email_address:, provider:, settings:, reauth_account_id: nil, scopes: nil, return_full_response: false) ⇒ String

Returns A Nylas access token for that particular user.

Returns:

  • (String) —

    A Nylas access token for that particular user.



27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/nylas/api.rb', line 27

def authenticate(name:, email_address:, provider:, settings:, reauth_account_id: nil, scopes: nil,
                 return_full_response: false)
  NativeAuthentication.new(api: self).authenticate(
    name: name,
    email_address: email_address,
    provider: provider,
    settings: settings,
    reauth_account_id: ,
    scopes: scopes,
    return_full_response: return_full_response
  )
end

#authentication_url(redirect_uri:, scopes:, response_type: "code", login_hint: nil, state: nil, provider: nil, redirect_on_error: nil, disable_provider_selection: nil) ⇒ Object 



40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/nylas/api.rb', line 40

def authentication_url(redirect_uri:, scopes:, response_type: "code", login_hint: nil, state: nil,
                       provider: nil, redirect_on_error: nil, disable_provider_selection: nil)
  params = { client_id: app_id, redirect_uri: redirect_uri, response_type: response_type,
             login_hint:  }

  params[:state] = state if state
  params[:scopes] = scopes.join(",") if scopes
  params[:provider] = provider if provider
  params[:redirect_on_error] = redirect_on_error if redirect_on_error
  params[:disable_provider_selection] = disable_provider_selection if disable_provider_selection

  "#{api_server}/oauth/authorize?#{URI.encode_www_form(params)}"
end

#calendars ⇒ CalendarCollection<Calendar>

Returns A queryable collection of Calendars.

Returns:



92
93
94
 
# File 'lib/nylas/api.rb', line 92

def calendars
  @calendars ||= CalendarCollection.new(model: Calendar, api: self)
end

#components ⇒ Collection<Component>

Returns A queryable collection of Components.

Returns:



160
161
162
 
# File 'lib/nylas/api.rb', line 160

def components
  @components ||= ComponentCollection.new(model: Component, api: as(client.app_secret))
end

#contact_groups ⇒ Collection<ContactGroup>

Returns A queryable collection of Contact Groups.

Returns:



76
77
78
 
# File 'lib/nylas/api.rb', line 76

def contact_groups
  @contact_groups ||= Collection.new(model: ContactGroup, api: self)
end

#contacts ⇒ Collection<Contact>

Returns A queryable collection of Contacts.

Returns:



71
72
73
 
# File 'lib/nylas/api.rb', line 71

def contacts
  @contacts ||= Collection.new(model: Contact, api: self)
end

#current_account ⇒ CurrentAccount

Returns The account details for whomevers access token is set.

Returns:

  • (CurrentAccount) —

    The account details for whomevers access token is set



81
82
83
84
 
# File 'lib/nylas/api.rb', line 81

def 
  prevent_calling_if_missing_access_token(:current_account)
  CurrentAccount.from_hash(execute(method: :get, path: "/account"), api: self)
end

#deltas ⇒ DeltasCollection<Delta>

Returns A queryable collection of Deltas, which are themselves a collection.

Returns:



97
98
99
 
# File 'lib/nylas/api.rb', line 97

def deltas
  @deltas ||= DeltasCollection.new(api: self)
end

#drafts ⇒ Object

@return A queryable collection of Draft objects



102
103
104
 
# File 'lib/nylas/api.rb', line 102

def drafts
  @drafts ||= Collection.new(model: Draft, api: self)
end

#events ⇒ EventCollection<Event>

Returns A queryable collection of Events.

Returns:



107
108
109
 
# File 'lib/nylas/api.rb', line 107

def events
  @events ||= EventCollection.new(model: Event, api: self)
end

#exchange_code_for_token(code, return_full_response: false) ⇒ String | Hash

Exchanges an authorization code for an access token

Parameters:

  • code (String) —

    The authorization code to exchange

  • return_full_response (Boolean) (defaults to: false) —

    If true, returns the full response body instead of just the token

Returns:

  • (String | Hash) —

    Returns just the access token as a string, or the full response as a hash



58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/nylas/api.rb', line 58

def exchange_code_for_token(code, return_full_response: false)
  data = {
    "client_id" => app_id,
    "client_secret" => client.app_secret,
    "grant_type" => "authorization_code",
    "code" => code
  }

  response = execute(method: :post, path: "/oauth/token", payload: data)
  return_full_response ? response : response[:access_token]
end

#files ⇒ Collection<File>

Returns A queryable collection of Files.

Returns:



117
118
119
 
# File 'lib/nylas/api.rb', line 117

def files
  @files ||= Collection.new(model: File, api: self)
end

#folders ⇒ Collection<Folder>

Returns A queryable collection of Folders.

Returns:



112
113
114
 
# File 'lib/nylas/api.rb', line 112

def folders
  @folders ||= Collection.new(model: Folder, api: self)
end

#free_busy(emails:, start_time:, end_time:) ⇒ Object

TODO: Move this into calendar collection



229
230
231
232
233
234
235
236
 
# File 'lib/nylas/api.rb', line 229

def free_busy(emails:, start_time:, end_time:)
  FreeBusyCollection.new(
    api: self,
    emails: emails,
    start_time: start_time.to_i,
    end_time: end_time.to_i
  )
end

#ip_addresses ⇒ Hash

Returns list of IP addresses hash has keys of :updated_at (unix timestamp) and :ip_addresses (array of strings)

Returns:

  • (Hash) 


198
199
200
201
 
# File 'lib/nylas/api.rb', line 198

def ip_addresses
  path = "/a/#{app_id}/ip_addresses"
  client.as(client.app_secret).get(path: path, auth_method: HttpClient::AuthMethod::BASIC)
end

#job_statuses ⇒ Object

@return A queryable collection of JobStatus objects



137
138
139
 
# File 'lib/nylas/api.rb', line 137

def job_statuses
  @job_statuses ||= JobStatusCollection.new(model: JobStatus, api: self)
end

#labels ⇒ Collection<Label>

Returns A queryable collection of Label objects.

Returns:



122
123
124
 
# File 'lib/nylas/api.rb', line 122

def labels
  @labels ||= Collection.new(model: Label, api: self)
end

#messages ⇒ Object

@return A queryable collection of Message objects



127
128
129
 
# File 'lib/nylas/api.rb', line 127

def messages
  @messages ||= Collection.new(model: Message, api: self)
end

#neural ⇒ Object

@return A collection of Neural operations



155
156
157
 
# File 'lib/nylas/api.rb', line 155

def neural
  @neural ||= Neural.new(api: self)
end

#outbox ⇒ Object

@return A collection of Outbox operations



142
143
144
 
# File 'lib/nylas/api.rb', line 142

def outbox
  @outbox ||= Outbox.new(api: self)
end

#revoke(access_token) ⇒ Boolean

Revokes access to the Nylas API for the given access token

Returns:

  • (Boolean) 


166
167
168
169
 
# File 'lib/nylas/api.rb', line 166

def revoke(access_token)
  response = client.as(access_token).post(path: "/oauth/revoke")
  response.code == 200 && response.empty?
end

#room_resources ⇒ Object

@return A queryable collection of RoomResource objects



132
133
134
 
# File 'lib/nylas/api.rb', line 132

def room_resources
  @room_resources ||= Collection.new(model: RoomResource, api: self)
end

#scheduler ⇒ Object

@return A queryable collection of Scheduler objects



147
148
149
150
151
152
 
# File 'lib/nylas/api.rb', line 147

def scheduler
  # Make a deep copy of the API as the scheduler API uses a different base URL
  scheduler_api = Marshal.load(Marshal.dump(self))
  scheduler_api.client.api_server = "https://api.schedule.nylas.com"
  @scheduler ||= SchedulerCollection.new(model: Scheduler, api: scheduler_api)
end

#send!(message) ⇒ Message

Returns The resulting message.

Parameters:

  • message (Hash, String, #send!)

Returns:

  • (Message) —

    The resulting message



205
206
207
208
209
 
# File 'lib/nylas/api.rb', line 205

def send!(message)
  return message.send! if message.respond_to?(:send!)
  return NewMessage.new(**message.merge(api: self)).send! if message.respond_to?(:key?)
  return RawMessage.new(message, api: self).send! if message.is_a? String
end

#threads ⇒ Collection<Thread>

Returns A queryable collection of Threads.

Returns:



219
220
221
 
# File 'lib/nylas/api.rb', line 219

def threads
  @threads ||= Collection.new(model: Thread, api: self)
end

#update_application_details(application_details) ⇒ ApplicationDetails

Updates the application details

Parameters:

Returns:

  • (ApplicationDetails) —

    The updated application details, returned from the server



185
186
187
188
189
190
191
192
193
 
# File 'lib/nylas/api.rb', line 185

def update_application_details(application_details)
  response = client.as(client.app_secret).execute(
    method: :put,
    path: "/a/#{app_id}",
    payload: JSON.dump(application_details.to_h),
    auth_method: HttpClient::AuthMethod::BASIC
  )
  ApplicationDetail.new(**response)
end

#webhooks ⇒ Collection<Webhook>

Returns A queryable collection of Webhooks.

Returns:



224
225
226
 
# File 'lib/nylas/api.rb', line 224

def webhooks
  @webhooks ||= Collection.new(model: Webhook, api: as(client.app_secret))
end