@dereekb/zoho 13.0.6 → 13.0.7

package/nestjs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hapier Creative LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/nestjs/README.md

@@ -0,0 +1,11 @@
+# zoho-nestjs
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build zoho-nestjs` to build the library.
+
+## Running unit tests
+
+Run `nx test zoho-nestjs` to execute the unit tests via [Jest](https://jestjs.io).

package/nestjs/docs/configuration.md

@@ -0,0 +1,165 @@
+# Zoho NestJS Configuration
+
+This document describes the environment variables used by `@dereekb/zoho/nestjs` and shows how to wire up the Zoho CRM and Zoho Recruit modules in a NestJS application.
+
+---
+
+## Environment Variables
+
+Configuration is read from a NestJS `ConfigService` (typically backed by process environment variables). Two naming conventions are supported for every credential: a **shared** variable that applies to all services, and a **service-specific** variable that takes precedence when present.
+
+### Variable Naming Convention
+
+The service-specific prefix is `ZOHO_<SERVICE>_`, where `<SERVICE>` is the uppercase `serviceAccessTokenKey` (e.g. `CRM` or `RECRUIT`). For each credential the lookup order is:
+
+1. `ZOHO_<SERVICE>_<KEY>` – service-specific (highest priority)
+2. `ZOHO_<KEY>` – shared fallback
+
+### Zoho Accounts (OAuth) Variables
+
+These credentials are shared across all Zoho services and are used to obtain access tokens via the Zoho Accounts API.
+
+| Variable | Service-specific (CRM) | Service-specific (Recruit) | Description |
+|---|---|---|---|
+| `ZOHO_ACCOUNTS_URL` | `ZOHO_CRM_ACCOUNTS_URL` | `ZOHO_RECRUIT_ACCOUNTS_URL` | Base URL of the Zoho Accounts API (e.g. `https://accounts.zoho.com`) |
+| `ZOHO_ACCOUNTS_REFRESH_TOKEN` | `ZOHO_CRM_ACCOUNTS_REFRESH_TOKEN` | `ZOHO_RECRUIT_ACCOUNTS_REFRESH_TOKEN` | OAuth refresh token for the service client |
+| `ZOHO_ACCOUNTS_CLIENT_ID` | `ZOHO_CRM_ACCOUNTS_CLIENT_ID` | `ZOHO_RECRUIT_ACCOUNTS_CLIENT_ID` | OAuth client ID for the service client |
+| `ZOHO_ACCOUNTS_CLIENT_SECRET` | `ZOHO_CRM_ACCOUNTS_CLIENT_SECRET` | `ZOHO_RECRUIT_ACCOUNTS_CLIENT_SECRET` | OAuth client secret for the service client |
+
+### Zoho API URL Variables
+
+Each service also needs to know the base URL of its own REST API.
+
+| Variable | Description |
+|---|---|
+| `ZOHO_CRM_API_URL` | Base URL of the Zoho CRM API (e.g. `https://www.zohoapis.com/crm/v2`) |
+| `ZOHO_RECRUIT_API_URL` | Base URL of the Zoho Recruit API (e.g. `https://recruit.zoho.com/recruit/v2`) |
+
+> **Note:** The shared fallback `ZOHO_API_URL` can also be used if both services share the same base URL.
+
+---
+
+## Setting Up Zoho CRM
+
+`appZohoCrmModuleMetadata()` generates the NestJS `ModuleMetadata` needed to bootstrap the Zoho CRM integration. It registers `ZohoCrmApi` and `ZohoAccountsApi` as providers and reads credentials from the environment automatically.
+
+### Required environment variables
+
+```
+ZOHO_ACCOUNTS_URL=https://accounts.zoho.com
+ZOHO_ACCOUNTS_REFRESH_TOKEN=<your-refresh-token>
+ZOHO_ACCOUNTS_CLIENT_ID=<your-client-id>
+ZOHO_ACCOUNTS_CLIENT_SECRET=<your-client-secret>
+ZOHO_CRM_API_URL=https://www.zohoapis.com/crm/v2
+```
+
+### Example
+
+```typescript
+import {
+  ZohoAccountsAccessTokenCacheService,
+  appZohoCrmModuleMetadata
+} from '@dereekb/zoho/nestjs';
+import { Module } from '@nestjs/common';
+
+// 1. Create a dependency module that provides ZohoAccountsAccessTokenCacheService.
+//    Here we use a simple in-memory cache. For production, consider also layering
+//    in a file-based or Redis-backed cache.
+@Module({
+  providers: [
+    {
+      provide: ZohoAccountsAccessTokenCacheService,
+      useFactory: () => memoryZohoAccountsAccessTokenCacheService()
+    }
+  ],
+  exports: [ZohoAccountsAccessTokenCacheService]
+})
+export class AppZohoCrmDependencyModule {}
+
+// 2. Declare the CRM module using the helper. Pass the dependency module so that
+//    ZohoAccountsAccessTokenCacheService is available to the internal providers.
+@Module(appZohoCrmModuleMetadata({ dependencyModule: AppZohoCrmDependencyModule }))
+export class AppZohoCrmModule {}
+```
+
+`ZohoCrmApi` is exported by `AppZohoCrmModule` and can be injected into any service that imports it.
+
+---
+
+## Setting Up Zoho Recruit
+
+`appZohoRecruitModuleMetadata()` mirrors the CRM helper for the Zoho Recruit API.
+
+### Required environment variables
+
+```
+ZOHO_ACCOUNTS_URL=https://accounts.zoho.com
+ZOHO_ACCOUNTS_REFRESH_TOKEN=<your-refresh-token>
+ZOHO_ACCOUNTS_CLIENT_ID=<your-client-id>
+ZOHO_ACCOUNTS_CLIENT_SECRET=<your-client-secret>
+ZOHO_RECRUIT_API_URL=https://recruit.zoho.com/recruit/v2
+```
+
+Or, if Recruit uses its own dedicated OAuth client, use the service-specific variables:
+
+```
+ZOHO_RECRUIT_ACCOUNTS_URL=https://accounts.zoho.com
+ZOHO_RECRUIT_ACCOUNTS_REFRESH_TOKEN=<recruit-refresh-token>
+ZOHO_RECRUIT_ACCOUNTS_CLIENT_ID=<recruit-client-id>
+ZOHO_RECRUIT_ACCOUNTS_CLIENT_SECRET=<recruit-client-secret>
+ZOHO_RECRUIT_API_URL=https://recruit.zoho.com/recruit/v2
+```
+
+### Example
+
+```typescript
+import {
+  ZohoAccountsAccessTokenCacheService,
+  appZohoRecruitModuleMetadata
+} from '@dereekb/zoho/nestjs';
+import { Module } from '@nestjs/common';
+
+@Module({
+  providers: [
+    {
+      provide: ZohoAccountsAccessTokenCacheService,
+      useFactory: () => memoryZohoAccountsAccessTokenCacheService()
+    }
+  ],
+  exports: [ZohoAccountsAccessTokenCacheService]
+})
+export class AppZohoRecruitDependencyModule {}
+
+@Module(appZohoRecruitModuleMetadata({ dependencyModule: AppZohoRecruitDependencyModule }))
+export class AppZohoRecruitModule {}
+```
+
+`ZohoRecruitApi` is exported by `AppZohoRecruitModule` and can be injected into any service that imports it.
+
+---
+
+## Using Both CRM and Recruit Together
+
+If your application uses both APIs, you can share or separate the token cache depending on whether the same OAuth client is used:
+
+```typescript
+// Shared dependency module (single OAuth client for both services)
+@Module({
+  providers: [
+    {
+      provide: ZohoAccountsAccessTokenCacheService,
+      useFactory: () => memoryZohoAccountsAccessTokenCacheService()
+    }
+  ],
+  exports: [ZohoAccountsAccessTokenCacheService]
+})
+export class AppZohoDependencyModule {}
+
+@Module(appZohoCrmModuleMetadata({ dependencyModule: AppZohoDependencyModule }))
+export class AppZohoCrmModule {}
+
+@Module(appZohoRecruitModuleMetadata({ dependencyModule: AppZohoDependencyModule }))
+export class AppZohoRecruitModule {}
+```
+
+When different OAuth clients are used for CRM and Recruit, set the service-specific environment variables (e.g. `ZOHO_CRM_ACCOUNTS_CLIENT_ID` vs `ZOHO_RECRUIT_ACCOUNTS_CLIENT_ID`) and use separate dependency modules with their own cache instances.

package/nestjs/docs/crm-getting-started.md

@@ -0,0 +1,296 @@
+# Zoho CRM - Getting Started with NestJS
+
+This guide walks through setting up Zoho CRM in a new NestJS project using `@dereekb/zoho` and `@dereekb/zoho-nestjs`.
+
+## 1. Install Dependencies
+
+```bash
+npm install @dereekb/zoho @dereekb/zoho-nestjs
+```
+
+## 2. Module & Authentication Setup
+
+The NestJS integration wires up OAuth authentication, token caching, rate limiting, and the CRM client in a single module declaration. All you need to provide is:
+
+- Environment variables for OAuth credentials and API URLs
+- A `ZohoAccountsAccessTokenCacheService` implementation for token persistence
+
+### Environment Variables
+
+```env
+# OAuth credentials (shared across all Zoho services)
+ZOHO_ACCOUNTS_URL=https://accounts.zoho.com
+ZOHO_ACCOUNTS_REFRESH_TOKEN=<your-refresh-token>
+ZOHO_ACCOUNTS_CLIENT_ID=<your-client-id>
+ZOHO_ACCOUNTS_CLIENT_SECRET=<your-client-secret>
+
+# CRM API endpoint
+ZOHO_API_URL=https://www.zohoapis.com
+```
+
+> You can also use CRM-specific env vars (e.g. `ZOHO_CRM_ACCOUNTS_REFRESH_TOKEN`) to override the shared values. This is useful when your app integrates multiple Zoho services (CRM, Recruit, Sign) with different credentials.
+
+### Token Cache
+
+You must provide a `ZohoAccountsAccessTokenCacheService` that persists OAuth access tokens. The library includes three built-in implementations:
+
+```typescript
+import {
+  memoryZohoAccountsAccessTokenCacheService,
+  fileZohoAccountsAccessTokenCacheService,
+  mergeZohoAccountsAccessTokenCacheServices
+} from '@dereekb/zoho-nestjs';
+
+// In-memory only (good for testing)
+const cacheService = memoryZohoAccountsAccessTokenCacheService();
+
+// File-based (good for local development, persists across restarts)
+const cacheService = fileZohoAccountsAccessTokenCacheService('.tmp/zoho-tokens.json');
+
+// Merged (fault-tolerant, tries multiple sources in sequence)
+const cacheService = mergeZohoAccountsAccessTokenCacheServices([cacheA, cacheB]);
+```
+
+### Module Declaration
+
+Create a dependency module that provides the token cache, then use `appZohoCrmModuleMetadata()` to wire everything together:
+
+```typescript
+import { Module } from '@nestjs/common';
+import {
+  ZohoAccountsAccessTokenCacheService,
+  ZohoCrmApi,
+  appZohoCrmModuleMetadata,
+  fileZohoAccountsAccessTokenCacheService
+} from '@dereekb/zoho-nestjs';
+
+@Module({
+  providers: [
+    {
+      provide: ZohoAccountsAccessTokenCacheService,
+      useValue: fileZohoAccountsAccessTokenCacheService()
+    }
+  ],
+  exports: [ZohoAccountsAccessTokenCacheService]
+})
+export class ZohoCrmDependencyModule {}
+
+@Module(appZohoCrmModuleMetadata({ dependencyModule: ZohoCrmDependencyModule }))
+export class AppZohoCrmModule {}
+```
+
+`appZohoCrmModuleMetadata()` automatically registers:
+- `ZohoAccountsServiceConfig` (reads OAuth env vars via `ConfigService`)
+- `ZohoAccountsApi` (manages token refresh and caching)
+- `ZohoCrmServiceConfig` (reads CRM API URL from env vars)
+- `ZohoCrmApi` (the injectable service you'll use everywhere)
+
+Import `AppZohoCrmModule` in your app module and inject `ZohoCrmApi` wherever needed.
+
+### Non-NestJS Setup
+
+If you're not using NestJS, create the accounts context and CRM client manually:
+
+```typescript
+import { zohoAccountsFactory, zohoCrmFactory } from '@dereekb/zoho';
+
+const accounts = zohoAccountsFactory({})({
+  apiUrl: 'us',
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+  refreshToken: 'your-refresh-token',
+  accessTokenCache: myOptionalCache
+});
+
+const crm = zohoCrmFactory({
+  accountsContext: accounts.accountsContext
+})({
+  apiUrl: 'production' // or 'sandbox'
+});
+
+const { crmContext } = crm;
+// Pass crmContext to all zohoCrmXxx() functions
+```
+
+## 3. CRUD Operations
+
+`ZohoCrmApi` exposes all CRM operations as getter properties. Each returns a pre-bound async function.
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { ZohoCrmApi } from '@dereekb/zoho-nestjs';
+
+@Injectable()
+export class ContactsService {
+  constructor(private readonly zohoCrmApi: ZohoCrmApi) {}
+
+  async createContact() {
+    return this.zohoCrmApi.insertRecord({
+      module: 'Contacts',
+      data: { First_Name: 'Jane', Last_Name: 'Doe', Email: 'jane@example.com' }
+    });
+  }
+
+  async getContact(id: string) {
+    return this.zohoCrmApi.getRecordById({ module: 'Contacts', id });
+  }
+
+  async updateContact(id: string, lastName: string) {
+    return this.zohoCrmApi.updateRecord({
+      module: 'Contacts',
+      data: { id, Last_Name: lastName }
+    });
+  }
+
+  async deleteContact(id: string) {
+    return this.zohoCrmApi.deleteRecord({ module: 'Contacts', ids: id });
+  }
+}
+```
+
+When passing a **single record**, the function returns the result directly or throws on error. When passing an **array** (up to 100 records), it returns `{ successItems, errorItems }`.
+
+## 4. Search with Criteria
+
+```typescript
+// Simple criteria (all AND-joined):
+const results = await this.zohoCrmApi.searchRecords({
+  module: 'Contacts',
+  criteria: [
+    { field: 'Last_Name', filter: 'starts_with', value: 'Sm' },
+    { field: 'Email', filter: 'contains', value: 'example.com' }
+  ]
+});
+
+// OR logic using a criteria tree:
+const results = await this.zohoCrmApi.searchRecords({
+  module: 'Contacts',
+  criteria: {
+    or: [
+      [{ field: 'Status', filter: 'equals', value: 'Active' }],
+      [{ field: 'Status', filter: 'equals', value: 'Pending' }]
+    ]
+  }
+});
+```
+
+Filter operators: `equals`, `starts_with`, `contains`. Maximum 10 criteria entries per search.
+
+## 5. Pagination
+
+All list/search results return `{ data, info: { more_records, page, per_page } }`. Use page factories for automatic chaining:
+
+```typescript
+const fetchPage = this.zohoCrmApi.searchRecordsPageFactory({
+  module: 'Contacts',
+  criteria: [{ field: 'Last_Name', filter: 'starts_with', value: 'A' }]
+});
+
+const page1 = await fetchPage.fetchNext();
+const page2 = await page1.fetchNext(); // auto-follows pagination
+```
+
+## 6. Notes, Tags, and Attachments
+
+### Notes
+
+```typescript
+// Create notes for a record
+await this.zohoCrmApi.createNotesForRecord({
+  module: 'Contacts',
+  id: contactId,
+  notes: [{ Note_Title: 'Call Log', Note_Content: 'Left voicemail' }]
+});
+
+// Get notes (paginated)
+const notes = await this.zohoCrmApi.getNotesForRecord({
+  module: 'Contacts',
+  id: contactId,
+  fields: 'Note_Title,Note_Content'
+});
+
+// Delete notes
+await this.zohoCrmApi.deleteNotes({ ids: [noteId1, noteId2] });
+```
+
+### Tags
+
+```typescript
+// Create tags for a module
+await this.zohoCrmApi.createTagsForModule({
+  module: 'Contacts',
+  tags: [{ name: 'VIP' }, { name: 'Hot Lead', color_code: '#FF0000' }]
+});
+
+// Add/remove tags on records
+await this.zohoCrmApi.addTagsToRecords({
+  module: 'Contacts',
+  ids: [contactId],
+  tag_names: ['VIP']
+});
+
+await this.zohoCrmApi.removeTagsFromRecords({
+  module: 'Contacts',
+  ids: [contactId],
+  tag_names: ['VIP']
+});
+```
+
+### Attachments
+
+```typescript
+// Upload (max 20MB)
+await this.zohoCrmApi.uploadAttachmentForRecord({
+  module: 'Contacts',
+  id: contactId,
+  file: myFile,
+  attachmentCategoryName: 'Resume'
+});
+
+// List attachments
+const attachments = await this.zohoCrmApi.getAttachmentsForRecord({
+  module: 'Contacts',
+  id: contactId
+});
+
+// Download
+const fileResponse = await this.zohoCrmApi.downloadAttachmentForRecord({
+  module: 'Contacts',
+  id: contactId,
+  attachment_id: attachmentId
+});
+
+// Delete
+await this.zohoCrmApi.deleteAttachmentFromRecord({
+  module: 'Contacts',
+  id: contactId,
+  attachment_id: attachmentId
+});
+```
+
+## 7. Serverless Functions
+
+Call Zoho CRM serverless functions via REST API:
+
+```typescript
+// OAuth-authenticated call
+const result = await this.zohoCrmApi.executeRestApiFunction({
+  functionName: 'my_custom_function',
+  params: { contact_id: '123' }
+});
+
+// API key-authenticated call (cross-environment)
+const result = await this.zohoCrmApi.executeRestApiFunction({
+  functionName: 'my_custom_function',
+  apiKey: 'your-zapikey',
+  apiUrl: 'production'
+});
+```
+
+## Key Design Details
+
+- **Rate limiting** is built-in (default 100 req/min), auto-adjusts from `X-RATELIMIT-LIMIT` response headers, and retries on HTTP 429.
+- **Token refresh** is automatic. On `ZohoInvalidTokenError`, the token is cleared and re-fetched transparently.
+- **Error classes** are specific and catchable: `ZohoCrmRecordNoContentError`, `ZohoCrmRecordCrudDuplicateDataError`, `ZohoCrmRecordCrudMandatoryFieldNotFoundError`, etc.
+- **Module constants** are provided for common modules: `ZOHO_CRM_LEADS_MODULE`, `ZOHO_CRM_CONTACTS_MODULE`, `ZOHO_CRM_TASKS_MODULE`, etc.
+- Uses the **Zoho CRM v8 API**.