@mrtimmy/payload-connector 0.2.0 → 0.2.1

package/README.md

@@ -18,6 +18,10 @@ export default buildConfig({
   plugins: [
     mrTimmyPayloadConnector({
       postsCollection: "posts",
+      taxonomies: {
+        categories: { matchFields: ["slug", "title"] },
+        tags: { matchFields: ["slug", "title"] },
+      },
     }),
   ],
 })
@@ -25,6 +29,17 @@ export default buildConfig({
 
 Deploy the Payload site after changing the config.
 
+If your Payload app runs inside Next.js and external packages are bundled too
+aggressively, keep the connector external in `next.config.js`:
+
+```js
+const nextConfig = {
+  serverExternalPackages: ["@mrtimmy/payload-connector"],
+}
+
+export default nextConfig
+```
+
 ## Create a Connector Key
 
 After deployment, open the Payload admin panel:
@@ -87,10 +102,12 @@ mrTimmyPayloadConnector({
     categories: {
       collection: "categories",
       create: true,
+      matchFields: ["slug", "title"],
     },
     tags: {
       collection: "tags",
       create: true,
+      matchFields: ["slug", "title"],
     },
   },
 })
@@ -146,8 +163,9 @@ The connector accepts category/tag input from fields like `categories`,
 `categoryNames`, `categorySlugs`, `tags`, `tagNames`, and `tagSlugs`.
 
 If the target Payload fields are relationship fields, the connector looks up
-matching documents by `slug`, `title`, or `name`. Missing terms are created by
-default.
+matching documents by `slug` or `title`. Missing terms are created by default.
+Configured `matchFields` that do not exist in the target Payload collection are
+ignored.
 
 ```ts
 mrTimmyPayloadConnector({
@@ -160,12 +178,14 @@ mrTimmyPayloadConnector({
       collection: "categories",
       labelField: "title",
       slugField: "slug",
+      matchFields: ["slug", "title"],
       create: true,
     },
     tags: {
       collection: "tags",
       labelField: "title",
       slugField: "slug",
+      matchFields: ["slug", "title"],
       create: true,
     },
   },
@@ -181,3 +201,6 @@ If your taxonomy collections use another required field, provide `createData`.
 - Draft/publish defaults to `_status: "draft" | "published"`, matching Payload draft-enabled collections.
 - If your collection does not use drafts or uses a custom status field, configure `fields.status` and `statuses`, or set `fields.status` to `null`.
 - Uploads use Payload's Local API with `filePath`; hooks and storage adapters on your media collection still run.
+- Connector errors include the failing step (`RichText-Konvertierung`,
+  `Taxonomie-Mapping`, `Media-Upload` or `Payload-Create`) so mr.timmy can show a
+  useful error instead of a generic Payload failure.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrtimmy/payload-connector",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Payload CMS connector for publishing mr.timmy blog posts.",
   "type": "module",
   "main": "./src/index.js",
@@ -22,6 +22,7 @@
   "files": [
     "src/index.js",
     "src/index.d.ts",
+    "src/lexical.js",
     "src/utils.js",
     "README.md"
   ],

package/src/index.js

@@ -2,17 +2,19 @@ import {
   DEFAULT_ENDPOINT_PATH,
   DEFAULT_HEADER_NAMES,
   DEFAULT_KEYS_COLLECTION,
+  ConnectorStepError,
   buildApiUrlHint,
   buildPostData,
   buildPublishData,
   constantTimeEquals,
+  errorMessage,
   generateConnectorKey,
   maskKey,
   normalizeEndpointPath,
   readConnectorHeader,
 } from "./utils.js"
 
-const VERSION = "0.2.0"
+const VERSION = "0.2.1"
 
 export function mrTimmyPayloadConnector(pluginOptions = {}) {
   return (incomingConfig = {}) => {
@@ -169,14 +171,25 @@ function createConnectorEndpoints(options) {
           return connectorError("Titel fehlt.", 400)
         }
 
-        const data = await buildPostData(input, options, req)
-        const doc = await req.payload.create({
-          collection: options.postsCollection,
-          data,
-          depth: 0,
-          draft: true,
-          overrideAccess: true,
-        })
+        let data
+        try {
+          data = await buildPostData(input, options, req)
+        } catch (error) {
+          return connectorException(req, "Datenaufbereitung", error)
+        }
+
+        let doc
+        try {
+          doc = await req.payload.create({
+            collection: options.postsCollection,
+            data,
+            depth: 0,
+            draft: true,
+            overrideAccess: true,
+          })
+        } catch (error) {
+          return connectorException(req, "Payload-Create", error)
+        }
 
         return Response.json({
           success: true,
@@ -199,15 +212,26 @@ function createConnectorEndpoints(options) {
         }
 
         const input = await req.json().catch(() => ({}))
-        const data = await buildPublishData(options, input, req)
-        const doc = await req.payload.update({
-          collection: options.postsCollection,
-          id,
-          data,
-          depth: 0,
-          draft: false,
-          overrideAccess: true,
-        })
+        let data
+        try {
+          data = await buildPublishData(options, input, req)
+        } catch (error) {
+          return connectorException(req, "Publish-Datenaufbereitung", error)
+        }
+
+        let doc
+        try {
+          doc = await req.payload.update({
+            collection: options.postsCollection,
+            id,
+            data,
+            depth: 0,
+            draft: false,
+            overrideAccess: true,
+          })
+        } catch (error) {
+          return connectorException(req, "Payload-Publish", error)
+        }
 
         const url =
           typeof options.resolvePublishedUrl === "function"
@@ -257,6 +281,34 @@ function connectorError(message, status = 500) {
   return Response.json({ success: false, error: message, message }, { status })
 }
 
+function connectorException(req, step, error, status = 500) {
+  const finalStep = error instanceof ConnectorStepError ? error.step : step
+  const message =
+    error instanceof ConnectorStepError
+      ? error.message
+      : `${step}: ${errorMessage(error)}`
+
+  logConnectorException(req, finalStep, error, message)
+  return Response.json(
+    { success: false, error: message, message, step: finalStep },
+    { status },
+  )
+}
+
+function logConnectorException(req, step, error, message) {
+  const line = `[mr.timmy Payload Connector] ${step} fehlgeschlagen: ${message}`
+  const logger = req?.payload?.logger
+  if (logger?.error) {
+    try {
+      logger.error(line)
+      return
+    } catch {
+      // Fall through to console logging.
+    }
+  }
+  console.error(line, error)
+}
+
 function defaultPublishedUrl(doc, req) {
   if (typeof doc.url === "string") return doc.url
   if (typeof doc.publishedUrl === "string") return doc.publishedUrl

package/src/lexical.js

@@ -0,0 +1,12 @@
+import { convertHTMLToLexical, editorConfigFactory } from "@payloadcms/richtext-lexical"
+import { JSDOM } from "jsdom"
+
+export async function convertHtmlToLexicalContent(html, req) {
+  return convertHTMLToLexical({
+    editorConfig: await editorConfigFactory.default({
+      config: req.payload.config,
+    }),
+    html,
+    JSDOM,
+  })
+}

package/src/utils.js

@@ -2,8 +2,7 @@ import crypto from "node:crypto"
 import fs from "node:fs/promises"
 import os from "node:os"
 import path from "node:path"
-
-const optionalImport = (specifier) => import(/* @vite-ignore */ specifier)
+import { marked } from "marked"
 
 export const DEFAULT_ENDPOINT_PATH = "/mrtimmy/create-post"
 export const DEFAULT_KEYS_COLLECTION = "mrtimmy-connector-keys"
@@ -47,17 +46,42 @@ export const DEFAULT_TAXONOMIES = {
     inputFields: ["categories", "categoryNames", "categorySlugs"],
     labelField: "title",
     slugField: "slug",
-    matchFields: ["slug", "title", "name"],
+    matchFields: ["slug", "title"],
   },
   tags: {
     create: true,
     inputFields: ["tags", "tagNames", "tagSlugs"],
     labelField: "title",
     slugField: "slug",
-    matchFields: ["slug", "title", "name"],
+    matchFields: ["slug", "title"],
   },
 }
 
+export class ConnectorStepError extends Error {
+  constructor(step, error) {
+    super(`${step}: ${errorMessage(error)}`)
+    this.name = "ConnectorStepError"
+    this.step = step
+    this.cause = error
+  }
+}
+
+export function errorMessage(error) {
+  if (error instanceof Error) return error.message
+  if (typeof error === "string") return error
+  try {
+    return JSON.stringify(error)
+  } catch {
+    return String(error)
+  }
+}
+
+function wrapStepError(step, error) {
+  return error instanceof ConnectorStepError
+    ? error
+    : new ConnectorStepError(step, error)
+}
+
 export function generateConnectorKey(prefix = "timmy") {
   return `${prefix}_${crypto.randomBytes(32).toString("hex")}`
 }
@@ -371,7 +395,6 @@ export function readConnectorHeader(req, headerNames = DEFAULT_HEADER_NAMES) {
 }
 
 export async function markdownToHtml(markdown) {
-  const { marked } = await import("marked")
   return marked.parse(String(markdown ?? ""))
 }
 
@@ -380,19 +403,8 @@ export async function convertContent(markdown, mode, req) {
   const html = await markdownToHtml(markdown)
   if (mode === "html") return html
 
-  const [{ convertHTMLToLexical, editorConfigFactory }, { JSDOM }] =
-    await Promise.all([
-      optionalImport("@payloadcms/richtext-lexical"),
-      optionalImport("jsdom"),
-    ])
-
-  return convertHTMLToLexical({
-    editorConfig: await editorConfigFactory.default({
-      config: req.payload.config,
-    }),
-    html,
-    JSDOM,
-  })
+  const { convertHtmlToLexicalContent } = await import("./lexical.js")
+  return convertHtmlToLexicalContent(html, req)
 }
 
 function taxonomyInput(input, config) {
@@ -408,7 +420,7 @@ async function findOrCreateTaxonomyDoc(term, config, collection, req) {
 
   const label = term.label ?? term.slug
   const slug = term.slug ?? slugify(label)
-  const matchFields = config.matchFields ?? []
+  const matchFields = existingMatchFields(req, collection, config.matchFields ?? [])
   const where = {
     or: matchFields.flatMap((field) => {
       const values = field === config.slugField ? [slug, label] : [label, slug]
@@ -448,6 +460,18 @@ async function findOrCreateTaxonomyDoc(term, config, collection, req) {
   return doc.id ?? doc._id
 }
 
+function existingMatchFields(req, collection, matchFields) {
+  const collectionConfig = getCollectionConfig(req, collection)
+  const unique = [...new Set(matchFields.filter(Boolean))]
+  if (!collectionConfig) return unique
+  return unique.filter(
+    (field) =>
+      field === "id" ||
+      field === "_id" ||
+      Boolean(getFieldConfig(req, collection, field)),
+  )
+}
+
 async function resolveTaxonomyValues(input, options, req, key, fieldConfig) {
   const config = options.taxonomies[key]
   if (!config) return undefined
@@ -483,43 +507,67 @@ export async function buildPostData(input, options, req) {
   const resolvedOptions = { ...options, taxonomies }
   const contentMode = options.contentMode ?? "lexical"
   const uploadCache = new Map()
-  const markdown = await rewriteInlineImages(
-    input.content ?? input.body ?? "",
-    media,
-    req,
-    uploadCache,
-  )
+  let markdown
+  try {
+    markdown = await rewriteInlineImages(
+      input.content ?? input.body ?? "",
+      media,
+      req,
+      uploadCache,
+    )
+  } catch (error) {
+    throw wrapStepError("Media-Upload/Inline-Bilder", error)
+  }
   const data = {}
   const featuredImageField = getFieldConfig(
     req,
     options.postsCollection,
     fields.featuredImageUrl,
   )
-  const featuredImage = input.featuredImage
-    ? fieldExpectsUpload(featuredImageField) && media.uploadFeaturedImage
-      ? await getUploadedImage(input.featuredImage, media, req, uploadCache, {
-          alt: input.imageAlt ?? input.title,
-          title: input.title,
-        })
-      : { url: input.featuredImage }
-    : null
-  const categories = await resolveTaxonomyValues(
-    input,
-    resolvedOptions,
-    req,
-    "categories",
-    getFieldConfig(req, options.postsCollection, fields.categories),
-  )
-  const tags = await resolveTaxonomyValues(
-    input,
-    resolvedOptions,
-    req,
-    "tags",
-    getFieldConfig(req, options.postsCollection, fields.tags),
-  )
+  let featuredImage
+  try {
+    featuredImage = input.featuredImage
+      ? fieldExpectsUpload(featuredImageField) && media.uploadFeaturedImage
+        ? await getUploadedImage(input.featuredImage, media, req, uploadCache, {
+            alt: input.imageAlt ?? input.title,
+            title: input.title,
+          })
+        : { url: input.featuredImage }
+      : null
+  } catch (error) {
+    throw wrapStepError("Media-Upload/Beitragsbild", error)
+  }
+
+  let categories
+  let tags
+  try {
+    categories = await resolveTaxonomyValues(
+      input,
+      resolvedOptions,
+      req,
+      "categories",
+      getFieldConfig(req, options.postsCollection, fields.categories),
+    )
+    tags = await resolveTaxonomyValues(
+      input,
+      resolvedOptions,
+      req,
+      "tags",
+      getFieldConfig(req, options.postsCollection, fields.tags),
+    )
+  } catch (error) {
+    throw wrapStepError("Taxonomie-Mapping", error)
+  }
+
+  let content
+  try {
+    content = await convertContent(markdown, contentMode, req)
+  } catch (error) {
+    throw wrapStepError("RichText-Konvertierung", error)
+  }
 
   setPath(data, fields.title, input.title)
-  setPath(data, fields.content, await convertContent(markdown, contentMode, req))
+  setPath(data, fields.content, content)
   setPath(data, fields.excerpt, input.excerpt ?? extractExcerpt(markdown))
   setPath(data, fields.slug, input.slug)
   setPath(data, fields.metaTitle, input.metaTitle)