@rippling/rippling-sdk 0.2.0-alpha.95 → 0.2.0-alpha.97

package/src/resources/hires.ts

@@ -0,0 +1,786 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+
+/**
+ * Hiring intent submitted for admin review in Rippling
+ */
+export class Hires extends APIResource {
+  /**
+   * Create or resume hire records for admin review. Idempotency-Key and
+   * requirements_version are required. First milestone is US and CA direct hire.
+   */
+  create(params: HireCreateParams, options?: RequestOptions): APIPromise<HireCreateResponse> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post('/hires/', {
+      body,
+      ...options,
+      headers: buildHeaders([{ 'Idempotency-Key': idempotencyKey }, options?.headers]),
+    });
+  }
+}
+
+export interface HireCreateResponse {
+  /**
+   * True when the envelope was accepted for processing.
+   */
+  ack: boolean;
+
+  /**
+   * One result per request hire, in request order.
+   */
+  results: Array<HireCreateResponse.Result>;
+}
+
+export namespace HireCreateResponse {
+  export interface Result {
+    /**
+     * ready_for_review, incomplete, or failed.
+     */
+    status: string;
+
+    /**
+     * Rippling hire role id when a role exists.
+     */
+    id?: string;
+
+    /**
+     * Echo of the caller-supplied item id.
+     */
+    client_request_id?: string;
+
+    /**
+     * Structured item errors using the same public field paths as GET
+     * /hire-requirements/.
+     */
+    errors?: Array<Result.Error>;
+
+    /**
+     * Matching existing role id for duplicate or rehire conflicts.
+     */
+    existing_role_id?: string;
+
+    /**
+     * Public field paths still required before review.
+     */
+    missing_required_fields?: Array<string>;
+
+    /**
+     * Resolution actions for duplicate or rehire conflicts.
+     */
+    next_actions?: Array<Result.NextAction>;
+
+    /**
+     * Accepted public field paths not yet active because progression is blocked.
+     */
+    pending_fields?: Array<string>;
+  }
+
+  export namespace Result {
+    export interface Error {
+      /**
+       * Machine-readable error code.
+       */
+      code: string;
+
+      /**
+       * Human-readable error message.
+       */
+      message: string;
+
+      /**
+       * Public field path when the error is field-scoped.
+       */
+      field?: string;
+    }
+
+    export interface NextAction {
+      /**
+       * Machine-readable next action.
+       */
+      code: string;
+
+      /**
+       * Role id the caller should continue, when applicable.
+       */
+      target_id?: string;
+    }
+  }
+}
+
+export interface HireCreateParams {
+  /**
+   * Body param: One to five hire submissions. Results are returned in the same
+   * order.
+   */
+  hires: Array<HireCreateParams.Hire>;
+
+  /**
+   * Body param: Requirements version returned by GET /hire-requirements/. Required.
+   */
+  requirements_version: string;
+
+  /**
+   * Header param: Caller-generated key used to deduplicate retried create requests.
+   */
+  'Idempotency-Key': string;
+}
+
+export namespace HireCreateParams {
+  export interface Hire {
+    /**
+     * Compensation intent for the hire.
+     */
+    compensation: Hire.Compensation;
+
+    /**
+     * Employment information for the hire.
+     */
+    employment: Hire.Employment;
+
+    /**
+     * Personal information for the hire.
+     */
+    personal: Hire.Personal;
+
+    /**
+     * Work location for the hire.
+     */
+    work_location: Hire.WorkLocation;
+
+    /**
+     * US additional employment fields such as tips, SOC, and job classification.
+     */
+    additional_employment_fields?: Hire.AdditionalEmploymentFields;
+
+    /**
+     * Caller-supplied correlation id echoed in the response.
+     */
+    client_request_id?: string;
+
+    /**
+     * CA vacation, probation, and notice terms. Required for CA direct hire.
+     */
+    country_job_fields?: Hire.CountryJobFields;
+
+    /**
+     * Optional hiring custom fields.
+     */
+    custom_fields?: Array<Hire.CustomField>;
+
+    /**
+     * Optional rehire, headcount, and ATS correlation context.
+     */
+    hire_context?: Hire.HireContext;
+  }
+
+  export namespace Hire {
+    /**
+     * Compensation intent for the hire.
+     */
+    export interface Compensation {
+      /**
+       * Base pay amount using currency_type and value.
+       */
+      base_pay_amount: Compensation.BasePayAmount;
+
+      /**
+       * Base pay period. One of YEAR, MONTH, WEEK, DAY, or HOUR.
+       */
+      base_pay_period: string;
+
+      /**
+       * Optional commission. When present, on_target_amount is required.
+       */
+      commission?: Compensation.Commission;
+
+      /**
+       * Optional equity grant. When present, amount is required.
+       */
+      equity?: Compensation.Equity;
+
+      /**
+       * Optional relocation reimbursement. When present, amount is required.
+       */
+      relocation?: Compensation.Relocation;
+
+      /**
+       * Optional signing bonus. When present, amount and schedule are required.
+       */
+      signing_bonus?: Compensation.SigningBonus;
+
+      /**
+       * Optional target bonus. When present, provide exactly one of amount or percent.
+       */
+      target_bonus?: Compensation.TargetBonus;
+    }
+
+    export namespace Compensation {
+      /**
+       * Base pay amount using currency_type and value.
+       */
+      export interface BasePayAmount {
+        /**
+         * The currency type, ex: USD, EUR, etc.
+         */
+        currency_type?: string;
+
+        /**
+         * The decimal amount for the currency.
+         */
+        value?: number;
+      }
+
+      /**
+       * Optional commission. When present, on_target_amount is required.
+       */
+      export interface Commission {
+        /**
+         * On-target commission amount.
+         */
+        on_target_amount: Commission.OnTargetAmount;
+
+        /**
+         * How often on-target commission is paid (MONTH, QUARTER, YEAR). Required for CA
+         * direct hire when commission is provided; not collected on US hiring UI.
+         */
+        payment_frequency?: string;
+      }
+
+      export namespace Commission {
+        /**
+         * On-target commission amount.
+         */
+        export interface OnTargetAmount {
+          /**
+           * The currency type, ex: USD, EUR, etc.
+           */
+          currency_type?: string;
+
+          /**
+           * The decimal amount for the currency.
+           */
+          value?: number;
+        }
+      }
+
+      /**
+       * Optional equity grant. When present, amount is required.
+       */
+      export interface Equity {
+        /**
+         * Equity grant amount.
+         */
+        amount: Equity.Amount;
+
+        /**
+         * Optional equity frequency, for example ANNUAL.
+         */
+        frequency?: string;
+
+        /**
+         * Optional number of shares.
+         */
+        num_shares?: number;
+      }
+
+      export namespace Equity {
+        /**
+         * Equity grant amount.
+         */
+        export interface Amount {
+          /**
+           * The currency type, ex: USD, EUR, etc.
+           */
+          currency_type?: string;
+
+          /**
+           * The decimal amount for the currency.
+           */
+          value?: number;
+        }
+      }
+
+      /**
+       * Optional relocation reimbursement. When present, amount is required.
+       */
+      export interface Relocation {
+        /**
+         * Relocation reimbursement amount.
+         */
+        amount: Relocation.Amount;
+      }
+
+      export namespace Relocation {
+        /**
+         * Relocation reimbursement amount.
+         */
+        export interface Amount {
+          /**
+           * The currency type, ex: USD, EUR, etc.
+           */
+          currency_type?: string;
+
+          /**
+           * The decimal amount for the currency.
+           */
+          value?: number;
+        }
+      }
+
+      /**
+       * Optional signing bonus. When present, amount and schedule are required.
+       */
+      export interface SigningBonus {
+        /**
+         * Signing bonus amount.
+         */
+        amount: SigningBonus.Amount;
+
+        /**
+         * When the signing bonus is paid, for example FIRST_PAYROLL.
+         */
+        schedule: string;
+
+        /**
+         * Optional number of days until signing bonus payment.
+         */
+        payment_days?: number;
+      }
+
+      export namespace SigningBonus {
+        /**
+         * Signing bonus amount.
+         */
+        export interface Amount {
+          /**
+           * The currency type, ex: USD, EUR, etc.
+           */
+          currency_type?: string;
+
+          /**
+           * The decimal amount for the currency.
+           */
+          value?: number;
+        }
+      }
+
+      /**
+       * Optional target bonus. When present, provide exactly one of amount or percent.
+       */
+      export interface TargetBonus {
+        /**
+         * Target bonus as a currency amount. Provide exactly one of amount or percent.
+         */
+        amount?: TargetBonus.Amount;
+
+        /**
+         * How often target bonus is paid (MONTH, QUARTER, SEMI_ANNUAL, YEAR). Required for
+         * CA direct hire when target_bonus is provided; not collected on US hiring UI.
+         */
+        payment_frequency?: string;
+
+        /**
+         * Target bonus as a percent string. Provide exactly one of amount or percent.
+         */
+        percent?: string;
+      }
+
+      export namespace TargetBonus {
+        /**
+         * Target bonus as a currency amount. Provide exactly one of amount or percent.
+         */
+        export interface Amount {
+          /**
+           * The currency type, ex: USD, EUR, etc.
+           */
+          currency_type?: string;
+
+          /**
+           * The decimal amount for the currency.
+           */
+          value?: number;
+        }
+      }
+    }
+
+    /**
+     * Employment information for the hire.
+     */
+    export interface Employment {
+      /**
+       * Employment type id from GET /employment-types/.
+       */
+      employment_type_id: string;
+
+      /**
+       * Legal entity id from GET /legal-entities/. Must be an active entity.
+       */
+      legal_entity_id: string;
+
+      /**
+       * Start date in YYYY-MM-DD format.
+       */
+      start_date: string;
+
+      /**
+       * Job title.
+       */
+      title: string;
+
+      /**
+       * Department id from GET /departments/.
+       */
+      department_id?: string;
+
+      /**
+       * Job duties.
+       */
+      duties?: string;
+
+      /**
+       * Optional job classification for the hire.
+       */
+      job_classification?: string;
+
+      /**
+       * Job function id from GET /job-functions/.
+       */
+      job_family_id?: string;
+
+      /**
+       * Level id from GET /levels/.
+       */
+      level_id?: string;
+
+      /**
+       * Manager worker id from GET /workers/.
+       */
+      manager_id?: string;
+
+      /**
+       * Overtime classification for US FLSA and CA direct hire. Public values are exempt
+       * and non-exempt.
+       */
+      overtime_exemption?: string;
+
+      /**
+       * Team ids from GET /teams/.
+       */
+      team_ids?: Array<string>;
+
+      /**
+       * Expected weekly hours as a decimal string (for example 40 or 37.5). Required
+       * when Hiring Flow collects exact weekly hours for the country/employment type.
+       */
+      weekly_hours?: string;
+
+      /**
+       * Hiring-owned weekly hours range when a range is collected instead of an exact
+       * value.
+       */
+      weekly_hours_range?: string;
+
+      /**
+       * Work email for the hire.
+       */
+      work_email?: string;
+
+      /**
+       * Optional work pattern template. Use INLINE with working_hours_schedule for a
+       * custom week.
+       */
+      work_pattern_template?: Employment.WorkPatternTemplate;
+
+      /**
+       * Working hours schedule. Required when the hiring flow collects work patterns.
+       */
+      working_hours_schedule?: Employment.WorkingHoursSchedule;
+    }
+
+    export namespace Employment {
+      /**
+       * Optional work pattern template. Use INLINE with working_hours_schedule for a
+       * custom week.
+       */
+      export interface WorkPatternTemplate {
+        /**
+         * Work pattern template id, for example US or INLINE.
+         */
+        id: string;
+
+        /**
+         * Template client type. GEO_CONFIG, WORK_PATTERN, or INLINE.
+         */
+        client_type: string;
+
+        /**
+         * Optional display name for the template.
+         */
+        readable_name?: string;
+      }
+
+      /**
+       * Working hours schedule. Required when the hiring flow collects work patterns.
+       */
+      export interface WorkingHoursSchedule {
+        /**
+         * Repeating week definition for the schedule.
+         */
+        recurrence: WorkingHoursSchedule.Recurrence;
+
+        /**
+         * IANA time zone for the schedule, for example America/Los_Angeles.
+         */
+        schedule_time_zone: string;
+
+        /**
+         * First day of the expansion cycle. Lowercase weekday, for example sunday.
+         */
+        start_day_of_week: string;
+
+        /**
+         * Optional work-pattern scope. GENERIC or INLINE.
+         */
+        scope_type?: string;
+      }
+
+      export namespace WorkingHoursSchedule {
+        /**
+         * Repeating week definition for the schedule.
+         */
+        export interface Recurrence {
+          /**
+           * One entry per day in the cycle, length times 7, starting at start_day_of_week.
+           */
+          expansion: Array<Recurrence.Expansion>;
+
+          /**
+           * Number of units in the cycle. 1 is a weekly pattern.
+           */
+          length: number;
+
+          /**
+           * Recurrence unit. Must be WEEKS.
+           */
+          unit: string;
+        }
+
+        export namespace Recurrence {
+          export interface Expansion {
+            /**
+             * Day duration as a decimal string, for example 8.00. Omit or null for an off day.
+             */
+            duration?: string;
+
+            /**
+             * End time as HH:MM:SS. Omit or null for an off day.
+             */
+            end_time?: string;
+
+            /**
+             * Start time as HH:MM:SS. Omit or null for an off day.
+             */
+            start_time?: string;
+          }
+        }
+      }
+    }
+
+    /**
+     * Personal information for the hire.
+     */
+    export interface Personal {
+      /**
+       * Legal first name of the hire.
+       */
+      first_name: string;
+
+      /**
+       * Legal last name of the hire.
+       */
+      last_name: string;
+
+      /**
+       * Invite email. Required unless invite_phone is provided.
+       */
+      invite_email?: string;
+
+      /**
+       * Invite phone in E.164. Required unless invite_email is provided.
+       */
+      invite_phone?: string;
+    }
+
+    /**
+     * Work location for the hire.
+     */
+    export interface WorkLocation {
+      /**
+       * ISO 3166-1 alpha-2 country code. Required for on-site and remote. First
+       * milestone accepts US and CA.
+       */
+      country_code: string;
+
+      /**
+       * When true, location_id is omitted.
+       */
+      is_remote?: boolean;
+
+      /**
+       * Work location id from GET /work-locations/. Required unless is_remote is true.
+       */
+      location_id?: string;
+
+      /**
+       * Optional state or region code for a remote work location.
+       */
+      state_code?: string;
+    }
+
+    /**
+     * US additional employment fields such as tips, SOC, and job classification.
+     */
+    export interface AdditionalEmploymentFields {
+      /**
+       * Whether the worker collects tips. US catalog field.
+       */
+      does_worker_collect_tips: boolean;
+
+      /**
+       * US EEOC job classification, for example PROFESSIONALS.
+       */
+      job_classification: string;
+
+      /**
+       * US SOC occupation code in NN-NNNN form, for example 15-1252.
+       */
+      soc_code?: string;
+    }
+
+    /**
+     * CA vacation, probation, and notice terms. Required for CA direct hire.
+     */
+    export interface CountryJobFields {
+      /**
+       * CA employment contract type and optional fixed-term duration. Not collected for
+       * US.
+       */
+      employment_contract: CountryJobFields.EmploymentContract;
+
+      /**
+       * CA notice type: STANDARD_NOTICE or CUSTOM_NOTICE.
+       */
+      notice_type: string;
+
+      /**
+       * CA probation type: STANDARD_PROBATION, SHORTER_PROBATION, or FORGO_PROBATION.
+       */
+      probation_type: string;
+
+      /**
+       * CA vacation type: STATUTORY_VACATION or CUSTOM_VACATION.
+       */
+      vacation_type: string;
+
+      /**
+       * Required when notice_type is CUSTOM_NOTICE.
+       */
+      notice_quantity?: number;
+
+      /**
+       * Required when notice_type is CUSTOM_NOTICE.
+       */
+      notice_unit?: string;
+
+      /**
+       * Required when probation_type is SHORTER_PROBATION.
+       */
+      probation_quantity?: number;
+
+      /**
+       * Required when probation_type is SHORTER_PROBATION.
+       */
+      probation_unit?: string;
+
+      /**
+       * Required when vacation_type is CUSTOM_VACATION.
+       */
+      vacation_days?: number;
+    }
+
+    export namespace CountryJobFields {
+      /**
+       * CA employment contract type and optional fixed-term duration. Not collected for
+       * US.
+       */
+      export interface EmploymentContract {
+        /**
+         * CA employment contract type: FIXED or INDEFINITE.
+         */
+        type: string;
+
+        /**
+         * Fixed-term duration unit when type is FIXED: DAYS, WEEKS, MONTHS, or YEARS.
+         * Required by Hiring Flow for FIXED contracts; omit for INDEFINITE.
+         */
+        duration_unit?: string;
+
+        /**
+         * Fixed-term duration length when type is FIXED. Required by Hiring Flow for FIXED
+         * contracts once duration_unit is set; omit for INDEFINITE.
+         */
+        duration_value?: number;
+      }
+    }
+
+    export interface CustomField {
+      /**
+       * Hiring custom field id.
+       */
+      field_id: string;
+
+      /**
+       * Custom field value.
+       */
+      value: unknown;
+    }
+
+    /**
+     * Optional rehire, headcount, and ATS correlation context.
+     */
+    export interface HireContext {
+      /**
+       * Optional ATS applicant id for correlation.
+       */
+      ats_applicant_id?: string;
+
+      /**
+       * Optional existing in-progress hire role id.
+       */
+      existing_role_id?: string;
+
+      /**
+       * Optional headcount position id (PID) to hire into.
+       */
+      headcount_position_id?: string;
+
+      /**
+       * Required with rehire_role_id. REUSE_EMPLOYEE_DETAILS or NEW_EMPLOYEE_DETAILS.
+       */
+      rehire_choice?: string;
+
+      /**
+       * Prior terminated role id when initiating a rehire.
+       */
+      rehire_role_id?: string;
+    }
+  }
+}
+
+export declare namespace Hires {
+  export { type HireCreateResponse as HireCreateResponse, type HireCreateParams as HireCreateParams };
+}