@mrtimmy/payload-connector 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# mr.timmy Payload Connector
+
+Payload CMS connector for publishing blog posts from mr.timmy.
+
+## Installation
+
+```bash
+pnpm add @mrtimmy/payload-connector
+```
+
+Add the plugin to `payload.config.ts`:
+
+```ts
+import { buildConfig } from "payload"
+import { mrTimmyPayloadConnector } from "@mrtimmy/payload-connector"
+
+export default buildConfig({
+  plugins: [
+    mrTimmyPayloadConnector({
+      postsCollection: "posts",
+    }),
+  ],
+})
+```
+
+Deploy the Payload site after changing the config.
+
+## Create a Connector Key
+
+After deployment, open the Payload admin panel:
+
+1. Go to `mr.timmy -> Connector Keys`.
+2. Create a new key.
+3. Copy the API URL and API key into mr.timmy under `Deine Kanäle -> Payload CMS`.
+
+The default API URL is:
+
+```text
+https://your-domain.com/api/mrtimmy/create-post
+```
+
+## Endpoints
+
+The plugin exposes:
+
+```text
+GET  /api/mrtimmy/create-post
+POST /api/mrtimmy/create-post
+POST /api/mrtimmy/create-post/:id/publish
+```
+
+Requests must include:
+
+```text
+x-api-key: timmy_xxx
+```
+
+`X-MarketingAI-Key` is also accepted for compatibility with the WordPress connector naming.
+
+## Options
+
+```ts
+mrTimmyPayloadConnector({
+  postsCollection: "posts",
+  contentMode: "lexical",
+  fields: {
+    title: "title",
+    content: "content",
+    excerpt: "excerpt",
+    slug: "slug",
+    status: "_status",
+    metaTitle: "meta.title",
+    metaDescription: "meta.description",
+    focusKeyword: "focusKeyword",
+    featuredImageUrl: "featuredImage",
+    imageAlt: "imageAlt",
+    contentAssets: "contentAssets",
+  },
+})
+```
+
+`contentMode` can be:
+
+- `lexical` (default): converts Markdown to HTML and then to Payload Lexical JSON.
+- `html`: converts Markdown to HTML.
+- `markdown`: stores Markdown as plain text.
+
+If your Payload post schema uses different field names, override `fields`.
+
+## 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.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@mrtimmy/payload-connector",
+  "version": "0.1.0",
+  "description": "Payload CMS connector for publishing mr.timmy blog posts.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mucahitoe/marketing-ai.git",
+    "directory": "payload-plugin/marketing-ai-payload-connector"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/index.js",
+    "src/index.d.ts",
+    "src/utils.js",
+    "README.md"
+  ],
+  "keywords": [
+    "payload",
+    "payloadcms",
+    "payload-plugin",
+    "mr-timmy",
+    "marketing-ai"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "payload": "^3.0.0"
+  },
+  "dependencies": {
+    "@payloadcms/richtext-lexical": "^3.85.1",
+    "jsdom": "^29.0.1",
+    "marked": "^18.0.4"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,52 @@
+export type ContentMode = "lexical" | "html" | "markdown"
+
+export type FieldMap = {
+  title?: string | null
+  content?: string | null
+  excerpt?: string | null
+  slug?: string | null
+  status?: string | null
+  metaTitle?: string | null
+  metaDescription?: string | null
+  focusKeyword?: string | null
+  featuredImageUrl?: string | null
+  imageAlt?: string | null
+  contentAssets?: string | null
+}
+
+export type ConnectorStatuses = {
+  draft?: string
+  published?: string
+}
+
+export type MrTimmyPayloadConnectorOptions = {
+  enabled?: boolean
+  postsCollection?: string
+  keysCollection?: string
+  endpointPath?: string
+  keyPrefix?: string
+  headerNames?: string[]
+  contentMode?: ContentMode
+  fields?: FieldMap
+  statuses?: ConnectorStatuses
+  mapCreateData?: (
+    data: Record<string, unknown>,
+    input: Record<string, unknown>,
+    req: unknown,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>
+  mapPublishData?: (
+    data: Record<string, unknown>,
+    input: Record<string, unknown>,
+    req: unknown,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>
+  resolvePublishedUrl?: (
+    doc: Record<string, unknown>,
+    req: unknown,
+  ) => string | undefined | Promise<string | undefined>
+}
+
+export declare function mrTimmyPayloadConnector(
+  options?: MrTimmyPayloadConnectorOptions,
+): (incomingConfig: Record<string, unknown>) => Record<string, unknown>
+
+export default mrTimmyPayloadConnector

package/src/index.js

@@ -0,0 +1,267 @@
+import {
+  DEFAULT_ENDPOINT_PATH,
+  DEFAULT_HEADER_NAMES,
+  DEFAULT_KEYS_COLLECTION,
+  buildApiUrlHint,
+  buildPostData,
+  buildPublishData,
+  constantTimeEquals,
+  generateConnectorKey,
+  maskKey,
+  normalizeEndpointPath,
+  readConnectorHeader,
+} from "./utils.js"
+
+const VERSION = "0.1.0"
+
+export function mrTimmyPayloadConnector(pluginOptions = {}) {
+  return (incomingConfig = {}) => {
+    if (pluginOptions.enabled === false) return incomingConfig
+
+    const options = normalizeOptions(pluginOptions)
+    const existingCollections = incomingConfig.collections ?? []
+    const hasKeysCollection = existingCollections.some(
+      (collection) => collection?.slug === options.keysCollection,
+    )
+
+    return {
+      ...incomingConfig,
+      collections: [
+        ...existingCollections,
+        ...(hasKeysCollection ? [] : [createKeysCollection(options)]),
+      ],
+      endpoints: [
+        ...(incomingConfig.endpoints ?? []),
+        ...createConnectorEndpoints(options),
+      ],
+    }
+  }
+}
+
+export default mrTimmyPayloadConnector
+
+function normalizeOptions(options) {
+  return {
+    ...options,
+    postsCollection: options.postsCollection ?? "posts",
+    keysCollection: options.keysCollection ?? DEFAULT_KEYS_COLLECTION,
+    endpointPath: normalizeEndpointPath(
+      options.endpointPath ?? DEFAULT_ENDPOINT_PATH,
+    ),
+    keyPrefix: options.keyPrefix ?? "timmy",
+    headerNames: options.headerNames ?? DEFAULT_HEADER_NAMES,
+    contentMode: options.contentMode ?? "lexical",
+  }
+}
+
+function isAuthed({ req }) {
+  return Boolean(req.user)
+}
+
+function createKeysCollection(options) {
+  return {
+    slug: options.keysCollection,
+    labels: {
+      singular: "mr.timmy Connector-Schlüssel",
+      plural: "mr.timmy Connector-Schlüssel",
+    },
+    admin: {
+      group: "mr.timmy",
+      useAsTitle: "name",
+      defaultColumns: ["name", "apiUrl", "keyPreview", "enabled", "updatedAt"],
+      description:
+        "Schlüssel und API-URL für die Verbindung zwischen dieser Payload-Seite und mr.timmy.",
+    },
+    access: {
+      create: isAuthed,
+      read: isAuthed,
+      update: isAuthed,
+      delete: isAuthed,
+    },
+    fields: [
+      {
+        name: "name",
+        type: "text",
+        required: true,
+        defaultValue: "mr.timmy",
+      },
+      {
+        name: "enabled",
+        type: "checkbox",
+        defaultValue: true,
+      },
+      {
+        name: "apiUrl",
+        type: "text",
+        admin: {
+          readOnly: true,
+          description:
+            "Diese URL in mr.timmy unter Deine Kanäle -> Payload CMS eintragen.",
+        },
+      },
+      {
+        name: "apiKey",
+        label: "API-Key",
+        type: "text",
+        admin: {
+          readOnly: true,
+          description:
+            "Diesen Schlüssel in mr.timmy eintragen. Zum Rotieren einen neuen Schlüssel anlegen und den alten deaktivieren.",
+        },
+      },
+      {
+        name: "keyPreview",
+        type: "text",
+        admin: {
+          readOnly: true,
+        },
+      },
+    ],
+    hooks: {
+      beforeValidate: [
+        ({ data = {}, operation, req }) => {
+          const next = { ...data }
+          if (operation === "create" && !next.apiKey) {
+            next.apiKey = generateConnectorKey(options.keyPrefix)
+          }
+          if (next.apiKey) {
+            next.keyPreview = maskKey(next.apiKey)
+          }
+          next.apiUrl = buildApiUrlHint(req, options.endpointPath)
+          return next
+        },
+      ],
+    },
+  }
+}
+
+function createConnectorEndpoints(options) {
+  const path = options.endpointPath
+  return [
+    {
+      path,
+      method: "get",
+      handler: async (req) => {
+        const auth = await authenticateConnectorRequest(req, options)
+        if (!auth.ok) return connectorError(auth.error, auth.status)
+
+        return Response.json({
+          status: "connected",
+          ok: true,
+          connector: "mrtimmy-payload-connector",
+          version: VERSION,
+          apiUrl: buildApiUrlHint(req, path),
+        })
+      },
+    },
+    {
+      path,
+      method: "post",
+      handler: async (req) => {
+        const auth = await authenticateConnectorRequest(req, options)
+        if (!auth.ok) return connectorError(auth.error, auth.status)
+
+        const input = await req.json().catch(() => null)
+        if (!input || typeof input !== "object") {
+          return connectorError("Ungültiger JSON-Body.", 400)
+        }
+        if (!input.title || typeof input.title !== "string") {
+          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,
+        })
+
+        return Response.json({
+          success: true,
+          id: String(doc.id),
+          slug: doc.slug,
+          status: "draft",
+        })
+      },
+    },
+    {
+      path: `${path}/:id/publish`,
+      method: "post",
+      handler: async (req) => {
+        const auth = await authenticateConnectorRequest(req, options)
+        if (!auth.ok) return connectorError(auth.error, auth.status)
+
+        const id = req.routeParams?.id
+        if (!id || typeof id !== "string") {
+          return connectorError("Post-ID fehlt.", 400)
+        }
+
+        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,
+        })
+
+        const url =
+          typeof options.resolvePublishedUrl === "function"
+            ? await options.resolvePublishedUrl(doc, req)
+            : defaultPublishedUrl(doc, req)
+
+        return Response.json({
+          success: true,
+          id: String(doc.id),
+          slug: doc.slug,
+          status: "published",
+          ...(url ? { url, publishedUrl: url } : {}),
+        })
+      },
+    },
+  ]
+}
+
+async function authenticateConnectorRequest(req, options) {
+  const provided = readConnectorHeader(req, options.headerNames)
+  if (!provided) {
+    return { ok: false, status: 401, error: "API-Key fehlt." }
+  }
+
+  const result = await req.payload.find({
+    collection: options.keysCollection,
+    where: {
+      and: [
+        { enabled: { equals: true } },
+        { apiKey: { equals: provided } },
+      ],
+    },
+    depth: 0,
+    limit: 1,
+    overrideAccess: true,
+  })
+
+  const key = result.docs?.[0]?.apiKey
+  if (!key || !constantTimeEquals(key, provided)) {
+    return { ok: false, status: 401, error: "API-Key stimmt nicht." }
+  }
+
+  return { ok: true }
+}
+
+function connectorError(message, status = 500) {
+  return Response.json({ success: false, error: message, message }, { status })
+}
+
+function defaultPublishedUrl(doc, req) {
+  if (typeof doc.url === "string") return doc.url
+  if (typeof doc.publishedUrl === "string") return doc.publishedUrl
+  if (!doc.slug) return undefined
+
+  const origin = buildApiUrlHint(req, "").replace(/\/api\/?$/, "")
+  return origin ? `${origin}/blog/${doc.slug}` : undefined
+}

package/src/utils.js

@@ -0,0 +1,163 @@
+import crypto from "node:crypto"
+
+const optionalImport = (specifier) => import(/* @vite-ignore */ specifier)
+
+export const DEFAULT_ENDPOINT_PATH = "/mrtimmy/create-post"
+export const DEFAULT_KEYS_COLLECTION = "mrtimmy-connector-keys"
+export const DEFAULT_HEADER_NAMES = ["x-api-key", "X-MarketingAI-Key"]
+
+export const DEFAULT_FIELDS = {
+  title: "title",
+  content: "content",
+  excerpt: "excerpt",
+  slug: "slug",
+  status: "_status",
+  metaTitle: "meta.title",
+  metaDescription: "meta.description",
+  focusKeyword: "focusKeyword",
+  featuredImageUrl: "featuredImage",
+  imageAlt: "imageAlt",
+  contentAssets: "contentAssets",
+}
+
+export const DEFAULT_STATUSES = {
+  draft: "draft",
+  published: "published",
+}
+
+export function generateConnectorKey(prefix = "timmy") {
+  return `${prefix}_${crypto.randomBytes(32).toString("hex")}`
+}
+
+export function maskKey(key) {
+  if (!key) return ""
+  return `••••••••••••${String(key).slice(-6)}`
+}
+
+export function constantTimeEquals(a, b) {
+  const left = Buffer.from(String(a ?? ""))
+  const right = Buffer.from(String(b ?? ""))
+  if (left.length !== right.length) return false
+  return crypto.timingSafeEqual(left, right)
+}
+
+export function normalizeEndpointPath(path = DEFAULT_ENDPOINT_PATH) {
+  const withSlash = path.startsWith("/") ? path : `/${path}`
+  return withSlash.replace(/\/+$/, "")
+}
+
+export function normalizeFields(fields = {}) {
+  return { ...DEFAULT_FIELDS, ...fields }
+}
+
+export function setPath(target, path, value) {
+  if (!path || value === undefined || value === null) return target
+  const parts = String(path).split(".").filter(Boolean)
+  if (parts.length === 0) return target
+  let cursor = target
+  for (const part of parts.slice(0, -1)) {
+    if (
+      typeof cursor[part] !== "object" ||
+      cursor[part] === null ||
+      Array.isArray(cursor[part])
+    ) {
+      cursor[part] = {}
+    }
+    cursor = cursor[part]
+  }
+  cursor[parts[parts.length - 1]] = value
+  return target
+}
+
+export function extractExcerpt(markdown = "") {
+  const lines = String(markdown).split("\n")
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("![")) continue
+    return trimmed
+      .replace(/[*_`>]/g, "")
+      .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+      .slice(0, 300)
+  }
+  return ""
+}
+
+export function buildOriginFromRequest(req) {
+  const headers = req?.headers
+  const host = headers?.get?.("x-forwarded-host") ?? headers?.get?.("host")
+  if (!host) return ""
+  const proto = headers?.get?.("x-forwarded-proto") ?? "https"
+  return `${proto}://${host}`
+}
+
+export function buildApiUrlHint(req, endpointPath) {
+  const origin = buildOriginFromRequest(req)
+  return origin ? `${origin}/api${endpointPath}` : `/api${endpointPath}`
+}
+
+export function readConnectorHeader(req, headerNames = DEFAULT_HEADER_NAMES) {
+  for (const name of headerNames) {
+    const value = req?.headers?.get?.(name)
+    if (value) return value
+  }
+  return ""
+}
+
+export async function markdownToHtml(markdown) {
+  const { marked } = await import("marked")
+  return marked.parse(String(markdown ?? ""))
+}
+
+export async function convertContent(markdown, mode, req) {
+  if (mode === "markdown") return String(markdown ?? "")
+  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,
+  })
+}
+
+export async function buildPostData(input, options, req) {
+  const fields = normalizeFields(options.fields)
+  const statuses = { ...DEFAULT_STATUSES, ...(options.statuses ?? {}) }
+  const contentMode = options.contentMode ?? "lexical"
+  const markdown = input.content ?? input.body ?? ""
+  const data = {}
+
+  setPath(data, fields.title, input.title)
+  setPath(data, fields.content, await convertContent(markdown, contentMode, req))
+  setPath(data, fields.excerpt, input.excerpt ?? extractExcerpt(markdown))
+  setPath(data, fields.slug, input.slug)
+  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.imageAlt, input.imageAlt)
+  setPath(data, fields.contentAssets, input.contentAssets)
+  setPath(data, fields.status, statuses.draft)
+
+  return typeof options.mapCreateData === "function"
+    ? await options.mapCreateData(data, input, req)
+    : data
+}
+
+export async function buildPublishData(options, input, req) {
+  const fields = normalizeFields(options.fields)
+  const statuses = { ...DEFAULT_STATUSES, ...(options.statuses ?? {}) }
+  const data = {}
+  setPath(data, fields.status, statuses.published)
+  return typeof options.mapPublishData === "function"
+    ? await options.mapPublishData(data, input, req)
+    : data
+}