@rippling/rippling-sdk 0.2.0-alpha.108 → 0.2.0-alpha.110

package/src/lib/manifest/definitions/custom-skill.ts

@@ -0,0 +1,28 @@
+import {
+  defineComponent,
+  withApiName,
+  detachedManifestScope,
+  validateCustomApiName,
+  type ComponentDefinition,
+} from './component';
+import { CustomSkill, type CustomSkillProps } from '../custom-skill';
+
+/** New skills use API names; the legacy constructor remains available separately. */
+export type DefinedCustomSkillProps = Omit<CustomSkillProps, 'sourceSkillId'> & {
+  apiName: `${string}__c`;
+  sourceSkillId?: never;
+};
+
+export function defineCustomSkill(props: DefinedCustomSkillProps): CustomSkill {
+  validateCustomApiName(props.apiName);
+  const { apiName, ...config } = props;
+  return customSkillComponent.register(
+    withApiName(new CustomSkill(detachedManifestScope, config), apiName, { source_skill_id: apiName }),
+    props,
+  );
+}
+
+const customSkillComponent: ComponentDefinition<typeof defineCustomSkill> = defineComponent({
+  type: 'CUSTOM_SKILL',
+  define: defineCustomSkill,
+});

package/src/lib/manifest/definitions/field-section.ts

@@ -0,0 +1,31 @@
+import { defineComponent, withApiName, validateCustomApiName, type ComponentDefinition } from './component';
+import { CustomObjectFieldSection, type CustomObjectFieldSectionProps } from '../custom-object-field-section';
+import { manifestObject, type ObjectReference, scopedDefinition, type ObjectScoped } from './custom-object';
+
+export type DefineFieldSectionProps = Omit<CustomObjectFieldSectionProps, 'sectionId' | 'apiName'> & {
+  apiName: `${string}__c`;
+};
+
+export function defineFieldSection<TObject extends ObjectReference>(
+  object: TObject,
+  props: DefineFieldSectionProps,
+): ObjectScoped<TObject, CustomObjectFieldSection> {
+  validateCustomApiName(props.apiName);
+  return fieldSectionComponent.register(
+    scopedDefinition(
+      object,
+      withApiName(
+        new CustomObjectFieldSection(manifestObject(object), { ...props, sectionId: props.apiName }),
+        props.apiName,
+      ),
+    ),
+    object,
+    props,
+  );
+}
+
+const fieldSectionComponent: ComponentDefinition<typeof defineFieldSection> = defineComponent({
+  type: 'CUSTOM_OBJECT_FIELD_SECTION',
+  define: defineFieldSection,
+  references: (_definition, object) => [object],
+});

package/src/lib/manifest/definitions/field.ts

@@ -0,0 +1,119 @@
+import * as legacy from '../../../core/platform/custom-objects/fields';
+import type {
+  TextFieldDefinition,
+  NumberFieldDefinition,
+  RadioFieldDefinition,
+} from '../../../core/platform/custom-objects/types';
+import { defineComponent, type ComponentDefinition } from './component';
+import { Field, type FieldProps } from '../field';
+import {
+  scopedDefinition,
+  type ObjectScoped,
+  manifestObject,
+  manifestSection,
+  trackFieldSection,
+  fieldSectionReferences,
+  type ObjectReference,
+  type SectionReference,
+} from './custom-object';
+
+export type DefineFieldProps<TObject extends ObjectReference> = Omit<FieldProps, 'section'> & {
+  section: SectionReference<NoInfer<TObject>>;
+};
+
+export function defineField<TObject extends ObjectReference>(
+  object: TObject,
+  props: DefineFieldProps<TObject>,
+): ObjectScoped<TObject, Field> {
+  const section = manifestSection(object, props.section);
+  const field = scopedDefinition(
+    object,
+    trackFieldSection(new Field(manifestObject(object), { ...props, section }), section),
+  );
+  return fieldComponent.register(field, object, props);
+}
+
+/** Field factories for reusable definitions. Existing standalone factories remain available. */
+export const fields: Readonly<
+  Omit<typeof legacy, 'text' | 'number'> & { text: typeof text; number: typeof number; choice: typeof choice }
+> = Object.freeze({ ...legacy, text, number, choice });
+
+const fieldComponent: ComponentDefinition<typeof defineField> = defineComponent({
+  type: 'CUSTOM_OBJECT_FIELD',
+  define: defineField,
+  references: (definition, object, props) => () => [
+    object,
+    ...fieldSectionReferences(definition),
+    ...(props.summarySpec == null ?
+      []
+    : [
+        props.summarySpec.aggregates,
+        props.summarySpec.lookup,
+        ...props.summarySpec.filters.map((filter) => filter.field),
+      ]),
+  ],
+});
+
+interface Presentation<TNullable extends boolean, TSection extends string | undefined = string | undefined> {
+  label: string;
+  description?: string;
+  nullable?: TNullable;
+  section?: TSection;
+}
+
+type Required<TNullable extends boolean> = TNullable extends true ? false : true;
+
+type Rules<TNullable extends boolean> = { readonly nullable: TNullable };
+
+function presentation<TNullable extends boolean, TSection extends string | undefined>(
+  props: Presentation<TNullable, TSection>,
+) {
+  return {
+    displayName: props.label,
+    description: props.description ?? '',
+    required: !props.nullable as Required<TNullable>,
+    nullable: (props.nullable ?? false) as TNullable,
+    ...(props.section !== undefined ? { section: props.section } : {}),
+  };
+}
+
+function text<
+  const TNullable extends boolean = false,
+  const TSection extends string | undefined = string | undefined,
+>(
+  props: Presentation<TNullable, TSection> & { maxLength?: number; unique?: boolean },
+): TextFieldDefinition<Required<TNullable>, TSection> & Rules<TNullable> {
+  return legacy.text({ ...props, ...presentation(props) }) as TextFieldDefinition<
+    Required<TNullable>,
+    TSection
+  > &
+    Rules<TNullable>;
+}
+
+function number<
+  const TNullable extends boolean = false,
+  const TSection extends string | undefined = string | undefined,
+>(
+  props: Presentation<TNullable, TSection> & { decimalPlaces?: number },
+): NumberFieldDefinition<Required<TNullable>, TSection> & Rules<TNullable> {
+  return legacy.number({ ...props, ...presentation(props) }) as NumberFieldDefinition<
+    Required<TNullable>,
+    TSection
+  > &
+    Rules<TNullable>;
+}
+
+function choice<
+  const TOptions extends readonly string[],
+  const TNullable extends boolean = false,
+  const TSection extends string | undefined = string | undefined,
+>(
+  props: Presentation<TNullable, TSection> & { options: TOptions },
+): Omit<RadioFieldDefinition<Required<TNullable>, TSection>, '__valueType__'> & {
+  readonly __valueType__?: TOptions[number];
+} & Rules<TNullable> {
+  return legacy.radio({ ...props, ...presentation(props) }) as Omit<
+    RadioFieldDefinition<Required<TNullable>, TSection>,
+    '__valueType__'
+  > & { readonly __valueType__?: TOptions[number] } & Rules<TNullable>;
+}

package/src/lib/manifest/definitions/function.ts

@@ -0,0 +1,198 @@
+import type { RipplingSDK } from '../../../client';
+import { FunctionResponse, type FunctionContext } from '../../../functions';
+import type {
+  FunctionExecution,
+  FunctionExecutionsPageCursorURL,
+  ExecutionListLogsResponse,
+} from '../../../resources/functions/executions';
+import type { APIPromise } from '../../../core/api-promise';
+import type { PagePromise } from '../../../core/pagination';
+import { detachedManifestScope, defineComponent, sourceEntry } from './component';
+import { ManifestFunction, type ManifestFunctionProps } from '../manifest-function';
+import type { RequestOptions } from '../../../internal/request-options';
+import type { ExecutionListParams, ExecutionListLogsParams } from '../../../resources/functions/executions';
+
+/** Parser shared by a function's caller and handler. */
+export interface ValueParser<TValue> {
+  parse(value: unknown): TValue;
+}
+
+/** Authenticated execution resources supplied per call. */
+export interface FunctionOperationsContext {
+  readonly functions: {
+    readonly executions: Pick<
+      RipplingSDK['functions']['executions'],
+      'create' | 'list' | 'retrieve' | 'listLogs'
+    >;
+  };
+}
+
+export interface DefinedFunctionProps<TInput, TOutput> extends ManifestFunctionProps {
+  /** Handler source file read unchanged by project export. Importing the definition performs no file I/O. */
+  source?: URL;
+  input?: ValueParser<TInput>;
+  output?: ValueParser<TOutput>;
+}
+
+/** Execution returned by a function with its declared input/output contract. */
+export type FunctionExecutionResult<TInput, TOutput> = Omit<FunctionExecution, 'inputs' | 'outputs'> & {
+  inputs: TInput;
+  outputs?: TOutput;
+};
+
+export interface FunctionExecutions {
+  list(
+    ctx: FunctionOperationsContext,
+    params?: ExecutionListParams,
+    options?: RequestOptions,
+  ): PagePromise<FunctionExecutionsPageCursorURL, FunctionExecution>;
+  retrieve(
+    ctx: FunctionOperationsContext,
+    executionID: string,
+    options?: RequestOptions,
+  ): APIPromise<FunctionExecution>;
+  listLogs(
+    ctx: FunctionOperationsContext,
+    executionID: string,
+    params?: Omit<ExecutionListLogsParams, 'function_api_name'>,
+    options?: RequestOptions,
+  ): APIPromise<ExecutionListLogsResponse>;
+}
+
+export interface FunctionClient<TInput, TOutput> {
+  execute(input: TInput, options?: RequestOptions): Promise<FunctionExecutionResult<TInput, TOutput>>;
+  executions: {
+    list(
+      params?: ExecutionListParams,
+      options?: RequestOptions,
+    ): PagePromise<FunctionExecutionsPageCursorURL, FunctionExecution>;
+    retrieve(executionID: string, options?: RequestOptions): APIPromise<FunctionExecution>;
+    listLogs(
+      executionID: string,
+      params?: Omit<ExecutionListLogsParams, 'function_api_name'>,
+      options?: RequestOptions,
+    ): APIPromise<ExecutionListLogsResponse>;
+  };
+}
+
+export function defineFunction<TInput = unknown, TOutput = unknown>(
+  props: DefinedFunctionProps<TInput, TOutput>,
+): DefinedFunction<TInput, TOutput> {
+  return functionComponent.register(new DefinedFunction(props), props);
+}
+
+/** A deployable function reference with the same input/output contract at each call site. */
+export class DefinedFunction<TInput = unknown, TOutput = unknown> extends ManifestFunction {
+  private _source: URL | undefined;
+  readonly input: ValueParser<TInput> | undefined;
+  readonly output: ValueParser<TOutput> | undefined;
+
+  readonly executions: FunctionExecutions = {
+    list: (ctx: FunctionOperationsContext, params?: ExecutionListParams, options?: RequestOptions) =>
+      ctx.functions.executions.list(this.getApiName(), params, options),
+    retrieve: (ctx: FunctionOperationsContext, executionID: string, options?: RequestOptions) =>
+      ctx.functions.executions.retrieve(executionID, { function_api_name: this.getApiName() }, options),
+    listLogs: (
+      ctx: FunctionOperationsContext,
+      executionID: string,
+      params: Omit<ExecutionListLogsParams, 'function_api_name'> = {},
+      options?: RequestOptions,
+    ) =>
+      ctx.functions.executions.listLogs(
+        executionID,
+        { ...params, function_api_name: this.getApiName() },
+        options,
+      ),
+  };
+
+  constructor(props: DefinedFunctionProps<TInput, TOutput>) {
+    super(detachedManifestScope, props);
+    this.input = props.input;
+    this.output = props.output;
+    if (props.source !== undefined && props.code !== undefined)
+      throw new Error('Define a function with either source or code, not both.');
+    if (props.source !== undefined && props.source.protocol !== 'file:')
+      throw new Error('Component source must be a file URL.');
+    this._source = props.source === undefined ? undefined : new URL(props.source.href);
+  }
+
+  get source(): URL | undefined {
+    return this._source;
+  }
+
+  /** Replaces inline code or a file-backed source with the supplied code. */
+  override setCode(code: string): this {
+    super.setCode(code);
+    this._source = undefined;
+    return this;
+  }
+
+  /** Wraps a handler with the shared contract. Deployed source must be standalone or use declared npm dependencies. */
+  handler(handler: (input: TInput, context: FunctionContext) => TOutput | Promise<TOutput>) {
+    return async (event: TInput, context: FunctionContext): Promise<FunctionResponse<TOutput>> => {
+      const result = await handler(this.input == null ? event : this.input.parse(event), context);
+      return new FunctionResponse({ body: this.output == null ? result : this.output.parse(result) });
+    };
+  }
+
+  /** Starts an execution. Asynchronous executions may not have outputs yet. */
+  async execute(
+    ctx: FunctionOperationsContext,
+    input: TInput,
+    options?: RequestOptions,
+  ): Promise<FunctionExecutionResult<TInput, TOutput>> {
+    const inputs = input;
+    const { outputs, ...execution } = await ctx.functions.executions.create(
+      this.getApiName(),
+      { inputs },
+      options,
+    );
+    const body = (outputs as { body: unknown } | null | undefined)?.body;
+    return {
+      ...execution,
+      inputs,
+      ...(outputs != null ?
+        { outputs: this.output == null ? (body as TOutput) : this.output.parse(body) }
+      : {}),
+    };
+  }
+}
+
+interface FunctionMetadata {
+  type: 'FUNCTION';
+  api_name: string;
+  name: string;
+  description: string;
+  code_draft?: string;
+}
+
+const functionComponent = defineComponent({
+  type: 'FUNCTION',
+  define: defineFunction,
+  serialize: (definition) =>
+    sourceEntry(definition.toDict() as FunctionMetadata, definition.source, (config, code_draft) => ({
+      ...config,
+      code_draft,
+    })),
+});
+
+/** @internal Forward client helpers to the definition operations. */
+export function createFunctionClient<TInput, TOutput>(
+  ctx: FunctionOperationsContext,
+  definition: DefinedFunction<TInput, TOutput>,
+): FunctionClient<TInput, TOutput> {
+  return {
+    execute: (input: TInput, options?: RequestOptions) => definition.execute(ctx, input, options),
+    executions: {
+      list: (params?: ExecutionListParams, options?: RequestOptions) =>
+        definition.executions.list(ctx, params, options),
+      retrieve: (executionID: string, options?: RequestOptions) =>
+        definition.executions.retrieve(ctx, executionID, options),
+      listLogs: (
+        executionID: string,
+        params?: Omit<ExecutionListLogsParams, 'function_api_name'>,
+        options?: RequestOptions,
+      ) => definition.executions.listLogs(ctx, executionID, params, options),
+    },
+  };
+}

package/src/lib/manifest/definitions/index.ts

@@ -0,0 +1,91 @@
+/** Standalone component definitions composed by defineManifest. */
+export {
+  defineComponent,
+  type ComponentImplementation,
+  type MetadataConfig,
+  type MetadataEntry,
+  type BuildContext,
+  type CompileContext,
+} from './component';
+export { defineAction, type DefineActionProps } from './action';
+export {
+  defineAgent,
+  DefinedAgent,
+  type DefinedAgentProps,
+  type AgentOperationsContext,
+  type AgentSessions,
+  type AgentOperations,
+  type AgentClient,
+} from './agent';
+export { defineApp } from './app';
+export { defineCategory, defineCustomObjectCategory, type DefineCustomObjectCategoryProps } from './category';
+export { defineCustomField, type DefineCustomFieldProps } from './custom-field';
+export {
+  defineCustomFieldSection,
+  type DefinedCustomFieldSection,
+  type DefineCustomFieldSectionProps,
+} from './custom-field-section';
+export {
+  defineCustomObject,
+  extendCustomObject,
+  eq,
+  ne,
+  lt,
+  lte,
+  gt,
+  gte,
+  inArray,
+  notInArray,
+  isNull,
+  isNotNull,
+  and,
+  or,
+  not,
+  type DefinedCustomObject,
+  type CustomObjectOperations,
+  type ObjectRecordsContext,
+  type ObjectSchemaContext,
+  type ObjectRecordListOptions,
+  type DefineCustomObjectProps,
+  type ObjectRecords,
+  type ObjectCreateInput,
+  type ObjectUpdateInput,
+  type ObjectBulkUpdateInput,
+  type ObjectSchema,
+  type ObjectSchemaFields,
+  type ObjectClient,
+  type ObjectFilter,
+} from './custom-object';
+export { defineCustomSkill, type DefinedCustomSkillProps } from './custom-skill';
+export { defineField, fields, type DefineFieldProps } from './field';
+export { defineFieldSection, type DefineFieldSectionProps } from './field-section';
+export {
+  defineFunction,
+  DefinedFunction,
+  type DefinedFunctionProps,
+  type FunctionOperationsContext,
+  type ValueParser,
+  type FunctionExecutions,
+  type FunctionExecutionResult,
+  type FunctionClient,
+} from './function';
+export { defineListView, type DefineListViewProps } from './list-view';
+export {
+  defineObjectSearchConfig,
+  type DefineObjectSearchConfigProps,
+  type DefinedObjectSearchConfig,
+} from './object-search-config';
+export {
+  defineObjectSettings,
+  type ObjectSettingsProps,
+  type DefinedObjectSettings,
+} from './object-settings';
+export { definePage, type DefinePageProps } from './page';
+export { definePageLayout, type PageLayoutOptions, type DefinedPageLayout } from './page-layout';
+export {
+  defineRecordTriggeredFlow,
+  type DefinedRuleAction,
+  type DefineRecordTriggeredFlowProps,
+} from './record-triggered-flow';
+export { defineValidation, type DefineValidationProps } from './validation';
+export { defineWorkflow, workflowFunction, type DefineWorkflowProps } from './workflow';

package/src/lib/manifest/definitions/list-view.ts

@@ -0,0 +1,48 @@
+import { defineComponent, withApiName, type ComponentDefinition } from './component';
+import {
+  fieldReferences,
+  manifestObject,
+  manifestField,
+  type ObjectReference,
+  type DefinitionFieldReference,
+} from './custom-object';
+import { ListViewDef, type ListViewDefProps } from '../list-view';
+
+export type DefineListViewProps<TObject extends ObjectReference> = Omit<
+  ListViewDefProps,
+  'viewId' | 'apiName' | 'fields' | 'orderBy'
+> & {
+  apiName: string;
+  fields: readonly NoInfer<DefinitionFieldReference<TObject>>[];
+  orderBy?: NoInfer<DefinitionFieldReference<TObject>>;
+};
+
+export function defineListView<TObject extends ObjectReference>(
+  object: TObject,
+  props: DefineListViewProps<TObject>,
+): ListViewDef {
+  const { fields, orderBy, ...rest } = props;
+  return listViewComponent.register(
+    withApiName(
+      new ListViewDef(manifestObject(object), {
+        ...rest,
+        viewId: rest.apiName,
+        fields: fields.map((field) => manifestField(object, field)),
+        ...(orderBy != null ? { orderBy: manifestField(object, orderBy) } : {}),
+      }),
+      rest.apiName,
+    ),
+    object,
+    props,
+  );
+}
+
+const listViewComponent: ComponentDefinition<typeof defineListView> = defineComponent({
+  type: 'CUSTOM_OBJECT_LIST_VIEW',
+  define: defineListView,
+  references: (_definition, object, props) => [
+    object,
+    ...props.fields.flatMap((field) => fieldReferences(object, field)),
+    ...(props.orderBy == null ? [] : fieldReferences(object, props.orderBy)),
+  ],
+});

package/src/lib/manifest/definitions/object-search-config.ts

@@ -0,0 +1,44 @@
+import { defineComponent, type ComponentDefinition } from './component';
+import {
+  fieldReferences,
+  manifestObject,
+  manifestField,
+  type ObjectReference,
+  type DefinitionFieldReference,
+} from './custom-object';
+
+export interface DefinedObjectSearchConfig {
+  toDict(): { type: 'CUSTOM_OBJECT_SEARCH_CONFIG'; model_rql_name: string; search_response_fields: string[] };
+}
+
+export type DefineObjectSearchConfigProps<TObject extends ObjectReference> = {
+  fields: readonly NoInfer<DefinitionFieldReference<TObject>>[];
+};
+
+export function defineObjectSearchConfig<TObject extends ObjectReference>(
+  reference: TObject,
+  props: DefineObjectSearchConfigProps<TObject>,
+): DefinedObjectSearchConfig {
+  const object = manifestObject(reference);
+  const fields = props.fields.map((field) => manifestField(reference, field));
+  return objectSearchConfigComponent.register(
+    {
+      toDict: () => ({
+        type: 'CUSTOM_OBJECT_SEARCH_CONFIG' as const,
+        model_rql_name: object.getApiName(),
+        search_response_fields: fields.map((field) => field.getApiName()),
+      }),
+    },
+    reference,
+    props,
+  );
+}
+
+const objectSearchConfigComponent: ComponentDefinition<typeof defineObjectSearchConfig> = defineComponent({
+  type: 'CUSTOM_OBJECT_SEARCH_CONFIG',
+  define: defineObjectSearchConfig,
+  references: (_definition, object, props) => [
+    object,
+    ...props.fields.flatMap((field) => fieldReferences(object, field)),
+  ],
+});

package/src/lib/manifest/definitions/object-settings.ts

@@ -0,0 +1,61 @@
+import { defineComponent, type ComponentDefinition } from './component';
+import { manifestObject, type ObjectReference, type ObjectScoped } from './custom-object';
+import type { CustomObjectPageLayout } from '../custom-object-page-layout';
+
+export interface ObjectSettingsProps<TObject extends ObjectReference = ObjectReference> {
+  allowAttachments?: boolean;
+  allowComments?: boolean;
+  isSearchable?: boolean;
+  defaultLayout?: ObjectScoped<
+    TObject,
+    Pick<CustomObjectPageLayout, 'getCustomObjectApiName' | 'getLayoutId'>
+  >;
+}
+
+/** Settings are identified by their parent object, rather than an independent API name. */
+export interface DefinedObjectSettings {
+  toDict(): {
+    type: 'CUSTOM_OBJECT_SETTINGS';
+    setting_id: string;
+    object_rql_name: string;
+    allow_attachments: boolean;
+    allow_comments: boolean;
+    is_searchable: boolean;
+    layout_config: { default_layout: string } | null;
+  };
+}
+
+export function defineObjectSettings<TObject extends ObjectReference>(
+  reference: TObject,
+  props: ObjectSettingsProps<NoInfer<TObject>>,
+): DefinedObjectSettings {
+  const { allowAttachments = false, allowComments = false, isSearchable = false, defaultLayout } = props;
+  const object = manifestObject(reference);
+  if (defaultLayout != null && defaultLayout.getCustomObjectApiName() !== object.getApiName()) {
+    throw new Error('The default layout must belong to the object being configured.');
+  }
+  return objectSettingsComponent.register(
+    {
+      toDict: () => ({
+        type: 'CUSTOM_OBJECT_SETTINGS' as const,
+        setting_id: `${object.getApiName()}_settings`,
+        object_rql_name: object.getApiName(),
+        allow_attachments: allowAttachments,
+        allow_comments: allowComments,
+        is_searchable: isSearchable,
+        layout_config: defaultLayout == null ? null : { default_layout: defaultLayout.getLayoutId() },
+      }),
+    },
+    reference,
+    props,
+  );
+}
+
+const objectSettingsComponent: ComponentDefinition<typeof defineObjectSettings> = defineComponent({
+  type: 'CUSTOM_OBJECT_SETTINGS',
+  define: defineObjectSettings,
+  references: (_definition, object, props) => [
+    object,
+    ...(props.defaultLayout == null ? [] : [props.defaultLayout]),
+  ],
+});