@dereekb/zoho 13.4.0 → 13.4.2

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

@@ -13,15 +13,39 @@ export interface ZohoConfigServiceReaderConfig {
 export type ZohoConfigServiceReaderFunction = (configKey: string) => string;
 /**
  * Creates a new ZohoConfigServiceReaderFunction that reads from the input ConfigService.
+ *
  * @param input
+ * @returns a function that reads config values for the given Zoho service
  */
 export declare function zohoConfigServiceReaderFunction(input: ZohoConfigServiceReaderConfig): ZohoConfigServiceReaderFunction;
 export declare function zohoConfigServiceReaderFunction(serviceAccessTokenKey: ZohoServiceAccessTokenKey, configService: ConfigService): ZohoConfigServiceReaderFunction;
+export interface ReadZohoConfigFromConfigServiceConfig {
+    readonly configService: ConfigService;
+    readonly servicePrefix?: string;
+    readonly assertValid?: boolean;
+}
 /**
  * Reads the ZohoConfig config from the ConfigService.
  *
- * @param configService
- * @param prefix
+ * @param config - Configuration for reading from the config service
+ * @param configService - NestJS ConfigService to read environment variables from
+ * @param servicePrefix - optional prefix to scope config keys per service
+ * @param assertValid - whether to throw if required config values are missing
+ * @returns ZohoConfig read from environment variables
+ */
+export declare function readZohoConfigFromConfigService(config: ReadZohoConfigFromConfigServiceConfig): ZohoConfig;
+/**
+ * @deprecated Use the config object overload instead.
+ *
+ * @param configService - NestJS ConfigService to read environment variables from
+ * @param servicePrefix - optional prefix to scope config keys per service
+ * @param assertValid - whether to throw if required config values are missing
+ * @returns ZohoConfig read from environment variables
  */
 export declare function readZohoConfigFromConfigService(configService: ConfigService, servicePrefix?: string, assertValid?: boolean): ZohoConfig;
+/**
+ * Asserts that the provided ZohoConfig has a valid API URL configured.
+ *
+ * @param config - the Zoho config to validate
+ */
 export declare function assertValidZohoConfig(config: ZohoConfig): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/zoho",
-  "version": "13.4.0",
+  "version": "13.4.2",
   "exports": {
     "./nestjs": {
       "module": "./nestjs/index.esm.js",
@@ -17,8 +17,8 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/nestjs": "13.4.0",
-    "@dereekb/util": "13.4.0",
+    "@dereekb/nestjs": "13.4.2",
+    "@dereekb/util": "13.4.2",
     "@nestjs/common": "^11.1.16",
     "@nestjs/config": "^4.0.3",
     "express": "^5.0.0",

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

@@ -26,23 +26,23 @@ export interface ZohoAccountsAccessTokenResponse {
     /**
      * Short-lived OAuth access token for authenticating API calls.
      */
-    access_token: ZohoAccessTokenString;
+    readonly access_token: ZohoAccessTokenString;
     /**
      * Comma-separated list of OAuth scopes granted to this token.
      */
-    scope: ZohoAccessTokenScopesString;
+    readonly scope: ZohoAccessTokenScopesString;
     /**
      * The API domain to use for subsequent API calls (e.g. `'https://www.zohoapis.com'`).
      */
-    api_domain: ZohoAccessTokenApiDomain;
+    readonly api_domain: ZohoAccessTokenApiDomain;
     /**
      * Token type, always `'Bearer'`.
      */
-    token_type: 'Bearer';
+    readonly token_type: 'Bearer';
     /**
      * Number of seconds until the access token expires.
      */
-    expires_in: Seconds;
+    readonly expires_in: Seconds;
 }
 /**
  * Error response from the Zoho OAuth token endpoint when the refresh fails.
@@ -169,5 +169,9 @@ export type ZohoAccountsRefreshTokenFromAuthorizationCodeFunction = (input: Zoho
 export declare function zohoAccountsRefreshTokenFromAuthorizationCode(context: ZohoAccountsContext): ZohoAccountsRefreshTokenFromAuthorizationCodeFunction;
 /**
  * Constructs a standard {@link FetchJsonInput} for Zoho Accounts API calls with the given HTTP method and optional body.
+ *
+ * @param method - HTTP method to use for the request
+ * @param body - Optional request body to include
+ * @returns Configured fetch input for the Zoho Accounts API call
  */
 export declare function zohoAccountsApiFetchJsonInput(method: string, body?: FetchJsonBody): FetchJsonInput;

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

@@ -16,6 +16,12 @@ export declare const ZOHO_ACCOUNTS_US_API_URL = "https://accounts.zoho.com";
 export type ZohoAccountsApiUrl = ZohoApiUrl;
 export type ZohoAccountsApiUrlKey = 'us';
 export type ZohoAccountsConfigApiUrlInput = ZohoAccountsApiUrlKey | ZohoAccountsApiUrl;
+/**
+ * Resolves a Zoho Accounts API URL input to the full base URL. The 'us' key maps to the US datacenter; custom URLs pass through unchanged.
+ *
+ * @param input - A well-known datacenter key or a custom Zoho Accounts API URL
+ * @returns The resolved full Zoho Accounts API base URL
+ */
 export declare function zohoAccountsConfigApiUrl(input: ZohoAccountsConfigApiUrlInput): ZohoApiUrl;
 /**
  * Configuration for ZohoAccounts.
@@ -30,10 +36,10 @@ export interface ZohoAccountsConfig extends ZohoConfig, ZohoAuthClientIdAndSecre
      */
     readonly accessTokenCache?: Maybe<ZohoAccessTokenCache>;
 }
-export interface ZohoAccountsFetchFactoryInput {
+export interface ZohoAccountsFetchFactoryParams {
     readonly apiUrl: ZohoApiUrl;
 }
-export type ZohoAccountsFetchFactory = FactoryWithRequiredInput<ConfiguredFetch, ZohoAccountsFetchFactoryInput>;
+export type ZohoAccountsFetchFactory = FactoryWithRequiredInput<ConfiguredFetch, ZohoAccountsFetchFactoryParams>;
 export interface ZohoAccountsContext {
     readonly fetch: ConfiguredFetch;
     readonly fetchJson: FetchJsonFunction;
@@ -43,3 +49,7 @@ export interface ZohoAccountsContext {
 export interface ZohoAccountsContextRef {
     readonly accountsContext: ZohoAccountsContext;
 }
+/**
+ * @deprecated use ZohoAccountsFetchFactoryParams instead.
+ */
+export type ZohoAccountsFetchFactoryInput = ZohoAccountsFetchFactoryParams;

package/src/lib/accounts/accounts.d.ts

@@ -1,4 +1,4 @@
-import { type Maybe } from '@dereekb/util';
+import { type Maybe, type Seconds } from '@dereekb/util';
 import { type ZohoApiServiceName } from '../zoho.config';
 /**
  * Arbitrary key used to identify a specific service's access token. Typically coincides with the ZohoApiServiceName.
@@ -30,9 +30,9 @@ export interface ZohoAccessToken {
     readonly scope: ZohoAccessTokenScopesString;
     readonly apiDomain: ZohoAccessTokenApiDomain;
     /**
-     * Length of time the token is valid for.
+     * Length of time the token is valid for, in seconds.
      */
-    readonly expiresIn: number;
+    readonly expiresIn: Seconds;
     /**
      * Date the token expires at.
      */
@@ -80,5 +80,8 @@ export type ZohoAccessTokenRefresher = ZohoAccessTokenFactory;
 export type ZohoAccessTokenStringFactory = () => Promise<ZohoAccessTokenString>;
 /**
  * Generates a new ZohoAccessTokenStringFactory.
+ *
+ * @param zohoAccessTokenFactory - Factory that produces ZohoAccessToken instances
+ * @returns A factory function that resolves to the access token string
  */
 export declare function zohoAccessTokenStringFactory(zohoAccessTokenFactory: ZohoAccessTokenFactory): ZohoAccessTokenStringFactory;

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

@@ -22,7 +22,20 @@ export declare class ZohoAccountsAuthFailureError extends FetchRequestFactoryErr
     constructor(reason?: string | undefined);
 }
 export declare const logZohoAccountsErrorToConsole: import("..").LogZohoServerErrorFunction;
+/**
+ * Parses a fetch response error into a typed Zoho Accounts 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 parseZohoAccountsError(responseError: FetchResponseError): Promise<ParsedZohoServerError>;
+/**
+ * Parses a Zoho Accounts error response body into a typed error. Handles account-specific error codes before falling back to the generic Zoho error parser.
+ *
+ * @param errorResponseData - The raw error response data from the Zoho Accounts 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 parseZohoAccountsServerErrorResponseData(errorResponseData: ZohoServerErrorResponseData, responseError: FetchResponseError): ParsedZohoServerError;
 export declare const interceptZohoAccounts200StatusWithErrorResponse: import("@dereekb/util/fetch").FetchJsonInterceptJsonResponseFunction;
 export declare const handleZohoAccountsErrorFetch: import("..").HandleZohoErrorFetchFactory;

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

@@ -16,11 +16,11 @@ export interface ZohoAccountsFactoryConfig {
      * Custom fetch factory for creating the underlying HTTP client.
      * Defaults to a standard fetch service with JSON content headers and a 20-second timeout.
      */
-    fetchFactory?: ZohoAccountsFetchFactory;
+    readonly fetchFactory?: ZohoAccountsFetchFactory;
     /**
      * Custom error logging function invoked when Zoho API errors are encountered.
      */
-    logZohoServerErrorFunction?: LogZohoServerErrorFunction;
+    readonly logZohoServerErrorFunction?: LogZohoServerErrorFunction;
 }
 /**
  * Factory function that creates a {@link ZohoAccounts} client from a {@link ZohoAccountsConfig}.

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

@@ -860,10 +860,16 @@ export type ZohoCrmExecuteRestApiFunctionFunction = (input: ZohoCrmExecuteRestAp
 export declare function zohoCrmExecuteRestApiFunction(context: ZohoCrmContext): ZohoCrmExecuteRestApiFunctionFunction;
 /**
  * Builds URL search params from the input objects, omitting the `module` key since it is used in the URL path rather than as a query parameter.
+ *
+ * @param input - One or more objects to convert into URL search parameters
+ * @returns URL search params string with the `module` key excluded
  */
 export declare function zohoCrmUrlSearchParamsMinusModule(...input: Maybe<object | Record<string, string | number>>[]): URLSearchParams;
 /**
  * Builds URL search params from the input objects, omitting both `id` and `module` keys since they are used in the URL path.
+ *
+ * @param input - One or more objects to convert into URL search parameters
+ * @returns URL search params string with `id` and `module` keys excluded
  */
 export declare function zohoCrmUrlSearchParamsMinusIdAndModule(...input: Maybe<object | Record<string, string | number>>[]): URLSearchParams;
 /**
@@ -872,12 +878,19 @@ export declare function zohoCrmUrlSearchParamsMinusIdAndModule(...input: Maybe<o
 export declare const zohoCrmUrlSearchParams: typeof makeUrlSearchParams;
 /**
  * Constructs the standard FetchJsonInput used by CRM API calls, pairing the HTTP method with an optional body.
+ *
+ * @param method - HTTP method to use for the request
+ * @param body - Optional request body to include
+ * @returns Configured fetch input for the Zoho CRM API call
  */
 export declare function zohoCrmApiFetchJsonInput(method: string, body?: Maybe<FetchJsonBody>): FetchJsonInput;
 /**
  * Catches ZohoServerFetchResponseDataArrayError and returns the error data array as the response data, as each data element will have the error details.
  *
  * Use to catch errors from functions that return ZohoCrmChangeObjectLikeResponse and pass the result to zohoCrmChangeObjectLikeResponseSuccessAndErrorPairs.
+ *
+ * @param e - The error to catch and potentially convert
+ * @returns The error data array wrapped as a change object response
  */
 export declare function zohoCrmCatchZohoCrmChangeObjectLikeResponseError<R extends ZohoCrmChangeObjectLikeResponse<any>>(e: unknown): R;
 export type ZohoCrmChangeObjectLikeResponse<T extends ZohoCrmChangeObjectLikeResponseEntry = ZohoCrmChangeObjectLikeResponseEntry> = ZohoDataArrayResultRef<T>;

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

@@ -28,6 +28,9 @@ export type ZohoCrmCreateNotesFunction = (input: ZohoCrmCreateNotesRequest) => P
  * Creates notes directly in the CRM Notes module. Each note must include the parent record reference and module name.
  *
  * For creating notes associated with a specific record, prefer {@link zohoCrmCreateNotesForRecord} which handles parent binding automatically.
+ *
+ * @param context - Authenticated Zoho CRM context for making API calls
+ * @returns Function that creates notes in the CRM Notes module
  */
 export declare function zohoCrmCreateNotes(context: ZohoCrmContext): (input: ZohoCrmCreateNotesRequest) => Promise<ZohoCrmMultiRecordResult<NewZohoCrmNoteData, ZohoCrmChangeObjectResponseSuccessEntry<import("./crm").ZohoCrmChangeObjectDetails>, ZohoCrmChangeObjectResponseErrorEntry>>;
 /**
@@ -47,6 +50,9 @@ export type ZohoCrmDeleteNotesResponse = ZohoCrmChangeObjectResponse;
 export type ZohoCrmDeleteNotesFunction = (input: ZohoCrmDeleteNotesRequest) => Promise<ZohoCrmDeleteNotesResult>;
 /**
  * Deletes one or more notes from the CRM Notes module by their IDs.
+ *
+ * @param context - Authenticated Zoho CRM context for making API calls
+ * @returns Function that deletes notes by their IDs
  */
 export declare function zohoCrmDeleteNotes(context: ZohoCrmContext): (input: ZohoCrmDeleteNotesRequest) => Promise<ZohoCrmMultiRecordResult<string, ZohoCrmChangeObjectResponseSuccessEntry<import("./crm").ZohoCrmChangeObjectDetails>, ZohoCrmChangeObjectResponseErrorEntry>>;
 /**
@@ -60,11 +66,17 @@ export type ZohoCrmGetNotesForRecordResponse = ZohoPageResult<ZohoCrmRecordNote>
 export type ZohoCrmGetNotesForRecordFunction = (input: ZohoCrmGetNotesForRecordRequest) => Promise<ZohoCrmGetNotesForRecordResponse>;
 /**
  * Retrieves paginated notes associated with a specific CRM record using the related records API.
+ *
+ * @param context - Authenticated Zoho CRM context for making API calls
+ * @returns Function that retrieves notes for a specific record
  */
 export declare function zohoCrmGetNotesForRecord(context: ZohoCrmContext): ZohoCrmGetNotesForRecordFunction;
 export type ZohoCrmGetNotesForRecordPageFactory = FetchPageFactory<ZohoCrmGetNotesForRecordRequest, ZohoCrmGetNotesForRecordResponse>;
 /**
  * Creates a page factory for iterating through all notes for a record across multiple pages.
+ *
+ * @param context - Authenticated Zoho CRM context for making API calls
+ * @returns Page factory for paginating through notes for a record
  */
 export declare function zohoCrmGetNotesForRecordPageFactory(context: ZohoCrmContext): ZohoCrmGetNotesForRecordPageFactory;
 /**
@@ -79,5 +91,8 @@ export type ZohoCrmCreateNotesForRecordFunction = (input: ZohoCrmCreateNotesForR
  * Creates notes for a specific record, automatically binding the parent module and record ID to each note entry.
  *
  * https://www.zoho.com/crm/developer/docs/api/v8/create-notes.html
+ *
+ * @param context - Authenticated Zoho CRM context for making API calls
+ * @returns Function that creates notes bound to a specific record
  */
 export declare function zohoCrmCreateNotesForRecord(context: ZohoCrmContext): ZohoCrmCreateNotesForRecordFunction;

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

@@ -31,6 +31,9 @@ export type ZohoCrmCreateTagsResult = ZohoCrmMultiRecordResult<ZohoCrmCreateTagD
 export type ZohoCrmCreateTagsFunction = (input: ZohoCrmCreateTagsRequest) => Promise<ZohoCrmCreateTagsResult>;
 /**
  * Creates one or more tags for a CRM module. Duplicate tag errors are separated from other errors in the result to simplify idempotent workflows.
+ *
+ * @param context - Authenticated Zoho CRM context for making API calls
+ * @returns Function that creates tags for a module
  */
 export declare function zohoCrmCreateTagsForModule(context: ZohoCrmContext): (input: ZohoCrmCreateTagsRequest) => Promise<{
     errorItems: ZohoCrmMultiRecordResultEntry<ZohoCrmCreateTagData, ZohoCrmChangeObjectResponseErrorEntry>[];
@@ -67,8 +70,8 @@ export type ZohoCrmDeleteTagFunction = (input: ZohoCrmDeleteTagRequest) => Promi
  *
  * https://www.zoho.com/crm/developer/docs/api/v8/delete-tag.html
  *
- * @param context
- * @returns
+ * @param context - Authenticated Zoho CRM context for making API calls
+ * @returns Function that deletes a tag by ID
  */
 export declare function zohoCrmDeleteTag(context: ZohoCrmContext): ZohoCrmDeleteTagFunction;
 /**
@@ -93,13 +96,16 @@ export type ZohoCrmGetTagsFunction = (input: ZohoCrmGetTagsRequest) => Promise<Z
  *
  * https://www.zoho.com/crm/developer-guide/apiv2/get-tag-list.html
  *
- * @param context
- * @returns
+ * @param context - Authenticated Zoho CRM context for making API calls
+ * @returns Function that retrieves tags for a module
  */
 export declare function zohoCrmGetTagsForModule(context: ZohoCrmContext): ZohoCrmGetTagsFunction;
 export type ZohoCrmGetTagsForModulePageFactory = (input: ZohoCrmGetTagsRequest, options?: Maybe<FetchPageFactoryOptions<ZohoCrmGetTagsRequest, ZohoCrmGetTagsResult>>) => FetchPage<ZohoCrmGetTagsRequest, ZohoCrmGetTagsResult>;
 /**
  * Creates a page factory for iterating through all tags in a module across multiple pages.
+ *
+ * @param context - Authenticated Zoho CRM context for making API calls
+ * @returns Page factory for paginating through tags in a module
  */
 export declare function zohoCrmGetTagsForModulePageFactory(context: ZohoCrmContext): ZohoCrmGetTagsForModulePageFactory;
 /**
@@ -165,12 +171,15 @@ export type ZohoCrmAddTagsToRecordsFunction = (input: ZohoCrmAddTagsToRecordsReq
  *
  * https://www.zoho.com/crm/developer-guide/apiv2/add-tags.html
  *
- * @param context
- * @returns
+ * @param context - Authenticated Zoho CRM context for making API calls
+ * @returns Function that adds tags to records
  */
 export declare function zohoCrmAddTagsToRecords(context: ZohoCrmContext): ZohoCrmAddTagsToRecordsFunction;
 /**
  * Builds the request body for the add/remove tags endpoints, merging `tag_names` into `tags` and enforcing the max ID limit.
+ *
+ * @param input - The add/remove tags request containing tag names, tag objects, and record IDs
+ * @returns The formatted request body with merged tags and record IDs
  */
 export declare function zohoCrmAddTagsToRecordsRequestBody(input: ZohoCrmAddTagsToRecordsRequest): {
     tags: (ZohoCrmTagData & {
@@ -217,7 +226,7 @@ export type ZohoCrmRemoveTagsFromRecordsFunction = (input: ZohoCrmRemoveTagsFrom
  *
  * https://www.zoho.com/crm/developer-guide/apiv2/remove-tags.html
  *
- * @param context
- * @returns
+ * @param context - Authenticated Zoho CRM context for making API calls
+ * @returns Function that removes tags from records
  */
 export declare function zohoCrmRemoveTagsFromRecords(context: ZohoCrmContext): ZohoCrmRemoveTagsFromRecordsFunction;

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

@@ -21,6 +21,9 @@ export type ZohoCrmApiUrlKey = ZohoApiUrlKey;
 export type ZohoCrmConfigApiUrlInput = ZohoCrmApiUrlKey | ZohoCrmApiUrl;
 /**
  * Resolves a CRM API URL input to its full base URL. Well-known keys ('sandbox', 'production') map to their respective Zoho CRM endpoints; custom URLs pass through unchanged.
+ *
+ * @param input - A well-known environment key or a custom CRM API URL
+ * @returns The resolved full Zoho CRM API base URL
  */
 export declare function zohoCrmConfigApiUrl(input: ZohoCrmConfigApiUrlInput): ZohoApiUrl;
 /**
@@ -30,13 +33,13 @@ export type ZohoCrmConfig = ZohoConfig;
 /**
  * Input provided to a CRM fetch factory to construct an authenticated fetch instance for a specific API base URL.
  */
-export interface ZohoCrmFetchFactoryInput {
+export interface ZohoCrmFetchFactoryParams {
     readonly apiUrl: ZohoCrmApiUrl;
 }
 /**
  * Factory that produces a pre-configured fetch instance bound to a specific Zoho CRM API URL, used to customize HTTP transport (e.g., timeouts, headers).
  */
-export type ZohoCrmFetchFactory = FactoryWithRequiredInput<ConfiguredFetch, ZohoCrmFetchFactoryInput>;
+export type ZohoCrmFetchFactory = FactoryWithRequiredInput<ConfiguredFetch, ZohoCrmFetchFactoryParams>;
 /**
  * Core context for making authenticated Zoho CRM API calls. Bundles the configured fetch, JSON parsing, access token management, rate limiting, and service configuration needed by all CRM operations.
  */
@@ -52,3 +55,7 @@ export interface ZohoCrmContext extends ZohoRateLimiterRef {
 export interface ZohoCrmContextRef {
     readonly crmContext: ZohoCrmContext;
 }
+/**
+ * @deprecated use ZohoCrmFetchFactoryParams instead.
+ */
+export type ZohoCrmFetchFactoryInput = ZohoCrmFetchFactoryParams;

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