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

package/src/core/platform/custom-objects.ts

@@ -0,0 +1,269 @@
+/**
+ * Public custom-object authoring surface for the Rippling TypeScript SDK.
+ *
+ * Import this module when you want a TypeScript-first, structural definition
+ * layer for custom objects that can be reused across manifests, functions,
+ * validators, tests, and agent-authored code.
+ *
+ * The implementation lives under `core/platform/custom-objects/`, but this file
+ * is the stable public entrypoint that consumers should import from:
+ *
+ * ```ts
+ * import { defineCustomObject, text } from '@rippling/rippling-sdk/core/platform/custom-objects';
+ * ```
+ *
+ * Manifest-specific adapters for typed custom objects live under:
+ *
+ * ```ts
+ * import { registerManifestCustomObject } from '@rippling/rippling-sdk/core/platform/manifest/custom-objects';
+ * ```
+ */
+
+/** Section-definition helper and foundational schema types. */
+export { section } from './custom-objects/types';
+
+/** Type-level contracts derived from typed custom-object definitions. */
+export type {
+  AnyCustomObjectDefinition,
+  AnyFieldDefinition,
+  CategoryApiName,
+  CreateInput,
+  CustomFieldApiName,
+  CustomObjectApiName,
+  CustomObjectDefinition,
+  CustomObjectIdentity,
+  CustomRecordFields,
+  FieldDefinitions,
+  FieldNames,
+  FieldValue,
+  FileReference,
+  FormulaFieldDefinition,
+  FormulaFieldKind,
+  FormulaValueByKind,
+  LogicalCategoryName,
+  LogicalCustomFieldName,
+  LogicalCustomObjectName,
+  LookupFieldDefinition,
+  LookupReference,
+  LookupTarget,
+  NameFieldDefinition,
+  NativeModelTarget,
+  OptionalWritableFieldNames,
+  ParentChildFieldDefinition,
+  ReadonlyFieldNames,
+  RecordShape,
+  RequiredWritableFieldNames,
+  ResolvedFieldDefinition,
+  SectionDefinition,
+  SectionDefinitions,
+  StandardCreateFields,
+  StandardRecordFields,
+  TargetApiName,
+  UpdateInput,
+  WritableFieldNames,
+} from './custom-objects/types';
+
+/** Field factories and reusable schema fragments. */
+export {
+  boolean,
+  currency,
+  date,
+  datetime,
+  email,
+  file,
+  formula,
+  longText,
+  lookup,
+  nativeModel,
+  number,
+  parentChild,
+  percentage,
+  phone,
+  radio,
+  sections,
+  select,
+  text,
+  time,
+  url,
+} from './custom-objects/fields';
+
+/** Immutable definition helpers for creating and extending schemas. */
+export {
+  defineCustomObject,
+  extendCustomObject,
+  fieldNames,
+  getFieldDefinition,
+  isWritableField,
+  toCustomCategoryApiName,
+  toCustomFieldApiName,
+  toCustomObjectApiName,
+} from './custom-objects/definition';
+
+/** Runtime validation result types for schema and record checks. */
+export type { ValidationIssue, ValidationResult } from './custom-objects/validation';
+
+/** Runtime validation and typed-record helpers. */
+export {
+  asTypedRecord,
+  assertValidCreateInput,
+  assertValidUpdateInput,
+  getRecordValue,
+  validateCreateInput,
+  validateCustomObjectDefinition,
+  validateLogicalCategoryName,
+  validateLogicalCustomFieldName,
+  validateLogicalCustomObjectName,
+  validateUpdateInput,
+} from './custom-objects/validation';
+
+/** Typed RQL helper types for custom-object query and formula authoring. */
+export type {
+  CustomObjectRqlHelpers,
+  RqlComparableValue,
+  RqlFieldName,
+  RqlFieldScope,
+  RqlFieldToken,
+  RqlFragment,
+  RqlInterpolation,
+  RqlValue,
+  StandardRqlFieldName,
+} from './custom-objects/rql';
+
+/** Typed parsed-string RQL field-name types for custom-object query authoring. */
+export type { ParsedRqlFieldName, ParsedRqlStandardFieldName } from './custom-objects/typed-rql';
+
+/** Typed RQL helper factories for custom-object query authoring. */
+export { createRqlHelpers } from './custom-objects/rql';
+
+/** Parsed-string RQL compiler that validates logical field names and value types. */
+export { typedRql } from './custom-objects/typed-rql';
+
+/** Typed category-definition and lifecycle types for custom-object metadata. */
+export type {
+  CustomObjectCategoryDefinition,
+  CustomObjectCategoryLifecycleAction,
+  CustomObjectCategoryMutationOptions,
+  ProvisionedCustomObjectCategory,
+  ReconciledCustomObjectCategory,
+} from './custom-objects/category';
+
+/** Typed category-definition helpers for custom-object metadata. */
+export {
+  buildObjectCategoryCreateParams,
+  buildObjectCategoryUpdateParams,
+  defineCustomObjectCategory,
+  deleteCustomObjectCategoryDefinition,
+  provisionCustomObjectCategoryDefinition,
+  provisionCustomObjectCategoryDefinitions,
+  reconcileCustomObjectCategoryDefinition,
+  reconcileCustomObjectCategoryDefinitions,
+} from './custom-objects/category';
+
+/** Provisioning result and option types for the REST custom-object helpers. */
+export type {
+  ProvisionCustomObjectOptions,
+  ProvisionCustomObjectsOptions,
+  ProvisionableFieldParams,
+  ProvisionedCustomObject,
+} from './custom-objects/provisioning';
+
+/** Helpers that compile typed schemas into low-level REST custom-object payloads. */
+export {
+  buildCustomObjectCreateParams,
+  buildCustomObjectNameFieldDetails,
+  buildCustomObjectUpdateParams,
+  buildProvisionableFieldParams,
+  provisionCustomObjectDefinition,
+  provisionCustomObjectDefinitions,
+} from './custom-objects/provisioning';
+
+/** Schema-lifecycle types for reconciling typed definitions with remote metadata. */
+export type {
+  CustomObjectLifecycleAction,
+  ReconcileCustomObjectDefinitionOptions,
+  ReconcileCustomObjectDefinitionsOptions,
+  ReconciledCustomObject,
+  ReconciledCustomObjectField,
+} from './custom-objects/lifecycle';
+
+/** Schema-lifecycle helpers for reconciling typed definitions with remote metadata. */
+export {
+  deleteCustomObjectDefinition,
+  reconcileCustomObjectDefinition,
+  reconcileCustomObjectDefinitions,
+} from './custom-objects/lifecycle';
+
+/** Typed schema-manager classes that bind definitions to a specific SDK client. */
+export type {} from './custom-objects/schema-manager';
+
+/** Typed schema-manager classes that bind definitions to a specific SDK client. */
+export {
+  COSchemaManager,
+  CustomObjectSchemaManager,
+  TypedCustomObjectCategoryManager,
+  TypedCustomObjectSchemaManager,
+} from './custom-objects/schema-manager';
+
+/** Low-level typed field-metadata payloads used by the generated REST resources. */
+export type {
+  ChoiceCustomObjectFieldDataType,
+  CurrencyCustomObjectFieldDataType,
+  CustomObjectFieldDataType,
+  CustomObjectFieldDerivedAggregationFilter,
+  CustomObjectFieldDerivedAggregatedField,
+  CustomObjectFieldFormulaAttrMetas,
+  CustomObjectFieldRqlDefinition,
+  CustomObjectFieldSection,
+  CustomObjectFieldSectionConfig,
+  CustomObjectFieldType,
+  CustomObjectNameFieldDetails,
+  DateCustomObjectFieldDataType,
+  DatetimeCustomObjectFieldDataType,
+  EmailCustomObjectFieldDataType,
+  FileCustomObjectFieldDataType,
+  LongTextCustomObjectFieldDataType,
+  NumberCustomObjectFieldDataType,
+  PercentageCustomObjectFieldDataType,
+  PhoneNumberCustomObjectFieldDataType,
+  ReferenceCustomObjectFieldDataType,
+  TextCustomObjectFieldDataType,
+  TimeCustomObjectFieldDataType,
+  URLCustomObjectFieldDataType,
+} from '../../resources/custom-objects/fields';
+
+/** Typed record-manager adapter, error, and pagination types. */
+export type {
+  CustomObjectManagerOptions,
+  CustomObjectRecordAdapter,
+  CustomObjectRecordBulkCreateRequest,
+  CustomObjectRecordBulkDeleteRequest,
+  CustomObjectRecordBulkUpdateRequest,
+  CustomObjectRecordQueryResponse,
+  CustomObjectRecordsClient,
+  InMemoryCustomObjectRecordAdapterOptions,
+  TypedBatchWriteOptions,
+  TypedBulkUpdateInput,
+  TypedRecordPage,
+  TypedRecordPageOptions,
+  TypedRecordQueryOptions,
+} from './custom-objects/manager';
+
+/** Typed record-manager utilities for CRUD, batch operations, and records-resource/in-memory adapters. */
+export {
+  COManager,
+  CustomObjectManager,
+  CustomObjectRecordValidationError,
+  InMemoryCustomObjectRecordAdapter,
+  TypedCustomObjectRecordManager,
+  createCustomObjectRecordAdapter,
+} from './custom-objects/manager';
+
+/** Shared function-runtime bootstrap types for custom-object-backed handlers. */
+export type {
+  CreateCustomObjectFunctionRuntimeOptions,
+  CustomObjectFunctionRuntime,
+  CustomObjectFunctionRuntimeClient,
+} from './custom-objects/function-runtime';
+
+/** Small bootstrap helper that creates one SDK client plus typed record managers for a function invocation. */
+export { createCustomObjectFunctionRuntime } from './custom-objects/function-runtime';

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 };
+}