Add documentation for carbon functions

CONTRIBUTING.md

@@ -56,6 +56,7 @@ REACT_APP_ALGOLIA_ID={algolia-search-id}
 REACT_APP_ALGOLIA_KEY={algolia-search-key}
 REACT_APP_ALGOLIA_INDEX={algolia-search-index-based-on-environment}
 REACT_APP_DEVELOPMENT_MODE=development
+MONGO_CONNECTION={mongodb-connection-string}
 ```
 
 ### Development
@@ -194,6 +195,11 @@ new working environment.
 
 In the end we should have 3 environments including master, working environment, and the past 1 version of master.
 
+### Netlify functions
+1. If not already installed, install `netlify-cli` globally
+2. Run `netlify dev`
+3. Invoke functions either through function url or [netlify-cli](https://cli.netlify.com/commands/functions)
+
 ## Naming Conventions
 
 ### Prefixes

netlify/functions/collectCarbon.mts

@@ -4,6 +4,12 @@ import { CarbonEntry } from '../../src/shared/types/docs';
 const { default: axios } = require('axios');
 const jsdom = require('jsdom');
 
+/**
+ * Query the website carbon api and return a CarbonEntry with date, url, carbon grams, and percent data.
+ * @param url Anatomy docs page url
+ * @param date Date string for the current date
+ * @returns Promise<CarbonEntry>
+ */
 async function getCarbon(url: string, date: string): Promise<CarbonEntry> {
   const api = 'https://api.websitecarbon.com/b?url=';
   try {
@@ -29,10 +35,14 @@ async function getCarbon(url: string, date: string): Promise<CarbonEntry> {
   }
 }
 
+/**
+ * Gets the sitemap from the main branch in the anatomy-docs github
+ * @returns Promise<string[]> A string of urls parsed from the sitemap
+ */
 async function parseSitemap(): Promise<string[] | null> {
   console.log('Parsing sitemap...');
   try {
-    const res = await axios.get('https://raw.githubusercontent.com/bsc-xdc/anatomy/master/public/sitemap.xml');
+    const res = await axios.get('https://raw.githubusercontent.com/bos-sci/anatomy-docs/main/public/sitemap.xml');
     const dom = new jsdom.JSDOM(res.data, { contentType: 'application/xml' });
     return Array.from(dom.window.document.querySelectorAll('loc'), (loc: Element) => loc.textContent || '');
   } catch (error) {
@@ -41,6 +51,10 @@ async function parseSitemap(): Promise<string[] | null> {
   }
 }
 
+/**
+ * PAss all the sitemap urls into the website carbon api
+ * @returns Promise<CarbonEntry[]> Records to be written to DB
+ */
 async function collectData(): Promise<CarbonEntry[] | null> {
   console.log('Collecting data...');
   const date = new Date().toISOString();
@@ -55,6 +69,10 @@ async function collectData(): Promise<CarbonEntry[] | null> {
   }
 }
 
+/**
+ * Connects to MongoDB and inserts records
+ * @returns Status code object
+ */
 const handler: Handler = async () => {
   const uri = process.env.MONGO_CONNECTION as string;
   const client = new MongoClient(uri);

netlify/functions/getAllCarbon.mts

@@ -8,7 +8,7 @@ export default async () => {
   try {
     const database = client.db('carbon-metrics');
     const carbon = database.collection<CarbonRecord>('metrics');
-    const cursor = carbon.find().sort({ date: 1 });
+    const cursor = carbon.find().sort({ date: 1 }); // Sort date ascending
     const allData = await cursor.toArray();
     return Response.json(allData);
   } catch (error) {

netlify/functions/getCarbon.mts

@@ -4,15 +4,16 @@ import { URL } from 'url';
 
 // eslint-disable-next-line import/no-anonymous-default-export
 export default async (req: Request) => {
+  // Build the search params object from query parameters
   const params = {};
   new URL(req.url).searchParams.forEach((value, key) => (params[key] = value));
-  console.log(params);
+  // Connect to MongoDB
   const uri = process.env.MONGO_CONNECTION as string;
   const client = new MongoClient(uri);
   try {
     const database = client.db('carbon-metrics');
     const carbon = database.collection<CarbonRecord>('metrics');
-    const cursor = carbon.find(params).sort({ date: 1 });
+    const cursor = carbon.find(params).sort({ date: 1 }); // Sort date ascending
     const allData = await cursor.toArray();
     return Response.json(allData);
   } catch (error) {