@rippling/rippling-sdk 0.2.0-alpha.64 → 0.2.0-alpha.68

package/examples/manifest/dental-practice-management/dental-practice-management.ts

@@ -16,6 +16,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {
   App,
+  BooleanField,
   Category,
   CustomObject,
   CustomObjectFieldSection,
@@ -103,6 +104,14 @@ const patientEmailField = new EmailField(patientObj, {
   section: patientIdentitySection,
 });
 
+const patientActiveField = new BooleanField(patientObj, {
+  apiName: 'active_patient__c',
+  displayName: 'Active patient',
+  description: 'Whether the patient is currently active in the practice',
+  required: true,
+  section: patientIdentitySection,
+});
+
 const patientAllergiesField = new LongTextField(patientObj, {
   apiName: 'allergies_and_alerts__c',
   displayName: 'Allergies & medical alerts',
@@ -216,7 +225,8 @@ const apptPatientRef = new LookupField(apptObj, {
   target: patientObj,
   relatedDataLabel: 'Appointments',
   required: true,
-  description: 'Chart to open for this visit',
+  lookup_filter_rql_condition: '(active_patient__c == True)',
+  description: 'Chart to open for this visit (active patients only)',
   section: apptPatientSection,
 });
 
@@ -378,7 +388,14 @@ new ListViewDef(patientObj, {
   viewId: 'view_dental_all_patients',
   name: 'All patients',
   description: 'Full chart list with plan counts',
-  fields: ['name', patientDobField, patientPhoneField, patientLabelField, planCountOnPatient],
+  fields: [
+    'name',
+    patientDobField,
+    patientPhoneField,
+    patientActiveField,
+    patientLabelField,
+    planCountOnPatient,
+  ],
   orderBy: 'name',
   sortOrder: 'ASC',
   isPublic: true,
@@ -449,6 +466,7 @@ new CustomObjectPageLayout(patientObj, {
               patientDobField,
               patientPhoneField,
               patientEmailField,
+              patientActiveField,
               patientLabelField,
             ],
           },
@@ -570,8 +588,8 @@ new CustomObjectPageLayout(planObj, {
 
 // ── SDUI object-list tabs ───────────────────────────────────────────────────
 const sduiObjectListDependencies = {
-  '@rippling/rippling-sdk': '^0.2.0-alpha.33',
-  '@rippling/pebble-sdui-web': '^0.3.0',
+  '@rippling/rippling-sdk': '^0.2.0-alpha.65',
+  '@rippling/pebble-sdui-web': '^0.6.3',
 };
 
 function loadFunctionCode(filename: string): string {

package/examples/manifest/gym-membership-management/gym-membership-management.ts

@@ -632,8 +632,8 @@ new CustomObjectPageLayout(enrollmentObj, {
 
 // ── SDUI object-list tabs ───────────────────────────────────────────────────
 const sduiObjectListDependencies = {
-  '@rippling/rippling-sdk': '^0.2.0-alpha.33',
-  '@rippling/pebble-sdui-web': '^0.3.0',
+  '@rippling/rippling-sdk': '^0.2.0-alpha.65',
+  '@rippling/pebble-sdui-web': '^0.6.3',
 };
 
 function loadFunctionCode(filename: string): string {

package/examples/manifest/simple-todo-app/simple-todo-app.ts

@@ -134,7 +134,7 @@ const todoListFn = new ManifestFunction(manifest, {
   name: 'renderTodos',
   description: 'SDUI ObjectListView for todo records',
   code: fs.readFileSync(path.join(__dirname, 'functions', 'todo-list.ts'), 'utf-8'),
-  dependencies: { '@rippling/rippling-sdk': '^0.2.0-alpha.33', '@rippling/pebble-sdui-web': '^0.3.0' },
+  dependencies: { '@rippling/rippling-sdk': '^0.2.0-alpha.65', '@rippling/pebble-sdui-web': '^0.6.3' },
   isAsync: false,
 });
 

package/examples/manifest/todo-app-without-object-list-view/functions/todo-page.ts

@@ -0,0 +1,487 @@
+/*
+ * Custom SDUI todo page backed by `todo__c` records.
+ *
+ * This function handles both the initial page render and follow-up UI actions:
+ * - `init` lists todos for the current `context.function.role_id` and returns
+ *   a JSON-stringified SDUI spec in `body.spec`.
+ * - `addTodo`, `toggleTodo`, and `clearCompleted` mutate Custom Object records,
+ *   then return the fresh `TodoListState` written into `/todoList` by
+ *   `responsePath`.
+ *
+ * In `triggerFunction`, server-bound action params live under `inputs` so
+ * repeated item values like `todo.$('id')` resolve before reaching
+ * `event['parameters']`. Client-side controls such as `functionId`,
+ * `responsePath`, `onSuccess`, and `onError` stay top-level.
+ *
+ * `/isMutating` is a shared loading flag: it disables every action while an API
+ * call is in flight and shows a small loading message so disabled controls have
+ * visible context.
+ */
+import { createSpec, equals, neq, or_, type SpecContext } from '@rippling/pebble-sdui-web';
+import {
+  Button,
+  Card,
+  Checkbox,
+  Field,
+  HStack,
+  PageContent,
+  Text,
+  TextInput,
+  VStack,
+  render,
+  setState,
+  triggerFunction,
+} from '@rippling/pebble-sdui-web/catalogs/custom-apps';
+import RipplingSDK, { FunctionContext, FunctionEvent, FunctionResponse } from '@rippling/rippling-sdk';
+import type { CustomObjectDataRow } from '@rippling/rippling-sdk/resources/custom-objects/records';
+
+const OBJECT_API_NAME = 'todo__c';
+
+type Todo = {
+  id: string;
+  text: string;
+  completed: boolean;
+};
+
+type TodoListState = {
+  todos: Todo[];
+  isEmpty: boolean;
+};
+
+type TodoAppState = {
+  newTodoText: string;
+  todoList: TodoListState;
+  isMutating: boolean;
+  errorMessage: string;
+};
+
+type TodoSpec = SpecContext<TodoAppState>;
+
+function createClient(context: FunctionContext): RipplingSDK {
+  return new RipplingSDK({
+    bearerToken: context.env.rippling_user_bearer_token,
+  });
+}
+
+function toTodo(record: CustomObjectDataRow): Todo {
+  return {
+    id: record.id,
+    text: record.name,
+    completed: record['completed__c'] === true,
+  };
+}
+
+async function listTodos(client: RipplingSDK, roleId: string): Promise<Todo[]> {
+  const response = await client.customObjects.records.query(OBJECT_API_NAME, {
+    limit: 100,
+    query: `created_by = "${roleId}"`, // RQL query to filter todos by the current role
+  });
+
+  return (response.results ?? []).map(toTodo);
+}
+
+function todoListState(todos: Todo[]): TodoListState {
+  return {
+    todos,
+    isEmpty: todos.length === 0,
+  };
+}
+
+function todoState(todos: Todo[]): TodoAppState {
+  return {
+    newTodoText: '',
+    todoList: todoListState(todos),
+    isMutating: false,
+    errorMessage: '',
+  };
+}
+
+function ok(body: Record<string, unknown> | unknown[] = {}): FunctionResponse {
+  return new FunctionResponse({
+    body: body as Record<string, unknown>,
+    statusCode: 200,
+    headers: {},
+    message: '',
+  });
+}
+
+function badRequest(message: string): FunctionResponse {
+  return new FunctionResponse({
+    body: { error: message },
+    statusCode: 400,
+    headers: {},
+    message,
+  });
+}
+
+function serverError(error: unknown): FunctionResponse {
+  const message = error instanceof Error ? error.message : 'Unknown error';
+
+  return new FunctionResponse({
+    body: { error: message },
+    statusCode: 500,
+    headers: {},
+    message,
+  });
+}
+
+function stringParam(params: Record<string, unknown>, key: string): string {
+  const value = params[key];
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+// A single mutation flag disables all actions and drives the visible loading text.
+function setMutationState(isMutating: boolean) {
+  return setState({
+    statePath: '/isMutating',
+    value: isMutating,
+  });
+}
+
+function buildAddTodoSection(spec: TodoSpec, functionId: string) {
+  return VStack({
+    id: 'addTodoSection',
+    props: {},
+    children: [
+      Field({
+        id: 'todoInputField',
+        props: {
+          label: 'New Todo',
+        },
+        children: [
+          TextInput({
+            id: 'todoInput',
+            props: {
+              name: 'newTodo',
+              placeholder: 'Enter a new todo item',
+              value: spec.$bindState('/newTodoText'),
+              isDisabled: spec.$state('/isMutating'),
+            },
+          }),
+        ],
+      }),
+      Button({
+        id: 'addButton',
+        props: {
+          label: 'Add Todo',
+          appearance: 'PRIMARY',
+          isFluid: true,
+          isDisabled: spec.$cond(
+            or_(equals(spec.$state('/newTodoText'), ''), equals(spec.$state('/isMutating'), true)),
+            true,
+            false,
+          ),
+        },
+        on: {
+          press: [
+            setMutationState(true),
+            triggerFunction(
+              {
+                functionId,
+                inputs: {
+                  action: 'addTodo',
+                  text: spec.$state('/newTodoText'),
+                },
+                responsePath: '/todoList',
+              } as any,
+              {
+                onSuccess: { set: { '/newTodoText': '', '/errorMessage': '', '/isMutating': false } },
+                onError: { set: { '/errorMessage': 'Could not add todo. Try again.', '/isMutating': false } },
+              },
+            ),
+          ],
+        },
+      }),
+    ],
+  });
+}
+
+function buildTodoItems(spec: TodoSpec, functionId: string) {
+  const [todoRepeat, todo] = spec.repeat('/todoList/todos', 'id');
+
+  return VStack({
+    id: 'todoItems',
+    repeat: todoRepeat,
+    props: {
+      gap: 'space200',
+    },
+    children: [
+      HStack({
+        id: 'todoItem',
+        props: {
+          gap: 'space300',
+          align: 'center',
+          padding: 'space300',
+          backgroundColor: 'colorSurfaceContainer',
+          radius: 'shapeCornerMd',
+        },
+        children: [
+          Checkbox({
+            id: 'todoCheckbox',
+            props: {
+              name: 'completed',
+              value: todo.$bind('completed'),
+              isDisabled: spec.$state('/isMutating'),
+            },
+            on: {
+              change: [
+                setMutationState(true),
+                triggerFunction(
+                  {
+                    functionId,
+                    inputs: {
+                      action: 'toggleTodo',
+                      todoId: todo.$('id'),
+                    },
+                    responsePath: '/todoList',
+                  } as any,
+                  {
+                    onSuccess: { set: { '/errorMessage': '', '/isMutating': false } },
+                    onError: {
+                      set: {
+                        '/errorMessage': 'Could not update todo. Refresh and try again.',
+                        '/isMutating': false,
+                      },
+                    },
+                  },
+                ),
+              ],
+            },
+          }),
+          Text({
+            id: 'todoText',
+            props: {
+              text: todo.$('text'),
+              decoration: spec.$cond(equals(todo.$('completed'), true), 'line-through', 'none'),
+              color: spec.$cond(equals(todo.$('completed'), true), 'colorOnSurfaceVariant', 'colorOnSurface'),
+            },
+          }),
+        ],
+      }),
+    ],
+  });
+}
+
+function buildTodoList(spec: TodoSpec, functionId: string) {
+  return VStack({
+    id: 'todoList',
+    props: {
+      gap: 'space300',
+    },
+    children: [
+      HStack({
+        id: 'todoListHeader',
+        props: {
+          align: 'center',
+          justify: 'space-between',
+          gap: 'space300',
+        },
+        children: [
+          Text({
+            id: 'todoListTitle',
+            props: {
+              text: 'Your Todos',
+              typestyle: 'typestyleTitleSmall600',
+            },
+          }),
+          Button({
+            id: 'clearCompletedButton',
+            props: {
+              label: 'Clear completed',
+              appearance: 'OUTLINE',
+              size: 'S',
+              isDisabled: spec.$cond(
+                or_(equals(spec.$state('/isMutating'), true), equals(spec.$state('/todoList/isEmpty'), true)),
+                true,
+                false,
+              ),
+            },
+            on: {
+              press: [
+                setMutationState(true),
+                triggerFunction(
+                  {
+                    functionId,
+                    inputs: {
+                      action: 'clearCompleted',
+                    },
+                    responsePath: '/todoList',
+                  } as any,
+                  {
+                    onSuccess: { set: { '/errorMessage': '', '/isMutating': false } },
+                    onError: {
+                      set: {
+                        '/errorMessage': 'Could not clear completed todos. Try again.',
+                        '/isMutating': false,
+                      },
+                    },
+                  },
+                ),
+              ],
+            },
+          }),
+        ],
+      }),
+      Text({
+        id: 'emptyTodos',
+        visible: equals(spec.$state('/todoList/isEmpty'), true),
+        props: {
+          text: 'No todos yet.',
+          color: 'colorOnSurfaceVariant',
+        },
+      }),
+      buildTodoItems(spec, functionId),
+    ],
+  });
+}
+
+function buildError(spec: TodoSpec) {
+  return Text({
+    id: 'todoError',
+    visible: neq(spec.$state('/errorMessage'), ''),
+    props: {
+      text: spec.$state('/errorMessage'),
+      color: 'colorError',
+    },
+  });
+}
+
+function buildLoading(spec: TodoSpec) {
+  return Text({
+    id: 'todoLoading',
+    // Keep disabled controls explainable while a triggerFunction call is in flight.
+    visible: equals(spec.$state('/isMutating'), true),
+    props: {
+      text: 'Updating todos...',
+      color: 'colorOnSurfaceVariant',
+    },
+  });
+}
+
+function buildTodoCard(spec: TodoSpec, functionId: string) {
+  return Card({
+    id: 'todoCard',
+    props: {},
+    children: [
+      VStack({
+        id: 'todoContent',
+        props: {
+          gap: 'space400',
+          padding: 'space400',
+        },
+        children: [
+          buildAddTodoSection(spec, functionId),
+          buildError(spec),
+          buildLoading(spec),
+          buildTodoList(spec, functionId),
+        ],
+      }),
+    ],
+  });
+}
+
+function renderSpec(state: TodoAppState, functionId: string) {
+  const spec = createSpec<TodoAppState>({ state });
+  const root = PageContent({
+    id: 'todoApp',
+    props: {
+      size: '776',
+      alignment: 'CENTER',
+    },
+    children: [buildTodoCard(spec, functionId)],
+  });
+
+  return render({ root, state });
+}
+
+async function addTodo(
+  client: RipplingSDK,
+  params: Record<string, unknown>,
+  roleId: string,
+): Promise<TodoListState> {
+  const text = stringParam(params, 'text');
+
+  if (!text) {
+    throw new Error('Todo text is required');
+  }
+
+  await client.customObjects.records.create(OBJECT_API_NAME, {
+    name: text,
+    completed__c: false,
+  });
+
+  return todoListState(await listTodos(client, roleId));
+}
+
+async function toggleTodo(
+  client: RipplingSDK,
+  params: Record<string, unknown>,
+  roleId: string,
+): Promise<TodoListState> {
+  const todoId = stringParam(params, 'todoId');
+
+  if (!todoId) {
+    throw new Error('todoId must be a todo record ID');
+  }
+
+  const todo = toTodo(await client.customObjects.records.retrieve(OBJECT_API_NAME, todoId));
+  await client.customObjects.records.update(OBJECT_API_NAME, todoId, {
+    completed__c: !todo.completed,
+  });
+
+  return todoListState(await listTodos(client, roleId));
+}
+
+async function clearCompleted(client: RipplingSDK, roleId: string): Promise<TodoListState> {
+  const todos = await listTodos(client, roleId);
+  const completedTodoIds = todos.filter((todo) => todo.completed).map((todo) => todo.id);
+
+  if (completedTodoIds.length === 0) {
+    return todoListState(todos);
+  }
+
+  await client.customObjects.records.bulkDelete(OBJECT_API_NAME, {
+    all_or_nothing: false,
+    rows_to_delete: completedTodoIds,
+  });
+
+  return todoListState(await listTodos(client, roleId));
+}
+
+export async function onRipplingEvent(
+  event: FunctionEvent,
+  context: FunctionContext,
+): Promise<FunctionResponse> {
+  const params = (event['parameters'] ?? {}) as Record<string, unknown>;
+  const action = typeof params['action'] === 'string' ? params['action'] : 'init';
+  const roleId = context.function.role_id;
+  if (!roleId) {
+    return badRequest('Role ID is required');
+  }
+
+  try {
+    const client = createClient(context);
+
+    if (action === 'init') {
+      const functionId = context.function.function_id;
+      const todos = await listTodos(client, roleId);
+      return ok({ spec: JSON.stringify(renderSpec(todoState(todos), functionId)) });
+    }
+
+    if (action === 'addTodo') {
+      return ok(await addTodo(client, params, roleId));
+    }
+
+    if (action === 'toggleTodo') {
+      return ok(await toggleTodo(client, params, roleId));
+    }
+
+    if (action === 'clearCompleted') {
+      return ok(await clearCompleted(client, roleId));
+    }
+
+    return badRequest(`Unknown action: ${action}`);
+  } catch (error) {
+    return serverError(error);
+  }
+}

package/examples/manifest/todo-app-without-object-list-view/todo-app-without-object-list-view.ts

@@ -0,0 +1,111 @@
+/*
+ * Todo App Without ObjectListView — custom SDUI backed by Custom Object records.
+ *
+ * This example intentionally does not render ObjectListView. The SDUI page reads
+ * and writes `todo__c` records from the function, then renders its own
+ * todo list with TextInput, Button, Checkbox, and layout components.
+ *
+ *   todo__c   <- name, completed__c
+ *
+ * Run:
+ *   yarn tsn examples/manifest/todo-app-without-object-list-view/todo-app-without-object-list-view.ts \
+ *       > examples/manifest/todo-app-without-object-list-view/manifest.json
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  App,
+  BooleanField,
+  Category,
+  CustomObject,
+  CustomObjectFieldSection,
+  CustomObjectPageLayout,
+  ManifestBuilder,
+  ManifestFunction,
+  SduiPage,
+} from '@rippling/rippling-sdk/lib/manifest';
+
+const manifest = new ManifestBuilder({
+  key: 'todo_app_without_object_list_view',
+  name: 'Todo App Without ObjectListView',
+  description: 'A todo app that renders custom SDUI and persists changes to Custom Object records',
+});
+
+const todoCategory = new Category(manifest, {
+  apiName: 'custom_todo_app__c',
+  name: 'Todo App',
+  description: 'Custom todo app records',
+});
+
+const todoObj = new CustomObject(manifest, {
+  apiName: 'todo__c',
+  name: 'Todo',
+  pluralLabel: 'Todos',
+  category: todoCategory,
+  description: 'A todo item rendered by a custom SDUI page',
+  icon: { emoji: '✅' },
+});
+
+const detailsSection = new CustomObjectFieldSection(todoObj, {
+  name: 'Details',
+  sectionId: 'sec_custom_todo_details',
+});
+
+const completedField = new BooleanField(todoObj, {
+  apiName: 'completed__c',
+  displayName: 'Completed',
+  description: 'Whether the todo item is complete',
+  section: detailsSection,
+});
+
+new CustomObjectPageLayout(todoObj, {
+  apiName: 'default',
+  name: 'Todo',
+  layoutId: 'layout_custom_todo',
+  tabEdits: {
+    newTabs: [
+      {
+        key: 'todo',
+        name: 'Todo',
+        type: 'tab_with_sections',
+        sections: [
+          {
+            name: 'Details',
+            type: 'fields_section',
+            section: detailsSection,
+            fields: [{ field: 'name', editable: true }, completedField],
+          },
+        ],
+      },
+    ],
+    systemTabEdits: {},
+    tabsOrder: ['todo'],
+  },
+  visibilityConditions: {},
+});
+
+const todoPageFn = new ManifestFunction(manifest, {
+  apiName: 'custom_todo_page_fn',
+  name: 'renderTodoPage',
+  description: 'Custom SDUI todo page backed by Custom Object record APIs',
+  code: fs.readFileSync(path.join(__dirname, 'functions', 'todo-page.ts'), 'utf-8'),
+  dependencies: { '@rippling/rippling-sdk': '^0.2.0-alpha.65', '@rippling/pebble-sdui-web': '^0.6.3' },
+  isAsync: false,
+});
+
+const todoPage = new SduiPage(manifest, {
+  sduiPageId: 'custom_todo_page',
+  name: 'Todos',
+  function: todoPageFn,
+});
+
+new App(manifest, {
+  apiName: 'todo_app_without_object_list_view',
+  name: 'Todo App Without ObjectListView',
+  description: 'Todo app with a fully custom SDUI page and Custom Object persistence',
+  appType: 'custom',
+  pages: [todoPage],
+});
+
+console.log(manifest.preview());

package/functions.d.mts

@@ -1,15 +1,15 @@
-export interface FunctionResponseOptions {
-    body?: Record<string, any>;
+export interface FunctionResponseOptions<T = Record<string, any>> {
+    body?: T;
     statusCode?: number;
     headers?: Record<string, string>;
     message?: string;
 }
-export declare class FunctionResponse {
-    body: Record<string, any>;
+export declare class FunctionResponse<T = Record<string, any>> {
+    body: T;
     statusCode: number;
     headers: Record<string, string>;
     message: string;
-    constructor({ body, statusCode, headers, message }?: FunctionResponseOptions);
+    constructor({ body, statusCode, headers, message, }?: FunctionResponseOptions<T>);
 }
 export type FunctionEvent = Record<string, any>;
 export type DurableDuration = number | string;