@rippling/rippling-sdk 0.2.0-alpha.100

package/src/resources/leave-program-evaluations.ts

@@ -0,0 +1,737 @@
+// 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 { RequestOptions } from '../internal/request-options';
+
+/**
+ * Leave program evaluations produced by the leave rules engine
+ */
+export class LeaveProgramEvaluations extends APIResource {
+  /**
+   * Evaluate leave programs for an employee leave request.
+   */
+  create(
+    body: LeaveProgramEvaluationCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<LeaveProgramEvaluationCreateResponse> {
+    return this._client.post('/leave-program-evaluations/', { body, ...options });
+  }
+}
+
+export interface LeaveProgramEvaluationCreateResponse {
+  /**
+   * Combined leave plan derived from all non-ineligible program results. Join
+   * program_results by program_code for eligibility, pay rates, and gaps;
+   * program_contributions carry placement windows only.
+   */
+  leave_plan: LeaveProgramEvaluationCreateResponse.LeavePlan;
+
+  /**
+   * Structured evidence gaps reported by evaluated eligibility rules.
+   */
+  missing_evidence: Array<LeaveProgramEvaluationCreateResponse.MissingEvidence>;
+
+  /**
+   * Per-program rule outputs in evaluation order.
+   */
+  program_results: Array<LeaveProgramEvaluationCreateResponse.ProgramResult>;
+}
+
+export namespace LeaveProgramEvaluationCreateResponse {
+  /**
+   * Combined leave plan derived from all non-ineligible program results. Join
+   * program_results by program_code for eligibility, pay rates, and gaps;
+   * program_contributions carry placement windows only.
+   */
+  export interface LeavePlan {
+    /**
+     * Flattened balance adjustment directives from payable program results.
+     */
+    balance_adjustments: Array<LeavePlan.BalanceAdjustment>;
+
+    /**
+     * Requested leave start date used for this plan.
+     */
+    claim_start_date: string;
+
+    /**
+     * Contiguous spans where the same program set overlaps.
+     */
+    coverage_segments: Array<LeavePlan.CoverageSegment>;
+
+    /**
+     * Flattened payroll earning directives from payable program results.
+     */
+    earnings: Array<LeavePlan.Earning>;
+
+    /**
+     * Estimated per-paycheck amounts when claim_end_date and pay schedule are known.
+     */
+    pay_periods: Array<LeavePlan.PayPeriod>;
+
+    /**
+     * Per-program placement windows on the claim.
+     */
+    program_contributions: Array<LeavePlan.ProgramContribution>;
+
+    /**
+     * Requested leave end date used for this plan, if provided.
+     */
+    claim_end_date?: string;
+
+    /**
+     * Merged bookable leave request directive, if any.
+     */
+    leave_request?: LeavePlan.LeaveRequest;
+  }
+
+  export namespace LeavePlan {
+    export interface BalanceAdjustment {
+      /**
+       * Adjustment amount serialized as a decimal string.
+       */
+      amount: string;
+
+      /**
+       * Leave type to adjust if applying the evaluation.
+       */
+      leave_type: string;
+
+      /**
+       * Unit for the adjustment amount, such as WEEKS, DAYS, or HOURS.
+       */
+      unit: string;
+
+      /**
+       * Accrual type to use when applying the adjustment.
+       */
+      accrual_type?: string;
+    }
+
+    export interface CoverageSegment {
+      /**
+       * Programs active over this segment.
+       */
+      program_codes: Array<string>;
+
+      /**
+       * Segment start date.
+       */
+      start_date: string;
+
+      /**
+       * Segment end date, if known.
+       */
+      end_date?: string;
+    }
+
+    export interface Earning {
+      /**
+       * Earning amount serialized as a decimal string.
+       */
+      amount: string;
+
+      /**
+       * Earning type to use if booking a payroll earning from the evaluation.
+       */
+      earning_type: string;
+
+      /**
+       * ISO 4217 currency code for the earning amount.
+       */
+      currency?: string;
+
+      /**
+       * Number of benefit weeks represented by this earning, serialized as a decimal
+       * string.
+       */
+      weeks?: string;
+    }
+
+    export interface PayPeriod {
+      /**
+       * Estimated program-level pay slices in this pay period.
+       */
+      contributions: Array<PayPeriod.Contribution>;
+
+      /**
+       * Estimated pay period end date.
+       */
+      period_end: string;
+
+      /**
+       * Estimated pay period start date.
+       */
+      period_start: string;
+
+      /**
+       * Total estimated carrier-paid amount in this pay period.
+       */
+      carrier_total?: PayPeriod.CarrierTotal;
+
+      /**
+       * Total estimated employer-paid amount in this pay period.
+       */
+      employer_total?: PayPeriod.EmployerTotal;
+
+      /**
+       * Total estimated government-paid amount in this pay period.
+       */
+      government_total?: PayPeriod.GovernmentTotal;
+
+      /**
+       * Total estimated amount in this pay period.
+       */
+      total?: PayPeriod.Total;
+    }
+
+    export namespace PayPeriod {
+      export interface Contribution {
+        /**
+         * Estimated amount for this program slice.
+         */
+        amount: Contribution.Amount;
+
+        /**
+         * Who pays the employee for this program slice.
+         */
+        pay_source: 'GOVERNMENT' | 'CARRIER' | 'EMPLOYER';
+
+        /**
+         * Program contributing pay in this pay period.
+         */
+        program_code: string;
+      }
+
+      export namespace Contribution {
+        /**
+         * Estimated amount for this program slice.
+         */
+        export interface Amount {
+          /**
+           * Decimal monetary amount serialized as a string.
+           */
+          amount: string;
+
+          /**
+           * ISO 4217 currency code for the amount.
+           */
+          currency: string;
+        }
+      }
+
+      /**
+       * Total estimated carrier-paid amount in this pay period.
+       */
+      export interface CarrierTotal {
+        /**
+         * Decimal monetary amount serialized as a string.
+         */
+        amount: string;
+
+        /**
+         * ISO 4217 currency code for the amount.
+         */
+        currency: string;
+      }
+
+      /**
+       * Total estimated employer-paid amount in this pay period.
+       */
+      export interface EmployerTotal {
+        /**
+         * Decimal monetary amount serialized as a string.
+         */
+        amount: string;
+
+        /**
+         * ISO 4217 currency code for the amount.
+         */
+        currency: string;
+      }
+
+      /**
+       * Total estimated government-paid amount in this pay period.
+       */
+      export interface GovernmentTotal {
+        /**
+         * Decimal monetary amount serialized as a string.
+         */
+        amount: string;
+
+        /**
+         * ISO 4217 currency code for the amount.
+         */
+        currency: string;
+      }
+
+      /**
+       * Total estimated amount in this pay period.
+       */
+      export interface Total {
+        /**
+         * Decimal monetary amount serialized as a string.
+         */
+        amount: string;
+
+        /**
+         * ISO 4217 currency code for the amount.
+         */
+        currency: string;
+      }
+    }
+
+    export interface ProgramContribution {
+      /**
+       * Whether this program has an estimated pay rate.
+       */
+      pay_status: 'NOT_APPLICABLE' | 'ESTIMATED';
+
+      /**
+       * Leave program code active on this claim window.
+       */
+      program_code: string;
+
+      /**
+       * Program placement start date.
+       */
+      start_date: string;
+
+      /**
+       * Program placement end date, if known.
+       */
+      end_date?: string;
+
+      /**
+       * Leave type associated with this program placement.
+       */
+      leave_type?: string;
+
+      /**
+       * Human-readable leave type label.
+       */
+      leave_type_label?: string;
+    }
+
+    /**
+     * Merged bookable leave request directive, if any.
+     */
+    export interface LeaveRequest {
+      /**
+       * Leave type to use if booking a leave request from the evaluation.
+       */
+      leave_type: string;
+
+      /**
+       * Recommended leave request start date.
+       */
+      start_date: string;
+
+      /**
+       * Recommended leave request end date, if known.
+       */
+      end_date?: string;
+
+      /**
+       * Optional leave request status to use when booking.
+       */
+      status?: string;
+    }
+  }
+
+  export interface MissingEvidence {
+    /**
+     * Expected answer type for this evidence key.
+     */
+    answer_type: string;
+
+    /**
+     * Stable evidence key that can be supplied in supplemental_evidence.
+     */
+    key: string;
+
+    /**
+     * Human-readable label for the missing evidence.
+     */
+    label: string;
+
+    /**
+     * Leave program codes that reported this missing evidence.
+     */
+    program_codes: Array<string>;
+  }
+
+  export interface ProgramResult {
+    /**
+     * Derived eligibility status for this program.
+     */
+    eligibility: 'eligible' | 'ineligible' | 'partially_eligible';
+
+    /**
+     * UNKNOWN evidence keys to fix before eligibility can be fully resolved.
+     */
+    gaps: Array<string>;
+
+    /**
+     * Whether the result is eligible and not blocked by payment-blocking requirements.
+     */
+    is_payable: boolean;
+
+    /**
+     * Leave program code evaluated by the rules engine.
+     */
+    program_code: string;
+
+    /**
+     * Eligibility and assumption validations run for this program.
+     */
+    program_validations: Array<ProgramResult.ProgramValidation>;
+
+    /**
+     * Legacy explanatory components for this program.
+     */
+    components?: Array<ProgramResult.Component>;
+
+    /**
+     * Bookable directives emitted by this program.
+     */
+    directives?: ProgramResult.Directives;
+
+    /**
+     * Time entitlement for this program, if any.
+     */
+    entitlement?: ProgramResult.Entitlement;
+
+    /**
+     * Job-protection details for this program, if any.
+     */
+    job_protection?: ProgramResult.JobProtection;
+
+    /**
+     * Estimated wage-replacement rate for this program, if any.
+     */
+    pay_rate?: ProgramResult.PayRate;
+
+    /**
+     * Who pays the employee for this program's wage-replacement slice.
+     */
+    pay_source?: 'GOVERNMENT' | 'CARRIER' | 'EMPLOYER';
+
+    /**
+     * Human-readable pay summary for this program.
+     */
+    pay_summary?: string;
+
+    /**
+     * Outstanding artifacts or actions for this program.
+     */
+    program_requirements?: Array<ProgramResult.ProgramRequirement>;
+  }
+
+  export namespace ProgramResult {
+    export interface ProgramValidation {
+      /**
+       * Human-readable validation message.
+       */
+      message: string;
+
+      /**
+       * Validation outcome.
+       */
+      outcome: 'PASSED' | 'FAILED' | 'UNKNOWN' | 'ASSUMED';
+
+      /**
+       * Machine-readable validation function that produced this outcome.
+       */
+      validation_func: string;
+
+      /**
+       * Evidence key or field path inspected by the validation.
+       */
+      data_source?: string;
+
+      /**
+       * Observed value at evaluation time, if available.
+       */
+      value?: string;
+    }
+
+    export interface Component {
+      /**
+       * Category of explanatory result component.
+       */
+      kind: 'ELIGIBILITY' | 'PAY' | 'TIME' | 'OTHER';
+
+      /**
+       * Human-readable summary for this component.
+       */
+      summary: string;
+
+      /**
+       * Additional component-specific data.
+       */
+      data?: unknown;
+
+      /**
+       * Optional machine-readable subtype for the component.
+       */
+      subkind?: string;
+    }
+
+    /**
+     * Bookable directives emitted by this program.
+     */
+    export interface Directives {
+      /**
+       * Balance adjustment directives emitted by payable program results.
+       */
+      balance_adjustments?: Array<Directives.BalanceAdjustment>;
+
+      /**
+       * Payroll earning directives emitted by payable program results.
+       */
+      earnings?: Array<Directives.Earning>;
+
+      /**
+       * Leave request directive emitted by payable program results.
+       */
+      leave_request?: Directives.LeaveRequest;
+    }
+
+    export namespace Directives {
+      export interface BalanceAdjustment {
+        /**
+         * Adjustment amount serialized as a decimal string.
+         */
+        amount: string;
+
+        /**
+         * Leave type to adjust if applying the evaluation.
+         */
+        leave_type: string;
+
+        /**
+         * Unit for the adjustment amount, such as WEEKS, DAYS, or HOURS.
+         */
+        unit: string;
+
+        /**
+         * Accrual type to use when applying the adjustment.
+         */
+        accrual_type?: string;
+      }
+
+      export interface Earning {
+        /**
+         * Earning amount serialized as a decimal string.
+         */
+        amount: string;
+
+        /**
+         * Earning type to use if booking a payroll earning from the evaluation.
+         */
+        earning_type: string;
+
+        /**
+         * ISO 4217 currency code for the earning amount.
+         */
+        currency?: string;
+
+        /**
+         * Number of benefit weeks represented by this earning, serialized as a decimal
+         * string.
+         */
+        weeks?: string;
+      }
+
+      /**
+       * Leave request directive emitted by payable program results.
+       */
+      export interface LeaveRequest {
+        /**
+         * Leave type to use if booking a leave request from the evaluation.
+         */
+        leave_type: string;
+
+        /**
+         * Recommended leave request start date.
+         */
+        start_date: string;
+
+        /**
+         * Recommended leave request end date, if known.
+         */
+        end_date?: string;
+
+        /**
+         * Optional leave request status to use when booking.
+         */
+        status?: string;
+      }
+    }
+
+    /**
+     * Time entitlement for this program, if any.
+     */
+    export interface Entitlement {
+      /**
+       * Entitlement amount serialized as a decimal string.
+       */
+      amount: string;
+
+      /**
+       * Leave type associated with the entitlement.
+       */
+      leave_type: string;
+
+      /**
+       * Unit for the entitlement amount, such as WEEKS, DAYS, or HOURS.
+       */
+      unit: string;
+    }
+
+    /**
+     * Job-protection details for this program, if any.
+     */
+    export interface JobProtection {
+      /**
+       * Job-restoration right provided by the program.
+       */
+      restoration: string;
+
+      /**
+       * Whether the program continues group health coverage.
+       */
+      continues_group_health?: boolean;
+    }
+
+    /**
+     * Estimated wage-replacement rate for this program, if any.
+     */
+    export interface PayRate {
+      /**
+       * Wage-replacement phases for the program.
+       */
+      phases: Array<PayRate.Phase>;
+    }
+
+    export namespace PayRate {
+      export interface Phase {
+        /**
+         * Pay amount for this phase serialized as a decimal string.
+         */
+        amount: string;
+
+        /**
+         * ISO 4217 currency code for this pay phase.
+         */
+        currency?: string;
+
+        /**
+         * Number of days this phase lasts. Null means the phase runs to the window end.
+         */
+        duration_days?: number;
+
+        /**
+         * Pay-rate unit for this phase, such as DAILY, WEEKLY, or BIWEEKLY.
+         */
+        unit?: string;
+      }
+    }
+
+    export interface ProgramRequirement {
+      /**
+       * Machine-readable requirement key.
+       */
+      key: string;
+
+      /**
+       * Human-readable requirement summary.
+       */
+      summary: string;
+
+      /**
+       * Whether this requirement blocks payment until resolved.
+       */
+      blocks_payment?: boolean;
+    }
+  }
+}
+
+export interface LeaveProgramEvaluationCreateParams {
+  /**
+   * Requested leave start date.
+   */
+  claim_start_date: string;
+
+  /**
+   * Normalized leave reason to evaluate against statutory and custom leave programs.
+   */
+  leave_reason:
+    | 'BONDING'
+    | 'PREGNANCY_DISABILITY'
+    | 'PREGNANCY_ACCOMMODATION'
+    | 'MEDICAL'
+    | 'VACATION'
+    | 'OTHER';
+
+  /**
+   * Role ID for the employee whose leave request should be evaluated.
+   */
+  role_id: string;
+
+  /**
+   * Optional delivery type for birthing-parent disability evaluations. Used to
+   * estimate postpartum disability windows for programs such as CA-SDI and CA-PDL.
+   */
+  birth_type?: 'VAGINAL' | 'C_SECTION' | 'UNKNOWN';
+
+  /**
+   * Optional date the child entered the family for bonding leave programs.
+   */
+  child_entered_family_date?: string;
+
+  /**
+   * Optional requested leave end date. When set, leave_plan.pay_periods includes
+   * estimated per-paycheck amounts for programs that publish pay rates.
+   */
+  claim_end_date?: string;
+
+  /**
+   * Demo/test-company only evidence overrides for exercising eligibility scenarios
+   * when the role's real data would not qualify.
+   */
+  evidence_override?: unknown;
+
+  /**
+   * Optional parental leave relationship type for parental leave programs.
+   * Deprecated for most bonding evaluations, but still accepted for backwards
+   * compatibility with 2024-08-01 SDK callers.
+   */
+  parental_leave_type?:
+    | 'birthing_parent'
+    | 'non_birthing_parent'
+    | 'adoption_parent'
+    | 'supporting_person'
+    | 'foster_parent';
+
+  /**
+   * Optional leave program codes to evaluate. When omitted, every registered leave
+   * program runs in dependency order.
+   */
+  program_codes?: Array<string>;
+
+  /**
+   * Answers for evidence keys returned in missing_evidence. These answers only fill
+   * facts that the evaluation reported as missing.
+   */
+  supplemental_evidence?: unknown;
+}
+
+export declare namespace LeaveProgramEvaluations {
+  export {
+    type LeaveProgramEvaluationCreateResponse as LeaveProgramEvaluationCreateResponse,
+    type LeaveProgramEvaluationCreateParams as LeaveProgramEvaluationCreateParams,
+  };
+}