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

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

@@ -0,0 +1,294 @@
+import type { RipplingSDK } from '../../../client';
+import type {
+  ObjectCategory,
+  ObjectCategoryCreateParams,
+  ObjectCategoryUpdateParams,
+} from '../../../resources/object-categories';
+import type { CategoryApiName, LogicalCategoryName } from './types';
+import { toCustomCategoryApiName } from './definition';
+import { validateLogicalCategoryName } from './validation';
+
+/**
+ * Author input accepted by {@link defineCustomObjectCategory}.
+ *
+ * @typeParam TName - Logical category name supplied by the caller.
+ */
+interface CustomObjectCategoryDefinitionInput<TName extends string> {
+  /** Logical unsuffixed snake_case category name. */
+  readonly name: LogicalCategoryName<TName>;
+  /** Human-readable display name applied after creation. */
+  readonly displayName: string;
+  /** Optional category description. */
+  readonly description?: string;
+}
+
+/** Immutable typed category definition used by provisioning and lifecycle helpers. */
+export interface CustomObjectCategoryDefinition<TName extends LogicalCategoryName = LogicalCategoryName> {
+  /** Logical unsuffixed snake_case category name. */
+  readonly name: TName;
+  /** Compiled wire-level category api name. */
+  readonly apiName: CategoryApiName<TName>;
+  /** Human-readable display name. */
+  readonly displayName: string;
+  /** Optional category description. */
+  readonly description?: string;
+}
+
+/** Result returned by category provisioning helpers. */
+export interface ProvisionedCustomObjectCategory<TName extends LogicalCategoryName = LogicalCategoryName> {
+  /** Source typed category definition. */
+  readonly definition: CustomObjectCategoryDefinition<TName>;
+  /** Response returned by `client.objectCategories.create(...)`. */
+  readonly createdCategory: ObjectCategory;
+  /** Response returned by `client.objectCategories.update(...)`. */
+  readonly updatedCategory: ObjectCategory;
+}
+
+/** Lifecycle action emitted by category reconciliation helpers. */
+export type CustomObjectCategoryLifecycleAction = 'created' | 'updated' | 'unchanged';
+
+/** Result returned by category reconciliation helpers. */
+export interface ReconciledCustomObjectCategory<TName extends LogicalCategoryName = LogicalCategoryName> {
+  /** Source typed category definition. */
+  readonly definition: CustomObjectCategoryDefinition<TName>;
+  /** Whether the remote category was created, updated, or already matched. */
+  readonly action: CustomObjectCategoryLifecycleAction;
+  /** Remote category after reconciliation. */
+  readonly category: ObjectCategory;
+}
+
+/** Options for category provisioning and reconciliation helpers. */
+export interface CustomObjectCategoryMutationOptions {
+  /** Whether to apply the follow-up display-metadata update. Defaults to `true`. */
+  readonly updateDisplayMetadata?: boolean;
+}
+
+/**
+ * Creates an immutable typed custom-object category definition.
+ *
+ * @param definition - Logical category metadata to normalize and freeze.
+ * @returns Immutable typed category definition with compiled API name.
+ * @typeParam TName - Logical category name supplied by the caller.
+ */
+export function defineCustomObjectCategory<TName extends string>(
+  definition: CustomObjectCategoryDefinitionInput<TName>,
+): Readonly<CustomObjectCategoryDefinition<LogicalCategoryName<TName>>> {
+  validateLogicalCategoryName(definition.name);
+  return Object.freeze({
+    name: definition.name,
+    apiName: toCustomCategoryApiName(definition.name),
+    displayName: definition.displayName,
+    ...(definition.description != null ? { description: definition.description } : {}),
+  }) as Readonly<CustomObjectCategoryDefinition<LogicalCategoryName<TName>>>;
+}
+
+/**
+ * Builds the low-level create payload for an object category.
+ *
+ * @param definition - Typed category definition to compile.
+ * @returns REST create payload using the logical category name.
+ * @typeParam TName - Logical category name carried by the definition.
+ */
+export function buildObjectCategoryCreateParams<TName extends LogicalCategoryName>(
+  definition: CustomObjectCategoryDefinition<TName>,
+): ObjectCategoryCreateParams {
+  return {
+    name: definition.name,
+    ...(definition.description != null ? { description: definition.description } : {}),
+  };
+}
+
+/**
+ * Builds the low-level update payload for an object category.
+ *
+ * @param definition - Typed category definition to compile.
+ * @returns REST update payload using human-facing display metadata.
+ * @typeParam TName - Logical category name carried by the definition.
+ */
+export function buildObjectCategoryUpdateParams<TName extends LogicalCategoryName>(
+  definition: CustomObjectCategoryDefinition<TName>,
+): ObjectCategoryUpdateParams {
+  return {
+    name: definition.displayName,
+    ...(definition.description != null ? { description: definition.description } : {}),
+  };
+}
+
+/**
+ * Returns whether one public category DTO matches the typed category definition by currently visible names.
+ *
+ * @param category - Public category DTO returned by the REST API.
+ * @param definition - Typed category definition being matched.
+ * @returns Whether the visible name matches either the logical or display name.
+ * @typeParam TName - Logical category name carried by the definition.
+ */
+function isMatchingCategoryName<TName extends LogicalCategoryName>(
+  category: ObjectCategory,
+  definition: CustomObjectCategoryDefinition<TName>,
+): boolean {
+  return category.name === definition.name || category.name === definition.displayName;
+}
+
+/**
+ * Lists all public category DTOs that ambiguously or exactly match one typed definition.
+ *
+ * @param client - SDK client used to enumerate categories.
+ * @param definition - Typed category definition being matched.
+ * @returns Frozen list of public categories whose visible names match.
+ * @typeParam TName - Logical category name carried by the definition.
+ */
+async function listMatchingCategories<TName extends LogicalCategoryName>(
+  client: RipplingSDK,
+  definition: CustomObjectCategoryDefinition<TName>,
+): Promise<readonly ObjectCategory[]> {
+  const matches: ObjectCategory[] = [];
+  for await (const category of client.objectCategories.list()) {
+    if (isMatchingCategoryName(category, definition)) {
+      matches.push(category);
+    }
+  }
+  return Object.freeze(matches);
+}
+
+/**
+ * Returns the single public category matching one typed definition or throws when the match is ambiguous.
+ *
+ * @param client - SDK client used to enumerate categories.
+ * @param definition - Typed category definition being matched.
+ * @returns Matching public category, if any.
+ * @throws Error when multiple public categories match the visible names.
+ * @typeParam TName - Logical category name carried by the definition.
+ */
+async function getSingleMatchingCategory<TName extends LogicalCategoryName>(
+  client: RipplingSDK,
+  definition: CustomObjectCategoryDefinition<TName>,
+): Promise<ObjectCategory | undefined> {
+  const matches = await listMatchingCategories(client, definition);
+  if (matches.length <= 1) return matches[0];
+
+  throw new Error(
+    `Ambiguous category match for "${definition.name}" / "${definition.displayName}". ` +
+      `Matched ids: ${matches.map((category) => category.id).join(', ')}.`,
+  );
+}
+
+/**
+ * Creates one typed custom-object category through the REST SDK.
+ *
+ * @param client - SDK client used to call the category APIs.
+ * @param definition - Typed category definition to provision.
+ * @param options - Provisioning behavior flags for display-metadata updates.
+ * @returns Frozen summary of the created and updated backend category DTOs.
+ * @typeParam TName - Logical category name carried by the definition.
+ */
+export async function provisionCustomObjectCategoryDefinition<TName extends LogicalCategoryName>(
+  client: RipplingSDK,
+  definition: CustomObjectCategoryDefinition<TName>,
+  options: CustomObjectCategoryMutationOptions = {},
+): Promise<ProvisionedCustomObjectCategory<TName>> {
+  const createdCategory = await client.objectCategories.create(buildObjectCategoryCreateParams(definition));
+  const updatedCategory =
+    options.updateDisplayMetadata ?? true ?
+      await client.objectCategories.update(createdCategory.id, buildObjectCategoryUpdateParams(definition))
+    : createdCategory;
+
+  return Object.freeze({ definition, createdCategory, updatedCategory });
+}
+
+/**
+ * Creates multiple typed custom-object categories through the REST SDK.
+ *
+ * @param client - SDK client used to call the category APIs.
+ * @param definitions - Typed category definitions to provision.
+ * @param options - Provisioning behavior flags shared across the batch.
+ * @returns Frozen batch of provisioning results in input order.
+ */
+export async function provisionCustomObjectCategoryDefinitions(
+  client: RipplingSDK,
+  definitions: readonly CustomObjectCategoryDefinition[],
+  options: CustomObjectCategoryMutationOptions = {},
+): Promise<readonly ProvisionedCustomObjectCategory[]> {
+  const results: ProvisionedCustomObjectCategory[] = [];
+  for (const definition of definitions) {
+    results.push(await provisionCustomObjectCategoryDefinition(client, definition, options));
+  }
+  return Object.freeze(results);
+}
+
+/**
+ * Reconciles one typed category definition against the backend by name.
+ *
+ * @param client - SDK client used to call the category APIs.
+ * @param definition - Typed category definition to reconcile.
+ * @param options - Reconciliation behavior flags for display-metadata updates.
+ * @returns Frozen reconciliation result describing the final backend category state.
+ * @typeParam TName - Logical category name carried by the definition.
+ */
+export async function reconcileCustomObjectCategoryDefinition<TName extends LogicalCategoryName>(
+  client: RipplingSDK,
+  definition: CustomObjectCategoryDefinition<TName>,
+  options: CustomObjectCategoryMutationOptions = {},
+): Promise<ReconciledCustomObjectCategory<TName>> {
+  const existing = await getSingleMatchingCategory(client, definition);
+  if (existing == null) {
+    const provisioned = await provisionCustomObjectCategoryDefinition(client, definition, options);
+    return Object.freeze({
+      definition,
+      action: 'created' as const,
+      category: provisioned.updatedCategory,
+    });
+  }
+
+  const shouldUpdate =
+    (options.updateDisplayMetadata ?? true) &&
+    (existing.name !== definition.displayName ||
+      (existing.description ?? '') !== (definition.description ?? ''));
+
+  if (!shouldUpdate) {
+    return Object.freeze({ definition, action: 'unchanged', category: existing });
+  }
+
+  const updated = await client.objectCategories.update(
+    existing.id,
+    buildObjectCategoryUpdateParams(definition),
+  );
+  return Object.freeze({ definition, action: 'updated', category: updated });
+}
+
+/**
+ * Reconciles multiple typed category definitions against the backend by name.
+ *
+ * @param client - SDK client used to call the category APIs.
+ * @param definitions - Typed category definitions to reconcile.
+ * @param options - Reconciliation behavior flags shared across the batch.
+ * @returns Frozen batch of reconciliation results in input order.
+ */
+export async function reconcileCustomObjectCategoryDefinitions(
+  client: RipplingSDK,
+  definitions: readonly CustomObjectCategoryDefinition[],
+  options: CustomObjectCategoryMutationOptions = {},
+): Promise<readonly ReconciledCustomObjectCategory[]> {
+  const results: ReconciledCustomObjectCategory[] = [];
+  for (const definition of definitions) {
+    results.push(await reconcileCustomObjectCategoryDefinition(client, definition, options));
+  }
+  return Object.freeze(results);
+}
+
+/**
+ * Deletes a category that matches the typed definition's logical or display name.
+ *
+ * @param client - SDK client used to call the category APIs.
+ * @param definition - Typed category definition used to find the category to delete.
+ * @returns Whether a matching category existed and was deleted.
+ * @typeParam TName - Logical category name carried by the definition.
+ */
+export async function deleteCustomObjectCategoryDefinition<TName extends LogicalCategoryName>(
+  client: RipplingSDK,
+  definition: CustomObjectCategoryDefinition<TName>,
+): Promise<boolean> {
+  const existing = await getSingleMatchingCategory(client, definition);
+  if (existing == null) return false;
+  await client.objectCategories.delete(existing.id);
+  return true;
+}

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

@@ -0,0 +1,373 @@
+import type { CustomObjectCategoryDefinition } from './category';
+import type {
+  AnyCustomObjectDefinition,
+  AnyFieldDefinition,
+  CategoryApiName,
+  CustomObjectApiName,
+  CustomObjectDefinition,
+  FieldDefinitions,
+  FieldNames,
+  LogicalCategoryName,
+  LogicalCustomFieldName,
+  LogicalCustomObjectName,
+  NameFieldDefinition,
+  ResolvedFieldDefinition,
+  SectionDefinitions,
+} from './types';
+import {
+  validateCustomObjectDefinition,
+  validateLogicalCategoryName,
+  validateLogicalCustomFieldName,
+  validateLogicalCustomObjectName,
+} from './validation';
+
+/**
+ * Internal input shape accepted by {@link defineCustomObject} before normalization.
+ *
+ * @typeParam TObjectName - Logical custom-object name for the definition.
+ * @typeParam TCategoryName - Logical category name associated with the object.
+ * @typeParam TSections - Section map available to field definitions.
+ * @typeParam TFields - Field map keyed by logical custom-field names.
+ * @typeParam TNameField - Optional name-field behavior supplied by the caller.
+ */
+type CategoryInput<TCategoryName extends string> =
+  | LogicalCategoryName<TCategoryName>
+  | CustomObjectCategoryDefinition<LogicalCategoryName<TCategoryName>>;
+
+/**
+ * Internal input shape accepted by {@link defineCustomObject} before normalization.
+ *
+ * @typeParam TObjectName - Logical custom-object name for the definition.
+ * @typeParam TCategoryName - Logical category name associated with the object.
+ * @typeParam TSections - Section map available to field definitions.
+ * @typeParam TFields - Field map keyed by logical custom-field names.
+ * @typeParam TNameField - Optional name-field behavior supplied by the caller.
+ */
+interface CustomObjectDefinitionInput<
+  TObjectName extends string,
+  TCategoryName extends string,
+  TSections extends SectionDefinitions,
+  TFields extends FieldDefinitions,
+  TNameField extends NameFieldDefinition,
+> {
+  readonly name: LogicalCustomObjectName<TObjectName>;
+  readonly displayName: string;
+  readonly pluralLabel?: string;
+  readonly category: CategoryInput<TCategoryName>;
+  readonly ownerRole?: string;
+  readonly enableHistory?: boolean;
+  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: ValidateFieldMap<TFields>;
+}
+
+/**
+ * Rejects extension objects that try to redefine keys already present on the base definition.
+ *
+ * @typeParam TExisting - Existing key set on the base definition.
+ * @typeParam TAdded - Proposed extension object.
+ */
+type NoOverlappingKeys<TExisting extends object, TAdded extends object> = Extract<
+  keyof TExisting,
+  keyof TAdded
+> extends never ?
+  TAdded
+: never;
+
+/**
+ * Converts a logical field map into a version whose keys must all satisfy the
+ * logical custom-field name contract.
+ *
+ * @typeParam TFields - Candidate logical field map supplied by callers.
+ */
+type ValidateFieldMap<TFields extends FieldDefinitions> = {
+  readonly [K in keyof TFields]: K extends string ?
+    LogicalCustomFieldName<K> extends never ?
+      never
+    : TFields[K]
+  : never;
+};
+
+/**
+ * Recursively freezes author-authored schema definitions.
+ *
+ * The schema layer is intended to act like durable configuration data rather
+ * than mutable runtime state, so this helper aggressively removes mutation as a
+ * failure mode after validation succeeds.
+ *
+ * @typeParam T - Value being frozen.
+ */
+/**
+ * Deeply freezes a schema fragment after validation succeeds.
+ *
+ * @param value - Value to recursively freeze in place.
+ * @returns The same value, now deeply frozen where applicable.
+ * @typeParam T - Value being frozen.
+ */
+function deepFreeze<T>(value: T): T {
+  if (value == null || typeof value !== 'object') return value;
+
+  for (const child of Object.values(value as Record<string, unknown>)) {
+    deepFreeze(child);
+  }
+
+  return Object.freeze(value);
+}
+
+/**
+ * Appends the platform-required `__c` suffix to a logical custom-object name.
+ *
+ * @param name - Logical unsuffixed custom-object name.
+ * @returns Wire-level custom-object API name with the required `__c` suffix.
+ * @typeParam TObjectName - Logical custom-object name to compile.
+ */
+export function toCustomObjectApiName<TObjectName extends string>(
+  name: LogicalCustomObjectName<TObjectName>,
+): CustomObjectApiName<TObjectName> {
+  return `${name}__c` as CustomObjectApiName<TObjectName>;
+}
+
+/**
+ * Appends the platform-required `__c` suffix to a logical custom-field name.
+ *
+ * @param name - Logical unsuffixed custom-field name.
+ * @returns Wire-level custom-field API name with the required `__c` suffix.
+ * @typeParam TFieldName - Logical custom-field name to compile.
+ */
+export function toCustomFieldApiName<TFieldName extends string>(
+  name: LogicalCustomFieldName<TFieldName>,
+): `${TFieldName}__c` {
+  return `${name}__c`;
+}
+
+/**
+ * Appends the platform-required `__c` suffix to a logical category name.
+ *
+ * @param name - Logical unsuffixed category name.
+ * @returns Wire-level category API name with the required `__c` suffix.
+ * @typeParam TCategoryName - Logical category name to compile.
+ */
+export function toCustomCategoryApiName<TCategoryName extends string>(
+  name: LogicalCategoryName<TCategoryName>,
+): CategoryApiName<TCategoryName> {
+  return `${name}__c` as CategoryApiName<TCategoryName>;
+}
+
+/**
+ * Defines an immutable, strongly typed custom-object schema.
+ *
+ * Callers author only logical snake_case names. The returned value includes the
+ * derived wire-level api names so downstream tooling can emit valid manifest
+ * payloads without requiring authors to know about the `__c` suffix contract.
+ *
+ * @typeParam TObjectName - Logical custom-object name for the definition.
+ * @typeParam TCategoryName - Logical category name associated with the object.
+ * @typeParam TSections - Section map available to field definitions.
+ * @typeParam TFields - Field map keyed by logical custom-field names.
+ * @param definition - Author-facing typed schema definition to normalize, validate, and freeze.
+ * @returns Immutable normalized custom-object definition with compiled field and object API names.
+ * @typeParam TNameField - Name-field behavior for the object.
+ */
+export function defineCustomObject<
+  TObjectName extends string,
+  TCategoryName extends string,
+  TSections extends SectionDefinitions = {},
+  TFields extends FieldDefinitions = FieldDefinitions,
+  TNameField extends NameFieldDefinition = { kind: 'text' },
+>(
+  definition: CustomObjectDefinitionInput<TObjectName, TCategoryName, TSections, TFields, TNameField>,
+): Readonly<
+  CustomObjectDefinition<
+    LogicalCustomObjectName<TObjectName>,
+    LogicalCategoryName<TCategoryName>,
+    TSections,
+    TFields,
+    TNameField
+  >
+> {
+  validateLogicalCustomObjectName(definition.name);
+
+  const categoryDefinition = typeof definition.category === 'string' ? undefined : definition.category;
+  const categoryName =
+    typeof definition.category === 'string' ? definition.category : definition.category.name;
+  const categoryApiName =
+    typeof definition.category === 'string' ?
+      toCustomCategoryApiName(definition.category)
+    : definition.category.apiName;
+
+  validateLogicalCategoryName(categoryName);
+
+  const resolvedFields = Object.fromEntries(
+    Object.entries(definition.fields).map(([logicalName, field]) => {
+      validateLogicalCustomFieldName(logicalName);
+      return [
+        logicalName,
+        {
+          ...field,
+          logicalName,
+          apiName: toCustomFieldApiName(logicalName),
+        },
+      ];
+    }),
+  ) as unknown as {
+    readonly [K in Extract<keyof TFields, string>]: ResolvedFieldDefinition<K, TFields[K]>;
+  };
+
+  const normalized = {
+    name: definition.name,
+    apiName: toCustomObjectApiName(definition.name) as CustomObjectApiName<
+      LogicalCustomObjectName<TObjectName>
+    >,
+    displayName: definition.displayName,
+    ...(definition.pluralLabel != null ? { pluralLabel: definition.pluralLabel } : {}),
+    category: categoryName,
+    ...(categoryDefinition != null ? { categoryDefinition } : {}),
+    ...(definition.ownerRole != null ? { ownerRole: definition.ownerRole } : {}),
+    ...(definition.enableHistory != null ? { enableHistory: definition.enableHistory } : {}),
+    categoryApiName: categoryApiName as CategoryApiName<LogicalCategoryName<TCategoryName>>,
+    description: definition.description,
+    ...(definition.icon != null ? { icon: definition.icon } : {}),
+    nameField: (definition.nameField ?? { kind: 'text' }) as TNameField,
+    sections: (definition.sections ?? ({} as TSections)) as TSections,
+    fields: resolvedFields,
+  };
+
+  const issues = validateCustomObjectDefinition(normalized as unknown as AnyCustomObjectDefinition);
+  if (issues.length > 0) {
+    throw new Error(
+      `Invalid custom object definition for "${definition.name}":\n` +
+        issues.map((issue) => `- ${issue.path}: ${issue.message}`).join('\n'),
+    );
+  }
+
+  return deepFreeze(normalized) as Readonly<
+    CustomObjectDefinition<
+      LogicalCustomObjectName<TObjectName>,
+      LogicalCategoryName<TCategoryName>,
+      TSections,
+      TFields,
+      TNameField
+    >
+  >;
+}
+
+/**
+ * Extends an existing object definition without losing type information.
+ *
+ * This helper is useful when a platform package wants to publish a base schema
+ * and another package wants to add fields or sections in a type-safe way.
+ *
+ * @typeParam TBase - Existing object definition being extended.
+ * @typeParam TAddedSections - New section definitions merged into the base object.
+ * @param base - Existing typed object definition to extend.
+ * @param extension - Additional metadata, sections, and fields to merge into the base definition.
+ * @returns New immutable custom-object definition preserving the combined type information.
+ * @typeParam TAddedFields - New field definitions merged into the base object.
+ */
+export function extendCustomObject<
+  TBase extends AnyCustomObjectDefinition,
+  TAddedSections extends SectionDefinitions = {},
+  TAddedFields extends FieldDefinitions = {},
+>(
+  base: TBase,
+  extension: {
+    readonly displayName?: string;
+    readonly pluralLabel?: string;
+    readonly ownerRole?: string;
+    readonly enableHistory?: boolean;
+    readonly description?: string;
+    readonly icon?: TBase['icon'];
+    readonly sections?: NoOverlappingKeys<TBase['sections'], TAddedSections>;
+    readonly fields?: NoOverlappingKeys<TBase['fields'], ValidateFieldMap<TAddedFields>>;
+  },
+): Readonly<
+  CustomObjectDefinition<
+    TBase['name'],
+    TBase['category'],
+    TBase['sections'] & TAddedSections,
+    Omit<TBase['fields'], never> & TAddedFields,
+    TBase['nameField']
+  >
+> {
+  const mergedSections = {
+    ...base.sections,
+    ...(extension.sections ?? {}),
+  } as TBase['sections'] & TAddedSections;
+
+  const mergedFields = Object.fromEntries(
+    Object.entries({ ...base.fields, ...(extension.fields ?? {}) }).map(([logicalName, field]) => [
+      logicalName,
+      {
+        ...field,
+        logicalName,
+        apiName: toCustomFieldApiName(logicalName as LogicalCustomFieldName<string>),
+      },
+    ]),
+  ) as unknown as Omit<TBase['fields'], never> & TAddedFields;
+
+  return defineCustomObject({
+    name: base.name,
+    displayName: extension.displayName ?? base.displayName,
+    ...(extension.pluralLabel != null || base.pluralLabel != null ?
+      { pluralLabel: extension.pluralLabel ?? base.pluralLabel }
+    : {}),
+    ...(extension.ownerRole != null || base.ownerRole != null ?
+      { ownerRole: extension.ownerRole ?? base.ownerRole }
+    : {}),
+    ...(extension.enableHistory != null || base.enableHistory != null ?
+      { enableHistory: extension.enableHistory ?? base.enableHistory }
+    : {}),
+    category: base.categoryDefinition ?? base.category,
+    description: extension.description ?? base.description,
+    ...((extension.icon ?? base.icon) != null ? { icon: extension.icon ?? base.icon } : {}),
+    nameField: base.nameField,
+    sections: mergedSections,
+    fields: mergedFields as ValidateFieldMap<Omit<TBase['fields'], never> & TAddedFields>,
+  });
+}
+
+/**
+ * Returns the logical custom field names defined on an object.
+ *
+ * @param definition - Object definition whose logical field names should be returned.
+ * @returns Frozen array of logical field names from the definition.
+ * @typeParam TDefinition - Object definition whose field names should be returned.
+ */
+export function fieldNames<TDefinition extends AnyCustomObjectDefinition>(
+  definition: TDefinition,
+): ReadonlyArray<FieldNames<TDefinition>> {
+  return Object.freeze(Object.keys(definition.fields) as FieldNames<TDefinition>[]);
+}
+
+/**
+ * Retrieves a field definition by logical field name with precise typing.
+ *
+ * @param definition - Object definition that owns the field.
+ * @param fieldName - Logical field name to retrieve.
+ * @returns Precisely typed field definition for the requested logical field name.
+ * @typeParam TDefinition - Object definition that owns the field.
+ * @typeParam TFieldName - Logical field name being retrieved.
+ */
+export function getFieldDefinition<
+  TDefinition extends AnyCustomObjectDefinition,
+  TFieldName extends FieldNames<TDefinition>,
+>(definition: TDefinition, fieldName: TFieldName): TDefinition['fields'][TFieldName] {
+  return (definition.fields as Record<string, unknown>)[fieldName] as TDefinition['fields'][TFieldName];
+}
+
+/**
+ * Returns whether one typed field definition is writable by record create/update helpers.
+ *
+ * @param field - Typed field definition to inspect.
+ * @returns Whether the field may be written by callers.
+ */
+export function isWritableField(field: AnyFieldDefinition): boolean {
+  return field.writable;
+}