dune

type DuneClient interface {
	// New APIs to read results in a more flexible way
	// returns the results or status of an execution, depending on whether it has completed
	QueryResultsV2(executionID string, options models.ResultOptions) (*models.ResultsResponse, error)
	// returns the results of a QueryID, depending on whether it has completed
	ResultsByQueryID(queryID string, options models.ResultOptions) (*models.ResultsResponse, error)

	// RunQuery submits a query for execution and returns an Execution object
	RunQuery(req models.ExecuteRequest) (Execution, error)
	// RunQueryGetRows submits a query for execution, blocks until execution is finished, and returns just the result rows
	RunQueryGetRows(req models.ExecuteRequest) ([]map[string]any, error)

	// QueryCancel cancels the execution of an execution in the pending or executing state
	QueryCancel(executionID string) error

	// QueryExecute submits a query to execute with the provided parameters
	QueryExecute(req models.ExecuteRequest) (*models.ExecuteResponse, error)

	// SQLExecute executes raw SQL with optional performance parameter
	SQLExecute(req models.ExecuteSQLRequest) (*models.ExecuteResponse, error)

	// QueryPipelineExecute submits a query pipeline for execution with optional performance parameter
	QueryPipelineExecute(req models.PipelineExecuteRequest) (*models.PipelineExecuteResponse, error)

	// PipelineStatus returns the current pipeline execution status
	PipelineStatus(pipelineExecutionID string) (*models.PipelineStatusResponse, error)

	// RunSQL submits raw SQL for execution and returns an Execution object
	RunSQL(req models.ExecuteSQLRequest) (Execution, error)

	// QueryStatus returns the current execution status
	QueryStatus(executionID string) (*models.StatusResponse, error)

	// QueryResults returns the results or status of an execution, depending on whether it has completed
	// DEPRECATED, use QueryResultsV2 instead
	QueryResults(executionID string) (*models.ResultsResponse, error)

	// QueryResultsCSV returns the results of an execution, as CSV text stream if the execution has completed
	QueryResultsCSV(executionID string) (io.Reader, error)

	// QueryResultsByQueryID returns the results of the lastest execution for a given query ID
	// DEPRECATED, use ResultsByQueryID instead
	QueryResultsByQueryID(queryID string) (*models.ResultsResponse, error)

	// QueryResultsCSVByQueryID returns the results of the lastest execution for a given query ID
	// as CSV text stream if the execution has completed
	QueryResultsCSVByQueryID(queryID string) (io.Reader, error)

	// GetUsage returns usage statistics for the current billing period
	GetUsage() (*models.UsageResponse, error)

	// GetUsageForDates returns usage statistics for a specified time range
	GetUsageForDates(startDate, endDate string) (*models.UsageResponse, error)

	// ListDatasets returns a paginated list of datasets with optional filtering
	ListDatasets(limit, offset int, ownerHandle, datasetType string) (*models.ListDatasetsResponse, error)

	// GetDataset returns detailed information about a specific dataset by slug
	GetDataset(slug string) (*models.DatasetResponse, error)

	// ListUploads returns a paginated list of uploaded tables
	ListUploads(limit, offset int) (*models.UploadsListResponse, error)

	// CreateUpload creates an empty table with defined schema
	CreateUpload(req models.UploadsCreateRequest) (*models.UploadsCreateResponse, error)

	// UploadCSV uploads CSV data to create a new table
	UploadCSV(req models.UploadsCSVRequest) (*models.UploadsCSVResponse, error)

	// DeleteUpload permanently deletes a table and all its data
	DeleteUpload(namespace, tableName string) (*models.UploadsDeleteResponse, error)

	// ClearUpload removes all data from a table while preserving schema
	ClearUpload(namespace, tableName string) (*models.UploadsClearResponse, error)

	// InsertIntoUpload inserts data into an existing table (CSV or NDJSON format)
	InsertIntoUpload(namespace, tableName, data, contentType string) (*models.UploadsInsertResponse, error)

	// DEPRECATED: Use ListUploads instead. Will be removed March 1, 2026.
	ListTables(limit, offset int) (*models.UploadsListResponse, error)

	// DEPRECATED: Use CreateUpload instead. Will be removed March 1, 2026.
	CreateTable(req models.UploadsCreateRequest) (*models.UploadsCreateResponse, error)

	// DEPRECATED: Use UploadCSV instead. Will be removed March 1, 2026.
	UploadCSVDeprecated(req models.UploadsCSVRequest) (*models.UploadsCSVResponse, error)

	// DEPRECATED: Use DeleteUpload instead. Will be removed March 1, 2026.
	DeleteTable(namespace, tableName string) (*models.UploadsDeleteResponse, error)

	// DEPRECATED: Use ClearUpload instead. Will be removed March 1, 2026.
	ClearTable(namespace, tableName string) (*models.UploadsClearResponse, error)

	// DEPRECATED: Use InsertIntoUpload instead. Will be removed March 1, 2026.
	InsertTable(namespace, tableName, data, contentType string) (*models.UploadsInsertResponse, error)

	// CreateQuery creates a new saved query
	CreateQuery(req models.CreateQueryRequest) (*models.CreateQueryResponse, error)

	// GetQuery retrieves a saved query by ID
	GetQuery(queryID int) (*models.GetQueryResponse, error)

	// UpdateQuery updates an existing saved query
	UpdateQuery(queryID int, req models.UpdateQueryRequest) (*models.UpdateQueryResponse, error)

	// ArchiveQuery archives a saved query
	ArchiveQuery(queryID int) (*models.UpdateQueryResponse, error)

	// SearchDatasets searches for datasets across the catalog with advanced filters
	SearchDatasets(req models.SearchDatasetsRequest) (*models.SearchDatasetsResponse, error)

	// SearchDatasetsByContractAddress finds decoded datasets associated with a smart contract address
	SearchDatasetsByContractAddress(req models.SearchDatasetsByContractAddressRequest) (*models.SearchDatasetsResponse, error)

	// WhoAmI returns the identity associated with the current API key
	WhoAmI() (*models.WhoAmIResponse, error)

	// CreateVisualization creates a new visualization on an existing query
	CreateVisualization(req models.CreateVisualizationRequest) (*models.CreateVisualizationResponse, error)

	// GetVisualization retrieves a visualization by ID
	GetVisualization(visualizationID int) (*models.GetVisualizationResponse, error)

	// UpdateVisualization updates an existing visualization
	UpdateVisualization(visualizationID int, req models.UpdateVisualizationRequest) (*models.UpdateVisualizationResponse, error)

	// DeleteVisualization deletes a visualization by ID
	DeleteVisualization(visualizationID int) (*models.DeleteVisualizationResponse, error)

	// ListQueryVisualizations returns a paginated list of visualizations for a query
	ListQueryVisualizations(queryID, limit, offset int) (*models.ListVisualizationsResponse, error)
}

type ErrorResponse struct {
	Error string `json:"error"`
}

type Execution interface {
	// QueryCancel cancels the execution
	Cancel() error
	// GetResults returns the results or status of the execution, depending on whether it has completed
	GetResults() (*models.ResultsResponse, error)
	// GetResultsCSV returns the results in CSV format
	GetResultsCSV() (io.Reader, error)
	// QueryStatus returns the current execution status
	GetStatus() (*models.StatusResponse, error)

	// GetResultsV2 returns the results or status of the execution, depending on whether it has completed
	// it uses options to refine futher what results to get
	GetResultsV2(options models.ResultOptions) (*models.ResultsResponse, error)

	// RunQueryGetResults  blocks until the execution is finished and returns the result
	// maxRetries is used when using the RunQueryToCompletion method, to limit the number of times the method
	// will tolerate API errors before giving up. A value of zero will disable the retry limit.
	// It is recommended to set this to something non-zero, as there is a risk that this will block indefinitely
	// if the Dune API is unreachable or returns an error. The pollInterval determines how long to wait between
	// GetResult requests. It is recommended to set to at least 5 seconds to prevent rate-limiting.
	WaitGetResults(pollInterval time.Duration, maxRetries int) (*models.ResultsResponse, error)
	// GetID returns the execution ID
	GetID() string
}

type Pipeline interface {
	GetStatus() (*models.PipelineStatusResponse, error)
	GetID() string
}