@questpie/admin 1.1.1 → 3.0.0

package/dist/server/adapters/tanstack.d.mts

@@ -0,0 +1,132 @@
+import { Questpie } from "questpie";
+
+//#region src/server/adapters/tanstack.d.ts
+
+/**
+ * Options for TanStack auth guard
+ */
+interface TanStackAuthGuardOptions {
+  /**
+   * The app instance with auth configured
+   */
+  app: Questpie<any>;
+  /**
+   * Path to redirect to when not authenticated
+   * @default "/admin/login"
+   */
+  loginPath?: string;
+  /**
+   * Required role for access
+   * @default "admin"
+   */
+  requiredRole?: string;
+  /**
+   * Query parameter name for redirect URL
+   * @default "redirect"
+   */
+  redirectParam?: string;
+}
+/**
+ * Context passed to TanStack Router beforeLoad
+ */
+interface BeforeLoadContext {
+  context: {
+    request: Request;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+/**
+ * Create a TanStack Router beforeLoad guard for admin authentication.
+ *
+ * Returns a function that can be used as beforeLoad in route definitions.
+ * Throws a redirect Response when authentication fails.
+ *
+ * @example
+ * ```ts
+ * import { createFileRoute } from "@tanstack/react-router";
+ * import { createTanStackAuthGuard } from "@questpie/admin/server/adapters/tanstack";
+ * import { app } from "@/questpie/server/app";
+ *
+ * export const Route = createFileRoute("/admin")({
+ *   beforeLoad: createTanStackAuthGuard({
+ *     app,
+ *     loginPath: "/admin/login",
+ *     requiredRole: "admin",
+ *   }),
+ *   component: AdminLayout,
+ * });
+ * ```
+ *
+ * @example With custom context
+ * ```ts
+ * export const Route = createFileRoute("/admin")({
+ *   beforeLoad: async (ctx) => {
+ *     // Run auth guard
+ *     await createTanStackAuthGuard({ app })(ctx);
+ *
+ *     // Add additional context
+ *     return { user: ctx.context.user };
+ *   },
+ * });
+ * ```
+ */
+declare function createTanStackAuthGuard({
+  app,
+  loginPath,
+  requiredRole,
+  redirectParam
+}: TanStackAuthGuardOptions): ({
+  context
+}: BeforeLoadContext) => Promise<void>;
+/**
+ * Create a TanStack Router loader that injects the admin session into context.
+ *
+ * Use this when you need access to the session in your components.
+ *
+ * @example
+ * ```ts
+ * import { createTanStackSessionLoader } from "@questpie/admin/server/adapters/tanstack";
+ *
+ * export const Route = createFileRoute("/admin")({
+ *   loader: createTanStackSessionLoader({ app }),
+ *   component: AdminLayout,
+ * });
+ *
+ * function AdminLayout() {
+ *   const { session } = Route.useLoaderData();
+ *   return <div>Hello {session?.user?.name}</div>;
+ * }
+ * ```
+ */
+declare function createTanStackSessionLoader({
+  app
+}: {
+  app: Questpie<any>;
+}): ({
+  context
+}: BeforeLoadContext) => Promise<{
+  session: {
+    session: {
+      id: string;
+      createdAt: Date;
+      updatedAt: Date;
+      userId: string;
+      expiresAt: Date;
+      token: string;
+      ipAddress?: string | null | undefined | undefined;
+      userAgent?: string | null | undefined | undefined;
+    };
+    user: {
+      id: string;
+      createdAt: Date;
+      updatedAt: Date;
+      email: string;
+      emailVerified: boolean;
+      name: string;
+      image?: string | null | undefined | undefined;
+    };
+  } | null;
+}>;
+//#endregion
+export { BeforeLoadContext, TanStackAuthGuardOptions, createTanStackAuthGuard, createTanStackSessionLoader };

package/dist/server/adapters/tanstack.mjs

@@ -0,0 +1,89 @@
+import { requireAdminAuth } from "../modules/admin/auth-helpers.mjs";
+
+//#region src/server/adapters/tanstack.ts
+/**
+* Create a TanStack Router beforeLoad guard for admin authentication.
+*
+* Returns a function that can be used as beforeLoad in route definitions.
+* Throws a redirect Response when authentication fails.
+*
+* @example
+* ```ts
+* import { createFileRoute } from "@tanstack/react-router";
+* import { createTanStackAuthGuard } from "@questpie/admin/server/adapters/tanstack";
+* import { app } from "@/questpie/server/app";
+*
+* export const Route = createFileRoute("/admin")({
+*   beforeLoad: createTanStackAuthGuard({
+*     app,
+*     loginPath: "/admin/login",
+*     requiredRole: "admin",
+*   }),
+*   component: AdminLayout,
+* });
+* ```
+*
+* @example With custom context
+* ```ts
+* export const Route = createFileRoute("/admin")({
+*   beforeLoad: async (ctx) => {
+*     // Run auth guard
+*     await createTanStackAuthGuard({ app })(ctx);
+*
+*     // Add additional context
+*     return { user: ctx.context.user };
+*   },
+* });
+* ```
+*/
+function createTanStackAuthGuard({ app, loginPath = "/admin/login", requiredRole = "admin", redirectParam = "redirect" }) {
+	return async function beforeLoad({ context }) {
+		const request = context.request;
+		if (!request) {
+			console.warn("createTanStackAuthGuard: No request in context. Make sure you're using TanStack Start with SSR enabled.");
+			return;
+		}
+		const redirect = await requireAdminAuth({
+			request,
+			app,
+			loginPath,
+			requiredRole,
+			redirectParam
+		});
+		if (redirect) throw redirect;
+	};
+}
+/**
+* Create a TanStack Router loader that injects the admin session into context.
+*
+* Use this when you need access to the session in your components.
+*
+* @example
+* ```ts
+* import { createTanStackSessionLoader } from "@questpie/admin/server/adapters/tanstack";
+*
+* export const Route = createFileRoute("/admin")({
+*   loader: createTanStackSessionLoader({ app }),
+*   component: AdminLayout,
+* });
+*
+* function AdminLayout() {
+*   const { session } = Route.useLoaderData();
+*   return <div>Hello {session?.user?.name}</div>;
+* }
+* ```
+*/
+function createTanStackSessionLoader({ app }) {
+	return async function loader({ context }) {
+		const request = context.request;
+		if (!request || !app.auth) return { session: null };
+		try {
+			return { session: await app.auth.api.getSession({ headers: request.headers }) ?? null };
+		} catch {
+			return { session: null };
+		}
+	};
+}
+
+//#endregion
+export { createTanStackAuthGuard, createTanStackSessionLoader };

package/dist/server/augmentation/actions.d.mts

@@ -0,0 +1,279 @@
+import { ComponentReference } from "./common.mjs";
+import { ComponentFactory } from "./views.mjs";
+import { I18nText } from "questpie/shared";
+
+//#region src/server/augmentation/actions.d.ts
+
+/**
+ * Action result types returned from action handlers.
+ */
+type ServerActionResult = ServerActionSuccess | ServerActionError | ServerActionRedirect | ServerActionDownload;
+/**
+ * Successful action result
+ */
+interface ServerActionSuccess {
+  type: "success";
+  /** Toast notification to show */
+  toast?: {
+    message: string;
+    title?: string;
+  };
+  /** Side effects to trigger */
+  effects?: ServerActionEffects;
+}
+/**
+ * Error action result
+ */
+interface ServerActionError {
+  type: "error";
+  /** Toast notification to show */
+  toast?: {
+    message: string;
+    title?: string;
+  };
+  /** Field-level errors */
+  errors?: Record<string, string>;
+}
+/**
+ * Redirect action result
+ */
+interface ServerActionRedirect {
+  type: "redirect";
+  /** URL to redirect to */
+  url: string;
+  /** Open in new tab */
+  external?: boolean;
+}
+/**
+ * Download action result
+ */
+interface ServerActionDownload {
+  type: "download";
+  /** File data */
+  file: {
+    name: string;
+    content: string | Uint8Array;
+    mimeType: string;
+  };
+}
+/**
+ * Action side effects
+ */
+interface ServerActionEffects {
+  /** Close the action modal */
+  closeModal?: boolean;
+  /** Invalidate queries (true = all, string[] = specific collections) */
+  invalidate?: boolean | string[];
+  /** Redirect after success */
+  redirect?: string;
+}
+/**
+ * Action handler context
+ */
+interface ServerActionContext<TData = Record<string, unknown>> {
+  /** Form data submitted */
+  data: TData;
+  /** Item ID (for single-item actions) */
+  itemId?: string;
+  /** Item IDs (for bulk actions) */
+  itemIds?: string[];
+  /** Auth instance (Better Auth API) */
+  auth: any;
+  /** Collection CRUD APIs */
+  collections: any;
+  /** Global CRUD APIs */
+  globals: any;
+  /** Database client */
+  db: unknown;
+  /** Current user session */
+  session?: unknown;
+  /** Current locale */
+  locale?: string;
+}
+/**
+ * Action handler function type
+ */
+type ServerActionHandler<TData = Record<string, unknown>> = (ctx: ServerActionContext<TData>) => Promise<ServerActionResult> | ServerActionResult;
+/**
+ * Server-side action form field definition.
+ * Can be either a field definition from the registry or a simple config object.
+ */
+type ServerActionFormField = ServerActionFormFieldConfig | ServerActionFormFieldDefinition;
+/**
+ * Simple field config for action forms (when not using field registry)
+ */
+interface ServerActionFormFieldConfig {
+  /** Field type */
+  type: string;
+  /** Field label */
+  label?: I18nText;
+  /** Field description */
+  description?: I18nText;
+  /** Whether field is required */
+  required?: boolean;
+  /** Default value */
+  default?: unknown;
+  /** Field-specific options */
+  options?: unknown;
+}
+/**
+ * Field definition from field registry (has getMetadata method)
+ */
+interface ServerActionFormFieldDefinition {
+  /** Field definition state */
+  state: {
+    type?: string;
+    config?: {
+      label?: I18nText;
+      description?: I18nText;
+      required?: boolean;
+      [key: string]: unknown;
+    };
+    /** @deprecated Use state.config.label instead */
+    label?: I18nText;
+    /** @deprecated Use state.config.description instead */
+    description?: I18nText;
+    /** @deprecated Use state.config.required instead */
+    required?: boolean;
+  };
+  /** Get metadata for introspection */
+  getMetadata(): {
+    type: string;
+    label?: I18nText;
+    description?: I18nText;
+    required?: boolean;
+  };
+  /** Generate Zod schema for validation */
+  toZodSchema(): unknown;
+}
+/**
+ * Server-side action form configuration
+ */
+interface ServerActionForm {
+  /** Form dialog title */
+  title: I18nText;
+  /** Form dialog description */
+  description?: I18nText;
+  /** Form fields */
+  fields: Record<string, ServerActionFormField>;
+  /** Submit button label */
+  submitLabel?: I18nText;
+  /** Cancel button label */
+  cancelLabel?: I18nText;
+  /** Dialog width */
+  width?: "sm" | "md" | "lg" | "xl";
+}
+/**
+ * Server-side action definition
+ */
+interface ServerActionDefinition<TData = Record<string, unknown>> {
+  /** Unique action ID */
+  id: string;
+  /** Display label */
+  label: I18nText;
+  /** Action description */
+  description?: I18nText;
+  /** Icon reference */
+  icon?: ComponentReference;
+  /** Button variant */
+  variant?: "default" | "destructive" | "outline" | "secondary" | "ghost";
+  /** Where the action appears */
+  scope?: "single" | "bulk" | "header" | "row";
+  /** Form configuration (for actions with input) */
+  form?: ServerActionForm;
+  /** Confirmation dialog */
+  confirmation?: {
+    title: I18nText;
+    description?: I18nText;
+    confirmLabel?: I18nText;
+    cancelLabel?: I18nText;
+    destructive?: boolean;
+  };
+  /** Action handler (runs on server) */
+  handler: ServerActionHandler<TData>;
+}
+/**
+ * Built-in action types
+ */
+type BuiltinActionType = "create" | "save" | "delete" | "deleteMany" | "restore" | "restoreMany" | "duplicate";
+/**
+ * Server-side actions configuration for a collection
+ */
+interface ServerActionsConfig {
+  /** Built-in actions to enable */
+  builtin?: BuiltinActionType[];
+  /** Custom actions */
+  custom?: ServerActionDefinition[];
+}
+/**
+ * Context for actions config function.
+ *
+ * Uses the same field registry as collections, so you can use `f.text()`, `f.select()` etc.
+ * for action form fields.
+ *
+ * @example
+ * ```ts
+ * .actions(({ a, c, f }) => ({
+ *   custom: [
+ *     a.action({
+ *       id: "send-email",
+ *       label: { en: "Send Email" },
+ *       form: {
+ *         title: { en: "Send Email" },
+ *         fields: {
+ *           subject: f.text({ label: { en: "Subject" }, required: true }),
+ *           message: f.textarea({ label: { en: "Message" } }),
+ *           priority: f.select({
+ *             label: { en: "Priority" },
+ *             options: [
+ *               { value: "low", label: { en: "Low" } },
+ *               { value: "high", label: { en: "High" } },
+ *             ],
+ *           }),
+ *         },
+ *       },
+ *       handler: async ({ data }) => {
+ *         // data.subject, data.message, data.priority are typed
+ *         return { type: "success" };
+ *       },
+ *     }),
+ *   ],
+ * }))
+ * ```
+ */
+interface ActionsConfigContext<_TFields extends Record<string, unknown> = Record<string, unknown>, TComponents extends Record<string, any> | string = string> {
+  /** Action builders */
+  a: {
+    /** Enable create action */
+    create: () => BuiltinActionType;
+    /** Enable save action */
+    save: () => BuiltinActionType;
+    /** Enable delete action */
+    delete: () => BuiltinActionType;
+    /** Enable delete many action */
+    deleteMany: () => BuiltinActionType;
+    /** Enable restore action */
+    restore: () => BuiltinActionType;
+    /** Enable restore many action */
+    restoreMany: () => BuiltinActionType;
+    /** Enable duplicate action */
+    duplicate: () => BuiltinActionType;
+    /** Define a custom action */
+    action: <TData = Record<string, unknown>>(def: Omit<ServerActionDefinition<TData>, "scope"> & {
+      scope?: "single" | "row";
+    }) => ServerActionDefinition<TData>;
+    /** Define a bulk action */
+    bulkAction: <TData = Record<string, unknown>>(def: Omit<ServerActionDefinition<TData>, "scope">) => ServerActionDefinition<TData>;
+    /** Define a header action */
+    headerAction: <TData = Record<string, unknown>>(def: Omit<ServerActionDefinition<TData>, "scope">) => ServerActionDefinition<TData>;
+  };
+  /** Component helpers (from registered component registry) */
+  c: ComponentFactory<TComponents>;
+  /**
+   * Field proxy from field registry.
+   * Use the same field types as in collections: f.text(), f.select(), etc.
+   */
+  f: Record<string, (config?: Record<string, unknown>) => ServerActionFormField>;
+}
+//#endregion
+export { ActionsConfigContext, BuiltinActionType, ServerActionContext, ServerActionDefinition, ServerActionDownload, ServerActionEffects, ServerActionError, ServerActionForm, ServerActionFormField, ServerActionFormFieldConfig, ServerActionFormFieldDefinition, ServerActionHandler, ServerActionRedirect, ServerActionResult, ServerActionSuccess, ServerActionsConfig };

package/dist/server/augmentation/common.d.mts

@@ -0,0 +1,76 @@
+//#region src/server/augmentation/common.d.ts
+/**
+ * Common Admin Types
+ *
+ * Base types used across admin augmentation: component references,
+ * component type registry, locale configuration, and action references.
+ */
+/**
+ * Admin locale configuration for UI language support.
+ * Separate from content locales - UI can have different languages than content.
+ *
+ * @example
+ * ```ts
+ * .adminLocale({
+ *   locales: ["en", "sk"],  // UI available in 2 languages
+ *   defaultLocale: "en",
+ * })
+ * ```
+ */
+interface AdminLocaleConfig {
+  /** Available UI locales for admin interface */
+  locales: string[];
+  /** Default UI locale */
+  defaultLocale: string;
+}
+/**
+ * Reference to a server-registered component.
+ * Used for icons, badges, and other UI elements defined on server.
+ *
+ * @example
+ * ```ts
+ * { type: "icon", props: { name: "ph:users" } }
+ * ```
+ */
+interface ComponentReference<TType extends string = string, TProps extends Record<string, unknown> = Record<string, unknown>> {
+  type: TType;
+  props: TProps;
+}
+/**
+ * Open augmentation point for component type names.
+ * Codegen augments this interface from module-contributed component maps,
+ * so user code gets autocomplete for valid component type names.
+ *
+ * When no modules are loaded (empty registry), `ComponentType` falls back to `string`.
+ *
+ * @example
+ * ```ts
+ * // Generated by codegen:
+ * declare module "@questpie/admin/server" {
+ *   interface ComponentTypeRegistry extends Record<_ComponentsNames_Strict, {}> {}
+ * }
+ *
+ * // Third-party plugin can extend:
+ * declare module "@questpie/admin/server" {
+ *   interface ComponentTypeRegistry {
+ *     avatar: {};
+ *     statusBadge: {};
+ *   }
+ * }
+ * ```
+ */
+interface ComponentTypeRegistry {}
+/**
+ * Union of all registered component type names.
+ * Falls back to `string` when no types are registered (empty ComponentTypeRegistry).
+ */
+type ComponentType = [keyof ComponentTypeRegistry] extends [never] ? string : keyof ComponentTypeRegistry;
+/**
+ * Reference to an action
+ */
+type ActionReference = string | {
+  type: string;
+  config?: unknown;
+};
+//#endregion
+export { ActionReference, AdminLocaleConfig, ComponentReference, ComponentType, ComponentTypeRegistry };