Added Contacts API Support (#513)

Contact group endpoint

Co-authored-by: Mostafa Rashed <17770919+mrashed-dev@users.noreply.github.com>

src/models/contacts.ts

@@ -0,0 +1,160 @@
+import { ListQueryParams } from './listQueryParams.js';
+
+/**
+ * Interface representing a Nylas Contact object.
+ */
+export interface Contact {
+  id: string;
+  grantId: string;
+  object: 'contact';
+  birthday?: string;
+  companyName?: string;
+  displayName: string;
+  emails: Email[];
+  imAddresses: InstantMessagingAddress[];
+  givenName?: string;
+  jobTitle?: string;
+  managerName?: string;
+  middleName?: string;
+  nickname?: string;
+  notes?: string;
+  officeLocation?: string;
+  pictureUrl?: string;
+  picture?: string;
+  suffix?: string;
+  surname?: string;
+  source?: SourceType;
+  phoneNumbers: PhoneNumber[];
+  physicalAddresses: PhysicalAddress[];
+  webPages: WebPage[];
+  groups: ContactGroup[];
+}
+
+/**
+ * Custom Types.
+ */
+export type ContactType = 'work' | 'home' | 'other';
+export type SourceType = 'address_book' | 'inbox' | 'domain';
+export type GroupType = 'user' | 'system' | 'other';
+
+/**
+ * Interface for email addresses in a contact.
+ */
+export interface Email {
+  email?: string;
+  type?: ContactType;
+}
+
+/**
+ * Interface for IM addresses in a contact.
+ */
+export interface InstantMessagingAddress {
+  type?: string;
+  imAddress?: string;
+}
+
+/**
+ * Interface for phone numbers in a contact.
+ */
+export interface PhoneNumber {
+  number?: string;
+  type?: ContactType;
+}
+
+/**
+ * Interface for physical addresses in a contact.
+ */
+export interface PhysicalAddress {
+  format?: string;
+  streetAddress?: string;
+  city?: string;
+  postalCode?: string;
+  state?: string;
+  country?: string;
+  type?: ContactType;
+}
+
+/**
+ * Interface for web pages in a contact.
+ */
+export interface WebPage {
+  url?: string;
+  type?: ContactType;
+}
+
+/**
+ * Interface representing a contact group.
+ */
+export interface ContactGroup {
+  id: string;
+  object: 'contact_group';
+  grantId?: string;
+  groupType?: GroupType;
+  name?: string;
+  path?: string;
+}
+
+/**
+ * Interface representing the query parameters for listing contacts.
+ */
+export interface ListContactQueryParams extends ListQueryParams {
+  /**
+   * Returns the contacts matching the exact contact's email.
+   */
+  email?: string;
+  /**
+   * Returns the contacts matching the contact's exact phone number
+   */
+  phoneNumber?: string;
+  /**
+   * Returns the contacts matching from the address book or auto-generated contacts from emails.
+   * For example of contacts only from the address book: /contacts?source=address_bookor for only autogenerated contacts:/contacts?source=inbox`
+   */
+  source?: string;
+  /**
+   * Returns the contacts belonging to the Contact Group matching this ID
+   */
+  group?: string;
+  /**
+   * When set to true, returns the contacts also within the specified Contact Group subgroups, if the group parameter is set.
+   */
+  recurse?: boolean;
+}
+
+/**
+ * Interface representing the query parameters for retrieving a single contact.
+ */
+export interface FindContactQueryParams {
+  profilePicture?: boolean;
+}
+
+/**
+ * Interface for creating a contact.
+ */
+export type CreateContactRequest = {
+  displayName?: string;
+  birthday?: string;
+  companyName?: string;
+  emails?: Email[];
+  givenName?: string;
+  imAddresses?: InstantMessagingAddress[];
+  jobTitle?: string;
+  managerName?: string;
+  middleName?: string;
+  nickname?: string;
+  notes?: string;
+  officeLocation?: string;
+  phoneNumbers?: PhoneNumber[];
+  physicalAddresses?: PhysicalAddress[];
+  suffix?: string;
+  surname?: string;
+  webPages?: WebPage[];
+  picture?: string;
+  source?: SourceType;
+  groups?: ContactGroup[];
+};
+
+/**
+ * Interface for updating a contact.
+ */
+export type UpdateContactRequest = CreateContactRequest;

src/nylas.ts

@@ -10,6 +10,7 @@ import { Drafts } from './resources/drafts.js';
 import { Threads } from './resources/threads.js';
 import { Connectors } from './resources/connectors.js';
 import { Folders } from './resources/folders.js';
+import { Contacts } from './resources/contacts.js';
 import { Attachments } from './resources/attachments.js';
 
 /**
@@ -23,6 +24,10 @@ export default class Nylas {
    * Access the Applications API
    */
   public applications: Applications;
+  /**
+   * Access the Attachments API
+   */
+  public attachments: Attachments;
   /**
    * Access the Auth API
    */
@@ -35,6 +40,10 @@ export default class Nylas {
    * Access the Connectors API
    */
   public connectors: Connectors;
+  /**
+   * Access the Contacts API
+   */
+  public contacts: Contacts;
   /**
    * Access the Drafts API
    */
@@ -59,10 +68,6 @@ export default class Nylas {
    * Access the Folders API
    */
   public folders: Folders;
-  /**
-   * Access the Attachments API
-   */
-  public attachments: Attachments;
 
   /**
    * The configured API client
@@ -90,6 +95,7 @@ export default class Nylas {
     this.threads = new Threads(this.apiClient);
     this.webhooks = new Webhooks(this.apiClient);
     this.folders = new Folders(this.apiClient);
+    this.contacts = new Contacts(this.apiClient);
     this.attachments = new Attachments(this.apiClient);
 
     return this;

src/resources/contacts.ts

@@ -0,0 +1,177 @@
+import { Overrides } from '../config.js';
+import {
+  CreateContactRequest,
+  Contact,
+  ListContactQueryParams,
+  FindContactQueryParams,
+  UpdateContactRequest,
+  ContactGroup,
+} from '../models/contacts.js';
+import {
+  NylasResponse,
+  NylasListResponse,
+  NylasDeleteResponse,
+} from '../models/response.js';
+import { AsyncListResponse, Resource } from './resource.js';
+
+/**
+ * @property contactId The id of the Contact to retrieve.
+ * @property identifier The identifier of the grant to act upon
+ * @property queryParams The query parameters to include in the request
+ */
+interface FindContactParams {
+  identifier: string;
+  contactId: string;
+  queryParams: FindContactQueryParams;
+}
+
+/**
+ * @property identifier The identifier of the grant to act upon
+ * @property queryParams The query parameters to include in the request
+ */
+interface ListContactParams {
+  identifier: string;
+  queryParams: ListContactQueryParams;
+}
+
+/**
+ * @property identifier The identifier of the grant to act upon
+ * @property requestBody The values to create the Contact with
+ */
+interface CreateContactParams {
+  identifier: string;
+  requestBody: CreateContactRequest;
+}
+
+/**
+ * @property identifier The identifier of the grant to act upon
+ * @property contactId The id of the Contact to retrieve.
+ * @property requestBody The values to update the Contact with
+ */
+interface UpdateContactParams {
+  identifier: string;
+  contactId: string;
+  requestBody: UpdateContactRequest;
+}
+
+/**
+ * @property identifier The identifier of the grant to act upon
+ * @property contactId The id of the Contact to retrieve.
+ */
+interface DestroyContactParams {
+  identifier: string;
+  contactId: string;
+}
+
+/**
+ * @property identifier The identifier of the grant to act upon
+ */
+interface ListContactGroupParams {
+  identifier: string;
+}
+
+/**
+ * Nylas Contacts API
+ *
+ * The Nylas Contacts API allows you to create, update, and delete contacts.
+ */
+export class Contacts extends Resource {
+  /**
+   * Return all Contacts
+   * @return The list of Contacts
+   */
+  public list({
+    identifier,
+    queryParams,
+    overrides,
+  }: ListContactParams & Overrides): AsyncListResponse<
+    NylasListResponse<Contact>
+  > {
+    return super._list({
+      queryParams,
+      path: `/v3/grants/${identifier}/contacts`,
+      overrides,
+    });
+  }
+
+  /**
+   * Return a Contact
+   * @return The Contact
+   */
+  public find({
+    identifier,
+    contactId,
+    queryParams,
+    overrides,
+  }: FindContactParams & Overrides): Promise<NylasResponse<Contact>> {
+    return super._find({
+      path: `/v3/grants/${identifier}/contacts/${contactId}`,
+      queryParams,
+      overrides,
+    });
+  }
+
+  /**
+   * Create a Contact
+   * @return The created Contact
+   */
+  public create({
+    identifier,
+    requestBody,
+    overrides,
+  }: CreateContactParams & Overrides): Promise<NylasResponse<Contact>> {
+    return super._create({
+      path: `/v3/grants/${identifier}/contacts`,
+      requestBody,
+      overrides,
+    });
+  }
+
+  /**
+   * Update a Contact
+   * @return The updated Contact
+   */
+  public update({
+    identifier,
+    contactId,
+    requestBody,
+    overrides,
+  }: UpdateContactParams & Overrides): Promise<NylasResponse<Contact>> {
+    return super._update({
+      path: `/v3/grants/${identifier}/contacts/${contactId}`,
+      requestBody,
+      overrides,
+    });
+  }
+
+  /**
+   * Delete a Contact
+   * @return The deletion response
+   */
+  public destroy({
+    identifier,
+    contactId,
+    overrides,
+  }: DestroyContactParams & Overrides): Promise<NylasDeleteResponse> {
+    return super._destroy({
+      path: `/v3/grants/${identifier}/contacts/${contactId}`,
+      overrides,
+    });
+  }
+
+  /**
+   * Return a Contact Group
+   * @return The list of Contact Groups
+   */
+  public groups({
+    identifier,
+    overrides,
+  }: ListContactGroupParams & Overrides): Promise<
+    NylasListResponse<ContactGroup>
+  > {
+    return super._list({
+      path: `/v3/grants/${identifier}/contacts/groups`,
+      overrides,
+    });
+  }
+}