Add support for listImportEvents method to import events from calendars (#623)

* Add support for listImportEvents method to import events from calendars

This adds support for the new beta endpoint GET /v3/grants/{grant_id}/events/import, which allows importing events from a calendar within a specified time frame. This is useful for applications that need to synchronize events with their own calendaring solution or enrich events with custom data.

* Rename ImportEventQueryParams to ListImportEventQueryParams for consistency

* Renamed max_results to limit for listImportEvents

* Ran prettier

Author: AaronDDM

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+### Unreleased
+* Add support for `listImportEvents` method to import events from a specified calendar within a given time frame
+
 ### 7.7.4 / 2025-01-23
 * Fix: any_email was not transformed to a comma delimited list for messages.list
 
@@ -91,7 +94,7 @@
 * **BREAKING CHANGE**: Dropped the use of 'Collections' in favor of 'Resources'
 * **BREAKING CHANGE**: Removed all REST calls from models and moved them directly into resources
 * **REMOVED**: Local Webhook development support is removed due to incompatibility
-* Rewrote the majority of SDK to be more modular and efficient
+* Rewritten the majority of SDK to be more modular and efficient
 * Removed the use of custom strings for serialization and deserialization, now automatically converting to camelCase and from the API's snake_case
 * Added support for both ES6 and CommonJS module systems
 * Created models for all API resources and endpoints, for all HTTP methods to reduce confusion on which fields are available for each endpoint
@@ -416,7 +419,7 @@ Note: version 4.2.1 was not released.
 * Added `upgrade()` and `downgrade()` for account management
 * Added `getRaw()` for retrieving raw messages
 * **BREAKING CHANGE**: Changed API for sending raw messages to use `draft.send()` instead of `Message.sendRaw()`
-* Changed `list()` to override default `offset` with user’s
+* Changed `list()` to override default `offset` with user's
 * **BREAKING CHANGE**: Changed models for `Contact`, `Draft`, `Event`, `File`, `Folder`, `Message`, and `Thread` to accurately reflect the attribute that the API returns
 * Return headers correctly for `expanded` view for `Message` objects
 * **BREAKING CHANGE**: Return `Message` object instead of `Draft` object after send

src/models/events.ts

@@ -333,6 +333,27 @@ export type DestroyEventQueryParams = CreateEventQueryParams;
  */
 export type SendRsvpQueryParams = FindEventQueryParams;
 
+/**
+ * Interface representing the query parameters for importing events.
+ */
+export interface ListImportEventQueryParams extends ListQueryParams {
+  /**
+   * (Required) Calendar ID to import events from. "primary" is a supported value indicating the user's primary calendar.
+   * Note: "primary" is not supported for iCloud.
+   */
+  calendarId: string;
+  /**
+   * Filter for events that start at or after the specified time, in Unix timestamp format.
+   * Defaults to the time of the request.
+   */
+  start?: number;
+  /**
+   * Filter for events that end at or before the specified time, in Unix timestamp format.
+   * Defaults to one month from the time of the request.
+   */
+  end?: number;
+}
+
 /**
  * Enum representing the status of an event.
  */

src/resources/events.ts

@@ -5,6 +5,7 @@ import {
   DestroyEventQueryParams,
   Event,
   FindEventQueryParams,
+  ListImportEventQueryParams,
   ListEventQueryParams,
   SendRsvpQueryParams,
   SendRsvpRequest,
@@ -74,6 +75,15 @@ export interface DestroyEventParams {
   queryParams: DestroyEventQueryParams;
 }
 
+/**
+ * @property identifier The identifier of the grant to act upon
+ * @property queryParams The query parameters to include in the request
+ */
+export interface ListImportEventParams {
+  identifier: string;
+  queryParams: ListImportEventQueryParams;
+}
+
 /**
  * @property identifier The identifier of the grant to act upon
  * @property eventId The id of the Event to update.
@@ -109,6 +119,25 @@ export class Events extends Resource {
     });
   }
 
+  /**
+   * (Beta) Import events from a calendar within a given time frame
+   * This is useful when you want to import, store, and synchronize events from the time frame to your application
+   * @return The list of imported Events
+   */
+  public listImportEvents({
+    identifier,
+    queryParams,
+    overrides,
+  }: ListImportEventParams & Overrides): AsyncListResponse<
+    NylasListResponse<Event>
+  > {
+    return super._list({
+      queryParams,
+      path: `/v3/grants/${identifier}/events/import`,
+      overrides,
+    });
+  }
+
   /**
    * Return an Event
    * @return The Event

tests/resources/events.spec.ts

@@ -128,6 +128,88 @@ describe('Events', () => {
     //TODO::More iterator tests
   });
 
+  describe('listImportEvents', () => {
+    it('should call apiClient.request with the correct params', async () => {
+      await events.listImportEvents({
+        identifier: 'id123',
+        queryParams: {
+          calendarId: 'calendar123',
+          start: 1617235200,
+          end: 1619827200,
+          limit: 100,
+          select: 'id,name',
+        },
+        overrides: {
+          apiUri: 'https://test.api.nylas.com',
+          headers: { override: 'bar' },
+        },
+      });
+
+      expect(apiClient.request).toHaveBeenCalledWith({
+        method: 'GET',
+        path: '/v3/grants/id123/events/import',
+        queryParams: {
+          calendarId: 'calendar123',
+          start: 1617235200,
+          end: 1619827200,
+          limit: 100,
+          select: 'id,name',
+        },
+        overrides: {
+          apiUri: 'https://test.api.nylas.com',
+          headers: { override: 'bar' },
+        },
+      });
+    });
+
+    it('should paginate correctly with page_token for import events', async () => {
+      apiClient.request.mockResolvedValueOnce({
+        requestId: 'request123',
+        data: [
+          {
+            id: 'id',
+            name: 'name',
+          },
+        ],
+        nextCursor: 'cursor123',
+      });
+      const eventList = await events.listImportEvents({
+        identifier: 'id123',
+        queryParams: {
+          calendarId: 'calendar123',
+        },
+        overrides: {
+          apiUri: 'https://test.api.nylas.com',
+          headers: { override: 'bar' },
+        },
+      });
+      apiClient.request.mockResolvedValueOnce({
+        requestId: 'request123',
+        data: [
+          {
+            id: 'id',
+            name: 'name',
+          },
+        ],
+      });
+      await eventList.next();
+
+      expect(apiClient.request).toBeCalledTimes(2);
+      expect(apiClient.request).toHaveBeenLastCalledWith({
+        method: 'GET',
+        path: '/v3/grants/id123/events/import',
+        queryParams: {
+          calendarId: 'calendar123',
+          pageToken: 'cursor123',
+        },
+        overrides: {
+          apiUri: 'https://test.api.nylas.com',
+          headers: { override: 'bar' },
+        },
+      });
+    });
+  });
+
   describe('find', () => {
     it('should call apiClient.request with the correct params', async () => {
       await events.find({