add documentation comments

.changeset/nervous-carrots-complain.md

@@ -0,0 +1,5 @@
+---
+"google-indexing-script": patch
+---
+
+Add documentation comments

src/index.ts

@@ -21,6 +21,11 @@ export type IndexOptions = {
   path?: string;
 };
 
+/**
+ * Indexes the specified domain or site URL.
+ * @param input - The domain or site URL to index.
+ * @param options - (Optional) Additional options for indexing.
+ */
 export const index = async (
   input: string = process.argv[2],
   options: IndexOptions = {},

src/shared/auth.ts

@@ -3,6 +3,13 @@ import fs from "fs";
 import path from "path";
 import os from "os";
 
+/**
+ * Retrieves an access token for Google APIs using service account credentials.
+ * @param client_email - The client email of the service account.
+ * @param private_key - The private key of the service account.
+ * @param customPath - (Optional) Custom path to the service account JSON file.
+ * @returns The access token.
+ */
 export async function getAccessToken(client_email?: string, private_key?: string, customPath?: string) {
   if (!client_email && !private_key) {
     const filePath = "service_account.json";

src/shared/gsc.ts

@@ -1,6 +1,11 @@
 import { Status } from "./types";
 import { fetchRetry } from "./utils";
 
+/**
+ * Converts a given input string to a valid Google Search Console site URL format.
+ * @param input - The input string to be converted.
+ * @returns The converted site URL (domain.com or https://domain.com/)
+ */
 export function convertToSiteUrl(input: string) {
   if (input.startsWith("http://") || input.startsWith("https://")) {
     return input.endsWith("/") ? input : `${input}/`;
@@ -8,10 +13,22 @@ export function convertToSiteUrl(input: string) {
   return `sc-domain:${input}`;
 }
 
+/**
+ * Converts a given file path to a formatted version suitable for use as a file name.
+ * @param path - The url to be converted as a file name
+ * @returns The converted file path
+ */
 export function convertToFilePath(path: string) {
   return path.replace("http://", "http_").replace("https://", "https_").replace("/", "_");
 }
 
+/**
+ * Retrieves the indexing status of a page.
+ * @param accessToken - The access token for authentication.
+ * @param siteUrl - The URL of the site.
+ * @param inspectionUrl - The URL of the page to inspect.
+ * @returns A promise resolving to the status of indexing.
+ */
 export async function getPageIndexingStatus(
   accessToken: string,
   siteUrl: string,
@@ -58,6 +75,11 @@ export async function getPageIndexingStatus(
   }
 }
 
+/**
+ * Retrieves an emoji representation corresponding to the given status.
+ * @param status - The status for which to retrieve the emoji.
+ * @returns The emoji representing the status.
+ */
 export function getEmojiForStatus(status: Status) {
   switch (status) {
     case Status.SubmittedAndIndexed:
@@ -78,6 +100,12 @@ export function getEmojiForStatus(status: Status) {
   }
 }
 
+/**
+ * Retrieves metadata for publishing from the given URL.
+ * @param accessToken - The access token for authentication.
+ * @param url - The URL for which to retrieve metadata.
+ * @returns The status of the request.
+ */
 export async function getPublishMetadata(accessToken: string, url: string) {
   const response = await fetchRetry(
     `https://indexing.googleapis.com/v3/urlNotifications/metadata?url=${encodeURIComponent(url)}`,
@@ -114,6 +142,11 @@ export async function getPublishMetadata(accessToken: string, url: string) {
   return response.status;
 }
 
+/**
+ * Requests indexing for the given URL.
+ * @param accessToken - The access token for authentication.
+ * @param url - The URL to be indexed.
+ */
 export async function requestIndexing(accessToken: string, url: string) {
   const response = await fetchRetry("https://indexing.googleapis.com/v3/urlNotifications:publish", {
     method: "POST",

src/shared/sitemap.ts

@@ -2,6 +2,12 @@ import Sitemapper from "sitemapper";
 import { fetchRetry } from "./utils";
 import { webmasters_v3 } from "googleapis";
 
+/**
+ * Retrieves a list of sitemaps associated with the specified site URL from the Google Webmasters API.
+ * @param accessToken The access token for authentication.
+ * @param siteUrl The URL of the site for which to retrieve the list of sitemaps.
+ * @returns An array containing the paths of the sitemaps associated with the site URL.
+ */
 async function getSitemapsList(accessToken: string, siteUrl: string) {
   const url = `https://www.googleapis.com/webmasters/v3/sites/${encodeURIComponent(siteUrl)}/sitemaps`;
 
@@ -34,6 +40,12 @@ async function getSitemapsList(accessToken: string, siteUrl: string) {
   return body.sitemap.filter((x) => x.path !== undefined && x.path !== null).map((x) => x.path as string);
 }
 
+/**
+ * Retrieves a list of pages from all sitemaps associated with the specified site URL.
+ * @param accessToken The access token for authentication.
+ * @param siteUrl The URL of the site for which to retrieve the sitemap pages.
+ * @returns An array containing the list of sitemaps and an array of unique page URLs extracted from those sitemaps.
+ */
 export async function getSitemapPages(accessToken: string, siteUrl: string) {
   const sitemaps = await getSitemapsList(accessToken, siteUrl);
 

src/shared/types.ts

@@ -1,3 +1,6 @@
+/**
+ * Enum representing indexing status of a URL
+ */
 export enum Status {
   SubmittedAndIndexed = "Submitted and indexed",
   DuplicateWithoutUserSelectedCanonical = "Duplicate without user-selected canonical",

src/shared/utils.ts

@@ -1,6 +1,19 @@
+/**
+ * Creates an array of chunks from the given array with a specified size.
+ * @param arr The array to be chunked.
+ * @param size The size of each chunk.
+ * @returns An array of chunks.
+ */
 const createChunks = (arr: any[], size: number) =>
   Array.from({ length: Math.ceil(arr.length / size) }, (_, i) => arr.slice(i * size, i * size + size));
 
+/**
+ * Executes tasks on items in batches and invokes a callback upon completion of each batch.
+ * @param task The task function to be executed on each item.
+ * @param items The array of items on which the task is to be executed.
+ * @param batchSize The size of each batch.
+ * @param onBatchComplete The callback function invoked upon completion of each batch.
+ */
 export async function batch(
   task: (url: string) => void,
   items: string[],
@@ -14,6 +27,14 @@ export async function batch(
   }
 }
 
+/**
+ * Fetches a resource from a URL with retry logic.
+ * @param url The URL of the resource to fetch.
+ * @param options The options for the fetch request.
+ * @param retries The number of retry attempts (default is 5).
+ * @returns A Promise resolving to the fetched response.
+ * @throws Error when retries are exhausted or server error occurs.
+ */
 export async function fetchRetry(url: string, options: RequestInit, retries: number = 5) {
   try {
     const response = await fetch(url, options);
@@ -30,6 +51,11 @@ export async function fetchRetry(url: string, options: RequestInit, retries: num
   }
 }
 
+/**
+ * Parses command-line arguments and returns key-value pairs.
+ * @param argv The array of command-line arguments.
+ * @returns An object containing parsed key-value pairs.
+ */
 export function parseCommandLineArgs(argv: string[]) {
   const parsedArgs: { [key: string]: string } = {};