@dereekb/zoho 13.0.5 → 13.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/zoho",
-  "version": "13.0.5",
+  "version": "13.0.7",
   "exports": {
     "./nestjs": {
       "module": "./nestjs/index.esm.js",
@@ -17,7 +17,7 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/util": "13.0.5",
+    "@dereekb/util": "13.0.7",
     "@nestjs/common": "^11.0.0",
     "@nestjs/config": "^4.0.0",
     "make-error": "^1.3.0"

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

@@ -4,24 +4,170 @@ import { type ZohoAuthClientIdAndSecretPair, type ZohoRefreshToken } from '../zo
 import { type ZohoAccessTokenApiDomain, type ZohoAccessTokenScopesString, type ZohoAccessTokenString } from './accounts';
 import { type Maybe, type Seconds } from '@dereekb/util';
 import { type ZohoAccountsAccessTokenErrorCode } from './accounts.error.api';
+/**
+ * Optional overrides for the access token request. When omitted, values
+ * are read from the {@link ZohoAccountsContext}'s config.
+ */
 export interface ZohoAccountsAccessTokenInput {
+    /**
+     * Override client credentials. Falls back to the context config's `clientId`/`clientSecret`.
+     */
     readonly client?: Maybe<ZohoAuthClientIdAndSecretPair>;
+    /**
+     * Override refresh token. Falls back to the context config's `refreshToken`.
+     */
     readonly refreshToken?: Maybe<ZohoRefreshToken>;
 }
+/**
+ * Successful response from the Zoho OAuth `/oauth/v2/token` endpoint
+ * when exchanging a refresh token for a new access token.
+ */
 export interface ZohoAccountsAccessTokenResponse {
+    /**
+     * Short-lived OAuth access token for authenticating API calls.
+     */
     access_token: ZohoAccessTokenString;
+    /**
+     * Comma-separated list of OAuth scopes granted to this token.
+     */
     scope: ZohoAccessTokenScopesString;
+    /**
+     * The API domain to use for subsequent API calls (e.g. `'https://www.zohoapis.com'`).
+     */
     api_domain: ZohoAccessTokenApiDomain;
+    /**
+     * Token type, always `'Bearer'`.
+     */
     token_type: 'Bearer';
+    /**
+     * Number of seconds until the access token expires.
+     */
     expires_in: Seconds;
 }
+/**
+ * Error response from the Zoho OAuth token endpoint when the refresh fails.
+ */
 export interface ZohoAccountsAccessTokenErrorResponse {
+    /**
+     * Error code indicating the reason for failure (e.g. `'invalid_code'`, `'invalid_client'`).
+     */
     error: ZohoAccountsAccessTokenErrorCode;
 }
 /**
- * Trades a refresh token for a new AccessToken
- * @param context
- * @returns
+ * Creates a function that exchanges a refresh token for a new short-lived access token
+ * via the Zoho OAuth `/oauth/v2/token` endpoint.
+ *
+ * The returned function accepts optional overrides for client credentials and refresh token.
+ * When omitted, values are read from the {@link ZohoAccountsContext}'s config.
+ *
+ * @param context - Authenticated Zoho Accounts context providing fetch and config
+ * @returns Function that exchanges a refresh token for an access token
+ *
+ * @example
+ * ```typescript
+ * const getAccessToken = zohoAccountsAccessToken(accountsContext);
+ *
+ * // Using config defaults:
+ * const { access_token, expires_in } = await getAccessToken();
+ *
+ * // With overrides:
+ * const response = await getAccessToken({
+ *   client: { clientId: 'other-id', clientSecret: 'other-secret' },
+ *   refreshToken: 'other-refresh-token'
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/accounts/protocol/oauth/web-apps/access-token-expiry.html
  */
 export declare function zohoAccountsAccessToken(context: ZohoAccountsContext): (input?: ZohoAccountsAccessTokenInput) => Promise<ZohoAccountsAccessTokenResponse>;
+/**
+ * OAuth authorization code received from the Zoho authorization server
+ * after the user grants consent. Single-use and short-lived.
+ */
+export type ZohoAuthorizationCode = string;
+/**
+ * Input for exchanging an authorization code for a refresh token and initial access token.
+ */
+export interface ZohoAccountsRefreshTokenFromAuthorizationCodeInput {
+    /**
+     * Override client credentials. Falls back to the context config's `clientId`/`clientSecret`.
+     */
+    readonly client?: Maybe<ZohoAuthClientIdAndSecretPair>;
+    /**
+     * The single-use authorization code obtained from the Zoho consent flow.
+     */
+    readonly code: ZohoAuthorizationCode;
+    /**
+     * The redirect URI registered in the Zoho API console.
+     * Must exactly match the URI used during the authorization request.
+     */
+    readonly redirectUri: string;
+}
+/**
+ * Successful response from the Zoho OAuth `/oauth/v2/token` endpoint
+ * when exchanging an authorization code for tokens.
+ */
+export interface ZohoAccountsRefreshTokenFromAuthorizationCodeResponse {
+    /**
+     * Short-lived OAuth access token for authenticating API calls.
+     */
+    readonly access_token: ZohoAccessTokenString;
+    /**
+     * Long-lived refresh token for obtaining new access tokens.
+     * Only included if `access_type=offline` was passed during the authorization request.
+     */
+    readonly refresh_token?: ZohoRefreshToken;
+    /**
+     * Comma-separated list of OAuth scopes granted to this token.
+     */
+    readonly scope: ZohoAccessTokenScopesString;
+    /**
+     * The API domain to use for subsequent API calls (e.g. `'https://www.zohoapis.com'`).
+     */
+    readonly api_domain: ZohoAccessTokenApiDomain;
+    /**
+     * Token type, always `'Bearer'`.
+     */
+    readonly token_type: 'Bearer';
+    /**
+     * Number of seconds until the access token expires (typically 3600).
+     */
+    readonly expires_in: Seconds;
+}
+/**
+ * Exchanges a single-use authorization code for tokens.
+ */
+export type ZohoAccountsRefreshTokenFromAuthorizationCodeFunction = (input: ZohoAccountsRefreshTokenFromAuthorizationCodeInput) => Promise<ZohoAccountsRefreshTokenFromAuthorizationCodeResponse>;
+/**
+ * Creates a function that exchanges a single-use OAuth authorization code for
+ * an access token and (optionally) a long-lived refresh token via the Zoho
+ * `/oauth/v2/token` endpoint with `grant_type=authorization_code`.
+ *
+ * This is the second step of the Zoho OAuth 2.0 web server flow:
+ * 1. Redirect the user to Zoho's consent page to obtain an authorization code
+ * 2. Exchange the authorization code for tokens using this function
+ * 3. Use the refresh token with {@link zohoAccountsAccessToken} to obtain new access tokens
+ *
+ * The refresh token is only returned if `access_type=offline` was passed during
+ * the initial authorization request.
+ *
+ * @param context - Zoho Accounts context providing fetch and config (clientId/clientSecret)
+ * @returns Function that exchanges an authorization code for tokens
+ *
+ * @example
+ * ```typescript
+ * const exchangeCode = zohoAccountsRefreshTokenFromAuthorizationCode(accountsContext);
+ *
+ * const { access_token, refresh_token } = await exchangeCode({
+ *   code: '1000.abc123.def456',
+ *   redirectUri: 'https://myapp.example.com/oauth/callback'
+ * });
+ * ```
+ *
+ * @see https://www.zoho.com/accounts/protocol/oauth/web-apps/access-token.html
+ */
+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.
+ */
 export declare function zohoAccountsApiFetchJsonInput(method: string, body?: FetchJsonBody): FetchJsonInput;

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

@@ -2,33 +2,100 @@ import { type ZohoAccountsConfig, type ZohoAccountsContextRef, type ZohoAccounts
 import { type LogZohoServerErrorFunction } from '../zoho.error.api';
 import { type ZohoAccessTokenCache, type ZohoAccessTokenFactory, type ZohoAccessTokenRefresher } from './accounts';
 import { type Maybe, type Milliseconds } from '@dereekb/util';
+/**
+ * Top-level Zoho Accounts client instance, providing access to the authenticated {@link ZohoAccountsContext}
+ * used for OAuth token management.
+ */
 export type ZohoAccounts = ZohoAccountsContextRef;
+/**
+ * Configuration for creating a {@link ZohoAccountsFactory}, with optional overrides
+ * for the HTTP client and error logging.
+ */
 export interface ZohoAccountsFactoryConfig {
     /**
-     * Creates a new fetch instance to use when making calls.
+     * 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;
     /**
-     * Custom log error function.
+     * Custom error logging function invoked when Zoho API errors are encountered.
      */
     logZohoServerErrorFunction?: LogZohoServerErrorFunction;
 }
+/**
+ * Factory function that creates a {@link ZohoAccounts} client from a {@link ZohoAccountsConfig}.
+ */
 export type ZohoAccountsFactory = (config: ZohoAccountsConfig) => ZohoAccounts;
+/**
+ * Creates a {@link ZohoAccountsFactory} from the given configuration.
+ *
+ * The factory pre-initializes shared resources (rate limiter) once, then produces
+ * {@link ZohoAccounts} client instances for each {@link ZohoAccountsConfig}. Each client
+ * handles OAuth token refresh via the configured `refreshToken`, `clientId`, and `clientSecret`,
+ * with in-memory caching and optional external {@link ZohoAccessTokenCache} support.
+ *
+ * The Accounts client is the foundation for CRM, Recruit, and Sign clients, as it provides
+ * the {@link ZohoAccountsContext} needed for OAuth token management.
+ *
+ * @param factoryConfig - Configuration providing optional fetch and logging overrides
+ * @returns A factory function that creates authenticated Zoho Accounts clients
+ * @throws {Error} If `refreshToken`, `clientId`, or `clientSecret` are missing from the config
+ *
+ * @example
+ * ```typescript
+ * const factory = zohoAccountsFactory({});
+ *
+ * const zohoAccounts = factory({
+ *   refreshToken: 'your-refresh-token',
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   apiUrl: 'us'
+ * });
+ *
+ * // Pass the accounts context to CRM/Recruit/Sign factories:
+ * const crmFactory = zohoCrmFactory({
+ *   accountsContext: zohoAccounts.accountsContext
+ * });
+ * ```
+ */
 export declare function zohoAccountsFactory(factoryConfig: ZohoAccountsFactoryConfig): ZohoAccountsFactory;
+/**
+ * Configuration for {@link zohoAccountsZohoAccessTokenFactory}, controlling token refresh,
+ * caching, and expiration buffer behavior.
+ */
 export interface ZohoAccountsZohoAccessTokenFactoryConfig {
     /**
-     * Number of milliseconds before the expiration time a token should be discarded.
+     * Number of milliseconds before the expiration time a token should be discarded
+     * and refreshed proactively.
      *
      * Defaults to 1 minute.
      */
     readonly tokenExpirationBuffer?: Milliseconds;
+    /**
+     * Function that fetches a fresh access token from the Zoho OAuth endpoint.
+     */
     readonly tokenRefresher: ZohoAccessTokenRefresher;
+    /**
+     * Optional external cache for persisting tokens across process restarts.
+     * When provided, tokens are loaded from and saved to this cache in addition
+     * to the in-memory cache.
+     */
     readonly accessTokenCache?: Maybe<ZohoAccessTokenCache>;
 }
 /**
- * Creates a ZohoAccountsZohoAccessTokenFactoryConfig
+ * Creates a {@link ZohoAccessTokenFactory} that manages access token lifecycle with
+ * in-memory caching, optional external cache support, and automatic refresh.
+ *
+ * Token resolution order:
+ * 1. Return the in-memory cached token if valid (not expired within the buffer)
+ * 2. Load from the external {@link ZohoAccessTokenCache} if available
+ * 3. Fetch a fresh token via the {@link ZohoAccessTokenRefresher}
+ *
+ * The returned function also exposes a `resetAccessToken()` method to invalidate
+ * the current cached token, typically called on {@link ZohoInvalidTokenError}.
  *
- * @param config
- * @returns
+ * @param config - Token refresh, caching, and expiration buffer configuration
+ * @returns A token factory function with `resetAccessToken` for cache invalidation
+ * @throws {ZohoAccountsAuthFailureError} If the token refresher fails
  */
 export declare function zohoAccountsZohoAccessTokenFactory(config: ZohoAccountsZohoAccessTokenFactoryConfig): ZohoAccessTokenFactory;