cloudflare/src/resources/radar/datasets.ts

The official TypeScript library for the Cloudflare API

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../core/resource';
import { APIPromise } from '../../core/api-promise';
import { buildHeaders } from '../../internal/headers';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';

export class BaseDatasets extends APIResource {
  static override readonly _key: readonly ['radar', 'datasets'] = Object.freeze([
    'radar',
    'datasets',
  ] as const);

  /**
   * Retrieves a list of datasets.
   *
   * @example
   * ```ts
   * const datasets = await client.radar.datasets.list();
   * ```
   */
  list(
    query: DatasetListParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<DatasetListResponse> {
    return (
      this._client.get('/radar/datasets', { query, ...options }) as APIPromise<{
        result: DatasetListResponse;
      }>
    )._thenUnwrap((obj) => obj.result);
  }

  /**
   * Retrieves an URL to download a single dataset.
   *
   * @example
   * ```ts
   * const response = await client.radar.datasets.download({
   *   datasetId: 3,
   * });
   * ```
   */
  download(params: DatasetDownloadParams, options?: RequestOptions): APIPromise<DatasetDownloadResponse> {
    const { format, ...body } = params;
    return (
      this._client.post('/radar/datasets/download', { query: { format }, body, ...options }) as APIPromise<{
        result: DatasetDownloadResponse;
      }>
    )._thenUnwrap((obj) => obj.result);
  }

  /**
   * Retrieves the CSV content of a given dataset by alias or ID. When getting the
   * content by alias the latest dataset is returned, optionally filtered by the
   * latest available at a given date.
   *
   * @example
   * ```ts
   * const dataset = await client.radar.datasets.get(
   *   'ranking_top_1000',
   * );
   * ```
   */
  get(alias: string, options?: RequestOptions): APIPromise<string> {
    return this._client.get(path`/radar/datasets/${alias}`, {
      ...options,
      headers: buildHeaders([{ Accept: 'text/csv' }, options?.headers]),
    });
  }
}
export class Datasets extends BaseDatasets {}

export interface DatasetListResponse {
  datasets: Array<DatasetListResponse.Dataset>;
}

export namespace DatasetListResponse {
  export interface Dataset {
    id: number;

    description: string;

    meta: unknown;

    tags: Array<string>;

    title: string;

    type: string;
  }
}

export interface DatasetDownloadResponse {
  dataset: DatasetDownloadResponse.Dataset;
}

export namespace DatasetDownloadResponse {
  export interface Dataset {
    url: string;
  }
}

export type DatasetGetResponse = string;

export interface DatasetListParams {
  /**
   * Filters results by dataset type.
   */
  datasetType?: 'RANKING_BUCKET' | 'REPORT';

  /**
   * Filters results by the specified date.
   */
  date?: string;

  /**
   * Format in which results will be returned.
   */
  format?: 'JSON' | 'CSV';

  /**
   * Limits the number of objects returned in the response.
   */
  limit?: number;

  /**
   * Skips the specified number of objects before fetching the results.
   */
  offset?: number;
}

export interface DatasetDownloadParams {
  /**
   * Body param
   */
  datasetId: number;

  /**
   * Query param: Format in which results will be returned.
   */
  format?: 'JSON' | 'CSV';
}

export declare namespace Datasets {
  export {
    type DatasetListResponse as DatasetListResponse,
    type DatasetDownloadResponse as DatasetDownloadResponse,
    type DatasetGetResponse as DatasetGetResponse,
    type DatasetListParams as DatasetListParams,
    type DatasetDownloadParams as DatasetDownloadParams,
  };
}