@dereekb/zoho 13.39.0 → 13.40.0

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

@@ -0,0 +1,104 @@
+import { type ZohoAnalyticsResponse, type ZohoAnalyticsViewId, type ZohoAnalyticsWorkspaceId } from './analytics';
+import { type ZohoAnalyticsContext } from './analytics.config';
+import { type ZohoAnalyticsColumn, type ZohoAnalyticsView, type ZohoAnalyticsViewDetails } from './analytics.view';
+/**
+ * Input for listing the views of a workspace.
+ */
+export interface ZohoAnalyticsGetViewsInput {
+    readonly workspaceId: ZohoAnalyticsWorkspaceId;
+}
+/**
+ * Payload of a {@link ZohoAnalyticsGetViewsResponse}.
+ */
+export interface ZohoAnalyticsGetViewsResponseData {
+    readonly views: ZohoAnalyticsView[];
+}
+/**
+ * Response for `GET /workspaces/{workspaceId}/views`.
+ */
+export type ZohoAnalyticsGetViewsResponse = ZohoAnalyticsResponse<ZohoAnalyticsGetViewsResponseData>;
+/**
+ * Lists the views of a workspace.
+ */
+export type ZohoAnalyticsGetViewsFunction = (input: ZohoAnalyticsGetViewsInput) => Promise<ZohoAnalyticsGetViewsResponse>;
+/**
+ * Creates a {@link ZohoAnalyticsGetViewsFunction} bound to the given context.
+ *
+ * This endpoint is not paginated — Zoho's OpenAPI specification declares no parameters for it, so
+ * the full set of views is always returned.
+ *
+ * @param context - Authenticated Zoho Analytics context providing fetch and rate limiting.
+ * @returns Function that lists every view in a workspace.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/metadata-api/get-views.html
+ */
+export declare function zohoAnalyticsGetViews(context: ZohoAnalyticsContext): ZohoAnalyticsGetViewsFunction;
+/**
+ * Input for retrieving a single view's details.
+ */
+export interface ZohoAnalyticsGetViewDetailsInput {
+    readonly viewId: ZohoAnalyticsViewId;
+}
+/**
+ * Payload of a {@link ZohoAnalyticsGetViewDetailsResponse}.
+ *
+ * The key is plural but holds a single view object.
+ */
+export interface ZohoAnalyticsGetViewDetailsResponseData {
+    readonly views: ZohoAnalyticsViewDetails;
+}
+/**
+ * Response for `GET /views/{viewId}`.
+ */
+export type ZohoAnalyticsGetViewDetailsResponse = ZohoAnalyticsResponse<ZohoAnalyticsGetViewDetailsResponseData>;
+/**
+ * Retrieves the details of a single view.
+ */
+export type ZohoAnalyticsGetViewDetailsFunction = (input: ZohoAnalyticsGetViewDetailsInput) => Promise<ZohoAnalyticsGetViewDetailsResponse>;
+/**
+ * Creates a {@link ZohoAnalyticsGetViewDetailsFunction} bound to the given context.
+ *
+ * Unlike the view listing, this endpoint is not workspace-scoped: view ids are globally unique, so
+ * the path is `/views/{viewId}` rather than `/workspaces/{workspaceId}/views/{viewId}`. It returns a
+ * different field set than the listing rather than a superset — see {@link ZohoAnalyticsViewDetails}.
+ * Both endpoints report `viewType` in the same mixed case (`'Table'`), verified live.
+ *
+ * @param context - Authenticated Zoho Analytics context providing fetch and rate limiting.
+ * @returns Function that retrieves a view by id.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/metadata-api/view-details.html
+ */
+export declare function zohoAnalyticsGetViewDetails(context: ZohoAnalyticsContext): ZohoAnalyticsGetViewDetailsFunction;
+/**
+ * Input for retrieving the column metadata of a table.
+ */
+export interface ZohoAnalyticsGetTableMetadataInput {
+    readonly workspaceId: ZohoAnalyticsWorkspaceId;
+    readonly viewId: ZohoAnalyticsViewId;
+}
+/**
+ * Payload of a {@link ZohoAnalyticsGetTableMetadataResponse}.
+ */
+export interface ZohoAnalyticsGetTableMetadataResponseData {
+    readonly columns: ZohoAnalyticsColumn[];
+}
+/**
+ * Response for `GET /workspaces/{workspaceId}/views/{viewId}/metadata`.
+ */
+export type ZohoAnalyticsGetTableMetadataResponse = ZohoAnalyticsResponse<ZohoAnalyticsGetTableMetadataResponseData>;
+/**
+ * Retrieves the column metadata of a table.
+ */
+export type ZohoAnalyticsGetTableMetadataFunction = (input: ZohoAnalyticsGetTableMetadataInput) => Promise<ZohoAnalyticsGetTableMetadataResponse>;
+/**
+ * Creates a {@link ZohoAnalyticsGetTableMetadataFunction} bound to the given context.
+ *
+ * Use this before an import to confirm the target table's column names, since an import matches
+ * incoming data to columns by name.
+ *
+ * @param context - Authenticated Zoho Analytics context providing fetch and rate limiting.
+ * @returns Function that retrieves a table's column metadata.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/metadata-api/get-table-metadata.html
+ */
+export declare function zohoAnalyticsGetTableMetadata(context: ZohoAnalyticsContext): ZohoAnalyticsGetTableMetadataFunction;

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

@@ -0,0 +1,96 @@
+import { type ZohoAnalyticsResponse, type ZohoAnalyticsWorkspaceId } from './analytics';
+import { type ZohoAnalyticsContext } from './analytics.config';
+import { type ZohoAnalyticsWorkspace, type ZohoAnalyticsWorkspaceSummary } from './analytics.org';
+/**
+ * Payload of a {@link ZohoAnalyticsGetAllWorkspacesResponse}.
+ *
+ * `GET /workspaces` splits its result into owned and shared workspaces, unlike the
+ * `/workspaces/owned` and `/workspaces/shared` endpoints which each return a single
+ * `workspaces` array.
+ */
+export interface ZohoAnalyticsGetAllWorkspacesResponseData {
+    readonly ownedWorkspaces: ZohoAnalyticsWorkspaceSummary[];
+    readonly sharedWorkspaces: ZohoAnalyticsWorkspaceSummary[];
+}
+/**
+ * Response for `GET /workspaces`.
+ */
+export type ZohoAnalyticsGetAllWorkspacesResponse = ZohoAnalyticsResponse<ZohoAnalyticsGetAllWorkspacesResponseData>;
+/**
+ * Lists every workspace the authenticated user can access, grouped by ownership.
+ */
+export type ZohoAnalyticsGetAllWorkspacesFunction = () => Promise<ZohoAnalyticsGetAllWorkspacesResponse>;
+/**
+ * Creates a {@link ZohoAnalyticsGetAllWorkspacesFunction} bound to the given context.
+ *
+ * @param context - Authenticated Zoho Analytics context providing fetch and rate limiting.
+ * @returns Function that lists all accessible workspaces, grouped into owned and shared.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/metadata-api/all-workspace.html
+ */
+export declare function zohoAnalyticsGetAllWorkspaces(context: ZohoAnalyticsContext): ZohoAnalyticsGetAllWorkspacesFunction;
+/**
+ * Payload of a workspace listing that returns a single flat array.
+ */
+export interface ZohoAnalyticsGetWorkspacesResponseData {
+    readonly workspaces: ZohoAnalyticsWorkspaceSummary[];
+}
+/**
+ * Response for `GET /workspaces/owned` and `GET /workspaces/shared`.
+ */
+export type ZohoAnalyticsGetWorkspacesResponse = ZohoAnalyticsResponse<ZohoAnalyticsGetWorkspacesResponseData>;
+/**
+ * Lists a single category of workspaces.
+ */
+export type ZohoAnalyticsGetWorkspacesFunction = () => Promise<ZohoAnalyticsGetWorkspacesResponse>;
+/**
+ * Creates a {@link ZohoAnalyticsGetWorkspacesFunction} for the workspaces owned by the
+ * authenticated user.
+ *
+ * @param context - Authenticated Zoho Analytics context providing fetch and rate limiting.
+ * @returns Function that lists the owned workspaces.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/metadata-api/owned-workspace.html
+ */
+export declare function zohoAnalyticsGetOwnedWorkspaces(context: ZohoAnalyticsContext): ZohoAnalyticsGetWorkspacesFunction;
+/**
+ * Creates a {@link ZohoAnalyticsGetWorkspacesFunction} for the workspaces shared with the
+ * authenticated user.
+ *
+ * @param context - Authenticated Zoho Analytics context providing fetch and rate limiting.
+ * @returns Function that lists the shared workspaces.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/metadata-api/shared-workspace.html
+ */
+export declare function zohoAnalyticsGetSharedWorkspaces(context: ZohoAnalyticsContext): ZohoAnalyticsGetWorkspacesFunction;
+/**
+ * Input for retrieving a single workspace's details.
+ */
+export interface ZohoAnalyticsGetWorkspaceDetailsInput {
+    readonly workspaceId: ZohoAnalyticsWorkspaceId;
+}
+/**
+ * Payload of a {@link ZohoAnalyticsGetWorkspaceDetailsResponse}.
+ *
+ * The key is plural but holds a single workspace object.
+ */
+export interface ZohoAnalyticsGetWorkspaceDetailsResponseData {
+    readonly workspaces: ZohoAnalyticsWorkspace;
+}
+/**
+ * Response for `GET /workspaces/{workspaceId}`.
+ */
+export type ZohoAnalyticsGetWorkspaceDetailsResponse = ZohoAnalyticsResponse<ZohoAnalyticsGetWorkspaceDetailsResponseData>;
+/**
+ * Retrieves the details of a single workspace.
+ */
+export type ZohoAnalyticsGetWorkspaceDetailsFunction = (input: ZohoAnalyticsGetWorkspaceDetailsInput) => Promise<ZohoAnalyticsGetWorkspaceDetailsResponse>;
+/**
+ * Creates a {@link ZohoAnalyticsGetWorkspaceDetailsFunction} bound to the given context.
+ *
+ * @param context - Authenticated Zoho Analytics context providing fetch and rate limiting.
+ * @returns Function that retrieves a workspace by id.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/metadata-api/workspace-details.html
+ */
+export declare function zohoAnalyticsGetWorkspaceDetails(context: ZohoAnalyticsContext): ZohoAnalyticsGetWorkspaceDetailsFunction;

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

@@ -0,0 +1,92 @@
+import { type FactoryWithRequiredInput, type Maybe } 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 ZohoAnalyticsOrgId } from './analytics';
+/**
+ * Service identifier used for Zoho Analytics API access token resolution and service routing.
+ */
+export declare const ZOHO_ANALYTICS_SERVICE_NAME: ZohoApiServiceName | ZohoServiceAccessTokenKey;
+/**
+ * Header that carries the {@link ZohoAnalyticsOrgId} on Zoho Analytics API requests.
+ *
+ * Required by every endpoint except `GET /orgs`.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/api-specification.html
+ */
+export declare const ZOHO_ANALYTICS_ORG_ID_HEADER = "ZANALYTICS-ORGID";
+/**
+ * Full base URL for the Zoho Analytics API.
+ */
+export type ZohoAnalyticsApiUrl = ZohoApiUrl;
+/**
+ * Well-known environment key for selecting a Zoho Analytics API endpoint.
+ *
+ * Zoho Analytics has no documented sandbox environment, so only 'production' is a known key.
+ * Custom URLs — including the regional variants below — can be passed directly.
+ *
+ * Zoho Analytics is served from eight data centers, each with its own host:
+ * `analyticsapi.zoho.com` (US), `.eu`, `.in`, `.com.au`, `.com.cn`, `.jp`, `.sa`, and
+ * `analyticsapi.zohocloud.ca` (CA). Pass the full URL for any non-US data center.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/api-specification.html
+ */
+export type ZohoAnalyticsApiUrlKey = ZohoApiUrlKey;
+/**
+ * Accepts either a well-known environment key or a custom full URL, allowing callers to target
+ * production or an arbitrary Analytics endpoint (e.g., regional variants).
+ */
+export type ZohoAnalyticsConfigApiUrlInput = ZohoAnalyticsApiUrlKey | ZohoAnalyticsApiUrl;
+/**
+ * Resolves an Analytics API URL input to its full base URL. The 'production' key maps to the
+ * primary US Zoho Analytics endpoint; custom URLs pass through unchanged.
+ *
+ * @param input - A well-known environment key or a custom Analytics API URL.
+ * @returns The resolved full Zoho Analytics API base URL.
+ */
+export declare function zohoAnalyticsConfigApiUrl(input: ZohoAnalyticsConfigApiUrlInput): ZohoApiUrl;
+/**
+ * Configuration for a Zoho Analytics service instance, including the target API URL and organization ID.
+ *
+ * Unlike Zoho Desk — where the org id is required — the Analytics org id is optional, because
+ * `GET /orgs` is the bootstrap call that discovers it and is the one endpoint that does not
+ * require the {@link ZOHO_ANALYTICS_ORG_ID_HEADER}.
+ */
+export interface ZohoAnalyticsConfig extends ZohoConfig {
+    /**
+     * Organization ID sent as the `ZANALYTICS-ORGID` header.
+     *
+     * Optional so that a client can be created before the org id is known; every endpoint other
+     * than `GET /orgs` will fail without it.
+     */
+    readonly orgId?: Maybe<ZohoAnalyticsOrgId>;
+}
+/**
+ * Input provided to an Analytics fetch factory to construct an authenticated fetch instance for a specific API base URL.
+ */
+export interface ZohoAnalyticsFetchFactoryParams {
+    readonly apiUrl: ZohoAnalyticsApiUrl;
+    readonly orgId?: Maybe<ZohoAnalyticsOrgId>;
+}
+/**
+ * Factory that produces a pre-configured fetch instance bound to a specific Zoho Analytics API URL and organization.
+ */
+export type ZohoAnalyticsFetchFactory = FactoryWithRequiredInput<ConfiguredFetch, ZohoAnalyticsFetchFactoryParams>;
+/**
+ * Core context for making authenticated Zoho Analytics API calls. Bundles the configured fetch,
+ * JSON parsing, access token management, rate limiting, and service configuration needed
+ * by all Analytics operations.
+ */
+export interface ZohoAnalyticsContext extends ZohoRateLimiterRef {
+    readonly fetch: ConfiguredFetch;
+    readonly fetchJson: FetchJsonFunction;
+    readonly accessTokenStringFactory: ZohoAccessTokenStringFactory;
+    readonly config: ZohoAnalyticsConfig;
+}
+/**
+ * Reference wrapper providing access to a {@link ZohoAnalyticsContext}. Used for dependency injection across Analytics service consumers.
+ */
+export interface ZohoAnalyticsContextRef {
+    readonly analyticsContext: ZohoAnalyticsContext;
+}

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

@@ -0,0 +1,86 @@
+/**
+ * Identifier of a Zoho Analytics organization.
+ *
+ * Sent as the `ZANALYTICS-ORGID` header on every request except `GET /orgs`, which is
+ * the bootstrap call used to discover it.
+ */
+export type ZohoAnalyticsOrgId = string;
+/**
+ * Generic identifier in Zoho Analytics.
+ */
+export type ZohoAnalyticsId = string;
+/**
+ * Identifier of a workspace in Zoho Analytics.
+ */
+export type ZohoAnalyticsWorkspaceId = string;
+/**
+ * Identifier of a view in Zoho Analytics.
+ *
+ * A view is any of a table, query table, dashboard, or report. View ids are globally
+ * unique, which is why `GET /views/{viewId}` is not workspace-scoped.
+ */
+export type ZohoAnalyticsViewId = string;
+/**
+ * Identifier of a column within a Zoho Analytics view.
+ */
+export type ZohoAnalyticsColumnId = string;
+/**
+ * Identifier of a folder in a Zoho Analytics workspace.
+ */
+export type ZohoAnalyticsFolderId = string;
+/**
+ * Identifier of an asynchronous import or export job in Zoho Analytics.
+ */
+export type ZohoAnalyticsJobId = string;
+/**
+ * Key that chains together the requests of a batch import.
+ *
+ * The first request of a batch sends the literal `'start'`, and the response returns the
+ * generated key that every subsequent request in the batch must echo back.
+ */
+export type ZohoAnalyticsBatchKey = string;
+/**
+ * Sentinel {@link ZohoAnalyticsBatchKey} that begins a new batch import.
+ */
+export declare const ZOHO_ANALYTICS_BATCH_KEY_START: ZohoAnalyticsBatchKey;
+/**
+ * Name of a table or column in Zoho Analytics.
+ */
+export type ZohoAnalyticsName = string;
+/**
+ * A row of data in a Zoho Analytics table, keyed by column name.
+ */
+export type ZohoAnalyticsRow = Record<ZohoAnalyticsName, unknown>;
+/**
+ * A raw filter expression evaluated by Zoho Analytics against a view.
+ *
+ * The syntax is a SQL-like boolean expression over quoted table and column names, for
+ * example `"Sales"."Region"='West'`. There is no structured alternative, so callers build
+ * and escape this string themselves.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/bulk-api/export-data.html
+ */
+export type ZohoAnalyticsCriteria = string;
+/**
+ * Standard envelope wrapping every Zoho Analytics API response.
+ *
+ * Successful responses carry `status: 'success'`; failures use the same envelope with
+ * `status: 'failure'` and are converted into thrown errors by the Analytics error parser.
+ *
+ * @see https://www.zoho.com/analytics/api/v2/api-specification.html
+ */
+export interface ZohoAnalyticsResponse<T> {
+    /**
+     * `'success'` on a successful call.
+     */
+    readonly status: string;
+    /**
+     * Human-readable description of the operation performed, e.g. `'Get all workspaces'`.
+     */
+    readonly summary: string;
+    readonly data: T;
+}
+/**
+ * Epoch milliseconds returned by Zoho Analytics as a string, e.g. `'1548914379156'`.
+ */
+export type ZohoAnalyticsTimestampString = string;

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

@@ -0,0 +1,74 @@
+import { type Maybe } from '@dereekb/util';
+import { type ZohoAnalyticsName, type ZohoAnalyticsRow } from './analytics';
+import { type ZohoAnalyticsImportFileType } from './analytics.import';
+/**
+ * Rows of import data alongside the column names the data declares.
+ *
+ * The column names are tracked separately from the rows because the two can disagree: a CSV header
+ * can declare a column that no row populates, and JSON rows are free to omit keys. An import is
+ * matched against the declared names, so a diff has to see them even when no row carries a value.
+ */
+export interface ZohoAnalyticsRowData {
+    /**
+     * Column names the data declares, in the order they appear.
+     */
+    readonly columnNames: ZohoAnalyticsName[];
+    /**
+     * The parsed rows.
+     */
+    readonly rows: ZohoAnalyticsRow[];
+}
+/**
+ * Field delimiter of the CSV being read. Defaults to a comma.
+ */
+export type ZohoAnalyticsCsvDelimiter = string;
+/**
+ * Reads CSV text into {@link ZohoAnalyticsRowData}, taking the first row as the header.
+ *
+ * Duplicate header names collapse into one column, matching what an import does: the later value
+ * wins. Trailing cells beyond the header's width are dropped rather than given a synthetic name,
+ * since an import has no column to put them in either.
+ *
+ * @param content - The CSV text to read.
+ * @param delimiter - Field delimiter of the CSV. Defaults to a comma.
+ * @returns The declared column names and parsed rows. Both are empty for blank content.
+ */
+export declare function zohoAnalyticsRowDataFromCsv(content: string, delimiter?: Maybe<ZohoAnalyticsCsvDelimiter>): ZohoAnalyticsRowData;
+/**
+ * Reads JSON import text into {@link ZohoAnalyticsRowData}.
+ *
+ * Zoho Analytics expects a JSON import to be an array of row objects, so that is what this accepts;
+ * a lone object is treated as a single row for convenience.
+ *
+ * The declared column names are the union of the rows' keys in first-seen order, since JSON rows are
+ * free to omit keys and no separate header declares them.
+ *
+ * @param content - The JSON text to read.
+ * @returns The declared column names and parsed rows.
+ * @throws {Error} When the text is not valid JSON, or is neither an array of objects nor an object.
+ */
+export declare function zohoAnalyticsRowDataFromJson(content: string): ZohoAnalyticsRowData;
+/**
+ * Input for reading the contents of an import file into rows.
+ */
+export interface ZohoAnalyticsRowDataFromFileContentInput {
+    /**
+     * The file's text.
+     */
+    readonly content: string;
+    /**
+     * Format of the text.
+     */
+    readonly fileType: ZohoAnalyticsImportFileType;
+    /**
+     * Field delimiter, for a CSV. Defaults to a comma.
+     */
+    readonly delimiter?: Maybe<ZohoAnalyticsCsvDelimiter>;
+}
+/**
+ * Reads the contents of an import file into {@link ZohoAnalyticsRowData}, dispatching on its format.
+ *
+ * @param input - The file's text and format.
+ * @returns The declared column names and parsed rows.
+ */
+export declare function zohoAnalyticsRowDataFromFileContent(input: ZohoAnalyticsRowDataFromFileContentInput): ZohoAnalyticsRowData;

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

@@ -0,0 +1,178 @@
+import { type Maybe } from '@dereekb/util';
+import { type ZohoAnalyticsName } from './analytics';
+import { type ZohoAnalyticsColumn, type ZohoAnalyticsColumnDataType } from './analytics.view';
+import { type ZohoAnalyticsRowData } from './analytics.data';
+/**
+ * Default number of offending values kept per conflict, so a column that is wrong in every row
+ * reports a usable example rather than a copy of the file.
+ */
+export declare const DEFAULT_ZOHO_ANALYTICS_SCHEMA_DIFF_MAX_SAMPLES = 3;
+/**
+ * Why an incoming value does not fit the column it was matched to.
+ *
+ * - `notANumber` the value is not numeric at all.
+ * - `notAnInteger` the value is numeric but has a fractional part a whole-number column truncates.
+ * - `negative` the value is negative in a column that only accepts positives.
+ * - `notADate` the value is neither parseable as a date nor shaped like one.
+ * - `notABoolean` the value is not one of the recognized true/false spellings.
+ * - `notAnEmail` the value is not shaped like an email address.
+ * - `notAUrl` the value is not shaped like a URL.
+ * - `tooLong` the value is longer than the column's `columnMaxSize`.
+ * - `emptyInNonNullable` the value is blank in a column that is not nullable and has no default.
+ */
+export type ZohoAnalyticsSchemaDiffConflictReason = 'notANumber' | 'notAnInteger' | 'negative' | 'notADate' | 'notABoolean' | 'notAnEmail' | 'notAUrl' | 'tooLong' | 'emptyInNonNullable';
+/**
+ * One offending value, kept as an example of a conflict.
+ */
+export interface ZohoAnalyticsSchemaDiffConflictSample {
+    /**
+     * 1-based position of the row within the data.
+     *
+     * A CSV header is not counted, so row 1 is the first row of values — one line lower in the file.
+     */
+    readonly row: number;
+    /**
+     * The offending value, as text.
+     */
+    readonly value: string;
+}
+/**
+ * A matched column carrying values that do not fit its declared data type.
+ *
+ * Reported once per column and reason, so a column that is wrong in two different ways appears
+ * twice rather than merging the counts.
+ */
+export interface ZohoAnalyticsSchemaDiffConflict {
+    readonly columnName: ZohoAnalyticsName;
+    readonly dataType: ZohoAnalyticsColumnDataType;
+    readonly reason: ZohoAnalyticsSchemaDiffConflictReason;
+    /**
+     * How many rows hit this conflict, which can exceed the number of samples kept.
+     */
+    readonly conflictCount: number;
+    readonly samples: ZohoAnalyticsSchemaDiffConflictSample[];
+}
+/**
+ * A column the data declares that the target table does not have.
+ *
+ * An import matches data to columns by name, so nothing is written for these — the values are
+ * silently discarded rather than reported as an error.
+ */
+export interface ZohoAnalyticsSchemaDiffDroppedColumn {
+    readonly columnName: ZohoAnalyticsName;
+    /**
+     * How many rows carry a non-blank value for it, i.e. how much data the import would discard.
+     */
+    readonly valueCount: number;
+}
+/**
+ * A column the target table has that the data does not declare.
+ *
+ * An `append` or `updateadd` import leaves these at their default; a `truncateadd` import blanks the
+ * column across the whole table, since it deletes every existing row first.
+ */
+export interface ZohoAnalyticsSchemaDiffEmptyColumn {
+    readonly columnName: ZohoAnalyticsName;
+    readonly dataType?: ZohoAnalyticsColumnDataType;
+    readonly isNullable?: boolean;
+    /**
+     * Whether omitting the column is expected to fail rather than just leave a gap: it is explicitly
+     * not nullable and carries no default value.
+     */
+    readonly required: boolean;
+}
+/**
+ * A column whose name matches a table column except for case or surrounding whitespace.
+ *
+ * Reported on its own rather than as a dropped column because whether Zoho matches these has not
+ * been verified against the live API: if it does not, the data is discarded, and if it does, the
+ * import succeeds. Either way the mismatch is worth fixing before finding out.
+ */
+export interface ZohoAnalyticsSchemaDiffCaseMismatch {
+    readonly dataColumnName: ZohoAnalyticsName;
+    readonly tableColumnName: ZohoAnalyticsName;
+}
+/**
+ * The difference between a set of rows about to be imported and the table receiving them.
+ *
+ * Purely descriptive: every category is reported and none is weighted against another. Use
+ * {@link isZohoAnalyticsSchemaDiffClean} to reduce it to a pass/fail verdict.
+ */
+export interface ZohoAnalyticsSchemaDiff {
+    /**
+     * Names matched exactly between the data and the table.
+     */
+    readonly matchedColumns: ZohoAnalyticsName[];
+    readonly droppedColumns: ZohoAnalyticsSchemaDiffDroppedColumn[];
+    readonly emptyColumns: ZohoAnalyticsSchemaDiffEmptyColumn[];
+    readonly caseMismatchedColumns: ZohoAnalyticsSchemaDiffCaseMismatch[];
+    readonly conflicts: ZohoAnalyticsSchemaDiffConflict[];
+    /**
+     * How many rows were compared.
+     */
+    readonly rowCount: number;
+}
+/**
+ * Input for comparing rows against a table's columns.
+ */
+export interface ZohoAnalyticsSchemaDiffInput extends ZohoAnalyticsRowData {
+    /**
+     * The target table's column metadata, as returned by `getTableMetadata()`.
+     */
+    readonly columns: ZohoAnalyticsColumn[];
+    /**
+     * How many offending values to keep per conflict. Defaults to
+     * {@link DEFAULT_ZOHO_ANALYTICS_SCHEMA_DIFF_MAX_SAMPLES}.
+     */
+    readonly maxSamples?: Maybe<number>;
+}
+/**
+ * Compares rows about to be imported against the columns of the table receiving them.
+ *
+ * Answers the question an import cannot: what of this data has nowhere to land, what the table
+ * expects that the data does not carry, and which values will not survive their column's type. An
+ * import reports none of that up front — a name that matches no column is discarded silently, since
+ * Zoho matches data to columns by name.
+ *
+ * Comparison is by exact name, with case-and-whitespace-only near misses split out into
+ * {@link ZohoAnalyticsSchemaDiff.caseMismatchedColumns} rather than counted as dropped or empty.
+ *
+ * @param input - The rows, their declared column names, and the table's column metadata.
+ * @returns The difference between the two.
+ *
+ * @example
+ * ```ts
+ * const { data } = await api.getTableMetadata({ workspaceId, viewId });
+ * const diff = zohoAnalyticsSchemaDiff({ ...zohoAnalyticsRowDataFromCsv(csv), columns: data.columns });
+ *
+ * if (!isZohoAnalyticsSchemaDiffClean(diff)) {
+ *   throw new Error(`${diff.droppedColumns.length} columns would be dropped.`);
+ * }
+ * ```
+ */
+export declare function zohoAnalyticsSchemaDiff(input: ZohoAnalyticsSchemaDiffInput): ZohoAnalyticsSchemaDiff;
+/**
+ * Options for reducing a {@link ZohoAnalyticsSchemaDiff} to a verdict.
+ */
+export interface IsZohoAnalyticsSchemaDiffCleanOptions {
+    /**
+     * Also treat a nullable column the data omits as drift.
+     *
+     * Off by default: omitting a nullable column is how a partial `append` import is supposed to look,
+     * so counting it would make the common case fail. A column that is not nullable and has no default
+     * counts as drift either way.
+     */
+    readonly strict?: Maybe<boolean>;
+}
+/**
+ * Decides whether a diff found anything that would change or lose data on import.
+ *
+ * Drift is: a dropped column, a case-mismatched column, a value that does not fit its column, or an
+ * omitted column the table requires. A nullable column the data omits is reported by the diff but is
+ * not drift unless `strict` is set.
+ *
+ * @param diff - The diff to judge.
+ * @param options - Whether to also count omitted nullable columns; see {@link IsZohoAnalyticsSchemaDiffCleanOptions}.
+ * @returns True when the data can be imported without loss or surprise.
+ */
+export declare function isZohoAnalyticsSchemaDiffClean(diff: ZohoAnalyticsSchemaDiff, options?: Maybe<IsZohoAnalyticsSchemaDiffCleanOptions>): boolean;