// 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 DepartmentsAPI from './departments';
import * as JobAssignmentsAPI from './job-assignments';
import { AttributeChangeDetailsPageCursorURL } from './job-assignments';
import * as JobDimensionsAPI from './job-dimensions';
import * as JobPayRateExceptionsAPI from './job-pay-rate-exceptions';
import * as Shared from './shared';
import * as WorkLocationsAPI from './work-locations';
import { APIPromise } from '../core/api-promise';
import { PageCursorURL, PagePromise } from '../core/pagination';
import { buildHeaders } from '../internal/headers';
import { RequestOptions } from '../internal/request-options';
import { path } from '../internal/utils/path';

/**
 * Job related information for the company
 */
export class JobCodes extends APIResource {
  /**
   * A list of job codes.
   *
   * - Requires: `API Tier 2`
   * - Filterable fields: `job_dimension_id`, `group_id`
   * - Expandable fields: `job_dimension`, `work_location`, `department`,
   *   `pay_rate_exceptions`
   * - Sortable fields: `id`, `created_at`, `updated_at`
   */
  list(
    query: JobCodeListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<JobCodesPageCursorURL, JobCode> {
    return this._client.getAPIList('/job-codes/', PageCursorURL<JobCode>, { query, ...options });
  }

  /**
   * Create a new job code
   */
  create(body: JobCodeCreateParams, options?: RequestOptions): APIPromise<JobCode> {
    return this._client.post('/job-codes/', { body, ...options });
  }

  /**
   * Retrieve a specific job code
   */
  retrieve(
    id: string,
    query: JobCodeRetrieveParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<JobCodeRetrieveResponse> {
    return this._client.get(path`/job-codes/${id}/`, { query, ...options });
  }

  /**
   * Update a specific job code.
   */
  update(id: string, body: JobCodeUpdateParams, options?: RequestOptions): APIPromise<JobCode> {
    return this._client.patch(path`/job-codes/${id}/`, { body, ...options });
  }

  /**
   * Delete a job code
   */
  delete(id: string, options?: RequestOptions): APIPromise<void> {
    return this._client.delete(path`/job-codes/${id}/`, {
      ...options,
      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
    });
  }

  /**
   * A list of attribute change logs.
   *
   * - Requires: `API Tier 2`
   * - Expandable fields: `changed_by_worker`
   * - Sortable fields: `id`
   */
  listChangeLog(
    jobCodeID: string,
    query: JobCodeListChangeLogParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<AttributeChangeDetailsPageCursorURL, JobAssignmentsAPI.AttributeChangeDetails> {
    return this._client.getAPIList(
      path`/job-codes/${jobCodeID}/change-log/`,
      PageCursorURL<JobAssignmentsAPI.AttributeChangeDetails>,
      { query, ...options },
    );
  }
}

export type JobCodesPageCursorURL = PageCursorURL<JobCode>;

export interface JobCode {
  /**
   * Identifier field
   */
  id: string;

  /**
   * Record creation date
   */
  created_at: string;

  /**
   * The ID of the job dimension this job code belongs to.
   */
  job_dimension_id: string;

  /**
   * The name of the job dimension.
   */
  name: string;

  /**
   * Record update date
   */
  updated_at: string;

  /**
   * The custom location of the job code. This location will be used for tax
   * calculation purposes if using US Payroll when an employee is working at this job
   * code.
   */
  custom_location?: JobCode.CustomLocation;

  /**
   * The department associated with the job code.
   *
   * Expandable field
   */
  department?: DepartmentsAPI.Department;

  /**
   * The department associated with the job code.
   */
  department_id?: string;

  /**
   * The unique identifier of the job code in an outside system.
   */
  external_id?: string;

  /**
   * The ID of the job roster group.
   */
  group_id?: string;

  /**
   * Whether this job code is archived. Set to true via PATCH to archive. Archiving
   * is irreversible via this API.
   */
  is_archived?: boolean;

  /**
   * The job dimension this job code belongs to.
   *
   * Expandable field
   */
  job_dimension?: JobDimensionsAPI.JobDimension;

  /**
   * The pay rate for this job code. Only applicable if the associated job dimension
   * includes the 'PAY_RATE' organizational attribute.
   */
  pay_rate?: number;

  /**
   * Pay rate overrides for the job based on exception dimension values.
   *
   * Expandable field
   */
  pay_rate_exceptions?: Array<JobPayRateExceptionsAPI.JobPayRateException>;

  /**
   * Pay rate overrides id for the job based on exception dimension values.
   */
  pay_rate_exceptions_id?: Array<string>;

  /**
   * The work location associated with the job code.
   *
   * Expandable field
   */
  work_location?: WorkLocationsAPI.WorkLocation;

  /**
   * The work location associated with the job code.
   */
  work_location_id?: string;
}

export namespace JobCode {
  /**
   * The custom location of the job code. This location will be used for tax
   * calculation purposes if using US Payroll when an employee is working at this job
   * code.
   */
  export interface CustomLocation {
    /**
     * The address of the custom location.
     */
    address: Shared.Address;
  }
}

export interface JobCodeRequest {
  /**
   * The ID of the job dimension this job code belongs to.
   */
  job_dimension_id: string;

  /**
   * The name of the job dimension.
   */
  name: string;

  /**
   * The custom location of the job code. This location will be used for tax
   * calculation purposes if using US Payroll when an employee is working at this job
   * code.
   */
  custom_location?: JobCodeRequest.CustomLocation;

  /**
   * The unique identifier of the job code in an outside system.
   */
  external_id?: string;

  /**
   * Whether this job code is archived. Set to true via PATCH to archive. Archiving
   * is irreversible via this API.
   */
  is_archived?: boolean;

  /**
   * The pay rate for this job code. Only applicable if the associated job dimension
   * includes the 'PAY_RATE' organizational attribute.
   */
  pay_rate?: number;

  /**
   * Reason for setting, updating, or resetting the pay rate on this job code.
   */
  pay_rate_change_reason?: string;

  /**
   * Date and time the pay rate becomes effective (ISO 8601 format
   * YYYY-MM-DDTHH:mm:ss.sssZ, e.g., 2025-11-07T17:00:00.000+00:00); defaults to
   * current time in UTC if not provided.
   */
  pay_rate_effective_from?: string;
}

export namespace JobCodeRequest {
  /**
   * The custom location of the job code. This location will be used for tax
   * calculation purposes if using US Payroll when an employee is working at this job
   * code.
   */
  export interface CustomLocation {
    /**
     * The address of the custom location.
     */
    address: CustomLocation.Address;
  }

  export namespace CustomLocation {
    /**
     * The address of the custom location.
     */
    export interface Address {
      /**
       * The country component, pursuant to SCIM RFC 7643 4.1.2.
       */
      country?: Shared.CountryCode;

      /**
       * The city or locality component.
       */
      locality?: string;

      /**
       * The zip code or postal code component, pursuant to SCIM RFC 7643 4.1.2.
       */
      postal_code?: string;

      /**
       * The state or region component, pursuant to SCIM RFC 7643 4.1.2.
       */
      region?: string;

      /**
       * The full street address component, which may include house number, street name,
       * P.O. box, and multi-line extended street address information, pursuant to SCIM
       * RFC 7643 4.1.2..
       */
      street_address?: string;

      /**
       * The classification of the address.
       */
      type?: 'HOME' | 'WORK' | 'OTHER';
    }
  }
}

/**
 * Meta information for the response.
 */
export interface JobCodeRetrieveResponse extends BusinessPartnersAPI.Meta, JobCode {}

export interface JobCodeListParams {
  cursor?: string;

  expand?: string;

  filter?: string;

  order_by?: string;
}

export interface JobCodeCreateParams {
  /**
   * The ID of the job dimension this job code belongs to.
   */
  job_dimension_id: string;

  /**
   * The name of the job dimension.
   */
  name: string;

  /**
   * The custom location of the job code. This location will be used for tax
   * calculation purposes if using US Payroll when an employee is working at this job
   * code.
   */
  custom_location?: JobCodeCreateParams.CustomLocation;

  /**
   * The unique identifier of the job code in an outside system.
   */
  external_id?: string;

  /**
   * Whether this job code is archived. Set to true via PATCH to archive. Archiving
   * is irreversible via this API.
   */
  is_archived?: boolean;

  /**
   * The pay rate for this job code. Only applicable if the associated job dimension
   * includes the 'PAY_RATE' organizational attribute.
   */
  pay_rate?: number;

  /**
   * Reason for setting, updating, or resetting the pay rate on this job code.
   */
  pay_rate_change_reason?: string;

  /**
   * Date and time the pay rate becomes effective (ISO 8601 format
   * YYYY-MM-DDTHH:mm:ss.sssZ, e.g., 2025-11-07T17:00:00.000+00:00); defaults to
   * current time in UTC if not provided.
   */
  pay_rate_effective_from?: string;
}

export namespace JobCodeCreateParams {
  /**
   * The custom location of the job code. This location will be used for tax
   * calculation purposes if using US Payroll when an employee is working at this job
   * code.
   */
  export interface CustomLocation {
    /**
     * The address of the custom location.
     */
    address: CustomLocation.Address;
  }

  export namespace CustomLocation {
    /**
     * The address of the custom location.
     */
    export interface Address {
      /**
       * The country component, pursuant to SCIM RFC 7643 4.1.2.
       */
      country?: Shared.CountryCode;

      /**
       * The city or locality component.
       */
      locality?: string;

      /**
       * The zip code or postal code component, pursuant to SCIM RFC 7643 4.1.2.
       */
      postal_code?: string;

      /**
       * The state or region component, pursuant to SCIM RFC 7643 4.1.2.
       */
      region?: string;

      /**
       * The full street address component, which may include house number, street name,
       * P.O. box, and multi-line extended street address information, pursuant to SCIM
       * RFC 7643 4.1.2..
       */
      street_address?: string;

      /**
       * The classification of the address.
       */
      type?: 'HOME' | 'WORK' | 'OTHER';
    }
  }
}

export interface JobCodeRetrieveParams {
  expand?: string;
}

export interface JobCodeUpdateParams {
  /**
   * The ID of the job dimension this job code belongs to.
   */
  job_dimension_id: string;

  /**
   * The name of the job dimension.
   */
  name: string;

  /**
   * The custom location of the job code. This location will be used for tax
   * calculation purposes if using US Payroll when an employee is working at this job
   * code.
   */
  custom_location?: JobCodeUpdateParams.CustomLocation;

  /**
   * The unique identifier of the job code in an outside system.
   */
  external_id?: string;

  /**
   * Whether this job code is archived. Set to true via PATCH to archive. Archiving
   * is irreversible via this API.
   */
  is_archived?: boolean;

  /**
   * The pay rate for this job code. Only applicable if the associated job dimension
   * includes the 'PAY_RATE' organizational attribute.
   */
  pay_rate?: number;

  /**
   * Reason for setting, updating, or resetting the pay rate on this job code.
   */
  pay_rate_change_reason?: string;

  /**
   * Date and time the pay rate becomes effective (ISO 8601 format
   * YYYY-MM-DDTHH:mm:ss.sssZ, e.g., 2025-11-07T17:00:00.000+00:00); defaults to
   * current time in UTC if not provided.
   */
  pay_rate_effective_from?: string;
}

export namespace JobCodeUpdateParams {
  /**
   * The custom location of the job code. This location will be used for tax
   * calculation purposes if using US Payroll when an employee is working at this job
   * code.
   */
  export interface CustomLocation {
    /**
     * The address of the custom location.
     */
    address: CustomLocation.Address;
  }

  export namespace CustomLocation {
    /**
     * The address of the custom location.
     */
    export interface Address {
      /**
       * The country component, pursuant to SCIM RFC 7643 4.1.2.
       */
      country?: Shared.CountryCode;

      /**
       * The city or locality component.
       */
      locality?: string;

      /**
       * The zip code or postal code component, pursuant to SCIM RFC 7643 4.1.2.
       */
      postal_code?: string;

      /**
       * The state or region component, pursuant to SCIM RFC 7643 4.1.2.
       */
      region?: string;

      /**
       * The full street address component, which may include house number, street name,
       * P.O. box, and multi-line extended street address information, pursuant to SCIM
       * RFC 7643 4.1.2..
       */
      street_address?: string;

      /**
       * The classification of the address.
       */
      type?: 'HOME' | 'WORK' | 'OTHER';
    }
  }
}

export interface JobCodeListChangeLogParams {
  cursor?: string;

  expand?: string;

  order_by?: string;
}

export declare namespace JobCodes {
  export {
    type JobCode as JobCode,
    type JobCodeRequest as JobCodeRequest,
    type JobCodeRetrieveResponse as JobCodeRetrieveResponse,
    type JobCodesPageCursorURL as JobCodesPageCursorURL,
    type JobCodeListParams as JobCodeListParams,
    type JobCodeCreateParams as JobCodeCreateParams,
    type JobCodeRetrieveParams as JobCodeRetrieveParams,
    type JobCodeUpdateParams as JobCodeUpdateParams,
    type JobCodeListChangeLogParams as JobCodeListChangeLogParams,
  };
}

export { type AttributeChangeDetailsPageCursorURL };