@rippling/rippling-sdk 0.2.0-alpha.34 → 0.2.0-alpha.36

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

@@ -1,28 +1,3 @@
-/*
- * The contents of this file were inserted manually and are not generated by Stainless.
- *
- * Custom object page layouts (detail page structure).
- * Backend schema: CUSTOM_OBJECT_PAGE_LAYOUT (v2)
- *
- * CDK-style: `new CustomObjectPageLayout(customObject, props)` auto-registers
- * with the CO's scope. `blueprint_key` defaults to the CO's api_name.
- * For the layout that drives **Add** and the default detail view, use
- * `apiName: 'default'` (one per custom object). `CustomObjectPageLayout.basic`
- * uses `default` automatically.
- *
- * TabEditsDTO / HeaderEditsDTO / VisibilityConditionsDTO are strict
- * dataclasses on the backend. They expect camelCase keys on the wire
- * (newTabs, systemTabEdits, fieldRqlName, newTitleField, ...). Snake_case
- * keys are silently dropped and produce an empty layout on deploy. The
- * interfaces below mirror the DTO field aliases exactly.
- *
- * TS catches misspellings on direct object literals but not on spreads,
- * `as` casts, or loosely-typed variables — so be careful when constructing
- * these objects dynamically.
- *
- * DTO references: types/edits.py, types/layout.py, types/sections.py.
- */
-
 import { generateId } from './_helpers';
 import type { CustomObject } from './custom-object';
 import type { Field } from './field';
@@ -33,34 +8,56 @@ import type { Field } from './field';
 
 /** Edit to a built-in (system) header field. */
 export interface SystemHeaderFieldEdit {
+  /** Replace the system field's RQL field reference. Optional. */
   newRqlField?: string;
+  /** Remove this system field from the header. Optional. */
   deleted?: boolean;
 }
 
-/** Custom header field added via newFields. `key` is required + non-empty. */
+/**
+ * Custom header field added via `newFields`.
+ *
+ * `key` is required and must be non-empty — it is used as the stable identity
+ * for this field in `headerFieldsOrder` and visibility conditions.
+ */
 export interface NewHeaderField {
+  /** RQL field name to display. Required. */
   rqlName: string;
+  /** Stable key for this field. Required. */
   key: string;
+  /** Whether the user can remove this field. Optional. */
   canBeDeleted?: boolean;
+  /** Whether the user can swap this field for another. Optional. */
   canBeChanged?: boolean;
+  /** Whether the user can reorder this field. Optional. */
   canBeMoved?: boolean;
 }
 
 /**
- * Strict shape for header_edits. Only the keys listed here are accepted by
- * HeaderEditsDTO — anything else is dropped on the wire. Pass `{}` for an
- * empty header.
+ * Header configuration for a page layout (`header_edits`).
+ *
+ * Only the keys listed here are accepted — anything else is silently dropped
+ * on the wire. Pass `{}` for an unchanged header.
+ *
+ * > **Caution:** key names are camelCase on the wire. Snake_case keys are
+ * > silently dropped and produce an empty header on deploy.
  */
 export interface HeaderEdits {
+  /** Replace the record title field (pass the field's api_name). Optional. */
   newTitleField?: string | null;
+  /** Remove the title field from the header. Optional. */
   titleFieldDeleted?: boolean;
+  /** Replace the record description field. Optional. */
   newDescriptionField?: string | null;
+  /** Remove the description field from the header. Optional. */
   descriptionFieldDeleted?: boolean;
-  /** Map of system field key → edit. */
+  /** Edits to built-in system header fields, keyed by system field key. Optional. */
   systemFieldEdits?: Record<string, SystemHeaderFieldEdit>;
+  /** Additional custom fields to add to the header. Optional. */
   newFields?: NewHeaderField[];
-  /** Sort order of header field `key` values (custom + system). */
+  /** Ordered list of header field `key` values (custom + system). Optional. */
   headerFieldsOrder?: string[];
+  /** Action button keys to show in the header. Optional. */
   buttons?: string[];
 }
 
@@ -68,81 +65,109 @@ export interface HeaderEdits {
 // tab_edits — TabEditsDTO + section/tab DTOs
 // ---------------------------------------------------------------------------
 
-/** SectionFieldDTO — one field inside a fields_section. */
+/** One field entry inside a `fields_section`. */
 export interface SectionField {
+  /** RQL name of the field to display. Required. */
   fieldRqlName: string;
+  /** Hide this field from view. Optional. */
   hidden?: boolean;
+  /** Allow inline editing of this field. Optional. */
   editable?: boolean;
+  /** Controls how the field can be moved in the UI. Optional. */
   movementOption?: 'tab' | 'free';
 }
 
-/** FieldsSectionDTO — standard field grid section. */
+/** A standard field-grid section inside a tab. */
 export interface FieldsSection {
   type: 'fields_section';
+  /** Stable key for this section. Required. */
   key: string;
+  /** Display name of the section. Required. */
   name: string;
+  /** Fields to display in this section. Required. */
   fields: SectionField[];
 }
 
-/** Only `fields_section` is modeled today (most common). Add other section
- *  types (related_object_section, custom_section, …) explicitly as needed. */
+/**
+ * A section inside a page layout tab.
+ *
+ * Only `fields_section` is modeled today. Add other section types
+ * (`related_object_section`, `custom_section`, …) explicitly as needed.
+ */
 export type PageLayoutSection = FieldsSection;
 
-/** PageLayoutTabWithSectionsDTO. */
+/** A tab that contains one or more field-grid sections. */
 export interface TabWithSections {
   type: 'tab_with_sections';
+  /** Stable key for this tab. Required. */
   key: string;
+  /** Display name of the tab. Required. */
   name: string;
+  /** Sections inside this tab. Required. */
   sections: PageLayoutSection[];
 }
 
-/** CustomTabDTO — host a custom component as a tab. */
+/** A tab that hosts a custom UI component. */
 export interface CustomTab {
   type: 'custom_tab';
+  /** Stable key for this tab. Required. */
   key: string;
+  /** Display name of the tab. Required. */
   name: string;
+  /** Key of the custom component to render. Required. */
   componentKey: string;
 }
 
+/** A tab entry in a page layout — either a sections-based tab or a custom component tab. */
 export type PageLayoutTab = TabWithSections | CustomTab;
 
-/** Layout of fields inside a fields_section. */
+/** Column layout for a `fields_section`. */
 export type SectionFieldsLayout = 'one_column' | 'two_column' | 'three_column' | 'responsive';
 
-/** SystemSectionEditDTO — edits to a built-in section inside a system tab. */
+/** Edits to a built-in section inside a system tab. */
 export interface SystemSectionEdit {
+  /** Rename this section. Optional. */
   newName?: string;
+  /** Remove this section. Optional. */
   deleted?: boolean;
+  /** Change the column layout. Optional. */
   newLayout?: SectionFieldsLayout;
+  /** Add fields to this section. Optional. */
   newFields?: SectionField[];
+  /** Hide the section name header. Optional. */
   newHideName?: boolean;
 }
 
-/** SystemTabEditDTO — edits to a built-in tab (rename, delete, add sections, …). */
+/** Edits to a built-in (system) tab. */
 export interface SystemTabEdit {
+  /** Rename this tab. Optional. */
   newName?: string;
+  /** Remove this tab. Optional. */
   deleted?: boolean;
+  /** Add new sections to this tab. Optional. */
   newSections?: PageLayoutSection[];
+  /** Edits to built-in sections inside this tab, keyed by section key. Optional. */
   systemSectionEdits?: Record<string, SystemSectionEdit>;
+  /** Reorder sections by key. Optional. */
   sectionsOrder?: string[];
 }
 
 /**
- * Strict shape for tab_edits. Only TabEditsDTO keys allowed.
+ * Tab structure configuration for a page layout (`tab_edits`).
  *
- * All fields are optional to match `TabEditsDTO`'s `default_factory` (empty
- * list / empty dict). An omitted `tabEdits` defaults to `{}` in the
- * constructor; partial objects rely on backend per-field defaults.
+ * All fields are optional. An omitted `tabEdits` defaults to `{}`.
  *
- * - newTabs:        tabs to create (each needs a `type` discriminator)
- * - systemTabEdits: edits keyed by built-in tab key
- * - tabsOrder:      ordered list of tab `key` values (new + system)
- * - newTabLayout:   optional orientation
+ * > **Caution:** key names are camelCase on the wire. Snake_case keys are
+ * > silently dropped and produce an empty layout on deploy.
  */
 export interface TabEdits {
+  /** New tabs to add to this layout. Each must include a `type` discriminator. Optional. */
   newTabs?: PageLayoutTab[];
+  /** Edits to existing system tabs, keyed by tab key. Optional. */
   systemTabEdits?: Record<string, SystemTabEdit>;
+  /** Ordered list of tab `key` values (new + system). Optional. */
   tabsOrder?: string[];
+  /** Tab strip orientation. Optional. */
   newTabLayout?: 'vertical' | 'horizontal';
 }
 
@@ -151,17 +176,27 @@ export interface TabEdits {
 // ---------------------------------------------------------------------------
 
 /**
- * VisibilityConditionDTO. Both fields are required on the Python type — pass
- * empty string / empty object if you genuinely have no formula or AST.
+ * A single visibility condition applied to a section or tab.
+ *
+ * Both fields are required by the backend — pass an empty string / empty object
+ * if you have no formula or condition tree.
  */
 export interface VisibilityCondition {
+  /** RQL formula that controls visibility. Required. */
   rqlFormula: string;
+  /** Layered conditions tree (AST). Required. */
   layeredConditionsTree: Record<string, any>;
 }
 
-/** Pass `{}` for "no conditions" — both maps default empty. */
+/**
+ * Visibility conditions for sections and tabs on a page layout.
+ *
+ * Pass `{}` for no conditions.
+ */
 export interface VisibilityConditions {
+  /** Per-section visibility conditions, keyed by section key. Optional. */
   sections?: Record<string, VisibilityCondition>;
+  /** Per-tab visibility conditions, keyed by tab key. Optional. */
   tabs?: Record<string, VisibilityCondition>;
 }
 
@@ -169,24 +204,54 @@ export interface VisibilityConditions {
 // Public props
 // ---------------------------------------------------------------------------
 
+/**
+ * Initialization properties for {@link CustomObjectPageLayout}.
+ */
 export interface CustomObjectPageLayoutProps {
   /**
-   * Required. Stable `api_name` for the layout. Use `'default'` for the layout
-   * that drives **Add** and the default object detail view (per Custom Object
-   * — one `default` per object).
+   * Stable identifier for this layout (e.g. `'default'`).
+   *
+   * Required. Use `'default'` for the layout that drives the **Add** form and
+   * the default record detail view. Each custom object supports one `'default'`
+   * layout.
    */
   apiName: string;
-  /** Required. Display name of the layout. */
+  /**
+   * Display name of this layout shown in the layout selector.
+   *
+   * Required.
+   */
   name: string;
-  /** Optional. Tab structure (TabEditsDTO). Defaults to empty. */
+  /**
+   * Tab structure — which tabs and sections to show on the detail page.
+   *
+   * Optional. @default `{}`
+   */
   tabEdits?: TabEdits;
-  /** Optional. Header configuration (HeaderEditsDTO). Defaults to empty. */
+  /**
+   * Header configuration — title field, description field, and action buttons.
+   *
+   * Optional. @default `{}`
+   */
   headerEdits?: HeaderEdits;
-  /** Optional. Visibility conditions. Defaults to empty (no conditions). */
+  /**
+   * Visibility conditions for individual tabs and sections.
+   *
+   * Optional. @default `{}`
+   */
   visibilityConditions?: VisibilityConditions;
-  /** Identity override. Override the layout identifier. @default generateId('layout') */
+  /**
+   * Stable identifier for this layout record. Pass a human-readable slug
+   * to keep it stable across regenerations.
+   *
+   * Optional. Auto-generated when omitted. @default generateId('layout')
+   */
   layoutId?: string;
-  /** Optional. Overwritten at install; defaults to object api_name. */
+  /**
+   * Blueprint key used during install. Defaults to the parent object's api_name.
+   *
+   * Optional.
+   */
   blueprintKey?: string;
 }
 
@@ -194,6 +259,46 @@ export interface CustomObjectPageLayoutProps {
 // Class
 // ---------------------------------------------------------------------------
 
+/**
+ * Defines a page layout and registers it with the manifest.
+ *
+ * A page layout controls the tab structure, section groupings, header fields,
+ * and visibility conditions on a custom object's record detail page. You would
+ * normally define one layout per custom object using `apiName: 'default'`.
+ *
+ * For simple single-tab layouts, use the {@link CustomObjectPageLayout.basic}
+ * factory instead of constructing the full props manually.
+ *
+ * > **Caution:** all keys inside `tabEdits` and `headerEdits` must be camelCase.
+ * > Snake_case keys are silently dropped on the wire and produce an empty layout.
+ *
+ * @example
+ * ```ts
+ * new CustomObjectPageLayout(memberObj, {
+ *   apiName: 'default',
+ *   name: 'Member',
+ *   layoutId: 'layout_gym_member',
+ *   headerEdits: { newTitleField: memberDisplayName.getApiName() },
+ *   tabEdits: {
+ *     newTabs: [{
+ *       key: 'member', name: 'Member', type: 'tab_with_sections',
+ *       sections: [{
+ *         key: 'profile', name: 'Profile', type: 'fields_section',
+ *         fields: [
+ *           { fieldRqlName: memberFirstName.getApiName() },
+ *           { fieldRqlName: memberEmail.getApiName() },
+ *         ],
+ *       }],
+ *     }],
+ *     systemTabEdits: {},
+ *     tabsOrder: ['member'],
+ *   },
+ *   visibilityConditions: {},
+ * });
+ * ```
+ *
+ * @see {@link CustomObjectPageLayout.basic} — factory for simple single-tab layouts.
+ */
 export class CustomObjectPageLayout {
   private readonly _layoutId: string;
   private readonly _apiName: string;
@@ -204,7 +309,11 @@ export class CustomObjectPageLayout {
   private readonly _visibilityConditions: VisibilityConditions;
   private readonly _blueprintKey: string | undefined;
 
-  /** Build a new layout and auto-register with the CO's scope. */
+  /**
+   * @param customObject - The custom object this layout belongs to.
+   * @param props - Initialization properties.
+   * @throws {Error} If `apiName` or `name` is empty.
+   */
   constructor(customObject: CustomObject, props: CustomObjectPageLayoutProps) {
     if (!props.apiName) throw new Error('CustomObjectPageLayout: apiName cannot be empty');
     if (!props.name) throw new Error('CustomObjectPageLayout: name cannot be empty');
@@ -219,22 +328,32 @@ export class CustomObjectPageLayout {
     customObject._register(this);
   }
 
-  /** Backend layout_id used as this layout's identifier. */
+  /**
+   * Returns the stable identifier for this layout record (e.g. `'layout_gym_member'`).
+   */
   getLayoutId(): string {
     return this._layoutId;
   }
 
-  /** Stable api_name for this layout. */
+  /**
+   * Returns the api_name of this layout (e.g. `'default'`).
+   */
   getApiName(): string {
     return this._apiName;
   }
 
-  /** api_name of the CustomObject this layout lives on. */
+  /**
+   * Returns the api_name of the custom object this layout belongs to.
+   */
   getCustomObjectApiName(): string {
     return this._customObjectApiName;
   }
 
-  /** Serialize to the backend `CUSTOM_OBJECT_PAGE_LAYOUT` wire shape. */
+  /**
+   * Serializes this layout to the wire format consumed by the manifest install endpoint.
+   *
+   * @returns A plain object with `type: 'CUSTOM_OBJECT_PAGE_LAYOUT'`.
+   */
   toDict(): Record<string, any> {
     const d: Record<string, any> = {
       type: 'CUSTOM_OBJECT_PAGE_LAYOUT',
@@ -252,7 +371,23 @@ export class CustomObjectPageLayout {
     return d;
   }
 
-  /** Factory for a single-tab "Details" page listing the given fields. */
+  /**
+   * Creates a simple single-tab "Details" layout with a single "General" section.
+   *
+   * Use this factory when you want a straightforward layout without customizing
+   * tabs or sections. Always uses `apiName: 'default'`.
+   *
+   * @param customObject - The custom object to create the layout for.
+   * @param props - Optional. Pass `fields` to populate the General section.
+   * @returns A new `CustomObjectPageLayout` registered with the manifest.
+   *
+   * @example
+   * ```ts
+   * CustomObjectPageLayout.basic(memberObj, {
+   *   fields: [memberFirstName, memberEmail, memberStatusField],
+   * });
+   * ```
+   */
   static basic(
     customObject: CustomObject,
     props: {

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

@@ -1,25 +1,3 @@
-/*
- * The contents of this file were inserted manually and are not generated by Stainless.
- *
- * CustomObject builder. Backend schema: CUSTOM_OBJECT (v2).
- *
- * Construction is CDK-style: `new CustomObject(scope, props)` where `scope`
- * is the `ManifestBuilder` (or any `ManifestScope`). The CO also acts as a
- * scope for its own children (fields, validations, rules, list views, page
- * layouts, sections, actions) — those take the CO as their first arg and
- * auto-register with the manifest through it.
- *
- * Every CO auto-registers 9 platform-managed standard field stubs at
- * construction, matching `STANDARD_FIELDS` in the backend's `constants.py`:
- *   id, created_at, updated_at, system_updated_at, external_id, name,
- *   owner_role, last_modified_by, created_by
- * The backend's closed-world `extract_from_configs` path (used by
- * `POST /metadata/v2/validate`) treats these as hard dependencies of the CO —
- * for any brand-new CO their configs must already be present in the submitted
- * manifest, else validation raises `DEPENDENCY_ERROR`. Users never declare
- * them explicitly; the SDK emits them with `is_standard: true`.
- */
-
 import { Category } from './category';
 import type { ManifestComponent, ManifestScope } from './manifest-builder';
 
@@ -161,36 +139,134 @@ class _StandardField implements ManifestComponent {
   }
 }
 
+/**
+ * Icon displayed next to the custom object name in the Rippling UI.
+ */
 export interface IconConfig {
+  /**
+   * A Unicode emoji character, e.g. `'🏋️'`.
+   *
+   * Optional. Omit all four sources (or pass `null`) to show no icon.
+   */
   emoji?: string | null;
+  /**
+   * Name of a built-in Rippling icon asset.
+   *
+   * Optional.
+   */
   ripplingIcon?: string | null;
+  /**
+   * S3 bucket for a custom image asset.
+   *
+   * Optional. Must be set together with `s3Key`.
+   */
   s3Bucket?: string;
+  /**
+   * S3 key (path) within `s3Bucket`.
+   *
+   * Optional. Must be set together with `s3Bucket`.
+   */
   s3Key?: string;
 }
 
+/**
+ * Initialization properties for {@link CustomObject}.
+ */
 export interface CustomObjectProps {
-  /** Required. Unique api_name (must end with `__c`). */
+  /**
+   * Unique identifier for this custom object.
+   *
+   * Required. Must end with `__c` (e.g. `'gym_member__c'`). The constructor throws
+   * immediately if this suffix is missing.
+   */
   apiName: string;
-  /** Required. Singular display name. */
+  /**
+   * Singular display name shown in the Rippling UI (e.g. `'Member'`).
+   *
+   * Required.
+   */
   name: string;
   /**
-   * Required. Category this object belongs to. Accepts a live `Category` ref
-   * (the SDK reads its api_name) or a raw api_name string for categories
-   * authored outside this manifest (e.g. Rippling-native or cross-package).
+   * The category this object belongs to.
+   *
+   * Required. Pass a {@link Category} instance defined in the same manifest, or a raw
+   * api_name string for categories defined outside this manifest.
    */
   category: Category | string;
-  /** Optional. What this entity represents. @default null */
+  /**
+   * Human-readable description of what this entity represents.
+   *
+   * Optional. @default null
+   */
   description?: string | null;
-  /** Optional. Icon configuration. @default null */
+  /**
+   * Icon shown next to the object name in the Rippling UI.
+   *
+   * Optional. @default null
+   */
   icon?: IconConfig | null;
-  /** Optional. Plural display form. @default null */
+  /**
+   * Plural form of the display name, used in list headings (e.g. `'Members'`).
+   *
+   * Optional. @default null
+   */
   pluralLabel?: string | null;
-  /** Optional. Overrides for autonumber name fields. @default null */
+  /**
+   * Overrides for the auto-number name field — controls the format string and starting number.
+   * Leave `null` to use the default name field behavior.
+   *
+   * Optional. @default null
+   */
   nameFieldDetails?: Record<string, any> | null;
-  /** Optional. Default field section name. @default null */
+  /**
+   * API name of the field section that newly created fields are grouped into by default.
+   *
+   * Optional. @default null
+   */
   defaultFieldSectionName?: string | 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 implements ManifestScope {
   private readonly _scope: ManifestScope;
   private readonly _apiName: string;
@@ -202,7 +278,11 @@ export class CustomObject implements ManifestScope {
   private _nameFieldDetails: Record<string, any> | null | undefined;
   private _defaultFieldSectionName: string | null | undefined;
 
-  /** Build a new CO and auto-register with `scope`; enforces `__c` suffix on `apiName`. */
+  /**
+   * @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: ManifestScope, props: CustomObjectProps) {
     if (!props.apiName.endsWith('__c')) {
       throw new Error(`Custom object api_name must end with __c: ${props.apiName}`);
@@ -224,22 +304,33 @@ export class CustomObject implements ManifestScope {
     }
   }
 
-  /** @internal Scope hook: forward child registration up to the builder. */
+  /** @internal Scope hook — forwards child registration up to the root builder. */
   _register(component: ManifestComponent): void {
     this._scope._register(component);
   }
 
-  /** Backend api_name for this custom object. */
+  /**
+   * 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(): string {
     return this._apiName;
   }
 
-  /** Singular display name. */
+  /**
+   * Returns the singular display name of this custom object (e.g. `'Member'`).
+   */
   getName(): string {
     return this._name;
   }
 
-  /** Serialize to the backend `CUSTOM_OBJECT` wire shape. */
+  /**
+   * 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(): Record<string, any> {
     const component: Record<string, any> = {
       type: 'CUSTOM_OBJECT',