@rippling/rippling-sdk 0.2.0-alpha.82 → 0.2.0-alpha.84

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

@@ -21,9 +21,11 @@ export class LeaveProgramEvaluations extends APIResource {
 
 export interface LeaveProgramEvaluationCreateResponse {
   /**
-   * Combined leave plan derived from all non-ineligible program results.
+   * 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: unknown;
+  leave_plan: LeaveProgramEvaluationCreateResponse.LeavePlan;
 
   /**
    * Structured evidence gaps reported by evaluated eligibility rules.
@@ -33,10 +35,311 @@ export interface LeaveProgramEvaluationCreateResponse {
   /**
    * Per-program rule outputs in evaluation order.
    */
-  program_results: Array<unknown>;
+  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.
@@ -58,6 +361,302 @@ export namespace LeaveProgramEvaluationCreateResponse {
      */
     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 {
@@ -87,6 +686,12 @@ export interface LeaveProgramEvaluationCreateParams {
    */
   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.
@@ -95,6 +700,8 @@ export interface LeaveProgramEvaluationCreateParams {
 
   /**
    * 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'