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

package/src/lib/manifest/rule.ts

@@ -0,0 +1,191 @@
+import { generateId, type TriggerType, type UpdateTriggerType } from './_helpers';
+import type { CustomObject } from './custom-object';
+import type { Field } from './field';
+
+/**
+ * A single action performed when a {@link Rule} fires.
+ */
+export interface RuleAction {
+  /**
+   * The field to set when this action runs.
+   *
+   * Required.
+   */
+  targetField: Field;
+  /**
+   * 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 field to the result of an RQL formula. Mutually exclusive with `fixedValue`.
+   *
+   * Optional.
+   */
+  rqlFormula?: string;
+}
+
+/**
+ * Initialization properties for {@link Rule}.
+ */
+export interface RuleProps {
+  /**
+   * Display name of this automation rule shown in the UI.
+   *
+   * Required.
+   */
+  flowName: string;
+  /**
+   * When this rule fires. One of `'CREATE'` | `'UPDATE'` | `'CREATE_OR_UPDATE'`.
+   *
+   * Required. The constructor throws if an invalid value is passed.
+   */
+  triggerType: TriggerType;
+  /**
+   * 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;
+  /**
+   * RQL formula guard — the rule fires only when this expression is truthy.
+   *
+   * Optional. @default null
+   */
+  rqlCondition?: string;
+  /**
+   * 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;
+  /**
+   * Internal description of this rule (for developer reference only).
+   *
+   * Optional. @default null
+   */
+  description?: string;
+  /**
+   * Actions to run when the rule fires. Each action sets one field to a fixed value
+   * or RQL formula result.
+   *
+   * Optional. @default `[]`
+   */
+  actions?: RuleAction[];
+}
+
+/** SELECT / RADIO rule actions use list `fixed_value` (Rippling rule builder). */
+function fixedValueToWire(targetField: Field, value: any): any {
+  const ft = targetField.getFieldType();
+  if (ft !== 'SELECT' && ft !== 'RADIO') {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value;
+  }
+  return [value];
+}
+
+function actionToDict(action: RuleAction): Record<string, any> {
+  const out: Record<string, any> = {
+    target_field: action.targetField.getApiName(),
+  };
+  if (action.fixedValue != null) {
+    out['fixed_value'] = fixedValueToWire(action.targetField, action.fixedValue);
+  } else if (action.rqlFormula != null) {
+    out['rql_formula'] = action.rqlFormula;
+  }
+  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;
+  private readonly _flowName: string;
+  private readonly _triggerType: TriggerType;
+  private readonly _rqlCondition: string | undefined;
+  private readonly _updateTriggerType: UpdateTriggerType | undefined;
+  private readonly _description: string | undefined;
+  private readonly _actions: RuleAction[];
+
+  /**
+   * @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(', ')}`,
+      );
+    }
+    this._flowId = props.flowId ?? generateId('flow');
+    this._customObjectApiName = customObject.getApiName();
+    this._flowName = props.flowName;
+    this._triggerType = props.triggerType;
+    this._rqlCondition = props.rqlCondition;
+    this._updateTriggerType = props.updateTriggerType;
+    this._description = props.description;
+    this._actions = [...(props.actions ?? [])];
+    customObject._register(this);
+  }
+
+  /**
+   * Returns the stable identifier for this rule (e.g. `'gym_default_enrollment_status'`).
+   */
+  getFlowId(): string {
+    return this._flowId;
+  }
+
+  /**
+   * Returns the api_name of the custom object this rule is attached to.
+   */
+  getCustomObjectApiName(): string {
+    return this._customObjectApiName;
+  }
+
+  /**
+   * 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',
+      model_rql_name: this._customObjectApiName,
+      flow_id: this._flowId,
+      flow_name: this._flowName,
+      trigger_type: this._triggerType,
+    };
+    if (this._description != null) component['description'] = this._description;
+    if (this._updateTriggerType != null) component['update_trigger_type'] = this._updateTriggerType;
+    if (this._rqlCondition != null) component['rql_condition'] = this._rqlCondition;
+    if (this._actions.length > 0) component['actions'] = this._actions.map(actionToDict);
+    return component;
+  }
+}

package/src/lib/manifest/sdui-page.ts

@@ -0,0 +1,118 @@
+import type { ManifestFunction } from './manifest-function';
+import type { ManifestScope } from './manifest-builder';
+
+/**
+ * Initialization properties for {@link SduiPage}.
+ */
+export interface SduiPageProps {
+  /**
+   * Unique identifier for this page within the package (e.g. `'gym_today_schedule'`).
+   *
+   * Required.
+   */
+  sduiPageId: string;
+  /**
+   * Display name shown as the tab label in the app (e.g. `'Today\'s schedule'`).
+   *
+   * Required.
+   */
+  name: string;
+  /**
+   * The function that renders this page. Pass a live {@link ManifestFunction} reference,
+   * or a raw api_name string for functions defined outside this manifest.
+   *
+   * Required.
+   */
+  function: ManifestFunction | string;
+  /**
+   * Human-readable description of what this page shows.
+   *
+   * Optional. @default `''`
+   */
+  description?: string;
+}
+
+/**
+ * Defines an SDUI page and registers it with the manifest.
+ *
+ * An SDUI page is a custom UI surface backed by a {@link ManifestFunction}. It appears
+ * as a tab in a Rippling {@link App}. You would normally define SDUI pages after the
+ * functions they reference, then pass them to an `App` via `pages`.
+ *
+ * @example
+ * ```ts
+ * const todaySchedulePage = new SduiPage(manifest, {
+ *   sduiPageId: 'gym_today_schedule',
+ *   name: 'Today\'s schedule',
+ *   function: todayScheduleFn,
+ *   description: 'SDUI list of class sessions for front desk',
+ * });
+ *
+ * new App(manifest, {
+ *   apiName: 'gym_membership_management_app',
+ *   name: 'Gym Membership Management',
+ *   pages: [memberObj, trainerObj, todaySchedulePage],
+ * });
+ * ```
+ *
+ * @see {@link ManifestFunction} — provides the handler that renders this page.
+ * @see {@link App} — hosts this page as a tab via `pages`.
+ */
+export class SduiPage {
+  private readonly _sduiPageId: string;
+  private readonly _name: string;
+  private readonly _functionApiName: string;
+  private readonly _description: string;
+
+  /**
+   * @param scope - The manifest to register this page with.
+   * @param props - Initialization properties.
+   * @throws {Error} If `sduiPageId`, `name`, or `function` is missing.
+   */
+  constructor(scope: ManifestScope, props: SduiPageProps) {
+    if (!props.sduiPageId) throw new Error('sduiPageId is required');
+    if (!props.name) throw new Error('name is required');
+    if (!props.function) throw new Error('function is required');
+    this._sduiPageId = props.sduiPageId;
+    this._name = props.name;
+    this._functionApiName = typeof props.function === 'string' ? props.function : props.function.getApiName();
+    this._description = props.description ?? '';
+    scope._register(this);
+  }
+
+  /**
+   * Returns the unique page identifier (e.g. `'gym_today_schedule'`).
+   */
+  getSduiPageId(): string {
+    return this._sduiPageId;
+  }
+
+  /**
+   * Returns the display name (tab label) of this page.
+   */
+  getName(): string {
+    return this._name;
+  }
+
+  /**
+   * Returns the api_name of the function backing this page.
+   */
+  getFunctionApiName(): string {
+    return this._functionApiName;
+  }
+
+  /**
+   * Serializes this SDUI page to the wire format consumed by the manifest install endpoint.
+   *
+   * @returns A plain object with `type: 'SDUI_PAGE'`.
+   */
+  toDict(): Record<string, any> {
+    return {
+      type: 'SDUI_PAGE',
+      name: this._name,
+      sdui_page_id: this._sduiPageId,
+      function_api_name: this._functionApiName,
+      description: this._description,
+    };
+  }
+}

package/src/lib/manifest/validation.ts

@@ -0,0 +1,150 @@
+import { generateId, type ValidationLevel, type ValidationState } from './_helpers';
+import type { CustomObject } from './custom-object';
+import type { Field } from './field';
+
+/**
+ * Initialization properties for {@link Validation}.
+ */
+export interface ValidationProps {
+  /**
+   * Display name of this validation rule shown in the UI.
+   *
+   * Required.
+   */
+  displayName: string;
+  /**
+   * RQL formula that returns `true` when the record is **invalid**.
+   *
+   * Required. Note the violation semantics: a truthy result triggers the error,
+   * not a passing check. Example: `'(end_time__c <= start_time__c)'` fires when
+   * end is not after start.
+   */
+  rqlFormula: string;
+  /**
+   * User-facing error message shown when the validation fires.
+   *
+   * Required. Pass an empty string for no message.
+   */
+  errorMessage: string;
+  /**
+   * Whether this rule is active or inactive.
+   *
+   * Required. One of `'ACTIVE'` | `'INACTIVE'`.
+   */
+  state: ValidationState;
+  /**
+   * Whether the error is shown at the record level or on a specific field.
+   *
+   * Required. One of `'RECORD'` | `'FIELD'`. When `'FIELD'`, also set `fieldRef`.
+   */
+  level: ValidationLevel;
+  /**
+   * Internal description of this rule (for developer reference only).
+   *
+   * Required. Pass an empty string if unused.
+   */
+  ruleDescription: string;
+  /**
+   * Stable identifier for this rule. Pass a human-readable slug
+   * (e.g. `'gym_session_end_after_start'`) to keep it stable across regenerations.
+   *
+   * Optional. Auto-generated when omitted. @default generateId('rule')
+   */
+  ruleId?: string;
+  /**
+   * The field the error is pinned to. Typically paired with `level: 'FIELD'`.
+   *
+   * Optional.
+   */
+  fieldRef?: Field;
+}
+
+/**
+ * Defines a validation rule and registers it with the manifest.
+ *
+ * A validation rule evaluates an RQL formula on save and blocks the operation
+ * when the formula returns `true`. You would normally define validations after
+ * the fields they reference.
+ *
+ * **Violation semantics:** the formula encodes the *invalid* condition, not the
+ * valid one. `'(end_time__c <= start_time__c)'` fires when end is before or equal
+ * to start — i.e., it is truthy when the record is wrong.
+ *
+ * @example
+ * ```ts
+ * new Validation(sessionObj, {
+ *   ruleId: 'gym_session_end_after_start',
+ *   displayName: 'End time must be after start',
+ *   rqlFormula: '(end_time__c <= start_time__c)',
+ *   errorMessage: 'End time must be after the start time.',
+ *   ruleDescription: 'Prevents zero-length or inverted intervals',
+ *   state: 'ACTIVE',
+ *   level: 'FIELD',
+ *   fieldRef: sessionEndField,
+ * });
+ * ```
+ */
+export class Validation {
+  private readonly _ruleId: string;
+  private readonly _customObjectApiName: string;
+  private readonly _displayName: string;
+  private readonly _rqlFormula: string;
+  private readonly _errorMessage: string;
+  private readonly _state: ValidationState;
+  private readonly _level: ValidationLevel;
+  private readonly _ruleDescription: string;
+  private readonly _fieldRef: Field | undefined;
+
+  /**
+   * @param customObject - The custom object this rule applies to.
+   * @param props - Initialization properties.
+   */
+  constructor(customObject: CustomObject, props: ValidationProps) {
+    this._ruleId = props.ruleId ?? generateId('rule');
+    this._customObjectApiName = customObject.getApiName();
+    this._displayName = props.displayName;
+    this._rqlFormula = props.rqlFormula;
+    this._errorMessage = props.errorMessage;
+    this._state = props.state;
+    this._level = props.level;
+    this._ruleDescription = props.ruleDescription;
+    this._fieldRef = props.fieldRef;
+    customObject._register(this);
+  }
+
+  /**
+   * Returns the stable identifier for this validation rule (e.g. `'gym_session_end_after_start'`).
+   */
+  getRuleId(): string {
+    return this._ruleId;
+  }
+
+  /**
+   * Returns the api_name of the custom object this validation rule applies to.
+   */
+  getCustomObjectApiName(): string {
+    return this._customObjectApiName;
+  }
+
+  /**
+   * Serializes this validation rule to the wire format consumed by the manifest install endpoint.
+   *
+   * @returns A plain object with `type: 'CUSTOM_OBJECT_VALIDATION_RULE'`.
+   * `field_rql_name` is omitted when `fieldRef` was not provided.
+   */
+  toDict(): Record<string, any> {
+    const component: Record<string, any> = {
+      type: 'CUSTOM_OBJECT_VALIDATION_RULE',
+      model_rql_name: this._customObjectApiName,
+      rule_id: this._ruleId,
+      state: this._state,
+      level: this._level,
+      display_name: this._displayName,
+      rule_description: this._ruleDescription,
+      custom_error_message: this._errorMessage,
+      rql_formula: this._rqlFormula,
+    };
+    if (this._fieldRef != null) component['field_rql_name'] = this._fieldRef.getApiName();
+    return component;
+  }
+}

package/src/lib/sdui/actions.ts

@@ -0,0 +1,58 @@
+import { extractPath } from './state';
+
+export interface ActionBinding {
+  action: string;
+  params?: Record<string, unknown>;
+  onSuccess?: ActionBinding | { set: Record<string, unknown> };
+  onError?: ActionBinding | { set: Record<string, unknown> };
+}
+
+export function set(ref: unknown, value: unknown): ActionBinding {
+  return { action: 'setState', params: { statePath: extractPath(ref), value } };
+}
+
+export function push(ref: unknown, value: unknown, opts?: { clear?: unknown }): ActionBinding {
+  const params: Record<string, unknown> = { statePath: extractPath(ref), value };
+  if (opts?.clear) {
+    params['clearStatePath'] = extractPath(opts.clear);
+  }
+  return { action: 'pushState', params };
+}
+
+export function remove(ref: unknown, index: unknown): ActionBinding {
+  return { action: 'removeState', params: { statePath: extractPath(ref), index } };
+}
+
+export function callFunction(
+  functionId: string,
+  action: string,
+  opts?: Record<string, unknown>,
+): ActionBinding {
+  const { responsePath, onSuccess, onError, ...rest } = opts || {};
+  const params: Record<string, unknown> = { functionId, action, ...rest };
+  if (responsePath !== undefined) params['responsePath'] = responsePath;
+  const binding: ActionBinding = { action: 'triggerFunction', params };
+  if (onSuccess) binding.onSuccess = onSuccess as ActionBinding;
+  if (onError) binding.onError = onError as ActionBinding;
+  return binding;
+}
+
+export function nav(config: { path: string; openInNewTab?: boolean }): ActionBinding {
+  return { action: 'navigate', params: config };
+}
+
+export function notify(message: string, variant: string): ActionBinding {
+  return { action: 'showNotification', params: { message, variant } };
+}
+
+export function validate(statePath = '/formValidation'): ActionBinding {
+  return { action: 'validateForm', params: { statePath } };
+}
+
+export function openModal(modalId: string): ActionBinding {
+  return { action: 'openModal', params: { modalId } };
+}
+
+export function closeModal(): ActionBinding {
+  return { action: 'closeModal' };
+}

package/src/lib/sdui/component.ts

@@ -0,0 +1,122 @@
+/**
+ * component() — creates a stateful component boundary.
+ *
+ * Provides ctx.useState (scoped local state) and ctx.useEffect (onMount actions).
+ * The returned element is automatically wrapped with _LocalStateProvider in the rendered spec.
+ *
+ * Usage:
+ *   function MembersGrid(props) {
+ *     return component((ctx) => {
+ *       const local = ctx.useState({ data: [], loading: true })
+ *       ctx.useEffect(fetchAction)
+ *       return { element: DataGrid({ ... }), refresh: fetchAction }
+ *     })
+ *   }
+ */
+
+import type { SpecNode } from './components';
+import type { ActionBinding } from './actions';
+
+let _idCounter = 0;
+function generateId(): string {
+  return `auto_${(++_idCounter).toString(36)}_${Date.now().toString(36)}`;
+}
+
+// Reset counter (for testing)
+export function _resetIdCounter(): void {
+  _idCounter = 0;
+}
+
+export interface StateScope {
+  /** Read state value: { $state: "/auto_xxx/field" } */
+  readonly [key: string]: any;
+  /** Two-way bind: { $bindState: "/auto_xxx/field" } */
+  readonly $bind: { $bindState: string };
+  /** Raw path string */
+  readonly $path: string;
+}
+
+interface ComponentContext {
+  /** Declare scoped local state. Returns a proxy for reading/binding. */
+  useState<T extends Record<string, unknown>>(initial: T): StateScope;
+  /** Register an action to fire on mount (when element becomes visible). */
+  useEffect(action: ActionBinding | ActionBinding[]): void;
+}
+
+interface ComponentResult {
+  element: SpecNode;
+  [key: string]: any; // exposed actions like refresh, reset, etc.
+}
+
+function createScopeProxy(basePath: string): StateScope {
+  const handler: ProxyHandler<object> = {
+    get(_target, prop) {
+      if (prop === '$bind') return { $bindState: basePath };
+      if (prop === '$path') return basePath;
+      if (prop === '$state') return basePath;
+      if (prop === 'toJSON') return () => ({ $state: basePath });
+      if (prop === Symbol.toPrimitive) return () => `$state:${basePath}`;
+
+      const childPath = `${basePath}/${String(prop)}`;
+      return createScopeProxy(childPath);
+    },
+  };
+  return new Proxy({} as any, handler);
+}
+
+export function component(factory: (ctx: ComponentContext) => ComponentResult): ComponentResult {
+  let localState: { path: string; initial: unknown } | null = null;
+  let mountAction: ActionBinding | ActionBinding[] | null = null;
+
+  const ctx: ComponentContext = {
+    useState<T extends Record<string, unknown>>(initial: T): StateScope {
+      const path = `/${generateId()}`;
+      localState = { path, initial };
+      return createScopeProxy(path);
+    },
+    useEffect(action: ActionBinding | ActionBinding[]) {
+      mountAction = action;
+    },
+  };
+
+  const result = factory(ctx);
+
+  // Capture state after factory execution (TS can't track closure mutations)
+  const capturedState = localState as { path: string; initial: unknown } | null;
+  const capturedMount = mountAction;
+
+  // If no local state and no effects, return as-is
+  if (!capturedState && !capturedMount) {
+    return result;
+  }
+
+  // Wrap element with _LocalStateProvider
+  const providerProps: Record<string, unknown> = {};
+  if (capturedState) {
+    providerProps['statePath'] = capturedState.path;
+    providerProps['initialValue'] = capturedState.initial;
+  }
+  if (capturedMount) {
+    providerProps['onMountAction'] = capturedMount;
+  }
+
+  const wrapper: SpecNode = {
+    type: '_LocalStateProvider',
+    props: providerProps,
+    children: [result.element],
+  };
+
+  // Attach the local state to the spec's state tree
+  // The render() function will collect this via a special marker
+  if (capturedState) {
+    (wrapper as any)._localStateRegistration = {
+      path: capturedState.path,
+      initial: capturedState.initial,
+    };
+  }
+
+  return {
+    ...result,
+    element: wrapper,
+  };
+}