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

package/lib/jf2.js

@@ -0,0 +1,318 @@
+import { excerpt, getDate, md5, slugify } from "@indiekit/util";
+import {
+  fetchReferences,
+  mf2tojf2,
+  mf2tojf2referenced,
+} from "@paulrobertlloyd/mf2tojf2";
+
+import { markdownToHtml, htmlToMarkdown } from "./markdown.js";
+import { reservedProperties } from "./reserved-properties.js";
+import { decodeQueryParameter, relativeMediaPath, toArray } from "./utils.js";
+
+/**
+ * Create JF2 object from form-encoded request
+ * @param {object} body - Form-encoded request body
+ * @param {boolean} [requestReferences] - Request data for any referenced URLs
+ * @returns {Promise<object>} Micropub action
+ */
+export const formEncodedToJf2 = async (body, requestReferences) => {
+  const jf2 = {
+    type: body.h || "entry",
+  };
+
+  for (const key in body) {
+    if (Object.prototype.hasOwnProperty.call(body, key)) {
+      // Delete reserved properties
+      const isReservedProperty = reservedProperties.includes(key);
+      if (isReservedProperty) {
+        delete body[key];
+        continue;
+      }
+
+      // Add decoded string value to JF2 object
+      jf2[key] = decodeQueryParameter(body[key]);
+    }
+  }
+
+  if (requestReferences) {
+    return fetchReferences(jf2);
+  }
+
+  return jf2;
+};
+
+/**
+ * Convert mf2 to JF2
+ * @param {object} body - Form-encoded request body
+ * @param {boolean} [requestReferences] - Request data for any referenced URLs
+ * @returns {Promise<object>} Micropub action
+ */
+export const mf2ToJf2 = async (body, requestReferences) => {
+  const mf2 = {
+    items: [body],
+  };
+
+  if (requestReferences) {
+    return mf2tojf2referenced(mf2);
+  }
+
+  return mf2tojf2(mf2);
+};
+
+/**
+ * Normalise JF2 properties
+ * @param {object} publication - Publication configuration
+ * @param {object} properties - JF2 properties
+ * @param {string} timeZone - Application time zone
+ * @returns {object} Normalised JF2 properties
+ */
+export const normaliseProperties = (publication, properties, timeZone) => {
+  const { channels, me, slugSeparator } = publication;
+
+  properties.published = getDate(timeZone, properties.published);
+
+  if (properties.name) {
+    properties.name = properties.name.trim();
+  }
+
+  if (properties.content) {
+    properties.content = getContentProperty(properties);
+  }
+
+  if (properties.location) {
+    properties.location = getLocationProperty(properties);
+  }
+
+  if (properties.audio) {
+    properties.audio = getAudioProperty(properties, me);
+  }
+
+  if (properties.photo) {
+    properties.photo = getPhotoProperty(properties, me);
+  }
+
+  if (properties.video) {
+    properties.video = getVideoProperty(properties, me);
+  }
+
+  properties.slug = getSlugProperty(properties, slugSeparator);
+
+  const publicationHasChannels = channels && Object.keys(channels).length > 0;
+  if (publicationHasChannels) {
+    properties.channel = getChannelProperty(properties, channels);
+    delete properties["mp-channel"];
+  }
+
+  if (properties["mp-syndicate-to"]) {
+    properties["mp-syndicate-to"] = toArray(properties["mp-syndicate-to"]);
+  }
+
+  if (properties.syndication) {
+    properties.syndication = toArray(properties.syndication);
+  }
+
+  return properties;
+};
+
+/**
+ * Get audio property
+ * @param {object} properties - JF2 properties
+ * @param {object} me - Publication URL
+ * @returns {Array} `audio` property
+ */
+export const getAudioProperty = (properties, me) => {
+  let { audio } = properties;
+  audio = Array.isArray(audio) ? audio : [audio];
+
+  return audio.map((item) => ({
+    url: relativeMediaPath(item.url || item, me),
+  }));
+};
+
+/**
+ * Get channel property.
+ *
+ * If a publication has configured channels, but no channel has been selected,
+ * the default channel is used.
+ *
+ * If `mp-channel` provides a UID that does not appear in the publication’s
+ * channels, the default channel is used.
+ *
+ * The first item in a publication’s configured channels is considered the
+ * default channel.
+ * @param {object} properties - JF2 properties
+ * @param {object} channels - Publication channels
+ * @returns {Array} `mp-channel` property
+ * @see {@link https://github.com/indieweb/micropub-extensions/issues/40}
+ */
+export const getChannelProperty = (properties, channels) => {
+  channels = Object.keys(channels);
+  const mpChannel = properties["mp-channel"];
+  const providedChannels = Array.isArray(mpChannel) ? mpChannel : [mpChannel];
+  const selectedChannels = new Set();
+
+  // Only select channels that have been configured
+  for (const uid of providedChannels) {
+    if (channels.includes(uid)) {
+      selectedChannels.add(uid);
+    }
+  }
+
+  // If no channels provided, use default channel UID
+  if (selectedChannels.size === 0) {
+    const defaultChannel = channels[0];
+    selectedChannels.add(defaultChannel);
+  }
+
+  return toArray([...selectedChannels]);
+};
+
+/**
+ * Get content property.
+ *
+ * JF2 allows for the provision of both plaintext and HTML representations.
+ * Use existing values, or add HTML representation if only plaintext provided.
+ * @param {object} properties - JF2 properties
+ * @returns {object} `content` property
+ * @see {@link https://www.w3.org/TR/jf2/#html-content}
+ */
+export const getContentProperty = (properties) => {
+  const { content } = properties;
+  let { html, text } = content;
+
+  // Return existing text and HTML representations, unamended
+  if (html && text) {
+    return { html, text };
+  }
+
+  // If HTML representation only, add text representation
+  if (html && !text) {
+    return { html, text: htmlToMarkdown(html) };
+  }
+
+  // If text representation only, add HTML representation
+  if (!html && text) {
+    return { html: markdownToHtml(text), text };
+  }
+
+  // If content is a string, add `html` and move plaintext to `text.
+  if (typeof content === "string") {
+    text = content;
+    html = markdownToHtml(content);
+  }
+
+  return { html, text };
+};
+
+/**
+ * Get location property, parsing a Geo URI if provided
+ * @param {object|string} properties - JF2 properties
+ * @returns {object} `location` property
+ */
+export const getLocationProperty = (properties) => {
+  let { location } = properties;
+
+  if (typeof location === "string" && location.startsWith("geo:")) {
+    const geoUriRegexp =
+      /geo:(?<latitude>[\d+.?-]*),(?<longitude>[\d+.?-]*)(?:,(?<altitude>[\d+.?-]*))?/;
+    const { latitude, longitude, altitude } =
+      location.match(geoUriRegexp).groups;
+
+    location = {
+      type: "geo",
+      latitude,
+      longitude,
+      ...(altitude ? { altitude } : {}),
+    };
+  }
+
+  return location;
+};
+
+/**
+ * Get photo property (adding text alternatives where provided)
+ * @param {object} properties - JF2 properties
+ * @param {object} me - Publication URL
+ * @returns {Array} `photo` property
+ */
+export const getPhotoProperty = (properties, me) => {
+  let { photo } = properties;
+  photo = Array.isArray(photo) ? photo : [photo];
+
+  let photoAlt = properties["mp-photo-alt"];
+  if (photoAlt) {
+    photoAlt = Array.isArray(photoAlt) ? photoAlt : [photoAlt];
+  }
+
+  const property = photo.map((item, index) => ({
+    url: relativeMediaPath(item.url || item, me),
+    ...(item.alt && { alt: item.alt.trim() }),
+    ...(photoAlt && { alt: photoAlt[index].trim() }),
+  }));
+  delete properties["mp-photo-alt"];
+  return property;
+};
+
+/**
+ * Get video property
+ * @param {object} properties - JF2 properties
+ * @param {object} me - Publication URL
+ * @returns {Array} `video` property
+ */
+export const getVideoProperty = (properties, me) => {
+  let { video } = properties;
+  video = Array.isArray(video) ? video : [video];
+
+  return video.map((item) => ({
+    url: relativeMediaPath(item.url || item, me),
+  }));
+};
+
+/**
+ * Get slug
+ * @param {object} properties - JF2 properties
+ * @param {string} separator - Slug separator
+ * @returns {string} Array containing slug value
+ */
+export const getSlugProperty = (properties, separator) => {
+  const suggested = properties["mp-slug"];
+  const { name, published } = properties;
+
+  let string;
+  if (suggested) {
+    string = suggested;
+  } else if (name) {
+    string = excerpt(name, 5);
+  } else {
+    string = md5(published).slice(0, 5);
+  }
+
+  return slugify(string, { separator });
+};
+
+/**
+ * Get `mp-syndicate-to` property
+ * @param {object} properties - JF2 properties
+ * @param {Array} syndicationTargets - Configured syndication targets
+ * @returns {Array|undefined} Resolved syndication targets
+ */
+export const getSyndicateToProperty = (properties, syndicationTargets) => {
+  const property = [];
+
+  if (!syndicationTargets || syndicationTargets.length === 0) {
+    return;
+  }
+
+  for (const target of syndicationTargets) {
+    const { uid } = target.info;
+    const syndicateTo = properties["mp-syndicate-to"];
+
+    if (syndicateTo?.includes(uid)) {
+      property.push(uid);
+    }
+  }
+
+  if (property.length > 0) {
+    return property;
+  }
+};

package/lib/markdown.js

@@ -0,0 +1,56 @@
+import markdownIt from "markdown-it";
+import TurndownService from "turndown";
+
+/**
+ * Convert Markdown to HTML
+ * @param {string} string - Markdown
+ * @returns {string} HTML
+ */
+export const markdownToHtml = (string) => {
+  const options = {
+    html: true,
+    breaks: true,
+    typographer: true,
+  };
+
+  const parser = markdownIt(options);
+
+  const html = parser.render(string).trim();
+
+  return html;
+};
+
+/**
+ * Convert HTML to Markdown
+ * @param {string} string - String (may be HTML or Markdown)
+ * @returns {string} Markdown
+ */
+export const htmlToMarkdown = (string) => {
+  // Normalise text as HTML before converting to Markdown
+  string = markdownToHtml(string);
+
+  const options = {
+    codeBlockStyle: "fenced",
+    emDelimiter: "*",
+    headingStyle: "atx",
+  };
+
+  const turndownService = new TurndownService(options);
+
+  /**
+   * Disable escaping of Markdown characters
+   * @param {string} string - String
+   * @returns {string} String
+   * @see {@link https://github.com/mixmark-io/turndown#escaping-markdown-characters}
+   */
+  turndownService.escape = (string) => string;
+
+  /**
+   * List of inline elements to keep in Markdown
+   */
+  turndownService.keep(["cite", "del", "ins"]);
+
+  const markdown = turndownService.turndown(string);
+
+  return markdown;
+};

package/lib/media.js

@@ -0,0 +1,45 @@
+/**
+ * Upload attached file(s) via media endpoint
+ * @param {string} mediaEndpoint - Media endpoint URL
+ * @param {string} token - Bearer token
+ * @param {object} properties - JF2 properties
+ * @param {object} files - Files to upload
+ * @returns {Promise<object>} Uploaded file locations
+ */
+export const uploadMedia = async (mediaEndpoint, token, properties, files) => {
+  for await (let [mediaProperty, media] of Object.entries(files)) {
+    // Media property may contain one or many media files
+    media = Array.isArray(media) ? media : [media];
+
+    for await (const file of media) {
+      const { data, name } = file;
+
+      // Create multipart/form-data
+      const formData = new FormData();
+      formData.append("file", new Blob([data]), name);
+
+      // Upload file via media endpoint
+      const response = await fetch(mediaEndpoint, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${token}`,
+        },
+        body: formData,
+      });
+
+      if (!response.ok) {
+        /** @type {object} */
+        const body = await response.json();
+
+        const message = body.error_description || response.statusText;
+        throw new Error(message);
+      }
+
+      // Update respective media property with location of upload
+      properties[mediaProperty] = properties[mediaProperty] || [];
+      properties[mediaProperty].push(response.headers.get("location"));
+    }
+  }
+
+  return properties;
+};

package/lib/mf2.js

@@ -0,0 +1,80 @@
+/**
+ * Return mf2 properties of a post
+ * @param {object} mf2 - mf2 object
+ * @param {Array<string>|string} requestedProperties - mf2 properties to select
+ * @returns {Promise<object>} mf2 with requested properties
+ */
+export const getMf2Properties = (mf2, requestedProperties) => {
+  if (!requestedProperties) {
+    return mf2;
+  }
+
+  const item = mf2.items ? mf2.items[0] : mf2;
+  const { properties } = item;
+
+  // Return requested properties
+  if (requestedProperties) {
+    requestedProperties = Array.isArray(requestedProperties)
+      ? requestedProperties
+      : [requestedProperties];
+
+    const selectedProperties = {};
+
+    for (const key of requestedProperties) {
+      if (properties[key]) {
+        selectedProperties[key] = properties[key];
+      }
+    }
+
+    item.properties = selectedProperties;
+  }
+
+  // Return properties
+  delete item.type;
+  return item;
+};
+
+/**
+ * Convert JF2 post data to mf2
+ * @param {object} postData - Post data
+ * @param {boolean} [includeObjectId] - Include ObjectID from post data
+ * @returns {object} mf2
+ */
+export const jf2ToMf2 = (postData, includeObjectId = true) => {
+  const { properties, _id } = postData;
+
+  const mf2 = {
+    type: [`h-${properties.type}`],
+    properties: {
+      ...(includeObjectId && _id && { uid: [_id] }),
+    },
+  };
+
+  delete properties.type;
+
+  // Move values to property object
+  for (const key in properties) {
+    // Convert nested vocabulary to mf2 (i.e. h-card, h-geo, h-adr)
+    if (Object.prototype.hasOwnProperty.call(properties[key], "type")) {
+      mf2.properties[key] = [jf2ToMf2({ properties: properties[key] }, false)];
+    }
+
+    // Convert values to arrays (i.e. 'a' => ['a'])
+    else if (Object.prototype.hasOwnProperty.call(properties, key)) {
+      const value = properties[key];
+      mf2.properties[key] = Array.isArray(value) ? value : [value];
+    }
+  }
+
+  // Update key for plaintext content
+  if (
+    mf2.properties.content &&
+    mf2.properties.content[0] &&
+    mf2.properties.content[0].text
+  ) {
+    mf2.properties.content[0].value = properties.content.text;
+    delete mf2.properties.content[0].text;
+  }
+
+  return mf2;
+};

package/lib/post-content.js

@@ -0,0 +1,147 @@
+import makeDebug from "debug";
+
+import { getPostTemplateProperties } from "./utils.js";
+
+const debug = makeDebug("indiekit:endpoint-micropub:post-content");
+
+export const postContent = {
+  /**
+   * Create post
+   * @param {object} publication - Publication configuration
+   * @param {object} postData - Post data
+   * @returns {Promise<object>} Response data
+   */
+  async create(publication, postData) {
+    debug(`Create %O`, { postData });
+
+    const { postTemplate, store, storeMessageTemplate } = publication;
+    const { path, properties } = postData;
+    const metaData = {
+      action: "create",
+      result: "created",
+      fileType: "post",
+      postType: properties["post-type"],
+    };
+    const templateProperties = getPostTemplateProperties(properties);
+    const content = await postTemplate(templateProperties);
+    const message = storeMessageTemplate(metaData);
+
+    await store.createFile(path, content, { message });
+
+    return {
+      location: properties.url,
+      status: 202,
+      json: {
+        success: "create_pending",
+        success_description: `Post will be created at ${properties.url}`,
+      },
+    };
+  },
+
+  /**
+   * Update post
+   * @param {object} publication - Publication configuration
+   * @param {object} postData - Post data
+   * @param {string} url - Files attached to request
+   * @returns {Promise<object>} Response data
+   */
+  async update(publication, postData, url) {
+    debug(`Update ${url} %O`, { postData });
+
+    const { postTemplate, store, storeMessageTemplate } = publication;
+    const { _originalPath, path, properties } = postData;
+    const metaData = {
+      action: "update",
+      result: "updated",
+      fileType: "post",
+      postType: properties["post-type"],
+    };
+    const templateProperties = getPostTemplateProperties(properties);
+    const content = await postTemplate(templateProperties);
+    const message = storeMessageTemplate(metaData);
+    const hasUpdatedUrl = url !== properties.url;
+
+    _originalPath === path
+      ? await store.updateFile(path, content, { message })
+      : await store.updateFile(_originalPath, content, {
+          message,
+          newPath: path,
+        });
+
+    delete postData._originalPath;
+
+    return {
+      location: properties.url,
+      status: hasUpdatedUrl ? 201 : 200,
+      json: {
+        success: "update",
+        success_description: hasUpdatedUrl
+          ? `Post updated and moved to ${properties.url}`
+          : `Post updated at ${url}`,
+      },
+    };
+  },
+
+  /**
+   * Delete post
+   * @param {object} publication - Publication configuration
+   * @param {object} postData - Post data
+   * @returns {Promise<object>} Response data
+   */
+  async delete(publication, postData) {
+    debug(`Delete %O`, { postData });
+
+    const { store, storeMessageTemplate } = publication;
+    const { path, properties } = postData;
+    const metaData = {
+      action: "delete",
+      result: "deleted",
+      fileType: "post",
+      postType: properties["post-type"],
+    };
+    const message = storeMessageTemplate(metaData);
+
+    await store.deleteFile(path, { message });
+
+    return {
+      status: 200,
+      json: {
+        success: "delete",
+        success_description: `Post deleted from ${properties.url}`,
+      },
+    };
+  },
+
+  /**
+   * Undelete post
+   * @param {object} publication - Publication configuration
+   * @param {object} postData - Post data
+   * @returns {Promise<object>} Response data
+   */
+  async undelete(publication, postData) {
+    debug(`Undelete %O`, { postData });
+
+    const { postTemplate, store, storeMessageTemplate } = publication;
+    const { path, properties } = postData;
+    const metaData = {
+      action: "undelete",
+      result: "undeleted",
+      fileType: "post",
+      postType: properties["post-type"],
+    };
+    const templateProperties = getPostTemplateProperties(properties);
+    const content = await postTemplate(templateProperties);
+    const message = storeMessageTemplate(metaData);
+
+    await store.createFile(path, content, { message });
+
+    return {
+      location: properties.url,
+      status: 200,
+      json: {
+        success: "delete_undelete",
+        success_description: `Post restored to ${properties.url}`,
+      },
+    };
+  },
+};