@dereekb/zoho 13.8.0 → 13.10.0

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

@@ -0,0 +1,308 @@
+import { type Maybe } from '@dereekb/util';
+import { type ZohoDateTimeString } from '../zoho.type';
+import { type ZohoDeskTicketId, type ZohoDeskContactId, type ZohoDeskProductId, type ZohoDeskDepartmentId, type ZohoDeskAgentId, type ZohoDeskTeamId, type ZohoDeskAccountId, type ZohoDeskContractId } from './desk';
+/**
+ * High-level ticket status category in Zoho Desk.
+ */
+export type ZohoDeskTicketStatusType = 'Open' | 'Closed' | 'On Hold';
+/**
+ * Ticket priority level in Zoho Desk.
+ *
+ * Known values include Low, Medium, High, and Urgent. Custom priorities may also be defined.
+ */
+export type ZohoDeskTicketPriority = 'Low' | 'Medium' | 'High' | 'Urgent' | string;
+/**
+ * Communication channel through which a Zoho Desk ticket was created.
+ *
+ * Known values include Phone, Email, Social, Web, Chat, and Forums. Custom channels may also be present.
+ */
+export type ZohoDeskTicketChannel = 'Phone' | 'Email' | 'Social' | 'Web' | 'Chat' | 'Forums' | string;
+/**
+ * Fields by which Zoho Desk ticket lists can be sorted.
+ */
+export type ZohoDeskTicketSortBy = 'ticketNumber' | 'modifiedTime' | 'customerResponseTime' | 'recentThread' | 'responseDueDate' | 'dueDate' | 'createdTime';
+/**
+ * Related entities that can be expanded inline when fetching Zoho Desk tickets via the `include` query parameter.
+ */
+export type ZohoDeskTicketInclude = 'isRead' | 'departments' | 'team' | 'assignee' | 'contacts' | 'products';
+/**
+ * Describes the originating source application or service for a Zoho Desk ticket.
+ */
+export interface ZohoDeskTicketSource {
+    readonly appName?: Maybe<string>;
+    readonly extId?: Maybe<string>;
+    readonly type?: Maybe<string>;
+    readonly permalink?: Maybe<string>;
+    readonly appPhotoURL?: Maybe<string>;
+}
+/**
+ * A support ticket in Zoho Desk.
+ *
+ * Contains the full set of fields returned by the Zoho Desk Tickets API.
+ */
+export interface ZohoDeskTicket {
+    readonly id: ZohoDeskTicketId;
+    readonly ticketNumber: string;
+    readonly subject: string;
+    readonly description?: Maybe<string>;
+    readonly status: string;
+    readonly statusType: ZohoDeskTicketStatusType;
+    readonly priority?: Maybe<ZohoDeskTicketPriority>;
+    readonly classification?: Maybe<string>;
+    readonly category?: Maybe<string>;
+    readonly subCategory?: Maybe<string>;
+    readonly channel?: Maybe<ZohoDeskTicketChannel>;
+    readonly channelCode?: Maybe<string>;
+    readonly email?: Maybe<string>;
+    readonly phone?: Maybe<string>;
+    readonly webUrl?: Maybe<string>;
+    readonly sentiment?: Maybe<string>;
+    readonly resolution?: Maybe<string>;
+    readonly departmentId?: Maybe<ZohoDeskDepartmentId>;
+    readonly contactId?: Maybe<ZohoDeskContactId>;
+    readonly productId?: Maybe<ZohoDeskProductId>;
+    readonly accountId?: Maybe<ZohoDeskAccountId>;
+    readonly assigneeId?: Maybe<ZohoDeskAgentId>;
+    readonly teamId?: Maybe<ZohoDeskTeamId>;
+    readonly contractId?: Maybe<ZohoDeskContractId>;
+    readonly dueDate?: Maybe<ZohoDateTimeString>;
+    readonly responseDueDate?: Maybe<ZohoDateTimeString>;
+    readonly createdTime?: Maybe<ZohoDateTimeString>;
+    readonly modifiedTime?: Maybe<ZohoDateTimeString>;
+    readonly closedTime?: Maybe<ZohoDateTimeString>;
+    readonly onholdTime?: Maybe<ZohoDateTimeString>;
+    readonly customerResponseTime?: Maybe<ZohoDateTimeString>;
+    readonly threadCount?: Maybe<number>;
+    readonly commentCount?: Maybe<number>;
+    readonly taskCount?: Maybe<number>;
+    readonly sharedCount?: Maybe<number>;
+    readonly approvalCount?: Maybe<number>;
+    readonly followerCount?: Maybe<number>;
+    readonly tagCount?: Maybe<number>;
+    readonly attachmentCount?: Maybe<number>;
+    readonly timeEntryCount?: Maybe<number>;
+    readonly isTrashed?: Maybe<boolean>;
+    readonly isResponseOverdue?: Maybe<boolean>;
+    readonly isSpam?: Maybe<boolean>;
+    readonly isRead?: Maybe<boolean>;
+    readonly isDeleted?: Maybe<boolean>;
+    readonly isFollowing?: Maybe<boolean>;
+    readonly source?: Maybe<ZohoDeskTicketSource>;
+    readonly secondaryContacts?: Maybe<string[]>;
+    readonly createdBy?: Maybe<string>;
+    readonly modifiedBy?: Maybe<string>;
+    readonly product?: Maybe<Record<string, unknown>>;
+    readonly contact?: Maybe<Record<string, unknown>>;
+    readonly team?: Maybe<Record<string, unknown>>;
+    readonly assignee?: Maybe<Record<string, unknown>>;
+    readonly department?: Maybe<Record<string, unknown>>;
+    readonly cf?: Maybe<Record<string, unknown>>;
+}
+/**
+ * Performance and SLA metrics for a single Zoho Desk ticket, returned by the ticket metrics endpoint.
+ */
+export interface ZohoDeskTicketMetrics {
+    readonly reopenCount?: Maybe<number>;
+    readonly firstResponseTime?: Maybe<string>;
+    readonly averageResponseTime?: Maybe<string>;
+    readonly resolutionTime?: Maybe<string>;
+    readonly happinessRating?: Maybe<string>;
+    readonly assigneeChanges?: Maybe<number>;
+    readonly threadCount?: Maybe<number>;
+    readonly responseCount?: Maybe<number>;
+}
+/**
+ * Ticket count data for a single agent, returned by the agents ticket count endpoint.
+ */
+export interface ZohoDeskAgentTicketCount {
+    readonly agentId: ZohoDeskAgentId;
+    readonly count: number;
+}
+/**
+ * A tag associated with a Zoho Desk ticket.
+ */
+export interface ZohoDeskTicketTag {
+    readonly id: string;
+    readonly name: string;
+    readonly createdTime?: Maybe<ZohoDateTimeString>;
+    readonly ticketCount?: Maybe<number>;
+}
+/**
+ * A follower of a Zoho Desk ticket (typically an agent).
+ */
+export interface ZohoDeskTicketFollower {
+    readonly id: string;
+    readonly name?: Maybe<string>;
+    readonly email?: Maybe<string>;
+    readonly photoURL?: Maybe<string>;
+}
+/**
+ * Fields by which Zoho Desk ticket attachment lists can be sorted.
+ */
+export type ZohoDeskAttachmentSortBy = 'createdTime';
+/**
+ * Related entities that can be expanded when fetching ticket attachments.
+ */
+export type ZohoDeskAttachmentInclude = 'creator';
+/**
+ * A file attachment on a Zoho Desk ticket.
+ */
+export interface ZohoDeskTicketAttachment {
+    readonly id: string;
+    readonly name: string;
+    readonly size?: Maybe<string>;
+    readonly href?: Maybe<string>;
+    readonly isPublic?: Maybe<boolean>;
+    readonly creatorId?: Maybe<string>;
+    readonly createdTime?: Maybe<ZohoDateTimeString>;
+    readonly creator?: Maybe<Record<string, unknown>>;
+}
+/**
+ * Content type of a Zoho Desk ticket comment.
+ */
+export type ZohoDeskCommentContentType = 'plainText' | 'html';
+/**
+ * Fields by which Zoho Desk ticket comment lists can be sorted.
+ */
+export type ZohoDeskCommentSortBy = 'commentedTime';
+/**
+ * Related entities that can be expanded when fetching ticket comments.
+ */
+export type ZohoDeskCommentInclude = 'mentions';
+/**
+ * A comment on a Zoho Desk ticket.
+ */
+export interface ZohoDeskTicketComment {
+    readonly id: string;
+    readonly content: string;
+    readonly encodedContent?: Maybe<string>;
+    readonly contentType?: Maybe<ZohoDeskCommentContentType>;
+    readonly commenterId?: Maybe<string>;
+    readonly commentedTime?: Maybe<ZohoDateTimeString>;
+    readonly modifiedTime?: Maybe<ZohoDateTimeString>;
+    readonly isPublic?: Maybe<boolean>;
+    readonly attachmentIds?: Maybe<string[]>;
+    readonly commenter?: Maybe<Record<string, unknown>>;
+    readonly mentions?: Maybe<Record<string, unknown>[]>;
+}
+/**
+ * A time entry recorded against a Zoho Desk ticket.
+ */
+export interface ZohoDeskTicketTimeEntry {
+    readonly id: string;
+    readonly ownerId?: Maybe<string>;
+    readonly billingType?: Maybe<string>;
+    readonly description?: Maybe<string>;
+    readonly executedTime?: Maybe<ZohoDateTimeString>;
+    readonly createdTime?: Maybe<ZohoDateTimeString>;
+    readonly hh?: Maybe<string>;
+    readonly mm?: Maybe<string>;
+    readonly requestedBy?: Maybe<string>;
+    readonly agentCostPerHour?: Maybe<string>;
+    readonly additionalCost?: Maybe<string>;
+    readonly totalCost?: Maybe<string>;
+}
+/**
+ * Timer state for a Zoho Desk ticket.
+ */
+export interface ZohoDeskTicketTimer {
+    readonly isBillable?: Maybe<boolean>;
+    readonly timerAction?: Maybe<string>;
+    readonly startedTime?: Maybe<ZohoDateTimeString>;
+}
+/**
+ * Communication channel for a thread.
+ */
+export type ZohoDeskThreadChannel = 'EMAIL' | 'PHONE' | 'WEB' | 'CUSTOMERPORTAL' | 'FORUMS' | 'FACEBOOK' | 'TWITTER' | 'TWITTER_DM' | 'ONLINE_CHAT' | 'OFFLINE_CHAT' | 'FEEDBACK' | 'FEEDBACK_WIDGET' | string;
+/**
+ * Direction of a thread message relative to the support team.
+ */
+export type ZohoDeskThreadDirection = 'in' | 'out';
+/**
+ * Visibility of a thread to end users.
+ */
+export type ZohoDeskThreadVisibility = 'public' | 'private';
+/**
+ * Delivery status of a thread.
+ */
+export type ZohoDeskThreadStatus = 'SUCCESS' | 'FAILED' | 'DRAFT' | 'PENDING';
+/**
+ * Related entities that can be expanded when fetching threads.
+ */
+export type ZohoDeskThreadInclude = 'plainText';
+/**
+ * A conversation thread on a Zoho Desk ticket (email, reply, note, etc.).
+ */
+export interface ZohoDeskTicketThread {
+    readonly id: string;
+    readonly content?: Maybe<string>;
+    readonly contentType?: Maybe<string>;
+    readonly direction?: Maybe<ZohoDeskThreadDirection>;
+    readonly channel?: Maybe<ZohoDeskThreadChannel>;
+    readonly visibility?: Maybe<ZohoDeskThreadVisibility>;
+    readonly status?: Maybe<ZohoDeskThreadStatus>;
+    readonly summary?: Maybe<string>;
+    readonly to?: Maybe<string>;
+    readonly cc?: Maybe<string>;
+    readonly bcc?: Maybe<string>;
+    readonly fromEmailAddress?: Maybe<string>;
+    readonly responderId?: Maybe<string>;
+    readonly replyTo?: Maybe<string>;
+    readonly fullContentURL?: Maybe<string>;
+    readonly isDescriptionThread?: Maybe<boolean>;
+    readonly isContentTruncated?: Maybe<boolean>;
+    readonly canReply?: Maybe<boolean>;
+    readonly isForward?: Maybe<boolean>;
+    readonly hasAttach?: Maybe<boolean>;
+    readonly attachmentCount?: Maybe<number>;
+    readonly createdTime?: Maybe<ZohoDateTimeString>;
+    readonly author?: Maybe<Record<string, unknown>>;
+    readonly source?: Maybe<Record<string, unknown>>;
+    readonly channelRelatedInfo?: Maybe<Record<string, unknown>>;
+    readonly plainText?: Maybe<string>;
+    readonly attachments?: Maybe<Record<string, unknown>[]>;
+}
+/**
+ * Type of activity associated with a ticket.
+ */
+export type ZohoDeskActivityType = 'Tasks' | 'Events' | 'Calls';
+/**
+ * Status of a ticket activity.
+ */
+export type ZohoDeskActivityStatus = 'Scheduled' | 'Completed' | 'Missed' | 'In Progress' | 'Canceled';
+/**
+ * Direction of a ticket activity.
+ */
+export type ZohoDeskActivityDirection = 'inbound' | 'outbound';
+/**
+ * Related entities that can be expanded when fetching activities.
+ */
+export type ZohoDeskActivityInclude = 'ticket' | 'contact' | 'assignee' | 'team';
+/**
+ * An activity (task, event, or call) associated with a Zoho Desk ticket.
+ */
+export interface ZohoDeskTicketActivity {
+    readonly id: string;
+    readonly activityType?: Maybe<ZohoDeskActivityType>;
+    readonly status?: Maybe<ZohoDeskActivityStatus>;
+    readonly direction?: Maybe<ZohoDeskActivityDirection>;
+    readonly subject?: Maybe<string>;
+    readonly description?: Maybe<string>;
+    readonly category?: Maybe<string>;
+    readonly priority?: Maybe<string>;
+    readonly ticketId?: Maybe<ZohoDeskTicketId>;
+    readonly contactId?: Maybe<ZohoDeskContactId>;
+    readonly departmentId?: Maybe<ZohoDeskDepartmentId>;
+    readonly creatorId?: Maybe<string>;
+    readonly ownerId?: Maybe<string>;
+    readonly dueDate?: Maybe<ZohoDateTimeString>;
+    readonly startTime?: Maybe<ZohoDateTimeString>;
+    readonly createdTime?: Maybe<ZohoDateTimeString>;
+    readonly completedTime?: Maybe<ZohoDateTimeString>;
+    readonly isCommented?: Maybe<boolean>;
+    readonly webUrl?: Maybe<string>;
+    readonly ticket?: Maybe<Record<string, unknown>>;
+    readonly contact?: Maybe<Record<string, unknown>>;
+    readonly assignee?: Maybe<Record<string, unknown>>;
+    readonly team?: Maybe<Record<string, unknown>>;
+}

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

@@ -0,0 +1,21 @@
+export * from './desk';
+export * from './desk.ticket';
+export * from './desk.department';
+export * from './desk.contact';
+export * from './desk.agent';
+export * from './desk.config';
+export * from './desk.factory';
+export * from './desk.error.api';
+export * from './desk.limit';
+export * from './desk.api.page';
+export * from './desk.api.tickets';
+export * from './desk.api.departments';
+export * from './desk.api.contacts';
+export * from './desk.api.tags';
+export * from './desk.api.followers';
+export * from './desk.api.attachments';
+export * from './desk.api.comments';
+export * from './desk.api.time';
+export * from './desk.api.threads';
+export * from './desk.api.activities';
+export * from './desk.api.agents';

package/src/lib/index.d.ts

@@ -1,6 +1,7 @@
 export * from './recruit';
 export * from './crm';
 export * from './sign';
+export * from './desk';
 export * from './accounts';
 export * from './zoho.error.api';
 export * from './zoho.api.page';

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

@@ -12,13 +12,13 @@ export interface ZohoRateLimiterRef {
  *
  * Typically used for logging or alerting. Any errors thrown by this function are silently ignored.
  */
-export type ZohoRateLimitedTooManyRequestsLogFunction = (headers: ZohoRateLimitHeaderDetails, response: Response, fetchResponseError?: FetchResponseError) => PromiseOrValue<void>;
+export type ZohoRateLimitedTooManyRequestsLogFunction = (headers: ZohoRateLimitHeaderDetails | ZohoRateLimitResponseDetails, response: Response, fetchResponseError?: FetchResponseError) => PromiseOrValue<void>;
 /**
  * Default handler that logs a warning to the console when the Zoho API rate limit is exceeded.
  *
- * @param headers - Rate limit details extracted from the Zoho API response headers
+ * @param details - Rate limit details extracted from the Zoho API response headers
  */
-export declare const DEFAULT_ZOHO_RATE_LIMITED_TOO_MANY_REQUESTS_LOG_FUNCTION: (headers: ZohoRateLimitHeaderDetails) => void;
+export declare const DEFAULT_ZOHO_RATE_LIMITED_TOO_MANY_REQUESTS_LOG_FUNCTION: (details: ZohoRateLimitHeaderDetails | ZohoRateLimitResponseDetails) => void;
 /**
  * Configuration for the Zoho rate-limited fetch handler, allowing customization of
  * the rate limit, reset period, and 429 response handling.
@@ -28,7 +28,7 @@ export interface ZohoRateLimitedFetchHandlerConfig {
      * Custom maximum number of requests allowed per reset period.
      *
      * Defaults to {@link DEFAULT_ZOHO_API_RATE_LIMIT} (100 requests).
-     * The actual limit may be dynamically adjusted based on `X-RATELIMIT-LIMIT` response headers.
+     * The actual limit may be dynamically adjusted based on rate limit response headers.
      *
      * Rate limits vary by Zoho account type:
      *
@@ -51,7 +51,7 @@ export interface ZohoRateLimitedFetchHandlerConfig {
     /**
      * Optional callback invoked when a 429 Too Many Requests response is received.
      *
-     * Defaults to {@link DEFAULT_ZOHO_RATE_LIMITED_TOO_MANY_REQUETS_LOG_FUNCTION}.
+     * Defaults to {@link DEFAULT_ZOHO_RATE_LIMITED_TOO_MANY_REQUESTS_LOG_FUNCTION}.
      * Pass `false` to disable the callback entirely.
      */
     readonly onTooManyRequests?: ZohoRateLimitedTooManyRequestsLogFunction | false;
@@ -62,22 +62,78 @@ export interface ZohoRateLimitedFetchHandlerConfig {
  */
 export type ZohoRateLimitedFetchHandler = RateLimitedFetchHandler<ResetPeriodPromiseRateLimiter>;
 /**
- * Creates a {@link ZohoRateLimitedFetchHandler} that throttles outgoing requests based on
- * Zoho's rate limit headers (`X-RATELIMIT-LIMIT`, `X-RATELIMIT-REMAINING`, `X-RATELIMIT-RESET`).
+ * Service-agnostic rate limit details parsed from response headers.
  *
+ * Each Zoho service (CRM, Recruit, Desk, etc.) provides its own reader function
+ * that maps service-specific headers to this common shape.
+ */
+export interface ZohoRateLimitResponseDetails {
+    /**
+     * Number of remaining allowed requests in the current period.
+     */
+    readonly remaining: number;
+    /**
+     * Total request limit for the current period. Optional because some services
+     * (e.g., Zoho Desk) do not provide this in response headers.
+     */
+    readonly limit?: Maybe<number>;
+    /**
+     * The time at which the rate limit window resets. Optional because the computation
+     * differs per service (e.g., CRM provides a Unix timestamp, Desk provides a Retry-After in seconds).
+     */
+    readonly resetAt?: Maybe<Date>;
+}
+/**
+ * Reads rate limit details from HTTP response headers.
+ * Returns null when the expected headers are absent (e.g., error responses).
+ */
+export type ZohoReadRateLimitDetailsFunction = (headers: Headers) => Maybe<ZohoRateLimitResponseDetails>;
+/**
+ * Configuration for {@link makeZohoRateLimitedFetchHandler}, extending the base handler config
+ * with a service-specific header reader function.
+ */
+export interface MakeZohoRateLimitedFetchHandlerConfig extends ZohoRateLimitedFetchHandlerConfig {
+    /**
+     * Parses service-specific rate limit headers into the common {@link ZohoRateLimitResponseDetails} shape.
+     */
+    readonly readRateLimitDetails: ZohoReadRateLimitDetailsFunction;
+}
+/**
+ * Creates a {@link ZohoRateLimitedFetchHandler} using a configurable header reader function.
+ *
+ * This is the core rate limiter factory that all service-specific wrappers delegate to.
  * The handler uses an exponential backoff strategy with the following behavior:
  * - Rate limiting begins after 10% of the allowed requests have been made (`startLimitAt`)
  * - Wait times increase exponentially (rate 1.08) as more requests are made, capped at 10 seconds
- * - On each response, the limiter updates its remaining count and reset time from headers
- * - When the API returns a different limit than configured, the limiter dynamically adjusts
+ * - On each response, the limiter updates its remaining count and reset time via the provided reader
+ * - When the API reports a different limit than configured, the limiter dynamically adjusts
  * - On 429 responses, the request is automatically retried after the rate limiter delay
  * - The limiter is disabled when responses lack rate limit headers (e.g., error responses)
  *
+ * @param config - Configuration including the service-specific header reader, rate limit, reset period, and 429 handling
+ * @returns A rate-limited fetch handler with the underlying rate limiter accessible via `_rateLimiter`
+ */
+export declare function makeZohoRateLimitedFetchHandler(config: MakeZohoRateLimitedFetchHandlerConfig): ZohoRateLimitedFetchHandler;
+/**
+ * Creates a {@link ZohoRateLimitedFetchHandler} that throttles outgoing requests based on
+ * Zoho's CRM/Recruit/Sign rate limit headers (`X-RATELIMIT-LIMIT`, `X-RATELIMIT-REMAINING`, `X-RATELIMIT-RESET`).
+ *
+ * This is a convenience wrapper around {@link makeZohoRateLimitedFetchHandler} pre-configured
+ * with the standard Zoho rate limit header reader.
+ *
  * @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 zohoRateLimitedFetchHandler(config?: Maybe<ZohoRateLimitedFetchHandlerConfig>): ZohoRateLimitedFetchHandler;
+/**
+ * Reads rate limit details from standard Zoho API response headers (`X-RATELIMIT-*`).
+ * Used by CRM, Recruit, and Sign services.
+ *
+ * @param headers - HTTP response headers
+ * @returns Parsed rate limit details, or null if headers are absent
+ */
+export declare function zohoStandardRateLimitDetailsReader(headers: Headers): Maybe<ZohoRateLimitResponseDetails>;
 /**
  * @deprecated use DEFAULT_ZOHO_RATE_LIMITED_TOO_MANY_REQUESTS_LOG_FUNCTION instead.
  */
-export declare const DEFAULT_ZOHO_RATE_LIMITED_TOO_MANY_REQUETS_LOG_FUNCTION: (headers: ZohoRateLimitHeaderDetails) => void;
+export declare const DEFAULT_ZOHO_RATE_LIMITED_TOO_MANY_REQUETS_LOG_FUNCTION: (details: ZohoRateLimitHeaderDetails | ZohoRateLimitResponseDetails) => void;