@dereekb/zoho 13.0.6 → 13.0.7

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

@@ -0,0 +1,109 @@
+import { type Maybe } from '@dereekb/util';
+import { type FetchPageFactoryConfigDefaults } from '@dereekb/util/fetch';
+/**
+ * Pagination parameters for Zoho Sign list endpoints.
+ *
+ * Unlike CRM/Recruit which use `page`/`per_page`, Zoho Sign uses an offset-based
+ * model with `start_index` and `row_count`.
+ */
+export interface ZohoSignPageFilter {
+    /**
+     * 1-based offset index of the first record to return.
+     */
+    readonly start_index?: number;
+    /**
+     * Number of records to return per page.
+     */
+    readonly row_count?: number;
+    /**
+     * Column to sort results by.
+     */
+    readonly sort_column?: ZohoSignSortColumn;
+    /**
+     * Sort direction.
+     */
+    readonly sort_order?: ZohoSignSortOrder;
+}
+/**
+ * Known sortable column names for Zoho Sign list endpoints, with a `string` fallback for custom columns.
+ */
+export type ZohoSignSortColumn = 'request_name' | 'folder_name' | 'owner_full_name' | 'recipient_email' | 'form_name' | 'created_time' | string;
+/**
+ * Sort direction for Zoho Sign list queries.
+ */
+export type ZohoSignSortOrder = 'ASC' | 'DESC';
+/**
+ * Optional search filters for narrowing Zoho Sign document list results by specific columns.
+ */
+export interface ZohoSignSearchColumns {
+    readonly request_name?: string;
+    readonly folder_name?: string;
+    readonly owner_full_name?: string;
+    readonly recipient_email?: string;
+    readonly recipient_name?: string;
+    readonly form_name?: string;
+    readonly template_name?: string;
+}
+/**
+ * Pagination metadata returned by Zoho Sign list endpoints alongside each page of results.
+ */
+export interface ZohoSignPageContext {
+    /**
+     * Whether additional rows exist beyond the current page.
+     */
+    readonly has_more_rows: boolean;
+    /**
+     * Total number of records matching the query across all pages.
+     */
+    readonly total_count: number;
+    /**
+     * The 1-based offset index of the first record on this page.
+     */
+    readonly start_index: number;
+    /**
+     * Number of records returned on this page.
+     */
+    readonly row_count: number;
+}
+/**
+ * Paginated response from a Zoho Sign list endpoint, containing an array of
+ * request records and pagination metadata.
+ */
+export interface ZohoSignPageResult<T> {
+    /**
+     * Array of sign request records for the current page.
+     */
+    readonly requests: T[];
+    /**
+     * Pagination metadata for the current page.
+     */
+    readonly page_context: ZohoSignPageContext;
+}
+/**
+ * A fetch function that accepts paginated input and returns a {@link ZohoSignPageResult}.
+ * Used as the underlying data source for {@link zohoSignFetchPageFactory}.
+ */
+export type ZohoSignFetchPageFetchFunction<I extends ZohoSignPageFilter, R extends ZohoSignPageResult<any>> = (input: I) => Promise<R>;
+/**
+ * Creates a page factory that wraps a Zoho Sign fetch function with automatic offset-based pagination.
+ *
+ * The factory reads `page_context.has_more_rows` from each response to determine if additional
+ * pages exist, and automatically advances `start_index` by `row_count` for subsequent requests.
+ *
+ * @param fetch - The Zoho Sign fetch function to paginate over
+ * @param defaults - Optional default configuration for the page factory
+ * @returns A page factory that produces iterable page fetchers
+ *
+ * @example
+ * ```typescript
+ * const pageFactory = zohoSignFetchPageFactory(zohoSignGetDocumentsList(context));
+ *
+ * const fetchPage = pageFactory({ row_count: 10 });
+ * const firstPage = await fetchPage.fetchNext();
+ *
+ * if (firstPage.result.page_context.has_more_rows) {
+ *   const secondPage = await firstPage.fetchNext();
+ * }
+ * ```
+ */
+export declare function zohoSignFetchPageFactory<I extends ZohoSignPageFilter, R extends ZohoSignPageResult<any>>(fetch: ZohoSignFetchPageFetchFunction<I, R>, defaults?: Maybe<FetchPageFactoryConfigDefaults>): import("@dereekb/util/fetch").FetchPageFactory<I, R>;

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

@@ -0,0 +1,24 @@
+import { type FactoryWithRequiredInput } from '@dereekb/util';
+import { type ConfiguredFetch, type FetchJsonFunction } from '@dereekb/util/fetch';
+import { type ZohoApiUrl, type ZohoApiUrlKey, type ZohoConfig, type ZohoApiServiceName } from '../zoho.config';
+import { type ZohoAccessTokenStringFactory, type ZohoServiceAccessTokenKey } from '../accounts';
+import { type ZohoRateLimiterRef } from '../zoho.limit';
+export declare const ZOHO_SIGN_SERVICE_NAME: ZohoApiServiceName | ZohoServiceAccessTokenKey;
+export type ZohoSignApiUrl = ZohoApiUrl;
+export type ZohoSignApiUrlKey = ZohoApiUrlKey;
+export type ZohoSignConfigApiUrlInput = ZohoSignApiUrlKey | ZohoSignApiUrl;
+export declare function zohoSignConfigApiUrl(input: ZohoSignConfigApiUrlInput): ZohoApiUrl;
+export type ZohoSignConfig = ZohoConfig;
+export interface ZohoSignFetchFactoryInput {
+    readonly apiUrl: ZohoSignApiUrl;
+}
+export type ZohoSignFetchFactory = FactoryWithRequiredInput<ConfiguredFetch, ZohoSignFetchFactoryInput>;
+export interface ZohoSignContext extends ZohoRateLimiterRef {
+    readonly fetch: ConfiguredFetch;
+    readonly fetchJson: FetchJsonFunction;
+    readonly accessTokenStringFactory: ZohoAccessTokenStringFactory;
+    readonly config: ZohoSignConfig;
+}
+export interface ZohoSignContextRef {
+    readonly signContext: ZohoSignContext;
+}

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

@@ -0,0 +1,225 @@
+import { type EmailAddress } from '@dereekb/util';
+/**
+ * An identifier in Zoho Sign.
+ */
+export type ZohoSignId = string;
+/**
+ * Identifier of a request (envelope) in Zoho Sign.
+ */
+export type ZohoSignRequestId = string;
+/**
+ * Identifier of a document within a Zoho Sign request.
+ */
+export type ZohoSignDocumentId = string;
+/**
+ * Identifier of an action (recipient action) in Zoho Sign.
+ */
+export type ZohoSignActionId = string;
+/**
+ * Identifier of a folder in Zoho Sign.
+ */
+export type ZohoSignFolderId = string;
+/**
+ * Identifier of a request type (document category) in Zoho Sign.
+ */
+export type ZohoSignRequestTypeId = string;
+/**
+ * Identifier of a field type in Zoho Sign.
+ */
+export type ZohoSignFieldTypeId = string;
+/**
+ * Status of a Zoho Sign request.
+ */
+export type ZohoSignRequestStatus = 'inprogress' | 'completed' | 'recalled' | 'declined' | 'expired' | string;
+/**
+ * Recipient action type in Zoho Sign.
+ */
+export type ZohoSignActionType = 'SIGN' | 'VIEW' | 'INPERSONSIGN' | 'APPROVER';
+/**
+ * Verification type for a recipient.
+ */
+export type ZohoSignVerificationType = 'EMAIL' | 'SMS' | 'OFFLINE';
+/**
+ * Field type name for document fields.
+ */
+export type ZohoSignFieldTypeName = 'Checkbox' | 'Radiogroup' | 'Signature' | 'Initial' | 'Textfield' | 'Email' | 'Date' | 'Name' | 'Company' | 'Jobtitle' | 'CustomDate' | 'Dropdown' | 'Attachment' | 'Checkout' | string;
+/**
+ * Name format for name fields.
+ */
+export type ZohoSignNameFormat = 'FIRST_NAME' | 'LAST_NAME' | 'FULL_NAME';
+/**
+ * Field category classification.
+ */
+export type ZohoSignFieldCategory = 'textfield' | 'image' | 'datefield' | string;
+/**
+ * Definition of a field type available in Zoho Sign.
+ */
+export interface ZohoSignFieldType {
+    readonly field_type_id: ZohoSignFieldTypeId;
+    readonly field_type_name: ZohoSignFieldTypeName;
+    readonly field_category: ZohoSignFieldCategory;
+    readonly is_mandatory: boolean;
+}
+/**
+ * Text styling properties for a field.
+ */
+export interface ZohoSignTextProperty {
+    readonly font_size?: number;
+    readonly font_color?: string;
+    readonly font?: string;
+    readonly is_italic?: boolean;
+    readonly is_underline?: boolean;
+    readonly is_bold?: boolean;
+    readonly is_read_only?: boolean;
+    readonly is_fixed_width?: boolean;
+    readonly is_fixed_height?: boolean;
+    readonly max_field_length?: number;
+}
+/**
+ * Validation settings for a field.
+ */
+export interface ZohoSignFieldValidation {
+    readonly validation_type?: string;
+    readonly validation_regex?: string;
+    readonly validation_error_message?: string;
+}
+/**
+ * A field placed on a document within a Zoho Sign request.
+ */
+export interface ZohoSignField {
+    readonly field_name?: string;
+    readonly field_id?: string;
+    readonly field_label?: string;
+    readonly field_type_name?: ZohoSignFieldTypeName;
+    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 default_value?: string;
+    readonly is_read_only?: boolean;
+    readonly name_format?: ZohoSignNameFormat;
+    readonly date_format?: string;
+    readonly description_tooltip?: string;
+    readonly text_property?: ZohoSignTextProperty;
+    readonly validation?: ZohoSignFieldValidation;
+}
+/**
+ * A recipient action within a Zoho Sign request.
+ */
+export interface ZohoSignAction {
+    readonly action_id?: ZohoSignActionId;
+    readonly action_type: ZohoSignActionType;
+    readonly recipient_name: string;
+    readonly recipient_email: EmailAddress;
+    readonly signing_order?: number;
+    readonly verify_recipient?: boolean;
+    readonly verification_type?: ZohoSignVerificationType;
+    readonly verification_code?: string;
+    readonly private_notes?: string;
+    readonly in_person_name?: string;
+    readonly in_person_email?: EmailAddress;
+    readonly fields?: ZohoSignActionFields;
+}
+/**
+ * Fields grouped by type within an action.
+ */
+export interface ZohoSignActionFields {
+    readonly check_boxes?: ZohoSignField[];
+    readonly text_fields?: ZohoSignField[];
+    readonly image_fields?: ZohoSignField[];
+}
+/**
+ * A document within a Zoho Sign request.
+ */
+export interface ZohoSignDocument {
+    readonly document_id: ZohoSignDocumentId;
+    readonly document_name?: string;
+    readonly document_size?: number;
+    readonly total_pages?: number;
+    readonly document_order?: string;
+}
+/**
+ * A Zoho Sign request (envelope) containing documents to be signed.
+ */
+export interface ZohoSignRequest {
+    readonly request_id?: ZohoSignRequestId;
+    readonly request_status?: ZohoSignRequestStatus;
+    readonly request_name: string;
+    readonly request_type_id?: ZohoSignRequestTypeId;
+    readonly request_type_name?: string;
+    readonly owner_id?: string;
+    readonly owner_email?: EmailAddress;
+    readonly owner_first_name?: string;
+    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 expiration_days?: number;
+    readonly sign_percentage?: number;
+    readonly email_reminders?: boolean;
+    readonly reminder_period?: number;
+    readonly is_sequential?: boolean;
+    readonly is_deleted?: boolean;
+    readonly folder_id?: ZohoSignFolderId;
+    readonly zsdocumentid?: string;
+    readonly attachment_size?: number;
+    readonly actions?: ZohoSignAction[];
+    readonly document_ids?: ZohoSignDocument[];
+    readonly document_fields?: ZohoSignDocumentFieldsEntry[];
+    readonly templates_used?: unknown[];
+    readonly attachments?: unknown[];
+}
+/**
+ * Document fields entry associating document_id with its fields.
+ */
+export interface ZohoSignDocumentFieldsEntry {
+    readonly document_id: ZohoSignDocumentId;
+    readonly fields: ZohoSignField[];
+}
+/**
+ * Form data returned for a completed request, containing field values.
+ */
+export interface ZohoSignDocumentFormData {
+    readonly request_name: string;
+    readonly zsdocumentid: string;
+    readonly actions: ZohoSignFormDataAction[];
+}
+/**
+ * Action within form data containing filled field values.
+ */
+export interface ZohoSignFormDataAction {
+    readonly action_type: ZohoSignActionType;
+    readonly signed_time?: string;
+    readonly recipient_email: EmailAddress;
+    readonly recipient_name: string;
+    readonly fields: ZohoSignFormDataField[];
+}
+/**
+ * A form data field with its label and filled value.
+ */
+export interface ZohoSignFormDataField {
+    readonly field_label: string;
+    readonly field_value: string;
+}
+/**
+ * Input data for creating or updating a Zoho Sign request.
+ */
+export interface ZohoSignRequestData {
+    readonly request_name: string;
+    readonly is_sequential: boolean;
+    readonly request_type_id?: ZohoSignRequestTypeId;
+    readonly notes?: string;
+    readonly expiration_days?: number;
+    readonly email_reminders?: boolean;
+    readonly reminder_period?: number;
+    readonly folder_id?: ZohoSignFolderId;
+    readonly actions: ZohoSignAction[];
+}

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

@@ -0,0 +1,7 @@
+import { type FetchResponseError } from '@dereekb/util/fetch';
+import { type ZohoServerErrorResponseData, type ParsedZohoServerError, type ZohoServerErrorResponseDataArrayRef } from '../zoho.error.api';
+export declare const logZohoSignErrorToConsole: import("..").LogZohoServerErrorFunction;
+export declare function parseZohoSignError(responseError: FetchResponseError): Promise<ParsedZohoServerError>;
+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

@@ -0,0 +1,58 @@
+import { type ZohoSignConfig, type ZohoSignContextRef, type ZohoSignFetchFactory } from './sign.config';
+import { type LogZohoServerErrorFunction } from '../zoho.error.api';
+import { type ZohoAccountsContextRef } from '../accounts/accounts.config';
+import { type ZohoRateLimitedFetchHandlerConfig } from '../zoho.limit';
+import { type Maybe } from '@dereekb/util';
+/**
+ * Top-level Zoho Sign client instance, providing access to the authenticated {@link ZohoSignContext}.
+ */
+export type ZohoSign = ZohoSignContextRef;
+/**
+ * Configuration for creating a {@link ZohoSignFactory}, combining account credentials
+ * with optional overrides for rate limiting, fetch behavior, and error logging.
+ */
+export interface ZohoSignFactoryConfig extends ZohoAccountsContextRef {
+    /**
+     * Custom rate limiter configuration to control request concurrency and throttling.
+     */
+    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;
+    /**
+     * Custom error logging function invoked when Zoho API errors are encountered.
+     */
+    logZohoServerErrorFunction?: LogZohoServerErrorFunction;
+}
+/**
+ * Factory function that creates a {@link ZohoSign} client from a {@link ZohoSignConfig}.
+ */
+export type ZohoSignFactory = (config: ZohoSignConfig) => ZohoSign;
+/**
+ * Creates a {@link ZohoSignFactory} from the given configuration.
+ *
+ * The factory pre-initializes shared resources (access token provider, rate limiter)
+ * once, then produces {@link ZohoSign} client instances for each {@link ZohoSignConfig}.
+ * Each client handles OAuth token refresh on {@link ZohoInvalidTokenError}, rate limiting,
+ * and Zoho Sign's non-standard error responses (200 status with error body).
+ *
+ * @param factoryConfig - Configuration providing account credentials and optional overrides
+ * @returns A factory function that creates authenticated Zoho Sign clients
+ *
+ * @example
+ * ```typescript
+ * const factory = zohoSignFactory({
+ *   accountsContext: zohoAccountsApi.accountsContext
+ * });
+ *
+ * const zohoSign = factory({
+ *   apiUrl: 'https://sign.zoho.com'
+ * });
+ *
+ * // Use the sign context for API calls:
+ * const { signContext } = zohoSign;
+ * ```
+ */
+export declare function zohoSignFactory(factoryConfig: ZohoSignFactoryConfig): ZohoSignFactory;

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

@@ -1,12 +1,21 @@
 import { type Maybe, type PageNumber } from '@dereekb/util';
 import { type FetchPageFactoryConfigDefaults } from '@dereekb/util/fetch';
 /**
- * Base page filter
+ * Base pagination parameters shared by all Zoho list/search API endpoints.
  */
 export interface ZohoPageFilter {
+    /**
+     * 1-based page number to retrieve.
+     */
     readonly page?: number;
+    /**
+     * Number of records to return per page.
+     */
     readonly per_page?: number;
 }
+/**
+ * Generic wrapper for Zoho API responses that return an array of records in a `data` field.
+ */
 export interface ZohoDataArrayResultRef<T> {
     /**
      * Array of data returned.
@@ -14,20 +23,23 @@ export interface ZohoDataArrayResultRef<T> {
     readonly data: T[];
 }
 /**
- * Page result that contains an array of data and page information.
+ * Paginated API response combining a data array with page metadata.
  */
 export interface ZohoPageResult<T, I extends ZohoPageResultInfo = ZohoPageResultInfo> extends ZohoDataArrayResultRef<T> {
     /**
-     * Current page information
+     * Pagination metadata for the current page.
      */
     readonly info: I;
 }
 /**
- * Returns an empty ZohoPageResult that is typed to R and has no more records/results.
+ * Creates an empty {@link ZohoPageResult} with no data and `more_records: false`.
+ * Useful as a fallback when the API returns `null` instead of an empty result.
+ *
+ * @returns An empty page result with default pagination info
  */
 export declare function emptyZohoPageResult<T = unknown>(): ZohoPageResult<T>;
 /**
- * Page information within a ZohoPageResult
+ * Pagination metadata returned by Zoho list/search API endpoints.
  */
 export interface ZohoPageResultInfo {
     /**
@@ -48,17 +60,36 @@ export interface ZohoPageResultInfo {
     readonly more_records: boolean;
 }
 /**
- * Reference to a ZohoPageResultInfo value
+ * Reference interface for objects that expose a {@link ZohoPageResultInfo}.
  */
 export interface ZohoPageResultInfoRef {
     readonly info: ZohoPageResultInfo;
 }
+/**
+ * A fetch function that accepts paginated input and returns a {@link ZohoPageResult}.
+ * Used as the underlying data source for {@link zohoFetchPageFactory}.
+ */
 export type ZohoFetchPageFetchFunction<I extends ZohoPageFilter, R extends ZohoPageResult<any>> = (input: I) => Promise<R>;
 /**
- * Creates a FetchPageFactory using the input ZohoFetchPageFetchFunction.
+ * Creates a page factory that wraps a Zoho fetch function with automatic pagination.
+ *
+ * The factory reads `info.more_records` from each response to determine if additional
+ * pages exist, and automatically increments the `page` parameter for subsequent requests.
+ *
+ * @param fetch - The Zoho fetch function to paginate over
+ * @param defaults - Optional default configuration for the page factory
+ * @returns A page factory that produces iterable page fetchers
+ *
+ * @example
+ * ```typescript
+ * const pageFactory = zohoFetchPageFactory(zohoCrmSearchRecords(context));
+ *
+ * const fetchPage = pageFactory({ module: 'Contacts', word: 'Smith', per_page: 10 });
+ * const firstPage = await fetchPage.fetchNext();
  *
- * @param fetch
- * @param defaults
- * @returns
+ * if (firstPage.result.info.more_records) {
+ *   const secondPage = await firstPage.fetchNext();
+ * }
+ * ```
  */
 export declare function zohoFetchPageFactory<I extends ZohoPageFilter, R extends ZohoPageResult<any>>(fetch: ZohoFetchPageFetchFunction<I, R>, defaults?: Maybe<FetchPageFactoryConfigDefaults>): import("@dereekb/util/fetch").FetchPageFactory<I, R>;

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

@@ -1,35 +1,50 @@
 /**
- * Name used to identify a specific service. Always lowercase.
- *
- * I.E. recruit
+ * Lowercase identifier for a specific Zoho service (e.g. `'recruit'`, `'crm'`, `'sign'`).
  */
 export type ZohoApiServiceName = string;
 /**
- * The base URL for a Zoho API.
+ * Fully-qualified base URL for a Zoho API endpoint (e.g. `'https://www.zohoapis.com/crm'`).
  */
 export type ZohoApiUrl = string;
 /**
- * Non-expiring refresh token used to retrieve access tokens for performing API calls.
+ * Non-expiring OAuth refresh token used to retrieve short-lived access tokens.
  *
- * https://www.zoho.com/recruit/developer-guide/apiv2/oauth-overview.html
+ * Format: `'1000.abc.123'`
  *
- * Is in the format of "1000.abc.123"
+ * @see https://www.zoho.com/recruit/developer-guide/apiv2/oauth-overview.html
  */
 export type ZohoRefreshToken = string;
 /**
- * OAuth Client Id
+ * OAuth 2.0 Client ID issued by the Zoho Developer Console.
  */
 export type ZohoOAuthClientId = string;
 /**
- * OAuth Client Secret
+ * OAuth 2.0 Client Secret issued by the Zoho Developer Console.
  */
 export type ZohoOAuthClientSecret = string;
+/**
+ * Paired OAuth client credentials required for token exchange.
+ */
 export interface ZohoAuthClientIdAndSecretPair {
     readonly clientId: ZohoOAuthClientId;
     readonly clientSecret: ZohoOAuthClientSecret;
 }
+/**
+ * Well-known environment key for selecting a pre-configured Zoho API URL.
+ */
 export type ZohoApiUrlKey = 'sandbox' | 'production';
+/**
+ * Input for configuring the target Zoho API URL. Accepts either a well-known
+ * {@link ZohoApiUrlKey} (e.g. `'sandbox'`, `'production'`) or a full {@link ZohoApiUrl}.
+ */
 export type ZohoConfigApiUrlInput = ZohoApiUrlKey | ZohoApiUrl;
+/**
+ * Base configuration shared by all Zoho service configs (CRM, Recruit, Sign, Accounts).
+ */
 export interface ZohoConfig {
+    /**
+     * Target API URL, either as an environment key or a full URL.
+     * Each service resolves this to a concrete URL via its own config utility.
+     */
     readonly apiUrl?: ZohoConfigApiUrlInput;
 }

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

@@ -1,37 +1,69 @@
 import { type Maybe, type Milliseconds, type PromiseOrValue, type ResetPeriodPromiseRateLimiter } from '@dereekb/util';
 import { type FetchResponseError, type RateLimitedFetchHandler } from '@dereekb/util/fetch';
 import { type ZohoRateLimitHeaderDetails } from './zoho.error.api';
+/**
+ * Reference interface for objects that expose the shared Zoho rate limiter instance.
+ */
 export interface ZohoRateLimiterRef {
     readonly zohoRateLimiter: ResetPeriodPromiseRateLimiter;
 }
 /**
- * Function to execute when too many requests is reached.
+ * Callback invoked when a 429 Too Many Requests response is received from the Zoho API.
  *
- * Typically used for logging of some sort. Thrown errors are ignored.
+ * Typically used for logging or alerting. Any errors thrown by this function are silently ignored.
  */
 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.
+ */
 export declare const DEFAULT_ZOHO_RATE_LIMITED_TOO_MANY_REQUETS_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.
+ */
 export interface ZohoRateLimitedFetchHandlerConfig {
     /**
-     * Custom max rate limit.
+     * Custom maximum number of requests allowed per reset period.
      *
-     * Rate limits are different between account types and are described here:
+     * Defaults to {@link DEFAULT_ZOHO_API_RATE_LIMIT} (100 requests).
+     * The actual limit may be dynamically adjusted based on `X-RATELIMIT-LIMIT` response headers.
      *
-     * 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.
+     * 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;
     /**
-     * Custom reset period for the rate limiter.
+     * Custom reset period for the rate limiter in milliseconds.
      *
-     * Defaults to 1 minute in milliseconds.
+     * Defaults to {@link DEFAULT_ZOHO_API_RATE_LIMIT_RESET_PERIOD} (1 minute).
      */
     readonly resetPeriod?: Milliseconds;
     /**
-     * Optional function to execute when too many requests is reached.t
+     * Optional callback invoked when a 429 Too Many Requests response is received.
      *
-     * Defaults to the default logging function, unless false is passed.
+     * Defaults to {@link DEFAULT_ZOHO_RATE_LIMITED_TOO_MANY_REQUETS_LOG_FUNCTION}.
+     * Pass `false` to disable the callback entirely.
      */
     readonly onTooManyRequests?: ZohoRateLimitedTooManyRequestsLogFunction | false;
 }
+/**
+ * A {@link RateLimitedFetchHandler} configured with a {@link ResetPeriodPromiseRateLimiter}
+ * for Zoho API rate limiting. Exposes the underlying `_rateLimiter` for sharing across contexts.
+ */
 export type ZohoRateLimitedFetchHandler = RateLimitedFetchHandler<ResetPeriodPromiseRateLimiter>;
+/**
+ * Creates a {@link ZohoRateLimitedFetchHandler} that throttles outgoing requests based on
+ * Zoho's rate limit headers (`X-RATELIMIT-LIMIT`, `X-RATELIMIT-REMAINING`, `X-RATELIMIT-RESET`).
+ *
+ * The handler uses an exponential backoff strategy with the following behavior:
+ * - Rate limiting begins after 10% of the allowed requests have been made (`startLimitAt`)
+ * - Wait times increase exponentially (rate 1.08) as more requests are made, capped at 10 seconds
+ * - On each response, the limiter updates its remaining count and reset time from headers
+ * - When the API returns a different limit than configured, the limiter dynamically adjusts
+ * - On 429 responses, the request is automatically retried after the rate limiter delay
+ * - The limiter is disabled when responses lack rate limit headers (e.g., error responses)
+ *
+ * @param config - Optional configuration for rate limit, reset period, and 429 handling
+ * @returns A rate-limited fetch handler with the underlying rate limiter accessible via `_rateLimiter`
+ */
 export declare function zohoRateLimitedFetchHandler(config?: Maybe<ZohoRateLimitedFetchHandlerConfig>): ZohoRateLimitedFetchHandler;