@dereekb/zoho 13.0.5 → 13.0.7

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

@@ -13,115 +13,311 @@ import { BaseError } from 'make-error';
  * This is a limit enforced by the Zoho Recruit API
  */
 export declare const ZOHO_RECRUIT_CRUD_FUNCTION_MAX_RECORDS_LIMIT = 100;
+/**
+ * Paired success/error result from a bulk record update, upsert, or insert operation.
+ */
 export type ZohoRecruitUpdateRecordResult<T> = ZohoRecruitMultiRecordResult<T, ZohoRecruitChangeObjectResponseSuccessEntry, ZohoRecruitChangeObjectResponseErrorEntry>;
+/**
+ * Raw API response from record change operations (insert/update/upsert).
+ */
 export type ZohoRecruitUpdateRecordResponse = ZohoRecruitChangeObjectResponse;
+/**
+ * Record data with the `id` field omitted, used for creating new records.
+ */
 export type ZohoRecruitCreateRecordData<T> = Omit<T, 'id'>;
+/**
+ * Input for inserting a single record into a module.
+ */
 export interface ZohoRecruitCreateSingleRecordInput<T> extends ZohoRecruitModuleNameRef {
     readonly data: ZohoRecruitCreateRecordData<T>;
 }
+/**
+ * Input for inserting multiple records into a module in a single API call.
+ */
 export interface ZohoRecruitCreateMultiRecordInput<T> extends ZohoRecruitModuleNameRef {
     readonly data: ZohoRecruitCreateRecordData<T>[];
 }
+/**
+ * Overloaded function signature supporting both single and multi-record creation.
+ */
 export type ZohoRecruitCreateRecordLikeFunction = ZohoRecruitCreateMultiRecordFunction & ZohoRecruitCreateSingleRecordFunction;
 export type ZohoRecruitCreateSingleRecordFunction = <T>(input: ZohoRecruitCreateSingleRecordInput<T>) => Promise<ZohoRecruitChangeObjectDetails>;
 export type ZohoRecruitCreateMultiRecordFunction = <T>(input: ZohoRecruitCreateMultiRecordInput<T>) => Promise<ZohoRecruitUpdateRecordResult<T>>;
+/**
+ * Union of single or multi-record update input types.
+ */
 export type ZohoRecruitUpdateRecordInput<T> = ZohoRecruitUpdateSingleRecordInput<T> | ZohoRecruitUpdateMultiRecordInput<T>;
+/**
+ * Record data that requires an `id` field for identifying which record to update.
+ */
 export type ZohoRecruitUpdateRecordData<T> = UniqueModelWithId & Partial<T>;
+/**
+ * Input for updating a single record in a module.
+ */
 export interface ZohoRecruitUpdateSingleRecordInput<T> extends ZohoRecruitModuleNameRef {
     readonly data: ZohoRecruitUpdateRecordData<T>;
 }
+/**
+ * Input for updating multiple records in a module in a single API call.
+ */
 export interface ZohoRecruitUpdateMultiRecordInput<T> extends ZohoRecruitModuleNameRef {
     readonly data: ZohoRecruitUpdateRecordData<T>[];
 }
+/**
+ * Overloaded function signature supporting both single and multi-record updates.
+ */
 export type ZohoRecruitUpdateRecordLikeFunction = ZohoRecruitUpdateMultiRecordFunction & ZohoRecruitUpdateSingleRecordFunction;
 export type ZohoRecruitUpdateMultiRecordFunction = <T>(input: ZohoRecruitUpdateMultiRecordInput<T>) => Promise<ZohoRecruitUpdateRecordResult<T>>;
 export type ZohoRecruitUpdateSingleRecordFunction = <T>(input: ZohoRecruitUpdateSingleRecordInput<T>) => Promise<ZohoRecruitChangeObjectDetails>;
+/**
+ * Record data that may or may not include an `id`, allowing either insert or update semantics.
+ */
 export type ZohoRecruitUpsertRecordData<T> = ZohoRecruitCreateRecordData<T> | ZohoRecruitUpdateRecordData<T>;
+/**
+ * Input for upserting a single record in a module.
+ */
 export interface ZohoRecruitUpsertSingleRecordInput<T> extends ZohoRecruitModuleNameRef {
     readonly data: ZohoRecruitUpsertRecordData<T>;
 }
+/**
+ * Input for upserting multiple records in a module in a single API call.
+ */
 export interface ZohoRecruitUpsertMultiRecordInput<T> extends ZohoRecruitModuleNameRef {
     readonly data: ZohoRecruitUpsertRecordData<T>[];
 }
+/**
+ * Overloaded function signature supporting both single and multi-record upserts.
+ */
 export type ZohoRecruitUpsertRecordLikeFunction = ZohoRecruitUpsertMultiRecordFunction & ZohoRecruitUpsertSingleRecordFunction;
 export type ZohoRecruitUpsertMultiRecordFunction = <T>(input: ZohoRecruitUpsertMultiRecordInput<T>) => Promise<ZohoRecruitUpdateRecordResult<T>>;
 export type ZohoRecruitUpsertSingleRecordFunction = <T>(input: ZohoRecruitUpsertSingleRecordInput<T>) => Promise<ZohoRecruitChangeObjectDetails>;
 export type ZohoRecruitInsertRecordFunction = ZohoRecruitCreateRecordLikeFunction;
 /**
- * Inserts one or more records into Recruit.
+ * Creates a {@link ZohoRecruitInsertRecordFunction} bound to the given context.
+ *
+ * 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.
+ *
+ * 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
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/insert-records.html
+ * @example
+ * ```typescript
+ * const insertRecord = zohoRecruitInsertRecord(context);
  *
- * @param context
- * @returns
+ * // 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
  */
 export declare function zohoRecruitInsertRecord(context: ZohoRecruitContext): ZohoRecruitInsertRecordFunction;
 /**
- * Upsert function that can do either an insert or and update ased on the input.
+ * Upsert function that can do either an insert or an update based on the input.
  */
 export type ZohoRecruitUpsertRecordFunction = ZohoRecruitUpsertRecordLikeFunction;
 /**
- * Updates or inserts one or more records in Recruit.
+ * Creates a {@link ZohoRecruitUpsertRecordFunction} bound to the given context.
+ *
+ * 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.
+ *
+ * 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' }
+ * });
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/upsert-records.html
+ * // 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' }
+ *   ]
+ * });
+ * ```
  *
- * @param context
- * @returns
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/upsert-records.html
  */
 export declare function zohoRecruitUpsertRecord(context: ZohoRecruitContext): ZohoRecruitUpsertRecordFunction;
 export type ZohoRecruitUpdateRecordFunction = ZohoRecruitUpdateRecordLikeFunction;
 /**
- * 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
  */
 export declare function zohoRecruitUpdateRecord(context: ZohoRecruitContext): ZohoRecruitUpdateRecordFunction;
+/**
+ * Function that deletes one or more records from a module.
+ */
 export type ZohoRecruitDeleteRecordFunction = (input: ZohoRecruitDeleteRecordInput) => Promise<ZohoRecruitDeleteRecordResponse>;
+/**
+ * Input for deleting records from a module.
+ */
 export interface ZohoRecruitDeleteRecordInput extends ZohoRecruitModuleNameRef {
     /**
      * Id or array of ids to delete.
      */
     readonly ids: ArrayOrValue<ZohoRecruitRecordId>;
+    /**
+     * Whether to trigger workflow rules on deletion.
+     */
     readonly wf_trigger?: boolean;
 }
+/**
+ * Successful deletion entry containing the deleted record's id.
+ */
 export interface ZohoRecruitDeleteRecordResponseSuccessEntry extends ZohoRecruitChangeObjectLikeResponseSuccessEntryMeta {
     readonly details: {
         readonly id: ZohoRecruitRecordId;
     };
 }
+/**
+ * Response from a delete operation, with entries pre-separated into `successItems` and `errorItems`.
+ */
 export type ZohoRecruitDeleteRecordResponse = ZohoRecruitChangeObjectLikeResponseSuccessAndErrorPairs<ZohoRecruitDeleteRecordResponseSuccessEntry>;
+/**
+ * Array of successful deletion entries extracted from a delete response.
+ */
 export type ZohoRecruitDeleteRecordResult = ZohoRecruitChangeObjectResponseSuccessEntry[];
 /**
- * Deletes one or more records from the given module.
+ * Creates a {@link ZohoRecruitDeleteRecordFunction} bound to the given context.
+ *
+ * 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 - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that deletes records from the specified module
+ *
+ * @example
+ * ```typescript
+ * const deleteRecord = zohoRecruitDeleteRecord(context);
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/delete-records.html
+ * const result = await deleteRecord({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   ids: candidateId
+ * });
+ * ```
  *
- * @param context
- * @returns ZohoRecruitDeleteRecordFunction
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/delete-records.html
  */
 export declare function zohoRecruitDeleteRecord(context: ZohoRecruitContext): ZohoRecruitDeleteRecordFunction;
+/**
+ * Input identifying a specific record within a module.
+ */
 export interface ZohoRecruitGetRecordByIdInput extends ZohoRecruitModuleNameRef {
     readonly id: ZohoRecruitRecordId;
 }
+/**
+ * Raw API response wrapping a single record in a data array.
+ */
 export type ZohoRecruitGetRecordByIdResponse<T = ZohoRecruitRecord> = ZohoDataArrayResultRef<T>;
+/**
+ * Unwrapped record returned by {@link ZohoRecruitGetRecordByIdFunction}.
+ */
 export type ZohoRecruitGetRecordByIdResult<T = ZohoRecruitRecord> = T;
+/**
+ * Retrieves a single record from a Recruit module by its ID.
+ * Throws {@link ZohoRecruitRecordNoContentError} if the record is not found.
+ */
 export type ZohoRecruitGetRecordByIdFunction = <T = ZohoRecruitRecord>(input: ZohoRecruitGetRecordByIdInput) => Promise<ZohoRecruitGetRecordByIdResult<T>>;
 /**
- * Retrieves a specific record from the given module.
+ * Creates a {@link ZohoRecruitGetRecordByIdFunction} bound to the given context.
+ *
+ * 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.
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/get-records.html
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that retrieves a record by module name and ID
  *
- * @param context
- * @returns
+ * @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
  */
 export declare function zohoRecruitGetRecordById(context: ZohoRecruitContext): ZohoRecruitGetRecordByIdFunction;
+/**
+ * Filter options for listing records, extending pagination with conversion and approval status filters.
+ */
 export interface ZohoRecruitGetRecordsPageFilter extends ZohoPageFilter {
     readonly converted?: ZohoRecruitTrueFalseBoth;
     readonly approved?: ZohoRecruitTrueFalseBoth;
 }
+/**
+ * Input for fetching records from a module, supporting field selection, sorting, pagination, and view filters.
+ */
 export interface ZohoRecruitGetRecordsInput extends ZohoRecruitModuleNameRef, ZohoRecruitGetRecordsPageFilter {
     readonly fields?: ZohoRecruitCommaSeparateFieldNames;
     readonly sort_order?: SortingOrder;
@@ -131,15 +327,35 @@ export interface ZohoRecruitGetRecordsInput extends ZohoRecruitModuleNameRef, Zo
     readonly include_child?: boolean;
     readonly $state?: ZohoRecruitDraftOrSaveState;
 }
+/**
+ * Paginated response containing records and page metadata.
+ */
 export type ZohoRecruitGetRecordsResponse<T = ZohoRecruitRecord> = ZohoPageResult<T>;
+/**
+ * Retrieves a paginated list of records from a Recruit module.
+ */
 export type ZohoRecruitGetRecordsFunction = <T = ZohoRecruitRecord>(input: ZohoRecruitGetRecordsInput) => Promise<ZohoRecruitGetRecordsResponse<T>>;
 /**
- * Retrieves records from the given module. Used for paginating across all records.
+ * Creates a {@link ZohoRecruitGetRecordsFunction} bound to the given context.
+ *
+ * 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 - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that retrieves paginated records from a module
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/get-records.html
+ * @example
+ * ```typescript
+ * const getRecords = zohoRecruitGetRecords(context);
  *
- * @param context
- * @returns
+ * const page = await getRecords({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   per_page: 10
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/get-records.html
  */
 export declare function zohoRecruitGetRecords(context: ZohoRecruitContext): ZohoRecruitGetRecordsFunction;
 /**
@@ -156,19 +372,79 @@ export interface ZohoRecruitSearchRecordsInput<T = ZohoRecruitRecord> extends Zo
     readonly phone?: Maybe<PhoneNumber>;
     readonly word?: Maybe<string>;
 }
+/**
+ * Paginated response from a search operation, identical in shape to {@link ZohoRecruitGetRecordsResponse}.
+ */
 export type ZohoRecruitSearchRecordsResponse<T = ZohoRecruitRecord> = ZohoRecruitGetRecordsResponse<T>;
+/**
+ * Searches records in a Recruit module using criteria, email, phone, or keyword.
+ * Returns a paginated result defaulting to an empty data array when no matches are found.
+ */
 export type ZohoRecruitSearchRecordsFunction = <T = ZohoRecruitRecord>(input: ZohoRecruitSearchRecordsInput<T>) => Promise<ZohoRecruitSearchRecordsResponse<T>>;
 /**
- * Searches records from the given module.
+ * Creates a {@link ZohoRecruitSearchRecordsFunction} bound to the given context.
+ *
+ * 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 - 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);
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/search-records.html
+ * // Search by criteria:
+ * const result = await searchRecords({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   criteria: [{ field: 'Last_Name', filter: 'starts_with', value: 'Smith' }],
+ *   per_page: 10
+ * });
  *
- * @param context
- * @returns
+ * // 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
  */
 export declare function zohoRecruitSearchRecords(context: ZohoRecruitContext): ZohoRecruitSearchRecordsFunction;
+/**
+ * Factory function type that produces paginated iterators over search results.
+ */
 export type ZohoRecruitSearchRecordsPageFactory = <T = ZohoRecruitRecord>(input: ZohoRecruitSearchRecordsInput<T>, options?: Maybe<FetchPageFactoryOptions<ZohoRecruitSearchRecordsInput<T>, ZohoRecruitSearchRecordsResponse<T>>>) => FetchPage<ZohoRecruitSearchRecordsInput<T>, ZohoRecruitSearchRecordsResponse<T>>;
+/**
+ * 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();
+ * ```
+ */
 export declare function zohoRecruitSearchRecordsPageFactory(context: ZohoRecruitContext): ZohoRecruitSearchRecordsPageFactory;
+/**
+ * Configuration for creating a related records retrieval function.
+ */
 export interface ZohoRecruitGetRelatedRecordsFunctionConfig {
     readonly targetModule: ZohoRecruitModuleName;
     /**
@@ -178,8 +454,17 @@ export interface ZohoRecruitGetRelatedRecordsFunctionConfig {
      */
     readonly returnEmptyRecordsInsteadOfNull?: boolean;
 }
+/**
+ * Factory that produces typed functions for fetching related records of a specific target module.
+ */
 export type ZohoRecruitGetRelatedRecordsFunctionFactory = <T = ZohoRecruitRecord>(input: ZohoRecruitGetRelatedRecordsFunctionConfig) => ZohoRecruitGetRelatedRecordsFunction<T>;
+/**
+ * Pagination filter for related records requests, equivalent to {@link ZohoPageFilter}.
+ */
 export type ZohoRecruitGetRelatedRecordsPageFilter = ZohoPageFilter;
+/**
+ * Request for fetching related records of a specific record in a module.
+ */
 export interface ZohoRecruitGetRelatedRecordsRequest extends ZohoRecruitGetRecordByIdInput, ZohoRecruitGetRelatedRecordsPageFilter {
     /**
      * Optional, Use to filter the related records of the primary/target record with said ids.
@@ -192,28 +477,190 @@ export interface ZohoRecruitGetRelatedRecordsRequest extends ZohoRecruitGetRecor
      */
     readonly filter?: Maybe<ZohoRecruitGetRelatedRecordsPageFilter>;
 }
+/**
+ * Paginated response containing related records and page metadata.
+ */
 export type ZohoRecruitGetRelatedRecordsResponse<T = ZohoRecruitRecord> = ZohoPageResult<T>;
+/**
+ * Typed function for fetching related records of a specific target module from a parent record.
+ */
 export type ZohoRecruitGetRelatedRecordsFunction<T = ZohoRecruitRecord> = (input: ZohoRecruitGetRelatedRecordsRequest) => Promise<ZohoRecruitGetRelatedRecordsResponse<T>>;
 /**
- * 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
  */
 export declare function zohoRecruitGetRelatedRecordsFunctionFactory(context: ZohoRecruitContext): ZohoRecruitGetRelatedRecordsFunctionFactory;
+/**
+ * Request input for fetching emails related to a record.
+ */
 export type ZohoRecruitGetEmailsForRecordRequest = ZohoRecruitGetRelatedRecordsRequest;
+/**
+ * Paginated response containing email metadata entries for a record.
+ */
 export type ZohoRecruitGetEmailsForRecordResponse = ZohoPageResult<ZohoRecruitRecordEmailMetadata>;
+/**
+ * Retrieves paginated email metadata for a specific record in a module.
+ */
 export type ZohoRecruitGetEmailsForRecordFunction = (input: ZohoRecruitGetEmailsForRecordRequest) => Promise<ZohoRecruitGetEmailsForRecordResponse>;
+/**
+ * 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
+ */
 export declare function zohoRecruitGetEmailsForRecord(context: ZohoRecruitContext): ZohoRecruitGetEmailsForRecordFunction;
+/**
+ * Page factory type for paginated email retrieval.
+ */
 export type ZohoRecruitGetEmailsForRecordPageFactory = FetchPageFactory<ZohoRecruitGetEmailsForRecordRequest, ZohoRecruitGetEmailsForRecordResponse>;
+/**
+ * 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
+ */
 export declare function zohoRecruitGetEmailsForRecordPageFactory(context: ZohoRecruitContext): ZohoRecruitGetEmailsForRecordPageFactory;
+/**
+ * Request input for fetching attachments related to a record.
+ */
 export type ZohoRecruitGetAttachmentsForRecordRequest = ZohoRecruitGetRelatedRecordsRequest;
+/**
+ * Paginated response containing attachment metadata entries for a record.
+ */
 export type ZohoRecruitGetAttachmentsForRecordResponse = ZohoPageResult<ZohoRecruitRecordAttachmentMetadata>;
+/**
+ * Retrieves paginated attachment metadata for a specific record in a module.
+ */
 export type ZohoRecruitGetAttachmentsForRecordFunction = (input: ZohoRecruitGetAttachmentsForRecordRequest) => Promise<ZohoRecruitGetAttachmentsForRecordResponse>;
+/**
+ * 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
+ */
 export declare function zohoRecruitGetAttachmentsForRecord(context: ZohoRecruitContext): ZohoRecruitGetAttachmentsForRecordFunction;
+/**
+ * Page factory type for paginated attachment retrieval.
+ */
 export type ZohoRecruitGetAttachmentsForRecordPageFactory = FetchPageFactory<ZohoRecruitGetAttachmentsForRecordRequest, ZohoRecruitGetAttachmentsForRecordResponse>;
+/**
+ * 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
+ */
 export declare function zohoRecruitGetAttachmentsForRecordPageFactory(context: ZohoRecruitContext): ZohoRecruitGetAttachmentsForRecordPageFactory;
 /**
  * Maximum attachment size allowed by Zoho Recruit.
@@ -221,80 +668,172 @@ export declare function zohoRecruitGetAttachmentsForRecordPageFactory(context: Z
  * 20MB
  */
 export declare const ZOHO_RECRUIT_ATTACHMENT_MAX_SIZE: number;
+/**
+ * Input for uploading an attachment to a record, specifying the file source and category.
+ */
 export interface ZohoRecruitUploadAttachmentForRecordRequest extends ZohoRecruitGetRecordByIdInput {
     /**
-     * Requires the use of a FormData object.
-     *
-     * Max of 20MB are allowed
+     * File to upload as an attachment. Max 20MB.
      *
-     * @deprecated Use attachmentUrl instead for now.
+     * Either this or attachmentUrl must be provided.
      */
-    readonly formData?: FormData;
+    readonly file?: Maybe<File>;
     /**
      * File url to pull the file from.
      *
-     * Either this or formData must be provided.
+     * Either this or file must be provided.
      */
     readonly attachmentUrl?: WebsiteUrlWithPrefix;
     /**
      * The category id(s) of the attachment.
      *
-     * Either this or attachments_category must be provided.
+     * Either this or attachmentCategoryName must be provided.
      */
     readonly attachmentCategoryId?: ArrayOrValue<ZohoRecruitAttachmentCategoryId>;
     /**
      * The category name(s) of the attachment.
      *
-     * Either this or attachments_category_id must be provided.
+     * Either this or attachmentCategoryId must be provided.
      *
      * Example: "Resume"
      */
     readonly attachmentCategoryName?: ArrayOrValue<KnownZohoRecruitAttachmentCategoryName>;
 }
+/**
+ * Raw fetch {@link Response} from the upload attachment endpoint.
+ */
 export type ZohoRecruitUploadAttachmentForRecordResponse = Response;
+/**
+ * Uploads a file or URL-based attachment to a specific record in a module.
+ */
 export type ZohoRecruitUploadAttachmentForRecordFunction = (input: ZohoRecruitUploadAttachmentForRecordRequest) => Promise<ZohoRecruitUploadAttachmentForRecordResponse>;
 /**
- * Uploads an attachment to a record.
+ * Creates a {@link ZohoRecruitUploadAttachmentForRecordFunction} bound to the given context.
+ *
+ * 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 - 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
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/upload-attachment.html
+ * @example
+ * ```typescript
+ * const uploadAttachment = zohoRecruitUploadAttachmentForRecord(context);
  *
- * @param context
- * @returns
+ * // 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
  */
 export declare function zohoRecruitUploadAttachmentForRecord(context: ZohoRecruitContext): ZohoRecruitUploadAttachmentForRecordFunction;
+/**
+ * Input for downloading a specific attachment from a record.
+ */
 export interface ZohoRecruitDownloadAttachmentForRecordRequest extends ZohoRecruitGetRecordByIdInput {
     readonly attachment_id: ZohoRecruitAttachmentRecordId;
 }
+/**
+ * Parsed file response containing the downloaded attachment data and metadata (file name, content type, etc.).
+ */
 export type ZohoRecruitDownloadAttachmentForRecordResponse = FetchFileResponse;
+/**
+ * Downloads a specific attachment from a record, returning a parsed {@link FetchFileResponse}.
+ */
 export type ZohoRecruitDownloadAttachmentForRecordFunction = (input: ZohoRecruitDownloadAttachmentForRecordRequest) => Promise<ZohoRecruitDownloadAttachmentForRecordResponse>;
 /**
- * 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
  */
 export declare function zohoRecruitDownloadAttachmentForRecord(context: ZohoRecruitContext): ZohoRecruitDownloadAttachmentForRecordFunction;
+/**
+ * Input for deleting a specific attachment from a record.
+ */
 export interface ZohoRecruitDeleteAttachmentFromRecordRequest extends ZohoRecruitGetRecordByIdInput {
     readonly attachment_id: ZohoRecruitAttachmentRecordId;
 }
+/**
+ * Raw fetch {@link Response} from the delete attachment endpoint.
+ */
 export type ZohoRecruitDeleteAttachmentFromRecordResponse = Response;
+/**
+ * Deletes a specific attachment from a record by its attachment ID.
+ */
 export type ZohoRecruitDeleteAttachmentFromRecordFunction = (input: ZohoRecruitDeleteAttachmentFromRecordRequest) => Promise<ZohoRecruitDeleteAttachmentFromRecordResponse>;
 /**
- * Deletes an attachment from a record.
+ * Creates a {@link ZohoRecruitDeleteAttachmentFromRecordFunction} bound to the given context.
+ *
+ * Deletes a specific attachment from a record by its attachment ID.
+ * Returns the raw {@link Response}.
+ *
+ * @param context - Authenticated Zoho Recruit context providing fetch and rate limiting
+ * @returns Function that deletes an attachment by record and attachment ID
+ *
+ * @example
+ * ```typescript
+ * const deleteAttachment = zohoRecruitDeleteAttachmentFromRecord(context);
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/delete-attachments.html
+ * const response = await deleteAttachment({
+ *   module: ZOHO_RECRUIT_CANDIDATES_MODULE,
+ *   id: candidateId,
+ *   attachment_id: attachmentId
+ * });
+ * ```
  *
- * @param context
- * @returns
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/delete-attachments.html
  */
 export declare function zohoRecruitDeleteAttachmentFromRecord(context: ZohoRecruitContext): ZohoRecruitDeleteAttachmentFromRecordFunction;
+/**
+ * Union of request types for executing a Zoho Recruit serverless function.
+ * Either uses the context's OAuth credentials or an explicit API key.
+ */
 export type ZohoRecruitExecuteRestApiFunctionRequest = ZohoRecruitExecuteRestApiFunctionNormalRequest | ZohoRecruitExecuteRestApiFunctionApiSpecificRequest;
+/**
+ * Standard request for executing a serverless function using the context's OAuth credentials.
+ */
 export interface ZohoRecruitExecuteRestApiFunctionNormalRequest {
     readonly functionName: ZohoRecruitRestFunctionApiName;
     readonly params?: Maybe<ZohoRecruitExecuteRestApiFunctionParams>;
 }
+/**
+ * Request that targets a specific API endpoint using an API key instead of OAuth, allowing cross-environment calls.
+ */
 export interface ZohoRecruitExecuteRestApiFunctionApiSpecificRequest extends ZohoRecruitExecuteRestApiFunctionNormalRequest {
     /**
      * If provided the function will use the API key provided instead of the internal oauth
@@ -307,24 +846,45 @@ export interface ZohoRecruitExecuteRestApiFunctionApiSpecificRequest extends Zoh
      */
     readonly apiUrl?: ZohoRecruitConfigApiUrlInput;
 }
+/**
+ * API key string used for authenticating serverless function calls outside of OAuth.
+ */
 export type ZohoRecruitRestFunctionApiKey = string;
+/**
+ * Key-value parameters passed to a serverless function as query string arguments.
+ */
 export type ZohoRecruitExecuteRestApiFunctionParams = Record<string, string | number | boolean | ZohoDateTimeString>;
+/**
+ * Union of success or error responses from a serverless function execution.
+ */
 export type ZohoRecruitExecuteRestApiFunctionResponse = ZohoRecruitExecuteRestApiFunctionSuccessResponse | ZohoRecruitExecuteRestApiFunctionErrorResponse;
+/**
+ * Successful response from a serverless function execution, containing the function's output details.
+ */
 export interface ZohoRecruitExecuteRestApiFunctionSuccessResponse {
     readonly code: 'success';
     readonly details: ZohoRecruitExecuteRestApiFunctionSuccessDetails;
     readonly message: string;
 }
+/**
+ * Details payload from a successful serverless function execution, including any user messages and the invoking user's ID.
+ */
 export interface ZohoRecruitExecuteRestApiFunctionSuccessDetails {
     readonly userMessage: string[];
     readonly output_type: string;
     readonly id: ZohoRecruitUserId;
 }
+/**
+ * Error response from a serverless function execution, containing the error code and message.
+ */
 export interface ZohoRecruitExecuteRestApiFunctionErrorResponse {
     readonly code: string;
     readonly details: unknown;
     readonly message: string;
 }
+/**
+ * Thrown when a Zoho Recruit serverless function execution fails, wrapping the error response with the API error code and message.
+ */
 export declare class ZohoRecruitExecuteRestApiFunctionError extends BaseError {
     readonly error: ZohoRecruitExecuteRestApiFunctionErrorResponse;
     constructor(error: ZohoRecruitExecuteRestApiFunctionErrorResponse);
@@ -336,52 +896,154 @@ export declare class ZohoRecruitExecuteRestApiFunctionError extends BaseError {
  */
 export type ZohoRecruitExecuteRestApiFunctionFunction = (input: ZohoRecruitExecuteRestApiFunctionRequest) => Promise<ZohoRecruitExecuteRestApiFunctionSuccessDetails>;
 /**
- * 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'
+ * });
+ * ```
  */
 export declare function zohoRecruitExecuteRestApiFunction(context: ZohoRecruitContext): ZohoRecruitExecuteRestApiFunctionFunction;
+/**
+ * Builds URL search params from input objects, omitting the `module` key since it is used in the URL path rather than query string.
+ */
 export declare function zohoRecruitUrlSearchParamsMinusModule(...input: Maybe<object | Record<string, string | number>>[]): URLSearchParams;
+/**
+ * Builds URL search params from input objects, omitting both `id` and `module` keys since they are used in the URL path.
+ */
 export declare function zohoRecruitUrlSearchParamsMinusIdAndModule(...input: Maybe<object | Record<string, string | number>>[]): URLSearchParams;
 /**
  * @deprecated use makeUrlSearchParams instead.
  */
 export declare const zohoRecruitUrlSearchParams: typeof makeUrlSearchParams;
+/**
+ * Constructs a standard {@link FetchJsonInput} for Zoho Recruit API calls with the given HTTP method and optional body.
+ */
 export declare function zohoRecruitApiFetchJsonInput(method: string, body?: Maybe<FetchJsonBody>): FetchJsonInput;
+/**
+ * Generic response wrapper for change operations that return an array of per-record results.
+ */
 export type ZohoRecruitChangeObjectLikeResponse<T extends ZohoRecruitChangeObjectLikeResponseEntry = ZohoRecruitChangeObjectLikeResponseEntry> = ZohoDataArrayResultRef<T>;
+/**
+ * Union of success or error entry types in a change response.
+ */
 export type ZohoRecruitChangeObjectLikeResponseEntry<E extends ZohoRecruitChangeObjectLikeResponseSuccessEntryMeta = ZohoRecruitChangeObjectLikeResponseSuccessEntryMeta> = E | ZohoRecruitChangeObjectResponseErrorEntry;
+/**
+ * Extracts the success entry type from a change response entry union.
+ */
 export type ZohoRecruitChangeObjectLikeResponseSuccessEntryType<T extends ZohoRecruitChangeObjectLikeResponseEntry> = T extends ZohoRecruitChangeObjectLikeResponseEntry<infer E> ? E : never;
+/**
+ * Common metadata present on all successful change operation entries.
+ */
 export interface ZohoRecruitChangeObjectLikeResponseSuccessEntryMeta {
     readonly code: ZohoServerSuccessCode;
     readonly status: ZohoServerSuccessStatus;
     readonly message: string;
 }
+/**
+ * Change response augmented with pre-separated success and error entry arrays for convenient access.
+ */
 export type ZohoRecruitChangeObjectLikeResponseSuccessAndErrorPairs<T extends ZohoRecruitChangeObjectLikeResponseEntry> = ZohoRecruitChangeObjectLikeResponse<T> & {
     readonly successItems: ZohoRecruitChangeObjectLikeResponseSuccessEntryType<T>[];
     readonly errorItems: ZohoRecruitChangeObjectResponseErrorEntry[];
 };
+/**
+ * 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
+ * ```
+ */
 export declare function zohoRecruitChangeObjectLikeResponseSuccessAndErrorPairs<T extends ZohoRecruitChangeObjectLikeResponseEntry>(response: ZohoRecruitChangeObjectLikeResponse<T>): ZohoRecruitChangeObjectLikeResponseSuccessAndErrorPairs<T>;
+/**
+ * Concrete change response type for insert/update/upsert operations, wrapping an array of per-record entries.
+ */
 export type ZohoRecruitChangeObjectResponse<T extends ZohoRecruitChangeObjectResponseEntry = ZohoRecruitChangeObjectResponseEntry> = ZohoRecruitChangeObjectLikeResponse<T>;
+/**
+ * Union of success or error entry types in an insert/update/upsert response.
+ */
 export type ZohoRecruitChangeObjectResponseEntry<E extends ZohoRecruitChangeObjectResponseSuccessEntry = ZohoRecruitChangeObjectResponseSuccessEntry> = ZohoRecruitChangeObjectLikeResponseEntry<E>;
+/**
+ * Successful change entry that includes the full object details (e.g., created/updated record fields).
+ */
 export interface ZohoRecruitChangeObjectResponseSuccessEntry<D extends ZohoRecruitChangeObjectDetails = ZohoRecruitChangeObjectDetails> extends ZohoRecruitChangeObjectLikeResponseSuccessEntryMeta {
     readonly details: D;
 }
+/**
+ * Error entry from a change operation, containing the Zoho error status and details.
+ */
 export interface ZohoRecruitChangeObjectResponseErrorEntry extends ZohoServerErrorDataWithDetails {
     readonly status: ZohoServerErrorStatus;
 }
+/**
+ * Paired result from a bulk operation, correlating each input record with its success or error outcome.
+ */
 export interface ZohoRecruitMultiRecordResult<I, OS, OE> {
     readonly successItems: ZohoRecruitMultiRecordResultEntry<I, OS>[];
     readonly errorItems: ZohoRecruitMultiRecordResultEntry<I, OE>[];
 }
+/**
+ * Constraint interface requiring a status field to distinguish success from error results.
+ */
 export interface ZohoRecruitMultiRecordResultItem {
     readonly status: ZohoServerSuccessStatus | ZohoServerErrorStatus;
 }
+/**
+ * Pairs each input record with its corresponding API result and separates them into success and error arrays by status.
+ *
+ * Iterates over the `input` and `results` arrays in parallel, matching each input record
+ * to its positional result. Entries are classified as success or error based on
+ * the result's `status` field matching {@link ZOHO_SUCCESS_STATUS}.
+ *
+ * Used internally by {@link updateRecordLikeFunction} to pair input data with API outcomes
+ * for insert, update, and upsert operations.
+ *
+ * @param input - Array of input records that were submitted to the API
+ * @param results - Array of per-record results returned by the API, positionally aligned with `input`
+ * @returns Object with `successItems` and `errorItems`, each containing paired `{ input, result }` entries
+ */
 export declare function zohoRecruitMultiRecordResult<I, OS extends ZohoRecruitMultiRecordResultItem, OE extends ZohoRecruitMultiRecordResultItem>(input: I[], results: (OS | OE)[]): ZohoRecruitMultiRecordResult<I, OS, OE>;
 export interface ZohoRecruitMultiRecordResultEntry<I, O> {
     /**
@@ -389,7 +1051,7 @@ export interface ZohoRecruitMultiRecordResultEntry<I, O> {
      */
     readonly input: I;
     /**
-     * The result of the insert.
+     * The API result for this record (success or error entry).
      */
     readonly result: O;
 }