Add execute raw sql, usage and status endpoint error field APP-6031 (#84)

Co-authored-by: Benjamin Smith <bh2smith@users.noreply.github.com>

Author: ivpusic

README.md

@@ -42,6 +42,24 @@ client
 //  ]
 ```
 
+## Execute Raw SQL
+
+You can execute raw SQL queries directly using the `executeSql` method:
+
+```ts
+const { DUNE_API_KEY } = process.env;
+
+const client = new DuneClient(DUNE_API_KEY ?? "");
+const execution = await client.exec.executeSql({
+  sql: "SELECT * FROM dex.trades WHERE block_time > now() - interval '1' day LIMIT 10",
+  performance: QueryEngine.Medium, // optional
+});
+
+const executionId = execution.execution_id;
+const status = await client.exec.getExecutionStatus(executionId);
+const results = await client.exec.getExecutionResults(executionId);
+```
+
 ## Custom API
 
 ```ts
@@ -56,6 +74,21 @@ const results = await client.custom.getResults({
 });
 ```
 
+## Usage API
+
+Get information about your API usage, including credits and storage:
+
+```ts
+const { DUNE_API_KEY } = process.env;
+
+const client = new DuneClient(DUNE_API_KEY ?? "");
+const usage = await client.usage.getUsage();
+
+console.log(`Credits used: ${usage.billing_periods[0].credits_used}`);
+console.log(`Private queries: ${usage.private_queries}`);
+console.log(`Storage: ${usage.bytes_used} / ${usage.bytes_allowed} bytes`);
+```
+
 
 Note also that the client has methods `executeQuery`, `getExecutionStatus`, `getExecutionResult` and `cancelExecution`
 

src/api/client.ts

@@ -24,6 +24,7 @@ import { POLL_FREQUENCY_SECONDS } from "../constants";
 import { QueryAPI } from "./query";
 import { TableAPI } from "./table";
 import { CustomAPI } from "./custom";
+import { UsageAPI } from "./usage";
 import { deprecationWarning } from "../deprecation";
 
 /// Various states of query execution that are "terminal".
@@ -47,12 +48,15 @@ export class DuneClient {
   table: TableAPI;
   /// Custom Endpoint Interface
   custom: CustomAPI;
+  /// Usage Interface
+  usage: UsageAPI;
 
   constructor(apiKey: string) {
     this.exec = new ExecutionAPI(apiKey);
     this.query = new QueryAPI(apiKey);
     this.table = new TableAPI(apiKey);
     this.custom = new CustomAPI(apiKey);
+    this.usage = new UsageAPI(apiKey);
   }
 
   /**

src/api/execution.ts

@@ -12,6 +12,7 @@ import {
   QueryEngine,
   GetResultParams,
   validateAndBuildGetResultParams,
+  ExecuteSqlParams,
 } from "../types";
 import log from "loglevel";
 import { ageInHours, logPrefix } from "../utils";
@@ -51,6 +52,23 @@ export class ExecutionAPI extends Router {
     return response as ExecutionResponse;
   }
 
+  /**
+   * Executes raw SQL according to:
+   * https://docs.dune.com/api-reference/executions/endpoint/execute-sql
+   * @param {ExecuteSqlParams} params including SQL query and execution performance.
+   * @returns {ExecutionResponse} response containing execution ID and state.
+   */
+  async executeSql(params: ExecuteSqlParams): Promise<ExecutionResponse> {
+    const { sql, performance = QueryEngine.Medium } = params;
+
+    const response = await this.post<ExecutionResponse>(`sql/execute`, {
+      sql,
+      performance,
+    });
+    log.debug(logPrefix, `execute sql response ${JSON.stringify(response)}`);
+    return response as ExecutionResponse;
+  }
+
   /**
    * Cancels an execution according to:
    * https://docs.dune.com/api-reference/executions/endpoint/cancel-execution

src/api/index.ts

@@ -4,3 +4,4 @@ export * from "./execution";
 export * from "./query";
 export * from "./router";
 export * from "./table";
+export * from "./usage";

src/api/usage.ts

@@ -0,0 +1,19 @@
+import { Router } from "./router";
+import { UsageResponse } from "../types";
+
+/**
+ * Usage API Interface:
+ * Get information about API usage and credits.
+ * https://docs.dune.com/api-reference/usage/endpoint/get-usage
+ */
+export class UsageAPI extends Router {
+  /**
+   * Get usage information for the current API key.
+   * Returns details about private queries, dashboards, storage,
+   * and credit usage for billing periods.
+   * @returns {Promise<UsageResponse>} usage information including credits and storage
+   */
+  async getUsage(): Promise<UsageResponse> {
+    return this.post<UsageResponse>("usage");
+  }
+}

src/index.ts

@@ -1,3 +1,3 @@
-export { DuneClient, QueryAPI, ExecutionAPI, CustomAPI, TableAPI } from "./api";
+export { DuneClient, QueryAPI, ExecutionAPI, CustomAPI, TableAPI, UsageAPI } from "./api";
 export * from "./types";
 export { Paginator } from "./paginator";

src/types/requestArgs.ts

@@ -24,6 +24,7 @@ export type UploadCSVArgs = {
 export type RequestPayload =
   | GetResultParams
   | ExecuteQueryParams
+  | ExecuteSqlParams
   | UpdateQueryParams
   | CreateQueryParams
   | UploadCSVArgs
@@ -204,6 +205,13 @@ export interface ExecuteQueryParams extends BaseParams {
   performance: QueryEngine;
 }
 
+export interface ExecuteSqlParams {
+  /// The SQL query to execute
+  sql: string;
+  /// The performance engine tier the execution will be run on
+  performance?: QueryEngine;
+}
+
 export interface BaseCRUDParams extends BaseParams {
   /// Description of the query.
   description?: string;

src/types/response.ts

@@ -91,6 +91,7 @@ interface BaseStatusResponse extends TimeData {
   // Unique identifier of the query.
   query_id: number;
   queue_position?: number;
+  error?: ErrorResult;
 }
 
 /// Format of a `GetStatusResponse` when the query execution is anything but complete.
@@ -215,3 +216,18 @@ export interface CreateTableResult {
 export interface InsertTableResult {
   rows_written: number;
 }
+
+export interface BillingPeriod {
+  start_date: string;
+  end_date: string;
+  credits_used: number;
+  credits_included: number;
+}
+
+export interface UsageResponse {
+  private_queries: number;
+  private_dashboards: number;
+  bytes_used: number;
+  bytes_allowed: number;
+  billing_periods: BillingPeriod[];
+}

tests/e2e/execution.spec.ts

@@ -244,6 +244,23 @@ describe("ExecutionAPI: native routes", () => {
     const expectedRows = ["number\n", "2\n"];
     expect(resultCSV.data).toEqual(expectedRows.join(""));
   });
+
+  it("executes raw SQL with executeSql", async () => {
+    const execution = await client.executeSql({
+      sql: "SELECT * FROM dex.trades WHERE block_time > now() - interval '1' day LIMIT 10",
+    });
+    expect(execution.execution_id).not.toEqual(null);
+    expect(execution.state).toBeDefined();
+  });
+
+  it("executes raw SQL with performance parameter", async () => {
+    const execution = await client.executeSql({
+      sql: "SELECT 1 as test_value",
+      performance: QueryEngine.Medium,
+    });
+    expect(execution.execution_id).not.toEqual(null);
+    expect(execution.state).toBeDefined();
+  });
 });
 
 describe("ExecutionAPI: Errors", () => {
@@ -306,7 +323,7 @@ describe("ExecutionAPI: Errors", () => {
     // Create a query with intentionally bad SQL
     const queryId = await fullClient.query.createQuery({
       name: "Test Failed Query",
-      query_sql: "SELECT x", // This will fail - column x doesn't exist
+      query_sql: "SELECT x",
       is_private: true,
     });
 
@@ -317,13 +334,18 @@ describe("ExecutionAPI: Errors", () => {
       // Wait a bit for it to fail
       await sleep(3);
 
-      // Get the results - should have an error
-      const result = await fullClient.exec.getExecutionResults(execution.execution_id);
+      // Get the status - should have an error
+      const status = await fullClient.exec.getExecutionStatus(execution.execution_id);
+      expect(status.error).toBeDefined();
+      expect(status.error?.type).toEqual("FAILED_TYPE_EXECUTION_FAILED");
+      expect(status.error?.message).toContain("Column 'x' cannot be resolved");
+      expect(status.state).toEqual(ExecutionState.FAILED);
 
-      // Verify error structure exists
+      // Get the results - should also have an error
+      const result = await fullClient.exec.getExecutionResults(execution.execution_id);
       expect(result.error).toBeDefined();
       expect(result.error?.type).toEqual("FAILED_TYPE_EXECUTION_FAILED");
-      expect(result.error?.message).toContain("x");
+      expect(result.error?.message).toContain("Column 'x' cannot be resolved");
       expect(result.state).toEqual(ExecutionState.FAILED);
     } finally {
       // Cleanup: archive the query even if test fails

tests/e2e/usage.spec.ts

@@ -0,0 +1,49 @@
+import { UsageAPI, DuneError } from "../../src";
+import log from "loglevel";
+
+log.setLevel("silent", true);
+
+const API_KEY = process.env.DUNE_API_KEY!;
+
+describe("UsageAPI", () => {
+  let client: UsageAPI;
+
+  beforeAll(() => {
+    client = new UsageAPI(API_KEY);
+  });
+
+  it("retrieves usage information", async () => {
+    const usage = await client.getUsage();
+
+    expect(usage).toBeDefined();
+    expect(typeof usage.private_queries).toBe("number");
+    expect(typeof usage.private_dashboards).toBe("number");
+    expect(typeof usage.bytes_used).toBe("number");
+    expect(typeof usage.bytes_allowed).toBe("number");
+    expect(Array.isArray(usage.billing_periods)).toBe(true);
+  });
+
+  it("returns valid billing periods structure", async () => {
+    const usage = await client.getUsage();
+
+    if (usage.billing_periods.length > 0) {
+      const period = usage.billing_periods[0];
+      expect(period.start_date).toBeDefined();
+      expect(period.end_date).toBeDefined();
+      expect(typeof period.credits_used).toBe("number");
+      expect(typeof period.credits_included).toBe("number");
+    }
+  });
+
+  it("throws error with invalid API key", async () => {
+    const badClient = new UsageAPI("Invalid_Key");
+
+    try {
+      await badClient.getUsage();
+      expect(false).toBe(true);
+    } catch (error) {
+      expect(error).toBeInstanceOf(DuneError);
+      expect((error as DuneError).message).toContain("401");
+    }
+  });
+});