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

package/src/lib/manifest/list-view.ts

@@ -1,41 +1,108 @@
-/*
- * The contents of this file were inserted manually and are not generated by Stainless.
- *
- * List view definitions for custom objects (column layout + sorting).
- * Backend schema: CUSTOM_OBJECT_LIST_VIEW (v2)
- *
- * Construction is CDK-style: `new ListViewDef(customObject, props)` — the
- * CO is the first positional arg, and the view auto-registers with the
- * manifest via the CO's scope chain.
- */
-
 import { generateId, type ObjectScope, type SortOrder } from './_helpers';
 import type { CustomObject } from './custom-object';
 import type { Field } from './field';
 
+/**
+ * Initialization properties for {@link ListViewDef}.
+ */
 export interface ListViewDefProps {
-  /** Required. Display name of the view. */
+  /**
+   * Display name of this list view shown in the UI (e.g. `'All members'`).
+   *
+   * Required.
+   */
   name: string;
-  /** Required. Column definitions (live `Field` refs; at least one). */
+  /**
+   * Columns to display, as live {@link Field} references. At least one field is required.
+   *
+   * Required.
+   */
   fields: Field[];
-  /** Required. Whether the view is visible to all users. */
+  /**
+   * Whether this view is visible to all users (`true`) or only the record owner (`false`).
+   *
+   * Required.
+   */
   isPublic: boolean;
-  /** Identity override. Override the view identifier. @default generateId('view') */
+  /**
+   * Stable identifier for this view. Pass a human-readable slug
+   * (e.g. `'view_gym_all_members'`) to keep it stable across regenerations.
+   *
+   * Optional. Auto-generated when omitted. @default generateId('view')
+   */
   viewId?: string;
-  /** Optional. Sort column (live `Field` ref). Required if `sortOrder` is set. */
+  /**
+   * Field to sort by. Required when `sortOrder` is set.
+   *
+   * Optional.
+   */
   orderBy?: Field;
-  /** Conditional. Sort direction — requires `orderBy`. */
+  /**
+   * Sort direction. One of `'ASC'` | `'DESC'`. Requires `orderBy` to be set.
+   *
+   * Optional.
+   */
   sortOrder?: SortOrder;
-  /** Optional. Object scope. @default 'all' */
+  /**
+   * Record scope for this view. One of `'all'` | `'my_records'`.
+   *
+   * Optional. @default `'all'`
+   */
   objectScope?: ObjectScope;
-  /** Optional. Free-form description. @default null */
+  /**
+   * Human-readable description of this view.
+   *
+   * Optional. @default null
+   */
   description?: string;
-  /** Optional. Per-column configuration overrides. @default {} */
+  /**
+   * Per-column configuration overrides (width, visibility, etc.).
+   *
+   * Optional. @default `{}`
+   */
   columnConfig?: Record<string, any>;
-  /** Optional. RQL filter expression. @default null */
+  /**
+   * RQL filter expression to pre-filter records shown in this view
+   * (e.g. `'(session_date__c == TODAY())'`).
+   *
+   * Optional. @default null
+   */
   rqlFilter?: string;
 }
 
+/**
+ * Defines a list view and registers it with the manifest.
+ *
+ * A list view defines which fields appear as columns, their sort order, and an
+ * optional RQL filter. You can define multiple views per custom object; each
+ * appears as a selectable view in the object's list page.
+ *
+ * @example
+ * ```ts
+ * new ListViewDef(memberObj, {
+ *   viewId: 'view_gym_all_members',
+ *   name: 'All members',
+ *   description: 'Directory with membership status',
+ *   fields: [memberDisplayName, memberEmail, memberPhone, memberStatusField, memberJoinDate],
+ *   orderBy: memberLastName,
+ *   sortOrder: 'ASC',
+ *   isPublic: true,
+ *   objectScope: 'all',
+ * });
+ *
+ * // Filtered view example:
+ * new ListViewDef(sessionObj, {
+ *   viewId: 'view_gym_today_sessions',
+ *   name: 'Today\'s class sessions',
+ *   fields: [sessionTrainerRef, sessionStartField, sessionClassTypeField],
+ *   orderBy: sessionStartField,
+ *   sortOrder: 'ASC',
+ *   isPublic: true,
+ *   objectScope: 'all',
+ *   rqlFilter: '(session_date__c == TODAY())',
+ * });
+ * ```
+ */
 export class ListViewDef {
   private readonly _viewId: string;
   private readonly _customObjectApiName: string;
@@ -49,7 +116,11 @@ export class ListViewDef {
   private readonly _columnConfig: Record<string, any> | undefined;
   private readonly _rqlFilter: string | undefined;
 
-  /** Build a new view def and auto-register with the CO's scope. */
+  /**
+   * @param customObject - The custom object this view belongs to.
+   * @param props - Initialization properties.
+   * @throws {Error} If `name` is empty, `fields` is empty, or `sortOrder` is set without `orderBy`.
+   */
   constructor(customObject: CustomObject, props: ListViewDefProps) {
     if (!props.name) throw new Error('ListViewDef: name cannot be empty');
     if (!props.fields || props.fields.length === 0) {
@@ -72,17 +143,26 @@ export class ListViewDef {
     customObject._register(this);
   }
 
-  /** Backend view_id used as this view's identifier. */
+  /**
+   * Returns the stable identifier for this view (e.g. `'view_gym_all_members'`).
+   */
   getViewId(): string {
     return this._viewId;
   }
 
-  /** api_name of the CustomObject this view lives on. */
+  /**
+   * Returns the api_name of the custom object this view belongs to.
+   */
   getCustomObjectApiName(): string {
     return this._customObjectApiName;
   }
 
-  /** Serialize to the backend `CUSTOM_OBJECT_LIST_VIEW` wire shape. */
+  /**
+   * Serializes this list view to the wire format consumed by the manifest install endpoint.
+   *
+   * @returns A plain object with `type: 'CUSTOM_OBJECT_LIST_VIEW'`.
+   * Optional fields are omitted when unset.
+   */
   toDict(): Record<string, any> {
     const d: Record<string, any> = {
       type: 'CUSTOM_OBJECT_LIST_VIEW',

package/src/lib/manifest/manifest-builder.ts

@@ -1,57 +1,85 @@
-/*
- * The contents of this file were inserted manually and are not generated by Stainless.
- *
- * ManifestBuilder collects manifest components and serializes to JSON.
- *
- * Wiring model (CDK-style scope-first):
- *   - Every component takes its parent scope as the first positional
- *     constructor arg. The scope is either a `ManifestBuilder` (root) or a
- *     `CustomObject` / `CustomObjectFieldSection` for nested children.
- *   - Constructing a component auto-registers it with the builder via the
- *     scope's `_register` hook. There is no public `addComponent` — the
- *     only way a component enters the manifest is by being constructed
- *     with a scope that forwards up to this builder.
- *   - The builder does not walk into components; each component emits the
- *     foreign-key fields (`custom_object_api_name`, `model_rql_name`, ...)
- *     itself in `toDict()`.
+/**
+ * Any object that can be included in a manifest.
  *
- * Local operations only (no HTTP):
- *   - preview()         — render manifest as a JSON string
- *   - buildManifest()   — return the manifest as a plain object
- *   - componentsList()  — return the flat list of component dicts
+ * Implement `toDict()` to return the component's wire-format dict.
+ * All built-in SDK classes implement this interface automatically.
  */
-
-/** Any object with a toDict() method can be a manifest component. */
 export interface ManifestComponent {
   toDict(): Record<string, any>;
 }
 
 /**
- * A scope — anything that can accept a child component for registration.
- * Implemented by `ManifestBuilder` (root) and by nestable parents like
- * `CustomObject` and `CustomObjectFieldSection` that forward to the builder.
+ * A scope — anything that can accept child component registrations.
+ *
+ * Implemented by {@link ManifestBuilder} (the root) and by nestable parents
+ * like `CustomObject` that forward registrations up to the builder.
+ * Pass a scope as the first argument when constructing any manifest component.
  */
 export interface ManifestScope {
   /** @internal Register a child component; builder-bound scopes forward up. */
   _register(component: ManifestComponent): void;
 }
 
+/**
+ * Initialization properties for {@link ManifestBuilder}.
+ */
 export interface ManifestBuilderProps {
-  /** Unique project key for this manifest. */
+  /**
+   * Unique project key for this manifest (e.g. `'gym_membership_management'`).
+   *
+   * Required.
+   */
   key: string;
-  /** Display name (defaults to key if not provided). */
+  /**
+   * Display name for this manifest.
+   *
+   * Optional. Defaults to `key` when not provided.
+   */
   name?: string;
-  /** Optional description. */
+  /**
+   * Human-readable description of what this manifest contains.
+   *
+   * Optional.
+   */
   description?: string;
 }
 
+/**
+ * Root container for a manifest — collects all components and serializes them to JSON.
+ *
+ * You would normally create one `ManifestBuilder` at the top of your manifest file,
+ * then pass it as the scope to all top-level components (categories, custom objects,
+ * functions, apps, SDUI pages). Each component auto-registers on construction; there
+ * is no separate add or register call.
+ *
+ * After defining all components, call `preview()` to emit the manifest as a
+ * pretty-printed JSON string, or `buildManifest()` to get the plain object.
+ *
+ * @example
+ * ```ts
+ * const manifest = new ManifestBuilder({
+ *   key: 'gym_membership_management',
+ *   name: 'Gym Membership Management',
+ *   description: 'Members, trainers, schedules, and check-in',
+ * });
+ *
+ * const category = new Category(manifest, { apiName: 'gym__c', name: 'Gym' });
+ * const memberObj = new CustomObject(manifest, { apiName: 'gym_member__c', name: 'Member', category });
+ * // ... define fields, rules, list views, etc. ...
+ *
+ * console.log(manifest.preview());
+ * ```
+ */
 export class ManifestBuilder implements ManifestScope {
   readonly key: string;
   readonly name: string;
   readonly description: string;
   private readonly _components: ManifestComponent[] = [];
 
-  /** Build a new manifest; `name` defaults to `key` when unset. */
+  /**
+   * @param props - Initialization properties.
+   * @throws {Error} If `props.key` is empty or missing.
+   */
   constructor(props: ManifestBuilderProps) {
     if (!props.key) {
       throw new Error('key is required');
@@ -72,7 +100,11 @@ export class ManifestBuilder implements ManifestScope {
     this._components.push(component);
   }
 
-  /** Build the manifest object: metadata + flat component list. */
+  /**
+   * Returns the manifest as a plain object with `metadata` and a flat `components` array.
+   *
+   * @returns `{ metadata: { key, name, description? }, components: Record<string, any>[] }`
+   */
   buildManifest(): { metadata: Record<string, any>; components: Record<string, any>[] } {
     const metadata: Record<string, any> = {
       key: this.key,
@@ -85,12 +117,23 @@ export class ManifestBuilder implements ManifestScope {
     return { metadata, components };
   }
 
-  /** Flat list of all component dicts. */
+  /**
+   * Returns the flat list of all registered component dicts.
+   *
+   * @returns An array of wire-format component objects, in registration order.
+   */
   componentsList(): Record<string, any>[] {
     return this._components.map((c) => c.toDict());
   }
 
-  /** Pretty-printed JSON string. */
+  /**
+   * Returns the full manifest as a pretty-printed JSON string.
+   *
+   * Typically used as the final line of a manifest file to emit the output:
+   * `console.log(manifest.preview())`.
+   *
+   * @returns Indented JSON string of the complete manifest.
+   */
   preview(): string {
     return JSON.stringify(this.buildManifest(), null, 2);
   }

package/src/lib/manifest/manifest-function.ts

@@ -1,37 +1,98 @@
-/*
- * The contents of this file were inserted manually and are not generated by Stainless.
- *
- * Custom function definitions (TypeScript handler code).
- * Backend schema: FUNCTION (v2)
- *
- * Named ManifestFunction to avoid collision with the JavaScript built-in Function.
- * Re-exported as both ManifestFunction and Function from the barrel.
- */
-
 import type { FunctionRuntime } from './_helpers';
 import type { ManifestScope } from './manifest-builder';
 
+/**
+ * Initialization properties for {@link ManifestFunction}.
+ */
 export interface ManifestFunctionProps {
-  /** Required. Function api_name (snake_case identifier). */
+  /**
+   * Unique identifier for this function (e.g. `'gym_today_schedule_fn'`).
+   *
+   * Required.
+   */
   apiName: string;
-  /** Required. Display name shown in the UI. */
+  /**
+   * Display name shown in the Rippling UI.
+   *
+   * Required.
+   */
   name: string;
-  /** Optional. TypeScript handler source; must export `onRipplingEvent`. @default '' */
+  /**
+   * TypeScript handler source code. Must export an `onRipplingEvent` function.
+   *
+   * Optional. @default `''`
+   */
   code?: string;
-  /** Optional. Function description. @default '' */
+  /**
+   * Human-readable description of what this function does.
+   *
+   * Optional. @default `''`
+   */
   description?: string;
-  /** Optional. NPM package dependencies. @default null */
+  /**
+   * NPM package dependencies as a `{ packageName: versionRange }` map
+   * (e.g. `{ '@rippling/rippling-sdk': '^0.2.0' }`).
+   *
+   * Optional. @default null
+   */
   dependencies?: Record<string, string>;
-  /** Optional. Raw deployment options. Prefer `runtime`. @default null */
+  /**
+   * Raw deployment options object. Prefer `runtime` for the common case.
+   *
+   * Optional. @default null
+   */
   deploymentOptions?: Record<string, any>;
-  /** Optional. Shorthand: sets `deploymentOptions.runtime`. */
+  /**
+   * Deployment runtime shorthand. Sets `deploymentOptions.runtime` and is merged
+   * with any explicit `deploymentOptions`. One of `'cloudflare-js'` | `'lambda-deno'`
+   * | `'lambda-python'`.
+   *
+   * Optional.
+   */
   runtime?: FunctionRuntime;
-  /** Optional. Outbound domain allowlist. @default null */
+  /**
+   * Outbound domain allowlist. Requests to domains not in this list will be blocked.
+   *
+   * Optional. @default null
+   */
   allowedDomains?: string[];
-  /** Optional. Whether the function runs asynchronously. @default false */
+  /**
+   * Whether this function runs asynchronously (fire-and-forget).
+   *
+   * Optional. @default `false`
+   */
   isAsync?: boolean;
 }
 
+/**
+ * Defines a serverless function and registers it with the manifest.
+ *
+ * A `ManifestFunction` packages TypeScript handler code that runs on Rippling's
+ * serverless infrastructure. Functions are the backing implementation for
+ * {@link SduiPage} surfaces. The handler must export `onRipplingEvent`.
+ *
+ * This class is named `ManifestFunction` to avoid collision with the JavaScript
+ * built-in `Function`. It is also re-exported as `Function` from the barrel for
+ * convenience.
+ *
+ * @example
+ * ```ts
+ * const todayScheduleFn = new ManifestFunction(manifest, {
+ *   apiName: 'gym_today_schedule_fn',
+ *   name: 'Today\'s schedule (SDUI)',
+ *   description: 'Searchable grid of class sessions',
+ *   runtime: 'lambda-deno',
+ *   code: handlerSource,
+ *   dependencies: {
+ *     '@rippling/rippling-sdk': '^0.2.0-alpha.33',
+ *     '@rippling/sdui-builder': '^0.1.0',
+ *   },
+ *   isAsync: false,
+ * });
+ * ```
+ *
+ * @see {@link SduiPage} — wraps a `ManifestFunction` as a navigable UI surface.
+ */
 export class ManifestFunction {
   private readonly _apiName: string;
   private readonly _name: string;
@@ -42,7 +103,10 @@ export class ManifestFunction {
   private readonly _allowedDomains: string[] | undefined;
   private readonly _isAsync: boolean;
 
-  /** Build a new function and auto-register with `scope`; `runtime` is merged into `deploymentOptions` if set. */
+  /**
+   * @param scope - The manifest to register this function with.
+   * @param props - Initialization properties.
+   */
   constructor(scope: ManifestScope, props: ManifestFunctionProps) {
     this._apiName = props.apiName;
     this._name = props.name;
@@ -58,12 +122,18 @@ export class ManifestFunction {
     scope._register(this);
   }
 
-  /** Backend api_name for this function. */
+  /**
+   * Returns the api_name of this function (e.g. `'gym_today_schedule_fn'`).
+   */
   getApiName(): string {
     return this._apiName;
   }
 
-  /** Serialize to the backend `FUNCTION` wire shape; empty fields are omitted. */
+  /**
+   * Serializes this function to the wire format consumed by the manifest install endpoint.
+   *
+   * @returns A plain object with `type: 'FUNCTION'`. Empty or unset optional fields are omitted.
+   */
   toDict(): Record<string, any> {
     const component: Record<string, any> = {
       type: 'FUNCTION',

package/src/lib/manifest/rule.ts

@@ -1,47 +1,81 @@
-/*
- * The contents of this file were inserted manually and are not generated by Stainless.
- *
- * Record-triggered flows (automation rules) for custom objects.
- * Backend schema: CUSTOM_OBJECT_RECORD_TRIGGERED_FLOW (v2)
- *
- * Construction is CDK-style: `new Rule(customObject, props)` — the CO is
- * the first positional arg, and the rule auto-registers with the manifest
- * via the CO's scope chain.
- */
-
 import { generateId, type TriggerType, type UpdateTriggerType } from './_helpers';
 import type { CustomObject } from './custom-object';
 import type { Field } from './field';
 
-const VALID_TRIGGERS: TriggerType[] = ['CREATE', 'UPDATE', 'CREATE_OR_UPDATE'];
-
+/**
+ * A single action performed when a {@link Rule} fires.
+ */
 export interface RuleAction {
-  /** Target field — live `Field` ref. */
+  /**
+   * The field to set when this action runs.
+   *
+   * Required.
+   */
   targetField: Field;
   /**
-   * Set the target to a fixed value. Mutually exclusive with `rqlFormula`.
-   * For `SELECT` / `RADIO` targets, the wire payload uses a list (multichoice
-   * shape); pass a string/one value or an array — both are normalized to an array.
+   * Set the target field to a fixed value. Mutually exclusive with `rqlFormula`.
+   *
+   * Optional. For `SELECT` / `RADIO` fields, pass a string or single-element array —
+   * both are normalized to an array on the wire.
    */
   fixedValue?: any;
-  /** Set the target to the result of an RQL formula. */
+  /**
+   * Set the target field to the result of an RQL formula. Mutually exclusive with `fixedValue`.
+   *
+   * Optional.
+   */
   rqlFormula?: string;
 }
 
+/**
+ * Initialization properties for {@link Rule}.
+ */
 export interface RuleProps {
-  /** Required. Display name of the flow. */
+  /**
+   * Display name of this automation rule shown in the UI.
+   *
+   * Required.
+   */
   flowName: string;
-  /** Required. When the flow fires. */
+  /**
+   * When this rule fires. One of `'CREATE'` | `'UPDATE'` | `'CREATE_OR_UPDATE'`.
+   *
+   * Required. The constructor throws if an invalid value is passed.
+   */
   triggerType: TriggerType;
-  /** Identity override. Override the flow identifier. @default generateId('flow') */
+  /**
+   * Stable identifier for this rule. Pass a human-readable slug
+   * (e.g. `'gym_default_enrollment_status'`) to keep it stable across regenerations.
+   *
+   * Optional. Auto-generated when omitted. @default generateId('flow')
+   */
   flowId?: string;
-  /** Optional. RQL formula guard — fires only when truthy. @default null */
+  /**
+   * RQL formula guard — the rule fires only when this expression is truthy.
+   *
+   * Optional. @default null
+   */
   rqlCondition?: string;
-  /** Conditional. Update-trigger condition type. @default 'MEETS_CONDITION_AFTER_ONLY' */
+  /**
+   * Controls when an `UPDATE` trigger fires relative to the condition.
+   * One of `'MEETS_CONDITION_AFTER_ONLY'` | `'MEETS_CONDITION_BEFORE_OR_AFTER'`.
+   *
+   * Conditional. Only meaningful when `triggerType` is `'UPDATE'` or `'CREATE_OR_UPDATE'`.
+   * @default `'MEETS_CONDITION_AFTER_ONLY'`
+   */
   updateTriggerType?: UpdateTriggerType;
-  /** Optional. Internal description. @default null */
+  /**
+   * Internal description of this rule (for developer reference only).
+   *
+   * Optional. @default null
+   */
   description?: string;
-  /** Optional. Actions to run when the flow fires. @default [] */
+  /**
+   * Actions to run when the rule fires. Each action sets one field to a fixed value
+   * or RQL formula result.
+   *
+   * Optional. @default `[]`
+   */
   actions?: RuleAction[];
 }
 
@@ -69,6 +103,24 @@ function actionToDict(action: RuleAction): Record<string, any> {
   return out;
 }
 
+/**
+ * Defines a record-triggered automation rule and registers it with the manifest.
+ *
+ * A rule fires automatically when a record on the parent custom object is created,
+ * updated, or both — depending on `triggerType`. Each rule runs a list of actions
+ * that set field values, optionally guarded by an RQL condition.
+ *
+ * @example
+ * ```ts
+ * new Rule(enrollmentObj, {
+ *   flowId: 'gym_default_enrollment_status',
+ *   flowName: 'Default attendance to Registered',
+ *   triggerType: 'CREATE',
+ *   description: 'New roster rows start as Registered unless changed',
+ *   actions: [{ targetField: enrollmentAttendanceField, fixedValue: ['Registered'] }],
+ * });
+ * ```
+ */
 export class Rule {
   private readonly _flowId: string;
   private readonly _customObjectApiName: string;
@@ -79,8 +131,13 @@ export class Rule {
   private readonly _description: string | undefined;
   private readonly _actions: RuleAction[];
 
-  /** Build a new rule and auto-register with the CO's scope; validates `triggerType`. */
+  /**
+   * @param customObject - The custom object this rule is attached to.
+   * @param props - Initialization properties.
+   * @throws {Error} If `props.triggerType` is not one of `'CREATE'`, `'UPDATE'`, `'CREATE_OR_UPDATE'`.
+   */
   constructor(customObject: CustomObject, props: RuleProps) {
+    const VALID_TRIGGERS: TriggerType[] = ['CREATE', 'UPDATE', 'CREATE_OR_UPDATE'];
     if (!VALID_TRIGGERS.includes(props.triggerType)) {
       throw new Error(
         `Invalid trigger_type: ${props.triggerType}. Must be one of: ${VALID_TRIGGERS.join(', ')}`,
@@ -97,17 +154,26 @@ export class Rule {
     customObject._register(this);
   }
 
-  /** Backend flow_id used as this rule's identifier. */
+  /**
+   * Returns the stable identifier for this rule (e.g. `'gym_default_enrollment_status'`).
+   */
   getFlowId(): string {
     return this._flowId;
   }
 
-  /** api_name of the CustomObject this rule lives on. */
+  /**
+   * Returns the api_name of the custom object this rule is attached to.
+   */
   getCustomObjectApiName(): string {
     return this._customObjectApiName;
   }
 
-  /** Serialize to the backend `CUSTOM_OBJECT_RECORD_TRIGGERED_FLOW` wire shape. */
+  /**
+   * Serializes this rule to the wire format consumed by the manifest install endpoint.
+   *
+   * @returns A plain object with `type: 'CUSTOM_OBJECT_RECORD_TRIGGERED_FLOW'`.
+   * Optional fields are omitted when unset; `actions` is omitted when empty.
+   */
   toDict(): Record<string, any> {
     const component: Record<string, any> = {
       type: 'CUSTOM_OBJECT_RECORD_TRIGGERED_FLOW',