@rippling/rippling-sdk 0.2.0-alpha.33 → 0.2.0-alpha.35

package/lib/manifest/custom-object.mjs

@@ -0,0 +1,250 @@
+// ────────────────────────────────────────────────────────────────────────
+// Platform-managed standard fields — mirrors
+// `app/hub_platform/custom_objects/constants.py::STANDARD_FIELDS`.
+// Kept here (not in `field.ts`) so the `Field` class stays focused on
+// user-authored `__c` fields with full validation.
+// ────────────────────────────────────────────────────────────────────────
+/** Specs for the 9 standard fields every CO ships with. Order matches the backend constant. */
+const STANDARD_FIELD_SPECS = [
+    {
+        apiName: 'id',
+        displayName: 'ID',
+        description: 'The Rippling ID of a record',
+        dataType: { field_type: 'TEXT' },
+        required: true,
+        unique: true,
+    },
+    {
+        apiName: 'created_at',
+        displayName: 'Created Date',
+        description: 'The date and time a record was created',
+        dataType: { field_type: 'DATETIME' },
+        required: false,
+        unique: false,
+    },
+    {
+        apiName: 'updated_at',
+        displayName: 'Last Modified Date',
+        description: 'The date and time a record was last updated',
+        dataType: { field_type: 'DATETIME' },
+        required: false,
+        unique: false,
+    },
+    {
+        apiName: 'system_updated_at',
+        displayName: 'System Modified At',
+        description: 'The date and time a record was last updated by the system',
+        dataType: { field_type: 'DATETIME' },
+        required: false,
+        unique: false,
+    },
+    {
+        apiName: 'external_id',
+        displayName: 'External ID',
+        description: 'The external identifier for a record used in third party integrations',
+        dataType: { field_type: 'TEXT' },
+        required: false,
+        unique: true,
+    },
+    {
+        apiName: 'name',
+        displayName: 'Name',
+        description: 'A string used to describe a record. This is used for display purposes as well as search',
+        dataType: { field_type: 'TEXT' },
+        required: true,
+        unique: false,
+    },
+    {
+        apiName: 'owner_role',
+        displayName: 'Owner',
+        description: 'The Employee responsible for the record. This is used by Permissions to determine who has ability to view, edit, and delete data',
+        dataType: {
+            field_type: 'NATIVE_EDGE',
+            og_model_rql_name: 'Employee',
+            db_model_name: 'RoleWithCompany',
+            reference_column_storage_type: 'STRING',
+        },
+        required: false,
+        unique: false,
+    },
+    {
+        apiName: 'last_modified_by',
+        displayName: 'Last Modified by',
+        description: 'The Employee who made the latest change.',
+        dataType: {
+            field_type: 'NATIVE_EDGE',
+            og_model_rql_name: 'Employee',
+            db_model_name: 'RoleWithCompany',
+            reference_column_storage_type: 'STRING',
+        },
+        required: false,
+        unique: false,
+    },
+    {
+        apiName: 'created_by',
+        displayName: 'Created by',
+        description: 'The Employee who created the record',
+        dataType: {
+            field_type: 'NATIVE_EDGE',
+            og_model_rql_name: 'Employee',
+            db_model_name: 'RoleWithCompany',
+            reference_column_storage_type: 'STRING',
+        },
+        required: false,
+        unique: false,
+    },
+];
+/**
+ * Minimal `ManifestComponent` that emits a single standard field stub.
+ * Intentionally bypasses `Field`'s `__c` validator since standard api_names
+ * (`id`, `created_at`, …) don't carry the custom-field suffix.
+ */
+class _StandardField {
+    constructor(customObjectApiName, spec) {
+        this.customObjectApiName = customObjectApiName;
+        this.spec = spec;
+    }
+    toDict() {
+        return {
+            type: 'CUSTOM_OBJECT_FIELD',
+            custom_object_api_name: this.customObjectApiName,
+            field_api_name: this.spec.apiName,
+            field_display_name: this.spec.displayName,
+            data_type: { options_list: [], supported_types: [], ...this.spec.dataType },
+            description: this.spec.description,
+            is_required: this.spec.required,
+            is_unique: this.spec.unique,
+            is_indexed: null,
+            rql_formula: null,
+            formula_attr_metas: null,
+            is_standard: true,
+            derived_aggregated_field: null,
+            derived_field_formula: null,
+            section: null,
+        };
+    }
+}
+/**
+ * Defines a custom object and registers it with the manifest.
+ *
+ * A custom object is a new entity type with its own fields, validations, rules, list views,
+ * and page layouts. You would normally define all custom objects near the top of your manifest
+ * file, then define their children (fields, sections, rules, etc.) below. Each child takes
+ * the `CustomObject` instance as its first argument and registers automatically.
+ *
+ * @example
+ * ```ts
+ * const manifest = new ManifestBuilder({
+ *   key: 'gym_membership_management',
+ *   name: 'Gym Membership Management',
+ * });
+ *
+ * const gymCategory = new Category(manifest, { apiName: 'gym__c', name: 'Gym' });
+ *
+ * const memberObj = new CustomObject(manifest, {
+ *   apiName: 'gym_member__c',
+ *   name: 'Member',
+ *   pluralLabel: 'Members',
+ *   category: gymCategory,
+ *   description: 'Gym member profile, contact, and membership status',
+ *   icon: { emoji: '🏋️' },
+ * });
+ *
+ * // The object is now a scope — children register through it:
+ * const firstName = new TextField(memberObj, {
+ *   apiName: 'first_name__c',
+ *   displayName: 'First name',
+ *   required: true,
+ * });
+ * ```
+ *
+ * @remarks
+ * **Required: every `CustomObject` must have at least one `CustomObjectPageLayout` in the
+ * manifest.** Omitting it passes component-level validation but fails at the package level
+ * 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.
+ */
+export class CustomObject {
+    /**
+     * @param scope - The manifest or parent scope to register this object with.
+     * @param props - Initialization properties.
+     * @throws {Error} If `props.apiName` does not end with `__c`.
+     */
+    constructor(scope, props) {
+        if (!props.apiName.endsWith('__c')) {
+            throw new Error(`Custom object api_name must end with __c: ${props.apiName}`);
+        }
+        this._scope = scope;
+        this._apiName = props.apiName;
+        this._name = props.name;
+        this._category = props.category;
+        this._description = props.description;
+        this._icon = props.icon;
+        this._pluralLabel = props.pluralLabel;
+        this._nameFieldDetails = props.nameFieldDetails;
+        this._defaultFieldSectionName = props.defaultFieldSectionName;
+        scope._register(this);
+        // Backend closed-world validation requires these 9 configs for every new CO.
+        for (const spec of STANDARD_FIELD_SPECS) {
+            scope._register(new _StandardField(this._apiName, spec));
+        }
+    }
+    /** @internal Scope hook — forwards child registration up to the root builder. */
+    _register(component) {
+        this._scope._register(component);
+    }
+    /**
+     * Returns the api_name of this custom object (e.g. `'gym_member__c'`).
+     *
+     * Use the return value wherever a field or layout needs to reference this object by name.
+     */
+    getApiName() {
+        return this._apiName;
+    }
+    /**
+     * Returns the singular display name of this custom object (e.g. `'Member'`).
+     */
+    getName() {
+        return this._name;
+    }
+    /**
+     * Serializes this custom object to the wire format consumed by the manifest install endpoint.
+     *
+     * @returns A plain object with `type: 'CUSTOM_OBJECT'` and all configured fields.
+     * Optional fields are omitted when `null`. An `icon` with no populated keys is omitted entirely.
+     */
+    toDict() {
+        const component = {
+            type: 'CUSTOM_OBJECT',
+            api_name: this._apiName,
+            name: this._name,
+            description: this._description ?? null,
+            category_api_name: typeof this._category === 'string' ? this._category : this._category.getApiName(),
+        };
+        if (this._icon != null) {
+            const iconDict = {};
+            if (this._icon.emoji != null)
+                iconDict['emoji'] = this._icon.emoji;
+            if (this._icon.ripplingIcon != null)
+                iconDict['rippling_icon'] = this._icon.ripplingIcon;
+            if (this._icon.s3Bucket != null)
+                iconDict['s3_bucket'] = this._icon.s3Bucket;
+            if (this._icon.s3Key != null)
+                iconDict['s3_key'] = this._icon.s3Key;
+            // Mirror backend `if self.icon:` — empty dict is falsy and gets omitted.
+            if (Object.keys(iconDict).length > 0) {
+                component['icon'] = iconDict;
+            }
+        }
+        if (this._pluralLabel != null)
+            component['plural_label'] = this._pluralLabel;
+        if (this._nameFieldDetails != null)
+            component['name_field_details'] = this._nameFieldDetails;
+        if (this._defaultFieldSectionName != null) {
+            component['default_field_section_name'] = this._defaultFieldSectionName;
+        }
+        return component;
+    }
+}
+//# sourceMappingURL=custom-object.mjs.map

package/lib/manifest/custom-object.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-object.mjs","sourceRoot":"","sources":["../../src/lib/manifest/custom-object.ts"],"names":[],"mappings":"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"}