@rmdes/indiekit-endpoint-micropub 1.0.0-beta.25

package/README.md

@@ -0,0 +1,76 @@
+# @rmdes/indiekit-endpoint-micropub
+
+Micropub endpoint for Indiekit. Enables publishing content to your website using the Micropub protocol.
+
+## Fork Notice
+
+This is a fork of `@indiekit/endpoint-micropub` with a fix for syndication services that require pre-syndication markup.
+
+### Issue Fixed
+
+Services like IndieNews require a `u-syndication` link in your HTML **before** they receive the syndication webmention. The upstream Micropub endpoint strips all `mp-*` properties (including `mp-syndicate-to`) before passing data to the preset's `postTemplate()`.
+
+This fork preserves `mp-syndicate-to` so that:
+1. The property reaches the preset's `postTemplate()`
+2. The preset can include it in frontmatter (as `mpSyndicateTo` in Eleventy)
+3. The theme can render the `u-syndication` link
+4. IndieNews (and similar services) can find the link when parsing the webmention
+
+### Technical Details
+
+The change is in `lib/utils.js`:
+
+```javascript
+// mp- properties to preserve for the template (needed for pre-syndication markup)
+const preserveMpProperties = ["mp-syndicate-to"];
+
+for (let key in templateProperties) {
+  if (key.startsWith("mp-") && !preserveMpProperties.includes(key)) {
+    delete templateProperties[key];
+  }
+  // ...
+}
+```
+
+## Installation
+
+```bash
+npm install @rmdes/indiekit-endpoint-micropub
+```
+
+### Using npm overrides (recommended)
+
+Add to your `package.json`:
+
+```json
+{
+  "overrides": {
+    "@indiekit/endpoint-micropub": "npm:@rmdes/indiekit-endpoint-micropub@^1.0.0-beta.25"
+  }
+}
+```
+
+This replaces the upstream package with this fork without changing your plugin configuration.
+
+## Options
+
+| Option      | Type     | Description                                                               |
+| :---------- | :------- | :------------------------------------------------------------------------ |
+| `mountPath` | `string` | Path to listen to Micropub requests. _Optional_, defaults to `/micropub`. |
+
+## Supported endpoint queries
+
+- Configuration: `/micropub?q=config`
+- Media endpoint location: `/micropub?q=media-endpoint`
+- Available syndication targets (list): `/micropub?q=syndicate-to`
+- Supported queries: `/micropub?q=config`
+- Supported vocabularies (list): `/micropub?q=post-types`
+- Publication categories (list): `/micropub?q=category`
+- Previously published posts (list): `/micropub?q=source`
+- Source content: `/micropub?q=source&url=WEBSITE_URL`
+
+List queries support `filter`, `limit` and `offset` and parameters. For example, `/micropub?q=source&filter=web&limit=10&offset=10`.
+
+## License
+
+MIT - Original work by Paul Robert Lloyd, syndication fix by Ricardo Mendes.

package/assets/icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96">
+  <path fill="#1B2" d="M0 0h96v96H0z"/>
+  <path fill="#FFF" d="M60 14a23 23 0 0 1 2 46V41.2a5 5 0 1 0-5 0v40.4a2 2 0 0 1-1 .3H37V41.3a5 5 0 1 0-5 0V82H14a2 2 0 0 1-2-2V37a23 23 0 0 1 35.5-19.3C51.1 15.4 55.4 14 60 14Z"/>
+</svg>

package/index.js

@@ -0,0 +1,33 @@
+import express from "express";
+
+import { actionController } from "./lib/controllers/action.js";
+import { queryController } from "./lib/controllers/query.js";
+
+const defaults = { mountPath: "/micropub" };
+const router = express.Router();
+
+export default class MicropubEndpoint {
+  name = "Micropub endpoint";
+
+  constructor(options = {}) {
+    this.options = { ...defaults, ...options };
+    this.mountPath = this.options.mountPath;
+  }
+
+  get routes() {
+    router.get("/", queryController);
+    router.post("/", actionController);
+
+    return router;
+  }
+
+  init(Indiekit) {
+    Indiekit.addCollection("posts");
+    Indiekit.addEndpoint(this);
+
+    // Only mount if micropub endpoint not already configured
+    if (!Indiekit.config.application.micropubEndpoint) {
+      Indiekit.config.application.micropubEndpoint = this.mountPath;
+    }
+  }
+}

package/lib/config.js

@@ -0,0 +1,82 @@
+/**
+ * Return queryable publication configuration
+ * @param {object} application - Application configuration
+ * @param {object} publication - Publication configuration
+ * @returns {object} Queryable configuration
+ */
+export const getConfig = (application, publication) => {
+  const { mediaEndpoint, url } = application;
+  const { categories, channels, postTypes, syndicationTargets } = publication;
+
+  // Supported queries
+  const q = [
+    "category",
+    "channel",
+    "config",
+    "media-endpoint",
+    "post-types",
+    "source",
+    "syndicate-to",
+  ];
+
+  // Ensure syndication targets use absolute URLs
+  const syndicateTo = syndicationTargets.map((target) => target.info);
+  for (const info of syndicateTo) {
+    if (info.service && info.service.photo) {
+      info.service.photo = new URL(info.service.photo, url).href;
+    }
+  }
+
+  return {
+    categories,
+    channels: Object.entries(channels).map(([uid, channel]) => ({
+      uid,
+      name: channel.name,
+    })),
+    "media-endpoint": mediaEndpoint,
+    "post-types": Object.values(postTypes).map((postType) => ({
+      type: postType.type,
+      name: postType.name,
+      h: postType.h,
+      properties: postType.properties,
+      "required-properties": postType["required-properties"],
+    })),
+    "syndicate-to": syndicateTo,
+    q,
+  };
+};
+
+/**
+ * Query config value
+ * @param {Array} property - Property to query
+ * @param {object} options - List options (filter, limit, offset)
+ * @param {string} [options.filter] - Value to filter items by
+ * @param {number} [options.limit] - Limit of items to return
+ * @param {number} [options.offset] - Offset to start limit of items
+ * @returns {Array} Updated config property
+ */
+export const queryConfig = (property, options) => {
+  const { filter, limit } = options;
+
+  if (!Array.isArray(property)) {
+    return property;
+  }
+
+  let properties = property || [];
+
+  if (filter) {
+    properties = properties.filter((item) => {
+      item = JSON.stringify(item);
+      item = item.toLowerCase();
+      return item.includes(filter);
+    });
+  }
+
+  if (limit) {
+    const offset = options.offset || 0;
+    properties = properties.slice(offset, offset + limit);
+    properties.length = Math.min(properties.length, limit);
+  }
+
+  return properties;
+};

package/lib/controllers/action.js

@@ -0,0 +1,141 @@
+import { IndiekitError } from "@indiekit/error";
+
+import { formEncodedToJf2, mf2ToJf2 } from "../jf2.js";
+import { uploadMedia } from "../media.js";
+import { postContent } from "../post-content.js";
+import { postData } from "../post-data.js";
+import { checkScope } from "../scope.js";
+
+/**
+ * Perform requested post action
+ * @type {import("express").RequestHandler}
+ */
+export const actionController = async (request, response, next) => {
+  const { app, body, files, query, session } = request;
+  const action = query.action || body?.action || "create";
+  const url = query.url || body?.url;
+  const { application, publication } = app.locals;
+
+  try {
+    // Check provided scope
+    const { scope, token } = session;
+    const hasScope = checkScope(scope, action);
+    if (!hasScope) {
+      throw IndiekitError.insufficientScope(
+        response.locals.__("ForbiddenError.insufficientScope"),
+        { scope: action },
+      );
+    }
+
+    // Toggle draft mode if `draft` scope
+    const draftMode = hasScope === "draft";
+
+    // Check for URL if not creating a new post
+    if (action !== "create" && !url) {
+      throw IndiekitError.badRequest(
+        response.locals.__("BadRequestError.missingParameter", "url"),
+      );
+    }
+
+    let data;
+    let jf2;
+    let content;
+    switch (action) {
+      case "create": {
+        // Create and normalise JF2 data
+        jf2 = request.is("json")
+          ? await mf2ToJf2(body, publication.enrichPostData)
+          : await formEncodedToJf2(body, publication.enrichPostData);
+
+        // Attach files
+        jf2 = files
+          ? await uploadMedia(application.mediaEndpoint, token, jf2, files)
+          : jf2;
+
+        data = await postData.create(application, publication, jf2, draftMode);
+        content = await postContent.create(publication, data);
+        break;
+      }
+
+      case "update": {
+        // Check for update operations
+        if (!(body.replace || body.add || body.remove)) {
+          throw IndiekitError.badRequest(
+            response.locals.__(
+              "BadRequestError.missingProperty",
+              "replace, add or remove operations",
+            ),
+          );
+        }
+
+        data = await postData.update(application, publication, url, body);
+
+        if (!data) {
+          content = {
+            status: 200,
+            location: url,
+            json: {
+              success: "update",
+              success_description: `Post at ${url} not updated as no properties changed`,
+            },
+          };
+          break;
+        }
+
+        // Draft mode: Only update posts that have `draft` post status
+        if (draftMode && data.properties["post-status"] !== "draft") {
+          throw IndiekitError.insufficientScope(
+            response.locals.__("ForbiddenError.insufficientScope"),
+            { scope: action },
+          );
+        }
+
+        content = await postContent.update(publication, data, url);
+        break;
+      }
+
+      case "delete": {
+        data = await postData.delete(application, publication, url);
+        content = await postContent.delete(publication, data);
+        break;
+      }
+
+      case "undelete": {
+        data = await postData.undelete(
+          application,
+          publication,
+          url,
+          draftMode,
+        );
+        content = await postContent.undelete(publication, data);
+        break;
+      }
+
+      default:
+    }
+
+    response
+      .status(content.status)
+      .location(content.location)
+      .json(content.json);
+  } catch (error) {
+    let nextError = error;
+
+    // Hoist not found error to controller to localise response
+    if (error.name === "NotFoundError") {
+      nextError = IndiekitError.notFound(
+        response.locals.__("NotFoundError.record", error.message),
+      );
+    }
+
+    // Hoist unsupported post type error to controller to localise response
+    if (error.name === "NotImplementedError") {
+      nextError = IndiekitError.notImplemented(
+        response.locals.__("NotImplementedError.postType", error.message),
+        { uri: "https://getindiekit.com/configuration/post-types" },
+      );
+    }
+
+    return next(nextError);
+  }
+};

package/lib/controllers/query.js

@@ -0,0 +1,117 @@
+import { IndiekitError } from "@indiekit/error";
+import { getCursor } from "@indiekit/util";
+
+import { getConfig, queryConfig } from "../config.js";
+import { getMf2Properties, jf2ToMf2 } from "../mf2.js";
+
+/**
+ * Query published posts
+ * @type {import("express").RequestHandler}
+ */
+export const queryController = async (request, response, next) => {
+  const { application, publication } = request.app.locals;
+  const postsCollection = application?.collections?.get("posts");
+
+  try {
+    const config = getConfig(application, publication);
+    const limit = Number(request.query.limit) || 0;
+    const offset = Number(request.query.offset) || 0;
+    let { after, before, filter, properties, q, url } = request.query;
+
+    if (!q) {
+      throw IndiekitError.badRequest(
+        response.locals.__("BadRequestError.missingParameter", "q"),
+      );
+    }
+
+    // `category` param is used to query `categories` configuration property
+    q = q === "category" ? "categories" : String(q);
+
+    // `channel` param is used to query `channels` configuration property
+    q = q === "channel" ? "channels" : String(q);
+
+    switch (q) {
+      case "config": {
+        response.json(config);
+
+        break;
+      }
+
+      case "source": {
+        if (url) {
+          // Return mf2 for a given URL (optionally filtered by properties)
+          let postData;
+
+          if (postsCollection) {
+            postData = await postsCollection.findOne({
+              "properties.url": url,
+            });
+          }
+
+          if (!postData) {
+            throw IndiekitError.badRequest(
+              response.locals.__("BadRequestError.missingResource", "post"),
+            );
+          }
+
+          const mf2 = jf2ToMf2(postData);
+          response.json(getMf2Properties(mf2, properties));
+        } else {
+          // Return mf2 for published posts
+          let cursor = {
+            items: [],
+            hasNext: false,
+            hasPrev: false,
+          };
+
+          if (postsCollection) {
+            cursor = await getCursor(postsCollection, after, before, limit);
+          }
+
+          const items = [];
+          for (let item of cursor.items) {
+            if (item.properties) {
+              items.push(jf2ToMf2(item));
+            } else {
+              /**
+               * @todo Consider better way to handle item with no properties
+               * - notify user and remove item from database?
+               * - notify user and don’t delete item from database?
+               * - fail silently?
+               */
+              console.warn(`Item ignored because it has no properties`, item);
+            }
+          }
+
+          response.json({
+            items,
+            paging: {
+              ...(cursor.hasNext && { after: cursor.lastItem }),
+              ...(cursor.hasPrev && { before: cursor.firstItem }),
+            },
+          });
+        }
+
+        break;
+      }
+
+      default: {
+        // Query configuration value (can be filtered, limited and offset)
+        if (config[q]) {
+          response.json({
+            [q]: queryConfig(config[q], { filter, limit, offset }),
+          });
+        } else {
+          throw IndiekitError.notImplemented(
+            response.locals.__("NotImplementedError.query", {
+              key: "q",
+              value: q,
+            }),
+          );
+        }
+      }
+    }
+  } catch (error) {
+    next(error);
+  }
+};