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

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,12 +1,24 @@
 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';
+import { ZohoConfig, ZohoLocation, 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)>;
+    location: ZohoLocation;
+    accountsServer: string | null;
     private static readonly CONTACTS_DEFAULT_FIELDS;
     private static readonly LEADS_DEFAULT_FIELDS;
     private static readonly ACCOUNTS_DEFAULT_FIELDS;
     constructor(params: ZohoConfig);
     getAuthUri(): string;
+    /**
+     * Sets the datacenter location and updates URLs accordingly.
+     * Note: tokenUri is only updated if accountsServer is not set.
+     */
+    setLocation(location: ZohoLocation): void;
+    /**
+     * Sets the accounts server URL for token operations.
+     * Call this when accounts-server is provided in OAuth callback.
+     */
+    setAccountsServer(accountsServer: string): void;
     getTokenFromCode(code: string): Promise<TokenResponse>;
     _delete(options: any): Promise<any>;
     /**
@@ -98,4 +110,19 @@ export declare class Api extends OAuth2Requester {
      * @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

@@ -3,12 +3,35 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Api = void 0;
 const FormData = require("form-data");
 const core_1 = require("@friggframework/core");
+/**
+ * Zoho datacenter URL configuration
+ * @see https://www.zoho.com/crm/developer/docs/api/v8/multi-dc.html
+ */
+const LOCATION_CONFIG = {
+    us: { accounts: 'https://accounts.zoho.com', api: 'https://www.zohoapis.com' },
+    eu: { accounts: 'https://accounts.zoho.eu', api: 'https://www.zohoapis.eu' },
+    in: { accounts: 'https://accounts.zoho.in', api: 'https://www.zohoapis.in' },
+    au: { accounts: 'https://accounts.zoho.com.au', api: 'https://www.zohoapis.com.au' },
+    cn: { accounts: 'https://accounts.zoho.com.cn', api: 'https://www.zohoapis.com.cn' },
+    ca: { accounts: 'https://accounts.zoho.ca', api: 'https://www.zohoapis.ca' },
+    jp: { accounts: 'https://accounts.zoho.jp', api: 'https://www.zohoapis.jp' },
+    sa: { accounts: 'https://accounts.zoho.sa', api: 'https://www.zohoapis.sa' },
+};
+const DEFAULT_LOCATION = 'us';
 class Api extends core_1.OAuth2Requester {
     constructor(params) {
         super(params);
-        this.baseUrl = 'https://www.zohoapis.com/crm/v8';
-        this.authorizationUri = encodeURI(`https://accounts.zoho.com/oauth/v2/auth?scope=${this.scope}&client_id=${this.client_id}&redirect_uri=${this.redirect_uri}&response_type=code&access_type=offline`);
-        this.tokenUri = 'https://accounts.zoho.com/oauth/v2/token';
+        this.accountsServer = (0, core_1.get)(params, 'accountsServer', null);
+        this.location = (0, core_1.get)(params, 'location', DEFAULT_LOCATION);
+        if (!LOCATION_CONFIG[this.location]) {
+            this.location = DEFAULT_LOCATION;
+        }
+        const locationConfig = LOCATION_CONFIG[this.location];
+        this.baseUrl = `${locationConfig.api}/crm/v8`;
+        this.tokenUri = this.accountsServer
+            ? `${this.accountsServer}/oauth/v2/token`
+            : `${locationConfig.accounts}/oauth/v2/token`;
+        this.authorizationUri = encodeURI(`${locationConfig.accounts}/oauth/v2/auth?scope=${this.scope}&client_id=${this.client_id}&redirect_uri=${this.redirect_uri}&response_type=code&access_type=offline`);
         this.access_token = (0, core_1.get)(params, 'access_token', null);
         this.refresh_token = (0, core_1.get)(params, 'refresh_token', null);
         this.URLs = {
@@ -26,12 +49,38 @@ 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() {
         return this.authorizationUri;
     }
+    /**
+     * Sets the datacenter location and updates URLs accordingly.
+     * Note: tokenUri is only updated if accountsServer is not set.
+     */
+    setLocation(location) {
+        if (!LOCATION_CONFIG[location]) {
+            throw new Error(`Invalid Zoho location: ${location}. Must be one of: ${Object.keys(LOCATION_CONFIG).join(', ')}`);
+        }
+        this.location = location;
+        const locationConfig = LOCATION_CONFIG[location];
+        this.baseUrl = `${locationConfig.api}/crm/v8`;
+        if (!this.accountsServer) {
+            this.tokenUri = `${locationConfig.accounts}/oauth/v2/token`;
+        }
+        this.authorizationUri = encodeURI(`${locationConfig.accounts}/oauth/v2/auth?scope=${this.scope}&client_id=${this.client_id}&redirect_uri=${this.redirect_uri}&response_type=code&access_type=offline`);
+    }
+    /**
+     * Sets the accounts server URL for token operations.
+     * Call this when accounts-server is provided in OAuth callback.
+     */
+    setAccountsServer(accountsServer) {
+        this.accountsServer = accountsServer;
+        this.tokenUri = `${accountsServer}/oauth/v2/token`;
+    }
     async getTokenFromCode(code) {
         const formData = new FormData();
         formData.append('grant_type', 'authorization_code');
@@ -201,6 +250,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;
         }
     }
@@ -247,6 +302,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;
         }
     }
@@ -293,6 +353,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;
         }
     }
@@ -514,6 +579,72 @@ class Api extends core_1.OAuth2Requester {
             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;
+        }
+    }
 }
 exports.Api = Api;
 Api.CONTACTS_DEFAULT_FIELDS = 'id,First_Name,Last_Name,Email,Phone,Mobile,Account_Name,Company,Owner,Lead_Source,Created_Time,Modified_Time';

package/dist/definition.d.ts

@@ -7,7 +7,7 @@ export declare const Definition: {
         getToken: (api: Api, params: any) => Promise<void>;
         apiPropertiesToPersist: {
             credential: string[];
-            entity: never[];
+            entity: string[];
         };
         getCredentialDetails: (api: Api, userId: string) => Promise<any>;
         getEntityDetails: (api: Api, callbackParams: any, tokenResponse: any, userId: string) => Promise<any>;

package/dist/definition.js

@@ -38,11 +38,19 @@ exports.Definition = {
     requiredAuthMethods: {
         getToken: async function (api, params) {
             const code = (0, core_1.get)(params, 'code');
+            const location = (0, core_1.get)(params, 'location', null);
+            const accountsServer = (0, core_1.get)(params, 'accounts-server', null);
+            if (location) {
+                api.setLocation(location);
+            }
+            if (accountsServer) {
+                api.setAccountsServer(accountsServer);
+            }
             await api.getTokenFromCode(code);
         },
         apiPropertiesToPersist: {
             credential: ['access_token', 'refresh_token'],
-            entity: [],
+            entity: ['location', 'accountsServer'],
         },
         getCredentialDetails: async function (api, userId) {
             const response = await api.listUsers({ type: 'CurrentUser' });
@@ -58,7 +66,9 @@ exports.Definition = {
             return {
                 identifiers: { externalId: currentUser.id, user: userId },
                 details: {
-                    name: currentUser.email
+                    name: currentUser.email,
+                    location: api.location,
+                    accountsServer: api.accountsServer,
                 },
             };
         },

package/dist/types.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Zoho datacenter locations
+ * @see https://www.zoho.com/crm/developer/docs/api/v8/multi-dc.html
+ */
+export type ZohoLocation = 'us' | 'eu' | 'in' | 'au' | 'cn' | 'ca' | 'jp' | 'sa';
 export interface ZohoConfig {
     client_id: string;
     client_secret: string;
@@ -5,6 +10,8 @@ export interface ZohoConfig {
     redirect_uri: string;
     access_token?: string | null;
     refresh_token?: string | null;
+    location?: ZohoLocation;
+    accountsServer?: string | null;
 }
 export interface PaginationInfo {
     per_page: number;
@@ -354,3 +361,47 @@ export interface NotificationCallbackPayload {
     /** 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.2",
+  "version": "2.0.0-next.4",
   "prettier": "@friggframework/prettier-config",
   "description": "Zoho CRM API module that lets the Frigg Framework interact with Zoho CRM",
   "main": "dist/index.js",
@@ -21,8 +21,8 @@
   "author": "",
   "license": "MIT",
   "devDependencies": {
-    "@friggframework/devtools": "^2.0.0-next.16",
-    "@friggframework/test": "^2.0.0-next.16",
+    "@friggframework/devtools": "^2.0.0-next.68",
+    "@friggframework/test": "^2.0.0-next.68",
     "@types/node": "^20.8.0",
     "dotenv": "^16.0.3",
     "eslint": "^8.22.0",
@@ -31,10 +31,10 @@
     "vitest": "^1.0.0"
   },
   "dependencies": {
-    "@friggframework/core": "^2.0.0-next.16"
+    "@friggframework/core": "^2.0.0-next.68"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "fa3f5ec40cbb9300511849233bddb0c463bfab2a"
+  "gitHead": "e067a887c7a7674018dc7e47bcf02a684400de70"
 }