@composius/payload-plugin-import-wordpress 0.1.0

package/README.md

@@ -0,0 +1,152 @@
+# @composius/payload-plugin-import-wordpress
+
+Imports WordPress posts into Payload via the WordPress REST API: content,
+categories, authors, featured images and in-content images. Images are fetched
+at their original size (and resized by your media collection), uploaded only
+once even when reused across posts, and internal links are rewritten (with 301
+redirects created for the rest). Imports run on the Payload jobs queue and are
+**idempotent and resumable**, writing a full report onto each job document.
+
+By default it targets the collections from
+[`@composius/payload-plugin-articles`](../payload-plugin-articles) (`articles`,
+`categories`, `authors`) and a `media` uploads collection.
+
+## Collections
+
+This plugin adds two collections (grouped under **WordPress import**):
+
+| Collection         | Purpose                                                                                     |
+| ------------------ | ------------------------------------------------------------------------------------------- |
+| `wp-import-jobs`   | The import "form" and report surface. Creating a document starts an import run.              |
+| `wp-import-records`| Source→target mappings that make imports idempotent, resumable and image-deduplicating.     |
+
+### `wp-import-jobs` fields
+
+The edit form is organized into one tab per import step:
+
+| Tab                | Fields                                                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------------------------ |
+| Configuration      | `sourceUrl`, `credentials` (`username` + `applicationPassword`, optional), `dateFrom`/`dateTo`, `limit`, `dryRun`, `resume` |
+| Authors            | `authorsReport` (read-only) — authors imported by this job.                                                  |
+| Categories         | `categoriesReport` (read-only) — categories imported, hierarchy preserved.                                   |
+| Media              | `mediaReport` (read-only) — images uploaded + how many were reused (deduped).                                |
+| Posts              | `postsReport` (read-only) — posts imported and remaining.                                                    |
+| Links & redirects  | `linksReport` (read-only) — every internal link: rewritten / redirect created / unresolved.                  |
+| Report             | `runs` + `progress` + `errorsReport` (read-only) — run history, live counts and per-item errors.             |
+
+`status`, `startedAt` and `finishedAt` sit in the sidebar (read-only).
+
+**Run history**: a job can run several times (resume/retry). Each run gets a
+number; `runs` lists every run with its status, timestamps and a final progress
+snapshot, and every reported item (post, category, author, media, link, error)
+carries the `run` that produced it. A resume **merges** with the previous
+reports instead of overwriting them — only entries from dry runs are dropped
+(they were plans, not imports).
+
+**Credentials** are optional: a WordPress username + [application password](https://make.wordpress.org/core/2020/11/05/application-passwords-integration-guide/)
+(Users → Profile → Application Passwords). When set, requests are authenticated
+with HTTP Basic auth, which unlocks non-public data — notably **author emails**
+(fetched via `?context=edit`), so the `users` author strategy can use real
+addresses instead of synthesized ones. The password is stored in plain text on
+the job document — delete the job (or clear the field) once the import is done.
+
+## What gets imported
+
+- **Posts** (published only) → the target content collection, preserving the
+  WordPress slug and publish date, created as published.
+- **Categories** → the categories collection, preserving the parent hierarchy.
+  Each post is assigned its **primary (first)** category.
+- **Authors** → the users collection by default (matched/created by email,
+  linked via `editor`), or the authors collection, or a fixed user.
+- **Featured + in-content images** → the media collection, original size,
+  de-duplicated across posts. When the embed is missing or a stub, the featured
+  image is re-fetched from the media endpoint; when a post has no featured image
+  at all, the first in-content image is promoted to the cover (see
+  `firstImageAsCover`), and a cover that also leads the content is removed from
+  it so the hero doesn't render twice.
+- **SEO meta** (when the target collection has a `meta` group) — `meta.title`
+  from the post title, `meta.image` from the cover image, and
+  `meta.description` from the excerpt (see `excerptToSeoDescription`).
+- **Links** — internal links to imported posts are rewritten; every other old
+  permalink gets a 301 redirect; anything unresolvable is listed in the report.
+
+## Requirements
+
+This plugin expects the following to be installed and configured in your project:
+
+- `payload` (`^3.84.1`)
+- `@payloadcms/richtext-lexical` (`^3.84.1`) — the target content field's editor.
+- `@payloadcms/ui` (`^3.84.1`) and `react` (`^19.0.0`) — the masked
+  application-password input in the admin form.
+- `@payloadcms/plugin-redirects` (`^3.84.1`) — required only when `redirects`
+  is enabled (the default); optional otherwise.
+
+```bash
+pnpm add @composius/payload-plugin-import-wordpress @payloadcms/richtext-lexical @payloadcms/ui react @payloadcms/plugin-redirects
+```
+
+You also need a target content collection with a rich text field (e.g. the
+`articles` collection from `@composius/payload-plugin-articles`), a `media`
+uploads collection, and the Payload **jobs queue** enabled to run (see
+`autoRun` below).
+
+## Usage
+
+```ts
+import { buildConfig } from 'payload'
+import { ComposiusPayloadPluginArticles } from '@composius/payload-plugin-articles'
+import { ComposiusPayloadPluginMedia } from '@composius/payload-plugin-media'
+import { ComposiusPayloadPluginImportWordpress } from '@composius/payload-plugin-import-wordpress'
+
+export default buildConfig({
+  // ...
+  plugins: [
+    ComposiusPayloadPluginMedia(),
+    ComposiusPayloadPluginArticles({ authors: true }),
+    ComposiusPayloadPluginImportWordpress({
+      // Auto-process queued imports so creating a job runs it.
+      autoRun: true,
+    }),
+  ],
+})
+```
+
+Then, in the admin panel, create a **WordPress import** document with the site
+URL (optionally a date range, a limit, or `dryRun`) and watch `status`,
+`progress` and `report` update. Or trigger programmatically:
+
+```bash
+curl -X POST /api/wp-import/start \
+  -H 'Content-Type: application/json' \
+  -b '<auth cookie>' \
+  -d '{ "sourceUrl": "https://example.com", "dryRun": true }'
+# → { "jobId": "..." }  then poll:
+curl /api/wp-import/status/<jobId>
+```
+
+## Options
+
+| Option                    | Type                                             | Default                          | Description                                                                                 |
+| ------------------------- | ------------------------------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------- |
+| `access`                  | per-operation access                             | authenticated                    | Access control for the jobs/records collections and the endpoints.                          |
+| `collections`             | `{ articles, categories, media, authors, users }`| `articles`/`categories`/`media`/`authors`/`users` | Target collection slugs.                                                  |
+| `articleUrl`              | `(slug?) => string`                              | `…/articles/<slug>`              | Builds the front-end URL used for redirects and rewritten links.                            |
+| `authorMapping`           | `{ strategy, defaultUserId, syntheticEmailDomain }` | `{ strategy: 'users', syntheticEmailDomain: 'imported.invalid' }` | `users` (default), `authors`, or `fixed`. WordPress's public REST API hides author emails, so `users` synthesizes `<author-slug>@<syntheticEmailDomain>`; set your own domain, or `false` to skip creating such users (falls back to `defaultUserId` and reports the author). |
+| `excerptToSeoDescription` | boolean                                          | `true`                           | Map the WordPress excerpt onto the article SEO `meta.description`.                           |
+| `firstImageAsCover`       | boolean                                          | `true`                           | When a post has no usable featured image, promote the first in-content image to the cover and remove it from the content. |
+| `redirects`               | boolean                                          | `true`                           | Create 301 redirects and apply `@payloadcms/plugin-redirects`.                              |
+| `fieldMap`                | article field overrides                          | `title`/`slug`/`content`/`coverImage`/`category`/`publishedAt` | Article field names the importer writes to.                    |
+| `autoRun`                 | boolean \| `{ cron, queue }`                     | `false`                          | Auto-process queued imports on a schedule (`true` = every minute).                           |
+| `dryRunPageLimit`         | number                                           | `1`                              | REST pages a dry run samples.                                                                |
+| `request`                 | `{ concurrency, timeoutMs, userAgent }`          | `{ concurrency: 5, timeoutMs: 30000 }` | HTTP tuning for WordPress fetches and image downloads.                                 |
+| `disabled`                | boolean                                          | `false`                          | Keep the collections (schema consistency) but skip endpoints, redirects and auto-run.       |
+
+## Notes
+
+- Only the **primary (first)** WordPress category is assigned to each post
+  (the `articles.category` relationship is single); the others are still created
+  in the categories collection and noted in the report.
+- The original image is recovered by stripping WordPress's `-WxH` size suffix;
+  if the original 404s the importer falls back to the URL WordPress provided.
+- Re-running (or toggling `resume`) skips already-imported items via
+  `wp-import-records`, so imports are safe to repeat.

package/dist/exports/client.d.ts

@@ -0,0 +1,10 @@
+import { TextFieldClientComponent } from 'payload';
+
+/**
+ * Renders the WordPress application-password input masked (•••) instead of as
+ * plain text, reusing Payload's own password field UI. The value is still a
+ * regular text field in the database — this only changes the input widget.
+ */
+declare const ApplicationPasswordFieldClient: TextFieldClientComponent;
+
+export { ApplicationPasswordFieldClient };

package/dist/exports/client.js

@@ -0,0 +1,10 @@
+'use client'
+
+// src/components/ApplicationPasswordField.tsx
+import { PasswordField } from "@payloadcms/ui";
+import { jsx } from "react/jsx-runtime";
+var ApplicationPasswordFieldClient = ({ field, path }) => /* @__PURE__ */ jsx(PasswordField, { autoComplete: "new-password", field, path });
+export {
+  ApplicationPasswordFieldClient
+};
+//# sourceMappingURL=client.js.map

package/dist/exports/client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/ApplicationPasswordField.tsx"],"sourcesContent":["'use client'\nimport type { TextFieldClientComponent } from 'payload'\n\nimport { PasswordField } from '@payloadcms/ui'\n\n/**\n * Renders the WordPress application-password input masked (•••) instead of as\n * plain text, reusing Payload's own password field UI. The value is still a\n * regular text field in the database — this only changes the input widget.\n */\nexport const ApplicationPasswordFieldClient: TextFieldClientComponent = ({ field, path }) => (\n  <PasswordField autoComplete=\"new-password\" field={field} path={path} />\n)\n"],"mappings":";;;AAGA,SAAS,qBAAqB;AAQ5B;AADK,IAAM,iCAA2D,CAAC,EAAE,OAAO,KAAK,MACrF,oBAAC,iBAAc,cAAa,gBAAe,OAAc,MAAY;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,182 @@
+import { Access, Config } from 'payload';
+
+type ImportAccess = {
+    create?: Access;
+    delete?: Access;
+    read?: Access;
+    update?: Access;
+};
+/** Slugs of the collections the import writes into. */
+type TargetCollections = {
+    /** Target content collection for posts. @default 'articles' */
+    articles?: string;
+    /** Taxonomy collection for categories. @default 'categories' */
+    categories?: string;
+    /** Uploads collection for images. @default 'media' */
+    media?: string;
+    /** Authors collection (used when `authorMapping.strategy` is `'authors'`). @default 'authors' */
+    authors?: string;
+    /** Users collection (used when `authorMapping.strategy` is `'users'`). @default 'users' */
+    users?: string;
+};
+type AuthorStrategy = 'authors' | 'fixed' | 'users';
+type AuthorMapping = {
+    /**
+     * How WordPress authors are mapped:
+     * - `users` (default): find-or-create in the users collection (matched by email),
+     *   linked via the article `editor` field.
+     * - `authors`: create in the authors collection, linked via the article `author` field
+     *   (requires the articles plugin to be configured with `authors: true`).
+     * - `fixed`: assign every imported article to `defaultUserId`.
+     */
+    strategy?: AuthorStrategy;
+    /** User id assigned when `strategy` is `fixed` (or as a fallback when an author has no email). */
+    defaultUserId?: number | string;
+    /**
+     * The public WordPress REST API does not expose author emails, so with the
+     * `users` strategy an email is synthesized as `<author-slug>@<domain>`.
+     * Configure the domain here, or pass `false` to skip creating users without
+     * a real email — the article then falls back to `defaultUserId` (or no
+     * editor) and the skipped author is listed in the report.
+     * @default 'imported.invalid' (a reserved TLD that can never be a real address)
+     */
+    syntheticEmailDomain?: false | string;
+};
+type AutoRunConfig = {
+    /** Cron expression for the auto-run schedule. @default '* * * * *' (every minute) */
+    cron?: string;
+    /** Queue processed by the schedule. @default 'default' */
+    queue?: string;
+};
+type FieldMap = {
+    /** Article field the post title maps to. @default 'title' */
+    title?: string;
+    /** Article field the post slug maps to. @default 'slug' */
+    slug?: string;
+    /** Article rich text field the post content maps to. @default 'content' */
+    content?: string;
+    /** Article upload field the featured image maps to. @default 'coverImage' */
+    coverImage?: string;
+    /** Article relationship field the primary category maps to. @default 'category' */
+    category?: string;
+    /** Article date field the publish date maps to. @default 'publishedAt' */
+    publishedAt?: string;
+};
+type RequestOptions = {
+    /** Per-image download concurrency. @default 5 */
+    concurrency?: number;
+    /** Per-request timeout in ms. @default 30000 */
+    timeoutMs?: number;
+    /** User-Agent header sent to WordPress. */
+    userAgent?: string;
+};
+type ComposiusPayloadPluginImportWordpressConfig = {
+    /**
+     * Access control for the import jobs/records collections, per operation.
+     * Defaults: `read`/`create`/`update`/`delete` require an authenticated user.
+     */
+    access?: ImportAccess;
+    /** Target collection slugs. Defaults: articles/categories/media/authors/users. */
+    collections?: TargetCollections;
+    /**
+     * Builds the front-end URL of an imported article from its slug. Used to
+     * rewrite internal links and as the target of created redirects.
+     * @default `${NEXT_PUBLIC_SERVER_URL || 'http://localhost:3000'}/articles/${slug}`
+     */
+    articleUrl?: (slug?: null | string) => string;
+    /** How WordPress authors are mapped. @default { strategy: 'users' } */
+    authorMapping?: AuthorMapping;
+    /** Map the WordPress excerpt onto the article SEO meta.description. @default true */
+    excerptToSeoDescription?: boolean;
+    /**
+     * When a post has no usable featured image, promote the first in-content
+     * image to the cover field and remove it from the content (themes often lead
+     * the content with the hero image instead of setting `featured_media`).
+     * @default true
+     */
+    firstImageAsCover?: boolean;
+    /**
+     * Create 301 redirects (via @payloadcms/plugin-redirects) from old WordPress
+     * permalinks to the new article URLs, and apply the redirects plugin.
+     * @default true
+     */
+    redirects?: boolean;
+    /** Override the article field names the importer writes to. */
+    fieldMap?: FieldMap;
+    /**
+     * Automatically process queued imports on a schedule so creating a job runs it
+     * without an external worker. Pass `true` for an every-minute schedule or a
+     * cron/queue config. @default false (the host app runs the jobs queue).
+     */
+    autoRun?: AutoRunConfig | boolean;
+    /** Number of REST pages a dry run samples. @default 1 */
+    dryRunPageLimit?: number;
+    /** HTTP request tuning for WordPress fetches and image downloads. */
+    request?: RequestOptions;
+    disabled?: boolean;
+};
+type ImportedItem = {
+    /** Number of the job run that imported this item. */
+    run?: number;
+    slug?: string;
+    sourceId: number;
+    targetId: number | string;
+    title?: string;
+};
+type LinkAction = 'redirect' | 'rewritten' | 'unresolved';
+type LinkMapping = {
+    action: LinkAction;
+    from: string;
+    post?: number;
+    /** Number of the job run that handled this link. */
+    run?: number;
+    to?: string;
+};
+type ImportError = {
+    message: string;
+    /** Number of the job run that hit this error. */
+    run?: number;
+    scope: string;
+    sourceId?: number;
+};
+type ImportReport = {
+    dryRun: boolean;
+    errors: ImportError[];
+    imported: {
+        authors: ImportedItem[];
+        categories: ImportedItem[];
+        media: ImportedItem[];
+        posts: ImportedItem[];
+    };
+    links: LinkMapping[];
+    remaining: {
+        posts: number;
+    };
+};
+type ImportProgress = {
+    currentPhase: string;
+    cursorPage: number;
+    importedAuthors: number;
+    importedCategories: number;
+    importedMedia: number;
+    importedPosts: number;
+    linksRewritten: number;
+    linksUnresolved: number;
+    redirectsCreated: number;
+    reusedMedia: number;
+    skippedPosts: number;
+    failedPosts: number;
+    totalPosts: number;
+};
+
+/**
+ * Imports WordPress posts (via the REST API) into a target content collection —
+ * by default the `@composius/payload-plugin-articles` `articles` collection —
+ * along with their categories, authors, featured and in-content images. Images
+ * are uploaded once and resized by the media collection; internal links are
+ * rewritten and the rest get 301 redirects. Runs on the jobs queue and is
+ * idempotent + resumable, writing a full report onto each job document.
+ */
+declare const ComposiusPayloadPluginImportWordpress: (pluginOptions?: ComposiusPayloadPluginImportWordpressConfig) => (config: Config) => Promise<Config>;
+
+export { ComposiusPayloadPluginImportWordpress, type ComposiusPayloadPluginImportWordpressConfig, type ImportProgress, type ImportReport };