From 40c9ed04c99ee1cc340d23b250ffbb1ad2509db2 Mon Sep 17 00:00:00 2001 From: Jon Jensen Date: Tue, 24 Oct 2023 14:00:45 -0700 Subject: [PATCH] JSDoc descriptions --- src/shared/links.js | 23 +++++++++++++++++- src/shared/rules.js | 10 +++++++- src/shared/s3.js | 54 ++++++++++++++++++++++++++++++++--------- src/shared/throttles.js | 7 +++++- 4 files changed, 80 insertions(+), 14 deletions(-) diff --git a/src/shared/links.js b/src/shared/links.js index 5c5e403..6082d3e 100644 --- a/src/shared/links.js +++ b/src/shared/links.js @@ -8,7 +8,13 @@ const AnalyticEngines = { /** * Find the host definition for a given host url. + * We want to match up the origin of the request (host) with our own metadata (hostDefs). * @param {string} host + * The host page, as a URL (string), from which the widget sent this request. + * @param {import('./s3.js').Host[]} hostDefs + * A list of host objects from the Airtable-derived definitions. + * @returns {import('./s3.js').Host|undefined} + * A matching host definition, or undefined if none are found. */ const findHostDef = (host, hostDefs) => { const pHostUrl = url.parse(host); @@ -28,8 +34,13 @@ const findHostDef = (host, hostDefs) => { /** * Add query string parameters for the target site's analytics engine. * @param {string} linkUrl + * The target link's URL as string. * @param {string} analytics - * @param {any} hostDef + * The target site's analytics engine, represented by a short code. @see AnalyticEngines + * @param {import('./s3.js').Host} hostDef + * A host object from the Airtable-derived definitions. + * @returns {string} + * A modified target link URL, including analytics query parameters if relevant. */ const addAnalytics = (linkUrl, analytics, hostDef) => { const pUrl = url.parse(linkUrl); @@ -51,19 +62,29 @@ const addAnalytics = (linkUrl, analytics, hostDef) => { * @typedef TargetLink * @type {object} * @property {string} id + * The id of this target link. * @property {string} language + * The language for this target link. * @property {string} lead + * The "lead text" of this target link. * @property {string} catalyst + * The "call to action" text of this target link. * @property {string} url + * The URL of this target link, as a string. * @property {string} graphic + * The SVG icon for this target link, as a string. */ /** * Construct link objects for the given language and host. * @param {import('./s3.js').Definitions} definitions + * A parsed object representing the Airtable-derived `benefits-recs-defs.json` file. * @param {string} language + * The language for this request, as an ISO 639-1 code. * @param {string} host + * The host page, as a URL (string), from which the widget sent this request. * @returns {TargetLink[]} + * A processed list of target links in the requested language. */ exports.assembleLinks = (definitions, language, host) => { const { targets, hosts: hostDefs } = definitions; diff --git a/src/shared/rules.js b/src/shared/rules.js index 0a533ed..bf33a55 100644 --- a/src/shared/rules.js +++ b/src/shared/rules.js @@ -14,9 +14,13 @@ const { getThrottles } = require("./throttles"); /** * @callback Rule * @param {import('./links.js').TargetLink[]} links + * A processed list of all target links in the user's requested language. * @param {object} params + * A collection of parameters from the request to help inform the rule. * @param {string} [params.host] + * The host page, as a URL (string), from which the widget sent this request. * @param {import('./s3.js').Throttle[]} [params.throttles] + * A processed list of target link throttles. * @returns {import('./links.js').TargetLink[]} */ @@ -69,11 +73,15 @@ const rules = [ ]; /** - * Apply the rules to the list of links. + * Apply the rules to the given list of links. * @param {import('./s3.js').Definitions} definitions + * A parsed object representing the Airtable-derived `benefits-recs-defs.json` file. * @param {import('./links.js').TargetLink[]} allLinks + * A processed list of all target links in the user's requested language. * @param {string} host + * The host page, as a URL (string), from which the widget sent this request. * @returns {Promise} + * A targetted list of target links. */ const applyRules = async (definitions, allLinks, host) => { const throttles = await getThrottles(definitions); diff --git a/src/shared/s3.js b/src/shared/s3.js index 3ecddeb..46362e2 100644 --- a/src/shared/s3.js +++ b/src/shared/s3.js @@ -3,54 +3,86 @@ const { GetObjectCommand, S3Client } = require("@aws-sdk/client-s3"); const s3 = new S3Client({}); /** - * @typedef Definitions - * @type {object} + * *Definitions* represents the latest content for the benefits recommender. + * It's derived from Airtable, and lives in a file on S3 called `benefits-recs-defs.json`. + * See the schedule/airtable job to understand how definitions are generated. + * @typedef {object} Definitions * @property {string} name + * The name of the definitions file. * @property {string} description + * The description of the definitions file. * @property {string} updated + * The date and time of last update for the definitions file. * @property {Target[]} targets + * A list of active target links. * @property {Throttle[]} throttles + * A list of active target link throttles. * @property {Host[]} hosts + * A list of hosts where the widget is placed. */ /** - * @typedef Target - * @type {object} + * *Target* represents a target link in the widget. + * Coming from the Airtable-derived definitons, this object includes all metadata and translations. + * See shared/links.js to understand how these targets are processed by the API. + * @typedef {object} Target * @property {string} id + * The id of the target. * @property {object.} translations + * A list of translations to different languages for this target. * @property {string[]} throttle_ids + * A list of IDs for applicable throttles. */ /** - * @typedef Translation - * @type {object} + * The *Translation* provides a *Target* in a different language. + * English language defaults are also included in a *Translation*. + * @typedef {object} Translation * @property {string} id + * The id of the translation. * @property {string} url + * The URL of the target for the given language. * @property {string} icon + * The icon code of the target for the given language. See shared/icons.js. * @property {string} analytics + * A code for analytics engine on the target site. See shared/links.js. * @property {string} lead + * The "lead text" for the target in the given language. * @property {string} catalyst + * The "call to action" text for the target in the given language. */ /** - * @typedef Throttle - * @type {object} + * *Throttle* defines conditions for limiting display of a target. + * @typedef {object} Throttle * @property {string} id + * The id for the throttle. * @property {number} [limit] + * A daily clickthrough limit for the target. * @property {string} [start] + * A start date for the target. * @property {string} [end] + * An end date for the target. * @property {string[]} urls + * The URLs to be throttled. * @property {boolean} [exceeded] + * Determines if the throttle has been exceeded, and the target should be throttled. + * Unlink the other properties here, *exceeded* does not come from the definitions file. + * We define it here in the API, based on the other properties, in real time. + * See shared/throttles.js. */ /** - * @typedef Host - * @type {object} + * A *Host* is a collection of related pages where the widget is located. + * @typedef {object} Host * @property {string} id + * The id of the host. * @property {string[]} urls + * The URLs associated with this host. */ -/** Grab the definitions file from S3. +/** + * Grab the definitions file from S3. * @returns {Promise} */ exports.getDefinitions = async () => { diff --git a/src/shared/throttles.js b/src/shared/throttles.js index 2cbd500..25bee68 100644 --- a/src/shared/throttles.js +++ b/src/shared/throttles.js @@ -1,9 +1,14 @@ const arc = require("@architect/functions"); /** - * Retrieve throttles. + * Based upon the Airtable-derived definitons, this function evaluates the throttles. + * We check DynamoDB to see if each throttle is still within daily clickthrough limits. + * We also look at other parameters, like start and end dates. + * The goal is to see which throttles need to be activated for this request. * @param {import('./s3.js').Definitions} definitions + * A parsed object representing the Airtable-derived `benefits-recs-defs.json` file. * @returns {Promise} + * A hydrated list of target link throttles. */ exports.getThrottles = async (definitions) => { const { throttles: throttleDefs } = definitions;