@dereekb/zoho 13.38.0 → 13.40.0

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

@@ -0,0 +1,51 @@
+import { type ZohoAnalyticsOrgId, type ZohoAnalyticsTimestampString } from './analytics';
+/**
+ * An organization in Zoho Analytics.
+ *
+ * The org id is required by the `ZANALYTICS-ORGID` header on every other endpoint, making
+ * `GET /orgs` the bootstrap call for a newly configured client.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/metadata-api/get-org.html
+ */
+export interface ZohoAnalyticsOrg {
+    readonly orgId: ZohoAnalyticsOrgId;
+    readonly orgName: string;
+    readonly orgDesc?: string;
+    readonly createdBy?: string;
+    readonly createdByZuId?: string;
+    /**
+     * Subscription plan name, e.g. `'Premium'`. Determines the daily API unit quota.
+     */
+    readonly planName?: string;
+    readonly isDefault?: boolean;
+    /**
+     * Number of workspaces in the organization.
+     *
+     * Spelled with a lowercase `w` to match the field name the Zoho Analytics API returns.
+     */
+    readonly numberOfworkspaces?: number;
+    /**
+     * The authenticated user's role in the organization, e.g. `'Account Admin'`.
+     */
+    readonly role?: string;
+}
+/**
+ * A workspace summary as returned by the workspace listing endpoints.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/metadata-api/all-workspace.html
+ */
+export interface ZohoAnalyticsWorkspaceSummary {
+    readonly workspaceId: string;
+    readonly workspaceName: string;
+    readonly workspaceDesc?: string;
+    readonly orgId?: ZohoAnalyticsOrgId;
+    readonly createdTime?: ZohoAnalyticsTimestampString;
+    readonly createdBy?: string;
+    readonly isDefault?: boolean;
+}
+/**
+ * Full details of a single workspace.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/metadata-api/workspace-details.html
+ */
+export type ZohoAnalyticsWorkspace = ZohoAnalyticsWorkspaceSummary;

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

@@ -0,0 +1,70 @@
+import { type Maybe } from '@dereekb/util';
+import { type FetchJsonBody, type FetchJsonInput } from '@dereekb/util/fetch';
+/**
+ * Name of the single parameter that carries every Zoho Analytics request option.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/api-specification.html
+ */
+export declare const ZOHO_ANALYTICS_CONFIG_PARAM = "CONFIG";
+/**
+ * Content type used when a Zoho Analytics `CONFIG` is sent in the request body.
+ */
+export declare const ZOHO_ANALYTICS_FORM_CONTENT_TYPE = "application/x-www-form-urlencoded";
+/**
+ * The options object for a Zoho Analytics request.
+ *
+ * Zoho Analytics does not accept a normal JSON request body. Instead every option is collected
+ * into a single `CONFIG` parameter whose value is the JSON of this object, URL-encoded.
+ *
+ * Where that parameter is placed depends on the API family:
+ *
+ * - the query string for every `GET`, for every Bulk API write (import/export), and for the
+ *   Modeling API deletes; use {@link zohoAnalyticsConfigQuerySuffix}
+ * - an `application/x-www-form-urlencoded` body for Data API row CRUD; use
+ *   {@link zohoAnalyticsFormApiFetchJsonInput}
+ *
+ * The row-CRUD form body is the odd one out, and it is not the general rule for writes: the
+ * Modeling delete endpoints take their `CONFIG` in the query string despite also being writes.
+ * Verified against the live API.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/api-specification.html
+ */
+export type ZohoAnalyticsRequestConfig = object;
+/**
+ * Encodes a {@link ZohoAnalyticsRequestConfig} as `CONFIG=<url-encoded json>`.
+ *
+ * Keys with an `undefined` value are dropped by JSON serialization, so optional request options
+ * can be passed through without filtering them first.
+ *
+ * @param config - The request options to encode, if any.
+ * @returns The encoded parameter, or an empty string when no config is provided.
+ */
+export declare function zohoAnalyticsConfigParamString(config?: Maybe<ZohoAnalyticsRequestConfig>): string;
+/**
+ * Encodes a {@link ZohoAnalyticsRequestConfig} as a query string suffix ready to append to a URL.
+ *
+ * @param config - The request options to encode, if any.
+ * @returns `'?CONFIG=...'`, or an empty string when no config is provided.
+ */
+export declare function zohoAnalyticsConfigQuerySuffix(config?: Maybe<ZohoAnalyticsRequestConfig>): string;
+/**
+ * Constructs the standard FetchJsonInput used by Zoho Analytics calls that carry their `CONFIG`
+ * in the query string, 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 Analytics API call.
+ */
+export declare function zohoAnalyticsApiFetchJsonInput(method: string, body?: Maybe<FetchJsonBody>): FetchJsonInput;
+/**
+ * Constructs the FetchJsonInput for a Zoho Analytics call that carries its `CONFIG` in an
+ * `application/x-www-form-urlencoded` body, as the Data API row operations require.
+ *
+ * The content type is set explicitly to override the JSON default applied by the Analytics fetch
+ * factory.
+ *
+ * @param method - HTTP method to use for the request.
+ * @param config - Request options to encode into the body.
+ * @returns Configured fetch input carrying the encoded config as its body.
+ */
+export declare function zohoAnalyticsFormApiFetchJsonInput(method: string, config: ZohoAnalyticsRequestConfig): FetchJsonInput;

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

@@ -0,0 +1,99 @@
+import { type SuggestedString } from '@dereekb/util';
+import { type ZohoAnalyticsColumnId, type ZohoAnalyticsFolderId, type ZohoAnalyticsName, type ZohoAnalyticsOrgId, type ZohoAnalyticsTimestampString, type ZohoAnalyticsViewId, type ZohoAnalyticsWorkspaceId } from './analytics';
+/**
+ * Type of a view in Zoho Analytics.
+ *
+ * Zoho returns this in mixed case — `'Table'`, not `'TABLE'` — from both `GET /workspaces/{id}/views`
+ * and `GET /views/{id}`, verified against the live API. Only `'Table'` has been confirmed against a
+ * real account; the other members are the documented view kinds and their casing is inferred, so
+ * compare case-insensitively rather than against these literals.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/metadata-api/get-views.html
+ */
+export type ZohoAnalyticsViewType = SuggestedString<'Table' | 'QueryTable' | 'Report' | 'Dashboard'>;
+/**
+ * A view in Zoho Analytics: a table, query table, report, or dashboard.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/metadata-api/get-views.html
+ */
+export interface ZohoAnalyticsView {
+    readonly viewId: ZohoAnalyticsViewId;
+    readonly viewName: ZohoAnalyticsName;
+    readonly viewDesc?: string;
+    readonly viewType?: ZohoAnalyticsViewType;
+    readonly folderId?: ZohoAnalyticsFolderId;
+    readonly folderName?: string;
+    readonly createdBy?: string;
+    readonly createdTime?: ZohoAnalyticsTimestampString;
+    /**
+     * View this one was derived from, for a query table or report.
+     */
+    readonly parentViewId?: ZohoAnalyticsViewId;
+    readonly lastModifiedTime?: ZohoAnalyticsTimestampString;
+    readonly lastModifiedBy?: string;
+    readonly isFavorite?: boolean;
+    /**
+     * Present when the view is shared with the authenticated user rather than owned by them.
+     */
+    readonly sharedBy?: string;
+}
+/**
+ * Full details of a single view, which include the owning workspace and organization.
+ *
+ * Carries a different field set than the listing rather than a superset: it adds the owning
+ * workspace/org and the design-modification fields, and drops the folder and favorite fields.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/metadata-api/view-details.html
+ */
+export interface ZohoAnalyticsViewDetails {
+    readonly viewId: ZohoAnalyticsViewId;
+    readonly viewName: ZohoAnalyticsName;
+    readonly viewDesc?: string;
+    readonly viewType?: ZohoAnalyticsViewType;
+    readonly workspaceId?: ZohoAnalyticsWorkspaceId;
+    readonly orgId?: ZohoAnalyticsOrgId;
+    readonly createdTime?: ZohoAnalyticsTimestampString;
+    readonly createdBy?: string;
+    readonly createdByName?: string;
+    readonly createdByZuId?: string;
+    /**
+     * When the view's design — its columns and formulas, not its rows — last changed.
+     */
+    readonly lastDesignModifiedTime?: ZohoAnalyticsTimestampString;
+    readonly lastDesignModifiedBy?: string;
+    readonly lastDesignModifiedByName?: string;
+    readonly lastDesignModifiedByZuId?: string;
+}
+/**
+ * Column data type in a Zoho Analytics table.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/bulk-api/import-data/existing-table.html
+ */
+export type ZohoAnalyticsColumnDataType = SuggestedString<'PLAIN' | 'MULTI_LINE' | 'EMAIL' | 'NUMBER' | 'POSITIVE_NUMBER' | 'DECIMAL_NUMBER' | 'CURRENCY' | 'PERCENT' | 'DATE' | 'BOOLEAN' | 'URL' | 'AUTO_NUMBER' | 'GEO'>;
+/**
+ * Metadata describing a single column of a Zoho Analytics table.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/metadata-api/get-table-metadata.html
+ */
+export interface ZohoAnalyticsColumn {
+    readonly columnId: ZohoAnalyticsColumnId;
+    readonly columnName: ZohoAnalyticsName;
+    readonly dataType?: ZohoAnalyticsColumnDataType;
+    readonly dataTypeId?: number;
+    readonly dataTypeName?: string;
+    readonly columnIndex?: number;
+    readonly columnDesc?: string;
+    readonly columnMaxSize?: number;
+    readonly isNullable?: boolean;
+    readonly defaultValue?: string;
+    readonly pkTableName?: string;
+    readonly pkColumnName?: string;
+    readonly formulaDisplayName?: string;
+    readonly isHidden?: boolean;
+    readonly sortedOrder?: number;
+    readonly sortedIndex?: number;
+    readonly currencyFormat?: string;
+    readonly thousandSeparator?: string;
+    readonly decimalSeparator?: string;
+    readonly decimalPlaces?: number;
+}

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

@@ -0,0 +1,20 @@
+export * from './analytics';
+export * from './analytics.config';
+export * from './analytics.param';
+export * from './analytics.error.api';
+export * from './analytics.limit';
+export * from './analytics.job';
+export * from './analytics.org';
+export * from './analytics.view';
+export * from './analytics.import';
+export * from './analytics.data';
+export * from './analytics.diff';
+export * from './analytics.export';
+export * from './analytics.factory';
+export * from './analytics.api.orgs';
+export * from './analytics.api.workspaces';
+export * from './analytics.api.views';
+export * from './analytics.api.import';
+export * from './analytics.api.export';
+export * from './analytics.api.rows';
+export * from './analytics.api.modeling';

package/src/lib/index.d.ts

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

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

@@ -97,6 +97,18 @@ export interface MakeZohoRateLimitedFetchHandlerConfig extends ZohoRateLimitedFe
      * Parses service-specific rate limit headers into the common {@link ZohoRateLimitResponseDetails} shape.
      */
     readonly readRateLimitDetails: ZohoReadRateLimitDetailsFunction;
+    /**
+     * Whether the rate limiter stays enabled when a response carries no rate limit details.
+     *
+     * Defaults to false, which suits services that advertise their limits via response headers
+     * (CRM, Recruit, Sign, Desk): a header-less response there means the limiter has nothing to
+     * synchronize against, so throttling is suspended.
+     *
+     * Set to true for services that document a fixed limit but return no rate limit headers at all
+     * (Zoho Analytics). The limiter then self-counts each request against `maxRateLimit` and resets
+     * on its own `resetPeriod` schedule.
+     */
+    readonly enabledWithoutRateLimitDetails?: boolean;
 }
 /**
  * Creates a {@link ZohoRateLimitedFetchHandler} using a configurable header reader function.
@@ -108,7 +120,8 @@ export interface MakeZohoRateLimitedFetchHandlerConfig extends ZohoRateLimitedFe
  * - 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)
+ * - The limiter is disabled when responses lack rate limit headers (e.g., error responses), unless
+ *   `enabledWithoutRateLimitDetails` is set, in which case it self-counts against `maxRateLimit`
  *
  * @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`

package/index.cjs.default.js

@@ -1 +0,0 @@
-exports._default = require('./index.cjs.js').default;