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

package/lib/manifest/custom-object-page-layout.mjs

@@ -1,33 +1,53 @@
-/*
- * The contents of this file were inserted manually and are not generated by Stainless.
+import { generateId } from "./_helpers.mjs";
+// ---------------------------------------------------------------------------
+// Class
+// ---------------------------------------------------------------------------
+/**
+ * Defines a page layout and registers it with the manifest.
  *
- * Custom object page layouts (detail page structure).
- * Backend schema: CUSTOM_OBJECT_PAGE_LAYOUT (v2)
+ * 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'`.
  *
- * 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.
+ * For simple single-tab layouts, use the {@link CustomObjectPageLayout.basic}
+ * factory instead of constructing the full props manually.
  *
- * 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.
+ * > **Caution:** all keys inside `tabEdits` and `headerEdits` must be camelCase.
+ * > Snake_case keys are silently dropped on the wire and produce an empty layout.
  *
- * 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.
+ * @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: {},
+ * });
+ * ```
  *
- * DTO references: types/edits.py, types/layout.py, types/sections.py.
+ * @see {@link CustomObjectPageLayout.basic} — factory for simple single-tab layouts.
  */
-import { generateId } from "./_helpers.mjs";
-// ---------------------------------------------------------------------------
-// Class
-// ---------------------------------------------------------------------------
 export class CustomObjectPageLayout {
-    /** 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, props) {
         if (!props.apiName)
             throw new Error('CustomObjectPageLayout: apiName cannot be empty');
@@ -43,19 +63,29 @@ export class CustomObjectPageLayout {
         this._blueprintKey = props.blueprintKey;
         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() {
         return this._layoutId;
     }
-    /** Stable api_name for this layout. */
+    /**
+     * Returns the api_name of this layout (e.g. `'default'`).
+     */
     getApiName() {
         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() {
         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() {
         const d = {
             type: 'CUSTOM_OBJECT_PAGE_LAYOUT',
@@ -72,7 +102,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, props = {}) {
         const coApiName = customObject.getApiName();
         const coName = customObject.getName();

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

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

package/lib/manifest/custom-object.d.mts

@@ -1,33 +1,131 @@
 import { Category } from "./category.mjs";
 import type { ManifestComponent, ManifestScope } from "./manifest-builder.mjs";
+/**
+ * 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 declare class CustomObject implements ManifestScope {
     private readonly _scope;
     private readonly _apiName;
@@ -38,15 +136,30 @@ export declare class CustomObject implements ManifestScope {
     private _pluralLabel;
     private _nameFieldDetails;
     private _defaultFieldSectionName;
-    /** 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);
-    /** @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;
-    /** 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;
-    /** Singular display name. */
+    /**
+     * Returns the singular display name of this custom object (e.g. `'Member'`).
+     */
     getName(): string;
-    /** 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>;
 }
 //# sourceMappingURL=custom-object.d.mts.map

package/lib/manifest/custom-object.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"custom-object.d.mts","sourceRoot":"","sources":["../../src/lib/manifest/custom-object.ts"],"names":[],"mappings":"OAsBO,EAAE,QAAQ,EAAE;OACZ,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE;AA4IhD,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kDAAkD;IAClD,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC9C,0DAA0D;IAC1D,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAED,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,iBAAiB,CAAyC;IAClE,OAAO,CAAC,wBAAwB,CAA4B;IAE5D,yFAAyF;gBAC7E,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,iBAAiB;IAqB1D,0EAA0E;IAC1E,SAAS,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI;IAI7C,+CAA+C;IAC/C,UAAU,IAAI,MAAM;IAIpB,6BAA6B;IAC7B,OAAO,IAAI,MAAM;IAIjB,2DAA2D;IAC3D,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CA0B9B"}
+{"version":3,"file":"custom-object.d.mts","sourceRoot":"","sources":["../../src/lib/manifest/custom-object.ts"],"names":[],"mappings":"OAAO,EAAE,QAAQ,EAAE;OACZ,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE;AA4IhD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC5B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;OAIG;IACH,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC9C;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,iBAAiB,CAAyC;IAClE,OAAO,CAAC,wBAAwB,CAA4B;IAE5D;;;;OAIG;gBACS,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,iBAAiB;IAqB1D,iFAAiF;IACjF,SAAS,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI;IAI7C;;;;OAIG;IACH,UAAU,IAAI,MAAM;IAIpB;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;;;;OAKG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CA0B9B"}

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

@@ -1,33 +1,131 @@
 import { Category } from "./category.js";
 import type { ManifestComponent, ManifestScope } from "./manifest-builder.js";
+/**
+ * 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 declare class CustomObject implements ManifestScope {
     private readonly _scope;
     private readonly _apiName;
@@ -38,15 +136,30 @@ export declare class CustomObject implements ManifestScope {
     private _pluralLabel;
     private _nameFieldDetails;
     private _defaultFieldSectionName;
-    /** 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);
-    /** @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;
-    /** 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;
-    /** Singular display name. */
+    /**
+     * Returns the singular display name of this custom object (e.g. `'Member'`).
+     */
     getName(): string;
-    /** 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>;
 }
 //# sourceMappingURL=custom-object.d.ts.map

package/lib/manifest/custom-object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"custom-object.d.ts","sourceRoot":"","sources":["../../src/lib/manifest/custom-object.ts"],"names":[],"mappings":"OAsBO,EAAE,QAAQ,EAAE;OACZ,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE;AA4IhD,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kDAAkD;IAClD,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC9C,0DAA0D;IAC1D,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAED,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,iBAAiB,CAAyC;IAClE,OAAO,CAAC,wBAAwB,CAA4B;IAE5D,yFAAyF;gBAC7E,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,iBAAiB;IAqB1D,0EAA0E;IAC1E,SAAS,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI;IAI7C,+CAA+C;IAC/C,UAAU,IAAI,MAAM;IAIpB,6BAA6B;IAC7B,OAAO,IAAI,MAAM;IAIjB,2DAA2D;IAC3D,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CA0B9B"}
+{"version":3,"file":"custom-object.d.ts","sourceRoot":"","sources":["../../src/lib/manifest/custom-object.ts"],"names":[],"mappings":"OAAO,EAAE,QAAQ,EAAE;OACZ,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE;AA4IhD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC5B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;OAIG;IACH,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC9C;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,iBAAiB,CAAyC;IAClE,OAAO,CAAC,wBAAwB,CAA4B;IAE5D;;;;OAIG;gBACS,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,iBAAiB;IAqB1D,iFAAiF;IACjF,SAAS,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI;IAI7C;;;;OAIG;IACH,UAAU,IAAI,MAAM;IAIpB;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;;;;OAKG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CA0B9B"}

package/lib/manifest/custom-object.js

@@ -1,25 +1,4 @@
 "use strict";
-/*
- * 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`.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CustomObject = void 0;
 // ────────────────────────────────────────────────────────────────────────
@@ -148,8 +127,53 @@ class _StandardField {
         };
     }
 }
+/**
+ * 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.
+ */
 class CustomObject {
-    /** 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, props) {
         if (!props.apiName.endsWith('__c')) {
             throw new Error(`Custom object api_name must end with __c: ${props.apiName}`);
@@ -169,19 +193,30 @@ class CustomObject {
             scope._register(new _StandardField(this._apiName, spec));
         }
     }
-    /** @internal Scope hook: forward child registration up to the builder. */
+    /** @internal Scope hook — forwards child registration up to the root builder. */
     _register(component) {
         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() {
         return this._apiName;
     }
-    /** Singular display name. */
+    /**
+     * Returns the singular display name of this custom object (e.g. `'Member'`).
+     */
     getName() {
         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() {
         const component = {
             type: 'CUSTOM_OBJECT',