@questpie/admin 1.1.1 → 3.0.0

package/dist/server/modules/admin/routes/execute-action.d.mts

@@ -0,0 +1,92 @@
+import { ServerActionDefinition, ServerActionResult } from "../../../augmentation/actions.mjs";
+import "../../../augmentation.mjs";
+import { App } from "./route-helpers.mjs";
+import * as questpie76 from "questpie";
+
+//#region src/server/modules/admin/routes/execute-action.d.ts
+
+/**
+ * Request to execute an action
+ */
+interface ExecuteActionRequest {
+  /** Collection slug */
+  collection: string;
+  /** Action ID (builtin: "create", "delete", etc. or custom id) */
+  actionId: string;
+  /** Single item ID (for single-item actions) */
+  itemId?: string;
+  /** Multiple item IDs (for bulk actions) */
+  itemIds?: string[];
+  /** Form data (for actions with forms) */
+  data?: Record<string, unknown>;
+  /** Current locale */
+  locale?: string;
+}
+/**
+ * Response from action execution
+ */
+interface ExecuteActionResponse {
+  success: boolean;
+  result?: ServerActionResult;
+  error?: string;
+}
+/**
+ * Get action configuration for introspection.
+ * Returns action definitions without handlers (for client-side rendering).
+ */
+declare function getActionsConfig(app: App, collectionSlug: string): {
+  builtin: string[];
+  custom: Array<Omit<ServerActionDefinition, "handler">>;
+} | null;
+/**
+ * Execute a collection action.
+ * Handles both built-in actions and custom actions.
+ */
+declare function executeAction(app: App, request: ExecuteActionRequest, session?: unknown): Promise<ExecuteActionResponse>;
+/**
+ * Execute a collection action.
+ *
+ * @example
+ * ```ts
+ * // From client
+ * const result = await client.routes.executeAction({
+ *   collection: "posts",
+ *   actionId: "publish",
+ *   itemId: "123",
+ * });
+ * ```
+ */
+declare const executeActionFn: questpie76.JsonRouteDefinition<{
+  collection: string;
+  actionId: string;
+  itemId?: string | undefined;
+  itemIds?: string[] | undefined;
+  data?: Record<string, unknown> | undefined;
+  locale?: string | undefined;
+}, any>;
+/**
+ * Get actions configuration for a collection.
+ * Returns action definitions without handlers for client rendering.
+ */
+declare const getActionsConfigFn: questpie76.JsonRouteDefinition<{
+  collection: string;
+}, any>;
+/**
+ * QUESTPIE functions for action execution.
+ * These are registered on the `adminModule`.
+ */
+declare const actionFunctions: {
+  executeAction: questpie76.JsonRouteDefinition<{
+    collection: string;
+    actionId: string;
+    itemId?: string | undefined;
+    itemIds?: string[] | undefined;
+    data?: Record<string, unknown> | undefined;
+    locale?: string | undefined;
+  }, any>;
+  getActionsConfig: questpie76.JsonRouteDefinition<{
+    collection: string;
+  }, any>;
+};
+//#endregion
+export { ExecuteActionRequest, ExecuteActionResponse, actionFunctions, executeAction, executeActionFn, getActionsConfig, getActionsConfigFn };

package/dist/server/modules/admin/routes/execute-action.mjs

@@ -0,0 +1,433 @@
+import { getApp, getAppState, getSession } from "./route-helpers.mjs";
+import { z } from "zod";
+import { route } from "questpie";
+
+//#region src/server/modules/admin/routes/execute-action.ts
+/**
+* Action Execution Functions
+*
+* Server-side functions for executing collection actions.
+* Actions can be built-in (create, delete, etc.) or custom with forms.
+*
+* @example
+* ```ts
+* // Execute a custom action
+* const result = await executeAction(app, {
+*   collection: "posts",
+*   actionId: "publish",
+*   itemId: "123",
+*   data: {},
+* });
+* ```
+*/
+/**
+* Get action configuration for introspection.
+* Returns action definitions without handlers (for client-side rendering).
+*/
+function getActionsConfig(app, collectionSlug) {
+	const collection$1 = getAppState(app).collections?.[collectionSlug];
+	if (!collection$1) return null;
+	const actionsConfig = (collection$1.state || collection$1).adminActions;
+	if (!actionsConfig) return {
+		builtin: [
+			"create",
+			"save",
+			"delete",
+			"deleteMany",
+			"restore",
+			"restoreMany",
+			"duplicate",
+			"transition"
+		],
+		custom: []
+	};
+	const customWithoutHandlers = (actionsConfig.custom || []).map((action) => {
+		const { handler, ...rest } = action;
+		return rest;
+	});
+	return {
+		builtin: actionsConfig.builtin || [
+			"create",
+			"save",
+			"delete",
+			"deleteMany",
+			"restore",
+			"restoreMany",
+			"duplicate"
+		],
+		custom: customWithoutHandlers
+	};
+}
+/**
+* Execute a collection action.
+* Handles both built-in actions and custom actions.
+*/
+async function executeAction(app, request, session) {
+	const { collection: collectionSlug, actionId, itemId, itemIds, data, locale } = request;
+	const collection$1 = getAppState(app).collections?.[collectionSlug];
+	if (!collection$1) return {
+		success: false,
+		error: `Collection "${collectionSlug}" not found`
+	};
+	const actionsConfig = (collection$1.state || collection$1).adminActions;
+	if ((actionsConfig?.builtin || [
+		"create",
+		"save",
+		"delete",
+		"deleteMany",
+		"restore",
+		"restoreMany",
+		"duplicate",
+		"transition"
+	]).includes(actionId)) return executeBuiltinAction(app, {
+		collectionSlug,
+		actionId,
+		itemId,
+		itemIds,
+		data,
+		locale,
+		session
+	});
+	const customAction = actionsConfig?.custom?.find((a) => a.id === actionId);
+	if (!customAction) return {
+		success: false,
+		error: `Action "${actionId}" not found on collection "${collectionSlug}"`
+	};
+	if (customAction.form) {
+		const validationError = validateActionFormData(customAction.form.fields, data || {});
+		if (validationError) return {
+			success: false,
+			result: {
+				type: "error",
+				toast: { message: validationError }
+			}
+		};
+	}
+	try {
+		const appRec = app;
+		const context = {
+			data: data || {},
+			itemId,
+			itemIds,
+			auth: appRec.auth,
+			collections: appRec.api?.collections,
+			globals: appRec.api?.globals,
+			db: appRec.db,
+			session,
+			locale
+		};
+		const result = await customAction.handler(context);
+		return {
+			success: result.type === "success" || result.type === "redirect",
+			result
+		};
+	} catch (error) {
+		console.error(`Action "${actionId}" failed:`, error);
+		return {
+			success: false,
+			result: {
+				type: "error",
+				toast: { message: error instanceof Error ? error.message : "Action execution failed" }
+			}
+		};
+	}
+}
+/**
+* Execute a built-in action.
+*/
+async function executeBuiltinAction(app, params) {
+	const { collectionSlug, actionId, itemId, itemIds, data } = params;
+	const appRec = app;
+	const collectionCrud = appRec.api?.collections?.[collectionSlug];
+	const crudContext = {
+		db: appRec.db,
+		session: params.session,
+		locale: params.locale
+	};
+	try {
+		switch (actionId) {
+			case "create": {
+				const result = await appRec.create(collectionSlug, data || {});
+				return {
+					success: true,
+					result: {
+						type: "success",
+						toast: { message: "Item created successfully" },
+						effects: {
+							invalidate: [collectionSlug],
+							redirect: `/admin/collections/${collectionSlug}/${result.id}`
+						}
+					}
+				};
+			}
+			case "save":
+				if (!itemId) return {
+					success: false,
+					result: {
+						type: "error",
+						toast: { message: "Item ID is required for save action" }
+					}
+				};
+				await appRec.update(collectionSlug, itemId, data || {});
+				return {
+					success: true,
+					result: {
+						type: "success",
+						toast: { message: "Item saved successfully" },
+						effects: { invalidate: [collectionSlug] }
+					}
+				};
+			case "delete":
+				if (!itemId) return {
+					success: false,
+					result: {
+						type: "error",
+						toast: { message: "Item ID is required for delete action" }
+					}
+				};
+				await appRec.delete(collectionSlug, itemId);
+				return {
+					success: true,
+					result: {
+						type: "success",
+						toast: { message: "Item deleted successfully" },
+						effects: {
+							invalidate: [collectionSlug],
+							redirect: `/admin/collections/${collectionSlug}`
+						}
+					}
+				};
+			case "deleteMany":
+				if (!itemIds || itemIds.length === 0) return {
+					success: false,
+					result: {
+						type: "error",
+						toast: { message: "Item IDs are required for bulk delete action" }
+					}
+				};
+				await Promise.all(itemIds.map((id) => appRec.delete(collectionSlug, id)));
+				return {
+					success: true,
+					result: {
+						type: "success",
+						toast: { message: `${itemIds.length} items deleted successfully` },
+						effects: { invalidate: [collectionSlug] }
+					}
+				};
+			case "restore":
+				if (!itemId) return {
+					success: false,
+					result: {
+						type: "error",
+						toast: { message: "Item ID is required for restore action" }
+					}
+				};
+				if (typeof appRec.restore === "function") await appRec.restore(collectionSlug, itemId);
+				else if (collectionCrud?.restoreById) await collectionCrud.restoreById({ id: itemId }, crudContext);
+				else return {
+					success: false,
+					result: {
+						type: "error",
+						toast: { message: "Restore is not supported for this collection" }
+					}
+				};
+				return {
+					success: true,
+					result: {
+						type: "success",
+						toast: { message: "Item restored successfully" },
+						effects: {
+							invalidate: [collectionSlug],
+							redirect: `/admin/collections/${collectionSlug}/${itemId}`
+						}
+					}
+				};
+			case "restoreMany":
+				if (!itemIds || itemIds.length === 0) return {
+					success: false,
+					result: {
+						type: "error",
+						toast: { message: "Item IDs are required for bulk restore action" }
+					}
+				};
+				if (typeof appRec.restore === "function") await Promise.all(itemIds.map((id) => appRec.restore(collectionSlug, id)));
+				else if (collectionCrud?.restoreById) await Promise.all(itemIds.map((id) => collectionCrud.restoreById({ id }, crudContext)));
+				else return {
+					success: false,
+					result: {
+						type: "error",
+						toast: { message: "Restore is not supported for this collection" }
+					}
+				};
+				return {
+					success: true,
+					result: {
+						type: "success",
+						toast: { message: `${itemIds.length} items restored successfully` },
+						effects: { invalidate: [collectionSlug] }
+					}
+				};
+			case "duplicate": {
+				if (!itemId) return {
+					success: false,
+					result: {
+						type: "error",
+						toast: { message: "Item ID is required for duplicate action" }
+					}
+				};
+				const original = await appRec.findById(collectionSlug, itemId);
+				if (!original) return {
+					success: false,
+					result: {
+						type: "error",
+						toast: { message: "Item not found" }
+					}
+				};
+				const { id, createdAt, updatedAt, ...duplicateData } = original;
+				const duplicated = await appRec.create(collectionSlug, duplicateData);
+				return {
+					success: true,
+					result: {
+						type: "success",
+						toast: { message: "Item duplicated successfully" },
+						effects: {
+							invalidate: [collectionSlug],
+							redirect: `/admin/collections/${collectionSlug}/${duplicated.id}`
+						}
+					}
+				};
+			}
+			case "transition": {
+				if (!itemId) return {
+					success: false,
+					result: {
+						type: "error",
+						toast: { message: "Item ID is required for transition action" }
+					}
+				};
+				const stage = data?.stage;
+				if (!stage) return {
+					success: false,
+					result: {
+						type: "error",
+						toast: { message: "Target stage is required for transition action" }
+					}
+				};
+				if (collectionCrud?.transitionStage) {
+					const scheduledAt = data?.scheduledAt;
+					const transitionParams = {
+						id: itemId,
+						stage
+					};
+					if (scheduledAt) transitionParams.scheduledAt = new Date(scheduledAt);
+					await collectionCrud.transitionStage(transitionParams, crudContext);
+				} else return {
+					success: false,
+					result: {
+						type: "error",
+						toast: { message: "Workflow transitions are not supported for this collection" }
+					}
+				};
+				return {
+					success: true,
+					result: {
+						type: "success",
+						toast: { message: `Transitioned to "${stage}" successfully` },
+						effects: { invalidate: [collectionSlug] }
+					}
+				};
+			}
+			default: return {
+				success: false,
+				result: {
+					type: "error",
+					toast: { message: `Unknown built-in action: ${actionId}` }
+				}
+			};
+		}
+	} catch (error) {
+		console.error(`Built-in action "${actionId}" failed:`, error);
+		return {
+			success: false,
+			result: {
+				type: "error",
+				toast: { message: error instanceof Error ? error.message : "Action execution failed" }
+			}
+		};
+	}
+}
+/**
+* Check if a field is a ServerActionFormFieldDefinition (has getMetadata)
+*/
+function isFieldDefinition(field$1) {
+	return typeof field$1.getMetadata === "function";
+}
+/**
+* Extract required status from a form field (handles both config and definition)
+*/
+function isFieldRequired(field$1) {
+	if (isFieldDefinition(field$1)) return !!field$1._state?.notNull;
+	return !!field$1.required;
+}
+/**
+* Validate form data against action form fields.
+* Returns error message if validation fails, null if valid.
+*/
+function validateActionFormData(fields, data) {
+	for (const [fieldName, fieldConfig] of Object.entries(fields)) if (isFieldRequired(fieldConfig) && !data[fieldName]) return `Field "${fieldName}" is required`;
+	return null;
+}
+const executeActionRequestSchema = z.object({
+	collection: z.string(),
+	actionId: z.string(),
+	itemId: z.string().optional(),
+	itemIds: z.array(z.string()).optional(),
+	data: z.record(z.string(), z.unknown()).optional(),
+	locale: z.string().optional()
+});
+const executeActionResponseSchema = z.object({
+	success: z.boolean(),
+	result: z.record(z.string(), z.any()).optional(),
+	error: z.string().optional()
+});
+const getActionsConfigRequestSchema = z.object({ collection: z.string() });
+const getActionsConfigResponseSchema = z.object({
+	builtin: z.array(z.string()),
+	custom: z.array(z.record(z.string(), z.any()))
+}).nullable();
+/**
+* Execute a collection action.
+*
+* @example
+* ```ts
+* // From client
+* const result = await client.routes.executeAction({
+*   collection: "posts",
+*   actionId: "publish",
+*   itemId: "123",
+* });
+* ```
+*/
+const executeActionFn = route().post().schema(executeActionRequestSchema).outputSchema(executeActionResponseSchema).handler(async (ctx) => {
+	const app = getApp(ctx);
+	const session = getSession(ctx);
+	return executeAction(app, ctx.input, session);
+});
+/**
+* Get actions configuration for a collection.
+* Returns action definitions without handlers for client rendering.
+*/
+const getActionsConfigFn = route().post().schema(getActionsConfigRequestSchema).outputSchema(getActionsConfigResponseSchema).handler((ctx) => {
+	return getActionsConfig(getApp(ctx), ctx.input.collection);
+});
+/**
+* QUESTPIE functions for action execution.
+* These are registered on the `adminModule`.
+*/
+const actionFunctions = {
+	executeAction: executeActionFn,
+	getActionsConfig: getActionsConfigFn
+};
+
+//#endregion
+export { actionFunctions, executeAction, executeActionFn, getActionsConfig, getActionsConfigFn };

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

@@ -0,0 +1,18 @@
+import * as questpie312 from "questpie";
+
+//#region src/server/modules/admin/routes/locales.d.ts
+
+/**
+ * Content Locales Functions
+ *
+ * Functions for retrieving available content locales from the app configuration.
+ * Used by the admin panel to populate locale switchers and validate locale selection.
+ */
+/**
+ * Bundle of locale-related functions.
+ */
+declare const localeFunctions: {
+  readonly getContentLocales: questpie312.JsonRouteDefinition<Record<string, never> | undefined, any>;
+};
+//#endregion
+export { localeFunctions };

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

@@ -0,0 +1,69 @@
+import { getApp } from "./route-helpers.mjs";
+import { z } from "zod";
+import { route } from "questpie";
+
+//#region src/server/modules/admin/routes/locales.ts
+/**
+* Content Locales Functions
+*
+* Functions for retrieving available content locales from the app configuration.
+* Used by the admin panel to populate locale switchers and validate locale selection.
+*/
+const getContentLocalesSchema = z.object({}).optional();
+const getContentLocalesOutputSchema = z.object({
+	locales: z.array(z.object({
+		code: z.string(),
+		label: z.string().optional(),
+		fallback: z.boolean().optional(),
+		flagCountryCode: z.string().optional()
+	})),
+	defaultLocale: z.string(),
+	fallbacks: z.record(z.string(), z.string()).optional()
+});
+/**
+* Get available content locales from app configuration.
+*
+* Returns the list of available locales for content localization,
+* the default locale, and any fallback mappings.
+*
+* @example
+* ```ts
+* const result = await client.routes.getContentLocales({});
+* // {
+* //   locales: [
+* //     { code: "en", label: "English", fallback: true },
+* //     { code: "sk", label: "Slovenčina" },
+* //   ],
+* //   defaultLocale: "en",
+* //   fallbacks: { "en-GB": "en" },
+* // }
+* ```
+*/
+const getContentLocales = route().post().schema(getContentLocalesSchema).outputSchema(getContentLocalesOutputSchema).handler(async (ctx) => {
+	const localeConfig = getApp(ctx).config.locale;
+	if (!localeConfig) return {
+		locales: [{
+			code: "en",
+			label: "English",
+			fallback: true
+		}],
+		defaultLocale: "en"
+	};
+	return {
+		locales: (typeof localeConfig.locales === "function" ? await localeConfig.locales() : localeConfig.locales).map((l) => ({
+			code: l.code,
+			label: l.label,
+			fallback: l.fallback,
+			flagCountryCode: l.flagCountryCode
+		})),
+		defaultLocale: localeConfig.defaultLocale,
+		fallbacks: localeConfig.fallbacks
+	};
+});
+/**
+* Bundle of locale-related functions.
+*/
+const localeFunctions = { getContentLocales };
+
+//#endregion
+export { localeFunctions };

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

@@ -0,0 +1,80 @@
+import * as questpie109 from "questpie";
+
+//#region src/server/modules/admin/routes/preview.d.ts
+
+/**
+ * Preview Functions - Server-side
+ *
+ * RPC functions for draft mode preview.
+ * Handles token minting for secure, shareable preview links.
+ *
+ * Browser-safe utilities (isDraftMode, createDraftModeCookie, etc.) are in @questpie/admin/shared
+ */
+interface PreviewTokenPayload {
+  path: string;
+  exp: number;
+}
+/**
+ * Create preview-related RPC functions.
+ *
+ * @param secret - Secret key for signing tokens
+ * @returns Object with preview functions
+ */
+declare function createPreviewFunctions(secret: string): {
+  mintPreviewToken: questpie109.JsonRouteDefinition<{
+    path: string;
+    ttlMs?: number | undefined;
+  }, any>;
+  verifyPreviewToken: questpie109.JsonRouteDefinition<{
+    token: string;
+  }, any>;
+};
+/**
+ * Verify a preview token without RPC.
+ * Used directly in route handlers where RPC is not available.
+ *
+ * @param token - The preview token to verify
+ * @param secret - The secret used to sign the token
+ * @returns The payload if valid, null otherwise
+ */
+declare function verifyPreviewTokenDirect(token: string, secret: string): PreviewTokenPayload | null;
+/**
+ * Create a preview token verifier with bound secret.
+ * Use this in route handlers to avoid passing secret repeatedly.
+ *
+ * @param secret - The secret used to sign tokens (optional, uses env if not provided)
+ * @returns A verify function that only needs the token
+ *
+ * @example
+ * ```ts
+ * // Create once at module level
+ * const verifyPreviewToken = createPreviewTokenVerifier();
+ *
+ * // Use in route handler
+ * const payload = verifyPreviewToken(token);
+ * if (!payload) {
+ *   return new Response("Invalid token", { status: 401 });
+ * }
+ * ```
+ */
+declare function createPreviewTokenVerifier(secret?: string): (token: string) => PreviewTokenPayload | null;
+/**
+ * Default preview functions bundle with env-based secret.
+ * Used by the `adminModule` to register preview RPC functions.
+ */
+declare const previewFunctions: {
+  getPreviewUrl: questpie109.JsonRouteDefinition<{
+    collection: string;
+    record: Record<string, unknown>;
+    locale?: string | undefined;
+  }, any>;
+  mintPreviewToken: questpie109.JsonRouteDefinition<{
+    path: string;
+    ttlMs?: number | undefined;
+  }, any>;
+  verifyPreviewToken: questpie109.JsonRouteDefinition<{
+    token: string;
+  }, any>;
+};
+//#endregion
+export { PreviewTokenPayload, createPreviewFunctions, createPreviewTokenVerifier, previewFunctions, verifyPreviewTokenDirect };