@rippling/rippling-sdk 0.2.0-alpha.85 → 0.2.0-alpha.87

package/src/core/platform/custom-objects/types.ts

@@ -0,0 +1,753 @@
+import type {
+  CustomObjectFieldDerivedAggregatedField,
+  CustomObjectFieldFormulaAttrMetas,
+  CustomObjectFieldRqlDefinition,
+  CustomObjectFieldSection as RestCustomObjectFieldSection,
+} from '../../../resources/custom-objects/fields';
+import type { CustomObjectCategoryDefinition } from './category';
+
+/** Lowercase alphabet used by the logical-name helper types. */
+type LowerAlpha =
+  | 'a'
+  | 'b'
+  | 'c'
+  | 'd'
+  | 'e'
+  | 'f'
+  | 'g'
+  | 'h'
+  | 'i'
+  | 'j'
+  | 'k'
+  | 'l'
+  | 'm'
+  | 'n'
+  | 'o'
+  | 'p'
+  | 'q'
+  | 'r'
+  | 's'
+  | 't'
+  | 'u'
+  | 'v'
+  | 'w'
+  | 'x'
+  | 'y'
+  | 'z';
+
+/** Returns `never` when the provided string is not a logical snake_case name. */
+type LogicalNameLike<TName extends string> =
+  string extends TName ? string
+  : TName extends `${string}__c` ? never
+  : TName extends Lowercase<TName> ?
+    TName extends (
+      `${string}-${string}` | `${string} ${string}` | `${string}.${string}` | `${string}/${string}`
+    ) ?
+      never
+    : TName extends `${infer First}${string}` ?
+      First extends LowerAlpha ?
+        TName
+      : never
+    : never
+  : never;
+
+/**
+ * Author-facing logical name for a custom object.
+ *
+ * Logical names are expected to be unsuffixed snake_case values such as
+ * `'dental_provider'`. The runtime compiler appends `__c` when generating the
+ * manifest api name.
+ *
+ * @typeParam TName - Candidate logical custom-object name.
+ */
+export type LogicalCustomObjectName<TName extends string = string> = LogicalNameLike<TName>;
+
+/**
+ * Author-facing logical name for a custom field.
+ *
+ * Logical names are expected to be unsuffixed snake_case values such as
+ * `'provider_status'`. The runtime compiler appends `__c` when generating the
+ * manifest field api name.
+ *
+ * @typeParam TName - Candidate logical custom-field name.
+ */
+export type LogicalCustomFieldName<TName extends string = string> = LogicalNameLike<TName>;
+
+/**
+ * Author-facing logical name for a custom category.
+ *
+ * Logical names are expected to be unsuffixed snake_case values such as
+ * `'dental'`. The runtime compiler appends `__c` when generating the manifest
+ * category api name.
+ *
+ * @typeParam TName - Candidate logical category name.
+ */
+export type LogicalCategoryName<TName extends string = string> = LogicalNameLike<TName>;
+
+/**
+ * Wire-level api name generated from a logical custom-object name.
+ *
+ * @typeParam TName - Logical custom-object name.
+ */
+export type CustomObjectApiName<TName extends string = string> = `${TName}__c`;
+
+/**
+ * Wire-level api name generated from a logical custom-field name.
+ *
+ * @typeParam TName - Logical custom-field name.
+ */
+export type CustomFieldApiName<TName extends string = string> = `${TName}__c`;
+
+/**
+ * Wire-level api name generated from a logical category name.
+ *
+ * @typeParam TName - Logical category name.
+ */
+export type CategoryApiName<TName extends string = string> = `${TName}__c`;
+
+/**
+ * Supported native Rippling model target for a lookup field.
+ *
+ * @typeParam TApiName - Native model api name, for example `'Employee'`.
+ */
+export interface NativeModelTarget<TApiName extends string = string> {
+  readonly kind: 'native-model-target';
+  readonly apiName: TApiName;
+}
+
+/**
+ * Compact lookup value used by derived record and input types.
+ *
+ * @typeParam TApiName - Target object or native model api name.
+ */
+export interface LookupReference<TApiName extends string = string> {
+  readonly id: string;
+  readonly apiName?: TApiName;
+}
+
+/** File value accepted by typed record and input helpers. */
+export type FileReference = string | { readonly id: string };
+
+/**
+ * Name-field configuration for a custom object.
+ *
+ * By default, the platform-managed `name` field behaves like a writable string
+ * field on create and update operations. When the object uses an autonumber
+ * name field, create-input types stop requiring `name`, and manifest
+ * compilation emits the wire-level autonumber metadata automatically.
+ */
+export type NameFieldDefinition =
+  | { readonly kind: 'text' }
+  | {
+      readonly kind: 'autonumber';
+      readonly format: string;
+      readonly startingNumber?: number;
+    };
+
+/** Manifest section metadata used by the typed schema layer. */
+export interface SectionDefinition {
+  /** Human-readable section label shown in object page layouts. */
+  readonly name: string;
+  /** Optional stable section id used when manifest output must remain deterministic. */
+  readonly sectionId?: string;
+}
+
+/**
+ * Reusable helper for defining a manifest section.
+ *
+ * The returned value is plain immutable data so teams can share section maps
+ * across files without instantiating manifest classes.
+ *
+ * @param name - Human-readable section label.
+ * @param options - Optional stable section-id metadata.
+ * @returns Immutable section definition.
+ */
+export function section(name: string, options: { sectionId?: string } = {}): SectionDefinition {
+  return Object.freeze({
+    name,
+    ...(options.sectionId != null ? { sectionId: options.sectionId } : {}),
+  });
+}
+
+/** Named map of section definitions keyed by author-facing aliases. */
+export type SectionDefinitions = Readonly<Record<string, SectionDefinition>>;
+
+/**
+ * Base presentation properties shared by every field definition.
+ *
+ * `section` refers to a key in the enclosing object's `sections` map. It is a
+ * plain string in the field factory layer so schemas can be composed cheaply;
+ * the object-definition validator later confirms that the referenced section is
+ * actually declared.
+ *
+ * @typeParam TSectionKey - Allowed section-key union for the enclosing object.
+ */
+export interface FieldPresentationProps<TSectionKey extends string | undefined = string | undefined> {
+  readonly displayName: string;
+  readonly description: string;
+  readonly section?: TSectionKey;
+  /** Whether the backend should track field-level history for this field. */
+  readonly enableHistory?: boolean;
+  /** Additional metadata for formula-field attributes when required by the backend. */
+  readonly formulaAttributeMetas?: CustomObjectFieldFormulaAttrMetas;
+  /** Additional metadata for backend-managed derived aggregate behavior. */
+  readonly derivedAggregatedField?: CustomObjectFieldDerivedAggregatedField;
+  /** Additional metadata for backend-managed computed-field RQL definitions. */
+  readonly rqlDefinition?: CustomObjectFieldRqlDefinition;
+  /** Explicit REST section override used during provisioning. */
+  readonly restSection?: RestCustomObjectFieldSection;
+}
+
+/**
+ * Generic field-definition shape used by all concrete field factories.
+ *
+ * `logicalName`, `apiName`, and `valueType` are compiler-owned metadata slots.
+ * Field factories intentionally leave the first two unset; `defineCustomObject`
+ * fills them in from the surrounding field map so callers do not have to author
+ * any `__c` suffixes manually.
+ *
+ * @typeParam TKind - Discriminant identifying the field variant.
+ * @typeParam TValue - Runtime value type represented by the field.
+ * @typeParam TRequired - Whether the field is required during record creation.
+ * @typeParam TWritable - Whether the field can be written by callers.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ * @typeParam TTargetApiName - Relationship target api name when applicable.
+ */
+export interface FieldDefinitionBase<
+  TKind extends string,
+  TValue,
+  TRequired extends boolean,
+  TWritable extends boolean,
+  TSectionKey extends string | undefined = string | undefined,
+  TTargetApiName extends string | undefined = undefined,
+> extends FieldPresentationProps<TSectionKey> {
+  readonly kind: TKind;
+  readonly required: TRequired;
+  readonly writable: TWritable;
+  readonly targetApiName?: TTargetApiName;
+  readonly logicalName?: string;
+  readonly apiName?: string;
+  readonly __valueType__?: TValue;
+}
+
+/**
+ * Type-level shape produced by {@link text}.
+ *
+ * @typeParam TRequired - Whether the field is required during record creation.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface TextFieldDefinition<
+  TRequired extends boolean = false,
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<'text', string, TRequired, true, TSectionKey> {
+  readonly unique?: boolean;
+  readonly maxLength?: number;
+}
+
+/**
+ * Type-level shape produced by {@link longText}.
+ *
+ * @typeParam TRequired - Whether the field is required during record creation.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface LongTextFieldDefinition<
+  TRequired extends boolean = false,
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<'long-text', string, TRequired, true, TSectionKey> {
+  readonly maxLength?: number;
+}
+
+/**
+ * Type-level shape produced by {@link email}.
+ *
+ * @typeParam TRequired - Whether the field is required during record creation.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface EmailFieldDefinition<
+  TRequired extends boolean = false,
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<'email', string, TRequired, true, TSectionKey> {
+  readonly unique?: boolean;
+}
+
+/**
+ * Type-level shape produced by {@link url}.
+ *
+ * @typeParam TRequired - Whether the field is required during record creation.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface UrlFieldDefinition<
+  TRequired extends boolean = false,
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<'url', string, TRequired, true, TSectionKey> {}
+
+/**
+ * Type-level shape produced by {@link phone}.
+ *
+ * @typeParam TRequired - Whether the field is required during record creation.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface PhoneFieldDefinition<
+  TRequired extends boolean = false,
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<'phone', string, TRequired, true, TSectionKey> {}
+
+/**
+ * Type-level shape produced by {@link number}.
+ *
+ * @typeParam TRequired - Whether the field is required during record creation.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface NumberFieldDefinition<
+  TRequired extends boolean = false,
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<'number', number, TRequired, true, TSectionKey> {
+  readonly unique?: boolean;
+  readonly decimalPlaces?: number;
+}
+
+/**
+ * Type-level shape produced by {@link currency}.
+ *
+ * @typeParam TRequired - Whether the field is required during record creation.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface CurrencyFieldDefinition<
+  TRequired extends boolean = false,
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<'currency', number, TRequired, true, TSectionKey> {
+  readonly currency?: string;
+  readonly decimalPlaces?: number;
+}
+
+/**
+ * Type-level shape produced by {@link percentage}.
+ *
+ * @typeParam TRequired - Whether the field is required during record creation.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface PercentageFieldDefinition<
+  TRequired extends boolean = false,
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<'percentage', number, TRequired, true, TSectionKey> {}
+
+/**
+ * Type-level shape produced by {@link date}.
+ *
+ * @typeParam TRequired - Whether the field is required during record creation.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface DateFieldDefinition<
+  TRequired extends boolean = false,
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<'date', string, TRequired, true, TSectionKey> {}
+
+/**
+ * Type-level shape produced by {@link datetime}.
+ *
+ * @typeParam TRequired - Whether the field is required during record creation.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface DatetimeFieldDefinition<
+  TRequired extends boolean = false,
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<'datetime', string, TRequired, true, TSectionKey> {}
+
+/**
+ * Type-level shape produced by {@link time}.
+ *
+ * @typeParam TRequired - Whether the field is required during record creation.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface TimeFieldDefinition<
+  TRequired extends boolean = false,
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<'time', string, TRequired, true, TSectionKey> {}
+
+/**
+ * Type-level shape produced by {@link select}.
+ *
+ * @typeParam TRequired - Whether the field is required during record creation.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface SelectFieldDefinition<
+  TRequired extends boolean = false,
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<'select', string[], TRequired, true, TSectionKey> {
+  readonly options: readonly string[];
+}
+
+/**
+ * Type-level shape produced by {@link radio}.
+ *
+ * @typeParam TRequired - Whether the field is required during record creation.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface RadioFieldDefinition<
+  TRequired extends boolean = false,
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<'radio', string, TRequired, true, TSectionKey> {
+  readonly options: readonly string[];
+}
+
+/**
+ * Type-level shape produced by {@link boolean}.
+ *
+ * @typeParam TRequired - Whether the field is required during record creation.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface BooleanFieldDefinition<
+  TRequired extends boolean = false,
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<'boolean', boolean, TRequired, true, TSectionKey> {}
+
+/**
+ * Type-level shape produced by {@link file}.
+ *
+ * @typeParam TRequired - Whether the field is required during record creation.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface FileFieldDefinition<
+  TRequired extends boolean = false,
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<'file', FileReference, TRequired, true, TSectionKey> {
+  readonly allowedType: 'images' | 'documents' | 'any';
+}
+
+/**
+ * Minimal identity contract shared by typed custom-object definitions.
+ *
+ * @typeParam TName - Logical custom-object name represented by the identity.
+ */
+export interface CustomObjectIdentity<TName extends LogicalCustomObjectName = LogicalCustomObjectName> {
+  readonly name: TName;
+  readonly apiName: CustomObjectApiName<TName>;
+}
+
+/**
+ * Allowed targets for a lookup field.
+ *
+ * Any structural value with an `apiName` can participate, which lets callers
+ * pass a typed custom-object definition directly without wrapping it first.
+ *
+ * @typeParam TApiName - Target api-name union carried through the type system.
+ */
+export type LookupTarget<TApiName extends string = string> = { readonly apiName: TApiName };
+
+/**
+ * Type-level shape produced by {@link lookup}.
+ *
+ * @typeParam TTarget - Target object or native model referenced by the lookup.
+ * @typeParam TRequired - Whether the lookup is required during record creation.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface LookupFieldDefinition<
+  TTarget extends LookupTarget = LookupTarget,
+  TRequired extends boolean = false,
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<
+    'lookup',
+    LookupReference<TargetApiName<TTarget>>,
+    TRequired,
+    true,
+    TSectionKey,
+    TargetApiName<TTarget>
+  > {
+  readonly target: TTarget;
+  readonly relatedDataLabel?: string;
+  readonly lookupFilterRqlCondition?: string;
+}
+
+/**
+ * Type-level shape produced by {@link parentChild}.
+ *
+ * @typeParam TTarget - Target parent object referenced by the relationship.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface ParentChildFieldDefinition<
+  TTarget extends CustomObjectIdentity = CustomObjectIdentity,
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<
+    'parent-child',
+    LookupReference<TargetApiName<TTarget>>,
+    true,
+    true,
+    TSectionKey,
+    TargetApiName<TTarget>
+  > {
+  readonly target: TTarget;
+  readonly relatedDataLabel?: string;
+  readonly parentChildType?: 'PRIMARY' | 'SECONDARY';
+  readonly enableParentOwnerInheritance?: boolean;
+}
+
+/** Discriminant union used by formula field definitions. */
+export type FormulaFieldKind =
+  | 'formula-text'
+  | 'formula-number'
+  | 'formula-boolean'
+  | 'formula-currency'
+  | 'formula-percentage'
+  | 'formula-date'
+  | 'formula-url';
+
+/** Value-type mapping for each supported formula field kind. */
+export interface FormulaValueByKind {
+  'formula-text': string;
+  'formula-number': number;
+  'formula-boolean': boolean;
+  'formula-currency': number;
+  'formula-percentage': number;
+  'formula-date': string;
+  'formula-url': string;
+}
+
+/**
+ * Type-level shape produced by the {@link formula} helpers.
+ *
+ * @typeParam TFormulaKind - Specific formula-field discriminant.
+ * @typeParam TValue - Runtime value type yielded by the formula.
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export interface FormulaFieldDefinition<
+  TFormulaKind extends FormulaFieldKind = FormulaFieldKind,
+  TValue = FormulaValueByKind[TFormulaKind],
+  TSectionKey extends string | undefined = string | undefined,
+> extends FieldDefinitionBase<TFormulaKind, TValue, false, false, TSectionKey> {
+  readonly formula: string;
+  readonly maxLength?: TFormulaKind extends 'formula-text' ? number : never;
+}
+
+/**
+ * Union of every supported field definition shape.
+ *
+ * @typeParam TSectionKey - Allowed section keys for the enclosing object.
+ */
+export type AnyFieldDefinition<TSectionKey extends string | undefined = string | undefined> =
+  | TextFieldDefinition<boolean, TSectionKey>
+  | LongTextFieldDefinition<boolean, TSectionKey>
+  | EmailFieldDefinition<boolean, TSectionKey>
+  | UrlFieldDefinition<boolean, TSectionKey>
+  | PhoneFieldDefinition<boolean, TSectionKey>
+  | NumberFieldDefinition<boolean, TSectionKey>
+  | CurrencyFieldDefinition<boolean, TSectionKey>
+  | PercentageFieldDefinition<boolean, TSectionKey>
+  | DateFieldDefinition<boolean, TSectionKey>
+  | DatetimeFieldDefinition<boolean, TSectionKey>
+  | TimeFieldDefinition<boolean, TSectionKey>
+  | SelectFieldDefinition<boolean, TSectionKey>
+  | RadioFieldDefinition<boolean, TSectionKey>
+  | BooleanFieldDefinition<boolean, TSectionKey>
+  | FileFieldDefinition<boolean, TSectionKey>
+  | LookupFieldDefinition<LookupTarget, boolean, TSectionKey>
+  | ParentChildFieldDefinition<CustomObjectIdentity, TSectionKey>
+  | FormulaFieldDefinition<FormulaFieldKind, FormulaValueByKind[FormulaFieldKind], TSectionKey>;
+
+/**
+ * Map of logical field names to typed field definitions.
+ *
+ * The field-definition validator adds `apiName` and `logicalName` automatically
+ * when a complete object definition is created.
+ */
+export type FieldDefinitions = Readonly<Record<string, AnyFieldDefinition>>;
+
+/**
+ * Final field-definition shape stored on a compiled custom-object definition.
+ *
+ * @typeParam TFieldName - Logical field name used by authors.
+ * @typeParam TField - Field definition returned by a field factory.
+ */
+export type ResolvedFieldDefinition<TFieldName extends string, TField> = Omit<
+  TField,
+  'logicalName' | 'apiName'
+> & {
+  readonly logicalName: TFieldName;
+  readonly apiName: CustomFieldApiName<TFieldName>;
+};
+
+/**
+ * Final immutable definition returned by {@link defineCustomObject}.
+ *
+ * @typeParam TObjectName - Logical custom-object name.
+ * @typeParam TCategoryName - Logical category name.
+ * @typeParam TSections - Section map available to field definitions.
+ * @typeParam TFields - Field map keyed by logical custom-field names.
+ * @typeParam TNameField - Name-field behavior for the object.
+ */
+export interface CustomObjectDefinition<
+  TObjectName extends LogicalCustomObjectName = LogicalCustomObjectName,
+  TCategoryName extends LogicalCategoryName = LogicalCategoryName,
+  TSections extends SectionDefinitions = {},
+  TFields extends FieldDefinitions = FieldDefinitions,
+  TNameField extends NameFieldDefinition = NameFieldDefinition,
+> extends CustomObjectIdentity<TObjectName> {
+  readonly displayName: string;
+  readonly pluralLabel?: string;
+  readonly category: TCategoryName;
+  /** Optional typed category definition embedded directly into the object definition. */
+  readonly categoryDefinition?: CustomObjectCategoryDefinition<TCategoryName>;
+  /** Optional owning role id applied during REST provisioning / reconciliation. */
+  readonly ownerRole?: string;
+  /** Optional desired history-tracking state observed during metadata reconciliation. */
+  readonly enableHistory?: boolean;
+  readonly categoryApiName: CategoryApiName<TCategoryName>;
+  readonly description: string;
+  readonly icon?: {
+    readonly emoji?: string | null;
+    readonly ripplingIcon?: string | null;
+    readonly s3Bucket?: string;
+    readonly s3Key?: string;
+  };
+  readonly nameField: TNameField;
+  readonly sections: TSections;
+  readonly fields: {
+    readonly [K in Extract<keyof TFields, string>]: ResolvedFieldDefinition<K, TFields[K]>;
+  };
+}
+
+/** Convenience alias for a custom-object definition with all generic slots widened. */
+export type AnyCustomObjectDefinition = CustomObjectDefinition<
+  LogicalCustomObjectName,
+  LogicalCategoryName,
+  SectionDefinitions,
+  FieldDefinitions,
+  NameFieldDefinition
+>;
+
+/**
+ * Extracts the logical field-name union from a custom-object definition.
+ *
+ * @typeParam TDefinition - Object definition whose field names should be extracted.
+ */
+export type FieldNames<TDefinition extends AnyCustomObjectDefinition> = Extract<
+  keyof TDefinition['fields'],
+  string
+>;
+
+/**
+ * Extracts the target api name from a lookup or parent-child target.
+ *
+ * @typeParam TTarget - Target type carrying an `apiName` property.
+ */
+export type TargetApiName<TTarget> =
+  TTarget extends { readonly apiName: infer TApiName extends string } ? TApiName : never;
+
+/**
+ * Type-level value mapping used by record and input utilities.
+ *
+ * @typeParam TField - Field definition whose runtime value type should be inferred.
+ */
+export type FieldValue<TField> = TField extends { readonly __valueType__?: infer TValue } ? TValue : never;
+
+/**
+ * Field-name union containing only writable custom fields.
+ *
+ * @typeParam TDefinition - Object definition whose writable field names should be extracted.
+ */
+export type WritableFieldNames<TDefinition extends AnyCustomObjectDefinition> = {
+  [K in FieldNames<TDefinition>]: TDefinition['fields'][K] extends { writable: true } ? K : never;
+}[FieldNames<TDefinition>];
+
+/**
+ * Field-name union containing only required writable custom fields.
+ *
+ * @typeParam TDefinition - Object definition whose required writable field names should be extracted.
+ */
+export type RequiredWritableFieldNames<TDefinition extends AnyCustomObjectDefinition> = {
+  [K in WritableFieldNames<TDefinition>]: TDefinition['fields'][K] extends { required: true } ? K : never;
+}[WritableFieldNames<TDefinition>];
+
+/**
+ * Field-name union containing writable fields that are optional on create.
+ *
+ * @typeParam TDefinition - Object definition whose optional writable field names should be extracted.
+ */
+export type OptionalWritableFieldNames<TDefinition extends AnyCustomObjectDefinition> = Exclude<
+  WritableFieldNames<TDefinition>,
+  RequiredWritableFieldNames<TDefinition>
+>;
+
+/**
+ * Field-name union containing computed or otherwise read-only custom fields.
+ *
+ * @typeParam TDefinition - Object definition whose read-only field names should be extracted.
+ */
+export type ReadonlyFieldNames<TDefinition extends AnyCustomObjectDefinition> = Exclude<
+  FieldNames<TDefinition>,
+  WritableFieldNames<TDefinition>
+>;
+
+/**
+ * Record-field map containing only custom fields defined by the schema.
+ *
+ * @typeParam TDefinition - Object definition whose custom record fields should be inferred.
+ */
+export type CustomRecordFields<TDefinition extends AnyCustomObjectDefinition> = {
+  [K in FieldNames<TDefinition>]: TDefinition['fields'][K] extends { required: true } ?
+    FieldValue<TDefinition['fields'][K]>
+  : FieldValue<TDefinition['fields'][K]> | null;
+};
+
+/**
+ * Standard Rippling fields present on every custom-object record.
+ *
+ * @typeParam TDefinition - Object definition whose standard record shape should be inferred.
+ */
+export type StandardRecordFields<TDefinition extends AnyCustomObjectDefinition> = {
+  id: string;
+  name: string;
+  created_at: string | null;
+  updated_at: string | null;
+  system_updated_at: string | null;
+  external_id: string | null;
+  owner_role: LookupReference<'Employee'> | null;
+  created_by: LookupReference<'Employee'> | null;
+  last_modified_by: LookupReference<'Employee'> | null;
+} & (TDefinition['nameField'] extends { kind: 'autonumber' } ? {} : {});
+
+/**
+ * Rich record shape for functions, validators, and record-access helpers.
+ *
+ * @typeParam TDefinition - Object definition whose record shape should be inferred.
+ */
+export type RecordShape<TDefinition extends AnyCustomObjectDefinition> = StandardRecordFields<TDefinition> &
+  CustomRecordFields<TDefinition>;
+
+/**
+ * Standard writable fields allowed on record creation.
+ *
+ * @typeParam TDefinition - Object definition whose standard create fields should be inferred.
+ */
+export type StandardCreateFields<TDefinition extends AnyCustomObjectDefinition> =
+  (TDefinition['nameField'] extends { kind: 'autonumber' } ? { name?: never } : { name: string }) & {
+    external_id?: string;
+    owner_role?: string | LookupReference<'Employee'>;
+  };
+
+/**
+ * Create payload derived from the schema definition.
+ *
+ * Custom fields use logical names rather than wire-level `__c` api names.
+ *
+ * @typeParam TDefinition - Object definition whose create payload should be inferred.
+ */
+export type CreateInput<TDefinition extends AnyCustomObjectDefinition> = StandardCreateFields<TDefinition> & {
+  [K in RequiredWritableFieldNames<TDefinition>]: FieldValue<TDefinition['fields'][K]>;
+} & {
+  [K in OptionalWritableFieldNames<TDefinition>]?: FieldValue<TDefinition['fields'][K]>;
+};
+
+/**
+ * Update payload derived from the schema definition.
+ *
+ * Custom fields use logical names rather than wire-level `__c` api names.
+ *
+ * @typeParam TDefinition - Object definition whose update payload should be inferred.
+ */
+export type UpdateInput<TDefinition extends AnyCustomObjectDefinition> = {
+  name?: string;
+  external_id?: string;
+  owner_role?: string | LookupReference<'Employee'>;
+} & {
+  [K in WritableFieldNames<TDefinition>]?: FieldValue<TDefinition['fields'][K]>;
+};