@friggframework/api-module-zoho-crm 2.0.0-next.1 → 2.0.0-next.3

package/README.md

@@ -52,7 +52,7 @@ If you've already done this, skip to the next section.
     ```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,ZohoCRM.modules.contacts.ALL,ZohoCRM.modules.leads.ALL,ZohoCRM.modules.accounts.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 ZohoCRM.modules.calls.ALL
     REDIRECT_URI=http://localhost:3000/redirect
     ```
 
@@ -90,6 +90,21 @@ If you've already done this, skip to the next section.
 - `getAccount(accountId)` - Get a specific account by ID
 - `searchAccounts(searchParams)` - Search accounts by phone, criteria, or word
 
+### Calls
+- `logCall(callData)` - Log a call in the Zoho CRM Calls module
+- `updateCall(callId, callData)` - Update an existing call record
+
+**Call Data Fields:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `Subject` | string | Yes | Call subject/title |
+| `Call_Type` | string | Yes | `Inbound`, `Outbound`, or `Missed` |
+| `Call_Start_Time` | string | Yes | ISO 8601 datetime |
+| `Call_Duration` | string | Yes* | `mm:ss` format (*required for Inbound/Outbound, cannot be zero) |
+| `Description` | string | No | Call notes |
+| `Who_Id` | string | No | Contact/Lead ID to associate |
+| `$se_module` | string | No | Module for Who_Id: `Contacts` or `Leads` |
+
 ## Using the API Module from the Terminal
 
 With your `.env` in place, you can test the API from a Node terminal.

package/dist/api.d.ts

@@ -1,5 +1,5 @@
 import { OAuth2Requester } from '@friggframework/core';
-import { ZohoConfig, QueryParams, SearchParams, UsersResponse, RolesResponse, ProfilesResponse, ContactsResponse, ContactResponse, LeadsResponse, LeadResponse, AccountsResponse, AccountResponse, TokenResponse } from './types';
+import { ZohoConfig, QueryParams, SearchParams, UsersResponse, RolesResponse, ProfilesResponse, ContactsResponse, ContactResponse, LeadsResponse, LeadResponse, AccountsResponse, AccountResponse, TokenResponse, CreateNoteData, NotesResponse, NoteListResponse, NotificationWatchConfig, NotificationResponse, NotificationDetailsResponse, ZohoCallData, CallsResponse } from './types';
 export declare class Api extends OAuth2Requester {
     URLs: Record<string, string | ((id: string) => string)>;
     private static readonly CONTACTS_DEFAULT_FIELDS;
@@ -9,6 +9,14 @@ export declare class Api extends OAuth2Requester {
     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>;
@@ -29,4 +37,80 @@ export declare class Api extends OAuth2Requester {
     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>;
+    /**
+     * Log a call in Zoho CRM Calls module
+     * @param callData - Call record data with Subject, Call_Type, Call_Start_Time, Call_Duration
+     * @returns Promise<CallsResponse> Created call response
+     * @see https://www.zoho.com/crm/developer/docs/api/v8/insert-records.html
+     */
+    logCall(callData: ZohoCallData): Promise<CallsResponse>;
+    /**
+     * Update an existing call record in Zoho CRM Calls module
+     * @param callId - Zoho Call ID to update
+     * @param callData - Partial call data to update (e.g., Description, Subject)
+     * @returns Promise<CallsResponse> Updated call response
+     * @see https://www.zoho.com/crm/developer/docs/api/v8/update-records.html
+     */
+    updateCall(callId: string, callData: Partial<ZohoCallData>): Promise<CallsResponse>;
 }

package/dist/api.js

@@ -26,6 +26,9 @@ class Api extends core_1.OAuth2Requester {
             accounts: '/Accounts',
             account: (accountId) => `/Accounts/${accountId}`,
             accountSearch: '/Accounts/search',
+            calls: '/Calls',
+            call: (callId) => `/Calls/${callId}`,
+            notificationsWatch: '/actions/watch',
         };
     }
     getAuthUri() {
@@ -52,6 +55,20 @@ class Api extends core_1.OAuth2Requester {
         const response = await super._delete(options);
         return await this.parsedBody(response);
     }
+    /**
+     * 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
+     */
+    buildNotesUrl(module, recordId, noteId) {
+        const segments = [module, recordId, 'Notes'];
+        if (noteId)
+            segments.push(noteId);
+        const encodedPath = segments.map(encodeURIComponent).join('/');
+        return `${this.baseUrl}/${encodedPath}`;
+    }
     async listUsers(queryParams = {}) {
         return this._get({
             url: this.baseUrl + this.URLs.users,
@@ -186,6 +203,12 @@ class Api extends core_1.OAuth2Requester {
             });
         }
         catch (error) {
+            // Zoho returns 204 No Content with empty body when no results found
+            // This causes JSON parsing to fail with "Unexpected end of JSON input"
+            if (error?.message?.includes('Unexpected end of JSON input') ||
+                error?.message?.includes('invalid json response body')) {
+                return { data: [], info: undefined };
+            }
             throw error;
         }
     }
@@ -232,6 +255,11 @@ class Api extends core_1.OAuth2Requester {
             });
         }
         catch (error) {
+            // Zoho returns 204 No Content with empty body when no results found
+            if (error?.message?.includes('Unexpected end of JSON input') ||
+                error?.message?.includes('invalid json response body')) {
+                return { data: [], info: undefined };
+            }
             throw error;
         }
     }
@@ -277,6 +305,295 @@ class Api extends core_1.OAuth2Requester {
                 query: params,
             });
         }
+        catch (error) {
+            // Zoho returns 204 No Content with empty body when no results found
+            if (error?.message?.includes('Unexpected end of JSON input') ||
+                error?.message?.includes('invalid json response body')) {
+                return { data: [], info: undefined };
+            }
+            throw error;
+        }
+    }
+    /**
+     * 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
+     */
+    async listNotes(module, recordId, queryParams = {}) {
+        if (!module) {
+            throw new Error('module is required');
+        }
+        if (!recordId) {
+            throw new Error('recordId is required');
+        }
+        try {
+            return await this._get({
+                url: this.buildNotesUrl(module, recordId),
+                query: queryParams,
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * 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
+     */
+    async getNote(module, recordId, noteId) {
+        if (!module) {
+            throw new Error('module is required');
+        }
+        if (!recordId) {
+            throw new Error('recordId is required');
+        }
+        if (!noteId) {
+            throw new Error('noteId is required');
+        }
+        try {
+            return await this._get({
+                url: this.buildNotesUrl(module, recordId, noteId),
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * 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
+     */
+    async createNote(module, recordId, noteData) {
+        if (!module) {
+            throw new Error('module is required');
+        }
+        if (!recordId) {
+            throw new Error('recordId is required');
+        }
+        if (!noteData || !noteData.Note_Content) {
+            throw new Error('noteData.Note_Content is required');
+        }
+        const body = {
+            data: [{
+                    Note_Content: noteData.Note_Content,
+                    ...(noteData.Note_Title && { Note_Title: noteData.Note_Title }),
+                }]
+        };
+        try {
+            return await this._post({
+                url: this.buildNotesUrl(module, recordId),
+                body: body,
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * 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
+     */
+    async updateNote(module, recordId, noteId, noteData) {
+        if (!module) {
+            throw new Error('module is required');
+        }
+        if (!recordId) {
+            throw new Error('recordId is required');
+        }
+        if (!noteId) {
+            throw new Error('noteId is required');
+        }
+        if (!noteData || (!noteData.Note_Content && !noteData.Note_Title)) {
+            throw new Error('noteData must contain Note_Content or Note_Title');
+        }
+        const body = {
+            data: [{
+                    ...(noteData.Note_Content && { Note_Content: noteData.Note_Content }),
+                    ...(noteData.Note_Title && { Note_Title: noteData.Note_Title }),
+                }]
+        };
+        try {
+            return await this._put({
+                url: this.buildNotesUrl(module, recordId, noteId),
+                body: body,
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * 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
+     */
+    async deleteNote(module, recordId, noteId) {
+        if (!module) {
+            throw new Error('module is required');
+        }
+        if (!recordId) {
+            throw new Error('recordId is required');
+        }
+        if (!noteId) {
+            throw new Error('noteId is required');
+        }
+        try {
+            return await this._delete({
+                url: this.buildNotesUrl(module, recordId, noteId),
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * 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
+     */
+    async enableNotification(body) {
+        if (!body || !body.watch || !Array.isArray(body.watch)) {
+            throw new Error('Body must contain watch array');
+        }
+        // Validate each watch item
+        body.watch.forEach((item, index) => {
+            if (!item.channel_id) {
+                throw new Error(`watch[${index}].channel_id is required`);
+            }
+            if (!item.events || !Array.isArray(item.events) || item.events.length === 0) {
+                throw new Error(`watch[${index}].events must be a non-empty array`);
+            }
+            if (!item.notify_url) {
+                throw new Error(`watch[${index}].notify_url is required`);
+            }
+            if (item.token && item.token.length > 50) {
+                throw new Error(`watch[${index}].token must be 50 characters or less`);
+            }
+        });
+        try {
+            return await this._post({
+                url: this.baseUrl + this.URLs.notificationsWatch,
+                body: body,
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * 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
+     */
+    async disableNotification(channelIds) {
+        if (!channelIds || !Array.isArray(channelIds) || channelIds.length === 0) {
+            throw new Error('channelIds must be a non-empty array');
+        }
+        try {
+            return await this._delete({
+                url: this.baseUrl + this.URLs.notificationsWatch,
+                query: {
+                    channel_ids: channelIds.join(',')
+                },
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * 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
+     */
+    async getNotificationDetails() {
+        try {
+            return await this._get({
+                url: this.baseUrl + this.URLs.notificationsWatch,
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Log a call in Zoho CRM Calls module
+     * @param callData - Call record data with Subject, Call_Type, Call_Start_Time, Call_Duration
+     * @returns Promise<CallsResponse> Created call response
+     * @see https://www.zoho.com/crm/developer/docs/api/v8/insert-records.html
+     */
+    async logCall(callData) {
+        if (!callData.Subject) {
+            throw new Error('callData.Subject is required');
+        }
+        if (!callData.Call_Type) {
+            throw new Error('callData.Call_Type is required');
+        }
+        if (!callData.Call_Start_Time) {
+            throw new Error('callData.Call_Start_Time is required');
+        }
+        // Duration is mandatory for Inbound/Outbound calls and cannot be zero
+        if ((callData.Call_Type === 'Inbound' || callData.Call_Type === 'Outbound') && !callData.Call_Duration) {
+            throw new Error('callData.Call_Duration is required for Inbound/Outbound calls');
+        }
+        const body = {
+            data: [callData]
+        };
+        try {
+            return await this._post({
+                url: this.baseUrl + this.URLs.calls,
+                body: body,
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Update an existing call record in Zoho CRM Calls module
+     * @param callId - Zoho Call ID to update
+     * @param callData - Partial call data to update (e.g., Description, Subject)
+     * @returns Promise<CallsResponse> Updated call response
+     * @see https://www.zoho.com/crm/developer/docs/api/v8/update-records.html
+     */
+    async updateCall(callId, callData) {
+        if (!callId) {
+            throw new Error('callId is required');
+        }
+        if (!callData || Object.keys(callData).length === 0) {
+            throw new Error('callData must contain at least one field to update');
+        }
+        const body = {
+            data: [callData]
+        };
+        try {
+            return await this._put({
+                url: this.baseUrl + this.URLs.call(callId),
+                body: body,
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+            });
+        }
         catch (error) {
             throw error;
         }

package/dist/types.d.ts

@@ -195,6 +195,61 @@ export interface DeleteResponse {
     message: string;
     status: string;
 }
+export interface ZohoNote {
+    id: string;
+    Note_Title?: string;
+    Note_Content: string;
+    Parent_Id?: {
+        module: {
+            api_name: string;
+            id: string;
+        };
+        id: string;
+    };
+    Owner?: {
+        name: string;
+        id: string;
+    };
+    Created_Time?: string;
+    Modified_Time?: string;
+    Created_By?: {
+        name: string;
+        id: string;
+    };
+    Modified_By?: {
+        name: string;
+        id: string;
+    };
+    [key: string]: any;
+}
+export interface CreateNoteData {
+    Note_Content: string;
+    Note_Title?: string;
+}
+export interface NotesResponse {
+    data: Array<{
+        code: string;
+        details: {
+            id: string;
+            Created_Time: string;
+            Modified_Time: string;
+            Created_By?: {
+                name: string;
+                id: string;
+            };
+            Modified_By?: {
+                name: string;
+                id: string;
+            };
+        };
+        message: string;
+        status: string;
+    }>;
+}
+export interface NoteListResponse {
+    data: ZohoNote[];
+    info?: PaginationInfo;
+}
 export interface QueryParams {
     fields?: string;
     per_page?: number;
@@ -220,3 +275,126 @@ export interface TokenResponse {
     token_type: string;
     expires_in: number;
 }
+/**
+ * Configuration for a single notification watch item
+ */
+export interface NotificationWatchItem {
+    /** Unique channel ID (use timestamp or UUID) */
+    channel_id: number | string;
+    /** Events to watch in format: "Module.operation" (e.g., "Contacts.all", "Contacts.create", "Accounts.edit") */
+    events: string[];
+    /** Callback URL to receive notifications */
+    notify_url: string;
+    /** Optional verification token (max 50 characters) */
+    token?: string;
+    /** Channel expiry time (ISO 8601 format, max 1 week from now) */
+    channel_expiry?: string;
+    /** Include field changes in callback payload */
+    return_affected_field_values?: boolean;
+    /** Trigger notifications on related record actions */
+    notify_on_related_action?: boolean;
+}
+/**
+ * Request body for enabling notifications
+ */
+export interface NotificationWatchConfig {
+    watch: NotificationWatchItem[];
+}
+/**
+ * Response from notification API operations
+ */
+export interface NotificationResponse {
+    watch: Array<{
+        code: string;
+        details: {
+            channel_id: number | string;
+            events: string[];
+            channel_expiry: string;
+            resource_uri: string;
+            resource_id: string;
+            resource_name: string;
+        };
+        message: string;
+        status: string;
+    }>;
+}
+/**
+ * Response from getting notification details
+ */
+export interface NotificationDetailsResponse {
+    watch: Array<{
+        channel_id: number | string;
+        events: string[];
+        channel_expiry: string;
+        notify_url: string;
+        resource_uri: string;
+        resource_id: string;
+        resource_name: string;
+        token?: string;
+    }>;
+}
+/**
+ * Payload received in notification callback
+ */
+export interface NotificationCallbackPayload {
+    /** Server timestamp */
+    server_time: number;
+    /** Module name (e.g., "Contacts", "Accounts") */
+    module: string;
+    /** Resource URI */
+    resource_uri: string;
+    /** Array of affected record IDs */
+    ids: string[];
+    /** Fields that were affected (if return_affected_field_values enabled) */
+    affected_fields?: string[];
+    /** Operation type: "insert", "update", or "delete" */
+    operation: 'insert' | 'update' | 'delete';
+    /** Channel ID that triggered this notification */
+    channel_id: number | string;
+    /** Verification token (if provided during setup) */
+    token?: string;
+}
+/**
+ * Data for creating/updating a call record in Zoho CRM Calls module
+ */
+export interface ZohoCallData {
+    /** Call subject/title (required) */
+    Subject: string;
+    /** Call type: Inbound, Outbound, or Missed (required) */
+    Call_Type: 'Inbound' | 'Outbound' | 'Missed';
+    /** Call start time in ISO 8601 format (required) */
+    Call_Start_Time: string;
+    /** Call duration in "HH:mm" or "mm:ss" format (required for Inbound/Outbound, cannot be zero) */
+    Call_Duration: string;
+    /** Call notes/description */
+    Description?: string;
+    /** Contact or Lead ID to associate the call with */
+    Who_Id?: string;
+    /** Module name for the Who_Id association: "Contacts" or "Leads" */
+    $se_module?: string;
+    /** Additional custom fields */
+    [key: string]: any;
+}
+/**
+ * Response from Calls module operations
+ */
+export interface CallsResponse {
+    data: Array<{
+        code: string;
+        details: {
+            id: string;
+            Created_Time: string;
+            Modified_Time: string;
+            Created_By?: {
+                name: string;
+                id: string;
+            };
+            Modified_By?: {
+                name: string;
+                id: string;
+            };
+        };
+        message: string;
+        status: string;
+    }>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@friggframework/api-module-zoho-crm",
-  "version": "2.0.0-next.1",
+  "version": "2.0.0-next.3",
   "prettier": "@friggframework/prettier-config",
   "description": "Zoho CRM API module that lets the Frigg Framework interact with Zoho CRM",
   "main": "dist/index.js",
@@ -36,5 +36,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "5b22500d5eb6b9032389753acad2279ddd70a8dd"
+  "gitHead": "fd8e7d7ad197886b7bd94a68fd26c179358f4b67"
 }