@dereekb/zoho 13.3.1 → 13.4.1

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

@@ -1,4 +1,4 @@
-import { type CommaSeparatedString, type EmailAddress, type ISO8601DateString, type UniqueModelWithId, type WebsiteUrl } from '@dereekb/util';
+import { type CommaSeparatedString, type EmailAddress, type ISO8601DateString, type Maybe, type UniqueModelWithId, type WebsiteUrl } from '@dereekb/util';
 /**
  * Zoho CRM module name.
  *
@@ -108,15 +108,15 @@ export type ZohoCrmCommaSeparateFieldNames = CommaSeparatedString;
 export type ZohoCrmDraftOrSaveState = 'draft' | 'save';
 export type ZohoCrmTrueFalseBoth = 'true' | 'false' | 'both';
 export interface ZohoCrmReferenceData {
-    name: string;
-    id: ZohoCrmId;
+    readonly name: string;
+    readonly id: ZohoCrmId;
 }
 /**
  * Reference pair of a Zoho Crm user name and id
  */
 export interface ZohoCrmUserReferenceData {
-    name: string;
-    id: ZohoCrmUserId;
+    readonly name: string;
+    readonly id: ZohoCrmUserId;
 }
 export interface ZohoCrmReferenceDataWithModule extends ZohoCrmReferenceData, ZohoCrmModuleNameRef {
 }
@@ -138,11 +138,11 @@ export type ZohoCrmValidUrl = WebsiteUrl;
  * Update details returned by the server for a created/updated object.
  */
 export interface ZohoCrmChangeObjectDetails {
-    id: ZohoCrmRecordId;
-    Modified_Time: ISO8601DateString;
-    Modified_By: ZohoCrmCreatedByData;
-    Created_Time: ISO8601DateString;
-    Created_By: ZohoCrmCreatedByData;
+    readonly id: ZohoCrmRecordId;
+    readonly Modified_Time: ISO8601DateString;
+    readonly Modified_By: ZohoCrmCreatedByData;
+    readonly Created_Time: ISO8601DateString;
+    readonly Created_By: ZohoCrmCreatedByData;
 }
 /**
  * Base Zoho Crm field data type.
@@ -287,7 +287,7 @@ export interface ZohoCrmRecordAttachmentMetadata {
     /**
      * Direct URL to the attachment, when available
      */
-    Attachment_URL: string | null;
+    Attachment_URL: Maybe<WebsiteUrl>;
     /**
      * User who last modified this attachment
      */
@@ -311,7 +311,7 @@ export interface ZohoCrmRecordAttachmentMetadata {
     /**
      * Link URL when the attachment is a link
      */
-    $link_url?: string | null;
+    $link_url?: Maybe<WebsiteUrl>;
     /**
      * Number of linked documents
      */

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

@@ -66,10 +66,17 @@ export declare class ZohoCrmRecordCrudNoMatchingRecordError extends ZohoCrmRecor
 }
 /**
  * Maps a Zoho CRM server error to the appropriate typed {@link ZohoCrmRecordCrudError} subclass based on the error code and affected field.
+ *
+ * @param error - The server error data containing the error code and field details
+ * @returns The appropriate typed CRM CRUD error instance
  */
 export declare function zohoCrmRecordCrudError(error: ZohoServerErrorDataWithDetails): ZohoCrmRecordCrudError;
 /**
  * Returns an assertion function that throws {@link ZohoCrmRecordNoContentError} when a data array result is empty or null, typically indicating a missing record.
+ *
+ * @param moduleName - Optional CRM module name for the error context
+ * @param recordId - Optional record ID for the error context
+ * @returns Assertion function that throws if the data array is empty
  */
 export declare function assertZohoCrmRecordDataArrayResultHasContent<T>(moduleName?: ZohoCrmModuleName, recordId?: ZohoCrmRecordId): <R extends ZohoDataArrayResultRef<T>>(x: R) => R;
 /**
@@ -78,10 +85,17 @@ export declare function assertZohoCrmRecordDataArrayResultHasContent<T>(moduleNa
 export declare const logZohoCrmErrorToConsole: import("..").LogZohoServerErrorFunction;
 /**
  * Parses a fetch response error into a typed Zoho CRM server error by extracting and interpreting the JSON error body.
+ *
+ * @param responseError - The fetch response error to parse
+ * @returns The parsed Zoho server error, or undefined if the response could not be parsed
  */
 export declare function parseZohoCrmError(responseError: FetchResponseError): Promise<ParsedZohoServerError>;
 /**
  * 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.
+ *
+ * @param errorResponseData - The raw error response data from the Zoho CRM API
+ * @param responseError - The original fetch response error for context
+ * @returns The parsed Zoho server error, or undefined if the error could not be classified
  */
 export declare function parseZohoCrmServerErrorResponseData(errorResponseData: ZohoServerErrorResponseData | ZohoServerErrorResponseDataArrayRef, responseError: FetchResponseError): ParsedZohoServerError;
 /**

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

@@ -15,16 +15,16 @@ export interface ZohoCrmFactoryConfig extends ZohoAccountsContextRef {
     /**
      * Custom rate limiter configuration to control request concurrency and throttling.
      */
-    rateLimiterConfig?: Maybe<ZohoRateLimitedFetchHandlerConfig>;
+    readonly rateLimiterConfig?: Maybe<ZohoRateLimitedFetchHandlerConfig>;
     /**
      * Custom fetch factory for creating the underlying HTTP client.
      * Defaults to a standard fetch service with OAuth Bearer token headers and a 20-second timeout.
      */
-    fetchFactory?: ZohoCrmFetchFactory;
+    readonly fetchFactory?: ZohoCrmFetchFactory;
     /**
      * Custom error logging function invoked when Zoho API errors are encountered.
      */
-    logZohoServerErrorFunction?: LogZohoServerErrorFunction;
+    readonly logZohoServerErrorFunction?: LogZohoServerErrorFunction;
 }
 /**
  * Factory function that creates a {@link ZohoCrm} client from a {@link ZohoCrmConfig}.

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

@@ -8,7 +8,7 @@ export type ZohoCrmNoteId = string;
  * Metadata describing whether the note action was triggered by the system.
  */
 export interface ZohoCrmNoteAction {
-    $is_system_action: boolean;
+    readonly $is_system_action: boolean;
 }
 /**
  * Known source name indicating the note was created by a normal user.
@@ -22,8 +22,8 @@ export type ZohoCrmNoteSourceType = number;
  * Describes the origin of a note, including who or what created it.
  */
 export interface ZohoCrmNoteSource {
-    name: ZohoCrmNoteSourceName;
-    type: ZohoCrmNoteSourceType;
+    readonly name: ZohoCrmNoteSourceName;
+    readonly type: ZohoCrmNoteSourceType;
 }
 /**
  * Reference data identifying the owner of a note.
@@ -33,26 +33,26 @@ export type ZohoCrmNoteOwnerData = ZohoCrmReferenceData;
  * Full data shape for a CRM note as returned by the API, including metadata fields like permissions, source, and timestamps.
  */
 export interface ZohoCrmNoteData {
-    Note_Title: string;
-    Note_Content: string;
-    Parent_Id: ZohoCrmParentReferenceData;
-    Created_Time: ISO8601DateString;
-    Modified_Time: ISO8601DateString;
-    $attachments: null;
-    $is_edit_allowed: boolean;
-    $editable: boolean;
-    $type_id: ZohoCrmTypeId;
-    $is_delete_allowed: boolean;
-    $note_action: ZohoCrmNoteAction;
-    $source: ZohoCrmNoteSource;
-    $se_module: ZohoCrmModuleName;
-    $is_shared_to_client: boolean;
-    Note_Owner: ZohoCrmNoteOwnerData;
-    Created_By: ZohoCrmCreatedByData;
-    Modified_By: ZohoCrmModifiedByData;
-    $size: ZohoCrmNoteFileSize | null;
-    $voice_note: boolean;
-    $status: ZohoCrmNoteStatus;
+    readonly Note_Title: string;
+    readonly Note_Content: string;
+    readonly Parent_Id: ZohoCrmParentReferenceData;
+    readonly Created_Time: ISO8601DateString;
+    readonly Modified_Time: ISO8601DateString;
+    readonly $attachments: null;
+    readonly $is_edit_allowed: boolean;
+    readonly $editable: boolean;
+    readonly $type_id: ZohoCrmTypeId;
+    readonly $is_delete_allowed: boolean;
+    readonly $note_action: ZohoCrmNoteAction;
+    readonly $source: ZohoCrmNoteSource;
+    readonly $se_module: ZohoCrmModuleName;
+    readonly $is_shared_to_client: boolean;
+    readonly Note_Owner: ZohoCrmNoteOwnerData;
+    readonly Created_By: ZohoCrmCreatedByData;
+    readonly Modified_By: ZohoCrmModifiedByData;
+    readonly $size: ZohoCrmNoteFileSize | null;
+    readonly $voice_note: boolean;
+    readonly $status: ZohoCrmNoteStatus;
 }
 /**
  * Data required to create a new note, including the parent record reference and target module.

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

@@ -22,14 +22,14 @@ export type ZohoCrmTagColorCode = HexColorCode;
  * The color and name of a Tag in Zoho Crm.
  */
 export interface ZohoCrmTagData {
-    color_code?: Maybe<ZohoCrmTagColorCode>;
-    name: ZohoCrmTagName;
+    readonly color_code?: Maybe<ZohoCrmTagColorCode>;
+    readonly name: ZohoCrmTagName;
 }
 /**
  * Includes the id of the Tag along with other tag data.
  */
 export interface ZohoCrmTag extends ZohoCrmTagData {
-    id: ZohoCrmTagId;
+    readonly id: ZohoCrmTagId;
 }
 /**
  * ZohoCrmTag that also has ZohoCrmChangeObjectDetails

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

@@ -59,6 +59,9 @@ export type ZohoRecruitAssociateCandidateRecordsWithJobOpeningsFunction = (input
  *
  * The result separates "already associated" errors from other errors, allowing callers to treat duplicate associations as non-fatal.
  *
+ * @param context - Zoho Recruit API context providing fetch and authentication
+ * @returns Factory function that associates candidates with job openings
+ *
  * https://www.zoho.com/recruit/developer-guide/apiv2/associate-candidate.html
  */
 export declare function zohoRecruitAssociateCandidateRecordsWithJobOpenings(context: ZohoRecruitContext): ZohoRecruitAssociateCandidateRecordsWithJobOpeningsFunction;
@@ -80,6 +83,9 @@ export type ZohoRecruitSearchAssociatedRecordsResponse<T = ZohoRecruitRecord> =
 export type ZohoRecruitSearchAssociatedRecordsFunction<R extends ZohoRecruitSearchAssociatedRecordsResponse> = (input: ZohoRecruitSearchAssociatedRecordsInput) => Promise<R>;
 /**
  * Searches for records associated with a given candidate or job opening. Returns an empty page result when no records are found.
+ *
+ * @param context - Zoho Recruit API context providing fetch and authentication
+ * @returns Factory function that searches for associated records
  */
 export declare function zohoRecruitSearchAssociatedRecords<R extends ZohoRecruitSearchAssociatedRecordsResponse>(context: ZohoRecruitContext): ZohoRecruitSearchAssociatedRecordsFunction<R>;
 /**
@@ -89,10 +95,16 @@ export type ZohoRecruitSearchCandidateAssociatedJobOpeningRecordsInput = Omit<Zo
 export type ZohoRecruitSearchCandidateAssociatedJobOpeningRecordsFunction<T extends ZohoRecruitRecord> = (input: ZohoRecruitSearchCandidateAssociatedJobOpeningRecordsInput) => Promise<ZohoRecruitSearchAssociatedRecordsResponse<T>>;
 /**
  * Searches for job openings associated with a specific candidate.
+ *
+ * @param context - Zoho Recruit API context providing fetch and authentication
+ * @returns Factory function that searches for job openings associated with a candidate
  */
 export declare function zohoRecruitSearchCandidateAssociatedJobOpeningRecords<T extends ZohoRecruitRecord>(context: ZohoRecruitContext): ZohoRecruitSearchCandidateAssociatedJobOpeningRecordsFunction<T>;
 /**
  * Creates a page factory for paginating over job openings associated with a candidate.
+ *
+ * @param context - Zoho Recruit API context providing fetch and authentication
+ * @returns Page factory for iterating through associated job openings
  */
 export declare function zohoRecruitSearchCandidateAssociatedJobOpeningRecordsPageFactory<T extends ZohoRecruitRecord>(context: ZohoRecruitContext): import("@dereekb/util/fetch").FetchPageFactory<ZohoRecruitSearchCandidateAssociatedJobOpeningRecordsInput, ZohoRecruitSearchAssociatedRecordsResponse<T>>;
 /**
@@ -102,9 +114,16 @@ export type ZohoRecruitSearchJobOpeningAssociatedCandidateRecordsInput = Omit<Zo
 export type ZohoRecruitSearchJobOpeningAssociatedCandidateRecordsFunction<T extends ZohoRecruitRecord> = (input: ZohoRecruitSearchJobOpeningAssociatedCandidateRecordsInput) => Promise<ZohoRecruitSearchAssociatedRecordsResponse<T>>;
 /**
  * Searches for candidates associated with a specific job opening.
+ *
+ * @param context - Zoho Recruit API context providing fetch and authentication
+ * @param jobOpeningModuleName - Module name for job openings, defaults to the standard module
+ * @returns Factory function that searches for candidates associated with a job opening
  */
 export declare function zohoRecruitSearchJobOpeningAssociatedCandidateRecords<T extends ZohoRecruitRecord>(context: ZohoRecruitContext, jobOpeningModuleName?: string): ZohoRecruitSearchJobOpeningAssociatedCandidateRecordsFunction<T>;
 /**
  * Creates a page factory for paginating over candidates associated with a job opening.
+ *
+ * @param context - Zoho Recruit API context providing fetch and authentication
+ * @returns Page factory for iterating through associated candidates
  */
 export declare function zohoRecruitSearchJobOpeningAssociatedCandidateRecordsPageFactory<T extends ZohoRecruitRecord>(context: ZohoRecruitContext): import("@dereekb/util/fetch").FetchPageFactory<ZohoRecruitSearchJobOpeningAssociatedCandidateRecordsInput, ZohoRecruitSearchAssociatedRecordsResponse<T>>;

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

@@ -933,10 +933,16 @@ export type ZohoRecruitExecuteRestApiFunctionFunction = (input: ZohoRecruitExecu
 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.
+ *
+ * @param input - One or more objects whose key-value pairs become query parameters
+ * @returns URLSearchParams with the `module` key excluded
  */
 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.
+ *
+ * @param input - One or more objects whose key-value pairs become query parameters
+ * @returns URLSearchParams with `id` and `module` keys excluded
  */
 export declare function zohoRecruitUrlSearchParamsMinusIdAndModule(...input: Maybe<object | Record<string, string | number>>[]): URLSearchParams;
 /**
@@ -945,6 +951,10 @@ export declare function zohoRecruitUrlSearchParamsMinusIdAndModule(...input: May
 export declare const zohoRecruitUrlSearchParams: typeof makeUrlSearchParams;
 /**
  * Constructs a standard {@link FetchJsonInput} for Zoho Recruit API calls with the given HTTP method and optional body.
+ *
+ * @param method - HTTP method for the request
+ * @param body - Optional JSON body to include in the request
+ * @returns Configured fetch JSON input
  */
 export declare function zohoRecruitApiFetchJsonInput(method: string, body?: Maybe<FetchJsonBody>): FetchJsonInput;
 /**

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

@@ -21,6 +21,9 @@ export type ZohoRecruitApiUrlKey = ZohoApiUrlKey;
 export type ZohoRecruitConfigApiUrlInput = ZohoRecruitApiUrlKey | ZohoRecruitApiUrl;
 /**
  * Resolves an environment key or passthrough URL to the full Zoho Recruit API URL.
+ *
+ * @param input - An environment key ('sandbox' or 'production') or a full API URL
+ * @returns The resolved Zoho Recruit API URL
  */
 export declare function zohoRecruitConfigApiUrl(input: ZohoRecruitConfigApiUrlInput): ZohoApiUrl;
 /**
@@ -30,13 +33,13 @@ export type ZohoRecruitConfig = ZohoConfig;
 /**
  * Input provided to a fetch factory so it can construct an HTTP client bound to the given Recruit API URL.
  */
-export interface ZohoRecruitFetchFactoryInput {
+export interface ZohoRecruitFetchFactoryParams {
     readonly apiUrl: ZohoRecruitApiUrl;
 }
 /**
  * Factory that produces a configured fetch client for a specific Zoho Recruit API endpoint.
  */
-export type ZohoRecruitFetchFactory = FactoryWithRequiredInput<ConfiguredFetch, ZohoRecruitFetchFactoryInput>;
+export type ZohoRecruitFetchFactory = FactoryWithRequiredInput<ConfiguredFetch, ZohoRecruitFetchFactoryParams>;
 /**
  * Core context required for all Zoho Recruit API calls, bundling the HTTP client, JSON fetcher, authentication, configuration, and rate limiting.
  */
@@ -52,3 +55,7 @@ export interface ZohoRecruitContext extends ZohoRateLimiterRef {
 export interface ZohoRecruitContextRef {
     readonly recruitContext: ZohoRecruitContext;
 }
+/**
+ * @deprecated use ZohoRecruitFetchFactoryParams instead.
+ */
+export type ZohoRecruitFetchFactoryInput = ZohoRecruitFetchFactoryParams;

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

@@ -1,4 +1,4 @@
-import { type CommaSeparatedString, type EmailAddress, type ISO8601DateString, type UniqueModelWithId, type WebsiteUrl } from '@dereekb/util';
+import { type CommaSeparatedString, type EmailAddress, type ISO8601DateString, type Maybe, type UniqueModelWithId, type WebsiteUrl } from '@dereekb/util';
 /**
  * Zoho Recruit module name.
  *
@@ -84,15 +84,15 @@ export type ZohoRecruitDraftOrSaveState = 'draft' | 'save';
 export type ZohoRecruitCommaSeparateFieldNames = CommaSeparatedString;
 export type ZohoRecruitTrueFalseBoth = 'true' | 'false' | 'both';
 export interface ZohoRecruitReferenceData {
-    name: string;
-    id: ZohoRecruitId;
+    readonly name: string;
+    readonly id: ZohoRecruitId;
 }
 /**
  * Reference pair of a Zoho Recruit user name and id
  */
 export interface ZohoRecruitUserReferenceData {
-    name: string;
-    id: ZohoRecruitUserId;
+    readonly name: string;
+    readonly id: ZohoRecruitUserId;
 }
 export interface ZohoRecruitReferenceDataWithModule extends ZohoRecruitReferenceData, ZohoRecruitModuleNameRef {
 }
@@ -114,11 +114,11 @@ export type ZohoRecruitValidUrl = WebsiteUrl;
  * Update details returned by the server for a created/updated object.
  */
 export interface ZohoRecruitChangeObjectDetails {
-    id: ZohoRecruitRecordId;
-    Modified_Time: ISO8601DateString;
-    Modified_By: ZohoRecruitCreatedByData;
-    Created_Time: ISO8601DateString;
-    Created_By: ZohoRecruitCreatedByData;
+    readonly id: ZohoRecruitRecordId;
+    readonly Modified_Time: ISO8601DateString;
+    readonly Modified_By: ZohoRecruitCreatedByData;
+    readonly Created_Time: ISO8601DateString;
+    readonly Created_By: ZohoRecruitCreatedByData;
 }
 /**
  * Base Zoho Recruit field data type.
@@ -267,7 +267,7 @@ export interface ZohoRecruitRecordAttachmentMetadata {
     /**
      * Direct URL to the attachment, when available
      */
-    Attachment_URL: string | null;
+    Attachment_URL: Maybe<WebsiteUrl>;
     /**
      * User who last modified this attachment
      */
@@ -291,7 +291,7 @@ export interface ZohoRecruitRecordAttachmentMetadata {
     /**
      * Link URL when the attachment is a link
      */
-    $link_url?: string | null;
+    $link_url?: Maybe<WebsiteUrl>;
     /**
      * Number of linked documents
      */

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

@@ -49,10 +49,17 @@ export declare class ZohoRecruitRecordCrudNoMatchingRecordError extends ZohoRecr
 }
 /**
  * Creates a typed CRUD error subclass based on the error code returned by the Zoho Recruit API, enabling callers to catch specific failure modes.
+ *
+ * @param error - Structured error data from the Zoho Recruit API response
+ * @returns A specific CRUD error subclass matching the error code
  */
 export declare function zohoRecruitRecordCrudError(error: ZohoServerErrorDataWithDetails): ZohoRecruitRecordCrudError;
 /**
  * Returns an assertion function that throws {@link ZohoRecruitRecordNoContentError} when the data array result is empty or null, indicating the requested record does not exist.
+ *
+ * @param moduleName - Optional module name for the error context
+ * @param recordId - Optional record ID for the error context
+ * @returns Assertion function that validates the data array is non-empty
  */
 export declare function assertZohoRecruitRecordDataArrayResultHasContent<T>(moduleName?: ZohoRecruitModuleName, recordId?: ZohoRecruitRecordId): <R extends ZohoDataArrayResultRef<T>>(x: R) => R;
 /**
@@ -61,10 +68,17 @@ export declare function assertZohoRecruitRecordDataArrayResultHasContent<T>(modu
 export declare const logZohoRecruitErrorToConsole: import("..").LogZohoServerErrorFunction;
 /**
  * Parses the JSON body of a failed Zoho Recruit fetch response into a structured error, returning undefined if the body cannot be parsed.
+ *
+ * @param responseError - The fetch response error to parse
+ * @returns Parsed Zoho server error, or undefined if parsing fails
  */
 export declare function parseZohoRecruitError(responseError: FetchResponseError): Promise<ParsedZohoServerError>;
 /**
  * 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.
+ *
+ * @param errorResponseData - Raw error response data from the Zoho Recruit API
+ * @param responseError - The underlying fetch response error
+ * @returns Parsed Zoho server error, or undefined if the data contains no recognizable error
  */
 export declare function parseZohoRecruitServerErrorResponseData(errorResponseData: ZohoServerErrorResponseData, responseError: FetchResponseError): ParsedZohoServerError;
 /**

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

@@ -15,16 +15,16 @@ export interface ZohoRecruitFactoryConfig extends ZohoAccountsContextRef {
     /**
      * Custom rate limiter configuration to control request concurrency and throttling.
      */
-    rateLimiterConfig?: Maybe<ZohoRateLimitedFetchHandlerConfig>;
+    readonly rateLimiterConfig?: Maybe<ZohoRateLimitedFetchHandlerConfig>;
     /**
      * Custom fetch factory for creating the underlying HTTP client.
      * Defaults to a standard fetch service with OAuth Bearer token headers and a 20-second timeout.
      */
-    fetchFactory?: ZohoRecruitFetchFactory;
+    readonly fetchFactory?: ZohoRecruitFetchFactory;
     /**
      * Custom error logging function invoked when Zoho API errors are encountered.
      */
-    logZohoServerErrorFunction?: LogZohoServerErrorFunction;
+    readonly logZohoServerErrorFunction?: LogZohoServerErrorFunction;
 }
 /**
  * Factory function that creates a {@link ZohoRecruit} client from a {@link ZohoRecruitConfig}.

package/src/lib/sign/sign.config.d.ts

@@ -7,12 +7,18 @@ export declare const ZOHO_SIGN_SERVICE_NAME: ZohoApiServiceName | ZohoServiceAcc
 export type ZohoSignApiUrl = ZohoApiUrl;
 export type ZohoSignApiUrlKey = ZohoApiUrlKey;
 export type ZohoSignConfigApiUrlInput = ZohoSignApiUrlKey | ZohoSignApiUrl;
+/**
+ * Resolves an environment key or passthrough URL to the full Zoho Sign API URL.
+ *
+ * @param input - An environment key ('sandbox' or 'production') or a full API URL
+ * @returns The resolved Zoho Sign API URL
+ */
 export declare function zohoSignConfigApiUrl(input: ZohoSignConfigApiUrlInput): ZohoApiUrl;
 export type ZohoSignConfig = ZohoConfig;
-export interface ZohoSignFetchFactoryInput {
+export interface ZohoSignFetchFactoryParams {
     readonly apiUrl: ZohoSignApiUrl;
 }
-export type ZohoSignFetchFactory = FactoryWithRequiredInput<ConfiguredFetch, ZohoSignFetchFactoryInput>;
+export type ZohoSignFetchFactory = FactoryWithRequiredInput<ConfiguredFetch, ZohoSignFetchFactoryParams>;
 export interface ZohoSignContext extends ZohoRateLimiterRef {
     readonly fetch: ConfiguredFetch;
     readonly fetchJson: FetchJsonFunction;
@@ -22,3 +28,7 @@ export interface ZohoSignContext extends ZohoRateLimiterRef {
 export interface ZohoSignContextRef {
     readonly signContext: ZohoSignContext;
 }
+/**
+ * @deprecated use ZohoSignFetchFactoryParams instead.
+ */
+export type ZohoSignFetchFactoryInput = ZohoSignFetchFactoryParams;

package/src/lib/sign/sign.d.ts

@@ -1,4 +1,4 @@
-import { type EmailAddress } from '@dereekb/util';
+import { type EmailAddress, type FileSize, type HexColorCode, type PageNumber, type Pixels, type UnixDateTimeMillisecondsNumber } from '@dereekb/util';
 /**
  * An identifier in Zoho Sign.
  */
@@ -64,8 +64,8 @@ export interface ZohoSignFieldType {
  * Text styling properties for a field.
  */
 export interface ZohoSignTextProperty {
-    readonly font_size?: number;
-    readonly font_color?: string;
+    readonly font_size?: Pixels;
+    readonly font_color?: HexColorCode;
     readonly font?: string;
     readonly is_italic?: boolean;
     readonly is_underline?: boolean;
@@ -94,11 +94,11 @@ export interface ZohoSignField {
     readonly document_id?: ZohoSignDocumentId;
     readonly action_id?: ZohoSignActionId;
     readonly is_mandatory?: boolean;
-    readonly x_coord?: number;
-    readonly y_coord?: number;
-    readonly abs_width?: number;
-    readonly abs_height?: number;
-    readonly page_no?: number;
+    readonly x_coord?: Pixels;
+    readonly y_coord?: Pixels;
+    readonly abs_width?: Pixels;
+    readonly abs_height?: Pixels;
+    readonly page_no?: PageNumber;
     readonly default_value?: string;
     readonly is_read_only?: boolean;
     readonly name_format?: ZohoSignNameFormat;
@@ -138,7 +138,7 @@ export interface ZohoSignActionFields {
 export interface ZohoSignDocument {
     readonly document_id: ZohoSignDocumentId;
     readonly document_name?: string;
-    readonly document_size?: number;
+    readonly document_size?: FileSize;
     readonly total_pages?: number;
     readonly document_order?: string;
 }
@@ -157,11 +157,11 @@ export interface ZohoSignRequest {
     readonly owner_last_name?: string;
     readonly description?: string;
     readonly notes?: string;
-    readonly created_time?: number;
-    readonly modified_time?: number;
-    readonly action_time?: number;
-    readonly sign_submitted_time?: number;
-    readonly expire_by?: number;
+    readonly created_time?: UnixDateTimeMillisecondsNumber;
+    readonly modified_time?: UnixDateTimeMillisecondsNumber;
+    readonly action_time?: UnixDateTimeMillisecondsNumber;
+    readonly sign_submitted_time?: UnixDateTimeMillisecondsNumber;
+    readonly expire_by?: UnixDateTimeMillisecondsNumber;
     readonly expiration_days?: number;
     readonly sign_percentage?: number;
     readonly email_reminders?: boolean;

package/src/lib/sign/sign.error.api.d.ts

@@ -1,7 +1,20 @@
 import { type FetchResponseError } from '@dereekb/util/fetch';
 import { type ZohoServerErrorResponseData, type ParsedZohoServerError, type ZohoServerErrorResponseDataArrayRef } from '../zoho.error.api';
 export declare const logZohoSignErrorToConsole: import("..").LogZohoServerErrorFunction;
+/**
+ * Parses the JSON body of a failed Zoho Sign fetch response into a structured error, returning undefined if the body cannot be parsed.
+ *
+ * @param responseError - The fetch response error to parse
+ * @returns Parsed Zoho server error, or undefined if parsing fails
+ */
 export declare function parseZohoSignError(responseError: FetchResponseError): Promise<ParsedZohoServerError>;
+/**
+ * Converts raw Zoho Sign error response data into a parsed error, delegating to Sign-specific handlers for known error codes and falling back to the shared Zoho parser.
+ *
+ * @param errorResponseData - Raw error response data from the Zoho Sign API
+ * @param responseError - The underlying fetch response error
+ * @returns Parsed Zoho server error, or undefined if the data contains no recognizable error
+ */
 export declare function parseZohoSignServerErrorResponseData(errorResponseData: ZohoServerErrorResponseData | ZohoServerErrorResponseDataArrayRef, responseError: FetchResponseError): ParsedZohoServerError;
 export declare const interceptZohoSign200StatusWithErrorResponse: import("@dereekb/util/fetch").FetchJsonInterceptJsonResponseFunction;
 export declare const handleZohoSignErrorFetch: import("..").HandleZohoErrorFetchFactory;

package/src/lib/sign/sign.factory.d.ts

@@ -15,16 +15,16 @@ export interface ZohoSignFactoryConfig extends ZohoAccountsContextRef {
     /**
      * Custom rate limiter configuration to control request concurrency and throttling.
      */
-    rateLimiterConfig?: Maybe<ZohoRateLimitedFetchHandlerConfig>;
+    readonly rateLimiterConfig?: Maybe<ZohoRateLimitedFetchHandlerConfig>;
     /**
      * Custom fetch factory for creating the underlying HTTP client.
      * Defaults to a standard fetch service with OAuth Bearer token headers and a 20-second timeout.
      */
-    fetchFactory?: ZohoSignFetchFactory;
+    readonly fetchFactory?: ZohoSignFetchFactory;
     /**
      * Custom error logging function invoked when Zoho API errors are encountered.
      */
-    logZohoServerErrorFunction?: LogZohoServerErrorFunction;
+    readonly logZohoServerErrorFunction?: LogZohoServerErrorFunction;
 }
 /**
  * Factory function that creates a {@link ZohoSign} client from a {@link ZohoSignConfig}.

package/src/lib/zoho.error.api.d.ts

@@ -76,6 +76,12 @@ export type ZohoServerSuccessData<T = unknown> = Omit<ZohoServerErrorData<T>, 'c
  * Contains details and a status
  */
 export type ZohoServerErrorDataWithDetails<T = unknown> = Required<ZohoServerErrorData<T>>;
+/**
+ * Normalizes a Zoho error response entry into a consistent {@link ZohoServerErrorData} shape, handling both object and string error formats.
+ *
+ * @param error - The raw error entry, either a structured object or a plain error code string
+ * @returns Normalized error data with code and message fields
+ */
 export declare function zohoServerErrorData(error: ZohoServerErrorResponseDataError): ZohoServerErrorData;
 /**
  * Zoho Server Error
@@ -117,8 +123,9 @@ export interface LogZohoServerErrorFunctionConfig {
 /**
  * Creates a logZohoServerErrorFunction that logs the error to console.
  *
- * @param zohoApiNamePrefix Prefix to use when logging. I.E. ZohoRecruitError, etc.
- * @returns
+ * @param zohoApiNamePrefix - Prefix to use when logging (e.g. 'ZohoRecruit', 'ZohoSign')
+ * @param options - Optional configuration for controlling which error types are logged
+ * @returns A function that logs Zoho server errors to the console
  */
 export declare function logZohoServerErrorFunction(zohoApiNamePrefix: string, options?: LogZohoServerErrorFunctionConfig): LogZohoServerErrorFunction;
 /**
@@ -128,18 +135,22 @@ export declare function logZohoServerErrorFunction(zohoApiNamePrefix: string, op
  * @returns
  */
 export type HandleZohoErrorFetchFactory = (fetch: ConfiguredFetch, logError?: LogZohoServerErrorFunction, onError?: (error: ParsedZohoServerError) => void) => ConfiguredFetch;
-export type ParsedZohoServerError = FetchRequestFactoryError | ZohoServerError | undefined;
+export type ParsedZohoServerError = Maybe<FetchRequestFactoryError | ZohoServerError>;
 export type ParseZohoFetchResponseErrorFunction = (responseError: FetchResponseError) => Promise<ParsedZohoServerError>;
 /**
  * Wraps a ConfiguredFetch to support handling errors returned by fetch.
  *
- * @param fetch
- * @returns
+ * @param parseZohoError - Function that parses a fetch response error into a Zoho-specific error
+ * @param defaultLogError - Default error logging function used when no custom logger is provided
+ * @returns Factory that wraps a ConfiguredFetch with Zoho error handling
  */
 export declare function handleZohoErrorFetchFactory(parseZohoError: ParseZohoFetchResponseErrorFunction, defaultLogError: LogZohoServerErrorFunction): HandleZohoErrorFetchFactory;
 export type ParseZohoServerErrorResponseData = (zohoServerErrorResponseData: ZohoServerErrorResponseData, fetchResponseError: FetchResponseError) => ParsedZohoServerError;
 /**
  * FetchJsonInterceptJsonResponseFunction that intercepts a 200 response that actually contains a ZohoServerError and throws a ZohoServerError for the error handling to catch.
+ *
+ * @param parseZohoServerErrorResponseData - Function that parses raw error response data into a structured error
+ * @returns Interceptor function that detects and throws hidden errors in 200 responses
  */
 export declare function interceptZohoErrorResponseFactory(parseZohoServerErrorResponseData: ParseZohoServerErrorResponseData): FetchJsonInterceptJsonResponseFunction;
 /**
@@ -229,6 +240,12 @@ export interface ZohoRateLimitHeaderDetails {
      */
     readonly resetAt: Date;
 }
+/**
+ * Extracts rate limit details from Zoho API response headers, returning null if the headers are absent.
+ *
+ * @param headers - HTTP response headers from a Zoho API call
+ * @returns Parsed rate limit details, or null if rate limit headers are missing
+ */
 export declare function zohoRateLimitHeaderDetails(headers: Headers): Maybe<ZohoRateLimitHeaderDetails>;
 export declare class ZohoTooManyRequestsError extends ZohoServerFetchResponseError {
     get headerDetails(): Maybe<ZohoRateLimitHeaderDetails>;
@@ -236,9 +253,9 @@ export declare class ZohoTooManyRequestsError extends ZohoServerFetchResponseErr
 /**
  * Function that parses/transforms a ZohoServerErrorResponseData into a general ZohoServerError or other known error type.
  *
- * @param errorResponseData
- * @param responseError
- * @returns
+ * @param errorResponseData - Raw error response data from the Zoho API
+ * @param responseError - The underlying fetch response error
+ * @returns A typed Zoho server error, or undefined if no error is found
  */
 export declare function parseZohoServerErrorResponseData(errorResponseData: ZohoServerErrorResponseData | ZohoServerErrorResponseDataArrayRef, responseError: FetchResponseError): ZohoServerFetchResponseError | undefined;
 /**