@dereekb/zoho 10.2.0

package/src/lib/zoho.api.page.d.ts

@@ -0,0 +1,37 @@
+import { PageNumber } from '@dereekb/util';
+export interface ZohoDataArrayResultRef<T> {
+    /**
+     * Array of data returned.
+     */
+    readonly data: T[];
+}
+/**
+ * Page result that contains an array of data and page information.
+ */
+export interface ZohoPageResult<T> extends ZohoDataArrayResultRef<T> {
+    /**
+     * Current page information
+     */
+    readonly info: ZohoPageResultInfo;
+}
+/**
+ * Page information within a ZohoPageResult
+ */
+export interface ZohoPageResultInfo {
+    /**
+     * Number of results being returned per page.
+     */
+    readonly per_page: number;
+    /**
+     * Number of results returned on this page.
+     */
+    readonly count: number;
+    /**
+     * The current page number.
+     */
+    readonly page: PageNumber;
+    /**
+     * Whether or not there are more records to return.
+     */
+    readonly more_records: boolean;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Name used to identify a specific service. Always lowercase.
+ *
+ * I.E. recruit
+ */
+export type ZohoApiServiceName = string;
+/**
+ * The base URL for a Zoho API.
+ */
+export type ZohoApiUrl = string;
+/**
+ * Non-expiring refresh token used to retrieve access tokens for performing API calls.
+ *
+ * https://www.zoho.com/recruit/developer-guide/apiv2/oauth-overview.html
+ *
+ * Is in the format of "1000.abc.123"
+ */
+export type ZohoRefreshToken = string;
+/**
+ * OAuth Client Id
+ */
+export type ZohoOAuthClientId = string;
+/**
+ * OAuth Client Secret
+ */
+export type ZohoOAuthClientSecret = string;
+export interface ZohoAuthClientIdAndSecretPair {
+    readonly clientId: ZohoOAuthClientId;
+    readonly clientSecret: ZohoOAuthClientSecret;
+}
+export type ZohoApiUrlKey = 'sandbox' | 'production';
+export type ZohoConfigApiUrlInput = ZohoApiUrlKey | ZohoApiUrl;
+export interface ZohoConfig {
+    readonly apiUrl?: ZohoConfigApiUrlInput;
+}

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

@@ -0,0 +1,145 @@
+import { Maybe } from '@dereekb/util';
+import { ConfiguredFetch, FetchJsonInterceptJsonResponseFunction, FetchRequestFactoryError, FetchResponseError } from '@dereekb/util/fetch';
+import { BaseError } from 'make-error';
+export type ZohoServerErrorResponseDataError = ZohoServerErrorData | ZohoServerErrorCode;
+export interface ZohoServerErrorResponseData {
+    readonly error: ZohoServerErrorResponseDataError;
+}
+/**
+ * A code used in some cases to denote success.
+ */
+export declare const ZOHO_SUCCESS_CODE = "SUCCESS";
+export type ZohoServerSuccessCode = typeof ZOHO_SUCCESS_CODE;
+export type ZohoServerSuccessStatus = 'success';
+export type ZohoServerErrorCode = string;
+export type ZohoServerErrorStatus = 'error';
+/**
+ * Zoho Server Error Data
+ *
+ * Always contains a code and message. Details and status are optional.
+ */
+export interface ZohoServerErrorData<T = unknown> {
+    readonly code: ZohoServerErrorCode;
+    readonly message: string;
+    readonly details?: T;
+    /**
+     * Is sometimes present on some error responses.
+     */
+    readonly status?: ZohoServerErrorStatus;
+}
+/**
+ * Contains details and a status
+ */
+export type ZohoServerErrorDataWithDetails<T = unknown> = Required<ZohoServerErrorData<T>>;
+export declare function zohoServerErrorData(error: ZohoServerErrorResponseDataError): ZohoServerErrorData;
+/**
+ * Zoho Server Error
+ */
+export declare class ZohoServerError<D extends ZohoServerErrorData = ZohoServerErrorData> extends BaseError {
+    readonly error: D;
+    get code(): string;
+    constructor(error: D);
+}
+/**
+ * Zoho Server Error that includes the FetchResponseError
+ */
+export declare class ZohoServerFetchResponseError<D extends ZohoServerErrorData = ZohoServerErrorData> extends ZohoServerError<D> {
+    readonly data: D;
+    readonly responseError: FetchResponseError;
+    constructor(data: D, responseError: FetchResponseError);
+}
+export type LogZohoServerErrorFunction = (error: FetchRequestFactoryError | ZohoServerError | ZohoServerFetchResponseError) => void;
+/**
+ * Creates a logZohoServerErrorFunction that logs the error to console.
+ *
+ * @param zohoApiNamePrefix Prefix to use when logging. I.E. ZohoRecruitError, etc.
+ * @returns
+ */
+export declare function logZohoServerErrorFunction(zohoApiNamePrefix: string): LogZohoServerErrorFunction;
+/**
+ * Wraps a ConfiguredFetch to support handling errors returned by fetch.
+ *
+ * @param fetch
+ * @returns
+ */
+export type HandleZohoErrorFetchFactory = (fetch: ConfiguredFetch, logError?: LogZohoServerErrorFunction) => ConfiguredFetch;
+export type ParsedZohoServerError = FetchRequestFactoryError | ZohoServerError | undefined;
+export type ParseZohoFetchResponseErrorFunction = (responseError: FetchResponseError) => Promise<ParsedZohoServerError>;
+/**
+ * Wraps a ConfiguredFetch to support handling errors returned by fetch.
+ *
+ * @param fetch
+ * @returns
+ */
+export declare function handleZohoErrorFetchFactory(parseZohoError: ParseZohoFetchResponseErrorFunction, defaultLogError: LogZohoServerErrorFunction): HandleZohoErrorFetchFactory;
+export type ParseZohoServerErrorResponseData = (zohoServerErrorResponseData: ZohoServerErrorResponseData, fetchResponseError: FetchResponseError) => ParsedZohoServerError;
+/**
+ * FetchJsonInterceptJsonResponseFunction that intercepts ZohoServerError responses and throws a ZohoServerError.
+ *
+ * @returns
+ */
+export declare function interceptZohoErrorResponseFactory(parseZohoServerErrorResponseData: ParseZohoServerErrorResponseData): FetchJsonInterceptJsonResponseFunction;
+/**
+ * Error in the following (but not limited to) cases:
+ * - An extra parameter is provided
+ */
+export declare const ZOHO_INTERNAL_ERROR_CODE = "INTERNAL_ERROR";
+/**
+ * Error when the Zoho API returns an internal error
+ */
+export declare class ZohoInternalError extends ZohoServerFetchResponseError {
+}
+/**
+ * Error in the following cases:
+ * - Authorization is not properly constructed ("Invalid Ticket Id")
+ * - OAuth token is expired ("Invalid OAuthtoken")
+ */
+export declare const ZOHO_INVALID_AUTHORIZATION_ERROR_CODE = "4834";
+/**
+ * Error when the Zoho API returns an invalid authorization error code.
+ */
+export declare class ZohoInvalidAuthorizationError extends ZohoServerFetchResponseError {
+}
+/**
+ * Error in the following cases:
+ * - Search query is invalid
+ */
+export declare const ZOHO_INVALID_QUERY_ERROR_CODE = "INVALID_QUERY";
+export interface ZohoInvalidQueryErrorDetails {
+    readonly reason: string;
+    readonly api_name: string;
+    readonly operator: string;
+}
+export declare class ZohoInvalidQueryError extends ZohoServerFetchResponseError {
+    get details(): ZohoInvalidQueryErrorDetails;
+}
+/**
+ * Error when a mandatory field is missing.
+ */
+export declare const ZOHO_MANDATORY_NOT_FOUND_ERROR_CODE = "MANDATORY_NOT_FOUND";
+/**
+ * Error when a duplicate record is found with a matching unique field value.
+ */
+export declare const ZOHO_DUPLICATE_DATA_ERROR_CODE = "DUPLICATE_DATA";
+/**
+ * Error when some passed data is invalid.
+ */
+export declare const ZOHO_INVALID_DATA_ERROR_CODE = "INVALID_DATA";
+/**
+ * Function that parses/transforms a ZohoServerErrorResponseData into a general ZohoServerError or other known error type.
+ *
+ * @param errorResponseData
+ * @param responseError
+ * @returns
+ */
+export declare function parseZohoServerErrorResponseData(errorResponseData: ZohoServerErrorResponseData, responseError: FetchResponseError): ZohoServerFetchResponseError | undefined;
+/**
+ * Attempts to retrieve an ZohoServerErrorResponseDataError from the input.
+ *
+ * Non-200 errors returned by the Zoho API are returned as the object directly instead of as an ZohoServerErrorResponseData directly.
+ *
+ * @param errorResponseData
+ * @param responseError
+ * @returns
+ */
+export declare function tryFindZohoServerErrorData(errorResponseData: ZohoServerErrorResponseData | ZohoServerErrorResponseDataError, responseError: FetchResponseError): Maybe<ZohoServerErrorResponseDataError>;

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

@@ -0,0 +1,20 @@
+import { WebsitePath } from '@dereekb/util';
+export interface ZohoModel {
+}
+/**
+ * General Zoho API GET request response sent by the v1 API.
+ *
+ * @deprecated
+ */
+export interface ZohoGetApiV1Result<T> {
+    readonly response: {
+        /**
+         * Result value
+         */
+        readonly result: T;
+        /**
+         * Path to the resource.
+         */
+        readonly url: WebsitePath;
+    };
+}