// 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 * as WorkerPayrollRecordsAPI from './worker-payroll-records';
import {
  WorkerPayrollRecordListParams,
  WorkerPayrollRecordListResponse,
  WorkerPayrollRecordListResponsesPageCursorURL,
  WorkerPayrollRecords,
} from './worker-payroll-records';
import { APIPromise } from '../../core/api-promise';
import { PageCursorURL, PagePromise } from '../../core/pagination';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';

/**
 * Payroll runs for the company
 */
export class PayrollRuns extends APIResource {
  workerPayrollRecords: WorkerPayrollRecordsAPI.WorkerPayrollRecords =
    new WorkerPayrollRecordsAPI.WorkerPayrollRecords(this._client);

  /**
   * A list of payroll-runs.
   *
   * - Requires: `Global Payroll`
   * - Sortable fields: `check_date`
   */
  list(
    query: PayrollRunListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<PayrollRunListResponsesPageCursorURL, PayrollRunListResponse> {
    return this._client.getAPIList('/payroll-runs/', PageCursorURL<PayrollRunListResponse>, {
      query,
      ...options,
    });
  }

  /**
   * Retrieve a specific payroll-run
   */
  retrieve(id: string, options?: RequestOptions): APIPromise<PayrollRunRetrieveResponse> {
    return this._client.get(path`/payroll-runs/${id}/`, options);
  }
}

export type PayrollRunListResponsesPageCursorURL = PageCursorURL<PayrollRunListResponse>;

/**
 * V2 DTO representing a single payroll run.
 *
 *     Used by:
 *       - GET /payroll-runs/      (list)
 *       - GET /payroll-runs/{id}  (retrieve)
 */
export interface PayrollRunListResponse {
  /**
   * Unique identifier for the payroll run.
   */
  id?: string;

  /**
   * Deadline for approving the payroll run.
   */
  approval_deadline?: string;

  /**
   * Timestamp when the run was approved.
   */
  approved_at?: string;

  /**
   * Date the paycheck is issued.
   */
  check_date?: string;

  /**
   * Identifier linking this payroll run to the company's legal entity in the HRIS
   * system.
   */
  company_entity_id?: string;

  /**
   * ISO country code where the payroll run applies.
   */
  country_code?: string;

  /**
   * Date funds are debited from the company's account.
   */
  debit_date?: string;

  /**
   * Deadline after which the run is locked for changes.
   */
  lock_deadline?: string;

  /**
   * Timestamp when the run was marked as paid.
   */
  paid_at?: string;

  /**
   * Pay period details for this run.
   */
  pay_period?: PayrollRunListResponse.PayPeriod;

  /**
   * Payment method used (e.g. WIRE, ACH).
   */
  payment_type?: string;

  /**
   * Current state of the run (e.g. DRAFT, PAID, APPROVED).
   */
  run_state?: string;

  /**
   * Type of the run (e.g. REGULAR, OFF_CYCLE, CORRECTION).
   */
  run_type?: string;

  /**
   * Human-readable title of the payroll run.
   */
  title?: string;
}

export namespace PayrollRunListResponse {
  /**
   * Pay period details for this run.
   */
  export interface PayPeriod {
    /**
     * End date of the pay period.
     */
    end_date?: string;

    /**
     * Pay frequency for this period (e.g. BI_WEEKLY, SEMI_MONTHLY, MONTHLY, WEEKLY).
     */
    pay_frequency?: string;

    /**
     * Start date of the pay period.
     */
    start_date?: string;
  }
}

/**
 * Meta information for the response.
 */
export interface PayrollRunRetrieveResponse extends BusinessPartnersAPI.Meta {
  /**
   * Unique identifier for the payroll run.
   */
  id?: string;

  /**
   * Deadline for approving the payroll run.
   */
  approval_deadline?: string;

  /**
   * Timestamp when the run was approved.
   */
  approved_at?: string;

  /**
   * Date the paycheck is issued.
   */
  check_date?: string;

  /**
   * Identifier linking this payroll run to the company's legal entity in the HRIS
   * system.
   */
  company_entity_id?: string;

  /**
   * ISO country code where the payroll run applies.
   */
  country_code?: string;

  /**
   * Date funds are debited from the company's account.
   */
  debit_date?: string;

  /**
   * Deadline after which the run is locked for changes.
   */
  lock_deadline?: string;

  /**
   * Timestamp when the run was marked as paid.
   */
  paid_at?: string;

  /**
   * Pay period details for this run.
   */
  pay_period?: PayrollRunRetrieveResponse.PayPeriod;

  /**
   * Payment method used (e.g. WIRE, ACH).
   */
  payment_type?: string;

  /**
   * Current state of the run (e.g. DRAFT, PAID, APPROVED).
   */
  run_state?: string;

  /**
   * Type of the run (e.g. REGULAR, OFF_CYCLE, CORRECTION).
   */
  run_type?: string;

  /**
   * Human-readable title of the payroll run.
   */
  title?: string;
}

export namespace PayrollRunRetrieveResponse {
  /**
   * Pay period details for this run.
   */
  export interface PayPeriod {
    /**
     * End date of the pay period.
     */
    end_date?: string;

    /**
     * Pay frequency for this period (e.g. BI_WEEKLY, SEMI_MONTHLY, MONTHLY, WEEKLY).
     */
    pay_frequency?: string;

    /**
     * Start date of the pay period.
     */
    start_date?: string;
  }
}

export interface PayrollRunListParams {
  order_by?: string;
}

PayrollRuns.WorkerPayrollRecords = WorkerPayrollRecords;

export declare namespace PayrollRuns {
  export {
    type PayrollRunListResponse as PayrollRunListResponse,
    type PayrollRunRetrieveResponse as PayrollRunRetrieveResponse,
    type PayrollRunListResponsesPageCursorURL as PayrollRunListResponsesPageCursorURL,
    type PayrollRunListParams as PayrollRunListParams,
  };

  export {
    WorkerPayrollRecords as WorkerPayrollRecords,
    type WorkerPayrollRecordListResponse as WorkerPayrollRecordListResponse,
    type WorkerPayrollRecordListResponsesPageCursorURL as WorkerPayrollRecordListResponsesPageCursorURL,
    type WorkerPayrollRecordListParams as WorkerPayrollRecordListParams,
  };
}