@riverfl0w/dune-client/dist/index.d.cts

A TypeScript client for querying the Dune API, designed to simplify the integration of Dune's powerful analytics into your projects.

import { ZodSchema, z } from 'zod';

interface CallOptions<S extends ZodSchema> extends RequestInit {
    path: string;
    searchParams?: URLSearchParams;
    schema: S;
    delay?: number;
}
/**
 * Base client for Dune API. It handles the API key and error handling.
 */
declare class BaseClient {
    private readonly apiKey;
    private readonly base;
    constructor(apiKey: string);
    protected call<S extends ZodSchema>({ path, searchParams, schema, delay, ...options }: CallOptions<S>): Promise<z.infer<S>>;
}

interface ExecutionResultsArgs {
    execution_id: string;
}

interface ExecutionStatusArgs {
    execution_id: string;
}

declare class ExecutionClient extends BaseClient {
    /**
     * Get the status of an execution.
     * @see https://dune.com/docs/api/api-reference/get-results/execution-status/
     */
    status({ execution_id }: ExecutionStatusArgs): Promise<{
        execution_id: string;
        query_id: number;
        is_execution_finished: boolean;
    } & ({
        state: "QUERY_STATE_PENDING";
        submitted_at: string;
        queue_position?: number | undefined;
    } | {
        state: "QUERY_STATE_EXECUTING";
        submitted_at: string;
        execution_started_at: string;
    } | {
        state: "QUERY_STATE_FAILED";
        submitted_at: string;
        expires_at: string;
        execution_started_at: string;
        execution_ended_at: string;
    } | {
        state: "QUERY_STATE_COMPLETED";
        submitted_at: string;
        expires_at: string;
        execution_started_at: string;
        execution_ended_at: string;
        result_metadata: {
            column_names: string[];
            result_set_bytes: number;
            total_row_count: number;
            datapoint_count: number;
            pending_time_millis: number;
            execution_time_millis: number;
        };
    } | {
        state: "QUERY_STATE_CANCELLED";
        submitted_at: string;
        expires_at: string;
        cancelled_at: string;
    } | {
        state: "QUERY_STATE_EXPIRED";
    })>;
    /**
     * Cancel an execution.
     * @see https://dune.com/docs/api/api-reference/execute-queries/cancel-execution/
     */
    cancel({ execution_id }: ExecutionStatusArgs): Promise<{
        success: boolean;
    }>;
    /**
     * Get the results of an execution.
     * @see https://dune.com/docs/api/api-reference/get-results/execution-status/
     */
    results({ execution_id }: ExecutionResultsArgs): Promise<{
        execution_id: string;
        query_id: number;
        is_execution_finished: boolean;
    } & ({
        error: {
            message: string;
            type: string;
            metadata: Record<string, unknown>;
        };
        state: "QUERY_STATE_FAILED";
        submitted_at: string;
        expires_at: string;
        execution_started_at: string;
        execution_ended_at: string;
    } | {
        state: "QUERY_STATE_COMPLETED";
        submitted_at: string;
        expires_at: string;
        execution_started_at: string;
        execution_ended_at: string;
        result: {
            metadata: {
                column_names: string[];
                result_set_bytes: number;
                total_row_count: number;
                datapoint_count: number;
                pending_time_millis: number;
                execution_time_millis: number;
            };
            rows: Record<string, unknown>[];
        };
    } | {
        state: "QUERY_STATE_CANCELLED";
        submitted_at: string;
        expires_at: string;
        cancelled_at: string;
    } | {
        state: "QUERY_STATE_EXPIRED";
    })>;
}

interface ExecuteQueryArgs {
    query_id: string | number;
    performance?: 'medium' | 'large';
    query_parameters?: Record<string, unknown>;
}

interface ResultsOptions {
    query_id: string | number;
    ignore_max_datapoints_per_request?: boolean;
}
declare class QueryClient extends BaseClient {
    /**
     * Execute am existing Dune query.
     * @see https://dune.com/docs/api/api-reference/execute-queries/execute-query-id/
     */
    execute({ query_id, ...options }: ExecuteQueryArgs): Promise<{
        execution_id: string;
    } & ({
        state: "QUERY_STATE_PENDING";
    } | {
        state: "QUERY_STATE_EXECUTING";
    })>;
    /**
     * Get the latedst results of a Dune query. This method does NOT execute the query.
     * @see https://dune.com/docs/api/api-reference/get-results/latest-results/
     */
    results({ query_id, ignore_max_datapoints_per_request }: ResultsOptions): Promise<{
        execution_id: string;
        query_id: number;
        is_execution_finished: boolean;
    } & ({
        error: {
            message: string;
            type: string;
            metadata: Record<string, unknown>;
        };
        state: "QUERY_STATE_FAILED";
        submitted_at: string;
        expires_at: string;
        execution_started_at: string;
        execution_ended_at: string;
    } | {
        state: "QUERY_STATE_COMPLETED";
        submitted_at: string;
        expires_at: string;
        execution_started_at: string;
        execution_ended_at: string;
        result: {
            metadata: {
                column_names: string[];
                result_set_bytes: number;
                total_row_count: number;
                datapoint_count: number;
                pending_time_millis: number;
                execution_time_millis: number;
            };
            rows: Record<string, unknown>[];
        };
    } | {
        state: "QUERY_STATE_CANCELLED";
        submitted_at: string;
        expires_at: string;
        cancelled_at: string;
    } | {
        state: "QUERY_STATE_EXPIRED";
    })>;
}

declare const CancelExecutionResponse: z.ZodObject<{
    success: z.ZodBoolean;
}, "strip", z.ZodTypeAny, {
    success: boolean;
}, {
    success: boolean;
}>;
type CancelExecutionResponse = z.infer<typeof CancelExecutionResponse>;

declare const ErrorResponse: z.ZodObject<{
    error: z.ZodString;
}, "strip", z.ZodTypeAny, {
    error: string;
}, {
    error: string;
}>;
type ErrorResponse = z.infer<typeof ErrorResponse>;

declare const ExecuteQueryResponse: z.ZodIntersection<z.ZodObject<{
    execution_id: z.ZodString;
}, "strip", z.ZodTypeAny, {
    execution_id: string;
}, {
    execution_id: string;
}>, z.ZodDiscriminatedUnion<"state", [z.ZodObject<{
    state: z.ZodLiteral<"QUERY_STATE_PENDING">;
}, "strip", z.ZodTypeAny, {
    state: "QUERY_STATE_PENDING";
}, {
    state: "QUERY_STATE_PENDING";
}>, z.ZodObject<{
    state: z.ZodLiteral<"QUERY_STATE_EXECUTING">;
}, "strip", z.ZodTypeAny, {
    state: "QUERY_STATE_EXECUTING";
}, {
    state: "QUERY_STATE_EXECUTING";
}>]>>;
type ExecuteQueryResponse = z.infer<typeof ExecuteQueryResponse>;

declare const ExecutionResultsResponse: z.ZodIntersection<z.ZodObject<{
    execution_id: z.ZodString;
    query_id: z.ZodNumber;
    is_execution_finished: z.ZodBoolean;
}, "strip", z.ZodTypeAny, {
    execution_id: string;
    query_id: number;
    is_execution_finished: boolean;
}, {
    execution_id: string;
    query_id: number;
    is_execution_finished: boolean;
}>, z.ZodDiscriminatedUnion<"state", [z.ZodObject<{
    state: z.ZodLiteral<"QUERY_STATE_FAILED">;
    submitted_at: z.ZodString;
    expires_at: z.ZodString;
    execution_started_at: z.ZodString;
    execution_ended_at: z.ZodString;
    error: z.ZodObject<{
        type: z.ZodString;
        message: z.ZodString;
        metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
    }, "strip", z.ZodTypeAny, {
        message: string;
        type: string;
        metadata: Record<string, unknown>;
    }, {
        message: string;
        type: string;
        metadata: Record<string, unknown>;
    }>;
}, "strip", z.ZodTypeAny, {
    error: {
        message: string;
        type: string;
        metadata: Record<string, unknown>;
    };
    state: "QUERY_STATE_FAILED";
    submitted_at: string;
    expires_at: string;
    execution_started_at: string;
    execution_ended_at: string;
}, {
    error: {
        message: string;
        type: string;
        metadata: Record<string, unknown>;
    };
    state: "QUERY_STATE_FAILED";
    submitted_at: string;
    expires_at: string;
    execution_started_at: string;
    execution_ended_at: string;
}>, z.ZodObject<{
    state: z.ZodLiteral<"QUERY_STATE_COMPLETED">;
    submitted_at: z.ZodString;
    expires_at: z.ZodString;
    execution_started_at: z.ZodString;
    execution_ended_at: z.ZodString;
    result: z.ZodObject<{
        rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">;
        metadata: z.ZodObject<{
            column_names: z.ZodArray<z.ZodString, "many">;
            result_set_bytes: z.ZodNumber;
            total_row_count: z.ZodNumber;
            datapoint_count: z.ZodNumber;
            pending_time_millis: z.ZodNumber;
            execution_time_millis: z.ZodNumber;
        }, "strip", z.ZodTypeAny, {
            column_names: string[];
            result_set_bytes: number;
            total_row_count: number;
            datapoint_count: number;
            pending_time_millis: number;
            execution_time_millis: number;
        }, {
            column_names: string[];
            result_set_bytes: number;
            total_row_count: number;
            datapoint_count: number;
            pending_time_millis: number;
            execution_time_millis: number;
        }>;
    }, "strip", z.ZodTypeAny, {
        metadata: {
            column_names: string[];
            result_set_bytes: number;
            total_row_count: number;
            datapoint_count: number;
            pending_time_millis: number;
            execution_time_millis: number;
        };
        rows: Record<string, unknown>[];
    }, {
        metadata: {
            column_names: string[];
            result_set_bytes: number;
            total_row_count: number;
            datapoint_count: number;
            pending_time_millis: number;
            execution_time_millis: number;
        };
        rows: Record<string, unknown>[];
    }>;
}, "strip", z.ZodTypeAny, {
    state: "QUERY_STATE_COMPLETED";
    submitted_at: string;
    expires_at: string;
    execution_started_at: string;
    execution_ended_at: string;
    result: {
        metadata: {
            column_names: string[];
            result_set_bytes: number;
            total_row_count: number;
            datapoint_count: number;
            pending_time_millis: number;
            execution_time_millis: number;
        };
        rows: Record<string, unknown>[];
    };
}, {
    state: "QUERY_STATE_COMPLETED";
    submitted_at: string;
    expires_at: string;
    execution_started_at: string;
    execution_ended_at: string;
    result: {
        metadata: {
            column_names: string[];
            result_set_bytes: number;
            total_row_count: number;
            datapoint_count: number;
            pending_time_millis: number;
            execution_time_millis: number;
        };
        rows: Record<string, unknown>[];
    };
}>, z.ZodObject<{
    state: z.ZodLiteral<"QUERY_STATE_CANCELLED">;
    submitted_at: z.ZodString;
    expires_at: z.ZodString;
    cancelled_at: z.ZodString;
}, "strip", z.ZodTypeAny, {
    state: "QUERY_STATE_CANCELLED";
    submitted_at: string;
    expires_at: string;
    cancelled_at: string;
}, {
    state: "QUERY_STATE_CANCELLED";
    submitted_at: string;
    expires_at: string;
    cancelled_at: string;
}>, z.ZodObject<{
    state: z.ZodLiteral<"QUERY_STATE_EXPIRED">;
}, "strip", z.ZodTypeAny, {
    state: "QUERY_STATE_EXPIRED";
}, {
    state: "QUERY_STATE_EXPIRED";
}>]>>;

declare const ExecutionStatusResponse: z.ZodIntersection<z.ZodObject<{
    execution_id: z.ZodString;
    query_id: z.ZodNumber;
    is_execution_finished: z.ZodBoolean;
}, "strip", z.ZodTypeAny, {
    execution_id: string;
    query_id: number;
    is_execution_finished: boolean;
}, {
    execution_id: string;
    query_id: number;
    is_execution_finished: boolean;
}>, z.ZodDiscriminatedUnion<"state", [z.ZodObject<{
    state: z.ZodLiteral<"QUERY_STATE_PENDING">;
    queue_position: z.ZodOptional<z.ZodNumber>;
    submitted_at: z.ZodString;
}, "strip", z.ZodTypeAny, {
    state: "QUERY_STATE_PENDING";
    submitted_at: string;
    queue_position?: number | undefined;
}, {
    state: "QUERY_STATE_PENDING";
    submitted_at: string;
    queue_position?: number | undefined;
}>, z.ZodObject<{
    state: z.ZodLiteral<"QUERY_STATE_EXECUTING">;
    submitted_at: z.ZodString;
    execution_started_at: z.ZodString;
}, "strip", z.ZodTypeAny, {
    state: "QUERY_STATE_EXECUTING";
    submitted_at: string;
    execution_started_at: string;
}, {
    state: "QUERY_STATE_EXECUTING";
    submitted_at: string;
    execution_started_at: string;
}>, z.ZodObject<{
    state: z.ZodLiteral<"QUERY_STATE_FAILED">;
    submitted_at: z.ZodString;
    expires_at: z.ZodString;
    execution_started_at: z.ZodString;
    execution_ended_at: z.ZodString;
}, "strip", z.ZodTypeAny, {
    state: "QUERY_STATE_FAILED";
    submitted_at: string;
    expires_at: string;
    execution_started_at: string;
    execution_ended_at: string;
}, {
    state: "QUERY_STATE_FAILED";
    submitted_at: string;
    expires_at: string;
    execution_started_at: string;
    execution_ended_at: string;
}>, z.ZodObject<{
    state: z.ZodLiteral<"QUERY_STATE_COMPLETED">;
    submitted_at: z.ZodString;
    expires_at: z.ZodString;
    execution_started_at: z.ZodString;
    execution_ended_at: z.ZodString;
    result_metadata: z.ZodObject<{
        column_names: z.ZodArray<z.ZodString, "many">;
        result_set_bytes: z.ZodNumber;
        total_row_count: z.ZodNumber;
        datapoint_count: z.ZodNumber;
        pending_time_millis: z.ZodNumber;
        execution_time_millis: z.ZodNumber;
    }, "strip", z.ZodTypeAny, {
        column_names: string[];
        result_set_bytes: number;
        total_row_count: number;
        datapoint_count: number;
        pending_time_millis: number;
        execution_time_millis: number;
    }, {
        column_names: string[];
        result_set_bytes: number;
        total_row_count: number;
        datapoint_count: number;
        pending_time_millis: number;
        execution_time_millis: number;
    }>;
}, "strip", z.ZodTypeAny, {
    state: "QUERY_STATE_COMPLETED";
    submitted_at: string;
    expires_at: string;
    execution_started_at: string;
    execution_ended_at: string;
    result_metadata: {
        column_names: string[];
        result_set_bytes: number;
        total_row_count: number;
        datapoint_count: number;
        pending_time_millis: number;
        execution_time_millis: number;
    };
}, {
    state: "QUERY_STATE_COMPLETED";
    submitted_at: string;
    expires_at: string;
    execution_started_at: string;
    execution_ended_at: string;
    result_metadata: {
        column_names: string[];
        result_set_bytes: number;
        total_row_count: number;
        datapoint_count: number;
        pending_time_millis: number;
        execution_time_millis: number;
    };
}>, z.ZodObject<{
    state: z.ZodLiteral<"QUERY_STATE_CANCELLED">;
    submitted_at: z.ZodString;
    expires_at: z.ZodString;
    cancelled_at: z.ZodString;
}, "strip", z.ZodTypeAny, {
    state: "QUERY_STATE_CANCELLED";
    submitted_at: string;
    expires_at: string;
    cancelled_at: string;
}, {
    state: "QUERY_STATE_CANCELLED";
    submitted_at: string;
    expires_at: string;
    cancelled_at: string;
}>, z.ZodObject<{
    state: z.ZodLiteral<"QUERY_STATE_EXPIRED">;
}, "strip", z.ZodTypeAny, {
    state: "QUERY_STATE_EXPIRED";
}, {
    state: "QUERY_STATE_EXPIRED";
}>]>>;
type ExecutionStatusResponse = z.infer<typeof ExecutionStatusResponse>;

declare const ResultMetadata: z.ZodObject<{
    column_names: z.ZodArray<z.ZodString, "many">;
    result_set_bytes: z.ZodNumber;
    total_row_count: z.ZodNumber;
    datapoint_count: z.ZodNumber;
    pending_time_millis: z.ZodNumber;
    execution_time_millis: z.ZodNumber;
}, "strip", z.ZodTypeAny, {
    column_names: string[];
    result_set_bytes: number;
    total_row_count: number;
    datapoint_count: number;
    pending_time_millis: number;
    execution_time_millis: number;
}, {
    column_names: string[];
    result_set_bytes: number;
    total_row_count: number;
    datapoint_count: number;
    pending_time_millis: number;
    execution_time_millis: number;
}>;
type ResultMetadata = z.infer<typeof ResultMetadata>;

/**
 * Custom error class for Dune.
 */
declare class DuneError extends Error {
}

interface RefreshQueryArgs extends ExecuteQueryArgs {
    cooldown?: number;
}

/**
 * Public API client for Dune Analytics. It contains the following sub-clients:
 * - `execution` for managing query executions
 * - `query` for querying the results of a query
 */
declare class DuneClient {
    readonly execution: ExecutionClient;
    readonly query: QueryClient;
    constructor(apiKey: string);
    /**
     * Convenience method to refresh the results of a query.
     * It will wait for the query to finish and return the results.
     * @param param0
     * @returns
     */
    refresh({ cooldown, ...args }: RefreshQueryArgs): Promise<{
        execution_id: string;
        query_id: number;
        is_execution_finished: boolean;
    } & ({
        error: {
            message: string;
            type: string;
            metadata: Record<string, unknown>;
        };
        state: "QUERY_STATE_FAILED";
        submitted_at: string;
        expires_at: string;
        execution_started_at: string;
        execution_ended_at: string;
    } | {
        state: "QUERY_STATE_COMPLETED";
        submitted_at: string;
        expires_at: string;
        execution_started_at: string;
        execution_ended_at: string;
        result: {
            metadata: {
                column_names: string[];
                result_set_bytes: number;
                total_row_count: number;
                datapoint_count: number;
                pending_time_millis: number;
                execution_time_millis: number;
            };
            rows: Record<string, unknown>[];
        };
    } | {
        state: "QUERY_STATE_CANCELLED";
        submitted_at: string;
        expires_at: string;
        cancelled_at: string;
    } | {
        state: "QUERY_STATE_EXPIRED";
    })>;
}

export { BaseClient, type CallOptions, CancelExecutionResponse as CancelQueryResponse, DuneClient, DuneError, ErrorResponse, ExecuteQueryResponse, ExecutionClient, ExecutionResultsResponse as ExecutionResultResponse, ExecutionStatusResponse, QueryClient, ResultMetadata };