ghost/webmentions/lib/MentionsAPI.js
const errors = require('@tryghost/errors');
const logging = require('@tryghost/logging');
const Mention = require('./Mention');
/**
* @template Model
* @typedef {object} Page<Model>
* @prop {Model[]} data
* @prop {object} meta
* @prop {object} meta.pagination
* @prop {number} meta.pagination.page - The current page
* @prop {number} meta.pagination.pages - The total number of pages
* @prop {number | 'all'} meta.pagination.limit - The limit of models per page
* @prop {number} meta.pagination.total - The total number of models across all pages
* @prop {number|null} meta.pagination.prev - The number of the previous page, or null if there isn't one
* @prop {number|null} meta.pagination.next - The number of the next page, or null if there isn't one
*/
/**
* @typedef {object} PaginatedOptions
* @prop {string} [filter] A valid NQL string
* @prop {string} [order]
* @prop {number} page
* @prop {number} limit
* @prop {boolean} [unique] Only return unique mentions by source
*/
/**
* @typedef {object} NonPaginatedOptions
* @prop {string} [filter] A valid NQL string
* @prop {string} [order]
* @prop {'all'} limit
* @prop {boolean} [unique] Only return unique mentions by source
*/
/**
* @typedef {PaginatedOptions | NonPaginatedOptions} GetPageOptions
*/
/**
* @typedef {object} GetAllOptions
* @prop {string} [filter] A valid NQL string
*/
/**
* @typedef {object} IMentionRepository
* @prop {(mention: Mention) => Promise<void>} save
* @prop {(options: GetPageOptions) => Promise<Page<Mention>>} getPage
* @prop {(options: GetAllOptions) => Promise<Mention[]>} getAll
* @prop {(source: URL, target: URL) => Promise<Mention>} getBySourceAndTarget
*/
/**
* @typedef {object} ResourceResult
* @prop {string | null} type
* @prop {import('bson-objectid').default | null} id
*/
/**
* @typedef {object} IResourceService
* @prop {(url: URL) => Promise<ResourceResult>} getByURL
*/
/**
* @typedef {object} IRoutingService
* @prop {(url: URL) => Promise<boolean>} pageExists
*/
/**
* @typedef {object} WebmentionMetadata
* @prop {string|null} siteTitle
* @prop {string|null} title
* @prop {string|null} excerpt
* @prop {string|null} author
* @prop {URL|null} image
* @prop {URL|null} favicon
* @prop {string} body
* @prop {string|undefined} contentType
*/
/**
* @typedef {object} MentionReport
* @prop {Date} startDate
* @prop {Date} endDate
* @prop {Mention[]} mentions
*/
/**
* @typedef {object} IWebmentionMetadata
* @prop {(url: URL) => Promise<WebmentionMetadata>} fetch
*/
module.exports = class MentionsAPI {
/** @type {IMentionRepository} */
#repository;
/** @type {IResourceService} */
#resourceService;
/** @type {IRoutingService} */
#routingService;
/** @type {IWebmentionMetadata} */
#webmentionMetadata;
/**
* @param {object} deps
* @param {IMentionRepository} deps.repository
* @param {IResourceService} deps.resourceService
* @param {IRoutingService} deps.routingService
* @param {IWebmentionMetadata} deps.webmentionMetadata
*/
constructor(deps) {
this.#repository = deps.repository;
this.#resourceService = deps.resourceService;
this.#routingService = deps.routingService;
this.#webmentionMetadata = deps.webmentionMetadata;
}
/**
* @param {Date} startDate
* @param {Date} endDate
* @returns {Promise<MentionReport>}
*/
async getMentionReport(startDate, endDate) {
const mentions = await this.#repository.getAll({
filter: `created_at:>${startDate.toISOString()}+created_at:<${endDate.toISOString()}`
});
const report = {
startDate: new Date(startDate),
endDate: new Date(endDate),
mentions
};
return report;
}
/**
* @param {object} options
* @returns {Promise<Page<Mention>>}
*/
async listMentions(options) {
/** @type {GetPageOptions} */
let pageOptions;
if (options.limit === 'all') {
pageOptions = {
filter: options.filter,
limit: options.limit,
order: options.order,
unique: options.unique ?? false
};
} else {
pageOptions = {
filter: options.filter,
limit: options.limit,
page: options.page,
order: options.order,
unique: options.unique ?? false
};
}
const page = await this.#repository.getPage(pageOptions);
return page;
}
/**
* Update the metadata of the webmentions in the database, and delete them if they are no longer valid.
* @param {object} options
* @param {number|'all'} [options.limit]
* @param {number} [options.page]
* @param {string} [options.filter]
*/
async refreshMentions(options) {
const mentions = await this.#repository.getAll(options);
for (const mention of mentions) {
await this.#updateWebmention(mention, {
source: mention.source,
target: mention.target
});
}
}
async #updateWebmention(mention, webmention) {
const isNew = !mention;
const wasDeleted = mention?.deleted ?? false;
const targetExists = await this.#routingService.pageExists(webmention.target);
if (!targetExists) {
if (!mention) {
throw new errors.BadRequestError({
message: `${webmention.target} is not a valid URL for this site.`
});
} else {
mention.delete();
}
}
if (targetExists) {
const resourceInfo = await this.#resourceService.getByURL(webmention.target);
let metadata;
try {
metadata = await this.#webmentionMetadata.fetch(webmention.source);
if (mention) {
mention.setSourceMetadata({
sourceTitle: metadata.title,
sourceSiteTitle: metadata.siteTitle,
sourceAuthor: metadata.author,
sourceExcerpt: metadata.excerpt,
sourceFavicon: metadata.favicon,
sourceFeaturedImage: metadata.image
});
}
} catch (err) {
if (!mention) {
throw err;
}
mention.delete();
}
if (!mention) {
mention = await Mention.create({
source: webmention.source,
target: webmention.target,
timestamp: new Date(),
payload: webmention.payload,
resourceId: resourceInfo.id ? resourceInfo.id.toHexString() : null,
resourceType: resourceInfo.type,
sourceTitle: metadata.title,
sourceSiteTitle: metadata.siteTitle,
sourceAuthor: metadata.author,
sourceExcerpt: metadata.excerpt,
sourceFavicon: metadata.favicon,
sourceFeaturedImage: metadata.image
});
}
if (metadata?.body) {
mention.verify(metadata.body, metadata.contentType);
}
}
await this.#repository.save(mention);
if (isNew) {
logging.info('[Webmention] Created ' + webmention.source + ' to ' + webmention.target + ', verified: ' + mention.verified + ', deleted: ' + mention.deleted);
} else {
if (mention.deleted && !wasDeleted) {
logging.info('[Webmention] Deleted ' + webmention.source + ' to ' + webmention.target + ', verified: ' + mention.verified);
} else {
if (!mention.deleted && wasDeleted) {
logging.info('[Webmention] Restored ' + webmention.source + ' to ' + webmention.target + ', verified: ' + mention.verified);
} else {
logging.info('[Webmention] Updated ' + webmention.source + ' to ' + webmention.target + ', verified: ' + mention.verified + ', deleted: ' + mention.deleted);
}
}
}
return mention;
}
/**
* @param {object} webmention
* @param {URL} webmention.source
* @param {URL} webmention.target
* @param {Object<string, any>} webmention.payload
*
* @returns {Promise<Mention>}
*/
async processWebmention(webmention) {
let mention = await this.#repository.getBySourceAndTarget(
webmention.source,
webmention.target
);
return await this.#updateWebmention(mention, webmention);
}
};