sveltekit-admin 0.5.3 → 0.8.1

package/dist/server/adapters/retry.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Reprise bornée des écritures transactionnelles.
+ *
+ * Une transaction `SERIALIZABLE` peut échouer sur un conflit que le moteur ne
+ * sait pas ordonner (PostgreSQL 40001) ou sur un deadlock (PostgreSQL 40P01,
+ * MySQL 1213). Ces échecs sont transitoires par construction : la transaction
+ * a été annulée entièrement, elle n'a donc rien écrit, et rejouer le même
+ * travail sur un instantané neuf aboutit presque toujours. Sans reprise ils
+ * remontent en 500 alors que rien n'est cassé.
+ *
+ * On ne rejoue QUE ces codes. Un refus de scope (« outside the authorization
+ * scope ») ou une FK invalide ne sont pas transitoires : les rejouer ne ferait
+ * que répéter le même refus, et masquerait un refus légitime derrière une
+ * latence. Le défaut est donc de laisser remonter.
+ *
+ * Pas de temporisation entre les tentatives : au moment où le moteur signale
+ * le conflit, la transaction concurrente est déjà terminée (committée ou
+ * annulée), donc attendre ne change rien à la probabilité de succès. Cela
+ * évite aussi d'introduire des minuteurs dans un chemin d'écriture.
+ */
+export declare function isRetryableWriteError(error: unknown): boolean;
+/**
+ * Exécute `run`, en le rejouant tant que l'échec est un conflit de concurrence
+ * et que le budget de tentatives n'est pas épuisé. `attempts` compte la
+ * tentative initiale : 3 signifie « un essai puis deux reprises ».
+ */
+export declare function withWriteRetry<T>(run: () => Promise<T>, attempts?: number): Promise<T>;

package/dist/server/adapters/retry.js

@@ -0,0 +1,53 @@
+/**
+ * Reprise bornée des écritures transactionnelles.
+ *
+ * Une transaction `SERIALIZABLE` peut échouer sur un conflit que le moteur ne
+ * sait pas ordonner (PostgreSQL 40001) ou sur un deadlock (PostgreSQL 40P01,
+ * MySQL 1213). Ces échecs sont transitoires par construction : la transaction
+ * a été annulée entièrement, elle n'a donc rien écrit, et rejouer le même
+ * travail sur un instantané neuf aboutit presque toujours. Sans reprise ils
+ * remontent en 500 alors que rien n'est cassé.
+ *
+ * On ne rejoue QUE ces codes. Un refus de scope (« outside the authorization
+ * scope ») ou une FK invalide ne sont pas transitoires : les rejouer ne ferait
+ * que répéter le même refus, et masquerait un refus légitime derrière une
+ * latence. Le défaut est donc de laisser remonter.
+ *
+ * Pas de temporisation entre les tentatives : au moment où le moteur signale
+ * le conflit, la transaction concurrente est déjà terminée (committée ou
+ * annulée), donc attendre ne change rien à la probabilité de succès. Cela
+ * évite aussi d'introduire des minuteurs dans un chemin d'écriture.
+ */
+import { codeOf } from '../errors.js';
+/** Codes que le moteur n'émet que pour un conflit de concurrence annulable. */
+const RETRYABLE_CODES = new Set([
+    '40001', // PostgreSQL / CockroachDB — serialization_failure
+    '40P01', // PostgreSQL — deadlock_detected
+    'ER_LOCK_DEADLOCK', // MySQL 1213
+    'ER_LOCK_WAIT_TIMEOUT' // MySQL 1205
+]);
+export function isRetryableWriteError(error) {
+    const code = codeOf(error);
+    return code !== undefined && RETRYABLE_CODES.has(code);
+}
+/**
+ * Exécute `run`, en le rejouant tant que l'échec est un conflit de concurrence
+ * et que le budget de tentatives n'est pas épuisé. `attempts` compte la
+ * tentative initiale : 3 signifie « un essai puis deux reprises ».
+ */
+export async function withWriteRetry(run, attempts = 3) {
+    // La boucle ne couvre que les reprises ; la dernière tentative est le `run`
+    // final, dont l'échec remonte tel quel. Écrit ainsi plutôt qu'en boucle
+    // infinie avec un `throw` de sortie : celle-ci n'aurait aucune sortie
+    // normale, donc une branche inatteignable et non testable.
+    for (let remaining = attempts - 1; remaining > 0; remaining -= 1) {
+        try {
+            return await run();
+        }
+        catch (error) {
+            if (!isRetryableWriteError(error))
+                throw error;
+        }
+    }
+    return run();
+}

package/dist/server/adapters/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * ORM-agnostic where-clause AST. `listQuery.ts#buildWhere` produces this;
+ * each adapter's own `filterCompiler` (see `adapters/prisma/filterCompiler.ts`)
+ * turns it into that ORM's native query shape. Never expose an ORM-specific
+ * operator here (no `mode: 'insensitive'`, no Prisma `not`) — those are
+ * compiler-side decisions made from `LeafFilter.op`, not carried in the AST.
+ */
+export type Filter = CompositeFilter | LeafFilter;
+export interface CompositeFilter {
+    op: 'and' | 'or';
+    clauses: Filter[];
+}
+export interface LeafFilter {
+    op: 'eq' | 'contains' | 'containsExact' | 'startsWith' | 'gte' | 'lte' | 'lt' | 'in' | 'isNull' | 'isNotNull';
+    field: string;
+    value?: unknown;
+}
+import type { Schema, Model } from '../types/schema.js';
+import type { RelationEdge } from '../introspection/relations.js';
+/** Boot-time schema source. One call per handler lifetime — no per-request cost. */
+export interface SchemaIntrospector {
+    introspect(): Schema | Promise<Schema>;
+}
+export interface TargetGuard {
+    targetModel: Model;
+    targetPk: string | number;
+    filter?: Filter;
+}
+/**
+ * Per-request CRUD + relation-read surface `handler.ts` talks to instead of
+ * a raw ORM client. See docs/superpowers/specs/2026-08-13-db-adapter-abstraction-design.md
+ * for the rationale behind each method's shape.
+ */
+export interface DataAdapter {
+    /** Vue liste paginée : toujours tri PK desc, toujours count + fetch ensemble. */
+    listRecords(model: Model, opts: {
+        filter?: Filter;
+        skip: number;
+        take: number;
+    }): Promise<{
+        rows: Record<string, unknown>[];
+        total: number;
+    }>;
+    /**
+     * Lecture générale sans pagination forcée : options de relation FK/m2m,
+     * options de filtre FK sidebar, endpoint `_search`. `orderBy` est le
+     * `Record<string, 'asc' | 'desc'>` déjà exposé tel quel côté config
+     * publique (`AdminHandlerConfig.models[].relations[field].orderBy`) —
+     * transmis de façon opaque, sans traduction.
+     */
+    findMany(model: Model, opts: {
+        filter?: Filter;
+        orderBy?: Record<string, 'asc' | 'desc'>;
+        skip?: number;
+        take?: number;
+    }): Promise<Record<string, unknown>[]>;
+    getRecord(model: Model, id: string | number): Promise<Record<string, unknown> | null>;
+    findFirst(model: Model, filter: Filter): Promise<Record<string, unknown> | null>;
+    countRecords(model: Model, filter?: Filter): Promise<number>;
+    /**
+     * `m2m`'s value carries the TARGET model's PK field name alongside the raw
+     * ids, not just the ids: this adapter has no `Schema`/`RelationGraph` of
+     * its own to resolve a target model from an edge, and `handler.ts` (the
+     * only caller) already resolves the target model before building this
+     * payload, at zero extra cost to it.
+     */
+    createRecord(model: Model, input: {
+        scalars: Record<string, unknown>;
+        m2m?: Record<string, {
+            targetPkField: string;
+            ids: Array<string | number>;
+        }>;
+        targetGuards?: TargetGuard[];
+    }): Promise<Record<string, unknown>>;
+    updateRecord(model: Model, id: string | number, input: {
+        scalars: Record<string, unknown>;
+        m2m?: Record<string, {
+            targetPkField: string;
+            ids: Array<string | number>;
+        }>;
+        targetGuards?: TargetGuard[];
+    }, authorizationFilter?: Filter): Promise<Record<string, unknown>>;
+    deleteRecord(model: Model, id: string | number, authorizationFilter?: Filter): Promise<void>;
+    /** `targetModel` est fourni par l'appelant : chaque site d'appel actuel l'a déjà résolu. */
+    getM2mSelectedIds(model: Model, edge: RelationEdge, targetModel: Model, recordId: string | number): Promise<Array<string | number>>;
+}

package/dist/server/adapters/types.js

@@ -0,0 +1 @@
+export {};

package/dist/server/audit.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Audit-log helpers for successful admin writes.
+ *
+ * The package has no session store and no first-party AuditLog table — same
+ * bring-your-own philosophy as `authCheck` / `logout`. This module builds a
+ * redacted `AuditEvent` and emits it to the consumer's callback. Sensitive
+ * names (`isSensitiveFieldName`) and config `hidden` fields are stripped from
+ * every snapshot so the audit sink cannot become a second oracle for secrets.
+ */
+import type { Model } from './types/schema.js';
+export type AuditAction = 'create' | 'update' | 'delete';
+export type AuditEvent = {
+    event: any;
+    at: Date;
+    action: 'create';
+    model: string;
+    id: string | number;
+    values: Record<string, unknown>;
+    after: Record<string, unknown>;
+    m2m?: Record<string, Array<string | number>>;
+} | {
+    event: any;
+    at: Date;
+    action: 'update';
+    model: string;
+    id: string | number;
+    values: Record<string, unknown>;
+    before: Record<string, unknown> | null;
+    after: Record<string, unknown>;
+    changes: Record<string, {
+        from: unknown;
+        to: unknown;
+    }>;
+    m2m?: Record<string, Array<string | number>>;
+} | {
+    event: any;
+    at: Date;
+    action: 'delete';
+    model: string;
+    id: string | number;
+    before: Record<string, unknown> | null;
+};
+export declare function redactForAudit(record: Record<string, unknown>, model: Model, hidden: ReadonlySet<string>): Record<string, unknown>;
+export declare function diffRecords(before: Record<string, unknown>, after: Record<string, unknown>): Record<string, {
+    from: unknown;
+    to: unknown;
+}>;
+export interface BuildAuditEventInput {
+    event: any;
+    at?: Date;
+    action: AuditAction;
+    model: Model;
+    id: string | number;
+    hidden: ReadonlySet<string>;
+    values?: Record<string, unknown>;
+    m2m?: Record<string, {
+        targetPkField: string;
+        ids: Array<string | number>;
+    }>;
+    before?: Record<string, unknown> | null;
+    after?: Record<string, unknown>;
+}
+export declare function buildAuditEvent(input: BuildAuditEventInput): AuditEvent;
+export declare function readAuditSnapshot(getRecord: (model: Model, id: string | number) => Promise<Record<string, unknown> | null>, model: Model, id: string | number): Promise<Record<string, unknown> | null>;
+export declare function emitAudit(audit: ((entry: AuditEvent) => void | Promise<void>) | undefined, entry: AuditEvent): Promise<void>;

package/dist/server/audit.js

@@ -0,0 +1,106 @@
+/**
+ * Audit-log helpers for successful admin writes.
+ *
+ * The package has no session store and no first-party AuditLog table — same
+ * bring-your-own philosophy as `authCheck` / `logout`. This module builds a
+ * redacted `AuditEvent` and emits it to the consumer's callback. Sensitive
+ * names (`isSensitiveFieldName`) and config `hidden` fields are stripped from
+ * every snapshot so the audit sink cannot become a second oracle for secrets.
+ */
+import { isSensitiveFieldName } from './introspection/parser.js';
+export function redactForAudit(record, model, hidden) {
+    const out = {};
+    for (const field of model.fields) {
+        if (field.relation || field.isList)
+            continue;
+        if (isSensitiveFieldName(field.name) || hidden.has(field.name))
+            continue;
+        if (!(field.name in record))
+            continue;
+        out[field.name] = record[field.name];
+    }
+    return out;
+}
+function auditValuesEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (a instanceof Date && b instanceof Date)
+        return a.getTime() === b.getTime();
+    if (typeof a === 'bigint' && typeof b === 'bigint')
+        return a === b;
+    if (typeof a === 'object' && typeof b === 'object') {
+        try {
+            return JSON.stringify(a) === JSON.stringify(b);
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+export function diffRecords(before, after) {
+    const changes = {};
+    const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    for (const key of keys) {
+        const from = before[key];
+        const to = after[key];
+        if (!auditValuesEqual(from, to)) {
+            changes[key] = { from, to };
+        }
+    }
+    return changes;
+}
+function compactM2m(m2m) {
+    if (!m2m)
+        return undefined;
+    const keys = Object.keys(m2m);
+    if (keys.length === 0)
+        return undefined;
+    const out = {};
+    for (const key of keys) {
+        out[key] = m2m[key].ids;
+    }
+    return out;
+}
+export function buildAuditEvent(input) {
+    const at = input.at ?? new Date();
+    const hidden = input.hidden;
+    const m2m = compactM2m(input.m2m);
+    const base = { event: input.event, at, model: input.model.name, id: input.id };
+    if (input.action === 'delete') {
+        const before = input.before ? redactForAudit(input.before, input.model, hidden) : null;
+        return { ...base, action: 'delete', before };
+    }
+    const values = redactForAudit(input.values ?? {}, input.model, hidden);
+    if (input.action === 'create') {
+        const after = redactForAudit(input.after ?? {}, input.model, hidden);
+        return m2m
+            ? { ...base, action: 'create', values, after, m2m }
+            : { ...base, action: 'create', values, after };
+    }
+    const afterRaw = { ...(input.before ?? {}), ...(input.after ?? {}) };
+    const after = redactForAudit(afterRaw, input.model, hidden);
+    const before = input.before ? redactForAudit(input.before, input.model, hidden) : null;
+    const changes = before ? diffRecords(before, after) : {};
+    return m2m
+        ? { ...base, action: 'update', values, before, after, changes, m2m }
+        : { ...base, action: 'update', values, before, after, changes };
+}
+export async function readAuditSnapshot(getRecord, model, id) {
+    try {
+        return await getRecord(model, id);
+    }
+    catch {
+        return null;
+    }
+}
+export async function emitAudit(audit, entry) {
+    if (!audit)
+        return;
+    try {
+        await audit(entry);
+    }
+    catch (e) {
+        console.error('[sveltekit-admin] audit callback failed:', e);
+    }
+}

package/dist/server/csrf.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Vérification d'origine des requêtes mutantes servies sous `basePath`.
+ *
+ * SvelteKit fait le même contrôle (`runtime/server/respond.js`) mais ne peut
+ * pas porter la garantie ici : il tourne avant le hook `handle` (invisible
+ * pour cette lib), un `kit.csrf.checkOrigin: false` posé pour une route sans
+ * rapport le désactive partout, et il est court-circuité en dev. Revérifié
+ * ici, dev compris : un proxy qui strippe `Origin` doit casser sur
+ * `pnpm run dev`, pas en production.
+ */
+export type CsrfConfig = false | {
+    /**
+     * Origines acceptées en plus de celle de la requête. Normalisées en
+     * origine, donc `https://ops.example/` et `https://ops.example` sont
+     * la même entrée.
+     */
+    trustedOrigins?: string[];
+};
+export interface ResolvedCsrf {
+    enabled: boolean;
+    trustedOrigins: Set<string>;
+}
+/** Résolue au boot : une entrée illisible doit faire échouer `createAdminHandler`. */
+export declare function resolveCsrfConfig(csrf: CsrfConfig | undefined): ResolvedCsrf;
+export declare function verifyOrigin(csrf: ResolvedCsrf, event: {
+    url: URL;
+    request: {
+        method: string;
+        headers: {
+            get(name: string): string | null;
+        };
+    };
+}): Response | null;

package/dist/server/csrf.js

@@ -0,0 +1,55 @@
+/**
+ * Vérification d'origine des requêtes mutantes servies sous `basePath`.
+ *
+ * SvelteKit fait le même contrôle (`runtime/server/respond.js`) mais ne peut
+ * pas porter la garantie ici : il tourne avant le hook `handle` (invisible
+ * pour cette lib), un `kit.csrf.checkOrigin: false` posé pour une route sans
+ * rapport le désactive partout, et il est court-circuité en dev. Revérifié
+ * ici, dev compris : un proxy qui strippe `Origin` doit casser sur
+ * `pnpm run dev`, pas en production.
+ */
+/** Sans effet de bord : jamais un vecteur CSRF, jamais inspectées. */
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+/** Résolue au boot : une entrée illisible doit faire échouer `createAdminHandler`. */
+export function resolveCsrfConfig(csrf) {
+    if (csrf === false)
+        return { enabled: false, trustedOrigins: new Set() };
+    const trustedOrigins = new Set();
+    for (const entry of csrf?.trustedOrigins ?? []) {
+        let origin;
+        try {
+            origin = new URL(entry).origin;
+        }
+        catch {
+            throw new Error(`[sveltekit-admin] csrf.trustedOrigins contains "${entry}", which is not an absolute ` +
+                'URL. Use a full origin such as "https://admin.example.com".');
+        }
+        // `javascript:`, `data:`, `file:`… normalisent en "null", ce qu'envoie
+        // aussi une iframe sandboxée : les accepter ouvrirait à tout contexte opaque.
+        if (origin === 'null') {
+            throw new Error(`[sveltekit-admin] csrf.trustedOrigins contains "${entry}", whose origin is opaque ` +
+                '("null"). Only http(s) origins can be trusted.');
+        }
+        trustedOrigins.add(origin);
+    }
+    return { enabled: true, trustedOrigins };
+}
+export function verifyOrigin(csrf, event) {
+    if (!csrf.enabled)
+        return null;
+    if (SAFE_METHODS.has(event.request.method))
+        return null;
+    const origin = event.request.headers.get('origin');
+    if (origin === event.url.origin)
+        return null;
+    // `trustedOrigins` ne contient jamais `null` (rejeté au boot) : un en-tête
+    // absent ne peut donc pas y correspondre.
+    if (origin !== null && csrf.trustedOrigins.has(origin))
+        return null;
+    // Corps statique : ne jamais réfléchir l'`Origin` reçu ni énumérer les
+    // origines acceptées.
+    return new Response('[sveltekit-admin] Cross-site request forbidden', {
+        status: 403,
+        headers: { 'Content-Type': 'text/plain; charset=utf-8' }
+    });
+}

package/dist/server/data.d.ts

@@ -28,11 +28,3 @@ export declare function paginate(pageParam: string | null, perPage: number): {
     skip: number;
     take: number;
 };
-export declare function listRecords(prisma: any, model: PrismaModel, page: number, perPage: number, where?: Record<string, unknown>): Promise<{
-    items: any[];
-    total: number;
-}>;
-export declare function getRecord(prisma: any, model: PrismaModel, id: string): Promise<any | null>;
-export declare function createRecord(prisma: any, model: PrismaModel, data: Record<string, unknown>): Promise<void>;
-export declare function updateRecord(prisma: any, model: PrismaModel, id: string, data: Record<string, unknown>): Promise<void>;
-export declare function deleteRecord(prisma: any, model: PrismaModel, id: string): Promise<void>;

package/dist/server/data.js

@@ -73,44 +73,3 @@ export function paginate(pageParam, perPage) {
     const page = Number.isSafeInteger(parsed) && parsed >= 1 ? parsed : 1;
     return { page, skip: (page - 1) * perPage, take: perPage };
 }
-export async function listRecords(prisma, model, page, perPage, where) {
-    const key = toPrismaModel(model.name);
-    const primaryKey = primaryKeyOf(model);
-    // Le calcul `(page - 1) * perPage` est dupliqué avec `paginate` DÉLIBÉRÉMENT.
-    // Router `listRecords` vers `paginate(String(page), perPage)` serait lossy : la
-    // conversion aller-retour passe par `parseInt`, et `String(1e24)` donne
-    // `'1e+24'`, que `parseInt` ramène à `1`. `listRecords` reçoit un `number` déjà
-    // validé par l'appelant ; ne pas « simplifier » en réintroduisant un parse.
-    const [items, total] = await Promise.all([
-        prisma[key].findMany({
-            where,
-            skip: (page - 1) * perPage,
-            take: perPage,
-            orderBy: { [primaryKey]: 'desc' }
-        }),
-        prisma[key].count({ where })
-    ]);
-    return { items, total };
-}
-export function getRecord(prisma, model, id) {
-    const primaryKey = primaryKeyOf(model);
-    return prisma[toPrismaModel(model.name)].findUnique({
-        where: { [primaryKey]: coerceId(id, model) }
-    });
-}
-export async function createRecord(prisma, model, data) {
-    await prisma[toPrismaModel(model.name)].create({ data });
-}
-export async function updateRecord(prisma, model, id, data) {
-    const primaryKey = primaryKeyOf(model);
-    await prisma[toPrismaModel(model.name)].update({
-        where: { [primaryKey]: coerceId(id, model) },
-        data
-    });
-}
-export async function deleteRecord(prisma, model, id) {
-    const primaryKey = primaryKeyOf(model);
-    await prisma[toPrismaModel(model.name)].delete({
-        where: { [primaryKey]: coerceId(id, model) }
-    });
-}

package/dist/server/errors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Forme unique des échecs de mutation admin.
+ *
+ * Deux producteurs, un seul type : `mutations.ts` pour les refus que la
+ * bibliothèque décide elle-même (validation, scope), `classifyWriteError`
+ * pour ceux que le moteur signale. Un seul consommateur : le site d'appel
+ * de `handleMutation` dans `handler.ts`, qui ne rend QUE le message d'une
+ * `AdminMutationError` — jamais celui d'une erreur pilote brute.
+ *
+ * La classification se fait par code, jamais par texte : les messages des
+ * pilotes changent entre versions, les codes non.
+ */
+export type MutationErrorKind = 'validation' | 'conflict' | 'reference' | 'restrict' | 'authorization' | 'notFound' | 'unknown';
+export declare class AdminMutationError extends Error {
+    readonly kind: MutationErrorKind;
+    readonly field?: string;
+    constructor(kind: MutationErrorKind, message: string, field?: string);
+}
+/**
+ * Erreur de configuration de la bibliothèque elle-même (scope non injectable,
+ * tenant absent…), destinée au développeur intégrateur et non à l'utilisateur
+ * de l'admin. Distincte d'`AdminMutationError` : elle ne décrit pas un refus
+ * de la donnée soumise, mais un montage incorrect côté consommateur, et c'est
+ * la SEULE erreur non typée que le chemin de mutation relaie telle quelle.
+ */
+export declare class AdminConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Les pilotes exposent le code SQLSTATE à des endroits différents : `code` sur
+ * `pg`, `mysql2` et `better-sqlite3`, `meta.code` sur une
+ * `PrismaClientKnownRequestError` issue d'une transaction interactive.
+ *
+ * Vit ici plutôt que dans `retry.ts` : deux modules classent désormais les
+ * erreurs pilote, et un second exemplaire de ce helper dériverait du premier.
+ */
+export declare function codeOf(error: unknown): string | undefined;
+/**
+ * Traduit un échec d'écriture en `AdminMutationError`, ou `null` si le code
+ * n'est pas reconnu — l'appelant rend alors un message générique.
+ *
+ * `reference` et `restrict` partagent le même code SQLSTATE (PostgreSQL 23503,
+ * SQLite SQLITE_CONSTRAINT_FOREIGNKEY) : c'est l'action en cours qui les
+ * sépare, pas le message. Sur create/update une cible soumise est invalide ;
+ * sur delete la ligne est référencée ailleurs.
+ */
+export declare function classifyWriteError(error: unknown, action: 'create' | 'update' | 'delete'): AdminMutationError | null;

package/dist/server/errors.js

@@ -0,0 +1,90 @@
+/**
+ * Forme unique des échecs de mutation admin.
+ *
+ * Deux producteurs, un seul type : `mutations.ts` pour les refus que la
+ * bibliothèque décide elle-même (validation, scope), `classifyWriteError`
+ * pour ceux que le moteur signale. Un seul consommateur : le site d'appel
+ * de `handleMutation` dans `handler.ts`, qui ne rend QUE le message d'une
+ * `AdminMutationError` — jamais celui d'une erreur pilote brute.
+ *
+ * La classification se fait par code, jamais par texte : les messages des
+ * pilotes changent entre versions, les codes non.
+ */
+export class AdminMutationError extends Error {
+    kind;
+    field;
+    constructor(kind, message, field) {
+        super(message);
+        this.name = 'AdminMutationError';
+        this.kind = kind;
+        this.field = field;
+    }
+}
+/**
+ * Erreur de configuration de la bibliothèque elle-même (scope non injectable,
+ * tenant absent…), destinée au développeur intégrateur et non à l'utilisateur
+ * de l'admin. Distincte d'`AdminMutationError` : elle ne décrit pas un refus
+ * de la donnée soumise, mais un montage incorrect côté consommateur, et c'est
+ * la SEULE erreur non typée que le chemin de mutation relaie telle quelle.
+ */
+export class AdminConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AdminConfigError';
+    }
+}
+/**
+ * Les pilotes exposent le code SQLSTATE à des endroits différents : `code` sur
+ * `pg`, `mysql2` et `better-sqlite3`, `meta.code` sur une
+ * `PrismaClientKnownRequestError` issue d'une transaction interactive.
+ *
+ * Vit ici plutôt que dans `retry.ts` : deux modules classent désormais les
+ * erreurs pilote, et un second exemplaire de ce helper dériverait du premier.
+ */
+export function codeOf(error) {
+    const candidate = error;
+    const raw = candidate?.code ?? candidate?.meta?.code;
+    return typeof raw === 'string' ? raw : undefined;
+}
+const UNIQUE_CODES = new Set([
+    'P2002', // Prisma
+    '23505', // PostgreSQL — unique_violation
+    'ER_DUP_ENTRY', // MySQL 1062
+    'SQLITE_CONSTRAINT_UNIQUE'
+]);
+const FOREIGN_KEY_CODES = new Set([
+    'P2003', // Prisma
+    '23503', // PostgreSQL — foreign_key_violation
+    'ER_NO_REFERENCED_ROW_2', // MySQL 1452 — la cible soumise n'existe pas
+    'ER_ROW_IS_REFERENCED_2', // MySQL 1451 — la ligne est référencée ailleurs
+    'SQLITE_CONSTRAINT_FOREIGNKEY'
+]);
+const NOT_FOUND_CODES = new Set(['P2025']);
+/**
+ * Traduit un échec d'écriture en `AdminMutationError`, ou `null` si le code
+ * n'est pas reconnu — l'appelant rend alors un message générique.
+ *
+ * `reference` et `restrict` partagent le même code SQLSTATE (PostgreSQL 23503,
+ * SQLite SQLITE_CONSTRAINT_FOREIGNKEY) : c'est l'action en cours qui les
+ * sépare, pas le message. Sur create/update une cible soumise est invalide ;
+ * sur delete la ligne est référencée ailleurs.
+ */
+export function classifyWriteError(error, action) {
+    if (error instanceof AdminMutationError)
+        return error;
+    const code = codeOf(error);
+    if (code === undefined)
+        return null;
+    if (UNIQUE_CODES.has(code)) {
+        return new AdminMutationError('conflict', 'A record with these values already exists.');
+    }
+    if (FOREIGN_KEY_CODES.has(code)) {
+        return action === 'delete'
+            ? new AdminMutationError('restrict', 'This record is referenced by other records.')
+            : new AdminMutationError('reference', 'A referenced record no longer exists.');
+    }
+    if (NOT_FOUND_CODES.has(code)) {
+        return new AdminMutationError('notFound', 'This record no longer exists.');
+    }
+    return null;
+}