// 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: `Worker Changes API` * - 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` * * @example HTTP * Representative request and response shapes. * ``` * GET /worker-changes/?filter=filter&expand=expand&order_by=order_by&limit=50&cursor=cursor HTTP/1.1 * Host: rest.ripplingapis.com * Accept: application/json * Rippling-Api-Version: 2024-08-01 * * HTTP/1.1 200 OK * Content-Type: application/json * * { * "__meta": { * "redacted_fields": [ * { * "name": "date_of_birth", * "reason": "Insufficient entitlements" * } * ] * }, * "results": [ * { * "id": "string", * "created_at": "string", * "updated_at": "string", * "referenced_transaction_id": "string", * "worker_id": "string", * "worker": { * "id": "string", * "created_at": "string", * "updated_at": "string", * "user_id": "string", * "user": {}, * "is_manager": "string", * "manager_id": "string", * "manager": {}, * "legal_entity_id": "string", * "legal_entity": {}, * "country": "AF", * "start_date": "string", * "end_date": "string", * "number": "string", * "work_email": "string", * "personal_email": "string", * "status": "INIT", * "location": {}, * "employment_type_id": "string", * "employment_type": {}, * "gender": "MALE", * "date_of_birth": "string", * "race": "BLACK", * "ethnicity": "HISPANIC_OR_LATINO", * "citizenship": "AF", * "compensation_id": "string", * "compensation": {}, * "overtime_exemption": "EXEMPT", * "department_id": "string", * "department": {}, * "teams_id": [], * "teams": [], * "title": "string", * "title_effective_date": "string", * "level_id": "string", * "level": {}, * "job_function_id": "string", * "job_function": {}, * "termination_details": {}, * "pay_schedule_id": "string", * "work_schedule": {}, * "compensation_grade": {}, * "original_start_date": "string", * "custom_fields": [], * "country_fields": {}, * "business_partners_id": [], * "business_partners": [] * }, * "changed_by_id": "string", * "changed_by": { * "id": "string", * "created_at": "string", * "updated_at": "string", * "user_id": "string", * "user": {}, * "is_manager": "string", * "manager_id": "string", * "manager": {}, * "legal_entity_id": "string", * "legal_entity": {}, * "country": "AF", * "start_date": "string", * "end_date": "string", * "number": "string", * "work_email": "string", * "personal_email": "string", * "status": "INIT", * "location": {}, * "employment_type_id": "string", * "employment_type": {}, * "gender": "MALE", * "date_of_birth": "string", * "race": "BLACK", * "ethnicity": "HISPANIC_OR_LATINO", * "citizenship": "AF", * "compensation_id": "string", * "compensation": {}, * "overtime_exemption": "EXEMPT", * "department_id": "string", * "department": {}, * "teams_id": [], * "teams": [], * "title": "string", * "title_effective_date": "string", * "level_id": "string", * "level": {}, * "job_function_id": "string", * "job_function": {}, * "termination_details": {}, * "pay_schedule_id": "string", * "work_schedule": {}, * "compensation_grade": {}, * "original_start_date": "string", * "custom_fields": [], * "country_fields": {}, * "business_partners_id": [], * "business_partners": [] * }, * "applied_on": "string", * "effective_on": "string", * "event_type": "HIRE", * "import_type": "INITIAL", * "reason_code": "string", * "change_note": "string", * "requested_on": "string", * "requested_on_source": "APPROVAL_REQUEST_SUBMITTED", * "changes": [ * {} * ] * } * ], * "next_link": "string" * } * ``` */ list( query: WorkerChangeListParams | null | undefined = {}, options?: RequestOptions, ): PagePromise { return this._client.getAPIList('/worker-changes/', PageCursorURL, { query, ...options, }); } /** * Retrieve a specific worker change * * @example HTTP * Representative request and response shapes. * ``` * GET /worker-changes/{id}/?expand=expand HTTP/1.1 * Host: rest.ripplingapis.com * Accept: application/json * Rippling-Api-Version: 2024-08-01 * * HTTP/1.1 200 OK * Content-Type: application/json * * { * "__meta": { * "redacted_fields": [ * {} * ] * } * } * ``` */ retrieve( id: string, query: WorkerChangeRetrieveParams | null | undefined = {}, options?: RequestOptions, ): APIPromise { return this._client.get(path`/worker-changes/${id}/`, { query, ...options }); } } export type WorkerChangeListResponsesPageCursorURL = PageCursorURL; 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; /** * 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; /** * Free-text explanation of the change, separate from the company-configured * reason_code label. Older records may contain a summary of the change instead of * an author-written note. Null when no explanation or field changes are available, * the caller cannot access the source transition, or access to every underlying * changed field cannot be verified. */ change_note?: 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'; /** * Company-configured transition reason label (e.g. 'Promotion', 'Market * adjustment'). Preserves the configured spelling and capitalization. Populated * only when the company has configured transition reasons and the change went * through a role transition with one selected. Null when the caller cannot access * the source transition, or no reason was recorded. Reason filters match only * labels the caller can access. */ reason_code?: string; /** * For amendments or undos, the id of the worker-change event being modified. */ referenced_transaction_id?: string; /** * Best available request timestamp in UTC. requested_on_source distinguishes * approval submission from request or transition creation time. Null when no * request source is known. Independent of applied_on, which remains the * incremental polling and cursor axis. */ requested_on?: string; /** * Source of requested_on. APPROVAL_REQUEST_SUBMITTED is persisted approval * submission time; TRANSITION_CREATED and SCHEDULED_CHANGE_CREATED are * record-creation proxies, not confirmed submission times. Null when requested_on * is null. */ requested_on_source?: 'APPROVAL_REQUEST_SUBMITTED' | 'TRANSITION_CREATED' | 'SCHEDULED_CHANGE_CREATED'; /** * 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. */ 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. */ 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). Phone extensions and * country-only address changes are preserved. 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; /** * 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; /** * Free-text explanation of the change, separate from the company-configured * reason_code label. Older records may contain a summary of the change instead of * an author-written note. Null when no explanation or field changes are available, * the caller cannot access the source transition, or access to every underlying * changed field cannot be verified. */ change_note?: 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'; /** * Company-configured transition reason label (e.g. 'Promotion', 'Market * adjustment'). Preserves the configured spelling and capitalization. Populated * only when the company has configured transition reasons and the change went * through a role transition with one selected. Null when the caller cannot access * the source transition, or no reason was recorded. Reason filters match only * labels the caller can access. */ reason_code?: string; /** * For amendments or undos, the id of the worker-change event being modified. */ referenced_transaction_id?: string; /** * Best available request timestamp in UTC. requested_on_source distinguishes * approval submission from request or transition creation time. Null when no * request source is known. Independent of applied_on, which remains the * incremental polling and cursor axis. */ requested_on?: string; /** * Source of requested_on. APPROVAL_REQUEST_SUBMITTED is persisted approval * submission time; TRANSITION_CREATED and SCHEDULED_CHANGE_CREATED are * record-creation proxies, not confirmed submission times. Null when requested_on * is null. */ requested_on_source?: 'APPROVAL_REQUEST_SUBMITTED' | 'TRANSITION_CREATED' | 'SCHEDULED_CHANGE_CREATED'; /** * 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. */ 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. */ 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). Phone extensions and * country-only address changes are preserved. 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; /** * The maximum number of results to return. Defaults to 50. Maximum is 100. */ limit?: number; 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, }; }