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

package/src/lib/manifest/definitions/page-layout.ts

@@ -0,0 +1,218 @@
+import { defineComponent, withApiName, registeredComponent, type ComponentDefinition } from './component';
+import { CustomObjectPageLayout, type CustomObjectPageLayoutProps } from '../custom-object-page-layout';
+import type { CustomObjectFieldSection } from '../custom-object-field-section';
+import type { Field } from '../field';
+import {
+  manifestObject,
+  manifestField,
+  manifestSection,
+  type ObjectReference,
+  type DefinitionFieldReference,
+  type SectionReference,
+  scopedDefinition,
+  type ObjectScoped,
+} from './custom-object';
+
+export type PageLayoutOptions<O extends ObjectReference> = LayoutInput<
+  O,
+  Omit<CustomObjectPageLayoutProps, 'layoutId'>
+>;
+
+export type DefinedPageLayout<O extends ObjectReference> = ObjectScoped<
+  O,
+  Omit<CustomObjectPageLayout, Mutations> & {
+    setTitleField(field: DefinitionFieldReference<O>): DefinedPageLayout<O>;
+    setDescriptionField(field: DefinitionFieldReference<O>): DefinedPageLayout<O>;
+    removeSection(
+      section: SectionReference<O> | string,
+      options?:
+        | import('../custom-object-page-layout').RemovePageLayoutSectionOptions
+        | import('../custom-object-page-layout').RemoveSystemPageLayoutSectionOptions,
+    ): DefinedPageLayout<O>;
+  } & {
+    [K in Exclude<
+      Mutations,
+      'setTitleField' | 'setDescriptionField' | 'removeSection'
+    >]: CustomObjectPageLayout[K] extends (...args: infer A) => unknown ?
+      (...args: LayoutInput<O, A>) => DefinedPageLayout<O>
+    : never;
+  }
+>;
+
+export function definePageLayout<O extends ObjectReference>(
+  object: O,
+  props: PageLayoutOptions<NoInfer<O>>,
+): DefinedPageLayout<O> {
+  const candidates = new Map<object, { field?: string; sections?: Set<string> }>();
+  // Adapt explicit references and delegate every layout operation to the existing implementation.
+  const adapt = (value: unknown, key?: string): any => {
+    if (key != null && opaque.has(key)) return value;
+    if (isSectionReference(value)) {
+      const sections = candidates.get(value)?.sections ?? new Set<string>();
+      sections.add(value.getSectionId());
+      candidates.set(value, { sections });
+      return manifestSection(object, value as SectionReference<O>);
+    }
+    if (
+      isFieldReference(value) ||
+      (value != null && typeof value === 'object' && 'objectApiName' in value && 'apiName' in value)
+    ) {
+      const field = manifestField(object, value as DefinitionFieldReference<O>);
+      if (registeredComponent(value) != null) candidates.set(value, { field: field.getApiName() });
+      return key != null && headerFields.has(key) ? field.getApiName() : field;
+    }
+    if (Array.isArray(value)) return value.map((item) => adapt(item));
+    if (value != null && typeof value === 'object') {
+      const input = value as Record<string, any>;
+      const result = Object.fromEntries(
+        Object.entries(input).map(([name, item]) => [
+          name,
+          input['type'] === 'fields_section' && name === 'section' ?
+            manifestSection(object, item as SectionReference<O>)
+          : adapt(item, name),
+        ]),
+      );
+      if (input['type'] === 'fields_section' && typeof input['section'] === 'object') {
+        const section = input['section'] as CustomObjectFieldSection;
+        const sections = candidates.get(section)?.sections ?? new Set<string>();
+        sections.add(input['key'] ?? section.getSectionId());
+        candidates.set(section, { sections });
+      }
+      return result;
+    }
+    return value;
+  };
+  const adapted = adapt(props) as CustomObjectPageLayoutProps;
+  if (adapted.tabEdits != null && adapted.tabEdits.tabsOrder === undefined) {
+    adapted.tabEdits.tabsOrder = [
+      ...new Set([
+        ...(adapted.tabEdits.newTabs ?? []).map((tab) => tab.key),
+        ...Object.entries(adapted.tabEdits.systemTabEdits ?? {})
+          .filter(([, tab]) => !tab.deleted)
+          .map(([key]) => key),
+      ]),
+    ];
+  }
+  const layout = withApiName(
+    new CustomObjectPageLayout(manifestObject(object), {
+      ...adapted,
+      layoutId: props.apiName,
+    }),
+    props.apiName,
+  );
+  for (const name of Object.getOwnPropertyNames(CustomObjectPageLayout.prototype)) {
+    if (!/^(add|remove|set)[A-Z]/.test(name)) continue;
+    const method = (layout as any)[name].bind(layout);
+    (layout as any)[name] = (...args: unknown[]) => {
+      if (/^(add|remove)Fields?$/.test(name)) {
+        const options = args[1];
+        if (
+          options != null &&
+          typeof options === 'object' &&
+          'section' in options &&
+          typeof options.section === 'string'
+        ) {
+          args[1] = {
+            ...options,
+            section: manifestSection(object, options.section as SectionReference<O>),
+          };
+        }
+      }
+      method(...args.map((arg) => adapt(arg)));
+      return layout;
+    };
+  }
+  // Only currently serialized structural references count; removed fields/sections do not become roots.
+  dependencies.set(layout, () => {
+    const config = layout.toDict();
+    const fields = new Set<string>();
+    const sections = new Set<string>();
+    const header = config['header_edits'] ?? {};
+    for (const name of [
+      header.newTitleField,
+      header.newDescriptionField,
+      ...(header.newFields ?? []).map((f: any) => f.rqlName),
+      ...Object.values(header.systemFieldEdits ?? {}).map((f: any) => f.newRqlField),
+    ])
+      if (typeof name === 'string') fields.add(name);
+    const collectSection = (section: any) => {
+      if (section.type !== 'fields_section') return;
+      sections.add(section.key);
+      for (const field of section.fields ?? []) fields.add(field.fieldRqlName);
+    };
+    const tabs = config['tab_edits'] ?? {};
+    for (const tab of tabs.newTabs ?? []) for (const section of tab.sections ?? []) collectSection(section);
+    for (const tab of Object.values(tabs.systemTabEdits ?? {}) as any[]) {
+      if (tab.deleted) continue;
+      for (const section of tab.newSections ?? []) collectSection(section);
+      for (const [key, section] of Object.entries(tab.systemSectionEdits ?? {}) as [string, any][]) {
+        if (section.deleted) continue;
+        sections.add(key);
+        for (const field of section.newFields ?? []) fields.add(field.fieldRqlName);
+      }
+    }
+    return [...candidates]
+      .filter(([, ref]) =>
+        ref.field != null ?
+          fields.has(ref.field)
+        : [...(ref.sections ?? [])].some((key) => sections.has(key)),
+      )
+      .map(([definition]) => definition);
+  });
+  return pageLayoutComponent.register(
+    scopedDefinition(object, layout) as unknown as DefinedPageLayout<O>,
+    object,
+    props,
+  );
+}
+
+function isFieldReference(value: unknown): value is Field {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    'getApiName' in value &&
+    typeof value.getApiName === 'function' &&
+    'getCustomObjectApiName' in value &&
+    typeof value.getCustomObjectApiName === 'function'
+  );
+}
+
+function isSectionReference(value: unknown): value is CustomObjectFieldSection {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    'getSectionId' in value &&
+    typeof value.getSectionId === 'function' &&
+    'getModelApiName' in value &&
+    typeof value.getModelApiName === 'function'
+  );
+}
+
+type LayoutInput<O extends ObjectReference, T> = T extends CustomObjectFieldSection ? SectionReference<O>
+: T extends Field ? DefinitionFieldReference<O>
+: T extends readonly unknown[] ? { [K in keyof T]: LayoutInput<O, T[K]> }
+: T extends object ?
+  {
+    [K in keyof T]: K extends 'defaultValue' | 'visibilityConditions' | 'inputMapping' ? T[K]
+    : K extends 'newRqlField' | 'newTitleField' | 'newDescriptionField' | 'rqlName' ?
+      T[K] | DefinitionFieldReference<O>
+    : LayoutInput<O, T[K]>;
+  }
+: T;
+
+type Mutations = Extract<keyof CustomObjectPageLayout, `add${string}` | `remove${string}` | `set${string}`>;
+
+const dependencies = new WeakMap<object, () => object[]>();
+
+const opaque = new Set(['defaultValue', 'visibilityConditions', 'inputMapping']);
+
+const headerFields = new Set(['newRqlField', 'newTitleField', 'newDescriptionField', 'rqlName']);
+
+const pageLayoutComponent: ComponentDefinition<typeof definePageLayout> = defineComponent({
+  type: 'CUSTOM_OBJECT_PAGE_LAYOUT',
+  define: definePageLayout,
+  references: (definition, object) => () => [
+    object,
+    ...(dependencies.get(definition)?.() ?? []).filter((reference) => registeredComponent(reference) != null),
+  ],
+});

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

@@ -0,0 +1,28 @@
+import {
+  defineComponent,
+  withApiName,
+  detachedManifestScope,
+  validateCustomApiName,
+  type ComponentDefinition,
+} from './component';
+import { ManifestFunction } from '../manifest-function';
+import { SduiPage, type SduiPageProps } from '../sdui-page';
+
+export type DefinePageProps = Omit<SduiPageProps, 'sduiPageId' | 'apiName' | 'function'> & {
+  apiName: `${string}__c`;
+  function: ManifestFunction;
+};
+
+export function definePage(props: DefinePageProps): SduiPage {
+  validateCustomApiName(props.apiName);
+  return pageComponent.register(
+    withApiName(new SduiPage(detachedManifestScope, { ...props, sduiPageId: props.apiName }), props.apiName),
+    props,
+  );
+}
+
+const pageComponent: ComponentDefinition<typeof definePage> = defineComponent({
+  type: 'SDUI_PAGE',
+  define: definePage,
+  references: (_definition, props) => [props.function],
+});

package/src/lib/manifest/definitions/record-triggered-flow.ts

@@ -0,0 +1,71 @@
+import { defineComponent, withApiName, validateCustomApiName, type ComponentDefinition } from './component';
+import {
+  fieldReferences,
+  type ObjectScoped,
+  manifestObject,
+  manifestField,
+  type ObjectReference,
+  type DefinitionFieldReference,
+} from './custom-object';
+import type { Field } from '../field';
+import type { AnyCustomObjectDefinition, FieldValue } from '../../../core/platform/custom-objects/types';
+import { Rule, type RuleProps, type RuleAction } from '../rule';
+
+/** Flow actions accept shared writable field definitions as well as existing manifest fields. */
+export type DefinedRuleAction<TObject extends ObjectReference> =
+  | (Omit<RuleAction, 'targetField'> & { targetField: ObjectScoped<TObject, Field> })
+  | (TObject extends AnyCustomObjectDefinition ?
+      {
+        [K in keyof TObject['fields']]: TypedRuleAction<TObject['fields'][K]>;
+      }[keyof TObject['fields']]
+    : never);
+
+export type DefineRecordTriggeredFlowProps<TObject extends ObjectReference> = Omit<
+  RuleProps,
+  'flowId' | 'apiName' | 'actions'
+> & {
+  apiName: `${string}__c`;
+  actions?: readonly DefinedRuleAction<NoInfer<TObject>>[];
+};
+
+export function defineRecordTriggeredFlow<TObject extends ObjectReference>(
+  object: TObject,
+  props: DefineRecordTriggeredFlowProps<TObject>,
+): Rule {
+  validateCustomApiName(props.apiName);
+  const { actions: inputActions, ...rest } = props;
+  const actions = inputActions?.map((action) => ({
+    ...action,
+    targetField: manifestField(object, action.targetField as DefinitionFieldReference<TObject>),
+  }));
+  return recordTriggeredFlowComponent.register(
+    withApiName(
+      new Rule(manifestObject(object), {
+        ...rest,
+        flowId: rest.apiName,
+        ...(actions != null ? { actions } : {}),
+      }),
+      rest.apiName,
+    ),
+    object,
+    props,
+  );
+}
+
+type TypedRuleAction<TField> =
+  TField extends { writable: true } ?
+    {
+      targetField: TField;
+      fixedValue?: FieldValue<TField>;
+      rqlFormula?: string;
+    }
+  : never;
+
+const recordTriggeredFlowComponent: ComponentDefinition<typeof defineRecordTriggeredFlow> = defineComponent({
+  type: 'CUSTOM_OBJECT_RECORD_TRIGGERED_FLOW',
+  define: defineRecordTriggeredFlow,
+  references: (_definition, object, props) => [
+    object,
+    ...(props.actions ?? []).flatMap((action) => fieldReferences(object, action.targetField)),
+  ],
+});

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

@@ -0,0 +1,46 @@
+import { defineComponent, withApiName, validateCustomApiName, type ComponentDefinition } from './component';
+import {
+  fieldReferences,
+  manifestObject,
+  manifestField,
+  type ObjectReference,
+  type DefinitionFieldReference,
+} from './custom-object';
+import { Validation, type ValidationProps } from '../validation';
+
+export type DefineValidationProps<TObject extends ObjectReference> = Omit<
+  ValidationProps,
+  'ruleId' | 'apiName' | 'fieldRef'
+> & {
+  apiName: `${string}__c`;
+  fieldRef?: NoInfer<DefinitionFieldReference<TObject>>;
+};
+
+export function defineValidation<TObject extends ObjectReference>(
+  object: TObject,
+  props: DefineValidationProps<TObject>,
+): Validation {
+  validateCustomApiName(props.apiName);
+  const { fieldRef, ...rest } = props;
+  return validationComponent.register(
+    withApiName(
+      new Validation(manifestObject(object), {
+        ...rest,
+        ruleId: rest.apiName,
+        ...(fieldRef != null ? { fieldRef: manifestField(object, fieldRef) } : {}),
+      }),
+      rest.apiName,
+    ),
+    object,
+    props,
+  );
+}
+
+const validationComponent: ComponentDefinition<typeof defineValidation> = defineComponent({
+  type: 'CUSTOM_OBJECT_VALIDATION_RULE',
+  define: defineValidation,
+  references: (_definition, object, props) => [
+    object,
+    ...(props.fieldRef == null ? [] : fieldReferences(object, props.fieldRef)),
+  ],
+});

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

@@ -0,0 +1,62 @@
+import {
+  detachedManifestScope,
+  defineComponent,
+  withApiName,
+  validateCustomApiName,
+  type ComponentDefinition,
+} from './component';
+import { Workflow, type WorkflowProps, type WorkflowNode, type WorkflowGraph } from '../workflow';
+import type { WorkflowActionPayloads } from '../workflow/actions';
+import type { ManifestFunction } from '../manifest-function';
+
+export type DefineWorkflowProps = Omit<WorkflowProps, 'definitionId' | 'apiName'> & {
+  apiName: `${string}__c`;
+};
+
+/** An explicit graph reference includes its function in the manifest and keeps the wire graph unchanged. */
+export function workflowFunction(
+  definition: ManifestFunction,
+  payload: Omit<WorkflowActionPayloads['RunFunction'], 'function_id'>,
+  options: Omit<WorkflowNode, 'config_id' | 'payload' | 'processing_context'> = {},
+): WorkflowNode {
+  const node: ReferencedNode = {
+    ...options,
+    config_id: 'RunFunction',
+    payload: { ...payload, function_id: definition.getApiName() },
+    processing_context: { function_context: { function_api_name: definition.getApiName() } },
+  };
+  Object.defineProperty(node, nodeFunction, { value: definition, enumerable: true });
+  return node;
+}
+
+export function defineWorkflow(props: DefineWorkflowProps): Workflow {
+  validateCustomApiName(props.apiName);
+  return workflowComponent.register(
+    withApiName(
+      new Workflow(detachedManifestScope, { ...props, definitionId: props.apiName }),
+      props.apiName,
+    ),
+    props,
+  );
+}
+
+const nodeFunction = Symbol.for('@rippling/sdk/workflow-node-function/v1');
+
+type ReferencedNode = WorkflowNode & { readonly [nodeFunction]?: ManifestFunction };
+
+const graphFunctions = (graph: WorkflowGraph | undefined): ManifestFunction[] =>
+  Object.values(graph?.nodes ?? {}).flatMap((node: ReferencedNode) =>
+    node[nodeFunction] == null ? [] : [node[nodeFunction]],
+  );
+
+const workflowComponent: ComponentDefinition<typeof defineWorkflow> = defineComponent({
+  type: 'WORKFLOW_DEFINITION',
+  define: defineWorkflow,
+  references:
+    (_definition, { function: fn, graph, functionsInferredGraph }) =>
+    () => [
+      ...(fn == null || typeof fn === 'string' ? [] : [fn]),
+      ...graphFunctions(graph),
+      ...graphFunctions(functionsInferredGraph),
+    ],
+});

package/src/lib/manifest/index.ts

@@ -322,3 +322,7 @@ export {
   type WorkflowWebhookDefinition,
   type WorkflowWebhookTrigger,
 } from './workflow';
+
+export * from './composition';
+export * from './package-manifest';
+export * from './definitions';

package/src/lib/manifest/package-manifest.ts

@@ -0,0 +1,40 @@
+import type { BuiltManifest } from './manifest-builder';
+
+/** Publisher-owned package information, independent of component identities. */
+export interface PackageInformation {
+  key: string;
+  name: string;
+  type: 'managed' | 'unmanaged';
+  description?: string;
+}
+
+/** Package information and a reference to the project's source manifest. */
+export interface PackageManifest {
+  package: PackageInformation;
+  version: string;
+  manifest: Readonly<BuiltManifest>;
+}
+
+/** Define package information around an existing manifest without compiling its sources. */
+export function definePackageManifest(input: PackageManifest): Readonly<PackageManifest> {
+  if (!/^[a-z][a-z0-9_]{0,99}$/.test(input.package.key))
+    throw new Error(
+      'Package key must start with a lowercase letter and contain only lowercase letters, digits, or underscores (maximum 100 characters).',
+    );
+  if (input.package.key.includes('rippling'))
+    throw new Error('Package key cannot contain the reserved name rippling.');
+  if (!input.package.name.trim()) throw new Error('Package name is required.');
+  if (input.package.type !== 'managed' && input.package.type !== 'unmanaged')
+    throw new Error('Package type must be managed or unmanaged.');
+  if (!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(input.version))
+    throw new Error('Package version must be major.minor.patch.');
+  if (input.manifest.metadata == null || !Array.isArray(input.manifest.components))
+    throw new Error('Package manifest requires metadata and components.');
+  if (input.manifest.components_to_delete != null && input.manifest.components_to_delete.length > 0)
+    throw new Error('Package snapshots cannot contain component deletions.');
+  return Object.freeze({
+    package: Object.freeze({ ...input.package }),
+    version: input.version,
+    manifest: input.manifest,
+  });
+}

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.2.0-alpha.109'; // x-release-please-version
+export const VERSION = '0.2.0-alpha.110'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.2.0-alpha.109";
+export declare const VERSION = "0.2.0-alpha.110";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.2.0-alpha.109";
+export declare const VERSION = "0.2.0-alpha.110";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.2.0-alpha.109'; // x-release-please-version
+exports.VERSION = '0.2.0-alpha.110'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.2.0-alpha.109'; // x-release-please-version
+export const VERSION = '0.2.0-alpha.110'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map