@dereekb/zoho 13.8.0 → 13.10.0

package/src/lib/desk/desk.api.tickets.d.ts

@@ -0,0 +1,227 @@
+import { type Maybe, type ArrayOrValue } from '@dereekb/util';
+import { type FetchJsonBody, type FetchJsonInput, type FetchPage, type FetchPageFactoryOptions } from '@dereekb/util/fetch';
+import { type ZohoDeskContext } from './desk.config';
+import { type ZohoDeskTicketId, type ZohoDeskContactId, type ZohoDeskProductId, type ZohoDeskDepartmentId, type ZohoDeskAgentId } from './desk';
+import { type ZohoDeskTicket, type ZohoDeskTicketSortBy, type ZohoDeskTicketInclude, type ZohoDeskTicketMetrics, type ZohoDeskTicketPriority, type ZohoDeskTicketChannel, type ZohoDeskAgentTicketCount } from './desk.ticket';
+import { type ZohoDeskPageFilter, type ZohoDeskPageResult } from './desk.api.page';
+/**
+ * Constructs the standard FetchJsonInput used by Desk 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 Desk API call
+ */
+export declare function zohoDeskApiFetchJsonInput(method: string, body?: Maybe<FetchJsonBody>): FetchJsonInput;
+/**
+ * Input parameters for listing tickets via `GET /tickets`.
+ */
+export interface ZohoDeskGetTicketsInput extends ZohoDeskPageFilter {
+    readonly sortBy?: ZohoDeskTicketSortBy;
+    readonly include?: ArrayOrValue<ZohoDeskTicketInclude>;
+    readonly departmentId?: ZohoDeskDepartmentId;
+    readonly departmentIds?: string;
+    readonly channel?: ZohoDeskTicketChannel;
+    readonly priority?: ZohoDeskTicketPriority;
+    readonly receivedInDays?: number;
+    readonly viewId?: string;
+    readonly assignee?: string;
+    readonly fields?: string;
+    readonly status?: string;
+}
+/**
+ * Response from listing tickets, containing an array of tickets.
+ */
+export type ZohoDeskGetTicketsResponse = ZohoDeskPageResult<ZohoDeskTicket>;
+/**
+ * Function that retrieves a paginated list of tickets.
+ */
+export type ZohoDeskGetTicketsFunction = (input: ZohoDeskGetTicketsInput) => Promise<ZohoDeskGetTicketsResponse>;
+/**
+ * Creates a {@link ZohoDeskGetTicketsFunction} bound to the given context.
+ *
+ * Retrieves a paginated list of tickets from Zoho Desk, with optional filtering by
+ * department, status, priority, channel, assignee, and view.
+ *
+ * @param context - Authenticated Zoho Desk context
+ * @returns Function that retrieves paginated tickets
+ */
+export declare function zohoDeskGetTickets(context: ZohoDeskContext): ZohoDeskGetTicketsFunction;
+/**
+ * Input parameters for retrieving a single ticket via `GET /tickets/{ticketId}`.
+ */
+export interface ZohoDeskGetTicketByIdInput {
+    readonly ticketId: ZohoDeskTicketId;
+    readonly include?: ArrayOrValue<ZohoDeskTicketInclude>;
+}
+/**
+ * Function that retrieves a single ticket by ID.
+ */
+export type ZohoDeskGetTicketByIdFunction = (input: ZohoDeskGetTicketByIdInput) => Promise<ZohoDeskTicket>;
+/**
+ * Creates a {@link ZohoDeskGetTicketByIdFunction} bound to the given context.
+ *
+ * Retrieves a single ticket by its ID, with optional inline expansion of related entities.
+ *
+ * @param context - Authenticated Zoho Desk context
+ * @returns Function that retrieves a single ticket
+ */
+export declare function zohoDeskGetTicketById(context: ZohoDeskContext): ZohoDeskGetTicketByIdFunction;
+/**
+ * Input parameters for searching tickets via `GET /tickets/search`.
+ */
+export interface ZohoDeskSearchTicketsInput extends ZohoDeskPageFilter {
+    readonly sortBy?: ZohoDeskTicketSortBy;
+    readonly ticketNumber?: string;
+    readonly subject?: string;
+    readonly departmentId?: ZohoDeskDepartmentId;
+    readonly channel?: string;
+    readonly customerResponseTimeRange?: string;
+    readonly description?: string;
+    readonly productName?: string;
+    readonly all?: string;
+    readonly dueDateRange?: string;
+    readonly id?: ZohoDeskTicketId;
+    readonly tag?: string;
+    readonly email?: string;
+    readonly productId?: ZohoDeskProductId;
+    readonly contactId?: ZohoDeskContactId;
+    readonly contactName?: string;
+    readonly createdTimeRange?: string;
+    readonly priority?: ZohoDeskTicketPriority;
+    readonly assigneeId?: ZohoDeskAgentId;
+    readonly accountId?: string;
+    readonly phone?: string;
+    readonly modifiedTimeRange?: string;
+    readonly category?: string;
+    readonly status?: string;
+    readonly customField1?: string;
+    readonly customField2?: string;
+    readonly customField3?: string;
+    readonly customField4?: string;
+    readonly customField5?: string;
+    readonly customField6?: string;
+    readonly customField7?: string;
+    readonly customField8?: string;
+    readonly customField9?: string;
+    readonly customField10?: string;
+}
+/**
+ * Response from searching tickets.
+ */
+export type ZohoDeskSearchTicketsResponse = ZohoDeskPageResult<ZohoDeskTicket>;
+/**
+ * Function that searches for tickets.
+ */
+export type ZohoDeskSearchTicketsFunction = (input: ZohoDeskSearchTicketsInput) => Promise<ZohoDeskSearchTicketsResponse>;
+/**
+ * Creates a {@link ZohoDeskSearchTicketsFunction} bound to the given context.
+ *
+ * Searches for tickets matching the given filter criteria. Supports filtering by
+ * many fields including subject, email, status, priority, date ranges, and custom fields.
+ *
+ * @param context - Authenticated Zoho Desk context
+ * @returns Function that searches for tickets
+ */
+export declare function zohoDeskSearchTickets(context: ZohoDeskContext): ZohoDeskSearchTicketsFunction;
+/**
+ * Input parameters for listing tickets for a specific contact via `GET /contacts/{contactId}/tickets`.
+ */
+export interface ZohoDeskGetTicketsForContactInput extends ZohoDeskPageFilter {
+    readonly contactId: ZohoDeskContactId;
+    readonly sortBy?: ZohoDeskTicketSortBy;
+    readonly include?: ArrayOrValue<ZohoDeskTicketInclude>;
+    readonly departmentId?: ZohoDeskDepartmentId;
+    readonly status?: string;
+}
+/**
+ * Function that retrieves tickets for a specific contact.
+ */
+export type ZohoDeskGetTicketsForContactFunction = (input: ZohoDeskGetTicketsForContactInput) => Promise<ZohoDeskPageResult<ZohoDeskTicket>>;
+/**
+ * Creates a {@link ZohoDeskGetTicketsForContactFunction} bound to the given context.
+ *
+ * @param context - Authenticated Zoho Desk context
+ * @returns Function that retrieves tickets for a contact
+ */
+export declare function zohoDeskGetTicketsForContact(context: ZohoDeskContext): ZohoDeskGetTicketsForContactFunction;
+/**
+ * Input parameters for listing tickets for a specific product via `GET /products/{productId}/tickets`.
+ */
+export interface ZohoDeskGetTicketsForProductInput extends ZohoDeskPageFilter {
+    readonly productId: ZohoDeskProductId;
+    readonly sortBy?: ZohoDeskTicketSortBy;
+    readonly include?: ArrayOrValue<ZohoDeskTicketInclude>;
+    readonly departmentId?: ZohoDeskDepartmentId;
+    readonly status?: string;
+}
+/**
+ * Function that retrieves tickets for a specific product.
+ */
+export type ZohoDeskGetTicketsForProductFunction = (input: ZohoDeskGetTicketsForProductInput) => Promise<ZohoDeskPageResult<ZohoDeskTicket>>;
+/**
+ * Creates a {@link ZohoDeskGetTicketsForProductFunction} bound to the given context.
+ *
+ * @param context - Authenticated Zoho Desk context
+ * @returns Function that retrieves tickets for a product
+ */
+export declare function zohoDeskGetTicketsForProduct(context: ZohoDeskContext): ZohoDeskGetTicketsForProductFunction;
+/**
+ * Input parameters for retrieving ticket metrics via `GET /tickets/{ticketId}/metrics`.
+ */
+export interface ZohoDeskGetTicketMetricsInput {
+    readonly ticketId: ZohoDeskTicketId;
+}
+/**
+ * Function that retrieves metrics for a specific ticket.
+ */
+export type ZohoDeskGetTicketMetricsFunction = (input: ZohoDeskGetTicketMetricsInput) => Promise<ZohoDeskTicketMetrics>;
+/**
+ * Creates a {@link ZohoDeskGetTicketMetricsFunction} bound to the given context.
+ *
+ * @param context - Authenticated Zoho Desk context
+ * @returns Function that retrieves ticket metrics
+ */
+export declare function zohoDeskGetTicketMetrics(context: ZohoDeskContext): ZohoDeskGetTicketMetricsFunction;
+/**
+ * Input parameters for retrieving agent ticket counts via `GET /agentsTicketsCount`.
+ */
+export interface ZohoDeskGetAgentsTicketsCountInput {
+    readonly agentIds: ArrayOrValue<ZohoDeskAgentId>;
+    readonly departmentId?: ZohoDeskDepartmentId;
+}
+/**
+ * Function that retrieves ticket counts per agent.
+ */
+export type ZohoDeskGetAgentsTicketsCountFunction = (input: ZohoDeskGetAgentsTicketsCountInput) => Promise<ZohoDeskAgentTicketCount[]>;
+/**
+ * Creates a {@link ZohoDeskGetAgentsTicketsCountFunction} bound to the given context.
+ *
+ * @param context - Authenticated Zoho Desk context
+ * @returns Function that retrieves agent ticket counts
+ */
+export declare function zohoDeskGetAgentsTicketsCount(context: ZohoDeskContext): ZohoDeskGetAgentsTicketsCountFunction;
+/**
+ * Factory that creates paginated iterators for ticket list queries.
+ */
+export type ZohoDeskGetTicketsPageFactory = (input: ZohoDeskGetTicketsInput, options?: Maybe<FetchPageFactoryOptions<ZohoDeskGetTicketsInput, ZohoDeskGetTicketsResponse>>) => FetchPage<ZohoDeskGetTicketsInput, ZohoDeskGetTicketsResponse>;
+/**
+ * Creates a {@link ZohoDeskGetTicketsPageFactory} bound to the given context.
+ *
+ * Returns a page factory that automatically handles Zoho Desk's offset-based pagination,
+ * making it easy to iterate through all tickets across multiple pages.
+ *
+ * @param context - Authenticated Zoho Desk context
+ * @returns Page factory for iterating over ticket results
+ */
+export declare function zohoDeskGetTicketsPageFactory(context: ZohoDeskContext): ZohoDeskGetTicketsPageFactory;
+/**
+ * Factory that creates paginated iterators for ticket search queries.
+ */
+export type ZohoDeskSearchTicketsPageFactory = (input: ZohoDeskSearchTicketsInput, options?: Maybe<FetchPageFactoryOptions<ZohoDeskSearchTicketsInput, ZohoDeskSearchTicketsResponse>>) => FetchPage<ZohoDeskSearchTicketsInput, ZohoDeskSearchTicketsResponse>;
+/**
+ * Creates a {@link ZohoDeskSearchTicketsPageFactory} bound to the given context.
+ *
+ * @param context - Authenticated Zoho Desk context
+ * @returns Page factory for iterating over search results
+ */
+export declare function zohoDeskSearchTicketsPageFactory(context: ZohoDeskContext): ZohoDeskSearchTicketsPageFactory;

package/src/lib/desk/desk.api.time.d.ts

@@ -0,0 +1,109 @@
+import { type Maybe } from '@dereekb/util';
+import { type ZohoDeskContext } from './desk.config';
+import { type ZohoDeskTicketId } from './desk';
+import { type ZohoDeskTicketTimeEntry, type ZohoDeskTicketTimer } from './desk.ticket';
+import { type ZohoDeskPageFilter, type ZohoDeskPageResult } from './desk.api.page';
+/**
+ * Input parameters for retrieving the timer state for a ticket via `GET /tickets/{ticketId}/timer`.
+ */
+export interface ZohoDeskGetTicketTimerInput {
+    readonly ticketId: ZohoDeskTicketId;
+}
+/**
+ * Function that retrieves the timer state for a ticket.
+ */
+export type ZohoDeskGetTicketTimerFunction = (input: ZohoDeskGetTicketTimerInput) => Promise<ZohoDeskTicketTimer>;
+/**
+ * Creates a {@link ZohoDeskGetTicketTimerFunction} bound to the given context.
+ *
+ * @param context - Authenticated Zoho Desk context
+ * @returns Function that retrieves the ticket timer
+ */
+export declare function zohoDeskGetTicketTimer(context: ZohoDeskContext): ZohoDeskGetTicketTimerFunction;
+/**
+ * Timer action to perform on a ticket.
+ */
+export type ZohoDeskTimerAction = 'start' | 'pause' | 'resume' | 'stop';
+/**
+ * Input parameters for performing a timer action on a ticket via `POST /tickets/{ticketId}/timer`.
+ */
+export interface ZohoDeskPerformTicketTimerActionInput {
+    readonly ticketId: ZohoDeskTicketId;
+    readonly timerAction: ZohoDeskTimerAction;
+}
+/**
+ * Function that performs a timer action on a ticket.
+ */
+export type ZohoDeskPerformTicketTimerActionFunction = (input: ZohoDeskPerformTicketTimerActionInput) => Promise<ZohoDeskTicketTimer>;
+/**
+ * Creates a {@link ZohoDeskPerformTicketTimerActionFunction} bound to the given context.
+ *
+ * @param context - Authenticated Zoho Desk context
+ * @returns Function that performs a timer action on a ticket
+ */
+export declare function zohoDeskPerformTicketTimerAction(context: ZohoDeskContext): ZohoDeskPerformTicketTimerActionFunction;
+/**
+ * Input parameters for listing time entries for a ticket via `GET /tickets/{ticketId}/timeEntries`.
+ */
+export interface ZohoDeskGetTicketTimeEntriesInput extends ZohoDeskPageFilter {
+    readonly ticketId: ZohoDeskTicketId;
+    readonly billingType?: string;
+}
+/**
+ * Response from listing ticket time entries.
+ */
+export type ZohoDeskGetTicketTimeEntriesResponse = ZohoDeskPageResult<ZohoDeskTicketTimeEntry>;
+/**
+ * Function that retrieves time entries for a specific ticket.
+ */
+export type ZohoDeskGetTicketTimeEntriesFunction = (input: ZohoDeskGetTicketTimeEntriesInput) => Promise<ZohoDeskGetTicketTimeEntriesResponse>;
+/**
+ * Creates a {@link ZohoDeskGetTicketTimeEntriesFunction} bound to the given context.
+ *
+ * @param context - Authenticated Zoho Desk context
+ * @returns Function that retrieves time entries for a ticket
+ */
+export declare function zohoDeskGetTicketTimeEntries(context: ZohoDeskContext): ZohoDeskGetTicketTimeEntriesFunction;
+/**
+ * Input parameters for retrieving a single time entry via `GET /tickets/{ticketId}/timeEntries/{timeEntryId}`.
+ */
+export interface ZohoDeskGetTicketTimeEntryByIdInput {
+    readonly ticketId: ZohoDeskTicketId;
+    readonly timeEntryId: string;
+}
+/**
+ * Function that retrieves a single time entry by ID.
+ */
+export type ZohoDeskGetTicketTimeEntryByIdFunction = (input: ZohoDeskGetTicketTimeEntryByIdInput) => Promise<ZohoDeskTicketTimeEntry>;
+/**
+ * Creates a {@link ZohoDeskGetTicketTimeEntryByIdFunction} bound to the given context.
+ *
+ * @param context - Authenticated Zoho Desk context
+ * @returns Function that retrieves a single time entry
+ */
+export declare function zohoDeskGetTicketTimeEntryById(context: ZohoDeskContext): ZohoDeskGetTicketTimeEntryByIdFunction;
+/**
+ * Input parameters for getting the summation of time entries via `GET /tickets/{ticketId}/timeEntries/summation`.
+ */
+export interface ZohoDeskGetTicketTimeEntrySummationInput {
+    readonly ticketId: ZohoDeskTicketId;
+}
+/**
+ * Summation of time entries for a ticket.
+ */
+export interface ZohoDeskTicketTimeEntrySummation {
+    readonly totalHours?: Maybe<string>;
+    readonly totalMinutes?: Maybe<string>;
+    readonly totalCost?: Maybe<string>;
+}
+/**
+ * Function that retrieves the summation of time entries for a ticket.
+ */
+export type ZohoDeskGetTicketTimeEntrySummationFunction = (input: ZohoDeskGetTicketTimeEntrySummationInput) => Promise<ZohoDeskTicketTimeEntrySummation>;
+/**
+ * Creates a {@link ZohoDeskGetTicketTimeEntrySummationFunction} bound to the given context.
+ *
+ * @param context - Authenticated Zoho Desk context
+ * @returns Function that retrieves time entry summation
+ */
+export declare function zohoDeskGetTicketTimeEntrySummation(context: ZohoDeskContext): ZohoDeskGetTicketTimeEntrySummationFunction;

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

@@ -0,0 +1,75 @@
+import { type FactoryWithRequiredInput } from '@dereekb/util';
+import { type ConfiguredFetch, type FetchJsonFunction } from '@dereekb/util/fetch';
+import { type ZohoApiUrl, type ZohoApiUrlKey, type ZohoConfig, type ZohoApiServiceName } from '../zoho.config';
+import { type ZohoAccessTokenStringFactory, type ZohoServiceAccessTokenKey } from '../accounts';
+import { type ZohoRateLimiterRef } from '../zoho.limit';
+import { type ZohoDeskOrgId } from './desk';
+/**
+ * Service identifier used for Zoho Desk API access token resolution and service routing.
+ */
+export declare const ZOHO_DESK_SERVICE_NAME: ZohoApiServiceName | ZohoServiceAccessTokenKey;
+/**
+ * Full base URL for the Zoho Desk API.
+ */
+export type ZohoDeskApiUrl = ZohoApiUrl;
+/**
+ * Well-known environment key for selecting a Zoho Desk API endpoint.
+ *
+ * Zoho Desk does not have a documented sandbox environment, so only 'production' is a known key.
+ * Custom URLs (including regional variants like desk.zoho.eu) can be passed directly.
+ */
+export type ZohoDeskApiUrlKey = ZohoApiUrlKey;
+/**
+ * Accepts either a well-known environment key or a custom full URL, allowing callers to target
+ * production or an arbitrary Desk endpoint (e.g., regional variants).
+ */
+export type ZohoDeskConfigApiUrlInput = ZohoDeskApiUrlKey | ZohoDeskApiUrl;
+/**
+ * Resolves a Desk API URL input to its full base URL. The 'production' key maps to the
+ * primary Zoho Desk endpoint; custom URLs pass through unchanged.
+ *
+ * @param input - A well-known environment key or a custom Desk API URL
+ * @returns The resolved full Zoho Desk API base URL
+ */
+export declare function zohoDeskConfigApiUrl(input: ZohoDeskConfigApiUrlInput): ZohoApiUrl;
+/**
+ * Configuration for a Zoho Desk service instance, including the target API URL and organization ID.
+ *
+ * Unlike other Zoho services (CRM, Recruit, Sign), the Desk API requires an `orgId` header
+ * on all requests.
+ */
+export interface ZohoDeskConfig extends ZohoConfig {
+    /**
+     * Organization ID required by all Zoho Desk API calls.
+     * Obtained from the Zoho Desk organization settings.
+     */
+    readonly orgId: ZohoDeskOrgId;
+}
+/**
+ * Input provided to a Desk fetch factory to construct an authenticated fetch instance for a specific API base URL.
+ */
+export interface ZohoDeskFetchFactoryParams {
+    readonly apiUrl: ZohoDeskApiUrl;
+    readonly orgId: ZohoDeskOrgId;
+}
+/**
+ * Factory that produces a pre-configured fetch instance bound to a specific Zoho Desk API URL and organization.
+ */
+export type ZohoDeskFetchFactory = FactoryWithRequiredInput<ConfiguredFetch, ZohoDeskFetchFactoryParams>;
+/**
+ * Core context for making authenticated Zoho Desk API calls. Bundles the configured fetch,
+ * JSON parsing, access token management, rate limiting, and service configuration needed
+ * by all Desk operations.
+ */
+export interface ZohoDeskContext extends ZohoRateLimiterRef {
+    readonly fetch: ConfiguredFetch;
+    readonly fetchJson: FetchJsonFunction;
+    readonly accessTokenStringFactory: ZohoAccessTokenStringFactory;
+    readonly config: ZohoDeskConfig;
+}
+/**
+ * Reference wrapper providing access to a {@link ZohoDeskContext}. Used for dependency injection across Desk service consumers.
+ */
+export interface ZohoDeskContextRef {
+    readonly deskContext: ZohoDeskContext;
+}

package/src/lib/desk/desk.contact.d.ts

@@ -0,0 +1,50 @@
+import { type Maybe } from '@dereekb/util';
+import { type ZohoDateTimeString } from '../zoho.type';
+import { type ZohoDeskContactId, type ZohoDeskAccountId } from './desk';
+/**
+ * Fields by which Zoho Desk contact lists can be sorted.
+ */
+export type ZohoDeskContactSortBy = 'firstName' | 'lastName' | 'modifiedTime' | 'phone' | 'createdTime' | 'email' | 'account';
+/**
+ * Related entities that can be expanded inline when fetching Zoho Desk contacts via the `include` query parameter.
+ */
+export type ZohoDeskContactInclude = 'owner' | 'accounts';
+/**
+ * A contact in Zoho Desk.
+ *
+ * Contacts represent end users or customers who submit support tickets.
+ */
+export interface ZohoDeskContact {
+    readonly id: ZohoDeskContactId;
+    readonly firstName?: Maybe<string>;
+    readonly lastName: string;
+    readonly email?: Maybe<string>;
+    readonly secondaryEmail?: Maybe<string>;
+    readonly phone?: Maybe<string>;
+    readonly mobile?: Maybe<string>;
+    readonly twitter?: Maybe<string>;
+    readonly facebook?: Maybe<string>;
+    readonly type?: Maybe<string>;
+    readonly title?: Maybe<string>;
+    readonly description?: Maybe<string>;
+    readonly photoURL?: Maybe<string>;
+    readonly webUrl?: Maybe<string>;
+    readonly accountId?: Maybe<ZohoDeskAccountId>;
+    readonly ownerId?: Maybe<string>;
+    readonly country?: Maybe<string>;
+    readonly state?: Maybe<string>;
+    readonly city?: Maybe<string>;
+    readonly street?: Maybe<string>;
+    readonly zip?: Maybe<string>;
+    readonly isDeleted?: Maybe<boolean>;
+    readonly isTrashed?: Maybe<boolean>;
+    readonly isEndUser?: Maybe<boolean>;
+    readonly isFollowing?: Maybe<boolean>;
+    readonly isAnonymous?: Maybe<boolean>;
+    readonly isSpam?: Maybe<boolean>;
+    readonly createdTime?: Maybe<ZohoDateTimeString>;
+    readonly modifiedTime?: Maybe<ZohoDateTimeString>;
+    readonly owner?: Maybe<Record<string, unknown>>;
+    readonly account?: Maybe<Record<string, unknown>>;
+    readonly cf?: Maybe<Record<string, unknown>>;
+}

package/src/lib/desk/desk.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Identifier of a Zoho Desk organization.
+ */
+export type ZohoDeskOrgId = string;
+/**
+ * Generic identifier in Zoho Desk.
+ */
+export type ZohoDeskId = string;
+/**
+ * Identifier of a ticket in Zoho Desk.
+ */
+export type ZohoDeskTicketId = string;
+/**
+ * Identifier of a contact in Zoho Desk.
+ */
+export type ZohoDeskContactId = string;
+/**
+ * Identifier of a product in Zoho Desk.
+ */
+export type ZohoDeskProductId = string;
+/**
+ * Identifier of a department in Zoho Desk.
+ */
+export type ZohoDeskDepartmentId = string;
+/**
+ * Identifier of an agent in Zoho Desk.
+ */
+export type ZohoDeskAgentId = string;
+/**
+ * Identifier of a team in Zoho Desk.
+ */
+export type ZohoDeskTeamId = string;
+/**
+ * Identifier of an account in Zoho Desk.
+ */
+export type ZohoDeskAccountId = string;
+/**
+ * Identifier of a contract in Zoho Desk.
+ */
+export type ZohoDeskContractId = string;
+/**
+ * Sort direction for Zoho Desk list queries.
+ */
+export type ZohoDeskSortOrder = 'asc' | 'desc';

package/src/lib/desk/desk.department.d.ts

@@ -0,0 +1,27 @@
+import { type Maybe } from '@dereekb/util';
+import { type ZohoDateTimeString } from '../zoho.type';
+import { type ZohoDeskDepartmentId } from './desk';
+/**
+ * Availability status of the live chat feature for a Zoho Desk department.
+ */
+export type ZohoDeskDepartmentChatStatus = 'AVAILABLE' | 'DISABLED' | 'NOT_CREATED';
+/**
+ * A department in Zoho Desk.
+ *
+ * Departments are organizational units that group tickets by functional area.
+ */
+export interface ZohoDeskDepartment {
+    readonly id: ZohoDeskDepartmentId;
+    readonly name: string;
+    readonly description?: Maybe<string>;
+    readonly isEnabled?: Maybe<boolean>;
+    readonly isDefault?: Maybe<boolean>;
+    readonly hasLogo?: Maybe<boolean>;
+    readonly chatStatus?: Maybe<ZohoDeskDepartmentChatStatus>;
+    readonly isVisibleInCustomerPortal?: Maybe<boolean>;
+    readonly nameInCustomerPortal?: Maybe<string>;
+    readonly isAssignToTeamEnabled?: Maybe<boolean>;
+    readonly creatorId?: Maybe<string>;
+    readonly createdTime?: Maybe<ZohoDateTimeString>;
+    readonly associatedAgentIds?: Maybe<string[]>;
+}

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

@@ -0,0 +1,33 @@
+import { type FetchResponseError } from '@dereekb/util/fetch';
+import { type ZohoServerErrorResponseData, type ZohoServerErrorResponseDataArrayRef, type ParsedZohoServerError } from '../zoho.error.api';
+/**
+ * Pre-configured console logger for Zoho Desk server errors.
+ * Data array errors are suppressed since they are handled separately.
+ */
+export declare const logZohoDeskErrorToConsole: import("..").LogZohoServerErrorFunction;
+/**
+ * Parses a fetch response error into a typed Zoho Desk 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 parseZohoDeskError(responseError: FetchResponseError): Promise<ParsedZohoServerError>;
+/**
+ * Parses a Zoho Desk error response body into a typed error. Delegates to Desk-specific
+ * error code handling before falling back to the generic Zoho error parser.
+ *
+ * @param errorResponseData - The raw error response data from the Zoho Desk 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 parseZohoDeskServerErrorResponseData(errorResponseData: ZohoServerErrorResponseData | ZohoServerErrorResponseDataArrayRef, responseError: FetchResponseError): ParsedZohoServerError;
+/**
+ * Fetch response interceptor that detects Zoho Desk error payloads hidden within HTTP 200 responses
+ * and converts them into proper errors.
+ */
+export declare const interceptZohoDesk200StatusWithErrorResponse: import("@dereekb/util/fetch").FetchJsonInterceptJsonResponseFunction;
+/**
+ * Wraps a fetch function with Zoho Desk error parsing and console logging,
+ * ensuring all Desk API errors are surfaced as typed exceptions.
+ */
+export declare const handleZohoDeskErrorFetch: import("..").HandleZohoErrorFetchFactory;

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

@@ -0,0 +1,47 @@
+import { type ZohoDeskConfig, type ZohoDeskContextRef, type ZohoDeskFetchFactory } from './desk.config';
+import { type LogZohoServerErrorFunction } from '../zoho.error.api';
+import { type ZohoAccountsContextRef } from '../accounts/accounts.config';
+import { type ZohoRateLimitedFetchHandlerConfig } from '../zoho.limit';
+import { type Maybe } from '@dereekb/util';
+/**
+ * Top-level Zoho Desk client instance, providing access to the authenticated {@link ZohoDeskContext}.
+ */
+export type ZohoDesk = ZohoDeskContextRef;
+/**
+ * Configuration for creating a {@link ZohoDeskFactory}, combining account credentials
+ * with optional overrides for rate limiting, fetch behavior, and error logging.
+ */
+export interface ZohoDeskFactoryConfig extends ZohoAccountsContextRef {
+    /**
+     * Custom rate limiter configuration to control request concurrency and throttling.
+     */
+    readonly rateLimiterConfig?: Maybe<ZohoRateLimitedFetchHandlerConfig>;
+    /**
+     * Custom fetch factory for creating the underlying HTTP client.
+     * Defaults to a standard fetch service with OAuth Bearer token and orgId headers and a 20-second timeout.
+     */
+    readonly fetchFactory?: ZohoDeskFetchFactory;
+    /**
+     * Custom error logging function invoked when Zoho API errors are encountered.
+     */
+    readonly logZohoServerErrorFunction?: LogZohoServerErrorFunction;
+}
+/**
+ * Factory function that creates a {@link ZohoDesk} client from a {@link ZohoDeskConfig}.
+ */
+export type ZohoDeskFactory = (config: ZohoDeskConfig) => ZohoDesk;
+/**
+ * Creates a {@link ZohoDeskFactory} from the given configuration.
+ *
+ * The factory pre-initializes shared resources (access token provider, rate limiter)
+ * once, then produces {@link ZohoDesk} client instances for each {@link ZohoDeskConfig}.
+ * Each client handles OAuth token refresh on {@link ZohoInvalidTokenError}, rate limiting,
+ * and Zoho Desk's non-standard error responses (200 status with error body).
+ *
+ * Unlike CRM/Recruit/Sign, the Desk API requires an `orgId` header on every request.
+ * This is injected automatically from the config.
+ *
+ * @param factoryConfig - Configuration providing account credentials and optional overrides
+ * @returns A factory function that creates authenticated Zoho Desk clients
+ */
+export declare function zohoDeskFactory(factoryConfig: ZohoDeskFactoryConfig): ZohoDeskFactory;

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

@@ -0,0 +1,39 @@
+import { type Maybe } from '@dereekb/util';
+import { type ZohoRateLimitResponseDetails, type ZohoRateLimitedFetchHandler, type ZohoRateLimitedFetchHandlerConfig } from '../zoho.limit';
+/**
+ * Header name for the credit weight consumed by the last Zoho Desk API request.
+ */
+export declare const ZOHO_DESK_RATE_LIMIT_WEIGHT_HEADER = "X-Rate-Limit-Request-Weight-v3";
+/**
+ * Header name for the remaining API credits in the current Zoho Desk rate limit window.
+ */
+export declare const ZOHO_DESK_RATE_LIMIT_REMAINING_HEADER = "X-Rate-Limit-Remaining-v3";
+/**
+ * Header name indicating how many seconds to wait before retrying after a Zoho Desk 429 response.
+ */
+export declare const ZOHO_DESK_RETRY_AFTER_HEADER = "Retry-After";
+/**
+ * Default rate limit for Zoho Desk API requests (credits per minute).
+ */
+export declare const DEFAULT_ZOHO_DESK_API_RATE_LIMIT = 200;
+/**
+ * Reads rate limit details from Zoho Desk v3 response headers.
+ *
+ * Desk uses a credit-based system with `X-Rate-Limit-Remaining-v3` and `Retry-After` (in seconds)
+ * rather than the `X-RATELIMIT-*` headers used by CRM/Recruit/Sign.
+ *
+ * @param headers - HTTP response headers from a Zoho Desk API call
+ * @returns Parsed rate limit details, or null if the Desk rate limit headers are absent
+ */
+export declare function zohoDeskRateLimitDetailsReader(headers: Headers): Maybe<ZohoRateLimitResponseDetails>;
+/**
+ * Creates a {@link ZohoRateLimitedFetchHandler} configured for Zoho Desk's v3 rate limit headers.
+ *
+ * This is a convenience wrapper around {@link makeZohoRateLimitedFetchHandler} pre-configured
+ * with the Desk-specific header reader. Unlike CRM, Desk does not provide a total limit header,
+ * so the configured `maxRateLimit` (defaulting to {@link DEFAULT_ZOHO_DESK_API_RATE_LIMIT}) is used throughout.
+ *
+ * @param config - Optional configuration for rate limit, reset period, and 429 handling
+ * @returns A rate-limited fetch handler with the underlying rate limiter accessible via `_rateLimiter`
+ */
+export declare function zohoDeskRateLimitedFetchHandler(config?: Maybe<ZohoRateLimitedFetchHandlerConfig>): ZohoRateLimitedFetchHandler;