@rippling/rippling-sdk 0.2.0-alpha.81 → 0.2.0-alpha.83

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

@@ -29,23 +29,31 @@ import {
   TextInput,
   VStack,
   render,
-  setState,
-  triggerFunction,
 } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
-import RipplingSDK, {
-  FunctionContext,
-  FunctionResponse,
-  SduiPageFunctionEvent,
-} from '@rippling/rippling-sdk';
-import type { CustomObjectDataRow } from '@rippling/rippling-sdk/resources/custom-objects/records';
-
-const OBJECT_API_NAME = 'todo__c';
+import { FunctionContext, FunctionResponse, SduiPageFunctionEvent } from '@rippling/rippling-sdk';
+import {
+  createCustomObjectFunctionRuntime,
+  createRqlHelpers,
+  type RecordShape,
+  type TypedCustomObjectRecordManager,
+} from '@rippling/rippling-sdk/core/platform/custom-objects';
+import {
+  createTypedSduiMutationTrigger,
+  defineTypedSduiPageHandlerFor,
+  defineTypedSduiStateAssignments,
+  resolveTypedSduiStatePath,
+  type TypedSduiPageActionParams,
+  type TypedSduiPageOutput,
+} from '@rippling/rippling-sdk/core/platform/manifest/custom-objects';
+import { todoDefinition } from '../schema';
+
+const todoRql = createRqlHelpers(todoDefinition);
 type TodoPageAction = 'init' | 'addTodo' | 'toggleTodo' | 'clearCompleted';
-type TodoPageFunctionParameters = {
-  action: TodoPageAction;
-  text?: string;
-  todoId?: string;
-};
+type TodoPageFunctionParameters =
+  | { action: 'init' }
+  | { action: 'addTodo'; text?: string }
+  | { action: 'toggleTodo'; todoId?: string }
+  | { action: 'clearCompleted' };
 
 type Todo = {
   id: string;
@@ -53,6 +61,8 @@ type Todo = {
   completed: boolean;
 };
 
+type TodoRecord = RecordShape<typeof todoDefinition>;
+
 type TodoListState = {
   todos: Todo[];
   isEmpty: boolean;
@@ -67,27 +77,43 @@ type TodoAppState = {
 
 type TodoSpec = SpecContext<TodoAppState>;
 
-function createClient(context: FunctionContext): RipplingSDK {
-  return new RipplingSDK({
-    bearerToken: context.env.rippling_user_bearer_token,
-  });
+const todoStatePath = resolveTypedSduiStatePath<TodoAppState>();
+const todoStatePaths = {
+  newTodoText: todoStatePath('/newTodoText'),
+  todoList: todoStatePath('/todoList'),
+  todoListTodos: todoStatePath('/todoList/todos'),
+  todoListIsEmpty: todoStatePath('/todoList/isEmpty'),
+  isMutating: todoStatePath('/isMutating'),
+  errorMessage: todoStatePath('/errorMessage'),
+} as const;
+
+export type Input = SduiPageFunctionEvent<TodoPageFunctionParameters>;
+
+export type Output = TypedSduiPageOutput<TodoListState>;
+
+function createTodoManager(context: FunctionContext): TypedCustomObjectRecordManager<typeof todoDefinition> {
+  const runtime = createCustomObjectFunctionRuntime(context);
+  return runtime.for(todoDefinition);
 }
 
-function toTodo(record: CustomObjectDataRow): Todo {
+function toTodo(record: TodoRecord): Todo {
   return {
     id: record.id,
     text: record.name,
-    completed: record['completed__c'] === true,
+    completed: record.completed === true,
   };
 }
 
-async function listTodos(client: RipplingSDK, roleId: string): Promise<Todo[]> {
-  const response = await client.customObjects.records.query(OBJECT_API_NAME, {
+async function listTodos(
+  manager: TypedCustomObjectRecordManager<typeof todoDefinition>,
+  roleId: string,
+): Promise<Todo[]> {
+  const response = await manager.query({
     limit: 100,
-    query: `created_by = "${roleId}"`, // RQL query to filter todos by the current role
+    query: todoRql.render(todoRql.eq(todoRql.fields.created_by, { id: roleId, apiName: 'Employee' })),
   });
 
-  return (response.results ?? []).map(toTodo);
+  return response.results.map(toTodo);
 }
 
 function todoListState(todos: Todo[]): TodoListState {
@@ -106,45 +132,28 @@ function todoState(todos: Todo[]): TodoAppState {
   };
 }
 
-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 todoTextParam(params: TypedSduiPageActionParams<TodoPageFunctionParameters, 'addTodo'>): string {
+  return typeof params.text === 'string' ? params.text.trim() : '';
 }
 
-function stringParam(params: TodoPageFunctionParameters, key: 'text' | 'todoId'): string {
-  const value = params[key];
-  return typeof value === 'string' ? value.trim() : '';
+function todoIdParam(params: TypedSduiPageActionParams<TodoPageFunctionParameters, 'toggleTodo'>): string {
+  return typeof params.todoId === 'string' ? params.todoId.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 mutationActions<TInputs extends { action: Exclude<TodoPageAction, 'init'> }>(
+  functionId: string,
+  inputs: TInputs,
+  errorMessage: string,
+  onSuccessState?: ReturnType<typeof defineTypedSduiStateAssignments<TodoAppState>>,
+) {
+  return createTypedSduiMutationTrigger<TodoAppState, TodoListState, typeof inputs>({
+    functionId,
+    inputs,
+    responsePath: todoStatePaths.todoList,
+    errorMessage,
+    mutationStatePath: todoStatePaths.isMutating,
+    errorStatePath: todoStatePaths.errorMessage,
+    ...(onSuccessState != null ? { onSuccessState } : {}),
   });
 }
 
@@ -164,8 +173,8 @@ function buildAddTodoSection(spec: TodoSpec, functionId: string) {
             props: {
               name: 'newTodo',
               placeholder: 'Enter a new todo item',
-              value: spec.$bindState('/newTodoText'),
-              isDisabled: spec.$state('/isMutating'),
+              value: spec.$bindState(todoStatePaths.newTodoText),
+              isDisabled: spec.$state(todoStatePaths.isMutating),
             },
           }),
         ],
@@ -177,29 +186,26 @@ function buildAddTodoSection(spec: TodoSpec, functionId: string) {
           appearance: 'PRIMARY',
           isFluid: true,
           isDisabled: spec.$cond(
-            or_(equals(spec.$state('/newTodoText'), ''), equals(spec.$state('/isMutating'), true)),
+            or_(
+              equals(spec.$state(todoStatePaths.newTodoText), ''),
+              equals(spec.$state(todoStatePaths.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 } },
-              },
-            ),
-          ],
+          press: mutationActions(
+            functionId,
+            {
+              action: 'addTodo',
+              text: spec.$state(todoStatePaths.newTodoText),
+            },
+            'Could not add todo. Try again.',
+            defineTypedSduiStateAssignments<TodoAppState>({
+              [todoStatePaths.newTodoText]: '',
+            }),
+          ),
         },
       }),
     ],
@@ -207,7 +213,7 @@ function buildAddTodoSection(spec: TodoSpec, functionId: string) {
 }
 
 function buildTodoItems(spec: TodoSpec, functionId: string) {
-  const [todoRepeat, todo] = spec.repeat('/todoList/todos', 'id');
+  const [todoRepeat, todo] = spec.repeat(todoStatePaths.todoListTodos, 'id');
 
   return VStack({
     id: 'todoItems',
@@ -231,31 +237,17 @@ function buildTodoItems(spec: TodoSpec, functionId: string) {
             props: {
               name: 'completed',
               value: todo.$bind('completed'),
-              isDisabled: spec.$state('/isMutating'),
+              isDisabled: spec.$state(todoStatePaths.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,
-                      },
-                    },
-                  },
-                ),
-              ],
+              change: mutationActions(
+                functionId,
+                {
+                  action: 'toggleTodo',
+                  todoId: todo.$('id'),
+                },
+                'Could not update todo. Refresh and try again.',
+              ),
             },
           }),
           Text({
@@ -301,40 +293,29 @@ function buildTodoList(spec: TodoSpec, functionId: string) {
               appearance: 'OUTLINE',
               size: 'S',
               isDisabled: spec.$cond(
-                or_(equals(spec.$state('/isMutating'), true), equals(spec.$state('/todoList/isEmpty'), true)),
+                or_(
+                  equals(spec.$state(todoStatePaths.isMutating), true),
+                  equals(spec.$state(todoStatePaths.todoListIsEmpty), 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,
-                      },
-                    },
-                  },
-                ),
-              ],
+              press: mutationActions(
+                functionId,
+                {
+                  action: 'clearCompleted',
+                },
+                'Could not clear completed todos. Try again.',
+              ),
             },
           }),
         ],
       }),
       Text({
         id: 'emptyTodos',
-        visible: equals(spec.$state('/todoList/isEmpty'), true),
+        visible: equals(spec.$state(todoStatePaths.todoListIsEmpty), true),
         props: {
           text: 'No todos yet.',
           color: 'colorOnSurfaceVariant',
@@ -348,9 +329,9 @@ function buildTodoList(spec: TodoSpec, functionId: string) {
 function buildError(spec: TodoSpec) {
   return Text({
     id: 'todoError',
-    visible: neq(spec.$state('/errorMessage'), ''),
+    visible: neq(spec.$state(todoStatePaths.errorMessage), ''),
     props: {
-      text: spec.$state('/errorMessage'),
+      text: spec.$state(todoStatePaths.errorMessage),
       color: 'colorError',
     },
   });
@@ -360,7 +341,7 @@ 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),
+    visible: equals(spec.$state(todoStatePaths.isMutating), true),
     props: {
       text: 'Updating todos...',
       color: 'colorOnSurfaceVariant',
@@ -405,93 +386,85 @@ function renderSpec(state: TodoAppState, functionId: string) {
 }
 
 async function addTodo(
-  client: RipplingSDK,
-  params: TodoPageFunctionParameters,
+  manager: TypedCustomObjectRecordManager<typeof todoDefinition>,
+  params: TypedSduiPageActionParams<TodoPageFunctionParameters, 'addTodo'>,
   roleId: string,
 ): Promise<TodoListState> {
-  const text = stringParam(params, 'text');
+  const text = todoTextParam(params);
 
   if (!text) {
     throw new Error('Todo text is required');
   }
 
-  await client.customObjects.records.create(OBJECT_API_NAME, {
+  await manager.create({
     name: text,
-    completed__c: false,
+    completed: false,
   });
 
-  return todoListState(await listTodos(client, roleId));
+  return todoListState(await listTodos(manager, roleId));
 }
 
 async function toggleTodo(
-  client: RipplingSDK,
-  params: TodoPageFunctionParameters,
+  manager: TypedCustomObjectRecordManager<typeof todoDefinition>,
+  params: TypedSduiPageActionParams<TodoPageFunctionParameters, 'toggleTodo'>,
   roleId: string,
 ): Promise<TodoListState> {
-  const todoId = stringParam(params, 'todoId');
+  const todoId = todoIdParam(params);
 
   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,
+  const todo = toTodo(await manager.get(todoId));
+  await manager.update(todoId, {
+    completed: !todo.completed,
   });
 
-  return todoListState(await listTodos(client, roleId));
+  return todoListState(await listTodos(manager, roleId));
 }
 
-async function clearCompleted(client: RipplingSDK, roleId: string): Promise<TodoListState> {
-  const todos = await listTodos(client, roleId);
+async function clearCompleted(
+  manager: TypedCustomObjectRecordManager<typeof todoDefinition>,
+  roleId: string,
+): Promise<TodoListState> {
+  const todos = await listTodos(manager, 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,
+  await manager.deleteMany(completedTodoIds, {
+    allOrNothing: false,
   });
 
-  return todoListState(await listTodos(client, roleId));
+  return todoListState(await listTodos(manager, roleId));
 }
 
+const defineTodoPageHandler = defineTypedSduiPageHandlerFor<TodoPageFunctionParameters, TodoListState>();
+
+const todoPageHandler = defineTodoPageHandler({
+  requireRoleId: true,
+  createRuntime(context) {
+    return {
+      manager: createTodoManager(context),
+      functionId: context.function.function_id,
+    };
+  },
+  async init({ runtime, roleId }) {
+    const todos = await listTodos(runtime.manager, roleId);
+    return renderSpec(todoState(todos), runtime.functionId);
+  },
+  actions: {
+    addTodo: async ({ runtime, params, roleId }) => addTodo(runtime.manager, params, roleId),
+    toggleTodo: async ({ runtime, params, roleId }) => toggleTodo(runtime.manager, params, roleId),
+    clearCompleted: async ({ runtime, roleId }) => clearCompleted(runtime.manager, roleId),
+  },
+});
+
 export async function onRipplingEvent(
-  event: SduiPageFunctionEvent<TodoPageFunctionParameters>,
+  event: Input,
   context: FunctionContext,
-): Promise<FunctionResponse> {
-  const params = event.parameters;
-  const action = params.action;
-  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);
-  }
+): Promise<FunctionResponse<Output>> {
+  return todoPageHandler(event, context);
 }

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

@@ -0,0 +1,28 @@
+/**
+ * Typed custom-object schema for the custom SDUI todo example.
+ */
+
+import { boolean, defineCustomObject, section } from '@rippling/rippling-sdk/core/platform/custom-objects';
+
+/** Logical category shared by the custom SDUI todo example. */
+export const CUSTOM_TODO_CATEGORY = 'custom_todo_app';
+
+/** Typed schema used by the custom SDUI todo manifest and function code. */
+export const todoDefinition = defineCustomObject({
+  name: 'todo',
+  displayName: 'Todo',
+  pluralLabel: 'Todos',
+  category: CUSTOM_TODO_CATEGORY,
+  description: 'A todo item rendered by a custom SDUI page.',
+  icon: { emoji: '✅' },
+  sections: {
+    details: section('Details', { sectionId: 'sec_custom_todo_details' }),
+  },
+  fields: {
+    completed: boolean({
+      displayName: 'Completed',
+      description: 'Whether the todo item is complete',
+      section: 'details',
+    }),
+  },
+});

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

@@ -1,9 +1,9 @@
 /*
- * Todo App Without ObjectListView — custom SDUI backed by Custom Object records.
+ * Todo App Without ObjectListView — custom SDUI backed by typed 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.
+ * 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
  *
@@ -12,54 +12,34 @@
  *       > examples/manifest/todo-app-without-object-list-view/manifest.json
  */
 
-import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { toCustomCategoryApiName } from '@rippling/rippling-sdk/core/platform/custom-objects';
 import {
-  App,
-  BooleanField,
-  Category,
-  CustomObject,
-  CustomObjectFieldSection,
-  CustomObjectPageLayout,
-  ManifestBuilder,
-  ManifestFunction,
-  SduiPage,
-} from '@rippling/rippling-sdk/lib/manifest';
+  defineSduiPageFromFunctionFile,
+  defineTypedPageLayout,
+  registerManifestCustomObject,
+} from '@rippling/rippling-sdk/core/platform/manifest/custom-objects';
+import { App, Category, ManifestBuilder } from '@rippling/rippling-sdk/lib/manifest';
+import { CUSTOM_TODO_CATEGORY, todoDefinition } from './schema';
 
 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',
+  description: 'A todo app that renders custom SDUI and persists changes to typed custom-object records',
 });
 
 const todoCategory = new Category(manifest, {
-  apiName: 'custom_todo_app__c',
+  apiName: toCustomCategoryApiName(CUSTOM_TODO_CATEGORY),
   name: 'Todo App',
   description: 'Custom todo app records',
 });
 
-const todoObj = new CustomObject(manifest, {
-  apiName: 'todo__c',
-  name: 'Todo',
-  pluralLabel: 'Todos',
+const todo = registerManifestCustomObject(manifest, {
+  definition: todoDefinition,
   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, {
+defineTypedPageLayout(todo, {
   apiName: 'default',
   name: 'Todo',
   layoutId: 'layout_custom_todo',
@@ -73,8 +53,8 @@ new CustomObjectPageLayout(todoObj, {
           {
             name: 'Details',
             type: 'fields_section',
-            section: detailsSection,
-            fields: [{ field: 'name', editable: true }, completedField],
+            section: todo.sections.details,
+            fields: [{ field: 'name', editable: true }, 'completed'],
           },
         ],
       },
@@ -85,25 +65,22 @@ new CustomObjectPageLayout(todoObj, {
   visibilityConditions: {},
 });
 
-const todoPageFn = new ManifestFunction(manifest, {
+const { page: todoPage } = defineSduiPageFromFunctionFile(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' },
+  description: 'Custom SDUI todo page backed by typed custom-object record APIs',
+  codeDirectory: path.join(__dirname, 'functions'),
+  codeFilename: 'todo-page.ts',
+  dependencies: { '@rippling/rippling-sdk': '^0.2.0-alpha.65', '@rippling/pebble-sdui-web': '^0.9.2' },
   isAsync: false,
-});
-
-const todoPage = new SduiPage(manifest, {
-  sduiPageId: 'custom_todo_page',
-  name: 'Todos',
-  function: todoPageFn,
+  pageId: 'custom_todo_page',
+  pageName: 'Todos',
 });
 
 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',
+  description: 'Todo app with a fully custom SDUI page and typed custom-object persistence',
   appType: 'custom',
   pages: [todoPage],
 });

package/functions.d.mts

@@ -100,6 +100,7 @@ export interface FunctionContext {
     function: {
         company_id: string;
         function_id: string;
+        function_api_name: string;
         function_version_id: string;
         run_id: string;
         role_id?: string;