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

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

@@ -10,7 +10,7 @@
  *
  * 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 `functionApiName`,
+ * `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
@@ -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,49 +132,32 @@ 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 } : {}),
   });
 }
 
-function buildAddTodoSection(spec: TodoSpec, functionApiName: string) {
+function buildAddTodoSection(spec: TodoSpec, functionId: string) {
   return VStack({
     id: 'addTodoSection',
     props: {},
@@ -164,8 +173,8 @@ function buildAddTodoSection(spec: TodoSpec, functionApiName: 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,37 +186,34 @@ function buildAddTodoSection(spec: TodoSpec, functionApiName: 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(
-              {
-                functionApiName,
-                inputs: {
-                  action: 'addTodo',
-                  text: spec.$state('/newTodoText'),
-                },
-                responsePath: '/todoList',
-              },
-              {
-                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]: '',
+            }),
+          ),
         },
       }),
     ],
   });
 }
 
-function buildTodoItems(spec: TodoSpec, functionApiName: string) {
-  const [todoRepeat, todo] = spec.repeat('/todoList/todos', 'id');
+function buildTodoItems(spec: TodoSpec, functionId: string) {
+  const [todoRepeat, todo] = spec.repeat(todoStatePaths.todoListTodos, 'id');
 
   return VStack({
     id: 'todoItems',
@@ -231,31 +237,17 @@ function buildTodoItems(spec: TodoSpec, functionApiName: string) {
             props: {
               name: 'completed',
               value: todo.$bind('completed'),
-              isDisabled: spec.$state('/isMutating'),
+              isDisabled: spec.$state(todoStatePaths.isMutating),
             },
             on: {
-              change: [
-                setMutationState(true),
-                triggerFunction(
-                  {
-                    functionApiName,
-                    inputs: {
-                      action: 'toggleTodo',
-                      todoId: todo.$('id'),
-                    },
-                    responsePath: '/todoList',
-                  },
-                  {
-                    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({
@@ -272,7 +264,7 @@ function buildTodoItems(spec: TodoSpec, functionApiName: string) {
   });
 }
 
-function buildTodoList(spec: TodoSpec, functionApiName: string) {
+function buildTodoList(spec: TodoSpec, functionId: string) {
   return VStack({
     id: 'todoList',
     props: {
@@ -301,46 +293,35 @@ function buildTodoList(spec: TodoSpec, functionApiName: 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(
-                  {
-                    functionApiName,
-                    inputs: {
-                      action: 'clearCompleted',
-                    },
-                    responsePath: '/todoList',
-                  },
-                  {
-                    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',
         },
       }),
-      buildTodoItems(spec, functionApiName),
+      buildTodoItems(spec, functionId),
     ],
   });
 }
@@ -348,9 +329,9 @@ function buildTodoList(spec: TodoSpec, functionApiName: 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',
@@ -368,7 +349,7 @@ function buildLoading(spec: TodoSpec) {
   });
 }
 
-function buildTodoCard(spec: TodoSpec, functionApiName: string) {
+function buildTodoCard(spec: TodoSpec, functionId: string) {
   return Card({
     id: 'todoCard',
     props: {},
@@ -380,17 +361,17 @@ function buildTodoCard(spec: TodoSpec, functionApiName: string) {
           padding: 'space400',
         },
         children: [
-          buildAddTodoSection(spec, functionApiName),
+          buildAddTodoSection(spec, functionId),
           buildError(spec),
           buildLoading(spec),
-          buildTodoList(spec, functionApiName),
+          buildTodoList(spec, functionId),
         ],
       }),
     ],
   });
 }
 
-function renderSpec(state: TodoAppState, functionApiName: string) {
+function renderSpec(state: TodoAppState, functionId: string) {
   const spec = createSpec<TodoAppState>({ state });
   const root = PageContent({
     id: 'todoApp',
@@ -398,100 +379,92 @@ function renderSpec(state: TodoAppState, functionApiName: string) {
       size: '776',
       alignment: 'CENTER',
     },
-    children: [buildTodoCard(spec, functionApiName)],
+    children: [buildTodoCard(spec, functionId)],
   });
 
   return render({ root, state });
 }
 
 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 functionApiName = context.function.function_api_name;
-      const todos = await listTodos(client, roleId);
-      return ok({ spec: JSON.stringify(renderSpec(todoState(todos), functionApiName)) });
-    }
-
-    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',
+    }),
+  },
+});