@delmaredigital/payload-puck 0.1.0

package/dist/api/index.d.ts

@@ -0,0 +1,460 @@
+import * as payload from 'payload';
+import { NextRequest } from 'next/server';
+import { Data } from '@measured/puck';
+
+/**
+ * Authenticated user from the auth system
+ */
+interface AuthenticatedUser {
+    id: string;
+    [key: string]: unknown;
+}
+/**
+ * Result of an authentication check
+ */
+interface AuthResult {
+    authenticated: boolean;
+    user?: AuthenticatedUser;
+    error?: string;
+}
+/**
+ * Result of a permission check
+ */
+interface PermissionResult {
+    allowed: boolean;
+    error?: string;
+}
+/**
+ * Authentication and authorization hooks for Puck API routes
+ *
+ * These hooks allow you to integrate with any authentication system
+ * (Better Auth, NextAuth, Payload auth, custom JWT, etc.)
+ *
+ * @example
+ * ```typescript
+ * // Example with Better Auth
+ * const authHooks: PuckApiAuthHooks = {
+ *   authenticate: async (request) => {
+ *     const session = await auth.api.getSession({ headers: await headers() })
+ *     if (!session?.user) return { authenticated: false }
+ *     return { authenticated: true, user: session.user }
+ *   },
+ *   canEdit: async (user, pageId) => {
+ *     return { allowed: hasRole(user, 'editor') }
+ *   },
+ * }
+ * ```
+ */
+interface PuckApiAuthHooks {
+    /**
+     * Authenticate the incoming request
+     * Should return the authenticated user or authentication failure
+     */
+    authenticate: (request: NextRequest) => Promise<AuthResult>;
+    /**
+     * Check if user can list pages
+     * @default Always allowed for authenticated users
+     */
+    canList?: (user: AuthenticatedUser) => Promise<PermissionResult> | PermissionResult;
+    /**
+     * Check if user can view a specific page
+     * @default Always allowed for authenticated users
+     */
+    canView?: (user: AuthenticatedUser, pageId: string) => Promise<PermissionResult> | PermissionResult;
+    /**
+     * Check if user can create new pages
+     * @default Always allowed for authenticated users
+     */
+    canCreate?: (user: AuthenticatedUser) => Promise<PermissionResult> | PermissionResult;
+    /**
+     * Check if user can edit a specific page
+     * @default Always allowed for authenticated users
+     */
+    canEdit?: (user: AuthenticatedUser, pageId: string) => Promise<PermissionResult> | PermissionResult;
+    /**
+     * Check if user can publish a specific page (change status to published)
+     * @default Same as canEdit
+     */
+    canPublish?: (user: AuthenticatedUser, pageId: string) => Promise<PermissionResult> | PermissionResult;
+    /**
+     * Check if user can delete a specific page
+     * @default Always allowed for authenticated users
+     */
+    canDelete?: (user: AuthenticatedUser, pageId: string) => Promise<PermissionResult> | PermissionResult;
+}
+/**
+ * Mapping configuration for syncing Puck root.props to Payload fields
+ *
+ * @example
+ * ```typescript
+ * // Simple mapping
+ * { from: 'pageLayout', to: 'pageLayout' }
+ *
+ * // Nested field mapping (uses official @payloadcms/plugin-seo convention)
+ * { from: 'title', to: 'meta.title' }
+ *
+ * // With transformation
+ * {
+ *   from: 'publishDate',
+ *   to: 'publishedAt',
+ *   transform: (value) => value ? new Date(value as string).toISOString() : null
+ * }
+ * ```
+ */
+interface RootPropsMapping {
+    /**
+     * Property name in Puck root.props
+     */
+    from: string;
+    /**
+     * Field path in Payload document (supports dot notation for nested fields)
+     */
+    to: string;
+    /**
+     * Optional transformation function
+     */
+    transform?: (value: unknown) => unknown;
+}
+/**
+ * Error context passed to onError callback
+ */
+interface ErrorContext {
+    operation: string;
+    request: NextRequest;
+    pageId?: string;
+}
+/**
+ * Configuration for Puck API routes
+ *
+ * @example
+ * ```typescript
+ * const config: PuckApiRoutesConfig = {
+ *   collection: 'pages',
+ *   auth: {
+ *     authenticate: async (request) => {
+ *       // Your auth logic here
+ *     },
+ *     canPublish: async (user) => {
+ *       return { allowed: user.role === 'admin' }
+ *     },
+ *   },
+ *   rootPropsMapping: [
+ *     { from: 'title', to: 'meta.title' },
+ *     { from: 'description', to: 'meta.description' },
+ *   ],
+ *   enableDrafts: true,
+ * }
+ * ```
+ */
+interface PuckApiRoutesConfig {
+    /**
+     * Payload collection slug for pages
+     * @default 'pages'
+     */
+    collection?: string;
+    /**
+     * Payload configuration - import from @payload-config
+     * Required for Turbopack/Next.js 16+ compatibility
+     *
+     * @example
+     * ```typescript
+     * import config from '@payload-config'
+     *
+     * createPuckApiRoutesWithId({
+     *   payloadConfig: config,
+     *   // ...
+     * })
+     * ```
+     */
+    payloadConfig: Promise<payload.SanitizedConfig>;
+    /**
+     * Authentication and authorization hooks
+     */
+    auth: PuckApiAuthHooks;
+    /**
+     * Custom mappings from Puck root.props to Payload fields
+     * These are merged with the default mappings
+     */
+    rootPropsMapping?: RootPropsMapping[];
+    /**
+     * Default Puck data for new pages
+     */
+    defaultPuckData?: Data;
+    /**
+     * Enable draft mode for page creation/updates
+     * @default true
+     */
+    enableDrafts?: boolean;
+    /**
+     * Custom error handler for logging/monitoring
+     */
+    onError?: (error: unknown, context: ErrorContext) => void;
+}
+/**
+ * Context passed to Next.js App Router route handlers
+ */
+interface RouteHandlerContext {
+    params: Promise<Record<string, string>>;
+}
+/**
+ * Context for route handlers that require an id parameter
+ */
+interface RouteHandlerWithIdContext {
+    params: Promise<{
+        id: string;
+    }>;
+}
+/**
+ * Next.js App Router route handler type
+ */
+type RouteHandler = (request: NextRequest, context: RouteHandlerContext) => Promise<Response>;
+/**
+ * Next.js App Router route handler type for [id] routes
+ */
+type RouteHandlerWithId = (request: NextRequest, context: RouteHandlerWithIdContext) => Promise<Response>;
+/**
+ * Route handlers returned by createPuckApiRoutes
+ */
+interface PuckApiRouteHandlers {
+    GET: RouteHandler;
+    POST: RouteHandler;
+}
+/**
+ * Route handlers returned by createPuckApiRoutesWithId
+ */
+interface PuckApiRouteWithIdHandlers {
+    GET: RouteHandlerWithId;
+    PATCH: RouteHandlerWithId;
+    DELETE: RouteHandlerWithId;
+}
+/**
+ * Request body for creating a new page
+ */
+interface CreatePageBody {
+    title: string;
+    slug: string;
+    puckData?: Data;
+    status?: 'draft' | 'published';
+}
+/**
+ * Request body for updating a page
+ */
+interface UpdatePageBody {
+    puckData?: Data;
+    title?: string;
+    slug?: string;
+    status?: 'draft' | 'published';
+    /**
+     * When true, save as draft without publishing.
+     * Used by Payload's versions.drafts system.
+     */
+    draft?: boolean;
+}
+/**
+ * Standard API response wrapper
+ */
+interface ApiResponse<T = unknown> {
+    doc?: T;
+    docs?: T[];
+    error?: string;
+    success?: boolean;
+    totalDocs?: number;
+    totalPages?: number;
+    page?: number;
+    limit?: number;
+    hasPrevPage?: boolean;
+    hasNextPage?: boolean;
+}
+/**
+ * A version entry from Payload's versions system
+ */
+interface PageVersion {
+    id: string;
+    parent: string;
+    version: {
+        title?: string;
+        slug?: string;
+        puckData?: Data;
+        _status?: 'draft' | 'published';
+        updatedAt: string;
+        createdAt: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+    autosave?: boolean;
+    latest?: boolean;
+}
+/**
+ * Route handlers returned by createPuckApiRoutesVersions
+ */
+interface PuckApiVersionsRouteHandlers {
+    GET: RouteHandlerWithId;
+    POST: RouteHandlerWithId;
+}
+
+/**
+ * Create API route handlers for /api/puck/pages
+ *
+ * Provides GET (list pages) and POST (create page) handlers
+ * with configurable authentication and authorization.
+ *
+ * @example
+ * ```typescript
+ * // src/app/api/puck/pages/route.ts
+ * import { createPuckApiRoutes } from '@delmaredigital/payload-puck/api'
+ * import config from '@payload-config'
+ *
+ * export const { GET, POST } = createPuckApiRoutes({
+ *   collection: 'pages',
+ *   payloadConfig: config,
+ *   auth: {
+ *     authenticate: async (request) => {
+ *       const session = await getSession(request)
+ *       if (!session?.user) return { authenticated: false }
+ *       return { authenticated: true, user: session.user }
+ *     },
+ *     canCreate: async (user) => {
+ *       return { allowed: user.role === 'admin' || user.role === 'editor' }
+ *     },
+ *   },
+ * })
+ * ```
+ */
+declare function createPuckApiRoutes(routeConfig: PuckApiRoutesConfig): PuckApiRouteHandlers;
+
+/**
+ * Create API route handlers for /api/puck/pages/[id]
+ *
+ * Provides GET (fetch page), PATCH (update page), and DELETE (delete page)
+ * handlers with configurable authentication and authorization.
+ *
+ * @example
+ * ```typescript
+ * // src/app/api/puck/pages/[id]/route.ts
+ * import { createPuckApiRoutesWithId } from '@delmaredigital/payload-puck/api'
+ * import config from '@payload-config'
+ *
+ * export const { GET, PATCH, DELETE } = createPuckApiRoutesWithId({
+ *   collection: 'pages',
+ *   payloadConfig: config,
+ *   auth: {
+ *     authenticate: async (request) => {
+ *       const session = await getSession(request)
+ *       if (!session?.user) return { authenticated: false }
+ *       return { authenticated: true, user: session.user }
+ *     },
+ *     canPublish: async (user) => {
+ *       return { allowed: user.role === 'admin' }
+ *     },
+ *   },
+ *   rootPropsMapping: [
+ *     { from: 'customField', to: 'customPayloadField' },
+ *   ],
+ * })
+ * ```
+ */
+declare function createPuckApiRoutesWithId(routeConfig: PuckApiRoutesConfig): PuckApiRouteWithIdHandlers;
+
+/**
+ * Create API route handlers for /api/puck/pages/[id]/versions
+ *
+ * Provides GET (list versions) and POST (restore version) handlers
+ * for managing page version history.
+ *
+ * @example
+ * ```typescript
+ * // src/app/api/puck/pages/[id]/versions/route.ts
+ * import { createPuckApiRoutesVersions } from '@delmaredigital/payload-puck/api'
+ * import config from '@payload-config'
+ *
+ * export const { GET, POST } = createPuckApiRoutesVersions({
+ *   collection: 'pages',
+ *   payloadConfig: config,
+ *   auth: {
+ *     authenticate: async (request) => {
+ *       const session = await getSession(request)
+ *       if (!session?.user) return { authenticated: false }
+ *       return { authenticated: true, user: session.user }
+ *     },
+ *   },
+ * })
+ * ```
+ */
+declare function createPuckApiRoutesVersions(routeConfig: PuckApiRoutesConfig): PuckApiVersionsRouteHandlers;
+
+/**
+ * Default mappings from Puck root.props to Payload fields
+ *
+ * These mappings sync common page properties from Puck's visual editor
+ * to the corresponding Payload collection fields.
+ *
+ * SEO fields use the official @payloadcms/plugin-seo convention: meta.title, meta.description
+ */
+declare const DEFAULT_ROOT_PROPS_MAPPINGS: RootPropsMapping[];
+/**
+ * Set a nested value in an object using dot notation path
+ *
+ * @example
+ * ```typescript
+ * const obj = {}
+ * setNestedValue(obj, 'meta.title', 'My Title')
+ * // Result: { meta: { title: 'My Title' } }
+ * ```
+ */
+declare function setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * Get a nested value from an object using dot notation path
+ *
+ * @example
+ * ```typescript
+ * const obj = { meta: { title: 'My Title' } }
+ * getNestedValue(obj, 'meta.title') // 'My Title'
+ * ```
+ */
+declare function getNestedValue(obj: Record<string, unknown>, path: string): unknown;
+/**
+ * Merge mappings, with custom mappings taking precedence over defaults
+ *
+ * @param customMappings - Custom mappings to merge with defaults
+ * @returns Merged array of mappings with duplicates resolved (custom wins)
+ */
+declare function mergeMappings(customMappings?: RootPropsMapping[]): RootPropsMapping[];
+/**
+ * Map Puck root.props to Payload field update data
+ *
+ * Takes the root.props from Puck data and maps them to the appropriate
+ * Payload fields based on the provided mappings.
+ *
+ * @param rootProps - The root.props object from Puck data
+ * @param customMappings - Optional custom mappings to merge with defaults
+ * @returns Object ready to be spread into Payload update data
+ *
+ * @example
+ * ```typescript
+ * const rootProps = {
+ *   title: 'My Page',
+ *   metaTitle: 'My Page | Site Name',
+ *   metaDescription: 'Description here',
+ * }
+ *
+ * const updateData = mapRootPropsToPayloadFields(rootProps)
+ * // Result: {
+ * //   title: 'My Page',
+ * //   meta: {
+ * //     title: 'My Page | Site Name',
+ * //     description: 'Description here',
+ * //   },
+ * // }
+ * ```
+ */
+declare function mapRootPropsToPayloadFields(rootProps: Record<string, unknown>, customMappings?: RootPropsMapping[]): Record<string, unknown>;
+/**
+ * Deep merge objects, with source values overwriting target values
+ *
+ * @param target - The target object to merge into
+ * @param source - The source object to merge from
+ * @returns The merged object (target is modified in place)
+ */
+declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+
+export { type ApiResponse, type AuthResult, type AuthenticatedUser, type CreatePageBody, DEFAULT_ROOT_PROPS_MAPPINGS, type ErrorContext, type PageVersion, type PermissionResult, type PuckApiAuthHooks, type PuckApiRouteHandlers, type PuckApiRouteWithIdHandlers, type PuckApiRoutesConfig, type PuckApiVersionsRouteHandlers, type RootPropsMapping, type RouteHandler, type RouteHandlerContext, type RouteHandlerWithId, type RouteHandlerWithIdContext, type UpdatePageBody, createPuckApiRoutes, createPuckApiRoutesVersions, createPuckApiRoutesWithId, deepMerge, getNestedValue, mapRootPropsToPayloadFields, mergeMappings, setNestedValue };