docs: Adds docs for Google Search console related functions

utils/domains.ts

@@ -2,6 +2,12 @@ import Keyword from '../database/models/keyword';
 import parseKeywords from './parseKeywords';
 import { readLocalSCData } from './searchConsole';
 
+/**
+ * The function `getdomainStats` takes an array of domain objects, retrieves keyword and stats data for
+ * each domain, and calculates various statistics for each domain.
+ * @param {DomainType[]} domains - An array of objects of type DomainType.
+ * @returns {DomainType[]} - An array of objects of type DomainType.
+ */
 const getdomainStats = async (domains:DomainType[]): Promise<DomainType[]> => {
    const finalDomains: DomainType[] = [];
    console.log('domains: ', domains.length);

utils/insight.ts

@@ -1,4 +1,10 @@
-export const sortInsightItems = (items:SCInsightItem[], sortBy: string = 'clicks') => {
+/**
+ * The function `sortInsightItems` sorts an array of `SCInsightItem` objects based on a specified property.
+ * @param {SCInsightItem[]} items - An array of SCInsightItem objects.
+ * @param {string} [sortBy=clicks] - The `sortBy` parameter determines the property by which the `items` array should be sorted.
+ * @returns {SCInsightItem[]}
+ */
+export const sortInsightItems = (items:SCInsightItem[], sortBy: string = 'clicks'): SCInsightItem[] => {
    const sortKey = sortBy as keyof SCInsightItem;
    let sortedItems = [];
    switch (sortKey) {
@@ -18,6 +24,13 @@ export const sortInsightItems = (items:SCInsightItem[], sortBy: string = 'clicks
    return sortedItems;
 };
 
+/**
+ * The `getCountryInsight` function takes search analytics data and returns insights about countries based on clicks, impressions, CTR, and position.
+ * @param {SCDomainDataType} SCData - The SCData parameter is an object that contains search analytics data for different dates.
+ * @param {string} [sortBy=clicks] - The "sortBy" parameter is used to specify the sorting criteria for the country insights.
+ * @param {string} [queryDate=thirtyDays] - The `queryDate` parameter is a string that represents the date range for which the search analytics data is retrieved.
+ * @returns {SCInsightItem[]}
+ */
 export const getCountryInsight = (SCData:SCDomainDataType, sortBy:string = 'clicks', queryDate:string = 'thirtyDays') : SCInsightItem[] => {
    const keywordsCounts: { [key:string]: string[] } = {};
    const countryItems: { [key:string]: SCInsightItem } = {};
@@ -57,6 +70,13 @@ export const getCountryInsight = (SCData:SCDomainDataType, sortBy:string = 'clic
    return sortBy ? sortInsightItems(countryInsight, sortBy) : countryInsight;
 };
 
+/**
+ * The `getKeywordsInsight` function takes search analytics data, sorts it based on specified criteria, and returns insights on keywords.
+ * @param {SCDomainDataType} SCData - The SCData parameter is of type SCDomainDataType, which is an object containing search analytics data for a specific domain.
+ * @param {string} [sortBy=clicks] - The "sortBy" parameter is used to specify the sorting criteria for the keyword insights.
+ * @param {string} [queryDate=thirtyDays] - The `queryDate` parameter is a string that represents the date range for which the search analytics data is retrieved.
+ * @returns {SCInsightItem[]}
+ */
 export const getKeywordsInsight = (SCData:SCDomainDataType, sortBy:string = 'clicks', queryDate:string = 'thirtyDays') : SCInsightItem[] => {
    const keywordItems: { [key:string]: SCInsightItem } = {};
    const keywordCounts: { [key:string]: number } = {};
@@ -99,6 +119,13 @@ export const getKeywordsInsight = (SCData:SCDomainDataType, sortBy:string = 'cli
    return sortBy ? sortInsightItems(keywordInsight, sortBy) : keywordInsight;
 };
 
+/**
+ * The `getPagesInsight` function takes a domain's search analytics data, sorts it based on specified criteria and returns insights about the pages.
+ * @param {SCDomainDataType} SCData - SCData is an object that contains search analytics data for a  specific domain.
+ * @param {string} [sortBy=clicks] - The `sortBy` parameter is used to specify the sorting criteria for the pages insight.
+ * @param {string} [queryDate=thirtyDays] - The `queryDate` parameter is a string that represents the date range for which you want to retrieve the data.
+ * @returns {SCInsightItem[]}
+ */
 export const getPagesInsight = (SCData:SCDomainDataType, sortBy:string = 'clicks', queryDate:string = 'thirtyDays') : SCInsightItem[] => {
    const pagesItems: { [key:string]: SCInsightItem } = {};
    const keywordCounts: { [key:string]: number } = {};

utils/searchConsole.ts

@@ -6,7 +6,16 @@ export type SCDomainFetchError = {
    error: boolean,
    errorMsg: string,
 }
+
 type fetchConsoleDataResponse = SearchAnalyticsItem[] | SearchAnalyticsStat[] | SCDomainFetchError;
+
+/**
+ * function that retrieves data from the Google Search Console API based on the provided domain name, number of days, and optional type.
+ * @param {string} domainName - The domain name for which you want to fetch search console data.
+ * @param {number} days - The `days` parameter is the number of days of data you want to fetch from the Search Console.
+ * @param {string} [type] - The `type` parameter is an optional parameter that specifies the type of data to fetch from the Search Console API.
+ * @returns {Promise<fetchConsoleDataResponse>}
+ */
 const fetchSearchConsoleData = async (domainName:string, days:number, type?:string): Promise<fetchConsoleDataResponse> => {
    if (!domainName) return { error: true, errorMsg: 'Domain Not Provided!' };
    try {
@@ -68,6 +77,13 @@ const fetchSearchConsoleData = async (domainName:string, days:number, type?:stri
    }
 };
 
+/**
+ * The function fetches search console data for a given domain and returns it in a structured format.
+ * @param {string} domain - The `domain` parameter is a string that represents the domain for which we
+ * want to fetch search console data.
+ * @returns The function `fetchDomainSCData` is returning a Promise that resolves to an object of type
+ * `SCDomainDataType`.
+ */
 export const fetchDomainSCData = async (domain:string): Promise<SCDomainDataType> => {
    const days = [3, 7, 30];
    const scDomainData:SCDomainDataType = { threeDays: [], sevenDays: [], thirtyDays: [], lastFetched: '', lastFetchError: '', stats: [] };
@@ -93,6 +109,12 @@ export const fetchDomainSCData = async (domain:string): Promise<SCDomainDataType
    return scDomainData;
 };
 
+/**
+ * The function takes a raw search console item and a domain name as input and returns a parsed search analytics item.
+ * @param {SearchAnalyticsRawItem} SCItem - The SCItem parameter is an object that represents a raw item from the Search Console API.
+ * @param {string} domainName - The `domainName` parameter is a string that represents the domain name of the website.
+ * @returns {SearchAnalyticsItem}.
+ */
 export const parseSearchConsoleItem = (SCItem: SearchAnalyticsRawItem, domainName: string): SearchAnalyticsItem => {
    const { clicks = 0, impressions = 0, ctr = 0, position = 0 } = SCItem;
    const keyword = SCItem.keys[0];
@@ -104,6 +126,12 @@ export const parseSearchConsoleItem = (SCItem: SearchAnalyticsRawItem, domainNam
    return { keyword, uid, device, country, clicks, impressions, ctr: ctr * 100, position, page };
 };
 
+/**
+ * The function integrates search console data with a keyword object and returns the updated keyword object with the search console data.
+ * @param {KeywordType} keyword - The `keyword` parameter is of type `KeywordType`, which is a custom type representing a keyword.
+ * @param {SCDomainDataType} SCData - SCData is an object that contains search analytics data for different time periods
+ * @returns {KeywordType}
+ */
 export const integrateKeywordSCData = (keyword: KeywordType, SCData:SCDomainDataType) : KeywordType => {
    const kuid = `${keyword.country.toLowerCase()}:${keyword.device}:${keyword.keyword.replaceAll(' ', '_')}`;
    const impressions:any = { yesterday: 0, threeDays: 0, sevenDays: 0, thirtyDays: 0, avgSevenDays: 0, avgThreeDays: 0, avgThirtyDays: 0 };
@@ -136,6 +164,11 @@ export const integrateKeywordSCData = (keyword: KeywordType, SCData:SCDomainData
    return { ...keyword, scData: finalSCData };
 };
 
+/**
+ * The function reads and returns the domain-specific data stored in a local JSON file.
+ * @param {string} domain - The `domain` parameter is a string that represents the domain for which the SC data is being read.
+ * @returns {Promise<SCDomainDataType>}
+ */
 export const readLocalSCData = async (domain:string): Promise<SCDomainDataType> => {
    const filePath = `${process.cwd()}/data/SC_${domain}.json`;
    const currentQueueRaw = await readFile(filePath, { encoding: 'utf-8' }).catch(async () => { await updateLocalSCData(domain); return '{}'; });
@@ -143,6 +176,12 @@ export const readLocalSCData = async (domain:string): Promise<SCDomainDataType>
    return domainSCData;
 };
 
+/**
+ * The function reads and returns the domain-specific data stored in a local JSON file.
+ * @param {string} domain - The `domain` parameter is a string that represents the domain for which the SC data will be written.
+ * @param {SCDomainDataType} scDomainData - an object that contains search analytics data for different time periods.
+ * @returns {Promise<SCDomainDataType|false>}
+ */
 export const updateLocalSCData = async (domain:string, scDomainData?:SCDomainDataType): Promise<SCDomainDataType|false> => {
    const filePath = `${process.cwd()}/data/SC_${domain}.json`;
    const emptyData:SCDomainDataType = { threeDays: [], sevenDays: [], thirtyDays: [], lastFetched: '', lastFetchError: '' };