@dereekb/zoho 13.3.1 → 13.4.1

package/nestjs/src/lib/sign/webhook/index.d.ts

@@ -0,0 +1,6 @@
+export * from './webhook.zoho.sign';
+export * from './webhook.zoho.sign.config';
+export * from './webhook.zoho.sign.controller';
+export * from './webhook.zoho.sign.module';
+export * from './webhook.zoho.sign.service';
+export * from './webhook.zoho.sign.verify';

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

@@ -0,0 +1,11 @@
+export declare const ZOHO_SIGN_WEBHOOK_SECRET_TOKEN_ENV_VAR = "ZOHO_SIGN_WEBHOOK_SECRET_TOKEN";
+export interface ZohoSignWebhookConfig {
+    readonly webhookSecret: string;
+}
+/**
+ * Configuration for the Zoho Sign webhook service.
+ */
+export declare abstract class ZohoSignWebhookServiceConfig {
+    readonly zohoSignWebhook: ZohoSignWebhookConfig;
+    static assertValidConfig(config: ZohoSignWebhookServiceConfig): void;
+}

package/nestjs/src/lib/sign/webhook/webhook.zoho.sign.controller.d.ts

@@ -0,0 +1,8 @@
+import { type RawBodyBuffer } from '@dereekb/nestjs';
+import { type Request } from 'express';
+import { ZohoSignWebhookService } from './webhook.zoho.sign.service';
+export declare class ZohoSignWebhookController {
+    private readonly _zohoSignWebhookService;
+    constructor(zohoSignWebhookService: ZohoSignWebhookService);
+    handleZohoSignWebhook(req: Request, rawBody: RawBodyBuffer): Promise<void>;
+}

package/nestjs/src/lib/sign/webhook/webhook.zoho.sign.d.ts

@@ -0,0 +1,127 @@
+import { type HandlerBindAccessor, type HandlerMappedSetFunction, type Handler, type EmailAddress } from '@dereekb/util';
+import { type ZohoSignRequestId, type ZohoSignDocumentId, type ZohoSignActionId, type ZohoSignRequestStatus, type ZohoSignRequestTypeId } from '@dereekb/zoho';
+/**
+ * Zoho Sign webhook operation type constants.
+ *
+ * These correspond to the `operation_type` field in the webhook `notifications` payload.
+ */
+export type ZohoSignWebhookOperationType = 'RequestSubmitted' | 'RequestViewed' | 'RequestSigningSuccess' | 'RequestCompleted' | 'RequestRejected' | 'RequestRecalled' | 'RequestForwarded' | 'RequestExpired';
+/**
+ * The `notifications` portion of a Zoho Sign webhook payload.
+ *
+ * Contains details about the action performed on the document.
+ */
+export interface ZohoSignWebhookNotification {
+    /**
+     * Email address of the person who performed the operation.
+     */
+    readonly performed_by_email: EmailAddress;
+    /**
+     * Name of the person who performed the operation.
+     */
+    readonly performed_by_name: string;
+    /**
+     * Timestamp of the operation in Java milliseconds.
+     */
+    readonly performed_at: number;
+    /**
+     * Reason stated for the operation, if applicable.
+     */
+    readonly reason?: string;
+    /**
+     * Short description of the activity performed.
+     */
+    readonly activity: string;
+    /**
+     * The type of operation that triggered this webhook.
+     */
+    readonly operation_type: ZohoSignWebhookOperationType;
+    /**
+     * Sign action ID of the signer.
+     *
+     * Present for signer-related actions: RequestViewed, RequestSigningSuccess,
+     * RequestRejected, and RequestForwarded.
+     */
+    readonly action_id?: ZohoSignActionId;
+    /**
+     * IP address captured during this operation.
+     */
+    readonly ip_address?: string;
+}
+/**
+ * A document reference within the webhook request data.
+ */
+export interface ZohoSignWebhookDocumentRef {
+    readonly document_name: string;
+    readonly document_id: ZohoSignDocumentId;
+}
+/**
+ * The `requests` portion of a Zoho Sign webhook payload.
+ *
+ * Contains details about the document for which the webhook was triggered.
+ */
+export interface ZohoSignWebhookRequestData {
+    readonly request_status: ZohoSignRequestStatus;
+    readonly request_name: string;
+    readonly request_id: ZohoSignRequestId;
+    readonly org_id?: string;
+    readonly request_type_id?: ZohoSignRequestTypeId;
+    readonly document_ids: ZohoSignWebhookDocumentRef[];
+}
+/**
+ * The complete webhook payload from Zoho Sign.
+ *
+ * Contains two top-level keys: `notifications` (the action details) and
+ * `requests` (the document details).
+ *
+ * @example
+ * ```json
+ * {
+ *   "notifications": {
+ *     "performed_by_email": "testuser@zoho.com",
+ *     "performed_at": 1555062604837,
+ *     "activity": "Document has been signed",
+ *     "operation_type": "RequestSigningSuccess",
+ *     "action_id": "1000000000090",
+ *     "performed_by_name": "test user"
+ *   },
+ *   "requests": {
+ *     "request_name": "NDA Document",
+ *     "request_id": "1000000000000",
+ *     "request_status": "inprogress",
+ *     "document_ids": [{ "document_name": "CommonNDA.pdf", "document_id": "100000000000050" }]
+ *   }
+ * }
+ * ```
+ */
+export interface ZohoSignWebhookPayload {
+    readonly notifications: ZohoSignWebhookNotification;
+    readonly requests: ZohoSignWebhookRequestData;
+}
+/**
+ * A parsed Zoho Sign webhook event, providing convenient access to the operation type.
+ */
+export type ZohoSignWebhookEvent<T extends ZohoSignWebhookOperationType = ZohoSignWebhookOperationType> = ZohoSignWebhookPayload & {
+    readonly operationType: T;
+};
+/**
+ * Creates a {@link ZohoSignWebhookEvent} from a raw payload.
+ *
+ * @param payload - the raw Zoho Sign webhook payload to convert
+ * @returns a webhook event with the operation type extracted for convenience
+ */
+export declare function zohoSignWebhookEvent(payload: ZohoSignWebhookPayload): ZohoSignWebhookEvent;
+export type ZohoSignEventHandler = Handler<ZohoSignWebhookEvent, ZohoSignWebhookOperationType>;
+export declare const zohoSignEventHandlerFactory: import("@dereekb/util").HandlerFactory<ZohoSignWebhookEvent<ZohoSignWebhookOperationType>, ZohoSignWebhookOperationType, boolean>;
+export type ZohoSignHandlerMappedSetFunction<T extends ZohoSignWebhookOperationType = ZohoSignWebhookOperationType> = HandlerMappedSetFunction<ZohoSignWebhookEvent<T>>;
+export interface ZohoSignEventHandlerConfigurer extends HandlerBindAccessor<ZohoSignWebhookEvent, ZohoSignWebhookOperationType> {
+    readonly handleRequestSubmitted: ZohoSignHandlerMappedSetFunction<'RequestSubmitted'>;
+    readonly handleRequestViewed: ZohoSignHandlerMappedSetFunction<'RequestViewed'>;
+    readonly handleRequestSigningSuccess: ZohoSignHandlerMappedSetFunction<'RequestSigningSuccess'>;
+    readonly handleRequestCompleted: ZohoSignHandlerMappedSetFunction<'RequestCompleted'>;
+    readonly handleRequestRejected: ZohoSignHandlerMappedSetFunction<'RequestRejected'>;
+    readonly handleRequestRecalled: ZohoSignHandlerMappedSetFunction<'RequestRecalled'>;
+    readonly handleRequestForwarded: ZohoSignHandlerMappedSetFunction<'RequestForwarded'>;
+    readonly handleRequestExpired: ZohoSignHandlerMappedSetFunction<'RequestExpired'>;
+}
+export declare const zohoSignEventHandlerConfigurerFactory: import("@dereekb/util").HandlerConfigurerFactory<ZohoSignEventHandlerConfigurer, ZohoSignWebhookEvent<ZohoSignWebhookOperationType>, ZohoSignWebhookOperationType, boolean>;

package/nestjs/src/lib/sign/webhook/webhook.zoho.sign.module.d.ts

@@ -0,0 +1,13 @@
+import { ZohoSignWebhookServiceConfig } from './webhook.zoho.sign.config';
+import { ConfigService } from '@nestjs/config';
+/**
+ * Reads the Zoho Sign webhook secret from the NestJS ConfigService
+ * and returns a validated webhook service config.
+ *
+ * @param configService - NestJS config service populated with webhook environment variables
+ * @returns Validated Zoho Sign webhook service configuration
+ * @throws {Error} If the webhook secret is not configured
+ */
+export declare function zohoSignWebhookServiceConfigFactory(configService: ConfigService): ZohoSignWebhookServiceConfig;
+export declare class ZohoSignWebhookModule {
+}

package/nestjs/src/lib/sign/webhook/webhook.zoho.sign.service.d.ts

@@ -0,0 +1,16 @@
+import { type Request } from 'express';
+import { type ZohoSignWebhookEvent, type ZohoSignWebhookOperationType } from './webhook.zoho.sign';
+import { type Handler } from '@dereekb/util';
+import { ZohoSignWebhookServiceConfig } from './webhook.zoho.sign.config';
+/**
+ * Service that handles Zoho Sign webhook events.
+ */
+export declare class ZohoSignWebhookService {
+    private readonly logger;
+    private readonly _verifier;
+    readonly handler: Handler<ZohoSignWebhookEvent, ZohoSignWebhookOperationType>;
+    readonly configure: import("@dereekb/util").HandlerConfigurer<import("./webhook.zoho.sign").ZohoSignEventHandlerConfigurer, ZohoSignWebhookEvent<ZohoSignWebhookOperationType>, ZohoSignWebhookOperationType, boolean>;
+    constructor(zohoSignWebhookServiceConfig: ZohoSignWebhookServiceConfig);
+    updateForWebhook(req: Request, rawBody: Buffer): Promise<void>;
+    updateForZohoSignEvent(event: ZohoSignWebhookEvent): Promise<void>;
+}

package/nestjs/src/lib/sign/webhook/webhook.zoho.sign.verify.d.ts

@@ -0,0 +1,45 @@
+import { type Request } from 'express';
+import { type ZohoSignWebhookEvent } from './webhook.zoho.sign';
+/**
+ * Header name used by Zoho Sign to send the HMAC signature.
+ */
+export declare const ZOHO_SIGN_WEBHOOK_SIGNATURE_HEADER = "x-zs-webhook-signature";
+export interface ZohoSignWebhookVerificationConfig {
+    /**
+     * Secret key configured in Zoho Sign webhook settings.
+     */
+    readonly secret: string;
+}
+export type ZohoSignWebhookEventVerificationResult = ZohoSignWebhookEventVerificationSuccessResult | ZohoSignWebhookEventVerificationErrorResult;
+export interface ZohoSignWebhookEventVerificationSuccessResult {
+    readonly valid: true;
+    readonly event: ZohoSignWebhookEvent;
+}
+export interface ZohoSignWebhookEventVerificationErrorResult {
+    readonly valid: false;
+}
+/**
+ * Function that verifies a Zoho Sign webhook event.
+ */
+export type ZohoSignWebhookEventVerifier = (req: Request, rawBody: Buffer) => Promise<ZohoSignWebhookEventVerificationResult>;
+/**
+ * Creates a verifier for Zoho Sign webhook events using HMAC-SHA256 signature verification.
+ *
+ * Zoho Sign computes `base64(HMAC-SHA256(payload, secret))` and sends the result
+ * in the `X-ZS-WEBHOOK-SIGNATURE` header. This verifier recomputes the signature
+ * from the raw request body and compares using timing-safe equality.
+ *
+ * @param config - Configuration containing the webhook secret key
+ * @returns A function that verifies webhook requests
+ *
+ * @example
+ * ```typescript
+ * const verifier = zohoSignWebhookEventVerifier({ secret: 'my-secret-key' });
+ * const result = await verifier(req, rawBody);
+ *
+ * if (result.valid) {
+ *   console.log(result.event.operationType);
+ * }
+ * ```
+ */
+export declare function zohoSignWebhookEventVerifier(config: ZohoSignWebhookVerificationConfig): ZohoSignWebhookEventVerifier;

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.3.1",
+  "version": "13.4.1",
   "exports": {
     "./nestjs": {
       "module": "./nestjs/index.esm.js",
@@ -17,9 +17,11 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/util": "13.3.1",
+    "@dereekb/nestjs": "13.4.1",
+    "@dereekb/util": "13.4.1",
     "@nestjs/common": "^11.1.16",
     "@nestjs/config": "^4.0.3",
+    "express": "^5.0.0",
     "make-error": "^1.3.0"
   },
   "devDependencies": {

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;