@dereekb/zoho 13.39.0 → 13.40.0

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

@@ -0,0 +1,150 @@
+import { type Maybe } from '@dereekb/util';
+import { type FetchJsonInterceptJsonResponseFunction, FetchResponseError } from '@dereekb/util/fetch';
+import { type ParsedZohoServerError, type ZohoServerErrorData, ZohoServerFetchResponseError } from '../zoho.error.api';
+/**
+ * Value of the `status` field on a successful Zoho Analytics response.
+ */
+export declare const ZOHO_ANALYTICS_SUCCESS_STATUS = "success";
+/**
+ * Value of the `status` field on a failed Zoho Analytics response.
+ */
+export declare const ZOHO_ANALYTICS_FAILURE_STATUS = "failure";
+/**
+ * Numeric error code returned by the Zoho Analytics API.
+ *
+ * Analytics identifies errors with numbers (e.g. `8535`) rather than the symbolic string codes
+ * (e.g. `'INVALID_TOKEN'`) used by CRM, Recruit, Desk and Sign.
+ */
+export type ZohoAnalyticsErrorCode = number | string;
+/**
+ * The error payload nested under `data` on a failed Zoho Analytics response.
+ */
+export interface ZohoAnalyticsErrorResponseDataError {
+    readonly errorCode?: Maybe<ZohoAnalyticsErrorCode>;
+    readonly errorMessage?: Maybe<string>;
+}
+/**
+ * Error response returned by the Zoho Analytics API.
+ *
+ * Analytics uses its own envelope rather than the `{ error }` / `{ data: [] }` shapes returned by
+ * the other Zoho services:
+ *
+ * ```json
+ * {"status":"failure","summary":"META_DBNAME_DUPLICATE",
+ *  "data":{"errorCode":7101,"errorMessage":"Workspace with the same name exists already"}}
+ * ```
+ *
+ * @see https://www.zoho.com/analytics/api/v2/api-specification.html
+ */
+export interface ZohoAnalyticsErrorResponseData {
+    readonly status?: Maybe<string>;
+    /**
+     * Symbolic constant naming the failure, e.g. `'META_DBNAME_DUPLICATE'`.
+     */
+    readonly summary?: Maybe<string>;
+    readonly data?: Maybe<ZohoAnalyticsErrorResponseDataError>;
+}
+/**
+ * Extra detail attached to a parsed Zoho Analytics error.
+ */
+export interface ZohoAnalyticsServerErrorDetails {
+    /**
+     * The `summary` constant from the Analytics error envelope.
+     */
+    readonly summary?: Maybe<string>;
+}
+/**
+ * Error code returned when the provided OAuth token is invalid or expired.
+ *
+ * Mapped to {@link ZohoInvalidTokenError} so that the Analytics fetch wrapper clears the cached
+ * access token and the next request retrieves a fresh one.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/common-error-codes.html
+ */
+export declare const ZOHO_ANALYTICS_INVALID_OAUTH_TOKEN_ERROR_CODE = "8535";
+/**
+ * Error code returned when the `ZANALYTICS-ORGID` header is missing from the request.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/common-error-codes.html
+ */
+export declare const ZOHO_ANALYTICS_ORG_ID_NOT_PRESENT_ERROR_CODE = "8083";
+/**
+ * Error code returned when the per-minute API frequency limit is exceeded.
+ *
+ * Analytics allows 100 requests per minute overall (40/min for bulk operations, 60/min for
+ * metadata).
+ *
+ * @see https://www.zoho.com/analytics/api/v2/api-limits-pricing/api-frequency.html
+ */
+export declare const ZOHO_ANALYTICS_FREQUENCY_LIMIT_ERROR_CODE = "6045";
+/**
+ * Error codes returned when the plan's daily API unit quota is exhausted.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/api-limits-pricing/api-units.html
+ */
+export declare const ZOHO_ANALYTICS_DAILY_UNIT_LIMIT_ERROR_CODES: string[];
+/**
+ * Error raised when a Zoho Analytics request omits the required organization id header.
+ *
+ * Indicates the `ZohoAnalyticsConfig` is missing its `orgId`.
+ */
+export declare class ZohoAnalyticsMissingOrgIdError extends ZohoServerFetchResponseError {
+}
+/**
+ * Returns true when the input looks like a failed Zoho Analytics response envelope.
+ *
+ * @param value - A parsed JSON response body.
+ * @returns Whether the body is an Analytics failure envelope.
+ */
+export declare function isZohoAnalyticsErrorResponseData(value: unknown): value is ZohoAnalyticsErrorResponseData;
+/**
+ * Normalizes a Zoho Analytics error envelope into the shared {@link ZohoServerErrorData} shape,
+ * stringifying the numeric error code so it can be compared against the shared string codes.
+ *
+ * @param errorResponseData - The Analytics failure envelope.
+ * @returns Normalized error data with code, message and the originating summary as details.
+ */
+export declare function zohoAnalyticsServerErrorData(errorResponseData: ZohoAnalyticsErrorResponseData): ZohoServerErrorData<ZohoAnalyticsServerErrorDetails>;
+/**
+ * Parses a Zoho Analytics response body into a typed error.
+ *
+ * Analytics error codes are numeric and unrelated to the symbolic codes the shared parser knows,
+ * so the Analytics-specific codes are classified here. Bodies that are not Analytics failure
+ * envelopes fall through to the shared parser, which covers errors raised upstream of Analytics
+ * (for example by Zoho Accounts during a token exchange).
+ *
+ * @param errorResponseData - The raw response body from the Zoho Analytics 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 parseZohoAnalyticsServerErrorResponseData(errorResponseData: unknown, responseError: FetchResponseError): ParsedZohoServerError;
+/**
+ * Pre-configured console logger for Zoho Analytics server errors.
+ */
+export declare const logZohoAnalyticsErrorToConsole: import("..").LogZohoServerErrorFunction;
+/**
+ * Parses a fetch response error into a typed Zoho Analytics error by reading 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 parseZohoAnalyticsError(responseError: FetchResponseError): Promise<ParsedZohoServerError>;
+/**
+ * Fetch response interceptor that detects a Zoho Analytics failure envelope returned with an HTTP
+ * 200 status and converts it into a thrown error.
+ *
+ * The shared `interceptZohoErrorResponseFactory` cannot be reused here: it looks for an
+ * `error` key, which Analytics never sets.
+ *
+ * @param json - The parsed response body.
+ * @param response - The originating HTTP response.
+ * @returns The body unchanged when it is not a failure envelope.
+ * @throws {ZohoServerFetchResponseError} When the body is an Analytics failure envelope.
+ */
+export declare const interceptZohoAnalytics200StatusWithErrorResponse: FetchJsonInterceptJsonResponseFunction;
+/**
+ * Wraps a fetch function with Zoho Analytics error parsing and console logging, ensuring all
+ * Analytics API errors are surfaced as typed exceptions.
+ */
+export declare const handleZohoAnalyticsErrorFetch: import("..").HandleZohoErrorFetchFactory;

package/src/lib/analytics/analytics.export.d.ts

@@ -0,0 +1,91 @@
+import { type WebsiteUrl } from '@dereekb/util';
+import { type ZohoAnalyticsCriteria, type ZohoAnalyticsName } from './analytics';
+import { type ZohoAnalyticsDelimiter, type ZohoAnalyticsQuoted } from './analytics.import';
+import { type ZohoAnalyticsJobStatus } from './analytics.job';
+/**
+ * Format of exported Zoho Analytics data.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/bulk-api/export-data.html
+ */
+export type ZohoAnalyticsExportResponseFormat = 'csv' | 'json' | 'xml' | 'xls' | 'pdf' | 'html' | 'image';
+/**
+ * Record delimiter of exported CSV data. `0` DOS, `1` UNIX, `2` MAC.
+ */
+export type ZohoAnalyticsRecordDelimiter = 0 | 1 | 2;
+/**
+ * Options controlling a Zoho Analytics data export.
+ *
+ * Only the data-oriented options are modeled. The presentation options that apply to the `pdf`,
+ * `html` and `image` formats (margins, headers, paper size, and so on) are not, since they are
+ * unrelated to moving data; pass them by extending this type if they are ever needed.
+ *
+ * Note there is no offset or limit option: Zoho Analytics does not paginate row data. Narrow a
+ * large export with `criteria` and `selectedColumns`, or use an asynchronous export job.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/bulk-api/export-data.html
+ */
+export interface ZohoAnalyticsExportConfig {
+    readonly responseFormat: ZohoAnalyticsExportResponseFormat;
+    /**
+     * Restricts the export to rows matching this filter expression.
+     */
+    readonly criteria?: ZohoAnalyticsCriteria;
+    /**
+     * Restricts the export to these columns.
+     */
+    readonly selectedColumns?: ZohoAnalyticsName[];
+    readonly showHiddenCols?: boolean;
+    readonly showPersonalCols?: boolean;
+    /**
+     * CSV only. Field delimiter.
+     */
+    readonly delimiter?: ZohoAnalyticsDelimiter;
+    /**
+     * CSV only. Record delimiter.
+     */
+    readonly recordDelimiter?: ZohoAnalyticsRecordDelimiter;
+    /**
+     * CSV only. Quote character.
+     */
+    readonly quoted?: ZohoAnalyticsQuoted;
+    /**
+     * CSV only. Whether to include a header row. Defaults to true.
+     */
+    readonly includeHeader?: boolean;
+    /**
+     * JSON only. Whether to emit rows as column-name/value pairs. Defaults to true.
+     */
+    readonly keyValueFormat?: boolean;
+}
+/**
+ * Options for an asynchronous export job.
+ */
+export interface ZohoAnalyticsExportJobConfig extends ZohoAnalyticsExportConfig {
+    /**
+     * URL that Zoho posts the job's completion status to.
+     */
+    readonly callbackUrl?: WebsiteUrl;
+}
+/**
+ * Options for an asynchronous export job driven by a SQL query.
+ *
+ * This runs an ad-hoc query and exports its result. It does not create anything: to persist a
+ * query as a reusable view, create a query table through the Modeling API instead.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/bulk-api/export-data-async/create-export/sql-query.html
+ */
+export interface ZohoAnalyticsExportJobSqlQueryConfig extends ZohoAnalyticsExportJobConfig {
+    /**
+     * The SQL `SELECT` statement to export the results of.
+     */
+    readonly sqlQuery: string;
+}
+/**
+ * Status of an asynchronous export job.
+ */
+export interface ZohoAnalyticsExportJobStatus extends ZohoAnalyticsJobStatus {
+    /**
+     * URL the exported file can be downloaded from once the job has completed.
+     */
+    readonly downloadUrl?: WebsiteUrl;
+}

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

@@ -0,0 +1,56 @@
+import { type ZohoAnalyticsConfig, type ZohoAnalyticsContextRef, type ZohoAnalyticsFetchFactory } from './analytics.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 Analytics client instance, providing access to the authenticated {@link ZohoAnalyticsContext}.
+ */
+export type ZohoAnalytics = ZohoAnalyticsContextRef;
+/**
+ * Configuration for creating a {@link ZohoAnalyticsFactory}, combining account credentials
+ * with optional overrides for rate limiting, fetch behavior, and error logging.
+ */
+export interface ZohoAnalyticsFactoryConfig 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 the Zoho-oauthtoken authorization and
+     * ZANALYTICS-ORGID headers and a 20-second timeout.
+     */
+    readonly fetchFactory?: ZohoAnalyticsFetchFactory;
+    /**
+     * Custom error logging function invoked when Zoho API errors are encountered.
+     */
+    readonly logZohoServerErrorFunction?: LogZohoServerErrorFunction;
+}
+/**
+ * Factory function that creates a {@link ZohoAnalytics} client from a {@link ZohoAnalyticsConfig}.
+ */
+export type ZohoAnalyticsFactory = (config: ZohoAnalyticsConfig) => ZohoAnalytics;
+/**
+ * Creates a {@link ZohoAnalyticsFactory} from the given configuration.
+ *
+ * The factory pre-initializes shared resources (access token provider, rate limiter)
+ * once, then produces {@link ZohoAnalytics} client instances for each {@link ZohoAnalyticsConfig}.
+ * Each client handles OAuth token refresh on {@link ZohoInvalidTokenError}, rate limiting,
+ * and Zoho Analytics' failure envelope returned with a 200 status.
+ *
+ * Two details differ from the other Zoho services:
+ *
+ * - Analytics authorizes with the `Zoho-oauthtoken` scheme rather than `Bearer`.
+ * - The `ZANALYTICS-ORGID` header is only attached when the config carries an `orgId`, because
+ *   `GET /orgs` is the bootstrap call that discovers it and is the one endpoint that does not
+ *   require it.
+ *
+ * @param factoryConfig - Configuration providing account credentials and optional overrides.
+ * @returns A factory function that creates authenticated Zoho Analytics clients.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/api-specification.html
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function zohoAnalyticsFactory(factoryConfig: ZohoAnalyticsFactoryConfig): ZohoAnalyticsFactory;

package/src/lib/analytics/analytics.import.d.ts

@@ -0,0 +1,176 @@
+import { type WebsiteUrl } from '@dereekb/util';
+import { type ZohoAnalyticsName, type ZohoAnalyticsViewId } from './analytics';
+import { type ZohoAnalyticsColumnDataType } from './analytics.view';
+/**
+ * How an import combines incoming data with the rows already in the target table.
+ *
+ * - `append` adds the incoming rows, leaving existing rows untouched.
+ * - `truncateadd` deletes every existing row first, making the import a full replacement.
+ * - `updateadd` updates rows matching `matchingColumns` and inserts the rest.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/bulk-api/import-data/existing-table.html
+ */
+export type ZohoAnalyticsImportType = 'append' | 'truncateadd' | 'updateadd';
+/**
+ * Format of the data being imported.
+ */
+export type ZohoAnalyticsImportFileType = 'csv' | 'json';
+/**
+ * What an import does when a row cannot be imported.
+ *
+ * - `abort` fails the whole import.
+ * - `skiprow` discards the offending row and continues.
+ * - `setcolumnempty` blanks the offending value and continues.
+ */
+export type ZohoAnalyticsImportOnError = 'abort' | 'skiprow' | 'setcolumnempty';
+/**
+ * Thousand separator present in the imported data.
+ *
+ * `0` comma, `1` dot, `2` space, `3` single quote.
+ */
+export type ZohoAnalyticsThousandSeparator = 0 | 1 | 2 | 3;
+/**
+ * Decimal separator present in the imported data. `0` dot, `1` comma.
+ */
+export type ZohoAnalyticsDecimalSeparator = 0 | 1;
+/**
+ * Field delimiter of imported CSV data.
+ *
+ * `0` comma, `1` tab, `2` semicolon, `3` space.
+ */
+export type ZohoAnalyticsDelimiter = 0 | 1 | 2 | 3;
+/**
+ * Text qualifier of imported CSV data.
+ *
+ * `0` none, `1` single quote, `2` double quote.
+ */
+export type ZohoAnalyticsQuoted = 0 | 1 | 2;
+/**
+ * Explicit data type for a column being created by an import.
+ */
+export interface ZohoAnalyticsImportColumnDataType {
+    readonly columnName: ZohoAnalyticsName;
+    readonly dataType: ZohoAnalyticsColumnDataType;
+    readonly geoRole?: string;
+}
+/**
+ * Import options shared by every import variant.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/bulk-api/import-data/existing-table.html
+ */
+export interface ZohoAnalyticsImportBaseConfig {
+    readonly fileType?: ZohoAnalyticsImportFileType;
+    /**
+     * Whether Zoho should auto-identify the format of the incoming data.
+     *
+     * Required by every import endpoint, despite reading like an optimization: a CONFIG that omits it
+     * is rejected with error 8504, "The parameter CONFIG is not proper". The client therefore sends
+     * `true` when this is unset, so it only has to be given to opt out with `false`.
+     */
+    readonly autoIdentify?: boolean;
+    readonly onError?: ZohoAnalyticsImportOnError;
+    /**
+     * Restricts the import to these columns.
+     */
+    readonly selectedColumns?: ZohoAnalyticsName[];
+    /**
+     * Number of leading rows to skip.
+     */
+    readonly skipTop?: number;
+    readonly thousandSeparator?: ZohoAnalyticsThousandSeparator;
+    readonly decimalSeparator?: ZohoAnalyticsDecimalSeparator;
+    /**
+     * Date format used by date columns that are not auto-detected, e.g. `'dd-MMM-YYYY'`.
+     */
+    readonly dateFormat?: string;
+    /**
+     * Per-column date formats, keyed by column name.
+     */
+    readonly columnDateFormat?: Record<ZohoAnalyticsName, string>;
+    /**
+     * Rows beginning with this single character are skipped.
+     */
+    readonly commentChar?: string;
+    readonly delimiter?: ZohoAnalyticsDelimiter;
+    readonly quoted?: ZohoAnalyticsQuoted;
+    readonly retainColumnNames?: boolean;
+}
+/**
+ * Import options for importing into an existing table.
+ */
+export interface ZohoAnalyticsImportConfig extends ZohoAnalyticsImportBaseConfig {
+    readonly importType: ZohoAnalyticsImportType;
+    /**
+     * Columns used to match incoming rows against existing ones.
+     *
+     * Required when `importType` is `'updateadd'`.
+     */
+    readonly matchingColumns?: ZohoAnalyticsName[];
+    /**
+     * Explicit data types for columns added by this import.
+     */
+    readonly columnDataTypes?: ZohoAnalyticsImportColumnDataType[];
+}
+/**
+ * Import options for creating a new table from the imported data.
+ *
+ * There is no `importType` here: a new table has nothing to append to or replace.
+ */
+export interface ZohoAnalyticsImportNewTableConfig extends ZohoAnalyticsImportBaseConfig {
+    /**
+     * Name of the table to create.
+     */
+    readonly tableName: ZohoAnalyticsName;
+}
+/**
+ * Options accepted only by the asynchronous import job and batch import endpoints.
+ */
+export interface ZohoAnalyticsImportJobConfigOptions {
+    /**
+     * URL that Zoho posts the job's completion status to.
+     */
+    readonly callbackUrl?: WebsiteUrl;
+}
+/**
+ * Import options for an asynchronous import job into an existing table.
+ */
+export interface ZohoAnalyticsImportJobConfig extends ZohoAnalyticsImportConfig, ZohoAnalyticsImportJobConfigOptions {
+}
+/**
+ * Import options for an asynchronous import job that creates a new table.
+ */
+export interface ZohoAnalyticsImportJobNewTableConfig extends ZohoAnalyticsImportNewTableConfig, ZohoAnalyticsImportJobConfigOptions {
+}
+/**
+ * Summary of what an import actually did.
+ *
+ * Compare `successRowCount` against `totalRowCount`: an import can report success overall while
+ * silently rejecting individual rows.
+ */
+export interface ZohoAnalyticsImportSummary {
+    readonly importType?: string;
+    readonly totalColumnCount?: number;
+    readonly selectedColumnCount?: number;
+    readonly totalRowCount?: number;
+    readonly successRowCount?: number;
+    readonly warnings?: number;
+    readonly importOperation?: string;
+}
+/**
+ * Payload returned by a completed import.
+ *
+ * A response with `status: 'success'` can still describe partially rejected data — always inspect
+ * `importSummary` and `importErrors` rather than treating success as "every row landed".
+ */
+export interface ZohoAnalyticsImportResult {
+    readonly importSummary: ZohoAnalyticsImportSummary;
+    /**
+     * Resolved data type of each imported column, keyed by column name.
+     */
+    readonly columnDetails?: Record<ZohoAnalyticsName, string>;
+    /**
+     * Description of the rows or columns that failed to import. Empty when nothing was rejected.
+     */
+    readonly importErrors?: string;
+    readonly viewId?: ZohoAnalyticsViewId;
+}

package/src/lib/analytics/analytics.job.d.ts

@@ -0,0 +1,132 @@
+import { type Milliseconds } from '@dereekb/util';
+import { type ZohoAnalyticsJobId, type ZohoAnalyticsTimestampString } from './analytics';
+/**
+ * Status code of an asynchronous Zoho Analytics import or export job.
+ *
+ * Returned as a string even though the values are numeric.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/bulk-api/export-data-async/get-export.html
+ */
+export type ZohoAnalyticsJobCode = string;
+/**
+ * The job has been accepted but has not started yet. Keep polling.
+ */
+export declare const ZOHO_ANALYTICS_JOB_CODE_NOT_INITIATED: ZohoAnalyticsJobCode;
+/**
+ * The job is running. Keep polling.
+ */
+export declare const ZOHO_ANALYTICS_JOB_CODE_IN_PROGRESS: ZohoAnalyticsJobCode;
+/**
+ * The job failed.
+ */
+export declare const ZOHO_ANALYTICS_JOB_CODE_ERROR: ZohoAnalyticsJobCode;
+/**
+ * The job finished successfully. Export results can now be downloaded.
+ */
+export declare const ZOHO_ANALYTICS_JOB_CODE_COMPLETED: ZohoAnalyticsJobCode;
+/**
+ * No job exists for the given id.
+ *
+ * Declared by Zoho but not observed in practice: asking for a job that does not exist throws a 404
+ * (error 8120 for an export job, 8137 for an import job) rather than resolving with this code, so
+ * polling never terminates on it. Verified against the live API.
+ */
+export declare const ZOHO_ANALYTICS_JOB_CODE_NOT_FOUND: ZohoAnalyticsJobCode;
+/**
+ * Maximum number of concurrent import jobs, and separately export jobs, allowed per organization.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/bulk-api/import-data-async/create-import-job/existing-table.html
+ */
+export declare const ZOHO_ANALYTICS_MAX_CONCURRENT_JOBS = 5;
+/**
+ * Default interval between Zoho Analytics job status checks.
+ *
+ * Checking job status costs zero API units, so polling is inexpensive; the interval exists to stay
+ * within the request frequency limit.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/api-limits-pricing/api-units.html
+ */
+export declare const DEFAULT_ZOHO_ANALYTICS_JOB_POLL_WAIT: Milliseconds;
+/**
+ * Default maximum number of Zoho Analytics job status checks before giving up.
+ */
+export declare const DEFAULT_ZOHO_ANALYTICS_JOB_MAX_POLLS = 150;
+/**
+ * Common shape of an asynchronous Zoho Analytics job status.
+ */
+export interface ZohoAnalyticsJobStatus {
+    readonly jobId: ZohoAnalyticsJobId;
+    readonly jobCode: ZohoAnalyticsJobCode;
+    /**
+     * Epoch milliseconds at which the job's result stops being retrievable, roughly an hour after
+     * completion.
+     *
+     * Returned by import jobs as well as export jobs, despite being documented only for exports.
+     */
+    readonly expiryTime?: ZohoAnalyticsTimestampString;
+    /**
+     * Human-readable status, e.g. `'JOB COMPLETED'`.
+     */
+    readonly jobStatus: string;
+}
+/**
+ * Returns true while the job is still queued or running and should continue to be polled.
+ *
+ * @param jobCode - The job's current status code.
+ * @returns Whether the job has not yet reached a terminal state.
+ */
+export declare function isZohoAnalyticsJobPending(jobCode: ZohoAnalyticsJobCode): boolean;
+/**
+ * Returns true when the job finished successfully.
+ *
+ * @param jobCode - The job's current status code.
+ * @returns Whether the job completed.
+ */
+export declare function isZohoAnalyticsJobComplete(jobCode: ZohoAnalyticsJobCode): boolean;
+/**
+ * Returns true when the job reached a terminal failure, either erroring or not existing.
+ *
+ * In practice only {@link ZOHO_ANALYTICS_JOB_CODE_ERROR} is reachable through the job endpoints: an
+ * unknown job id throws rather than reporting {@link ZOHO_ANALYTICS_JOB_CODE_NOT_FOUND}.
+ *
+ * @param jobCode - The job's current status code.
+ * @returns Whether the job failed.
+ */
+export declare function isZohoAnalyticsJobError(jobCode: ZohoAnalyticsJobCode): boolean;
+/**
+ * Configuration for {@link pollZohoAnalyticsJob}.
+ */
+export interface PollZohoAnalyticsJobConfig<T> {
+    /**
+     * Loads the job's current status.
+     */
+    readonly loadJob: () => Promise<T>;
+    /**
+     * Reads the status code from a loaded job.
+     */
+    readonly readJobCode: (job: T) => ZohoAnalyticsJobCode;
+    /**
+     * Milliseconds to wait between status checks.
+     *
+     * Defaults to {@link DEFAULT_ZOHO_ANALYTICS_JOB_POLL_WAIT}.
+     */
+    readonly pollWait?: Milliseconds;
+    /**
+     * Maximum number of status checks before returning the last observed job.
+     *
+     * Defaults to {@link DEFAULT_ZOHO_ANALYTICS_JOB_MAX_POLLS}.
+     */
+    readonly maxPolls?: number;
+}
+/**
+ * Polls an asynchronous Zoho Analytics job until it reaches a terminal state.
+ *
+ * Resolves with the last observed job, whether it completed, errored, or the poll budget ran out.
+ * Inspect the returned job's code with {@link isZohoAnalyticsJobComplete} and
+ * {@link isZohoAnalyticsJobError} — a job still pending on return means the budget was exhausted
+ * rather than that it failed.
+ *
+ * @param config - The job loader, status reader, and polling budget.
+ * @returns The last observed job status.
+ */
+export declare function pollZohoAnalyticsJob<T>(config: PollZohoAnalyticsJobConfig<T>): Promise<T>;

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

@@ -0,0 +1,55 @@
+import { type Maybe } from '@dereekb/util';
+import { type ZohoRateLimitedFetchHandler, type ZohoRateLimitedFetchHandlerConfig } from '../zoho.limit';
+/**
+ * Overall Zoho Analytics API request limit per minute, across every API type.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/api-limits-pricing/api-frequency.html
+ */
+export declare const DEFAULT_ZOHO_ANALYTICS_API_RATE_LIMIT = 100;
+/**
+ * Per-minute request limit for Zoho Analytics bulk (import/export) operations.
+ *
+ * Pass this as `maxRateLimit` for a client dedicated to bulk work.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/api-limits-pricing/api-frequency.html
+ */
+export declare const ZOHO_ANALYTICS_BULK_API_RATE_LIMIT = 40;
+/**
+ * Per-minute request limit for Zoho Analytics metadata operations.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/api-limits-pricing/api-frequency.html
+ */
+export declare const ZOHO_ANALYTICS_METADATA_API_RATE_LIMIT = 60;
+/**
+ * Per-minute request limit for Zoho Analytics DML (row-level) operations.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/api-limits-pricing/api-frequency.html
+ */
+export declare const ZOHO_ANALYTICS_DML_API_RATE_LIMIT = 100;
+/**
+ * Reset period for the Zoho Analytics request frequency limit.
+ */
+export declare const ZOHO_ANALYTICS_API_RATE_LIMIT_RESET_PERIOD: number;
+/**
+ * Creates a {@link ZohoRateLimitedFetchHandler} configured for Zoho Analytics' documented request
+ * frequency limit.
+ *
+ * Zoho Analytics documents a fixed limit but returns no rate limit headers at all, and does not
+ * document a status code for a throttled request — throttling is reported as error code `6045`
+ * (per-minute) or `6043`/`6044` (daily unit quota) inside the response body, which this handler
+ * cannot inspect without consuming it. The limiter therefore runs in self-counting mode via
+ * `enabledWithoutRateLimitDetails`, pacing requests against {@link DEFAULT_ZOHO_ANALYTICS_API_RATE_LIMIT}
+ * rather than synchronizing with the server.
+ *
+ * The standard `X-RATELIMIT-*` reader is still supplied so that the limiter synchronizes
+ * automatically should Analytics begin returning those headers.
+ *
+ * Throttling that does slip through is surfaced to callers as a `ZohoTooManyRequestsError` by
+ * the Analytics error parser.
+ *
+ * @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`
+ *
+ * @see https://www.zoho.com/analytics/api/v2/api-limits-pricing/api-frequency.html
+ */
+export declare function zohoAnalyticsRateLimitedFetchHandler(config?: Maybe<ZohoRateLimitedFetchHandlerConfig>): ZohoRateLimitedFetchHandler;