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

package/src/lib/manifest/app.ts

@@ -1,5 +1,6 @@
 import { CustomObject } from './custom-object';
-import type { ManifestScope } from './manifest-builder';
+import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
+import type { ManifestComponentDeletion, ManifestScope } from './manifest-builder';
 import { SduiPage } from './sdui-page';
 
 /**
@@ -82,6 +83,11 @@ function resolvePage(entry: AppPage): Record<string, any> {
   }
 }
 
+function cloneJson<T>(value: T): T {
+  if (value == null) return value;
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
 /**
  * Defines a Rippling app and registers it with the manifest.
  *
@@ -105,6 +111,15 @@ function resolvePage(entry: AppPage): Record<string, any> {
  * @see {@link SduiPage} — SDUI surface tab source.
  */
 export class App {
+  static readonly componentType = 'CUSTOM_APP' as const;
+
+  static toDeletionIdentifier(apiName: string): ManifestComponentDeletion {
+    return {
+      type: App.componentType,
+      api_name: apiName,
+    };
+  }
+
   private readonly _apiName: string;
   private readonly _name: string;
   private readonly _description: string | undefined;
@@ -127,6 +142,35 @@ export class App {
     scope._register(this);
   }
 
+  /**
+   * Loads this app from the active existing-manifest JSON context.
+   */
+  static loadFromExisting(apiName: string, options: ExistingManifestContextOptions = {}): App {
+    return getExistingManifestContext(options).loadApp(apiName);
+  }
+
+  /** @internal Hydrates an app from existing manifest wire JSON. */
+  static _fromExistingComponent(scope: ManifestScope, component: Record<string, any>): App {
+    const app = Object.create(App.prototype) as App;
+    Object.assign(app as Record<string, any>, {
+      _apiName: component['api_name'],
+      _name: component['name'] ?? component['api_name'],
+      _description: component['description'],
+      _appType: component['app_type'],
+      _icon: App.appIconFromExistingComponent(component['icon']),
+      _pages: cloneJson(component['pages'] ?? []),
+    });
+    scope._register(app);
+    return app;
+  }
+
+  private static appIconFromExistingComponent(value: unknown): AppIcon | undefined {
+    if (value == null || typeof value !== 'object') return undefined;
+    const wire = value as Record<string, any>;
+    if (typeof wire['s3_bucket'] !== 'string' || typeof wire['s3_key'] !== 'string') return undefined;
+    return { s3Bucket: wire['s3_bucket'], s3Key: wire['s3_key'] };
+  }
+
   /**
    * Returns the api_name of this app (e.g. `'gym_membership_management_app'`).
    */
@@ -148,7 +192,7 @@ export class App {
    */
   toDict(): Record<string, any> {
     const component: Record<string, any> = {
-      type: 'CUSTOM_APP',
+      type: App.componentType,
       api_name: this._apiName,
       name: this._name,
     };

package/src/lib/manifest/category.ts

@@ -1,4 +1,5 @@
-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 Category}.
@@ -19,9 +20,11 @@ export interface CategoryProps {
   /**
    * Human-readable description of what this category groups.
    *
-   * Optional. @default null
+   * Required. The backend (`CustomCategoryConfig.description: str`) requires the
+   * key to be present and rejects `null`. Pass an empty string only if you truly
+   * have no meaningful copy.
    */
-  description?: string | null;
+  description: string;
 }
 
 /**
@@ -55,9 +58,18 @@ export interface CategoryProps {
  * @see {@link CustomObject} — references this category via instance or api_name string.
  */
 export class Category {
+  static readonly componentType = 'CUSTOM_CATEGORY' as const;
+
+  static toDeletionIdentifier(apiName: string): ManifestComponentDeletion {
+    return {
+      type: Category.componentType,
+      api_name: apiName,
+    };
+  }
+
   private readonly _apiName: string;
   private readonly _name: string;
-  private readonly _description: string | null;
+  private readonly _description: string;
 
   /**
    * @param scope - The manifest to register this category with.
@@ -66,10 +78,26 @@ export class Category {
   constructor(scope: ManifestScope, props: CategoryProps) {
     this._apiName = props.apiName;
     this._name = props.name;
-    this._description = props.description ?? null;
+    this._description = props.description;
     scope._register(this);
   }
 
+  /**
+   * Loads this category from the active existing-manifest JSON context.
+   */
+  static loadFromExisting(apiName: string, options: ExistingManifestContextOptions = {}): Category {
+    return getExistingManifestContext(options).loadCategory(apiName);
+  }
+
+  /** @internal Hydrates a category from existing manifest wire JSON. */
+  static _fromExistingComponent(scope: ManifestScope, component: Record<string, any>): Category {
+    return new Category(scope, {
+      apiName: component['api_name'],
+      name: component['name'] ?? component['api_name'],
+      description: component['description'] ?? '',
+    });
+  }
+
   /**
    * Returns the api_name of this category (e.g. `'gym__c'`).
    */
@@ -91,10 +119,10 @@ export class Category {
    */
   toDict(): Record<string, any> {
     return {
-      type: 'CUSTOM_CATEGORY',
+      type: Category.componentType,
       api_name: this._apiName,
       name: this._name,
-      description: this._description ?? null,
+      description: this._description,
     };
   }
 }

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

@@ -1,5 +1,11 @@
 import { generateId } from './_helpers';
 import type { CustomObject } from './custom-object';
+import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
+import type { ManifestComponentDeletion } from './manifest-builder';
+
+export interface CustomObjectFieldSectionLoadFromExistingOptions extends ExistingManifestContextOptions {
+  customObjectApiName?: string;
+}
 
 /**
  * Initialization properties for {@link CustomObjectFieldSection}.
@@ -45,6 +51,15 @@ export interface CustomObjectFieldSectionProps {
  * @see {@link CustomObjectPageLayout} — controls which sections appear on which tab.
  */
 export class CustomObjectFieldSection {
+  static readonly componentType = 'CUSTOM_OBJECT_FIELD_SECTION' as const;
+
+  static toDeletionIdentifier(sectionId: string): ManifestComponentDeletion {
+    return {
+      type: CustomObjectFieldSection.componentType,
+      section_id: sectionId,
+    };
+  }
+
   private readonly _sectionId: string;
   private readonly _name: string;
   private readonly _model: CustomObject;
@@ -60,6 +75,27 @@ export class CustomObjectFieldSection {
     customObject._register(this);
   }
 
+  /**
+   * Loads this field section from the active existing-manifest JSON context.
+   */
+  static loadFromExisting(
+    sectionId: string,
+    options: CustomObjectFieldSectionLoadFromExistingOptions = {},
+  ): CustomObjectFieldSection {
+    return getExistingManifestContext(options).loadFieldSection(sectionId, options);
+  }
+
+  /** @internal Hydrates a field section from existing manifest wire JSON. */
+  static _fromExistingComponent(
+    customObject: CustomObject,
+    component: Record<string, any>,
+  ): CustomObjectFieldSection {
+    return new CustomObjectFieldSection(customObject, {
+      sectionId: component['section_id'],
+      name: component['name'] ?? component['section_id'],
+    });
+  }
+
   /**
    * Returns the stable identifier for this section (e.g. `'sec_gm_profile'`).
    *
@@ -91,7 +127,7 @@ export class CustomObjectFieldSection {
    */
   toDict(): Record<string, any> {
     return {
-      type: 'CUSTOM_OBJECT_FIELD_SECTION',
+      type: CustomObjectFieldSection.componentType,
       section_id: this._sectionId,
       model_name: this._model.getApiName(),
       name: this._name,

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

@@ -1,7 +1,14 @@
 import { generateId } from './_helpers';
 import { CustomObjectFieldSection } from './custom-object-field-section';
 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 PageLayoutDeletionIdentifier {
+  layoutId: string;
+  objectRqlName: string;
+}
 
 // ---------------------------------------------------------------------------
 // header_edits — HeaderEditsDTO
@@ -96,6 +103,8 @@ export interface FieldsSection {
   name?: string;
   /** Fields to display in this section. Required. */
   fields: SectionField[];
+  /** Column layout for the fields. Optional. @default `'responsive'` (backend default). */
+  layout?: SectionFieldsLayout;
 }
 
 /**
@@ -265,6 +274,10 @@ export interface CustomObjectPageLayoutProps {
   blueprintKey?: string;
 }
 
+export interface CustomObjectPageLayoutLoadFromExistingOptions extends ExistingManifestContextOptions {
+  customObjectApiName?: string;
+}
+
 interface SerializedSectionField extends SectionFieldOptions {
   fieldRqlName: string;
 }
@@ -274,6 +287,7 @@ interface SerializedFieldsSection {
   key: string;
   name: string;
   fields: SerializedSectionField[];
+  layout?: SectionFieldsLayout;
 }
 
 interface SerializedTabWithSections {
@@ -380,12 +394,14 @@ function normalizeFieldsSection(
   assertSectionBelongsTo(customObject, input.section);
   const key = input.key ?? input.section.getSectionId();
   const name = input.name ?? input.section.getName();
-  return {
+  const normalized: SerializedFieldsSection = {
     key,
     name,
     type: 'fields_section',
     fields: input.fields.map((field) => normalizeSectionField(customObject, input.section, key, field)),
   };
+  if (input.layout != null) normalized.layout = input.layout;
+  return normalized;
 }
 
 function normalizeTab(customObject: CustomObject, tab: PageLayoutTab): SerializedPageLayoutTab {
@@ -453,6 +469,11 @@ function normalizeTabEdits(customObject: CustomObject, tabEdits: TabEdits): Seri
   return normalized;
 }
 
+function cloneJson<T>(value: T): T {
+  if (value == null) return value;
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
 // ---------------------------------------------------------------------------
 // Class
 // ---------------------------------------------------------------------------
@@ -498,6 +519,16 @@ function normalizeTabEdits(customObject: CustomObject, tabEdits: TabEdits): Seri
  * @see {@link CustomObjectPageLayout.basic} — factory for simple single-tab layouts.
  */
 export class CustomObjectPageLayout {
+  static readonly componentType = 'CUSTOM_OBJECT_PAGE_LAYOUT' as const;
+
+  static toDeletionIdentifier(identifier: PageLayoutDeletionIdentifier): ManifestComponentDeletion {
+    return {
+      type: CustomObjectPageLayout.componentType,
+      layout_id: identifier.layoutId,
+      object_rql_name: identifier.objectRqlName,
+    };
+  }
+
   private readonly _layoutId: string;
   private readonly _apiName: string;
   private readonly _customObjectApiName: string;
@@ -526,6 +557,40 @@ export class CustomObjectPageLayout {
     customObject._register(this);
   }
 
+  /**
+   * Loads this page layout from the active existing-manifest JSON context.
+   *
+   * `id` resolves against `layout_id` first, then `api_name`. When loading by
+   * api_name such as `'default'`, pass `customObjectApiName` if multiple objects
+   * have a layout with the same api_name.
+   */
+  static loadFromExisting(
+    layoutIdOrApiName: string,
+    options: CustomObjectPageLayoutLoadFromExistingOptions = {},
+  ): CustomObjectPageLayout {
+    return getExistingManifestContext(options).loadPageLayout(layoutIdOrApiName, options);
+  }
+
+  /** @internal Hydrates a page layout from existing manifest wire JSON. */
+  static _fromExistingComponent(
+    customObject: CustomObject,
+    component: Record<string, any>,
+  ): CustomObjectPageLayout {
+    const layout = Object.create(CustomObjectPageLayout.prototype) as CustomObjectPageLayout;
+    Object.assign(layout as Record<string, any>, {
+      _layoutId: component['layout_id'],
+      _apiName: component['api_name'],
+      _customObjectApiName: component['object_rql_name'],
+      _name: component['name'] ?? component['api_name'],
+      _tabEdits: cloneJson(component['tab_edits'] ?? {}),
+      _headerEdits: cloneJson(component['header_edits'] ?? {}),
+      _visibilityConditions: cloneJson(component['visibility_conditions'] ?? {}),
+      _blueprintKey: component['blueprint_key'],
+    });
+    customObject._register(layout);
+    return layout;
+  }
+
   /**
    * Returns the stable identifier for this layout record (e.g. `'layout_gym_member'`).
    */
@@ -554,7 +619,7 @@ export class CustomObjectPageLayout {
    */
   toDict(): Record<string, any> {
     const d: Record<string, any> = {
-      type: 'CUSTOM_OBJECT_PAGE_LAYOUT',
+      type: CustomObjectPageLayout.componentType,
       layout_id: this._layoutId,
       api_name: this._apiName,
       object_rql_name: this._customObjectApiName,

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

@@ -1,5 +1,6 @@
 import { Category } from './category';
-import type { ManifestComponent, ManifestScope } from './manifest-builder';
+import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
+import type { ManifestComponent, ManifestComponentDeletion, ManifestScope } from './manifest-builder';
 
 // ────────────────────────────────────────────────────────────────────────
 // Platform-managed standard fields — mirrors
@@ -113,6 +114,8 @@ const STANDARD_FIELD_SPECS: ReadonlyArray<{
  * (`id`, `created_at`, …) don't carry the custom-field suffix.
  */
 class _StandardField implements ManifestComponent {
+  static readonly componentType = 'CUSTOM_OBJECT_FIELD' as const;
+
   constructor(
     private readonly customObjectApiName: string,
     private readonly spec: (typeof STANDARD_FIELD_SPECS)[number],
@@ -120,7 +123,7 @@ class _StandardField implements ManifestComponent {
 
   toDict(): Record<string, any> {
     return {
-      type: 'CUSTOM_OBJECT_FIELD',
+      type: _StandardField.componentType,
       custom_object_api_name: this.customObjectApiName,
       field_api_name: this.spec.apiName,
       field_display_name: this.spec.displayName,
@@ -215,6 +218,21 @@ export interface CustomObjectProps {
    * Overrides for the auto-number name field — controls the format string and starting number.
    * Leave `null` to use the default name field behavior.
    *
+   * Example:
+   * ```ts
+   * nameFieldDetails: {
+   *   is_autonumber_field: true,
+   *   starting_number: 1,
+   *   autonumber_format: 'EXP-{0000}',
+   * }
+   * ```
+   *
+   * @remarks
+   * The backend auto-appends `{0000}` to `autonumber_format` if the format string
+   * doesn't already contain a sequence token — so `'EXP-'` becomes `'EXP-{0000}'`
+   * on the wire. Include the token explicitly when you want a different width
+   * (e.g. `'EXP-{00000}'`).
+   *
    * Optional. @default null
    */
   nameFieldDetails?: Record<string, any> | null;
@@ -241,7 +259,7 @@ export interface CustomObjectProps {
  *   name: 'Gym Membership Management',
  * });
  *
- * const gymCategory = new Category(manifest, { apiName: 'gym__c', name: 'Gym' });
+ * const gymCategory = new Category(manifest, { apiName: 'gym__c', name: 'Gym', description: 'Gym domain' });
  *
  * const memberObj = new CustomObject(manifest, {
  *   apiName: 'gym_member__c',
@@ -266,8 +284,31 @@ export interface CustomObjectProps {
  * with `DEPENDENCY_ERROR: Page layout config for CO (api_name=...) not found in package
  * configs. CO requires at least one page layout in the package.`
  * Use {@link CustomObjectPageLayout.basic} for a minimal single-tab layout.
+ *
+ * **Consider defining at least one {@link ListViewDef}.** Without a list view,
+ * the records page has nothing to display by default — users land on an empty grid.
+ * Consider shipping a "default" view with the columns most users want to see
+ * (typically `name`, the status / category field, owner, and `created_at`), sorted
+ * however the records are most commonly browsed.
+ *
+ * **Consider system fields before authoring new ones.** Every CO ships with
+ * `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` drives Rippling's record-level permissions, so a parallel field
+ * can fragment ownership and complicate the permission story.
  */
 export class CustomObject implements ManifestScope {
+  static readonly componentType = 'CUSTOM_OBJECT' as const;
+
+  static toDeletionIdentifier(apiName: string): ManifestComponentDeletion {
+    return {
+      type: CustomObject.componentType,
+      api_name: apiName,
+    };
+  }
+
   private readonly _scope: ManifestScope;
   private readonly _apiName: string;
   private readonly _name: string;
@@ -304,6 +345,49 @@ export class CustomObject implements ManifestScope {
     }
   }
 
+  /**
+   * Loads this custom object from the active existing-manifest JSON context.
+   */
+  static loadFromExisting(apiName: string, options: ExistingManifestContextOptions = {}): CustomObject {
+    return getExistingManifestContext(options).loadCustomObject(apiName);
+  }
+
+  /** @internal Hydrates a custom object from existing manifest wire JSON. */
+  static _fromExistingComponent(
+    scope: ManifestScope,
+    component: Record<string, any>,
+    resolveCategory: (apiName: string) => Category | string,
+  ): CustomObject {
+    const categoryApiName = component['category_api_name'];
+    const props: CustomObjectProps = {
+      apiName: component['api_name'],
+      name: component['name'] ?? component['api_name'],
+      category: typeof categoryApiName === 'string' ? resolveCategory(categoryApiName) : categoryApiName,
+    };
+    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'];
+    }
+    if (component['default_field_section_name'] !== undefined) {
+      props.defaultFieldSectionName = component['default_field_section_name'];
+    }
+    const icon = CustomObject.iconFromExistingComponent(component['icon']);
+    if (icon != null) props.icon = icon;
+    return new CustomObject(scope, props);
+  }
+
+  private static iconFromExistingComponent(value: unknown): IconConfig | undefined {
+    if (value == null || typeof value !== 'object') return undefined;
+    const wire = value as Record<string, any>;
+    const icon: IconConfig = {};
+    if (wire['emoji'] !== undefined) icon.emoji = wire['emoji'];
+    if (wire['rippling_icon'] !== undefined) icon.ripplingIcon = wire['rippling_icon'];
+    if (wire['s3_bucket'] !== undefined) icon.s3Bucket = wire['s3_bucket'];
+    if (wire['s3_key'] !== undefined) icon.s3Key = wire['s3_key'];
+    return Object.keys(icon).length > 0 ? icon : undefined;
+  }
+
   /** @internal Scope hook — forwards child registration up to the root builder. */
   _register(component: ManifestComponent): void {
     this._scope._register(component);
@@ -333,7 +417,7 @@ export class CustomObject implements ManifestScope {
    */
   toDict(): Record<string, any> {
     const component: Record<string, any> = {
-      type: 'CUSTOM_OBJECT',
+      type: CustomObject.componentType,
       api_name: this._apiName,
       name: this._name,
       description: this._description ?? null,