initial batch of doc

Author: JosiasAurel

api/channel-is-forbidden.js

@@ -1,3 +1,9 @@
+/**
+* check if the slack channel is forbidden
+* @function 
+* @param {string} channelID - The ID of the slack channel
+* @returns {boolean}
+*/
 export default (channelID) => {
   const forbiddenChannels = [
     'C74HZS5A5', // #lobby

api/close-stale-calls.js

@@ -1,12 +1,17 @@
 import Prisma from "./prisma.js"
 import closeZoomCall from "./close-zoom-call.js"
 
+/**
+* @param {Object}
+*/
 export default async ({creatorSlackID} = {}) => {
   const startTS = Date.now()
   console.log(`Starting to close stale calls at ${startTS}`)
 
   const cutoff = 60 * 2 * 1000 // 2 minutes
 
+  // get meetings started more than two minutes ago
+  // that haven't ended
   const where = {
     endedAt: {
       equals: null,
@@ -26,7 +31,6 @@ export default async ({creatorSlackID} = {}) => {
 
     if (closedCall) {
       closedCalls.push(closedCall)
-      
     }
   }))
 

api/find-or-create-meeting.js

@@ -1,20 +1,26 @@
 import Bottleneck from 'bottleneck'
-
 import Prisma from './prisma.js'
 import openZoomMeeting from "./open-zoom-meeting.js"
 import sendHostKey from "./send-host-key.js";
 
+/**
+* finds an existing meeting or create a new one with the query id
+* @function 
+* @params {string} queryID - The schedule link id
+*/
 const findOrCreateMeeting = async (queryID) => {
   // Find the scheduling link record with the ID we've been given
   let link = await Prisma.find('schedulingLink', {
     where: {name: queryID}
   })
+
   if (!link) {
     const err = Error('Scheduling meeting not found!')
     err.statusCode = 404
     throw err
   }
 
+  // find open meetings using the schedule link id
   let openMeetingsCount = await Prisma.count('meeting', { where: { endedAt: {
     equals: null,
   }, schedulingLinkId: link.id } })

api/get-public-meetings.js

@@ -2,6 +2,12 @@ import Prisma from "./prisma.js"
 import transcript from "./transcript.js"
 import fetch from 'node-fetch'
 
+/**
+* Get the number of participants in a slack call
+* @function
+* @param {string} slackCallID - The ID of the slack call
+* @returns {Promise<number>}
+*/
 async function getParticipantCount(slackCallID) {
   const callInfo = await fetch('https://slack.com/api/calls.info', {
     method: 'post',
@@ -19,6 +25,11 @@ async function getParticipantCount(slackCallID) {
   return callInfo.call.users.length
 }
 
+/**
+* Get a list of meetings having one or more participants
+* @function
+* @returns {Promise<Object[]>}
+*/
 export default async function() {
   const meetings = await Prisma.get('meeting', {where: {NOT: {startedAt: {equals: null}}, endedAt: {equals: null}, public: true}})
   const meetingsWithParticipants = await Promise.all(

api/get-scheduled-meetings.js

@@ -1,5 +1,11 @@
 import prisma from "./prisma.js"
 
+/**
+* Get scheduled meetings
+* @function
+* @param {string} user - The slack ID of the user
+* @returns {Promise<Object[]>}
+*/
 export default async function(user) {
   const linksWhere = {
     creatorSlackID: user,

api/hack-night.js

@@ -1,6 +1,11 @@
 import fetch from "node-fetch";
 import { currentTimeHash } from "./time-hash.js";
 
+/**
+* Get the title of a bookmarked slack channel
+* @function 
+* @returns {Promise<string>}
+*/
 export async function fetchBookmarkTitle () {
   const response = await fetch('https://slack.com/api/bookmarks.list?channel_id=C0JDWKJVA', {
     headers: {
@@ -12,6 +17,12 @@ export async function fetchBookmarkTitle () {
   return title;
 }
 
+/**
+* Set the bookmark title of a slack channel
+* @function 
+* @param {string} title - The new title of the bookmark
+* @returns {Promise<Object>}
+*/
 export async function setBookmarkTitle (title) {
   const response = await fetch('https://slack.com/api/bookmarks.edit', {
     method: 'POST',
@@ -31,16 +42,35 @@ export async function setBookmarkTitle (title) {
   return json;
 }
 
+/**
+* Return the number of participants in a hack night call
+* @function
+* @returns {Promise<number>}
+*/
 export async function fetchParticipantNumber () {
   const title = await fetchBookmarkTitle();
   const number = +(title.split('').filter(char => !isNaN(char)).join('') || '0');
   return number;
 }
 
+/**
+* Set the participant number in a hack night call
+* @function
+* @param {number} - number
+* @returns {Promise<string>}
+*/
 export async function setParticipantNumber (number) {
   return await setBookmarkTitle('Join Hack Night! 👤 ' + number);
 }
 
+/**
+* Return the stats of a hack night call
+* @function
+* @param {string} event - The event name e.g "meeting.ended"
+* @param {any} meeting
+* @param {Object} payload
+* @returns {Promise<void>}
+*/
 export default async function hackNightStats (event, meeting, payload) {
   switch (event) {
     case 'meeting.ended':

api/is-public-slack-channel.js

@@ -1,6 +1,12 @@
 import airbridge from "./airbridge.js"
 import fetch from 'node-fetch'
 
+/**
+* Returns true if the channelID is a public slack channel
+* @function
+* @param {string} channelID - The ID of the slack channel
+* @returns {Promise<boolean>}
+*/
 export default async function(channelID) {
   if (channelID[0].toLowerCase() != 'c') {
     // slack channels start with 'c'

api/open-zoom-meeting.js

@@ -8,6 +8,11 @@ const hackNightSettings = {
   participants_share_simultaneously: 'multiple'
 }
 
+/**
+* Pick a random host not used in a call
+* @function
+* @returns {Promise<Object>}
+*/
 async function availableHost() {
   const hosts = await Prisma.get("host", {
     where: {
@@ -26,6 +31,14 @@ async function availableHost() {
   return hosts[Math.floor(Math.random() * hosts.length)];
 }
 
+/**
+* Opens a new zoom meeting 
+* @function  
+* @param {Object} prop 
+* @param {string} prop.creatorSlackID - The ID of the slack creator
+* @param {boolean} prop.isHackNight - Should the zoom meeting be a hack night
+* @returns {Object}
+*/
 export default async ({ creatorSlackID, isHackNight } = {}) => {
   // find an open host w/ less then 2 open meetings. why 2? Zoom lets us host up to 2 concurrent meetings
   // https://support.zoom.us/hc/en-us/articles/206122046-Can-I-Host-Concurrent-Meetings-

api/prisma.js

@@ -1,8 +1,6 @@
 import pkg from "@prisma/client"
 import metrics from "../metrics.js"
 const { PrismaClient } = pkg
-let prisma = new PrismaClient()
-
 import Bottleneck from 'bottleneck'
 
 const VERBOSE_PRISMA_LOGGING = process.env.VERBOSE_PRISMA_LOGGING ? false : process.env.VERBOSE_PRISMA_LOGGING=='true'
@@ -11,9 +9,18 @@ const limiter = new Bottleneck({
   maxConcurrent: 4,
 })
 
+let prisma = new PrismaClient()
 // prismaGet('Meeting')
 // prismaGet('Meeting', '01234567')
 // prismaGet('Meeting', { where: {id: '01234567'} })
+
+/**
+* Get all records matching clauses in options
+* @function
+* @param {string} table - The name of the database table
+* @param {Object} options - options
+* @returns {Promise<Object[]>}
+*/
 const get = async (table, options) => {
   const ts = Date.now()
   if (VERBOSE_PRISMA_LOGGING)
@@ -42,6 +49,14 @@ const get = async (table, options) => {
 // prismaFind('User')
 // prismaFind('User', '01234567')
 // prismaFind('User', )
+
+/**
+* Returns a single record matching the clauses in options
+* @function 
+* @param {string} table - The database table name
+* @param {Object} options - The query options
+* @returns {Promise<Object>}
+*/
 const find = async (table, options) => {
   const ts = Date.now()
   if (VERBOSE_PRISMA_LOGGING)
@@ -66,6 +81,13 @@ const find = async (table, options) => {
   }
 }
 
+/**
+* Returns the number of records in table
+* @function
+* @param {string} table - The database table name
+* @param {Object} - The query options
+* @returns {Promise<number>}
+*/
 const count = async (table, options) => {
   let where, orderBy, include
   if (VERBOSE_PRISMA_LOGGING)
@@ -87,6 +109,14 @@ const count = async (table, options) => {
   }
 }
 
+/**
+* Update fields on record with {recordID} in table
+* @function
+* @param {string} table - The table name in the database
+* @param {string} recordID - The ID of the record in table
+* @param {Object} fields - The fields to update on the record
+* @returns {Promise<Object>} 
+*/
 const patch = async (table, recordID, fields) => {
   const ts = Date.now()
   try {
@@ -108,6 +138,13 @@ const patch = async (table, recordID, fields) => {
   }
 }
 
+/**
+* Create a new record with {fields} in {table}
+* @function 
+* @param {string} table - The database table name
+* @param {Object} fields - The new record's values
+* @returns {Promise<Object>}
+*/
 const create = async (table, fields) => {
   const ts = Date.now()
   try {
@@ -124,6 +161,13 @@ const create = async (table, fields) => {
   }
 }
 
+/**
+* Delete the record with id {id} from {table}
+* @function
+* @param {string} table - The database table name
+* @param {string} id - The id of the record to delete in {table}
+* @returns {Promise<Object>}
+*/
 const destroy = async (table, id) => {
   const ts = Date.now()
   try {

api/transcript.js

@@ -3,6 +3,13 @@ import { readFileSync } from 'fs'
 import path from 'path'
 import os from "os"
 
+/**
+* Returns the plural of {word}
+* @function
+* @param {string} word
+* @param {number} count
+* @returns {string}
+*/
 const pluralize = (word, count) => {
   // want to use this method? make sure to add your word to transcript.yml under 'plurals'
   if (count == 1) {
@@ -18,6 +25,11 @@ const sample = (arr) => {
   return arr[Math.floor(Math.random() * arr.length)]
 }
 
+/**
+* Loads the transcipt.yml file
+* @function
+* @returns {string}
+*/
 const loadTranscript = () => {
   const moduleURL = new URL(import.meta.url);
   let __dirname = decodeURIComponent(path.dirname(moduleURL.pathname));
@@ -32,6 +44,7 @@ const loadTranscript = () => {
     console.error(e)
   }
 }
+
 const recurseTranscript = (searchArr, transcriptObj, fallback) => {
   const searchCursor = searchArr.shift()
   const targetObj = transcriptObj[searchCursor]
@@ -66,6 +79,14 @@ const replaceErrors = (key, value) => {
   return value
 }
 
+/**
+* Returns the 
+* @function
+* @param {string} search - the word to transcribe
+* @param {Object} vars
+* @param {Object} fallback
+* @returns {string} 
+*/
 const transcript = (search, vars, fallback) => {
   if (vars) {
     console.log(
@@ -82,6 +103,7 @@ const transcript = (search, vars, fallback) => {
   const dehydratedTarget = recurseTranscript(searchArr, transcriptObj, fallback)
   return hydrateObj(dehydratedTarget, vars)
 }
+
 const hydrateObj = (obj, vars = {}) => {
   if (obj == null) {
     return null

api/user-is-restricted.js

@@ -1,5 +1,11 @@
 import fetch from 'node-fetch'
 
+/**
+* Determine if a channel is restricted or not
+* @function
+* @param {string} userID - The slack user ID
+* @returns {Promise<boolean>}
+*/
 export default async (userID) => {
   const userInfo = await fetch(`https://slack.com/api/users.info?user=${userID}`, {
     headers: {