@nest-admin/nestjs 0.11.0

package/dist/index.d.ts

@@ -0,0 +1,1652 @@
+import { ExecutionContext, DynamicModule, ModuleMetadata, FactoryProvider, Type } from '@nestjs/common';
+
+/**
+ * Normalised, ORM-independent description of a model and its fields.
+ *
+ * Every ORM adapter translates its own schema representation (Prisma DMMF,
+ * TypeORM entity metadata, a Drizzle table object, ...) into these shapes.
+ * Nothing downstream - the CRUD engine, the HTTP API, the admin UI - is
+ * allowed to look at anything else.
+ *
+ * @experimental Draft contract. Expected to change during MVP implementation.
+ */
+/** ORM-independent classification of a scalar or relation field. */
+type FieldKind = 'string' | 'number' | 'boolean' | 'datetime' | 'enum' | 'json' | 'relation'
+/** The adapter recognised the field but cannot map it onto a known kind. */
+ | 'unknown';
+/** Cardinality of a relation from the owning model's point of view. */
+type RelationCardinality = 'one' | 'many';
+/**
+ * A relation, and how to act on it.
+ *
+ * `from` and `to` are what turn a relation from something an admin can only
+ * display into something it can filter and write. A to-one relation is stored
+ * as an ordinary scalar column - `Post.authorId` - and that column is what a
+ * query has to be expressed in terms of. Without knowing its name, a filter on
+ * `author` cannot be translated, and a form has no field to submit.
+ *
+ * Both are absent on to-many relations, which have no column on this side.
+ */
+interface RelationMetadata {
+    /** `name` of the {@link ModelMetadata} on the other side of the relation. */
+    readonly targetModel: string;
+    readonly cardinality: RelationCardinality;
+    /**
+     * Scalar field on **this** model holding the foreign key, for a to-one
+     * relation - `authorId` on `Post.author`.
+     *
+     * Absent when the relation has no column on this side: every to-many, and
+     * the non-owning half of a one-to-one.
+     */
+    readonly from?: string;
+    /** Field on the target model that `from` points at - usually its id. */
+    readonly to?: string;
+    /**
+     * Name shared by both halves of the relation.
+     *
+     * The only reliable way to pair `User.posts` with `Post.author`, which two
+     * things need. Distinguishing a many-to-many from a one-to-many requires
+     * looking at the other side - both are `'many'` from here, but only one has
+     * no column anywhere. And knowing whether a child's key is required decides
+     * whether it can be detached at all.
+     *
+     * Two relations between the same pair of models are told apart by it too:
+     * `Post.author` and `Post.reviewer` both target `User`.
+     */
+    readonly name?: string;
+}
+interface FieldMetadata {
+    readonly name: string;
+    readonly kind: FieldKind;
+    /** Part of the model's primary key. */
+    readonly isId: boolean;
+    readonly isRequired: boolean;
+    readonly isUnique: boolean;
+    /** The field holds a list of {@link FieldKind} values. */
+    readonly isList: boolean;
+    /**
+     * The value is produced by the database or the ORM and is not asked of the
+     * user - `@default(cuid())`, `@default(now())`, `@default(autoincrement())`,
+     * `@updatedAt`. Such fields are displayed but not editable.
+     *
+     * This is NOT "has a default". A field with a literal default
+     * (`active Boolean @default(true)`) is an ordinary editable field that
+     * happens to arrive pre-filled; see {@link FieldMetadata.defaultValue}.
+     *
+     * NAME COLLISION - read before implementing an adapter. Prisma's DMMF also
+     * has a field called `isGenerated`, and it does NOT mean this. Measured
+     * against Prisma 7.10.0, DMMF reports `isGenerated: false` for
+     * `id String @id @default(cuid())`. Mapping it across directly produces
+     * editable primary keys. The correct derivation - a *function* default, or
+     * an updated-at column - is in `packages/prisma/src/metadata/to-metadata.ts`
+     * and `packages/drizzle/src/metadata/to-metadata.ts`, which state it in each
+     * ORM's own terms.
+     */
+    readonly isGenerated: boolean;
+    /**
+     * Accepted on a write, never returned on a read.
+     *
+     * Set by `writeOnly` in the configuration. A password is the reason it
+     * exists: it has to be typed into a form and must never come back out, and
+     * `hidden` cannot express that - it refuses the field in both directions, so
+     * a hidden password column leaves no way to set one.
+     *
+     * Enforced twice, deliberately: the field is left out of the columns the
+     * adapter is asked for, *and* out of the projection applied to whatever comes
+     * back. One of those is enough; two is what it takes for a future adapter
+     * that ignores the field scope not to become a leak.
+     */
+    readonly writeOnly?: boolean;
+    /**
+     * Literal default the admin should pre-fill on create, when the schema
+     * declares one (`@default(true)`, `@default(0)`, `@default("USER")`).
+     *
+     * Absent for generated values: there is no literal to pre-fill for
+     * `@default(now())`, and {@link FieldMetadata.isGenerated} is `true` instead.
+     */
+    readonly defaultValue?: unknown;
+    /** Populated when `kind` is `'enum'`. */
+    readonly enumValues?: readonly string[];
+    /** Populated when `kind` is `'relation'`. */
+    readonly relation?: RelationMetadata;
+}
+interface ModelMetadata {
+    /** Adapter-facing identifier, e.g. the Prisma model name `User`. */
+    readonly name: string;
+    /**
+     * Field names forming the primary key. Modelled as a list rather than a
+     * single `id` so composite keys do not require a breaking change later,
+     * even though the MVP will only support single-column keys.
+     */
+    readonly primaryKey: readonly string[];
+    readonly fields: readonly FieldMetadata[];
+    /**
+     * Field that names a record of this model in one line, when the application
+     * has declared one.
+     *
+     * A slot rather than a value: left unset, `displayFieldFor` works it out from
+     * the fields. It is here so that a declared choice travels with the model and
+     * reaches the adapter and the metadata document alike, without either of them
+     * having to read configuration.
+     */
+    readonly displayField?: string;
+}
+
+/**
+ * Per-model and per-field configuration.
+ *
+ * The schema says what a model *is*; this says how the admin should treat it.
+ * Two different questions, so they are two different inputs - a column being a
+ * string is a fact about the database, and that column being a password is a
+ * fact about the application.
+ *
+ * The overrides divide into two kinds, and the difference matters:
+ *
+ *   behaviour     `hidden`, `readOnly`, `displayField`. Enforced. A hidden
+ *                 field is removed from the metadata every layer reads, so it
+ *                 cannot be filtered, sorted, written or returned - see
+ *                 `applyOverrides`.
+ *
+ *   behaviour     `writeOnly` too - accepted on a write and stripped from
+ *                 every read.
+ *
+ *   presentation  `label`, `widget`, `order`. Passed to the client, which is
+ *                 free to ignore them. Nothing depends on them being honoured.
+ *
+ * Anything in the first group that were only presentation would be a security
+ * hole with a reassuring name.
+ */
+
+/**
+ * How a field should be edited, when its type does not say enough.
+ *
+ * A `string` column may be a sentence, a password, an address or a colour, and
+ * the schema cannot tell them apart. Deliberately a closed list: a client has
+ * to know how to render each one, so an open string would mean silently
+ * falling back to a plain input and no way to notice.
+ */
+type FieldWidget = 'textarea' | 'password' | 'email' | 'url' | 'color' | 'json';
+interface FieldOverride {
+    /**
+     * Remove the field from the admin entirely.
+     *
+     * **Enforced, not cosmetic.** The field is dropped from the metadata before
+     * anything reads it, so it is absent from the schema document, rejected in
+     * filters and sorts, refused in writes, and stripped from every response.
+     * A password hash is the reason this exists.
+     */
+    readonly hidden?: boolean;
+    /** Show the field, refuse to write it. Generated columns are already this. */
+    readonly readOnly?: boolean;
+    /**
+     * Write the field, never read it back. The mirror of `readOnly`.
+     *
+     * **Enforced, not cosmetic.** The column is left out of the query the adapter
+     * makes and out of the projection applied to the result, so it is absent from
+     * a list, from a detail page and from the record a write returns - while
+     * still being accepted in the write itself.
+     *
+     * A password is what this is for. `hidden` is the wrong tool: it refuses the
+     * field in both directions, so a hidden password column can never be set.
+     */
+    readonly writeOnly?: boolean;
+    /** What to call it, when the column name is not what people call the thing. */
+    readonly label?: string;
+    /** How to edit it. See {@link FieldWidget}. */
+    readonly widget?: FieldWidget;
+    /** Where it sits among the others. Lower comes first; unset comes last. */
+    readonly order?: number;
+}
+/**
+ * Icons a model may be given in the navigation.
+ *
+ * A closed list, for the same reason `FieldWidget` is one: the interface has to
+ * know how to draw each name, so an open string would mean silently rendering
+ * nothing and no way to notice. It is also a bundle decision - the icon set has
+ * about fifteen hundred entries, and only the ones named here are shipped.
+ *
+ * Chosen to cover what an admin's resources usually are rather than to be
+ * complete. A model with no icon is drawn without one, which is the default and
+ * is not a lesser state: identical icons down a column are decoration, and the
+ * navigation reads better with none than with thirty of the same shape.
+ */
+type ModelIcon = 'users' | 'user' | 'building' | 'box' | 'package' | 'tag' | 'shopping-cart' | 'credit-card' | 'receipt' | 'file-text' | 'folder' | 'image' | 'calendar' | 'clock' | 'mail' | 'message-square' | 'bell' | 'star' | 'map-pin' | 'globe' | 'settings' | 'key' | 'shield' | 'database' | 'table' | 'layers' | 'list' | 'chart-bar' | 'activity' | 'truck' | 'gift' | 'bookmark' | 'link';
+interface ModelOverride {
+    /** What to call the model. */
+    readonly label?: string;
+    /**
+     * Which icon to show beside it in the navigation.
+     *
+     * Presentational: the client may ignore it, and nothing depends on it being
+     * honoured. See {@link ModelIcon} for why the list is closed.
+     */
+    readonly icon?: ModelIcon;
+    /**
+     * Which field names a record, overriding what would be detected.
+     *
+     * The detection rule guesses well on conventional schemas and has no way to
+     * know that a `code` column is the one people recognise.
+     */
+    readonly displayField?: string;
+    /** Where the model sits in the resource list. Lower first; unset last. */
+    readonly order?: number;
+    readonly fields?: Readonly<Record<string, FieldOverride>>;
+}
+type ModelOverrides = Readonly<Record<string, ModelOverride>>;
+
+/**
+ * Where admin accounts live, as a contract.
+ *
+ * ## Why this exists at all
+ *
+ * Until 0.9.0 the answer to "who may open the admin?" was always the host
+ * application's: it already had sessions, and `AdminAuth` asked it one
+ * question. That is still right for a team that has an identity system, and
+ * nothing about it changes.
+ *
+ * It is a wall for everyone else. An application with no login of its own had
+ * to write a password hash, a session cookie and a form before the admin could
+ * go anywhere near production - which is a strange thing to ask of a package
+ * whose whole claim is that you do not build an admin.
+ *
+ * ## Why it is a contract rather than a table
+ *
+ * The same reason `OrmAdapter` is. An admin whose accounts can only live in
+ * Prisma has learned about Prisma, and the second ORM would find out the hard
+ * way. Everything here is plain data and promises; nothing knows what a
+ * database is.
+ *
+ * ## These accounts are not the application's users
+ *
+ * Deliberately, and this is the point most worth getting right. The people who
+ * administer a system are usually not rows in the table they administer, and
+ * conflating the two means a customer record with a password that opens the
+ * admin. The store is separate storage - a different model, or a different
+ * database entirely - and the admin never reads or writes the application's
+ * own users to decide who may sign in.
+ */
+/** One account that may sign in to the admin. */
+interface AdminAccount {
+    readonly id: string;
+    /**
+     * What is typed into the login form.
+     *
+     * Called `email` because that is what it almost always is, and a name people
+     * recognise is worth more than one that covers a case nobody has. A store is
+     * free to hold usernames in it.
+     */
+    readonly email: string;
+    /** Shown in the interface. Falls back to the email when absent. */
+    readonly name?: string | undefined;
+    /**
+     * The stored password hash, in whatever form the hasher produced.
+     *
+     * Read by the sign-in check and by nothing else. It must never reach a
+     * response, and the account the interface is told about is a projection that
+     * does not include it.
+     */
+    readonly passwordHash: string;
+    /**
+     * Suspended without being deleted.
+     *
+     * Distinct from removing the row: an account that has done things is worth
+     * keeping for the record, and "cannot sign in" is not the same fact as
+     * "never existed".
+     */
+    readonly disabled?: boolean | undefined;
+}
+/**
+ * The account as the interface may see it.
+ *
+ * A separate type rather than a comment on {@link AdminAccount}, because "do
+ * not send the hash" is a rule that gets forgotten and a type that cannot
+ * carry it does not.
+ */
+interface AdminAccountSummary {
+    readonly id: string;
+    readonly email: string;
+    readonly name?: string | undefined;
+}
+/**
+ * How the admin reaches its accounts.
+ *
+ * Read-only by design. Creating and editing accounts is the application's
+ * business: it owns the storage, it knows whether that is a migration, a seed
+ * script or a form somewhere else, and an admin that could mint its own
+ * administrators is an escalation waiting for its first mistake.
+ */
+interface AdminAccountStore {
+    /**
+     * Find an account by what was typed into the login form.
+     *
+     * Matching is the store's decision, and it should be case-insensitive on the
+     * local part in practice: someone who registered as `Ada@example.com` will
+     * type `ada@example.com` eventually.
+     *
+     * Returns `null` when there is none. The caller must not behave observably
+     * differently for `null` than for a wrong password - see the sign-in code.
+     */
+    findByEmail(email: string): Promise<AdminAccount | null>;
+    /**
+     * Find an account by its id, for a request that arrives with a session.
+     *
+     * Called on every authenticated request, so it should be cheap. It is also
+     * what makes a disabled or deleted account stop working immediately rather
+     * than when its session happens to expire.
+     */
+    findById(id: string): Promise<AdminAccount | null>;
+    /**
+     * How many accounts exist.
+     *
+     * Used once, at startup, to say so when the answer is zero - an admin nobody
+     * can sign in to is a configuration mistake that otherwise announces itself
+     * as a login form that rejects everything.
+     */
+    count(): Promise<number>;
+    /**
+     * Note that an account signed in. Optional.
+     *
+     * A store that does not care about this can leave it out; the sign-in path
+     * does not wait for it and a failure is logged rather than surfaced, because
+     * "your login worked but we could not write down that it did" is not
+     * something the person signing in can act on.
+     */
+    recordLogin?(id: string): Promise<void>;
+    /**
+     * What this store reads, for diagnostics. Optional.
+     *
+     * A model name, a table, a directory - whatever names the storage in a way a
+     * person would recognise. It exists so a startup check can say something
+     * useful rather than something generic: an admin that exposes its own
+     * account model as an editable resource is an escalation, and a warning that
+     * cannot name the model is a warning nobody acts on.
+     *
+     * Never used to decide anything, and never sent to a client.
+     */
+    readonly describes?: string;
+}
+
+/**
+ * ORM-independent query description.
+ *
+ * The admin UI and the HTTP layer speak only this vocabulary; each adapter is
+ * responsible for translating it into its own query language.
+ *
+ * @experimental Draft contract. Expected to change during MVP implementation.
+ */
+type SortDirection = 'asc' | 'desc';
+interface SortRule {
+    readonly field: string;
+    readonly direction: SortDirection;
+}
+/**
+ * The deliberately small operator set the MVP targets. Anything richer
+ * (nested relation filters, OR/AND trees, full-text) is a later concern and
+ * should extend this union rather than bypass it.
+ */
+type FilterOperator = 'eq' | 'ne' | 'contains' | 'startsWith' | 'endsWith' | 'gt' | 'gte' | 'lt' | 'lte' | 'in';
+interface FilterRule {
+    readonly field: string;
+    readonly operator: FilterOperator;
+    readonly value: unknown;
+}
+/** Page-number based pagination. Cursor pagination is a later addition. */
+interface ListQuery {
+    readonly page?: number;
+    readonly perPage?: number;
+    readonly sort?: readonly SortRule[];
+    readonly filters?: readonly FilterRule[];
+    /** Free-text term the adapter applies across searchable string fields. */
+    readonly search?: string;
+    /**
+     * The fields this query may touch, and the only ones it should return.
+     *
+     * Set by the caller that knows which fields the admin exposes - the adapter
+     * reads a schema, not a configuration. Without it, a field the application
+     * hid would still be searched by free text, sortable, filterable and
+     * returned, because from the adapter's side it is an ordinary column.
+     *
+     * Omitted means "every field the model has".
+     */
+    readonly fields?: readonly string[];
+}
+interface Page<T> {
+    readonly data: readonly T[];
+    readonly total: number;
+    readonly page: number;
+    readonly perPage: number;
+}
+
+/**
+ * The single seam between Nest Admin and any ORM.
+ *
+ * Adding support for a new ORM means writing one implementation of
+ * {@link OrmAdapter} and nothing else. Core, the NestJS integration, the HTTP
+ * contract and the admin UI stay untouched.
+ *
+ * @experimental Draft contract. Expected to change during MVP implementation.
+ */
+
+/**
+ * Primary key value of a single record. Composite keys are represented by
+ * {@link ModelMetadata.primaryKey}; supporting them at this level is a
+ * post-MVP change.
+ */
+type RecordId = string | number;
+/** An untyped record as it crosses the adapter boundary. */
+type RecordData = Record<string, unknown>;
+interface OrmAdapter {
+    /** Stable identifier used in diagnostics, e.g. `'prisma'`. */
+    readonly name: string;
+    /**
+     * Discover the models the adapter can serve. Asynchronous because an adapter
+     * may need to read a schema file or import a generated client.
+     */
+    getModels(): Promise<readonly ModelMetadata[]>;
+    list(model: string, query: ListQuery): Promise<Page<RecordData>>;
+    findOne(model: string, id: RecordId): Promise<RecordData | null>;
+    create(model: string, data: RecordData): Promise<RecordData>;
+    update(model: string, id: RecordId, data: RecordData): Promise<RecordData>;
+    delete(model: string, id: RecordId): Promise<void>;
+    /**
+     * A page of the records on the far side of a to-many relation.
+     *
+     * Paginated for the same reason a list is: the number of children is a
+     * property of the data, not of the schema, and a parent with fifty thousand
+     * of them must not be a page that never loads.
+     *
+     * Kept separate from `list` rather than expressed as a filter because a
+     * many-to-many has no column to filter on - the link lives in a join table.
+     * A one-to-many could be asked for either way; going through one method means
+     * the caller does not have to know which it is looking at.
+     */
+    listRelated(model: string, id: RecordId, relationField: string, query: ListQuery): Promise<Page<RecordData>>;
+    /**
+     * Link an existing record to this one.
+     *
+     * Across a many-to-many this adds a row to the join table and changes
+     * neither record. Across a one-to-many it rewrites the child's foreign key,
+     * which also **removes it from whatever parent held it** - the same operation
+     * with a consequence the caller should have been told about. Deciding whether
+     * to warn is the transport layer's job; the adapter performs what it is asked.
+     */
+    attachRelated(model: string, id: RecordId, relationField: string, targetId: RecordId): Promise<void>;
+    /**
+     * Unlink a record from this one, without deleting either.
+     *
+     * Across a one-to-many this clears the child's foreign key, which is
+     * impossible when that column is required - see `detachBlockedReason`. The
+     * adapter may assume the caller has checked, and will surface the database's
+     * own refusal if it has not.
+     */
+    detachRelated(model: string, id: RecordId, relationField: string, targetId: RecordId): Promise<void>;
+}
+
+/**
+ * Which models the admin exposes at all.
+ *
+ * Distinct from resource authorization, and the two answer different questions.
+ * A `ResourceSelection` is structural: it decides what the admin *is*, the same
+ * for everyone, and a model outside it does not exist as far as the admin is
+ * concerned. `AdminResourceAuth` is per-principal: the model exists, and this
+ * caller may or may not act on it.
+ *
+ * That difference is visible in the response. An excluded model answers 404 -
+ * there is no such resource - where a denied one answers 403.
+ */
+interface ResourceSelection {
+    /**
+     * When present, only these models are exposed. Everything else is dropped,
+     * including models added to the schema later - which is the point: an
+     * allow-list does not quietly grow when someone edits the schema.
+     */
+    readonly include?: readonly string[];
+    /**
+     * Models removed from the selection, applied after `include`.
+     *
+     * The usual reason is a table that is not domain data: session stores,
+     * migration bookkeeping, queue tables.
+     */
+    readonly exclude?: readonly string[];
+}
+
+/**
+ * Framework error vocabulary.
+ *
+ * Deliberately small. These exist so that adapters raise ORM-independent
+ * errors and the transport layer can map them to status codes without knowing
+ * which ORM produced them. Resist growing this taxonomy - add a new type only
+ * when a caller genuinely needs to branch on it.
+ *
+ * ## Why these are not identified with `instanceof`
+ *
+ * A published bundle can contain more than one copy of this module. The
+ * package ships two CommonJS entrypoints and each inlines its own copy of
+ * Core, so an error thrown inside the Prisma adapter is an instance of a
+ * *different* `FieldNotFoundError` class than the one the exception filter
+ * holds. `instanceof` compares class identity, so it answered `false` and
+ * every adapter-raised error was mapped to a generic 500 - a caller who
+ * mistyped a sort field got "internal error" instead of "unknown field".
+ *
+ * That was invisible to this repository's own tests, which resolve Core to a
+ * single source module, and only appeared when the built package was installed
+ * and run. So errors are identified by *value* rather than identity: a
+ * `Symbol.for` brand, which duplicate copies agree on by definition, plus a
+ * stable `kind` string. Neither depends on which copy created the object.
+ *
+ * `scripts/verify-packed-consumer.mjs` asserts the arrangement every release:
+ * one shared copy in ESM, one per entrypoint in CJS. If that ever changes, the
+ * count changes there first.
+ *
+ * @experimental Draft contract. Expected to change during MVP implementation.
+ */
+/**
+ * Stable discriminator for each error type.
+ *
+ * A declared string rather than the class, so it survives duplicate bundles,
+ * and rather than `name`, so it survives minification.
+ */
+type AdminErrorKind = 'unauthorized' | 'forbidden' | 'model-not-found' | 'field-not-found' | 'record-not-found' | 'invalid-query'
+/** Application code refused the input. Its message reaches the client. */
+ | 'validation'
+/** The database refused the write: unique, foreign key, or required. */
+ | 'constraint' | 'adapter'
+/** A subclass that declared no kind of its own. Treated as internal. */
+ | 'unknown';
+/**
+ * Base error type. Every error raised by Nest Admin extends it so that the
+ * NestJS integration can distinguish framework errors from application errors
+ * without depending on concrete subclasses.
+ */
+declare class NestAdminError extends Error {
+    /**
+     * Which error this is.
+     *
+     * Subclasses override it with a literal. The base value covers anything that
+     * extends this class without declaring one - the Prisma schema errors, for
+     * instance - which the transport layer treats as internal.
+     */
+    readonly kind: AdminErrorKind;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Is this one of ours?
+ *
+ * Works across duplicate copies of this module, which `instanceof` does not.
+ */
+declare function isNestAdminError(value: unknown): value is NestAdminError;
+/** The requested model is not part of the admin's resource set. */
+declare class ModelNotFoundError extends NestAdminError {
+    readonly model: string;
+    readonly availableModels: readonly string[];
+    readonly kind: "model-not-found";
+    constructor(model: string, availableModels?: readonly string[]);
+}
+/** A referenced field does not exist on the model, or cannot be used this way. */
+declare class FieldNotFoundError extends NestAdminError {
+    readonly model: string;
+    readonly field: string;
+    readonly kind: "field-not-found";
+    constructor(model: string, field: string, reason?: string);
+}
+/** No record matched the given identifier. */
+declare class RecordNotFoundError extends NestAdminError {
+    readonly model: string;
+    readonly id: unknown;
+    readonly kind: "record-not-found";
+    constructor(model: string, id: unknown);
+}
+/**
+ * The query is structurally invalid - an unusable operator/field combination,
+ * a malformed value, or a request the adapter cannot express.
+ */
+declare class InvalidQueryError extends NestAdminError {
+    readonly kind: "invalid-query";
+}
+/**
+ * The input is not acceptable, and the caller should be told why.
+ *
+ * Raised by application code - a hook rejecting a value, a rule the schema
+ * cannot express - rather than by the framework. It exists because such a
+ * refusal has to reach the person who typed the value, and the alternatives are
+ * wrong in one direction or the other: `InvalidQueryError` claims the *query*
+ * was malformed, and anything unrecognised becomes a generic 500 with the
+ * message withheld.
+ *
+ * The message **is** forwarded to the client, which is the point of it and also
+ * the responsibility that comes with it: whatever goes in is published.
+ *
+ * Naming the fields it is about is optional and worth doing. An interface that
+ * knows which input was refused can say so next to that input, where the person
+ * is looking, instead of in a banner above a form they then have to re-read.
+ */
+declare class ValidationError extends NestAdminError {
+    /** The inputs this is about. Empty when it is about the record as a whole. */
+    readonly fields: readonly string[];
+    readonly kind: "validation";
+    constructor(message: string, 
+    /** The inputs this is about. Empty when it is about the record as a whole. */
+    fields?: readonly string[], options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * What the database refused, and about which fields.
+ *
+ * The distinction that matters is between a request that is *wrong* and a
+ * database that is *broken*. A duplicate email, a foreign key pointing at
+ * nothing, a missing required value - these are ordinary mistakes a person
+ * makes in a form, and until they were told apart from a real failure the admin
+ * answered every one of them with "an internal error occurred".
+ *
+ * The message is built here, from the constraint and the field names, rather
+ * than taken from the ORM. An ORM's own text carries file paths, generated
+ * query fragments and the values that collided, none of which should be
+ * published - which is exactly why the generic 500 existed in the first place.
+ */
+type ConstraintKind = 
+/** A value that has to be unique is not. */
+'unique'
+/** A reference points at a record that is not there, or is still referenced. */
+ | 'foreign-key'
+/** A value the database requires was not supplied. */
+ | 'required';
+declare class ConstraintError extends NestAdminError {
+    readonly constraint: ConstraintKind;
+    readonly model: string;
+    /** The columns involved. Empty when the ORM did not say. */
+    readonly fields: readonly string[];
+    readonly kind: "constraint";
+    constructor(constraint: ConstraintKind, model: string, 
+    /** The columns involved. Empty when the ORM did not say. */
+    fields?: readonly string[]);
+}
+/**
+ * The underlying ORM or database failed. Always wraps the original error as
+ * `cause` so the real failure is never lost.
+ */
+declare class AdapterError extends NestAdminError {
+    readonly kind: "adapter";
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * No authenticated identity was presented with the request.
+ *
+ * Raised by the host application's admin auth implementation, never by Core
+ * itself - Core has no notion of a request, a header or a session, and must
+ * not acquire one. It exists here so the transport layer can map it without
+ * knowing which framework produced it.
+ *
+ * The default message is deliberately uninformative. An authentication failure
+ * must not reveal whether a credential was absent, malformed, expired or
+ * simply wrong.
+ */
+declare class UnauthorizedError extends NestAdminError {
+    readonly kind: "unauthorized";
+    constructor(message?: string);
+}
+/**
+ * An identity was established, but it is not permitted to do this.
+ *
+ * Deliberately distinct from {@link UnauthorizedError}: collapsing the two
+ * leaves a client unable to tell "log in" from "you cannot do this", and
+ * pushes that guesswork into every consumer.
+ */
+declare class ForbiddenError extends NestAdminError {
+    readonly kind: "forbidden";
+    constructor(message?: string);
+}
+
+/**
+ * Buttons the application adds.
+ *
+ * CRUD covers what a schema implies. It does not cover "publish", "resend the
+ * invitation", "recalculate the total" - operations that are obvious to the
+ * domain and invisible to the database. Without somewhere to put them, the
+ * usual answer is a second internal tool beside the admin.
+ *
+ * An action is defined once and drawn by the interface from metadata, so adding
+ * one is a server-side change and needs no rebuild of the UI.
+ *
+ * ## Authorization
+ *
+ * Actions are a distinct operation, `'action'`, rather than folded into
+ * `update`. An action can do anything, including things no CRUD route offers,
+ * so a policy should be able to decide about it separately - and a policy
+ * written before actions existed denies the unfamiliar value, which is the
+ * right direction to fail in.
+ *
+ * Actions the principal may not run are absent from the metadata, so the
+ * interface does not draw a button that would be refused.
+ */
+
+/** What an action reports back. */
+interface AdminActionResult {
+    /**
+     * A sentence for the person who pressed the button.
+     *
+     * Shown as-is, so it is published - the same responsibility as a
+     * `ValidationError` message.
+     */
+    readonly message?: string;
+}
+interface AdminAction {
+    /** Stable identifier, used in the URL. Letters, digits, `-` and `_`. */
+    readonly name: string;
+    /** What the button says. Defaults to `name`. */
+    readonly label?: string;
+    /**
+     * Whether the action applies to one record or to the model as a whole.
+     *
+     * A `'record'` action is offered on the detail page and receives the record's
+     * id; a `'list'` action is offered above the list and receives none.
+     */
+    readonly scope: 'record' | 'list';
+    /**
+     * Ask before running, with this as the question.
+     *
+     * Worth setting for anything that cannot be undone. The interface refuses to
+     * proceed without an answer; it is not a substitute for the server checking
+     * that the action is permitted.
+     */
+    readonly confirm?: string;
+    /** Draw the button as destructive. Presentation only. */
+    readonly danger?: boolean;
+    /**
+     * The work.
+     *
+     * Throw to refuse: a `ValidationError` reaches the caller with its message,
+     * anything else becomes a 500 with the message withheld.
+     */
+    readonly run: (args: {
+        readonly context: ExecutionContext;
+        readonly model: string;
+        /** Present for a `'record'` action, absent for a `'list'` one. */
+        readonly id?: RecordId;
+    }) => AdminActionResult | void | Promise<AdminActionResult | void>;
+}
+/** Actions per model. Models without an entry have none. */
+type AdminActionsByModel = Readonly<Record<string, readonly AdminAction[]>>;
+
+/**
+ * Application code that runs around a write.
+ *
+ * The admin is generic on purpose: it knows a schema, not a domain. Hashing a
+ * password, deriving a slug, writing an audit row, sending a notification -
+ * none of these can be inferred from a column type, and all of them are the
+ * reason a real application eventually stops using a generic admin. This is the
+ * seam where they go in.
+ *
+ * ## Where they run
+ *
+ * After authorization and after validation, immediately around the adapter
+ * call. A hook is therefore never reached for a request that would have been
+ * refused, and never sees a payload naming a hidden or read-only field.
+ *
+ * ## What a `before` hook returns
+ *
+ * The data to write. Returning a changed object is how a value is added or
+ * rewritten, and returning the object unchanged is fine. It is not applied
+ * blindly: the result is validated again, so a hook cannot introduce a field
+ * the admin refuses to write.
+ *
+ * ## Failing
+ *
+ * Throw. A `ValidationError` reaches the caller with its message intact and is
+ * the way to refuse an input for a reason a person should read. Anything else
+ * becomes a 500 with the message withheld, which is the right treatment for a
+ * hook that broke rather than one that objected.
+ *
+ * Nothing is transactional. An `after` hook that throws leaves the write
+ * already done, so it should be used for work whose failure is not worse than
+ * its absence - and anything that must be atomic belongs in the application's
+ * own transaction, not here.
+ */
+
+/** What every hook is given. */
+interface AdminHookContext {
+    /**
+     * The NestJS execution context for the request being served.
+     *
+     * Reach the principal through it, exactly as in `AdminAuth.authorize` and
+     * `AdminResourceAuth.authorize` - one accessor works for all three.
+     */
+    readonly context: ExecutionContext;
+    /** The model being written. */
+    readonly model: string;
+}
+interface AdminHooks {
+    /** Runs before a record is created. Returns the data to write. */
+    readonly beforeCreate?: (args: AdminHookContext & {
+        readonly data: RecordData;
+    }) => RecordData | Promise<RecordData>;
+    /** Runs after a record is created. Its return value is ignored. */
+    readonly afterCreate?: (args: AdminHookContext & {
+        readonly record: RecordData;
+    }) => void | Promise<void>;
+    /**
+     * Runs before a record is updated. Returns the data to write.
+     *
+     * The data is the *patch*, not the whole record: only the fields the request
+     * named are present.
+     */
+    readonly beforeUpdate?: (args: AdminHookContext & {
+        readonly id: RecordId;
+        readonly data: RecordData;
+    }) => RecordData | Promise<RecordData>;
+    readonly afterUpdate?: (args: AdminHookContext & {
+        readonly id: RecordId;
+        readonly record: RecordData;
+    }) => void | Promise<void>;
+    /**
+     * Runs before a record is deleted.
+     *
+     * Throw to refuse the deletion - a `ValidationError` says why in a way the
+     * caller can read.
+     */
+    readonly beforeDelete?: (args: AdminHookContext & {
+        readonly id: RecordId;
+    }) => void | Promise<void>;
+    /** Runs after a record is deleted. The record is already gone. */
+    readonly afterDelete?: (args: AdminHookContext & {
+        readonly id: RecordId;
+    }) => void | Promise<void>;
+}
+/** Hooks per model. Models without an entry have none. */
+type AdminHooksByModel = Readonly<Record<string, AdminHooks>>;
+
+/**
+ * Implemented by the consuming application and passed to
+ * `AdminModule.forRoot({ auth })`.
+ *
+ * ```ts
+ * const auth: AdminAuth = {
+ *   authorize(context) {
+ *     const request = context.switchToHttp().getRequest()
+ *     if (!request.user) throw new UnauthorizedError()
+ *     if (!request.user.isStaff) throw new ForbiddenError()
+ *   },
+ * }
+ * ```
+ */
+interface AdminAuth {
+    /**
+     * Decide whether the request may proceed.
+     *
+     * Return (or resolve) normally to allow it. To deny it, throw:
+     *
+     * - {@link UnauthorizedError} - no identity was established. 401.
+     * - {@link ForbiddenError} - an identity exists but may not do this. 403.
+     *
+     * Throwing is the intended way to deny, because it forces the caller to say
+     * *which* denial it is. A client cannot act on "denied"; it can act on "log
+     * in" versus "you may not do this".
+     *
+     * Returning `false` is also treated as a denial, mapped to `403`, so a guard
+     * written in the reflexive NestJS style still fails closed rather than
+     * silently allowing the request. Prefer throwing: `false` cannot express the
+     * 401/403 distinction, and 403 is only the safer of the two guesses.
+     *
+     * May be synchronous or asynchronous.
+     *
+     * @param context The NestJS execution context. Use it to reach the request -
+     *   including any principal the host application already attached, and the
+     *   `model` route parameter on per-model routes.
+     */
+    authorize(context: ExecutionContext): void | boolean | Promise<void | boolean>;
+}
+/**
+ * An {@link AdminAuth} that permits every request. **The admin API becomes
+ * completely public.**
+ *
+ * It exists because `auth` is required, and a required option with no escape
+ * hatch pushes people toward writing their own always-allow implementation -
+ * which is the same hole, only invisible in review. This one is deliberately
+ * hard to mistake for anything else: the name says `unsafe`, and it logs a
+ * warning every time an application starts with it.
+ *
+ * Intended for local development, examples and tests. Never for a deployed
+ * application.
+ */
+declare function unsafeAllowAllRequests(): AdminAuth;
+
+/**
+ * The resource authorization boundary.
+ *
+ * Phase 4 gave the host a say over whether a *request* may enter the admin at
+ * all (`AdminAuth`). This answers a narrower question: may this principal touch
+ * *this model*, for *this operation*?
+ *
+ * The two are deliberately separate contracts. A host that only needs "staff
+ * only" implements `AdminAuth` and stops; a host that needs "support can read
+ * Users but nobody outside finance sees Payment" adds this one. Folding them
+ * together would force every consumer to think about resources whether or not
+ * they have per-resource rules.
+ *
+ * Why this exists at all: a host can already deny per model from `AdminAuth`,
+ * because the guard sees `params.model`. But `GET /admin/meta` has no `:model`
+ * segment, so route-level checks cannot stop the metadata endpoint from
+ * describing every table in the database - and the admin UI renders itself from
+ * that endpoint. Resource authorization has to live where metadata is produced.
+ */
+
+/**
+ * What the caller is trying to do.
+ *
+ * `'metadata'` is the odd one out: it is not an operation on records, it asks
+ * whether the model should be *visible* to this principal at all. A model that
+ * fails a `'metadata'` check disappears from `GET /admin/meta` entirely.
+ */
+type AdminOperation = 'metadata' | 'list' | 'read' | 'create' | 'update' | 'delete'
+/**
+ * An application-defined action.
+ *
+ * Distinct from `update` because an action can do anything, including things
+ * no CRUD route offers, so a policy should be able to decide about it
+ * separately. A policy written before actions existed does not recognise the
+ * value and denies it, which is the right direction to fail in.
+ */
+ | 'action';
+/** Everything the policy is given to decide with. */
+interface ResourceAuthorization {
+    /**
+     * The NestJS execution context for the request being served. Use it to reach
+     * whatever principal the host application attached to the request - exactly
+     * as in `AdminAuth.authorize`, so one accessor works for both contracts.
+     */
+    readonly context: ExecutionContext;
+    /** The model name as the schema declares it, e.g. `User`. */
+    readonly model: string;
+    readonly operation: AdminOperation;
+}
+/**
+ * Implemented by the consuming application and passed to
+ * `AdminModule.forRoot({ resourceAuth })`.
+ *
+ * ```ts
+ * const resourceAuth: AdminResourceAuth = {
+ *   authorize({ context, model, operation }) {
+ *     const { user } = context.switchToHttp().getRequest()
+ *     if (model === 'AuditLog') return user.isAdmin
+ *     if (operation === 'delete') return user.isAdmin
+ *     return true
+ *   },
+ * }
+ * ```
+ */
+interface AdminResourceAuth {
+    /**
+     * Decide whether this principal may perform `operation` on `model`.
+     *
+     * Return `true`, or return nothing, to allow. To deny, return `false` or
+     * throw `ForbiddenError`. Both are treated identically - unlike
+     * `AdminAuth`, there is no 401/403 ambiguity to resolve here, because a
+     * request that reached this point has already passed authentication.
+     *
+     * The consequence of a denial depends on the operation:
+     *
+     * - `'metadata'` - the model is **omitted** from `GET /admin/meta`. It is not
+     *   an error; the response simply describes a smaller schema.
+     * - everything else - the request fails with `403 FORBIDDEN`, and the ORM
+     *   adapter is never called.
+     *
+     * Anything else thrown is treated as a bug in the host's policy: the request
+     * fails with a generic 500 and the real error is logged. A failing policy
+     * never allows access.
+     *
+     * May be synchronous or asynchronous.
+     */
+    authorize(resource: ResourceAuthorization): void | boolean | Promise<void | boolean>;
+}
+
+/**
+ * What an application puts on the dashboard.
+ *
+ * ## A closed set of four
+ *
+ * `count`, `list`, `chart`, `stat`. Closed for the same reason `FieldWidget` is:
+ * the interface has to know how to draw each one, so an open string would mean
+ * rendering nothing and no way to notice.
+ *
+ * It is also the line this release does not cross. An arbitrary React component
+ * would mean the consuming application builds and bundles one, which is exactly
+ * the thing this package exists not to make people do - and the reason custom
+ * pages have been out of scope since 0.6.0.
+ *
+ * ## Three of them are declarative on purpose
+ *
+ * `count`, `list` and `chart` name a model and a filter; the server does the
+ * work. That is not just terseness. A widget that names a model can be
+ * *authorized*: one over a resource this principal cannot see is absent from
+ * the document, the same way a hidden model and a refused action already are.
+ * A widget built from a closure could not be checked, only trusted.
+ *
+ * `stat` is the escape hatch and has no model, because the number it shows may
+ * come from anywhere - a payment processor, a queue, three tables joined. It
+ * runs application code, so the application's own rules apply to it.
+ *
+ * ## Nothing is configured by default
+ *
+ * An admin with no `dashboard` option still gets one, built from metadata
+ * alone: a count per model, and recent records where the schema says when a
+ * record was created. Declaring widgets replaces that rather than adding to it,
+ * because a dashboard is a page someone designed, and half-designed is worse
+ * than either.
+ */
+
+/** How wide a widget sits in the four-column grid. */
+type WidgetSpan = 1 | 2 | 3 | 4;
+interface Common {
+    /** Shown above it. The one thing every widget needs. */
+    readonly title: string;
+    /** A sentence under the title, when the title cannot carry it alone. */
+    readonly description?: string;
+    /** Columns out of four. Sensible per kind when omitted. */
+    readonly span?: WidgetSpan;
+}
+/**
+ * A single number, from a model.
+ *
+ * The most common thing on any dashboard, and the reason it is declarative:
+ * "how many open orders" is a model, a filter, and nothing else.
+ */
+interface CountWidget extends Common {
+    readonly kind: 'count';
+    readonly model: string;
+    /** `field:op:value`, the same syntax the list screen's URL uses. */
+    readonly filter?: string;
+    /**
+     * Compare against the same count a period ago, and show the change.
+     *
+     * Needs the model to have a creation timestamp; the comparison is silently
+     * omitted when it does not, rather than the widget disappearing.
+     */
+    readonly compareDays?: number;
+}
+/** A few records, most recent first where the model says which those are. */
+interface ListWidget extends Common {
+    readonly kind: 'list';
+    readonly model: string;
+    readonly filter?: string;
+    /** How many rows. Five by default; more than ten belongs on the list screen. */
+    readonly limit?: number;
+}
+/** How many records appeared per day, week or month. */
+interface ChartWidget extends Common {
+    readonly kind: 'chart';
+    readonly model: string;
+    readonly filter?: string;
+    readonly bucket?: 'day' | 'week' | 'month';
+    /** How many buckets. Thirty by default, ninety at most - see the service. */
+    readonly buckets?: number;
+}
+/**
+ * A number the application works out for itself.
+ *
+ * The escape hatch, and the only widget that runs application code. Whatever it
+ * returns is shown; whatever it throws becomes a widget that says it could not
+ * load, rather than a dashboard that does not.
+ */
+interface StatWidget extends Common {
+    readonly kind: 'stat';
+    readonly load: (args: {
+        readonly context: ExecutionContext;
+    }) => Promise<StatResult> | StatResult;
+}
+interface StatResult {
+    /** Shown large. A string is passed through, so it can carry a currency. */
+    readonly value: string | number;
+    /** A change against some previous period, as a percentage. */
+    readonly delta?: number;
+    /** Under the value. "vs last month", "across 4 regions". */
+    readonly hint?: string;
+}
+type DashboardWidget = CountWidget | ListWidget | ChartWidget | StatWidget;
+/**
+ * The dashboard an application declares.
+ *
+ * An array rather than a keyed object: a dashboard is read top to bottom, and
+ * the order things appear in is part of the design.
+ */
+type AdminDashboard = readonly DashboardWidget[];
+
+interface AdminTheme {
+    /**
+     * Accent colour, as a CSS hex value - `#0b6e6e` or `#0b6`.
+     *
+     * Hex only. A full CSS colour grammar would mean parsing one, and a value
+     * this small is not worth a parser; named colours and `rgb()` are excluded
+     * for the same reason.
+     */
+    readonly brandColor?: string;
+    /** Page title and the name shown in the header. Plain text. */
+    readonly title?: string;
+    /**
+     * Logo shown beside the title.
+     *
+     * An `http(s)` URL or a `data:image/...` URI. Other schemes are refused:
+     * `javascript:` in an image source is the obvious one, but the rule is a
+     * whitelist rather than a blacklist so there is nothing to keep up with.
+     */
+    readonly logoUrl?: string;
+    /**
+     * Which appearance to start from, before anyone chooses.
+     *
+     * `'system'` follows the viewer's operating system and is the default. A
+     * viewer's own choice, once made, wins over this and is remembered by their
+     * browser - so this sets the first impression rather than a policy.
+     */
+    readonly appearance?: 'system' | 'light' | 'dark';
+}
+
+/**
+ * `AdminModule` - the NestJS integration.
+ *
+ * ```ts
+ * AdminModule.forRoot({
+ *   adapter: new PrismaAdapter({ client: prisma }),
+ *   auth: myAdminAuth,
+ * })
+ * ```
+ *
+ * The module wires an `OrmAdapter` and an `AdminAuth` into the admin HTTP
+ * layer and does nothing else. It does not construct a database client, does
+ * not authenticate anyone, does not read configuration from disk, and holds no
+ * module-level mutable state - so two instances in the same process cannot
+ * interfere with each other.
+ *
+ * It is not `@Global()`: making a library's providers globally visible in
+ * someone else's application is a decision the application should make.
+ */
+
+interface AdminModuleOptions {
+    /**
+     * The ORM adapter the admin reads and writes through.
+     *
+     * Constructed by the consuming application, never by the framework: under
+     * Prisma 7 a client is built from a driver adapter, so only the application
+     * knows the provider, the credentials and the connection strategy.
+     */
+    readonly adapter: OrmAdapter;
+    /**
+     * Decides whether a request may reach the admin.
+     *
+     * **Required, deliberately.** The admin exposes every record in the database
+     * and, through `/admin/meta`, the shape of the entire schema. An optional
+     * option defaulting to "open" would mean a forgotten line in a config file
+     * silently publishes the database - the failure would be invisible until
+     * someone else found it.
+     *
+     * For local development and examples, pass `unsafeAllowAllRequests()`, which
+     * is explicit at the call site and warns at startup.
+     */
+    readonly auth: AdminAuth;
+    /**
+     * Decides which models this principal may see and act on.
+     *
+     * Optional, defaulting to allowing every model. Unlike `auth`, that default
+     * is not a hole: `auth` is required, so the door is already shut, and
+     * omitting this only means everyone admitted sees the whole schema - exactly
+     * the behaviour before the option existed. Requiring it would break every
+     * existing consumer to express a rule most applications do not have.
+     *
+     * Supply it when some models should be invisible or read-only to some
+     * principals. A model denied for `'metadata'` disappears from
+     * `GET /admin/meta`; a model denied for any other operation makes the request
+     * fail with 403 before the ORM adapter is called.
+     */
+    readonly resourceAuth?: AdminResourceAuth;
+    /**
+     * Where the admin is mounted. Defaults to `/admin`.
+     *
+     * Accepts `admin`, `/admin` and `/admin/` alike, and may be nested, as in
+     * `/internal/admin`. It cannot be empty or `/`: these routes end in
+     * `:model`, so mounting them at the root would capture every unmatched
+     * request in the host application.
+     *
+     * The API and the UI move together. There is one mount point, not two.
+     */
+    readonly path?: string;
+    /**
+     * Which models the admin exposes at all. Defaults to every model the adapter
+     * reports.
+     *
+     * Structural, and not a substitute for `resourceAuth`: this is the same for
+     * every principal, so an excluded model answers 404 rather than 403. Use it
+     * for tables that are not domain data - session stores, migration
+     * bookkeeping, queues - and `resourceAuth` for who may do what.
+     *
+     * A name that matches no model fails at startup rather than being ignored: a
+     * typo in `exclude` would otherwise leave the model exposed.
+     */
+    readonly resources?: ResourceSelection;
+    /**
+     * Per-model configuration: labels, widgets, ordering, and the two that are
+     * enforced rather than suggested - hidden and readOnly.
+     *
+     * A hidden field is removed from the metadata every layer reads, so it cannot
+     * be filtered, sorted, written, or returned. A name matching no model or
+     * field fails at startup.
+     */
+    readonly models?: ModelOverrides;
+    /**
+     * Application code that runs around a write, per model.
+     *
+     * Where hashing a password, deriving a slug or writing an audit row goes -
+     * none of which can be inferred from a column type. See `AdminHooks`.
+     */
+    readonly hooks?: AdminHooksByModel;
+    /**
+     * Buttons the application adds, per model.
+     *
+     * CRUD covers what a schema implies; "publish" and "resend the invitation"
+     * are obvious to the domain and invisible to the database. See `AdminAction`.
+     */
+    readonly actions?: AdminActionsByModel;
+    /**
+     * Branding the served page applies without a rebuild: an accent colour, a
+     * title, a logo. Structural, because the page is rendered before any
+     * provider exists.
+     */
+    readonly theme?: AdminTheme;
+    /**
+     * What the dashboard shows.
+     *
+     * Omit it and the dashboard is built from the schema: a count per model, the
+     * newest records, and a month of activity. Declaring widgets replaces that
+     * rather than adding to it - a dashboard is a page someone designed, and
+     * half-designed is worse than either.
+     */
+    readonly dashboard?: AdminDashboard;
+    /**
+     * Directory holding the built admin UI.
+     *
+     * Defaults to the copy bundled inside this package, which is what a consumer
+     * wants and why it is optional. Overriding it exists for this repository's
+     * own tests, which run from `src` while the built UI lives in `dist`.
+     *
+     * @internal
+     */
+    readonly uiRoot?: string;
+}
+/**
+ * What a `forRootAsync` factory returns.
+ *
+ * Everything except the structural options, which are decided when the module
+ * is defined and so cannot come from a provider - see `forRootAsync`.
+ */
+type AdminModuleFactoryOptions = Omit<AdminModuleOptions, 'path' | 'uiRoot' | 'theme'>;
+/** Supply options from a class rather than a factory function. */
+interface AdminModuleOptionsFactory {
+    createAdminOptions(): AdminModuleFactoryOptions | Promise<AdminModuleFactoryOptions>;
+}
+interface AdminModuleAsyncOptions {
+    /** As `AdminModuleOptions.path`. Structural, so it is not from the factory. */
+    readonly path?: string;
+    /** @internal As `AdminModuleOptions.uiRoot`. */
+    readonly uiRoot?: string;
+    /**
+     * As `AdminModuleOptions.theme`. Structural, so it is not from the factory:
+     * the shell is rendered from it and no provider exists at that point.
+     */
+    readonly theme?: AdminTheme;
+    /** Modules whose providers the factory needs. */
+    readonly imports?: ModuleMetadata['imports'];
+    /** Providers passed to `useFactory`, in order. */
+    readonly inject?: FactoryProvider['inject'];
+    readonly useFactory?: (...args: never[]) => AdminModuleFactoryOptions | Promise<AdminModuleFactoryOptions>;
+    /** Instantiated by Nest, then asked for the options. */
+    readonly useClass?: Type<AdminModuleOptionsFactory>;
+    /** An options factory the application already provides elsewhere. */
+    readonly useExisting?: Type<AdminModuleOptionsFactory>;
+}
+declare class AdminModule {
+    static forRoot(options: AdminModuleOptions): DynamicModule;
+    /**
+     * The same module, with the adapter and the auth policy resolved through DI.
+     *
+     * For the ordinary case where those things are not available when the module
+     * is declared: a `PrismaService` that belongs to another module, a connection
+     * string that comes from `ConfigService`.
+     *
+     * ```ts
+     * AdminModule.forRootAsync({
+     *   imports: [PrismaModule, ConfigModule],
+     *   inject: [PrismaService, ConfigService],
+     *   useFactory: (prisma: PrismaService, config: ConfigService) => ({
+     *     adapter: new PrismaAdapter({ client: prisma }),
+     *     auth: new SessionAdminAuth(config.get('ADMIN_ROLE')),
+     *   }),
+     * })
+     * ```
+     *
+     * `path` stays on this object rather than coming from the factory. Routes are
+     * registered when the module is defined, which is before any provider has
+     * been instantiated, so the mount path cannot wait for an injection - and a
+     * `path` returned from the factory would be silently ignored, which is worse
+     * than not offering it.
+     */
+    static forRootAsync(options: AdminModuleAsyncOptions): DynamicModule;
+}
+
+/**
+ * An `AdminAuth` that ships in the box.
+ *
+ * ## This does not move the boundary
+ *
+ * `AdminAuth` is unchanged and still the only way in. An application with its
+ * own identity system implements it and never sees any of this. What changes is
+ * that an application *without* one no longer has to write a password hash, a
+ * cookie and a form before the admin can be put behind a login.
+ *
+ * So there are three answers to "who may open this?", and a consumer picks one:
+ *
+ *     auth: unsafeAllowAllRequests()   development only, warns at startup
+ *     auth: myOwnAuth                  an application that already has identity
+ *     auth: builtInAuth({ ... })       a login page, sessions and a store
+ *
+ * ## The accounts are separate from the application's users
+ *
+ * By construction: the store is a contract over storage the application
+ * nominates, and the intended shape is a model of its own. The admin never
+ * consults the application's user table to decide who may sign in, and adding
+ * a customer never adds someone who can administer the system.
+ */
+
+interface BuiltInAuthOptions {
+    /**
+     * Where the accounts live.
+     *
+     * `prismaAccountStore` from `@nest-admin/nestjs/prisma` covers the usual
+     * case; anything satisfying the contract works.
+     */
+    readonly store: AdminAccountStore;
+    readonly session: {
+        /**
+         * The key the session cookie is signed with. **Required.**
+         *
+         * At least 32 characters, checked at startup. A short secret is a
+         * forgeable cookie, and the failure is silent: everything works, and
+         * anybody can mint a session for any account.
+         *
+         * Read it from the environment. A secret in source control is a secret
+         * everyone who has ever cloned the repository knows.
+         */
+        readonly secret: string;
+        /** How long a session lasts, in seconds. Twelve hours by default. */
+        readonly maxAge?: number;
+        /** The cookie's name. Change it only to avoid a collision. */
+        readonly cookieName?: string;
+        /**
+         * Send the cookie only over HTTPS.
+         *
+         * Left unset it is decided per request: on for everything except
+         * localhost, which is what makes the admin work in development without
+         * being insecure anywhere else. Set it to `true` to require HTTPS always.
+         */
+        readonly secure?: boolean;
+    };
+    /** Failed attempts before a pause. Ten by default. */
+    readonly maxAttempts?: number;
+    /** How long that pause lasts, in seconds. Fifteen minutes by default. */
+    readonly lockoutSeconds?: number;
+}
+/**
+ * The account this request signed in as.
+ *
+ * For a `resourceAuth` policy or a hook that needs to know who is asking.
+ * `undefined` when the admin is not using the built-in auth, which is why it
+ * is optional rather than assumed.
+ */
+declare function adminAccountOf(context: ExecutionContext): AdminAccountSummary | undefined;
+declare function builtInAuth(options: BuiltInAuthOptions): AdminAuth;
+
+/**
+ * Hash a password for storage.
+ *
+ * Exported for the application, because creating accounts is its business -
+ * a seed script, a migration, or a form of its own. The admin never mints an
+ * administrator; see `AdminAccountStore` for why.
+ */
+declare function hashAdminPassword(password: string): Promise<string>;
+/**
+ * Does this password match this stored hash?
+ *
+ * Never throws for a malformed or unrecognised hash - it answers `false`. A
+ * store holding something this function does not understand is a configuration
+ * problem, and turning it into a 500 on the login route would tell an attacker
+ * that the account exists and that its record is unusual.
+ *
+ * The comparison is `timingSafeEqual`, not `===`. String equality returns as
+ * soon as two bytes differ, and the difference is measurable often enough to
+ * recover a hash a byte at a time.
+ */
+declare function verifyAdminPassword(password: string, stored: string): Promise<boolean>;
+
+/** A secret of the right shape, for a consumer that needs one generated. */
+declare function generateSessionSecret(): string;
+
+/**
+ * The response envelope.
+ *
+ * Every admin endpoint returns the same two shapes, so a generic frontend can
+ * branch on one field rather than on status codes plus per-endpoint knowledge.
+ *
+ * Success:  { success: true,  data: <payload>, meta?: <pagination> }
+ * Failure:  { success: false, error: { code, message, details? } }
+ *
+ * @experimental The HTTP contract is expected to change before 1.0.
+ */
+/** Pagination facts a list response carries alongside its rows. */
+interface PageMeta {
+    readonly total: number;
+    readonly page: number;
+    readonly perPage: number;
+}
+interface SuccessResponse<T> {
+    readonly success: true;
+    readonly data: T;
+    readonly meta?: PageMeta;
+}
+/**
+ * Stable, machine-readable error codes.
+ *
+ * Clients branch on these, never on the human-readable message. Adding a code
+ * is a compatible change; renaming one is not.
+ */
+type AdminErrorCode = 'UNAUTHORIZED' | 'FORBIDDEN' | 'MODEL_NOT_FOUND' | 'RECORD_NOT_FOUND' | 'FIELD_NOT_FOUND' | 'INVALID_QUERY' | 'VALIDATION_ERROR' | 'CONSTRAINT_VIOLATION' | 'INTERNAL_ERROR';
+interface ErrorResponse {
+    readonly success: false;
+    readonly error: {
+        readonly code: AdminErrorCode;
+        readonly message: string;
+        /** Structured context, e.g. `{ model, field }`. Never internal detail. */
+        readonly details?: Readonly<Record<string, unknown>>;
+    };
+}
+type AdminResponse<T> = SuccessResponse<T> | ErrorResponse;
+
+/**
+ * The public HTTP representation of model metadata.
+ *
+ * This is the contract between the backend and any future admin frontend, and
+ * it is deliberately declared separately from Core's `ModelMetadata` rather
+ * than serialised straight from it. Two reasons:
+ *
+ *   1. Core's contract is marked `@experimental` and will keep moving. The wire
+ *      format must not move with it by accident.
+ *   2. An explicit mapper is a whitelist. If a future adapter puts something
+ *      ORM-specific on `FieldMetadata`, it cannot silently reach a client.
+ *
+ * Nothing here mentions Prisma, DMMF, or any ORM. Replacing the Prisma adapter
+ * with another one must not change a single byte of this shape.
+ *
+ * @experimental The HTTP contract is expected to change before 1.0.
+ */
+
+/** Mirrors Core's `FieldKind`, restated so the wire format is self-contained. */
+type FieldKindDto = 'string' | 'number' | 'boolean' | 'datetime' | 'enum' | 'json' | 'relation' | 'unknown';
+interface RelationDto {
+    readonly targetModel: string;
+    readonly cardinality: 'one' | 'many';
+    /**
+     * Scalar field on this model holding the key, for a to-one relation.
+     *
+     * The UI needs it twice over: it is the field a form submits when the user
+     * picks a related record, and the field a filter is expressed in. Absent on
+     * to-many relations, which have no column on this side.
+     */
+    readonly from?: string;
+    /** Field on the target the key points at - usually its id. */
+    readonly to?: string;
+    /**
+     * Where the link is stored, which decides what may be done to it.
+     *
+     * Computed on the server rather than left for the client to derive, for the
+     * same reason as `displayField`: working it out needs the other half of the
+     * relation, and two implementations of that rule would drift. A client that
+     * guessed wrong would offer a button that cannot work.
+     */
+    readonly shape?: 'to-one' | 'one-to-many' | 'many-to-many';
+    /**
+     * Why records cannot be detached from this relation, when they cannot.
+     *
+     * Present only for a one-to-many whose child key is required: such a child
+     * cannot exist without a parent, so there is nothing to detach it to.
+     */
+    readonly detachBlocked?: string;
+    /**
+     * The column on the target model that points back at this one.
+     *
+     * What "all the posts by this author" is expressed as:
+     * `?filter=<targetForeignKey>:eq:<parentId>`. Present only for a one-to-many,
+     * since a many-to-many has no such column on either side.
+     *
+     * Sent rather than derived, for the same reason as `shape`: finding it means
+     * pairing the two halves of the relation, and a rule implemented twice is a
+     * rule that will eventually disagree with itself.
+     */
+    readonly targetForeignKey?: string;
+}
+interface FieldDto {
+    readonly name: string;
+    readonly kind: FieldKindDto;
+    /** Part of the model's primary key. */
+    readonly isId: boolean;
+    readonly isRequired: boolean;
+    readonly isUnique: boolean;
+    readonly isList: boolean;
+    /**
+     * Produced by the database or ORM (`cuid()`, `now()`, `autoincrement()`,
+     * `@updatedAt`). Display it; do not ask the user for it.
+     */
+    readonly isGenerated: boolean;
+    /**
+     * Literal default to pre-fill on create. Present only for editable fields
+     * that declare one - a generated value has no literal to pre-fill.
+     */
+    readonly defaultValue?: unknown;
+    /** Present when `kind` is `'enum'`. */
+    readonly enumValues?: readonly string[];
+    /**
+     * What to call the field, when the column name is not what people call it.
+     *
+     * Absent unless the application said so. A client falls back to `name`.
+     */
+    readonly label?: string;
+    /**
+     * How the field should be edited, when its kind does not say enough.
+     *
+     * A `string` column may be a sentence, a password or a colour, and the schema
+     * cannot tell them apart.
+     */
+    readonly widget?: 'textarea' | 'password' | 'email' | 'url' | 'color' | 'json';
+    /**
+     * The admin will refuse to write this field.
+     *
+     * True for generated columns, and for anything the application marked
+     * read-only. Enforced: a write naming it is rejected, so a client that
+     * ignores this gets a 400 rather than a surprise.
+     */
+    readonly readOnly: boolean;
+    /**
+     * The admin accepts this field on a write and never sends it back.
+     *
+     * Sent so the interface knows the blank it shows is not the stored value. A
+     * password field that looked empty because the record had none would be a
+     * different thing entirely.
+     */
+    readonly writeOnly?: boolean;
+    /** Present when `kind` is `relation`. */
+    readonly relation?: RelationDto;
+}
+/** Which operations a principal may perform on one model. */
+interface ModelPermissionsDto {
+    readonly list: boolean;
+    readonly read: boolean;
+    readonly create: boolean;
+    readonly update: boolean;
+    readonly delete: boolean;
+}
+/** An application-defined button the interface should draw. */
+interface ActionDto {
+    readonly name: string;
+    readonly label: string;
+    readonly scope: 'record' | 'list';
+    /** Ask this before running. Absent means run straight away. */
+    readonly confirm?: string;
+    /** Draw it as destructive. */
+    readonly danger?: boolean;
+}
+interface ModelDto {
+    readonly name: string;
+    /** Field names forming the primary key. Single-column in this version. */
+    readonly primaryKey: readonly string[];
+    readonly fields: readonly FieldDto[];
+    /**
+     * Field that names a record of this model in one line.
+     *
+     * Sent rather than left for the UI to guess, because the guess would have to
+     * match what the adapter already selected when it loaded the relation. Both
+     * come from one rule in Core, so they cannot disagree.
+     */
+    readonly displayField: string;
+    /**
+     * What this principal may do with the model.
+     *
+     * Sent so the interface can stop offering actions that will be refused. It is
+     * a description of the policy's answers, not the enforcement: every request is
+     * checked again when it arrives, and a client that ignores this gets a 403
+     * rather than access.
+     *
+     * `metadata` is not among them - a model the principal cannot see is absent
+     * from this document entirely.
+     */
+    readonly can: ModelPermissionsDto;
+    /**
+     * Application-defined actions this principal may run.
+     *
+     * Already filtered by the policy: an action that would be refused is absent,
+     * so the interface never draws a button that cannot work.
+     */
+    readonly actions: readonly ActionDto[];
+    /** What to call the model. Absent unless the application said so. */
+    readonly label?: string;
+    /**
+     * Which icon to draw beside it in the navigation.
+     *
+     * One of a closed set the interface knows how to render - see `ModelIcon` in
+     * Core. Absent unless the application named one, and absent is a real answer:
+     * the same icon repeated down a column is decoration.
+     */
+    readonly icon?: ModelIcon;
+}
+interface MetadataDto {
+    readonly models: readonly ModelDto[];
+}
+
+export { type ActionDto, AdapterError, type AdminAccount, type AdminAccountStore, type AdminAccountSummary, type AdminAction, type AdminActionResult, type AdminActionsByModel, type AdminAuth, type AdminDashboard, type AdminErrorCode, type AdminErrorKind, type AdminHookContext, type AdminHooks, type AdminHooksByModel, AdminModule, type AdminModuleAsyncOptions, type AdminModuleFactoryOptions, type AdminModuleOptions, type AdminModuleOptionsFactory, type AdminOperation, type AdminResourceAuth, type AdminResponse, type BuiltInAuthOptions, type ChartWidget, ConstraintError, type ConstraintKind, type CountWidget, type DashboardWidget, type ErrorResponse, type FieldDto, type FieldKind, type FieldKindDto, type FieldMetadata, FieldNotFoundError, type FieldOverride, type FieldWidget, type FilterOperator, type FilterRule, ForbiddenError, InvalidQueryError, type ListQuery, type ListWidget, type MetadataDto, type ModelDto, type ModelMetadata, ModelNotFoundError, type ModelOverride, type ModelOverrides, NestAdminError, type OrmAdapter, type Page, type PageMeta, type RecordData, type RecordId, RecordNotFoundError, type RelationCardinality, type RelationDto, type RelationMetadata, type ResourceAuthorization, type SortDirection, type SortRule, type StatResult, type StatWidget, type SuccessResponse, UnauthorizedError, ValidationError, type WidgetSpan, adminAccountOf, builtInAuth, generateSessionSecret, hashAdminPassword, isNestAdminError, unsafeAllowAllRequests, verifyAdminPassword };