@dereekb/zoho 13.0.5 → 13.0.7

package/index.cjs.js

@@ -5,7 +5,10 @@ var fetch = require('@dereekb/util/fetch');
 var makeError = require('make-error');
 
 /**
- * Returns an empty ZohoPageResult that is typed to R and has no more records/results.
+ * Creates an empty {@link ZohoPageResult} with no data and `more_records: false`.
+ * Useful as a fallback when the API returns `null` instead of an empty result.
+ *
+ * @returns An empty page result with default pagination info
  */
 function emptyZohoPageResult() {
     return {
@@ -19,11 +22,26 @@ function emptyZohoPageResult() {
     };
 }
 /**
- * Creates a FetchPageFactory using the input ZohoFetchPageFetchFunction.
+ * Creates a page factory that wraps a Zoho fetch function with automatic pagination.
  *
- * @param fetch
- * @param defaults
- * @returns
+ * The factory reads `info.more_records` from each response to determine if additional
+ * pages exist, and automatically increments the `page` parameter for subsequent requests.
+ *
+ * @param fetch - The Zoho fetch function to paginate over
+ * @param defaults - Optional default configuration for the page factory
+ * @returns A page factory that produces iterable page fetchers
+ *
+ * @example
+ * ```typescript
+ * const pageFactory = zohoFetchPageFactory(zohoCrmSearchRecords(context));
+ *
+ * const fetchPage = pageFactory({ module: 'Contacts', word: 'Smith', per_page: 10 });
+ * const firstPage = await fetchPage.fetchNext();
+ *
+ * if (firstPage.result.info.more_records) {
+ *   const secondPage = await firstPage.fetchNext();
+ * }
+ * ```
  */
 function zohoFetchPageFactory(fetch$1, defaults) {
     return fetch.fetchPageFactory({
@@ -40,7 +58,13 @@ function zohoFetchPageFactory(fetch$1, defaults) {
     });
 }
 
+/**
+ * Service identifier used to distinguish Zoho Recruit from other Zoho services when managing access tokens and API routing.
+ */
 const ZOHO_RECRUIT_SERVICE_NAME = 'recruit';
+/**
+ * Resolves an environment key or passthrough URL to the full Zoho Recruit API URL.
+ */
 function zohoRecruitConfigApiUrl(input) {
     switch (input) {
         case 'sandbox':
@@ -88,9 +112,33 @@ const ZOHO_RECRUIT_RECORD_ATTACHMENT_METADATA_ATTACH_TYPE_RESUME = 'Resume';
  */
 const MAX_ZOHO_SEARCH_MODULE_RECORDS_CRITERIA = 10;
 /**
- * Creates a ZohoSearchRecordsCriteriaString from a ZohoSearchRecordsCriteriaTree.
+ * Compiles a {@link ZohoSearchRecordsCriteriaTreeElement} into a URL-ready criteria string.
+ *
+ * Accepts any supported input shape: a raw criteria string (passed through),
+ * an array of {@link ZohoSearchRecordsCriteriaEntry} (AND-joined), or a full
+ * {@link ZohoSearchRecordsCriteriaTree} with nested AND/OR groups. Returns
+ * `undefined` when the input is nullish or empty.
  *
- * If the input tree is empty, returns undefined.
+ * @param input - Criteria tree element, entry array, or raw criteria string
+ * @returns Compiled criteria string, or `undefined` if input is empty
+ *
+ * @example
+ * ```typescript
+ * // From an entry array (AND-joined):
+ * const criteria = zohoSearchRecordsCriteriaString([
+ *   { field: 'Last_Name', filter: 'equals', value: 'Smith' },
+ *   { field: 'Email', filter: 'contains', value: 'example.com' }
+ * ]);
+ * // => '((Last_Name:equals:Smith)and(Email:contains:example.com))'
+ *
+ * // From a tree with OR:
+ * const orCriteria = zohoSearchRecordsCriteriaString({
+ *   or: [
+ *     [{ field: 'Status', filter: 'equals', value: 'Active' }],
+ *     [{ field: 'Status', filter: 'equals', value: 'Pending' }]
+ *   ]
+ * });
+ * ```
  */
 function zohoSearchRecordsCriteriaString(input) {
     let result;
@@ -113,6 +161,14 @@ function zohoSearchRecordsCriteriaString(input) {
     }
     return result;
 }
+/**
+ * Compiles a {@link ZohoSearchRecordsCriteriaTree} into a criteria string by
+ * recursively resolving nested AND/OR groups. When both `and` and `or` are
+ * present at the same level, the OR group is merged into the AND group.
+ *
+ * @param tree - Criteria tree containing `and` and/or `or` branches
+ * @returns Compiled criteria string, or `undefined` if the tree is empty
+ */
 function zohoSearchRecordsCriteriaStringForTree(tree) {
     function convertToString(value) {
         let result;
@@ -146,7 +202,9 @@ function zohoSearchRecordsCriteriaStringForTree(tree) {
     return result;
 }
 /**
- * Escape used for ZohoSearchRecordsCriteriaString
+ * Escapes parentheses and commas in a field value for use in a {@link ZohoSearchRecordsCriteriaString}.
+ *
+ * Characters `(`, `)`, and `,` are escaped with a double-backslash prefix as required by the Zoho API.
  */
 const escapeZohoFieldValueForCriteriaString = util.escapeStringCharactersFunction({
     /**
@@ -156,10 +214,22 @@ const escapeZohoFieldValueForCriteriaString = util.escapeStringCharactersFunctio
     escapeCharacter: (char) => `\\\\${char}`
 });
 /**
- * Converts the input entry to a ZohoSearchRecordsCriteriaString. Properly escapes any parenthesis or commas.
+ * Converts a single {@link ZohoSearchRecordsCriteriaEntry} into a parenthesized criteria string.
  *
- * @param entry
- * @returns
+ * Automatically escapes parentheses and commas in the value via {@link escapeZohoFieldValueForCriteriaString}.
+ *
+ * @param entry - The criteria entry to convert
+ * @returns Criteria string in the format `(field:filter:escapedValue)`
+ *
+ * @example
+ * ```typescript
+ * const str = zohoSearchRecordsCriteriaEntryToCriteriaString({
+ *   field: 'Last_Name',
+ *   filter: 'equals',
+ *   value: 'Smith'
+ * });
+ * // => '(Last_Name:equals:Smith)'
+ * ```
  */
 function zohoSearchRecordsCriteriaEntryToCriteriaString(entry) {
     const escapedValue = escapeZohoFieldValueForCriteriaString(entry.value);
@@ -167,15 +237,35 @@ function zohoSearchRecordsCriteriaEntryToCriteriaString(entry) {
 }
 
 /**
- * Can search up to 10 criteria at a time.
- *
- * https://www.zoho.com/recruit/developer-guide/apiv2/search-records.html
+ * Maximum number of criteria allowed per Recruit search query (10).
  *
  * "You can search for a maximum of 10 criteria (with the same or different column) with equals and starts_with conditions."
+ *
+ * Re-exports {@link MAX_ZOHO_SEARCH_MODULE_RECORDS_CRITERIA}.
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/search-records.html
  */
 const MAX_ZOHO_RECRUIT_SEARCH_MODULE_RECORDS_CRITERIA = MAX_ZOHO_SEARCH_MODULE_RECORDS_CRITERIA;
+/**
+ * Recruit-specific re-export of {@link zohoSearchRecordsCriteriaString}.
+ *
+ * Compiles a criteria tree element (entry array, nested tree, or raw string) into a
+ * URL-ready criteria string. Returns `undefined` when the input is nullish or empty.
+ */
 const zohoRecruitSearchRecordsCriteriaString = zohoSearchRecordsCriteriaString;
+/**
+ * Recruit-specific re-export of {@link zohoSearchRecordsCriteriaStringForTree}.
+ *
+ * Compiles a {@link ZohoRecruitSearchRecordsCriteriaTree} into a criteria string by
+ * recursively resolving nested AND/OR groups.
+ */
 const zohoRecruitSearchRecordsCriteriaStringForTree = zohoSearchRecordsCriteriaStringForTree;
+/**
+ * Recruit-specific re-export of {@link zohoSearchRecordsCriteriaEntryToCriteriaString}.
+ *
+ * Converts a single criteria entry into a parenthesized criteria string
+ * in the format `(field:filter:escapedValue)`.
+ */
 const zohoRecruitSearchRecordsCriteriaEntryToCriteriaString = zohoSearchRecordsCriteriaEntryToCriteriaString;
 
 /**
@@ -482,19 +572,37 @@ class ZohoRecruitRecordNoContentError extends makeError.BaseError {
         this.recordId = recordId;
     }
 }
+/**
+ * Base error for Zoho Recruit record CRUD operations, carrying structured error details from the API response.
+ */
 class ZohoRecruitRecordCrudError extends ZohoServerError {
 }
+/**
+ * Thrown when a required field is missing from the record data submitted to Zoho Recruit.
+ */
 class ZohoRecruitRecordCrudMandatoryFieldNotFoundError extends ZohoRecruitRecordCrudError {
 }
+/**
+ * Thrown when a record cannot be created or updated because it would produce duplicate data in Zoho Recruit.
+ */
 class ZohoRecruitRecordCrudDuplicateDataError extends ZohoRecruitRecordCrudError {
 }
+/**
+ * Thrown when the Zoho Recruit API rejects record data as invalid. Provides per-field error details via {@link invalidFieldDetails}.
+ */
 class ZohoRecruitRecordCrudInvalidDataError extends ZohoRecruitRecordCrudError {
     get invalidFieldDetails() {
         return this.error.details;
     }
 }
+/**
+ * Thrown when the 'id' field in the submitted data does not match any existing Zoho Recruit record.
+ */
 class ZohoRecruitRecordCrudNoMatchingRecordError extends ZohoRecruitRecordCrudInvalidDataError {
 }
+/**
+ * Creates a typed CRUD error subclass based on the error code returned by the Zoho Recruit API, enabling callers to catch specific failure modes.
+ */
 function zohoRecruitRecordCrudError(error) {
     let result;
     switch (error.code) {
@@ -519,6 +627,9 @@ function zohoRecruitRecordCrudError(error) {
     }
     return result;
 }
+/**
+ * Returns an assertion function that throws {@link ZohoRecruitRecordNoContentError} when the data array result is empty or null, indicating the requested record does not exist.
+ */
 function assertZohoRecruitRecordDataArrayResultHasContent(moduleName, recordId) {
     return (x) => {
         if (x == null || !x.data?.length) {
@@ -529,7 +640,13 @@ function assertZohoRecruitRecordDataArrayResultHasContent(moduleName, recordId)
         }
     };
 }
+/**
+ * Logs Zoho Recruit server errors to the console, prefixed with the 'ZohoRecruit' service label.
+ */
 const logZohoRecruitErrorToConsole = logZohoServerErrorFunction('ZohoRecruit');
+/**
+ * Parses the JSON body of a failed Zoho Recruit fetch response into a structured error, returning undefined if the body cannot be parsed.
+ */
 async function parseZohoRecruitError(responseError) {
     const data = await responseError.response.json().catch((x) => undefined);
     let result;
@@ -538,6 +655,9 @@ async function parseZohoRecruitError(responseError) {
     }
     return result;
 }
+/**
+ * Converts raw Zoho Recruit error response data into a parsed error, delegating to Recruit-specific handlers for known error codes and falling back to the shared Zoho parser.
+ */
 function parseZohoRecruitServerErrorResponseData(errorResponseData, responseError) {
     let result;
     const error = tryFindZohoServerErrorData(errorResponseData, responseError);
@@ -552,7 +672,13 @@ function parseZohoRecruitServerErrorResponseData(errorResponseData, responseErro
     }
     return result;
 }
+/**
+ * Intercepts Zoho Recruit API responses that return HTTP 200 but contain an error payload, re-throwing them as proper errors so callers are not silently misled by a success status.
+ */
 const interceptZohoRecruit200StatusWithErrorResponse = interceptZohoErrorResponseFactory(parseZohoRecruitServerErrorResponseData);
+/**
+ * Wraps a fetch client to automatically parse Zoho Recruit error responses, log them, and invoke a custom handler (e.g., for token refresh on authentication failures).
+ */
 const handleZohoRecruitErrorFetch = handleZohoErrorFetchFactory(parseZohoRecruitError, logZohoRecruitErrorToConsole);
 // MARK: Compat
 /**
@@ -568,9 +694,10 @@ const assertRecordDataArrayResultHasContent = assertZohoRecruitRecordDataArrayRe
  */
 const ZOHO_RECRUIT_CRUD_FUNCTION_MAX_RECORDS_LIMIT = 100;
 /**
- * The APIs for Insert, Upsert, and Update have the same structure.
+ * Shared implementation for the Insert, Upsert, and Update endpoints, which all share the same request/response structure.
  *
- * @returns
+ * When a single record is provided, the function returns the change details directly or throws on error.
+ * When multiple records are provided, it returns a paired success/error result.
  */
 function updateRecordLikeFunction$1(context, fetchUrlPrefix, fetchMethod) {
     return (({ data, module }) => context.fetchJson(`/v2/${module}${fetchUrlPrefix}`, zohoRecruitApiFetchJsonInput(fetchMethod, { data: util.asArray(data) })).then((x) => {
@@ -591,45 +718,145 @@ function updateRecordLikeFunction$1(context, fetchUrlPrefix, fetchMethod) {
     }));
 }
 /**
- * Inserts one or more records into Recruit.
+ * Creates a {@link ZohoRecruitInsertRecordFunction} bound to the given context.
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/insert-records.html
+ * Inserts one or more records into a Recruit module. When a single record is
+ * provided, returns the {@link ZohoRecruitChangeObjectDetails} directly or
+ * throws on error. When multiple records are provided, returns a
+ * {@link ZohoRecruitUpdateRecordResult} with paired success/error arrays.
  *
- * @param context
- * @returns
+ * Maximum of {@link ZOHO_RECRUIT_CRUD_FUNCTION_MAX_RECORDS_LIMIT} records per call.
+ *
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that inserts records into the specified module
+ *
+ * @example
+ * ```typescript
+ * const insertRecord = zohoRecruitInsertRecord(context);
+ *
+ * // Single record — returns details directly or throws on error:
+ * const details = await insertRecord({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   data: { First_Name: 'Jane', Last_Name: 'Doe', Email: 'jane@example.com' }
+ * });
+ *
+ * // Multiple records — returns paired success/error arrays:
+ * const result = await insertRecord({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   data: [
+ *     { First_Name: 'Jane', Last_Name: 'Doe', Email: 'jane@example.com' },
+ *     { First_Name: 'John', Last_Name: 'Doe', Email: 'john@example.com' }
+ *   ]
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/insert-records.html
  */
 function zohoRecruitInsertRecord(context) {
     return updateRecordLikeFunction$1(context, '', 'POST');
 }
 /**
- * Updates or inserts one or more records in Recruit.
+ * Creates a {@link ZohoRecruitUpsertRecordFunction} bound to the given context.
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/upsert-records.html
+ * Inserts or updates one or more records in a Recruit 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_RECRUIT_CRUD_FUNCTION_MAX_RECORDS_LIMIT} records per call.
+ *
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that upserts records in the specified module
+ *
+ * @example
+ * ```typescript
+ * const upsertRecord = zohoRecruitUpsertRecord(context);
+ *
+ * // Create (no id) — returns details directly:
+ * const created = await upsertRecord({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   data: { Email: 'new@example.com', Last_Name: 'New' }
+ * });
+ *
+ * // Update (with id) — returns details directly:
+ * const updated = await upsertRecord({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   data: { id: existingId, First_Name: 'Updated' }
+ * });
+ *
+ * // Mixed create and update — returns paired arrays:
+ * const result = await upsertRecord({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   data: [
+ *     { Email: 'create@example.com', Last_Name: 'Create' },
+ *     { id: existingId, First_Name: 'Update' }
+ *   ]
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/upsert-records.html
  */
 function zohoRecruitUpsertRecord(context) {
     return updateRecordLikeFunction$1(context, '/upsert', 'POST');
 }
 /**
- * Updates one or more records in Recruit.
+ * Creates a {@link ZohoRecruitUpdateRecordFunction} bound to the given context.
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/update-records.html
+ * Updates one or more existing records in a Recruit module. Each record must
+ * include an `id` field. Single-record calls return details directly or throw;
+ * multi-record calls return paired success/error arrays.
  *
- * @param context
- * @returns
+ * Maximum of {@link ZOHO_RECRUIT_CRUD_FUNCTION_MAX_RECORDS_LIMIT} records per call.
+ *
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that updates records in the specified module
+ *
+ * @example
+ * ```typescript
+ * const updateRecord = zohoRecruitUpdateRecord(context);
+ *
+ * // Single record — returns details directly:
+ * const details = await updateRecord({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   data: { id: recordId, First_Name: 'Updated Name' }
+ * });
+ *
+ * // Multiple records — returns paired arrays:
+ * const result = await updateRecord({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   data: [
+ *     { id: recordId1, First_Name: 'Updated 1' },
+ *     { id: recordId2, First_Name: 'Updated 2' }
+ *   ]
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/update-records.html
  */
 function zohoRecruitUpdateRecord(context) {
     return updateRecordLikeFunction$1(context, '', 'PUT');
 }
 /**
- * Deletes one or more records from the given module.
+ * Creates a {@link ZohoRecruitDeleteRecordFunction} bound to the given context.
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/delete-records.html
+ * Deletes one or more records from a Recruit 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
- * @returns ZohoRecruitDeleteRecordFunction
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that deletes records from the specified module
+ *
+ * @example
+ * ```typescript
+ * const deleteRecord = zohoRecruitDeleteRecord(context);
+ *
+ * const result = await deleteRecord({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   ids: candidateId
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/delete-records.html
  */
 function zohoRecruitDeleteRecord(context) {
     return ({ ids, module, wf_trigger }) => {
@@ -637,12 +864,26 @@ function zohoRecruitDeleteRecord(context) {
     };
 }
 /**
- * Retrieves a specific record from the given module.
+ * Creates a {@link ZohoRecruitGetRecordByIdFunction} bound to the given context.
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/get-records.html
+ * Retrieves a single record from a Recruit 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 Recruit context providing fetch and rate limiting
+ * @returns Function that retrieves a record by module name and ID
+ *
+ * @example
+ * ```typescript
+ * const getRecordById = zohoRecruitGetRecordById(context);
+ *
+ * const record = await getRecordById({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   id: candidateId
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/get-records.html
  */
 function zohoRecruitGetRecordById(context) {
     return (input) => context
@@ -651,23 +892,61 @@ function zohoRecruitGetRecordById(context) {
         .then((x) => x.data[0]);
 }
 /**
- * Retrieves records from the given module. Used for paginating across all records.
+ * Creates a {@link ZohoRecruitGetRecordsFunction} bound to the given context.
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/get-records.html
+ * Retrieves a paginated list of records from a Recruit module. Supports field
+ * selection, sorting, custom view filtering, territory filtering, and
+ * conversion/approval status filters via {@link ZohoRecruitGetRecordsInput}.
  *
- * @param context
- * @returns
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that retrieves paginated records from a module
+ *
+ * @example
+ * ```typescript
+ * const getRecords = zohoRecruitGetRecords(context);
+ *
+ * const page = await getRecords({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   per_page: 10
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/get-records.html
  */
 function zohoRecruitGetRecords(context) {
     return ((input) => context.fetchJson(`/v2/${input.module}?${zohoRecruitUrlSearchParamsMinusModule(input).toString()}`, zohoRecruitApiFetchJsonInput('GET')));
 }
 /**
- * Searches records from the given module.
+ * Creates a {@link ZohoRecruitSearchRecordsFunction} bound to the given context.
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/search-records.html
+ * Searches records in a Recruit module using one of: criteria tree (compiled
+ * via {@link zohoRecruitSearchRecordsCriteriaString}), email, phone, 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 Recruit context providing fetch and rate limiting
+ * @returns Function that searches records in the specified module
+ * @throws {Error} If none of `criteria`, `email`, `phone`, or `word` are provided
+ *
+ * @example
+ * ```typescript
+ * const searchRecords = zohoRecruitSearchRecords(context);
+ *
+ * // Search by criteria:
+ * const result = await searchRecords({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   criteria: [{ field: 'Last_Name', filter: 'starts_with', value: 'Smith' }],
+ *   per_page: 10
+ * });
+ *
+ * // Search by keyword:
+ * const wordResult = await searchRecords({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   word: 'engineer'
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/search-records.html
  */
 function zohoRecruitSearchRecords(context) {
     function searchRecordsUrlSearchParams(input) {
@@ -685,16 +964,60 @@ function zohoRecruitSearchRecords(context) {
     }
     return ((input) => context.fetchJson(`/v2/${input.module}/search?${searchRecordsUrlSearchParams(input).toString()}`, zohoRecruitApiFetchJsonInput('GET')).then((x) => x ?? { data: [], info: { more_records: false } }));
 }
+/**
+ * Creates a {@link ZohoRecruitSearchRecordsPageFactory} bound to the given context.
+ *
+ * Returns a page factory that automatically handles Zoho Recruit's pagination,
+ * making it easy to iterate through all search results across multiple pages.
+ *
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Page factory for iterating over search results
+ *
+ * @example
+ * ```typescript
+ * const pageFactory = zohoRecruitSearchRecordsPageFactory(context);
+ *
+ * const fetchPage = pageFactory({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   criteria: [{ field: 'Last_Name', filter: 'starts_with', value: 'Smith' }],
+ *   per_page: 5
+ * });
+ *
+ * const firstPage = await fetchPage.fetchNext();
+ * const secondPage = await firstPage.fetchNext();
+ * ```
+ */
 function zohoRecruitSearchRecordsPageFactory(context) {
     return zohoFetchPageFactory(zohoRecruitSearchRecords(context));
 }
 /**
- * Creates a ZohoRecruitGetRelatedRecordsFunctionFactory, which can be used to create ZohoRecruitGetRelatedRecordsFunction<T> that targets retrieving related records of a given type.
+ * Creates a {@link ZohoRecruitGetRelatedRecordsFunctionFactory} 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 ZohoRecruitGetRelatedRecordsFunctionConfig} 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 Recruit context providing fetch and rate limiting
+ * @returns Factory that creates typed related-records retrieval functions
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/get-related-records.html
+ * @example
+ * ```typescript
+ * const factory = zohoRecruitGetRelatedRecordsFunctionFactory(context);
  *
- * @param context the ZohoRecruitContext to use
- * @returns a ZohoRecruitGetRelatedRecordsFunctionFactory
+ * // Create a typed function for fetching related Notes:
+ * const getNotesForRecord = factory<ZohoRecruitRecordNote>({
+ *   targetModule: ZOHO_RECRUIT_NOTES_MODULE
+ * });
+ *
+ * const notes = await getNotesForRecord({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   id: candidateId
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/get-related-records.html
  */
 function zohoRecruitGetRelatedRecordsFunctionFactory(context) {
     return (config) => {
@@ -702,15 +1025,126 @@ function zohoRecruitGetRelatedRecordsFunctionFactory(context) {
         return (input) => context.fetchJson(`/v2/${input.module}/${input.id}/${targetModule}?${zohoRecruitUrlSearchParamsMinusIdAndModule(input, input.filter).toString()}`, zohoRecruitApiFetchJsonInput('GET')).then((x) => x ?? (returnEmptyRecordsInsteadOfNull !== false ? emptyZohoPageResult() : x));
     };
 }
+/**
+ * Creates a {@link ZohoRecruitGetEmailsForRecordFunction} bound to the given context.
+ *
+ * Retrieves email metadata related to a specific record by targeting the
+ * Emails module via the related records API. Returns a paginated result of
+ * {@link ZohoRecruitRecordEmailMetadata} entries. When no emails exist for the
+ * record, the result contains an empty data array rather than null.
+ *
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that retrieves emails for a record
+ *
+ * @example
+ * ```typescript
+ * const getEmailsForRecord = zohoRecruitGetEmailsForRecord(context);
+ *
+ * const result = await getEmailsForRecord({
+ *   id: candidateId,
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/get-related-records.html
+ */
 function zohoRecruitGetEmailsForRecord(context) {
     return zohoRecruitGetRelatedRecordsFunctionFactory(context)({ targetModule: ZOHO_RECRUIT_EMAILS_MODULE });
 }
+/**
+ * Creates a {@link ZohoRecruitGetEmailsForRecordPageFactory} bound to the given context.
+ *
+ * Returns a page factory for iterating over emails related to a record across
+ * multiple pages. Wraps {@link zohoRecruitGetEmailsForRecord} with automatic
+ * pagination handling via {@link zohoFetchPageFactory}.
+ *
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Page factory for iterating over record emails
+ *
+ * @example
+ * ```typescript
+ * const pageFactory = zohoRecruitGetEmailsForRecordPageFactory(context);
+ *
+ * const fetchPage = pageFactory({
+ *   id: candidateId,
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   per_page: 5
+ * });
+ *
+ * const firstPage = await fetchPage.fetchNext();
+ *
+ * if (firstPage.result.info.more_records) {
+ *   const secondPage = await firstPage.fetchNext();
+ * }
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/get-related-records.html
+ */
 function zohoRecruitGetEmailsForRecordPageFactory(context) {
     return zohoFetchPageFactory(zohoRecruitGetEmailsForRecord(context));
 }
+/**
+ * Creates a {@link ZohoRecruitGetAttachmentsForRecordFunction} 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 ZohoRecruitRecordAttachmentMetadata} 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.
+ *
+ * Each attachment entry includes a `$type` field that distinguishes between
+ * directly uploaded attachments (`'Attachment'`) and linked attachments.
+ *
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that retrieves attachments for a record
+ *
+ * @example
+ * ```typescript
+ * const getAttachmentsForRecord = zohoRecruitGetAttachmentsForRecord(context);
+ *
+ * const result = await getAttachmentsForRecord({
+ *   id: candidateId,
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE
+ * });
+ *
+ * // Filter to only directly uploaded attachments (downloadable):
+ * const downloadable = result.data.filter((x) => x.$type === 'Attachment');
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/get-related-records.html
+ */
 function zohoRecruitGetAttachmentsForRecord(context) {
     return zohoRecruitGetRelatedRecordsFunctionFactory(context)({ targetModule: ZOHO_RECRUIT_ATTACHMENTS_MODULE });
 }
+/**
+ * Creates a {@link ZohoRecruitGetAttachmentsForRecordPageFactory} bound to the given context.
+ *
+ * Returns a page factory for iterating over attachments related to a record
+ * across multiple pages. Wraps {@link zohoRecruitGetAttachmentsForRecord} with
+ * automatic pagination handling via {@link zohoFetchPageFactory}.
+ *
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Page factory for iterating over record attachments
+ *
+ * @example
+ * ```typescript
+ * const pageFactory = zohoRecruitGetAttachmentsForRecordPageFactory(context);
+ *
+ * const fetchPage = pageFactory({
+ *   id: candidateId,
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   per_page: 10
+ * });
+ *
+ * const firstPage = await fetchPage.fetchNext();
+ *
+ * if (firstPage.result.info.more_records) {
+ *   const secondPage = await firstPage.fetchNext();
+ * }
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/get-related-records.html
+ */
 function zohoRecruitGetAttachmentsForRecordPageFactory(context) {
     return zohoFetchPageFactory(zohoRecruitGetAttachmentsForRecord(context));
 }
@@ -721,88 +1155,121 @@ function zohoRecruitGetAttachmentsForRecordPageFactory(context) {
  */
 const ZOHO_RECRUIT_ATTACHMENT_MAX_SIZE = 20 * 1024 * 1024;
 /**
- * Uploads an attachment to a record.
+ * Creates a {@link ZohoRecruitUploadAttachmentForRecordFunction} bound to the given context.
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/upload-attachment.html
+ * Uploads an attachment to a specific record. Supports either a direct
+ * {@link File} upload (sent as multipart/form-data) or a URL from which Zoho
+ * will fetch the file. An attachment category must be specified by ID or name.
+ * Maximum file size is {@link ZOHO_RECRUIT_ATTACHMENT_MAX_SIZE} (20MB).
  *
- * @param context
- * @returns
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that uploads an attachment to a record
+ * @throws {Error} If neither `file` nor `attachmentUrl` is provided
+ * @throws {Error} If neither `attachmentCategoryId` nor `attachmentCategoryName` is provided
+ *
+ * @example
+ * ```typescript
+ * const uploadAttachment = zohoRecruitUploadAttachmentForRecord(context);
+ *
+ * // Upload a file directly:
+ * await uploadAttachment({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   id: candidateId,
+ *   file: new File(['content'], 'resume.pdf', { type: 'application/pdf' }),
+ *   attachmentCategoryName: 'Resume'
+ * });
+ *
+ * // Upload from a URL:
+ * await uploadAttachment({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   id: candidateId,
+ *   attachmentUrl: 'https://example.com/document.pdf',
+ *   attachmentCategoryName: 'Others'
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/upload-attachment.html
  */
 function zohoRecruitUploadAttachmentForRecord(context) {
     return (input) => {
-        const { attachmentCategoryId, attachmentCategoryName, formData } = input;
+        const { attachmentCategoryId, attachmentCategoryName, file, attachmentUrl } = input;
         const urlParams = {
             attachments_category_id: util.joinStringsWithCommas(attachmentCategoryId),
-            attachments_category: util.joinStringsWithCommas(attachmentCategoryName),
-            attachment_url: input.attachmentUrl
+            attachments_category: util.joinStringsWithCommas(attachmentCategoryName)
         };
         if (!urlParams.attachments_category_id?.length && !urlParams.attachments_category?.length) {
             throw new Error('attachmentCategoryId or attachmentCategoryName must be provided and not empty.');
         }
-        if (formData != null) {
-            delete urlParams.attachment_url;
+        const url = `/v2/${input.module}/${input.id}/${ZOHO_RECRUIT_ATTACHMENTS_MODULE}?${fetch.makeUrlSearchParams(urlParams).toString()}`;
+        if (file != null) {
+            const body = new FormData();
+            body.append('file', file);
+            // Clear the base Content-Type header (empty string removes it via mergeRequestHeaders) so fetch auto-detects multipart/form-data with the correct boundary from the FormData body.
+            return context.fetch(url, { method: 'POST', headers: { 'Content-Type': '' }, body });
         }
-        const url = `https://recruitsandbox.zoho.com/recruit/v2/${input.module}/${input.id}/${ZOHO_RECRUIT_ATTACHMENTS_MODULE}?${fetch.makeUrlSearchParams(urlParams).toString()}`;
-        let response;
-        if (urlParams.attachment_url) {
-            response = context.fetch(url, { method: 'POST' });
-        }
-        else if (formData != null) {
-            throw new Error('unsupported currently. Use the attachmentUrl parameter instead.');
-            // There is something weird going on with sending requests this way and zoho's server is rejecting it.
-            /*
-            response = context.fetch(url, {
-              method: 'POST',
-              headers: {
-                'Content-Type': 'multipart/form-data',
-                'content-length': '210'
-              },
-              body: formData
-            });
-            */
-            /*
-            const fullUrl = (context.config.apiUrl as string) + url;
-            const accessToken = await context.accessTokenStringFactory();
-      
-            response = fetch(fullUrl, {
-              headers: {
-                Authorization: `Bearer ${accessToken}`
-              },
-              body: formData,
-              method: 'POST'
-            });
-      
-            console.log({ response });
-            */
+        else if (attachmentUrl) {
+            const urlWithAttachment = `${url}&${fetch.makeUrlSearchParams({ attachment_url: attachmentUrl }).toString()}`;
+            return context.fetch(urlWithAttachment, { method: 'POST' });
         }
         else {
-            throw new Error('body or attachmentUrl must be provided.');
+            throw new Error('file or attachmentUrl must be provided.');
         }
-        return response;
     };
 }
 /**
- * Downloads an attachment from a record.
+ * Creates a {@link ZohoRecruitDownloadAttachmentForRecordFunction} bound to the given context.
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/download-attachments.html
+ * 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
- * @returns
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that downloads an attachment by record and attachment ID
+ *
+ * @example
+ * ```typescript
+ * const downloadAttachment = zohoRecruitDownloadAttachmentForRecord(context);
+ *
+ * const fileResponse = await downloadAttachment({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   id: candidateId,
+ *   attachment_id: attachmentId
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/download-attachments.html
  */
 function zohoRecruitDownloadAttachmentForRecord(context) {
     return (input) => context.fetch(`/v2/${input.module}/${input.id}/${ZOHO_RECRUIT_ATTACHMENTS_MODULE}/${input.attachment_id}`, { method: 'GET' }).then(fetch.parseFetchFileResponse);
 }
 /**
- * Deletes an attachment from a record.
+ * Creates a {@link ZohoRecruitDeleteAttachmentFromRecordFunction} bound to the given context.
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/delete-attachments.html
+ * Deletes a specific attachment from a record by its attachment ID.
+ * Returns the raw {@link Response}.
  *
- * @param context
- * @returns
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that deletes an attachment by record and attachment ID
+ *
+ * @example
+ * ```typescript
+ * const deleteAttachment = zohoRecruitDeleteAttachmentFromRecord(context);
+ *
+ * const response = await deleteAttachment({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   id: candidateId,
+ *   attachment_id: attachmentId
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/delete-attachments.html
  */
 function zohoRecruitDeleteAttachmentFromRecord(context) {
     return (input) => context.fetch(`/v2/${input.module}/${input.id}/${ZOHO_RECRUIT_ATTACHMENTS_MODULE}/${input.attachment_id}`, { method: 'DELETE' });
 }
+/**
+ * Thrown when a Zoho Recruit serverless function execution fails, wrapping the error response with the API error code and message.
+ */
 class ZohoRecruitExecuteRestApiFunctionError extends makeError.BaseError {
     error;
     constructor(error) {
@@ -811,15 +1278,39 @@ class ZohoRecruitExecuteRestApiFunctionError extends makeError.BaseError {
     }
 }
 /**
- * Creates a ZohoRecruitExecuteRestApiFunctionFunction
+ * Creates a function that executes Zoho Recruit 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 ZohoRecruit specifically, but it seems to behave the same way
  * - You will need the following scopes: ZohoRecruit.functions.execute.READ,ZohoRecruit.functions.execute.CREATE
  *
- * @param context
- * @returns
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that executes serverless functions via the REST API
+ * @throws {ZohoRecruitExecuteRestApiFunctionError} If the function execution fails
+ *
+ * @example
+ * ```typescript
+ * const executeFunction = zohoRecruitExecuteRestApiFunction(context);
+ *
+ * // Execute using OAuth credentials:
+ * const result = await executeFunction({ functionName: 'my_function' });
+ *
+ * // Execute with parameters:
+ * const paramResult = await executeFunction({
+ *   functionName: 'process_candidate',
+ *   params: { candidate_id: '12345', action: 'approve' }
+ * });
+ *
+ * // Execute using an API key (cross-environment):
+ * const apiResult = await executeFunction({
+ *   functionName: 'my_function',
+ *   apiKey: 'your-api-key',
+ *   apiUrl: 'production'
+ * });
+ * ```
  */
 function zohoRecruitExecuteRestApiFunction(context) {
     return (input) => {
@@ -841,9 +1332,15 @@ function zohoRecruitExecuteRestApiFunction(context) {
     };
 }
 // MARK: Util
+/**
+ * Builds URL search params from input objects, omitting the `module` key since it is used in the URL path rather than query string.
+ */
 function zohoRecruitUrlSearchParamsMinusModule(...input) {
     return fetch.makeUrlSearchParams(input, { omitKeys: 'module' });
 }
+/**
+ * Builds URL search params from input objects, omitting both `id` and `module` keys since they are used in the URL path.
+ */
 function zohoRecruitUrlSearchParamsMinusIdAndModule(...input) {
     return fetch.makeUrlSearchParams(input, { omitKeys: ['id', 'module'] });
 }
@@ -851,6 +1348,9 @@ function zohoRecruitUrlSearchParamsMinusIdAndModule(...input) {
  * @deprecated use makeUrlSearchParams instead.
  */
 const zohoRecruitUrlSearchParams = fetch.makeUrlSearchParams;
+/**
+ * Constructs a standard {@link FetchJsonInput} for Zoho Recruit API calls with the given HTTP method and optional body.
+ */
 function zohoRecruitApiFetchJsonInput(method, body) {
     const result = {
         method,
@@ -858,6 +1358,28 @@ function zohoRecruitApiFetchJsonInput(method, body) {
     };
     return result;
 }
+/**
+ * Separates a change response's entries into success and error arrays based on their status.
+ *
+ * Iterates over the `data` array from a Zoho Recruit 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 zohoRecruitDeleteRecord} 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<ZohoRecruitChangeObjectLikeResponse>(...);
+ * const result = zohoRecruitChangeObjectLikeResponseSuccessAndErrorPairs(rawResponse);
+ *
+ * result.successItems; // entries with status === 'success'
+ * result.errorItems;   // entries with non-success status
+ * ```
+ */
 function zohoRecruitChangeObjectLikeResponseSuccessAndErrorPairs(response) {
     const { data } = response;
     const successItems = [];
@@ -877,6 +1399,20 @@ function zohoRecruitChangeObjectLikeResponseSuccessAndErrorPairs(response) {
     };
     return result;
 }
+/**
+ * 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
+ */
 function zohoRecruitMultiRecordResult(input, results) {
     const successItems = [];
     const errorItems = [];
@@ -973,10 +1509,9 @@ const executeRestApiFunction = zohoRecruitExecuteRestApiFunction;
 /**
  * Associates one or more candidates with one or more job openings.
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/associate-candidate.html
+ * The result separates "already associated" errors from other errors, allowing callers to treat duplicate associations as non-fatal.
  *
- * @param context
- * @returns
+ * https://www.zoho.com/recruit/developer-guide/apiv2/associate-candidate.html
  */
 function zohoRecruitAssociateCandidateRecordsWithJobOpenings(context) {
     return (input) => context.fetchJson(`/v2/${ZOHO_RECRUIT_CANDIDATES_MODULE}/actions/associate`, zohoRecruitApiFetchJsonInput('PUT', { data: util.asArray(input) })).then((x) => {
@@ -993,6 +1528,9 @@ function zohoRecruitAssociateCandidateRecordsWithJobOpenings(context) {
         };
     });
 }
+/**
+ * Searches for records associated with a given candidate or job opening. Returns an empty page result when no records are found.
+ */
 function zohoRecruitSearchAssociatedRecords(context) {
     return (input) => {
         return context.fetchJson(`/v2/${input.module}/${input.id}/associate?${zohoRecruitUrlSearchParamsMinusIdAndModule(input).toString()}`, zohoRecruitApiFetchJsonInput('GET')).then((x) => {
@@ -1001,6 +1539,9 @@ function zohoRecruitSearchAssociatedRecords(context) {
         });
     };
 }
+/**
+ * Searches for job openings associated with a specific candidate.
+ */
 function zohoRecruitSearchCandidateAssociatedJobOpeningRecords(context) {
     const searchAssociatedRecordsFactory = zohoRecruitSearchAssociatedRecords(context);
     return (input) => {
@@ -1010,9 +1551,15 @@ function zohoRecruitSearchCandidateAssociatedJobOpeningRecords(context) {
         });
     };
 }
+/**
+ * Creates a page factory for paginating over job openings associated with a candidate.
+ */
 function zohoRecruitSearchCandidateAssociatedJobOpeningRecordsPageFactory(context) {
     return zohoFetchPageFactory(zohoRecruitSearchCandidateAssociatedJobOpeningRecords(context));
 }
+/**
+ * Searches for candidates associated with a specific job opening.
+ */
 function zohoRecruitSearchJobOpeningAssociatedCandidateRecords(context, jobOpeningModuleName = ZOHO_RECRUIT_JOB_OPENINGS_MODULE) {
     const searchAssociatedRecordsFactory = zohoRecruitSearchAssociatedRecords(context);
     return (input) => {
@@ -1022,26 +1569,124 @@ function zohoRecruitSearchJobOpeningAssociatedCandidateRecords(context, jobOpeni
         });
     };
 }
+/**
+ * Creates a page factory for paginating over candidates associated with a job opening.
+ */
 function zohoRecruitSearchJobOpeningAssociatedCandidateRecordsPageFactory(context) {
     return zohoFetchPageFactory(zohoRecruitSearchJobOpeningAssociatedCandidateRecords(context));
 }
 
+/**
+ * Creates a {@link ZohoRecruitCreateNotesFunction} bound to the given context.
+ *
+ * Creates one or more notes directly in the Notes module. Each note entry must include
+ * `se_module` and `Parent_Id` to link the note to a record.
+ *
+ * Prefer {@link zohoRecruitCreateNotesForRecord} when creating notes linked to a specific
+ * record, as it handles the module/parent linking automatically.
+ *
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that creates notes in the Notes module
+ *
+ * @example
+ * ```typescript
+ * const createNotes = zohoRecruitCreateNotes(context);
+ *
+ * const result = await createNotes({
+ *   data: [{
+ *     Note_Title: 'Interview Notes',
+ *     Note_Content: 'Strong candidate',
+ *     se_module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *     Parent_Id: candidateId
+ *   }]
+ * });
+ * ```
+ */
 function zohoRecruitCreateNotes(context) {
     return (input) => context.fetchJson(`/v2/${ZOHO_RECRUIT_NOTES_MODULE}`, zohoRecruitApiFetchJsonInput('POST', { data: input.data })).then((x) => {
         return zohoRecruitMultiRecordResult(util.asArray(input.data), x.data);
     });
 }
+/**
+ * Creates a {@link ZohoRecruitDeleteNotesFunction} bound to the given context.
+ *
+ * Deletes one or more notes by their IDs from the Notes module. Returns a paired
+ * success/error result for each note ID.
+ *
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that deletes notes by ID
+ *
+ * @example
+ * ```typescript
+ * const deleteNotes = zohoRecruitDeleteNotes(context);
+ *
+ * const result = await deleteNotes({ ids: [noteId1, noteId2] });
+ * ```
+ */
 function zohoRecruitDeleteNotes(context) {
     return (input) => context.fetchJson(`/v2/${ZOHO_RECRUIT_NOTES_MODULE}?${fetch.makeUrlSearchParams({ ids: input.ids })}`, zohoRecruitApiFetchJsonInput('DELETE')).then((x) => {
         return zohoRecruitMultiRecordResult(util.asArray(input.ids), x.data);
     });
 }
+/**
+ * Creates a {@link ZohoRecruitGetNotesForRecordFunction} bound to the given context.
+ *
+ * Retrieves notes related to a specific record by targeting the Notes module
+ * via the related records API. Returns an empty page result when no notes exist.
+ *
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that retrieves notes for a record
+ *
+ * @example
+ * ```typescript
+ * const getNotesForRecord = zohoRecruitGetNotesForRecord(context);
+ *
+ * const result = await getNotesForRecord({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   id: candidateId
+ * });
+ * ```
+ */
 function zohoRecruitGetNotesForRecord(context) {
     return zohoRecruitGetRelatedRecordsFunctionFactory(context)({ targetModule: ZOHO_RECRUIT_NOTES_MODULE });
 }
+/**
+ * Creates a {@link ZohoRecruitGetNotesForRecordPageFactory} bound to the given context.
+ *
+ * Returns a page factory for iterating over notes related to a record across
+ * multiple pages. Wraps {@link zohoRecruitGetNotesForRecord} with automatic
+ * pagination handling via {@link zohoFetchPageFactory}.
+ *
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Page factory for iterating over record notes
+ */
 function zohoRecruitGetNotesForRecordPageFactory(context) {
     return zohoFetchPageFactory(zohoRecruitGetNotesForRecord(context));
 }
+/**
+ * Creates a {@link ZohoRecruitCreateNotesForRecordFunction} bound to the given context.
+ *
+ * Creates one or more notes linked to a specific record. Automatically sets
+ * `se_module` and `Parent_Id` on each note entry from the request's `module` and `id`,
+ * then delegates to {@link zohoRecruitCreateNotes}.
+ *
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that creates notes linked to a specific record
+ *
+ * @example
+ * ```typescript
+ * const createNotesForRecord = zohoRecruitCreateNotesForRecord(context);
+ *
+ * const result = await createNotesForRecord({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   id: candidateId,
+ *   notes: {
+ *     Note_Title: 'Interview Notes',
+ *     Note_Content: 'Strong candidate for the role.'
+ *   }
+ * });
+ * ```
+ */
 function zohoRecruitCreateNotesForRecord(context) {
     const createNotesInstance = zohoRecruitCreateNotes(context);
     return (input) => {
@@ -1078,6 +1723,30 @@ const getNotesForRecordPageFactory = zohoRecruitGetNotesForRecordPageFactory;
  */
 const createNotesForRecord = zohoRecruitCreateNotesForRecord;
 
+/**
+ * Creates a {@link ZohoRecruitCreateTagsFunction} bound to the given context.
+ *
+ * Creates one or more tags for a module. The result separates duplicate tag errors
+ * (which are often non-fatal) from other errors, making it easy to handle the common
+ * case where a tag already exists.
+ *
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that creates tags in the specified module
+ *
+ * @example
+ * ```typescript
+ * const createTags = zohoRecruitCreateTagsForModule(context);
+ *
+ * const result = await createTags({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   tags: [{ name: 'Interviewed' }, { name: 'Priority', color_code: '#FF0000' }]
+ * });
+ *
+ * // Duplicate tags are separated for convenience:
+ * result.duplicateErrorItems; // tags that already existed
+ * result.errorItems;          // other (real) errors
+ * ```
+ */
 function zohoRecruitCreateTagsForModule(context) {
     return (input) => context.fetchJson(`/v2/settings/tags?${fetch.makeUrlSearchParams({ module: input.module })}`, zohoRecruitApiFetchJsonInput('POST', { tags: util.asArray(input.tags) })).then((x) => {
         const result = zohoRecruitMultiRecordResult(util.asArray(input.tags), x.tags);
@@ -1093,12 +1762,24 @@ function zohoRecruitCreateTagsForModule(context) {
     });
 }
 /**
- * Returns the list of tags within a module.
+ * Creates a {@link ZohoRecruitGetTagsFunction} bound to the given context.
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/get-tag-list.html
+ * Returns the list of tags within a module. Normalizes the non-standard API response
+ * that returns data under a `tags` key instead of the standard `data` key.
  *
- * @param context
- * @returns
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that retrieves tags for a module
+ *
+ * @example
+ * ```typescript
+ * const getTags = zohoRecruitGetTagsForModule(context);
+ *
+ * const result = await getTags({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/get-tag-list.html
  */
 function zohoRecruitGetTagsForModule(context) {
     return (input) => context.fetchJson(`/v2/settings/tags?${fetch.makeUrlSearchParams({ module: input.module, my_tags: input.my_tags })}`, zohoRecruitApiFetchJsonInput('GET')).then((x) => {
@@ -1109,21 +1790,45 @@ function zohoRecruitGetTagsForModule(context) {
         };
     });
 }
+/**
+ * Creates a {@link ZohoRecruitGetTagsForModulePageFactory} bound to the given context.
+ *
+ * Returns a page factory for iterating over tags in a module across multiple pages.
+ * Wraps {@link zohoRecruitGetTagsForModule} with automatic pagination handling.
+ *
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Page factory for iterating over module tags
+ */
 function zohoRecruitGetTagsForModulePageFactory(context) {
     return zohoFetchPageFactory(zohoRecruitGetTagsForModule(context));
 }
 // MARK: Add Tag To Record
 /**
- * Limit enforced by Zoho Recruit
+ * Maximum number of record ids allowed when adding tags, enforced by the Zoho Recruit API.
  */
 const ZOHO_RECRUIT_ADD_TAGS_TO_RECORDS_MAX_IDS_ALLOWED = 100;
 /**
- * Adds one or more tags to one or more records.
+ * Creates a {@link ZohoRecruitAddTagsToRecordsFunction} bound to the given context.
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/add-tags.html
+ * Adds one or more tags to one or more records. Returns a paired success/error result
+ * for each record. Maximum of {@link ZOHO_RECRUIT_ADD_TAGS_TO_RECORDS_MAX_IDS_ALLOWED} (100) record IDs per call.
  *
- * @param context
- * @returns
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that adds tags to records
+ * @throws {Error} If more than 100 record IDs are provided
+ *
+ * @example
+ * ```typescript
+ * const addTags = zohoRecruitAddTagsToRecords(context);
+ *
+ * const result = await addTags({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   tag_names: ['Interviewed', 'Priority'],
+ *   ids: [candidateId1, candidateId2]
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/add-tags.html
  */
 function zohoRecruitAddTagsToRecords(context) {
     return (input) => {
@@ -1138,16 +1843,31 @@ function zohoRecruitAddTagsToRecords(context) {
 }
 // MARK: Remove Tag From Record
 /**
- * Limit enforced by Zoho Recruit
+ * Maximum number of record ids allowed when removing tags, enforced by the Zoho Recruit API.
  */
 const ZOHO_RECRUIT_REMOVE_TAGS_FROM_RECORDS_MAX_IDS_ALLOWED = 100;
 /**
- * Removes one or more tags from one or more records.
+ * Creates a {@link ZohoRecruitRemoveTagsFromRecordsFunction} bound to the given context.
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/remove-tags.html
+ * Removes one or more tags from one or more records. Returns a paired success/error result
+ * for each record. Maximum of {@link ZOHO_RECRUIT_REMOVE_TAGS_FROM_RECORDS_MAX_IDS_ALLOWED} (100) record IDs per call.
  *
- * @param context
- * @returns
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that removes tags from records
+ * @throws {Error} If more than 100 record IDs are provided
+ *
+ * @example
+ * ```typescript
+ * const removeTags = zohoRecruitRemoveTagsFromRecords(context);
+ *
+ * const result = await removeTags({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   tag_names: 'Interviewed',
+ *   ids: candidateId
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/remove-tags.html
  */
 function zohoRecruitRemoveTagsFromRecords(context) {
     return (input) => {
@@ -1250,16 +1970,39 @@ function zohoAccessTokenStringFactory(zohoAccessTokenFactory) {
     };
 }
 
+/**
+ * Default handler that logs a warning to the console when the Zoho API rate limit is exceeded.
+ */
 const DEFAULT_ZOHO_RATE_LIMITED_TOO_MANY_REQUETS_LOG_FUNCTION = (headers) => {
     console.warn(`zohoRateLimitedFetchHandler(): Too many requests made. The limit is ${headers.limit} requests per reset period. Will be reset at ${headers.resetAt}.`);
 };
+/**
+ * Creates a {@link ZohoRateLimitedFetchHandler} that throttles outgoing requests based on
+ * Zoho's rate limit headers (`X-RATELIMIT-LIMIT`, `X-RATELIMIT-REMAINING`, `X-RATELIMIT-RESET`).
+ *
+ * The handler uses an exponential backoff strategy with the following behavior:
+ * - Rate limiting begins after 10% of the allowed requests have been made (`startLimitAt`)
+ * - Wait times increase exponentially (rate 1.08) as more requests are made, capped at 10 seconds
+ * - On each response, the limiter updates its remaining count and reset time from headers
+ * - When the API returns a different limit than configured, the limiter dynamically adjusts
+ * - On 429 responses, the request is automatically retried after the rate limiter delay
+ * - The limiter is disabled when responses lack rate limit headers (e.g., error responses)
+ *
+ * @param config - Optional configuration for rate limit, reset period, and 429 handling
+ * @returns A rate-limited fetch handler with the underlying rate limiter accessible via `_rateLimiter`
+ */
 function zohoRateLimitedFetchHandler(config) {
     const onTooManyRequests = config?.onTooManyRequests !== false ? (config?.onTooManyRequests ?? DEFAULT_ZOHO_RATE_LIMITED_TOO_MANY_REQUETS_LOG_FUNCTION) : undefined;
     const defaultLimit = config?.maxRateLimit ?? DEFAULT_ZOHO_API_RATE_LIMIT;
     const defaultResetPeriod = config?.resetPeriod ?? DEFAULT_ZOHO_API_RATE_LIMIT_RESET_PERIOD;
+    /**
+     * Builds a rate limiter config derived from the given limit.
+     * Called once at initialization with `defaultLimit`, and again dynamically
+     * when the API's `X-RATELIMIT-LIMIT` header reports a different value.
+     */
     function configForLimit(limit, resetAt) {
         return {
-            limit: defaultLimit,
+            limit,
             startLimitAt: Math.ceil(limit / 10), // can do 10% of the requests of the limit before rate limiting begins
             cooldownRate: 1.2 * (limit / (defaultResetPeriod / util.MS_IN_SECOND)),
             exponentRate: 1.08,
@@ -1272,6 +2015,10 @@ function zohoRateLimitedFetchHandler(config) {
     const rateLimiter = util.resetPeriodPromiseRateLimiter(defaultConfig);
     return fetch.rateLimitedFetchHandler({
         rateLimiter,
+        /**
+         * Inspects each response for Zoho rate limit headers and updates the limiter accordingly.
+         * Returns `true` to signal a retry when a 429 status is received.
+         */
         updateWithResponse: function (response, fetchResponseError) {
             const hasLimitHeader = response.headers.has(ZOHO_RATE_LIMIT_REMAINING_HEADER);
             let shouldRetry = false;
@@ -1280,7 +2027,7 @@ function zohoRateLimitedFetchHandler(config) {
                 const headerDetails = zohoRateLimitHeaderDetails(response.headers);
                 if (headerDetails) {
                     const { limit, resetAt, remaining } = headerDetails;
-                    if (limit !== defaultLimit) {
+                    if (limit && limit !== defaultLimit) {
                         const newConfig = configForLimit(limit, resetAt);
                         rateLimiter.setConfig(newConfig, false);
                     }
@@ -1303,6 +2050,31 @@ function zohoRateLimitedFetchHandler(config) {
     });
 }
 
+/**
+ * Creates a {@link ZohoRecruitFactory} from the given configuration.
+ *
+ * The factory pre-initializes shared resources (access token provider, rate limiter)
+ * once, then produces {@link ZohoRecruit} client instances for each {@link ZohoRecruitConfig}.
+ * Each client handles OAuth token refresh on {@link ZohoInvalidTokenError}, rate limiting,
+ * and Zoho Recruit's non-standard error responses (200 status with error body).
+ *
+ * @param factoryConfig - Configuration providing account credentials and optional overrides
+ * @returns A factory function that creates authenticated Zoho Recruit clients
+ *
+ * @example
+ * ```typescript
+ * const factory = zohoRecruitFactory({
+ *   accountsContext: zohoAccountsApi.accountsContext
+ * });
+ *
+ * const zohoRecruit = factory({
+ *   apiUrl: 'https://recruit.zoho.com'
+ * });
+ *
+ * // Use the recruit context for API calls:
+ * const { recruitContext } = zohoRecruit;
+ * ```
+ */
 function zohoRecruitFactory(factoryConfig) {
     const { accountsContext } = factoryConfig;
     const accessTokenStringFactory = zohoAccessTokenStringFactory(accountsContext.loadAccessToken);
@@ -1357,7 +2129,13 @@ function zohoRecruitFactory(factoryConfig) {
  */
 const ZOHO_RECRUIT_TAG_NAME_MAX_LENGTH = 25;
 
+/**
+ * Service identifier used for Zoho CRM API access token resolution and service routing.
+ */
 const ZOHO_CRM_SERVICE_NAME = 'crm';
+/**
+ * Resolves a CRM API URL input to its full base URL. Well-known keys ('sandbox', 'production') map to their respective Zoho CRM endpoints; custom URLs pass through unchanged.
+ */
 function zohoCrmConfigApiUrl(input) {
     switch (input) {
         case 'sandbox':
@@ -1400,16 +2178,41 @@ const isZohoCrmValidUrl = util.isStandardInternetAccessibleWebsiteUrl;
 const ZOHO_CRM_RECORD_ATTACHMENT_METADATA_ATTACH_TYPE_RESUME = 'Resume';
 
 /**
- * Can search up to 10 criteria at a time.
- *
- * https://www.zoho.com/crm/developer/docs/api/v8/search-records.html
+ * Maximum number of criteria allowed per CRM search query (10).
  *
  * "You can search for a maximum of 10 criteria (with the same or different column) with equals and starts_with conditions."
+ *
+ * Re-exports {@link MAX_ZOHO_SEARCH_MODULE_RECORDS_CRITERIA}.
+ *
+ * @see https://www.zoho.com/crm/developer/docs/api/v8/search-records.html
  */
 const MAX_ZOHO_CRM_SEARCH_MODULE_RECORDS_CRITERIA = MAX_ZOHO_SEARCH_MODULE_RECORDS_CRITERIA;
+/**
+ * CRM-specific re-export of {@link zohoSearchRecordsCriteriaString}.
+ *
+ * Compiles a criteria tree element (entry array, nested tree, or raw string) into a
+ * URL-ready criteria string. Returns `undefined` when the input is nullish or empty.
+ */
 const zohoCrmSearchRecordsCriteriaString = zohoSearchRecordsCriteriaString;
+/**
+ * CRM-specific re-export of {@link zohoSearchRecordsCriteriaStringForTree}.
+ *
+ * Compiles a {@link ZohoCrmSearchRecordsCriteriaTree} into a criteria string by
+ * recursively resolving nested AND/OR groups.
+ */
 const zohoCrmSearchRecordsCriteriaStringForTree = zohoSearchRecordsCriteriaStringForTree;
+/**
+ * CRM-specific re-export of {@link escapeZohoFieldValueForCriteriaString}.
+ *
+ * Escapes parentheses and commas in a field value for use in a criteria string.
+ */
 const escapeZohoCrmFieldValueForCriteriaString = escapeZohoFieldValueForCriteriaString;
+/**
+ * CRM-specific re-export of {@link zohoSearchRecordsCriteriaEntryToCriteriaString}.
+ *
+ * Converts a single criteria entry into a parenthesized criteria string
+ * in the format `(field:filter:escapedValue)`.
+ */
 const zohoCrmSearchRecordsCriteriaEntryToCriteriaString = zohoSearchRecordsCriteriaEntryToCriteriaString;
 
 /**
@@ -1430,19 +2233,37 @@ class ZohoCrmRecordNoContentError extends makeError.BaseError {
         this.recordId = recordId;
     }
 }
+/**
+ * Base error for Zoho CRM record CRUD operations. Wraps the server-provided error data including field-level details.
+ */
 class ZohoCrmRecordCrudError extends ZohoServerError {
 }
+/**
+ * Thrown when a CRM create/update request is missing a required field defined in the module layout.
+ */
 class ZohoCrmRecordCrudMandatoryFieldNotFoundError extends ZohoCrmRecordCrudError {
 }
+/**
+ * Thrown when a CRM create/update request would produce a duplicate record based on unique field constraints.
+ */
 class ZohoCrmRecordCrudDuplicateDataError extends ZohoCrmRecordCrudError {
 }
+/**
+ * Thrown when a CRM request contains invalid field data. Provides access to the offending field details via {@link invalidFieldDetails}.
+ */
 class ZohoCrmRecordCrudInvalidDataError extends ZohoCrmRecordCrudError {
     get invalidFieldDetails() {
         return this.error.details;
     }
 }
+/**
+ * Thrown when an invalid data error targets the 'id' field, indicating the referenced record does not exist.
+ */
 class ZohoCrmRecordCrudNoMatchingRecordError extends ZohoCrmRecordCrudInvalidDataError {
 }
+/**
+ * Maps a Zoho CRM server error to the appropriate typed {@link ZohoCrmRecordCrudError} subclass based on the error code and affected field.
+ */
 function zohoCrmRecordCrudError(error) {
     let result;
     switch (error.code) {
@@ -1467,6 +2288,9 @@ function zohoCrmRecordCrudError(error) {
     }
     return result;
 }
+/**
+ * Returns an assertion function that throws {@link ZohoCrmRecordNoContentError} when a data array result is empty or null, typically indicating a missing record.
+ */
 function assertZohoCrmRecordDataArrayResultHasContent(moduleName, recordId) {
     return (x) => {
         if (x == null || !x.data?.length) {
@@ -1477,7 +2301,13 @@ function assertZohoCrmRecordDataArrayResultHasContent(moduleName, recordId) {
         }
     };
 }
+/**
+ * Pre-configured console logger for Zoho CRM server errors. Data array errors are suppressed since they are handled separately by CRUD error classes.
+ */
 const logZohoCrmErrorToConsole = logZohoServerErrorFunction('ZohoCrm', { logDataArrayErrors: false });
+/**
+ * Parses a fetch response error into a typed Zoho CRM server error by extracting and interpreting the JSON error body.
+ */
 async function parseZohoCrmError(responseError) {
     const data = await responseError.response.json().catch((x) => undefined);
     let result;
@@ -1486,6 +2316,9 @@ async function parseZohoCrmError(responseError) {
     }
     return result;
 }
+/**
+ * Parses a Zoho CRM error response body into a typed error. Delegates to CRM-specific error code handling before falling back to the generic Zoho error parser.
+ */
 function parseZohoCrmServerErrorResponseData(errorResponseData, responseError) {
     let result;
     const error = tryFindZohoServerErrorData(errorResponseData, responseError);
@@ -1500,7 +2333,13 @@ function parseZohoCrmServerErrorResponseData(errorResponseData, responseError) {
     }
     return result;
 }
+/**
+ * Fetch response interceptor that detects Zoho CRM error payloads hidden within HTTP 200 responses and converts them into proper errors.
+ */
 const interceptZohoCrm200StatusWithErrorResponse = interceptZohoErrorResponseFactory(parseZohoCrmServerErrorResponseData);
+/**
+ * Wraps a fetch function with Zoho CRM error parsing and console logging, ensuring all CRM API errors are surfaced as typed exceptions.
+ */
 const handleZohoCrmErrorFetch = handleZohoErrorFetchFactory(parseZohoCrmError, logZohoCrmErrorToConsole);
 
 // MARK: Insert/Update/Upsert Response
@@ -1511,9 +2350,10 @@ const handleZohoCrmErrorFetch = handleZohoErrorFetchFactory(parseZohoCrmError, l
  */
 const ZOHO_CRM_CRUD_FUNCTION_MAX_RECORDS_LIMIT = 100;
 /**
- * The APIs for Insert, Upsert, and Update have the same structure.
+ * Shared implementation for the Insert, Upsert, and Update endpoints, which all share the same request/response structure.
  *
- * @returns
+ * When a single record is provided, the function returns the change details directly or throws on error.
+ * When multiple records are provided, it returns a paired success/error result.
  */
 function updateRecordLikeFunction(context, fetchUrlPrefix, fetchMethod) {
     return (({ data, module }) => context
@@ -1537,45 +2377,145 @@ function updateRecordLikeFunction(context, fetchUrlPrefix, fetchMethod) {
     }));
 }
 /**
- * Inserts one or more records into Crm.
+ * Creates a {@link ZohoCrmInsertRecordFunction} bound to the given context.
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/insert-records.html
+ * 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.
  *
- * @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 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' }
+ * });
+ *
+ * // 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' }
+ *   ]
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/insert-records.html
  */
 function zohoCrmInsertRecord(context) {
     return updateRecordLikeFunction(context, '', 'POST');
 }
 /**
- * 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
  */
 function zohoCrmUpsertRecord(context) {
     return updateRecordLikeFunction(context, '/upsert', 'POST');
 }
 /**
- * Updates one or more records in Crm.
+ * Creates a {@link ZohoCrmUpdateRecordFunction} bound to the given context.
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/update-records.html
+ * 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.
  *
- * @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 updates records in the specified module
+ *
+ * @example
+ * ```typescript
+ * const updateRecord = zohoCrmUpdateRecord(context);
+ *
+ * // Single record — returns details directly:
+ * const details = await updateRecord({
+ *   module: 'Contacts',
+ *   data: { id: recordId, First_Name: 'Updated Name' }
+ * });
+ *
+ * // 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
  */
 function zohoCrmUpdateRecord(context) {
     return updateRecordLikeFunction(context, '', 'PUT');
 }
 /**
- * Deletes one or more records from the given module.
+ * Creates a {@link ZohoCrmDeleteRecordFunction} bound to the given context.
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/delete-records.html
+ * 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
- * @returns ZohoCrmDeleteRecordFunction
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Function that deletes records from the specified module
+ *
+ * @example
+ * ```typescript
+ * const deleteRecord = zohoCrmDeleteRecord(context);
+ *
+ * const result = await deleteRecord({
+ *   module: 'Contacts',
+ *   ids: contactId
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/delete-records.html
  */
 function zohoCrmDeleteRecord(context) {
     return ({ ids, module, wf_trigger }) => {
@@ -1586,12 +2526,26 @@ function zohoCrmDeleteRecord(context) {
     };
 }
 /**
- * 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
  */
 function zohoCrmGetRecordById(context) {
     return (input) => context
@@ -1600,23 +2554,62 @@ function zohoCrmGetRecordById(context) {
         .then((x) => x.data[0]);
 }
 /**
- * Retrieves records from the given module. Used for paginating across all records.
+ * Creates a {@link ZohoCrmGetRecordsFunction} bound to the given context.
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/get-records.html
+ * 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
- * @returns
+ * @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);
+ *
+ * const page = await getRecords({
+ *   module: 'Contacts',
+ *   fields: 'First_Name,Last_Name,Email',
+ *   per_page: 10
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/get-records.html
  */
 function zohoCrmGetRecords(context) {
     return ((input) => context.fetchJson(`/v8/${input.module}?${zohoCrmUrlSearchParamsMinusModule(input).toString()}`, zohoCrmApiFetchJsonInput('GET')));
 }
 /**
- * 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
  */
 function zohoCrmSearchRecords(context) {
     function searchRecordsUrlSearchParams(input) {
@@ -1634,16 +2627,60 @@ function zohoCrmSearchRecords(context) {
     }
     return ((input) => context.fetchJson(`/v8/${input.module}/search?${searchRecordsUrlSearchParams(input).toString()}`, zohoCrmApiFetchJsonInput('GET')).then((x) => x ?? { data: [], info: { more_records: false } }));
 }
+/**
+ * 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();
+ * ```
+ */
 function zohoCrmSearchRecordsPageFactory(context) {
     return zohoFetchPageFactory(zohoCrmSearchRecords(context));
 }
 /**
- * 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
+ *
+ * @example
+ * ```typescript
+ * const factory = zohoCrmGetRelatedRecordsFunctionFactory(context);
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/get-related-records.html
+ * // Create a typed function for fetching related Notes:
+ * const getNotesForRecord = factory<ZohoCrmRecordNote>({
+ *   targetModule: ZOHO_CRM_NOTES_MODULE
+ * });
  *
- * @param context the ZohoCrmContext to use
- * @returns a ZohoCrmGetRelatedRecordsFunctionFactory
+ * const notes = await getNotesForRecord({
+ *   module: 'Contacts',
+ *   id: contactId
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/get-related-records.html
  */
 function zohoCrmGetRelatedRecordsFunctionFactory(context) {
     return (config) => {
@@ -1651,6 +2688,29 @@ function zohoCrmGetRelatedRecordsFunctionFactory(context) {
         return (input) => context.fetchJson(`/v8/${input.module}/${input.id}/${targetModule}?${zohoCrmUrlSearchParamsMinusIdAndModule(input, input.filter).toString()}`, zohoCrmApiFetchJsonInput('GET')).then((x) => x ?? (returnEmptyRecordsInsteadOfNull !== false ? emptyZohoPageResult() : x));
     };
 }
+/**
+ * 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
+ */
 function zohoCrmGetEmailsForRecord(context) {
     const getEmailsFactory = zohoCrmGetRelatedRecordsFunctionFactory(context)({ targetModule: ZOHO_CRM_EMAILS_MODULE });
     return (input) => getEmailsFactory(input).then((x) => {
@@ -1658,12 +2718,96 @@ function zohoCrmGetEmailsForRecord(context) {
         return { ...x, data };
     });
 }
+/**
+ * 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
+ */
 function zohoCrmGetEmailsForRecordPageFactory(context) {
     return zohoFetchPageFactory(zohoCrmGetEmailsForRecord(context));
 }
+/**
+ * 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
+ */
 function zohoCrmGetAttachmentsForRecord(context) {
     return zohoCrmGetRelatedRecordsFunctionFactory(context)({ targetModule: ZOHO_CRM_ATTACHMENTS_MODULE });
 }
+/**
+ * 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
+ */
 function zohoCrmGetAttachmentsForRecordPageFactory(context) {
     return zohoFetchPageFactory(zohoCrmGetAttachmentsForRecord(context));
 }
@@ -1674,88 +2818,101 @@ function zohoCrmGetAttachmentsForRecordPageFactory(context) {
  */
 const ZOHO_CRM_ATTACHMENT_MAX_SIZE = 20 * 1024 * 1024;
 /**
- * Uploads an attachment to a record.
+ * Creates a {@link ZohoCrmUploadAttachmentForRecordFunction} bound to the given context.
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/upload-attachment.html
+ * 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
- * @returns
+ * @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
+ *
+ * @example
+ * ```typescript
+ * const uploadAttachment = zohoCrmUploadAttachmentForRecord(context);
+ *
+ * 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
  */
 function zohoCrmUploadAttachmentForRecord(context) {
     return (input) => {
-        const { attachmentCategoryId, attachmentCategoryName, formData } = input;
+        const { attachmentCategoryId, attachmentCategoryName, file } = input;
         const urlParams = {
             attachments_category_id: util.joinStringsWithCommas(attachmentCategoryId),
-            attachments_category: util.joinStringsWithCommas(attachmentCategoryName),
-            attachment_url: input.attachmentUrl
+            attachments_category: util.joinStringsWithCommas(attachmentCategoryName)
         };
         if (!urlParams.attachments_category_id?.length && !urlParams.attachments_category?.length) {
             throw new Error('attachmentCategoryId or attachmentCategoryName must be provided and not empty.');
         }
-        if (formData != null) {
-            delete urlParams.attachment_url;
-        }
-        const url = `https://crmsandbox.zoho.com/crm/v8/${input.module}/${input.id}/${ZOHO_CRM_ATTACHMENTS_MODULE}?${fetch.makeUrlSearchParams(urlParams).toString()}`;
-        let response;
-        if (urlParams.attachment_url) {
-            response = context.fetch(url, { method: 'POST' });
-        }
-        else if (formData != null) {
-            throw new Error('unsupported currently. Use the attachmentUrl parameter instead.');
-            // There is something weird going on with sending requests this way and zoho's server is rejecting it.
-            /*
-            response = context.fetch(url, {
-              method: 'POST',
-              headers: {
-                'Content-Type': 'multipart/form-data',
-                'content-length': '210'
-              },
-              body: formData
-            });
-            */
-            /*
-            const fullUrl = (context.config.apiUrl as string) + url;
-            const accessToken = await context.accessTokenStringFactory();
-      
-            response = fetch(fullUrl, {
-              headers: {
-                Authorization: `Bearer ${accessToken}`
-              },
-              body: formData,
-              method: 'POST'
-            });
-      
-            console.log({ response });
-            */
-        }
-        else {
-            throw new Error('body or attachmentUrl must be provided.');
-        }
-        return response;
+        const url = `/v8/${input.module}/${input.id}/${ZOHO_CRM_ATTACHMENTS_MODULE}?${fetch.makeUrlSearchParams(urlParams).toString()}`;
+        const body = new FormData();
+        body.append('file', file);
+        // Clear the base Content-Type header (empty string removes it via mergeRequestHeaders) so fetch auto-detects multipart/form-data with the correct boundary from the FormData body.
+        return context.fetch(url, { method: 'POST', headers: { 'Content-Type': '' }, body });
     };
 }
 /**
- * Downloads an attachment from a record.
+ * Creates a {@link ZohoCrmDownloadAttachmentForRecordFunction} bound to the given context.
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/download-attachments.html
+ * 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
- * @returns
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Function that downloads an attachment by record and attachment ID
+ *
+ * @example
+ * ```typescript
+ * const downloadAttachment = zohoCrmDownloadAttachmentForRecord(context);
+ *
+ * const fileResponse = await downloadAttachment({
+ *   module: 'Contacts',
+ *   id: contactId,
+ *   attachment_id: attachmentId
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/download-attachments.html
  */
 function zohoCrmDownloadAttachmentForRecord(context) {
     return (input) => context.fetch(`/v8/${input.module}/${input.id}/${ZOHO_CRM_ATTACHMENTS_MODULE}/${input.attachment_id}`, { method: 'GET' }).then(fetch.parseFetchFileResponse);
 }
 /**
- * Deletes an attachment from a record.
+ * Creates a {@link ZohoCrmDeleteAttachmentFromRecordFunction} bound to the given context.
  *
- * https://www.zoho.com/crm/developer-guide/apiv2/delete-attachments.html
+ * Deletes a specific attachment from a record by its attachment ID.
+ * Returns the raw {@link Response}.
  *
- * @param context
- * @returns
+ * @param context - Authenticated Zoho CRM context providing fetch and rate limiting
+ * @returns Function that deletes an attachment by record and attachment ID
+ *
+ * @example
+ * ```typescript
+ * const deleteAttachment = zohoCrmDeleteAttachmentFromRecord(context);
+ *
+ * const response = await deleteAttachment({
+ *   module: 'Contacts',
+ *   id: contactId,
+ *   attachment_id: attachmentId
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/crm/developer-guide/apiv2/delete-attachments.html
  */
 function zohoCrmDeleteAttachmentFromRecord(context) {
     return (input) => context.fetch(`/v8/${input.module}/${input.id}/${ZOHO_CRM_ATTACHMENTS_MODULE}/${input.attachment_id}`, { method: 'DELETE' });
 }
+/**
+ * Thrown when a Zoho CRM serverless function returns a non-success response code.
+ */
 class ZohoCrmExecuteRestApiFunctionError extends makeError.BaseError {
     error;
     constructor(error) {
@@ -1764,15 +2921,41 @@ class ZohoCrmExecuteRestApiFunctionError extends makeError.BaseError {
     }
 }
 /**
- * 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'
+ * });
+ * ```
  */
 function zohoCrmExecuteRestApiFunction(context) {
     return (input) => {
@@ -1794,9 +2977,15 @@ function zohoCrmExecuteRestApiFunction(context) {
     };
 }
 // MARK: Util
+/**
+ * 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.
+ */
 function zohoCrmUrlSearchParamsMinusModule(...input) {
     return fetch.makeUrlSearchParams(input, { omitKeys: 'module' });
 }
+/**
+ * Builds URL search params from the input objects, omitting both `id` and `module` keys since they are used in the URL path.
+ */
 function zohoCrmUrlSearchParamsMinusIdAndModule(...input) {
     return fetch.makeUrlSearchParams(input, { omitKeys: ['id', 'module'] });
 }
@@ -1804,6 +2993,9 @@ function zohoCrmUrlSearchParamsMinusIdAndModule(...input) {
  * @deprecated use makeUrlSearchParams instead.
  */
 const zohoCrmUrlSearchParams = fetch.makeUrlSearchParams;
+/**
+ * Constructs the standard FetchJsonInput used by CRM API calls, pairing the HTTP method with an optional body.
+ */
 function zohoCrmApiFetchJsonInput(method, body) {
     const result = {
         method,
@@ -1829,6 +3021,28 @@ function zohoCrmCatchZohoCrmChangeObjectLikeResponseError(e) {
     }
     return result;
 }
+/**
+ * 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
+ * ```
+ */
 function zohoCrmChangeObjectLikeResponseSuccessAndErrorPairs(response) {
     const { data } = response;
     const successItems = [];
@@ -1848,6 +3062,20 @@ function zohoCrmChangeObjectLikeResponseSuccessAndErrorPairs(response) {
     };
     return result;
 }
+/**
+ * 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
+ */
 function zohoCrmMultiRecordResult(input, results) {
     const successItems = [];
     const errorItems = [];
@@ -1873,27 +3101,40 @@ function zohoCrmMultiRecordResult(input, results) {
     return result;
 }
 
+/**
+ * Creates notes directly in the CRM Notes module. Each note must include the parent record reference and module name.
+ *
+ * For creating notes associated with a specific record, prefer {@link zohoCrmCreateNotesForRecord} which handles parent binding automatically.
+ */
 function zohoCrmCreateNotes(context) {
     return (input) => context.fetchJson(`/v2/${ZOHO_CRM_NOTES_MODULE}`, zohoCrmApiFetchJsonInput('POST', { data: input.data })).then((x) => {
         return zohoCrmMultiRecordResult(util.asArray(input.data), x.data);
     });
 }
+/**
+ * Deletes one or more notes from the CRM Notes module by their IDs.
+ */
 function zohoCrmDeleteNotes(context) {
     return (input) => context.fetchJson(`/v2/${ZOHO_CRM_NOTES_MODULE}?${fetch.makeUrlSearchParams({ ids: input.ids })}`, zohoCrmApiFetchJsonInput('DELETE')).then((x) => {
         return zohoCrmMultiRecordResult(util.asArray(input.ids), x.data);
     });
 }
+/**
+ * Retrieves paginated notes associated with a specific CRM record using the related records API.
+ */
 function zohoCrmGetNotesForRecord(context) {
     return zohoCrmGetRelatedRecordsFunctionFactory(context)({ targetModule: ZOHO_CRM_NOTES_MODULE });
 }
+/**
+ * Creates a page factory for iterating through all notes for a record across multiple pages.
+ */
 function zohoCrmGetNotesForRecordPageFactory(context) {
     return zohoFetchPageFactory(zohoCrmGetNotesForRecord(context));
 }
 /**
- * https://www.zoho.com/crm/developer/docs/api/v8/create-notes.html
+ * Creates notes for a specific record, automatically binding the parent module and record ID to each note entry.
  *
- * @param context
- * @returns
+ * https://www.zoho.com/crm/developer/docs/api/v8/create-notes.html
  */
 function zohoCrmCreateNotesForRecord(context) {
     const createNotesInstance = zohoCrmCreateNotes(context);
@@ -1910,6 +3151,9 @@ function zohoCrmCreateNotesForRecord(context) {
     };
 }
 
+/**
+ * Creates one or more tags for a CRM module. Duplicate tag errors are separated from other errors in the result to simplify idempotent workflows.
+ */
 function zohoCrmCreateTagsForModule(context) {
     return (input) => context
         .fetchJson(`/v8/settings/tags?${fetch.makeUrlSearchParams({ module: input.module })}`, zohoCrmApiFetchJsonInput('POST', { tags: util.asArray(input.tags) }))
@@ -1971,12 +3215,15 @@ function zohoCrmGetTagsForModule(context) {
         };
     });
 }
+/**
+ * Creates a page factory for iterating through all tags in a module across multiple pages.
+ */
 function zohoCrmGetTagsForModulePageFactory(context) {
     return zohoFetchPageFactory(zohoCrmGetTagsForModule(context));
 }
 // MARK: Add Tag To Record
 /**
- * Limit enforced by Zoho Crm
+ * Maximum number of record IDs allowed per add-tags request, enforced by Zoho CRM.
  */
 const ZOHO_CRM_ADD_TAGS_TO_RECORDS_MAX_IDS_ALLOWED = 100;
 /**
@@ -1995,6 +3242,9 @@ function zohoCrmAddTagsToRecords(context) {
         });
     };
 }
+/**
+ * Builds the request body for the add/remove tags endpoints, merging `tag_names` into `tags` and enforcing the max ID limit.
+ */
 function zohoCrmAddTagsToRecordsRequestBody(input) {
     if (Array.isArray(input.ids) && input.ids.length > ZOHO_CRM_ADD_TAGS_TO_RECORDS_MAX_IDS_ALLOWED) {
         throw new Error(`Cannot add/remove tags from more than ${ZOHO_CRM_ADD_TAGS_TO_RECORDS_MAX_IDS_ALLOWED} records at once.`);
@@ -2016,7 +3266,7 @@ function zohoCrmAddTagsToRecordsRequestBody(input) {
 }
 // MARK: Remove Tag From Record
 /**
- * Limit enforced by Zoho Crm
+ * Maximum number of record IDs allowed per remove-tags request, enforced by Zoho CRM.
  */
 const ZOHO_CRM_REMOVE_TAGS_FROM_RECORDS_MAX_IDS_ALLOWED = 100;
 /**
@@ -2036,6 +3286,31 @@ function zohoCrmRemoveTagsFromRecords(context) {
     };
 }
 
+/**
+ * Creates a {@link ZohoCrmFactory} from the given configuration.
+ *
+ * The factory pre-initializes shared resources (access token provider, rate limiter)
+ * once, then produces {@link ZohoCrm} client instances for each {@link ZohoCrmConfig}.
+ * Each client handles OAuth token refresh on {@link ZohoInvalidTokenError}, rate limiting,
+ * and Zoho CRM's non-standard error responses (200 status with error body).
+ *
+ * @param factoryConfig - Configuration providing account credentials and optional overrides
+ * @returns A factory function that creates authenticated Zoho CRM clients
+ *
+ * @example
+ * ```typescript
+ * const factory = zohoCrmFactory({
+ *   accountsContext: zohoAccountsApi.accountsContext
+ * });
+ *
+ * const zohoCrm = factory({
+ *   apiUrl: 'https://www.zohoapis.com/crm'
+ * });
+ *
+ * // Use the CRM context for API calls:
+ * const { crmContext } = zohoCrm;
+ * ```
+ */
 function zohoCrmFactory(factoryConfig) {
     const { accountsContext } = factoryConfig;
     const accessTokenStringFactory = zohoAccessTokenStringFactory(accountsContext.loadAccessToken);
@@ -2091,9 +3366,543 @@ function zohoCrmFactory(factoryConfig) {
 const ZOHO_CRM_TAG_NAME_MAX_LENGTH = 25;
 
 /**
- * Trades a refresh token for a new AccessToken
- * @param context
- * @returns
+ * Creates a page factory that wraps a Zoho Sign fetch function with automatic offset-based pagination.
+ *
+ * The factory reads `page_context.has_more_rows` from each response to determine if additional
+ * pages exist, and automatically advances `start_index` by `row_count` for subsequent requests.
+ *
+ * @param fetch - The Zoho Sign fetch function to paginate over
+ * @param defaults - Optional default configuration for the page factory
+ * @returns A page factory that produces iterable page fetchers
+ *
+ * @example
+ * ```typescript
+ * const pageFactory = zohoSignFetchPageFactory(zohoSignGetDocumentsList(context));
+ *
+ * const fetchPage = pageFactory({ row_count: 10 });
+ * const firstPage = await fetchPage.fetchNext();
+ *
+ * if (firstPage.result.page_context.has_more_rows) {
+ *   const secondPage = await firstPage.fetchNext();
+ * }
+ * ```
+ */
+function zohoSignFetchPageFactory(fetch$1, defaults) {
+    return fetch.fetchPageFactory({
+        ...defaults,
+        fetch: fetch$1,
+        readFetchPageResultInfo: function (result) {
+            return {
+                hasNext: result.page_context?.has_more_rows ?? false
+            };
+        },
+        buildInputForNextPage: function (pageResult, input, options) {
+            const previousResult = pageResult.result;
+            const previousPageContext = previousResult?.page_context;
+            const rowCount = options.maxItemsPerPage ?? input.row_count ?? previousPageContext?.row_count ?? 20;
+            const nextStartIndex = (previousPageContext?.start_index ?? input.start_index ?? 1) + rowCount;
+            return { ...input, start_index: nextStartIndex, row_count: rowCount };
+        }
+    });
+}
+
+// MARK: Utility
+/**
+ * Builds a {@link FetchJsonInput} for Zoho Sign API calls.
+ */
+function zohoSignApiFetchJsonInput(method, body) {
+    return {
+        method,
+        body: body ?? undefined
+    };
+}
+/**
+ * Creates a {@link ZohoSignGetDocumentFunction} bound to the given context.
+ *
+ * Fetches the full details of a single Zoho Sign request (envelope) by its ID,
+ * including actions, documents, and field data.
+ *
+ * @param context - Authenticated Zoho Sign context providing fetch and rate limiting
+ * @returns Function that retrieves a document by request ID
+ *
+ * @example
+ * ```typescript
+ * const getDocument = zohoSignGetDocument(context);
+ * const response = await getDocument({ requestId: '12345' });
+ * ```
+ *
+ * @see https://www.zoho.com/sign/api/document-managment/get-details-of-a-particular-document.html
+ */
+function zohoSignGetDocument(context) {
+    return ({ requestId }) => context.fetchJson(`/requests/${requestId}`, zohoSignApiFetchJsonInput('GET'));
+}
+/**
+ * Creates a {@link ZohoSignGetDocumentsFunction} bound to the given context.
+ *
+ * Fetches a paginated list of Zoho Sign requests. Supports sorting via
+ * {@link ZohoSignPageFilter} and filtering via {@link ZohoSignSearchColumns}.
+ * Pagination parameters (`start_index`, `row_count`) are serialized as a
+ * JSON `data` query parameter per the Zoho Sign API convention.
+ *
+ * @param context - Authenticated Zoho Sign context providing fetch and rate limiting
+ * @returns Function that retrieves a paginated list of documents
+ *
+ * @example
+ * ```typescript
+ * const getDocuments = zohoSignGetDocuments(context);
+ * const response = await getDocuments({ start_index: 1, row_count: 10 });
+ * ```
+ *
+ * @see https://www.zoho.com/sign/api/document-managment/get-document-list.html
+ */
+function zohoSignGetDocuments(context) {
+    return (input) => {
+        const { search_columns, ...pageFilter } = input;
+        const data = {
+            page_context: {
+                ...pageFilter,
+                ...(search_columns ? { search_columns } : {})
+            }
+        };
+        return context.fetchJson({
+            url: `/requests`,
+            queryParams: { data: JSON.stringify(data) }
+        }, zohoSignApiFetchJsonInput('GET'));
+    };
+}
+/**
+ * Creates a {@link zohoSignFetchPageFactory} bound to the given context.
+ *
+ * Returns a page factory that automatically handles Zoho Sign's
+ * `start_index`/`row_count` pagination, making it easy to iterate
+ * through all documents across multiple pages.
+ *
+ * @param context - Authenticated Zoho Sign context providing fetch and rate limiting
+ * @returns Page factory for iterating through documents
+ *
+ * @example
+ * ```typescript
+ * const pageFactory = zohoSignGetDocumentsPageFactory(context);
+ * const fetchPage = pageFactory({ row_count: 5 });
+ *
+ * const firstPage = await fetchPage.fetchNext();
+ * const secondPage = await firstPage.fetchNext();
+ * ```
+ */
+function zohoSignGetDocumentsPageFactory(context) {
+    const getDocuments = zohoSignGetDocuments(context);
+    return zohoSignFetchPageFactory(getDocuments);
+}
+/**
+ * Creates a {@link ZohoSignGetDocumentFormDataFunction} bound to the given context.
+ *
+ * Retrieves the filled form field values for a completed document. Only
+ * returns data after all recipients have signed. The response includes
+ * field labels and values grouped by recipient action.
+ *
+ * @param context - Authenticated Zoho Sign context providing fetch and rate limiting
+ * @returns Function that retrieves form data for a completed document
+ *
+ * @example
+ * ```typescript
+ * const getFormData = zohoSignGetDocumentFormData(context);
+ * const response = await getFormData({ requestId: '12345' });
+ * ```
+ *
+ * @see https://www.zoho.com/sign/api/document-managment/get-document-form-data.html
+ */
+function zohoSignGetDocumentFormData(context) {
+    return ({ requestId }) => context.fetchJson(`/requests/${requestId}/fielddata`, zohoSignApiFetchJsonInput('GET'));
+}
+/**
+ * Creates a {@link ZohoSignRetrieveFieldTypesFunction} bound to the given context.
+ *
+ * Retrieves all available field types (e.g. Signature, Textfield, Checkbox)
+ * that can be placed on documents. Useful for dynamically building document
+ * templates or validating field configurations.
+ *
+ * @param context - Authenticated Zoho Sign context providing fetch and rate limiting
+ * @returns Function that retrieves all available field types
+ *
+ * @example
+ * ```typescript
+ * const retrieveFieldTypes = zohoSignRetrieveFieldTypes(context);
+ * const response = await retrieveFieldTypes();
+ * ```
+ *
+ * @see https://www.zoho.com/sign/api/document-managment/retrieve-field-type.html
+ */
+function zohoSignRetrieveFieldTypes(context) {
+    return () => context.fetchJson(`/fieldtypes`, zohoSignApiFetchJsonInput('GET'));
+}
+/**
+ * Creates a {@link ZohoSignDownloadPdfFunction} bound to the given context.
+ *
+ * Downloads the signed PDF document(s) for a completed request. Returns a
+ * raw {@link Response} containing either a PDF (single document) or a ZIP
+ * archive (multiple documents). Supports optional parameters to include the
+ * completion certificate, merge all documents, or provide a password for
+ * protected files.
+ *
+ * @param context - Authenticated Zoho Sign context providing fetch and rate limiting
+ * @returns Function that downloads signed PDFs by request ID
+ *
+ * @example
+ * ```typescript
+ * const downloadPdf = zohoSignDownloadPdf(context);
+ *
+ * // Download signed PDF with completion certificate merged in:
+ * const response = await downloadPdf({
+ *   requestId: '12345',
+ *   with_coc: true,
+ *   merge: true
+ * });
+ *
+ * const blob = await response.blob();
+ * ```
+ *
+ * @see https://www.zoho.com/sign/api/document-managment/download-pdf.html
+ */
+function zohoSignDownloadPdf(context) {
+    return ({ requestId, ...params }) => {
+        const searchParams = fetch.makeUrlSearchParams(params);
+        const queryString = searchParams.toString();
+        const url = `/requests/${requestId}/pdf${queryString ? `?${queryString}` : ''}`;
+        return context.fetch(url, { method: 'GET' });
+    };
+}
+/**
+ * Creates a {@link ZohoSignDownloadCompletionCertificateFunction} bound to the given context.
+ *
+ * Downloads the completion certificate PDF for a finished request. The
+ * certificate contains an audit trail of the signing process including
+ * timestamps and recipient details. Returns a raw {@link Response}.
+ *
+ * @param context - Authenticated Zoho Sign context providing fetch and rate limiting
+ * @returns Function that downloads the completion certificate by request ID
+ *
+ * @example
+ * ```typescript
+ * const downloadCert = zohoSignDownloadCompletionCertificate(context);
+ * const response = await downloadCert({ requestId: '12345' });
+ * const blob = await response.blob();
+ * ```
+ *
+ * @see https://www.zoho.com/sign/api/document-managment/download-completion-certificate.html
+ */
+function zohoSignDownloadCompletionCertificate(context) {
+    return ({ requestId }) => context.fetch(`/requests/${requestId}/completioncertificate`, { method: 'GET' });
+}
+/**
+ * Creates a {@link ZohoSignCreateDocumentFunction} bound to the given context.
+ *
+ * Creates a new document draft in Zoho Sign. The request data and file are
+ * sent as multipart/form-data. The `Content-Type` header is intentionally
+ * cleared so that `fetch` auto-detects the correct multipart boundary from
+ * the {@link FormData} body.
+ *
+ * The created document starts in draft status and must be submitted
+ * separately via {@link zohoSignSendDocumentForSignature}.
+ *
+ * @param context - Authenticated Zoho Sign context providing fetch and rate limiting
+ * @returns Function that creates a new document draft
+ *
+ * @example
+ * ```typescript
+ * const createDocument = zohoSignCreateDocument(context);
+ *
+ * const response = await createDocument({
+ *   requestData: {
+ *     request_name: 'NDA Agreement',
+ *     is_sequential: true,
+ *     actions: [
+ *       {
+ *         action_type: 'SIGN',
+ *         recipient_name: 'Jane Doe',
+ *         recipient_email: 'jane@example.com'
+ *       }
+ *     ]
+ *   },
+ *   file: new File([pdfBuffer], 'nda.pdf', { type: 'application/pdf' })
+ * });
+ *
+ * const draftId = response.requests.request_id;
+ * ```
+ *
+ * @see https://www.zoho.com/sign/api/document-managment/create-document.html
+ */
+function zohoSignCreateDocument(context) {
+    return ({ requestData, file }) => {
+        const body = new FormData();
+        body.append('data', JSON.stringify({ requests: requestData }));
+        body.append('file', file);
+        // Clear the base Content-Type header (empty string removes it via mergeRequestHeaders) so fetch auto-detects multipart/form-data with the correct boundary from the FormData body.
+        return context.fetch(`/requests`, { method: 'POST', headers: { 'Content-Type': '' }, body }).then((response) => response.json());
+    };
+}
+/**
+ * Creates a {@link ZohoSignUpdateDocumentFunction} bound to the given context.
+ *
+ * Updates an existing document that is still in draft status. Accepts partial
+ * {@link ZohoSignRequestData} to modify fields such as actions, notes, or
+ * expiration settings. Cannot be used on documents that have already been
+ * submitted for signature.
+ *
+ * @param context - Authenticated Zoho Sign context providing fetch and rate limiting
+ * @returns Function that updates a draft document by request ID
+ *
+ * @example
+ * ```typescript
+ * const updateDocument = zohoSignUpdateDocument(context);
+ *
+ * await updateDocument({
+ *   requestId: '12345',
+ *   data: { notes: 'Updated notes for this document' }
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/sign/api/document-managment/update-document.html
+ */
+function zohoSignUpdateDocument(context) {
+    return ({ requestId, data }) => context.fetchJson(`/requests/${requestId}`, zohoSignApiFetchJsonInput('PUT', { requests: data }));
+}
+/**
+ * Creates a {@link ZohoSignSendDocumentForSignatureFunction} bound to the given context.
+ *
+ * Submits a draft document to its recipients for signing. Optionally accepts
+ * partial {@link ZohoSignRequestData} to apply last-minute updates before
+ * submission. Once submitted, the document transitions from draft to
+ * "inprogress" status and recipients receive signing notifications.
+ *
+ * @param context - Authenticated Zoho Sign context providing fetch and rate limiting
+ * @returns Function that sends a document for signature by request ID
+ *
+ * @example
+ * ```typescript
+ * const sendForSignature = zohoSignSendDocumentForSignature(context);
+ *
+ * // Submit a draft for signing:
+ * await sendForSignature({ requestId: '12345' });
+ *
+ * // Submit with last-minute updates:
+ * await sendForSignature({
+ *   requestId: '12345',
+ *   data: { expiration_days: 30 }
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/sign/api/document-managment/send-document-for-signature.html
+ */
+function zohoSignSendDocumentForSignature(context) {
+    return ({ requestId, data }) => {
+        const body = data ? { requests: data } : undefined;
+        return context.fetchJson(`/requests/${requestId}/submit`, zohoSignApiFetchJsonInput('POST', body));
+    };
+}
+/**
+ * Creates a {@link ZohoSignExtendDocumentFunction} bound to the given context.
+ *
+ * Extends the expiration date of an in-progress document. The new date is
+ * provided as a human-readable string (e.g. "30 November 2024"). Useful for
+ * giving recipients additional time to complete signing.
+ *
+ * @param context - Authenticated Zoho Sign context providing fetch and rate limiting
+ * @returns Function that extends a document's expiration by request ID
+ *
+ * @example
+ * ```typescript
+ * const extendDocument = zohoSignExtendDocument(context);
+ * await extendDocument({ requestId: '12345', expire_by: '30 November 2024' });
+ * ```
+ *
+ * @see https://www.zoho.com/sign/api/document-managment/extend-document.html
+ */
+function zohoSignExtendDocument(context) {
+    return ({ requestId, expire_by }) => context.fetchJson(`/requests/${requestId}/extend`, zohoSignApiFetchJsonInput('PUT', { expire_by }));
+}
+/**
+ * Creates a {@link ZohoSignDeleteDocumentFunction} bound to the given context.
+ *
+ * Deletes a document from Zoho Sign. For documents that are currently
+ * in-progress, set `recall_inprogress` to `true` to recall the document
+ * from recipients before deletion. An optional `reason` can be provided
+ * to explain the recall. Sends the parameters as URL-encoded form data.
+ *
+ * @param context - Authenticated Zoho Sign context providing fetch and rate limiting
+ * @returns Function that deletes a document by request ID
+ *
+ * @example
+ * ```typescript
+ * const deleteDocument = zohoSignDeleteDocument(context);
+ *
+ * // Delete a draft:
+ * await deleteDocument({ requestId: '12345' });
+ *
+ * // Recall an in-progress document before deleting:
+ * await deleteDocument({
+ *   requestId: '12345',
+ *   recall_inprogress: true,
+ *   reason: 'Contract terms changed'
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/sign/api/document-managment/delete-document.html
+ */
+function zohoSignDeleteDocument(context) {
+    return ({ requestId, recall_inprogress, reason }) => {
+        const params = {};
+        if (recall_inprogress != null) {
+            params['recall_inprogress'] = String(recall_inprogress);
+        }
+        if (reason != null) {
+            params['reason'] = reason;
+        }
+        const form = fetch.makeUrlSearchParams(params);
+        const hasForm = form.toString().length > 0;
+        return context.fetchJson(`/requests/${requestId}/delete`, {
+            method: 'PUT',
+            ...(hasForm ? { headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: form.toString() } : {})
+        });
+    };
+}
+
+const ZOHO_SIGN_SERVICE_NAME = 'sign';
+function zohoSignConfigApiUrl(input) {
+    switch (input) {
+        case 'sandbox':
+            return 'https://signsandbox.zoho.com/api/v1';
+        case 'production':
+            return 'https://sign.zoho.com/api/v1';
+        default:
+            return input;
+    }
+}
+
+const logZohoSignErrorToConsole = logZohoServerErrorFunction('ZohoSign', { logDataArrayErrors: false });
+async function parseZohoSignError(responseError) {
+    const data = await responseError.response.json().catch(() => undefined);
+    let result;
+    if (data) {
+        result = parseZohoSignServerErrorResponseData(data, responseError);
+    }
+    return result;
+}
+function parseZohoSignServerErrorResponseData(errorResponseData, responseError) {
+    let result;
+    const error = tryFindZohoServerErrorData(errorResponseData, responseError);
+    if (error) {
+        const errorData = zohoServerErrorData(error);
+        switch (errorData.code) {
+            // TODO: Add sign-specific error codes here.
+            default:
+                result = parseZohoServerErrorResponseData(errorResponseData, responseError);
+                break;
+        }
+    }
+    return result;
+}
+const interceptZohoSign200StatusWithErrorResponse = interceptZohoErrorResponseFactory(parseZohoSignServerErrorResponseData);
+const handleZohoSignErrorFetch = handleZohoErrorFetchFactory(parseZohoSignError, logZohoSignErrorToConsole);
+
+/**
+ * Creates a {@link ZohoSignFactory} from the given configuration.
+ *
+ * The factory pre-initializes shared resources (access token provider, rate limiter)
+ * once, then produces {@link ZohoSign} client instances for each {@link ZohoSignConfig}.
+ * Each client handles OAuth token refresh on {@link ZohoInvalidTokenError}, rate limiting,
+ * and Zoho Sign's non-standard error responses (200 status with error body).
+ *
+ * @param factoryConfig - Configuration providing account credentials and optional overrides
+ * @returns A factory function that creates authenticated Zoho Sign clients
+ *
+ * @example
+ * ```typescript
+ * const factory = zohoSignFactory({
+ *   accountsContext: zohoAccountsApi.accountsContext
+ * });
+ *
+ * const zohoSign = factory({
+ *   apiUrl: 'https://sign.zoho.com'
+ * });
+ *
+ * // Use the sign context for API calls:
+ * const { signContext } = zohoSign;
+ * ```
+ */
+function zohoSignFactory(factoryConfig) {
+    const { accountsContext } = factoryConfig;
+    const accessTokenStringFactory = zohoAccessTokenStringFactory(accountsContext.loadAccessToken);
+    const fetchHandler = zohoRateLimitedFetchHandler(factoryConfig.rateLimiterConfig);
+    const { logZohoServerErrorFunction, fetchFactory = (input) => fetch.fetchApiFetchService.makeFetch({
+        baseUrl: input.apiUrl,
+        baseRequest: async () => ({
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${await accessTokenStringFactory()}`
+            }
+        }),
+        fetchHandler,
+        timeout: 20 * 1000, // 20 second timeout
+        requireOkResponse: true, // enforce ok response
+        useTimeout: true // use timeout
+    }) } = factoryConfig;
+    return (config) => {
+        if (!config.apiUrl) {
+            throw new Error('ZohoConfig missing api url.');
+        }
+        const apiUrl = zohoSignConfigApiUrl(config.apiUrl);
+        const baseFetch = fetchFactory({ apiUrl });
+        const fetch$1 = handleZohoSignErrorFetch(baseFetch, logZohoServerErrorFunction, (x) => {
+            if (x instanceof ZohoInvalidTokenError) {
+                accountsContext.loadAccessToken.resetAccessToken();
+            }
+        });
+        const fetchJson = fetch.fetchJsonFunction(fetch$1, {
+            interceptJsonResponse: interceptZohoSign200StatusWithErrorResponse, // intercept errors that return status 200
+            handleFetchJsonParseErrorFunction: fetch.returnNullHandleFetchJsonParseErrorFunction
+        });
+        const signContext = {
+            fetch: fetch$1,
+            fetchJson,
+            accessTokenStringFactory,
+            config: {
+                ...config,
+                apiUrl
+            },
+            zohoRateLimiter: fetchHandler._rateLimiter
+        };
+        const zohoSign = {
+            signContext
+        };
+        return zohoSign;
+    };
+}
+
+/**
+ * Creates a function that exchanges a refresh token for a new short-lived access token
+ * via the Zoho OAuth `/oauth/v2/token` endpoint.
+ *
+ * The returned function accepts optional overrides for client credentials and refresh token.
+ * When omitted, values are read from the {@link ZohoAccountsContext}'s config.
+ *
+ * @param context - Authenticated Zoho Accounts context providing fetch and config
+ * @returns Function that exchanges a refresh token for an access token
+ *
+ * @example
+ * ```typescript
+ * const getAccessToken = zohoAccountsAccessToken(accountsContext);
+ *
+ * // Using config defaults:
+ * const { access_token, expires_in } = await getAccessToken();
+ *
+ * // With overrides:
+ * const response = await getAccessToken({
+ *   client: { clientId: 'other-id', clientSecret: 'other-secret' },
+ *   refreshToken: 'other-refresh-token'
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/accounts/protocol/oauth/web-apps/access-token-expiry.html
  */
 function zohoAccountsAccessToken(context) {
     return (input) => {
@@ -2102,9 +3911,62 @@ function zohoAccountsAccessToken(context) {
         const clientId = client?.clientId ?? configClientId;
         const clientSecret = client?.clientSecret ?? configClientSecret;
         const refreshToken = inputRefreshToken ?? configRefreshToken;
-        return context.fetchJson(`/oauth/v2/token?grant_type=refresh_token&client_id=${clientId}&client_secret=${clientSecret}&refresh_token=${refreshToken}`, zohoAccountsApiFetchJsonInput('POST'));
+        const params = fetch.makeUrlSearchParams({
+            grant_type: 'refresh_token',
+            client_id: clientId,
+            client_secret: clientSecret,
+            refresh_token: refreshToken
+        });
+        return context.fetchJson(`/oauth/v2/token?${params}`, zohoAccountsApiFetchJsonInput('POST'));
     };
 }
+/**
+ * Creates a function that exchanges a single-use OAuth authorization code for
+ * an access token and (optionally) a long-lived refresh token via the Zoho
+ * `/oauth/v2/token` endpoint with `grant_type=authorization_code`.
+ *
+ * This is the second step of the Zoho OAuth 2.0 web server flow:
+ * 1. Redirect the user to Zoho's consent page to obtain an authorization code
+ * 2. Exchange the authorization code for tokens using this function
+ * 3. Use the refresh token with {@link zohoAccountsAccessToken} to obtain new access tokens
+ *
+ * The refresh token is only returned if `access_type=offline` was passed during
+ * the initial authorization request.
+ *
+ * @param context - Zoho Accounts context providing fetch and config (clientId/clientSecret)
+ * @returns Function that exchanges an authorization code for tokens
+ *
+ * @example
+ * ```typescript
+ * const exchangeCode = zohoAccountsRefreshTokenFromAuthorizationCode(accountsContext);
+ *
+ * const { access_token, refresh_token } = await exchangeCode({
+ *   code: '1000.abc123.def456',
+ *   redirectUri: 'https://myapp.example.com/oauth/callback'
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/accounts/protocol/oauth/web-apps/access-token.html
+ */
+function zohoAccountsRefreshTokenFromAuthorizationCode(context) {
+    return (input) => {
+        const { clientId: configClientId, clientSecret: configClientSecret } = context.config;
+        const { client, code, redirectUri } = input;
+        const clientId = client?.clientId ?? configClientId;
+        const clientSecret = client?.clientSecret ?? configClientSecret;
+        const params = fetch.makeUrlSearchParams({
+            grant_type: 'authorization_code',
+            client_id: clientId,
+            client_secret: clientSecret,
+            code,
+            redirect_uri: redirectUri
+        });
+        return context.fetchJson(`/oauth/v2/token?${params}`, zohoAccountsApiFetchJsonInput('POST'));
+    };
+}
+/**
+ * Constructs a standard {@link FetchJsonInput} for Zoho Accounts API calls with the given HTTP method and optional body.
+ */
 function zohoAccountsApiFetchJsonInput(method, body) {
     const result = {
         method,
@@ -2126,6 +3988,38 @@ function zohoAccountsConfigApiUrl(input) {
     }
 }
 
+/**
+ * Creates a {@link ZohoAccountsFactory} from the given configuration.
+ *
+ * The factory pre-initializes shared resources (rate limiter) once, then produces
+ * {@link ZohoAccounts} client instances for each {@link ZohoAccountsConfig}. Each client
+ * handles OAuth token refresh via the configured `refreshToken`, `clientId`, and `clientSecret`,
+ * with in-memory caching and optional external {@link ZohoAccessTokenCache} support.
+ *
+ * The Accounts client is the foundation for CRM, Recruit, and Sign clients, as it provides
+ * the {@link ZohoAccountsContext} needed for OAuth token management.
+ *
+ * @param factoryConfig - Configuration providing optional fetch and logging overrides
+ * @returns A factory function that creates authenticated Zoho Accounts clients
+ * @throws {Error} If `refreshToken`, `clientId`, or `clientSecret` are missing from the config
+ *
+ * @example
+ * ```typescript
+ * const factory = zohoAccountsFactory({});
+ *
+ * const zohoAccounts = factory({
+ *   refreshToken: 'your-refresh-token',
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   apiUrl: 'us'
+ * });
+ *
+ * // Pass the accounts context to CRM/Recruit/Sign factories:
+ * const crmFactory = zohoCrmFactory({
+ *   accountsContext: zohoAccounts.accountsContext
+ * });
+ * ```
+ */
 function zohoAccountsFactory(factoryConfig) {
     const fetchHandler = zohoRateLimitedFetchHandler();
     const { logZohoServerErrorFunction, fetchFactory = (input) => fetch.fetchApiFetchService.makeFetch({
@@ -2192,10 +4086,20 @@ function zohoAccountsFactory(factoryConfig) {
     };
 }
 /**
- * Creates a ZohoAccountsZohoAccessTokenFactoryConfig
+ * Creates a {@link ZohoAccessTokenFactory} that manages access token lifecycle with
+ * in-memory caching, optional external cache support, and automatic refresh.
  *
- * @param config
- * @returns
+ * Token resolution order:
+ * 1. Return the in-memory cached token if valid (not expired within the buffer)
+ * 2. Load from the external {@link ZohoAccessTokenCache} if available
+ * 3. Fetch a fresh token via the {@link ZohoAccessTokenRefresher}
+ *
+ * The returned function also exposes a `resetAccessToken()` method to invalidate
+ * the current cached token, typically called on {@link ZohoInvalidTokenError}.
+ *
+ * @param config - Token refresh, caching, and expiration buffer configuration
+ * @returns A token factory function with `resetAccessToken` for cache invalidation
+ * @throws {ZohoAccountsAuthFailureError} If the token refresher fails
  */
 function zohoAccountsZohoAccessTokenFactory(config) {
     const { tokenRefresher, accessTokenCache, tokenExpirationBuffer: inputTokenExpirationBuffer } = config;
@@ -2250,10 +4154,17 @@ function safeZohoDateTimeString(date) {
     return date != null ? zohoDateTimeString(date) : date;
 }
 /**
- * Converts the input date to a Zoho date.
+ * Converts a {@link Date} to a {@link ZohoDateTimeString} by stripping milliseconds
+ * from the ISO 8601 representation.
  *
- * @param date
- * @returns
+ * @param date - Date to convert
+ * @returns Zoho-formatted date-time string (e.g. `'2019-05-02T11:17:33Z'`)
+ *
+ * @example
+ * ```typescript
+ * zohoDateTimeString(new Date('2019-05-02T11:17:33.000Z'));
+ * // => '2019-05-02T11:17:33Z'
+ * ```
  */
 function zohoDateTimeString(date) {
     const isoDate = date.toISOString();
@@ -2308,6 +4219,7 @@ exports.ZOHO_RECRUIT_RECORD_ATTACHMENT_METADATA_ATTACH_TYPE_RESUME = ZOHO_RECRUI
 exports.ZOHO_RECRUIT_REMOVE_TAGS_FROM_RECORDS_MAX_IDS_ALLOWED = ZOHO_RECRUIT_REMOVE_TAGS_FROM_RECORDS_MAX_IDS_ALLOWED;
 exports.ZOHO_RECRUIT_SERVICE_NAME = ZOHO_RECRUIT_SERVICE_NAME;
 exports.ZOHO_RECRUIT_TAG_NAME_MAX_LENGTH = ZOHO_RECRUIT_TAG_NAME_MAX_LENGTH;
+exports.ZOHO_SIGN_SERVICE_NAME = ZOHO_SIGN_SERVICE_NAME;
 exports.ZOHO_SUCCESS_CODE = ZOHO_SUCCESS_CODE;
 exports.ZOHO_SUCCESS_STATUS = ZOHO_SUCCESS_STATUS;
 exports.ZOHO_TOO_MANY_REQUESTS_ERROR_CODE = ZOHO_TOO_MANY_REQUESTS_ERROR_CODE;
@@ -2365,11 +4277,13 @@ exports.handleZohoAccountsErrorFetch = handleZohoAccountsErrorFetch;
 exports.handleZohoCrmErrorFetch = handleZohoCrmErrorFetch;
 exports.handleZohoErrorFetchFactory = handleZohoErrorFetchFactory;
 exports.handleZohoRecruitErrorFetch = handleZohoRecruitErrorFetch;
+exports.handleZohoSignErrorFetch = handleZohoSignErrorFetch;
 exports.insertRecord = insertRecord;
 exports.interceptZohoAccounts200StatusWithErrorResponse = interceptZohoAccounts200StatusWithErrorResponse;
 exports.interceptZohoCrm200StatusWithErrorResponse = interceptZohoCrm200StatusWithErrorResponse;
 exports.interceptZohoErrorResponseFactory = interceptZohoErrorResponseFactory;
 exports.interceptZohoRecruit200StatusWithErrorResponse = interceptZohoRecruit200StatusWithErrorResponse;
+exports.interceptZohoSign200StatusWithErrorResponse = interceptZohoSign200StatusWithErrorResponse;
 exports.isZohoCrmValidUrl = isZohoCrmValidUrl;
 exports.isZohoRecruitValidUrl = isZohoRecruitValidUrl;
 exports.isZohoServerErrorResponseDataArrayRef = isZohoServerErrorResponseDataArrayRef;
@@ -2377,6 +4291,7 @@ exports.logZohoAccountsErrorToConsole = logZohoAccountsErrorToConsole;
 exports.logZohoCrmErrorToConsole = logZohoCrmErrorToConsole;
 exports.logZohoRecruitErrorToConsole = logZohoRecruitErrorToConsole;
 exports.logZohoServerErrorFunction = logZohoServerErrorFunction;
+exports.logZohoSignErrorToConsole = logZohoSignErrorToConsole;
 exports.parseZohoAccountsError = parseZohoAccountsError;
 exports.parseZohoAccountsServerErrorResponseData = parseZohoAccountsServerErrorResponseData;
 exports.parseZohoCrmError = parseZohoCrmError;
@@ -2384,6 +4299,8 @@ exports.parseZohoCrmServerErrorResponseData = parseZohoCrmServerErrorResponseDat
 exports.parseZohoRecruitError = parseZohoRecruitError;
 exports.parseZohoRecruitServerErrorResponseData = parseZohoRecruitServerErrorResponseData;
 exports.parseZohoServerErrorResponseData = parseZohoServerErrorResponseData;
+exports.parseZohoSignError = parseZohoSignError;
+exports.parseZohoSignServerErrorResponseData = parseZohoSignServerErrorResponseData;
 exports.removeTagsFromRecords = removeTagsFromRecords;
 exports.safeZohoDateTimeString = safeZohoDateTimeString;
 exports.searchRecords = searchRecords;
@@ -2397,6 +4314,7 @@ exports.zohoAccountsAccessToken = zohoAccountsAccessToken;
 exports.zohoAccountsApiFetchJsonInput = zohoAccountsApiFetchJsonInput;
 exports.zohoAccountsConfigApiUrl = zohoAccountsConfigApiUrl;
 exports.zohoAccountsFactory = zohoAccountsFactory;
+exports.zohoAccountsRefreshTokenFromAuthorizationCode = zohoAccountsRefreshTokenFromAuthorizationCode;
 exports.zohoAccountsZohoAccessTokenFactory = zohoAccountsZohoAccessTokenFactory;
 exports.zohoCrmAddTagsToRecords = zohoCrmAddTagsToRecords;
 exports.zohoCrmAddTagsToRecordsRequestBody = zohoCrmAddTagsToRecordsRequestBody;
@@ -2490,3 +4408,18 @@ exports.zohoRecruitUrlSearchParams = zohoRecruitUrlSearchParams;
 exports.zohoRecruitUrlSearchParamsMinusIdAndModule = zohoRecruitUrlSearchParamsMinusIdAndModule;
 exports.zohoRecruitUrlSearchParamsMinusModule = zohoRecruitUrlSearchParamsMinusModule;
 exports.zohoServerErrorData = zohoServerErrorData;
+exports.zohoSignConfigApiUrl = zohoSignConfigApiUrl;
+exports.zohoSignCreateDocument = zohoSignCreateDocument;
+exports.zohoSignDeleteDocument = zohoSignDeleteDocument;
+exports.zohoSignDownloadCompletionCertificate = zohoSignDownloadCompletionCertificate;
+exports.zohoSignDownloadPdf = zohoSignDownloadPdf;
+exports.zohoSignExtendDocument = zohoSignExtendDocument;
+exports.zohoSignFactory = zohoSignFactory;
+exports.zohoSignFetchPageFactory = zohoSignFetchPageFactory;
+exports.zohoSignGetDocument = zohoSignGetDocument;
+exports.zohoSignGetDocumentFormData = zohoSignGetDocumentFormData;
+exports.zohoSignGetDocuments = zohoSignGetDocuments;
+exports.zohoSignGetDocumentsPageFactory = zohoSignGetDocumentsPageFactory;
+exports.zohoSignRetrieveFieldTypes = zohoSignRetrieveFieldTypes;
+exports.zohoSignSendDocumentForSignature = zohoSignSendDocumentForSignature;
+exports.zohoSignUpdateDocument = zohoSignUpdateDocument;