@questpie/admin 3.2.7 → 3.4.0

package/dist/server/modules/audit/collections/audit-log.d.mts

@@ -1,13 +1,18 @@
-import * as questpie_shared6 from "questpie/shared";
-import * as questpie98 from "questpie";
-import * as questpie_src_server_modules_core_fields_email_js2 from "questpie/src/server/modules/core/fields/email.js";
-import * as questpie_src_server_modules_core_fields_json_js2 from "questpie/src/server/modules/core/fields/json.js";
-import * as drizzle_orm_pg_core9 from "drizzle-orm/pg-core";
-import * as drizzle_orm9 from "drizzle-orm";
+import * as questpie_shared0 from "questpie/shared";
+import * as questpie21 from "questpie";
+import * as questpie_src_server_modules_core_fields_email_js0 from "questpie/src/server/modules/core/fields/email.js";
+import * as questpie_src_server_modules_core_fields_json_js0 from "questpie/src/server/modules/core/fields/json.js";
+import * as drizzle_orm_pg_core0 from "drizzle-orm/pg-core";
+import * as drizzle_orm0 from "drizzle-orm";
 import * as questpie_src_server_fields_operators_builtin_js0 from "questpie/src/server/fields/operators/builtin.js";
 
 //#region src/server/modules/audit/collections/audit-log.d.ts
-
+/**
+ * The collection slug used by the audit log.
+ * Exported so hooks and jobs can reference the collection dynamically
+ * instead of hardcoding the name.
+ */
+declare const AUDIT_LOG_COLLECTION: "admin_audit_log";
 /**
  * Audit Log Collection
  *
@@ -19,140 +24,142 @@ import * as questpie_src_server_fields_operators_builtin_js0 from "questpie/src/
  * - update: disallowed
  * - read: allowed (for admin UI display)
  */
-declare const auditLogCollection: questpie98.CollectionBuilder<questpie_shared6.Override<questpie_shared6.Override<questpie_shared6.Override<questpie_shared6.Override<questpie_shared6.Override<questpie98.EmptyCollectionState<"admin_audit_log", undefined, {
-  readonly text: typeof questpie98.text;
-  readonly textarea: typeof questpie98.textarea;
-  readonly email: typeof questpie_src_server_modules_core_fields_email_js2.email;
-  readonly url: typeof questpie98.url;
-  readonly number: typeof questpie98.number;
-  readonly boolean: typeof questpie98.boolean;
-  readonly date: typeof questpie98.date;
-  readonly datetime: typeof questpie98.datetime;
-  readonly time: typeof questpie98.time;
-  readonly select: typeof questpie98.select;
-  readonly upload: typeof questpie98.upload;
-  readonly relation: typeof questpie98.relation;
-  readonly object: typeof questpie98.object;
-  readonly json: typeof questpie_src_server_modules_core_fields_json_js2.json;
-  readonly from: typeof questpie98.from;
+declare const auditLogCollection: questpie21.CollectionBuilder<questpie_shared0.Override<questpie_shared0.Override<questpie_shared0.Override<questpie_shared0.Override<questpie_shared0.Override<questpie_shared0.Override<questpie21.EmptyCollectionState<"admin_audit_log", undefined, {
+  readonly text: typeof questpie21.text;
+  readonly textarea: typeof questpie21.textarea;
+  readonly email: typeof questpie_src_server_modules_core_fields_email_js0.email;
+  readonly url: typeof questpie21.url;
+  readonly number: typeof questpie21.number;
+  readonly boolean: typeof questpie21.boolean;
+  readonly date: typeof questpie21.date;
+  readonly datetime: typeof questpie21.datetime;
+  readonly time: typeof questpie21.time;
+  readonly select: typeof questpie21.select;
+  readonly upload: typeof questpie21.upload;
+  readonly relation: typeof questpie21.relation;
+  readonly object: typeof questpie21.object;
+  readonly json: typeof questpie_src_server_modules_core_fields_json_js0.json;
+  readonly from: typeof questpie21.from;
 }>, {
   fields: {
-    readonly action: drizzle_orm9.NotNull<drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>>;
-    readonly resourceType: drizzle_orm9.NotNull<drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>>;
-    readonly resource: drizzle_orm9.NotNull<drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>>;
-    readonly resourceId: drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>;
-    readonly resourceLabel: drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>;
-    readonly userId: drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>;
-    readonly userName: drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>;
-    readonly locale: drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>;
-    readonly changes: drizzle_orm_pg_core9.PgJsonbBuilder;
-    readonly metadata: drizzle_orm_pg_core9.PgJsonbBuilder;
-    readonly title: drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>;
+    readonly action: drizzle_orm0.NotNull<drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>>;
+    readonly resourceType: drizzle_orm0.NotNull<drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>>;
+    readonly resource: drizzle_orm0.NotNull<drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>>;
+    readonly resourceId: drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>;
+    readonly resourceLabel: drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>;
+    readonly userId: drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>;
+    readonly userName: drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>;
+    readonly locale: drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>;
+    readonly changes: drizzle_orm_pg_core0.PgJsonbBuilder;
+    readonly metadata: drizzle_orm_pg_core0.PgJsonbBuilder;
+    readonly title: drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>;
   };
   localized: readonly string[];
   fieldDefinitions: {
     /** Action performed: create, update, delete, transition, custom */
-    readonly action: questpie98.FieldWithMethods<Omit<questpie98.TextFieldState, "notNull" | "column"> & {
+    readonly action: questpie21.FieldWithMethods<Omit<questpie21.TextFieldState, "notNull" | "column"> & {
       notNull: true;
-      column: drizzle_orm9.NotNull<drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>>;
+      column: drizzle_orm0.NotNull<drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>>;
     } & {
-      label: questpie_shared6.I18nText;
-    }, questpie98.TextFieldMethods>;
+      label: questpie_shared0.I18nText;
+    }, questpie21.TextFieldMethods>;
     /** Resource type: collection, global, auth, system, custom */
-    readonly resourceType: questpie98.FieldWithMethods<Omit<questpie98.TextFieldState, "notNull" | "column"> & {
+    readonly resourceType: questpie21.FieldWithMethods<Omit<questpie21.TextFieldState, "notNull" | "column"> & {
       notNull: true;
-      column: drizzle_orm9.NotNull<drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>>;
+      column: drizzle_orm0.NotNull<drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>>;
     } & {
-      label: questpie_shared6.I18nText;
-    }, questpie98.TextFieldMethods>;
+      label: questpie_shared0.I18nText;
+    }, questpie21.TextFieldMethods>;
     /** Resource slug (collection/global name) */
-    readonly resource: questpie98.FieldWithMethods<Omit<questpie98.TextFieldState, "notNull" | "column"> & {
+    readonly resource: questpie21.FieldWithMethods<Omit<questpie21.TextFieldState, "notNull" | "column"> & {
       notNull: true;
-      column: drizzle_orm9.NotNull<drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>>;
+      column: drizzle_orm0.NotNull<drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>>;
     } & {
-      label: questpie_shared6.I18nText;
-    }, questpie98.TextFieldMethods>;
+      label: questpie_shared0.I18nText;
+    }, questpie21.TextFieldMethods>;
     /** ID of the specific record (null for globals) */
-    readonly resourceId: questpie98.FieldWithMethods<questpie98.DefaultFieldState & {
+    readonly resourceId: questpie21.FieldWithMethods<questpie21.DefaultFieldState & {
       type: "text";
       data: string;
-      column: drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>;
+      column: drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>;
       operators: typeof questpie_src_server_fields_operators_builtin_js0.stringOps;
     } & {
-      label: questpie_shared6.I18nText;
-    }, questpie98.TextFieldMethods>;
+      label: questpie_shared0.I18nText;
+    }, questpie21.TextFieldMethods>;
     /** Denormalized display label for the affected record */
-    readonly resourceLabel: questpie98.FieldWithMethods<questpie98.DefaultFieldState & {
+    readonly resourceLabel: questpie21.FieldWithMethods<questpie21.DefaultFieldState & {
       type: "text";
       data: string;
-      column: drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>;
+      column: drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>;
       operators: typeof questpie_src_server_fields_operators_builtin_js0.stringOps;
     } & {
-      label: questpie_shared6.I18nText;
-    }, questpie98.TextFieldMethods>;
+      label: questpie_shared0.I18nText;
+    }, questpie21.TextFieldMethods>;
     /** User who performed the action */
-    readonly userId: questpie98.FieldWithMethods<questpie98.DefaultFieldState & {
+    readonly userId: questpie21.FieldWithMethods<questpie21.DefaultFieldState & {
       type: "text";
       data: string;
-      column: drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>;
+      column: drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>;
       operators: typeof questpie_src_server_fields_operators_builtin_js0.stringOps;
     } & {
-      label: questpie_shared6.I18nText;
-    }, questpie98.TextFieldMethods>;
+      label: questpie_shared0.I18nText;
+    }, questpie21.TextFieldMethods>;
     /** Denormalized user display name */
-    readonly userName: questpie98.FieldWithMethods<questpie98.DefaultFieldState & {
+    readonly userName: questpie21.FieldWithMethods<questpie21.DefaultFieldState & {
       type: "text";
       data: string;
-      column: drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>;
+      column: drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>;
       operators: typeof questpie_src_server_fields_operators_builtin_js0.stringOps;
     } & {
-      label: questpie_shared6.I18nText;
-    }, questpie98.TextFieldMethods>;
+      label: questpie_shared0.I18nText;
+    }, questpie21.TextFieldMethods>;
     /** Locale context of the operation */
-    readonly locale: questpie98.FieldWithMethods<questpie98.DefaultFieldState & {
+    readonly locale: questpie21.FieldWithMethods<questpie21.DefaultFieldState & {
       type: "text";
       data: string;
-      column: drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>;
+      column: drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>;
       operators: typeof questpie_src_server_fields_operators_builtin_js0.stringOps;
     } & {
-      label: questpie_shared6.I18nText;
-    }, questpie98.TextFieldMethods>;
+      label: questpie_shared0.I18nText;
+    }, questpie21.TextFieldMethods>;
     /** Field-level diffs: { field: { from, to } } or null */
-    readonly changes: questpie98.Field<questpie98.DefaultFieldState & {
+    readonly changes: questpie21.Field<questpie21.DefaultFieldState & {
       type: "json";
-      data: questpie98.JsonValue;
-      column: drizzle_orm_pg_core9.PgJsonbBuilder;
+      data: questpie21.JsonValue;
+      column: drizzle_orm_pg_core0.PgJsonbBuilder;
       operators: typeof questpie_src_server_fields_operators_builtin_js0.basicOps;
     } & {
-      label: questpie_shared6.I18nText;
+      label: questpie_shared0.I18nText;
     }>;
     /** Extra context metadata */
-    readonly metadata: questpie98.Field<questpie98.DefaultFieldState & {
+    readonly metadata: questpie21.Field<questpie21.DefaultFieldState & {
       type: "json";
-      data: questpie98.JsonValue;
-      column: drizzle_orm_pg_core9.PgJsonbBuilder;
+      data: questpie21.JsonValue;
+      column: drizzle_orm_pg_core0.PgJsonbBuilder;
       operators: typeof questpie_src_server_fields_operators_builtin_js0.basicOps;
     } & {
-      label: questpie_shared6.I18nText;
+      label: questpie_shared0.I18nText;
     }>;
     /** Human-readable title: "User Action ResourceType 'ResourceLabel'" */
-    readonly title: questpie98.FieldWithMethods<questpie98.DefaultFieldState & {
+    readonly title: questpie21.FieldWithMethods<questpie21.DefaultFieldState & {
       type: "text";
       data: string;
-      column: drizzle_orm_pg_core9.PgVarcharBuilder<[string, ...string[]]>;
+      column: drizzle_orm_pg_core0.PgVarcharBuilder<[string, ...string[]]>;
       operators: typeof questpie_src_server_fields_operators_builtin_js0.stringOps;
     } & {
-      label: questpie_shared6.I18nText;
-    }, questpie98.TextFieldMethods>;
+      label: questpie_shared0.I18nText;
+    }, questpie21.TextFieldMethods>;
   };
 }>, {
   options: {
     timestamps: true;
   };
 }>, {
-  indexes: drizzle_orm_pg_core9.IndexBuilder[];
+  indexes: drizzle_orm_pg_core0.IndexBuilder[];
 }>, {
   access: Record<string, any>;
+}>, {
+  hooks: Record<string, any>;
 }> & Record<"admin", {
   label: {
     key: string;
@@ -211,4 +218,4 @@ declare const auditLogCollection: questpie98.CollectionBuilder<questpie_shared6.
   })[];
 }>>;
 //#endregion
-export { auditLogCollection };
+export { AUDIT_LOG_COLLECTION, auditLogCollection };

package/dist/server/modules/audit/collections/audit-log.mjs

@@ -1,4 +1,5 @@
-import { collection } from "questpie";
+import { localizeAuditTitle } from "../config/localize-title.mjs";
+import { collection, tryGetContext } from "questpie";
 import { index } from "questpie/drizzle-pg-core";
 
 //#region src/server/modules/audit/collections/audit-log.ts
@@ -41,7 +42,11 @@ const auditLogCollection = collection(AUDIT_LOG_COLLECTION).fields(({ f }) => ({
 	update: false,
 	delete: false,
 	read: true
-}).set("admin", {
+}).hooks({ afterRead: ({ data, locale }) => {
+	if (!data) return;
+	const localized = localizeAuditTitle(data, locale, tryGetContext()?.app);
+	if (localized) data.title = localized;
+} }).set("admin", {
 	label: { key: "audit.collection.label" },
 	icon: {
 		type: "icon",

package/dist/server/modules/audit/config/localize-title.mjs

@@ -0,0 +1,67 @@
+import { getAdminMessagesForLocale } from "../../../i18n/index.mjs";
+import { isI18nTranslationKey, resolveI18nText } from "questpie/shared";
+
+//#region src/server/modules/audit/config/localize-title.ts
+function lookupMessage(messages, key) {
+	const value = messages[key];
+	if (typeof value === "string") return value;
+	if (value && typeof value === "object") {
+		const plural = value.other;
+		if (typeof plural === "string") return plural;
+	}
+	return null;
+}
+function makeTranslator(messages) {
+	return (key) => lookupMessage(messages, key) ?? key;
+}
+function getResourceLabel(app, resourceType, resource) {
+	if (!app) return null;
+	if (resourceType === "collection") {
+		const config = app.getCollectionConfig?.(resource);
+		return config?.state?.admin?.label ?? config?.state?.label ?? null;
+	}
+	if (resourceType === "global") {
+		const config = app.getGlobals?.()?.[resource];
+		return config?.state?.admin?.label ?? config?.state?.label ?? null;
+	}
+	return null;
+}
+function resolveLabel(label, locale, t) {
+	if (label == null) return null;
+	if (isI18nTranslationKey(label)) {
+		const resolved = t(label.key);
+		return resolved === label.key ? label.fallback ?? null : resolved;
+	}
+	return resolveI18nText(label, locale, t);
+}
+function interpolate(template, values) {
+	return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (_m, k) => values[k] ?? `{{${k}}}`);
+}
+/**
+* Recompute the audit log title in the viewer's locale.
+* Returns null when no locale is provided so the caller can keep the stored value.
+*/
+function localizeAuditTitle(data, locale, app) {
+	if (!locale) return null;
+	const messages = getAdminMessagesForLocale(locale);
+	const t = makeTranslator(messages);
+	const action = String(data.action ?? "");
+	const resourceType = String(data.resourceType ?? "");
+	const resource = String(data.resource ?? "");
+	const userName = String(data.userName ?? "");
+	const actionText = lookupMessage(messages, `audit.action.${action}`) ?? action;
+	const resourceTypeText = lookupMessage(messages, `audit.resourceType.${resourceType}`) ?? resourceType;
+	const resourceName = resolveLabel(getResourceLabel(app, resourceType, resource), locale, t) ?? resource;
+	const rawLabel = typeof data.resourceLabel === "string" && data.resourceLabel.length > 0 ? data.resourceLabel : null;
+	const unnamed = lookupMessage(messages, "audit.unnamed") ?? "(unnamed)";
+	const resourceLabel = rawLabel ? `'${rawLabel}'` : unnamed;
+	return interpolate(lookupMessage(messages, "audit.title.template") ?? "{{userName}} {{action}} {{resourceType}} {{resourceLabel}}", {
+		userName,
+		action: actionText,
+		resourceType: `${resourceTypeText} ${resourceName}`,
+		resourceLabel
+	});
+}
+
+//#endregion
+export { localizeAuditTitle };

package/dist/server/modules/audit/index.d.mts

@@ -1,2 +1,3 @@
-import { auditLogCollection } from "./collections/audit-log.mjs";
-import { AuditModule, _module } from "./.generated/module.mjs";
+import { AUDIT_LOG_COLLECTION, auditLogCollection } from "./collections/audit-log.mjs";
+import { AuditModule, _module } from "./.generated/module.mjs";
+import { AuditActorType, AuditContext, LogAuditEntryOptions, logAuditEntry } from "./log-audit-entry.mjs";

package/dist/server/modules/audit/jobs/audit-cleanup.d.mts

@@ -1,4 +1,4 @@
-import * as questpie461 from "questpie";
+import * as questpie151 from "questpie";
 
 //#region src/server/modules/audit/jobs/audit-cleanup.d.ts
 
@@ -6,7 +6,7 @@ import * as questpie461 from "questpie";
  * Audit log cleanup job.
  * Runs daily (via cron) to delete entries older than the configured retention period.
  */
-declare const auditCleanupJob: questpie461.JobDefinition<{
+declare const auditCleanupJob: questpie151.JobDefinition<{
   retentionDays: number;
 }, void, "audit-cleanup">;
 //#endregion

package/dist/server/modules/audit/log-audit-entry.d.mts

@@ -0,0 +1,85 @@
+//#region src/server/modules/audit/log-audit-entry.d.ts
+/**
+ * Options for a custom audit log entry.
+ */
+type AuditActorType = "anonymous" | "system" | "user" | (string & {});
+interface LogAuditEntryOptions {
+  /** Action performed (e.g., "create", "bulk-email", "archive", "migrate"). */
+  action: string;
+  /**
+   * Category of the affected resource.
+   * Built-in: "collection" | "global"
+   * Custom: "system" | "job" | "webhook" | any string
+   */
+  resourceType: string;
+  /** Resource identifier (e.g., collection slug, job name). */
+  resource: string;
+  /** Optional ID of a specific record. */
+  resourceId?: string | null;
+  /** Display label for the affected resource (e.g., record title, job description). */
+  resourceLabel?: string | null;
+  /** Override actor user name (auto-resolved from session when omitted). */
+  userName?: string;
+  /** Override actor user ID (auto-resolved from session when omitted). */
+  userId?: string | null;
+  /** Override actor category stored in metadata. */
+  actorType?: AuditActorType;
+  /** Locale context of the operation. */
+  locale?: string | null;
+  /** Field-level changes, or arbitrary structured data. */
+  changes?: Record<string, unknown> | null;
+  /** Extra metadata (e.g., job payload, webhook source). */
+  metadata?: Record<string, unknown> | null;
+}
+/**
+ * Audit context — pass the hook/job context directly.
+ * Needs `collections` (or `app.collections`) and optionally `session`, `db`.
+ */
+interface AuditContext {
+  collections?: Record<string, any>;
+  app?: {
+    collections?: Record<string, any>;
+    getCollectionConfig?: (slug: string) => any;
+    getGlobals?: () => Record<string, any>;
+  };
+  session?: {
+    user?: Record<string, unknown> | null;
+  } | null;
+  accessMode?: string;
+  db?: unknown;
+  logger?: {
+    error?: (...args: any[]) => void;
+  };
+}
+/**
+ * Write a custom audit log entry.
+ *
+ * Use this in jobs, custom actions, webhooks, or anywhere you want
+ * to record a meaningful event in the audit trail.
+ *
+ * @example
+ * ```ts
+ * import { logAuditEntry } from "@questpie/admin/server";
+ *
+ * // Inside a job handler:
+ * await logAuditEntry(ctx, {
+ *   action: "bulk-email",
+ *   resourceType: "system",
+ *   resource: "newsletter",
+ *   resourceLabel: "Q1 Campaign",
+ *   metadata: { sentCount: 1234, jobId: ctx.id },
+ * });
+ *
+ * // Inside a collection hook with session:
+ * await logAuditEntry(ctx, {
+ *   action: "export",
+ *   resourceType: "collection",
+ *   resource: "orders",
+ *   resourceLabel: "Monthly export",
+ *   changes: { format: { from: null, to: "csv" } },
+ * });
+ * ```
+ */
+declare function logAuditEntry(ctx: AuditContext, options: LogAuditEntryOptions): Promise<void>;
+//#endregion
+export { AuditActorType, AuditContext, LogAuditEntryOptions, logAuditEntry };

package/dist/server/modules/audit/log-audit-entry.mjs

@@ -0,0 +1,125 @@
+import { AUDIT_LOG_COLLECTION } from "./collections/audit-log.mjs";
+import { tryGetContext } from "questpie";
+
+//#region src/server/modules/audit/log-audit-entry.ts
+function resolveCollections(ctx) {
+	return ctx.collections ?? ctx.app?.collections ?? null;
+}
+function resolveActor(ctx) {
+	const user = ctx.session?.user;
+	const userId = user?.id != null ? String(user.id) : null;
+	for (const candidate of [
+		user?.name,
+		user?.email,
+		userId
+	]) if (typeof candidate === "string" && candidate.trim().length > 0) return {
+		actorType: "user",
+		userId,
+		userName: candidate.trim()
+	};
+	if (ctx.accessMode === "system") return {
+		actorType: "system",
+		userId: "system",
+		userName: "System"
+	};
+	return {
+		actorType: "anonymous",
+		userId: null,
+		userName: "Anonymous"
+	};
+}
+function getResourceTypeLabel(ctx, resourceType, resource) {
+	const stored = tryGetContext();
+	const app = ctx.app ?? stored?.app;
+	if (!app) return resource;
+	if (resourceType === "collection") {
+		const config = app.getCollectionConfig?.(resource);
+		const label = config?.state?.admin?.label ?? config?.state?.label;
+		if (typeof label === "string") return label;
+		return resource;
+	}
+	if (resourceType === "global") {
+		const config = app.getGlobals?.()?.[resource];
+		const label = config?.state?.admin?.label ?? config?.state?.label;
+		if (typeof label === "string") return label;
+		return resource;
+	}
+	return resource;
+}
+function resolveActorType(actor, options, userId) {
+	if (options.actorType) return options.actorType;
+	if (options.userId !== void 0 || options.userName !== void 0) return userId && userId !== "system" ? "user" : "system";
+	return actor.actorType;
+}
+/**
+* Write a custom audit log entry.
+*
+* Use this in jobs, custom actions, webhooks, or anywhere you want
+* to record a meaningful event in the audit trail.
+*
+* @example
+* ```ts
+* import { logAuditEntry } from "@questpie/admin/server";
+*
+* // Inside a job handler:
+* await logAuditEntry(ctx, {
+*   action: "bulk-email",
+*   resourceType: "system",
+*   resource: "newsletter",
+*   resourceLabel: "Q1 Campaign",
+*   metadata: { sentCount: 1234, jobId: ctx.id },
+* });
+*
+* // Inside a collection hook with session:
+* await logAuditEntry(ctx, {
+*   action: "export",
+*   resourceType: "collection",
+*   resource: "orders",
+*   resourceLabel: "Monthly export",
+*   changes: { format: { from: null, to: "csv" } },
+* });
+* ```
+*/
+async function logAuditEntry(ctx, options) {
+	const collections = resolveCollections(ctx);
+	if (!collections?.[AUDIT_LOG_COLLECTION]) {
+		ctx.logger?.error?.("[Audit] Cannot write audit entry — audit log collection not available");
+		return;
+	}
+	const actor = resolveActor(ctx);
+	const userName = options.userName ?? actor.userName;
+	const userId = options.userId !== void 0 ? options.userId : actor.userId;
+	const actorType = resolveActorType(actor, options, userId);
+	const resourceTypeLabel = getResourceTypeLabel(ctx, options.resourceType, options.resource);
+	const resourceLabel = options.resourceLabel ?? null;
+	const label = resourceLabel || "(unnamed)";
+	const title = `${userName} ${{
+		create: "created",
+		update: "updated",
+		delete: "deleted",
+		transition: "changed status of"
+	}[options.action] || options.action} ${resourceTypeLabel} '${label}'`;
+	await collections[AUDIT_LOG_COLLECTION].create({
+		action: options.action,
+		resourceType: options.resourceType,
+		resource: options.resource,
+		resourceId: options.resourceId ?? null,
+		resourceLabel,
+		userId,
+		userName,
+		locale: options.locale ?? null,
+		changes: options.changes ?? null,
+		metadata: {
+			actorType,
+			accessMode: ctx.accessMode ?? "system",
+			...options.metadata ?? {}
+		},
+		title
+	}, {
+		accessMode: "system",
+		db: ctx.db
+	});
+}
+
+//#endregion
+export { logAuditEntry };

package/dist/server/plugin.d.mts

@@ -1,4 +1,4 @@
-import { CodegenPlugin } from "questpie";
+import { CodegenPlugin } from "questpie/codegen";
 
 //#region src/server/plugin.d.ts