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

package/lib/post-data.js

@@ -0,0 +1,285 @@
+import { isDeepStrictEqual } from "node:util";
+
+import { IndiekitError } from "@indiekit/error";
+import { getCanonicalUrl, getDate } from "@indiekit/util";
+import makeDebug from "debug";
+
+import { getSyndicateToProperty, normaliseProperties } from "./jf2.js";
+import { getPostType } from "./post-type-discovery.js";
+import * as updateMf2 from "./update.js";
+import { getPostTemplateProperties, renderPath } from "./utils.js";
+
+const debug = makeDebug("indiekit:endpoint-micropub:post-data");
+
+export const postData = {
+  /**
+   * Create post data
+   * @param {object} application - Application configuration
+   * @param {object} publication - Publication configuration
+   * @param {object} properties - JF2 properties
+   * @param {boolean} [draftMode] - Draft mode
+   * @returns {Promise<object>} Post data
+   */
+  async create(application, publication, properties, draftMode = false) {
+    debug(`Create %O`, { draftMode, properties });
+
+    const { timeZone } = application;
+    const { me, postTypes, syndicationTargets } = publication;
+
+    // Add syndication targets
+    const syndicateTo = getSyndicateToProperty(properties, syndicationTargets);
+    if (syndicateTo) {
+      properties["mp-syndicate-to"] = syndicateTo;
+    }
+
+    // Normalise properties
+    properties = normaliseProperties(publication, properties, timeZone);
+
+    // Post type
+    const type = getPostType(postTypes, properties);
+    properties["post-type"] = type;
+
+    // Get post type configuration
+    const typeConfig = postTypes[type];
+    if (!typeConfig || !typeConfig.post?.path) {
+      throw IndiekitError.notImplemented(type);
+    }
+
+    // Post paths
+    const path = await renderPath(
+      typeConfig.post.path,
+      properties,
+      application,
+      publication,
+    );
+    const url = await renderPath(
+      typeConfig.post.url || typeConfig.post.path,
+      properties,
+      application,
+      publication,
+    );
+    properties.url = getCanonicalUrl(url, me);
+
+    // Post status
+    // Draft mode: Only create post with a `draft` post-status
+    properties["post-status"] = draftMode
+      ? "draft"
+      : properties["post-status"] || "published";
+
+    const postData = { path, properties };
+
+    // Add data to posts collection (or replace existing if present)
+    const postsCollection = application?.collections?.get("posts");
+    if (postsCollection) {
+      const query = { "properties.url": properties.url };
+      await postsCollection.replaceOne(query, postData, { upsert: true });
+    }
+
+    return postData;
+  },
+
+  /**
+   * Read post data
+   * @param {object} application - Application configuration
+   * @param {string} url - URL of existing post
+   * @returns {Promise<object>} Post data
+   */
+  async read(application, url) {
+    debug(`Read ${url}`);
+
+    const query = { "properties.url": url };
+    const postsCollection = application?.collections?.get("posts");
+
+    const postData = await postsCollection.findOne(query);
+    if (!postData) {
+      throw IndiekitError.notFound(url);
+    }
+
+    return postData;
+  },
+
+  /**
+   * Update post data
+   *
+   * Add, delete or replace properties and/or replace property values
+   * @param {object} application - Application configuration
+   * @param {object} publication - Publication configuration
+   * @param {string} url - URL of existing post
+   * @param {object} operation - Requested operation(s)
+   * @returns {Promise<object>} Post data
+   */
+  async update(application, publication, url, operation) {
+    debug(`Update ${url} %O`, { operation });
+
+    const { timeZone } = application;
+    const { me, postTypes } = publication;
+    const postsCollection = application?.collections?.get("posts");
+
+    // Read properties
+    let { path: _originalPath, properties } = await this.read(application, url);
+
+    // Save incoming properties for later comparison
+    let oldProperties = structuredClone(properties);
+
+    // Add properties
+    if (operation.add) {
+      properties = updateMf2.addProperties(properties, operation.add);
+    }
+
+    // Replace property entries
+    if (operation.replace) {
+      properties = await updateMf2.replaceEntries(
+        properties,
+        operation.replace,
+      );
+    }
+
+    // Remove properties and/or property entries
+    if (operation.delete) {
+      properties = Array.isArray(operation.delete)
+        ? updateMf2.deleteProperties(properties, operation.delete)
+        : updateMf2.deleteEntries(properties, operation.delete);
+    }
+
+    // Normalise properties
+    properties = normaliseProperties(publication, properties, timeZone);
+    oldProperties = normaliseProperties(publication, oldProperties, timeZone);
+
+    // Post type
+    const type = getPostType(postTypes, properties);
+    const typeConfig = postTypes[type];
+    properties["post-type"] = type;
+
+    // Post paths
+    const path = await renderPath(
+      typeConfig.post.path,
+      properties,
+      application,
+      publication,
+    );
+    const updatedUrl = await renderPath(
+      typeConfig.post.url,
+      properties,
+      application,
+      publication,
+    );
+    properties.url = getCanonicalUrl(updatedUrl, me);
+
+    // Return if no changes to template properties detected
+    const newProperties = getPostTemplateProperties(properties);
+    oldProperties = getPostTemplateProperties(oldProperties);
+    if (isDeepStrictEqual(newProperties, oldProperties)) {
+      return;
+    }
+
+    // Add updated date
+    properties.updated = getDate(timeZone);
+
+    // Update data in posts collection
+    const postData = { _originalPath, path, properties };
+    const query = { "properties.url": url };
+    await postsCollection.replaceOne(query, postData);
+
+    return postData;
+  },
+
+  /**
+   * Delete post data
+   *
+   * Delete (most) properties, keeping a record of deleted for later retrieval
+   * @param {object} application - Application configuration
+   * @param {object} publication - Publication configuration
+   * @param {string} url - URL of existing post
+   * @returns {Promise<object>} Post data
+   */
+  async delete(application, publication, url) {
+    debug(`Delete ${url}`);
+
+    const { timeZone } = application;
+    const { postTypes } = publication;
+    const postsCollection = application?.collections?.get("posts");
+
+    // Read properties
+    const { properties } = await this.read(application, url);
+
+    // Make a copy of existing properties
+    const _deletedProperties = structuredClone(properties);
+
+    // Delete all properties, except those required for path creation
+    for (const key in _deletedProperties) {
+      if (!["post-type", "published", "slug", "type", "url"].includes(key)) {
+        delete properties[key];
+      }
+    }
+
+    // Add deleted date
+    properties.deleted = getDate(timeZone);
+
+    // Post type
+    const type = properties["post-type"];
+    const typeConfig = postTypes[type];
+
+    // Post paths
+    const path = await renderPath(
+      typeConfig.post.path,
+      properties,
+      application,
+      publication,
+    );
+
+    // Update data in posts collection
+    const postData = { path, properties, _deletedProperties };
+    const query = { "properties.url": url };
+    await postsCollection.replaceOne(query, postData);
+
+    return postData;
+  },
+
+  /**
+   * Undelete post data
+   *
+   * Restore previously deleted properties
+   * @param {object} application - Application configuration
+   * @param {object} publication - Publication configuration
+   * @param {string} url - URL of existing post
+   * @param {boolean} [draftMode] - Draft mode
+   * @returns {Promise<object>} Post data
+   */
+  async undelete(application, publication, url, draftMode) {
+    debug(`Undelete ${url} %O`, { draftMode });
+
+    const { postTypes } = publication;
+    const postsCollection = application?.collections?.get("posts");
+
+    // Read deleted properties
+    const { _deletedProperties } = await this.read(application, url);
+
+    // Restore previously deleted properties
+    const properties = _deletedProperties;
+
+    // Post type
+    const type = properties["post-type"];
+    const typeConfig = postTypes[type];
+
+    // Post paths
+    const path = await renderPath(
+      typeConfig.post.path,
+      properties,
+      application,
+      publication,
+    );
+
+    // Post status
+    // Draft mode: Only restore post with a `draft` post-status
+    properties["post-status"] = draftMode
+      ? "draft"
+      : properties["post-status"] || "published";
+
+    // Update data in posts collection
+    const postData = { path, properties };
+    const query = { "properties.url": url };
+    await postsCollection.replaceOne(query, postData);
+
+    return postData;
+  },
+};

package/lib/post-type-count.js

@@ -0,0 +1,49 @@
+import { getObjectId } from "@indiekit/util";
+
+export const postTypeCount = {
+  /**
+   * Count the number of posts of a given type
+   * @param {object} postsCollection - Posts database collection
+   * @param {object} properties - JF2 properties
+   * @returns {Promise<object>} Post count
+   */
+  async get(postsCollection, properties) {
+    if (!postsCollection || !postsCollection.count()) {
+      console.warn("No database configuration provided");
+      console.info(
+        "See https://getindiekit.com/configuration/application/#mongodburl",
+      );
+
+      return;
+    }
+
+    // Post type
+    const postType = properties["post-type"];
+    const postUid = properties.uid;
+    const startDate = new Date(new Date(properties.published).toDateString());
+    const endDate = new Date(startDate);
+    endDate.setDate(endDate.getDate() + 1);
+    const response = await postsCollection
+      .aggregate([
+        {
+          $addFields: {
+            convertedDate: {
+              $toDate: "$properties.published",
+            },
+          },
+        },
+        {
+          $match: {
+            _id: getObjectId(postUid),
+            "properties.post-type": postType,
+            convertedDate: {
+              $gte: startDate,
+              $lt: endDate,
+            },
+          },
+        },
+      ])
+      .toArray();
+    return response.length;
+  },
+};

package/lib/post-type-discovery.js

@@ -0,0 +1,68 @@
+/**
+ * Accepts a JF2 object and attempts to determine the post type
+ * @param {object} postTypes - Configured post types
+ * @param {object} properties - JF2 properties
+ * @returns {string|null} The post type or null if unknown
+ * @see {@link https://ptd.spec.indieweb.org/#algorithm}
+ */
+export const getPostType = (postTypes, properties) => {
+  const propertiesMap = new Map(Object.entries(properties));
+
+  // If post has the event type, it’s an event
+  if (properties.type && properties.type === "event") {
+    return properties.type;
+  }
+
+  const basePostTypes = new Map([
+    ["rsvp", "rsvp"],
+    ["repost", "repost-of"],
+    ["like", "like-of"],
+    ["reply", "in-reply-to"],
+    ["video", "video"],
+    ["photo", "photo"],
+  ]);
+
+  // Types defined in Post Type Discovery specification
+
+  // Types defined in post type configuration
+  for (const [type, { discovery }] of Object.entries(postTypes)) {
+    if (!discovery) {
+      continue;
+    }
+
+    basePostTypes.set(type, discovery);
+  }
+
+  for (const basePostType of basePostTypes) {
+    if (propertiesMap.has(basePostType[1])) {
+      return basePostType[0];
+    }
+  }
+
+  // If has `children` property that is populated, is collection type
+  if (
+    properties.children &&
+    Array.isArray(properties.children) &&
+    properties.children.length > 0
+  ) {
+    return "collection";
+  }
+
+  // Use summary value for content if no content value
+  let content;
+  if (propertiesMap.has("content")) {
+    content =
+      properties.content.text || properties.content.html || properties.content;
+  } else if (propertiesMap.has("summary")) {
+    content = properties.summary;
+  }
+
+  // If post has `name` and content, it’s an article
+  // This is a deviation from the Post Type Algorithm, which identifies a post
+  // as a note if the content is prefixed with the `name` value.
+  if (properties.name && content) {
+    return "article";
+  }
+
+  return "note";
+};

package/lib/reserved-properties.js

@@ -0,0 +1,10 @@
+/**
+ * Reserved body property names
+ * @see {@link https://micropub.spec.indieweb.org/#reserved-properties}
+ */
+export const reservedProperties = Object.freeze([
+  "access_token",
+  "h",
+  "action",
+  "url",
+]);

package/lib/scope.js

@@ -0,0 +1,36 @@
+/**
+ * Check provided scope(s) satisfies required scope
+ * @param {string} scope - Provided scope (space separated)
+ * @param {string} [action] - Required action
+ * @returns {boolean|string} `true` if provided scope includes action,
+ *                           `draft` if draft scope, otherwise `false`
+ */
+export const checkScope = (scope, action = "create") => {
+  // Default scope request is `create`
+  if (!scope) {
+    scope = "create";
+  }
+
+  // Undeleting a post is equivalent to creating a post
+  if (action === "undelete") {
+    action = "create";
+  }
+
+  // Check for scope matching desired action
+  let hasScope = scope.includes(action);
+
+  // Handle deprecated `post` scope
+  if (!hasScope && action === "create") {
+    hasScope = scope.includes("post");
+  }
+
+  // Check for draft scope
+  const draftScope = scope.includes("draft");
+
+  // Can create/update with `draft` scope, but using draft post status
+  if (draftScope && (action === "create" || action === "update")) {
+    hasScope = "draft";
+  }
+
+  return hasScope;
+};

package/lib/update.js

@@ -0,0 +1,129 @@
+import _ from "lodash";
+
+import { mf2ToJf2 } from "./jf2.js";
+
+/**
+ * Add properties to object
+ * @param {object} object - Object to update
+ * @param {object} additions - Properties to add (mf2)
+ * @returns {object|undefined} Updated object
+ */
+export const addProperties = (object, additions) => {
+  for (const key in additions) {
+    if (Object.prototype.hasOwnProperty.call(additions, key)) {
+      const newValue = additions[key];
+      let existingValue = object[key];
+
+      // If no existing value, add it
+      if (!existingValue) {
+        object[key] = newValue;
+        return object;
+      }
+
+      // If existing value, add to it
+      if (existingValue) {
+        existingValue = Array.isArray(existingValue)
+          ? existingValue
+          : [existingValue];
+
+        const updatedValue = [...existingValue];
+
+        for (const value of newValue) {
+          updatedValue.push(value);
+        }
+
+        object = _.set(object, key, updatedValue);
+        return object;
+      }
+    }
+  }
+};
+
+/**
+ * Replace entries of a property. If property doesn’t exist, create it.
+ * @param {object} object - Object to update
+ * @param {object} replacements - Properties to replace (mf2)
+ * @returns {Promise<object>} Updated object (JF2)
+ */
+export const replaceEntries = async (object, replacements) => {
+  for await (const [key, value] of Object.entries(replacements)) {
+    if (!Array.isArray(value)) {
+      throw new TypeError("Replacement value should be an array");
+    }
+
+    // Replacement given as mf2, but data stored as JF2
+    switch (value.length) {
+      case 0: {
+        // Array is empty, don’t perform replacement
+        continue;
+      }
+
+      case 1: {
+        // Array contains a single value, save as JF2
+        const jf2 = await mf2ToJf2(value[0], false);
+        object = _.set(object, key, jf2);
+        break;
+      }
+
+      default: {
+        // Array contains multiple values, save as array
+        object = _.set(object, key, value);
+        break;
+      }
+    }
+  }
+
+  return object;
+};
+
+/**
+ * Delete entries for properties of object
+ * @param {object} object - Object to update
+ * @param {object} deletions - Property entries to delete (mf2)
+ * @returns {object} Updated object
+ */
+export const deleteEntries = (object, deletions) => {
+  for (const key in deletions) {
+    if (Object.prototype.hasOwnProperty.call(deletions, key)) {
+      const valuesToDelete = deletions[key];
+
+      if (!Array.isArray(valuesToDelete)) {
+        throw new TypeError(`${key} should be an array`);
+      }
+
+      const values = object[key];
+      if (!valuesToDelete || !values) {
+        return object;
+      }
+
+      for (const value of valuesToDelete) {
+        const index = values.indexOf(value);
+        if (index !== -1) {
+          values.splice(index, 1);
+        }
+
+        if (values.length === 0) {
+          delete object[key]; // Delete property if no values remain
+        } else {
+          object[key] = values;
+        }
+      }
+    }
+  }
+
+  return object;
+};
+
+/**
+ * Delete properties of object
+ * @param {object} object - Object to update
+ * @param {Array} deletions - Properties to delete (mf2)
+ * @returns {object} Updated object
+ */
+export const deleteProperties = (object, deletions) => {
+  for (const key of deletions) {
+    delete object[key];
+  }
+
+  return object;
+};

package/lib/utils.js

@@ -0,0 +1,121 @@
+import { dateTokens, formatDate, isDate, supplant } from "@indiekit/util";
+import newbase60 from "newbase60";
+
+import { postTypeCount } from "./post-type-count.js";
+
+/**
+ * Decode form-encoded query parameter
+ * @param {string} value - Parameter value to decode
+ * @returns {string} Decoded string, else original parameter value
+ * @example decodeQueryParameter(['foo', 'bar']) => ['foo', 'bar']
+ * @example decodeQueryParameter('2024-02-14T13:24:00+0100') => '2024-02-14T13:24:00+0100'
+ * @example decodeQueryParameter('https%3A%2F%2Ffoo.bar') => 'https://foo.bar'
+ * @example decodeQueryParameter('foo+bar') => 'foo bar'
+ */
+export const decodeQueryParameter = (value) => {
+  if (typeof value !== "string") {
+    return value;
+  }
+
+  return isDate(value)
+    ? decodeURIComponent(value)
+    : decodeURIComponent(value.replaceAll("+", " "));
+};
+
+/**
+ * Get post template properties
+ * @param {object} properties - JF2 properties
+ * @returns {object} Template properties
+ */
+export const getPostTemplateProperties = (properties) => {
+  const templateProperties = structuredClone(properties);
+
+  // mp- properties to preserve for the template (needed for pre-syndication markup)
+  // mp-syndicate-to must appear in frontmatter so themes can render u-syndication
+  // links BEFORE the syndication webmention is sent (required by IndieNews, etc.)
+  const preserveMpProperties = ["mp-syndicate-to"];
+
+  for (let key in templateProperties) {
+    // Remove server commands from post template properties
+    // Exception: preserve mp-syndicate-to for pre-syndication u-syndication links
+    if (key.startsWith("mp-") && !preserveMpProperties.includes(key)) {
+      delete templateProperties[key];
+    }
+
+    // Remove post-type property, only needed internally
+    if (key === "post-type") {
+      delete templateProperties["post-type"];
+    }
+  }
+
+  return templateProperties;
+};
+
+/**
+ * Render relative path if URL is on publication
+ * @param {string} url - External URL
+ * @param {string} me - Publication URL
+ * @returns {string} Path
+ */
+export const relativeMediaPath = (url, me) =>
+  url.includes(me) ? url.replace(me, "") : url;
+
+/**
+ * Render path from URI template and properties
+ * @param {string} path - URI template path
+ * @param {object} properties - JF2 properties
+ * @param {object} application - Application configuration
+ * @param {object} publication - Publication configuration
+ * @returns {Promise<string>} Path
+ */
+export const renderPath = async (
+  path,
+  properties,
+  application,
+  publication,
+) => {
+  const dateObject = new Date(properties.published);
+  const { timeZone } = Intl.DateTimeFormat().resolvedOptions();
+  const { slugSeparator } = publication;
+  let tokens = {};
+
+  // Add date tokens
+  for (const dateToken of dateTokens) {
+    tokens[dateToken] = formatDate(properties.published, dateToken, {
+      locale: application.locale,
+      timeZone:
+        application.timeZone === "server" ? timeZone : application.timeZone,
+      useAdditionalDayOfYearTokens: true,
+    });
+  }
+
+  // Add day of the year (NewBase60) token
+  tokens.D60 = newbase60.DateToSxg(dateObject);
+
+  // Add count of post-type for the day
+  const postsCollection = application?.collections?.get("posts");
+  const count = await postTypeCount.get(postsCollection, properties);
+  tokens.n = count + 1;
+
+  // Add slug token
+  tokens.slug = properties.slug;
+
+  // Add channel token
+  if (properties.channel) {
+    tokens.channel = Array.isArray(properties.channel)
+      ? properties.channel.join(slugSeparator)
+      : properties.channel;
+  }
+
+  // Populate URI template path with properties
+  path = supplant(path, tokens);
+
+  return path;
+};
+
+/**
+ * Convert string to array if not already an array
+ * @param {string|Array} object - String or array to convert
+ * @returns {Array} Array
+ */
+export const toArray = (object) => (Array.isArray(object) ? object : [object]);