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

package/src/core/platform/manifest/custom-objects/sdui-page.ts

@@ -0,0 +1,515 @@
+import { buildAction, type ActionBinding, type ActionOptions } from '@rippling/pebble-sdui-web';
+import { setState } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
+import {
+  FunctionResponse,
+  type FunctionContext,
+  type FunctionResponseOptions,
+  type SduiPageFunctionEvent,
+} from '../../../../functions';
+
+type TypedSduiStatePathPrefix<TPrefix extends string, TKey extends string> = `${TPrefix}/${TKey}`;
+type TypedSduiPathKeys<TValue> = Extract<keyof TValue, string>;
+
+type TypedSduiStatePathInner<TValue, TPrefix extends string> = {
+  readonly [TKey in TypedSduiPathKeys<TValue>]: TValue[TKey] extends readonly unknown[] ?
+    TypedSduiStatePathPrefix<TPrefix, TKey>
+  : TValue[TKey] extends Record<string, unknown> ?
+    | TypedSduiStatePathPrefix<TPrefix, TKey>
+    | TypedSduiStatePathInner<TValue[TKey], TypedSduiStatePathPrefix<TPrefix, TKey>>
+  : TypedSduiStatePathPrefix<TPrefix, TKey>;
+}[TypedSduiPathKeys<TValue>];
+
+type TypedSduiStatePathValueInner<TValue, TSegments extends string> = TSegments extends (
+  `${infer THead}/${infer TRest}`
+) ?
+  THead extends TypedSduiPathKeys<TValue> ?
+    TypedSduiStatePathValueInner<TValue[THead], TRest>
+  : never
+: TSegments extends TypedSduiPathKeys<TValue> ? TValue[TSegments]
+: never;
+
+/** JSON-pointer-like state path derived from one SDUI page-state shape. */
+export type TypedSduiStatePath<TState> = TypedSduiStatePathInner<TState, ''>;
+
+/** Value type stored at one typed SDUI page-state path. */
+export type TypedSduiStatePathValue<TState, TPath extends TypedSduiStatePath<TState>> = TPath extends (
+  `/${infer TSegments}`
+) ?
+  TypedSduiStatePathValueInner<TState, TSegments>
+: never;
+
+/** Typed SDUI page-state paths whose values accept `TValue`. */
+export type TypedSduiStatePathForValue<TState, TValue> = {
+  readonly [TPath in TypedSduiStatePath<TState>]: TValue extends TypedSduiStatePathValue<TState, TPath> ?
+    TPath
+  : never;
+}[TypedSduiStatePath<TState>];
+
+/** State assignments applied by common SDUI helper actions. */
+export type TypedSduiStateAssignments<TState> = Partial<{
+  readonly [TPath in TypedSduiStatePath<TState>]: TypedSduiStatePathValue<TState, TPath>;
+}>;
+
+/** Returns a typed SDUI page-state path resolver that preserves literal path inference. */
+export function resolveTypedSduiStatePath<TState>() {
+  return <TPath extends TypedSduiStatePath<TState>>(path: TPath): TPath => path;
+}
+
+/** Returns one typed SDUI page-state assignment map as-is while preserving compile-time validation. */
+export function defineTypedSduiStateAssignments<TState>(
+  assignments: TypedSduiStateAssignments<TState>,
+): TypedSduiStateAssignments<TState> {
+  return assignments;
+}
+
+/** Standard output body returned when a function renders one SDUI page spec. */
+export interface TypedSduiPageSpecOutput {
+  /** JSON-serialized SDUI spec payload returned to the platform. */
+  readonly spec: string;
+}
+
+/** Standard error output body for SDUI page functions. */
+export interface TypedSduiPageErrorOutput {
+  /** Human-readable error message surfaced back to the caller. */
+  readonly error: string;
+}
+
+/**
+ * Common output union for stateful SDUI page functions.
+ *
+ * @typeParam TStateUpdate - State payload returned for follow-up actions such as
+ * partial updates written into a `responsePath`.
+ */
+export type TypedSduiPageOutput<TStateUpdate> =
+  | TypedSduiPageSpecOutput
+  | TStateUpdate
+  | TypedSduiPageErrorOutput;
+
+/**
+ * Serializes one rendered SDUI spec into the standard function output shape.
+ *
+ * @param spec - Rendered SDUI spec object that should be JSON-serialized.
+ * @returns Standard SDUI spec output payload.
+ */
+export function createTypedSduiPageSpecOutput<TSpec extends TypedSduiPageSpec>(
+  spec: TSpec,
+): TypedSduiPageSpecOutput {
+  return { spec: JSON.stringify(spec) };
+}
+
+/**
+ * Builds one successful SDUI page-function response.
+ *
+ * @param body - Response body to return to the platform.
+ * @param options - Optional response metadata such as status code, headers, or message.
+ * @returns Typed function response.
+ * @typeParam TBody - Body shape returned by the function.
+ */
+export function createTypedSduiPageResponse<TBody>(
+  body: TBody,
+  options: Omit<FunctionResponseOptions<TBody>, 'body'> = {},
+): FunctionResponse<TBody> {
+  return new FunctionResponse<TBody>({
+    body,
+    statusCode: options.statusCode ?? 200,
+    headers: options.headers ?? {},
+    message: options.message ?? '',
+  });
+}
+
+/**
+ * Builds the standard SDUI page-function response for one rendered page spec.
+ *
+ * @param spec - Rendered SDUI spec object that should be JSON-serialized.
+ * @returns Typed function response containing `body.spec`.
+ * @typeParam TOutput - Output union that includes the standard spec payload.
+ */
+export function createTypedSduiPageSpecResponse<
+  TOutput = TypedSduiPageSpecOutput,
+  TSpec extends TypedSduiPageSpec = TypedSduiPageSpec,
+>(spec: TSpec): FunctionResponse<TOutput> {
+  return createTypedSduiPageResponse(createTypedSduiPageSpecOutput(spec) as TOutput);
+}
+
+/**
+ * Builds a 400 SDUI page-function error response.
+ *
+ * @param message - Human-readable error message.
+ * @returns Typed function response containing the standard error payload.
+ * @typeParam TOutput - Output union that includes the standard error payload.
+ */
+export function createTypedSduiPageBadRequestResponse<TOutput = TypedSduiPageErrorOutput>(
+  message: string,
+): FunctionResponse<TOutput> {
+  return createTypedSduiPageResponse({ error: message } as TOutput, {
+    statusCode: 400,
+    message,
+  });
+}
+
+/**
+ * Builds a 500 SDUI page-function error response from one thrown value.
+ *
+ * @param error - Unknown thrown value that should be normalized to a message.
+ * @returns Typed function response containing the standard error payload.
+ * @typeParam TOutput - Output union that includes the standard error payload.
+ */
+export function createTypedSduiPageServerErrorResponse<TOutput = TypedSduiPageErrorOutput>(
+  error: unknown,
+): FunctionResponse<TOutput> {
+  const message = error instanceof Error ? error.message : 'Unknown error';
+  return createTypedSduiPageResponse({ error: message } as TOutput, {
+    statusCode: 500,
+    message,
+  });
+}
+
+type TypedSduiPageEvent<TParameters extends { action: string }> = Omit<
+  SduiPageFunctionEvent,
+  'parameters'
+> & {
+  readonly parameters: TParameters;
+};
+
+export type TypedSduiPageActionName<TParameters extends { action: string }> = TParameters['action'];
+
+export type TypedSduiPageActionParams<
+  TParameters extends { action: string },
+  TAction extends TypedSduiPageActionName<TParameters>,
+> = Extract<TParameters, { action: TAction }>;
+
+type TypedSduiPageRoleId<TRequireRoleId extends boolean | undefined> =
+  TRequireRoleId extends true ? string : string | undefined;
+
+type TypedSduiPageSpec = object;
+
+type DefaultInitAction<TParameters extends { action: string }> =
+  Extract<TypedSduiPageActionName<TParameters>, 'init'> extends never ? TypedSduiPageActionName<TParameters>
+  : Extract<TypedSduiPageActionName<TParameters>, 'init'>;
+
+type TypedSduiNonInitActionName<
+  TParameters extends { action: string },
+  TInitAction extends TypedSduiPageActionName<TParameters>,
+> = Exclude<TypedSduiPageActionName<TParameters>, TInitAction>;
+
+type TypedSduiActionHandlerMap<
+  TParameters extends { action: string },
+  TRuntime,
+  TStateUpdate,
+  TInitAction extends TypedSduiPageActionName<TParameters>,
+  TRequireRoleId extends boolean | undefined,
+> = {
+  readonly [TAction in TypedSduiNonInitActionName<TParameters, TInitAction>]: (
+    args: TypedSduiPageHandlerArgs<TParameters, TRuntime, TAction, TRequireRoleId>,
+  ) => TStateUpdate | Promise<TStateUpdate>;
+};
+
+/** Shared arguments passed to typed SDUI page handler callbacks. */
+export interface TypedSduiPageHandlerArgs<
+  TParameters extends { action: string },
+  TRuntime,
+  TAction extends TypedSduiPageActionName<TParameters>,
+  TRequireRoleId extends boolean | undefined = false,
+> {
+  /** Raw SDUI page event supplied by the platform. */
+  readonly event: TypedSduiPageEvent<TParameters>;
+  /** Function context supplied by the platform. */
+  readonly context: FunctionContext;
+  /** Action-specific parameter payload narrowed by the selected action string. */
+  readonly params: TypedSduiPageActionParams<TParameters, TAction>;
+  /** Per-request runtime created once for this handler invocation. */
+  readonly runtime: TRuntime;
+  /** Current function role id when present. */
+  readonly roleId: TypedSduiPageRoleId<TRequireRoleId>;
+}
+
+/**
+ * Initialization properties for {@link defineTypedSduiPageHandler}.
+ *
+ * @typeParam TParameters - SDUI page parameter union discriminated by `action`.
+ * @typeParam TRuntime - Shared runtime created once per invocation.
+ * @typeParam TStateUpdate - State payload returned for follow-up actions.
+ * @typeParam TInitAction - Action string that renders the initial SDUI spec.
+ * @typeParam TRequireRoleId - Whether callback args should require `roleId`.
+ */
+type TypedSduiPageHandlerOptionsBase<
+  TParameters extends { action: string },
+  TRuntime,
+  TStateUpdate,
+  TInitAction extends TypedSduiPageActionName<TParameters>,
+  TRequireRoleId extends boolean | undefined,
+> = {
+  /** Whether the handler should reject requests without `context.function.role_id`. */
+  readonly requireRoleId?: TRequireRoleId;
+  /** Error message used when `requireRoleId` is true but no role id is present. */
+  readonly missingRoleIdMessage?: string;
+  /** Creates one shared runtime object for this invocation. */
+  readonly createRuntime: (context: FunctionContext) => TRuntime | Promise<TRuntime>;
+  /** Renders the initial SDUI page spec for the selected init action. */
+  readonly init: (
+    args: TypedSduiPageHandlerArgs<TParameters, TRuntime, TInitAction, TRequireRoleId>,
+  ) => TypedSduiPageSpec | Promise<TypedSduiPageSpec>;
+  /** Returns one state update payload for each non-init action. */
+  readonly actions: TypedSduiActionHandlerMap<
+    TParameters,
+    TRuntime,
+    TStateUpdate,
+    TInitAction,
+    TRequireRoleId
+  >;
+  /** Optional formatter for the unknown-action bad-request message. */
+  readonly unknownActionMessage?: (action: string) => string;
+};
+
+export type TypedSduiPageHandlerOptions<
+  TParameters extends { action: string },
+  TRuntime,
+  TStateUpdate = never,
+  TInitAction extends TypedSduiPageActionName<TParameters> = DefaultInitAction<TParameters>,
+  TRequireRoleId extends boolean | undefined = false,
+> = TypedSduiPageHandlerOptionsBase<TParameters, TRuntime, TStateUpdate, TInitAction, TRequireRoleId> &
+  (Extract<TypedSduiPageActionName<TParameters>, 'init'> extends never ?
+    /** Action string treated as the initial SDUI render request when no literal `init` action exists. */
+    { readonly initAction: TInitAction }
+  : /** Optional action string treated as the initial SDUI render request. Defaults to `'init'` when present. */
+    { readonly initAction?: TInitAction });
+
+function hasOwnActionHandler<
+  TParameters extends { action: string },
+  TRuntime,
+  TStateUpdate,
+  TInitAction extends TypedSduiPageActionName<TParameters>,
+  TRequireRoleId extends boolean | undefined,
+>(
+  actions: TypedSduiActionHandlerMap<TParameters, TRuntime, TStateUpdate, TInitAction, TRequireRoleId>,
+  action: string,
+): action is TypedSduiNonInitActionName<TParameters, TInitAction> {
+  return Object.prototype.hasOwnProperty.call(actions, action);
+}
+
+type TypedSduiPageHandler<TParameters extends { action: string }, TStateUpdate> = (
+  event: TypedSduiPageEvent<TParameters>,
+  context: FunctionContext,
+) => Promise<FunctionResponse<TypedSduiPageOutput<TStateUpdate>>>;
+
+function buildTypedSduiPageHandler<
+  TParameters extends { action: string },
+  TRuntime,
+  TStateUpdate = never,
+  TInitAction extends TypedSduiPageActionName<TParameters> = DefaultInitAction<TParameters>,
+  TRequireRoleId extends boolean | undefined = false,
+>(
+  options: TypedSduiPageHandlerOptions<TParameters, TRuntime, TStateUpdate, TInitAction, TRequireRoleId>,
+): TypedSduiPageHandler<TParameters, TStateUpdate> {
+  const initAction = (options.initAction ?? 'init') as TInitAction;
+
+  return async (
+    event: TypedSduiPageEvent<TParameters>,
+    context: FunctionContext,
+  ): Promise<FunctionResponse<TypedSduiPageOutput<TStateUpdate>>> => {
+    const roleId = context.function.role_id;
+    if (options.requireRoleId === true && !roleId) {
+      return createTypedSduiPageBadRequestResponse<TypedSduiPageOutput<TStateUpdate>>(
+        options.missingRoleIdMessage ?? 'Role ID is required',
+      );
+    }
+
+    try {
+      const runtime = await options.createRuntime(context);
+      const action = String(event.parameters.action);
+
+      if (action === initAction) {
+        const spec = await options.init({
+          event,
+          context,
+          params: event.parameters as TypedSduiPageActionParams<TParameters, TInitAction>,
+          runtime,
+          roleId: roleId as TypedSduiPageRoleId<TRequireRoleId>,
+        });
+        return createTypedSduiPageSpecResponse<TypedSduiPageOutput<TStateUpdate>>(spec);
+      }
+
+      if (!hasOwnActionHandler(options.actions, action)) {
+        return createTypedSduiPageBadRequestResponse<TypedSduiPageOutput<TStateUpdate>>(
+          options.unknownActionMessage?.(action) ?? `Unknown action: ${action}`,
+        );
+      }
+
+      const stateUpdate = await options.actions[action]({
+        event,
+        context,
+        params: event.parameters as TypedSduiPageActionParams<TParameters, typeof action>,
+        runtime,
+        roleId: roleId as TypedSduiPageRoleId<TRequireRoleId>,
+      });
+      return createTypedSduiPageResponse<TypedSduiPageOutput<TStateUpdate>>(stateUpdate);
+    } catch (error) {
+      return createTypedSduiPageServerErrorResponse<TypedSduiPageOutput<TStateUpdate>>(error);
+    }
+  };
+}
+
+export function defineTypedSduiPageHandler<
+  TParameters extends { action: string },
+  TRuntime,
+  TStateUpdate = never,
+  TInitAction extends TypedSduiPageActionName<TParameters> = DefaultInitAction<TParameters>,
+>(
+  options: TypedSduiPageHandlerOptions<TParameters, TRuntime, TStateUpdate, TInitAction, true>,
+): TypedSduiPageHandler<TParameters, TStateUpdate>;
+
+export function defineTypedSduiPageHandler<
+  TParameters extends { action: string },
+  TRuntime,
+  TStateUpdate = never,
+  TInitAction extends TypedSduiPageActionName<TParameters> = DefaultInitAction<TParameters>,
+  TRequireRoleId extends boolean | undefined = false,
+>(
+  options: TypedSduiPageHandlerOptions<TParameters, TRuntime, TStateUpdate, TInitAction, TRequireRoleId>,
+): TypedSduiPageHandler<TParameters, TStateUpdate>;
+
+/**
+ * Defines one typed SDUI page handler with a shared runtime, one init action,
+ * and a typed action-dispatch table for follow-up state updates.
+ *
+ * The returned handler still accepts the normal `(event, context)` signature, so
+ * callers can keep an exported `onRipplingEvent(...)` function declaration that
+ * backend IO-contract derivation understands while removing the repetitive
+ * action-routing / response-wrapping boilerplate from the function body.
+ *
+ * @param options - Handler configuration including init renderer, runtime factory, and action dispatch table.
+ * @returns Handler function that returns typed SDUI spec / state / error responses.
+ * @typeParam TParameters - SDUI page parameter union discriminated by `action`.
+ * @typeParam TRuntime - Shared runtime created once per invocation.
+ * @typeParam TStateUpdate - State payload returned for follow-up actions.
+ * @typeParam TInitAction - Action string that renders the initial SDUI spec.
+ * @typeParam TRequireRoleId - Whether callback args should require `roleId`.
+ */
+export function defineTypedSduiPageHandler<
+  TParameters extends { action: string },
+  TRuntime,
+  TStateUpdate = never,
+  TInitAction extends TypedSduiPageActionName<TParameters> = DefaultInitAction<TParameters>,
+  TRequireRoleId extends boolean | undefined = false,
+>(
+  options: TypedSduiPageHandlerOptions<TParameters, TRuntime, TStateUpdate, TInitAction, TRequireRoleId>,
+): TypedSduiPageHandler<TParameters, TStateUpdate> {
+  return buildTypedSduiPageHandler(options);
+}
+
+/**
+ * Creates one parameter-first SDUI page-handler builder that fixes the action
+ * union and state-update payload up front, then infers the shared runtime type
+ * from `createRuntime(...)` when the returned builder is called.
+ *
+ * This is the intended golden path for normal page-function authoring: specify
+ * the discriminated input union and returned state payload once, then let the
+ * runtime object and `requireRoleId` behavior infer from the provided options.
+ *
+ * @returns Builder that accepts typed SDUI page-handler options.
+ * @typeParam TParameters - SDUI page parameter union discriminated by `action`.
+ * @typeParam TStateUpdate - State payload returned for follow-up actions.
+ */
+export function defineTypedSduiPageHandlerFor<
+  TParameters extends { action: string },
+  TStateUpdate = never,
+>(): <
+  TRuntime,
+  TInitAction extends TypedSduiPageActionName<TParameters> = DefaultInitAction<TParameters>,
+  TRequireRoleId extends boolean | undefined = false,
+>(
+  options: TypedSduiPageHandlerOptions<TParameters, TRuntime, TStateUpdate, TInitAction, TRequireRoleId>,
+) => TypedSduiPageHandler<TParameters, TStateUpdate> {
+  return <
+    TRuntime,
+    TInitAction extends TypedSduiPageActionName<TParameters> = DefaultInitAction<TParameters>,
+    TRequireRoleId extends boolean | undefined = false,
+  >(
+    options: TypedSduiPageHandlerOptions<TParameters, TRuntime, TStateUpdate, TInitAction, TRequireRoleId>,
+  ): TypedSduiPageHandler<TParameters, TStateUpdate> => buildTypedSduiPageHandler(options);
+}
+
+/**
+ * Configuration for the standard "set loading state, trigger function, write
+ * responsePath, then clear loading / error state" SDUI interaction pattern.
+ *
+ * @typeParam TState - SDUI page-state shape that owns the referenced state paths.
+ * @typeParam TResponse - Response payload written into `responsePath`.
+ * @typeParam TInputs - Server-bound function input payload sent through `triggerFunction(...)`.
+ */
+export interface TypedSduiMutationTriggerOptions<TState, TResponse, TInputs extends { action: string }> {
+  /** Target function id that should handle the mutation. */
+  readonly functionId: string;
+  /** Server-bound input payload forwarded to the function. */
+  readonly inputs: TInputs;
+  /** State path that should receive the function response body. */
+  readonly responsePath: TypedSduiStatePathForValue<TState, TResponse>;
+  /** Human-readable error message shown when the function call fails. */
+  readonly errorMessage: string;
+  /** Optional state assignments applied after a successful mutation. */
+  readonly onSuccessState?: TypedSduiStateAssignments<TState>;
+  /** Optional state assignments applied after a failed mutation. */
+  readonly onErrorState?: TypedSduiStateAssignments<TState>;
+  /** State path that stores the shared in-flight mutation flag. Defaults to `/isMutating`. */
+  readonly mutationStatePath?: TypedSduiStatePathForValue<TState, boolean>;
+  /** State path that stores the visible error message. Defaults to `/errorMessage`. */
+  readonly errorStatePath?: TypedSduiStatePathForValue<TState, string>;
+}
+
+/**
+ * Builds the common SDUI mutation action sequence used by stateful page
+ * functions: set a shared mutation flag, call the function, write the response
+ * into one `responsePath`, then clear the mutation/error state.
+ *
+ * Pebble's generated `triggerFunction(...)` params are currently too weakly
+ * typed for nested `inputs` expression objects, so this helper builds the same
+ * action binding through the lower-level action factory while keeping a fully
+ * typed public surface here.
+ *
+ * @param options - Trigger configuration for one mutation action.
+ * @returns Two-action sequence: optimistic mutation-state update plus function trigger.
+ * @typeParam TState - SDUI page-state shape that owns the referenced state paths.
+ * @typeParam TResponse - Response payload written into `responsePath`.
+ * @typeParam TInputs - Server-bound function input payload sent through the trigger action.
+ */
+type TypedSduiTriggerFunctionParams<TInputs extends { action: string }> = {
+  readonly functionId: string;
+  readonly inputs: TInputs;
+  readonly responsePath: string;
+} & Record<string, string | TInputs>;
+
+export function createTypedSduiMutationTrigger<TState, TResponse, TInputs extends { action: string }>(
+  options: TypedSduiMutationTriggerOptions<TState, TResponse, TInputs>,
+): ActionBinding[] {
+  const mutationStatePath = options.mutationStatePath ?? '/isMutating';
+  const errorStatePath = options.errorStatePath ?? '/errorMessage';
+  const triggerParams: TypedSduiTriggerFunctionParams<TInputs> = {
+    functionId: options.functionId,
+    inputs: options.inputs,
+    responsePath: options.responsePath,
+  };
+  const triggerOptions: ActionOptions = {
+    onSuccess: {
+      set: {
+        [errorStatePath]: '',
+        [mutationStatePath]: false,
+        ...(options.onSuccessState ?? {}),
+      },
+    },
+    onError: {
+      set: {
+        [errorStatePath]: options.errorMessage,
+        [mutationStatePath]: false,
+        ...(options.onErrorState ?? {}),
+      },
+    },
+  };
+
+  return [
+    setState({
+      statePath: mutationStatePath,
+      value: true,
+    }),
+    buildAction('triggerFunction', triggerParams, triggerOptions),
+  ];
+}