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

package/src/client.ts

@@ -432,6 +432,22 @@ import {
   ShiftassignmentUpdateResponse,
   Shiftassignments,
 } from './resources/shiftassignments';
+import {
+  SiteCreateParams,
+  SiteCreateResponse,
+  SiteFileOperationsParams,
+  SiteFileOperationsResponse,
+  SiteFilesParams,
+  SiteFilesResponse,
+  SiteListResponse,
+  SiteListResponsesPageCursorURL,
+  SiteRetrieveResponse,
+  SiteUpdateParams,
+  SiteUpdateResponse,
+  SiteUploadBatchesParams,
+  SiteUploadBatchesResponse,
+  Sites,
+} from './resources/sites';
 import {
   SoftwareDeploymentCreateParams,
   SoftwareDeploymentCreateResponse,
@@ -564,6 +580,17 @@ import {
   WorkflowActionExecutionCreateResponse,
   WorkflowActionExecutions,
 } from './resources/workflow-action-executions';
+import {
+  AgentCreateParams,
+  AgentCreateResponse,
+  AgentListParams,
+  AgentListResponse,
+  AgentListResponsesPageCursorURL,
+  AgentRetrieveResponse,
+  AgentUpdateParams,
+  AgentUpdateResponse,
+  Agents,
+} from './resources/agents/agents';
 import {
   CustomObject,
   CustomObjectCreateParams,
@@ -581,6 +608,17 @@ import {
   Functions,
   FunctionsPageCursorURL,
 } from './resources/functions/functions';
+import {
+  PackageCreateParams,
+  PackageCreateResponse,
+  PackageListParams,
+  PackageListResponse,
+  PackageListResponsesPageCursorURL,
+  PackageRetrieveResponse,
+  PackageUpdateParams,
+  PackageUpdateResponse,
+  Packages,
+} from './resources/packages/packages';
 import {
   PayrollRunListParams,
   PayrollRunListResponse,
@@ -1461,6 +1499,10 @@ export class RipplingSDK {
    * Job related information for the company
    */
   jobPayRateExceptions: API.JobPayRateExceptions = new API.JobPayRateExceptions(this);
+  /**
+   * Agents defined by the company
+   */
+  agents: API.Agents = new API.Agents(this);
   /**
    * Mappings between Rippling workers and their user accounts in third-party apps
    */
@@ -1564,6 +1606,10 @@ export class RipplingSDK {
    * Geographic compensation adjustment factors that modify base compensation based on location-specific market conditions and cost of living
    */
   locationFactors: API.LocationFactors = new API.LocationFactors(this);
+  /**
+   * Author, publish, and install Unity Packages V2 packages
+   */
+  packages: API.Packages = new API.Packages(this);
   /**
    * Payroll runs for the company
    */
@@ -1592,6 +1638,7 @@ export class RipplingSDK {
    * Shift assignments assigned to workers
    */
   shiftassignments: API.Shiftassignments = new API.Shiftassignments(this);
+  sites: API.Sites = new API.Sites(this);
   /**
    * Software deployed to company devices
    */
@@ -1660,6 +1707,7 @@ RipplingSDK.BusinessPartnerGroups = BusinessPartnerGroups;
 RipplingSDK.Functions = Functions;
 RipplingSDK.JobAssignments = JobAssignments;
 RipplingSDK.JobPayRateExceptions = JobPayRateExceptions;
+RipplingSDK.Agents = Agents;
 RipplingSDK.AppUsers = AppUsers;
 RipplingSDK.BreakPolicies = BreakPolicies;
 RipplingSDK.BreakTypes = BreakTypes;
@@ -1688,6 +1736,7 @@ RipplingSDK.JobRequisitionsWrite = JobRequisitionsWrite;
 RipplingSDK.LeaveAccruals = LeaveAccruals;
 RipplingSDK.LeaveProgramEvaluations = LeaveProgramEvaluations;
 RipplingSDK.LocationFactors = LocationFactors;
+RipplingSDK.Packages = Packages;
 RipplingSDK.PayrollRuns = PayrollRuns;
 RipplingSDK.PlatformCapabilities = PlatformCapabilities;
 RipplingSDK.Reports = Reports;
@@ -1695,6 +1744,7 @@ RipplingSDK.ReportRuns = ReportRuns;
 RipplingSDK.Schedules = Schedules;
 RipplingSDK.ScheduledJobAssignments = ScheduledJobAssignments;
 RipplingSDK.Shiftassignments = Shiftassignments;
+RipplingSDK.Sites = Sites;
 RipplingSDK.SoftwareDeployments = SoftwareDeployments;
 RipplingSDK.Titles = Titles;
 RipplingSDK.Unassignedshifts = Unassignedshifts;
@@ -2011,6 +2061,18 @@ export declare namespace RipplingSDK {
     type JobPayRateExceptionListChangeLogParams as JobPayRateExceptionListChangeLogParams,
   };
 
+  export {
+    Agents as Agents,
+    type AgentListResponse as AgentListResponse,
+    type AgentCreateResponse as AgentCreateResponse,
+    type AgentRetrieveResponse as AgentRetrieveResponse,
+    type AgentUpdateResponse as AgentUpdateResponse,
+    type AgentListResponsesPageCursorURL as AgentListResponsesPageCursorURL,
+    type AgentListParams as AgentListParams,
+    type AgentCreateParams as AgentCreateParams,
+    type AgentUpdateParams as AgentUpdateParams,
+  };
+
   export {
     AppUsers as AppUsers,
     type AppUserListResponse as AppUserListResponse,
@@ -2239,6 +2301,18 @@ export declare namespace RipplingSDK {
     type LocationFactorListParams as LocationFactorListParams,
   };
 
+  export {
+    Packages as Packages,
+    type PackageListResponse as PackageListResponse,
+    type PackageCreateResponse as PackageCreateResponse,
+    type PackageRetrieveResponse as PackageRetrieveResponse,
+    type PackageUpdateResponse as PackageUpdateResponse,
+    type PackageListResponsesPageCursorURL as PackageListResponsesPageCursorURL,
+    type PackageListParams as PackageListParams,
+    type PackageCreateParams as PackageCreateParams,
+    type PackageUpdateParams as PackageUpdateParams,
+  };
+
   export {
     PayrollRuns as PayrollRuns,
     type PayrollRunListResponse as PayrollRunListResponse,
@@ -2296,6 +2370,23 @@ export declare namespace RipplingSDK {
     type ShiftassignmentUpdateParams as ShiftassignmentUpdateParams,
   };
 
+  export {
+    Sites as Sites,
+    type SiteListResponse as SiteListResponse,
+    type SiteCreateResponse as SiteCreateResponse,
+    type SiteRetrieveResponse as SiteRetrieveResponse,
+    type SiteUpdateResponse as SiteUpdateResponse,
+    type SiteUploadBatchesResponse as SiteUploadBatchesResponse,
+    type SiteFilesResponse as SiteFilesResponse,
+    type SiteFileOperationsResponse as SiteFileOperationsResponse,
+    type SiteListResponsesPageCursorURL as SiteListResponsesPageCursorURL,
+    type SiteCreateParams as SiteCreateParams,
+    type SiteUpdateParams as SiteUpdateParams,
+    type SiteUploadBatchesParams as SiteUploadBatchesParams,
+    type SiteFilesParams as SiteFilesParams,
+    type SiteFileOperationsParams as SiteFileOperationsParams,
+  };
+
   export {
     SoftwareDeployments as SoftwareDeployments,
     type SoftwareDeploymentListResponse as SoftwareDeploymentListResponse,

package/src/lib/leave-programs/README.md

@@ -0,0 +1,160 @@
+# Leave Program Authoring
+
+Draft handwritten helpers for authoring company leave programs in Rippling
+Functions.
+
+This library is intended to be the customer-facing authoring surface for
+company-specific leave policy. A customer should be able to write a Rippling
+Function that imports this package, describes their company leave program, and
+returns a constrained program result that Rippling can evaluate later.
+
+This is not the leave engine itself. It does not register programs, hydrate
+employee or payroll facts, run statutory programs, calculate payroll outputs, or
+build leave plans. Those responsibilities stay in `rippling-main`.
+
+## Intended Flow
+
+```text
+Customer Function imports @rippling/rippling-sdk/lib/leave-programs
+  -> customer defines a company leave policy
+  -> library emits CompanyLeaveProgramResult IR
+  -> rippling-main validates and compiles the IR
+  -> leave engine runs the company program alongside statutory programs
+  -> leave engine composes the final leave plan and program outputs
+```
+
+The important boundary is that customer code describes policy intent. It does
+not emit raw `LeaveProgramResult`, payroll directives, earning lines, balance
+adjustments, or internal leave engine objects.
+
+## What Customers Can Express
+
+Company policies should be able to express a small set of leave-domain concepts:
+
+- Applicability, such as employee country or jurisdiction.
+- Eligibility, such as leave reason, parental relationship, tenure tiers, and
+  required evidence.
+- Entitlement, such as a paid leave bank in weeks, days, or hours.
+- Pay intent, such as no company pay, fixed pay, percent of contractual pay, or
+  make-whole top-up.
+- Coordination with Rippling-owned statutory or insurance wage replacement
+  programs.
+- Admin requirements that Rippling can surface during review.
+
+Pay is intentionally constrained. For example, a customer can say "top the
+employee up to 100% of contractual weekly pay, net of CA-PFL." They cannot say
+"create this payroll earning line with this internal earning code on this
+payrun."
+
+## What Rippling Still Owns
+
+`rippling-main` remains responsible for:
+
+- Program registration, activation, versioning, effective dates, and company
+  scope.
+- Deciding which statutory, insurance, and company programs run for a claim.
+- Dependency ordering between statutory programs and company policies.
+- Hydrating sanitized facts from HRIS, Payroll, PTO, Benefits, and other source
+  systems.
+- Validating the program result IR returned by customer code.
+- Missing evidence handling.
+- Payroll-safe pay phase construction, rounding, currency handling, earning type
+  mapping, caps, and offsets.
+- Conversion to internal `LeaveProgramResult`, directives, and leave plan
+  outputs.
+
+## Example: Common Recipe
+
+Recipes are the simplest authoring lane. They cover common company policies
+without requiring customers to write lower-level policy composition code.
+
+```ts
+import { defineCompanyLeaveProgram, parentalTopUpPolicy } from '@rippling/rippling-sdk/lib/leave-programs';
+
+export default defineCompanyLeaveProgram(
+  parentalTopUpPolicy({
+    code: 'ACME_US_PARENTAL_TOPUP',
+    displayName: 'Acme US parental top-up',
+    jurisdiction: { country: 'US' },
+    appliesTo: { employeeCountry: 'US' },
+    qualifyingLeaveReasons: ['BONDING', 'PREGNANCY_DISABILITY'],
+    paidWeeksByParentalRelationship: {
+      birthingParent: 16,
+      nonBirthingParent: 6,
+      adoptionParent: 10,
+      fosterParent: 10,
+    },
+    pay: {
+      type: 'MAKE_WHOLE_TOPUP',
+      targetPercentOfPay: 100,
+      offsetByPrograms: ['CA-SDI', 'CA-PFL', 'INSURANCE-STD'],
+    },
+  }),
+);
+```
+
+This emits policy IR that says:
+
+- The program applies to US employees.
+- Bonding and pregnancy disability are qualifying leave reasons.
+- The paid leave bank depends on parental relationship.
+- Company pay tops up statutory or insurance wage replacement to 100% of
+  contractual weekly pay.
+- The backend should coordinate this policy after `CA-SDI`, `CA-PFL`, and
+  `INSURANCE-STD`.
+
+## Example: Composable Builder
+
+Builders are for company policies that do not fit a recipe cleanly, but still
+use supported leave-policy primitives.
+
+```ts
+import { defineCompanyLeaveProgram, percentOfPay, weeks } from '@rippling/rippling-sdk/lib/leave-programs';
+
+export default defineCompanyLeaveProgram({
+  code: 'ACME_TENURE_PARENTAL_TOPUP',
+  displayName: 'Acme tenure parental top-up',
+  jurisdiction: { country: 'US' },
+  dependsOn: ['CA-PFL'],
+
+  evaluate(ctx) {
+    const paidWeeks = ctx.employee.tenure.monthsAt(ctx.leave.startDate).match([
+      { gte: 0, lt: 6, value: weeks(4) },
+      { gte: 6, lt: 12, value: weeks(8) },
+      { gte: 12, value: weeks(12) },
+    ]);
+
+    return ctx
+      .policy()
+      .eligibleWhen(ctx.employee.country.is('US'))
+      .eligibleWhen(ctx.leave.reason.isParental())
+      .grantPaidLeave(paidWeeks, { leaveType: 'EMPLOYER_PARENTAL_TOPUP' })
+      .topUpTo(percentOfPay(100), {
+        base: ctx.pay.contractualWeeklyPay,
+        offsetBy: ctx.programs.wageReplacement(['CA-PFL']),
+        earningType: 'EMPLOYER_TOPUP_MAKE_WHOLE',
+      })
+      .build();
+  },
+});
+```
+
+The builder still returns the same constrained `CompanyLeaveProgramResult` IR.
+It does not expose raw payroll, PTO, HRIS, Benefits, ZObject, or leave-engine
+records.
+
+## Current Draft Scope
+
+This package currently provides the SDK-side authoring shape only:
+
+- `defineCompanyLeaveProgram`
+- duration helpers such as `weeks`, `days`, and `hours`
+- pay helpers such as `percentOfPay` and `fixedAmount`
+- the `parentalTopUpPolicy` recipe
+- constrained `CompanyLeaveProgramResult` types
+- draft advanced and testing entry points
+
+Backend registration, activation, validation, Function execution, and leave
+engine compilation are intentionally out of scope for this package. Those pieces
+must be implemented in `rippling-main` before a customer-authored Function can
+run in production alongside Rippling-owned statutory programs.

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

@@ -0,0 +1,11 @@
+export type {
+  AdvancedCapability,
+  CompanyLeaveProgramDefinitionConfig,
+  DurationExpression,
+  FactRef,
+  PolicyCondition,
+} from './types';
+
+export { defineCompanyLeaveProgram as defineAdvancedCompanyLeaveProgram } from './define-company-leave-program';
+export { percentOfPay, fixedAmount } from './pay';
+export { weeks, days, hours } from './duration';

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

@@ -0,0 +1,101 @@
+import { CompanyPolicyBuilder } from './policy-builder';
+import type {
+  CompanyLeaveProgramContext,
+  Duration,
+  DurationExpression,
+  EvidenceRequirement,
+  FactRef,
+  ParentalRelationship,
+  PolicyCondition,
+  TenureMatchTier,
+  WageReplacementRef,
+} from './types';
+
+function fact(path: string): FactRef {
+  return { kind: 'fact_ref', path };
+}
+
+function isEvidenceRequirement(value: Duration | EvidenceRequirement): value is EvidenceRequirement {
+  return 'key' in value;
+}
+
+export function createCompanyLeaveProgramContext(): CompanyLeaveProgramContext {
+  return {
+    employee: {
+      country: {
+        is(country: string): PolicyCondition {
+          return { type: 'employee_country_is', country };
+        },
+      },
+      tenure: {
+        monthsAt(asOf: FactRef) {
+          return {
+            match(tiers: TenureMatchTier[]): DurationExpression {
+              return {
+                type: 'tenure_months_duration',
+                tiers: tiers.map((tier) => ({ ...tier })),
+              };
+            },
+          };
+        },
+      },
+    },
+    leave: {
+      reason: {
+        isParental(): PolicyCondition {
+          return { type: 'leave_reason_is_parental' };
+        },
+        isOneOf(values: string[]): PolicyCondition {
+          return { type: 'leave_reason_in', values: [...values] };
+        },
+      },
+      startDate: fact('leave.startDate'),
+      parentalRelationship: {
+        match(cases): DurationExpression {
+          const durationCases: Partial<Record<ParentalRelationship, Duration>> = {};
+          let unknown: EvidenceRequirement | undefined;
+
+          for (const [relationship, value] of Object.entries(cases)) {
+            if (value === undefined) {
+              continue;
+            }
+            if (relationship === 'unknown') {
+              if (isEvidenceRequirement(value)) {
+                unknown = value;
+              }
+              continue;
+            }
+            if (!isEvidenceRequirement(value)) {
+              durationCases[relationship as ParentalRelationship] = value;
+            }
+          }
+
+          return {
+            type: 'parental_relationship_duration',
+            cases: durationCases,
+            ...(unknown === undefined ? {} : { unknown }),
+          };
+        },
+      },
+    },
+    pay: {
+      contractualWeeklyPay: fact('pay.contractualWeeklyPay'),
+    },
+    programs: {
+      wageReplacement(programCodes: string[]): WageReplacementRef {
+        return { kind: 'wage_replacement_ref', programCodes: [...programCodes] };
+      },
+    },
+    evidence: {
+      require(key: string, message?: string): EvidenceRequirement {
+        return {
+          key,
+          ...(message === undefined ? {} : { message }),
+        };
+      },
+    },
+    policy() {
+      return new CompanyPolicyBuilder();
+    },
+  };
+}

package/src/lib/leave-programs/define-company-leave-program.ts

@@ -0,0 +1,58 @@
+import { createCompanyLeaveProgramContext } from './context';
+import type {
+  CompanyLeaveProgramContext,
+  CompanyLeaveProgramResult,
+  CompanyLeaveProgramDefinition,
+  CompanyLeaveProgramDefinitionConfig,
+  PolicyCondition,
+} from './types';
+
+function asArray(value: PolicyCondition | PolicyCondition[] | undefined): PolicyCondition[] {
+  if (value === undefined) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}
+
+export function defineCompanyLeaveProgram(
+  config: CompanyLeaveProgramDefinitionConfig,
+): CompanyLeaveProgramDefinition {
+  const dependsOn = config.dependsOn === undefined ? [] : [...config.dependsOn];
+  const capabilities = config.capabilities === undefined ? [] : [...config.capabilities];
+
+  return {
+    contractVersion: 'company_leave_program.v1',
+    code: config.code,
+    displayName: config.displayName,
+    jurisdiction: { ...config.jurisdiction },
+    dependsOn,
+
+    toResult(
+      context: CompanyLeaveProgramContext = createCompanyLeaveProgramContext(),
+    ): CompanyLeaveProgramResult {
+      const result = config.evaluate(context);
+      return {
+        contractVersion: 'company_leave_program.v1',
+        program: {
+          code: config.code,
+          displayName: config.displayName,
+          ...(config.description === undefined ? {} : { description: config.description }),
+          programKind: config.programKind ?? 'COMPANY_POLICY',
+          jurisdiction: { ...config.jurisdiction },
+          dependsOn,
+          capabilities,
+        },
+        appliesTo: asArray(config.appliesTo?.(context)),
+        eligibility: {
+          conditions: result.conditions,
+          requiredEvidence: result.requiredEvidence,
+        },
+        ...(result.entitlement === undefined ? {} : { entitlement: result.entitlement }),
+        pay: result.pay,
+        requirements: result.requirements,
+        jobProtection: result.jobProtection,
+        diagnostics: result.diagnostics,
+      };
+    },
+  };
+}

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

@@ -0,0 +1,20 @@
+import type { Duration } from './types';
+
+function duration(amount: number, unit: Duration['unit']): Duration {
+  if (!Number.isFinite(amount) || amount < 0) {
+    throw new Error('Duration amount must be a non-negative finite number.');
+  }
+  return { kind: 'duration', amount, unit };
+}
+
+export function weeks(amount: number): Duration {
+  return duration(amount, 'WEEKS');
+}
+
+export function days(amount: number): Duration {
+  return duration(amount, 'DAYS');
+}
+
+export function hours(amount: number): Duration {
+  return duration(amount, 'HOURS');
+}

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

@@ -0,0 +1,18 @@
+import type { MoneyAmount, PercentOfPay } from './types';
+
+export function percentOfPay(percent: number): PercentOfPay {
+  if (!Number.isFinite(percent) || percent < 0) {
+    throw new Error('Percent of pay must be a non-negative finite number.');
+  }
+  return { kind: 'percent_of_pay', percent };
+}
+
+export function fixedAmount(amount: string, currency: string): MoneyAmount {
+  if (amount.trim() === '') {
+    throw new Error('Fixed amount must be a non-empty decimal string.');
+  }
+  if (currency.trim() === '') {
+    throw new Error('Currency must be a non-empty ISO currency code.');
+  }
+  return { kind: 'money_amount', amount, currency };
+}

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: [],
+    };
+  }
+}