@dyrected/core 2.18.0 → 2.19.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { F as Field, B as Block, C as CollectionConfig, D as DyrectedConfig, A as AdminAuthConfig, P as PublicAdminAuthConfig, G as GlobalConfig, a as DeclarativeHookExpression, W as WorkflowConfig, b as AuthenticatedUser, c as WorkflowTransition, L as LifecycleEventName, d as LifecycleEvent, e as DatabaseAdapter, f as BaseDocument, H as HookRequestContext, T as TaskRunResult, g as TaskConfig, h as DetailActionOptions, i as DetailAction, j as DetailComputedOptions, k as ComputedHandler, l as DetailComputed, m as DetailCustomOptions, n as DetailCustom, o as DetailDividerOptions, p as DetailDivider, q as DisplayFieldOptions, r as DetailField, s as DetailItem, t as DetailGridOptions, u as DetailGrid, v as DetailRepeatOptions, w as DetailRepeat, x as DetailSectionOptions, y as DetailSection, z as DetailTabOptions, E as DetailTab, I as DetailTabsOptions, J as DetailTabs, K as DetailTextOptions, M as DetailText, N as DetailSchema, O as DyrectedContext, Q as AIConfig, R as AIPIIConfig, S as IdStrategy, U as CompiledNavTree, V as CompiledNavItem, X as UserNavigationPreferences, Y as DefineWorkspaceOptions, Z as ArrayField, _ as FieldType, $ as BooleanField, a0 as AuthConfig, a1 as AccessPolicyResolver, a2 as DateField, a3 as DateTimeField, a4 as EmailField, a5 as IconField, a6 as ImageField, a7 as JoinField, a8 as JsonField, a9 as MoneyField, aa as MultiSelectField, ab as NumberField, ac as ObjectField, ad as RadioField, ae as RelationshipField, af as RichTextField, ag as RowField, ah as SelectField, ai as TextField, aj as TextareaField, ak as TimeField, al as UrlField } from './app-Dd9cBbCs.cjs';
-export { am as AIAction, an as AIActionStatus, ao as AIActionType, ap as AIAuditActionType, aq as AIAuditRecord, ar as AIChunk, as as AIMessage, at as AIPIIPattern, au as AIRateLimitResult, av as AIRateLimitStore, aw as AIThread, ax as AIToolContext, ay as AIToolDefinition, az as AI_ACTIONS_COLLECTION, aA as AI_AUDIT_COLLECTION, aB as AI_CHUNKS_COLLECTION, aC as AI_MESSAGES_COLLECTION, aD as AI_THREADS_COLLECTION, aE as AccessConfig, aF as AccessFunction, aG as AccessFunctionArgs, aH as AccessResult, aI as AccessRule, aJ as ActionConfig, aK as ActionConfigBase, aL as ActionConfigWithHandler, aM as ActionConfigWithMutation, aN as ActionContext, aO as ActionType, aP as AdminAuthAccessResolution, aQ as AdminAuthClaimMapping, aR as AdminAuthMember, aS as AdminAuthProvider, aT as AdminAuthProviderMembersConfig, aU as AdminAuthProvisioningMode, aV as AdminAuthResolveAccessArgs, aW as AdminAuthResolvedIdentity, aX as AdminConfig, aY as AdminDashboardComponentSlots, aZ as AdminIconName, a_ as AggregateArgs, a$ as AggregateCastType, b0 as AggregateCollectionResult, b1 as AggregateInput, b2 as AggregateOperation, b3 as AggregateResult, b4 as BaseAdminAuthProvider, b5 as BaseFieldAdmin, b6 as BlockVariant, b7 as BlocksField, b8 as BooleanFieldAdmin, b9 as BooleanFormat, ba as CURRENT_NAV_PREFERENCES_VERSION, bb as CalendarViewConfig, bc as CardsViewConfig, bd as CharacterLimitFieldAdmin, be as CharacterLimitFieldConfig, bf as CollectionAfterChangeHook, bg as CollectionAfterDeleteHook, bh as CollectionAfterReadHook, bi as CollectionAfterReadHookEntry, bj as CollectionAfterTransitionHook, bk as CollectionBeforeChangeHook, bl as CollectionBeforeChangeHookEntry, bm as CollectionBeforeCommitHook, bn as CollectionBeforeDeleteHook, bo as CollectionBeforeReadHook, bp as CollectionBeforeReadHookEntry, bq as CollectionBeforeTransitionHook, br as CollectionIndex, bs as CollectionListComponentSlots, bt as CollectionRAGConfig, bu as CollectionSchemaResult, bv as CollectionSummaryResult, bw as CollectionViewComponentSlots, bx as CompiledNavGroup, by as CountOperation, bz as CustomAdminAuthProvider, bA as DEFAULT_USER_NAV_PREFERENCES, bB as DateFieldAdmin, bC as DateFormat, bD as DefaultValueContext, bE as DefineActionOptions, bF as DefineCalendarViewOptions, bG as DefineCardsViewOptions, bH as DefineGanttViewOptions, bI as DefineKanbanViewOptions, bJ as DefineTableViewOptions, bK as DefineViewBaseOptions, bL as DefineViewOptions, bM as DetailSpan, bN as DisplayTone, bO as DisplayVariant, bP as DistinctCountOperation, bQ as DistinctValuesOperation, bR as DynamicOptionItem, bS as DynamicOptionsConfig, bT as DynamicOptionsResolver, bU as DynamicOptionsResolverArgs, bV as DyrectedAIContext, bW as DyrectedLoggerConfig, bX as DyrectedObservabilityConfig, bY as EmailFieldAdmin, bZ as FieldAdminHooks, b_ as FieldAdminOnChangeHook, b$ as FieldAdminOnChangeHookArgs, c0 as FieldAdminOptionsHook, c1 as FieldAdminOptionsHookArgs, c2 as FieldAdminOptionsHookResult, c3 as FieldAfterReadHook, c4 as FieldAfterReadHookArgs, c5 as FieldBase, c6 as FieldBeforeChangeHook, c7 as FieldBeforeChangeHookArgs, c8 as FieldHook, c9 as FieldHooks, ca as FileData, cb as GanttViewConfig, cc as GetDocumentResult, cd as GlobalAfterChangeHook, ce as GlobalAfterReadHook, cf as GlobalAfterReadHookEntry, cg as GlobalBeforeChangeHook, ch as GlobalBeforeChangeHookEntry, ci as GlobalBeforeReadHook, cj as GlobalBeforeReadHookEntry, ck as GlobalRAGConfig, cl as GlobalSchemaResult, cm as GlobalSummaryResult, cn as HeadingLevel, co as HookFunction, cp as IconFieldAdmin, cq as ImageService, cr as ImageTransformOptions, cs as InferAggregateResult, ct as JoinFieldAdmin, cu as JsonFieldAdmin, cv as JsonFormat, cw as KanbanViewConfig, cx as LIFECYCLE_EVENT_NAMES, cy as LifecycleEventHandler, cz as LinkFormat, cA as MetricColor, cB as MoneyFieldAdmin, cC as MoneyFieldConfig, cD as MultiSelectFieldAdmin, cE as NamedAccessPolicy, cF as NavBadgeConfig, cG as NavGroup, cH as NumberFieldAdmin, cI as NumberFormat, cJ as NumberLimitFieldAdmin, cK as NumberLimitFieldConfig, cL as NumericOperation, cM as NumericUpdateOperator, cN as OIDCAdminAuthProvider, cO as OptionFormat, cP as PaginatedResult, cQ as PinnedNavItemRef, cR as PublicAdminAuthProvider, cS as QueryCollectionResult, cT as RAGSearchResult, cU as RadioFieldAdmin, cV as RateLimitConfig, cW as ReadonlyDatabaseAdapter, cX as RichTextFeature, cY as RichTextFieldConfig, cZ as SelectFieldAdmin, c_ as SqlWhereResult, c$ as StorageAdapter, d0 as TableViewConfig, d1 as TaskContext, d2 as TaskLogger, d3 as TaskRunStatus, d4 as TextFieldAdmin, d5 as TextFormat, d6 as TextareaFieldAdmin, d7 as TrustProxyConfig, d8 as TypedField, d9 as UploadConfig, da as UrlFieldAdmin, db as UrlLinkValue, dc as ViewActionFeatures, dd as ViewComponentSlots, de as ViewConfig, df as ViewConfigBase, dg as ViewLayout, dh as ViewMetric, di as ViewSubMetric, dj as WhereClause, dk as WhereOperator, dl as WhereOperatorName, dm as WordLimitFieldAdmin, dn as WordLimitFieldConfig, dp as WorkflowMetadata, dq as WorkflowOnTransitionContext, dr as WorkflowOnTransitionHook, ds as WorkflowRole, dt as WorkflowState, du as WorkflowTransitionContext, dv as coerceBooleanWhere, dw as defineAction, dx as defineCalendarView, dy as defineCardsView, dz as defineGanttView, dA as defineKanbanView, dB as defineTableView, dC as defineView, dD as defineWorkspace, dE as isAICollection, dF as parseMongoWhere, dG as parseSqlWhere } from './app-Dd9cBbCs.cjs';
+import { F as Field, B as Block, C as CollectionConfig, D as DyrectedConfig, A as AdminAuthConfig, P as PublicAdminAuthConfig, G as GlobalConfig, a as DeclarativeHookExpression, W as WorkflowConfig, b as AuthenticatedUser, c as WorkflowTransition, L as LifecycleEventName, d as LifecycleEvent, e as DatabaseAdapter, f as BaseDocument, H as HookRequestContext, T as TaskRunResult, g as TaskConfig, h as DetailActionOptions, i as DetailAction, j as DetailComputedOptions, k as ComputedHandler, l as DetailComputed, m as DetailCustomOptions, n as DetailCustom, o as DetailDividerOptions, p as DetailDivider, q as DisplayFieldOptions, r as DetailField, s as DetailItem, t as DetailGridOptions, u as DetailGrid, v as DetailRepeatOptions, w as DetailRepeat, x as DetailSectionOptions, y as DetailSection, z as DetailTabOptions, E as DetailTab, I as DetailTabsOptions, J as DetailTabs, K as DetailTextOptions, M as DetailText, N as DetailSchema, O as DyrectedContext, Q as AIConfig, R as AIPIIConfig, S as IdStrategy, U as CompiledNavTree, V as CompiledNavItem, X as UserNavigationPreferences, Y as DefineWorkspaceOptions, Z as ViewConfig, _ as DateTimeField, $ as RelationshipField, a0 as SelectField, a1 as ArrayField, a2 as FieldType, a3 as BooleanField, a4 as AuthConfig, a5 as AccessPolicyResolver, a6 as DateField, a7 as TextField, a8 as EmailField, a9 as IconField, aa as ImageField, ab as JoinField, ac as JsonField, ad as MoneyField, ae as MultiSelectField, af as NumberField, ag as ObjectField, ah as RadioField, ai as RichTextField, aj as RowField, ak as TextareaField, al as TimeField, am as UrlField } from './app-CXF4MdJc.cjs';
+export { an as AIAction, ao as AIActionStatus, ap as AIActionType, aq as AIAuditActionType, ar as AIAuditRecord, as as AIChunk, at as AIMessage, au as AIPIIPattern, av as AIRateLimitResult, aw as AIRateLimitStore, ax as AIThread, ay as AIToolContext, az as AIToolDefinition, aA as AI_ACTIONS_COLLECTION, aB as AI_AUDIT_COLLECTION, aC as AI_CHUNKS_COLLECTION, aD as AI_MESSAGES_COLLECTION, aE as AI_THREADS_COLLECTION, aF as AccessConfig, aG as AccessFunction, aH as AccessFunctionArgs, aI as AccessResult, aJ as AccessRule, aK as ActionConfig, aL as ActionConfigBase, aM as ActionConfigWithHandler, aN as ActionConfigWithMutation, aO as ActionContext, aP as ActionType, aQ as AdminAuthAccessResolution, aR as AdminAuthClaimMapping, aS as AdminAuthMember, aT as AdminAuthProvider, aU as AdminAuthProviderMembersConfig, aV as AdminAuthProvisioningMode, aW as AdminAuthResolveAccessArgs, aX as AdminAuthResolvedIdentity, aY as AdminConfig, aZ as AdminDashboardComponentSlots, a_ as AdminIconName, a$ as AggregateArgs, b0 as AggregateCastType, b1 as AggregateCollectionResult, b2 as AggregateInput, b3 as AggregateOperation, b4 as AggregateResult, b5 as AppTrashConfig, b6 as BaseAdminAuthProvider, b7 as BaseFieldAdmin, b8 as BlockVariant, b9 as BlocksField, ba as BooleanFieldAdmin, bb as BooleanFormat, bc as CURRENT_NAV_PREFERENCES_VERSION, bd as CalendarViewConfig, be as CardsViewConfig, bf as CharacterLimitFieldAdmin, bg as CharacterLimitFieldConfig, bh as CollectionAfterChangeHook, bi as CollectionAfterDeleteHook, bj as CollectionAfterReadHook, bk as CollectionAfterReadHookEntry, bl as CollectionAfterRestoreHook, bm as CollectionAfterTransitionHook, bn as CollectionAfterTrashHook, bo as CollectionBeforeChangeHook, bp as CollectionBeforeChangeHookEntry, bq as CollectionBeforeCommitHook, br as CollectionBeforeDeleteHook, bs as CollectionBeforeReadHook, bt as CollectionBeforeReadHookEntry, bu as CollectionBeforeRestoreHook, bv as CollectionBeforeTransitionHook, bw as CollectionBeforeTrashHook, bx as CollectionIndex, by as CollectionListComponentSlots, bz as CollectionRAGConfig, bA as CollectionSchemaResult, bB as CollectionSummaryResult, bC as CollectionViewComponentSlots, bD as CompiledNavGroup, bE as CountOperation, bF as CustomAdminAuthProvider, bG as DEFAULT_USER_NAV_PREFERENCES, bH as DateFieldAdmin, bI as DateFormat, bJ as DefaultValueContext, bK as DefineActionOptions, bL as DefineCalendarViewOptions, bM as DefineCardsViewOptions, bN as DefineGanttViewOptions, bO as DefineKanbanViewOptions, bP as DefineTableViewOptions, bQ as DefineViewBaseOptions, bR as DefineViewOptions, bS as DetailSpan, bT as DisplayTone, bU as DisplayVariant, bV as DistinctCountOperation, bW as DistinctValuesOperation, bX as DynamicOptionItem, bY as DynamicOptionsConfig, bZ as DynamicOptionsResolver, b_ as DynamicOptionsResolverArgs, b$ as DyrectedAIContext, c0 as DyrectedLoggerConfig, c1 as DyrectedObservabilityConfig, c2 as EmailFieldAdmin, c3 as FieldAdminHooks, c4 as FieldAdminOnChangeHook, c5 as FieldAdminOnChangeHookArgs, c6 as FieldAdminOptionsHook, c7 as FieldAdminOptionsHookArgs, c8 as FieldAdminOptionsHookResult, c9 as FieldAfterReadHook, ca as FieldAfterReadHookArgs, cb as FieldBase, cc as FieldBeforeChangeHook, cd as FieldBeforeChangeHookArgs, ce as FieldHook, cf as FieldHooks, cg as FileData, ch as GanttViewConfig, ci as GetDocumentResult, cj as GlobalAfterChangeHook, ck as GlobalAfterReadHook, cl as GlobalAfterReadHookEntry, cm as GlobalBeforeChangeHook, cn as GlobalBeforeChangeHookEntry, co as GlobalBeforeReadHook, cp as GlobalBeforeReadHookEntry, cq as GlobalRAGConfig, cr as GlobalSchemaResult, cs as GlobalSummaryResult, ct as HeadingLevel, cu as HookFunction, cv as IconFieldAdmin, cw as ImageService, cx as ImageTransformOptions, cy as InferAggregateResult, cz as JoinFieldAdmin, cA as JsonFieldAdmin, cB as JsonFormat, cC as KanbanViewConfig, cD as LIFECYCLE_EVENT_NAMES, cE as LifecycleEventHandler, cF as LinkFormat, cG as MetricColor, cH as MoneyFieldAdmin, cI as MoneyFieldConfig, cJ as MultiSelectFieldAdmin, cK as NamedAccessPolicy, cL as NavBadgeConfig, cM as NavGroup, cN as NumberFieldAdmin, cO as NumberFormat, cP as NumberLimitFieldAdmin, cQ as NumberLimitFieldConfig, cR as NumericOperation, cS as NumericUpdateOperator, cT as OIDCAdminAuthProvider, cU as OptionFormat, cV as PaginatedResult, cW as PinnedNavItemRef, cX as PublicAdminAuthProvider, cY as QueryCollectionResult, cZ as RAGSearchResult, c_ as RadioFieldAdmin, c$ as RateLimitConfig, d0 as ReadonlyDatabaseAdapter, d1 as RichTextFeature, d2 as RichTextFieldConfig, d3 as SelectFieldAdmin, d4 as SqlWhereResult, d5 as StorageAdapter, d6 as TableViewConfig, d7 as TaskContext, d8 as TaskLogger, d9 as TaskRunStatus, da as TextFieldAdmin, db as TextFormat, dc as TextareaFieldAdmin, dd as TrashConfig, de as TrustProxyConfig, df as TypedField, dg as UploadConfig, dh as UrlFieldAdmin, di as UrlLinkValue, dj as ViewActionFeatures, dk as ViewComponentSlots, dl as ViewConfigBase, dm as ViewLayout, dn as ViewMetric, dp as ViewSubMetric, dq as WhereClause, dr as WhereOperator, ds as WhereOperatorName, dt as WordLimitFieldAdmin, du as WordLimitFieldConfig, dv as WorkflowMetadata, dw as WorkflowOnTransitionContext, dx as WorkflowOnTransitionHook, dy as WorkflowRole, dz as WorkflowState, dA as WorkflowTransitionContext, dB as coerceBooleanWhere, dC as defineAction, dD as defineCalendarView, dE as defineCardsView, dF as defineGanttView, dG as defineKanbanView, dH as defineTableView, dI as defineView, dJ as defineWorkspace, dK as isAICollection, dL as parseMongoWhere, dM as parseSqlWhere } from './app-CXF4MdJc.cjs';
 import jexl from 'jexl';
 import { Context } from 'hono';
 export { z } from 'zod';
@@ -17,7 +17,7 @@ type FieldValueType<F extends Field> = F["type"] extends "text" | "textarea" | "
     hasMany: true;
 } ? string[] : string : F["type"] extends "image" ? F extends {
     hasMany: true;
-} ? string[] : string : F["type"] extends "richText" | "json" ? Record<string, unknown> : F["type"] extends "object" ? F extends {
+} ? string[] : string : F["type"] extends "richText" ? string | Record<string, unknown> : F["type"] extends "json" ? Record<string, unknown> : F["type"] extends "object" ? F extends {
     fields: infer SF extends readonly Field[];
 } ? Prettify<InferDocShape<SF>> : Record<string, unknown> : F["type"] extends "array" ? F extends {
     fields: infer SF extends readonly Field[];
@@ -719,6 +719,11 @@ interface TaskRunner {
     }): void;
     /** Stops polling and waits for any run in progress to settle. */
     stop(): Promise<void>;
+    /** Lists all registered tasks with their configured cron expression. */
+    getTasks(): Array<{
+        name: string;
+        cron?: string;
+    }>;
 }
 /**
  * Creates the runner for the tasks in `config.tasks`. Coordination between
@@ -1539,6 +1544,74 @@ declare function compileNavigation(config: DyrectedConfig<any> | {
  * Filter compiled navigation based on user access rules.
  */
 declare function pruneNavigationForUser(tree: CompiledNavTree, user?: any): CompiledNavTree;
+/**
+ * Resolves all operational views associated with a collection, combining:
+ * 1. Views declared directly on the collection (`collection.views`)
+ * 2. Views targeting this collection via `admin.navigation` (including `addToCollection`,
+ *    explicit collection navigation items, and views inside standalone operational workspaces).
+ */
+declare function resolveAllCollectionViews(collection: CollectionConfig, config?: Partial<DyrectedConfig> | null): ViewConfig[];
+
+declare const TRASH_COLLECTION = "__trash";
+/**
+ * Internal collection holding snapshots of trashed documents across all collections.
+ */
+declare const TRASH_COLLECTION_CONFIG: CollectionConfig;
+/**
+ * Deterministic primary key for a trash entry: `${collection}:${docId}`.
+ */
+declare function getTrashEntryId(collection: string, docId: string): string;
+interface ResolvedTrashConfig {
+    enabled: boolean;
+    retentionDays: number | null;
+    allowPermanentDelete: boolean;
+}
+/**
+ * Resolves trash settings for a collection based on collection and app-level config.
+ *
+ * Resolution order:
+ * | Collection trash | App trash.enabled | Result |
+ * |---|---|---|
+ * | false            | any               | hard delete |
+ * | true / object    | any               | trash enabled |
+ * | omitted          | false             | hard delete |
+ * | omitted          | omitted / true    | trash enabled (default: 30 days retention) |
+ */
+declare function resolveTrashConfig(collection: CollectionConfig, appConfig?: DyrectedConfig): ResolvedTrashConfig;
+/**
+ * Validates trash configuration for app and collections.
+ */
+declare function assertValidTrashInConfig(config: DyrectedConfig, source?: string): void;
+/**
+ * Resolves a human-readable title for a document snapshot using collection useAsTitle.
+ */
+declare function resolveDocumentTitle(collection: CollectionConfig, doc: any): string;
+/**
+ * Creates the built-in purge task that automatically permanently deletes
+ * expired documents from __trash.
+ */
+declare function createTrashPurgeTask(config: DyrectedConfig): TaskConfig;
+interface SoftDeleteOptions {
+    db: any;
+    config: DyrectedConfig;
+    collection: string;
+    id: string;
+    deletedBy?: string | null;
+}
+declare function softDeleteDocument(options: SoftDeleteOptions): Promise<{
+    id: string;
+    purgeAt: number | null;
+}>;
+interface RestoreDocumentOptions {
+    db: any;
+    config: DyrectedConfig;
+    collection: string;
+    trashId: string;
+    overrides?: Record<string, unknown>;
+}
+declare function restoreDocument(options: RestoreDocumentOptions): Promise<{
+    restoredDoc: any;
+}>;
 
 type TopLevelFieldName<TFields extends readonly Field[]> = Extract<TFields[number], {
     name: string;
@@ -1963,9 +2036,12 @@ declare const _defineJoinFieldBase: <const T extends Omit<JoinField, "type">>(fi
  * })
  * ```
  */
-declare function defineRelationshipField<TValidSlugs extends string = string>(config: Omit<Omit<Parameters<typeof _defineRelationshipFieldBase>[0], "type">, "relationTo"> & {
+declare function defineRelationshipField<TValidSlugs extends string = string, const T extends Omit<Omit<Parameters<typeof _defineRelationshipFieldBase>[0], "type">, "relationTo"> & {
     relationTo: TValidSlugs;
-}): RelationshipField;
+} = any>(config: T): T & {
+    type: "relationship";
+    relationTo: TValidSlugs;
+};
 declare function defineRelationshipField(config: Parameters<typeof _defineRelationshipFieldBase>[0]): RelationshipField;
 /**
  * Define an `image` field with automatic slug inference from your collection config.
@@ -2006,6 +2082,162 @@ declare function defineJoinField<TValidSlugs extends string = string>(config: Om
     collection: TValidSlugs;
 }): JoinField;
 declare function defineJoinField(config: Parameters<typeof _defineJoinFieldBase>[0]): JoinField;
+interface CreatedAtFieldOptions extends Partial<Omit<DateTimeField, "type">> {
+    type?: "datetime" | "date";
+}
+/**
+ * Define a `createdAt` timestamp field.
+ * Defaults to `type: "datetime"`, `name: "createdAt"`, `label: "Created At"`, and `admin: { readOnly: true }`.
+ *
+ * @example
+ * ```ts
+ * defineCreatedAtField()
+ * defineCreatedAtField({ name: "created_at", admin: { position: "sidebar" } })
+ * ```
+ */
+declare function defineCreatedAtField<const T extends CreatedAtFieldOptions = {
+    name: "createdAt";
+}>(config?: T): (T extends {
+    type: "date";
+} ? DateField : DateTimeField) & {
+    name: T extends {
+        name: infer N extends string;
+    } ? N : "createdAt";
+    type: T extends {
+        type: infer Type extends "datetime" | "date";
+    } ? Type : "datetime";
+};
+interface UpdatedAtFieldOptions extends Partial<Omit<DateTimeField, "type">> {
+    type?: "datetime" | "date";
+}
+/**
+ * Define an `updatedAt` timestamp field.
+ * Defaults to `type: "datetime"`, `name: "updatedAt"`, `label: "Updated At"`, and `admin: { readOnly: true }`.
+ *
+ * @example
+ * ```ts
+ * defineUpdatedAtField()
+ * defineUpdatedAtField({ name: "updated_at", admin: { position: "sidebar" } })
+ * ```
+ */
+declare function defineUpdatedAtField<const T extends UpdatedAtFieldOptions = {
+    name: "updatedAt";
+}>(config?: T): (T extends {
+    type: "date";
+} ? DateField : DateTimeField) & {
+    name: T extends {
+        name: infer N extends string;
+    } ? N : "updatedAt";
+    type: T extends {
+        type: infer Type extends "datetime" | "date";
+    } ? Type : "datetime";
+};
+interface CreatedByFieldOptions<TValidSlugs extends string = string> extends Partial<Omit<RelationshipField, "type" | "relationTo">> {
+    type?: "relationship" | "text";
+    relationTo?: TValidSlugs | TValidSlugs[];
+}
+/**
+ * Define a `createdBy` audit user field.
+ * Defaults to `type: "relationship"`, `name: "createdBy"`, `label: "Created By"`, `relationTo: "users"`, and `admin: { readOnly: true }`.
+ * If `type: "text"` is specified, creates a read-only text field instead of a relationship.
+ *
+ * @example
+ * ```ts
+ * defineCreatedByField() // relationship to 'users'
+ * defineCreatedByField({ relationTo: 'authors' }) // relationship to 'authors'
+ * defineCreatedByField({ type: 'text' }) // text user identifier
+ * ```
+ */
+declare function defineCreatedByField<TValidSlugs extends string = string, const T extends CreatedByFieldOptions<TValidSlugs> = CreatedByFieldOptions<TValidSlugs>>(config?: T): (T extends {
+    type: "text";
+} ? TextField : RelationshipField) & {
+    name: T extends {
+        name: infer N extends string;
+    } ? N : "createdBy";
+    type: T extends {
+        type: "text";
+    } ? "text" : "relationship";
+};
+interface UpdatedByFieldOptions<TValidSlugs extends string = string> extends Partial<Omit<RelationshipField, "type" | "relationTo">> {
+    type?: "relationship" | "text";
+    relationTo?: TValidSlugs | TValidSlugs[];
+}
+/**
+ * Define an `updatedBy` audit user field.
+ * Defaults to `type: "relationship"`, `name: "updatedBy"`, `label: "Updated By"`, `relationTo: "users"`, and `admin: { readOnly: true }`.
+ * If `type: "text"` is specified, creates a read-only text field instead of a relationship.
+ *
+ * @example
+ * ```ts
+ * defineUpdatedByField() // relationship to 'users'
+ * defineUpdatedByField({ relationTo: 'authors' }) // relationship to 'authors'
+ * defineUpdatedByField({ type: 'text' }) // text user identifier
+ * ```
+ */
+declare function defineUpdatedByField<TValidSlugs extends string = string, const T extends UpdatedByFieldOptions<TValidSlugs> = UpdatedByFieldOptions<TValidSlugs>>(config?: T): (T extends {
+    type: "text";
+} ? TextField : RelationshipField) & {
+    name: T extends {
+        name: infer N extends string;
+    } ? N : "updatedBy";
+    type: T extends {
+        type: "text";
+    } ? "text" : "relationship";
+};
+interface RoleOption {
+    value: string;
+    label: string;
+}
+interface RolesFieldOptions extends Partial<Omit<SelectField, "type" | "options">> {
+    type?: "select" | "multiSelect";
+    multiple?: boolean;
+    hasMany?: boolean;
+    roles?: readonly string[] | readonly RoleOption[];
+    options?: readonly string[] | readonly RoleOption[] | SelectField["options"];
+    /**
+     * The role name or names authorized to update this field.
+     * Defaults to `"admin"`.
+     * Can be a single role (`"super-admin"`) or an array (`["owner", "super-admin"]`).
+     */
+    adminRole?: string | readonly string[];
+}
+/**
+ * Define a `roles` authorization field on an auth or users collection.
+ * Replaces manual select/multiSelect field boilerplate with built-in role options,
+ * safe non-self-elevation update access control, and singular/multiple mode support.
+ *
+ * @example
+ * ```ts
+ * defineRolesField() // single select with admin, editor, viewer
+ * defineRoles({ multiple: true }) // multiSelect roles array
+ * defineRoles({ roles: ['super-admin', 'moderator', 'member'], adminRole: 'super-admin' })
+ * defineRoles({ name: 'role' }) // singular role
+ * ```
+ */
+declare function defineRolesField<const T extends RolesFieldOptions = {
+    name: "roles";
+}>(config?: T): (T extends {
+    multiple: true;
+} | {
+    hasMany: true;
+} | {
+    type: "multiSelect";
+} ? MultiSelectField : SelectField) & {
+    name: T extends {
+        name: infer N extends string;
+    } ? N : "roles";
+    type: T extends {
+        multiple: true;
+    } | {
+        hasMany: true;
+    } | {
+        type: "multiSelect";
+    } ? "multiSelect" : "select";
+};
+/**
+ * Convenience alias for {@link defineRolesField}.
+ */
+declare const defineRoles: typeof defineRolesField;
 /**
  * Group fields under a named tab in the Admin edit form. Tabs are presentational
  * only: `defineTab` returns the given fields unchanged except that each one's
@@ -2040,4 +2272,4 @@ declare function defineTab<const T extends readonly Field[]>(args: {
     fields: T;
 }): T;
 
-export { AIConfig, type AIErrorCode, AIPIIConfig, type AccessConditions, AccessPolicyResolver, AdminAuthConfig, ArrayField, AuthConfig, type AuthDocFields, AuthenticatedUser, BASE62_ALPHABET, BUILTIN_JEXL_HELPERS, BaseDocument, Block, BooleanField, CROCKFORD_BASE32, CollectionConfig, CompiledNavItem, CompiledNavTree, ComputedHandler, type ConfigDiagnostic, ConfigValidationError, ConflictError, DatabaseAdapter, DateField, DateTimeField, type DeclarativeAccessSurface, type DeclarativeAccessValidationIssue, type DeclarativeAdminSurface, type DeclarativeAdminValidationIssue, DeclarativeHookExpression, type DeclarativeHookSurface, type DeclarativeHookValidationIssue, type DeclarativePreviewSurface, type DeclarativePreviewValidationIssue, DefineWorkspaceOptions, DetailAction, DetailActionOptions, DetailComputed, DetailComputedOptions, DetailCustom, DetailCustomOptions, DetailDivider, DetailDividerOptions, DetailField, DetailGrid, DetailGridOptions, DetailItem, DetailRepeat, DetailRepeatOptions, DetailSchema, DetailSection, DetailSectionOptions, DetailTab, DetailTabOptions, DetailTabs, DetailTabsOptions, DetailText, DetailTextOptions, DisplayFieldOptions, DuplicateKeyError, DyrectedAIError, DyrectedConfig, DyrectedError, EmailField, type ExprFunction, type ExtractCollectionSlugs, Field, FieldConditionBuilder, FieldType, ForbiddenError, type GenerateIdOptions, GlobalConfig, HookRequestContext, IconField, IdStrategy, ImageField, type InferDocShape, JoinField, JsonField, LIFECYCLE_EVENTS_COLLECTION, LifecycleEvent, LifecycleEventName, MatchBuilder, MoneyField, MultiSelectField, NANOID_ALPHABET, NON_NEGOTIABLE_CREDENTIAL_FIELDS, NotFoundError, NumberField, ObjectField, PII_REGEX_PATTERNS, type Prettify, PublicAdminAuthConfig, type PublishingWorkflowOptions, RESERVED_NAVIGATION_SLUGS, RadioField, type ReconcileNavigationOptions, type ReconciledNavTree, RelationshipField, RichTextField, RowField, type SanitizeDocForAIOptions, SelectField, type SortClause, type SortDirection, type SqlSortDialect, type SystemDocFields, TASK_LOCKS_COLLECTION, TASK_LOCKS_COLLECTION_CONFIG, TaskConfig, TaskRunResult, type TaskRunner, TextField, TextareaField, TimeField, UNASSIGNED_GROUP_KEY, type UploadDocFields, UrlField, UserNavigationPreferences, ValidationError, WORKFLOW_HISTORY_COLLECTION, type WhenFunction, WorkflowConfig, WorkflowTransition, abs, addDays, asCollection, assertValidAdminConditionsInConfig, assertValidDeclarativeAccessInConfig, assertValidDeclarativeHookExpression, assertValidDeclarativeHookResult, assertValidDeclarativeHooksInConfig, assertValidNavigationSlugs, assertValidPreviewUrlsInConfig, availableWorkflowTransitions, buildSqlOrderBy, canViewWorkflowDraft, capitalize, ceil, clamp, coalesce, collectAdminConditionValidationIssues, collectConfigDiagnostics, collectDeclarativeAccessValidationIssues, collectDeclarativeHookValidationIssues, collectPreviewUrlValidationIssues, compact, compileNavigation, count, createLifecycleEvent, createTaskRunner, createWorkflowDocument, defaultValue, defineArrayField, defineBlock, defineBlocksField, defineBooleanField, defineCollection, defineConfig, defineDateField, defineDateTimeField, defineEmailField, defineField, defineGlobal, defineIconField, defineImageField, defineJoinField, defineJsonField, defineMoneyField, defineMultiSelectField, defineNumberField, defineObjectField, definePublishingWorkflow, defineRadioField, defineRelationshipField, defineRichTextField, defineRowField, defineSelectField, defineTab, defineTask, defineTextField, defineTextareaField, defineTimeField, defineUrlField, diffDays, dispatchLifecycleEvent, dispatchPendingLifecycleEvents, displayAction, displayComputed, displayCustom, displayCustomComponent, displayDivider, displayField, displayGrid, displayRepeat, displaySection, displayTab, displayTabs, displayText, endsWith, evaluateDetailComputed, evaluateJexl, evaluateJexlSync, executeFieldAfterRead, executeFieldBeforeChange, expr, first, floor, formatConfigDiagnostics, formatDate, formatJexlValue, generateDefaultDetailSchema, generateDocumentId, generateId, generateOpenApi, get, getAdminAuthCollection, getAdminRoleForCollection, getAllowedSitesForUser, getPublicAdminAuthConfig, includes, initializeWorkflowDocument, isConfigValidationError, isDetailItemVisible, isEmpty, isFuture, isPast, isSiteAuthorized, isUserAdmin, join, last, length, lower, maskEmail, maskPhone, maskTextPII, materializeWorkflowDocument, max, min, nanoid, nextCronRun, normalizeConfig, normalizeDetailItem, normalizeGroupKey, now, numericFieldNames, parseCron, parseSort, pow, prefixedId, pruneNavigationForUser, publishedStateName, publishingWorkflow, readingTime, reconcileNavigation, registerJexlHelpers, replace, resolveAdminAuthCollection, resolveAuthorizedSiteId, resolveIndexName, resolvePrefix, round, runCollectionHooks, sanitizeDocForAI, saveWorkflowDraft, simplePublishingWorkflow, slugify, sqrt, startsWith, sum, today, transitionWorkflow, trim, truncate, ulid, unique, upper, uuid, validateAdminConditionExpression, validateDeclarativeAccessExpression, validateDeclarativeHookExpression, validatePreviewUrlExpression, when, wordCount, workflowCapabilities };
+export { AIConfig, type AIErrorCode, AIPIIConfig, type AccessConditions, AccessPolicyResolver, AdminAuthConfig, ArrayField, AuthConfig, type AuthDocFields, AuthenticatedUser, BASE62_ALPHABET, BUILTIN_JEXL_HELPERS, BaseDocument, Block, BooleanField, CROCKFORD_BASE32, CollectionConfig, CompiledNavItem, CompiledNavTree, ComputedHandler, type ConfigDiagnostic, ConfigValidationError, ConflictError, type CreatedAtFieldOptions, type CreatedByFieldOptions, DatabaseAdapter, DateField, DateTimeField, type DeclarativeAccessSurface, type DeclarativeAccessValidationIssue, type DeclarativeAdminSurface, type DeclarativeAdminValidationIssue, DeclarativeHookExpression, type DeclarativeHookSurface, type DeclarativeHookValidationIssue, type DeclarativePreviewSurface, type DeclarativePreviewValidationIssue, DefineWorkspaceOptions, DetailAction, DetailActionOptions, DetailComputed, DetailComputedOptions, DetailCustom, DetailCustomOptions, DetailDivider, DetailDividerOptions, DetailField, DetailGrid, DetailGridOptions, DetailItem, DetailRepeat, DetailRepeatOptions, DetailSchema, DetailSection, DetailSectionOptions, DetailTab, DetailTabOptions, DetailTabs, DetailTabsOptions, DetailText, DetailTextOptions, DisplayFieldOptions, DuplicateKeyError, DyrectedAIError, DyrectedConfig, DyrectedError, EmailField, type ExprFunction, type ExtractCollectionSlugs, Field, FieldConditionBuilder, FieldType, ForbiddenError, type GenerateIdOptions, GlobalConfig, HookRequestContext, IconField, IdStrategy, ImageField, type InferDocShape, JoinField, JsonField, LIFECYCLE_EVENTS_COLLECTION, LifecycleEvent, LifecycleEventName, MatchBuilder, MoneyField, MultiSelectField, NANOID_ALPHABET, NON_NEGOTIABLE_CREDENTIAL_FIELDS, NotFoundError, NumberField, ObjectField, PII_REGEX_PATTERNS, type Prettify, PublicAdminAuthConfig, type PublishingWorkflowOptions, RESERVED_NAVIGATION_SLUGS, RadioField, type ReconcileNavigationOptions, type ReconciledNavTree, RelationshipField, type ResolvedTrashConfig, type RestoreDocumentOptions, RichTextField, type RoleOption, type RolesFieldOptions, RowField, type SanitizeDocForAIOptions, SelectField, type SoftDeleteOptions, type SortClause, type SortDirection, type SqlSortDialect, type SystemDocFields, TASK_LOCKS_COLLECTION, TASK_LOCKS_COLLECTION_CONFIG, TRASH_COLLECTION, TRASH_COLLECTION_CONFIG, TaskConfig, TaskRunResult, type TaskRunner, TextField, TextareaField, TimeField, UNASSIGNED_GROUP_KEY, type UpdatedAtFieldOptions, type UpdatedByFieldOptions, type UploadDocFields, UrlField, UserNavigationPreferences, ValidationError, ViewConfig, WORKFLOW_HISTORY_COLLECTION, type WhenFunction, WorkflowConfig, WorkflowTransition, abs, addDays, asCollection, assertValidAdminConditionsInConfig, assertValidDeclarativeAccessInConfig, assertValidDeclarativeHookExpression, assertValidDeclarativeHookResult, assertValidDeclarativeHooksInConfig, assertValidNavigationSlugs, assertValidPreviewUrlsInConfig, assertValidTrashInConfig, availableWorkflowTransitions, buildSqlOrderBy, canViewWorkflowDraft, capitalize, ceil, clamp, coalesce, collectAdminConditionValidationIssues, collectConfigDiagnostics, collectDeclarativeAccessValidationIssues, collectDeclarativeHookValidationIssues, collectPreviewUrlValidationIssues, compact, compileNavigation, count, createLifecycleEvent, createTaskRunner, createTrashPurgeTask, createWorkflowDocument, defaultValue, defineArrayField, defineBlock, defineBlocksField, defineBooleanField, defineCollection, defineConfig, defineCreatedAtField, defineCreatedByField, defineDateField, defineDateTimeField, defineEmailField, defineField, defineGlobal, defineIconField, defineImageField, defineJoinField, defineJsonField, defineMoneyField, defineMultiSelectField, defineNumberField, defineObjectField, definePublishingWorkflow, defineRadioField, defineRelationshipField, defineRichTextField, defineRoles, defineRolesField, defineRowField, defineSelectField, defineTab, defineTask, defineTextField, defineTextareaField, defineTimeField, defineUpdatedAtField, defineUpdatedByField, defineUrlField, diffDays, dispatchLifecycleEvent, dispatchPendingLifecycleEvents, displayAction, displayComputed, displayCustom, displayCustomComponent, displayDivider, displayField, displayGrid, displayRepeat, displaySection, displayTab, displayTabs, displayText, endsWith, evaluateDetailComputed, evaluateJexl, evaluateJexlSync, executeFieldAfterRead, executeFieldBeforeChange, expr, first, floor, formatConfigDiagnostics, formatDate, formatJexlValue, generateDefaultDetailSchema, generateDocumentId, generateId, generateOpenApi, get, getAdminAuthCollection, getAdminRoleForCollection, getAllowedSitesForUser, getPublicAdminAuthConfig, getTrashEntryId, includes, initializeWorkflowDocument, isConfigValidationError, isDetailItemVisible, isEmpty, isFuture, isPast, isSiteAuthorized, isUserAdmin, join, last, length, lower, maskEmail, maskPhone, maskTextPII, materializeWorkflowDocument, max, min, nanoid, nextCronRun, normalizeConfig, normalizeDetailItem, normalizeGroupKey, now, numericFieldNames, parseCron, parseSort, pow, prefixedId, pruneNavigationForUser, publishedStateName, publishingWorkflow, readingTime, reconcileNavigation, registerJexlHelpers, replace, resolveAdminAuthCollection, resolveAllCollectionViews, resolveAuthorizedSiteId, resolveDocumentTitle, resolveIndexName, resolvePrefix, resolveTrashConfig, restoreDocument, round, runCollectionHooks, sanitizeDocForAI, saveWorkflowDraft, simplePublishingWorkflow, slugify, softDeleteDocument, sqrt, startsWith, sum, today, transitionWorkflow, trim, truncate, ulid, unique, upper, uuid, validateAdminConditionExpression, validateDeclarativeAccessExpression, validateDeclarativeHookExpression, validatePreviewUrlExpression, when, wordCount, workflowCapabilities };