JSDoc descriptions

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;

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<import('./links.js').TargetLink[]>}
+ * A targetted list of target links.
  */
 const applyRules = async (definitions, allLinks, host) => {
   const throttles = await getThrottles(definitions);

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.<string, Translation>} 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<Definitions>}
  */
 exports.getDefinitions = async () => {

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<import('./s3.js').Throttle[]>}
+ * A hydrated list of target link throttles.
  */
 exports.getThrottles = async (definitions) => {
   const { throttles: throttleDefs } = definitions;