@rippling/rippling-sdk 0.2.0-alpha.37 → 0.2.0-alpha.39

package/src/lib/manifest/field.ts

@@ -7,6 +7,13 @@ import {
 } from './_helpers';
 import type { CustomObject } from './custom-object';
 import type { CustomObjectFieldSection } from './custom-object-field-section';
+import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
+import type { ManifestComponentDeletion } from './manifest-builder';
+
+export interface CustomObjectFieldDeletionIdentifier {
+  customObjectApiName: string;
+  fieldApiName: string;
+}
 
 /**
  * A filter condition applied to a {@link SummaryField}.
@@ -53,6 +60,11 @@ function validateApiName(apiName: string): void {
   }
 }
 
+function cloneJson<T>(value: T): T {
+  if (value == null) return value;
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
 /** Props shared by every field variant. */
 interface CommonFieldProps {
   apiName: string;
@@ -90,6 +102,61 @@ export interface FieldProps {
   summarySpec?: SummarySpec | undefined;
 }
 
+export interface FieldLoadFromExistingOptions extends ExistingManifestContextOptions {
+  customObjectApiName?: string;
+}
+
+class ExistingFieldReference {
+  private _section: string | null;
+
+  constructor(
+    private readonly customObjectApiName: string,
+    private readonly component: Record<string, any>,
+  ) {
+    this._section = (component['section'] as string | null | undefined) ?? null;
+  }
+
+  getApiName(): string {
+    return this.component['field_api_name'];
+  }
+
+  getDisplayName(): string {
+    return this.component['field_display_name'] ?? this.getApiName();
+  }
+
+  getCustomObjectApiName(): string {
+    return this.customObjectApiName;
+  }
+
+  getFieldType(): FieldType | null {
+    return (this.getDataType()['field_type'] as FieldType | undefined) ?? null;
+  }
+
+  getDataType(): Readonly<Record<string, any>> {
+    return this.component['data_type'] ?? {};
+  }
+
+  isFormula(): boolean {
+    return this.component['derived_field_formula'] != null;
+  }
+
+  isSummary(): boolean {
+    return this.component['derived_aggregated_field'] != null;
+  }
+
+  getSectionId(): string | null {
+    return this._section;
+  }
+
+  _assignSection(section: CustomObjectFieldSection | string): void {
+    this._section = typeof section === 'string' ? section : section.getSectionId();
+  }
+
+  toDict(): Record<string, any> {
+    return cloneJson(this.component);
+  }
+}
+
 // ────────────────────────────────────────────────────────────────────────
 // Base class
 // ────────────────────────────────────────────────────────────────────────
@@ -119,6 +186,16 @@ export interface FieldProps {
  * @see {@link TextField}, {@link NumberField}, {@link LookupField}, {@link SummaryField}
  */
 export class Field {
+  static readonly componentType = 'CUSTOM_OBJECT_FIELD' as const;
+
+  static toDeletionIdentifier(identifier: CustomObjectFieldDeletionIdentifier): ManifestComponentDeletion {
+    return {
+      type: Field.componentType,
+      custom_object_api_name: identifier.customObjectApiName,
+      field_api_name: identifier.fieldApiName,
+    };
+  }
+
   private readonly _fieldApiName: string;
   private readonly _fieldDisplayName: string;
   private readonly _customObjectApiName: string;
@@ -172,6 +249,68 @@ export class Field {
     customObject._register(this);
   }
 
+  /**
+   * Loads this field from the active existing-manifest JSON context.
+   *
+   * For fields whose api_name is not globally unique, pass `customObjectApiName`
+   * or use a qualified id like `'object__c.field__c'`.
+   */
+  static loadFromExisting(apiName: string, options: FieldLoadFromExistingOptions = {}): Field {
+    return getExistingManifestContext(options).loadField(apiName, options);
+  }
+
+  /** @internal Hydrates a custom object field from existing manifest wire JSON. */
+  static _fromExistingComponent(customObject: CustomObject, component: Record<string, any>): Field {
+    const props: FieldProps = {
+      apiName: component['field_api_name'],
+      displayName: component['field_display_name'] ?? component['field_api_name'],
+    };
+    if (component['data_type'] !== undefined) props.dataType = cloneJson(component['data_type'] ?? {});
+    if (component['description'] !== undefined) props.description = component['description'];
+    if (component['is_required'] !== undefined) props.required = component['is_required'];
+    if (component['is_unique'] !== undefined) props.unique = component['is_unique'];
+    if (component['is_indexed'] !== undefined) props.indexed = component['is_indexed'];
+    if (component['rql_formula'] !== undefined) props.rqlFormula = component['rql_formula'];
+    if (component['formula_attr_metas'] !== undefined)
+      props.formulaAttrMetas = component['formula_attr_metas'];
+    if (component['derived_aggregated_field'] !== undefined) {
+      props.derivedAggregatedField = component['derived_aggregated_field'];
+    }
+    if (component['derived_field_formula'] !== undefined)
+      props.derivedFieldFormula = component['derived_field_formula'];
+    if (component['section'] !== undefined) props.section = component['section'];
+    return new Field(customObject, props);
+  }
+
+  /** @internal Creates a non-registered reference for standard or external fields. */
+  static _referenceFromExistingComponent(component: Record<string, any>): Field {
+    return new ExistingFieldReference(
+      component['custom_object_api_name'],
+      cloneJson(component),
+    ) as unknown as Field;
+  }
+
+  /** @internal Creates a non-registered reference for a known wire field name. */
+  static _syntheticReference(customObjectApiName: string, fieldApiName: string): Field {
+    return new ExistingFieldReference(customObjectApiName, {
+      type: 'CUSTOM_OBJECT_FIELD',
+      custom_object_api_name: customObjectApiName,
+      field_api_name: fieldApiName,
+      field_display_name: fieldApiName,
+      data_type: {},
+      description: null,
+      is_required: null,
+      is_unique: null,
+      is_indexed: null,
+      rql_formula: null,
+      formula_attr_metas: null,
+      is_standard: true,
+      derived_aggregated_field: null,
+      derived_field_formula: null,
+      section: null,
+    }) as unknown as Field;
+  }
+
   // ── Getters ────────────────────────────────────────────────────────────
 
   /** Returns the api_name of this field (e.g. `'first_name__c'`). */
@@ -220,7 +359,7 @@ export class Field {
    */
   toDict(): Record<string, any> {
     return {
-      type: 'CUSTOM_OBJECT_FIELD',
+      type: Field.componentType,
       custom_object_api_name: this._customObjectApiName,
       field_api_name: this._fieldApiName,
       field_display_name: this._fieldDisplayName,
@@ -446,7 +585,12 @@ export interface SelectFieldProps extends CommonFieldProps {
   /** Whether a value is required on save. Optional. */
   required?: boolean;
 }
-/** Dropdown single-select field. */
+/**
+ * Multi-select dropdown field. Renders as a dropdown that allows multiple
+ * options to be selected at once.
+ *
+ * Use {@link RadioField} instead when only one option should be selectable.
+ */
 export class SelectField extends Field {
   constructor(customObject: CustomObject, props: SelectFieldProps) {
     super(customObject, { ...props, fieldType: 'SELECT' });
@@ -464,7 +608,11 @@ export interface RadioFieldProps extends CommonFieldProps {
   /** Whether a value is required on save. Optional. */
   required?: boolean;
 }
-/** Radio button group field. */
+/**
+ * Single-select radio button group field. Exactly one option can be selected.
+ *
+ * Use {@link SelectField} instead when multiple options should be selectable.
+ */
 export class RadioField extends Field {
   constructor(customObject: CustomObject, props: RadioFieldProps) {
     super(customObject, { ...props, fieldType: 'RADIO' });
@@ -538,6 +686,15 @@ export interface LookupFieldProps extends CommonFieldProps {
  *
  * Use {@link ParentChildField} instead when the relationship should create a
  * parent-child hierarchy with rollup support.
+ *
+ * @remarks
+ * **For "the employee responsible for this record" semantics, consider the built-in
+ * `owner_role` standard field instead of a new `LookupField` to `'role'`.** Every
+ * `CustomObject` ships with `owner_role` (an Employee reference) plus `created_by`
+ * and `last_modified_by`. `owner_role` drives Rippling's record-level permissions,
+ * so a parallel custom employee field can fragment ownership and complicate the
+ * permission story. Consider a new `LookupField` to `'role'` when you need a
+ * *second*, non-owner employee reference (e.g. an "approver", a "manager on record").
  */
 export class LookupField extends Field {
   constructor(customObject: CustomObject, props: LookupFieldProps) {

package/src/lib/manifest/index.ts

@@ -23,15 +23,21 @@ export { Category, type CategoryProps } from './category';
 
 export { CustomObject, type CustomObjectProps, type IconConfig } from './custom-object';
 
-export { CustomObjectFieldSection, type CustomObjectFieldSectionProps } from './custom-object-field-section';
+export {
+  CustomObjectFieldSection,
+  type CustomObjectFieldSectionLoadFromExistingOptions,
+  type CustomObjectFieldSectionProps,
+} from './custom-object-field-section';
 
 export {
   CustomObjectPageLayout,
+  type CustomObjectPageLayoutLoadFromExistingOptions,
   type CustomObjectPageLayoutProps,
   type CustomTab,
   type FieldsSection,
   type HeaderEdits,
   type NewHeaderField,
+  type PageLayoutDeletionIdentifier,
   type PageLayoutSection,
   type PageLayoutTab,
   type SectionField,
@@ -49,6 +55,8 @@ export {
 
 export {
   Field,
+  type CustomObjectFieldDeletionIdentifier,
+  type FieldLoadFromExistingOptions,
   type FieldProps,
   type SummaryFilter,
 
@@ -94,12 +102,28 @@ export {
   type SummaryFieldProps,
 } from './field';
 
-export { ListViewDef, type ListViewDefProps } from './list-view';
+export {
+  ExistingManifestContext,
+  type ExistingManifest,
+  type ExistingManifestContextOptions,
+  type ExistingManifestSource,
+} from './existing-manifest-context';
+
+export {
+  ListViewDef,
+  type ListViewDefLoadFromExistingOptions,
+  type ListViewDefProps,
+  type ListViewDeletionIdentifier,
+} from './list-view';
 
 export {
   ManifestBuilder,
+  type BuiltManifest,
   type ManifestBuilderProps,
   type ManifestComponent,
+  type ManifestComponentClass,
+  type ManifestComponentDeletion,
+  type ManifestComponentType,
   type ManifestScope,
 } from './manifest-builder';
 
@@ -109,8 +133,19 @@ export {
   type ManifestFunctionProps,
 } from './manifest-function';
 
-export { Rule, type RuleAction, type RuleProps } from './rule';
+export {
+  Rule,
+  type RuleAction,
+  type RuleDeletionIdentifier,
+  type RuleLoadFromExistingOptions,
+  type RuleProps,
+} from './rule';
 
 export { SduiPage, type SduiPageProps } from './sdui-page';
 
-export { Validation, type ValidationProps } from './validation';
+export {
+  Validation,
+  type ValidationDeletionIdentifier,
+  type ValidationLoadFromExistingOptions,
+  type ValidationProps,
+} from './validation';

package/src/lib/manifest/list-view.ts

@@ -1,6 +1,13 @@
 import { generateId, type ObjectScope, type SortOrder } from './_helpers';
 import type { CustomObject } from './custom-object';
+import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
 import type { Field } from './field';
+import type { ManifestComponentDeletion } from './manifest-builder';
+
+export interface ListViewDeletionIdentifier {
+  viewId: string;
+  objectRqlName: string;
+}
 
 /**
  * Initialization properties for {@link ListViewDef}.
@@ -70,6 +77,10 @@ export interface ListViewDefProps {
   rqlFilter?: string;
 }
 
+export interface ListViewDefLoadFromExistingOptions extends ExistingManifestContextOptions {
+  customObjectApiName?: string;
+}
+
 /**
  * Defines a list view and registers it with the manifest.
  *
@@ -104,6 +115,16 @@ export interface ListViewDefProps {
  * ```
  */
 export class ListViewDef {
+  static readonly componentType = 'CUSTOM_OBJECT_LIST_VIEW' as const;
+
+  static toDeletionIdentifier(identifier: ListViewDeletionIdentifier): ManifestComponentDeletion {
+    return {
+      type: ListViewDef.componentType,
+      view_id: identifier.viewId,
+      object_rql_name: identifier.objectRqlName,
+    };
+  }
+
   private readonly _viewId: string;
   private readonly _customObjectApiName: string;
   private readonly _name: string;
@@ -143,6 +164,34 @@ export class ListViewDef {
     customObject._register(this);
   }
 
+  /**
+   * Loads this list view from the active existing-manifest JSON context.
+   */
+  static loadFromExisting(viewId: string, options: ListViewDefLoadFromExistingOptions = {}): ListViewDef {
+    return getExistingManifestContext(options).loadListView(viewId, options);
+  }
+
+  /** @internal Hydrates a list view from existing manifest wire JSON. */
+  static _fromExistingComponent(
+    customObject: CustomObject,
+    component: Record<string, any>,
+    resolveField: (apiName: string) => Field,
+  ): ListViewDef {
+    const props: ListViewDefProps = {
+      viewId: component['view_id'],
+      name: component['name'] ?? component['view_id'],
+      fields: (component['fields'] ?? []).map((fieldApiName: string) => resolveField(fieldApiName)),
+      isPublic: Boolean(component['public']),
+    };
+    if (component['description'] !== undefined) props.description = component['description'];
+    if (component['object_scope'] !== undefined) props.objectScope = component['object_scope'];
+    if (component['sort_order'] !== undefined) props.sortOrder = component['sort_order'];
+    if (component['column_config'] !== undefined) props.columnConfig = component['column_config'];
+    if (component['rql_filter'] !== undefined) props.rqlFilter = component['rql_filter'];
+    if (component['order_by'] != null) props.orderBy = resolveField(component['order_by']);
+    return new ListViewDef(customObject, props);
+  }
+
   /**
    * Returns the stable identifier for this view (e.g. `'view_gym_all_members'`).
    */
@@ -165,7 +214,7 @@ export class ListViewDef {
    */
   toDict(): Record<string, any> {
     const d: Record<string, any> = {
-      type: 'CUSTOM_OBJECT_LIST_VIEW',
+      type: ListViewDef.componentType,
       object_rql_name: this._customObjectApiName,
       view_id: this._viewId,
       name: this._name,

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

@@ -1,3 +1,5 @@
+import { ExistingManifestContext, type ExistingManifestSource } from './existing-manifest-context';
+
 /**
  * Any object that can be included in a manifest.
  *
@@ -8,6 +10,39 @@ export interface ManifestComponent {
   toDict(): Record<string, any>;
 }
 
+/**
+ * Wire-level component types supported by the manifest builder.
+ */
+export type ManifestComponentType =
+  | 'CUSTOM_APP'
+  | 'CUSTOM_CATEGORY'
+  | 'CUSTOM_OBJECT'
+  | 'CUSTOM_OBJECT_FIELD'
+  | 'CUSTOM_OBJECT_FIELD_SECTION'
+  | 'CUSTOM_OBJECT_LIST_VIEW'
+  | 'CUSTOM_OBJECT_PAGE_LAYOUT'
+  | 'CUSTOM_OBJECT_RECORD_TRIGGERED_FLOW'
+  | 'CUSTOM_OBJECT_VALIDATION_RULE'
+  | 'FUNCTION'
+  | 'SDUI_PAGE';
+
+/**
+ * Static side of a manifest component class.
+ */
+export interface ManifestComponentClass<TIdentifierInput = unknown> {
+  readonly componentType: ManifestComponentType;
+  toDeletionIdentifier(identifier: TIdentifierInput): ManifestComponentDeletion;
+  new (...args: any[]): ManifestComponent;
+}
+
+/**
+ * A manifest component reference that should be deleted during install.
+ */
+export interface ManifestComponentDeletion extends Record<string, any> {
+  /** Wire-level component type, e.g. `'CUSTOM_OBJECT'` or `'CUSTOM_OBJECT_FIELD'`. */
+  type: ManifestComponentType;
+}
+
 /**
  * A scope — anything that can accept child component registrations.
  *
@@ -44,6 +79,15 @@ export interface ManifestBuilderProps {
   description?: string;
 }
 
+/**
+ * Plain object returned by {@link ManifestBuilder.buildManifest}.
+ */
+export interface BuiltManifest {
+  metadata: Record<string, any>;
+  components: Record<string, any>[];
+  components_to_delete?: ManifestComponentDeletion[];
+}
+
 /**
  * Root container for a manifest — collects all components and serializes them to JSON.
  *
@@ -63,7 +107,7 @@ export interface ManifestBuilderProps {
  *   description: 'Members, trainers, schedules, and check-in',
  * });
  *
- * const category = new Category(manifest, { apiName: 'gym__c', name: 'Gym' });
+ * const category = new Category(manifest, { apiName: 'gym__c', name: 'Gym', description: 'Gym domain' });
  * const memberObj = new CustomObject(manifest, { apiName: 'gym_member__c', name: 'Member', category });
  * // ... define fields, rules, list views, etc. ...
  *
@@ -75,6 +119,7 @@ export class ManifestBuilder implements ManifestScope {
   readonly name: string;
   readonly description: string;
   private readonly _components: ManifestComponent[] = [];
+  private readonly _componentsToDelete: ManifestComponentDeletion[] = [];
 
   /**
    * @param props - Initialization properties.
@@ -89,6 +134,24 @@ export class ManifestBuilder implements ManifestScope {
     this.description = props.description ?? '';
   }
 
+  /**
+   * Parses an existing manifest JSON blob, installs it as the active load context,
+   * hydrates every known component, and returns a normal `ManifestBuilder`.
+   */
+  static loadFromExistingJson(source: ExistingManifestSource): ManifestBuilder {
+    return ExistingManifestContext.fromJson(source).loadManifestBuilder();
+  }
+
+  /**
+   * Parses an existing manifest JSON blob and installs it as the active lazy-load context.
+   *
+   * After calling this, individual components can be loaded with
+   * `CustomObjectPageLayout.loadFromExisting(...)`, `Field.loadFromExisting(...)`, etc.
+   */
+  static useExistingJson(source: ExistingManifestSource): ExistingManifestContext {
+    return ExistingManifestContext.fromJson(source);
+  }
+
   /**
    * @internal Scope hook invoked by child constructors. Components enter the
    * manifest here — there is no other path.
@@ -101,11 +164,45 @@ export class ManifestBuilder implements ManifestScope {
   }
 
   /**
-   * Returns the manifest as a plain object with `metadata` and a flat `components` array.
+   * Marks a component to be deleted when this manifest is installed.
    *
-   * @returns `{ metadata: { key, name, description? }, components: Record<string, any>[] }`
+   * @param componentClass - Component class, e.g. `CustomObject`.
+   * @param identifier - Component identifier/key, such as an api_name or the component's identifier object.
+   * @returns This builder for chaining.
    */
-  buildManifest(): { metadata: Record<string, any>; components: Record<string, any>[] } {
+  markComponentForDeletion<TIdentifierInput>(
+    componentClass: ManifestComponentClass<TIdentifierInput>,
+    identifier: TIdentifierInput,
+  ): this {
+    if (identifier == null || identifier === '') {
+      throw new Error('identifier is required');
+    }
+    if (!componentClass.componentType) {
+      throw new Error('type is required');
+    }
+    if (typeof componentClass.toDeletionIdentifier !== 'function') {
+      throw new TypeError('Component class must have a toDeletionIdentifier() method');
+    }
+
+    const deletion = componentClass.toDeletionIdentifier(identifier);
+    if (!deletion.type) {
+      throw new Error('type is required');
+    }
+    if (Object.keys(deletion).length <= 1) {
+      throw new Error('identifier is required');
+    }
+
+    this._componentsToDelete.push({ ...deletion });
+    return this;
+  }
+
+  /**
+   * Returns the manifest as a plain object with `metadata`, a flat `components` array,
+   * and a `components_to_delete` array when deletions are registered.
+   *
+   * @returns `{ metadata: { key, name, description? }, components, components_to_delete? }`
+   */
+  buildManifest(): BuiltManifest {
     const metadata: Record<string, any> = {
       key: this.key,
       name: this.name,
@@ -114,7 +211,11 @@ export class ManifestBuilder implements ManifestScope {
       metadata['description'] = this.description;
     }
     const components = this._components.map((c) => c.toDict());
-    return { metadata, components };
+    const manifest: BuiltManifest = { metadata, components };
+    if (this._componentsToDelete.length > 0) {
+      manifest.components_to_delete = this.componentsToDeleteList();
+    }
+    return manifest;
   }
 
   /**
@@ -126,6 +227,15 @@ export class ManifestBuilder implements ManifestScope {
     return this._components.map((c) => c.toDict());
   }
 
+  /**
+   * Returns the flat list of component deletion references.
+   *
+   * @returns An array of component identifier objects, in registration order.
+   */
+  componentsToDeleteList(): ManifestComponentDeletion[] {
+    return this._componentsToDelete.map((component) => ({ ...component }));
+  }
+
   /**
    * Returns the full manifest as a pretty-printed JSON string.
    *

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

@@ -1,5 +1,6 @@
 import type { FunctionRuntime } from './_helpers';
-import type { ManifestScope } from './manifest-builder';
+import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
+import type { ManifestComponentDeletion, ManifestScope } from './manifest-builder';
 
 /**
  * Initialization properties for {@link ManifestFunction}.
@@ -68,8 +69,14 @@ export interface ManifestFunctionProps {
  * Defines a serverless function and registers it with the manifest.
  *
  * A `ManifestFunction` packages TypeScript handler code that runs on Rippling's
- * serverless infrastructure. Functions are the backing implementation for
- * {@link SduiPage} surfaces. The handler must export `onRipplingEvent`.
+ * serverless infrastructure. The handler must export `onRipplingEvent`.
+ *
+ * Functions have two primary uses:
+ * 1. **Authoring SDUI for Custom Apps** — the function returns an SDUI spec
+ *    (built with `@rippling/sdui-builder`) that renders as a page tab. Wrap the
+ *    function in an {@link SduiPage} and reference it from an {@link App}.
+ * 2. **Workflow / event handlers** — functions invoked from rules, automations,
+ *    or callbacks that do not render UI.
  *
  * This class is named `ManifestFunction` to avoid collision with the JavaScript
  * built-in `Function`. It is also re-exported as `Function` from the barrel for
@@ -94,6 +101,15 @@ export interface ManifestFunctionProps {
  * @see {@link SduiPage} — wraps a `ManifestFunction` as a navigable UI surface.
  */
 export class ManifestFunction {
+  static readonly componentType = 'FUNCTION' as const;
+
+  static toDeletionIdentifier(apiName: string): ManifestComponentDeletion {
+    return {
+      type: ManifestFunction.componentType,
+      api_name: apiName,
+    };
+  }
+
   private readonly _apiName: string;
   private readonly _name: string;
   private readonly _code: string;
@@ -122,6 +138,30 @@ export class ManifestFunction {
     scope._register(this);
   }
 
+  /**
+   * Loads this function from the active existing-manifest JSON context.
+   */
+  static loadFromExisting(apiName: string, options: ExistingManifestContextOptions = {}): ManifestFunction {
+    return getExistingManifestContext(options).loadFunction(apiName);
+  }
+
+  /** @internal Hydrates a function from existing manifest wire JSON. */
+  static _fromExistingComponent(scope: ManifestScope, component: Record<string, any>): ManifestFunction {
+    const props: ManifestFunctionProps = {
+      apiName: component['api_name'],
+      name: component['name'] ?? component['api_name'],
+    };
+    if (component['code_draft'] !== undefined) props.code = component['code_draft'];
+    if (component['description'] !== undefined) props.description = component['description'];
+    if (component['dependencies'] !== undefined) props.dependencies = component['dependencies'];
+    if (component['deployment_options'] !== undefined) {
+      props.deploymentOptions = component['deployment_options'];
+    }
+    if (component['allowed_domains'] !== undefined) props.allowedDomains = component['allowed_domains'];
+    if (component['is_async'] !== undefined) props.isAsync = component['is_async'];
+    return new ManifestFunction(scope, props);
+  }
+
   /**
    * Returns the api_name of this function (e.g. `'gym_today_schedule_fn'`).
    */
@@ -136,7 +176,7 @@ export class ManifestFunction {
    */
   toDict(): Record<string, any> {
     const component: Record<string, any> = {
-      type: 'FUNCTION',
+      type: ManifestFunction.componentType,
       name: this._name,
       api_name: this._apiName,
     };