// 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 { PagePromise, V4PagePaginationArray, type V4PagePaginationArrayParams } from '../../core/pagination';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';

export class BaseScans extends APIResource {
  static override readonly _key: readonly ['vulnerabilityScanner', 'scans'] = Object.freeze([
    'vulnerabilityScanner',
    'scans',
  ] as const);

  /**
   * Creates and starts a new vulnerability scan. The response may include non-fatal
   * warnings in the `messages` array.
   *
   * @example
   * ```ts
   * const scan = await client.vulnerabilityScanner.scans.create(
   *   {
   *     account_id: '023e105f4ecef8ad9ca31a8372d0c353',
   *     credential_sets: {
   *       attacker: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
   *       owner: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
   *     },
   *     open_api: 'open_api',
   *     scan_type: 'bola',
   *     target_environment_id:
   *       '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
   *   },
   * );
   * ```
   */
  create(params: ScanCreateParams, options?: RequestOptions): APIPromise<ScanCreateResponse> {
    const { account_id, ...body } = params;
    return (
      this._client.post(path`/accounts/${account_id}/vuln_scanner/scans`, {
        body,
        ...options,
      }) as APIPromise<{ result: ScanCreateResponse }>
    )._thenUnwrap((obj) => obj.result);
  }

  /**
   * Returns all scans for the account.
   *
   * @example
   * ```ts
   * // Automatically fetches more pages as needed.
   * for await (const scanListResponse of client.vulnerabilityScanner.scans.list(
   *   { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
   * )) {
   *   // ...
   * }
   * ```
   */
  list(
    params: ScanListParams,
    options?: RequestOptions,
  ): PagePromise<ScanListResponsesV4PagePaginationArray, ScanListResponse> {
    const { account_id, ...query } = params;
    return this._client.getAPIList(
      path`/accounts/${account_id}/vuln_scanner/scans`,
      V4PagePaginationArray<ScanListResponse>,
      { query, ...options },
    );
  }

  /**
   * Returns a single scan by ID.
   *
   * @example
   * ```ts
   * const scan = await client.vulnerabilityScanner.scans.get(
   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
   *   { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
   * );
   * ```
   */
  get(scanID: string, params: ScanGetParams, options?: RequestOptions): APIPromise<ScanGetResponse> {
    const { account_id } = params;
    return (
      this._client.get(path`/accounts/${account_id}/vuln_scanner/scans/${scanID}`, options) as APIPromise<{
        result: ScanGetResponse;
      }>
    )._thenUnwrap((obj) => obj.result);
  }
}
export class Scans extends BaseScans {}

export type ScanListResponsesV4PagePaginationArray = V4PagePaginationArray<ScanListResponse>;

export interface ScanCreateResponse {
  /**
   * Scan identifier.
   */
  id: string;

  /**
   * The type of vulnerability scan.
   */
  scan_type: 'bola';

  /**
   * Current lifecycle status of the scan.
   */
  status: 'created' | 'scheduled' | 'planning' | 'running' | 'finished' | 'failed';

  /**
   * The target environment this scan runs against.
   */
  target_environment_id: string;

  /**
   * Vulnerability report produced after the scan completes. The shape depends on the
   * scan type. Present only for finished scans.
   */
  report?: ScanCreateResponse.Report | null;
}

export namespace ScanCreateResponse {
  /**
   * Vulnerability report produced after the scan completes. The shape depends on the
   * scan type. Present only for finished scans.
   */
  export interface Report {
    /**
     * Version 1 of the BOLA vulnerability scan report.
     */
    report: Report.Report;

    /**
     * Version of the report schema.
     */
    report_schema_version: 'v1';
  }

  export namespace Report {
    /**
     * Version 1 of the BOLA vulnerability scan report.
     */
    export interface Report {
      /**
       * Summary of all steps and findings.
       */
      summary: Report.Summary;

      /**
       * List of tests that were run.
       */
      tests: Array<Report.Test>;
    }

    export namespace Report {
      /**
       * Summary of all steps and findings.
       */
      export interface Summary {
        /**
         * Overall verdict of the vulnerability scan.
         */
        verdict: 'ok' | 'warning' | 'inconclusive';
      }

      /**
       * Result of a single test.
       */
      export interface Test {
        /**
         * Steps that were executed.
         */
        steps: Array<Test.Step>;

        /**
         * Verdict of this single test.
         */
        verdict: 'ok' | 'warning' | 'inconclusive';

        /**
         * Errors that prevented step execution.
         */
        preflight_errors?: Array<Test.PreflightError>;
      }

      export namespace Test {
        /**
         * A single step in a test.
         */
        export interface Step {
          /**
           * Assertions that were made against the received response.
           */
          assertions: Array<Step.Assertion>;

          /**
           * Errors the step encountered that may explain absent or incomplete fields.
           */
          errors?: Array<Step.Error>;

          /**
           * HTTP request that was made, if any.
           */
          request?: Step.Request | null;

          /**
           * HTTP response that was received, if any.
           */
          response?: Step.Response | null;
        }

        export namespace Step {
          /**
           * Assertion that was made against the received response.
           */
          export interface Assertion {
            /**
             * Human-readable description of the assertion, explaining what was checked.
             */
            description: string;

            /**
             * Kind of assertion.
             */
            kind: Assertion.Kind;

            /**
             * Observed value on which the assertion was made.
             */
            observed: number | null;

            /**
             * Outcome of the assertion.
             */
            outcome: 'ok' | 'fail' | 'inconclusive';
          }

          export namespace Assertion {
            /**
             * Kind of assertion.
             */
            export interface Kind {
              /**
               * Range of HTTP status codes.
               */
              parameters: Kind.Parameters;

              type: 'http_status_within_range';
            }

            export namespace Kind {
              /**
               * Range of HTTP status codes.
               */
              export interface Parameters {
                /**
                 * Maximum (inclusive) status code of the range.
                 */
                max: number;

                /**
                 * Minimum (inclusive) status code of the range.
                 */
                min: number;
              }
            }
          }

          /**
           * Error that occurred during a test.
           */
          export interface Error {
            /**
             * Human-readable error description.
             */
            description: string;

            /**
             * Numeric error code identifying the class of error, if available.
             */
            error_code?: number | null;
          }

          /**
           * HTTP request that was made, if any.
           */
          export interface Request {
            /**
             * Credential set that was used.
             */
            credential_set: Request.CredentialSet;

            /**
             * Names of headers that were sent.
             */
            header_names: Array<string>;

            /**
             * HTTP method.
             */
            method: 'GET' | 'DELETE' | 'PATCH' | 'POST' | 'PUT';

            /**
             * Exact and full URL (including host, query parameters) that was requested.
             */
            url: string;

            /**
             * Variable captures requested for this step.
             */
            variable_captures: Array<Request.VariableCapture>;

            /**
             * Request body, if any.
             */
            body?: unknown | null;
          }

          export namespace Request {
            /**
             * Credential set that was used.
             */
            export interface CredentialSet {
              /**
               * ID of the credential set.
               */
              id: string;

              /**
               * Role of the credential set.
               */
              role: 'owner' | 'attacker';
            }

            /**
             * A variable to capture from the response body.
             */
            export interface VariableCapture {
              /**
               * JSONPath expression used for capture, e.g. `"$.id"`.
               */
              json_path: string;

              /**
               * Variable name, e.g. `"resource_id"`.
               */
              name: string;
            }
          }

          /**
           * HTTP response that was received, if any.
           */
          export interface Response {
            /**
             * HTTP response body.
             */
            body:
              | Response.VulnScannerBOLABodyResponseNotFound
              | Response.VulnScannerBOLABodyResponseBytes
              | Response.VulnScannerBOLABodyResponseText
              | Response.VulnScannerBOLABodyResponseJson;

            /**
             * Names of headers that were received.
             */
            header_names: Array<string>;

            /**
             * HTTP status code.
             */
            status: number;

            /**
             * HTTP status text, if available for the status code.
             */
            status_text?: string | null;
          }

          export namespace Response {
            /**
             * No body was received.
             */
            export interface VulnScannerBOLABodyResponseNotFound {
              kind: 'not_found';
            }

            /**
             * Body received but unable to read as UTF-8. Raw bytes, base64-encoded.
             */
            export interface VulnScannerBOLABodyResponseBytes {
              contents: string;

              kind: 'bytes';

              truncated: boolean;
            }

            /**
             * Body received as valid UTF-8 text but not valid JSON.
             */
            export interface VulnScannerBOLABodyResponseText {
              contents: string;

              kind: 'text';

              truncated: boolean;
            }

            /**
             * Body received as valid JSON.
             */
            export interface VulnScannerBOLABodyResponseJson {
              contents: string;

              kind: 'json';

              truncated: boolean;
            }
          }
        }

        /**
         * Error that occurred during a test.
         */
        export interface PreflightError {
          /**
           * Human-readable error description.
           */
          description: string;

          /**
           * Numeric error code identifying the class of error, if available.
           */
          error_code?: number | null;
        }
      }
    }
  }
}

export interface ScanListResponse {
  /**
   * Scan identifier.
   */
  id: string;

  /**
   * The type of vulnerability scan.
   */
  scan_type: 'bola';

  /**
   * Current lifecycle status of the scan.
   */
  status: 'created' | 'scheduled' | 'planning' | 'running' | 'finished' | 'failed';

  /**
   * The target environment this scan runs against.
   */
  target_environment_id: string;

  /**
   * Vulnerability report produced after the scan completes. The shape depends on the
   * scan type. Present only for finished scans.
   */
  report?: ScanListResponse.Report | null;
}

export namespace ScanListResponse {
  /**
   * Vulnerability report produced after the scan completes. The shape depends on the
   * scan type. Present only for finished scans.
   */
  export interface Report {
    /**
     * Version 1 of the BOLA vulnerability scan report.
     */
    report: Report.Report;

    /**
     * Version of the report schema.
     */
    report_schema_version: 'v1';
  }

  export namespace Report {
    /**
     * Version 1 of the BOLA vulnerability scan report.
     */
    export interface Report {
      /**
       * Summary of all steps and findings.
       */
      summary: Report.Summary;

      /**
       * List of tests that were run.
       */
      tests: Array<Report.Test>;
    }

    export namespace Report {
      /**
       * Summary of all steps and findings.
       */
      export interface Summary {
        /**
         * Overall verdict of the vulnerability scan.
         */
        verdict: 'ok' | 'warning' | 'inconclusive';
      }

      /**
       * Result of a single test.
       */
      export interface Test {
        /**
         * Steps that were executed.
         */
        steps: Array<Test.Step>;

        /**
         * Verdict of this single test.
         */
        verdict: 'ok' | 'warning' | 'inconclusive';

        /**
         * Errors that prevented step execution.
         */
        preflight_errors?: Array<Test.PreflightError>;
      }

      export namespace Test {
        /**
         * A single step in a test.
         */
        export interface Step {
          /**
           * Assertions that were made against the received response.
           */
          assertions: Array<Step.Assertion>;

          /**
           * Errors the step encountered that may explain absent or incomplete fields.
           */
          errors?: Array<Step.Error>;

          /**
           * HTTP request that was made, if any.
           */
          request?: Step.Request | null;

          /**
           * HTTP response that was received, if any.
           */
          response?: Step.Response | null;
        }

        export namespace Step {
          /**
           * Assertion that was made against the received response.
           */
          export interface Assertion {
            /**
             * Human-readable description of the assertion, explaining what was checked.
             */
            description: string;

            /**
             * Kind of assertion.
             */
            kind: Assertion.Kind;

            /**
             * Observed value on which the assertion was made.
             */
            observed: number | null;

            /**
             * Outcome of the assertion.
             */
            outcome: 'ok' | 'fail' | 'inconclusive';
          }

          export namespace Assertion {
            /**
             * Kind of assertion.
             */
            export interface Kind {
              /**
               * Range of HTTP status codes.
               */
              parameters: Kind.Parameters;

              type: 'http_status_within_range';
            }

            export namespace Kind {
              /**
               * Range of HTTP status codes.
               */
              export interface Parameters {
                /**
                 * Maximum (inclusive) status code of the range.
                 */
                max: number;

                /**
                 * Minimum (inclusive) status code of the range.
                 */
                min: number;
              }
            }
          }

          /**
           * Error that occurred during a test.
           */
          export interface Error {
            /**
             * Human-readable error description.
             */
            description: string;

            /**
             * Numeric error code identifying the class of error, if available.
             */
            error_code?: number | null;
          }

          /**
           * HTTP request that was made, if any.
           */
          export interface Request {
            /**
             * Credential set that was used.
             */
            credential_set: Request.CredentialSet;

            /**
             * Names of headers that were sent.
             */
            header_names: Array<string>;

            /**
             * HTTP method.
             */
            method: 'GET' | 'DELETE' | 'PATCH' | 'POST' | 'PUT';

            /**
             * Exact and full URL (including host, query parameters) that was requested.
             */
            url: string;

            /**
             * Variable captures requested for this step.
             */
            variable_captures: Array<Request.VariableCapture>;

            /**
             * Request body, if any.
             */
            body?: unknown | null;
          }

          export namespace Request {
            /**
             * Credential set that was used.
             */
            export interface CredentialSet {
              /**
               * ID of the credential set.
               */
              id: string;

              /**
               * Role of the credential set.
               */
              role: 'owner' | 'attacker';
            }

            /**
             * A variable to capture from the response body.
             */
            export interface VariableCapture {
              /**
               * JSONPath expression used for capture, e.g. `"$.id"`.
               */
              json_path: string;

              /**
               * Variable name, e.g. `"resource_id"`.
               */
              name: string;
            }
          }

          /**
           * HTTP response that was received, if any.
           */
          export interface Response {
            /**
             * HTTP response body.
             */
            body:
              | Response.VulnScannerBOLABodyResponseNotFound
              | Response.VulnScannerBOLABodyResponseBytes
              | Response.VulnScannerBOLABodyResponseText
              | Response.VulnScannerBOLABodyResponseJson;

            /**
             * Names of headers that were received.
             */
            header_names: Array<string>;

            /**
             * HTTP status code.
             */
            status: number;

            /**
             * HTTP status text, if available for the status code.
             */
            status_text?: string | null;
          }

          export namespace Response {
            /**
             * No body was received.
             */
            export interface VulnScannerBOLABodyResponseNotFound {
              kind: 'not_found';
            }

            /**
             * Body received but unable to read as UTF-8. Raw bytes, base64-encoded.
             */
            export interface VulnScannerBOLABodyResponseBytes {
              contents: string;

              kind: 'bytes';

              truncated: boolean;
            }

            /**
             * Body received as valid UTF-8 text but not valid JSON.
             */
            export interface VulnScannerBOLABodyResponseText {
              contents: string;

              kind: 'text';

              truncated: boolean;
            }

            /**
             * Body received as valid JSON.
             */
            export interface VulnScannerBOLABodyResponseJson {
              contents: string;

              kind: 'json';

              truncated: boolean;
            }
          }
        }

        /**
         * Error that occurred during a test.
         */
        export interface PreflightError {
          /**
           * Human-readable error description.
           */
          description: string;

          /**
           * Numeric error code identifying the class of error, if available.
           */
          error_code?: number | null;
        }
      }
    }
  }
}

export interface ScanGetResponse {
  /**
   * Scan identifier.
   */
  id: string;

  /**
   * The type of vulnerability scan.
   */
  scan_type: 'bola';

  /**
   * Current lifecycle status of the scan.
   */
  status: 'created' | 'scheduled' | 'planning' | 'running' | 'finished' | 'failed';

  /**
   * The target environment this scan runs against.
   */
  target_environment_id: string;

  /**
   * Vulnerability report produced after the scan completes. The shape depends on the
   * scan type. Present only for finished scans.
   */
  report?: ScanGetResponse.Report | null;
}

export namespace ScanGetResponse {
  /**
   * Vulnerability report produced after the scan completes. The shape depends on the
   * scan type. Present only for finished scans.
   */
  export interface Report {
    /**
     * Version 1 of the BOLA vulnerability scan report.
     */
    report: Report.Report;

    /**
     * Version of the report schema.
     */
    report_schema_version: 'v1';
  }

  export namespace Report {
    /**
     * Version 1 of the BOLA vulnerability scan report.
     */
    export interface Report {
      /**
       * Summary of all steps and findings.
       */
      summary: Report.Summary;

      /**
       * List of tests that were run.
       */
      tests: Array<Report.Test>;
    }

    export namespace Report {
      /**
       * Summary of all steps and findings.
       */
      export interface Summary {
        /**
         * Overall verdict of the vulnerability scan.
         */
        verdict: 'ok' | 'warning' | 'inconclusive';
      }

      /**
       * Result of a single test.
       */
      export interface Test {
        /**
         * Steps that were executed.
         */
        steps: Array<Test.Step>;

        /**
         * Verdict of this single test.
         */
        verdict: 'ok' | 'warning' | 'inconclusive';

        /**
         * Errors that prevented step execution.
         */
        preflight_errors?: Array<Test.PreflightError>;
      }

      export namespace Test {
        /**
         * A single step in a test.
         */
        export interface Step {
          /**
           * Assertions that were made against the received response.
           */
          assertions: Array<Step.Assertion>;

          /**
           * Errors the step encountered that may explain absent or incomplete fields.
           */
          errors?: Array<Step.Error>;

          /**
           * HTTP request that was made, if any.
           */
          request?: Step.Request | null;

          /**
           * HTTP response that was received, if any.
           */
          response?: Step.Response | null;
        }

        export namespace Step {
          /**
           * Assertion that was made against the received response.
           */
          export interface Assertion {
            /**
             * Human-readable description of the assertion, explaining what was checked.
             */
            description: string;

            /**
             * Kind of assertion.
             */
            kind: Assertion.Kind;

            /**
             * Observed value on which the assertion was made.
             */
            observed: number | null;

            /**
             * Outcome of the assertion.
             */
            outcome: 'ok' | 'fail' | 'inconclusive';
          }

          export namespace Assertion {
            /**
             * Kind of assertion.
             */
            export interface Kind {
              /**
               * Range of HTTP status codes.
               */
              parameters: Kind.Parameters;

              type: 'http_status_within_range';
            }

            export namespace Kind {
              /**
               * Range of HTTP status codes.
               */
              export interface Parameters {
                /**
                 * Maximum (inclusive) status code of the range.
                 */
                max: number;

                /**
                 * Minimum (inclusive) status code of the range.
                 */
                min: number;
              }
            }
          }

          /**
           * Error that occurred during a test.
           */
          export interface Error {
            /**
             * Human-readable error description.
             */
            description: string;

            /**
             * Numeric error code identifying the class of error, if available.
             */
            error_code?: number | null;
          }

          /**
           * HTTP request that was made, if any.
           */
          export interface Request {
            /**
             * Credential set that was used.
             */
            credential_set: Request.CredentialSet;

            /**
             * Names of headers that were sent.
             */
            header_names: Array<string>;

            /**
             * HTTP method.
             */
            method: 'GET' | 'DELETE' | 'PATCH' | 'POST' | 'PUT';

            /**
             * Exact and full URL (including host, query parameters) that was requested.
             */
            url: string;

            /**
             * Variable captures requested for this step.
             */
            variable_captures: Array<Request.VariableCapture>;

            /**
             * Request body, if any.
             */
            body?: unknown | null;
          }

          export namespace Request {
            /**
             * Credential set that was used.
             */
            export interface CredentialSet {
              /**
               * ID of the credential set.
               */
              id: string;

              /**
               * Role of the credential set.
               */
              role: 'owner' | 'attacker';
            }

            /**
             * A variable to capture from the response body.
             */
            export interface VariableCapture {
              /**
               * JSONPath expression used for capture, e.g. `"$.id"`.
               */
              json_path: string;

              /**
               * Variable name, e.g. `"resource_id"`.
               */
              name: string;
            }
          }

          /**
           * HTTP response that was received, if any.
           */
          export interface Response {
            /**
             * HTTP response body.
             */
            body:
              | Response.VulnScannerBOLABodyResponseNotFound
              | Response.VulnScannerBOLABodyResponseBytes
              | Response.VulnScannerBOLABodyResponseText
              | Response.VulnScannerBOLABodyResponseJson;

            /**
             * Names of headers that were received.
             */
            header_names: Array<string>;

            /**
             * HTTP status code.
             */
            status: number;

            /**
             * HTTP status text, if available for the status code.
             */
            status_text?: string | null;
          }

          export namespace Response {
            /**
             * No body was received.
             */
            export interface VulnScannerBOLABodyResponseNotFound {
              kind: 'not_found';
            }

            /**
             * Body received but unable to read as UTF-8. Raw bytes, base64-encoded.
             */
            export interface VulnScannerBOLABodyResponseBytes {
              contents: string;

              kind: 'bytes';

              truncated: boolean;
            }

            /**
             * Body received as valid UTF-8 text but not valid JSON.
             */
            export interface VulnScannerBOLABodyResponseText {
              contents: string;

              kind: 'text';

              truncated: boolean;
            }

            /**
             * Body received as valid JSON.
             */
            export interface VulnScannerBOLABodyResponseJson {
              contents: string;

              kind: 'json';

              truncated: boolean;
            }
          }
        }

        /**
         * Error that occurred during a test.
         */
        export interface PreflightError {
          /**
           * Human-readable error description.
           */
          description: string;

          /**
           * Numeric error code identifying the class of error, if available.
           */
          error_code?: number | null;
        }
      }
    }
  }
}

export interface ScanCreateParams {
  /**
   * Path param: Account identifier.
   */
  account_id: string;

  /**
   * Body param: Credential set references for a BOLA scan. The scanner uses the
   * `owner` credentials for legitimate requests and the `attacker` credentials to
   * attempt unauthorized access.
   */
  credential_sets: ScanCreateParams.CredentialSets;

  /**
   * Body param: OpenAPI schema definition for the API under test. The scanner uses
   * this to discover endpoints and construct requests.
   */
  open_api: string;

  /**
   * Body param
   */
  scan_type: 'bola';

  /**
   * Body param: The target environment to scan.
   */
  target_environment_id: string;
}

export namespace ScanCreateParams {
  /**
   * Credential set references for a BOLA scan. The scanner uses the `owner`
   * credentials for legitimate requests and the `attacker` credentials to attempt
   * unauthorized access.
   */
  export interface CredentialSets {
    /**
     * Credential set ID for the attacker.
     */
    attacker: string;

    /**
     * Credential set ID for the resource owner.
     */
    owner: string;
  }
}

export interface ScanListParams extends V4PagePaginationArrayParams {
  /**
   * Path param: Account identifier.
   */
  account_id: string;
}

export interface ScanGetParams {
  /**
   * Account identifier.
   */
  account_id: string;
}

export declare namespace Scans {
  export {
    type ScanCreateResponse as ScanCreateResponse,
    type ScanListResponse as ScanListResponse,
    type ScanGetResponse as ScanGetResponse,
    type ScanListResponsesV4PagePaginationArray as ScanListResponsesV4PagePaginationArray,
    type ScanCreateParams as ScanCreateParams,
    type ScanListParams as ScanListParams,
    type ScanGetParams as ScanGetParams,
  };
}