@friggframework/api-module-zoho-crm 2.0.0-next.0 → 2.0.0-next.2

package/README.md

@@ -1,29 +1,33 @@
-# Zoho CRM
+# Zoho CRM API Module
 
-This is the API Module for Zoho CRM that allows the [Frigg](https://friggframework.org) code to talk to the Zoho CRM API.
+This is the TypeScript API Module for Zoho CRM that allows [Frigg](https://friggframework.org) applications to interact with the Zoho CRM API v8.
 
-[Link to the Zoho CRM REST API Postman collection.](https://www.postman.com/zohocrmdevelopers/workspace/zoho-crm-developers/collection/8522016-0a15778a-ccb1-4676-98b7-4cf1fe7fc940?ctx=documentation)
+**Features:**
+- TypeScript with full type definitions
+- OAuth 2.0 authentication
+- Support for Users, Roles, Profiles, Contacts, Leads, and Accounts resources
+- Comprehensive error handling
+- Vitest test suite
 
-Read more on the [Frigg documentation site](https://docs.friggframework.org/api-modules/list/zoho-crm
+[Link to the Zoho CRM REST API Postman collection](https://www.postman.com/zohocrmdevelopers/workspace/zoho-crm-developers/collection/8522016-0a15778a-ccb1-4676-98b7-4cf1fe7fc940?ctx=documentation)
 
+Read more on the [Frigg documentation site](https://docs.friggframework.org/api-modules/list/zoho-crm)
 
-## Setup a Zoho CRM developer account 
+## Setup a Zoho CRM Developer Account
 
-In order to test this api module, you will need to populate your local `.env` file with a set of credentials (`ZOHO_CRM_CLIENT_ID` and `ZOHO_CRM_CLIENT_SECRET`).
+To test this API module, you'll need to populate your local `.env` file with credentials (`ZOHO_CRM_CLIENT_ID` and `ZOHO_CRM_CLIENT_SECRET`).
 
-To get those, you will need to sign up for a Zoho CRM developer account and [create a new API client](https://www.zoho.com/crm/developer/docs/api/v6/register-client.html), which is explained below.
+To get these credentials, sign up for a Zoho CRM developer account and [create a new API client](https://www.zoho.com/crm/developer/docs/api/v8/register-client.html).
 
-If you've already done this, skip to the next section. 
+If you've already done this, skip to the next section.
 
 1. Go to https://www.zoho.com/crm/developer/ and click `Sign Up For Free`
 ![alt text](images/image.jpg)
 
-
 2. Once you're in, set up your example company. Check the `Load Sample Data` box.
 ![alt text](images/image-1.jpg)
 
-
-3. Go to your account's API Console at https://api-console.zoho.com/.
+3. Go to your account's API Console at https://api-console.zoho.com/
 
     * You may be asked to verify your email address before accessing your API Console
     ![alt text](images/image-2.jpg)
@@ -31,239 +35,221 @@ If you've already done this, skip to the next section.
     * You'll receive an email with a verification link
     ![alt text](images/image-3.jpg)
 
-
-4. From your API Console, you are able to create client for your account. For our purposes, select `Server-based Applications`.
+4. From your API Console, create a client for your account. Select `Server-based Applications`.
 ![alt text](images/image-5.jpg)
 
-
-5. When filling in the details for your new client, make sure to use `http://localhost:3000/redirect/zoho-crm` in the `Authorized Redirect URIs` field.
+5. When filling in the details for your new client, use `http://localhost:3000/redirect/zoho-crm` in the `Authorized Redirect URIs` field.
 ![alt text](images/image-6.jpg)
 
-
-6. After creating the client, you will be sent to the `Client Secret` tab where you can grab your Client ID and Client Secret.
+6. After creating the client, you'll be sent to the `Client Secret` tab where you can grab your Client ID and Client Secret.
 ![alt text](images/image-7.jpg)
 
+## Set Up Your Local `.env` File
 
-## Set up your local `.env` file
-
-1. Make a copy of `.env.example` and name it `.env`.
-
+1. Make a copy of `.env.example` and name it `.env`
 
-2. Grab your Client ID and Client Secret from the Zoho CRM API Console and paste them into your local `.env` file. It should look something like this:
+2. Paste your Client ID and Client Secret from the Zoho CRM API Console into your `.env` file:
     ```shell
     ZOHO_CRM_CLIENT_ID=your_client_id
     ZOHO_CRM_CLIENT_SECRET=your_client_secret
-    ZOHO_CRM_SCOPE=ZohoCRM.users.ALL,ZohoCRM.org.ALL,ZohoCRM.settings.roles.ALL,ZohoCRM.settings.profiles.ALL
+    ZOHO_CRM_SCOPE=ZohoCRM.users.ALL,ZohoCRM.org.ALL,ZohoCRM.settings.roles.ALL,ZohoCRM.settings.profiles.ALL,ZohoCRM.modules.contacts.ALL,ZohoCRM.modules.leads.ALL,ZohoCRM.modules.accounts.ALL
     REDIRECT_URI=http://localhost:3000/redirect
     ```
 
+## Available API Resources
 
-## Using the api module from the terminal
+### Users
+- `listUsers(queryParams)` - List all users with optional filters
+- `getUser(userId)` - Get a specific user by ID
+- `createUser(body)` - Create a new user
+- `updateUser(userId, body)` - Update an existing user
+- `deleteUser(userId)` - Delete a user
 
-With your `.env` in place, you can now open a terminal to play around with the available APIs.
+### Roles
+- `listRoles()` - List all roles
+- `getRole(roleId)` - Get a specific role by ID
+- `createRole(body)` - Create a new role
+- `updateRole(roleId, body)` - Update an existing role
+- `deleteRole(roleId, queryParams)` - Delete a role
 
-1. Start a `node` terminal in `packages/zoho-crm`
+### Profiles
+- `listProfiles()` - List all profiles
 
-2. Paste the following code into the terminal:
-    ```js
-        require('dotenv').config();
-        const {Authenticator} = require('@friggframework/test');
-        const {Api} = require('./api.js');
+### Contacts
+- `listContacts(queryParams)` - List contacts with optional filters (fields, per_page, page, sort_by, sort_order)
+- `getContact(contactId)` - Get a specific contact by ID
+- `searchContacts(searchParams)` - Search contacts by email, phone, criteria, or word
 
-        api = new Api({
-            client_id: process.env.ZOHO_CRM_CLIENT_ID,
-            client_secret: process.env.ZOHO_CRM_CLIENT_SECRET,
-            scope: process.env.ZOHO_CRM_SCOPE,
-            redirect_uri: `${process.env.REDIRECT_URI}/zoho-crm`,
-        });
+### Leads
+- `listLeads(queryParams)` - List leads with optional filters (fields, per_page, page, sort_by, sort_order)
+- `getLead(leadId)` - Get a specific lead by ID
+- `searchLeads(searchParams)` - Search leads by email, phone, criteria, or word
 
-        const url = await api.getAuthUri();
-        const response = await Authenticator.oauth2(url);
-        const baseArr = response.base.split('/');
-        response.entityType = baseArr[baseArr.length - 1];
-        delete response.base;
+### Accounts
+- `listAccounts(queryParams)` - List accounts with optional filters (fields, per_page, page, sort_by, sort_order)
+- `getAccount(accountId)` - Get a specific account by ID
+- `searchAccounts(searchParams)` - Search accounts by phone, criteria, or word
 
-        await api.getTokenFromCode(response.data.code);
+## Using the API Module from the Terminal
 
-        console.log('api ready!');
+With your `.env` in place, you can test the API from a Node terminal.
 
+1. Build the module first:
+    ```bash
+    npm run build
     ```
 
-3. Your browser will open a tab and send you to Zoho CRM to authorize the client. You may need to log in first.
-    ![alt text](images/image-9.jpg)
-
-
-4. After authorizing, the tokens are returned to your terminal where they are used to create an authenticated instance of the Zoho CRM API module in the `api` variable. From here you can call any of the existing API resources defined in the module.
-    * List existing Users:
-        ```js
-        > await api.listUsers()
-        {
-          users: [
-            {
-              country: 'HN',
-              name_format__s: 'Salutation,First Name,Last Name',
-              language: 'en_US',
-              microsoft: false,
-              '$shift_effective_from': null,
-              id: '6238474000000461001',
-              state: 'Francisco Morazan',
-              fax: null,
-              country_locale: 'en_US',
-              sandboxDeveloper: false,
-              zip: null,
-              decimal_separator: 'Period',
-              created_time: '2024-04-20T10:35:36-06:00',
-              time_format: 'hh:mm a',
-              offset: -21600000,
-              profile: [Object],
-              created_by: [Object],
-              zuid: '851289894',
-              full_name: 'Armando Alvarado',
-              phone: '32415425',
-              dob: null,
-              sort_order_preference__s: 'First Name,Last Name',
-              status: 'active',
-              role: [Object],
-              customize_info: [Object],
-              city: null,
-              signature: null,
-              locale: 'en_US',
-              personal_account: false,
-              Source__s: null,
-              Isonline: false,
-              default_tab_group: '0',
-              Modified_By: [Object],
-              street: null,
-              '$current_shift': null,
-              alias: null,
-              theme: [Object],
-              first_name: 'Armando Alvarado',
-              email: 'aaj2006@hotmail.com',
-              status_reason__s: null,
-              website: null,
-              Modified_Time: '2024-04-20T10:37:55-06:00',
-              '$next_shift': null,
-              mobile: null,
-              last_name: null,
-              time_zone: 'America/Tegucigalpa',
-              number_separator: 'Comma',
-              confirm: true,
-              date_format: 'MM-dd-yyyy',
-              category: 'regular_user'
-            }
-          ]
-        }
-        ```
-
-    * List existing Roles:
-        ```js
-        > await api.listRoles()
-        {
-          roles: [
-            {
-              display_label: 'CEO',
-              created_by__s: null,
-              modified_by__s: null,
-              forecast_manager: null,
-              share_with_peers: true,
-              modified_time__s: null,
-              name: 'CEO',
-              description: 'Users with this role have access to   the data owned by all other users.',
-              reporting_to: null,
-              id: '6238474000000026005',
-              created_time__s: null
-            },
-            {
-              display_label: 'Manager',
-              created_by__s: null,
-              modified_by__s: null,
-              forecast_manager: null,
-              share_with_peers: false,
-              modified_time__s: null,
-              name: 'Manager',
-              description: 'Users belonging to this role cannot   see data for admin users.',
-              reporting_to: [Object],
-              id: '6238474000000026008',
-              created_time__s: null
-            }
-          ]
-        }
-        ```
+2. Start a `node` terminal in `packages/v1-ready/zoho-crm`
 
-## Using this API module in a Frigg instance
-1. Run `npm install @friggframework/api-module-zoho-crm`
+3. Paste the following code:
+    ```js
+    require('dotenv').config();
+    const {Authenticator} = require('@friggframework/test');
+    const {Api} = require('./dist/api.js');
+
+    api = new Api({
+        client_id: process.env.ZOHO_CRM_CLIENT_ID,
+        client_secret: process.env.ZOHO_CRM_CLIENT_SECRET,
+        scope: process.env.ZOHO_CRM_SCOPE,
+        redirect_uri: `${process.env.REDIRECT_URI}/zoho-crm`,
+    });
+
+    const url = api.getAuthUri();
+    const response = await Authenticator.oauth2(url);
+    const baseArr = response.base.split('/');
+    response.entityType = baseArr[baseArr.length - 1];
+    delete response.base;
+
+    await api.getTokenFromCode(response.data.code);
+
+    console.log('api ready!');
+    ```
+
+4. Your browser will open and send you to Zoho CRM to authorize the client. You may need to log in first.
+![alt text](images/image-9.jpg)
+
+5. After authorizing, the tokens are returned to your terminal and used to create an authenticated API instance. You can now call any API method:
+
+    **List Users:**
+    ```js
+    await api.listUsers()
+    ```
 
-2. Populate your `.env` file with `ZOHO_CRM_CLIENT_ID`, `ZOHO_CRM_CLIENT_SECRET`, and `ZOHO_CRM_SCOPE`.
+    **List Roles:**
+    ```js
+    await api.listRoles()
+    ```
 
-3. Create a subclass of `IntegrationBase` from `@friggframework/core` in `src/integrations` and plug in the Zoho CRM API module. Example:
+    **List Contacts:**
     ```js
-    const { IntegrationBase, Options } = require('@friggframework/core');
-    const { Definition: ZohoCRMModule } = require('@friggframework/api-module-zoho-crm');
-    const _ = require('lodash');
+    await api.listContacts({ per_page: 10, fields: 'First_Name,Last_Name,Email' })
+    ```
+
+    **Get Contact by ID:**
+    ```js
+    await api.getContact('contact_id_here')
+    ```
+
+    **Search Contacts:**
+    ```js
+    await api.searchContacts({ email: 'example@email.com' })
+    ```
+
+## Using this API Module in a Frigg Application
+
+1. Install the module:
+    ```bash
+    npm install @friggframework/api-module-zoho-crm
+    ```
+
+2. Populate your `.env` file with `ZOHO_CRM_CLIENT_ID`, `ZOHO_CRM_CLIENT_SECRET`, and `ZOHO_CRM_SCOPE`
+
+3. Create a Frigg integration class:
+    ```typescript
+    import { IntegrationBase } from '@friggframework/core';
+    import { Definition as ZohoCRMModule } from '@friggframework/api-module-zoho-crm';
 
     class ZohoCRMIntegration extends IntegrationBase {
-        static Config = {
-            name: 'zoho-crm',
+        static Definition = {
+            name: 'zohoCrm',
             version: '1.0.0',
-            supportedVersions: ['1.0.0'],
-            events: ['GET_SOMETHING'],
+            display: {
+                name: 'Zoho CRM',
+                description: 'Zoho CRM integration for managing contacts, users, and roles',
+                category: 'CRM',
+            },
+            modules: {
+                'zohoCrm': ZohoCRMModule
+            }
         };
 
-        static Options =
-            new Options({
-                module: ZohoCRMModule,
-                integrations: [ZohoCRMModule],
-                display: {
-                    name: 'Zoho CRM',
-                    description: 'CRM Stuff',
-                    category: 'CRM',
-                    detailsUrl: 'https://www.zoho.com/crm/',
-                    icon: 'https://static.zohocdn.com/crm/images/favicon_cbfca4856ba4bfb37be615b152f95251_.ico',
-                }
-            });
-
-        static modules = {
-            'zoho-crm': ZohoCRMModule
+        constructor() {
+            super();
+            this.events = {
+                LIST_CONTACTS: { handler: this.listContacts },
+                GET_CONTACT: { handler: this.getContact },
+            };
         }
 
-        /**
-        * HANDLE EVENTS
-        */
-        async receiveNotification(notifier, event, object = null) {
-            if (event === 'GET_SOMETHING') {
-                return this.target.api.getProjects();
-            }
+        async listContacts(params) {
+            return this.modules['zoho-crm'].api.listContacts(params);
         }
 
-        /**
-        * ALL CUSTOM/OPTIONAL METHODS FOR AN INTEGRATION
-        */
-        async getSampleData() {
-            const response = await this.target.api.listRoles();
-            const data = response.roles.map(role => ({
-                'Id': role.id,
-                'Name': role.name,
-                'Description': role.description,
-            }));
-            return {data};
+        async getContact(params) {
+            return this.modules['zoho-crm'].api.getContact(params.contactId);
         }
     }
-    
-    module.exports = ZohoCRMIntegration;
+
+    export default ZohoCRMIntegration;
     ```
 
-4. Plug your subclass into your app definition's `integrations` array. 
+4. Register your integration in your Frigg app definition's `integrations` array
 ![alt text](images/image-11.jpg)
 
-5. Zoho CRM should now appear in your list of available integrations
+5. Zoho CRM will appear in your list of available integrations
 ![alt text](images/image-12.jpg)
 
+## Development
+
+### Build
+```bash
+npm run build
+```
+
+### Run Tests
+The API tests verify CRUD operations work as expected. You'll need valid credentials in your `.env` file.
+
+```bash
+npm test
+```
+
+When running tests, a browser tab will open requesting authorization. After authorizing, the tests will run.
+
+**Note:** There is a 240-second timeout for authorization requests.
+
+### Watch Mode
+```bash
+npm run test:watch
+```
+
+## TypeScript Support
+
+This module is written in TypeScript and includes full type definitions. Import types as needed:
+
+```typescript
+import { Api, ZohoConfig, ContactsResponse, QueryParams } from '@friggframework/api-module-zoho-crm';
+```
+
+## API Version
+
+This module uses **Zoho CRM API v8**. The base URL is `https://www.zohoapis.com/crm/v8`.
 
-## Running the tests
+## Dependencies
 
-The API tests verify that the usual CRUD operations against the API resources work as expected. Because of that, you will need to have a valid set of credentials in your local `.env` file.
+- `@friggframework/core` ^2.0.0-next.16
+- `dotenv` ^16.0.0
+- `form-data` (for OAuth token exchange)
 
-When running `npm run test`, a browser tab will open to ask you for authorization. After you've authorized, the tests will run and produce an output similar to this:
-![alt text](images/image-10.jpg)
+## License
 
-**Note:** There is a 30-second timeout for the authorization request. You may need to try again if your browser does not open fast enough.
+MIT

package/dist/api.d.ts

@@ -0,0 +1,101 @@
+import { OAuth2Requester } from '@friggframework/core';
+import { ZohoConfig, QueryParams, SearchParams, UsersResponse, RolesResponse, ProfilesResponse, ContactsResponse, ContactResponse, LeadsResponse, LeadResponse, AccountsResponse, AccountResponse, TokenResponse, CreateNoteData, NotesResponse, NoteListResponse, NotificationWatchConfig, NotificationResponse, NotificationDetailsResponse } from './types';
+export declare class Api extends OAuth2Requester {
+    URLs: Record<string, string | ((id: string) => string)>;
+    private static readonly CONTACTS_DEFAULT_FIELDS;
+    private static readonly LEADS_DEFAULT_FIELDS;
+    private static readonly ACCOUNTS_DEFAULT_FIELDS;
+    constructor(params: ZohoConfig);
+    getAuthUri(): string;
+    getTokenFromCode(code: string): Promise<TokenResponse>;
+    _delete(options: any): Promise<any>;
+    /**
+     * Build URL for notes endpoints with proper encoding
+     * @param module - Module API name (e.g., 'Contacts', 'Leads')
+     * @param recordId - Record ID
+     * @param noteId - Optional note ID for specific note operations
+     * @returns Encoded URL path for notes endpoint
+     */
+    private buildNotesUrl;
+    listUsers(queryParams?: QueryParams): Promise<UsersResponse>;
+    getUser(userId: string): Promise<UsersResponse>;
+    createUser(body?: any): Promise<any>;
+    updateUser(userId: string, body?: any): Promise<any>;
+    deleteUser(userId: string): Promise<any>;
+    listRoles(): Promise<RolesResponse>;
+    getRole(roleId: string): Promise<RolesResponse>;
+    createRole(body?: any): Promise<any>;
+    updateRole(roleId: string, body?: any): Promise<any>;
+    deleteRole(roleId: string, queryParams?: any): Promise<any>;
+    listProfiles(): Promise<ProfilesResponse>;
+    listContacts(queryParams?: QueryParams): Promise<ContactsResponse>;
+    getContact(contactId: string): Promise<ContactResponse>;
+    searchContacts(searchParams?: SearchParams): Promise<ContactsResponse>;
+    listLeads(queryParams?: QueryParams): Promise<LeadsResponse>;
+    getLead(leadId: string): Promise<LeadResponse>;
+    searchLeads(searchParams?: SearchParams): Promise<LeadsResponse>;
+    listAccounts(queryParams?: QueryParams): Promise<AccountsResponse>;
+    getAccount(accountId: string): Promise<AccountResponse>;
+    searchAccounts(searchParams?: SearchParams): Promise<AccountsResponse>;
+    /**
+     * List all notes for a specific record
+     * @param module - Module API name (Contacts, Leads, Accounts, etc.)
+     * @param recordId - Record ID to get notes for
+     * @param queryParams - Optional query parameters (per_page, page, etc.)
+     * @returns Promise<NoteListResponse> Notes list response
+     */
+    listNotes(module: string, recordId: string, queryParams?: QueryParams): Promise<NoteListResponse>;
+    /**
+     * Get a specific note by ID
+     * @param module - Module API name (Contacts, Leads, Accounts, etc.)
+     * @param recordId - Record ID the note is attached to
+     * @param noteId - Note ID to retrieve
+     * @returns Promise<NotesResponse> Note details
+     */
+    getNote(module: string, recordId: string, noteId: string): Promise<NotesResponse>;
+    /**
+     * Create a note for a specific record
+     * @param module - Module API name (Contacts, Leads, Accounts, etc.)
+     * @param recordId - Record ID to attach note to
+     * @param noteData - Note data with Note_Content (required) and optional Note_Title
+     * @returns Promise<NotesResponse> Created note response
+     */
+    createNote(module: string, recordId: string, noteData: CreateNoteData): Promise<NotesResponse>;
+    /**
+     * Update an existing note
+     * @param module - Module API name (Contacts, Leads, Accounts, etc.)
+     * @param recordId - Record ID the note is attached to
+     * @param noteId - Note ID to update
+     * @param noteData - Updated note data. At least one of Note_Content or Note_Title must be provided.
+     * @returns Promise<NotesResponse> Updated note response
+     */
+    updateNote(module: string, recordId: string, noteId: string, noteData: Partial<CreateNoteData>): Promise<NotesResponse>;
+    /**
+     * Delete a note
+     * @param module - Module API name (Contacts, Leads, Accounts, etc.)
+     * @param recordId - Record ID the note is attached to
+     * @param noteId - Note ID to delete
+     * @returns Promise<NotesResponse> Deletion response
+     */
+    deleteNote(module: string, recordId: string, noteId: string): Promise<NotesResponse>;
+    /**
+     * Enable notification channel to receive real-time events
+     * @param body - Notification configuration with watch items
+     * @returns Promise<NotificationResponse> Response with channel details
+     * @see https://www.zoho.com/crm/developer/docs/api/v8/notifications/enable.html
+     */
+    enableNotification(body: NotificationWatchConfig): Promise<NotificationResponse>;
+    /**
+     * Disable notification channels
+     * @param channelIds - Array of channel IDs to disable
+     * @returns Promise<NotificationResponse> Response confirming deletion
+     * @see https://www.zoho.com/crm/developer/docs/api/v8/notifications/disable.html
+     */
+    disableNotification(channelIds: Array<string | number>): Promise<NotificationResponse>;
+    /**
+     * Get details of all active notification channels
+     * @returns Promise<NotificationDetailsResponse> Details of all active channels
+     * @see https://www.zoho.com/crm/developer/docs/api/v8/notifications/get-details.html
+     */
+    getNotificationDetails(): Promise<NotificationDetailsResponse>;
+}