etherpad-lite/src/node/db/API.ts

'use strict';
/**
 * This module provides all API functions
 */

/*
 * 2011 Peter 'Pita' Martischka (Primary Technology Ltd)
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS-IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

const Changeset = require('../../static/js/Changeset');
const ChatMessage = require('../../static/js/ChatMessage');
const CustomError = require('../utils/customError');
const padManager = require('./PadManager');
const padMessageHandler = require('../handler/PadMessageHandler');
const readOnlyManager = require('./ReadOnlyManager');
const groupManager = require('./GroupManager');
const authorManager = require('./AuthorManager');
const sessionManager = require('./SessionManager');
const exportHtml = require('../utils/ExportHtml');
const exportTxt = require('../utils/ExportTxt');
const importHtml = require('../utils/ImportHtml');
const cleanText = require('./Pad').cleanText;
const PadDiff = require('../utils/padDiff');
const {checkValidRev, isInt} = require('../utils/checkValidRev');

/* ********************
 * GROUP FUNCTIONS ****
 ******************** */

exports.listAllGroups = groupManager.listAllGroups;
exports.createGroup = groupManager.createGroup;
exports.createGroupIfNotExistsFor = groupManager.createGroupIfNotExistsFor;
exports.deleteGroup = groupManager.deleteGroup;
exports.listPads = groupManager.listPads;
exports.createGroupPad = groupManager.createGroupPad;

/* ********************
 * PADLIST FUNCTION ***
 ******************** */

exports.listAllPads = padManager.listAllPads;

/* ********************
 * AUTHOR FUNCTIONS ***
 ******************** */

exports.createAuthor = authorManager.createAuthor;
exports.createAuthorIfNotExistsFor = authorManager.createAuthorIfNotExistsFor;
exports.getAuthorName = authorManager.getAuthorName;
exports.listPadsOfAuthor = authorManager.listPadsOfAuthor;
exports.padUsers = padMessageHandler.padUsers;
exports.padUsersCount = padMessageHandler.padUsersCount;

/* ********************
 * SESSION FUNCTIONS **
 ******************** */

exports.createSession = sessionManager.createSession;
exports.deleteSession = sessionManager.deleteSession;
exports.getSessionInfo = sessionManager.getSessionInfo;
exports.listSessionsOfGroup = sessionManager.listSessionsOfGroup;
exports.listSessionsOfAuthor = sessionManager.listSessionsOfAuthor;

/* ***********************
 * PAD CONTENT FUNCTIONS *
 *********************** */

/**
getAttributePool(padID) returns the attribute pool of a pad

Example returns:
{
 "code":0,
 "message":"ok",
 "data": {
    "pool":{
        "numToAttrib":{
            "0":["author","a.X4m8bBWJBZJnWGSh"],
            "1":["author","a.TotfBPzov54ihMdH"],
            "2":["author","a.StiblqrzgeNTbK05"],
            "3":["bold","true"]
        },
        "attribToNum":{
            "author,a.X4m8bBWJBZJnWGSh":0,
            "author,a.TotfBPzov54ihMdH":1,
            "author,a.StiblqrzgeNTbK05":2,
            "bold,true":3
        },
        "nextNum":4
    }
 }
}

*/
exports.getAttributePool = async (padID: string) => {
  const pad = await getPadSafe(padID, true);
  return {pool: pad.pool};
};

/**
getRevisionChangeset (padID, [rev])

get the changeset at a given revision, or last revision if 'rev' is not defined.

Example returns:
{
    "code" : 0,
    "message" : "ok",
    "data" : "Z:1>6b|5+6b$Welcome to Etherpad!\n\nThis pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents!\n\nGet involved with Etherpad at http://etherpad.org\n"
}

*/
exports.getRevisionChangeset = async (padID: string, rev: string) => {
  // try to parse the revision number
  if (rev !== undefined) {
    rev = checkValidRev(rev);
  }

  // get the pad
  const pad = await getPadSafe(padID, true);
  const head = pad.getHeadRevisionNumber();

  // the client asked for a special revision
  if (rev !== undefined) {
    // check if this is a valid revision
    if (rev > head) {
      throw new CustomError('rev is higher than the head revision of the pad', 'apierror');
    }

    // get the changeset for this revision
    return await pad.getRevisionChangeset(rev);
  }

  // the client wants the latest changeset, lets return it to him
  return await pad.getRevisionChangeset(head);
};

/**
getText(padID, [rev]) returns the text of a pad

Example returns:

{code: 0, message:"ok", data: {text:"Welcome Text"}}
{code: 1, message:"padID does not exist", data: null}
*/
exports.getText = async (padID: string, rev: string) => {
  // try to parse the revision number
  if (rev !== undefined) {
    rev = checkValidRev(rev);
  }

  // get the pad
  const pad = await getPadSafe(padID, true);
  const head = pad.getHeadRevisionNumber();

  // the client asked for a special revision
  if (rev !== undefined) {
    // check if this is a valid revision
    if (rev > head) {
      throw new CustomError('rev is higher than the head revision of the pad', 'apierror');
    }

    // get the text of this revision
    // getInternalRevisionAText() returns an atext object, but we only want the .text inside it.
    // Details at https://github.com/ether/etherpad-lite/issues/5073
    const {text} = await pad.getInternalRevisionAText(rev);
    return {text};
  }

  // the client wants the latest text, lets return it to him
  const text = exportTxt.getTXTFromAtext(pad, pad.atext);
  return {text};
};

/**
setText(padID, text, [authorId]) sets the text of a pad

Example returns:

{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}
{code: 1, message:"text too long", data: null}
*/
/**
 *
 * @param {String} padID the id of the pad
 * @param {String} text the text of the pad
 * @param {String} authorId the id of the author, defaulting to empty string
 * @returns {Promise<void>}
 */
exports.setText = async (padID: string, text?: string, authorId: string = ''): Promise<void> => {
  // text is required
  if (typeof text !== 'string') {
    throw new CustomError('text is not a string', 'apierror');
  }

  // get the pad
  const pad = await getPadSafe(padID, true);

  await pad.setText(text, authorId);
  await padMessageHandler.updatePadClients(pad);
};

/**
appendText(padID, text, [authorId]) appends text to a pad

Example returns:

{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}
{code: 1, message:"text too long", data: null}
 @param {String} padID the id of the pad
 @param {String} text the text of the pad
 @param {String} authorId the id of the author, defaulting to empty string
 */
exports.appendText = async (padID:string, text?: string, authorId:string = '') => {
  // text is required
  if (typeof text !== 'string') {
    throw new CustomError('text is not a string', 'apierror');
  }

  const pad = await getPadSafe(padID, true);
  await pad.appendText(text, authorId);
  await padMessageHandler.updatePadClients(pad);
};

/**
getHTML(padID, [rev]) returns the html of a pad

Example returns:

{code: 0, message:"ok", data: {text:"Welcome <strong>Text</strong>"}}
{code: 1, message:"padID does not exist", data: null}
 @param {String} padID the id of the pad
 @param {String} rev the revision number, defaulting to the latest revision
 @return {Promise<{html: string}>} the html of the pad
*/
exports.getHTML = async (padID: string, rev: string): Promise<{ html: string; }> => {
  if (rev !== undefined) {
    rev = checkValidRev(rev);
  }

  const pad = await getPadSafe(padID, true);

  // the client asked for a special revision
  if (rev !== undefined) {
    // check if this is a valid revision
    const head = pad.getHeadRevisionNumber();
    if (rev > head) {
      throw new CustomError('rev is higher than the head revision of the pad', 'apierror');
    }
  }

  // get the html of this revision
  let html = await exportHtml.getPadHTML(pad, rev);

  // wrap the HTML
  html = `<!DOCTYPE HTML><html><body>${html}</body></html>`;
  return {html};
};

/**
setHTML(padID, html, [authorId]) sets the text of a pad based on HTML

Example returns:

{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}

 @param {String} padID the id of the pad
 @param {String} html the html of the pad
 @param {String} authorId the id of the author, defaulting to empty string
*/
exports.setHTML = async (padID: string, html:string|object, authorId = '') => {
  // html string is required
  if (typeof html !== 'string') {
    throw new CustomError('html is not a string', 'apierror');
  }

  // get the pad
  const pad = await getPadSafe(padID, true);

  // add a new changeset with the new html to the pad
  try {
    await importHtml.setPadHTML(pad, cleanText(html), authorId);
  } catch (e) {
    throw new CustomError('HTML is malformed', 'apierror');
  }

  // update the clients on the pad
  padMessageHandler.updatePadClients(pad);
};

/* ****************
 * CHAT FUNCTIONS *
 **************** */

/**
getChatHistory(padId, start, end), returns a part of or the whole chat-history of this pad

Example returns:

{"code":0,"message":"ok","data":{"messages":[
  {"text":"foo","authorID":"a.foo","time":1359199533759,"userName":"test"},
  {"text":"bar","authorID":"a.foo","time":1359199534622,"userName":"test"}
]}}

{code: 1, message:"start is higher or equal to the current chatHead", data: null}

{code: 1, message:"padID does not exist", data: null}
 @param {String} padID the id of the pad
 @param {Number} start the start point of the chat-history
 @param {Number} end the end point of the chat-history
*/
exports.getChatHistory = async (padID: string, start:number, end:number) => {
  if (start && end) {
    if (start < 0) {
      throw new CustomError('start is below zero', 'apierror');
    }
    if (end < 0) {
      throw new CustomError('end is below zero', 'apierror');
    }
    if (start > end) {
      throw new CustomError('start is higher than end', 'apierror');
    }
  }

  // get the pad
  const pad = await getPadSafe(padID, true);

  const chatHead = pad.chatHead;

  // fall back to getting the whole chat-history if a parameter is missing
  if (!start || !end) {
    start = 0;
    end = pad.chatHead;
  }

  if (start > chatHead) {
    throw new CustomError('start is higher than the current chatHead', 'apierror');
  }
  if (end > chatHead) {
    throw new CustomError('end is higher than the current chatHead', 'apierror');
  }

  // the whole message-log and return it to the client
  const messages = await pad.getChatMessages(start, end);

  return {messages};
};

/**
appendChatMessage(padID, text, authorID, time), creates a chat message for the pad id,
time is a timestamp

Example returns:

{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}
 @param {String} padID the id of the pad
 @param {String} text the text of the chat-message
 @param {String} authorID the id of the author
 @param {Number} time the timestamp of the chat-message
*/
exports.appendChatMessage = async (padID: string, text: string|object, authorID: string, time: number) => {
  // text is required
  if (typeof text !== 'string') {
    throw new CustomError('text is not a string', 'apierror');
  }

  // if time is not an integer value set time to current timestamp
  if (time === undefined || !isInt(time)) {
    time = Date.now();
  }

  // @TODO - missing getPadSafe() call ?

  // save chat message to database and send message to all connected clients
  await padMessageHandler.sendChatMessageToPadClients(new ChatMessage(text, authorID, time), padID);
};

/* ***************
 * PAD FUNCTIONS *
 *************** */

/**
getRevisionsCount(padID) returns the number of revisions of this pad

Example returns:

{code: 0, message:"ok", data: {revisions: 56}}
{code: 1, message:"padID does not exist", data: null}
 @param {String} padID the id of the pad
*/
exports.getRevisionsCount = async (padID: string) => {
  // get the pad
  const pad = await getPadSafe(padID, true);
  return {revisions: pad.getHeadRevisionNumber()};
};

/**
getSavedRevisionsCount(padID) returns the number of saved revisions of this pad

Example returns:

{code: 0, message:"ok", data: {savedRevisions: 42}}
{code: 1, message:"padID does not exist", data: null}
 @param {String} padID the id of the pad
*/
exports.getSavedRevisionsCount = async (padID: string) => {
  // get the pad
  const pad = await getPadSafe(padID, true);
  return {savedRevisions: pad.getSavedRevisionsNumber()};
};

/**
listSavedRevisions(padID) returns the list of saved revisions of this pad

Example returns:

{code: 0, message:"ok", data: {savedRevisions: [2, 42, 1337]}}
{code: 1, message:"padID does not exist", data: null}
 @param {String} padID the id of the pad
*/
exports.listSavedRevisions = async (padID: string) => {
  // get the pad
  const pad = await getPadSafe(padID, true);
  return {savedRevisions: pad.getSavedRevisionsList()};
};

/**
saveRevision(padID) returns the list of saved revisions of this pad

Example returns:

{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}
    @param {String} padID the id of the pad
     @param {Number} rev the revision number, defaulting to the latest revision
*/
exports.saveRevision = async (padID: string, rev: number) => {
  // check if rev is a number
  if (rev !== undefined) {
    rev = checkValidRev(rev);
  }

  // get the pad
  const pad = await getPadSafe(padID, true);
  const head = pad.getHeadRevisionNumber();

  // the client asked for a special revision
  if (rev !== undefined) {
    if (rev > head) {
      throw new CustomError('rev is higher than the head revision of the pad', 'apierror');
    }
  } else {
    rev = pad.getHeadRevisionNumber();
  }

  const author = await authorManager.createAuthor('API');
  await pad.addSavedRevision(rev, author.authorID, 'Saved through API call');
};

/**
getLastEdited(padID) returns the timestamp of the last revision of the pad

Example returns:

{code: 0, message:"ok", data: {lastEdited: 1340815946602}}
{code: 1, message:"padID does not exist", data: null}
    @param {String} padID the id of the pad
 @return {Promise<{lastEdited: number}>} the timestamp of the last revision of the pad
*/
exports.getLastEdited = async (padID: string): Promise<{ lastEdited: number; }> => {
  // get the pad
  const pad = await getPadSafe(padID, true);
  const lastEdited = await pad.getLastEdit();
  return {lastEdited};
};

/**
createPad(padName, [text], [authorId]) creates a new pad in this group

Example returns:

{code: 0, message:"ok", data: null}
{code: 1, message:"pad does already exist", data: null}
 @param {String} padID the name of the new pad
    @param {String} text the initial text of the pad
     @param {String} authorId the id of the author, defaulting to empty string
*/
exports.createPad = async (padID: string, text: string, authorId = '') => {
  if (padID) {
    // ensure there is no $ in the padID
    if (padID.indexOf('$') !== -1) {
      throw new CustomError("createPad can't create group pads", 'apierror');
    }

    // check for url special characters
    if (padID.match(/(\/|\?|&|#)/)) {
      throw new CustomError('malformed padID: Remove special characters', 'apierror');
    }
  }

  // create pad
  await getPadSafe(padID, false, text, authorId);
};

/**
deletePad(padID) deletes a pad

Example returns:

{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}
 @param {String} padID the id of the pad
*/
exports.deletePad = async (padID: string) => {
  const pad = await getPadSafe(padID, true);
  await pad.remove();
};

/**
 restoreRevision(padID, rev, [authorId]) Restores revision from past as new changeset

 Example returns:

 {code:0, message:"ok", data:null}
 {code: 1, message:"padID does not exist", data: null}
 @param {String} padID the id of the pad
 @param {Number} rev the revision number, defaulting to the latest revision
 @param {String} authorId the id of the author, defaulting to empty string
 */
exports.restoreRevision = async (padID: string, rev: number, authorId = '') => {
  // check if rev is a number
  if (rev === undefined) {
    throw new CustomError('rev is not defined', 'apierror');
  }
  rev = checkValidRev(rev);

  // get the pad
  const pad = await getPadSafe(padID, true);

  // check if this is a valid revision
  if (rev > pad.getHeadRevisionNumber()) {
    throw new CustomError('rev is higher than the head revision of the pad', 'apierror');
  }

  const atext = await pad.getInternalRevisionAText(rev);

  const oldText = pad.text();
  atext.text += '\n';

  const eachAttribRun = (attribs: string[], func:Function) => {
    let textIndex = 0;
    const newTextStart = 0;
    const newTextEnd = atext.text.length;
    for (const op of Changeset.deserializeOps(attribs)) {
      const nextIndex = textIndex + op.chars;
      if (!(nextIndex <= newTextStart || textIndex >= newTextEnd)) {
        func(Math.max(newTextStart, textIndex), Math.min(newTextEnd, nextIndex), op.attribs);
      }
      textIndex = nextIndex;
    }
  };

  // create a new changeset with a helper builder object
  const builder = Changeset.builder(oldText.length);

  // assemble each line into the builder
  eachAttribRun(atext.attribs, (start: number, end: number, attribs:string[]) => {
    builder.insert(atext.text.substring(start, end), attribs);
  });

  const lastNewlinePos = oldText.lastIndexOf('\n');
  if (lastNewlinePos < 0) {
    builder.remove(oldText.length - 1, 0);
  } else {
    builder.remove(lastNewlinePos, oldText.match(/\n/g).length - 1);
    builder.remove(oldText.length - lastNewlinePos - 1, 0);
  }

  const changeset = builder.toString();

  await pad.appendRevision(changeset, authorId);
  await padMessageHandler.updatePadClients(pad);
};

/**
copyPad(sourceID, destinationID[, force=false]) copies a pad. If force is true,
  the destination will be overwritten if it exists.

Example returns:

{code: 0, message:"ok", data: {padID: destinationID}}
{code: 1, message:"padID does not exist", data: null}
 @param {String} sourceID the id of the source pad
 @param {String} destinationID the id of the destination pad
 @param {Boolean} force whether to overwrite the destination pad if it exists
*/
exports.copyPad = async (sourceID: string, destinationID: string, force: boolean) => {
  const pad = await getPadSafe(sourceID, true);
  await pad.copy(destinationID, force);
};

/**
copyPadWithoutHistory(sourceID, destinationID[, force=false], [authorId]) copies a pad. If force is
true, the destination will be overwritten if it exists.

Example returns:

{code: 0, message:"ok", data: {padID: destinationID}}
{code: 1, message:"padID does not exist", data: null}
 @param {String} sourceID the id of the source pad
 @param {String} destinationID the id of the destination pad
 @param {Boolean} force whether to overwrite the destination pad if it exists
 @param {String} authorId the id of the author, defaulting to empty string
*/
exports.copyPadWithoutHistory = async (sourceID: string, destinationID: string, force:boolean, authorId = '') => {
  const pad = await getPadSafe(sourceID, true);
  await pad.copyPadWithoutHistory(destinationID, force, authorId);
};

/**
movePad(sourceID, destinationID[, force=false]) moves a pad. If force is true,
  the destination will be overwritten if it exists.

Example returns:

{code: 0, message:"ok", data: {padID: destinationID}}
{code: 1, message:"padID does not exist", data: null}
 @param {String} sourceID the id of the source pad
 @param {String} destinationID the id of the destination pad
 @param {Boolean} force whether to overwrite the destination pad if it exists
*/
exports.movePad = async (sourceID: string, destinationID: string, force:boolean) => {
  const pad = await getPadSafe(sourceID, true);
  await pad.copy(destinationID, force);
  await pad.remove();
};

/**
getReadOnlyLink(padID) returns the read only link of a pad

Example returns:

{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}
 @param {String} padID the id of the pad
*/
exports.getReadOnlyID = async (padID: string) => {
  // we don't need the pad object, but this function does all the security stuff for us
  await getPadSafe(padID, true);

  // get the readonlyId
  const readOnlyID = await readOnlyManager.getReadOnlyId(padID);

  return {readOnlyID};
};

/**
getPadID(roID) returns the padID of a pad based on the readonlyID(roID)

Example returns:

{code: 0, message:"ok", data: {padID: padID}}
{code: 1, message:"padID does not exist", data: null}
    @param {String} roID the readonly id of the pad
*/
exports.getPadID = async (roID: string) => {
  // get the PadId
  const padID = await readOnlyManager.getPadId(roID);
  if (padID == null) {
    throw new CustomError('padID does not exist', 'apierror');
  }

  return {padID};
};

/**
setPublicStatus(padID, publicStatus) sets a boolean for the public status of a pad

Example returns:

{code: 0, message:"ok", data: null}
{code: 1, message:"padID does not exist", data: null}
    @param {String} padID the id of the pad
     @param {Boolean} publicStatus the public status of the pad
*/
exports.setPublicStatus = async (padID: string, publicStatus: boolean|string) => {
  // ensure this is a group pad
  checkGroupPad(padID, 'publicStatus');

  // get the pad
  const pad = await getPadSafe(padID, true);

  // convert string to boolean
  if (typeof publicStatus === 'string') {
    publicStatus = (publicStatus.toLowerCase() === 'true');
  }

  await pad.setPublicStatus(publicStatus);
};

/**
getPublicStatus(padID) return true of false

Example returns:

{code: 0, message:"ok", data: {publicStatus: true}}
{code: 1, message:"padID does not exist", data: null}
     @param {String} padID the id of the pad
*/
exports.getPublicStatus = async (padID: string) => {
  // ensure this is a group pad
  checkGroupPad(padID, 'publicStatus');

  // get the pad
  const pad = await getPadSafe(padID, true);
  return {publicStatus: pad.getPublicStatus()};
};

/**
listAuthorsOfPad(padID) returns an array of authors who contributed to this pad

Example returns:

{code: 0, message:"ok", data: {authorIDs : ["a.s8oes9dhwrvt0zif", "a.akf8finncvomlqva"]}
{code: 1, message:"padID does not exist", data: null}
     @param {String} padID the id of the pad
*/
exports.listAuthorsOfPad = async (padID: string) => {
  // get the pad
  const pad = await getPadSafe(padID, true);
  const authorIDs = pad.getAllAuthors();
  return {authorIDs};
};

/**
sendClientsMessage(padID, msg) sends a message to all clients connected to the
pad, possibly for the purpose of signalling a plugin.

Note, this will only accept strings from the HTTP API, so sending bogus changes
or chat messages will probably not be possible.

The resulting message will be structured like so:

{
  type: 'COLLABROOM',
  data: {
    type: <msg>,
    time: <time the message was sent>
  }
}

Example returns:

{code: 0, message:"ok"}
{code: 1, message:"padID does not exist"}
     @param {String} padID the id of the pad
     @param {String} msg the message to send
*/

exports.sendClientsMessage = async (padID: string, msg: string) => {
  await getPadSafe(padID, true); // Throw if the padID is invalid or if the pad does not exist.
  padMessageHandler.handleCustomMessage(padID, msg);
};

/**
checkToken() returns ok when the current api token is valid

Example returns:

{"code":0,"message":"ok","data":null}
{"code":4,"message":"no or wrong API Key","data":null}
*/
exports.checkToken = async () => {
};

/**
getChatHead(padID) returns the chatHead (last number of the last chat-message) of the pad

Example returns:

{code: 0, message:"ok", data: {chatHead: 42}}
{code: 1, message:"padID does not exist", data: null}
     @param {String} padID the id of the pad
     @return {Promise<{chatHead: number}>} the chatHead of the pad
*/
exports.getChatHead = async (padID:string): Promise<{ chatHead: number; }> => {
  // get the pad
  const pad = await getPadSafe(padID, true);
  return {chatHead: pad.chatHead};
};

/**
createDiffHTML(padID, startRev, endRev) returns an object of diffs from 2 points in a pad

Example returns:
{
  "code": 0,
  "message": "ok",
  "data": {
    "html": "...",
    "authors": [
      "a.HKIv23mEbachFYfH",
      ""
    ]
  }
}
{"code":4,"message":"no or wrong API Key","data":null}
  @param {String} padID the id of the pad
 @param {Number} startRev the start revision number
 @param {Number} endRev the end revision number
*/
exports.createDiffHTML = async (padID: string, startRev: number, endRev: number) => {
  // check if startRev is a number
  if (startRev !== undefined) {
    startRev = checkValidRev(startRev);
  }

  // check if endRev is a number
  if (endRev !== undefined) {
    endRev = checkValidRev(endRev);
  }

  // get the pad
  const pad = await getPadSafe(padID, true);
  const headRev = pad.getHeadRevisionNumber();
  if (startRev > headRev) startRev = headRev;

  if (endRev > headRev) endRev = headRev;

  let padDiff;
  try {
    padDiff = new PadDiff(pad, startRev, endRev);
  } catch (e:any) {
    throw {stop: e.message};
  }

  const html = await padDiff.getHtml();
  const authors = await padDiff.getAuthors();

  return {html, authors};
};

/* ********************
 ** GLOBAL FUNCTIONS **
 ******************** */

/**
 getStats() returns an json object with some instance stats

 Example returns:

 {"code":0,"message":"ok","data":{"totalPads":3,"totalSessions": 2,"totalActivePads": 1}}
 {"code":4,"message":"no or wrong API Key","data":null}
 */
exports.getStats = async () => {
  const sessionInfos = padMessageHandler.sessioninfos;

  const sessionKeys = Object.keys(sessionInfos);
  // @ts-ignore
  const activePads = new Set(Object.entries(sessionInfos).map((k) => k[1].padId));

  const {padIDs} = await padManager.listAllPads();

  return {
    totalPads: padIDs.length,
    totalSessions: sessionKeys.length,
    totalActivePads: activePads.size,
  };
};

/* ****************************
 ** INTERNAL HELPER FUNCTIONS *
 **************************** */

// gets a pad safe
const getPadSafe = async (padID: string|object, shouldExist: boolean, text?:string, authorId:string = '') => {
  // check if padID is a string
  if (typeof padID !== 'string') {
    throw new CustomError('padID is not a string', 'apierror');
  }

  // check if the padID maches the requirements
  if (!padManager.isValidPadId(padID)) {
    throw new CustomError('padID did not match requirements', 'apierror');
  }

  // check if the pad exists
  const exists = await padManager.doesPadExists(padID);

  if (!exists && shouldExist) {
    // does not exist, but should
    throw new CustomError('padID does not exist', 'apierror');
  }

  if (exists && !shouldExist) {
    // does exist, but shouldn't
    throw new CustomError('padID does already exist', 'apierror');
  }

  // pad exists, let's get it
  return padManager.getPad(padID, text, authorId);
};

// checks if a padID is part of a group
const checkGroupPad = (padID: string, field: string) => {
  // ensure this is a group pad
  if (padID && padID.indexOf('$') === -1) {
    throw new CustomError(
        `You can only get/set the ${field} of pads that belong to a group`, 'apierror');
  }
};