// 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 WorkersAPI from './workers';
import { APIPromise } from '../core/api-promise';
import { PageCursorURL, PagePromise } from '../core/pagination';
import { RequestOptions } from '../internal/request-options';
import { path } from '../internal/utils/path';

/**
 * Historical changes to worker data over time
 */
export class WorkerChanges extends APIResource {
  /**
   * A list of worker changes.
   *
   * - Requires: `API Tier 2`
   * - Filterable fields: `worker_id`, `applied_on`, `effective_on`, `changed_by_id`,
   *   `reason_code`, `field_key`, `event_type`
   * - Expandable fields: `worker`, `changed_by`
   * - Sortable fields: `id`, `created_at`, `updated_at`, `applied_on`,
   *   `effective_on`
   */
  list(
    query: WorkerChangeListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<WorkerChangeListResponsesPageCursorURL, WorkerChangeListResponse> {
    return this._client.getAPIList('/worker-changes/', PageCursorURL<WorkerChangeListResponse>, {
      query,
      ...options,
    });
  }

  /**
   * Retrieve a specific worker change
   */
  retrieve(
    id: string,
    query: WorkerChangeRetrieveParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<WorkerChangeRetrieveResponse> {
    return this._client.get(path`/worker-changes/${id}/`, { query, ...options });
  }
}

export type WorkerChangeListResponsesPageCursorURL = PageCursorURL<WorkerChangeListResponse>;

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

  /**
   * When the change was persisted (approval time for changes that went through an
   * approval workflow). UTC. Monotonically increasing as new commits land; use as
   * the cursor axis for incremental polling.
   */
  applied_on: string;

  /**
   * Field-level changes captured by this event. Per-field REDACTED entries appear
   * for fields the caller cannot read so consumers can detect that a change occurred
   * even when the value is hidden. Events where every changed field is invisible to
   * the caller — either internal fields not exposed via the public Object Graph, or
   * fields the caller's role has zero read permission on — are dropped from the
   * response entirely (they never appear with an all-REDACTED changes array).
   */
  changes: Array<WorkerChangeListResponse.Change>;

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

  /**
   * When the change is true in the business domain. Can be past, present, or future.
   * Independent of applied_on. UTC.
   */
  effective_on: string;

  /**
   * The lifecycle event type this change represents. CHANGE is the catch-all for
   * non-lifecycle field edits.
   */
  event_type:
    | 'HIRE'
    | 'CHANGE'
    | 'SCHEDULED_CHANGE'
    | 'OFFBOARD'
    | 'SCHEDULED_OFFBOARD'
    | 'IMPORT'
    | 'UNDO'
    | 'EFFECTIVE_DATE_AMENDMENT';

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

  /**
   * The worker affected by this change.
   */
  worker_id: string;

  /**
   * The actor as the current Worker DTO. Returned only when expand=changed_by is
   * requested.
   *
   * Expandable field
   */
  changed_by?: WorkersAPI.Worker;

  /**
   * Actor who made the change. Null for system-initiated events.
   */
  changed_by_id?: string;

  /**
   * INITIAL (census import at company onboarding) or HISTORICAL (historical data
   * imported later). Set only when event_type is IMPORT.
   */
  import_type?: 'INITIAL' | 'HISTORICAL';

  /**
   * Structured transition reason (e.g. 'PROMOTION', 'MARKET_ADJUSTMENT'). Populated
   * only when the company has configured transition reasons and the change went
   * through a role transition with one selected. Null for most companies and events.
   */
  reason_code?: string;

  /**
   * For amendments or undos, the id of the worker-change event being modified.
   */
  referenced_transaction_id?: string;

  /**
   * The affected worker as the current Worker DTO. Returned only when expand=worker
   * is requested. Includes terminated employees.
   *
   * Expandable field
   */
  worker?: WorkersAPI.Worker;
}

export namespace WorkerChangeListResponse {
  export interface Change {
    /**
     * VISIBLE or REDACTED. REDACTED means the caller's role lacks permission to read
     * this field; from_value/to_value are null but the entry still appears so
     * consumers know a change occurred.
     */
    display_type: 'VISIBLE' | 'REDACTED';

    /**
     * UI label for the field (English).
     */
    field_display_name: string;

    /**
     * Field key in snake_case (see GET /worker-change-fields for the valid set).
     */
    field_key: string;

    /**
     * The underlying value type of this field. Populated regardless of display_type so
     * consumers can interpret from_value / to_value (or anticipate a future typed
     * representation) without a separate lookup against GET /worker-change-fields.
     */
    value_type: 'STRING' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'DATETIME' | 'CURRENCY' | 'ENUM' | 'REFERENCE';

    /**
     * Value before the change, rendered as a display string (locale- and
     * currency-formatted per the activity-log convention). Null when display_type is
     * REDACTED. Typed JSON values are tracked as a future addition; consult value_type
     * to interpret the rendering.
     */
    from_value?: string;

    /**
     * Value after the change, rendered as a display string. Null when display_type is
     * REDACTED. See from_value for notes on typed-value plans.
     */
    to_value?: string;
  }
}

/**
 * Meta information for the response.
 */
export interface WorkerChangeRetrieveResponse extends BusinessPartnersAPI.Meta {
  /**
   * Identifier field
   */
  id: string;

  /**
   * When the change was persisted (approval time for changes that went through an
   * approval workflow). UTC. Monotonically increasing as new commits land; use as
   * the cursor axis for incremental polling.
   */
  applied_on: string;

  /**
   * Field-level changes captured by this event. Per-field REDACTED entries appear
   * for fields the caller cannot read so consumers can detect that a change occurred
   * even when the value is hidden. Events where every changed field is invisible to
   * the caller — either internal fields not exposed via the public Object Graph, or
   * fields the caller's role has zero read permission on — are dropped from the
   * response entirely (they never appear with an all-REDACTED changes array).
   */
  changes: Array<WorkerChangeRetrieveResponse.Change>;

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

  /**
   * When the change is true in the business domain. Can be past, present, or future.
   * Independent of applied_on. UTC.
   */
  effective_on: string;

  /**
   * The lifecycle event type this change represents. CHANGE is the catch-all for
   * non-lifecycle field edits.
   */
  event_type:
    | 'HIRE'
    | 'CHANGE'
    | 'SCHEDULED_CHANGE'
    | 'OFFBOARD'
    | 'SCHEDULED_OFFBOARD'
    | 'IMPORT'
    | 'UNDO'
    | 'EFFECTIVE_DATE_AMENDMENT';

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

  /**
   * The worker affected by this change.
   */
  worker_id: string;

  /**
   * The actor as the current Worker DTO. Returned only when expand=changed_by is
   * requested.
   *
   * Expandable field
   */
  changed_by?: WorkersAPI.Worker;

  /**
   * Actor who made the change. Null for system-initiated events.
   */
  changed_by_id?: string;

  /**
   * INITIAL (census import at company onboarding) or HISTORICAL (historical data
   * imported later). Set only when event_type is IMPORT.
   */
  import_type?: 'INITIAL' | 'HISTORICAL';

  /**
   * Structured transition reason (e.g. 'PROMOTION', 'MARKET_ADJUSTMENT'). Populated
   * only when the company has configured transition reasons and the change went
   * through a role transition with one selected. Null for most companies and events.
   */
  reason_code?: string;

  /**
   * For amendments or undos, the id of the worker-change event being modified.
   */
  referenced_transaction_id?: string;

  /**
   * The affected worker as the current Worker DTO. Returned only when expand=worker
   * is requested. Includes terminated employees.
   *
   * Expandable field
   */
  worker?: WorkersAPI.Worker;
}

export namespace WorkerChangeRetrieveResponse {
  export interface Change {
    /**
     * VISIBLE or REDACTED. REDACTED means the caller's role lacks permission to read
     * this field; from_value/to_value are null but the entry still appears so
     * consumers know a change occurred.
     */
    display_type: 'VISIBLE' | 'REDACTED';

    /**
     * UI label for the field (English).
     */
    field_display_name: string;

    /**
     * Field key in snake_case (see GET /worker-change-fields for the valid set).
     */
    field_key: string;

    /**
     * The underlying value type of this field. Populated regardless of display_type so
     * consumers can interpret from_value / to_value (or anticipate a future typed
     * representation) without a separate lookup against GET /worker-change-fields.
     */
    value_type: 'STRING' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'DATETIME' | 'CURRENCY' | 'ENUM' | 'REFERENCE';

    /**
     * Value before the change, rendered as a display string (locale- and
     * currency-formatted per the activity-log convention). Null when display_type is
     * REDACTED. Typed JSON values are tracked as a future addition; consult value_type
     * to interpret the rendering.
     */
    from_value?: string;

    /**
     * Value after the change, rendered as a display string. Null when display_type is
     * REDACTED. See from_value for notes on typed-value plans.
     */
    to_value?: string;
  }
}

export interface WorkerChangeListParams {
  cursor?: string;

  expand?: string;

  filter?: string;

  order_by?: string;
}

export interface WorkerChangeRetrieveParams {
  expand?: string;
}

export declare namespace WorkerChanges {
  export {
    type WorkerChangeListResponse as WorkerChangeListResponse,
    type WorkerChangeRetrieveResponse as WorkerChangeRetrieveResponse,
    type WorkerChangeListResponsesPageCursorURL as WorkerChangeListResponsesPageCursorURL,
    type WorkerChangeListParams as WorkerChangeListParams,
    type WorkerChangeRetrieveParams as WorkerChangeRetrieveParams,
  };
}