@payload-onpage/plugin 0.2.0 → 0.3.0

package/src/endpoints.ts

@@ -1,91 +1,97 @@
 /**
  * The plugin's endpoints, under `${api}${routePrefix}` (default /api/onpage):
  *
- *   GET  /schema/:kind/:slug   editable field schema for the signed-in editor
+ *   GET  /schema/:kind/:slug   editable field schema for the signed-in editor (JSON)
  *   POST /enter                start editing or previewing a document's page
  *   POST /mode                 switch the current page between editing and previewing
  *   POST /exit                 leave edit/preview mode
  *   POST /preview-link         create a sealed, expiring read-only link (JSON)
  *   GET  /preview?token=       open a preview link
  *
- * State-changing endpoints are same-origin POSTs (CSRF-safe). Every
- * authorization decision goes through ./access (Payload's own access rules).
+ * JSON endpoints throw Payload's errors, so responses, logging, CORS and
+ * translations match Payload's own. The form/new-tab endpoints answer in plain
+ * text or redirect. State-changing endpoints are same-origin POSTs (CSRF-safe),
+ * and every authorization decision goes through ./access (Payload's access rules).
  */
 import {
+  isOnPageMode,
   parseRefKey,
   pathnameOf,
   refKey,
+  ROUTES,
   safePath,
   samePath,
   SEAL_PURPOSE,
   seal,
+  type DocRef,
   type DocumentSchema,
-  type OnPageMode,
+  type PreviewGrant,
   type SessionAdapter,
 } from '@payload-onpage/core'
-import type { CollectionConfig, Endpoint, GlobalConfig, PayloadRequest } from 'payload'
-import { hasAutosaveEnabled, hasDraftsEnabled, getAutosaveInterval } from 'payload/shared'
+import {
+  addDataAndFileToRequest,
+  APIError,
+  Forbidden,
+  NotFound,
+  type Endpoint,
+  type PayloadRequest,
+  type TypedLocale,
+} from 'payload'
+import { getAutosaveInterval, hasAutosaveEnabled, hasDraftsEnabled, toWords } from 'payload/shared'
 import { canEditDocument, canUseOnPage, documentPermissions } from './access.ts'
 import {
+  apiURL,
+  entityConfig,
   isSecure,
   json,
-  originOf,
-  queryOf,
   readRef,
   redirectTo,
   rejectCrossSite,
   text,
+  withIdType,
 } from './http.ts'
 import type { Entry, OnPageOptions } from './options.ts'
 import { resolvePath } from './paths.ts'
-import { relationTargets, serializeFields } from './schema.ts'
+import { label, relationTargets, serializeFields } from './schema.ts'
 import { createPreviewToken, verifyPreviewToken } from './tokens.ts'
 
 export interface EndpointContext {
-  options: OnPageOptions
-  prefix: string
-  apiRoute: string
-  entry: (kind: string, slug: string) => Entry | undefined
+  options: OnPageOptions & { session: SessionAdapter }
+  prefix: `/${string}`
+  entry: (kind: DocRef['kind'], slug: string) => Entry | undefined
 }
 
 const DAY = 24 * 3600
 
-export const secretOf = (req: PayloadRequest, options: OnPageOptions): string =>
+const secretOf = (req: PayloadRequest, options: OnPageOptions): string =>
   options.secret ?? req.payload.config.secret
 
 /** Name of the auth cookie an editor's mode is bound to. */
 const authCookieOf = (req: PayloadRequest, options: OnPageOptions): string =>
   options.authCookie ?? `${req.payload.config.cookiePrefix || 'payload'}-token`
 
-function requireSession(options: OnPageOptions): SessionAdapter {
-  if (!options.session)
-    throw new Error(
-      'payload-onpage: pass `session` (e.g. nextSession()) to use the enter, mode, exit and preview endpoints',
-    )
-  return options.session
-}
+/** A locale value from a body, if it's one Payload knows. */
+const knownLocale = (req: PayloadRequest, value: unknown): TypedLocale | undefined =>
+  typeof value === 'string' && req.payload.config.localization
+    ? req.payload.config.localization.localeCodes.find((c) => c === value)
+    : undefined
 
 export function createEndpoints(ctx: EndpointContext): Endpoint[] {
-  const { options, prefix, apiRoute } = ctx
+  const { options, prefix } = ctx
+  const { session } = options
 
   const schema: Endpoint = {
-    path: `${prefix}/schema/:kind/:slug`,
+    path: `${prefix}${ROUTES.schema}/:kind/:slug`,
     method: 'get',
     handler: async (req) => {
       const kind = req.routeParams?.kind === 'global' ? 'global' : 'collection'
       const slug = typeof req.routeParams?.slug === 'string' ? req.routeParams.slug : ''
       const entry = ctx.entry(kind, slug)
-      const cfg: CollectionConfig | GlobalConfig | undefined =
-        kind === 'global'
-          ? req.payload.globals.config.find((g) => g.slug === slug)
-          : req.payload.collections[slug]?.config
-      if (!entry || !cfg) return json({ error: 'Not enabled for on-page editing' }, 404)
-      if (!(await canUseOnPage(req, options))) return json({ error: 'Forbidden' }, 403)
+      const cfg = entityConfig(req, kind, slug)
+      if (!entry || !cfg) throw new NotFound(req.t)
+      if (!(await canUseOnPage(req, options))) throw new Forbidden(req.t)
 
-      const perms = await documentPermissions(
-        req,
-        kind === 'global' ? { kind, slug } : { kind, slug },
-      )
+      const perms = await documentPermissions(req, { kind, slug })
       const pending: Promise<void>[] = []
       const all = serializeFields(cfg.fields, {
         i18n: req.i18n,
@@ -94,47 +100,43 @@ export function createEndpoints(ctx: EndpointContext): Endpoint[] {
         defaults: { req, pending },
       })
       await Promise.all(pending)
-      const fields = entry.options.fields
-        ? all.filter((f) => entry.options.fields!.includes(f.name))
-        : all
+      const only = entry.options.fields
+      const fields = only ? all.filter((f) => only.includes(f.name)) : all
 
+      const i18n = { i18n: req.i18n }
       const relations: NonNullable<DocumentSchema['relations']> = {}
       for (const target of relationTargets(fields)) {
-        const c = req.payload.collections[target]?.config
-        if (!c) continue
-        relations[target] = {
-          titleField: c.admin?.useAsTitle ?? 'id',
-          label: typeof c.labels?.singular === 'string' ? c.labels.singular : target,
-        }
+        const c = entityConfig(req, 'collection', target)
+        if (c)
+          relations[target] = {
+            titleField: c.admin?.useAsTitle ?? 'id',
+            label: label(c.labels?.singular, toWords(target), i18n),
+          }
       }
+      const labels =
+        'labels' in cfg
+          ? {
+              singular: label(cfg.labels?.singular, toWords(slug), i18n),
+              plural: label(cfg.labels?.plural, toWords(slug), i18n),
+            }
+          : {
+              singular: label(cfg.label, toWords(slug), i18n),
+              plural: label(cfg.label, toWords(slug), i18n),
+            }
+      const useAsTitle = 'labels' in cfg ? cfg.admin?.useAsTitle : undefined
       const localization = req.payload.config.localization
-      const labelOf = (v: unknown) => (typeof v === 'string' ? v : slug)
       const body: DocumentSchema = {
         kind,
         slug,
-        labels:
-          kind === 'global'
-            ? {
-                singular: labelOf((cfg as GlobalConfig).label),
-                plural: labelOf((cfg as GlobalConfig).label),
-              }
-            : {
-                singular: labelOf((cfg as CollectionConfig).labels?.singular),
-                plural: labelOf((cfg as CollectionConfig).labels?.plural),
-              },
+        labels,
         editable: fields.map((f) => f.name),
         fields,
         drafts: hasDraftsEnabled(cfg),
         ...(hasAutosaveEnabled(cfg) ? { autosaveInterval: getAutosaveInterval(cfg) } : {}),
-        ...(kind === 'collection' && (cfg as CollectionConfig).admin?.useAsTitle
-          ? { useAsTitle: (cfg as CollectionConfig).admin!.useAsTitle }
-          : {}),
+        ...(useAsTitle ? { useAsTitle } : {}),
         ...(Object.keys(relations).length ? { relations } : {}),
         ...(localization
-          ? {
-              defaultLocale: localization.defaultLocale,
-              locales: localization.locales.map((l) => (typeof l === 'string' ? l : l.code)),
-            }
+          ? { defaultLocale: localization.defaultLocale, locales: localization.localeCodes }
           : {}),
       }
       return json(body)
@@ -142,23 +144,23 @@ export function createEndpoints(ctx: EndpointContext): Endpoint[] {
   }
 
   const enter: Endpoint = {
-    path: `${prefix}/enter`,
+    path: `${prefix}${ROUTES.enter}`,
     method: 'post',
     handler: async (req) => {
       const refused = rejectCrossSite(req)
       if (refused) return refused
-      const q = queryOf(req)
-      const ref = readRef({ kind: q.get('kind'), slug: q.get('slug'), id: q.get('id') })
+      const q = req.searchParams
+      const ref = readRef(req, { kind: q.get('kind'), slug: q.get('slug'), id: q.get('id') })
       const entry = ref && ctx.entry(ref.kind, ref.slug)
       if (!ref || !entry) return text('Unknown document', 400)
       if (!req.user) return text('Sign in to the admin first', 401)
       if (!(await canEditDocument(req, ref, options)))
         return text('You cannot edit this document', 403)
-      const locale = q.get('locale') ?? undefined
+      const locale = req.locale && req.locale !== 'all' ? req.locale : undefined
       const path = safePath(q.get('path')) ?? (await resolvePath(req, ref, entry, locale))
       if (!path) return text('This document has no page to open', 404)
-      const mode: OnPageMode = q.get('mode') === 'view' ? 'view' : 'edit'
-      await requireSession(options).enable(mode, {
+      const mode = q.get('mode')
+      await session.enable(isOnPageMode(mode) ? mode : 'edit', {
         secure: isSecure(req),
         bindTo: authCookieOf(req, options),
       })
@@ -167,14 +169,16 @@ export function createEndpoints(ctx: EndpointContext): Endpoint[] {
   }
 
   const mode: Endpoint = {
-    path: `${prefix}/mode`,
+    path: `${prefix}${ROUTES.mode}`,
     method: 'post',
     handler: async (req) => {
       const refused = rejectCrossSite(req)
       if (refused) return refused
-      if (!(await canUseOnPage(req, options))) return text('Sign in as an editor first', 401)
-      const q = queryOf(req)
-      await requireSession(options).enable(q.get('mode') === 'view' ? 'view' : 'edit', {
+      if (!req.user) return text('Sign in to the admin first', 401)
+      if (!(await canUseOnPage(req, options))) return text('You cannot use on-page editing', 403)
+      const q = req.searchParams
+      const next = q.get('mode')
+      await session.enable(isOnPageMode(next) ? next : 'edit', {
         secure: isSecure(req),
         bindTo: authCookieOf(req, options),
       })
@@ -183,41 +187,41 @@ export function createEndpoints(ctx: EndpointContext): Endpoint[] {
   }
 
   const exit: Endpoint = {
-    path: `${prefix}/exit`,
+    path: `${prefix}${ROUTES.exit}`,
     method: 'post',
     handler: async (req) => {
       const refused = rejectCrossSite(req)
       if (refused) return refused
-      await requireSession(options).disable()
-      return redirectTo(req, queryOf(req).get('path'))
+      await session.disable()
+      return redirectTo(req, req.searchParams.get('path'))
     },
   }
 
   const previewLink: Endpoint = {
-    path: `${prefix}/preview-link`,
+    path: `${prefix}${ROUTES.previewLink}`,
     method: 'post',
     handler: async (req) => {
       const refused = rejectCrossSite(req)
       if (refused) return refused
       if (!req.headers.get('content-type')?.includes('application/json'))
-        return json({ error: 'Expected JSON' }, 415)
-      const body = ((await req.json?.().catch(() => null)) ?? {}) as Record<string, unknown>
-      const ref = readRef(body)
+        throw new APIError('Expected a JSON body', 415)
+      await addDataAndFileToRequest(req) // parses JSON, or throws a 400
+      const body: Record<string, unknown> = req.data ?? {}
+      const ref = readRef(req, body)
       const entry = ref && ctx.entry(ref.kind, ref.slug)
-      if (!ref || !entry) return json({ error: 'Unknown document' }, 400)
-      if (!(await canEditDocument(req, ref, options))) return json({ error: 'Forbidden' }, 403)
-      const locale = typeof body.locale === 'string' ? body.locale : undefined
+      if (!ref || !entry) throw new APIError('Unknown document', 400)
+      if (!(await canEditDocument(req, ref, options))) throw new Forbidden(req.t)
+      const locale = knownLocale(req, body.locale)
       // The path is always derived on the server: a link opens this document's page and nothing else.
       const path = await resolvePath(req, ref, entry, locale)
-      if (!path) return json({ error: 'This document has no page' }, 404)
-      const ttl = options.previewLinkTTL ?? DAY
+      if (!path) throw new APIError('This document has no page', 404)
       const { token, payload } = await createPreviewToken(
-        { ref: refKey(ref), path, locale },
+        { ref: refKey(ref), path, ...(locale ? { locale } : {}) },
         secretOf(req, options),
-        ttl,
+        options.previewLinkTTL ?? DAY,
       )
       return json({
-        url: `${originOf(req)}${apiRoute}${prefix}/preview?token=${encodeURIComponent(token)}`,
+        url: `${apiURL(req, `${prefix}${ROUTES.preview}`)}?token=${encodeURIComponent(token)}`,
         expiresAt: new Date(payload.exp * 1000).toISOString(),
         id: payload.jti,
       })
@@ -225,17 +229,18 @@ export function createEndpoints(ctx: EndpointContext): Endpoint[] {
   }
 
   const preview: Endpoint = {
-    path: `${prefix}/preview`,
+    path: `${prefix}${ROUTES.preview}`,
     method: 'get',
     handler: async (req) => {
       const invalid = () => text('This preview link is invalid or has expired.', 403)
       const secret = secretOf(req, options)
-      const token = await verifyPreviewToken(queryOf(req).get('token') ?? '', secret)
-      const ref = token && parseRefKey(token.ref)
+      const token = await verifyPreviewToken(req.searchParams.get('token') ?? '', secret)
+      const parsed = token && parseRefKey(token.ref)
+      const ref = parsed && withIdType(req, parsed)
       const entry = ref && ctx.entry(ref.kind, ref.slug)
       if (!token || !ref || !entry) return invalid()
       // Still the document's page? (It may have been deleted, or its slug changed.)
-      const current = await resolvePath(req, ref, entry, token.locale)
+      const current = await resolvePath(req, ref, entry, knownLocale(req, token.locale))
       if (!current || !samePath(current, token.path)) return invalid()
       if (
         options.validatePreviewLink &&
@@ -249,17 +254,19 @@ export function createEndpoints(ctx: EndpointContext): Endpoint[] {
       ) {
         return invalid()
       }
-      const expiresAt = new Date(token.exp * 1000)
-      await requireSession(options).enableLink({
+      await session.enableLink({
         secure: isSecure(req),
         path: pathnameOf(token.path),
-        expiresAt,
-        seal: (draftSecret) =>
-          seal(
-            { path: pathnameOf(token.path), ref: token.ref, exp: token.exp, draft: draftSecret },
-            secret,
-            SEAL_PURPOSE.previewCookie,
-          ),
+        expiresAt: new Date(token.exp * 1000),
+        seal: (draftSecret) => {
+          const grant: PreviewGrant = {
+            path: pathnameOf(token.path),
+            ref: token.ref,
+            exp: token.exp,
+            draft: draftSecret,
+          }
+          return seal(grant, secret, SEAL_PURPOSE.previewCookie)
+        },
       })
       return redirectTo(req, token.path, 307)
     },

package/src/hooks.ts

@@ -5,23 +5,32 @@
  *  - beforeChange: stale-write guard (409) when the editor sends the version it last saw
  */
 import {
+  CONTEXT_KEY,
   encodeDocument,
   HEADER,
   refKey,
   stegaCleanDeep,
+  type DocRef,
   type EncodeFilter,
   type SchemaField,
 } from '@payload-onpage/core'
-import { APIError, type PayloadRequest } from 'payload'
+import { APIError, type PayloadRequest, type RequestContext } from 'payload'
+
+declare module 'payload' {
+  interface RequestContext {
+    /** Set by `onpageContext()`: this read should carry auto-mapping markers. */
+    [CONTEXT_KEY]?: boolean
+  }
+}
 
 /** True when a read asked for auto-mapping markers (see `onpageContext()`). */
-export const wantsMarkers = (context: unknown): boolean =>
-  !!(context && typeof context === 'object' && (context as Record<string, unknown>).onpage === true)
+export const wantsMarkers = (context: RequestContext | undefined): boolean =>
+  context?.[CONTEXT_KEY] === true
 
 export const stripMarkers = ({ data }: { data?: unknown }) => (data ? stegaCleanDeep(data) : data)
 
 export function encodeOnRead(opts: {
-  kind: 'collection' | 'global'
+  kind: DocRef['kind']
   slug: string
   fields: () => SchemaField[]
   only?: string[]
@@ -34,7 +43,7 @@ export function encodeOnRead(opts: {
   }: {
     doc: Record<string, unknown>
     req: PayloadRequest
-    context: unknown
+    context: RequestContext
   }) => {
     if (!wantsMarkers(context) || req.locale === 'all' || !doc) return doc
     const ref =

package/src/http.ts

@@ -1,25 +1,24 @@
 /** Request helpers shared by the endpoints. */
-import { parseRefKey, safePath, type DocRef } from '@payload-onpage/core'
-import type { PayloadRequest } from 'payload'
+import { safePath, type DocRef } from '@payload-onpage/core'
+import type { PayloadRequest, SanitizedCollectionConfig, SanitizedGlobalConfig } from 'payload'
+import { formatAdminURL, stripTrailingSlash } from 'payload/shared'
 
 /** The site origin: `serverURL` when configured, else the request's own origin. */
-export function originOf(req: PayloadRequest): string {
+export const originOf = (req: PayloadRequest): string => {
   const configured = req.payload.config.serverURL
-  if (configured) return configured.replace(/\/$/, '')
-  try {
-    return new URL(req.url ?? '').origin
-  } catch {
-    const host = req.headers.get('x-forwarded-host') ?? req.headers.get('host') ?? 'localhost'
-    const proto = req.headers.get('x-forwarded-proto') ?? 'http'
-    return `${proto}://${host}`
-  }
+  return configured ? stripTrailingSlash(configured) : req.origin
 }
 
 export const isSecure = (req: PayloadRequest): boolean => originOf(req).startsWith('https:')
 
-export const queryOf = (req: PayloadRequest): URLSearchParams =>
-  new URL(req.url ?? '/', 'http://localhost').searchParams
+/**
+ * Absolute URL of one of our API routes (e.g. `/onpage/preview`), built the way
+ * Payload builds its own: honours `routes.api`, Next's basePath and trailing slashes.
+ */
+export const apiURL = (req: PayloadRequest, path: `/${string}`): string =>
+  formatAdminURL({ apiRoute: req.payload.config.routes.api, path, serverURL: originOf(req) })
 
+/** Plain-text reply for the form-POST / new-tab endpoints, where JSON would just be shown raw. */
 export const text = (body: string, status: number): Response =>
   new Response(body, {
     status,
@@ -45,13 +44,50 @@ export function rejectCrossSite(req: PayloadRequest): Response | null {
   return site === 'same-origin' || site === 'none' ? null : text('Cross-site request refused', 403)
 }
 
+/** A collection's or global's sanitized config. */
+export function entityConfig(
+  req: PayloadRequest,
+  kind: 'collection',
+  slug: string,
+): SanitizedCollectionConfig | undefined
+export function entityConfig(
+  req: PayloadRequest,
+  kind: 'global',
+  slug: string,
+): SanitizedGlobalConfig | undefined
+export function entityConfig(
+  req: PayloadRequest,
+  kind: DocRef['kind'],
+  slug: string,
+): SanitizedCollectionConfig | SanitizedGlobalConfig | undefined
+export function entityConfig(req: PayloadRequest, kind: DocRef['kind'], slug: string) {
+  return kind === 'global'
+    ? req.payload.globals.config.find((g) => g.slug === slug)
+    : req.payload.collections[slug]?.config
+}
+
 /** A document ref from `kind`, `slug`, `id` query/body values. */
-export function readRef(values: { kind?: unknown; slug?: unknown; id?: unknown }): DocRef | null {
+export function readRef(
+  req: PayloadRequest,
+  values: { kind?: unknown; slug?: unknown; id?: unknown },
+): DocRef | null {
   const slug = typeof values.slug === 'string' ? values.slug : ''
   if (!slug) return null
   if (values.kind === 'global') return { kind: 'global', slug }
   const id = values.id
   if (typeof id === 'number') return { kind: 'collection', slug, id }
   if (typeof id !== 'string' || !id) return null
-  return parseRefKey(`c:${slug}:${id}`)
+  return withIdType(req, { kind: 'collection', slug, id })
+}
+
+/**
+ * The ref with its id typed the way the collection stores it (number or text),
+ * so a text id that looks numeric ("007") is never coerced.
+ */
+export function withIdType(req: PayloadRequest, ref: DocRef): DocRef {
+  if (ref.kind === 'global') return ref
+  const type = req.payload.collections[ref.slug]?.customIDType ?? req.payload.db.defaultIDType
+  const raw = String(ref.id)
+  const n = Number(raw)
+  return { ...ref, id: type === 'number' && Number.isSafeInteger(n) && String(n) === raw ? n : raw }
 }