nylas / nylas-java Goto Github PK

Nylas Java SDK

License: MIT License

Kotlin 100.00%

nylas-java's Introduction

Nylas SDK for Kotlin & Java

This is the GitHub repository for the Nylas SDK for Kotlin and Java. This repo is primarily for anyone who wants to make contributions to the SDK or install it from source. For documentation on how to use this SDK to access the Nylas Email, Calendar, or Contacts APIs, see the official Java SDK Quickstart Guide.

The Nylas Communications Platform provides REST APIs for Email, Calendar, and Contacts, and the Nylas SDK is the quickest way to build your integration using Kotlin or Java.

Here are some resources to help you get started:

If you have a question about the Nylas Communications Platform, contact Nylas Support for help.

⚙️ Install

Note: The Nylas SDK for Kotlin & Java requires JRE 8 or later.

Set up using Gradle

If you're using Gradle, add the following to the dependencies section of build.gradle:

implementation("com.nylas.sdk:nylas:2.4.1")

Build from source

To build from source, clone this repo and build the project with Gradle.

git clone https://github.com/nylas/nylas-java.git && cd nylas-java
./gradlew build uberJar

This creates a new jar file in build/libs/nylas-java-sdk-2.4.1-uber.jar.

See the Gradle documentation on Building Libraries or the Gradle User Manual for more information.

⚡️Usage

To use this SDK, you must first get a free Nylas account.

Then, follow the Quickstart guide to set up your first app and get your API keys.

For code examples that demonstrate how to use this SDK, take a look at our Java repos in the Nylas Samples collection.

🚀 Making Your First Request

You use the NylasClient object to make requests to the Nylas API. The SDK is organized into different resources, each of which has methods to make requests to the API. Each resource is available through the NylasClient object configured with your API key.

For example, to get a list of calendars, you can use the following code:

NylasClient nylas = new NylasClient.Builder("API_KEY").build();
ListResponse<Calendars> calendars = nylas.calendars().list("GRANT_ID");

📚 Documentation

Nylas maintains a reference guide for the Kotlin and Java SDK to help you get familiar with the available methods and classes.

✨ Upgrading from 1.x

See UPGRADE.md for instructions on upgrading from 1.x to 2.x.

Note: The Kotlin/Java SDK 2.x is not compatible with the Nylas API earlier than v3-beta.

🪵 Logging

The SDK uses SLF4J for logging. If you are using the SDK you can choose what logging framework to use with it for your app.

Common choices are log4j, logback, java.util.logging. If the application doesn't specify any logging framework, SLF4J emits one single warning and is then completely silent.

By default, the HTTP client is configured with the com.nylas.HttpLoggingInterceptor which provides three DEBUG level loggers for HTTP requests.

com.nylas.http.Summary logs one line for each request, containing the method, URI, and content size, and one line for each response containing the status code, message, content size and duration.
com.nylas.http.Headers logs the request and response HTTP headers (except Authorization value by default).
com.nylas.http.Body logs request and response bodies (first 10kB by default).

You can enable or disable these loggers using whatever logging framework you use.

For example, if you're using log4j2 and with an xml configuration file, include this line to enable all three: <Logger name="com.nylas" level="DEBUG"/>

You can configure how you log HTTP Authorization header values and the body size limit using a NylasClient.Builder with a customized HttpLoggingInterceptor

💙 Contributing

We value and appreciate contributors' time! We welcome questions, bug reports, and pull requests.

See the Contributing for information about how to make contributions to this project.

📝 License

This project is licensed under the terms of the MIT license. See the LICENSE for the full terms.

nylas-java's People

Contributors

Stargazers

Watchers

Forkers

benlloydpearson ddlatham magg khuntmanish saralashree talktosmruti leminhitalia tdtianzhenjiu cuz-we-care orderoftheoverflow nickbair-nylas isabella232 bloobirds-it nylas burtonrhodes kraju3

nylas-java's Issues

Add "from" field to CreateDraftRequest to allow overriding the from address

Is your feature request related to a problem? Please describe.
Currently the SDK does not provide a way to set the "from" address. This was a feature in the v2 SDK and is implemented in the v3 API. However, it is currently not an option in the v3 SDK.

Describe the solution you'd like
Add "from" to CreateDraftRequest.kt

Additional context
I have created a PR here: #233 Through limited testing, this appears to work.

Async API

Hey team! What do you think about java async client with https://projectreactor.io/

FindAttachmentQueryParams builder returns FindEventQueryParams

Describe the bug
The return type of FindAttachmentQueryParams.Builder.build() method is defined as FindEventQueryParams

To Reproduce
See code: https://github.com/nylas/nylas-java/blob/main/src/main/kotlin/com/nylas/models/FindAttachmentQueryParams.kt

Expected behavior
Should return FindAttachmentQueryParams

SDK Version:
2.1.0

Attachments not send when < 3 MB

SDK 2.2.1

In Messages.kt:

 return if (attachmentSize >= FileUtils.MAXIMUM_JSON_ATTACHMENT_SIZE) {
      val attachmentLessPayload = requestBody.copy(attachments = null)
      val serializedRequestBody = adapter.toJson(attachmentLessPayload)
      val multipart = FileUtils.buildFormRequest(requestBody, serializedRequestBody)

      client.executeFormRequest(path, NylasClient.HttpMethod.POST, multipart, responseType)
    } else {
      val serializedRequestBody = adapter.toJson(requestBody)
      createResource(path, serializedRequestBody)
    }

As the attachments field on SendMessageRequest is marked as transient, this part of the conditional statement

val attachmentLessPayload = requestBody.copy(attachments = null)

is useless
and the else part ignores attachments.

duplicated http logs on 1.3.0 when not using NylasClient.Builder

Version 1.3.0 introduced NylasClient.Builder to allow more control over custom http client configuration, but retained other NylasClient constructors for backward compatibility. However, when those other constructors are used, the SDK logs all HTTP requests and responses twice. This will be addressed in the next release. In the mean time, a workaround is to switch to use the NylasClient.Builder for constructing the NylasClient.

Using internal api of OkHttp stops us from using newer version of OkHttp

Describe the bug
Using internal api of OkHttp stops us from using newer version of OkHttp

nylas-java/src/main/java/com/nylas/HttpLoggingInterceptor.java

Line 115 in 5e79d07

+ " resBodySize=" + HttpHeaders.contentLength(response)

import okhttp3.internal.http.HttpHeaders
...
  + " resBodySize=" + HttpHeaders.contentLength(response)

HttpHeaders is part of internal api of OkHttp and should not be used in the sdk.

To Reproduce
Create a project, add nylas sdk as dependency and override OkHttp in your project, calling methods like
account.events().list().fetchAll()
ends up with such stacktrace:

	at com.nylas.HttpLoggingInterceptor.logResponse(HttpLoggingInterceptor.java:115)
	at com.nylas.HttpLoggingInterceptor.intercept(HttpLoggingInterceptor.java:73)
	at okhttp3.internal.http.RealInterceptorChain.proceed(RealInterceptorChain.kt:109)
	at okhttp3.internal.connection.ConnectInterceptor.intercept(ConnectInterceptor.kt:34)
	at okhttp3.internal.http.RealInterceptorChain.proceed(RealInterceptorChain.kt:109)
	at okhttp3.internal.cache.CacheInterceptor.intercept(CacheInterceptor.kt:95)
	at okhttp3.internal.http.RealInterceptorChain.proceed(RealInterceptorChain.kt:109)
	at okhttp3.internal.http.BridgeInterceptor.intercept(BridgeInterceptor.kt:83)
	at okhttp3.internal.http.RealInterceptorChain.proceed(RealInterceptorChain.kt:109)
	at okhttp3.internal.http.RetryAndFollowUpInterceptor.intercept(RetryAndFollowUpInterceptor.kt:76)
	at okhttp3.internal.http.RealInterceptorChain.proceed(RealInterceptorChain.kt:109)
	at com.nylas.AddVersionHeadersInterceptor.intercept(AddVersionHeadersInterceptor.java:24)
	at okhttp3.internal.http.RealInterceptorChain.proceed(RealInterceptorChain.kt:109)
	at okhttp3.internal.connection.RealCall.getResponseWithInterceptorChain$okhttp(RealCall.kt:201)
	at okhttp3.internal.connection.RealCall.execute(RealCall.kt:154)
	at com.nylas.NylasClient.executeRequest(NylasClient.java:170)
	at com.nylas.NylasClient.executeRequestWithAuth(NylasClient.java:153)
	at com.nylas.NylasClient.executeGet(NylasClient.java:112)
	at com.nylas.RestfulDAO.fetchQuery(RestfulDAO.java:56)
	at com.nylas.RemoteCollection.fetchSet(RemoteCollection.java:71)
	at com.nylas.RemoteCollection.fetchAll(RemoteCollection.java:58)```

// Helps us with reproducing the error :)


**Expected behavior**
Please remove HttpHeaders references from the sdk.

**SDK Version:**
The most recent version 1.11 and previous ones

Drafts - delete Method not Available

Hi,

Below code is documented in Nylas API doc. However, we are not able to use this.

NylasClient nylas = new NylasClient();
NylasAccount account = nylas.account("{ACCESS_TOKEN}");
Drafts drafts = account.drafts();
// Delete drafts by specifying the appropriate id
drafts.delete("{draft_id}");

We get error when we try tp access drafts.delete() method.

The method delete(String) from the type RestfulDAO is not visible
delete(java.lang.String,java.util.Map<java.lang.String,java.lang.String>) has protected access in com.nylas.RestfulDAO

Cannot create Event.Recurrence

Currently, in the Java SDK v1.0.0, com.nylas.Event.Recurrence object only has an empty constructor. How can we create a new Recurrence object and set it to an event?

The field "reply_to_message_id" is not available ( or maybe I cannot see) in the Message object the response of the getting the emails from the java SDK. Can you help me with this?

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Question :: How to construct GoogleProviderSettings class if protected?

I am attempting to setup "native" authorization and following the example here, but since the GoogleProviderSettings class's visibility is "protected", the lines below aren't valid. Am I missing something obvious?

GoogleProviderSettings googleSettings = new GoogleProviderSettings() .googleClientId("google.api.client.id") .googleClientSecret("google.api.client.secret") .googleRefreshToken("google.refresh.token") ;

Java SDK: Thread: thread.getMessages() return an empty list

Describe the bug
The java SDK has a bug with thread.getMessages() method. Even if a thread has multiple messages, this method returns an empty array

To Reproduce

List<Message> messages = thread.getMessages();

Expected behavior
This method should return the message list

SDK Version:
1.9.0

Additional context
The doc samples or cases can not be achieved

Need to access Response Headers through RequestFailedException

Is your feature request related to a problem? Please describe.
When performing email account authorization with Nylas, if the request fails due to hitting the rate limit (status code 429), Nylas suggests implementing an exponential backoff strategy. However, the RequestFailedException thrown by Nylas does not provide access to the response headers, which contain valuable information such as the rate limit and reset time.

Describe the solution you'd like

Modify the executeRequest method in the NylasClient class to capture and return the response headers along with the response body.
Enhance the RequestFailedException class to include a field for storing the response headers.
Pass the response headers to the RequestFailedException.parseErrorResponse method when creating a new instance of RequestFailedException.
Provide getter methods in the RequestFailedException class to retrieve the response headers.
Then we can utilize the response headers in the application code to implement the exponential backoff strategy based on the rate limit and reset time provided by Nylas.

Adding calendar to MS/Outlook provider causes error, Google does not.

When adding a new calendar for an Outlook provider, and the "description" is set, I get an error and the calendar is not added. The error is specific and tells me that I can't add this calendar due to setting the "description" (and apparently the timezone or location) which is helpful. However, I feel like this should be a warning, not an error.

One of the main advantages of a standardized API is not having to modify code based off the provider. So now when adding a Calendar I will need to check the provider first before adding certain elements descriptive elements. Is there something I'm missing on why this request becomes a full-stop error instead of just adding the calendar without a description? Curious your thoughts on is the API should be modified for this scenario.

Code

Calendar calendar = new Calendar();
calendar.setName("My Calendar");
calendar.setDescription("Calendar for UserId: " + appUserId);
calendar.getMetadata().put("UserId", appUserId.toString());
calendar = this.account.calendars().create(calendar);

Error when provider is MS/Outlook
ERROR com.nylas.RequestFailedException: statusCode=400, type=invalid_request_error, message=This provider only supports 'name'; does not support 'timezone', 'description', nor 'location'. at com.nylas.RequestFailedException.parseErrorResponse(RequestFailedException.java:84) at com.nylas.NylasClient.throwAndCloseOnFailedRequest(NylasClient.java:255) at com.nylas.NylasClient.executeRequest(NylasClient.java:239) at com.nylas.NylasClient.executeRequestWithAuth(NylasClient.java:204) at com.nylas.NylasClient.executePost(NylasClient.java:168) at com.nylas.RestfulDAO.create(RestfulDAO.java:88) at com.nylas.RestfulDAO.create(RestfulDAO.java:77) at com.nylas.RestfulDAO.create(RestfulDAO.java:69) at com.nylas.Calendars.create(Calendars.java:36)

Thanks!

Make Recurrence implement JsonObject

Currently, Recurrence class doesn't implement JsonObject interface.

Participant status is not serialized when creating an event

Describe the bug
Participant status is not serialized when creating an event. Invocation of Event.getWritableFields(true) always calls Participant.getWritableFields(false), so status is not present in HTTP request.

To Reproduce
Create event and set at least one participant with status = 'YES'

Event event = new Event();
// Set all required fields
Participant participant = new Participant("[email protected]");
participant.status(Participant.Status.YES);
event.setParticipants(List.of(participant));

application.getClient().account(accessToken).events().create(event, true);

Expected behavior
Participant status should be sent when creating an event

SDK Version:
Version - 1.18.0

Additional context
It seems that the bug was made after this commit d97dec6

[SDK][Java][1.9.0] Read Email Messages and Threads sample not working

Describe the bug
The code sample in the document is incorrect.

To Reproduce
The code sample is incorrect. It will not compile.

Expected behavior
The sample should be able to comple and run

SDK Version:
1.9.0

Suggested fix

import java.util.List;

import com.nylas.*;
import com.nylas.Thread;

public class ReadMessagesThreads {
    public static void main(String[] args) throws Exception {
        // Create client object and connect it to Nylas using
        // an account's access token

        NylasClient client = new NylasClient();

        // Provide the access token for a specific account
        NylasAccount account = client.account("ACCESS_TOKEN");
        // Return the most recent email message
        RemoteCollection<Message> messagesList = account.messages().list(new MessageQuery().limit(1));

        for (Message message : messagesList) {
            System.out.printf("Subject: %s | Unread: %s | ID: %s\n",
                    message.getSubject(),
                    message.getUnread(),
                    message.getId()
            );
        }

        // Return the 5 most recent unread threads.
        ThreadQuery unread = new ThreadQuery().limit(5).unread(true);
        RemoteCollection<Thread> threads = account.threads().list(unread);

        for (Thread thread : threads) {
            StringBuilder participants = new StringBuilder();
            for (NameEmail participant : thread.getParticipants()) {
                participants.append(participant.getEmail()).append(" ");
            }
            System.out.printf("Subject: %s | Participants: %s\n",
                    thread.getSubject(),
                    participants
            );
        }

    }
}

does nylas support send attachment using amazon s3 ?

when i using java SDK send attachment, usually must com.nylas.Files.upload method and using byte[] pass to it.
so upload the file in backend，and it's cost double traffic .
i want upload file in frontend, after upload file successful notice backend, and then java sdk to send email out,

does nylas support send attachment by using a s3 file link?

getReplyToMessageId is Not available in the Message object ( when getting the emails) , can you please add it

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Custom authentication with provider type IMAP: Exception on response deserialization

Describe the bug
According to the specification, scopes for IMAP email accounts are optional.
See point 5 here: Nylas Docs

If you call the customAuthentication API endpoint via the SDK with settings for an IMAP account and do not specify any scopes, the response will not contain any scopes either. This causes the json deserializer to throw an exception, as scopes are expected:

org.jboss.resteasy.spi.UnhandledException: com.squareup.moshi.JsonDataException: Required value 'scope' missing at $.data
        at org.jboss.resteasy.core.ExceptionHandler.handleApplicationException(ExceptionHandler.java:105)
        at org.jboss.resteasy.core.ExceptionHandler.handleException(ExceptionHandler.java:359)
        at org.jboss.resteasy.core.SynchronousDispatcher.writeException(SynchronousDispatcher.java:218)
        at org.jboss.resteasy.core.SynchronousDispatcher.invoke(SynchronousDispatcher.java:519)
        at org.jboss.resteasy.core.SynchronousDispatcher.lambda$invoke$4(SynchronousDispatcher.java:261)
        at org.jboss.resteasy.core.SynchronousDispatcher.lambda$preprocess$0(SynchronousDispatcher.java:161)
        at org.jboss.resteasy.core.interception.jaxrs.PreMatchContainerRequestContext.filter(PreMatchContainerRequestContext.java:364)
        at org.jboss.resteasy.core.SynchronousDispatcher.preprocess(SynchronousDispatcher.java:164)
        at org.jboss.resteasy.core.SynchronousDispatcher.invoke(SynchronousDispatcher.java:247)
        at io.quarkus.resteasy.runtime.standalone.RequestDispatcher.service(RequestDispatcher.java:82)
        at io.quarkus.resteasy.runtime.standalone.VertxRequestHandler.dispatch(VertxRequestHandler.java:147)
        at io.quarkus.resteasy.runtime.standalone.VertxRequestHandler$1.run(VertxRequestHandler.java:93)
        at io.quarkus.vertx.core.runtime.VertxCoreRecorder$14.runWith(VertxCoreRecorder.java:576)
        at org.jboss.threads.EnhancedQueueExecutor$Task.run(EnhancedQueueExecutor.java:2449)
        at org.jboss.threads.EnhancedQueueExecutor$ThreadBody.run(EnhancedQueueExecutor.java:1478)
        at org.jboss.threads.DelegatingRunnable.run(DelegatingRunnable.java:29)
        at org.jboss.threads.ThreadLocalResettingRunnable.run(ThreadLocalResettingRunnable.java:29)
        at io.netty.util.concurrent.FastThreadLocalRunnable.run(FastThreadLocalRunnable.java:30)
        at java.base/java.lang.Thread.run(Thread.java:833)
Caused by: com.squareup.moshi.JsonDataException: Required value 'scope' missing at $.data
        at com.squareup.moshi.internal.Util.missingProperty(Util.java:660)
        at com.squareup.moshi.kotlin.reflect.KotlinJsonAdapter.fromJson(KotlinJsonAdapter.kt:105)
        at com.squareup.moshi.internal.NullSafeJsonAdapter.fromJson(NullSafeJsonAdapter.java:41)
        at com.squareup.moshi.kotlin.reflect.KotlinJsonAdapter.fromJson(KotlinJsonAdapter.kt:86)
        at com.squareup.moshi.internal.NullSafeJsonAdapter.fromJson(NullSafeJsonAdapter.java:41)
        at com.squareup.moshi.JsonAdapter.fromJson(JsonAdapter.java:58)
        at com.nylas.NylasClient.executeRequest(NylasClient.kt:331)
        at com.nylas.NylasClient.executePost(NylasClient.kt:263)
        at com.nylas.NylasClient.executePost$default(NylasClient.kt:252)
        at com.nylas.resources.Auth.customAuthentication(Auth.kt:103)

To Reproduce

Map<String, Object> settings = new HashMap<>();
		settings.put("imap_username", imapUsername);
		settings.put("imap_password", imapPassword);
		settings.put("imap_host", imapHost);
		settings.put("imap_port", imapPort);
		settings.put("smtp_host", smtpHost);
		settings.put("smtp_port", smtpPort);
CreateGrantRequest r = new CreateGrantRequest.Builder(AuthProvider.IMAP, settings).build();
		Grant grant = nylasClient.auth().customAuthentication(r).getData();

Expected behavior
According to the documentation: "If you don't define scopes in the request payload, Nylas uses the default scopes set on the relevant connector." Since there are no scopes on the imap connector (at least i cant specify any within the nylas dashboard), scopes should be optional on response and the SDK should be able to handle this.

SDK Version:
2.1.0

Additional context
Providing some scopes, e.g.:

CreateGrantRequest r = new CreateGrantRequest.Builder(AuthProvider.IMAP, settings)
				.scopes(List.of("Mail.Read", "User.Read", "offline_access")).build();

is a workaround.

Event ical_uid field

Is your feature request related to a problem? Please describe.
When I call Nylas Rest API endpoint /events/{event_id}
I can see that ical_uid field is present and it has the value filled.

But when I call Java methods

account.events().create(event);
account.events().get(event_id);

I get an Event object as a return value where ical_uid field is null .

Describe the solution you'd like
I'd like to have this field value filled.

Describe alternatives you've considered
No alternatives.

Additional context
I'm using Nylas Java SDK 1.17.0.