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

import { APIResource } from '../core/resource';
import * as BusinessPartnersAPI from './business-partners';
import { APIPromise } from '../core/api-promise';
import { RequestOptions } from '../internal/request-options';
import { path } from '../internal/utils/path';

/**
 * Report data for company
 */
export class ReportRuns extends APIResource {
  /**
   * Trigger a new report run
   */
  create(body: ReportRunCreateParams, options?: RequestOptions): APIPromise<ReportRunCreateResponse> {
    return this._client.post('/report-runs/', { body, ...options });
  }

  /**
   * Retrieve the status and data for a specific report run
   */
  retrieve(runID: string, options?: RequestOptions): APIPromise<ReportRunRetrieveResponse> {
    return this._client.get(path`/report-runs/${runID}/`, options);
  }
}

export interface ReportRunCreateResponse {
  /**
   * The ID of this run
   */
  id: string;

  /**
   * The ID of the report associated with this run
   */
  report_id: string;

  /**
   * Report run status
   */
  status: 'IN_PROGRESS' | 'SUCCESS' | 'FAILURE';

  /**
   * Report data, available once the run is complete
   */
  result?: ReportRunCreateResponse.Result;
}

export namespace ReportRunCreateResponse {
  /**
   * Report data, available once the run is complete
   */
  export interface Result {
    /**
     * The expiry time of the execution
     */
    expires_at: string;

    /**
     * The presigned file url
     */
    file_url: string;

    /**
     * The type of the output file
     */
    output_type: 'JSON' | 'CSV';
  }
}

/**
 * Meta information for the response.
 */
export interface ReportRunRetrieveResponse extends BusinessPartnersAPI.Meta {
  /**
   * The ID of this run
   */
  id: string;

  /**
   * The ID of the report associated with this run
   */
  report_id: string;

  /**
   * Report run status
   */
  status: 'IN_PROGRESS' | 'SUCCESS' | 'FAILURE';

  /**
   * Report data, available once the run is complete
   */
  result?: ReportRunRetrieveResponse.Result;
}

export namespace ReportRunRetrieveResponse {
  /**
   * Report data, available once the run is complete
   */
  export interface Result {
    /**
     * The expiry time of the execution
     */
    expires_at: string;

    /**
     * The presigned file url
     */
    file_url: string;

    /**
     * The type of the output file
     */
    output_type: 'JSON' | 'CSV';
  }
}

export interface ReportRunCreateParams {
  /**
   * The ID of the report to run
   */
  report_id: string;

  /**
   * Optional list of filters to apply when running the report
   */
  filters?: Array<ReportRunCreateParams.Filter> | null;

  /**
   * Formatting options for currency fields
   */
  format_currency_fields?: ReportRunCreateParams.FormatCurrencyFields | null;

  /**
   * Formatting options for date fields
   */
  format_date_fields?: ReportRunCreateParams.FormatDateFields | null;

  /**
   * Whether to include object IDs in the report output
   */
  include_object_ids?: boolean;

  /**
   * Whether to include total row count in the report output
   */
  include_total_rows?: boolean;

  /**
   * Output format for the report data
   */
  output_type?: 'JSON' | 'CSV';

  /**
   * Controls whose permissions are used when running the report. VIEWER (default)
   * uses the API token owner's own permissions. OWNER uses the report owner's
   * permissions (requires owner-level access to the report).
   */
  view_as?: 'VIEWER' | 'OWNER';
}

export namespace ReportRunCreateParams {
  /**
   * A single filter to apply when running a report. The expected shape of 'value'
   * depends on the operator — see the FilterOperator description for details.
   */
  export interface Filter {
    /**
     * The ID of the report field to filter on
     */
    field_id: string;

    /**
     * Comparison operator for the filter. Single-value operators (EQ, NE, GT, GTE, LT,
     * LTE, STARTS_WITH, ENDS_WITH, CONTAINS, NOT_CONTAINS, BEFORE, AFTER) require a
     * scalar value. List operators (IN, NOT_IN) require a non-empty array. Range
     * operators (BETWEEN, NOT_BETWEEN) require an object with 'from' and 'to' keys.
     * No-value operators (IS_EMPTY, IS_NOT_EMPTY) do not require a value. Rolling-date
     * operators (LAST_N, NEXT_N) require an object with 'unit' (DAY, WEEK, MONTH,
     * YEAR) and 'n' (integer). Calendar-date operators (CURRENT_CALENDAR,
     * PREVIOUS_CALENDAR) require a unit string (DAY, WEEK, MONTH, QUARTER, YEAR).
     */
    operator:
      | 'EQ'
      | 'NE'
      | 'IN'
      | 'NOT_IN'
      | 'STARTS_WITH'
      | 'ENDS_WITH'
      | 'CONTAINS'
      | 'NOT_CONTAINS'
      | 'GT'
      | 'GTE'
      | 'LT'
      | 'LTE'
      | 'BETWEEN'
      | 'NOT_BETWEEN'
      | 'IS_EMPTY'
      | 'IS_NOT_EMPTY'
      | 'BEFORE'
      | 'AFTER'
      | 'LAST_N'
      | 'NEXT_N'
      | 'CURRENT_CALENDAR'
      | 'PREVIOUS_CALENDAR';

    /**
     * The filter value. Shape depends on the operator: scalar for single-value
     * operators; array for list operators; RangeValue object ({from, to}) for range
     * operators; RollingDateValue object ({unit, n}) for rolling-date operators; unit
     * string for calendar-date operators; omitted or null for IS_EMPTY/IS_NOT_EMPTY.
     */
    value?: string | number | boolean | Array<unknown> | Filter.RangeValue | Filter.RollingDateValue | null;
  }

  export namespace Filter {
    /**
     * Range bounds for 'between' and 'not_between' operators
     */
    export interface RangeValue {
      /**
       * Lower bound of the range (inclusive)
       */
      from: number | string;

      /**
       * Upper bound of the range (inclusive)
       */
      to: number | string;
    }

    /**
     * Rolling date window for 'last_n' and 'next_n' operators
     */
    export interface RollingDateValue {
      /**
       * Number of units
       */
      n: number;

      /**
       * Unit of time for rolling/calendar date filters
       */
      unit: 'DAY' | 'WEEK' | 'MONTH' | 'QUARTER' | 'YEAR';
    }
  }

  /**
   * Formatting options for currency fields
   */
  export interface FormatCurrencyFields {
    /**
     * Currency column format for currency fields
     */
    columns: 'TYPE_AND_AMOUNT' | 'VALUE_ONLY';

    /**
     * Currency type (e.g., 'USD')
     */
    currency_type?: string | null;
  }

  /**
   * Formatting options for date fields
   */
  export interface FormatDateFields {
    /**
     * Date format for date fields in the report output
     */
    date_format: 'ISO_8601' | 'APPLY_VISUALIZATION_SETTINGS';

    /**
     * Timezone for datetime fields (e.g., 'America/Los_Angeles')
     */
    datetime_timezone?: string | null;
  }
}

export declare namespace ReportRuns {
  export {
    type ReportRunCreateResponse as ReportRunCreateResponse,
    type ReportRunRetrieveResponse as ReportRunRetrieveResponse,
    type ReportRunCreateParams as ReportRunCreateParams,
  };
}