diff --git a/utils/domains.ts b/utils/domains.ts index 0f81760..dc4b673 100644 --- a/utils/domains.ts +++ b/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 => { const finalDomains: DomainType[] = []; console.log('domains: ', domains.length); diff --git a/utils/insight.ts b/utils/insight.ts index 148f931..d5dd4d8 100644 --- a/utils/insight.ts +++ b/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 } = {}; diff --git a/utils/searchConsole.ts b/utils/searchConsole.ts index bbb5227..c4b34e7 100644 --- a/utils/searchConsole.ts +++ b/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} + */ const fetchSearchConsoleData = async (domainName:string, days:number, type?:string): Promise => { 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 => { 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 { 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} + */ export const readLocalSCData = async (domain:string): Promise => { 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 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} + */ export const updateLocalSCData = async (domain:string, scDomainData?:SCDomainDataType): Promise => { const filePath = `${process.cwd()}/data/SC_${domain}.json`; const emptyData:SCDomainDataType = { threeDays: [], sevenDays: [], thirtyDays: [], lastFetched: '', lastFetchError: '' };