@questpie/admin 1.1.1 → 3.0.0

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

@@ -0,0 +1,230 @@
+import { getApp, getCollectionState, getSession } from "./route-helpers.mjs";
+import { getPreviewSecret } from "../../../../shared/preview-utils.mjs";
+import { z } from "zod";
+import { ApiError, route } from "questpie";
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+//#region src/server/modules/admin/routes/preview.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
+*/
+function base64UrlEncode(input) {
+	return (Buffer.isBuffer(input) ? input : Buffer.from(input)).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function base64UrlDecode(input) {
+	let base64 = input.replace(/-/g, "+").replace(/_/g, "/");
+	const padding = base64.length % 4;
+	if (padding) base64 += "=".repeat(4 - padding);
+	return Buffer.from(base64, "base64").toString("utf8");
+}
+const mintPreviewTokenSchema = z.object({
+	path: z.string().min(1, "Path is required"),
+	ttlMs: z.number().positive().optional()
+});
+const mintPreviewTokenOutputSchema = z.object({
+	token: z.string(),
+	expiresAt: z.number()
+});
+const verifyPreviewTokenSchema = z.object({ token: z.string() });
+const verifyPreviewTokenOutputSchema = z.object({
+	valid: z.boolean(),
+	path: z.string().optional(),
+	error: z.string().optional()
+});
+const DEFAULT_TTL_MS = 3600 * 1e3;
+/**
+* Create preview-related RPC functions.
+*
+* @param secret - Secret key for signing tokens
+* @returns Object with preview functions
+*/
+function createPreviewFunctions(secret) {
+	const signPayload = (payload) => {
+		return base64UrlEncode(createHmac("sha256", secret).update(payload).digest());
+	};
+	return {
+		mintPreviewToken: route().post().schema(mintPreviewTokenSchema).outputSchema(mintPreviewTokenOutputSchema).handler(async (ctx) => {
+			const { input } = ctx;
+			if (!getSession(ctx)) throw ApiError.unauthorized("Admin session required");
+			const { path, ttlMs = DEFAULT_TTL_MS } = input;
+			const expiresAt = Date.now() + ttlMs;
+			const payload = {
+				path,
+				exp: expiresAt
+			};
+			const encodedPayload = base64UrlEncode(JSON.stringify(payload));
+			return {
+				token: `${encodedPayload}.${signPayload(encodedPayload)}`,
+				expiresAt
+			};
+		}),
+		verifyPreviewToken: route().post().schema(verifyPreviewTokenSchema).outputSchema(verifyPreviewTokenOutputSchema).handler(async ({ input }) => {
+			const { token } = input;
+			const [encodedPayload, signature] = token.split(".");
+			if (!encodedPayload || !signature) return {
+				valid: false,
+				error: "Invalid token format"
+			};
+			const expectedSignature = signPayload(encodedPayload);
+			const signatureBuffer = Uint8Array.from(Buffer.from(signature));
+			const expectedBuffer = Uint8Array.from(Buffer.from(expectedSignature));
+			if (signatureBuffer.length !== expectedBuffer.length) return {
+				valid: false,
+				error: "Invalid signature"
+			};
+			if (!timingSafeEqual(signatureBuffer, expectedBuffer)) return {
+				valid: false,
+				error: "Invalid signature"
+			};
+			try {
+				const payload = JSON.parse(base64UrlDecode(encodedPayload));
+				if (!payload?.exp || typeof payload.exp !== "number") return {
+					valid: false,
+					error: "Invalid payload"
+				};
+				if (payload.exp < Date.now()) return {
+					valid: false,
+					error: "Token expired"
+				};
+				if (!payload.path || typeof payload.path !== "string") return {
+					valid: false,
+					error: "Invalid path"
+				};
+				return {
+					valid: true,
+					path: payload.path
+				};
+			} catch {
+				return {
+					valid: false,
+					error: "Invalid payload"
+				};
+			}
+		})
+	};
+}
+/**
+* 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
+*/
+function verifyPreviewTokenDirect(token, secret) {
+	const [encodedPayload, signature] = token.split(".");
+	if (!encodedPayload || !signature) return null;
+	const expectedSignature = base64UrlEncode(createHmac("sha256", secret).update(encodedPayload).digest());
+	const signatureBuffer = Uint8Array.from(Buffer.from(signature));
+	const expectedBuffer = Uint8Array.from(Buffer.from(expectedSignature));
+	if (signatureBuffer.length !== expectedBuffer.length) return null;
+	if (!timingSafeEqual(signatureBuffer, expectedBuffer)) return null;
+	try {
+		const payload = JSON.parse(base64UrlDecode(encodedPayload));
+		if (!payload?.exp || typeof payload.exp !== "number") return null;
+		if (payload.exp < Date.now()) return null;
+		if (!payload.path || typeof payload.path !== "string") return null;
+		return payload;
+	} catch {
+		return 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 });
+* }
+* ```
+*/
+function createPreviewTokenVerifier(secret) {
+	const resolvedSecret = secret ?? getPreviewSecret();
+	return (token) => {
+		return verifyPreviewTokenDirect(token, resolvedSecret);
+	};
+}
+const getPreviewUrlSchema = z.object({
+	collection: z.string().min(1, "Collection name is required"),
+	record: z.record(z.string(), z.unknown()),
+	locale: z.string().optional()
+});
+const getPreviewUrlOutputSchema = z.object({
+	url: z.string().nullable(),
+	error: z.string().optional()
+});
+/**
+* Get preview URL for a collection record.
+*
+* Calls the server-side url() function from the collection's .preview() config.
+* This is needed because url() is a function that cannot be serialized to JSON.
+*
+* @example
+* ```ts
+* const { url } = await client.routes.getPreviewUrl({
+*   collection: "pages",
+*   record: { slug: "about", title: "About Us" },
+*   locale: "en",
+* });
+* // Returns: "/about?preview=true"
+* ```
+*/
+const getPreviewUrl = route().post().schema(getPreviewUrlSchema).outputSchema(getPreviewUrlOutputSchema).handler(async (ctx) => {
+	const { input } = ctx;
+	if (!getSession(ctx)) return {
+		url: null,
+		error: "Unauthorized: Admin session required"
+	};
+	const { collection: collectionName, record, locale } = input;
+	const collection$1 = getApp(ctx).getCollections()[collectionName];
+	if (!collection$1) return {
+		url: null,
+		error: `Collection '${collectionName}' not found`
+	};
+	const previewConfig = getCollectionState(collection$1).adminPreview;
+	if (!previewConfig?.url) return {
+		url: null,
+		error: "No preview URL configured for this collection"
+	};
+	if (previewConfig.enabled === false) return {
+		url: null,
+		error: "Preview is disabled for this collection"
+	};
+	try {
+		return { url: previewConfig.url({
+			record,
+			locale
+		}) };
+	} catch (err) {
+		return {
+			url: null,
+			error: `Failed to generate preview URL: ${err instanceof Error ? err.message : "Unknown error"}`
+		};
+	}
+});
+/**
+* Default preview functions bundle with env-based secret.
+* Used by the `adminModule` to register preview RPC functions.
+*/
+const previewFunctions = {
+	...createPreviewFunctions(getPreviewSecret()),
+	getPreviewUrl
+};
+
+//#endregion
+export { createPreviewFunctions, createPreviewTokenVerifier, previewFunctions, verifyPreviewTokenDirect };

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

@@ -0,0 +1,74 @@
+import * as questpie105 from "questpie";
+
+//#region src/server/modules/admin/routes/reactive.d.ts
+
+/**
+ * Reactive Field RPC Endpoints
+ *
+ * Provides server-side execution of reactive field handlers:
+ * - /reactive: Batch endpoint for compute, hidden, readOnly, disabled
+ * - /options: Dynamic options for select/relation fields
+ */
+/**
+ * Batch reactive endpoint.
+ * Executes multiple reactive handlers in a single request.
+ */
+declare const batchReactive: questpie105.JsonRouteDefinition<{
+  collection: string;
+  type: "collection" | "global";
+  requests: {
+    field: string;
+    type: "hidden" | "readOnly" | "disabled" | "compute";
+    formData?: Record<string, unknown> | undefined;
+    siblingData?: Record<string, unknown> | null | undefined;
+    prevData?: Record<string, unknown> | null | undefined;
+    prevSiblingData?: Record<string, unknown> | null | undefined;
+  }[];
+  formData?: Record<string, unknown> | undefined;
+  prevData?: Record<string, unknown> | null | undefined;
+}, any>;
+/**
+ * Dynamic options endpoint.
+ * Fetches options for select/relation fields with search and pagination.
+ */
+declare const fieldOptions: questpie105.JsonRouteDefinition<{
+  collection: string;
+  type: "collection" | "global";
+  field: string;
+  formData: Record<string, unknown>;
+  search: string;
+  page: number;
+  limit: number;
+  siblingData?: Record<string, unknown> | null | undefined;
+}, any>;
+/**
+ * Reactive functions bundle.
+ */
+declare const reactiveFunctions: {
+  readonly batchReactive: questpie105.JsonRouteDefinition<{
+    collection: string;
+    type: "collection" | "global";
+    requests: {
+      field: string;
+      type: "hidden" | "readOnly" | "disabled" | "compute";
+      formData?: Record<string, unknown> | undefined;
+      siblingData?: Record<string, unknown> | null | undefined;
+      prevData?: Record<string, unknown> | null | undefined;
+      prevSiblingData?: Record<string, unknown> | null | undefined;
+    }[];
+    formData?: Record<string, unknown> | undefined;
+    prevData?: Record<string, unknown> | null | undefined;
+  }, any>;
+  readonly fieldOptions: questpie105.JsonRouteDefinition<{
+    collection: string;
+    type: "collection" | "global";
+    field: string;
+    formData: Record<string, unknown>;
+    search: string;
+    page: number;
+    limit: number;
+    siblingData?: Record<string, unknown> | null | undefined;
+  }, any>;
+};
+//#endregion
+export { batchReactive, fieldOptions, reactiveFunctions };

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

@@ -0,0 +1,350 @@
+import { buildServerContext, getApp } from "./route-helpers.mjs";
+import { z } from "zod";
+import { ApiError, route } from "questpie";
+
+//#region src/server/modules/admin/routes/reactive.ts
+/**
+* Build ReactiveContext from request data.
+*/
+function buildReactiveContext(formData, siblingData, prevData, prevSiblingData, serverCtx) {
+	return {
+		data: formData,
+		sibling: siblingData || {},
+		prev: {
+			data: prevData || formData,
+			sibling: prevSiblingData || siblingData || {}
+		},
+		ctx: serverCtx
+	};
+}
+/**
+* Build OptionsContext from request data.
+*/
+function buildOptionsContext(formData, siblingData, search, page, limit, serverCtx) {
+	return {
+		data: formData,
+		sibling: siblingData || {},
+		search,
+		page,
+		limit,
+		ctx: serverCtx
+	};
+}
+/**
+* Get collection builder by name.
+*/
+function getCollection(app, collectionName) {
+	const collection$1 = app.getCollections()[collectionName];
+	if (!collection$1) throw ApiError.notFound("Collection", collectionName);
+	return collection$1;
+}
+/**
+* Get global builder by name.
+*/
+function getGlobal(app, globalName) {
+	const global = app.getGlobals()[globalName];
+	if (!global) throw ApiError.notFound("Global", globalName);
+	return global;
+}
+/**
+* Get entity (collection or global) builder by name and type.
+*/
+function getEntity(app, entityName, type) {
+	if (type === "global") return getGlobal(app, entityName);
+	return getCollection(app, entityName);
+}
+/**
+* Get field definition from collection or global.
+*/
+function getFieldDefinition(app, entityName, fieldPath, type = "collection") {
+	const fieldDefinitions = getEntity(app, entityName, type).state.fieldDefinitions || {};
+	const parts = fieldPath.split(".");
+	let currentDefs = fieldDefinitions;
+	let fieldDef = null;
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i];
+		if (/^\d+$/.test(part)) continue;
+		if (currentDefs[part]) {
+			fieldDef = currentDefs[part];
+			if (fieldDef.getNestedFields) currentDefs = fieldDef.getNestedFields();
+			else if (fieldDef._state?.innerField) {
+				const ofField = fieldDef._state.innerField;
+				if (ofField?.getNestedFields) currentDefs = ofField.getNestedFields();
+			}
+		} else throw ApiError.notFound("Field", `${part} in path '${fieldPath}'`);
+	}
+	if (!fieldDef) {
+		const entityType = type === "global" ? "Global" : "Collection";
+		throw ApiError.notFound(`${entityType} field`, `${entityName}.${fieldPath}`);
+	}
+	return fieldDef;
+}
+/**
+* Remove numeric indices from nested field paths.
+*/
+function normalizeFieldPath(fieldPath) {
+	return fieldPath.split(".").filter((part) => !/^\d+$/.test(part)).join(".");
+}
+/**
+* Generate candidate field paths for matching form entries.
+*/
+function getFieldPathCandidates(fieldPath) {
+	const normalized = normalizeFieldPath(fieldPath);
+	const candidates = new Set([normalized]);
+	const parts = normalized.split(".");
+	if (parts.length > 1) {
+		const leaf = parts[parts.length - 1];
+		if (leaf) candidates.add(leaf);
+	}
+	return candidates;
+}
+/**
+* Find a reactive field entry in form layout items recursively.
+*/
+function findReactiveFieldEntryInLayoutItems(items, fieldCandidates) {
+	if (!Array.isArray(items)) return null;
+	for (const item of items) {
+		if (!item || typeof item !== "object") continue;
+		const entry = item;
+		if (typeof entry.field === "string" && fieldCandidates.has(entry.field)) return entry;
+		if (entry.type === "section") {
+			const found = findReactiveFieldEntryInLayoutItems(entry.fields, fieldCandidates);
+			if (found) return found;
+			continue;
+		}
+		if (entry.type === "tabs") {
+			const found = findReactiveFieldEntryInTabs(entry.tabs, fieldCandidates);
+			if (found) return found;
+		}
+	}
+	return null;
+}
+/**
+* Find a reactive field entry in form sections.
+*/
+function findReactiveFieldEntryInSections(sections, fieldCandidates) {
+	if (!Array.isArray(sections)) return null;
+	for (const section of sections) {
+		if (!section || typeof section !== "object") continue;
+		const found = findReactiveFieldEntryInLayoutItems(section.fields, fieldCandidates);
+		if (found) return found;
+	}
+	return null;
+}
+/**
+* Find a reactive field entry in form tabs.
+*/
+function findReactiveFieldEntryInTabs(tabs, fieldCandidates) {
+	if (!Array.isArray(tabs)) return null;
+	for (const tab of tabs) {
+		if (!tab || typeof tab !== "object") continue;
+		const tabConfig = tab;
+		const fromFields = findReactiveFieldEntryInLayoutItems(tabConfig.fields, fieldCandidates);
+		if (fromFields) return fromFields;
+		const fromSections = findReactiveFieldEntryInSections(tabConfig.sections, fieldCandidates);
+		if (fromSections) return fromSections;
+	}
+	return null;
+}
+/**
+* Find field entry config from collection form configuration.
+*/
+function findReactiveFieldEntry(formConfig, fieldPath) {
+	if (!formConfig || typeof formConfig !== "object") return null;
+	const fieldCandidates = getFieldPathCandidates(fieldPath);
+	const form = formConfig;
+	const fromFields = findReactiveFieldEntryInLayoutItems(form.fields, fieldCandidates);
+	if (fromFields) return fromFields;
+	const fromSections = findReactiveFieldEntryInSections(form.sections, fieldCandidates);
+	if (fromSections) return fromSections;
+	const fromTabs = findReactiveFieldEntryInTabs(form.tabs, fieldCandidates);
+	if (fromTabs) return fromTabs;
+	if (form.sidebar && typeof form.sidebar === "object") {
+		const sidebar = form.sidebar;
+		return findReactiveFieldEntryInLayoutItems(sidebar.fields, fieldCandidates);
+	}
+	return null;
+}
+/**
+* Get reactive handler from collection/global form config.
+*/
+function getReactiveHandler(app, entityName, fieldPath, handlerType, type = "collection") {
+	const formConfig = getEntity(app, entityName, type).state.adminForm;
+	const fieldEntry = findReactiveFieldEntry(formConfig, fieldPath);
+	if (!fieldEntry) return null;
+	const handlerConfig = fieldEntry[handlerType];
+	if (!handlerConfig || typeof handlerConfig === "boolean") return null;
+	if (typeof handlerConfig === "function") return handlerConfig;
+	if (typeof handlerConfig === "object" && handlerConfig !== null && "handler" in handlerConfig && typeof handlerConfig.handler === "function") return handlerConfig.handler;
+	return null;
+}
+/**
+* Get options handler from field config.
+*/
+function getOptionsHandler(fieldDef) {
+	const options = fieldDef._state?.options;
+	if (!options) return null;
+	if (typeof options === "object" && "handler" in options) return options.handler;
+	return null;
+}
+/**
+* Single reactive request in a batch.
+*/
+const reactiveRequestSchema = z.object({
+	field: z.string(),
+	type: z.enum([
+		"hidden",
+		"readOnly",
+		"disabled",
+		"compute"
+	]),
+	formData: z.record(z.string(), z.unknown()).optional(),
+	siblingData: z.record(z.string(), z.unknown()).nullable().optional(),
+	prevData: z.record(z.string(), z.unknown()).nullable().optional(),
+	prevSiblingData: z.record(z.string(), z.unknown()).nullable().optional()
+});
+/**
+* Batch reactive request.
+*/
+const batchReactiveInputSchema = z.object({
+	collection: z.string(),
+	type: z.enum(["collection", "global"]).default("collection"),
+	formData: z.record(z.string(), z.unknown()).optional(),
+	prevData: z.record(z.string(), z.unknown()).nullable().optional(),
+	requests: z.array(reactiveRequestSchema)
+});
+/**
+* Single reactive result.
+*/
+const reactiveResultSchema = z.object({
+	field: z.string(),
+	type: z.enum([
+		"hidden",
+		"readOnly",
+		"disabled",
+		"compute"
+	]),
+	value: z.unknown(),
+	error: z.string().optional()
+});
+/**
+* Batch reactive response.
+*/
+const batchReactiveOutputSchema = z.object({ results: z.array(reactiveResultSchema) });
+/**
+* Options request.
+*/
+const optionsInputSchema = z.object({
+	collection: z.string(),
+	type: z.enum(["collection", "global"]).default("collection"),
+	field: z.string(),
+	formData: z.record(z.string(), z.unknown()),
+	siblingData: z.record(z.string(), z.unknown()).nullable().optional(),
+	search: z.string().default(""),
+	page: z.number().int().min(0).default(0),
+	limit: z.number().int().min(1).max(100).default(20)
+});
+/**
+* Options response.
+*/
+const optionsOutputSchema = z.object({
+	options: z.array(z.object({
+		value: z.union([z.string(), z.number()]),
+		label: z.union([z.string(), z.record(z.string(), z.string())])
+	})),
+	hasMore: z.boolean().optional(),
+	total: z.number().optional()
+});
+/**
+* Batch reactive endpoint.
+* Executes multiple reactive handlers in a single request.
+*/
+const batchReactive = route().post().schema(batchReactiveInputSchema).outputSchema(batchReactiveOutputSchema).handler(async (ctx) => {
+	const app = getApp(ctx);
+	const { collection: entityName, type: entityType, requests, formData: sharedFormData, prevData: sharedPrevData } = ctx.input;
+	const serverCtx = buildServerContext(ctx);
+	return { results: await Promise.all(requests.map(async (request) => {
+		const { field: field$1, type, formData, siblingData, prevData, prevSiblingData } = request;
+		const resolvedFormData = formData ?? sharedFormData ?? {};
+		const resolvedPrevData = prevData ?? sharedPrevData ?? null;
+		try {
+			getFieldDefinition(app, entityName, field$1, entityType);
+			const handler = getReactiveHandler(app, entityName, field$1, type, entityType);
+			if (!handler) return {
+				field: field$1,
+				type,
+				value: void 0,
+				error: `No ${type} handler found for field '${field$1}'`
+			};
+			return {
+				field: field$1,
+				type,
+				value: await handler(buildReactiveContext(resolvedFormData, siblingData, resolvedPrevData, prevSiblingData, serverCtx))
+			};
+		} catch (error) {
+			return {
+				field: field$1,
+				type,
+				value: void 0,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	})) };
+});
+/**
+* Dynamic options endpoint.
+* Fetches options for select/relation fields with search and pagination.
+*/
+const fieldOptions = route().post().schema(optionsInputSchema).outputSchema(optionsOutputSchema).handler(async (ctx) => {
+	const app = getApp(ctx);
+	const { collection: entityName, type: entityType, field: field$1, formData, siblingData, search, page, limit } = ctx.input;
+	const serverCtx = buildServerContext(ctx);
+	try {
+		const fieldDef = getFieldDefinition(app, entityName, field$1, entityType);
+		const handler = getOptionsHandler(fieldDef);
+		if (!handler) {
+			const fieldOptions$1 = fieldDef._state?.options;
+			if (Array.isArray(fieldOptions$1)) {
+				let options = fieldOptions$1;
+				if (search) {
+					const searchLower = search.toLowerCase();
+					options = options.filter((opt) => {
+						return (typeof opt.label === "string" ? opt.label : Object.values(opt.label).join(" ")).toLowerCase().includes(searchLower);
+					});
+				}
+				const start = page * limit;
+				return {
+					options: options.slice(start, start + limit),
+					hasMore: start + limit < options.length,
+					total: options.length
+				};
+			}
+			return {
+				options: [],
+				hasMore: false
+			};
+		}
+		const result = await handler(buildOptionsContext(formData, siblingData, search, page, limit, serverCtx));
+		return {
+			options: result.options || [],
+			hasMore: result.hasMore,
+			total: result.total
+		};
+	} catch (error) {
+		console.error(`Error fetching options for ${entityName}.${field$1}:`, error);
+		return {
+			options: [],
+			hasMore: false
+		};
+	}
+});
+/**
+* Reactive functions bundle.
+*/
+const reactiveFunctions = {
+	batchReactive,
+	fieldOptions
+};
+
+//#endregion
+export { batchReactive, fieldOptions, reactiveFunctions };

package/dist/server/modules/admin/routes/route-helpers.d.mts

@@ -0,0 +1,23 @@
+import { Questpie } from "questpie";
+
+//#region src/server/modules/admin/routes/route-helpers.d.ts
+
+/**
+ * Minimal typed shape for route handler context.
+ * The actual context is `JsonRouteHandlerArgs<T>` which extends `AppContext`,
+ * but AppContext is empty in the admin package (augmented by user's codegen).
+ *
+ * These helpers safely extract the known properties at runtime.
+ * Uses Record<string, any> base to accept JsonRouteHandlerArgs without index signature issues.
+ */
+type RouteHandlerContext = Record<string, any>;
+/**
+ * Typed app instance type used throughout admin routes.
+ */
+type App = Questpie<any>;
+/**
+ * Get typed Questpie app instance from route handler context.
+ */
+declare function getApp(ctx: RouteHandlerContext): App;
+//#endregion
+export { App, getApp };