@dereekb/zoho 13.0.6 → 13.0.7

package/src/lib/crm/crm.api.d.ts

@@ -3,7 +3,7 @@ import { type FetchFileResponse, type FetchJsonBody, type FetchJsonInput, type F
 import { type ZohoCrmConfigApiUrlInput, type ZohoCrmContext } from './crm.config';
 import { type ZohoCrmCommaSeparateFieldNames, type ZohoCrmCustomViewId, type ZohoCrmDraftOrSaveState, type ZohoCrmFieldName, type ZohoCrmModuleNameRef, type ZohoCrmChangeObjectDetails, type ZohoCrmRecord, type ZohoCrmRecordId, type ZohoCrmTerritoryId, type ZohoCrmTrueFalseBoth, type ZohoCrmRestFunctionApiName, type ZohoCrmUserId, type ZohoCrmModuleName, type ZohoCrmRecordEmailMetadata, type ZohoCrmRecordAttachmentMetadata, type ZohoCrmAttachmentRecordId, type ZohoCrmAttachmentCategoryId, type KnownZohoCrmAttachmentCategoryName } from './crm';
 import { type ZohoCrmSearchRecordsCriteriaTreeElement } from './crm.criteria';
-import { type ArrayOrValue, type EmailAddress, type Maybe, type PhoneNumber, type SortingOrder, type UniqueModelWithId, type WebsiteUrlWithPrefix } from '@dereekb/util';
+import { type ArrayOrValue, type EmailAddress, type Maybe, type PhoneNumber, type SortingOrder, type UniqueModelWithId } from '@dereekb/util';
 import { type ZohoServerErrorDataWithDetails, type ZohoServerErrorStatus, type ZohoServerSuccessCode, type ZohoServerSuccessStatus } from '../zoho.error.api';
 import { type ZohoDateTimeString } from '../zoho.type';
 import { BaseError } from 'make-error';
@@ -13,47 +13,140 @@ import { BaseError } from 'make-error';
  * This is a limit enforced by the Zoho Crm API
  */
 export declare const ZOHO_CRM_CRUD_FUNCTION_MAX_RECORDS_LIMIT = 100;
+/**
+ * Paired success/error results from a multi-record update, upsert, or insert operation.
+ */
 export type ZohoCrmUpdateRecordResult<T> = ZohoCrmMultiRecordResult<T, ZohoCrmChangeObjectResponseSuccessEntry, ZohoCrmChangeObjectResponseErrorEntry>;
+/**
+ * Raw API response from a record change operation containing the data array.
+ */
 export type ZohoCrmUpdateRecordResponse = ZohoCrmChangeObjectResponse;
+/**
+ * Record data for creation, excluding the `id` field since it is assigned by Zoho.
+ */
 export type ZohoCrmCreateRecordData<T> = Omit<T, 'id'>;
+/**
+ * Input for creating a single record in a CRM module.
+ */
 export interface ZohoCrmCreateSingleRecordInput<T> extends ZohoCrmModuleNameRef {
     readonly data: ZohoCrmCreateRecordData<T>;
 }
+/**
+ * Input for creating multiple records in a CRM module in a single API call.
+ */
 export interface ZohoCrmCreateMultiRecordInput<T> extends ZohoCrmModuleNameRef {
     readonly data: ZohoCrmCreateRecordData<T>[];
 }
+/**
+ * Overloaded function type that handles both single and multi-record creation.
+ */
 export type ZohoCrmCreateRecordLikeFunction = ZohoCrmCreateMultiRecordFunction & ZohoCrmCreateSingleRecordFunction;
+/**
+ * Creates a single record and resolves with the created record's details.
+ */
 export type ZohoCrmCreateSingleRecordFunction = <T>(input: ZohoCrmCreateSingleRecordInput<T>) => Promise<ZohoCrmChangeObjectDetails>;
+/**
+ * Creates multiple records and resolves with paired success/error results.
+ */
 export type ZohoCrmCreateMultiRecordFunction = <T>(input: ZohoCrmCreateMultiRecordInput<T>) => Promise<ZohoCrmUpdateRecordResult<T>>;
+/**
+ * Discriminated input for updating one or more records.
+ */
 export type ZohoCrmUpdateRecordInput<T> = ZohoCrmUpdateSingleRecordInput<T> | ZohoCrmUpdateMultiRecordInput<T>;
+/**
+ * Partial record data for updates, requiring the `id` to identify the target record.
+ */
 export type ZohoCrmUpdateRecordData<T> = UniqueModelWithId & Partial<T>;
+/**
+ * Input for updating a single record in a CRM module.
+ */
 export interface ZohoCrmUpdateSingleRecordInput<T> extends ZohoCrmModuleNameRef {
     readonly data: ZohoCrmUpdateRecordData<T>;
 }
+/**
+ * Input for updating multiple records in a CRM module in a single API call.
+ */
 export interface ZohoCrmUpdateMultiRecordInput<T> extends ZohoCrmModuleNameRef {
     readonly data: ZohoCrmUpdateRecordData<T>[];
 }
+/**
+ * Overloaded function type that handles both single and multi-record updates.
+ */
 export type ZohoCrmUpdateRecordLikeFunction = ZohoCrmUpdateMultiRecordFunction & ZohoCrmUpdateSingleRecordFunction;
+/**
+ * Updates multiple records and resolves with paired success/error results.
+ */
 export type ZohoCrmUpdateMultiRecordFunction = <T>(input: ZohoCrmUpdateMultiRecordInput<T>) => Promise<ZohoCrmUpdateRecordResult<T>>;
+/**
+ * Updates a single record and resolves with the updated record's details.
+ */
 export type ZohoCrmUpdateSingleRecordFunction = <T>(input: ZohoCrmUpdateSingleRecordInput<T>) => Promise<ZohoCrmChangeObjectDetails>;
+/**
+ * Record data for upsert, accepting either create data (without `id`) or update data (with `id`).
+ */
 export type ZohoCrmUpsertRecordData<T> = ZohoCrmCreateRecordData<T> | ZohoCrmUpdateRecordData<T>;
+/**
+ * Input for upserting a single record in a CRM module.
+ */
 export interface ZohoCrmUpsertSingleRecordInput<T> extends ZohoCrmModuleNameRef {
     readonly data: ZohoCrmUpsertRecordData<T>;
 }
+/**
+ * Input for upserting multiple records in a CRM module in a single API call.
+ */
 export interface ZohoCrmUpsertMultiRecordInput<T> extends ZohoCrmModuleNameRef {
     readonly data: ZohoCrmUpsertRecordData<T>[];
 }
+/**
+ * Overloaded function type that handles both single and multi-record upserts.
+ */
 export type ZohoCrmUpsertRecordLikeFunction = ZohoCrmUpsertMultiRecordFunction & ZohoCrmUpsertSingleRecordFunction;
+/**
+ * Upserts multiple records and resolves with paired success/error results.
+ */
 export type ZohoCrmUpsertMultiRecordFunction = <T>(input: ZohoCrmUpsertMultiRecordInput<T>) => Promise<ZohoCrmUpdateRecordResult<T>>;
+/**
+ * Upserts a single record and resolves with the record's details.
+ */
 export type ZohoCrmUpsertSingleRecordFunction = <T>(input: ZohoCrmUpsertSingleRecordInput<T>) => Promise<ZohoCrmChangeObjectDetails>;
+/**
+ * Alias for the insert record function, supporting both single and multi-record creation.
+ */
 export type ZohoCrmInsertRecordFunction = ZohoCrmCreateRecordLikeFunction;
 /**
- * Inserts one or more records into Crm.
+ * Creates a {@link ZohoCrmInsertRecordFunction} bound to the given context.
+ *
+ * Inserts one or more records into a CRM module. When a single record is
+ * provided, returns the {@link ZohoCrmChangeObjectDetails} directly or
+ * throws on error. When multiple records are provided, returns a
+ * {@link ZohoCrmUpdateRecordResult} with paired success/error arrays.
+ *
+ * Maximum of {@link ZOHO_CRM_CRUD_FUNCTION_MAX_RECORDS_LIMIT} records per call.
+ *
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Function that inserts records into the specified module
+ *
+ * @example
+ * ```typescript
+ * const insertRecord = zohoCrmInsertRecord(context);
+ *
+ * // Single record — returns details directly or throws on error:
+ * const details = await insertRecord({
+ *   module: 'Contacts',
+ *   data: { First_Name: 'Jane', Last_Name: 'Doe', Email: 'jane@example.com' }
+ * });
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/insert-records.html
+ * // Multiple records — returns paired success/error arrays:
+ * const result = await insertRecord({
+ *   module: 'Contacts',
+ *   data: [
+ *     { First_Name: 'Jane', Last_Name: 'Doe', Email: 'jane@example.com' },
+ *     { First_Name: 'John', Last_Name: 'Doe', Email: 'john@example.com' }
+ *   ]
+ * });
+ * ```
  *
- * @param context
- * @returns
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/insert-records.html
  */
 export declare function zohoCrmInsertRecord(context: ZohoCrmContext): ZohoCrmInsertRecordFunction;
 /**
@@ -61,61 +154,181 @@ export declare function zohoCrmInsertRecord(context: ZohoCrmContext): ZohoCrmIns
  */
 export type ZohoCrmUpsertRecordFunction = ZohoCrmUpsertRecordLikeFunction;
 /**
- * Updates or inserts one or more records in Crm.
+ * Creates a {@link ZohoCrmUpsertRecordFunction} bound to the given context.
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/upsert-records.html
+ * Inserts or updates one or more records in a CRM module based on whether
+ * each record includes an `id`. Uses the `/upsert` endpoint. Single-record
+ * calls return details directly or throw; multi-record calls return paired
+ * success/error arrays.
  *
- * @param context
- * @returns
+ * Maximum of {@link ZOHO_CRM_CRUD_FUNCTION_MAX_RECORDS_LIMIT} records per call.
+ *
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Function that upserts records in the specified module
+ *
+ * @example
+ * ```typescript
+ * const upsertRecord = zohoCrmUpsertRecord(context);
+ *
+ * // Create (no id) — returns details directly:
+ * const created = await upsertRecord({
+ *   module: 'Contacts',
+ *   data: { Email: 'new@example.com', Last_Name: 'New' }
+ * });
+ *
+ * // Update (with id) — returns details directly:
+ * const updated = await upsertRecord({
+ *   module: 'Contacts',
+ *   data: { id: existingId, First_Name: 'Updated' }
+ * });
+ *
+ * // Mixed create and update — returns paired arrays:
+ * const result = await upsertRecord({
+ *   module: 'Contacts',
+ *   data: [
+ *     { Email: 'create@example.com', Last_Name: 'Create' },
+ *     { id: existingId, First_Name: 'Update' }
+ *   ]
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/upsert-records.html
  */
 export declare function zohoCrmUpsertRecord(context: ZohoCrmContext): ZohoCrmUpsertRecordFunction;
+/**
+ * Alias for the update record function, supporting both single and multi-record updates.
+ */
 export type ZohoCrmUpdateRecordFunction = ZohoCrmUpdateRecordLikeFunction;
 /**
- * Updates one or more records in Crm.
+ * Creates a {@link ZohoCrmUpdateRecordFunction} bound to the given context.
+ *
+ * Updates one or more existing records in a CRM module. Each record must
+ * include an `id` field. Single-record calls return details directly or throw;
+ * multi-record calls return paired success/error arrays.
+ *
+ * Maximum of {@link ZOHO_CRM_CRUD_FUNCTION_MAX_RECORDS_LIMIT} records per call.
+ *
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Function that updates records in the specified module
+ *
+ * @example
+ * ```typescript
+ * const updateRecord = zohoCrmUpdateRecord(context);
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/update-records.html
+ * // Single record — returns details directly:
+ * const details = await updateRecord({
+ *   module: 'Contacts',
+ *   data: { id: recordId, First_Name: 'Updated Name' }
+ * });
  *
- * @param context
- * @returns
+ * // Multiple records — returns paired arrays:
+ * const result = await updateRecord({
+ *   module: 'Contacts',
+ *   data: [
+ *     { id: recordId1, First_Name: 'Updated 1' },
+ *     { id: recordId2, First_Name: 'Updated 2' }
+ *   ]
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/update-records.html
  */
 export declare function zohoCrmUpdateRecord(context: ZohoCrmContext): ZohoCrmUpdateRecordFunction;
+/**
+ * Function that deletes one or more records from a module.
+ */
 export type ZohoCrmDeleteRecordFunction = (input: ZohoCrmDeleteRecordInput) => Promise<ZohoCrmDeleteRecordResponse>;
+/**
+ * Input for deleting records from a module.
+ */
 export interface ZohoCrmDeleteRecordInput extends ZohoCrmModuleNameRef {
     /**
      * Id or array of ids to delete.
      */
     readonly ids: ArrayOrValue<ZohoCrmRecordId>;
+    /**
+     * Whether to trigger workflow rules on deletion.
+     */
     readonly wf_trigger?: boolean;
 }
+/**
+ * Successful entry in a delete response, containing the deleted record's id.
+ */
 export interface ZohoCrmDeleteRecordResponseSuccessEntry extends ZohoCrmChangeObjectLikeResponseSuccessEntryMeta {
     readonly details: {
         readonly id: ZohoCrmRecordId;
     };
 }
+/**
+ * Response from a delete operation, split into success and error pairs.
+ */
 export type ZohoCrmDeleteRecordResponse = ZohoCrmChangeObjectLikeResponseSuccessAndErrorPairs<ZohoCrmDeleteRecordResponseSuccessEntry>;
+/**
+ * Array of successful delete entries.
+ */
 export type ZohoCrmDeleteRecordResult = ZohoCrmChangeObjectResponseSuccessEntry[];
 /**
- * Deletes one or more records from the given module.
+ * Creates a {@link ZohoCrmDeleteRecordFunction} bound to the given context.
+ *
+ * Deletes one or more records from a CRM module by their IDs. Supports
+ * an optional `wf_trigger` flag to execute workflow rules on deletion. Returns
+ * a response with separated success and error entries.
+ *
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Function that deletes records from the specified module
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/delete-records.html
+ * @example
+ * ```typescript
+ * const deleteRecord = zohoCrmDeleteRecord(context);
  *
- * @param context
- * @returns ZohoCrmDeleteRecordFunction
+ * const result = await deleteRecord({
+ *   module: 'Contacts',
+ *   ids: contactId
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/delete-records.html
  */
 export declare function zohoCrmDeleteRecord(context: ZohoCrmContext): ZohoCrmDeleteRecordFunction;
+/**
+ * Input identifying a specific record by module and id.
+ */
 export interface ZohoCrmGetRecordByIdInput extends ZohoCrmModuleNameRef {
     readonly id: ZohoCrmRecordId;
 }
+/**
+ * Raw API response wrapping the record in a data array.
+ */
 export type ZohoCrmGetRecordByIdResponse<T = ZohoCrmRecord> = ZohoDataArrayResultRef<T>;
+/**
+ * The unwrapped record returned from a get-by-id call.
+ */
 export type ZohoCrmGetRecordByIdResult<T = ZohoCrmRecord> = T;
+/**
+ * Retrieves a single record by id and resolves with the unwrapped record.
+ */
 export type ZohoCrmGetRecordByIdFunction = <T = ZohoCrmRecord>(input: ZohoCrmGetRecordByIdInput) => Promise<ZohoCrmGetRecordByIdResult<T>>;
 /**
- * Retrieves a specific record from the given module.
+ * Creates a {@link ZohoCrmGetRecordByIdFunction} bound to the given context.
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/get-records.html
+ * Retrieves a single record from a CRM module by its ID. The response is
+ * unwrapped from the standard data array, returning the record directly.
+ * Throws if the record is not found.
  *
- * @param context
- * @returns
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Function that retrieves a record by module name and ID
+ *
+ * @example
+ * ```typescript
+ * const getRecordById = zohoCrmGetRecordById(context);
+ *
+ * const record = await getRecordById({
+ *   module: 'Contacts',
+ *   id: contactId
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/get-records.html
  */
 export declare function zohoCrmGetRecordById(context: ZohoCrmContext): ZohoCrmGetRecordByIdFunction;
 export interface ZohoCrmGetRecordsPageFilter extends ZohoPageFilter {
@@ -136,12 +349,27 @@ export interface ZohoCrmGetRecordsInput extends ZohoCrmModuleNameRef, ZohoCrmGet
 export type ZohoCrmGetRecordsResponse<T = ZohoCrmRecord> = ZohoPageResult<T>;
 export type ZohoCrmGetRecordsFunction = <T = ZohoCrmRecord>(input: ZohoCrmGetRecordsInput) => Promise<ZohoCrmGetRecordsResponse<T>>;
 /**
- * Retrieves records from the given module. Used for paginating across all records.
+ * Creates a {@link ZohoCrmGetRecordsFunction} bound to the given context.
+ *
+ * Retrieves a paginated list of records from a CRM module. Supports field
+ * selection, sorting, custom view filtering, territory filtering, and
+ * conversion/approval status filters via {@link ZohoCrmGetRecordsInput}.
+ *
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Function that retrieves paginated records from a module
+ *
+ * @example
+ * ```typescript
+ * const getRecords = zohoCrmGetRecords(context);
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/get-records.html
+ * const page = await getRecords({
+ *   module: 'Contacts',
+ *   fields: 'First_Name,Last_Name,Email',
+ *   per_page: 10
+ * });
+ * ```
  *
- * @param context
- * @returns
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/get-records.html
  */
 export declare function zohoCrmGetRecords(context: ZohoCrmContext): ZohoCrmGetRecordsFunction;
 /**
@@ -159,15 +387,65 @@ export interface ZohoCrmSearchRecordsInput<T = ZohoCrmRecord> extends ZohoCrmMod
 export type ZohoCrmSearchRecordsResponse<T = ZohoCrmRecord> = ZohoCrmGetRecordsResponse<T>;
 export type ZohoCrmSearchRecordsFunction = <T = ZohoCrmRecord>(input: ZohoCrmSearchRecordsInput<T>) => Promise<ZohoCrmSearchRecordsResponse<T>>;
 /**
- * Searches records from the given module.
+ * Creates a {@link ZohoCrmSearchRecordsFunction} bound to the given context.
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/search-records.html
+ * Searches records in a CRM module using one of: criteria tree (compiled
+ * via {@link zohoCrmSearchRecordsCriteriaString}), email, phone, cvid, or keyword.
+ * At least one search parameter must be provided. Returns a paginated result,
+ * defaulting to an empty data array when no matches are found.
  *
- * @param context
- * @returns
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Function that searches records in the specified module
+ * @throws {Error} If none of `criteria`, `email`, `phone`, `cvid`, or `word` are provided
+ *
+ * @example
+ * ```typescript
+ * const searchRecords = zohoCrmSearchRecords(context);
+ *
+ * // Search by criteria:
+ * const result = await searchRecords({
+ *   module: 'Contacts',
+ *   criteria: [{ field: 'Last_Name', filter: 'starts_with', value: 'Smith' }],
+ *   per_page: 10
+ * });
+ *
+ * // Search by keyword:
+ * const wordResult = await searchRecords({
+ *   module: 'Contacts',
+ *   word: 'engineer'
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/search-records.html
  */
 export declare function zohoCrmSearchRecords(context: ZohoCrmContext): ZohoCrmSearchRecordsFunction;
+/**
+ * Factory that creates paginated search iterators for search record queries.
+ */
 export type ZohoCrmSearchRecordsPageFactory = <T = ZohoCrmRecord>(input: ZohoCrmSearchRecordsInput<T>, options?: Maybe<FetchPageFactoryOptions<ZohoCrmSearchRecordsInput<T>, ZohoCrmSearchRecordsResponse<T>>>) => FetchPage<ZohoCrmSearchRecordsInput<T>, ZohoCrmSearchRecordsResponse<T>>;
+/**
+ * Creates a {@link ZohoCrmSearchRecordsPageFactory} bound to the given context.
+ *
+ * Returns a page factory that automatically handles Zoho CRM's pagination,
+ * making it easy to iterate through all search results across multiple pages.
+ *
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Page factory for iterating over search results
+ *
+ * @example
+ * ```typescript
+ * const pageFactory = zohoCrmSearchRecordsPageFactory(context);
+ *
+ * const fetchPage = pageFactory({
+ *   module: 'Contacts',
+ *   criteria: [{ field: 'Last_Name', filter: 'starts_with', value: 'Smith' }],
+ *   per_page: 5
+ * });
+ *
+ * const firstPage = await fetchPage.fetchNext();
+ * const secondPage = await firstPage.fetchNext();
+ * ```
+ */
 export declare function zohoCrmSearchRecordsPageFactory(context: ZohoCrmContext): ZohoCrmSearchRecordsPageFactory;
 export interface ZohoCrmGetRelatedRecordsFunctionConfig {
     readonly targetModule: ZohoCrmModuleName;
@@ -200,12 +478,33 @@ export interface ZohoCrmGetRelatedRecordsRequestWithFields extends ZohoCrmGetRel
 export type ZohoCrmGetRelatedRecordsResponse<T = ZohoCrmRecord> = ZohoPageResult<T>;
 export type ZohoCrmGetRelatedRecordsFunction<T = ZohoCrmRecord> = (input: ZohoCrmGetRelatedRecordsRequest) => Promise<ZohoCrmGetRelatedRecordsResponse<T>>;
 /**
- * Creates a ZohoCrmGetRelatedRecordsFunctionFactory, which can be used to create ZohoCrmGetRelatedRecordsFunction<T> that targets retrieving related records of a given type.
+ * Creates a {@link ZohoCrmGetRelatedRecordsFunctionFactory} bound to the given context.
+ *
+ * Returns a factory that produces typed functions for fetching related records
+ * (e.g. Notes, Emails, Attachments) of a specific target module. The factory
+ * accepts a {@link ZohoCrmGetRelatedRecordsFunctionConfig} to specify the
+ * target module and empty-result behavior. By default, returns an empty page
+ * result instead of null when no records are found.
+ *
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Factory that creates typed related-records retrieval functions
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/get-related-records.html
+ * @example
+ * ```typescript
+ * const factory = zohoCrmGetRelatedRecordsFunctionFactory(context);
  *
- * @param context the ZohoCrmContext to use
- * @returns a ZohoCrmGetRelatedRecordsFunctionFactory
+ * // Create a typed function for fetching related Notes:
+ * const getNotesForRecord = factory<ZohoCrmRecordNote>({
+ *   targetModule: ZOHO_CRM_NOTES_MODULE
+ * });
+ *
+ * const notes = await getNotesForRecord({
+ *   module: 'Contacts',
+ *   id: contactId
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/get-related-records.html
  */
 export declare function zohoCrmGetRelatedRecordsFunctionFactory(context: ZohoCrmContext): ZohoCrmGetRelatedRecordsFunctionFactory;
 /**
@@ -231,14 +530,136 @@ export type ZohoCrmGetEmailsForRecordFunction = (input: ZohoCrmGetEmailsForRecor
 export type ZohoCrmGetEmailsForRecordRawApiResponse = Omit<ZohoCrmGetEmailsForRecordResponse, 'data'> & {
     Emails: ZohoCrmGetEmailsForRecordResponse['data'];
 };
+/**
+ * Creates a {@link ZohoCrmGetEmailsForRecordFunction} bound to the given context.
+ *
+ * Retrieves email metadata related to a specific record by targeting the
+ * Emails module via the related records API. Normalizes the Zoho API response
+ * which returns email data under an `Emails` key instead of the standard `data` key.
+ * Returns a paginated result of {@link ZohoCrmRecordEmailMetadata} entries.
+ *
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Function that retrieves emails for a record
+ *
+ * @example
+ * ```typescript
+ * const getEmailsForRecord = zohoCrmGetEmailsForRecord(context);
+ *
+ * const result = await getEmailsForRecord({
+ *   id: contactId,
+ *   module: 'Contacts'
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer/docs/api/v8/get-email-rel-list.html
+ */
 export declare function zohoCrmGetEmailsForRecord(context: ZohoCrmContext): ZohoCrmGetEmailsForRecordFunction;
+/**
+ * Factory that creates paginated iterators for fetching emails related to a record.
+ */
 export type ZohoCrmGetEmailsForRecordPageFactory = FetchPageFactory<ZohoCrmGetEmailsForRecordRequest, ZohoCrmGetEmailsForRecordResponse>;
+/**
+ * Creates a {@link ZohoCrmGetEmailsForRecordPageFactory} bound to the given context.
+ *
+ * Returns a page factory for iterating over emails related to a record across
+ * multiple pages. Wraps {@link zohoCrmGetEmailsForRecord} with automatic
+ * pagination handling via {@link zohoFetchPageFactory}.
+ *
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Page factory for iterating over record emails
+ *
+ * @example
+ * ```typescript
+ * const pageFactory = zohoCrmGetEmailsForRecordPageFactory(context);
+ *
+ * const fetchPage = pageFactory({
+ *   id: contactId,
+ *   module: 'Contacts',
+ *   per_page: 5
+ * });
+ *
+ * const firstPage = await fetchPage.fetchNext();
+ *
+ * if (firstPage.result.info.more_records) {
+ *   const secondPage = await firstPage.fetchNext();
+ * }
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer/docs/api/v8/get-email-rel-list.html
+ */
 export declare function zohoCrmGetEmailsForRecordPageFactory(context: ZohoCrmContext): ZohoCrmGetEmailsForRecordPageFactory;
+/**
+ * Request for fetching attachments, requiring fields to select from the attachment metadata.
+ */
 export type ZohoCrmGetAttachmentsForRecordRequest = ZohoCrmGetRelatedRecordsRequest & ZohoCrmGetRecordsFieldsRef;
+/**
+ * Paginated response containing attachment metadata records.
+ */
 export type ZohoCrmGetAttachmentsForRecordResponse = ZohoPageResult<ZohoCrmRecordAttachmentMetadata>;
+/**
+ * Fetches attachment metadata for a given record.
+ */
 export type ZohoCrmGetAttachmentsForRecordFunction = (input: ZohoCrmGetAttachmentsForRecordRequest) => Promise<ZohoCrmGetAttachmentsForRecordResponse>;
+/**
+ * Creates a {@link ZohoCrmGetAttachmentsForRecordFunction} bound to the given context.
+ *
+ * Retrieves attachment metadata related to a specific record by targeting the
+ * Attachments module via the related records API. Returns a paginated result of
+ * {@link ZohoCrmRecordAttachmentMetadata} entries including file names, sizes,
+ * and category information. When no attachments exist for the record, the result
+ * contains an empty data array rather than null.
+ *
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Function that retrieves attachments for a record
+ *
+ * @example
+ * ```typescript
+ * const getAttachmentsForRecord = zohoCrmGetAttachmentsForRecord(context);
+ *
+ * const result = await getAttachmentsForRecord({
+ *   id: contactId,
+ *   module: 'Contacts',
+ *   fields: 'File_Name,Size,Created_Time'
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/get-related-records.html
+ */
 export declare function zohoCrmGetAttachmentsForRecord(context: ZohoCrmContext): ZohoCrmGetAttachmentsForRecordFunction;
+/**
+ * Factory that creates paginated iterators for fetching attachments related to a record.
+ */
 export type ZohoCrmGetAttachmentsForRecordPageFactory = FetchPageFactory<ZohoCrmGetAttachmentsForRecordRequest, ZohoCrmGetAttachmentsForRecordResponse>;
+/**
+ * Creates a {@link ZohoCrmGetAttachmentsForRecordPageFactory} bound to the given context.
+ *
+ * Returns a page factory for iterating over attachments related to a record
+ * across multiple pages. Wraps {@link zohoCrmGetAttachmentsForRecord} with
+ * automatic pagination handling via {@link zohoFetchPageFactory}.
+ *
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Page factory for iterating over record attachments
+ *
+ * @example
+ * ```typescript
+ * const pageFactory = zohoCrmGetAttachmentsForRecordPageFactory(context);
+ *
+ * const fetchPage = pageFactory({
+ *   id: contactId,
+ *   module: 'Contacts',
+ *   fields: 'File_Name,Size',
+ *   per_page: 10
+ * });
+ *
+ * const firstPage = await fetchPage.fetchNext();
+ *
+ * if (firstPage.result.info.more_records) {
+ *   const secondPage = await firstPage.fetchNext();
+ * }
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/get-related-records.html
+ */
 export declare function zohoCrmGetAttachmentsForRecordPageFactory(context: ZohoCrmContext): ZohoCrmGetAttachmentsForRecordPageFactory;
 /**
  * Maximum attachment size allowed by Zoho Crm.
@@ -248,29 +669,19 @@ export declare function zohoCrmGetAttachmentsForRecordPageFactory(context: ZohoC
 export declare const ZOHO_CRM_ATTACHMENT_MAX_SIZE: number;
 export interface ZohoCrmUploadAttachmentForRecordRequest extends ZohoCrmGetRecordByIdInput {
     /**
-     * Requires the use of a FormData object.
-     *
-     * Max of 20MB are allowed
-     *
-     * @deprecated Use attachmentUrl instead for now.
-     */
-    readonly formData?: FormData;
-    /**
-     * File url to pull the file from.
-     *
-     * Either this or formData must be provided.
+     * File to upload as an attachment. Max 20MB.
      */
-    readonly attachmentUrl?: WebsiteUrlWithPrefix;
+    readonly file: File;
     /**
      * The category id(s) of the attachment.
      *
-     * Either this or attachments_category must be provided.
+     * Either this or attachmentCategoryName must be provided.
      */
     readonly attachmentCategoryId?: ArrayOrValue<ZohoCrmAttachmentCategoryId>;
     /**
      * The category name(s) of the attachment.
      *
-     * Either this or attachments_category_id must be provided.
+     * Either this or attachmentCategoryId must be provided.
      *
      * Example: "Resume"
      */
@@ -279,12 +690,29 @@ export interface ZohoCrmUploadAttachmentForRecordRequest extends ZohoCrmGetRecor
 export type ZohoCrmUploadAttachmentForRecordResponse = Response;
 export type ZohoCrmUploadAttachmentForRecordFunction = (input: ZohoCrmUploadAttachmentForRecordRequest) => Promise<ZohoCrmUploadAttachmentForRecordResponse>;
 /**
- * Uploads an attachment to a record.
+ * Creates a {@link ZohoCrmUploadAttachmentForRecordFunction} bound to the given context.
+ *
+ * Uploads a file attachment to a specific record. The file is sent as
+ * multipart/form-data. An attachment category must be specified by ID or name.
+ * Maximum file size is {@link ZOHO_CRM_ATTACHMENT_MAX_SIZE} (20MB).
+ *
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Function that uploads an attachment to a record
+ * @throws {Error} If neither `attachmentCategoryId` nor `attachmentCategoryName` is provided
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/upload-attachment.html
+ * @example
+ * ```typescript
+ * const uploadAttachment = zohoCrmUploadAttachmentForRecord(context);
  *
- * @param context
- * @returns
+ * await uploadAttachment({
+ *   module: 'Contacts',
+ *   id: contactId,
+ *   file: new File(['content'], 'resume.pdf', { type: 'application/pdf' }),
+ *   attachmentCategoryName: 'Resume'
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer/docs/api/v2.1/upload-attachment.html
  */
 export declare function zohoCrmUploadAttachmentForRecord(context: ZohoCrmContext): ZohoCrmUploadAttachmentForRecordFunction;
 export interface ZohoCrmDownloadAttachmentForRecordRequest extends ZohoCrmGetRecordByIdInput {
@@ -293,12 +721,27 @@ export interface ZohoCrmDownloadAttachmentForRecordRequest extends ZohoCrmGetRec
 export type ZohoCrmDownloadAttachmentForRecordResponse = FetchFileResponse;
 export type ZohoCrmDownloadAttachmentForRecordFunction = (input: ZohoCrmDownloadAttachmentForRecordRequest) => Promise<ZohoCrmDownloadAttachmentForRecordResponse>;
 /**
- * Downloads an attachment from a record.
+ * Creates a {@link ZohoCrmDownloadAttachmentForRecordFunction} bound to the given context.
+ *
+ * Downloads a specific attachment from a record. Returns a parsed
+ * {@link FetchFileResponse} containing the file data and metadata extracted
+ * from the response headers.
+ *
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Function that downloads an attachment by record and attachment ID
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/download-attachments.html
+ * @example
+ * ```typescript
+ * const downloadAttachment = zohoCrmDownloadAttachmentForRecord(context);
  *
- * @param context
- * @returns
+ * const fileResponse = await downloadAttachment({
+ *   module: 'Contacts',
+ *   id: contactId,
+ *   attachment_id: attachmentId
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/download-attachments.html
  */
 export declare function zohoCrmDownloadAttachmentForRecord(context: ZohoCrmContext): ZohoCrmDownloadAttachmentForRecordFunction;
 export interface ZohoCrmDeleteAttachmentFromRecordRequest extends ZohoCrmGetRecordByIdInput {
@@ -307,12 +750,26 @@ export interface ZohoCrmDeleteAttachmentFromRecordRequest extends ZohoCrmGetReco
 export type ZohoCrmDeleteAttachmentFromRecordResponse = Response;
 export type ZohoCrmDeleteAttachmentFromRecordFunction = (input: ZohoCrmDeleteAttachmentFromRecordRequest) => Promise<ZohoCrmDeleteAttachmentFromRecordResponse>;
 /**
- * Deletes an attachment from a record.
+ * Creates a {@link ZohoCrmDeleteAttachmentFromRecordFunction} bound to the given context.
+ *
+ * Deletes a specific attachment from a record by its attachment ID.
+ * Returns the raw {@link Response}.
+ *
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Function that deletes an attachment by record and attachment ID
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/delete-attachments.html
+ * @example
+ * ```typescript
+ * const deleteAttachment = zohoCrmDeleteAttachmentFromRecord(context);
  *
- * @param context
- * @returns
+ * const response = await deleteAttachment({
+ *   module: 'Contacts',
+ *   id: contactId,
+ *   attachment_id: attachmentId
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/delete-attachments.html
  */
 export declare function zohoCrmDeleteAttachmentFromRecord(context: ZohoCrmContext): ZohoCrmDeleteAttachmentFromRecordFunction;
 export type ZohoCrmExecuteRestApiFunctionRequest = ZohoCrmExecuteRestApiFunctionNormalRequest | ZohoCrmExecuteRestApiFunctionApiSpecificRequest;
@@ -350,6 +807,9 @@ export interface ZohoCrmExecuteRestApiFunctionErrorResponse {
     readonly details: unknown;
     readonly message: string;
 }
+/**
+ * Thrown when a Zoho CRM serverless function returns a non-success response code.
+ */
 export declare class ZohoCrmExecuteRestApiFunctionError extends BaseError {
     readonly error: ZohoCrmExecuteRestApiFunctionErrorResponse;
     constructor(error: ZohoCrmExecuteRestApiFunctionErrorResponse);
@@ -361,23 +821,58 @@ export declare class ZohoCrmExecuteRestApiFunctionError extends BaseError {
  */
 export type ZohoCrmExecuteRestApiFunctionFunction = (input: ZohoCrmExecuteRestApiFunctionRequest) => Promise<ZohoCrmExecuteRestApiFunctionSuccessDetails>;
 /**
- * Creates a ZohoCrmExecuteRestApiFunctionFunction
+ * Creates a {@link ZohoCrmExecuteRestApiFunctionFunction} bound to the given context.
+ *
+ * Executes Zoho CRM serverless functions via the REST API. Supports both
+ * OAuth-based and API-key-based authentication. When using an API key, a custom
+ * target URL can be specified for cross-environment calls.
  *
  * OAuth Details:
  * - https://www.zoho.com/crm/developer/docs/functions/serverless-fn-oauth.html#OAuth2
  * - There is no documentation for ZohoCrm specifically, but it seems to behave the same way
  * - You will need the following scopes: ZohoCrm.functions.execute.READ,ZohoCrm.functions.execute.CREATE
  *
- * @param context
- * @returns
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Function that executes serverless functions via the REST API
+ * @throws {ZohoCrmExecuteRestApiFunctionError} If the function execution fails
+ *
+ * @example
+ * ```typescript
+ * const executeFunction = zohoCrmExecuteRestApiFunction(context);
+ *
+ * // Execute using OAuth credentials:
+ * const result = await executeFunction({ functionName: 'my_function' });
+ *
+ * // Execute with parameters:
+ * const paramResult = await executeFunction({
+ *   functionName: 'process_contact',
+ *   params: { contact_id: '12345', action: 'approve' }
+ * });
+ *
+ * // Execute using an API key (cross-environment):
+ * const apiResult = await executeFunction({
+ *   functionName: 'my_function',
+ *   apiKey: 'your-api-key',
+ *   apiUrl: 'production'
+ * });
+ * ```
  */
 export declare function zohoCrmExecuteRestApiFunction(context: ZohoCrmContext): ZohoCrmExecuteRestApiFunctionFunction;
+/**
+ * Builds URL search params from the input objects, omitting the `module` key since it is used in the URL path rather than as a query parameter.
+ */
 export declare function zohoCrmUrlSearchParamsMinusModule(...input: Maybe<object | Record<string, string | number>>[]): URLSearchParams;
+/**
+ * Builds URL search params from the input objects, omitting both `id` and `module` keys since they are used in the URL path.
+ */
 export declare function zohoCrmUrlSearchParamsMinusIdAndModule(...input: Maybe<object | Record<string, string | number>>[]): URLSearchParams;
 /**
  * @deprecated use makeUrlSearchParams instead.
  */
 export declare const zohoCrmUrlSearchParams: typeof makeUrlSearchParams;
+/**
+ * Constructs the standard FetchJsonInput used by CRM API calls, pairing the HTTP method with an optional body.
+ */
 export declare function zohoCrmApiFetchJsonInput(method: string, body?: Maybe<FetchJsonBody>): FetchJsonInput;
 /**
  * Catches ZohoServerFetchResponseDataArrayError and returns the error data array as the response data, as each data element will have the error details.
@@ -397,6 +892,28 @@ export type ZohoCrmChangeObjectLikeResponseSuccessAndErrorPairs<T extends ZohoCr
     readonly successItems: ZohoCrmChangeObjectLikeResponseSuccessEntryType<T>[];
     readonly errorItems: ZohoCrmChangeObjectResponseErrorEntry[];
 };
+/**
+ * Separates a change response's entries into success and error arrays based on their status.
+ *
+ * Iterates over the `data` array from a Zoho CRM change operation response and
+ * partitions entries into `successItems` and `errorItems` based on their `status` field.
+ * The original response is spread into the result, so all original fields remain accessible.
+ *
+ * Used internally by {@link zohoCrmDeleteRecord} and similar functions to provide
+ * convenient access to separated success/error results.
+ *
+ * @param response - Raw change operation response containing mixed success/error entries
+ * @returns The response augmented with pre-separated `successItems` and `errorItems` arrays
+ *
+ * @example
+ * ```typescript
+ * const rawResponse = await context.fetchJson<ZohoCrmChangeObjectLikeResponse>(...);
+ * const result = zohoCrmChangeObjectLikeResponseSuccessAndErrorPairs(rawResponse);
+ *
+ * result.successItems; // entries with status === 'success'
+ * result.errorItems;   // entries with non-success status
+ * ```
+ */
 export declare function zohoCrmChangeObjectLikeResponseSuccessAndErrorPairs<T extends ZohoCrmChangeObjectLikeResponseEntry>(response: ZohoCrmChangeObjectLikeResponse<T>): ZohoCrmChangeObjectLikeResponseSuccessAndErrorPairs<T>;
 export type ZohoCrmChangeObjectResponse<T extends ZohoCrmChangeObjectResponseEntry = ZohoCrmChangeObjectResponseEntry> = ZohoCrmChangeObjectLikeResponse<T>;
 export type ZohoCrmChangeObjectResponseEntry<E extends ZohoCrmChangeObjectResponseSuccessEntry = ZohoCrmChangeObjectResponseSuccessEntry> = ZohoCrmChangeObjectLikeResponseEntry<E>;
@@ -406,13 +923,33 @@ export interface ZohoCrmChangeObjectResponseSuccessEntry<D extends ZohoCrmChange
 export interface ZohoCrmChangeObjectResponseErrorEntry extends ZohoServerErrorDataWithDetails {
     readonly status: ZohoServerErrorStatus;
 }
+/**
+ * Result of a multi-record operation, grouping inputs by whether their API call succeeded or failed.
+ */
 export interface ZohoCrmMultiRecordResult<I, OS, OE> {
     readonly successItems: ZohoCrmMultiRecordResultEntry<I, OS>[];
     readonly errorItems: ZohoCrmMultiRecordResultEntry<I, OE>[];
 }
+/**
+ * Minimal shape required to determine whether an API result entry is a success or error.
+ */
 export interface ZohoCrmMultiRecordResultItem {
     readonly status: ZohoServerSuccessStatus | ZohoServerErrorStatus;
 }
+/**
+ * Pairs each input record with its corresponding API result and separates them into success and error arrays by status.
+ *
+ * Iterates over the `input` and `results` arrays in parallel, matching each input record
+ * to its positional result. Entries are classified as success or error based on
+ * the result's `status` field matching {@link ZOHO_SUCCESS_STATUS}.
+ *
+ * Used internally by {@link updateRecordLikeFunction} to pair input data with API outcomes
+ * for insert, update, and upsert operations.
+ *
+ * @param input - Array of input records that were submitted to the API
+ * @param results - Array of per-record results returned by the API, positionally aligned with `input`
+ * @returns Object with `successItems` and `errorItems`, each containing paired `{ input, result }` entries
+ */
 export declare function zohoCrmMultiRecordResult<I, OS extends ZohoCrmMultiRecordResultItem, OE extends ZohoCrmMultiRecordResultItem>(input: I[], results: (OS | OE)[]): ZohoCrmMultiRecordResult<I, OS, OE>;
 export interface ZohoCrmMultiRecordResultEntry<I, O> {
     /**