mr.timmy Payload Connector

Payload CMS connector for publishing blog posts from mr.timmy.

Installation

pnpm add @mrtimmy/payload-connector

Add the plugin to payload.config.ts:

import { buildConfig } from "payload"
import { mrTimmyPayloadConnector } from "@mrtimmy/payload-connector"

export default buildConfig({
  plugins: [
    mrTimmyPayloadConnector({
      postsCollection: "posts",
      taxonomies: {
        categories: { matchFields: ["slug", "title"] },
        tags: { matchFields: ["slug", "title"] },
      },
    }),
  ],
})

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:

const nextConfig = {
  serverExternalPackages: ["@mrtimmy/payload-connector"],
}

export default nextConfig

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:

https://your-domain.com/api/mrtimmy/create-post

Endpoints

The plugin exposes:

GET  /api/mrtimmy/create-post
POST /api/mrtimmy/create-post
POST /api/mrtimmy/create-post/:id/publish

Requests must include:

x-api-key: timmy_xxx

X-MarketingAI-Key is also accepted for compatibility with the WordPress connector naming.

Options

mrTimmyPayloadConnector({
  postsCollection: "posts",
  contentMode: "lexical",
  media: {
    collection: "media",
    uploadFeaturedImage: true,
    uploadInlineImages: true,
  },
  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",
    categories: "categories",
    tags: "tags",
  },
  taxonomies: {
    categories: {
      collection: "categories",
      create: true,
      matchFields: ["slug", "title"],
    },
    tags: {
      collection: "tags",
      create: true,
      matchFields: ["slug", "title"],
    },
  },
})

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.

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.

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:

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 or title. Missing terms are created by default. Configured matchFields that do not exist in the target Payload collection are ignored.

mrTimmyPayloadConnector({
  fields: {
    categories: "categories",
    tags: "tags",
  },
  taxonomies: {
    categories: {
      collection: "categories",
      labelField: "title",
      slugField: "slug",
      matchFields: ["slug", "title"],
      create: true,
    },
    tags: {
      collection: "tags",
      labelField: "title",
      slugField: "slug",
      matchFields: ["slug", "title"],
      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.
• 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.