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

package/src/lib/manifest/field.ts

@@ -0,0 +1,632 @@
+/*
+ * 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,
+  type FormulaFieldType,
+  type SummaryAggregation,
+  type SummaryFilterOperator,
+} from './_helpers';
+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`. */
+export interface SummaryFilter {
+  /** Filter field on the child CO. */
+  field: Field;
+  operator: SummaryFilterOperator;
+  /** Raw RQL value, e.g. `"'Active'"`, `"50"`, `"true"`, `"DATE(2026,1,1)"`. */
+  value: string;
+}
+
+interface SummarySpec {
+  aggregates: Field;
+  using: SummaryAggregation;
+  lookup: Field;
+  filters: SummaryFilter[];
+  currencyCode: string | null;
+}
+
+function validateApiName(apiName: string): void {
+  if (!apiName.endsWith('__c')) {
+    throw new Error(`Field api_name must end with __c: ${apiName}`);
+  }
+}
+
+/** Props shared by every field variant. */
+interface CommonFieldProps {
+  apiName: string;
+  displayName: string;
+  description?: string;
+  section?: CustomObjectFieldSection | string;
+}
+
+/**
+ * Low-level props for the base `Field`. Most users should use one of the
+ * concrete subclasses (`TextField`, `LookupField`, …) instead of constructing
+ * `Field` directly.
+ */
+export interface FieldProps {
+  apiName: string;
+  displayName: string;
+  // Optional members use `| undefined` so subclass constructors can spread
+  // props under `exactOptionalPropertyTypes`.
+  fieldType?: FieldType | undefined;
+  dataType?: Record<string, any> | undefined;
+  description?: string | null | undefined;
+  required?: boolean | null | undefined;
+  unique?: boolean | null | undefined;
+  indexed?: boolean | null | undefined;
+  rqlFormula?: string | null | undefined;
+  formulaAttrMetas?: Record<string, any> | null | undefined;
+  derivedAggregatedField?: Record<string, any> | null | undefined;
+  derivedFieldFormula?: string | null | undefined;
+  section?: CustomObjectFieldSection | string | null | undefined;
+  maxLength?: number | undefined;
+  decimalPlaces?: number | undefined;
+  currency?: string | undefined;
+  options?: string[] | undefined;
+  /** Internal — set by `SummaryField`; drives the `derived_aggregated_field` wire field. */
+  summarySpec?: SummarySpec | undefined;
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Base class
+// ────────────────────────────────────────────────────────────────────────
+
+/**
+ * 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.
+ */
+export class Field {
+  private readonly _fieldApiName: string;
+  private readonly _fieldDisplayName: string;
+  private readonly _customObjectApiName: string;
+  private readonly _dataType: Record<string, any>;
+  private readonly _description: string | null;
+  private readonly _isRequired: boolean | null;
+  private readonly _isUnique: boolean | null;
+  private readonly _isIndexed: boolean | null;
+  private readonly _rqlFormula: string | null;
+  private readonly _formulaAttrMetas: Record<string, any> | null;
+  private readonly _derivedFieldFormula: string | null;
+  private readonly _section: string | null;
+  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`. */
+  constructor(customObject: CustomObject, props: FieldProps) {
+    validateApiName(props.apiName);
+    this._fieldApiName = props.apiName;
+    this._fieldDisplayName = props.displayName;
+    this._customObjectApiName = customObject.getApiName();
+
+    const dt: Record<string, any> = { ...(props.dataType ?? {}) };
+    if (props.fieldType != null) dt['field_type'] = props.fieldType;
+    if (props.maxLength != null) dt['max_length'] = props.maxLength;
+    if (props.decimalPlaces != null) dt['num_of_decimal_places'] = props.decimalPlaces;
+    if (props.currency != null) dt['currency'] = props.currency;
+    if (props.options != null) dt['options_list'] = [...props.options];
+    this._dataType = dt;
+
+    this._description = props.description ?? null;
+    this._isRequired = props.required ?? null;
+    this._isUnique = props.unique ?? null;
+    this._isIndexed = props.indexed ?? null;
+    this._rqlFormula = props.rqlFormula ?? null;
+    this._formulaAttrMetas = props.formulaAttrMetas ?? null;
+    this._derivedAggregatedFieldStatic = props.derivedAggregatedField ?? null;
+    this._derivedFieldFormula = props.derivedFieldFormula ?? null;
+    this._summarySpec = props.summarySpec ?? null;
+
+    const rawSection = props.section;
+    this._section =
+      rawSection == null ? null
+      : typeof rawSection === 'string' ? rawSection
+      : rawSection.getSectionId();
+
+    customObject._register(this);
+  }
+
+  // ── Getters ────────────────────────────────────────────────────────────
+
+  /** Backend api_name for this field. */
+  getApiName(): string {
+    return this._fieldApiName;
+  }
+  /** Human-readable display name. */
+  getDisplayName(): string {
+    return this._fieldDisplayName;
+  }
+  /** api_name of the CustomObject this field lives on. */
+  getCustomObjectApiName(): string {
+    return this._customObjectApiName;
+  }
+  /** Resolved `data_type.field_type`, or null if unset. */
+  getFieldType(): FieldType | null {
+    return (this._dataType['field_type'] as FieldType | undefined) ?? null;
+  }
+  /** Raw `data_type` dict (read-only view). */
+  getDataType(): Readonly<Record<string, any>> {
+    return this._dataType;
+  }
+  /** True if this field is a simple formula field. */
+  isFormula(): boolean {
+    return this._derivedFieldFormula != null;
+  }
+  /** True if this field is a summary/rollup field. */
+  isSummary(): boolean {
+    return this._summarySpec != null;
+  }
+
+  // ── Serialization ──────────────────────────────────────────────────────
+
+  /** Serialize to the backend `CUSTOM_OBJECT_FIELD` wire shape. */
+  toDict(): Record<string, any> {
+    return {
+      type: 'CUSTOM_OBJECT_FIELD',
+      custom_object_api_name: this._customObjectApiName,
+      field_api_name: this._fieldApiName,
+      field_display_name: this._fieldDisplayName,
+      data_type: { options_list: [], supported_types: [], ...this._dataType },
+      description: this._description,
+      is_required: this._isRequired,
+      is_unique: this._isUnique,
+      is_indexed: this._isIndexed,
+      rql_formula: this._rqlFormula ?? null,
+      formula_attr_metas: this._formulaAttrMetas,
+      // User-authored package fields are never standard (backend invariant).
+      is_standard: false,
+      derived_aggregated_field: this._resolveAggregatedField(),
+      derived_field_formula: this._derivedFieldFormula ?? null,
+      section: this._section,
+    };
+  }
+
+  /** Build the `derived_aggregated_field` dict from `_summarySpec` with cross-CO checks. */
+  private _resolveAggregatedField(): Record<string, any> | null {
+    if (this._summarySpec == null) return this._derivedAggregatedFieldStatic;
+    const spec = this._summarySpec;
+
+    const aggParent = spec.aggregates.getCustomObjectApiName();
+    const lookupParent = spec.lookup.getCustomObjectApiName();
+    if (lookupParent !== aggParent) {
+      throw new Error(
+        `SummaryField "${this._fieldApiName}": lookup lives on "${lookupParent}" ` +
+          `but aggregates lives on "${aggParent}" — both must live on the same ` +
+          `child CustomObject.`,
+      );
+    }
+
+    // Per-filter residency / back-ref / LONG_TEXT / formula checks: backend only.
+
+    return {
+      aggregation_function: spec.using,
+      child_model_name: aggParent,
+      currency_code: spec.currencyCode,
+      field_to_aggregate: spec.aggregates.getApiName(),
+      filters: spec.filters.map((f) => ({
+        field_name: f.field.getApiName(),
+        filter_value: f.value,
+        operator: f.operator,
+      })),
+      lookup_field_api_name: spec.lookup.getApiName(),
+    };
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Concrete field subclasses — one per wire-level variant.
+// Each sets its own `fieldType` / `dataType` and forwards the rest to
+// `Field`'s constructor. Order matches the UI's "Data type" dropdown.
+// ────────────────────────────────────────────────────────────────────────
+
+// ── Text-like ──────────────────────────────────────────────────────────
+
+export interface TextFieldProps extends CommonFieldProps {
+  required?: boolean;
+  unique?: boolean;
+  maxLength?: number;
+}
+/** Single-line text. */
+export class TextField extends Field {
+  constructor(customObject: CustomObject, props: TextFieldProps) {
+    super(customObject, { ...props, fieldType: 'TEXT' });
+  }
+}
+
+export interface LongTextFieldProps extends CommonFieldProps {
+  required?: boolean;
+  maxLength?: number;
+}
+/** Multi-line text. */
+export class LongTextField extends Field {
+  constructor(customObject: CustomObject, props: LongTextFieldProps) {
+    super(customObject, { ...props, fieldType: 'LONG_TEXT' });
+  }
+}
+
+export interface EmailFieldProps extends CommonFieldProps {
+  required?: boolean;
+  unique?: boolean;
+}
+/** Email address (format-validated by the UI). */
+export class EmailField extends Field {
+  constructor(customObject: CustomObject, props: EmailFieldProps) {
+    super(customObject, { ...props, fieldType: 'EMAIL' });
+  }
+}
+
+export interface UrlFieldProps extends CommonFieldProps {
+  required?: boolean;
+}
+/** URL (format-validated by the UI). */
+export class UrlField extends Field {
+  constructor(customObject: CustomObject, props: UrlFieldProps) {
+    super(customObject, { ...props, fieldType: 'URL' });
+  }
+}
+
+export interface PhoneFieldProps extends CommonFieldProps {
+  required?: boolean;
+}
+/** Phone number. */
+export class PhoneField extends Field {
+  constructor(customObject: CustomObject, props: PhoneFieldProps) {
+    super(customObject, { ...props, fieldType: 'PHONE_NUMBER' });
+  }
+}
+
+// ── Numeric ────────────────────────────────────────────────────────────
+
+export interface NumberFieldProps extends CommonFieldProps {
+  required?: boolean;
+  unique?: boolean;
+  decimalPlaces?: number;
+}
+/** Number. */
+export class NumberField extends Field {
+  constructor(customObject: CustomObject, props: NumberFieldProps) {
+    super(customObject, { ...props, fieldType: 'NUMBER' });
+  }
+}
+
+export interface CurrencyFieldProps extends CommonFieldProps {
+  required?: boolean;
+  currency?: string;
+  decimalPlaces?: number;
+}
+/** Currency amount; `currency` is forwarded only when set. */
+export class CurrencyField extends Field {
+  constructor(customObject: CustomObject, props: CurrencyFieldProps) {
+    super(customObject, { ...props, fieldType: 'CURRENCY' });
+  }
+}
+
+export interface PercentageFieldProps extends CommonFieldProps {
+  required?: boolean;
+  decimalPlaces?: number;
+}
+/** Percentage. */
+export class PercentageField extends Field {
+  constructor(customObject: CustomObject, props: PercentageFieldProps) {
+    super(customObject, { ...props, fieldType: 'PERCENTAGE' });
+  }
+}
+
+// ── Date/time ──────────────────────────────────────────────────────────
+
+export interface DateFieldProps extends CommonFieldProps {
+  required?: boolean;
+}
+/** Date (no time). */
+export class DateField extends Field {
+  constructor(customObject: CustomObject, props: DateFieldProps) {
+    super(customObject, { ...props, fieldType: 'DATE' });
+  }
+}
+
+export interface DatetimeFieldProps extends CommonFieldProps {
+  required?: boolean;
+}
+/** Date + time. */
+export class DatetimeField extends Field {
+  constructor(customObject: CustomObject, props: DatetimeFieldProps) {
+    super(customObject, { ...props, fieldType: 'DATETIME' });
+  }
+}
+
+export interface TimeFieldProps extends CommonFieldProps {
+  required?: boolean;
+}
+/** Time of day. */
+export class TimeField extends Field {
+  constructor(customObject: CustomObject, props: TimeFieldProps) {
+    super(customObject, { ...props, fieldType: 'TIME' });
+  }
+}
+
+// ── Choice ─────────────────────────────────────────────────────────────
+
+export interface SelectFieldProps extends CommonFieldProps {
+  /** Required choice list. */
+  options: string[];
+  required?: boolean;
+}
+/** Dropdown select. */
+export class SelectField extends Field {
+  constructor(customObject: CustomObject, props: SelectFieldProps) {
+    super(customObject, { ...props, fieldType: 'SELECT' });
+  }
+}
+
+export interface RadioFieldProps extends CommonFieldProps {
+  /** Required choice list. */
+  options: string[];
+  required?: boolean;
+}
+/** Radio button group. */
+export class RadioField extends Field {
+  constructor(customObject: CustomObject, props: RadioFieldProps) {
+    super(customObject, { ...props, fieldType: 'RADIO' });
+  }
+}
+
+export interface BooleanFieldProps extends CommonFieldProps {
+  required?: boolean;
+}
+/** Boolean (checkbox). */
+export class BooleanField extends Field {
+  constructor(customObject: CustomObject, props: BooleanFieldProps) {
+    super(customObject, { ...props, fieldType: 'BOOLEAN' });
+  }
+}
+
+// ── File ───────────────────────────────────────────────────────────────
+
+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
+   */
+  allowedType: 'images' | 'documents' | 'any';
+  required?: boolean;
+}
+/** File attachment; `allowedType` mirrors the UI's "File type" dropdown. */
+export class FileField extends Field {
+  constructor(customObject: CustomObject, props: FileFieldProps) {
+    const { allowedType, ...rest } = props;
+    const supported = allowedType === 'any' ? ['*'] : [allowedType];
+    super(customObject, {
+      ...rest,
+      fieldType: 'FILE',
+      dataType: { supported_types: supported },
+    });
+  }
+}
+
+// ── Relational ─────────────────────────────────────────────────────────
+
+export interface LookupFieldProps extends CommonFieldProps {
+  /** Target object. Live `CustomObject` (SDK reads api_name) or native-model api_name string (e.g. `'role'`). */
+  target: CustomObject | string;
+  relatedDataLabel?: string;
+  required?: boolean;
+}
+/** Many-to-one reference. */
+export class LookupField extends Field {
+  constructor(customObject: CustomObject, props: LookupFieldProps) {
+    const targetApiName = typeof props.target === 'string' ? props.target : props.target.getApiName();
+    super(customObject, {
+      apiName: props.apiName,
+      displayName: props.displayName,
+      dataType: {
+        field_type: 'OG_REFERENCE_FIELD',
+        og_model_rql_name: targetApiName,
+        edge_type: 'LOOKUP',
+        ...(props.relatedDataLabel != null ? { related_data_label: props.relatedDataLabel } : {}),
+      },
+      required: props.required,
+      description: props.description,
+      section: props.section,
+    });
+  }
+}
+
+export interface ParentChildFieldProps extends CommonFieldProps {
+  /** Target parent object. Must be a live `CustomObject`. */
+  target: CustomObject;
+  relatedDataLabel?: string;
+  parentChildType?: 'PRIMARY' | 'SECONDARY';
+  enableParentOwnerInheritance?: boolean;
+}
+/** Parent-child reference — always required on the wire. */
+export class ParentChildField extends Field {
+  constructor(customObject: CustomObject, props: ParentChildFieldProps) {
+    super(customObject, {
+      apiName: props.apiName,
+      displayName: props.displayName,
+      dataType: {
+        field_type: 'OG_REFERENCE_FIELD',
+        og_model_rql_name: props.target.getApiName(),
+        edge_type: 'PARENT_CHILD',
+        ...(props.relatedDataLabel != null ? { related_data_label: props.relatedDataLabel } : {}),
+        ...(props.parentChildType != null ? { parent_child_type: props.parentChildType } : {}),
+        ...(props.enableParentOwnerInheritance != null ?
+          { enable_parent_owner_inheritance: props.enableParentOwnerInheritance }
+        : {}),
+      },
+      required: true,
+      description: props.description,
+      section: props.section,
+    });
+  }
+}
+
+// ── Computed ───────────────────────────────────────────────────────────
+
+export interface FormulaFieldProps extends CommonFieldProps {
+  /** The computed RQL expression. */
+  formula: string;
+  /** Output type narrowed to the 7 variants the UI "Data type" dropdown exposes. */
+  fieldType: FormulaFieldType;
+  /** Required when `fieldType === 'TEXT'`. */
+  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'`.
+ */
+export class FormulaField extends Field {
+  constructor(customObject: CustomObject, props: FormulaFieldProps) {
+    if (props.fieldType === 'TEXT' && props.maxLength == null) {
+      throw new Error(`FormulaField "${props.apiName}": maxLength is required when fieldType is 'TEXT'.`);
+    }
+    const { formula, ...rest } = props;
+    super(customObject, {
+      ...rest,
+      derivedFieldFormula: formula,
+      required: null,
+      unique: null,
+      indexed: null,
+    });
+  }
+}
+
+export interface SummaryFieldProps extends CommonFieldProps {
+  /** Child-CO field being aggregated. Must have a known fieldType. */
+  aggregates: Field;
+  using: SummaryAggregation;
+  /** Child-CO's parentChild field pointing back at this CO. */
+  lookup: Field;
+  filters?: SummaryFilter[];
+  /** Only valid when the output fieldType resolves to `'CURRENCY'`. */
+  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.
+ */
+export class SummaryField extends Field {
+  constructor(customObject: CustomObject, props: SummaryFieldProps) {
+    // lookup must be a parentChild field.
+    if (props.lookup.getDataType()['edge_type'] !== 'PARENT_CHILD') {
+      throw new Error(
+        `SummaryField "${props.apiName}": 'lookup' must be a parentChild ` +
+          `field on the child CO (got edge_type=` +
+          `${props.lookup.getDataType()['edge_type'] ?? 'undefined'}).`,
+      );
+    }
+
+    // Infer output fieldType: NUMBER for COUNT, else the aggregated field's type.
+    let outputFieldType: FieldType;
+    if (props.using === 'COUNT') {
+      outputFieldType = 'NUMBER';
+    } else {
+      const agg = props.aggregates.getFieldType();
+      if (agg == null) {
+        throw new Error(
+          `SummaryField "${props.apiName}": cannot infer output type — ` +
+            `aggregates field "${props.aggregates.getApiName()}" has no ` +
+            `known field_type. Construct it with a typed subclass (e.g. ` +
+            `CurrencyField / NumberField).`,
+        );
+      }
+      outputFieldType = agg;
+    }
+
+    // Summary-filter field restrictions. Mirror the admin condition-builder
+    // picker so SDK-authored manifests are fully editable in the UI, and
+    // catch the backend's own hard rejects ahead of /validate.
+    for (const f of props.filters ?? []) {
+      const fname = f.field.getApiName();
+      const ft = f.field.getFieldType();
+
+      // (a) Can't filter on the parent-child lookup field itself
+      //     (backend: parent_child_util.py rejects this explicitly).
+      if (f.field === props.lookup) {
+        throw new Error(
+          `SummaryField "${props.apiName}": filter field "${fname}" is the ` +
+            `parent-child lookup field — that's reserved as the aggregation ` +
+            `axis and can't be a filter. Pick a scalar field on the child CO.`,
+        );
+      }
+      // (b) Can't filter on a derived (formula or summary) field
+      //     (backend rejects both).
+      if (f.field.isFormula() || f.field.isSummary()) {
+        throw new Error(
+          `SummaryField "${props.apiName}": filter field "${fname}" is ` +
+            `itself a derived field (formula/summary). The backend does not ` +
+            `allow derived fields as summary-filter fields. Filter on a ` +
+            `plain scalar field on the child CO instead.`,
+        );
+      }
+      if (ft == null) continue;
+      // (c) FILTER_OPERATORS_BY_TYPE is the single source of truth for
+      //     "which field types can be used as summary-filter fields".
+      //     Absent key ⇒ UI picker hides this type ⇒ SDK rejects it.
+      const allowed = FILTER_OPERATORS_BY_TYPE[ft];
+      if (allowed == null) {
+        throw new Error(
+          `SummaryField "${props.apiName}": filter field "${fname}" has type ` +
+            `${ft}, which the admin UI excludes from summary-filter pickers ` +
+            `(ambiguous semantics for aggregations). Model a plain BOOLEAN ` +
+            `field on the child CO (updated via a Rule) and filter on that.`,
+        );
+      }
+      // (d) Per-type operator allow-list.
+      if (!allowed.has(f.operator)) {
+        throw new Error(
+          `SummaryField "${props.apiName}": operator "${f.operator}" is ` +
+            `not valid for ${ft} field "${fname}". ` +
+            `Allowed: ${[...allowed].join(', ')}.`,
+        );
+      }
+    }
+
+    super(customObject, {
+      apiName: props.apiName,
+      displayName: props.displayName,
+      fieldType: outputFieldType,
+      currency: outputFieldType === 'CURRENCY' ? props.currencyCode : undefined,
+      required: null,
+      unique: null,
+      indexed: null,
+      description: props.description,
+      section: props.section,
+      summarySpec: {
+        aggregates: props.aggregates,
+        using: props.using,
+        lookup: props.lookup,
+        filters: props.filters ?? [],
+        currencyCode: props.currencyCode ?? null,
+      },
+    });
+  }
+}