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

package/src/lib/manifest/_helpers.ts

@@ -0,0 +1,164 @@
+/*
+ * The contents of this file were inserted manually and are not generated by Stainless.
+ *
+ * Shared helpers and enum types for the manifest builder.
+ */
+
+let _counter = 0;
+
+/** Generate a short unique ID string (e.g. "id_a3f1b2"). */
+export function generateId(prefix = 'id'): string {
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `${prefix}_${rand}${(_counter++).toString(36)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Enum types for strongly-typed setters
+// ---------------------------------------------------------------------------
+
+/** Record-triggered flow trigger type. */
+export type TriggerType = 'CREATE' | 'UPDATE' | 'CREATE_OR_UPDATE';
+
+/**
+ * Update-trigger condition type. Mirrors the backend
+ * `FlowUpdateTriggerBehavior` enum (`constants.py`). Note the `OR_AFTER`
+ * spelling — `BEFORE_AND_AFTER` is a common typo that /validate will reject.
+ */
+export type UpdateTriggerType = 'MEETS_CONDITION_AFTER_ONLY' | 'MEETS_CONDITION_BEFORE_OR_AFTER';
+
+/** Validation rule state. */
+export type ValidationState = 'ACTIVE' | 'INACTIVE';
+
+/** Validation rule level. */
+export type ValidationLevel = 'RECORD' | 'FIELD';
+
+/** Sort direction for list views. */
+export type SortOrder = 'ASC' | 'DESC';
+
+/** Scope for list views. */
+export type ObjectScope = 'all' | 'my_records';
+
+/**
+ * Supported `data_type.field_type` values for CUSTOM_OBJECT_FIELD and
+ * CUSTOM_FIELD_V2. Note: lookup and parent-child relationships both use
+ * `field_type: 'OG_REFERENCE_FIELD'` and are differentiated by `edge_type`
+ * (see `EdgeType`). `'LOOKUP'` and `'PARENT_CHILD'` are NOT valid
+ * `field_type` values — emitting them produces invalid manifests.
+ */
+export type FieldType =
+  | 'TEXT'
+  | 'LONG_TEXT'
+  | 'EMAIL'
+  | 'URL'
+  | 'PHONE_NUMBER'
+  | 'NUMBER'
+  | 'CURRENCY'
+  | 'PERCENTAGE'
+  | 'DATE'
+  | 'DATETIME'
+  | 'TIME'
+  | 'SELECT'
+  | 'RADIO'
+  | 'BOOLEAN'
+  | 'FILE'
+  | 'OG_REFERENCE_FIELD';
+
+/**
+ * Discriminator for `OG_REFERENCE_FIELD` data types — distinguishes a plain
+ * lookup from a parent-child relationship.
+ */
+export type EdgeType = 'LOOKUP' | 'PARENT_CHILD';
+
+/**
+ * Allowed output `field_type` for Simple Formula Fields. Mirrors the UI
+ * "Data type" dropdown in the formula field editor — backend `field_type` is
+ * free-form `str`, but the product only validates these 7 variants end-to-end.
+ */
+export type FormulaFieldType = 'TEXT' | 'NUMBER' | 'BOOLEAN' | 'CURRENCY' | 'PERCENTAGE' | 'DATE' | 'URL';
+
+/** Runtime for FUNCTION component. */
+export type FunctionRuntime = 'cloudflare-js' | 'lambda-deno' | 'lambda-python';
+
+/**
+ * Page type inside CUSTOM_APP. Mirrors the backend `PageType` enum
+ * (`pages.py`). The SDK currently models the two surfaces it supports —
+ * object pages and SDUI pages. `function_page` is NOT a valid backend token;
+ * wrap a function in an SDUI page instead.
+ */
+export type PageType = 'object_page' | 'sdui_page';
+
+// ---------------------------------------------------------------------------
+// Summary-field constants (for Field.summary)
+// ---------------------------------------------------------------------------
+
+/** Backend supports exactly these four (`constants.py:1316`). */
+export type SummaryAggregation = 'COUNT' | 'SUM' | 'MIN' | 'MAX';
+
+/**
+ * RQL operator for summary filters. Scalar-only, matching the admin
+ * condition-builder dropdown.
+ *
+ * The backend's RQL engine accepts a wider set (WHERE_CLAUSE_OPERATORS
+ * includes `LIKE`, `ILIKE`, `IN`, `CONTAINS`, …), but summary filters
+ * authored by the UI are restricted to plain scalar comparisons. Emitting
+ * anything else from the SDK produces a manifest that /validate accepts
+ * but the admin UI cannot render or edit — a split-brain config.
+ */
+export type SummaryFilterOperator =
+  | '='
+  | '!=' // equality (all scalar types)
+  | '>'
+  | '>='
+  | '<'
+  | '<='; // ordered numeric / currency / date
+
+/**
+ * Mirrors `DERIVED_AGGREGATION_FUNCTIONS_AND_SUPPORTED_TYPES` (constants.py:1316).
+ * The output field_type of a summary must be in the aggregation function's
+ * supported set. For non-COUNT, backend further requires the output to equal
+ * the aggregated field's field_type (parent_child_util.py:217-220).
+ */
+export const ALLOWED_SUMMARY_OUTPUT: Record<SummaryAggregation, ReadonlySet<FieldType>> = {
+  COUNT: new Set(['NUMBER']),
+  SUM: new Set(['NUMBER', 'PERCENTAGE', 'CURRENCY']),
+  MIN: new Set(['NUMBER', 'PERCENTAGE', 'DATE', 'DATETIME', 'TIME', 'CURRENCY']),
+  MAX: new Set(['NUMBER', 'PERCENTAGE', 'DATE', 'DATETIME', 'TIME', 'CURRENCY']),
+};
+
+/**
+ * Per-field-type allow-list for summary filter operators, mirroring the
+ * admin condition-builder picker.
+ *
+ * This is also the single source of truth for "which field types can be
+ * used as a summary filter at all": field types **absent from this map**
+ * are rejected as filter fields entirely. The UI-hidden types are:
+ *
+ *   SELECT / RADIO          — array-valued at the RQL layer; the
+ *                             "is this option selected?" semantics are
+ *                             ambiguous for aggregations. Users are
+ *                             expected to model a plain BOOLEAN on the
+ *                             child CO (updated via Rule) and filter
+ *                             on that.
+ *   LONG_TEXT               — backend hard-rejects (parent_child_util.py).
+ *   OG_REFERENCE_FIELD      — lookup/parent-child: filter-on-what is
+ *                             ambiguous (id vs. name vs. edge metadata).
+ *
+ * The backend additionally rejects formula and summary fields as filter
+ * fields, and rejects the summary's own parent-child `lookup` field as
+ * its filter field. Those are enforced at construction-time in
+ * `SummaryField` (see `field.ts`) so the error surfaces before /validate.
+ */
+export const FILTER_OPERATORS_BY_TYPE: Partial<Record<FieldType, ReadonlySet<SummaryFilterOperator>>> = {
+  TEXT: new Set(['=', '!=']),
+  EMAIL: new Set(['=', '!=']),
+  URL: new Set(['=', '!=']),
+  PHONE_NUMBER: new Set(['=', '!=']),
+  BOOLEAN: new Set(['=', '!=']),
+  FILE: new Set(['=', '!=']),
+  NUMBER: new Set(['=', '!=', '>', '>=', '<', '<=']),
+  PERCENTAGE: new Set(['=', '!=', '>', '>=', '<', '<=']),
+  CURRENCY: new Set(['=', '!=', '>', '>=', '<', '<=']),
+  DATE: new Set(['=', '<', '>']),
+  DATETIME: new Set(['=', '<', '>']),
+  TIME: new Set(['=', '<', '>']),
+};

package/src/lib/manifest/app.ts

@@ -0,0 +1,163 @@
+import { CustomObject } from './custom-object';
+import type { ManifestScope } from './manifest-builder';
+import { SduiPage } from './sdui-page';
+
+/**
+ * A single page entry in an {@link App}.
+ *
+ * - Pass a {@link CustomObject} to create an object-page tab.
+ * - Pass an {@link SduiPage} to create a custom SDUI surface tab.
+ */
+export type AppPage = CustomObject | SduiPage;
+
+/**
+ * S3 icon reference for an {@link App}.
+ */
+export interface AppIcon {
+  /** S3 bucket holding the icon asset. */
+  s3Bucket: string;
+  /** S3 key (path) within `s3Bucket`. */
+  s3Key: string;
+}
+
+/**
+ * Initialization properties for {@link App}.
+ */
+export interface AppProps {
+  /**
+   * Unique identifier for this app (e.g. `'gym_membership_management_app'`).
+   *
+   * Required.
+   */
+  apiName: string;
+  /**
+   * Display name shown as the app title in the Rippling UI.
+   *
+   * Required.
+   */
+  name: string;
+  /**
+   * Human-readable description of what this app does.
+   *
+   * Optional. @default null
+   */
+  description?: string;
+  /**
+   * App type discriminator.
+   *
+   * Optional. @default `'custom'`
+   */
+  appType?: string;
+  /**
+   * S3 icon for this app.
+   *
+   * Optional. @default null
+   */
+  icon?: AppIcon;
+  /**
+   * Pages shown as tabs in the app. Pass {@link CustomObject} instances for object-page
+   * tabs and {@link SduiPage} instances for custom SDUI surfaces. Tab order matches
+   * the array order.
+   *
+   * Optional. @default `[]`
+   */
+  pages?: AppPage[];
+}
+
+function resolvePage(entry: AppPage): Record<string, any> {
+  if (entry instanceof CustomObject) {
+    const apiName = entry.getApiName();
+    return {
+      api_name: apiName,
+      page_type: 'object_page',
+      object_rql_name: apiName,
+    };
+  } else {
+    const sduiPageId = entry.getSduiPageId();
+    return {
+      api_name: sduiPageId,
+      page_type: 'sdui_page',
+      sdui_page_id: sduiPageId,
+    };
+  }
+}
+
+/**
+ * Defines a Rippling app and registers it with the manifest.
+ *
+ * An app is the top-level navigation container. It groups one or more pages —
+ * either custom-object record pages or SDUI surfaces — as tabs visible to users.
+ * You would normally define the app last in your manifest file, after all objects,
+ * functions, and SDUI pages have been declared.
+ *
+ * @example
+ * ```ts
+ * new App(manifest, {
+ *   apiName: 'gym_membership_management_app',
+ *   name: 'Gym Membership Management',
+ *   description: 'Members, trainers, schedules, and check-in',
+ *   appType: 'custom',
+ *   pages: [memberObj, trainerObj, sessionObj, todaySchedulePage, checkInDeskPage],
+ * });
+ * ```
+ *
+ * @see {@link CustomObject} — object-page tab source.
+ * @see {@link SduiPage} — SDUI surface tab source.
+ */
+export class App {
+  private readonly _apiName: string;
+  private readonly _name: string;
+  private readonly _description: string | undefined;
+  private readonly _appType: string | undefined;
+  private readonly _icon: AppIcon | undefined;
+  /** Wire-format pages, resolved eagerly at construction. */
+  private readonly _pages: Record<string, any>[];
+
+  /**
+   * @param scope - The manifest to register this app with.
+   * @param props - Initialization properties.
+   */
+  constructor(scope: ManifestScope, props: AppProps) {
+    this._apiName = props.apiName;
+    this._name = props.name;
+    this._description = props.description;
+    this._appType = props.appType;
+    this._icon = props.icon;
+    this._pages = (props.pages ?? []).map(resolvePage);
+    scope._register(this);
+  }
+
+  /**
+   * Returns the api_name of this app (e.g. `'gym_membership_management_app'`).
+   */
+  getApiName(): string {
+    return this._apiName;
+  }
+
+  /**
+   * Returns the display name of this app.
+   */
+  getName(): string {
+    return this._name;
+  }
+
+  /**
+   * Serializes this app to the wire format consumed by the manifest install endpoint.
+   *
+   * @returns A plain object with `type: 'CUSTOM_APP'`. Optional fields are omitted when unset.
+   */
+  toDict(): Record<string, any> {
+    const component: Record<string, any> = {
+      type: 'CUSTOM_APP',
+      api_name: this._apiName,
+      name: this._name,
+    };
+    if (this._description != null) component['description'] = this._description;
+    if (this._icon != null) {
+      component['icon'] = { s3_bucket: this._icon.s3Bucket, s3_key: this._icon.s3Key };
+    }
+    if (this._appType != null) component['app_type'] = this._appType;
+    if (this._pages.length > 0) component['pages'] = this._pages.map((p) => ({ ...p }));
+    return component;
+  }
+}

package/src/lib/manifest/category.ts

@@ -0,0 +1,100 @@
+import type { ManifestScope } from './manifest-builder';
+
+/**
+ * Initialization properties for {@link Category}.
+ */
+export interface CategoryProps {
+  /**
+   * Unique identifier for this category (e.g. `'gym__c'`). Must end with `__c`.
+   *
+   * Required.
+   */
+  apiName: string;
+  /**
+   * Display name shown in the Rippling UI (e.g. `'Gym'`).
+   *
+   * Required.
+   */
+  name: string;
+  /**
+   * Human-readable description of what this category groups.
+   *
+   * Optional. @default null
+   */
+  description?: string | null;
+}
+
+/**
+ * Defines a category and registers it with the manifest.
+ *
+ * A category is the navigation grouping that organizes related custom objects
+ * in the Rippling sidebar. You would normally define one category per domain,
+ * then pass it (or its api_name string) to each {@link CustomObject} in that domain.
+ *
+ * @example
+ * ```ts
+ * const manifest = new ManifestBuilder({
+ *   key: 'gym_membership_management',
+ *   name: 'Gym Membership Management',
+ * });
+ *
+ * const gymCategory = new Category(manifest, {
+ *   apiName: 'gym__c',
+ *   name: 'Gym',
+ *   description: 'Memberships, staff, schedules, and attendance',
+ * });
+ *
+ * // Pass the instance to any CustomObject in this domain:
+ * const memberObj = new CustomObject(manifest, {
+ *   apiName: 'gym_member__c',
+ *   name: 'Member',
+ *   category: gymCategory,
+ * });
+ * ```
+ *
+ * @see {@link CustomObject} — references this category via instance or api_name string.
+ */
+export class Category {
+  private readonly _apiName: string;
+  private readonly _name: string;
+  private readonly _description: string | null;
+
+  /**
+   * @param scope - The manifest to register this category with.
+   * @param props - Initialization properties.
+   */
+  constructor(scope: ManifestScope, props: CategoryProps) {
+    this._apiName = props.apiName;
+    this._name = props.name;
+    this._description = props.description ?? null;
+    scope._register(this);
+  }
+
+  /**
+   * Returns the api_name of this category (e.g. `'gym__c'`).
+   */
+  getApiName(): string {
+    return this._apiName;
+  }
+
+  /**
+   * Returns the display name of this category (e.g. `'Gym'`).
+   */
+  getName(): string {
+    return this._name;
+  }
+
+  /**
+   * Serializes this category to the wire format consumed by the manifest install endpoint.
+   *
+   * @returns A plain object with `type: 'CUSTOM_CATEGORY'` and all configured fields.
+   */
+  toDict(): Record<string, any> {
+    return {
+      type: 'CUSTOM_CATEGORY',
+      api_name: this._apiName,
+      name: this._name,
+      description: this._description ?? null,
+    };
+  }
+}

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

@@ -0,0 +1,93 @@
+import { generateId } from './_helpers';
+import type { CustomObject } from './custom-object';
+
+/**
+ * Initialization properties for {@link CustomObjectFieldSection}.
+ */
+export interface CustomObjectFieldSectionProps {
+  /**
+   * Display name of the section shown as a group header on the detail page
+   * (e.g. `'Profile'`, `'Membership'`).
+   *
+   * Required.
+   */
+  name: string;
+  /**
+   * Stable identifier for this section. Pass a human-readable slug
+   * (e.g. `'sec_gm_profile'`) to keep it stable across manifest regenerations.
+   *
+   * Optional. Auto-generated when omitted. @default generateId('sec')
+   */
+  sectionId?: string;
+}
+
+/**
+ * Defines a field section and registers it with the manifest.
+ *
+ * A field section is a named group of fields displayed together on a custom
+ * object's detail page. After creating a section, pass it as the `section`
+ * prop on any field that should belong to it.
+ *
+ * @example
+ * ```ts
+ * const profileSection = new CustomObjectFieldSection(memberObj, {
+ *   name: 'Profile',
+ *   sectionId: 'sec_gm_profile',
+ * });
+ *
+ * const firstName = new TextField(memberObj, {
+ *   apiName: 'first_name__c',
+ *   displayName: 'First name',
+ *   section: profileSection,
+ * });
+ * ```
+ *
+ * @see {@link CustomObjectPageLayout} — controls which sections appear on which tab.
+ */
+export class CustomObjectFieldSection {
+  private readonly _sectionId: string;
+  private readonly _name: string;
+  private readonly _model: CustomObject;
+
+  /**
+   * @param customObject - The custom object this section belongs to.
+   * @param props - Initialization properties.
+   */
+  constructor(customObject: CustomObject, props: CustomObjectFieldSectionProps) {
+    this._sectionId = props.sectionId ?? generateId('sec');
+    this._name = props.name;
+    this._model = customObject;
+    customObject._register(this);
+  }
+
+  /**
+   * Returns the stable identifier for this section (e.g. `'sec_gm_profile'`).
+   *
+   * Use this value in page layout field entries via `getSectionId()`, or pass
+   * the section instance directly to field `section` props.
+   */
+  getSectionId(): string {
+    return this._sectionId;
+  }
+
+  /**
+   * Returns the api_name of the custom object this section belongs to.
+   */
+  getModelApiName(): string {
+    return this._model.getApiName();
+  }
+
+  /**
+   * Serializes this section to the wire format consumed by the manifest install endpoint.
+   *
+   * @returns A plain object with `type: 'CUSTOM_OBJECT_FIELD_SECTION'`.
+   */
+  toDict(): Record<string, any> {
+    return {
+      type: 'CUSTOM_OBJECT_FIELD_SECTION',
+      section_id: this._sectionId,
+      model_name: this._model.getApiName(),
+      name: this._name,
+    };
+  }
+}