@dereekb/zoho 13.32.0 → 13.33.0

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

@@ -0,0 +1,107 @@
+import { type ZohoAccessTokenString, type ZohoAccountsAccessTokenResponse, type ZohoAccountsApiUrl, type ZohoAccountsConfigApiUrlInput, type ZohoAccountsOAuthClientContext, type ZohoAccountsRefreshTokenFromAuthorizationCodeResponse, type ZohoAccountsUserInfoResponse, type ZohoAuthorizationCode, type ZohoOAuthClientId, type ZohoRefreshToken } from '@dereekb/zoho';
+import { type Maybe, type WebsiteUrl } from '@dereekb/util';
+import { ZohoAccountsOAuthServiceConfig } from './accounts.oauth.config';
+export interface ZohoAccountsExchangeAuthorizationCodeInput {
+    /**
+     * The single-use authorization code obtained from the Zoho consent flow.
+     */
+    readonly code: ZohoAuthorizationCode;
+    /**
+     * The redirect URI the code was issued against. Must match the authorize request byte-for-byte.
+     */
+    readonly redirectUri: WebsiteUrl;
+    /**
+     * The accounts host to exchange against. Defaults to the configured datacenter.
+     */
+    readonly accountsApiUrl?: Maybe<ZohoAccountsConfigApiUrlInput>;
+}
+export interface ZohoAccountsUserInfoApiInput {
+    /**
+     * The access token to read the identity of.
+     */
+    readonly accessToken: ZohoAccessTokenString;
+    /**
+     * The accounts host to read from. Defaults to the configured datacenter.
+     */
+    readonly accountsApiUrl?: Maybe<ZohoAccountsConfigApiUrlInput>;
+}
+export interface ZohoAccountsRefreshUserAccessTokenInput {
+    /**
+     * The user's refresh token.
+     */
+    readonly refreshToken: ZohoRefreshToken;
+    /**
+     * The accounts host to refresh against. Defaults to the configured datacenter.
+     *
+     * Should be the datacenter the grant was created at — a refresh token issued by one datacenter is
+     * not honored by another.
+     */
+    readonly accountsApiUrl?: Maybe<ZohoAccountsConfigApiUrlInput>;
+}
+/**
+ * The Zoho Accounts endpoints a per-user connect flow needs: the authorization-code exchange, the
+ * per-user token refresh, and the identity lookup that labels the connection.
+ *
+ * Deliberately separate from {@link ZohoAccountsApi}, which requires a server refresh token and a
+ * token cache. A per-user handoff has neither — the handoff is how a refresh token is obtained.
+ */
+export declare class ZohoAccountsOAuthApi {
+    readonly config: ZohoAccountsOAuthServiceConfig;
+    private readonly _clientFactory;
+    /**
+     * Per-host clients, memoized so a repeated datacenter reuses one client rather than rebuilding
+     * its fetch stack per callback.
+     */
+    private readonly _clients;
+    /**
+     * The accounts host configured for this app.
+     */
+    readonly apiUrl: ZohoAccountsApiUrl;
+    /**
+     * The OAuth client id the authorize request is composed with.
+     */
+    readonly clientId: ZohoOAuthClientId;
+    private readonly _clientSecret;
+    constructor(config: ZohoAccountsOAuthServiceConfig);
+    /**
+     * The client for the configured datacenter.
+     */
+    get oauthClientContext(): ZohoAccountsOAuthClientContext;
+    /**
+     * The client for a specific accounts host, memoized per host.
+     *
+     * Zoho echoes the issuing datacenter back as `accounts-server` on the callback, and a code issued
+     * by one datacenter cannot be exchanged at another. Callers MUST have checked the host against
+     * `isKnownZohoAccountsApiUrl` first — this method will happily build a client for any URL, and the
+     * client secret travels to whatever host it is given.
+     *
+     * @param apiUrl - The datacenter key or full accounts URL to build a client for.
+     * @returns The memoized client context for that host.
+     */
+    oauthClientContextForApiUrl(apiUrl: ZohoAccountsConfigApiUrlInput): ZohoAccountsOAuthClientContext;
+    /**
+     * Exchanges a single-use authorization code for tokens.
+     *
+     * @param input - The code, the redirect URI it was issued against, and the optional accounts host.
+     * @returns The Zoho token response. `refresh_token` may be absent on a re-consent.
+     */
+    exchangeAuthorizationCode(input: ZohoAccountsExchangeAuthorizationCodeInput): Promise<ZohoAccountsRefreshTokenFromAuthorizationCodeResponse>;
+    /**
+     * Exchanges a user's refresh token for a new access token.
+     *
+     * Zoho does not rotate refresh tokens, so the token passed in stays valid and the response carries
+     * no replacement — the caller keeps the one it already has. The response DOES carry `api_domain`,
+     * which is the host the new access token is usable against, so persist it.
+     *
+     * @param input - The user's refresh token and the optional accounts host.
+     * @returns The Zoho access token response.
+     */
+    refreshUserAccessToken(input: ZohoAccountsRefreshUserAccessTokenInput): Promise<ZohoAccountsAccessTokenResponse>;
+    /**
+     * Reads the Zoho identity an access token was issued to.
+     *
+     * @param input - The access token and the optional accounts host.
+     * @returns The user info response.
+     */
+    userInfo(input: ZohoAccountsUserInfoApiInput): Promise<ZohoAccountsUserInfoResponse>;
+}

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

@@ -0,0 +1,45 @@
+import { type ZohoAccountsConfigApiUrlInput, type ZohoAccountsOAuthClientFactoryConfig, type ZohoOAuthClientId, type ZohoOAuthClientSecret } from '@dereekb/zoho';
+import { type Maybe } from '@dereekb/util';
+import { type ConfigService } from '@nestjs/config';
+/**
+ * Environment key naming the Zoho Accounts datacenter (or a full accounts URL) to authorize against.
+ */
+export declare const ZOHO_ACCOUNTS_URL_CONFIG_KEY = "ZOHO_ACCOUNTS_URL";
+/**
+ * Environment key holding the Zoho OAuth client id.
+ */
+export declare const ZOHO_ACCOUNTS_CLIENT_ID_CONFIG_KEY = "ZOHO_ACCOUNTS_CLIENT_ID";
+/**
+ * Environment key holding the Zoho OAuth client secret.
+ */
+export declare const ZOHO_ACCOUNTS_CLIENT_SECRET_CONFIG_KEY = "ZOHO_ACCOUNTS_CLIENT_SECRET";
+export interface ZohoAccountsOAuthServiceApiConfig {
+    readonly clientId?: Maybe<ZohoOAuthClientId>;
+    readonly clientSecret?: Maybe<ZohoOAuthClientSecret>;
+    /**
+     * The datacenter (or full accounts URL) to authorize and exchange against. Defaults to `us`.
+     */
+    readonly apiUrl?: Maybe<ZohoAccountsConfigApiUrlInput>;
+}
+/**
+ * Configuration for {@link ZohoAccountsOAuthApi}.
+ *
+ * Read from the three existing flat `ZOHO_ACCOUNTS_*` keys rather than composed through
+ * `zohoConfigServiceReaderFunction`, which requires a `serviceAccessTokenKey` a per-user OAuth
+ * client does not have. Notably absent: `ZOHO_ACCOUNTS_REFRESH_TOKEN` (a per-user flow has no
+ * server refresh token) and any scope variable (scopes are declared in code).
+ */
+export declare abstract class ZohoAccountsOAuthServiceConfig {
+    readonly zohoAccountsOAuth: ZohoAccountsOAuthServiceApiConfig;
+    readonly factoryConfig?: ZohoAccountsOAuthClientFactoryConfig;
+    static assertValidConfig(config: ZohoAccountsOAuthServiceConfig): void;
+}
+/**
+ * Factory function that creates a {@link ZohoAccountsOAuthServiceConfig} from NestJS ConfigService
+ * environment variables.
+ *
+ * @param configService - The NestJS ConfigService instance.
+ * @returns A validated ZohoAccountsOAuthServiceConfig.
+ * @throws {Error} When the client id or client secret is not configured.
+ */
+export declare function zohoAccountsOAuthServiceConfigFactory(configService: ConfigService): ZohoAccountsOAuthServiceConfig;

package/nestjs/src/lib/accounts/accounts.oauth.module.d.ts

@@ -0,0 +1,22 @@
+import { type ModuleMetadata } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { ZohoAccountsOAuthServiceConfig } from './accounts.oauth.config';
+export type ZohoAccountsOAuthServiceConfigFactory = (configService: ConfigService) => ZohoAccountsOAuthServiceConfig;
+export interface ProvideAppZohoAccountsOAuthMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * Optional override for the ZohoAccountsOAuthServiceConfigFactory.
+     *
+     * @default zohoAccountsOAuthServiceConfigFactory
+     */
+    readonly zohoAccountsOAuthServiceConfigFactory?: ZohoAccountsOAuthServiceConfigFactory;
+}
+/**
+ * Convenience function used to generate ModuleMetadata for an app's ZohoAccountsOAuthModule.
+ *
+ * Unlike `appZohoCrmModuleMetadata`, this needs no `ZohoAccountsAccessTokenCacheService` and
+ * therefore no dependency module: a per-user connect flow has no server token to cache.
+ *
+ * @param config - The module metadata configuration including an optional config factory.
+ * @returns NestJS ModuleMetadata for registering the ZohoAccountsOAuthApi.
+ */
+export declare function appZohoAccountsOAuthModuleMetadata(config: ProvideAppZohoAccountsOAuthMetadataConfig): ModuleMetadata;

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

@@ -1,3 +1,6 @@
 export * from './accounts.api';
 export * from './accounts.config';
+export * from './accounts.oauth.api';
+export * from './accounts.oauth.config';
+export * from './accounts.oauth.module';
 export * from './accounts.service';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/zoho",
-  "version": "13.32.0",
+  "version": "13.33.0",
   "bin": {
     "zoho-cli": "cli/index.js"
   },
@@ -23,13 +23,13 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "13.32.0",
-    "@dereekb/dbx-cli": "13.32.0",
-    "@dereekb/firebase": "13.32.0",
-    "@dereekb/model": "13.32.0",
-    "@dereekb/nestjs": "13.32.0",
-    "@dereekb/rxjs": "13.32.0",
-    "@dereekb/util": "13.32.0",
+    "@dereekb/date": "13.33.0",
+    "@dereekb/dbx-cli": "13.33.0",
+    "@dereekb/firebase": "13.33.0",
+    "@dereekb/model": "13.33.0",
+    "@dereekb/nestjs": "13.33.0",
+    "@dereekb/rxjs": "13.33.0",
+    "@dereekb/util": "13.33.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

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

@@ -1,9 +1,22 @@
-import { type FetchJsonBody, type FetchJsonInput } from '@dereekb/util/fetch';
+import { type FetchJsonBody, type FetchJsonFunction, type FetchJsonInput } from '@dereekb/util/fetch';
 import { type ZohoAccountsContext } from './accounts.config';
 import { type ZohoAuthClientIdAndSecretPair, type ZohoRefreshToken } from '../zoho.config';
 import { type ZohoAccessTokenApiDomain, type ZohoAccessTokenScopesString, type ZohoAccessTokenString } from './accounts';
 import { type Maybe, type Seconds } from '@dereekb/util';
 import { type ZohoAccountsAccessTokenErrorCode } from './accounts.error.api';
+import { type ZohoOAuthScope } from './accounts.authorize';
+/**
+ * The parts of a {@link ZohoAccountsContext} an authorization-code exchange actually needs.
+ *
+ * Narrower than ZohoAccountsContext on purpose: the exchange is how a refresh token is OBTAINED, so
+ * requiring a context that already has one (as `zohoAccountsFactory` does) is circular for a
+ * per-user connect flow. A full `ZohoAccountsContext` remains structurally assignable to this, so
+ * every existing caller is unaffected.
+ */
+export interface ZohoAccountsOAuthClientContext {
+    readonly fetchJson: FetchJsonFunction;
+    readonly config: ZohoAuthClientIdAndSecretPair;
+}
 /**
  * Optional overrides for the access token request. When omitted, values
  * are read from the {@link ZohoAccountsContext}'s config.
@@ -80,6 +93,53 @@ export interface ZohoAccountsAccessTokenErrorResponse {
  * ```
  */
 export declare function zohoAccountsAccessToken(context: ZohoAccountsContext): (input?: ZohoAccountsAccessTokenInput) => Promise<ZohoAccountsAccessTokenResponse>;
+/**
+ * Input for exchanging a specific user's refresh token for a new access token.
+ *
+ * Unlike {@link ZohoAccountsAccessTokenInput}, the refresh token is REQUIRED: there is no config-level
+ * token to fall back to, because the whole point is that the token belongs to a user rather than to
+ * the app.
+ */
+export interface ZohoAccountsUserAccessTokenInput {
+    /**
+     * The user's long-lived refresh token.
+     */
+    readonly refreshToken: ZohoRefreshToken;
+    /**
+     * Override client credentials. Falls back to the context config's `clientId`/`clientSecret`.
+     */
+    readonly client?: Maybe<ZohoAuthClientIdAndSecretPair>;
+}
+/**
+ * Exchanges a user's refresh token for a new access token.
+ */
+export type ZohoAccountsUserAccessTokenFunction = (input: ZohoAccountsUserAccessTokenInput) => Promise<ZohoAccountsAccessTokenResponse>;
+/**
+ * Creates a function that exchanges a SPECIFIC USER's refresh token for a new access token.
+ *
+ * The per-user counterpart of {@link zohoAccountsAccessToken}, and narrowed the same way
+ * {@link zohoAccountsRefreshTokenFromAuthorizationCode} is: it takes a
+ * {@link ZohoAccountsOAuthClientContext} rather than a full {@link ZohoAccountsContext}. That matters
+ * because a `ZohoAccountsContext`'s config REQUIRES a `refreshToken` — the app's own — so it cannot
+ * describe a client that refreshes on behalf of many users. A full context stays structurally
+ * assignable, so this is usable from either.
+ *
+ * Zoho does not rotate refresh tokens and its refresh response carries NO `refresh_token`, so the
+ * token passed in here stays valid and must be retained by the caller. The response does carry
+ * `api_domain`, which can differ from the one the grant was created with, so persist it.
+ *
+ * @param context - A Zoho Accounts client context providing fetch and client credentials.
+ * @returns Function that exchanges a user's refresh token for an access token.
+ *
+ * @see https://www.zoho.com/accounts/protocol/oauth/web-apps/access-token-expiry.html
+ *
+ * @example
+ * ```typescript
+ * const userAccessToken = zohoAccountsUserAccessToken(accountsClientContext);
+ * const { access_token, api_domain, expires_in } = await userAccessToken({ refreshToken: user.zohoRefreshToken });
+ * ```
+ */
+export declare function zohoAccountsUserAccessToken(context: ZohoAccountsOAuthClientContext): ZohoAccountsUserAccessTokenFunction;
 /**
  * OAuth authorization code received from the Zoho authorization server
  * after the user grants consent. Single-use and short-lived.
@@ -166,7 +226,57 @@ export type ZohoAccountsRefreshTokenFromAuthorizationCodeFunction = (input: Zoho
  * });
  * ```
  */
-export declare function zohoAccountsRefreshTokenFromAuthorizationCode(context: ZohoAccountsContext): ZohoAccountsRefreshTokenFromAuthorizationCodeFunction;
+export declare function zohoAccountsRefreshTokenFromAuthorizationCode(context: ZohoAccountsOAuthClientContext): ZohoAccountsRefreshTokenFromAuthorizationCodeFunction;
+/**
+ * Path of the Zoho Accounts endpoint that describes the authorizing user.
+ */
+export declare const ZOHO_ACCOUNTS_USER_INFO_PATH = "/oauth/user/info";
+/**
+ * Scope required to read {@link zohoAccountsUserInfo}.
+ */
+export declare const ZOHO_ACCOUNTS_PROFILE_READ_SCOPE: ZohoOAuthScope;
+/**
+ * Input for reading the identity an access token was issued to.
+ */
+export interface ZohoAccountsUserInfoInput {
+    /**
+     * The access token to read the identity of.
+     */
+    readonly accessToken: ZohoAccessTokenString;
+}
+/**
+ * The authorizing user, as described by the Zoho Accounts user info endpoint.
+ *
+ * EVERY field is optional. The documented casing (`ZUID`, `Email`, `Display_Name`) cannot be
+ * verified without live credentials, so a consumer must tolerate a response whose shape differs —
+ * the worst case is a connection with no label, not a failed connect.
+ */
+export interface ZohoAccountsUserInfoResponse {
+    /**
+     * The Zoho user id.
+     */
+    readonly ZUID?: Maybe<number | string>;
+    readonly Email?: Maybe<string>;
+    readonly Display_Name?: Maybe<string>;
+    readonly First_Name?: Maybe<string>;
+    readonly Last_Name?: Maybe<string>;
+}
+/**
+ * Reads the identity an access token was issued to.
+ */
+export type ZohoAccountsUserInfoFunction = (input: ZohoAccountsUserInfoInput) => Promise<ZohoAccountsUserInfoResponse>;
+/**
+ * Creates a function that reads the authorizing user's Zoho identity, so a connection can be
+ * labelled with the account it belongs to.
+ *
+ * Requires the {@link ZOHO_ACCOUNTS_PROFILE_READ_SCOPE} scope on the access token.
+ *
+ * @param context - Zoho Accounts OAuth client context providing fetch.
+ * @returns Function that reads the user info for an access token.
+ *
+ * @see https://www.zoho.com/accounts/protocol/oauth/web-apps/get-user-info.html
+ */
+export declare function zohoAccountsUserInfo(context: ZohoAccountsOAuthClientContext): ZohoAccountsUserInfoFunction;
 /**
  * Constructs a standard {@link FetchJsonInput} for Zoho Accounts API calls with the given HTTP method and optional body.
  *

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

@@ -0,0 +1,119 @@
+import { type Maybe, type WebsiteUrl } from '@dereekb/util';
+import { type ZohoOAuthClientId } from '../zoho.config';
+import { type ZohoAccountsConfigApiUrlInput } from './accounts.config';
+/**
+ * Path of the Zoho Accounts authorization (consent screen) endpoint.
+ */
+export declare const ZOHO_ACCOUNTS_AUTHORIZE_PATH = "/oauth/v2/auth";
+/**
+ * Path of the Zoho Accounts token endpoint.
+ */
+export declare const ZOHO_ACCOUNTS_TOKEN_PATH = "/oauth/v2/token";
+/**
+ * The delimiter Zoho joins and returns granted scopes with.
+ *
+ * A comma, NOT the space OAuth 2.0 specifies. Both halves of the round trip use this: the authorize
+ * request joins on it, and the granted `scope` string comes back split on it.
+ */
+export declare const ZOHO_OAUTH_SCOPE_DELIMITER = ",";
+/**
+ * The `response_type` used by the authorization-code flow.
+ */
+export declare const ZOHO_OAUTH_AUTHORIZE_RESPONSE_TYPE = "code";
+/**
+ * Required for Zoho to return a `refresh_token` at all.
+ */
+export declare const ZOHO_OAUTH_OFFLINE_ACCESS_TYPE = "offline";
+/**
+ * Forces the consent screen.
+ *
+ * Without it Zoho returns a refresh token only on a user's FIRST authorization, so a reconnect would
+ * come back with an access token alone — and a persisted exchange that omits the refresh token
+ * silently breaks the connection.
+ */
+export declare const ZOHO_OAUTH_CONSENT_PROMPT = "consent";
+/**
+ * A Zoho OAuth scope, e.g. `ZohoCRM.modules.READ` or `AaaServer.profile.READ`.
+ *
+ * Deliberately an open string alias and NOT a closed union: Zoho's scope namespace is per-product,
+ * dotted, and open-ended, so a runtime list would be stale on arrival. Cal.com can enumerate its
+ * twelve; Zoho cannot.
+ */
+export type ZohoOAuthScope = string;
+export interface ZohoAccountsAuthorizeUrlFactoryConfig {
+    /**
+     * The OAuth client id to authorize as.
+     */
+    readonly clientId: ZohoOAuthClientId;
+    /**
+     * The redirect URI to return to after the user consents.
+     *
+     * Must match the URI registered on the Zoho OAuth client byte-for-byte, including the port, and
+     * must be identical to the `redirectUri` later passed to the token exchange.
+     */
+    readonly redirectUri: WebsiteUrl;
+    /**
+     * The scopes to request.
+     */
+    readonly scopes: readonly ZohoOAuthScope[];
+    /**
+     * Accounts host to authorize against. Defaults to the `us` datacenter.
+     */
+    readonly accountsApiUrl?: Maybe<ZohoAccountsConfigApiUrlInput>;
+    /**
+     * Defaults to {@link ZOHO_OAUTH_OFFLINE_ACCESS_TYPE}, without which no refresh token is issued.
+     */
+    readonly accessType?: Maybe<string>;
+    /**
+     * Defaults to {@link ZOHO_OAUTH_CONSENT_PROMPT}, without which a RE-consent issues no refresh token.
+     */
+    readonly prompt?: Maybe<string>;
+}
+export interface ZohoAccountsAuthorizeUrlParams {
+    /**
+     * Opaque state echoed back to the redirect URI.
+     *
+     * Carries the acting user and is the CSRF defense for the handoff, so it should be signed and
+     * short-lived.
+     */
+    readonly state?: Maybe<string>;
+}
+export type ZohoAccountsAuthorizeUrlFactory = (params?: Maybe<ZohoAccountsAuthorizeUrlParams>) => WebsiteUrl;
+/**
+ * Creates a {@link ZohoAccountsAuthorizeUrlFactory} that composes the Zoho authorize URL a user's
+ * browser is redirected to in order to begin the authorization-code flow.
+ *
+ * The client id, redirect URI, and scopes are fixed by the config, since a consumer holds those
+ * constant and varies only the per-request `state`.
+ *
+ * @param config - The client id, redirect URI, scopes, and optional datacenter/consent overrides.
+ * @returns A factory that builds an authorize URL for the given params.
+ * @throws {Error} When no client id is given, or when no scopes are requested — Zoho refuses an
+ *   authorize request carrying no scope, and failing at construction beats failing at the consent
+ *   screen.
+ *
+ * @see https://www.zoho.com/accounts/protocol/oauth/web-apps/authorization.html
+ *
+ * @example
+ * ```typescript
+ * const authorizeUrlFactory = zohoAccountsAuthorizeUrlFactory({
+ *   clientId: 'client-id',
+ *   redirectUri: 'http://localhost:9901/oauth/zoho/callback',
+ *   scopes: ['AaaServer.profile.READ']
+ * });
+ *
+ * const url = authorizeUrlFactory({ state: 'signed-state' });
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function zohoAccountsAuthorizeUrlFactory(config: ZohoAccountsAuthorizeUrlFactoryConfig): ZohoAccountsAuthorizeUrlFactory;
+/**
+ * Splits a granted Zoho `scope` string on the same delimiter the authorize request joins with.
+ *
+ * @param scope - The granted scope string returned on a token response.
+ * @returns The granted scopes, or undefined when none were granted.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function zohoOAuthScopesFromScopeString(scope: Maybe<string>): Maybe<ZohoOAuthScope[]>;

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

@@ -6,6 +6,34 @@ import { type ZohoAccessTokenCache, type ZohoAccessTokenFactory } from './accoun
  * The Zoho Accounts API URL for the US datacenter.
  */
 export declare const ZOHO_ACCOUNTS_US_API_URL = "https://accounts.zoho.com";
+/**
+ * The Zoho Accounts API URL for the EU datacenter.
+ */
+export declare const ZOHO_ACCOUNTS_EU_API_URL = "https://accounts.zoho.eu";
+/**
+ * The Zoho Accounts API URL for the India datacenter.
+ */
+export declare const ZOHO_ACCOUNTS_IN_API_URL = "https://accounts.zoho.in";
+/**
+ * The Zoho Accounts API URL for the Australia datacenter.
+ */
+export declare const ZOHO_ACCOUNTS_AU_API_URL = "https://accounts.zoho.com.au";
+/**
+ * The Zoho Accounts API URL for the Japan datacenter.
+ */
+export declare const ZOHO_ACCOUNTS_JP_API_URL = "https://accounts.zoho.jp";
+/**
+ * The Zoho Accounts API URL for the United Kingdom datacenter.
+ */
+export declare const ZOHO_ACCOUNTS_UK_API_URL = "https://accounts.zoho.uk";
+/**
+ * The Zoho Accounts API URL for the Canada datacenter.
+ */
+export declare const ZOHO_ACCOUNTS_CA_API_URL = "https://accounts.zohocloud.ca";
+/**
+ * The Zoho Accounts API URL for the Saudi Arabia datacenter.
+ */
+export declare const ZOHO_ACCOUNTS_SA_API_URL = "https://accounts.zoho.sa";
 /**
  * Url for the Zoho Accounts API.
  *
@@ -14,15 +42,50 @@ export declare const ZOHO_ACCOUNTS_US_API_URL = "https://accounts.zoho.com";
  * https://help.zoho.com/portal/en/kb/creator/developer-guide/others/url-patterns/articles/know-your-creator-account-s-base-url
  */
 export type ZohoAccountsApiUrl = ZohoApiUrl;
-export type ZohoAccountsApiUrlKey = 'us';
+export type ZohoAccountsApiUrlKey = 'us' | 'eu' | 'in' | 'au' | 'jp' | 'uk' | 'ca' | 'sa';
 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.
+ * Every Zoho Accounts host this package will talk to, keyed by datacenter.
+ *
+ * A closed set rather than an open string, because a value echoed back on an OAuth callback
+ * (`accounts-server`) is checked against it before being used as a token-exchange target — an
+ * unchecked host there would receive the client secret.
+ */
+export declare const ZOHO_ACCOUNTS_API_URLS: Readonly<Record<ZohoAccountsApiUrlKey, ZohoAccountsApiUrl>>;
+/**
+ * Resolves a Zoho Accounts API URL input to the full base URL. A datacenter key maps to that
+ * datacenter's host; 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;
+/**
+ * Returns whether the input is one of the known Zoho Accounts hosts.
+ *
+ * Exists to gate a value that arrives from OUTSIDE the process: Zoho echoes the issuing datacenter
+ * back as the `accounts-server` OAuth callback parameter, and that host becomes the POST target the
+ * client secret is sent to. An attacker can compose that redirect, so only an exact match against
+ * {@link ZOHO_ACCOUNTS_API_URLS} may be honored.
+ *
+ * @param url - The candidate accounts host.
+ * @returns True when the value is exactly one of the known Zoho Accounts hosts.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function isKnownZohoAccountsApiUrl(url: Maybe<string>): boolean;
+/**
+ * Returns the datacenter key for a known Zoho Accounts host.
+ *
+ * A trailing slash is tolerated, since Zoho's `accounts-server` value is URL-encoded and some
+ * datacenters echo it back with one; nothing else about the value is normalized.
+ *
+ * @param url - The candidate accounts host.
+ * @returns The matching datacenter key, or undefined when the host is not a known one.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function zohoAccountsApiUrlKeyForApiUrl(url: Maybe<string>): Maybe<ZohoAccountsApiUrlKey>;
 /**
  * Configuration for ZohoAccounts.
  */

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

@@ -1,7 +1,10 @@
+import { type FetchHandler } from '@dereekb/util/fetch';
 import { type ZohoAccountsConfig, type ZohoAccountsContextRef, type ZohoAccountsFetchFactory } from './accounts.config';
+import { type ZohoAuthClientIdAndSecretPair, type ZohoConfig } from '../zoho.config';
 import { type LogZohoServerErrorFunction } from '../zoho.error.api';
 import { type ZohoAccessTokenCache, type ZohoAccessTokenFactory, type ZohoAccessTokenRefresher } from './accounts';
 import { type Maybe, type Milliseconds } from '@dereekb/util';
+import { type ZohoAccountsOAuthClientContext } from './accounts.api';
 /**
  * Top-level Zoho Accounts client instance, providing access to the authenticated {@link ZohoAccountsContext}
  * used for OAuth token management.
@@ -26,6 +29,15 @@ export interface ZohoAccountsFactoryConfig {
  * Factory function that creates a {@link ZohoAccounts} client from a {@link ZohoAccountsConfig}.
  */
 export type ZohoAccountsFactory = (config: ZohoAccountsConfig) => ZohoAccounts;
+/**
+ * Creates the {@link ZohoAccountsFetchFactory} the Zoho Accounts clients use when none is supplied.
+ *
+ * @param fetchHandler - The handler the produced fetches route through.
+ * @returns The default Zoho Accounts fetch factory.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function defaultZohoAccountsFetchFactory(fetchHandler: FetchHandler): ZohoAccountsFetchFactory;
 /**
  * Creates a {@link ZohoAccountsFactory} from the given configuration.
  *
@@ -65,6 +77,63 @@ export declare function zohoAccountsFactory(factoryConfig: ZohoAccountsFactoryCo
  * Configuration for {@link zohoAccountsZohoAccessTokenFactory}, controlling token refresh,
  * caching, and expiration buffer behavior.
  */
+/**
+ * Configuration for a {@link ZohoAccountsOAuthClient}.
+ *
+ * Notably absent: a refresh token. A per-user authorization-code handoff is how one is obtained.
+ */
+export interface ZohoAccountsOAuthClientConfig extends ZohoConfig, ZohoAuthClientIdAndSecretPair {
+}
+/**
+ * A Zoho Accounts client authenticated by client credentials alone.
+ */
+export interface ZohoAccountsOAuthClient {
+    readonly oauthClientContext: ZohoAccountsOAuthClientContext;
+}
+/**
+ * Configuration for creating a {@link ZohoAccountsOAuthClientFactory}.
+ */
+export interface ZohoAccountsOAuthClientFactoryConfig {
+    /**
+     * Custom fetch factory for creating the underlying HTTP client.
+     */
+    readonly fetchFactory?: ZohoAccountsFetchFactory;
+    /**
+     * Custom FetchHandler to use with the default fetchFactory.
+     *
+     * Intercepts requests before they leave the process, so specs can assert the RESOLVED url.
+     * Ignored when a `fetchFactory` is provided.
+     */
+    readonly fetchHandler?: Maybe<FetchHandler>;
+    /**
+     * Custom error logging function invoked when Zoho API errors are encountered.
+     */
+    readonly logZohoServerErrorFunction?: LogZohoServerErrorFunction;
+}
+/**
+ * Factory function that creates a {@link ZohoAccountsOAuthClient} from a {@link ZohoAccountsOAuthClientConfig}.
+ */
+export type ZohoAccountsOAuthClientFactory = (config: ZohoAccountsOAuthClientConfig) => ZohoAccountsOAuthClient;
+/**
+ * Creates a {@link ZohoAccountsOAuthClientFactory}, producing Zoho Accounts clients authenticated by
+ * CLIENT CREDENTIALS ALONE.
+ *
+ * {@link zohoAccountsFactory} requires a refresh token, which a per-user authorization-code handoff
+ * does not have yet — the handoff is how the refresh token is obtained. This client covers exactly
+ * the two endpoints that need no user token: the authorization-code exchange and
+ * `/oauth/user/info`.
+ *
+ * It builds its fetch through the same error handling as the full client, which matters more than it
+ * looks: Zoho answers a failed token exchange with HTTP 200 and an `{ "error": … }` body, and
+ * `interceptZohoAccounts200StatusWithErrorResponse` is what turns that into a thrown error instead
+ * of a "successful" exchange with an undefined access token.
+ *
+ * @param factoryConfig - Configuration providing optional fetch and logging overrides.
+ * @returns A factory function that creates client-credentials-only Zoho Accounts clients.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function zohoAccountsOAuthClientFactory(factoryConfig: ZohoAccountsOAuthClientFactoryConfig): ZohoAccountsOAuthClientFactory;
 export interface ZohoAccountsZohoAccessTokenFactoryConfig {
     /**
      * Number of milliseconds before the expiration time a token should be discarded

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

@@ -1,5 +1,6 @@
 export * from './accounts';
 export * from './accounts.api';
+export * from './accounts.authorize';
 export * from './accounts.config';
 export * from './accounts.error.api';
 export * from './accounts.factory';