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:



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

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

#application_details ⇒ ApplicationDetail

Returns the application details

Returns:



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

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:



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

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, provider: nil, redirect_on_error: nil) ⇒ Object 



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

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

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

#calendars ⇒ CalendarCollection<Calendar>

Returns A queryable collection of Calendars.

Returns:



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

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

#components ⇒ Collection<Component>

Returns A queryable collection of Components.

Returns:



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

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:



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

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

#contacts ⇒ Collection<Contact>

Returns A queryable collection of Contacts.

Returns:



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

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



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

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:



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

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

#drafts ⇒ Object

@Draft objects



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

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

#events ⇒ EventCollection<Event>

Returns A queryable collection of Events.

Returns:



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

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



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

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:



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

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

#folders ⇒ Collection<Folder>

Returns A queryable collection of Folders.

Returns:



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

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

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

TODO: Move this into calendar collection



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

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) 


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

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



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

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

#labels ⇒ Collection<Label>

Returns A queryable collection of Label objects.

Returns:



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

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

#messages ⇒ Object

@Message objects



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

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

#neural ⇒ Object

@return A collection of Neural operations



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

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

#outbox ⇒ Object

@return A collection of Outbox operations



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

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) 


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

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

#room_resources ⇒ Object

@RoomResource objects



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

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

#scheduler ⇒ Object

@Scheduler objects



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

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



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

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:



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

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



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

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:



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

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