@mrtimmy/payload-connector 0.1.0 → 0.2.0

package/README.md

@@ -63,6 +63,11 @@ x-api-key: timmy_xxx
 mrTimmyPayloadConnector({
   postsCollection: "posts",
   contentMode: "lexical",
+  media: {
+    collection: "media",
+    uploadFeaturedImage: true,
+    uploadInlineImages: true,
+  },
   fields: {
     title: "title",
     content: "content",
@@ -75,6 +80,18 @@ mrTimmyPayloadConnector({
     featuredImageUrl: "featuredImage",
     imageAlt: "imageAlt",
     contentAssets: "contentAssets",
+    categories: "categories",
+    tags: "tags",
+  },
+  taxonomies: {
+    categories: {
+      collection: "categories",
+      create: true,
+    },
+    tags: {
+      collection: "tags",
+      create: true,
+    },
   },
 })
 ```
@@ -87,10 +104,80 @@ mrTimmyPayloadConnector({
 
 If your Payload post schema uses different field names, override `fields`.
 
+## Media Uploads
+
+If the configured `featuredImageUrl` field points to a Payload `upload` field,
+the connector downloads the incoming image URL, uploads it to the configured
+media collection, and stores the new media document ID on the post.
+
+```ts
+mrTimmyPayloadConnector({
+  media: {
+    collection: "media",
+    fields: {
+      alt: "alt",
+      title: "title",
+    },
+  },
+  fields: {
+    featuredImageUrl: "featuredImage",
+  },
+})
+```
+
+If `featuredImageUrl` is a plain text/URL field, the connector keeps the old
+behavior and stores the image URL instead.
+
+Inline Markdown images in the article body are also uploaded to the media
+collection when possible. Their URLs are rewritten before the content is
+converted to HTML or Lexical JSON.
+
+To disable media handling:
+
+```ts
+mrTimmyPayloadConnector({
+  media: false,
+})
+```
+
+## Categories and Tags
+
+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.
+
+```ts
+mrTimmyPayloadConnector({
+  fields: {
+    categories: "categories",
+    tags: "tags",
+  },
+  taxonomies: {
+    categories: {
+      collection: "categories",
+      labelField: "title",
+      slugField: "slug",
+      create: true,
+    },
+    tags: {
+      collection: "tags",
+      labelField: "title",
+      slugField: "slug",
+      create: true,
+    },
+  },
+})
+```
+
+If your taxonomy collections use another required field, provide `createData`.
+
 ## Notes
 
 - The plugin uses Payload Custom Endpoints and Payload Local API.
 - Custom endpoints are authenticated by this plugin, not by Payload automatically.
 - 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`.
-- Featured images are passed as URL fields in this MVP. Upload-collection integration is project-specific and should be added with a custom mapper later.
+- Uploads use Payload's Local API with `filePath`; hooks and storage adapters on your media collection still run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrtimmy/payload-connector",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Payload CMS connector for publishing mr.timmy blog posts.",
   "type": "module",
   "main": "./src/index.js",

package/src/index.d.ts

@@ -12,6 +12,8 @@ export type FieldMap = {
   featuredImageUrl?: string | null
   imageAlt?: string | null
   contentAssets?: string | null
+  categories?: string | null
+  tags?: string | null
 }
 
 export type ConnectorStatuses = {
@@ -19,6 +21,44 @@ export type ConnectorStatuses = {
   published?: string
 }
 
+export type MediaOptions = false | {
+  collection?: string
+  uploadFeaturedImage?: boolean
+  uploadInlineImages?: boolean
+  maxBytes?: number
+  fields?: {
+    alt?: string | null
+    title?: string | null
+  }
+}
+
+export type TaxonomyTerm = {
+  id?: string | number
+  _id?: string | number
+  label?: string
+  title?: string
+  name?: string
+  slug?: string
+}
+
+export type TaxonomyOptions = false | {
+  collection?: string
+  create?: boolean
+  inputFields?: string[]
+  labelField?: string | null
+  slugField?: string | null
+  matchFields?: string[]
+  createData?: (
+    args: { label?: string; slug?: string; term: TaxonomyTerm },
+    req: unknown,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>
+}
+
+export type TaxonomiesOptions = {
+  categories?: TaxonomyOptions
+  tags?: TaxonomyOptions
+}
+
 export type MrTimmyPayloadConnectorOptions = {
   enabled?: boolean
   postsCollection?: string
@@ -29,6 +69,8 @@ export type MrTimmyPayloadConnectorOptions = {
   contentMode?: ContentMode
   fields?: FieldMap
   statuses?: ConnectorStatuses
+  media?: MediaOptions
+  taxonomies?: TaxonomiesOptions
   mapCreateData?: (
     data: Record<string, unknown>,
     input: Record<string, unknown>,

package/src/index.js

@@ -12,7 +12,7 @@ import {
   readConnectorHeader,
 } from "./utils.js"
 
-const VERSION = "0.1.0"
+const VERSION = "0.2.0"
 
 export function mrTimmyPayloadConnector(pluginOptions = {}) {
   return (incomingConfig = {}) => {

package/src/utils.js

@@ -1,4 +1,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)
 
@@ -18,6 +21,8 @@ export const DEFAULT_FIELDS = {
   featuredImageUrl: "featuredImage",
   imageAlt: "imageAlt",
   contentAssets: "contentAssets",
+  categories: "categories",
+  tags: "tags",
 }
 
 export const DEFAULT_STATUSES = {
@@ -25,6 +30,34 @@ export const DEFAULT_STATUSES = {
   published: "published",
 }
 
+export const DEFAULT_MEDIA = {
+  collection: "media",
+  uploadFeaturedImage: true,
+  uploadInlineImages: true,
+  maxBytes: 15 * 1024 * 1024,
+  fields: {
+    alt: "alt",
+    title: "title",
+  },
+}
+
+export const DEFAULT_TAXONOMIES = {
+  categories: {
+    create: true,
+    inputFields: ["categories", "categoryNames", "categorySlugs"],
+    labelField: "title",
+    slugField: "slug",
+    matchFields: ["slug", "title", "name"],
+  },
+  tags: {
+    create: true,
+    inputFields: ["tags", "tagNames", "tagSlugs"],
+    labelField: "title",
+    slugField: "slug",
+    matchFields: ["slug", "title", "name"],
+  },
+}
+
 export function generateConnectorKey(prefix = "timmy") {
   return `${prefix}_${crypto.randomBytes(32).toString("hex")}`
 }
@@ -50,6 +83,38 @@ export function normalizeFields(fields = {}) {
   return { ...DEFAULT_FIELDS, ...fields }
 }
 
+export function normalizeMedia(media = {}) {
+  if (media === false) return { enabled: false }
+  return {
+    enabled: true,
+    ...DEFAULT_MEDIA,
+    ...media,
+    fields: {
+      ...DEFAULT_MEDIA.fields,
+      ...(media.fields ?? {}),
+    },
+  }
+}
+
+export function normalizeTaxonomies(taxonomies = {}) {
+  return {
+    categories:
+      taxonomies.categories === false
+        ? false
+        : {
+            ...DEFAULT_TAXONOMIES.categories,
+            ...(taxonomies.categories ?? {}),
+          },
+    tags:
+      taxonomies.tags === false
+        ? false
+        : {
+            ...DEFAULT_TAXONOMIES.tags,
+            ...(taxonomies.tags ?? {}),
+          },
+  }
+}
+
 export function setPath(target, path, value) {
   if (!path || value === undefined || value === null) return target
   const parts = String(path).split(".").filter(Boolean)
@@ -69,6 +134,81 @@ export function setPath(target, path, value) {
   return target
 }
 
+export function slugify(value = "") {
+  return String(value)
+    .trim()
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/ä/g, "ae")
+    .replace(/ö/g, "oe")
+    .replace(/ü/g, "ue")
+    .replace(/ß/g, "ss")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}
+
+export function normalizeTermList(value) {
+  const values = Array.isArray(value) ? value : value ? [value] : []
+  return values
+    .map((entry) => {
+      if (entry && typeof entry === "object") {
+        const id = entry.id ?? entry._id
+        const label = entry.label ?? entry.title ?? entry.name ?? entry.slug
+        const slug = entry.slug ?? (label ? slugify(label) : undefined)
+        return id || label || slug ? { id, label, slug } : null
+      }
+      const label = String(entry ?? "").trim()
+      return label ? { label, slug: slugify(label) } : null
+    })
+    .filter(Boolean)
+}
+
+export function getCollectionConfig(req, slug) {
+  return req?.payload?.config?.collections?.find(
+    (collection) => collection?.slug === slug,
+  )
+}
+
+function findFieldInFields(fields = [], parts = []) {
+  for (const field of fields) {
+    if (!field) continue
+
+    if (field.type === "tabs") {
+      for (const tab of field.tabs ?? []) {
+        const found = findFieldInFields(tab.fields ?? [], parts)
+        if (found) return found
+      }
+      continue
+    }
+
+    if (!field.name) {
+      const found = findFieldInFields(field.fields ?? [], parts)
+      if (found) return found
+      continue
+    }
+
+    if (field.name !== parts[0]) continue
+    if (parts.length === 1) return field
+    return findFieldInFields(field.fields ?? [], parts.slice(1))
+  }
+  return undefined
+}
+
+export function getFieldConfig(req, collectionSlug, fieldPath) {
+  if (!fieldPath) return undefined
+  const collection = getCollectionConfig(req, collectionSlug)
+  return findFieldInFields(collection?.fields ?? [], String(fieldPath).split("."))
+}
+
+export function fieldExpectsUpload(field) {
+  return field?.type === "upload"
+}
+
+export function fieldExpectsRelationship(field) {
+  return field?.type === "relationship"
+}
+
 export function extractExcerpt(markdown = "") {
   const lines = String(markdown).split("\n")
   for (const line of lines) {
@@ -95,6 +235,133 @@ export function buildApiUrlHint(req, endpointPath) {
   return origin ? `${origin}/api${endpointPath}` : `/api${endpointPath}`
 }
 
+function absolutizeUrl(url, req) {
+  if (!url || typeof url !== "string") return url
+  if (/^https?:\/\//i.test(url)) return url
+  if (!url.startsWith("/")) return url
+  const origin = buildOriginFromRequest(req)
+  return origin ? `${origin}${url}` : url
+}
+
+function isHttpUrl(value) {
+  return /^https?:\/\//i.test(String(value ?? ""))
+}
+
+function extensionFor(contentType, sourceUrl) {
+  const fromType = {
+    "image/jpeg": ".jpg",
+    "image/jpg": ".jpg",
+    "image/png": ".png",
+    "image/webp": ".webp",
+    "image/gif": ".gif",
+    "image/avif": ".avif",
+    "image/svg+xml": ".svg",
+  }[String(contentType ?? "").split(";")[0].trim().toLowerCase()]
+  if (fromType) return fromType
+  const ext = path.extname(new URL(sourceUrl).pathname)
+  return ext || ".jpg"
+}
+
+function safeFileBase(value) {
+  const base = slugify(value) || `mrtimmy-${Date.now()}`
+  return base.slice(0, 80)
+}
+
+async function downloadImageToTempFile(sourceUrl, media) {
+  const response = await fetch(sourceUrl)
+  if (!response.ok) {
+    throw new Error(`Bild konnte nicht geladen werden: ${response.status}`)
+  }
+
+  const contentType =
+    response.headers.get("content-type") ?? "application/octet-stream"
+  if (!contentType.toLowerCase().startsWith("image/")) {
+    throw new Error(`URL ist kein Bild: ${contentType}`)
+  }
+
+  const buffer = Buffer.from(await response.arrayBuffer())
+  if (buffer.byteLength > media.maxBytes) {
+    throw new Error(
+      `Bild ist zu groß (${buffer.byteLength} Bytes, Limit ${media.maxBytes})`,
+    )
+  }
+
+  const extension = extensionFor(contentType, sourceUrl)
+  const filePath = path.join(
+    os.tmpdir(),
+    `${safeFileBase(path.basename(new URL(sourceUrl).pathname, extension))}-${crypto.randomBytes(8).toString("hex")}${extension}`,
+  )
+  await fs.writeFile(filePath, buffer)
+  return { filePath, contentType }
+}
+
+function buildMediaData(media, alt, title) {
+  const data = {}
+  setPath(data, media.fields.alt, alt)
+  setPath(data, media.fields.title, title)
+  return data
+}
+
+export async function uploadImageFromUrl(sourceUrl, media, req, meta = {}) {
+  if (!media.enabled || !isHttpUrl(sourceUrl)) return null
+  if (!getCollectionConfig(req, media.collection)?.upload) return null
+
+  const { filePath } = await downloadImageToTempFile(sourceUrl, media)
+  try {
+    const doc = await req.payload.create({
+      collection: media.collection,
+      data: buildMediaData(media, meta.alt, meta.title),
+      filePath,
+      depth: 0,
+      overrideAccess: true,
+    })
+    return {
+      id: doc.id ?? doc._id,
+      url: absolutizeUrl(doc.url, req),
+      doc,
+      originalUrl: sourceUrl,
+    }
+  } finally {
+    await fs.unlink(filePath).catch(() => {})
+  }
+}
+
+export function extractMarkdownImages(markdown = "") {
+  const images = []
+  String(markdown).replace(
+    /!\[([^\]]*)\]\(([^)\s]+)(?:\s+["'][^"']*["'])?\)/g,
+    (match, alt, url) => {
+      if (isHttpUrl(url)) images.push({ match, alt, url })
+      return match
+    },
+  )
+  return images
+}
+
+async function rewriteInlineImages(markdown, media, req, cache) {
+  if (!media.enabled || !media.uploadInlineImages) return markdown
+  const images = extractMarkdownImages(markdown)
+  if (images.length === 0) return markdown
+
+  let next = String(markdown)
+  for (const image of images) {
+    const asset = await getUploadedImage(image.url, media, req, cache, {
+      alt: image.alt,
+      title: image.alt,
+    })
+    if (!asset?.url) continue
+    next = next.replace(image.url, asset.url)
+  }
+  return next
+}
+
+async function getUploadedImage(sourceUrl, media, req, cache, meta) {
+  if (!cache.has(sourceUrl)) {
+    cache.set(sourceUrl, uploadImageFromUrl(sourceUrl, media, req, meta))
+  }
+  return cache.get(sourceUrl)
+}
+
 export function readConnectorHeader(req, headerNames = DEFAULT_HEADER_NAMES) {
   for (const name of headerNames) {
     const value = req?.headers?.get?.(name)
@@ -128,12 +395,128 @@ export async function convertContent(markdown, mode, req) {
   })
 }
 
+function taxonomyInput(input, config) {
+  for (const name of config.inputFields ?? []) {
+    const terms = normalizeTermList(input[name])
+    if (terms.length > 0) return terms
+  }
+  return []
+}
+
+async function findOrCreateTaxonomyDoc(term, config, collection, req) {
+  if (term.id) return term.id
+
+  const label = term.label ?? term.slug
+  const slug = term.slug ?? slugify(label)
+  const matchFields = config.matchFields ?? []
+  const where = {
+    or: matchFields.flatMap((field) => {
+      const values = field === config.slugField ? [slug, label] : [label, slug]
+      return [...new Set(values.filter(Boolean))].map((value) => ({
+        [field]: { equals: value },
+      }))
+    }),
+  }
+
+  if (where.or.length > 0) {
+    const result = await req.payload.find({
+      collection,
+      where,
+      depth: 0,
+      limit: 1,
+      overrideAccess: true,
+    })
+    const existing = result.docs?.[0]
+    if (existing) return existing.id ?? existing._id
+  }
+
+  if (!config.create) return undefined
+
+  const data =
+    typeof config.createData === "function"
+      ? await config.createData({ label, slug, term }, req)
+      : {}
+  setPath(data, config.labelField, label)
+  setPath(data, config.slugField, slug)
+
+  const doc = await req.payload.create({
+    collection,
+    data,
+    depth: 0,
+    overrideAccess: true,
+  })
+  return doc.id ?? doc._id
+}
+
+async function resolveTaxonomyValues(input, options, req, key, fieldConfig) {
+  const config = options.taxonomies[key]
+  if (!config) return undefined
+  const terms = taxonomyInput(input, config)
+  if (terms.length === 0) return undefined
+
+  if (fieldExpectsRelationship(fieldConfig)) {
+    const relationTo = Array.isArray(fieldConfig.relationTo)
+      ? fieldConfig.relationTo[0]
+      : fieldConfig.relationTo
+    const collection = config.collection ?? relationTo
+    if (!collection) return undefined
+
+    const ids = []
+    for (const term of terms) {
+      const id = await findOrCreateTaxonomyDoc(term, config, collection, req)
+      if (id) ids.push(id)
+    }
+    if (ids.length === 0) return undefined
+    return fieldConfig.hasMany === false ? ids[0] : ids
+  }
+
+  const values = terms.map((term) => term.slug ?? term.label).filter(Boolean)
+  if (fieldConfig?.hasMany === false) return values[0]
+  return values
+}
+
 export async function buildPostData(input, options, req) {
   const fields = normalizeFields(options.fields)
   const statuses = { ...DEFAULT_STATUSES, ...(options.statuses ?? {}) }
+  const media = normalizeMedia(options.media)
+  const taxonomies = normalizeTaxonomies(options.taxonomies)
+  const resolvedOptions = { ...options, taxonomies }
   const contentMode = options.contentMode ?? "lexical"
-  const markdown = input.content ?? input.body ?? ""
+  const uploadCache = new Map()
+  const markdown = await rewriteInlineImages(
+    input.content ?? input.body ?? "",
+    media,
+    req,
+    uploadCache,
+  )
   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),
+  )
 
   setPath(data, fields.title, input.title)
   setPath(data, fields.content, await convertContent(markdown, contentMode, req))
@@ -142,9 +525,17 @@ export async function buildPostData(input, options, req) {
   setPath(data, fields.metaTitle, input.metaTitle)
   setPath(data, fields.metaDescription, input.metaDescription)
   setPath(data, fields.focusKeyword, input.focusKeyword)
-  setPath(data, fields.featuredImageUrl, input.featuredImage)
+  setPath(
+    data,
+    fields.featuredImageUrl,
+    fieldExpectsUpload(featuredImageField)
+      ? featuredImage?.id
+      : featuredImage?.url,
+  )
   setPath(data, fields.imageAlt, input.imageAlt)
   setPath(data, fields.contentAssets, input.contentAssets)
+  setPath(data, fields.categories, categories)
+  setPath(data, fields.tags, tags)
   setPath(data, fields.status, statuses.draft)
 
   return typeof options.mapCreateData === "function"