cloudflare/src/resources/cloudforce-one/threat-events/indicators/by-dataset/by-dataset.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 * as TagsAPI from './tags';
import { BaseTags, TagListParams, TagListResponse, Tags } from './tags';
import { APIPromise } from '../../../../../core/api-promise';
import { RequestOptions } from '../../../../../internal/request-options';
import { path } from '../../../../../internal/utils/path';

export class BaseByDataset extends APIResource {
  static override readonly _key: readonly ['cloudforceOne', 'threatEvents', 'indicators', 'byDataset'] =
    Object.freeze(['cloudforceOne', 'threatEvents', 'indicators', 'byDataset'] as const);

  /**
   * This method is deprecated. Please use /events/indicators to retrieve a paginated
   * list of indicators.
   *
   * @deprecated Use indicators.list instead (GET /accounts/{account_id}/cloudforce-one/events/indicators).
   */
  list(
    datasetID: string,
    params: ByDatasetListParams,
    options?: RequestOptions,
  ): APIPromise<ByDatasetListResponse> {
    const { account_id, ...query } = params;
    return this._client.get(
      path`/accounts/${account_id}/cloudforce-one/events/dataset/${datasetID}/indicators`,
      { query, ...options },
    );
  }

  /**
   * Retrieves a specific indicator by its UUID.
   *
   * @example
   * ```ts
   * const byDataset =
   *   await client.cloudforceOne.threatEvents.indicators.byDataset.get(
   *     'indicator_id',
   *     { account_id: 'account_id', dataset_id: 'dataset_id' },
   *   );
   * ```
   */
  get(
    indicatorID: string,
    params: ByDatasetGetParams,
    options?: RequestOptions,
  ): APIPromise<ByDatasetGetResponse> {
    const { account_id, dataset_id } = params;
    return this._client.get(
      path`/accounts/${account_id}/cloudforce-one/events/dataset/${dataset_id}/indicators/${indicatorID}`,
      options,
    );
  }
}
export class ByDataset extends BaseByDataset {
  tags: TagsAPI.Tags = new TagsAPI.Tags(this._client);
}

export interface ByDatasetListResponse {
  indicators: Array<ByDatasetListResponse.Indicator>;

  pagination: ByDatasetListResponse.Pagination;
}

export namespace ByDatasetListResponse {
  export interface Indicator {
    createdAt: string;

    indicatorType: string;

    /**
     * RSS article sources from which this indicator was extracted.
     */
    sources: Array<Indicator.Source>;

    updatedAt: string;

    uuid: string;

    value: string;

    /**
     * The dataset ID this indicator belongs to. Included in list responses.
     */
    datasetId?: string;

    /**
     * Related events, capped by `relatedEventsLimit` (default 2). Check
     * `relatedEventsHasMore` to detect a capped list; pass `relatedEventsLimit=-1` to
     * retrieve all of them.
     */
    relatedEvents?: Array<Indicator.RelatedEvent>;

    /**
     * True when this indicator appears in more events than `relatedEvents` contains
     * because `relatedEventsLimit` capped the list. Pass `relatedEventsLimit=-1` to
     * retrieve every related event.
     */
    relatedEventsHasMore?: boolean;

    tags?: Array<Indicator.Tag>;

    /**
     * Traffic Light Protocol designation. UPPERCASE. Possible values: CLEAR, GREEN,
     * AMBER, AMBER-STRICT, RED, PURPLE. Null when not set.
     */
    tlp?: string | null;
  }

  export namespace Indicator {
    export interface Source {
      resourceId: string;

      resourceType: 'article';

      system: 'threat-signals';

      /**
       * Threat Signals article title; null for historical provenance without a stored
       * title.
       */
      title: string | null;
    }

    export interface RelatedEvent {
      datasetId: string;

      eventId: string;

      /**
       * ISO 8601 date of the related event. Null for legacy relationships created before
       * event-date tracking was added.
       */
      eventDate?: string | null;
    }

    export interface Tag {
      /**
       * The UUID of the tag category, or null when the tag is uncategorized.
       */
      categoryId?: string | null;

      categoryName?: string;

      uuid?: string;

      value?: string;
    }
  }

  export interface Pagination {
    page: number;

    pageSize: number;

    totalCount: number;

    totalPages: number;
  }
}

export interface ByDatasetGetResponse {
  createdAt: string;

  indicatorType: string;

  updatedAt: string;

  uuid: string;

  value: string;

  /**
   * The dataset ID this indicator belongs to. Included in list responses.
   */
  datasetId?: string;

  /**
   * Related events, capped by `relatedEventsLimit` (default 2). Check
   * `relatedEventsHasMore` to detect a capped list; pass `relatedEventsLimit=-1` to
   * retrieve all of them.
   */
  relatedEvents?: Array<ByDatasetGetResponse.RelatedEvent>;

  /**
   * True when this indicator appears in more events than `relatedEvents` contains
   * because `relatedEventsLimit` capped the list. Pass `relatedEventsLimit=-1` to
   * retrieve every related event.
   */
  relatedEventsHasMore?: boolean;

  tags?: Array<ByDatasetGetResponse.Tag>;

  /**
   * Traffic Light Protocol designation. UPPERCASE. Possible values: CLEAR, GREEN,
   * AMBER, AMBER-STRICT, RED, PURPLE. Null when not set.
   */
  tlp?: string | null;
}

export namespace ByDatasetGetResponse {
  export interface RelatedEvent {
    datasetId: string;

    eventId: string;

    /**
     * ISO 8601 date of the related event. Null for legacy relationships created before
     * event-date tracking was added.
     */
    eventDate?: string | null;
  }

  export interface Tag {
    /**
     * The UUID of the tag category, or null when the tag is uncategorized.
     */
    categoryId?: string | null;

    categoryName?: string;

    uuid?: string;

    value?: string;
  }
}

export interface ByDatasetListParams {
  /**
   * Path param: Account ID.
   */
  account_id: string;

  /**
   * Query param
   */
  indicatorType?: string;

  /**
   * Query param: Filter by indicator value (substring match)
   */
  name?: string;

  /**
   * Query param
   */
  page?: number;

  /**
   * Query param
   */
  pageSize?: number;

  /**
   * Query param: Filter indicators by related event UUID(s). Multiple UUIDs can be
   * provided by repeating the parameter.
   */
  relatedEvent?: Array<string>;
}

export interface ByDatasetGetParams {
  /**
   * Account ID.
   */
  account_id: string;

  /**
   * Dataset ID.
   */
  dataset_id: string;
}

ByDataset.Tags = Tags;
ByDataset.BaseTags = BaseTags;

export declare namespace ByDataset {
  export {
    type ByDatasetListResponse as ByDatasetListResponse,
    type ByDatasetGetResponse as ByDatasetGetResponse,
    type ByDatasetListParams as ByDatasetListParams,
    type ByDatasetGetParams as ByDatasetGetParams,
  };

  export {
    Tags as Tags,
    BaseTags as BaseTags,
    type TagListResponse as TagListResponse,
    type TagListParams as TagListParams,
  };
}