@dereekb/zoho 13.4.0 → 13.4.2

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;
 /**

package/src/lib/zoho.limit.d.ts

@@ -15,8 +15,10 @@ export interface ZohoRateLimiterRef {
 export type ZohoRateLimitedTooManyRequestsLogFunction = (headers: ZohoRateLimitHeaderDetails, response: Response, fetchResponseError?: FetchResponseError) => PromiseOrValue<void>;
 /**
  * Default handler that logs a warning to the console when the Zoho API rate limit is exceeded.
+ *
+ * @param headers - Rate limit details extracted from the Zoho API response headers
  */
-export declare const DEFAULT_ZOHO_RATE_LIMITED_TOO_MANY_REQUETS_LOG_FUNCTION: (headers: ZohoRateLimitHeaderDetails) => void;
+export declare const DEFAULT_ZOHO_RATE_LIMITED_TOO_MANY_REQUESTS_LOG_FUNCTION: (headers: ZohoRateLimitHeaderDetails) => void;
 /**
  * Configuration for the Zoho rate-limited fetch handler, allowing customization of
  * the rate limit, reset period, and 429 response handling.
@@ -29,6 +31,7 @@ export interface ZohoRateLimitedFetchHandlerConfig {
      * The actual limit may be dynamically adjusted based on `X-RATELIMIT-LIMIT` response headers.
      *
      * Rate limits vary by Zoho account type:
+     *
      * @see https://help.zoho.com/portal/en/community/topic/key-changes-in-api-limits-26-9-2018#:~:text=X%2DRATELIMIT%2DREMAINING%20%2D%20Represents,time%20of%20the%20current%20window.&text=Please%20note%20that%20these%20Rate,API%20limit%20changes%20are%20implemented.
      */
     readonly maxRateLimit?: number;
@@ -67,3 +70,7 @@ export type ZohoRateLimitedFetchHandler = RateLimitedFetchHandler<ResetPeriodPro
  * @returns A rate-limited fetch handler with the underlying rate limiter accessible via `_rateLimiter`
  */
 export declare function zohoRateLimitedFetchHandler(config?: Maybe<ZohoRateLimitedFetchHandlerConfig>): ZohoRateLimitedFetchHandler;
+/**
+ * @deprecated use DEFAULT_ZOHO_RATE_LIMITED_TOO_MANY_REQUESTS_LOG_FUNCTION instead.
+ */
+export declare const DEFAULT_ZOHO_RATE_LIMITED_TOO_MANY_REQUETS_LOG_FUNCTION: (headers: ZohoRateLimitHeaderDetails) => void;