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

package/src/lib/manifest/index.ts

@@ -0,0 +1,114 @@
+/** Manifest builder public API (hand-written, not Stainless-generated). */
+
+export {
+  generateId,
+  type EdgeType,
+  type FieldType,
+  type FormulaFieldType,
+  type FunctionRuntime,
+  type ObjectScope,
+  type PageType,
+  type SortOrder,
+  type SummaryAggregation,
+  type SummaryFilterOperator,
+  type TriggerType,
+  type UpdateTriggerType,
+  type ValidationLevel,
+  type ValidationState,
+} from './_helpers';
+
+export { App, type AppIcon, type AppPage, type AppProps } from './app';
+
+export { Category, type CategoryProps } from './category';
+
+export { CustomObject, type CustomObjectProps, type IconConfig } from './custom-object';
+
+export { CustomObjectFieldSection, type CustomObjectFieldSectionProps } from './custom-object-field-section';
+
+export {
+  CustomObjectPageLayout,
+  type CustomObjectPageLayoutProps,
+  type CustomTab,
+  type FieldsSection,
+  type HeaderEdits,
+  type NewHeaderField,
+  type PageLayoutSection,
+  type PageLayoutTab,
+  type SectionField,
+  type SectionFieldsLayout,
+  type SystemHeaderFieldEdit,
+  type SystemSectionEdit,
+  type SystemTabEdit,
+  type TabEdits,
+  type TabWithSections,
+  type VisibilityCondition,
+  type VisibilityConditions,
+} from './custom-object-page-layout';
+
+export {
+  Field,
+  type FieldProps,
+  type SummaryFilter,
+
+  // Concrete field variants (one class per wire-level field type, mirroring
+  // AWS CDK's per-action-class pattern in `aws-codepipeline-actions`).
+  TextField,
+  type TextFieldProps,
+  LongTextField,
+  type LongTextFieldProps,
+  EmailField,
+  type EmailFieldProps,
+  UrlField,
+  type UrlFieldProps,
+  PhoneField,
+  type PhoneFieldProps,
+  NumberField,
+  type NumberFieldProps,
+  CurrencyField,
+  type CurrencyFieldProps,
+  PercentageField,
+  type PercentageFieldProps,
+  DateField,
+  type DateFieldProps,
+  DatetimeField,
+  type DatetimeFieldProps,
+  TimeField,
+  type TimeFieldProps,
+  SelectField,
+  type SelectFieldProps,
+  RadioField,
+  type RadioFieldProps,
+  BooleanField,
+  type BooleanFieldProps,
+  FileField,
+  type FileFieldProps,
+  LookupField,
+  type LookupFieldProps,
+  ParentChildField,
+  type ParentChildFieldProps,
+  FormulaField,
+  type FormulaFieldProps,
+  SummaryField,
+  type SummaryFieldProps,
+} from './field';
+
+export { ListViewDef, type ListViewDefProps } from './list-view';
+
+export {
+  ManifestBuilder,
+  type ManifestBuilderProps,
+  type ManifestComponent,
+  type ManifestScope,
+} from './manifest-builder';
+
+export {
+  ManifestFunction,
+  ManifestFunction as Function,
+  type ManifestFunctionProps,
+} from './manifest-function';
+
+export { Rule, type RuleAction, type RuleProps } from './rule';
+
+export { SduiPage, type SduiPageProps } from './sdui-page';
+
+export { Validation, type ValidationProps } from './validation';

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

@@ -0,0 +1,183 @@
+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 {
+  /**
+   * Display name of this list view shown in the UI (e.g. `'All members'`).
+   *
+   * Required.
+   */
+  name: string;
+  /**
+   * Columns to display, as live {@link Field} references. At least one field is required.
+   *
+   * Required.
+   */
+  fields: Field[];
+  /**
+   * Whether this view is visible to all users (`true`) or only the record owner (`false`).
+   *
+   * Required.
+   */
+  isPublic: boolean;
+  /**
+   * 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;
+  /**
+   * Field to sort by. Required when `sortOrder` is set.
+   *
+   * Optional.
+   */
+  orderBy?: Field;
+  /**
+   * Sort direction. One of `'ASC'` | `'DESC'`. Requires `orderBy` to be set.
+   *
+   * Optional.
+   */
+  sortOrder?: SortOrder;
+  /**
+   * Record scope for this view. One of `'all'` | `'my_records'`.
+   *
+   * Optional. @default `'all'`
+   */
+  objectScope?: ObjectScope;
+  /**
+   * Human-readable description of this view.
+   *
+   * Optional. @default null
+   */
+  description?: string;
+  /**
+   * Per-column configuration overrides (width, visibility, etc.).
+   *
+   * Optional. @default `{}`
+   */
+  columnConfig?: Record<string, any>;
+  /**
+   * 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;
+  private readonly _name: string;
+  private readonly _fields: Field[];
+  private readonly _isPublic: boolean;
+  private readonly _orderBy: Field | undefined;
+  private readonly _sortOrder: SortOrder | undefined;
+  private readonly _objectScope: ObjectScope | undefined;
+  private readonly _description: string | undefined;
+  private readonly _columnConfig: Record<string, any> | undefined;
+  private readonly _rqlFilter: string | undefined;
+
+  /**
+   * @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) {
+      throw new Error('ListViewDef: must have at least one field');
+    }
+    if (props.sortOrder && !props.orderBy) {
+      throw new Error('ListViewDef: sortOrder requires orderBy to be set');
+    }
+    this._viewId = props.viewId ?? generateId('view');
+    this._customObjectApiName = customObject.getApiName();
+    this._name = props.name;
+    this._fields = [...props.fields];
+    this._isPublic = props.isPublic;
+    this._orderBy = props.orderBy;
+    this._sortOrder = props.sortOrder;
+    this._objectScope = props.objectScope ?? 'all';
+    this._description = props.description;
+    this._columnConfig = props.columnConfig;
+    this._rqlFilter = props.rqlFilter;
+    customObject._register(this);
+  }
+
+  /**
+   * Returns the stable identifier for this view (e.g. `'view_gym_all_members'`).
+   */
+  getViewId(): string {
+    return this._viewId;
+  }
+
+  /**
+   * Returns the api_name of the custom object this view belongs to.
+   */
+  getCustomObjectApiName(): string {
+    return this._customObjectApiName;
+  }
+
+  /**
+   * 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',
+      object_rql_name: this._customObjectApiName,
+      view_id: this._viewId,
+      name: this._name,
+      public: this._isPublic,
+      fields: this._fields.map((f) => f.getApiName()),
+    };
+    if (this._description != null) d['description'] = this._description;
+    if (this._objectScope != null) d['object_scope'] = this._objectScope;
+    if (this._sortOrder != null) d['sort_order'] = this._sortOrder;
+    if (this._orderBy != null) d['order_by'] = this._orderBy.getApiName();
+    if (this._columnConfig != null) d['column_config'] = this._columnConfig;
+    if (this._rqlFilter != null) d['rql_filter'] = this._rqlFilter;
+    return d;
+  }
+}

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

@@ -0,0 +1,140 @@
+/**
+ * Any object that can be included in a manifest.
+ *
+ * Implement `toDict()` to return the component's wire-format dict.
+ * All built-in SDK classes implement this interface automatically.
+ */
+export interface ManifestComponent {
+  toDict(): Record<string, any>;
+}
+
+/**
+ * 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 (e.g. `'gym_membership_management'`).
+   *
+   * Required.
+   */
+  key: string;
+  /**
+   * Display name for this manifest.
+   *
+   * Optional. Defaults to `key` when not provided.
+   */
+  name?: string;
+  /**
+   * 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[] = [];
+
+  /**
+   * @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');
+    }
+    this.key = props.key;
+    this.name = props.name || props.key;
+    this.description = props.description ?? '';
+  }
+
+  /**
+   * @internal Scope hook invoked by child constructors. Components enter the
+   * manifest here — there is no other path.
+   */
+  _register(component: ManifestComponent): void {
+    if (typeof component.toDict !== 'function') {
+      throw new TypeError('Component must have a toDict() method');
+    }
+    this._components.push(component);
+  }
+
+  /**
+   * 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,
+      name: this.name,
+    };
+    if (this.description) {
+      metadata['description'] = this.description;
+    }
+    const components = this._components.map((c) => c.toDict());
+    return { metadata, components };
+  }
+
+  /**
+   * 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());
+  }
+
+  /**
+   * 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

@@ -0,0 +1,151 @@
+import type { FunctionRuntime } from './_helpers';
+import type { ManifestScope } from './manifest-builder';
+
+/**
+ * Initialization properties for {@link ManifestFunction}.
+ */
+export interface ManifestFunctionProps {
+  /**
+   * Unique identifier for this function (e.g. `'gym_today_schedule_fn'`).
+   *
+   * Required.
+   */
+  apiName: string;
+  /**
+   * Display name shown in the Rippling UI.
+   *
+   * Required.
+   */
+  name: string;
+  /**
+   * TypeScript handler source code. Must export an `onRipplingEvent` function.
+   *
+   * Optional. @default `''`
+   */
+  code?: string;
+  /**
+   * Human-readable description of what this function does.
+   *
+   * Optional. @default `''`
+   */
+  description?: string;
+  /**
+   * NPM package dependencies as a `{ packageName: versionRange }` map
+   * (e.g. `{ '@rippling/rippling-sdk': '^0.2.0' }`).
+   *
+   * Optional. @default null
+   */
+  dependencies?: Record<string, string>;
+  /**
+   * Raw deployment options object. Prefer `runtime` for the common case.
+   *
+   * Optional. @default null
+   */
+  deploymentOptions?: Record<string, any>;
+  /**
+   * Deployment runtime shorthand. Sets `deploymentOptions.runtime` and is merged
+   * with any explicit `deploymentOptions`. One of `'cloudflare-js'` | `'lambda-deno'`
+   * | `'lambda-python'`.
+   *
+   * Optional.
+   */
+  runtime?: FunctionRuntime;
+  /**
+   * Outbound domain allowlist. Requests to domains not in this list will be blocked.
+   *
+   * Optional. @default null
+   */
+  allowedDomains?: string[];
+  /**
+   * 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;
+  private readonly _code: string;
+  private readonly _description: string;
+  private readonly _dependencies: Record<string, string> | undefined;
+  private readonly _deploymentOptions: Record<string, any> | undefined;
+  private readonly _allowedDomains: string[] | undefined;
+  private readonly _isAsync: boolean;
+
+  /**
+   * @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;
+    this._code = props.code ?? '';
+    this._description = props.description ?? '';
+    this._dependencies = props.dependencies;
+    this._deploymentOptions = props.deploymentOptions;
+    if (props.runtime) {
+      this._deploymentOptions = { ...(this._deploymentOptions ?? {}), runtime: props.runtime };
+    }
+    this._allowedDomains = props.allowedDomains;
+    this._isAsync = props.isAsync ?? false;
+    scope._register(this);
+  }
+
+  /**
+   * Returns the api_name of this function (e.g. `'gym_today_schedule_fn'`).
+   */
+  getApiName(): string {
+    return this._apiName;
+  }
+
+  /**
+   * 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',
+      name: this._name,
+      api_name: this._apiName,
+    };
+    if (this._description) component['description'] = this._description;
+    if (this._code) component['code_draft'] = this._code;
+    if (this._dependencies != null) component['dependencies'] = this._dependencies;
+    if (this._deploymentOptions != null) component['deployment_options'] = this._deploymentOptions;
+    if (this._allowedDomains != null) component['allowed_domains'] = this._allowedDomains;
+    if (this._isAsync) component['is_async'] = true;
+    return component;
+  }
+}