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

import { APIResource } from '../../core/resource';
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 WorkerPayrollRecords extends APIResource {
  /**
   * A list of worker-payroll-records for a payroll run. Supports filtering by worker
   * via `filter=worker_id in ('<id1>', '<id2>')`.
   *
   * - Requires: `Global Payroll`
   */
  list(
    runID: string,
    query: WorkerPayrollRecordListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<WorkerPayrollRecordListResponsesPageCursorURL, WorkerPayrollRecordListResponse> {
    return this._client.getAPIList(
      path`/payroll-runs/${runID}/worker-payroll-records/`,
      PageCursorURL<WorkerPayrollRecordListResponse>,
      { query, ...options },
    );
  }
}

export type WorkerPayrollRecordListResponsesPageCursorURL = PageCursorURL<WorkerPayrollRecordListResponse>;

/**
 * V2 DTO representing earnings, deductions, taxes, and garnishments
 *     for a single worker in a payroll run.
 *
 *     Used by:
 *       - GET /payroll-runs/{run_id}/worker-payroll-records/      (list)
 *       - GET /payroll-runs/{run_id}/worker-payroll-records/{id}   (retrieve)
 */
export interface WorkerPayrollRecordListResponse {
  /**
   * Unique identifier for this payroll record (PRE version ID).
   */
  id?: string;

  /**
   * ISO country code where this payroll record applies.
   */
  country_code?: string;

  /**
   * ISO currency code for monetary amounts in this record.
   */
  currency?: string;

  /**
   * List of deduction line items.
   */
  deductions?: Array<WorkerPayrollRecordListResponse.Deduction>;

  /**
   * List of earning line items.
   */
  earnings?: Array<WorkerPayrollRecordListResponse.Earning>;

  /**
   * List of garnishment line items.
   */
  garnishments?: Array<WorkerPayrollRecordListResponse.Garnishment>;

  /**
   * Gross pay amount for the current period.
   */
  gross_pay?: string;

  /**
   * Net pay amount for the current period.
   */
  net_pay?: string;

  /**
   * Identifier of the payroll run this record belongs to.
   */
  run_id?: string;

  /**
   * Aggregate totals for taxes, deductions, and garnishments.
   */
  summary?: WorkerPayrollRecordListResponse.Summary;

  /**
   * List of tax line items.
   */
  taxes?: Array<WorkerPayrollRecordListResponse.Tax>;

  /**
   * Identifier of the worker (role ID).
   */
  worker_id?: string;
}

export namespace WorkerPayrollRecordListResponse {
  /**
   * A single deduction line item on a worker's payroll record.
   */
  export interface Deduction {
    /**
     * Code identifying the deduction type.
     */
    deduction_code?: string;

    /**
     * Human-readable name of the deduction.
     */
    display_name?: string;

    /**
     * Employee contribution amount for the current period.
     */
    employee_amount?: string;

    /**
     * Employer contribution amount for the current period.
     */
    employer_amount?: string;
  }

  /**
   * A single earning line item on a worker's payroll record.
   */
  export interface Earning {
    /**
     * Earning amount for the current period.
     */
    amount?: string;

    /**
     * Human-readable name of the earning.
     */
    display_name?: string;

    /**
     * Category of the earning (e.g. SALARY, HOURLY).
     */
    earning_category?: string;

    /**
     * Code identifying the earning type (e.g. regular_salary).
     */
    earning_code?: string;

    /**
     * Hours worked for this earning in the current period.
     */
    hours?: string;

    /**
     * Hourly rate applied to this earning.
     */
    rate?: string;

    /**
     * Time tracking labels associated with this earning.
     */
    time_labels?: Array<string>;
  }

  /**
   * A single garnishment line item on a worker's payroll record.
   */
  export interface Garnishment {
    /**
     * Garnishment amount for the current period.
     */
    amount?: string;

    /**
     * Code identifying the garnishment.
     */
    garnishment_code?: string;
  }

  /**
   * Aggregate totals for taxes, deductions, and garnishments.
   */
  export interface Summary {
    /**
     * Total employee deductions.
     */
    employee_deductions?: string;

    /**
     * Total employee-paid taxes.
     */
    employee_taxes?: string;

    /**
     * Total employer contributions (e.g. retirement matching).
     */
    employer_contributions?: string;

    /**
     * Total employer-paid taxes.
     */
    employer_taxes?: string;

    /**
     * Total garnishments withheld.
     */
    total_garnishments?: string;
  }

  /**
   * A single tax line item on a worker's payroll record.
   */
  export interface Tax {
    /**
     * Tax amount for the current period.
     */
    amount?: string;

    /**
     * Human-readable name of the tax.
     */
    display_name?: string;

    /**
     * Who pays this tax: EMPLOYER or EMPLOYEE.
     */
    paid_by?: string;

    /**
     * Unique code identifying the tax.
     */
    tax_code?: string;
  }
}

export interface WorkerPayrollRecordListParams {
  cursor?: string;

  /**
   * OData-style filter. Only `worker_id in ('<id1>', '<id2>', ...)` is supported.
   */
  filter?: string;
}

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