@rippling/rippling-sdk 0.2.0-alpha.76 → 0.2.0-alpha.78

package/src/lib/manifest/custom-field.ts

@@ -0,0 +1,309 @@
+import { generateId } from './_helpers';
+import { CustomFieldSection } from './custom-field-section';
+import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
+import type { ManifestComponentDeletion, ManifestScope } from './manifest-builder';
+import { requireObjectComponentField, requireStringComponentField } from './_existing-component-fields';
+
+export const CUSTOM_FIELD_TYPES = [
+  'TEXT',
+  'DATE',
+  'NUMBER',
+  'CURRENCY',
+  'PERCENTAGE',
+  'SELECT',
+  'FILE',
+  'ID',
+  'RADIO',
+  'TEXTAREA',
+  'RANGE',
+  'REFERENCE_ID',
+  'BOOLEAN',
+  'ADDRESS',
+  'OG_REFERENCE_FIELD',
+  'EMAIL',
+  'URL',
+] as const;
+
+export type CustomFieldType = (typeof CUSTOM_FIELD_TYPES)[number];
+export type CustomFieldApiName = `${string}__cfv2`;
+
+export type CustomFieldUniqueIDCharacterType = 'DIGITS_ONLY' | 'TEXT_ONLY' | 'DIGITS_TEXT_BOTH';
+
+type CustomFieldSimpleType = Exclude<
+  CustomFieldType,
+  'NUMBER' | 'CURRENCY' | 'SELECT' | 'RADIO' | 'ID' | 'OG_REFERENCE_FIELD'
+>;
+
+export type CustomFieldDataType =
+  | { fieldType: CustomFieldSimpleType }
+  | { fieldType: 'NUMBER'; decimalPlaces?: number | null }
+  | { fieldType: 'CURRENCY'; currency?: string | null }
+  | { fieldType: 'SELECT' | 'RADIO'; options: readonly string[] }
+  | {
+      fieldType: 'ID';
+      numberOfCharacters?: number | null;
+      characterType?: CustomFieldUniqueIDCharacterType | null;
+    }
+  | { fieldType: 'OG_REFERENCE_FIELD'; referencedModelRqlName: string };
+
+export type CustomFieldPermissionClassification =
+  | 'BASIC_PERSONAL_INFO'
+  | 'PERSONAL_INFO'
+  | 'SENSITIVE_PERSONAL_INFO'
+  | 'BASIC_EMPLOYMENT_INFO'
+  | 'EMPLOYMENT_INFO'
+  | 'SENSITIVE_EMPLOYMENT_INFO';
+
+export type CustomFieldReadAccess = 'ALL_ACCESS' | 'ADMIN_ACCESS' | 'ADMIN_AND_EMPLOYEE_ACCESS';
+
+export type CustomFieldWriteAccess =
+  | 'EMPLOYEE_ACCESS'
+  | 'ADMIN_ACCESS'
+  | 'ADMIN_AND_EMPLOYEE_ACCESS'
+  | 'NO_ACCESS';
+
+export type CustomFieldCollectionTiming = 'NONE' | 'HIRING' | 'ONBOARDING' | 'TERMINATING';
+
+export type CustomFieldDefaultValue =
+  | { value: string; rqlDefinitionFormula?: never }
+  | { value?: never; rqlDefinitionFormula: string };
+
+interface CustomFieldCommonProps {
+  fieldId?: string;
+  name: string;
+  section: CustomFieldSection;
+  modelRqlName: string;
+  dataType: CustomFieldDataType;
+  apiName: CustomFieldApiName;
+  fieldPermissionClassification?: CustomFieldPermissionClassification | null;
+  fieldReadAccess?: CustomFieldReadAccess | null;
+  fieldWriteAccess?: CustomFieldWriteAccess | null;
+  applicableGroup?: string | null;
+  description?: string | null;
+  displayOrder?: number | null;
+}
+
+export type CustomFieldProps = CustomFieldCommonProps &
+  (
+    | {
+        rqlDefinitionFormula: string;
+        collectDuring?: null;
+        required?: null;
+        tip?: null;
+        defaultValue?: null;
+      }
+    | {
+        rqlDefinitionFormula?: null;
+        collectDuring?: CustomFieldCollectionTiming | null;
+        required?: boolean | null;
+        tip?: string | null;
+        defaultValue?: CustomFieldDefaultValue | null;
+      }
+  );
+
+function cloneJson<T>(value: T): T {
+  if (value == null) return value;
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function customFieldDataTypeFromWire(dataType: Record<string, any>): CustomFieldDataType {
+  const fieldType = requireStringComponentField(
+    dataType,
+    'field_type',
+    CustomField.componentType,
+  ) as CustomFieldType;
+  switch (fieldType) {
+    case 'NUMBER':
+      return {
+        fieldType,
+        decimalPlaces: (dataType['num_of_decimal_places'] as number | null | undefined) ?? null,
+      };
+    case 'CURRENCY':
+      return { fieldType, currency: (dataType['currency'] as string | null | undefined) ?? null };
+    case 'SELECT':
+    case 'RADIO': {
+      const options = dataType['options_list'];
+      if (!Array.isArray(options) || !options.every((option) => typeof option === 'string')) {
+        throw new TypeError(`CUSTOM_FIELD_V2 data_type.options_list must be a string array.`);
+      }
+      return { fieldType, options };
+    }
+    case 'ID':
+      return {
+        fieldType,
+        numberOfCharacters: (dataType['num_of_chars'] as number | null | undefined) ?? null,
+        characterType:
+          (dataType['type_of_chars'] as CustomFieldUniqueIDCharacterType | null | undefined) ?? null,
+      };
+    case 'OG_REFERENCE_FIELD':
+      return {
+        fieldType,
+        referencedModelRqlName: requireStringComponentField(
+          dataType,
+          'og_model_rql_name',
+          CustomField.componentType,
+        ),
+      };
+    default:
+      if (!(CUSTOM_FIELD_TYPES as readonly string[]).includes(fieldType)) {
+        throw new TypeError(`Unsupported CUSTOM_FIELD_V2 field_type: ${fieldType}`);
+      }
+      return { fieldType };
+  }
+}
+
+/** A Custom Field V2 field on a native or custom object. */
+export class CustomField {
+  static readonly componentType = 'CUSTOM_FIELD_V2' as const;
+
+  static toDeletionIdentifier(customFieldId: string): ManifestComponentDeletion {
+    return { type: CustomField.componentType, cfv2_id: customFieldId };
+  }
+
+  private readonly _fieldId: string;
+  private readonly props: CustomFieldProps;
+
+  constructor(scope: ManifestScope, props: CustomFieldProps) {
+    if (!props.apiName.endsWith('__cfv2')) {
+      throw new Error(`Custom Field V2 api_name must end with __cfv2: ${props.apiName}`);
+    }
+    if (props.section.getModelRqlName() !== props.modelRqlName) {
+      throw new Error(
+        `Custom field "${props.apiName}" section belongs to "${props.section.getModelRqlName()}", ` +
+          `but the field belongs to "${props.modelRqlName}".`,
+      );
+    }
+    this._fieldId = props.fieldId ?? generateId('cfv2');
+    this.props = {
+      ...props,
+      dataType: cloneJson(props.dataType),
+    };
+    scope._register(this);
+  }
+
+  static loadFromExisting(
+    fieldIdOrApiName: string,
+    options: ExistingManifestContextOptions = {},
+  ): CustomField {
+    return getExistingManifestContext(options).loadCustomField(fieldIdOrApiName);
+  }
+
+  /** @internal Hydrates a custom field from existing manifest wire JSON. */
+  static _fromExistingComponent(
+    scope: ManifestScope,
+    component: Record<string, any>,
+    section: CustomFieldSection,
+  ): CustomField {
+    const dataType = requireObjectComponentField(component, 'data_type', CustomField.componentType);
+    const defaultValue = component['default_value'] as Record<string, any> | null | undefined;
+    const formula = component['rql_definition_formula'];
+    const applicableGroup =
+      component['applicable_group'] == null ?
+        null
+      : requireObjectComponentField(component, 'applicable_group', CustomField.componentType);
+    const common = {
+      fieldId: requireStringComponentField(component, 'obj_id', CustomField.componentType),
+      name: requireStringComponentField(component, 'name', CustomField.componentType),
+      section,
+      modelRqlName: requireStringComponentField(component, 'model_rql_name', CustomField.componentType),
+      apiName: requireStringComponentField(
+        component,
+        'api_name',
+        CustomField.componentType,
+      ) as CustomFieldApiName,
+      dataType: customFieldDataTypeFromWire(dataType),
+      fieldPermissionClassification:
+        (component['field_permission_classification'] as
+          | CustomFieldPermissionClassification
+          | null
+          | undefined) ?? null,
+      fieldReadAccess: (component['field_read_access'] as CustomFieldReadAccess | null | undefined) ?? null,
+      fieldWriteAccess:
+        (component['field_write_access'] as CustomFieldWriteAccess | null | undefined) ?? null,
+      applicableGroup:
+        applicableGroup == null ? null : (
+          requireStringComponentField(applicableGroup, 'me_obj_id', CustomField.componentType)
+        ),
+      description: (component['description'] as string | null | undefined) ?? null,
+      displayOrder: (component['display_order'] as number | null | undefined) ?? null,
+    };
+    if (typeof formula === 'string') {
+      return new CustomField(scope, {
+        ...common,
+        rqlDefinitionFormula: formula,
+        collectDuring: null,
+        required: null,
+        tip: null,
+        defaultValue: null,
+      });
+    }
+
+    const defaultValueFormula = defaultValue?.['rql_definition_formula'];
+    const staticDefaultValue = defaultValue?.['value'];
+    return new CustomField(scope, {
+      ...common,
+      rqlDefinitionFormula: null,
+      collectDuring: (component['collect_during'] as CustomFieldCollectionTiming | null | undefined) ?? null,
+      required: (component['required'] as boolean | null | undefined) ?? null,
+      tip: (component['tip'] as string | null | undefined) ?? null,
+      defaultValue:
+        typeof defaultValueFormula === 'string' ? { rqlDefinitionFormula: defaultValueFormula }
+        : typeof staticDefaultValue === 'string' ? { value: staticDefaultValue }
+        : null,
+    });
+  }
+
+  getFieldId(): string {
+    return this._fieldId;
+  }
+
+  getApiName(): CustomFieldApiName {
+    return this.props.apiName;
+  }
+
+  getModelRqlName(): string {
+    return this.props.modelRqlName;
+  }
+
+  toDict(): Record<string, any> {
+    const dataType = this.props.dataType;
+    const defaultValue = this.props.defaultValue;
+    return {
+      type: CustomField.componentType,
+      obj_id: this._fieldId,
+      name: this.props.name,
+      section: this.props.section.getSectionId(),
+      model_rql_name: this.props.modelRqlName,
+      data_type: {
+        type: CustomField.componentType,
+        field_type: dataType.fieldType,
+        options_list: 'options' in dataType ? [...dataType.options] : null,
+        currency: 'currency' in dataType ? dataType.currency ?? null : null,
+        num_of_decimal_places: 'decimalPlaces' in dataType ? dataType.decimalPlaces ?? null : null,
+        num_of_chars: 'numberOfCharacters' in dataType ? dataType.numberOfCharacters ?? null : null,
+        type_of_chars: 'characterType' in dataType ? dataType.characterType ?? null : null,
+        og_model_rql_name: 'referencedModelRqlName' in dataType ? dataType.referencedModelRqlName : null,
+      },
+      api_name: this.props.apiName,
+      field_permission_classification: this.props.fieldPermissionClassification ?? null,
+      field_read_access: this.props.fieldReadAccess ?? null,
+      field_write_access: this.props.fieldWriteAccess ?? null,
+      collect_during: this.props.collectDuring ?? null,
+      applicable_group: this.props.applicableGroup ?? null,
+      description: this.props.description ?? null,
+      required: this.props.required ?? null,
+      tip: this.props.tip ?? null,
+      rql_definition_formula: this.props.rqlDefinitionFormula ?? null,
+      default_value:
+        defaultValue == null ? null : (
+          {
+            type: CustomField.componentType,
+            value: 'value' in defaultValue ? defaultValue.value : null,
+            rql_definition_formula:
+              'rqlDefinitionFormula' in defaultValue ? defaultValue.rqlDefinitionFormula : null,
+          }
+        ),
+      display_order: this.props.displayOrder ?? null,
+    };
+  }
+}

package/src/lib/manifest/custom-object-action.ts

@@ -41,9 +41,9 @@ export class CustomObjectAction {
 
   private readonly _actionId: string;
   private readonly _objectRqlName: string;
-  private readonly _name: string;
-  private readonly _functionApiName: string;
-  private readonly _visibilityPreferences: CustomObjectActionVisibilityPreference[];
+  private _name: string;
+  private _functionApiName: string;
+  private _visibilityPreferences: CustomObjectActionVisibilityPreference[];
 
   constructor(customObject: CustomObject, props: CustomObjectActionProps) {
     if (!props.name.trim()) throw new Error('CustomObjectAction: name cannot be empty');
@@ -86,6 +86,25 @@ export class CustomObjectAction {
     return this._actionId;
   }
 
+  /** Replaces the action's display name. */
+  setName(name: string): this {
+    if (!name.trim()) throw new Error('CustomObjectAction: name cannot be empty');
+    this._name = name;
+    return this;
+  }
+
+  /** Replaces the function invoked by this action. */
+  setFunction(fn: ManifestFunction): this {
+    this._functionApiName = fn.getApiName();
+    return this;
+  }
+
+  /** Replaces the views where this action is shown. */
+  setVisibilityPreferences(preferences: CustomObjectActionVisibilityPreference[]): this {
+    this._visibilityPreferences = [...preferences];
+    return this;
+  }
+
   toDict(): Record<string, any> {
     return {
       type: CustomObjectAction.componentType,

package/src/lib/manifest/existing-manifest-context.ts

@@ -1,5 +1,7 @@
 import { App } from './app';
 import { Category } from './category';
+import { CustomField } from './custom-field';
+import { CustomFieldSection } from './custom-field-section';
 import { CustomObject } from './custom-object';
 import { CustomObjectAction } from './custom-object-action';
 import { CustomObjectFieldSection } from './custom-object-field-section';
@@ -189,6 +191,24 @@ export class ExistingManifestContext {
     return this.loadCustomObjectComponent(component);
   }
 
+  loadCustomFieldSection(sectionId: string): CustomFieldSection {
+    const component = this.findUnique(
+      'CUSTOM_FIELD_SECTION',
+      (candidate) => candidate['obj_id'] === sectionId,
+      `CUSTOM_FIELD_SECTION ${sectionId}`,
+    );
+    return this.loadCustomFieldSectionComponent(component);
+  }
+
+  loadCustomField(fieldIdOrApiName: string): CustomField {
+    const component = this.findUnique(
+      'CUSTOM_FIELD_V2',
+      (candidate) => candidate['obj_id'] === fieldIdOrApiName || candidate['api_name'] === fieldIdOrApiName,
+      `CUSTOM_FIELD_V2 ${fieldIdOrApiName}`,
+    );
+    return this.loadCustomFieldComponent(component);
+  }
+
   loadFieldSection(
     sectionIdOrQualifiedId: string,
     options: ExistingManifestObjectOptions = {},
@@ -309,6 +329,10 @@ export class ExistingManifestContext {
         return this.loadCategoryComponent(component);
       case 'CUSTOM_OBJECT':
         return this.loadCustomObjectComponent(component);
+      case 'CUSTOM_FIELD_SECTION':
+        return this.loadCustomFieldSectionComponent(component);
+      case 'CUSTOM_FIELD_V2':
+        return this.loadCustomFieldComponent(component);
       case 'CUSTOM_OBJECT_ACTION':
         return this.loadCustomObjectActionComponent(component);
       case 'CUSTOM_OBJECT_FIELD_SECTION':
@@ -362,6 +386,24 @@ export class ExistingManifestContext {
     });
   }
 
+  private loadCustomFieldSectionComponent(component: Record<string, any>): CustomFieldSection {
+    const sectionId = requireStringComponentField(component, 'obj_id', CustomFieldSection.componentType);
+    const cacheKey = this.cacheKey('CUSTOM_FIELD_SECTION', sectionId);
+    return this.getOrLoad(cacheKey, () =>
+      CustomFieldSection._fromExistingComponent(this.getManifestBuilder(), component),
+    );
+  }
+
+  private loadCustomFieldComponent(component: Record<string, any>): CustomField {
+    const fieldId = requireStringComponentField(component, 'obj_id', CustomField.componentType);
+    const sectionId = requireStringComponentField(component, 'section', CustomField.componentType);
+    const cacheKey = this.cacheKey('CUSTOM_FIELD_V2', fieldId);
+    return this.getOrLoad(cacheKey, () => {
+      const section = this.loadCustomFieldSection(sectionId);
+      return CustomField._fromExistingComponent(this.getManifestBuilder(), component, section);
+    });
+  }
+
   private loadFieldSectionComponent(component: Record<string, any>): CustomObjectFieldSection {
     const modelName = requireStringComponentField(
       component,

package/src/lib/manifest/index.ts

@@ -20,6 +20,24 @@ export { App, type AppIcon, type AppPage, type AppProps } from './app';
 
 export { Category, type CategoryProps } from './category';
 
+export {
+  CUSTOM_FIELD_TYPES,
+  CustomField,
+  CustomField as CustomFieldV2,
+  type CustomFieldApiName,
+  type CustomFieldCollectionTiming,
+  type CustomFieldDataType,
+  type CustomFieldDefaultValue,
+  type CustomFieldPermissionClassification,
+  type CustomFieldProps,
+  type CustomFieldReadAccess,
+  type CustomFieldType,
+  type CustomFieldUniqueIDCharacterType,
+  type CustomFieldWriteAccess,
+} from './custom-field';
+
+export { CustomFieldSection, type CustomFieldSectionProps } from './custom-field-section';
+
 export {
   CustomObject,
   type CustomObjectFieldInput,

package/src/lib/manifest/manifest-builder.ts

@@ -16,6 +16,8 @@ export interface ManifestComponent {
 export type ManifestComponentType =
   | 'CUSTOM_APP'
   | 'CUSTOM_CATEGORY'
+  | 'CUSTOM_FIELD_SECTION'
+  | 'CUSTOM_FIELD_V2'
   | 'CUSTOM_OBJECT'
   | 'CUSTOM_OBJECT_ACTION'
   | 'CUSTOM_OBJECT_FIELD'

package/src/resources/custom-fields.ts

@@ -77,6 +77,12 @@ export interface CustomFieldListResponse {
    */
   description?: string;
 
+  /**
+   * The available choice values for SELECT and RADIO custom fields. Null for other
+   * field types.
+   */
+  options?: Array<string>;
+
   /**
    * Whether the custom field is required.
    */

package/src/resources/index.ts

@@ -314,6 +314,11 @@ export {
   type LeaveBalanceRetrieveParams,
   type LeaveBalancesPageCursorURL,
 } from './leave-balances';
+export {
+  LeaveProgramEvaluations,
+  type LeaveProgramEvaluationCreateResponse,
+  type LeaveProgramEvaluationCreateParams,
+} from './leave-program-evaluations';
 export {
   LeaveRequests,
   type LeaveRequest,

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

@@ -0,0 +1,88 @@
+// 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.
+   */
+  leave_plan: unknown;
+
+  /**
+   * Distinct evidence gaps reported by evaluated eligibility rules.
+   */
+  missing_evidence: Array<string>;
+
+  /**
+   * Per-program rule outputs in evaluation order.
+   */
+  program_results: Array<unknown>;
+}
+
+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 date the child entered the family for bonding leave programs.
+   */
+  child_entered_family_date?: string;
+
+  /**
+   * Optional parental leave relationship type for parental leave programs.
+   */
+  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>;
+}
+
+export declare namespace LeaveProgramEvaluations {
+  export {
+    type LeaveProgramEvaluationCreateResponse as LeaveProgramEvaluationCreateResponse,
+    type LeaveProgramEvaluationCreateParams as LeaveProgramEvaluationCreateParams,
+  };
+}

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.2.0-alpha.76'; // x-release-please-version
+export const VERSION = '0.2.0-alpha.78'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.2.0-alpha.76";
+export declare const VERSION = "0.2.0-alpha.78";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.2.0-alpha.76";
+export declare const VERSION = "0.2.0-alpha.78";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.2.0-alpha.76'; // x-release-please-version
+exports.VERSION = '0.2.0-alpha.78'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.2.0-alpha.76'; // x-release-please-version
+export const VERSION = '0.2.0-alpha.78'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map