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

package/lib/manifest/validation.mjs

@@ -1,4 +1,5 @@
 import { generateId } from "./_helpers.mjs";
+import { getExistingManifestContext } from "./existing-manifest-context.mjs";
 /**
  * Defines a validation rule and registers it with the manifest.
  *
@@ -25,6 +26,13 @@ import { generateId } from "./_helpers.mjs";
  * ```
  */
 export class Validation {
+    static toDeletionIdentifier(identifier) {
+        return {
+            type: Validation.componentType,
+            rule_id: identifier.ruleId,
+            model_rql_name: identifier.modelRqlName,
+        };
+    }
     /**
      * @param customObject - The custom object this rule applies to.
      * @param props - Initialization properties.
@@ -41,6 +49,27 @@ export class Validation {
         this._fieldRef = props.fieldRef;
         customObject._register(this);
     }
+    /**
+     * Loads this validation rule from the active existing-manifest JSON context.
+     */
+    static loadFromExisting(ruleId, options = {}) {
+        return getExistingManifestContext(options).loadValidation(ruleId, options);
+    }
+    /** @internal Hydrates a validation rule from existing manifest wire JSON. */
+    static _fromExistingComponent(customObject, component, resolveField) {
+        const props = {
+            ruleId: component['rule_id'],
+            displayName: component['display_name'] ?? component['rule_id'],
+            rqlFormula: component['rql_formula'] ?? '',
+            errorMessage: component['custom_error_message'] ?? '',
+            state: component['state'],
+            level: component['level'],
+            ruleDescription: component['rule_description'] ?? '',
+        };
+        if (component['field_rql_name'] != null)
+            props.fieldRef = resolveField(component['field_rql_name']);
+        return new Validation(customObject, props);
+    }
     /**
      * Returns the stable identifier for this validation rule (e.g. `'gym_session_end_after_start'`).
      */
@@ -61,7 +90,7 @@ export class Validation {
      */
     toDict() {
         const component = {
-            type: 'CUSTOM_OBJECT_VALIDATION_RULE',
+            type: Validation.componentType,
             model_rql_name: this._customObjectApiName,
             rule_id: this._ruleId,
             state: this._state,
@@ -76,4 +105,5 @@ export class Validation {
         return component;
     }
 }
+Validation.componentType = 'CUSTOM_OBJECT_VALIDATION_RULE';
 //# sourceMappingURL=validation.mjs.map

package/lib/manifest/validation.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"validation.mjs","sourceRoot":"","sources":["../../src/lib/manifest/validation.ts"],"names":[],"mappings":"OAAO,EAAE,UAAU,EAA8C;AA6DjE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,OAAO,UAAU;IAWrB;;;OAGG;IACH,YAAY,YAA0B,EAAE,KAAsB;QAC5D,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,MAAM,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;QAClD,IAAI,CAAC,oBAAoB,GAAG,YAAY,CAAC,UAAU,EAAE,CAAC;QACtD,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,WAAW,CAAC;QACtC,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,UAAU,CAAC;QACpC,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC,YAAY,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC;QAC1B,IAAI,CAAC,gBAAgB,GAAG,KAAK,CAAC,eAAe,CAAC;QAC9C,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,QAAQ,CAAC;QAChC,YAAY,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,sBAAsB;QACpB,OAAO,IAAI,CAAC,oBAAoB,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,MAAM;QACJ,MAAM,SAAS,GAAwB;YACrC,IAAI,EAAE,+BAA+B;YACrC,cAAc,EAAE,IAAI,CAAC,oBAAoB;YACzC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,KAAK,EAAE,IAAI,CAAC,MAAM;YAClB,KAAK,EAAE,IAAI,CAAC,MAAM;YAClB,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;YACvC,oBAAoB,EAAE,IAAI,CAAC,aAAa;YACxC,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC;QACF,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI;YAAE,SAAS,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;QACtF,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}
+{"version":3,"file":"validation.mjs","sourceRoot":"","sources":["../../src/lib/manifest/validation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rippling/rippling-sdk",
-  "version": "0.2.0-alpha.38",
+  "version": "0.2.0-alpha.39",
   "description": "The official TypeScript library for the Rippling SDK API",
   "author": "Rippling SDK <no-reply@rippling.com>",
   "types": "./index.d.ts",

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}.
@@ -57,6 +58,15 @@ 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;
@@ -72,6 +82,22 @@ export class Category {
     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'`).
    */
@@ -93,7 +119,7 @@ export class Category {
    */
   toDict(): Record<string, any> {
     return {
-      type: 'CUSTOM_CATEGORY',
+      type: Category.componentType,
       api_name: this._apiName,
       name: this._name,
       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
@@ -267,6 +274,10 @@ export interface CustomObjectPageLayoutProps {
   blueprintKey?: string;
 }
 
+export interface CustomObjectPageLayoutLoadFromExistingOptions extends ExistingManifestContextOptions {
+  customObjectApiName?: string;
+}
+
 interface SerializedSectionField extends SectionFieldOptions {
   fieldRqlName: string;
 }
@@ -458,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
 // ---------------------------------------------------------------------------
@@ -503,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;
@@ -531,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'`).
    */
@@ -559,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,
@@ -297,6 +300,15 @@ export interface CustomObjectProps {
  * 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;
@@ -333,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);
@@ -362,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,