@questpie/admin 1.1.1 → 3.0.0

package/dist/server/modules/admin/routes/route-helpers.mjs

@@ -0,0 +1,76 @@
+//#region src/server/modules/admin/routes/route-helpers.ts
+/**
+* Get typed Questpie app instance from route handler context.
+*/
+function getApp(ctx) {
+	return ctx.app;
+}
+/**
+* Get session from route handler context.
+* Returns undefined if no session exists.
+*/
+function getSession(ctx) {
+	return ctx.session;
+}
+/**
+* Get database instance from route handler context.
+*/
+function getDb(ctx) {
+	return ctx.db;
+}
+/**
+* Get current locale from route handler context.
+*/
+function getLocale(ctx) {
+	return ctx.locale;
+}
+/**
+* Get the full access context needed by hasReadAccess and similar functions.
+*/
+function getAccessContext(ctx) {
+	return {
+		app: getApp(ctx),
+		session: getSession(ctx),
+		db: getDb(ctx),
+		locale: getLocale(ctx)
+	};
+}
+/**
+* Get typed collection state.
+*/
+function getCollectionState(collection) {
+	return collection.state;
+}
+/**
+* Get typed global state.
+*/
+function getGlobalState(global) {
+	return global.state;
+}
+/**
+* Get typed app state from app instance.
+*/
+function getAppState(app) {
+	return app.state || {};
+}
+/**
+* Get admin config from app state.
+*/
+function getAdminConfig(app) {
+	return getAppState(app).config?.admin || {};
+}
+/**
+* Build a ReactiveServerContext from route handler context.
+*/
+function buildServerContext(ctx) {
+	const session = getSession(ctx);
+	return {
+		db: getDb(ctx),
+		user: session?.user ?? null,
+		req: new Request("http://localhost"),
+		locale: getLocale(ctx) ?? "en"
+	};
+}
+
+//#endregion
+export { buildServerContext, getAccessContext, getAdminConfig, getApp, getAppState, getCollectionState, getGlobalState, getSession };

package/dist/server/modules/admin/routes/setup.d.mts

@@ -0,0 +1,63 @@
+import * as questpie114 from "questpie";
+
+//#region src/server/modules/admin/routes/setup.d.ts
+
+/**
+ * Setup Functions
+ *
+ * Built-in functions for bootstrapping the first admin user.
+ * Solves the chicken-and-egg problem where invitation-based systems
+ * need an existing admin to create the first invitation.
+ */
+/**
+ * Check if setup is required (no users exist in the system).
+ *
+ * @example
+ * ```ts
+ * const result = await client.routes.isSetupRequired({});
+ * if (result.required) {
+ *   // Redirect to setup page
+ * }
+ * ```
+ */
+declare const isSetupRequired: questpie114.JsonRouteDefinition<Record<string, never>, any>;
+/**
+ * Create the first admin user in the system.
+ * This function only works when no users exist (setup mode).
+ *
+ * Security: Once any user exists, this function will refuse to create more users.
+ * This prevents unauthorized admin creation after initial setup.
+ *
+ * @example
+ * ```ts
+ * const result = await client.routes.createFirstAdmin({
+ *   email: "admin@example.com",
+ *   password: "securepassword123",
+ *   name: "Admin User",
+ * });
+ *
+ * if (result.success) {
+ *   // Redirect to login page
+ * } else {
+ *   console.error(result.error);
+ * }
+ * ```
+ */
+declare const createFirstAdmin: questpie114.JsonRouteDefinition<{
+  email: string;
+  password: string;
+  name: string;
+}, any>;
+/**
+ * Bundle of setup-related functions.
+ */
+declare const setupFunctions: {
+  readonly isSetupRequired: questpie114.JsonRouteDefinition<Record<string, never>, any>;
+  readonly createFirstAdmin: questpie114.JsonRouteDefinition<{
+    email: string;
+    password: string;
+    name: string;
+  }, any>;
+};
+//#endregion
+export { createFirstAdmin, isSetupRequired, setupFunctions };

package/dist/server/modules/admin/routes/setup.mjs

@@ -0,0 +1,114 @@
+import { getApp } from "./route-helpers.mjs";
+import { z } from "zod";
+import { route } from "questpie";
+import { eq, sql as sql$1 } from "drizzle-orm";
+
+//#region src/server/modules/admin/routes/setup.ts
+/**
+* Setup Functions
+*
+* Built-in functions for bootstrapping the first admin user.
+* Solves the chicken-and-egg problem where invitation-based systems
+* need an existing admin to create the first invitation.
+*/
+const isSetupRequiredSchema = z.object({});
+const isSetupRequiredOutputSchema = z.object({ required: z.boolean() });
+const createFirstAdminSchema = z.object({
+	email: z.string().email("Invalid email address"),
+	password: z.string().min(8, "Password must be at least 8 characters"),
+	name: z.string().min(2, "Name must be at least 2 characters")
+});
+const createFirstAdminOutputSchema = z.object({
+	success: z.boolean(),
+	user: z.object({
+		id: z.string(),
+		email: z.string(),
+		name: z.string()
+	}).optional(),
+	error: z.string().optional()
+});
+/**
+* Check if setup is required (no users exist in the system).
+*
+* @example
+* ```ts
+* const result = await client.routes.isSetupRequired({});
+* if (result.required) {
+*   // Redirect to setup page
+* }
+* ```
+*/
+const isSetupRequired = route().post().schema(isSetupRequiredSchema).outputSchema(isSetupRequiredOutputSchema).handler(async (ctx) => {
+	const app = getApp(ctx);
+	const userCollection = app.getCollectionConfig("user");
+	return { required: (await app.db.select({ count: sql$1`count(*)::int` }).from(userCollection.table))[0].count === 0 };
+});
+/**
+* Create the first admin user in the system.
+* This function only works when no users exist (setup mode).
+*
+* Security: Once any user exists, this function will refuse to create more users.
+* This prevents unauthorized admin creation after initial setup.
+*
+* @example
+* ```ts
+* const result = await client.routes.createFirstAdmin({
+*   email: "admin@example.com",
+*   password: "securepassword123",
+*   name: "Admin User",
+* });
+*
+* if (result.success) {
+*   // Redirect to login page
+* } else {
+*   console.error(result.error);
+* }
+* ```
+*/
+const createFirstAdmin = route().post().schema(createFirstAdminSchema).outputSchema(createFirstAdminOutputSchema).handler(async (ctx) => {
+	const app = getApp(ctx);
+	const input = ctx.input;
+	const userCollection = app.getCollectionConfig("user");
+	if ((await app.db.select({ count: sql$1`count(*)::int` }).from(userCollection.table))[0].count > 0) return {
+		success: false,
+		error: "Setup already completed - users exist in the system"
+	};
+	try {
+		const signUpResult = await app.auth.api.signUpEmail({ body: {
+			email: input.email,
+			password: input.password,
+			name: input.name
+		} });
+		if (!signUpResult.user) return {
+			success: false,
+			error: "Failed to create user account"
+		};
+		await app.db.update(userCollection.table).set({
+			role: "admin",
+			emailVerified: true
+		}).where(eq(userCollection.table.id, signUpResult.user.id));
+		return {
+			success: true,
+			user: {
+				id: signUpResult.user.id,
+				email: signUpResult.user.email,
+				name: signUpResult.user.name
+			}
+		};
+	} catch (error) {
+		return {
+			success: false,
+			error: error instanceof Error ? error.message : "An unexpected error occurred"
+		};
+	}
+});
+/**
+* Bundle of setup-related functions.
+*/
+const setupFunctions = {
+	isSetupRequired,
+	createFirstAdmin
+};
+
+//#endregion
+export { createFirstAdmin, isSetupRequired, setupFunctions };

package/dist/server/modules/admin/routes/translations.d.mts

@@ -0,0 +1,26 @@
+import * as questpie310 from "questpie";
+
+//#region src/server/modules/admin/routes/translations.d.ts
+
+/**
+ * Admin Translations Functions
+ *
+ * Functions for retrieving admin UI translations from the server.
+ * The client fetches translations for its current UI locale.
+ *
+ * This enables:
+ * - Single source of truth for all translations on server
+ * - Dynamic locale switching without bundling all languages
+ * - Custom messages via config translations
+ */
+/**
+ * Bundle of translation-related functions.
+ */
+declare const translationFunctions: {
+  readonly getAdminTranslations: questpie310.JsonRouteDefinition<{
+    locale: string;
+  }, any>;
+  readonly getAdminLocales: questpie310.JsonRouteDefinition<Record<string, never> | undefined, any>;
+};
+//#endregion
+export { translationFunctions };

package/dist/server/modules/admin/routes/translations.mjs

@@ -0,0 +1,114 @@
+import { getAdminMessagesForLocale, getSupportedAdminLocales } from "../../../i18n/index.mjs";
+import { z } from "zod";
+import { route } from "questpie";
+
+//#region src/server/modules/admin/routes/translations.ts
+/**
+* Admin Translations Functions
+*
+* Functions for retrieving admin UI translations from the server.
+* The client fetches translations for its current UI locale.
+*
+* This enables:
+* - Single source of truth for all translations on server
+* - Dynamic locale switching without bundling all languages
+* - Custom messages via config translations
+*/
+/**
+* Helper to get typed app from handler context.
+*/
+function getApp(ctx) {
+	return ctx.app;
+}
+/**
+* Get admin locale config from app state.
+*/
+function getAdminLocaleConfig(app) {
+	return app.state?.adminLocale;
+}
+const getAdminTranslationsSchema = z.object({ locale: z.string() });
+const messageValueSchema = z.union([z.string(), z.object({
+	one: z.string(),
+	other: z.string()
+})]);
+const getAdminTranslationsOutputSchema = z.object({
+	locale: z.string(),
+	messages: z.record(z.string(), messageValueSchema),
+	fallbackLocale: z.string()
+});
+const getAdminLocalesSchema = z.object({}).optional();
+const getAdminLocalesOutputSchema = z.object({
+	locales: z.array(z.string()),
+	defaultLocale: z.string()
+});
+/**
+* Get admin UI translations for a specific locale.
+*
+* Merges:
+* 1. Built-in admin messages for the locale
+* 2. Custom messages from config translations
+*
+* Custom messages override built-in messages with the same key.
+*
+* @example
+* ```ts
+* // Client fetches translations
+* const { messages, locale, fallbackLocale } = await client.routes.getAdminTranslations({
+*   locale: "sk",
+* });
+*
+* // messages contains all admin UI strings in Slovak
+* ```
+*/
+const getAdminTranslations = route().post().schema(getAdminTranslationsSchema).outputSchema(getAdminTranslationsOutputSchema).handler(async (ctx) => {
+	const app = getApp(ctx);
+	const requestedLocale = ctx.input.locale;
+	const adminLocaleConfig = getAdminLocaleConfig(app);
+	const supportedLocales = adminLocaleConfig?.locales ?? getSupportedAdminLocales();
+	const defaultLocale = adminLocaleConfig?.defaultLocale ?? "en";
+	const locale = supportedLocales.includes(requestedLocale) ? requestedLocale : defaultLocale;
+	const builtInMessages = getAdminMessagesForLocale(locale);
+	const fallbackMessages = locale !== defaultLocale ? getAdminMessagesForLocale(defaultLocale) : {};
+	const customFallbackMessages = locale !== defaultLocale ? app.config.translations?.messages?.[defaultLocale] ?? {} : {};
+	const customMessages = app.config.translations?.messages?.[locale] ?? {};
+	return {
+		locale,
+		messages: {
+			...fallbackMessages,
+			...customFallbackMessages,
+			...builtInMessages,
+			...customMessages
+		},
+		fallbackLocale: defaultLocale
+	};
+});
+/**
+* Get available admin UI locales.
+*
+* Returns locales configured via .adminLocale() or defaults to
+* all locales that have built-in message files.
+*
+* @example
+* ```ts
+* const { locales, defaultLocale } = await client.routes.getAdminLocales({});
+* // locales: ["en", "sk"]
+* // defaultLocale: "en"
+* ```
+*/
+const getAdminLocales = route().post().schema(getAdminLocalesSchema).outputSchema(getAdminLocalesOutputSchema).handler(async (ctx) => {
+	const adminLocaleConfig = getAdminLocaleConfig(getApp(ctx));
+	return {
+		locales: adminLocaleConfig?.locales ?? getSupportedAdminLocales(),
+		defaultLocale: adminLocaleConfig?.defaultLocale ?? "en"
+	};
+});
+/**
+* Bundle of translation-related functions.
+*/
+const translationFunctions = {
+	getAdminTranslations,
+	getAdminLocales
+};
+
+//#endregion
+export { translationFunctions };

package/dist/server/modules/admin/routes/widget-data.d.mts

@@ -0,0 +1,32 @@
+import * as questpie118 from "questpie";
+
+//#region src/server/modules/admin/routes/widget-data.d.ts
+
+/**
+ * Widget Data Functions
+ *
+ * Provides server-side data fetching for widgets that declare a loader.
+ * Called by the client when a widget has `hasLoader: true`.
+ */
+/**
+ * Fetch data for a server-side widget by its ID.
+ *
+ * Looks up the widget in the dashboard config, evaluates its access rule,
+ * and executes its loader with server context.
+ *
+ * @example
+ * ```ts
+ * // Client usage (via useServerWidgetData hook)
+ * const data = await client.routes.fetchWidgetData({ widgetId: "my-widget" });
+ * ```
+ */
+declare const fetchWidgetData: questpie118.JsonRouteDefinition<{
+  widgetId: string;
+}, any>;
+declare const widgetDataFunctions: {
+  readonly fetchWidgetData: questpie118.JsonRouteDefinition<{
+    widgetId: string;
+  }, any>;
+};
+//#endregion
+export { fetchWidgetData, widgetDataFunctions };

package/dist/server/modules/admin/routes/widget-data.mjs

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { ApiError, route, tryGetContext } from "questpie";
+
+//#region src/server/modules/admin/routes/widget-data.ts
+/**
+* Widget Data Functions
+*
+* Provides server-side data fetching for widgets that declare a loader.
+* Called by the client when a widget has `hasLoader: true`.
+*/
+/**
+* Find a widget by ID in the dashboard tree (searches raw server config
+* which still has loader attached).
+*/
+function findWidgetById(items, id) {
+	for (const item of items) {
+		const rec = item;
+		if (item.type === "section") {
+			const found = findWidgetById(rec.items || [], id);
+			if (found) return found;
+		} else if (item.type === "tabs") for (const tab of rec.tabs || []) {
+			const found = findWidgetById(tab.items || [], id);
+			if (found) return found;
+		}
+		else if (rec.id === id) return rec;
+	}
+	return null;
+}
+const fetchWidgetDataSchema = z.object({ widgetId: z.string() });
+/**
+* Fetch data for a server-side widget by its ID.
+*
+* Looks up the widget in the dashboard config, evaluates its access rule,
+* and executes its loader with server context.
+*
+* @example
+* ```ts
+* // Client usage (via useServerWidgetData hook)
+* const data = await client.routes.fetchWidgetData({ widgetId: "my-widget" });
+* ```
+*/
+const fetchWidgetData = route().post().schema(fetchWidgetDataSchema).outputSchema(z.unknown()).handler(async (ctx) => {
+	const appState = (tryGetContext()?.app)?.state || {};
+	const dashboard = appState.config?.admin?.dashboard ?? appState.dashboard;
+	if (!dashboard?.items) throw ApiError.internal("No dashboard configured");
+	const widget = findWidgetById(dashboard.items, ctx.input.widgetId);
+	if (!widget) throw ApiError.notFound("Widget", ctx.input.widgetId);
+	if (!widget.loader) throw ApiError.badRequest(`Widget "${ctx.input.widgetId}" has no loader`);
+	const widgetCtx = ctx;
+	if (widget.access !== void 0) {
+		if ((typeof widget.access === "function" ? await widget.access(widgetCtx) : widget.access) === false) throw ApiError.forbidden({
+			operation: "read",
+			resource: "widget",
+			reason: "Access denied"
+		});
+	}
+	return widget.loader(widgetCtx);
+});
+const widgetDataFunctions = { fetchWidgetData };
+
+//#endregion
+export { fetchWidgetData, widgetDataFunctions };

package/dist/server/modules/admin/views/form.d.mts

@@ -0,0 +1,8 @@
+import { FormViewConfig } from "../../../augmentation/form-layout.mjs";
+import { ViewDefinition } from "../../../augmentation/views.mjs";
+import "../../../augmentation.mjs";
+
+//#region src/server/modules/admin/views/form.d.ts
+declare const _default: ViewDefinition<"collection-form", "form", FormViewConfig>;
+//#endregion
+export { _default };

package/dist/server/modules/admin/views/form.mjs

@@ -0,0 +1,7 @@
+import { view } from "../../../registry-helpers.mjs";
+
+//#region src/server/modules/admin/views/form.ts
+var form_default = view("collection-form", { kind: "form" });
+
+//#endregion
+export { form_default as default };

package/dist/server/modules/admin/views/global-form.d.mts

@@ -0,0 +1,8 @@
+import { FormViewConfig } from "../../../augmentation/form-layout.mjs";
+import { ViewDefinition } from "../../../augmentation/views.mjs";
+import "../../../augmentation.mjs";
+
+//#region src/server/modules/admin/views/global-form.d.ts
+declare const _default: ViewDefinition<"global-form", "form", FormViewConfig>;
+//#endregion
+export { _default };

package/dist/server/modules/admin/views/global-form.mjs

@@ -0,0 +1,7 @@
+import { view } from "../../../registry-helpers.mjs";
+
+//#region src/server/modules/admin/views/global-form.ts
+var global_form_default = view("global-form", { kind: "form" });
+
+//#endregion
+export { global_form_default as default };

package/dist/server/modules/admin/views/table.d.mts

@@ -0,0 +1,8 @@
+import { ListViewConfig } from "../../../augmentation/form-layout.mjs";
+import { ViewDefinition } from "../../../augmentation/views.mjs";
+import "../../../augmentation.mjs";
+
+//#region src/server/modules/admin/views/table.d.ts
+declare const _default: ViewDefinition<"collection-table", "list", ListViewConfig>;
+//#endregion
+export { _default };

package/dist/server/modules/admin/views/table.mjs

@@ -0,0 +1,7 @@
+import { view } from "../../../registry-helpers.mjs";
+
+//#region src/server/modules/admin/views/table.ts
+var table_default = view("collection-table", { kind: "list" });
+
+//#endregion
+export { table_default as default };

package/dist/server/modules/admin-preferences/collections/admin-preferences.mjs

@@ -0,0 +1,37 @@
+import { collection } from "questpie";
+import { uniqueIndex } from "drizzle-orm/pg-core";
+
+//#region src/server/modules/admin-preferences/collections/admin-preferences.ts
+/**
+* Admin Preferences Collection
+*
+* Stores user-specific preferences for admin UI state.
+* This includes view configurations (columns, filters, sort)
+* that persist across devices and sessions.
+*
+* Key format: "viewState:{collectionName}" for view state preferences
+*
+* @example
+* ```ts
+* import { runtimeConfig } from "questpie";
+* import { adminModule } from "@questpie/admin/server";
+*
+* export default runtimeConfig({
+*   modules: [adminModule],
+*   // ...
+* });
+*
+* // Access preferences
+* const prefs = await app.collections.admin_preferences.findOne({
+*   where: { userId: currentUser.id, key: "viewState:posts" }
+* });
+* ```
+*/
+const adminPreferencesCollection = collection("admin_preferences").fields(({ f }) => ({
+	userId: f.text(255).required().label("User ID"),
+	key: f.text(255).required().label("Key"),
+	value: f.json().required().label("Value")
+})).options({ timestamps: true }).indexes(({ table }) => [uniqueIndex("admin_preferences_user_key_idx").on(table.userId, table.key)]);
+
+//#endregion
+export { adminPreferencesCollection };

package/dist/server/modules/admin-preferences/collections/locks.collection.mjs

@@ -0,0 +1,55 @@
+import { collection } from "questpie";
+
+//#region src/server/modules/admin-preferences/collections/locks.collection.ts
+/**
+* Admin Locks Collection
+*
+* Stores document locks for collaborative editing awareness.
+* When a user opens a document for editing, a lock is created.
+* Other users see who is editing and the document becomes read-only for them.
+*
+* Lock behavior:
+* - Locks expire after 60 seconds without heartbeat
+* - Client sends heartbeat every 30 seconds to keep lock alive
+* - On browser close/crash, lock expires automatically
+* - Realtime subscription shows locks in table rows
+*
+* @example
+* ```ts
+* // Acquire lock when opening document
+* await app.collections.admin_locks.create({
+*   resourceType: "collection",
+*   resource: "posts",
+*   resourceId: "123",
+*   userId: currentUser.id,
+*   userName: currentUser.name,
+*   expiresAt: new Date(Date.now() + 60000),
+* });
+*
+* // Heartbeat to keep lock alive
+* await app.collections.admin_locks.update({
+*   id: lockId,
+*   data: { expiresAt: new Date(Date.now() + 60000) },
+* });
+*
+* // Release lock when closing document
+* await app.collections.admin_locks.delete({ id: lockId });
+* ```
+*/
+const locksCollection = collection("admin_locks").fields(({ f }) => ({
+	resourceType: f.select([{
+		value: "collection",
+		label: "Collection"
+	}, {
+		value: "global",
+		label: "Global"
+	}]).required().label("Resource Type"),
+	resource: f.text(255).required().label("Resource"),
+	resourceId: f.text(255).required().label("Resource ID"),
+	user: f.relation("user").required().label("User"),
+	sessionId: f.text(64).required().label("Session ID"),
+	expiresAt: f.date().required().label("Expires At")
+})).options({ timestamps: true });
+
+//#endregion
+export { locksCollection };