@rippling/rippling-sdk 0.2.0-alpha.34 → 0.2.0-alpha.36

package/src/lib/manifest/field.ts

@@ -1,24 +1,3 @@
-/*
- * Fields for Rippling custom objects (CUSTOM_OBJECT_FIELD v2).
- * Hand-written (not Stainless-generated); mirrors custom_object_field.py.
- *
- * Each concrete field type is its own class that extends the internal `Field`
- * base. Construct like any other component:
- *
- *     new TextField(customObject, { apiName, displayName, ... });
- *     new LookupField(customObject, { apiName, target: otherCo, ... });
- *     new SummaryField(customObject, { apiName, aggregates, using, lookup, ... });
- *
- * This mirrors AWS CDK's per-variant-class pattern (e.g.
- * `new codepipeline_actions.GitHubSourceAction({...})` rather than a single
- * Action class with 30 static factories). Every subclass serializes to the
- * same `CUSTOM_OBJECT_FIELD` wire shape, discriminated by `data_type.field_type`.
- *
- * The parent CO is the first positional arg (the "scope") — its `api_name`
- * becomes `custom_object_api_name` at serialization, and the field
- * auto-registers with the manifest via the CO's scope chain.
- */
-
 import {
   FILTER_OPERATORS_BY_TYPE,
   type FieldType,
@@ -29,12 +8,34 @@ import {
 import type { CustomObject } from './custom-object';
 import type { CustomObjectFieldSection } from './custom-object-field-section';
 
-/** Summary filter. Lives here (not `_helpers.ts`) to avoid a circular import with `Field`. */
+/**
+ * A filter condition applied to a {@link SummaryField}.
+ *
+ * Filters restrict which child records are included in the aggregation.
+ * Only scalar field types are supported as filter fields — see
+ * `FILTER_OPERATORS_BY_TYPE` in `_helpers.ts` for the per-type operator allow-list.
+ */
 export interface SummaryFilter {
-  /** Filter field on the child CO. */
+  /**
+   * The child-CO field to filter on.
+   *
+   * Required. Must be a scalar field on the same child object as `lookup`.
+   * Cannot be a formula field, summary field, or the `lookup` field itself.
+   */
   field: Field;
+  /**
+   * Comparison operator. Allowed operators depend on the field's type —
+   * text/boolean fields support `=` and `!=`; numeric/date fields additionally
+   * support `>`, `>=`, `<`, `<=`.
+   *
+   * Required.
+   */
   operator: SummaryFilterOperator;
-  /** Raw RQL value, e.g. `"'Active'"`, `"50"`, `"true"`, `"DATE(2026,1,1)"`. */
+  /**
+   * Raw RQL value string, e.g. `"'Active'"`, `"50"`, `"true"`, `"DATE(2026,1,1)"`.
+   *
+   * Required.
+   */
   value: string;
 }
 
@@ -94,9 +95,28 @@ export interface FieldProps {
 // ────────────────────────────────────────────────────────────────────────
 
 /**
- * Base class for every custom-object field. Prefer the concrete subclasses
- * (`TextField`, `LookupField`, `SummaryField`, …). Construct `Field` directly
- * only for wire-types the SDK doesn't yet model.
+ * Base class for every custom-object field.
+ *
+ * Prefer the typed subclasses (`TextField`, `NumberField`, `LookupField`, …) over
+ * constructing `Field` directly. Use `Field` only for wire-level field types the
+ * SDK does not yet model with a dedicated subclass.
+ *
+ * All field classes share the same scope-first CDK pattern: pass the parent
+ * {@link CustomObject} as the first argument and the field auto-registers with
+ * the manifest. Every field api_name must end with `__c`.
+ *
+ * @example
+ * ```ts
+ * // Prefer typed subclasses:
+ * const firstName = new TextField(memberObj, {
+ *   apiName: 'first_name__c',
+ *   displayName: 'First name',
+ *   required: true,
+ *   maxLength: 80,
+ * });
+ * ```
+ *
+ * @see {@link TextField}, {@link NumberField}, {@link LookupField}, {@link SummaryField}
  */
 export class Field {
   private readonly _fieldApiName: string;
@@ -114,7 +134,11 @@ export class Field {
   private readonly _summarySpec: SummarySpec | null;
   private readonly _derivedAggregatedFieldStatic: Record<string, any> | null;
 
-  /** Build a new field; enforces `__c` suffix and folds props into `data_type`. */
+  /**
+   * @param customObject - The custom object this field belongs to.
+   * @param props - Field configuration. See {@link FieldProps}.
+   * @throws {Error} If `props.apiName` does not end with `__c`.
+   */
   constructor(customObject: CustomObject, props: FieldProps) {
     validateApiName(props.apiName);
     this._fieldApiName = props.apiName;
@@ -150,38 +174,42 @@ export class Field {
 
   // ── Getters ────────────────────────────────────────────────────────────
 
-  /** Backend api_name for this field. */
+  /** Returns the api_name of this field (e.g. `'first_name__c'`). */
   getApiName(): string {
     return this._fieldApiName;
   }
-  /** Human-readable display name. */
+  /** Returns the display name of this field. */
   getDisplayName(): string {
     return this._fieldDisplayName;
   }
-  /** api_name of the CustomObject this field lives on. */
+  /** Returns the api_name of the custom object this field belongs to. */
   getCustomObjectApiName(): string {
     return this._customObjectApiName;
   }
-  /** Resolved `data_type.field_type`, or null if unset. */
+  /** Returns the resolved `field_type` (e.g. `'TEXT'`), or `null` if unset. */
   getFieldType(): FieldType | null {
     return (this._dataType['field_type'] as FieldType | undefined) ?? null;
   }
-  /** Raw `data_type` dict (read-only view). */
+  /** Returns a read-only view of the raw `data_type` dict. */
   getDataType(): Readonly<Record<string, any>> {
     return this._dataType;
   }
-  /** True if this field is a simple formula field. */
+  /** Returns `true` if this is a formula (computed) field. */
   isFormula(): boolean {
     return this._derivedFieldFormula != null;
   }
-  /** True if this field is a summary/rollup field. */
+  /** Returns `true` if this is a summary (rollup) field. */
   isSummary(): boolean {
     return this._summarySpec != null;
   }
 
   // ── Serialization ──────────────────────────────────────────────────────
 
-  /** Serialize to the backend `CUSTOM_OBJECT_FIELD` wire shape. */
+  /**
+   * Serializes this field to the wire format consumed by the manifest install endpoint.
+   *
+   * @returns A plain object with `type: 'CUSTOM_OBJECT_FIELD'`.
+   */
   toDict(): Record<string, any> {
     return {
       type: 'CUSTOM_OBJECT_FIELD',
@@ -243,54 +271,68 @@ export class Field {
 
 // ── Text-like ──────────────────────────────────────────────────────────
 
+/** Initialization properties for {@link TextField}. */
 export interface TextFieldProps extends CommonFieldProps {
+  /** Whether a value is required on save. Optional. */
   required?: boolean;
+  /** Whether values must be unique across records. Optional. */
   unique?: boolean;
+  /** Maximum character length. Optional. */
   maxLength?: number;
 }
-/** Single-line text. */
+/** Single-line text field. */
 export class TextField extends Field {
   constructor(customObject: CustomObject, props: TextFieldProps) {
     super(customObject, { ...props, fieldType: 'TEXT' });
   }
 }
 
+/** Initialization properties for {@link LongTextField}. */
 export interface LongTextFieldProps extends CommonFieldProps {
+  /** Whether a value is required on save. Optional. */
   required?: boolean;
+  /** Maximum character length. Optional. */
   maxLength?: number;
 }
-/** Multi-line text. */
+/** Multi-line text field. */
 export class LongTextField extends Field {
   constructor(customObject: CustomObject, props: LongTextFieldProps) {
     super(customObject, { ...props, fieldType: 'LONG_TEXT' });
   }
 }
 
+/** Initialization properties for {@link EmailField}. */
 export interface EmailFieldProps extends CommonFieldProps {
+  /** Whether a value is required on save. Optional. */
   required?: boolean;
+  /** Whether values must be unique across records. Optional. */
   unique?: boolean;
 }
-/** Email address (format-validated by the UI). */
+/** Email address field. Format is validated by the Rippling UI. */
 export class EmailField extends Field {
   constructor(customObject: CustomObject, props: EmailFieldProps) {
     super(customObject, { ...props, fieldType: 'EMAIL' });
   }
 }
 
+/** Initialization properties for {@link UrlField}. */
 export interface UrlFieldProps extends CommonFieldProps {
+  /** Whether a value is required on save. Optional. */
   required?: boolean;
 }
-/** URL (format-validated by the UI). */
+/** URL field. Format is validated by the Rippling UI. */
 export class UrlField extends Field {
   constructor(customObject: CustomObject, props: UrlFieldProps) {
     super(customObject, { ...props, fieldType: 'URL' });
   }
 }
 
+/** Initialization properties for {@link PhoneField}. */
 export interface PhoneFieldProps extends CommonFieldProps {
+  /** Whether a value is required on save. Optional. */
   required?: boolean;
 }
-/** Phone number. */
+/** Phone number field. */
 export class PhoneField extends Field {
   constructor(customObject: CustomObject, props: PhoneFieldProps) {
     super(customObject, { ...props, fieldType: 'PHONE_NUMBER' });
@@ -299,35 +341,46 @@ export class PhoneField extends Field {
 
 // ── Numeric ────────────────────────────────────────────────────────────
 
+/** Initialization properties for {@link NumberField}. */
 export interface NumberFieldProps extends CommonFieldProps {
+  /** Whether a value is required on save. Optional. */
   required?: boolean;
+  /** Whether values must be unique across records. Optional. */
   unique?: boolean;
+  /** Number of decimal places to display and store. Optional. */
   decimalPlaces?: number;
 }
-/** Number. */
+/** Numeric field. */
 export class NumberField extends Field {
   constructor(customObject: CustomObject, props: NumberFieldProps) {
     super(customObject, { ...props, fieldType: 'NUMBER' });
   }
 }
 
+/** Initialization properties for {@link CurrencyField}. */
 export interface CurrencyFieldProps extends CommonFieldProps {
+  /** Whether a value is required on save. Optional. */
   required?: boolean;
+  /** ISO 4217 currency code (e.g. `'USD'`). Optional. Forwarded to the wire only when set. */
   currency?: string;
+  /** Number of decimal places. Optional. */
   decimalPlaces?: number;
 }
-/** Currency amount; `currency` is forwarded only when set. */
+/** Currency amount field. */
 export class CurrencyField extends Field {
   constructor(customObject: CustomObject, props: CurrencyFieldProps) {
     super(customObject, { ...props, fieldType: 'CURRENCY' });
   }
 }
 
+/** Initialization properties for {@link PercentageField}. */
 export interface PercentageFieldProps extends CommonFieldProps {
+  /** Whether a value is required on save. Optional. */
   required?: boolean;
+  /** Number of decimal places. Optional. */
   decimalPlaces?: number;
 }
-/** Percentage. */
+/** Percentage field. */
 export class PercentageField extends Field {
   constructor(customObject: CustomObject, props: PercentageFieldProps) {
     super(customObject, { ...props, fieldType: 'PERCENTAGE' });
@@ -336,30 +389,36 @@ export class PercentageField extends Field {
 
 // ── Date/time ──────────────────────────────────────────────────────────
 
+/** Initialization properties for {@link DateField}. */
 export interface DateFieldProps extends CommonFieldProps {
+  /** Whether a value is required on save. Optional. */
   required?: boolean;
 }
-/** Date (no time). */
+/** Date field (no time component). */
 export class DateField extends Field {
   constructor(customObject: CustomObject, props: DateFieldProps) {
     super(customObject, { ...props, fieldType: 'DATE' });
   }
 }
 
+/** Initialization properties for {@link DatetimeField}. */
 export interface DatetimeFieldProps extends CommonFieldProps {
+  /** Whether a value is required on save. Optional. */
   required?: boolean;
 }
-/** Date + time. */
+/** Date and time field. */
 export class DatetimeField extends Field {
   constructor(customObject: CustomObject, props: DatetimeFieldProps) {
     super(customObject, { ...props, fieldType: 'DATETIME' });
   }
 }
 
+/** Initialization properties for {@link TimeField}. */
 export interface TimeFieldProps extends CommonFieldProps {
+  /** Whether a value is required on save. Optional. */
   required?: boolean;
 }
-/** Time of day. */
+/** Time-of-day field. */
 export class TimeField extends Field {
   constructor(customObject: CustomObject, props: TimeFieldProps) {
     super(customObject, { ...props, fieldType: 'TIME' });
@@ -368,34 +427,48 @@ export class TimeField extends Field {
 
 // ── Choice ─────────────────────────────────────────────────────────────
 
+/** Initialization properties for {@link SelectField}. */
 export interface SelectFieldProps extends CommonFieldProps {
-  /** Required choice list. */
+  /**
+   * The list of selectable options (e.g. `['Active', 'Frozen', 'Cancelled']`).
+   *
+   * Required.
+   */
   options: string[];
+  /** Whether a value is required on save. Optional. */
   required?: boolean;
 }
-/** Dropdown select. */
+/** Dropdown single-select field. */
 export class SelectField extends Field {
   constructor(customObject: CustomObject, props: SelectFieldProps) {
     super(customObject, { ...props, fieldType: 'SELECT' });
   }
 }
 
+/** Initialization properties for {@link RadioField}. */
 export interface RadioFieldProps extends CommonFieldProps {
-  /** Required choice list. */
+  /**
+   * The list of selectable options.
+   *
+   * Required.
+   */
   options: string[];
+  /** Whether a value is required on save. Optional. */
   required?: boolean;
 }
-/** Radio button group. */
+/** Radio button group field. */
 export class RadioField extends Field {
   constructor(customObject: CustomObject, props: RadioFieldProps) {
     super(customObject, { ...props, fieldType: 'RADIO' });
   }
 }
 
+/** Initialization properties for {@link BooleanField}. */
 export interface BooleanFieldProps extends CommonFieldProps {
+  /** Whether a value is required on save. Optional. */
   required?: boolean;
 }
-/** Boolean (checkbox). */
+/** Boolean (checkbox) field. */
 export class BooleanField extends Field {
   constructor(customObject: CustomObject, props: BooleanFieldProps) {
     super(customObject, { ...props, fieldType: 'BOOLEAN' });
@@ -404,17 +477,21 @@ export class BooleanField extends Field {
 
 // ── File ───────────────────────────────────────────────────────────────
 
+/** Initialization properties for {@link FileField}. */
 export interface FileFieldProps extends CommonFieldProps {
   /**
-   * File-type restriction. Matches the UI's "File type" dropdown options.
-   *   'images'     — jpg, jpeg, png, gif, bmp, svg
-   *   'documents'  — doc, docx, pdf, csv, txt, rtf, ppt, pptx
-   *   'any'        — any file type
+   * Restricts which file types can be uploaded. Mirrors the UI's "File type" dropdown.
+   *
+   * Required.
+   * - `'images'` — jpg, jpeg, png, gif, bmp, svg
+   * - `'documents'` — doc, docx, pdf, csv, txt, rtf, ppt, pptx
+   * - `'any'` — any file type
    */
   allowedType: 'images' | 'documents' | 'any';
+  /** Whether a file is required on save. Optional. */
   required?: boolean;
 }
-/** File attachment; `allowedType` mirrors the UI's "File type" dropdown. */
+/** File attachment field. */
 export class FileField extends Field {
   constructor(customObject: CustomObject, props: FileFieldProps) {
     const { allowedType, ...rest } = props;
@@ -429,13 +506,31 @@ export class FileField extends Field {
 
 // ── Relational ─────────────────────────────────────────────────────────
 
+/** Initialization properties for {@link LookupField}. */
 export interface LookupFieldProps extends CommonFieldProps {
-  /** Target object. Live `CustomObject` (SDK reads api_name) or native-model api_name string (e.g. `'role'`). */
+  /**
+   * The object this field points to. Pass a live {@link CustomObject} instance,
+   * or a raw api_name string for native Rippling models (e.g. `'role'`).
+   *
+   * Required.
+   */
   target: CustomObject | string;
+  /**
+   * Label for the related-records panel on the target object's detail page
+   * (e.g. `'Class enrollments'`).
+   *
+   * Optional.
+   */
   relatedDataLabel?: string;
+  /** Whether a value is required on save. Optional. */
   required?: boolean;
 }
-/** Many-to-one reference. */
+/**
+ * Many-to-one reference field. Links this record to one record on the target object.
+ *
+ * Use {@link ParentChildField} instead when the relationship should create a
+ * parent-child hierarchy with rollup support.
+ */
 export class LookupField extends Field {
   constructor(customObject: CustomObject, props: LookupFieldProps) {
     const targetApiName = typeof props.target === 'string' ? props.target : props.target.getApiName();
@@ -455,14 +550,42 @@ export class LookupField extends Field {
   }
 }
 
+/** Initialization properties for {@link ParentChildField}. */
 export interface ParentChildFieldProps extends CommonFieldProps {
-  /** Target parent object. Must be a live `CustomObject`. */
+  /**
+   * The parent object. Must be a live {@link CustomObject} instance.
+   *
+   * Required.
+   */
   target: CustomObject;
+  /**
+   * Label for the child-records panel on the parent's detail page
+   * (e.g. `'Enrollments'`).
+   *
+   * Optional.
+   */
   relatedDataLabel?: string;
+  /**
+   * Whether this is the primary or secondary parent-child edge.
+   * One of `'PRIMARY'` | `'SECONDARY'`.
+   *
+   * Optional.
+   */
   parentChildType?: 'PRIMARY' | 'SECONDARY';
+  /**
+   * Whether the child record inherits the owner from the parent.
+   *
+   * Optional.
+   */
   enableParentOwnerInheritance?: boolean;
 }
-/** Parent-child reference — always required on the wire. */
+/**
+ * Parent-child reference field. Creates a hierarchical relationship between
+ * this object (child) and the target (parent), enabling {@link SummaryField}
+ * rollups from the child to the parent.
+ *
+ * Always emitted as `required: true` on the wire.
+ */
 export class ParentChildField extends Field {
   constructor(customObject: CustomObject, props: ParentChildFieldProps) {
     super(customObject, {
@@ -487,18 +610,45 @@ export class ParentChildField extends Field {
 
 // ── Computed ───────────────────────────────────────────────────────────
 
+/** Initialization properties for {@link FormulaField}. */
 export interface FormulaFieldProps extends CommonFieldProps {
-  /** The computed RQL expression. */
+  /**
+   * The RQL expression that computes this field's value
+   * (e.g. `"CONCATENATE(TRIM(first_name__c), ' ', TRIM(last_name__c))"`).
+   *
+   * Required.
+   */
   formula: string;
-  /** Output type narrowed to the 7 variants the UI "Data type" dropdown exposes. */
+  /**
+   * Output data type. One of `'TEXT'` | `'NUMBER'` | `'BOOLEAN'` | `'CURRENCY'`
+   * | `'PERCENTAGE'` | `'DATE'` | `'URL'`.
+   *
+   * Required.
+   */
   fieldType: FormulaFieldType;
-  /** Required when `fieldType === 'TEXT'`. */
+  /**
+   * Maximum character length of the computed value.
+   *
+   * Required when `fieldType === 'TEXT'`. The constructor throws if omitted for text formulas.
+   */
   maxLength?: number;
 }
 /**
- * Computed formula field (read-only). `fieldType` is required and narrowed
- * to the 7 variants the UI "Data type" dropdown exposes. `maxLength` is
- * required when `fieldType === 'TEXT'`.
+ * Read-only computed field whose value is derived from an RQL formula.
+ *
+ * `fieldType` is required and restricted to the 7 output types the Rippling
+ * formula editor supports. `maxLength` is required when `fieldType === 'TEXT'`.
+ *
+ * @example
+ * ```ts
+ * const memberDisplayName = new FormulaField(memberObj, {
+ *   apiName: 'member_display_name__c',
+ *   displayName: 'Display name',
+ *   fieldType: 'TEXT',
+ *   maxLength: 200,
+ *   formula: "CONCATENATE(TRIM(first_name__c), ' ', TRIM(last_name__c))",
+ * });
+ * ```
  */
 export class FormulaField extends Field {
   constructor(customObject: CustomObject, props: FormulaFieldProps) {
@@ -516,22 +666,62 @@ export class FormulaField extends Field {
   }
 }
 
+/** Initialization properties for {@link SummaryField}. */
 export interface SummaryFieldProps extends CommonFieldProps {
-  /** Child-CO field being aggregated. Must have a known fieldType. */
+  /**
+   * The child-CO field whose values are aggregated.
+   *
+   * Required. Must have a known `fieldType` (use a typed subclass, not bare `Field`).
+   * Must live on the same child object as `lookup`.
+   */
   aggregates: Field;
+  /**
+   * Aggregation function. One of `'COUNT'` | `'SUM'` | `'MIN'` | `'MAX'`.
+   *
+   * Required. `COUNT` always produces a `NUMBER` output; other functions
+   * inherit the output type from `aggregates`.
+   */
   using: SummaryAggregation;
-  /** Child-CO's parentChild field pointing back at this CO. */
+  /**
+   * The {@link ParentChildField} on the child CO that points back at this parent object.
+   *
+   * Required. Must be a `ParentChildField` (the constructor throws otherwise).
+   */
   lookup: Field;
+  /**
+   * Optional filter conditions applied before aggregating. Each filter restricts
+   * which child records are included.
+   *
+   * Optional. @default `[]`
+   */
   filters?: SummaryFilter[];
-  /** Only valid when the output fieldType resolves to `'CURRENCY'`. */
+  /**
+   * ISO 4217 currency code (e.g. `'USD'`). Only valid when the aggregated field
+   * resolves to `'CURRENCY'`.
+   *
+   * Optional.
+   */
   currencyCode?: string;
 }
 /**
- * Summary/rollup field — aggregates a child-object field (read-only).
- * SDK enforces only what backend/UI won't: `lookup` edge_type, output-type
- * inference, per-type filter operators, and same-child-CO residency for
- * `aggregates` + `lookup`. Per-filter residency / LONG_TEXT / formula
- * filter / currency pairing checks are left to the backend.
+ * Read-only rollup field that aggregates a child object's field values.
+ *
+ * Defined on the **parent** object. Requires a {@link ParentChildField} on the
+ * child object pointing back at this parent as the `lookup` edge.
+ *
+ * @example
+ * ```ts
+ * // Count enrollments on a class session:
+ * const enrollmentCount = new SummaryField(sessionObj, {
+ *   apiName: 'enrollment_count__c',
+ *   displayName: 'Enrolled (count)',
+ *   aggregates: enrollmentMemberRef,
+ *   using: 'COUNT',
+ *   lookup: enrollmentSessionRef,  // ParentChildField on enrollmentObj → sessionObj
+ * });
+ * ```
+ *
+ * @see {@link ParentChildField} — must be used as `lookup`.
  */
 export class SummaryField extends Field {
   constructor(customObject: CustomObject, props: SummaryFieldProps) {