@rippling/rippling-sdk 0.2.0-alpha.48 → 0.2.0-alpha.50

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

@@ -1,7 +1,7 @@
 import { Category } from './category';
 import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
 import type { ManifestComponent, ManifestComponentDeletion, ManifestScope } from './manifest-builder';
-import { requireStringComponentField } from './_existing-component-fields';
+import { optionalStringComponentField, requireStringComponentField } from './_existing-component-fields';
 
 // ────────────────────────────────────────────────────────────────────────
 // Platform-managed standard fields — mirrors
@@ -199,9 +199,9 @@ export interface CustomObjectProps {
   /**
    * Human-readable description of what this entity represents.
    *
-   * Optional. @default null
+   * Required.
    */
-  description?: string | null;
+  description: string;
   /**
    * Icon shown next to the object name in the Rippling UI.
    *
@@ -301,7 +301,7 @@ export interface CustomObjectProps {
  * `owner_role`, `created_by`, and `last_modified_by` (all `Employee` references),
  * plus `name`, `created_at`, `updated_at`, `external_id`, and `id`. For any
  * "the employee responsible for this record" semantics, consider using
- * `owner_role` rather than adding a new {@link LookupField} targeting `'role'`.
+ * `owner_role` rather than adding a new {@link LookupField} targeting `'Employee'`.
  * `owner_role` drives Rippling's record-level permissions, so a parallel field
  * can fragment ownership and complicate the permission story.
  */
@@ -319,7 +319,7 @@ export class CustomObject implements ManifestScope {
   private readonly _apiName: string;
   private readonly _name: string;
   private readonly _category: Category;
-  private _description: string | null | undefined;
+  private _description: string;
   private _icon: IconConfig | null | undefined;
   private _pluralLabel: string | null | undefined;
   private _nameFieldDetails: Record<string, any> | null | undefined;
@@ -379,8 +379,8 @@ export class CustomObject implements ManifestScope {
       apiName: requireStringComponentField(component, 'api_name', CustomObject.componentType),
       name: requireStringComponentField(component, 'name', CustomObject.componentType),
       category: resolveCategory(categoryApiName),
+      description: optionalStringComponentField(component, 'description'),
     };
-    if (component['description'] !== undefined) props.description = component['description'];
     if (component['plural_label'] !== undefined) props.pluralLabel = component['plural_label'];
     if (component['name_field_details'] !== undefined) {
       props.nameFieldDetails = component['name_field_details'];
@@ -436,7 +436,7 @@ export class CustomObject implements ManifestScope {
       type: CustomObject.componentType,
       api_name: this._apiName,
       name: this._name,
-      description: this._description ?? null,
+      description: this._description,
       category_api_name: this._category.getApiName(),
     };
     if (this._icon != null) {

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

@@ -10,7 +10,11 @@ import { ManifestFunction } from './manifest-function';
 import { Rule } from './rule';
 import { SduiPage } from './sdui-page';
 import { Validation } from './validation';
-import { requireObjectComponentField, requireStringComponentField } from './_existing-component-fields';
+import {
+  optionalStringComponentField,
+  requireObjectComponentField,
+  requireStringComponentField,
+} from './_existing-component-fields';
 
 export interface ExistingManifest {
   metadata?: Record<string, any>;
@@ -145,10 +149,8 @@ export class ExistingManifestContext {
       const props = {
         key,
         name: typeof metadata['name'] === 'string' ? metadata['name'] : key,
+        description: optionalStringComponentField(metadata, 'description'),
       };
-      if (typeof metadata['description'] === 'string') {
-        (props as Record<string, any>)['description'] = metadata['description'];
-      }
       this.builder = new ManifestBuilder(props);
     }
     return this.builder;

package/src/lib/manifest/field.ts

@@ -9,7 +9,11 @@ import type { CustomObject } from './custom-object';
 import { CustomObjectFieldSection } from './custom-object-field-section';
 import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
 import type { ManifestComponentDeletion } from './manifest-builder';
-import { requireObjectComponentField, requireStringComponentField } from './_existing-component-fields';
+import {
+  optionalStringComponentField,
+  requireObjectComponentField,
+  requireStringComponentField,
+} from './_existing-component-fields';
 
 export interface CustomObjectFieldDeletionIdentifier {
   customObjectApiName: string;
@@ -70,7 +74,7 @@ function cloneJson<T>(value: T): T {
 interface CommonFieldProps {
   apiName: string;
   displayName: string;
-  description?: string;
+  description: string;
   section: CustomObjectFieldSection;
 }
 
@@ -86,7 +90,7 @@ export interface FieldProps {
   // props under `exactOptionalPropertyTypes`.
   fieldType?: FieldType | undefined;
   dataType?: Record<string, any> | undefined;
-  description?: string | null | undefined;
+  description: string;
   required?: boolean | null | undefined;
   unique?: boolean | null | undefined;
   indexed?: boolean | null | undefined;
@@ -237,7 +241,7 @@ export class Field {
   private readonly _fieldDisplayName: string;
   private readonly _customObjectApiName: string;
   private readonly _dataType: Record<string, any>;
-  private readonly _description: string | null;
+  private readonly _description: string;
   private readonly _isRequired: boolean | null;
   private readonly _isUnique: boolean | null;
   private readonly _isIndexed: boolean | null;
@@ -267,7 +271,7 @@ export class Field {
     if (props.options != null) dt['options_list'] = [...props.options];
     this._dataType = dt;
 
-    this._description = props.description ?? null;
+    this._description = props.description;
     this._isRequired = props.required ?? null;
     this._isUnique = props.unique ?? null;
     this._isIndexed = props.indexed ?? null;
@@ -302,8 +306,8 @@ export class Field {
       apiName: requireStringComponentField(component, 'field_api_name', Field.componentType),
       displayName: requireStringComponentField(component, 'field_display_name', Field.componentType),
       dataType: cloneJson(requireObjectComponentField(component, 'data_type', Field.componentType)),
+      description: optionalStringComponentField(component, 'description'),
     } as FieldProps;
-    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'];
@@ -717,7 +721,7 @@ export class FileField extends Field {
 export interface LookupFieldProps extends CommonFieldProps {
   /**
    * 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'`).
+   * or a raw api_name string for native Rippling models (e.g. `'Employee'`).
    *
    * Required.
    */
@@ -740,11 +744,11 @@ export interface LookupFieldProps extends CommonFieldProps {
  *
  * @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
+ * `owner_role` standard field instead of a new `LookupField` to `'Employee'`.** 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
+ * permission story. Consider a new `LookupField` to `'Employee'` when you need a
  * *second*, non-owner employee reference (e.g. an "approver", a "manager on record").
  */
 export class LookupField extends Field {

package/src/lib/manifest/index.ts

@@ -35,28 +35,55 @@ export {
   type AddPageLayoutFieldsOptions,
   type AddPageLayoutSectionOptions,
   type AddPageLayoutTabOptions,
+  type BlueprintKey,
+  type CanvasCompositionId,
+  type CanvasSection,
+  type CustomObjectCustomSectionComponentKey,
   type CustomObjectPageLayoutLoadFromExistingOptions,
   type CustomObjectPageLayoutProps,
+  type CustomSection,
   type CustomTab,
+  type FieldMovementOption,
+  type FieldRqlName,
   type FieldsSection,
   type HeaderEdits,
+  type HeaderButtonKey,
+  type HeaderFieldKey,
+  type JsonObject,
+  type JsonPrimitive,
+  type JsonValue,
+  type LayoutApiName,
   type NewHeaderField,
+  type ObjectRqlName,
   type PageLayoutDeletionIdentifier,
   type PageLayoutMutationPosition,
   type PageLayoutSection,
+  type PageLayoutSectionOptions,
   type PageLayoutTab,
+  type RelatedFieldSection,
+  type RelatedObjectRqlName,
+  type RelatedObjectSection,
   type RemoveHeaderFieldOptions,
   type RemovePageLayoutFieldOptions,
   type RemovePageLayoutSectionOptions,
   type RemovePageLayoutTabOptions,
+  type ReportsSection,
+  type ReportsSectionItem,
+  type ResizableLayoutPosition,
   type SectionField,
+  type SectionFieldDefaultValue,
+  type SectionFieldInput,
   type SectionFieldOptions,
   type SectionFieldRef,
   type SectionFieldsLayout,
+  type SectionKey,
+  type SectionMovementOption,
   type SystemHeaderFieldEdit,
   type SystemSectionEdit,
   type SystemTabEdit,
+  type TabKey,
   type TabEdits,
+  type TabLayout,
   type TabWithSections,
   type VisibilityCondition,
   type VisibilityConditions,

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

@@ -4,6 +4,7 @@ import { getExistingManifestContext, type ExistingManifestContextOptions } from
 import type { Field } from './field';
 import type { ManifestComponentDeletion } from './manifest-builder';
 import {
+  optionalStringComponentField,
   requireArrayComponentField,
   requireBooleanComponentField,
   requireStringComponentField,
@@ -74,9 +75,9 @@ export interface ListViewDefProps {
   /**
    * Human-readable description of this view.
    *
-   * Optional. @default null
+   * Required.
    */
-  description?: string;
+  description: string;
   /**
    * Per-column configuration overrides keyed by field API name.
    *
@@ -151,7 +152,7 @@ export class ListViewDef {
   private readonly _orderBy: Field | undefined;
   private readonly _sortOrder: SortOrder | undefined;
   private readonly _objectScope: ObjectScope | undefined;
-  private readonly _description: string | undefined;
+  private readonly _description: string;
   private readonly _columnConfig: Record<string, ListViewColumnConfig> | undefined;
   private readonly _rqlFilter: string | undefined;
 
@@ -198,12 +199,12 @@ export class ListViewDef {
     const props: ListViewDefProps = {
       viewId: requireStringComponentField(component, 'view_id', ListViewDef.componentType),
       name: requireStringComponentField(component, 'name', ListViewDef.componentType),
+      description: optionalStringComponentField(component, 'description'),
       fields: requireArrayComponentField<string>(component, 'fields', ListViewDef.componentType).map(
         (fieldApiName: string) => resolveField(fieldApiName),
       ),
       isPublic: requireBooleanComponentField(component, 'public', ListViewDef.componentType),
     };
-    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'];
@@ -240,8 +241,8 @@ export class ListViewDef {
       name: this._name,
       public: this._isPublic,
       fields: this._fields.map((f) => f.getApiName()),
+      description: this._description,
     };
-    if (this._description != null) d['description'] = this._description;
     if (this._objectScope != null) d['object_scope'] = this._objectScope;
     if (this._sortOrder != null) d['sort_order'] = this._sortOrder;
     if (this._orderBy != null) d['order_by'] = this._orderBy.getApiName();

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

@@ -74,9 +74,9 @@ export interface ManifestBuilderProps {
   /**
    * Human-readable description of what this manifest contains.
    *
-   * Optional.
+   * Required.
    */
-  description?: string;
+  description: string;
 }
 
 /**
@@ -131,7 +131,7 @@ export class ManifestBuilder implements ManifestScope {
     }
     this.key = props.key;
     this.name = props.name || props.key;
-    this.description = props.description ?? '';
+    this.description = props.description;
   }
 
   /**
@@ -200,16 +200,14 @@ export class ManifestBuilder implements ManifestScope {
    * 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? }`
+   * @returns `{ metadata: { key, name, description }, components, components_to_delete? }`
    */
   buildManifest(): BuiltManifest {
     const metadata: Record<string, any> = {
       key: this.key,
       name: this.name,
+      description: this.description,
     };
-    if (this.description) {
-      metadata['description'] = this.description;
-    }
     const components = this._components.map((c) => c.toDict());
     const manifest: BuiltManifest = { metadata, components };
     if (this._componentsToDelete.length > 0) {

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

@@ -1,6 +1,6 @@
 import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
 import type { ManifestComponentDeletion, ManifestScope } from './manifest-builder';
-import { requireStringComponentField } from './_existing-component-fields';
+import { optionalStringComponentField, requireStringComponentField } from './_existing-component-fields';
 
 /**
  * Initialization properties for {@link ManifestFunction}.
@@ -27,9 +27,9 @@ export interface ManifestFunctionProps {
   /**
    * Human-readable description of what this function does.
    *
-   * Optional. @default `''`
+   * Required.
    */
-  description?: string;
+  description: string;
   /**
    * NPM package dependencies as a `{ packageName: versionRange }` map
    * (e.g. `{ '@rippling/rippling-sdk': '^0.2.0' }`).
@@ -65,8 +65,8 @@ export interface ManifestFunctionProps {
  *
  * 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}.
+ *    (built with `@rippling/rippling-sdk/lib/sdui`) 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.
  *
@@ -83,7 +83,6 @@ export interface ManifestFunctionProps {
  *   code: handlerSource,
  *   dependencies: {
  *     '@rippling/rippling-sdk': '^0.2.0-alpha.33',
- *     '@rippling/sdui-builder': '^0.1.0',
  *   },
  *   isAsync: false,
  * });
@@ -118,7 +117,7 @@ export class ManifestFunction {
     this._apiName = props.apiName;
     this._name = props.name;
     this._code = props.code ?? '';
-    this._description = props.description ?? '';
+    this._description = props.description;
     this._dependencies = props.dependencies;
     this._deploymentOptions = props.deploymentOptions;
     this._allowedDomains = props.allowedDomains;
@@ -138,9 +137,9 @@ export class ManifestFunction {
     const props: ManifestFunctionProps = {
       apiName: requireStringComponentField(component, 'api_name', ManifestFunction.componentType),
       name: requireStringComponentField(component, 'name', ManifestFunction.componentType),
+      description: optionalStringComponentField(component, 'description'),
     };
     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'];
@@ -167,8 +166,8 @@ export class ManifestFunction {
       type: ManifestFunction.componentType,
       name: this._name,
       api_name: this._apiName,
+      description: this._description,
     };
-    if (this._description) component['description'] = this._description;
     if (this._code) component['code_draft'] = this._code;
     if (this._dependencies != null) component['dependencies'] = this._dependencies;
     if (this._deploymentOptions != null) component['deployment_options'] = this._deploymentOptions;

package/src/lib/manifest/rule.ts

@@ -3,7 +3,7 @@ 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';
-import { requireStringComponentField } from './_existing-component-fields';
+import { optionalStringComponentField, requireStringComponentField } from './_existing-component-fields';
 
 export interface RuleDeletionIdentifier {
   flowId: string;
@@ -75,9 +75,9 @@ export interface RuleProps {
   /**
    * Internal description of this rule (for developer reference only).
    *
-   * Optional. @default null
+   * Required.
    */
-  description?: string;
+  description: string;
   /**
    * Actions to run when the rule fires. Each action sets one field to a fixed value
    * or RQL formula result.
@@ -154,7 +154,7 @@ export class Rule {
   private readonly _triggerType: TriggerType;
   private readonly _rqlCondition: string | undefined;
   private readonly _updateTriggerType: UpdateTriggerType | undefined;
-  private readonly _description: string | undefined;
+  private readonly _description: string;
   private readonly _actions: RuleAction[];
 
   /**
@@ -197,6 +197,7 @@ export class Rule {
       flowId: requireStringComponentField(component, 'flow_id', Rule.componentType),
       flowName: requireStringComponentField(component, 'flow_name', Rule.componentType),
       triggerType: requireStringComponentField(component, 'trigger_type', Rule.componentType) as TriggerType,
+      description: optionalStringComponentField(component, 'description'),
       actions: (component['actions'] ?? []).map((action: Record<string, any>): RuleAction => {
         const out: RuleAction = {
           targetField: resolveField(action['target_field']),
@@ -206,7 +207,6 @@ export class Rule {
         return out;
       }),
     };
-    if (component['description'] !== undefined) props.description = component['description'];
     if (component['rql_condition'] !== undefined) props.rqlCondition = component['rql_condition'];
     if (component['update_trigger_type'] !== undefined) {
       props.updateTriggerType = component['update_trigger_type'];
@@ -241,8 +241,8 @@ export class Rule {
       flow_id: this._flowId,
       flow_name: this._flowName,
       trigger_type: this._triggerType,
+      description: this._description,
     };
-    if (this._description != null) component['description'] = this._description;
     if (this._updateTriggerType != null) component['update_trigger_type'] = this._updateTriggerType;
     if (this._rqlCondition != null) component['rql_condition'] = this._rqlCondition;
     if (this._actions.length > 0) component['actions'] = this._actions.map(actionToDict);

package/src/lib/manifest/sdui-page.ts

@@ -1,7 +1,7 @@
 import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
 import type { ManifestFunction } from './manifest-function';
 import type { ManifestComponentDeletion, ManifestScope } from './manifest-builder';
-import { requireStringComponentField } from './_existing-component-fields';
+import { optionalStringComponentField, requireStringComponentField } from './_existing-component-fields';
 
 /**
  * Initialization properties for {@link SduiPage}.
@@ -29,9 +29,9 @@ export interface SduiPageProps {
   /**
    * Human-readable description of what this page shows.
    *
-   * Optional. @default `''`
+   * Required.
    */
-  description?: string;
+  description: string;
 }
 
 /**
@@ -92,7 +92,7 @@ export class SduiPage {
     this._sduiPageId = props.sduiPageId;
     this._name = props.name;
     this._functionApiName = typeof props.function === 'string' ? props.function : props.function.getApiName();
-    this._description = props.description ?? '';
+    this._description = props.description;
     scope._register(this);
   }
 
@@ -118,10 +118,8 @@ export class SduiPage {
       sduiPageId: requireStringComponentField(component, 'sdui_page_id', SduiPage.componentType),
       name: requireStringComponentField(component, 'name', SduiPage.componentType),
       function: resolveFunction(functionApiName),
+      description: optionalStringComponentField(component, 'description'),
     };
-    if (component['description'] !== undefined) {
-      props.description = component['description'];
-    }
     return new SduiPage(scope, props);
   }
 

package/src/lib/manifest.ts

@@ -0,0 +1 @@
+export * from './manifest/index';