-
Notifications
You must be signed in to change notification settings - Fork 18
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
# Description This PR is a culmination of all the PRs that contained v2-related development, with formal support for the Nylas API v3. This release is essentially the same as the v2.0.0-beta.5 release found on maven. This release also formally switches the development language of the SDK from Java to Kotlin, as well as the artifact name from `nylas-java-sdk` to `nylas`. Please refer to the readme for a quick start guide on using the new SDK, as well as links to the upgrade doc as well as the SDK reference docs. # Changelog ### BREAKING CHANGES * Renamed artifact from `nylas-java-sdk` to `nylas`. * Nylas SDK v2 supports the Nylas API v3 exclusively, dropping support for any endpoints that are not available in v3. * Removed all REST calls from models and moved them directly into resources ### Added * Full Kotlin support * Created models for all API resources and endpoints, for all HTTP methods to reduce confusion on which fields are available for each endpoint * Created error classes for the different API errors as well as SDK-specific errors ### Changed * Leveraged Moshi annotations for JSON serialization/deserialization as opposed to manually writing JSON maps * Removed all REST calls from models and moved them directly into resources ### Removed * Non-builder ways for initializing `NylasClient` * Local Webhook development support is removed due to incompatibility with the new API version # License <!-- Your PR comment must contain the following line for us to merge the PR. --> I confirm that this contribution is made under the terms of the MIT license and that I have the authority necessary to make this contribution on behalf of its copyright owner. --------- Co-authored-by: Aaron de Mello <[email protected]> Co-authored-by: Lrubin <[email protected]> Co-authored-by: LRubin <[email protected]> Co-authored-by: Blag <[email protected]> Co-authored-by: YIFAN WU <[email protected]>
- Loading branch information
6 people
authored
Feb 6, 2024
1 parent
52cf0ff
commit 9bc4b02
Showing
428 changed files
with
16,944 additions
and
22,170 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| root = true | ||
|
|
||
| [*.{kt,kts}] | ||
| ktlint_code_style = intellij_idea | ||
| indent_size = 2 | ||
| indent_style = space | ||
| ktlint_standard_no-wildcard-imports = disabled |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| name: sdk-reference | ||
|
|
||
| on: | ||
| push: | ||
| branches: | ||
| - main | ||
| pull_request: | ||
|
|
||
| jobs: | ||
| docs: | ||
| runs-on: ubuntu-latest | ||
| environment: | ||
| name: sdk-reference | ||
| url: ${{ steps.deploy.outputs.url }} | ||
| steps: | ||
| - uses: actions/checkout@v3 | ||
| - name: Setup Java 8 | ||
| uses: actions/setup-java@v3 | ||
| with: | ||
| java-version: "8" | ||
| distribution: "corretto" | ||
| cache: gradle | ||
| - uses: burrunan/gradle-cache-action@v1 | ||
| name: Build SDK refernece | ||
| with: | ||
| arguments: dokkaHtml | ||
| gradle-version: wrapper | ||
| properties: | | ||
| kotlin.js.compiler=ir | ||
| kotlin.parallel.tasks.in.project=true | ||
| - name: Set env BRANCH | ||
| run: echo "BRANCH=$(echo $GITHUB_REF | cut -d'/' -f 3)" >> $GITHUB_ENV | ||
| - name: Set env CLOUDFLARE_BRANCH | ||
| run: | | ||
| if [[ $BRANCH == 'main' && $GITHUB_EVENT_NAME == 'push' ]]; then | ||
| echo "CLOUDFLARE_BRANCH=main" >> "$GITHUB_ENV" | ||
| else | ||
| echo "CLOUDFLARE_BRANCH=$BRANCH" >> "$GITHUB_ENV" | ||
| fi | ||
| - name: Publish to Cloudflare Pages | ||
| uses: cloudflare/pages-action@v1 | ||
| id: deploy | ||
| with: | ||
| apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} | ||
| accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} | ||
| projectName: nylas-java-sdk-reference | ||
| directory: build/dokka/html | ||
| wranglerVersion: "3" | ||
| branch: ${{ env.CLOUDFLARE_BRANCH }} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -12,4 +12,6 @@ bin | |
| out | ||
|
|
||
| # Ignore Intellij files | ||
| .idea | ||
| .idea | ||
| .DS_Store | ||
| src/main/kotlin/com/nylas/Main.kt | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,75 +1,110 @@ | ||
| # Nylas Java SDK | ||
| This is the GitHub repository for the Nylas Java SDK and this repo is primarily for anyone who wants to make contributions to the SDK or install it from source. If you are looking to use Java to access the Nylas Email, Calendar, or Contacts API you should refer to our official [Java SDK Quickstart Guide](https://docs.nylas.com/docs/quickstart-java). | ||
| <a href="https://www.nylas.com/"> | ||
| <img src="https://brand.nylas.com/assets/downloads/logo_horizontal_png/Nylas-Logo-Horizontal-Blue_.png" alt="Aimeos logo" title="Aimeos" align="right" height="60" /> | ||
| </a> | ||
|
|
||
| The Nylas Communications Platform provides REST APIs for [Email](https://docs.nylas.com/docs/quickstart-email), [Calendar](https://docs.nylas.com/docs/quickstart-calendar), and [Contacts](https://docs.nylas.com/docs/quickstart-contacts), and the Java SDK is the quickest way to build your integration using Java. | ||
| # Nylas SDK for Kotlin & Java | ||
|
|
||
|  | ||
| [](https://codecov.io/gh/nylas/nylas-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](https://developer.nylas.com/docs/sdks/java/). | ||
|
|
||
| The Nylas Communications Platform provides REST APIs for [Email](https://developer.nylas.com/docs/email/), [Calendar](https://developer.nylas.com/docs/calendar/), and [Contacts](https://developer.nylas.com/docs/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: | ||
|
|
||
| - [Nylas SDK Tutorials](https://docs.nylas.com/docs/tutorials) | ||
| - [Get Started with the Nylas Communications Platform](https://docs.nylas.com/docs/getting-started) | ||
| - [Sign up for your Nylas developer account.](https://nylas.com/register) | ||
| - [Nylas API Reference](https://docs.nylas.com/reference) | ||
| - [Sign up for your free Nylas account](https://dashboard.nylas.com/register) | ||
| - [Nylas API v3 Quickstart Guide](https://developer.nylas.com/docs/v3-beta/v3-quickstart/) | ||
| - [Nylas SDK Reference](https://nylas-java-sdk-reference.pages.dev/) | ||
| - [Nylas API Reference](https://developer.nylas.com/docs/api/) | ||
| - [Nylas Samples repo for code samples and example applications](https://github.com/orgs/nylas-samples/repositories?q=&type=all&language=java) | ||
|
|
||
| If you have a question about the Nylas Communications Platform, [contact Nylas Support](https://support.nylas.com/) for help. | ||
|
|
||
| ## ⚙️ Install | ||
|
|
||
| If you have a question about the Nylas Communications Platform, please reach out to [email protected] to get help. | ||
| **Note:** The Nylas SDK for Kotlin & Java requires JRE 8 or later. | ||
|
|
||
| # Install | ||
| **Note:** The Nylas Java SDK requires Java 8 or above. | ||
| ### Set up using Gradle | ||
|
|
||
| **Setup via Gradle**: If you're using Gradle, add the following to your dependencies section of build.gradle: | ||
| If you're using Gradle, add the following to the dependencies section of `build.gradle`: | ||
|
|
||
| implementation("com.nylas.sdk:nylas-java-sdk:1.22.0") | ||
| ```groovy | ||
| implementation("com.nylas.sdk:nylas:2.0.0") | ||
| ``` | ||
|
|
||
| **Setup via Maven**: For projects using Maven, add the following to your POM file: | ||
| ### Build from source | ||
|
|
||
| <dependency> | ||
| <groupId>com.nylas.sdk</groupId> | ||
| <artifactId>nylas-java-sdk</artifactId> | ||
| <version>1.22.0</version> | ||
| </dependency> | ||
|
|
||
| **Build from source**: To build from source, clone this repo and build the project with Gradle. | ||
| 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 | ||
| ```shell | ||
| git clone https://github.com/nylas/nylas-java.git && cd nylas-java | ||
| ./gradlew build uberJar | ||
| ``` | ||
|
|
||
| This will create a new jar file in the `build/libs` subdirectory. | ||
| This creates a new jar file in `build/libs/nylas-java-sdk-2.0.0-uber.jar`. | ||
|
|
||
| See Gradle documentation on [Building Java Libraries](https://guides.gradle.org/building-java-libraries/) | ||
| See the Gradle documentation on [Building Libraries](https://guides.gradle.org/building-java-libraries/) | ||
| or the [Gradle User Manual](https://docs.gradle.org/current/userguide/userguide.html) for more information. | ||
|
|
||
| # Usage | ||
| ## ⚡️Usage | ||
|
|
||
| To use this SDK, you must first [get a free Nylas account](https://dashboard.nylas.com/register). | ||
|
|
||
| Then, follow the Quickstart guide to [set up your first app and get your API keys](https://developer.nylas.com/docs/v3-beta/v3-quickstart/). | ||
|
|
||
| For code examples that demonstrate how to use this SDK, take a look at our [Java repos in the Nylas Samples collection](https://github.com/orgs/nylas-samples/repositories?q=&type=all&language=java). | ||
|
|
||
| ### 🚀 Making Your First Request | ||
|
|
||
| To use this SDK, you first need to [sign up for a free Nylas developer account](https://nylas.com/register). | ||
| 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. | ||
|
|
||
| Then, follow our guide to [setup your first app and get your API access keys](https://docs.nylas.com/docs/get-your-developer-api-keys). | ||
| For example, to get a list of calendars, you can use the following code: | ||
|
|
||
| For code examples that demonstrate how to use this SDK, take a look at our [Java SDK Quickstart Guide](https://docs.nylas.com/docs/quickstart-java). | ||
| ```java | ||
| NylasClient nylas = new NylasClient.Builder("API_KEY").build(); | ||
| ListResponse<Calendars> calendars = nylas.calendars().list("GRANT_ID"); | ||
| ``` | ||
|
|
||
| ## Logging | ||
| ## 📚 Documentation | ||
|
|
||
| Nylas maintains a [reference guide for the Kotlin and Java SDK](https://nylas-java-sdk-reference.pages.dev/) to help you get familiar with the available methods and classes. | ||
|
|
||
| ## ✨ Upgrading from 1.x | ||
|
|
||
| See [UPGRADE.md](UPGRADING.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](http://www.slf4j.org) for logging. If you are using the SDK you can [choose what logging framework to use with it](http://www.slf4j.org/manual.html#projectDep) for your app. | ||
|
|
||
| The SDK uses [SLF4J](http://www.slf4j.org) for logging. Applications using the SDK can | ||
| [choose what logging framework to use with it](http://www.slf4j.org/manual.html#projectDep). | ||
| Common choices are log4j, logback, java.util.logging. If the application doesn't specify any logging framework, | ||
| then SLF4J will emit one warning and then be completely silent. | ||
| SLF4J emits one single warning and is then completely silent. | ||
|
|
||
| By default, the HTTP client is configured with the `com.nylas.HttpLoggingInterceptor` | ||
| which provides 3 loggers for HTTP requests that only log at DEBUG level. | ||
| - `com.nylas.http.Summary` logs one line for each request, containing method, URI, and content size | ||
| and one line for each response containing status code, message, content size and duration. | ||
| 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). | ||
|
|
||
| Enabling or disabling those loggers is done via the logging framework being used. | ||
| For example, if using log4j2 and with an xml configuration file, include this line to enable all three: | ||
| 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"/>` | ||
|
|
||
| Configuring the logging of the HTTP Authorization header values and the body size limit can be done by using a | ||
| You can configure how you log HTTP Authorization header values and the body size limit using a | ||
| `NylasClient.Builder` with a customized `HttpLoggingInterceptor` | ||
|
|
||
| # Contributing | ||
| ## 💙 Contributing | ||
|
|
||
| We value and appreciate contributors' time! We welcome questions, bug reports, and pull requests. | ||
|
|
||
| Please refer to [Contributing](Contributing.md) for information about how to make contributions to this project. We welcome questions, bug reports, and pull requests. | ||
| See the [Contributing](Contributing.md) for information about how to make contributions to this project. | ||
|
|
||
| # License | ||
| ## 📝 License | ||
|
|
||
| This project is licensed under the terms of the MIT license. Please refer to [LICENSE](LICENSE) for the full terms. | ||
| This project is licensed under the terms of the MIT license. See the [LICENSE](LICENSE) for the full terms. |
Oops, something went wrong.