cloudflare/src/resources/intel/domains/bulks.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 { RequestOptions } from '../../../internal/request-options';
import { path } from '../../../internal/utils/path';

export class BaseBulks extends APIResource {
  static override readonly _key: readonly ['intel', 'domains', 'bulks'] = Object.freeze([
    'intel',
    'domains',
    'bulks',
  ] as const);

  /**
   * Returns security details and statistics about multiple domains in a single
   * request.
   *
   * **Behavior change — domain ranking is becoming opt-in.** This endpoint
   * previously included domain ranking data in every response and accepted a
   * `skip_ranking=true` query parameter to opt out. That parameter is being
   * deprecated and ranking will no longer be returned by default. Callers that want
   * ranking data must pass `include_ranking=true`. The `skip_ranking` parameter will
   * be silently ignored once the change ships.
   *
   * @example
   * ```ts
   * const bulks = await client.intel.domains.bulks.get({
   *   account_id: '023e105f4ecef8ad9ca31a8372d0c353',
   * });
   * ```
   */
  get(params: BulkGetParams, options?: RequestOptions): APIPromise<BulkGetResponse | null> {
    const { account_id, ...query } = params;
    return (
      this._client.get(path`/accounts/${account_id}/intel/domain/bulk`, { query, ...options }) as APIPromise<{
        result: BulkGetResponse | null;
      }>
    )._thenUnwrap((obj) => obj.result);
  }
}
export class Bulks extends BaseBulks {}

export type BulkGetResponse = Array<BulkGetResponse.BulkGetResponseItem>;

export namespace BulkGetResponse {
  export interface BulkGetResponseItem {
    /**
     * Additional information related to the host name.
     */
    additional_information?: BulkGetResponseItem.AdditionalInformation;

    /**
     * Application that the hostname belongs to.
     */
    application?: BulkGetResponseItem.Application;

    content_categories?: Array<BulkGetResponseItem.ContentCategory>;

    domain?: string;

    inherited_content_categories?: Array<BulkGetResponseItem.InheritedContentCategory>;

    /**
     * Domain from which `inherited_content_categories` and `inherited_risk_types` are
     * inherited, if applicable.
     */
    inherited_from?: string;

    inherited_risk_types?: Array<BulkGetResponseItem.InheritedRiskType>;

    /**
     * Global Cloudflare 100k ranking for the last 30 days, if available for the
     * hostname. The top ranked domain is 1, the lowest ranked domain is 100,000.
     */
    popularity_rank?: number;

    /**
     * Hostname risk score, which is a value between 0 (lowest risk) to 1 (highest
     * risk).
     */
    risk_score?: number;

    risk_types?: Array<BulkGetResponseItem.RiskType>;
  }

  export namespace BulkGetResponseItem {
    /**
     * Additional information related to the host name.
     */
    export interface AdditionalInformation {
      /**
       * Suspected DGA malware family.
       */
      suspected_malware_family?: string;
    }

    /**
     * Application that the hostname belongs to.
     */
    export interface Application {
      id?: number;

      name?: string;
    }

    /**
     * Current content categories.
     */
    export interface ContentCategory {
      id?: number;

      name?: string;

      super_category_id?: number;
    }

    export interface InheritedContentCategory {
      id?: number;

      name?: string;

      super_category_id?: number;
    }

    export interface InheritedRiskType {
      id?: number;

      name?: string;

      super_category_id?: number;
    }

    export interface RiskType {
      id?: number;

      name?: string;

      super_category_id?: number;
    }
  }
}

export interface BulkGetParams {
  /**
   * Path param: Identifier.
   */
  account_id: string;

  /**
   * Query param: Accepts multiple values like
   * `?domain=cloudflare.com&domain=example.com`.
   */
  domain?: Array<string>;

  /**
   * Query param: Whether to include domain ranking data in the response. Defaults to
   * `false` — ranking lookups are expensive at bulk scale and most callers do not
   * need them. Set to `true` to opt in. This parameter replaces the deprecated
   * `skip_ranking` (see below).
   */
  include_ranking?: boolean;

  /**
   * Query param: **Deprecated.** Previously controlled whether the ranking lookup
   * was skipped (defaulted to `false`, meaning ranking ran). The endpoint's default
   * behavior is being flipped — ranking is now opt-in via `include_ranking=true` —
   * and this parameter will be silently ignored. Remove it from your callers and use
   * `include_ranking` instead.
   */
  skip_ranking?: boolean;
}

export declare namespace Bulks {
  export { type BulkGetResponse as BulkGetResponse, type BulkGetParams as BulkGetParams };
}