@rippling/rippling-sdk 0.2.0-alpha.85 → 0.2.0-alpha.87

package/src/lib/leave-programs/policy-builder.ts

@@ -0,0 +1,113 @@
+import type {
+  AdminTask,
+  DurationExpression,
+  EntitlementDecision,
+  FactRef,
+  GrantPaidLeaveOptions,
+  MoneyAmount,
+  PayDecision,
+  PayFixedAmountOptions,
+  PayPercentOfPayOptions,
+  PercentOfPay,
+  PolicyBuilder,
+  PolicyBuilderResult,
+  PolicyCondition,
+  RequireKnownOptions,
+  RequirementDecision,
+  TopUpToOptions,
+  WageReplacementRef,
+} from './types';
+
+export class CompanyPolicyBuilder implements PolicyBuilder {
+  private readonly conditions: PolicyCondition[] = [];
+  private readonly requiredEvidence: PolicyBuilderResult['requiredEvidence'] = [];
+  private entitlementDecision: EntitlementDecision | undefined;
+  private payDecision: PayDecision = { type: 'NO_COMPANY_PAY' };
+  private readonly requirementDecisions: RequirementDecision[] = [];
+  private jobProtectionDecision: PolicyBuilderResult['jobProtection'] = 'UNCHANGED';
+
+  eligibleWhen(condition: PolicyCondition): PolicyBuilder {
+    this.conditions.push(condition);
+    return this;
+  }
+
+  requireKnown(_fact: FactRef | WageReplacementRef, options: RequireKnownOptions): PolicyBuilder {
+    this.requiredEvidence.push({
+      key: options.evidenceKey,
+      ...(options.message === undefined ? {} : { message: options.message }),
+    });
+    return this;
+  }
+
+  grantPaidLeave(duration: DurationExpression, options: GrantPaidLeaveOptions = {}): PolicyBuilder {
+    this.entitlementDecision = {
+      type: 'PAID_LEAVE',
+      duration,
+      ...(options.leaveType === undefined ? {} : { leaveType: options.leaveType }),
+    };
+    return this;
+  }
+
+  noCompanyPay(): PolicyBuilder {
+    this.payDecision = { type: 'NO_COMPANY_PAY' };
+    return this;
+  }
+
+  payFixedAmount(amount: MoneyAmount, options: PayFixedAmountOptions): PolicyBuilder {
+    this.payDecision = {
+      type: 'FIXED_AMOUNT',
+      amount,
+      duration: options.duration,
+      earningType: options.earningType,
+    };
+    return this;
+  }
+
+  payPercentOfPay(target: PercentOfPay, options: PayPercentOfPayOptions): PolicyBuilder {
+    this.payDecision = {
+      type: 'PERCENT_OF_PAY',
+      target,
+      base: options.base,
+      duration: options.duration,
+      earningType: options.earningType,
+    };
+    return this;
+  }
+
+  topUpTo(target: PercentOfPay, options: TopUpToOptions): PolicyBuilder {
+    this.payDecision = {
+      type: 'MAKE_WHOLE_TOPUP',
+      target,
+      base: options.base,
+      offsetBy: options.offsetBy,
+      earningType: options.earningType,
+    };
+    return this;
+  }
+
+  requireAdminTask(key: AdminTask | string): PolicyBuilder {
+    this.requirementDecisions.push({
+      type: 'ADMIN_TASK',
+      key,
+      blocksPayment: false,
+    });
+    return this;
+  }
+
+  doesNotProvideJobProtection(): PolicyBuilder {
+    this.jobProtectionDecision = 'NONE';
+    return this;
+  }
+
+  build(): PolicyBuilderResult {
+    return {
+      conditions: [...this.conditions],
+      requiredEvidence: [...this.requiredEvidence],
+      ...(this.entitlementDecision === undefined ? {} : { entitlement: this.entitlementDecision }),
+      pay: this.payDecision,
+      requirements: [...this.requirementDecisions],
+      jobProtection: this.jobProtectionDecision,
+      diagnostics: [],
+    };
+  }
+}

package/src/lib/leave-programs/recipes/parental-top-up-policy.ts

@@ -0,0 +1,85 @@
+import { percentOfPay } from '../pay';
+import { AdminTask, type CompanyLeaveProgramDefinitionConfig, type ParentalRelationship } from '../types';
+import { weeks } from '../duration';
+
+export interface ParentalTopUpPolicyOptions {
+  code: string;
+  displayName: string;
+  description?: string;
+  jurisdiction: {
+    country: string;
+    subdivisions?: string[];
+  };
+  appliesTo?: {
+    employeeCountry?: string;
+  };
+  qualifyingLeaveReasons: string[];
+  paidWeeksByParentalRelationship: Partial<Record<ParentalRelationship, number>>;
+  pay: {
+    type: 'MAKE_WHOLE_TOPUP';
+    targetPercentOfPay: number;
+    offsetByPrograms: string[];
+    earningType?: string;
+  };
+  requirements?: Array<AdminTask | string>;
+  leaveType?: string;
+}
+
+export function parentalTopUpPolicy(
+  options: ParentalTopUpPolicyOptions,
+): CompanyLeaveProgramDefinitionConfig {
+  const requirements = options.requirements ?? [
+    AdminTask.ManagerAcknowledgement,
+    AdminTask.PaymentRecordReconciliation,
+    AdminTask.SeparateFromJobProtection,
+  ];
+  const earningType = options.pay.earningType ?? 'EMPLOYER_TOPUP_MAKE_WHOLE';
+  const leaveType = options.leaveType ?? 'EMPLOYER_PARENTAL_TOPUP';
+  const paidWeeksByRelationship = options.paidWeeksByParentalRelationship;
+  const employeeCountry = options.appliesTo?.employeeCountry;
+
+  return {
+    code: options.code,
+    displayName: options.displayName,
+    ...(options.description === undefined ? {} : { description: options.description }),
+    jurisdiction: options.jurisdiction,
+    dependsOn: options.pay.offsetByPrograms,
+    ...(employeeCountry === undefined ?
+      {}
+    : { appliesTo: (context) => context.employee.country.is(employeeCountry) }),
+    evaluate(context) {
+      const paidLeaveCases = Object.fromEntries(
+        Object.entries(paidWeeksByRelationship).map(([relationship, paidWeeks]) => [
+          relationship,
+          weeks(paidWeeks ?? 0),
+        ]),
+      );
+
+      const builder = context
+        .policy()
+        .eligibleWhen(context.leave.reason.isOneOf(options.qualifyingLeaveReasons))
+        .requireKnown(context.pay.contractualWeeklyPay, {
+          evidenceKey: 'weekly_wage',
+          message: 'Contractual weekly pay is required to calculate company top-up.',
+        })
+        .requireKnown(context.programs.wageReplacement(options.pay.offsetByPrograms), {
+          evidenceKey: 'upstream_pay_rates',
+          message:
+            'Statutory or insurance wage-replacement amounts are required to calculate company top-up.',
+        })
+        .grantPaidLeave(context.leave.parentalRelationship.match(paidLeaveCases), { leaveType })
+        .topUpTo(percentOfPay(options.pay.targetPercentOfPay), {
+          base: context.pay.contractualWeeklyPay,
+          offsetBy: context.programs.wageReplacement(options.pay.offsetByPrograms),
+          earningType,
+        })
+        .doesNotProvideJobProtection();
+
+      for (const requirement of requirements) {
+        builder.requireAdminTask(requirement);
+      }
+
+      return builder.build();
+    },
+  };
+}

package/src/lib/leave-programs/testing.ts

@@ -0,0 +1,16 @@
+import type { CompanyLeaveProgramResult, CompanyLeaveProgramDefinition } from './types';
+
+export interface LeaveProgramScenario {
+  name: string;
+  expect: Partial<CompanyLeaveProgramResult>;
+}
+
+export function scenario(name: string, options: Omit<LeaveProgramScenario, 'name'>): LeaveProgramScenario {
+  return { name, ...options };
+}
+
+export function evaluateCompanyLeaveProgram(
+  definition: CompanyLeaveProgramDefinition,
+): CompanyLeaveProgramResult {
+  return definition.toResult();
+}

package/src/lib/leave-programs/types.ts

@@ -0,0 +1,274 @@
+export type LeaveProgramContractVersion = 'company_leave_program.v1';
+
+export type ProgramKind = 'COMPANY_POLICY';
+
+export interface LeaveProgramJurisdiction {
+  country: string;
+  subdivisions?: string[];
+}
+
+export interface Duration {
+  kind: 'duration';
+  amount: number;
+  unit: 'HOURS' | 'DAYS' | 'WEEKS';
+}
+
+export interface MoneyAmount {
+  kind: 'money_amount';
+  amount: string;
+  currency: string;
+}
+
+export interface PercentOfPay {
+  kind: 'percent_of_pay';
+  percent: number;
+}
+
+export interface FactRef {
+  kind: 'fact_ref';
+  path: string;
+}
+
+export interface WageReplacementRef {
+  kind: 'wage_replacement_ref';
+  programCodes: string[];
+}
+
+export interface EvidenceRequirement {
+  key: string;
+  message?: string;
+}
+
+export type PolicyCondition =
+  | {
+      type: 'employee_country_is';
+      country: string;
+    }
+  | {
+      type: 'leave_reason_is_parental';
+    }
+  | {
+      type: 'leave_reason_in';
+      values: string[];
+    }
+  | {
+      type: 'tenure_months_match';
+      asOf: FactRef;
+      tiers: TenureMatchTier[];
+    }
+  | {
+      type: 'advanced_predicate';
+      name: string;
+      uses: FactRef[];
+    };
+
+export interface TenureMatchTier {
+  gte?: number;
+  lt?: number;
+  value: Duration;
+}
+
+export type DurationExpression =
+  | Duration
+  | {
+      type: 'parental_relationship_duration';
+      cases: Partial<Record<ParentalRelationship, Duration>>;
+      unknown?: EvidenceRequirement;
+    }
+  | {
+      type: 'tenure_months_duration';
+      tiers: TenureMatchTier[];
+    }
+  | {
+      type: 'advanced_duration_formula';
+      name: string;
+      uses: FactRef[];
+    };
+
+export type ParentalRelationship =
+  | 'birthingParent'
+  | 'nonBirthingParent'
+  | 'adoptionParent'
+  | 'fosterParent'
+  | 'supportingPerson';
+
+export type PayDecision =
+  | {
+      type: 'NO_COMPANY_PAY';
+    }
+  | {
+      type: 'FIXED_AMOUNT';
+      amount: MoneyAmount;
+      duration: DurationExpression;
+      earningType: string;
+    }
+  | {
+      type: 'PERCENT_OF_PAY';
+      target: PercentOfPay;
+      base: FactRef;
+      duration: DurationExpression;
+      earningType: string;
+    }
+  | {
+      type: 'MAKE_WHOLE_TOPUP';
+      target: PercentOfPay;
+      base: FactRef;
+      offsetBy: WageReplacementRef;
+      earningType: string;
+    };
+
+export interface EntitlementDecision {
+  type: 'PAID_LEAVE';
+  duration: DurationExpression;
+  leaveType?: string;
+}
+
+export interface RequirementDecision {
+  type: 'ADMIN_TASK';
+  key: string;
+  blocksPayment: boolean;
+}
+
+export interface LeaveProgramDiagnostic {
+  code: string;
+  message: string;
+}
+
+export type AdvancedCapability =
+  | 'CUSTOM_ELIGIBILITY_PREDICATE'
+  | 'CUSTOM_DURATION_FORMULA'
+  | 'CUSTOM_PAY_FORMULA';
+
+export interface CompanyLeaveProgramResult {
+  contractVersion: LeaveProgramContractVersion;
+  program: {
+    code: string;
+    displayName: string;
+    description?: string;
+    programKind: ProgramKind;
+    jurisdiction: LeaveProgramJurisdiction;
+    dependsOn: string[];
+    capabilities: AdvancedCapability[];
+  };
+  appliesTo: PolicyCondition[];
+  eligibility: {
+    conditions: PolicyCondition[];
+    requiredEvidence: EvidenceRequirement[];
+  };
+  entitlement?: EntitlementDecision;
+  pay: PayDecision;
+  requirements: RequirementDecision[];
+  jobProtection: 'NONE' | 'UNCHANGED';
+  diagnostics: LeaveProgramDiagnostic[];
+}
+
+export interface CompanyLeaveProgramDefinition {
+  readonly contractVersion: LeaveProgramContractVersion;
+  readonly code: string;
+  readonly displayName: string;
+  readonly jurisdiction: LeaveProgramJurisdiction;
+  readonly dependsOn: string[];
+  toResult(context?: CompanyLeaveProgramContext): CompanyLeaveProgramResult;
+}
+
+export interface CompanyLeaveProgramDefinitionConfig {
+  code: string;
+  displayName: string;
+  description?: string;
+  jurisdiction: LeaveProgramJurisdiction;
+  programKind?: ProgramKind;
+  dependsOn?: string[];
+  capabilities?: AdvancedCapability[];
+  appliesTo?: (context: CompanyLeaveProgramContext) => PolicyCondition | PolicyCondition[];
+  evaluate: (context: CompanyLeaveProgramContext) => PolicyBuilderResult;
+}
+
+export interface PolicyBuilderResult {
+  conditions: PolicyCondition[];
+  requiredEvidence: EvidenceRequirement[];
+  entitlement?: EntitlementDecision;
+  pay: PayDecision;
+  requirements: RequirementDecision[];
+  jobProtection: 'NONE' | 'UNCHANGED';
+  diagnostics: LeaveProgramDiagnostic[];
+}
+
+export interface CompanyLeaveProgramContext {
+  employee: {
+    country: {
+      is(country: string): PolicyCondition;
+    };
+    tenure: {
+      monthsAt(asOf: FactRef): {
+        match(tiers: TenureMatchTier[]): DurationExpression;
+      };
+    };
+  };
+  leave: {
+    reason: {
+      isParental(): PolicyCondition;
+      isOneOf(values: string[]): PolicyCondition;
+    };
+    startDate: FactRef;
+    parentalRelationship: {
+      match(
+        cases: Partial<Record<ParentalRelationship | 'unknown', Duration | EvidenceRequirement>>,
+      ): DurationExpression;
+    };
+  };
+  pay: {
+    contractualWeeklyPay: FactRef;
+  };
+  programs: {
+    wageReplacement(programCodes: string[]): WageReplacementRef;
+  };
+  evidence: {
+    require(key: string, message?: string): EvidenceRequirement;
+  };
+  policy(): PolicyBuilder;
+}
+
+export interface TopUpToOptions {
+  base: FactRef;
+  offsetBy: WageReplacementRef;
+  earningType: string;
+}
+
+export interface PayPercentOfPayOptions {
+  base: FactRef;
+  duration: DurationExpression;
+  earningType: string;
+}
+
+export interface PayFixedAmountOptions {
+  duration: DurationExpression;
+  earningType: string;
+}
+
+export interface GrantPaidLeaveOptions {
+  leaveType?: string;
+}
+
+export interface RequireKnownOptions {
+  evidenceKey: string;
+  message?: string;
+}
+
+export interface PolicyBuilder {
+  eligibleWhen(condition: PolicyCondition): PolicyBuilder;
+  requireKnown(fact: FactRef | WageReplacementRef, options: RequireKnownOptions): PolicyBuilder;
+  grantPaidLeave(duration: DurationExpression, options?: GrantPaidLeaveOptions): PolicyBuilder;
+  noCompanyPay(): PolicyBuilder;
+  payFixedAmount(amount: MoneyAmount, options: PayFixedAmountOptions): PolicyBuilder;
+  payPercentOfPay(target: PercentOfPay, options: PayPercentOfPayOptions): PolicyBuilder;
+  topUpTo(target: PercentOfPay, options: TopUpToOptions): PolicyBuilder;
+  requireAdminTask(key: AdminTask | string): PolicyBuilder;
+  doesNotProvideJobProtection(): PolicyBuilder;
+  build(): PolicyBuilderResult;
+}
+
+export enum AdminTask {
+  ManagerAcknowledgement = 'manager_acknowledgement',
+  PaymentRecordReconciliation = 'payment_record_reconciliation',
+  SeparateFromJobProtection = 'separate_from_job_protection',
+}

package/src/lib/leave-programs.ts

@@ -0,0 +1,35 @@
+export { defineCompanyLeaveProgram } from './leave-programs/define-company-leave-program';
+export { createCompanyLeaveProgramContext } from './leave-programs/context';
+export { weeks, days, hours } from './leave-programs/duration';
+export { fixedAmount, percentOfPay } from './leave-programs/pay';
+export {
+  parentalTopUpPolicy,
+  type ParentalTopUpPolicyOptions,
+} from './leave-programs/recipes/parental-top-up-policy';
+export {
+  AdminTask,
+  type AdvancedCapability,
+  type CompanyLeaveProgramContext,
+  type CompanyLeaveProgramResult,
+  type CompanyLeaveProgramDefinition,
+  type CompanyLeaveProgramDefinitionConfig,
+  type Duration,
+  type DurationExpression,
+  type EntitlementDecision,
+  type EvidenceRequirement,
+  type FactRef,
+  type GrantPaidLeaveOptions,
+  type LeaveProgramContractVersion,
+  type LeaveProgramDiagnostic,
+  type LeaveProgramJurisdiction,
+  type MoneyAmount,
+  type ParentalRelationship,
+  type PayDecision,
+  type PercentOfPay,
+  type PolicyBuilder,
+  type PolicyBuilderResult,
+  type PolicyCondition,
+  type ProgramKind,
+  type RequirementDecision,
+  type WageReplacementRef,
+} from './leave-programs/types';