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:



84
85
86
 
# File 'lib/nylas/api.rb', line 84

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

#application_details ⇒ ApplicationDetail

Returns the application details

Returns:



170
171
172
173
174
175
176
177
 
# File 'lib/nylas/api.rb', line 170

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:



211
212
213
 
# File 'lib/nylas/api.rb', line 211

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

#authenticate(name:, email_address:, provider:, settings:, reauth_account_id: nil, scopes: nil) ⇒ 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
 
# File 'lib/nylas/api.rb', line 27

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

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



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

def authentication_url(redirect_uri:, scopes:, response_type: "code", login_hint: nil, state: 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

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

#calendars ⇒ CalendarCollection<Calendar>

Returns A queryable collection of Calendars.

Returns:



89
90
91
 
# File 'lib/nylas/api.rb', line 89

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

#components ⇒ Collection<Component>

Returns A queryable collection of Components.

Returns:



157
158
159
 
# File 'lib/nylas/api.rb', line 157

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:



73
74
75
 
# File 'lib/nylas/api.rb', line 73

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

#contacts ⇒ Collection<Contact>

Returns A queryable collection of Contacts.

Returns:



68
69
70
 
# File 'lib/nylas/api.rb', line 68

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



78
79
80
81
 
# File 'lib/nylas/api.rb', line 78

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:



94
95
96
 
# File 'lib/nylas/api.rb', line 94

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

#drafts ⇒ Object

@Draft objects



99
100
101
 
# File 'lib/nylas/api.rb', line 99

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

#events ⇒ EventCollection<Event>

Returns A queryable collection of Events.

Returns:



104
105
106
 
# File 'lib/nylas/api.rb', line 104

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



55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/nylas/api.rb', line 55

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:



114
115
116
 
# File 'lib/nylas/api.rb', line 114

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

#folders ⇒ Collection<Folder>

Returns A queryable collection of Folders.

Returns:



109
110
111
 
# File 'lib/nylas/api.rb', line 109

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

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

TODO: Move this into calendar collection



226
227
228
229
230
231
232
233
 
# File 'lib/nylas/api.rb', line 226

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) 


195
196
197
198
 
# File 'lib/nylas/api.rb', line 195

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

@JobStatus objects



134
135
136
 
# File 'lib/nylas/api.rb', line 134

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

#labels ⇒ Collection<Label>

Returns A queryable collection of Label objects.

Returns:



119
120
121
 
# File 'lib/nylas/api.rb', line 119

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

#messages ⇒ Object

@Message objects



124
125
126
 
# File 'lib/nylas/api.rb', line 124

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

#neural ⇒ Object

@return A collection of Neural operations



152
153
154
 
# File 'lib/nylas/api.rb', line 152

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

#outbox ⇒ Object

@return A collection of Outbox operations



139
140
141
 
# File 'lib/nylas/api.rb', line 139

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) 


163
164
165
166
 
# File 'lib/nylas/api.rb', line 163

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

#room_resources ⇒ Object

@RoomResource objects



129
130
131
 
# File 'lib/nylas/api.rb', line 129

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

#scheduler ⇒ Object

@Scheduler objects



144
145
146
147
148
149
 
# File 'lib/nylas/api.rb', line 144

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



202
203
204
205
206
 
# File 'lib/nylas/api.rb', line 202

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:



216
217
218
 
# File 'lib/nylas/api.rb', line 216

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



182
183
184
185
186
187
188
189
190
 
# File 'lib/nylas/api.rb', line 182

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:



221
222
223
 
# File 'lib/nylas/api.rb', line 221

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