@polygonlabs/servercore 1.5.0 → 1.5.1

package/dist/index.d.ts

@@ -1,31 +1,443 @@
-export { handleError, handleResponse } from './api/response_handler.js';
-export { validateBody, validateParams, validateQuery } from './api/zod_utils.js';
-export { HealthCheck, setupHealthCheckServer } from './api/health-check.js';
-export { Logger } from './logger/logger.js';
-export { errorCodes } from './constants/error_codes.js';
-export { httpResponseCodes } from './constants/http_success_codes.js';
-export { ILoggerConfig } from './types/logger_config.js';
-export { AddDocumentsParams, ConditionalUpdateDocumentsParams, DeleteDocumentsParams, GetCollectionGroupParams, GetDocumentParams, GetDocumentsParams, IDocumentConditionalModifications, IQueryFilterOperationParams, IQueryOrFilterParams, IQueryOrderOperationParams, OrderByDirection, UpdateDocumentsParams, WhereFilterOp } from './types/database.js';
-export { IObserver } from './types/observer.js';
-export { ChainNativeCurrency, IEventConsumerConfig } from './types/event_consumer_config.js';
-export { ResponseContext } from './types/response_context.js';
-export { JobOpts } from './types/queue_job_opts.js';
-export { IRestAPIConsumerConfig } from './types/rest_api_consumer_config.js';
-export { ApiError, BadRequestError, ForbiddenError, NotFoundError, RateLimitError, TimeoutError, UnauthorizedError } from './errors/api_errors.js';
-export { DatabaseError } from './errors/database_errors.js';
-export { ExternalDependencyError } from './errors/external_dependency_error.js';
-export { BaseError } from './errors/base_error.js';
-export { ConsumerError } from './errors/consumer_errors.js';
-export { Database } from './storage/db_interface.js';
-export { IQueue } from './storage/queue_interface.js';
-export { ICache } from './storage/cache_interface.js';
-export { EventConsumer } from './consumers/event_consumer.js';
-export { RestAPIConsumer } from './consumers/rest_api_consumer.js';
-export { AbstractCronEventConsumer } from './consumers/abstract_cron_event_consumer.js';
-export { decodeAbiParams, parseEventLog } from './utils/decoder.js';
-export { generateDeterministicULID } from './utils/ulid.js';
-import 'zod';
-import 'winston';
-import 'viem';
-import './consumers/abstract_event_consumer.js';
-import 'events';
+import { z } from 'zod';
+import winston from 'winston';
+import { Address, AbiEvent, PublicClient, WatchEventReturnType } from 'viem';
+import { EventEmitter } from 'events';
+
+/**
+ * BaseError used within the micro services that guarantees we don't loose the stack trace.
+ */
+declare class BaseError extends Error {
+    readonly name: string;
+    readonly code: number;
+    readonly isFatal: boolean;
+    readonly origin: string;
+    readonly context: Record<string, any>;
+    /**
+     * @param name {string} - The error name
+     * @param code {number} - The error code
+     * @param isFatal {boolean} - Flag to know if it is a fatal error
+     * @param message {string} - The actual error message
+     * @param origin {string} - The point this error originated
+     * @param context Record<string, any> - The stack trace
+     */
+    constructor(name: string, code: number, message?: string, isFatal?: boolean, origin?: string, context?: Record<string, any>);
+    identifier: number;
+}
+
+declare class ApiError extends BaseError {
+    constructor(message: string, { name, code, isFatal, origin, context, }?: {
+        name?: string;
+        code?: number;
+        isFatal?: boolean;
+        origin?: string;
+        context?: Record<string, any>;
+    });
+}
+declare class UnauthorizedError extends ApiError {
+    constructor(message?: string, context?: Record<string, any>, origin?: string);
+}
+declare class ForbiddenError extends ApiError {
+    constructor(message?: string, context?: Record<string, any>, origin?: string);
+}
+declare class BadRequestError extends ApiError {
+    readonly validationErrors: Record<string, string[]>;
+    constructor(message?: string, validationErrors?: Record<string, any>, context?: Record<string, any>, origin?: string);
+}
+declare class NotFoundError extends ApiError {
+    constructor(message: string, entity?: string, identifier?: string | number, context?: Record<string, any>, origin?: string);
+}
+declare class RateLimitError extends ApiError {
+    constructor(message?: string, context?: Record<string, any>, origin?: string);
+}
+declare class TimeoutError extends ApiError {
+    constructor(operation: string, timeoutMs: number, context?: Record<string, any>, origin?: string);
+}
+
+declare class DatabaseError extends BaseError {
+    constructor(message: string, originalError?: Error, { name, code, isFatal, origin, context, }?: {
+        name?: string;
+        code?: number;
+        isFatal?: boolean;
+        origin?: string;
+        context?: Record<string, any>;
+    });
+}
+
+declare class ExternalDependencyError extends BaseError {
+    readonly apiName: string;
+    readonly externalCode?: string | number;
+    readonly rawError?: any;
+    constructor(apiName: string, message: string, { externalCode, rawError, context, origin, }?: {
+        externalCode?: string | number;
+        rawError?: any;
+        context?: Record<string, any>;
+        origin?: string;
+    });
+}
+
+declare class ConsumerError extends BaseError {
+    constructor(message: string, { name, code, isFatal, origin, context, }?: {
+        name?: string;
+        code?: number;
+        isFatal?: boolean;
+        origin?: string;
+        context?: Record<string, any>;
+    });
+}
+
+/**
+ * Logger configuration interface
+ */
+interface ILoggerConfig {
+    sentry?: {
+        dsn?: string;
+        level?: string;
+        environment?: string;
+    };
+    console?: {
+        level?: string;
+    };
+    winston?: winston.LoggerOptions;
+}
+
+type WhereFilterOp = "<" | "<=" | "==" | "!=" | ">=" | ">" | "array-contains" | "in" | "not-in" | "array-contains-any";
+type OrderByDirection = "desc" | "asc";
+interface IQueryFilterOperationParams {
+    field: string;
+    operator: WhereFilterOp;
+    value: string | number | boolean | string[] | number[];
+}
+interface IQueryOrderOperationParams {
+    field: string;
+    order: OrderByDirection;
+}
+interface IDocumentConditionalModifications {
+    field: string;
+    value: string | number | boolean;
+    defaultValue: string | number | boolean;
+}
+interface IQueryOrFilterParams {
+    or: IQueryFilterOperationParams[];
+}
+interface AddDocumentsParams {
+    collectionPaths: string[] | string;
+    docDatas: any[];
+    docIds?: string[];
+}
+interface UpdateDocumentsParams {
+    collectionPaths: string[] | string;
+    docDatas: any[];
+    docIds: string[];
+}
+interface ConditionalUpdateDocumentsParams {
+    collectionPaths: string[] | string;
+    docDatas: any[];
+    docIds: string[];
+    conditions: IQueryFilterOperationParams[];
+    conditionModifications: IDocumentConditionalModifications[];
+}
+interface GetDocumentsParams {
+    collectionPath: string;
+    filter?: IQueryFilterOperationParams[];
+    limit?: number;
+    order?: IQueryOrderOperationParams[];
+    startAfterCursor?: string | number;
+    selectFields?: string[];
+    orFilters?: IQueryOrFilterParams[];
+    offset?: number;
+    returnTotalDocumentsCount?: boolean;
+}
+interface GetDocumentParams {
+    collectionId: string;
+    docId: string;
+}
+interface DeleteDocumentsParams {
+    collectionId: string;
+    docIds: string[];
+}
+interface GetCollectionGroupParams {
+    groupId: string;
+    filter?: IQueryFilterOperationParams[];
+    orFilters?: IQueryOrFilterParams[];
+}
+
+interface IObserver<T, E, U> {
+    next: (value: T) => Promise<void> | void;
+    summary: (value: U) => Promise<void> | void;
+    error: (value: E) => void;
+    closed: () => void;
+}
+
+type ChainNativeCurrency = {
+    name: string;
+    symbol: string;
+    decimals: number;
+};
+interface IEventConsumerConfig {
+    contractAddress: Address | Address[];
+    events: AbiEvent[];
+    chainId: number;
+    rpcUrl: string;
+    nativeCurrency: ChainNativeCurrency;
+    startBlock: bigint;
+    pollBatchSize: bigint;
+    pollInterval: number;
+}
+
+type ResponseContext = {
+    status: (statusCode: number) => ResponseContext;
+    json: (body: any) => any;
+};
+
+type JobOpts = {
+    replace?: boolean;
+};
+
+interface IRestAPIConsumerConfig {
+    apiUrl: URL;
+    startCount: {
+        key: string;
+        value: number;
+    };
+    cronExpr?: string;
+    pollSize?: number;
+    body?: Record<string, any>;
+    headers?: Record<string, string>;
+    method?: "GET" | "POST";
+    params?: Record<string, string>;
+    paginationParam?: string;
+    resultPath?: string;
+}
+
+declare const handleResponse: (c: ResponseContext, data: any, pagination?: {
+    total: number;
+    limit: number;
+    offset?: number;
+    nextStartAfterCursor?: string | number;
+}) => any;
+declare const handleError: (c: ResponseContext, error: ApiError | ExternalDependencyError | DatabaseError) => any;
+
+declare const validateBody: <T extends z.ZodTypeAny>(schema: T, data: unknown) => z.infer<T>;
+declare const validateQuery: <T extends z.ZodTypeAny>(schema: T, query: Record<string, unknown>) => z.infer<T>;
+declare const validateParams: <T extends z.ZodTypeAny>(schema: T, params: Record<string, string>) => z.infer<T>;
+
+declare class HealthCheck {
+    private readonly urls;
+    constructor(urls: string[]);
+    checkHealth(): Promise<string>;
+}
+declare function setupHealthCheckServer(urls: string[], serverPort: number, func?: Function): void;
+
+declare class Logger {
+    private static logger;
+    /**
+     * @static
+     * Create method must first be called before using the logger. It creates a singleton, which will then
+     * be referred to throughout the application.
+     */
+    static create(config: ILoggerConfig): void;
+    static ensureInitialized(): void;
+    /**
+     * @static
+     * Method to log for level - "info", this should not be called if it has been custom levels are
+     * set which does not include "info"
+     *
+     * @param {string|object} message - String or object to log.
+     */
+    static info(message: string | object): void;
+    /**
+     * @static
+     * Method to log for level - "debug", this should not be called if it has been custom levels are
+     * set which does not include "debug"
+     *
+     * @param {string|object} message - String or object to log.
+     */
+    static debug(message: string | object): void;
+    /**
+     * @static
+     * Method to log for level - "error", this should not be called if it has been custom levels are
+     * set which does not include "error"
+     *
+     * @param {string|object} error - String or object to log.
+     */
+    static error(error: string | object): void;
+    /**
+     * @static
+     * Method to log for level - "warn", this should not be called if it has been custom levels are
+     * set which does not include "warn"
+     *
+     * @param {string|object} message - String or object to log.
+     */
+    static warn(message: string | object): void;
+    /**
+     * @static
+     * Method to log for any level, which should be used to log all custom levels that may be added.
+     *
+     * @param {string|object} message - String or object to log.
+     */
+    static log(level: string, message: string | object): void;
+}
+
+declare const errorCodes: {
+    base: {
+        BASE_ERROR: number;
+    };
+    consumer: {
+        UNKNOWN_CONSUMER_ERR: number;
+    };
+    datastore: {
+        UNKNOWN_DATASTORE_ERR: number;
+        DATASTORE_AUTH_ERR: number;
+        DATASTORE_READ_ERROR: number;
+        DATASTORE_WRITE_ERROR: number;
+    };
+    external: {
+        UNKNOWN_EXTERNAL_DEPENDENCY_ERROR: number;
+    };
+    api: {
+        BAD_REQUEST: number;
+        UNAUTHORIZED: number;
+        FORBIDDEN: number;
+        NOT_FOUND: number;
+        TOO_MANY_REQUESTS: number;
+        INTERNAL_SERVER_ERROR: number;
+        GATEWAY_ERROR: number;
+        TIMEOUT_ERROR: number;
+    };
+};
+
+declare const httpResponseCodes: {
+    OK_RESPONSE: number;
+};
+
+interface Database {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    addDocuments(params: AddDocumentsParams): Promise<void>;
+    updateDocuments(params: UpdateDocumentsParams): Promise<void>;
+    conditionalUpdateDocuments(params: ConditionalUpdateDocumentsParams): Promise<void>;
+    getDocuments(params: GetDocumentsParams): Promise<{
+        documents: any[];
+        totalDocumentsCount?: number;
+    }>;
+    getDocument(params: GetDocumentParams): Promise<any | null>;
+    getCollectionGroup(params: GetCollectionGroupParams): Promise<any | null>;
+    deleteDocuments(params: DeleteDocumentsParams): Promise<void>;
+}
+
+interface IQueue<JobData = any, JobResult = any> {
+    addJob(name: string, data: JobData, jobOpts?: JobOpts): Promise<void>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    clean(type: "completed" | "failed" | "wait" | "delayed"): Promise<void>;
+    getJobCounts(): Promise<Record<string, number>>;
+}
+
+interface ICache<T = any> {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    get(key: string): Promise<T | null>;
+    set(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    ttl(key: string): Promise<number>;
+    keys(pattern?: string): Promise<string[]>;
+}
+
+declare class AbstractEventConsumer extends EventEmitter {
+    constructor();
+    /**
+     * @public
+     *
+     * Method to register listener for events. The Abstract Event Consumer emits fatalError
+     * event.
+     *
+     * @param {"fatalError"} eventName - Event name to register listener for.
+     * @param listener - Listener to be called when emitting the event.
+     *
+     * @returns {this} - Returns an instance of the class.
+     */
+    on(eventName: "fatalError", listener: (error: Error | ConsumerError) => void): this;
+    /**
+     * @public
+     *
+     * Method to register listener for events that will be called only once. The Abstract Event Consumer emits fatalError
+     * event.
+     *
+     * @param {"fatalError"} eventName - Event name to register listener for.
+     * @param listener - Listener to be called when emitting the event.
+     *
+     * @returns {this} - Returns an instance of the class.
+     */
+    once(eventName: "fatalError", listener: (error: Error | ConsumerError) => void): this;
+    protected onFatalError(error: Error | ConsumerError): void;
+}
+
+declare class EventConsumer<T, U> extends AbstractEventConsumer {
+    private readonly config;
+    protected client: PublicClient | null;
+    protected observer: IObserver<T, ConsumerError, U> | null;
+    isBackfillingInProcess: boolean;
+    protected unWatchFunction: WatchEventReturnType | undefined;
+    constructor(config: IEventConsumerConfig);
+    private _backfillEvents;
+    start(observer: IObserver<T, ConsumerError, U>): Promise<void>;
+    /**
+     * Private method which updates the connection status of consumer to disconnected, and removes all listeners.
+     *
+     * @returns {void}
+     */
+    onDisconnect(): void;
+}
+
+declare abstract class AbstractCronEventConsumer extends AbstractEventConsumer {
+    private cronJob;
+    /**
+     * Start the cron job with the given cron expression.
+     * @param cronExpr Cron expression string
+     */
+    startCron(cronExpr: string): void;
+    /**
+     * Stop the cron job.
+     */
+    stopCron(): void;
+    /**
+     * Implement this in subclasses to define what happens on each cron tick.
+     */
+    protected abstract onTick(): Promise<void>;
+}
+
+declare class RestAPIConsumer<T, U> extends AbstractCronEventConsumer {
+    private readonly config;
+    protected observer: IObserver<T, ConsumerError, U> | null;
+    private currentPage;
+    private highestValueSeen;
+    constructor(config: IRestAPIConsumerConfig);
+    start(observer: IObserver<T, ConsumerError, U>): Promise<void>;
+    stop(): void;
+    protected onTick(): Promise<void>;
+    private fetchPage;
+    private getValueByPath;
+    private processDataForCurrentCountValue;
+    /**
+     * Updates the start count value to a specific value.
+     * This allows reprocessing data from a specified point.
+     *
+     * @param value The value to set as the new start count
+     */
+    setStartValue(value: number): void;
+}
+
+declare const parseEventLog: (eventSignature: string[], data: `0x${string}`, topics: any) => {
+    eventName: undefined;
+    args: readonly unknown[] | undefined;
+};
+declare const decodeAbiParams: (params: Array<{
+    name?: string;
+    type: string;
+}>, data: `0x${string}`) => readonly unknown[];
+
+declare function generateDeterministicULID(dataToEncode: string[], timeSeed?: number, separator?: string): string;
+
+export { AbstractCronEventConsumer, type AddDocumentsParams, ApiError, BadRequestError, BaseError, type ChainNativeCurrency, type ConditionalUpdateDocumentsParams, ConsumerError, type Database, DatabaseError, type DeleteDocumentsParams, EventConsumer, ExternalDependencyError, ForbiddenError, type GetCollectionGroupParams, type GetDocumentParams, type GetDocumentsParams, HealthCheck, type ICache, type IDocumentConditionalModifications, type IEventConsumerConfig, type ILoggerConfig, type IObserver, type IQueryFilterOperationParams, type IQueryOrFilterParams, type IQueryOrderOperationParams, type IQueue, type IRestAPIConsumerConfig, type JobOpts, Logger, NotFoundError, type OrderByDirection, RateLimitError, type ResponseContext, RestAPIConsumer, TimeoutError, UnauthorizedError, type UpdateDocumentsParams, type WhereFilterOp, decodeAbiParams, errorCodes, generateDeterministicULID, handleError, handleResponse, httpResponseCodes, parseEventLog, setupHealthCheckServer, validateBody, validateParams, validateQuery };