Generate API documentation via TypeDoc

Fixes #796

---

For more details, open the [Copilot Workspace session](https://copilot-workspace.githubnext.com/chapter-three/next-drupal/issues/796?shareId=XXXX-XXXX-XXXX-XXXX).

Author: backlineint

packages/next-drupal/src/next-drupal-base.ts

@@ -30,6 +30,9 @@ const DEFAULT_HEADERS = {
   Accept: "application/json",
 }
 
+/**
+ * The base class for NextDrupal clients.
+ */
 export class NextDrupalBase {
   accessToken?: NextDrupalBaseOptions["accessToken"]
 
@@ -173,6 +176,13 @@ export class NextDrupalBase {
     return this._token
   }
 
+  /**
+   * Fetches a resource from the given input URL or path.
+   *
+   * @param {RequestInfo} input The input URL or path.
+   * @param {FetchOptions} init The fetch options.
+   * @returns {Promise<Response>} The fetch response.
+   */
   async fetch(
     input: RequestInfo,
     { withAuth, ...init }: FetchOptions = {}
@@ -215,6 +225,12 @@ export class NextDrupalBase {
     return await fetch(input, init)
   }
 
+  /**
+   * Gets the authorization header value based on the provided auth configuration.
+   *
+   * @param {NextDrupalAuth} auth The auth configuration.
+   * @returns {Promise<string>} The authorization header value.
+   */
   async getAuthorizationHeader(auth: NextDrupalAuth) {
     let header: string
 
@@ -250,6 +266,13 @@ export class NextDrupalBase {
     return header
   }
 
+  /**
+   * Builds a URL with the given path and search parameters.
+   *
+   * @param {string} path The URL path.
+   * @param {EndpointSearchParams} searchParams The search parameters.
+   * @returns {URL} The constructed URL.
+   */
   buildUrl(path: string, searchParams?: EndpointSearchParams): URL {
     const url = new URL(path, this.baseUrl)
 
@@ -269,7 +292,15 @@ export class NextDrupalBase {
     return url
   }
 
-  // async so subclasses can query for endpoint discovery.
+  /**
+   * Builds an endpoint URL with the given options.
+   *
+   * @param {Object} options The options for building the endpoint.
+   * @param {string} options.locale The locale.
+   * @param {string} options.path The path.
+   * @param {EndpointSearchParams} options.searchParams The search parameters.
+   * @returns {Promise<string>} The constructed endpoint URL.
+   */
   async buildEndpoint({
     locale = "",
     path = "",
@@ -291,6 +322,16 @@ export class NextDrupalBase {
     ).toString()
   }
 
+  /**
+   * Constructs a path from the given segment and options.
+   *
+   * @param {string | string[]} segment The path segment.
+   * @param {Object} options The options for constructing the path.
+   * @param {Locale} options.locale The locale.
+   * @param {Locale} options.defaultLocale The default locale.
+   * @param {PathPrefix} options.pathPrefix The path prefix.
+   * @returns {string} The constructed path.
+   */
   constructPathFromSegment(
     segment: string | string[],
     options: {
@@ -338,6 +379,15 @@ export class NextDrupalBase {
     })
   }
 
+  /**
+   * Adds a locale prefix to the given path.
+   *
+   * @param {string} path The path.
+   * @param {Object} options The options for adding the locale prefix.
+   * @param {Locale} options.locale The locale.
+   * @param {Locale} options.defaultLocale The default locale.
+   * @returns {string} The path with the locale prefix.
+   */
   addLocalePrefix(
     path: string,
     options: { locale?: Locale; defaultLocale?: Locale } = {}
@@ -356,6 +406,12 @@ export class NextDrupalBase {
     return `${localePrefix}${path}`
   }
 
+  /**
+   * Gets an access token using the provided client ID and secret.
+   *
+   * @param {NextDrupalAuthClientIdSecret} clientIdSecret The client ID and secret.
+   * @returns {Promise<AccessToken>} The access token.
+   */
   async getAccessToken(
     clientIdSecret?: NextDrupalAuthClientIdSecret
   ): Promise<AccessToken> {
@@ -435,6 +491,12 @@ export class NextDrupalBase {
     return result
   }
 
+  /**
+   * Validates the draft URL using the provided search parameters.
+   *
+   * @param {URLSearchParams} searchParams The search parameters.
+   * @returns {Promise<Response>} The validation response.
+   */
   async validateDraftUrl(searchParams: URLSearchParams): Promise<Response> {
     const path = searchParams.get("path")
 
@@ -468,17 +530,35 @@ export class NextDrupalBase {
     return response
   }
 
+  /**
+   * Logs a debug message if debug mode is enabled.
+   *
+   * @param {string} message The debug message.
+   */
   debug(message) {
     this.isDebugEnabled && this.logger.debug(message)
   }
 
+  /**
+   * Throws an error if the response contains JSON:API errors.
+   *
+   * @param {Response} response The fetch response.
+   * @param {string} messagePrefix The error message prefix.
+   * @throws {JsonApiErrors} The JSON:API errors.
+   */
   async throwIfJsonErrors(response: Response, messagePrefix = "") {
     if (!response?.ok) {
       const errors = await this.getErrorsFromResponse(response)
       throw new JsonApiErrors(errors, response.status, messagePrefix)
     }
   }
 
+  /**
+   * Extracts errors from the fetch response.
+   *
+   * @param {Response} response The fetch response.
+   * @returns {Promise<string | JsonApiResponse>} The extracted errors.
+   */
   async getErrorsFromResponse(response: Response) {
     const type = response.headers.get("content-type")
     let error: JsonApiResponse | { message: string }
@@ -506,6 +586,12 @@ export class NextDrupalBase {
   }
 }
 
+/**
+ * Checks if the provided auth configuration is basic auth.
+ *
+ * @param {NextDrupalAuth} auth The auth configuration.
+ * @returns {boolean} True if the auth configuration is basic auth, false otherwise.
+ */
 export function isBasicAuth(
   auth: NextDrupalAuth
 ): auth is NextDrupalAuthUsernamePassword {
@@ -515,6 +601,12 @@ export function isBasicAuth(
   )
 }
 
+/**
+ * Checks if the provided auth configuration is access token auth.
+ *
+ * @param {NextDrupalAuth} auth The auth configuration.
+ * @returns {boolean} True if the auth configuration is access token auth, false otherwise.
+ */
 export function isAccessTokenAuth(
   auth: NextDrupalAuth
 ): auth is NextDrupalAuthAccessToken {
@@ -524,6 +616,12 @@ export function isAccessTokenAuth(
   )
 }
 
+/**
+ * Checks if the provided auth configuration is client ID and secret auth.
+ *
+ * @param {NextDrupalAuth} auth The auth configuration.
+ * @returns {boolean} True if the auth configuration is client ID and secret auth, false otherwise.
+ */
 export function isClientIdSecretAuth(
   auth: NextDrupalAuth
 ): auth is NextDrupalAuthClientIdSecret {

packages/next-drupal/src/next-drupal-pages.ts

@@ -27,6 +27,10 @@ import type {
   NextApiResponse,
 } from "next"
 
+/**
+ * The NextDrupalPages class extends the NextDrupal class and provides methods
+ * for interacting with a Drupal backend in the context of Next.js pages.
+ */
 export class NextDrupalPages extends NextDrupal {
   private serializer: DrupalClientOptions["serializer"]
 
@@ -59,6 +63,13 @@ export class NextDrupalPages extends NextDrupal {
     ) => this.serializer.deserialize(body, options)
   }
 
+  /**
+   * Gets the entry point for a given resource type.
+   *
+   * @param {string} resourceType The resource type.
+   * @param {Locale} locale The locale.
+   * @returns {Promise<string>} The entry point URL.
+   */
   async getEntryForResourceType(
     resourceType: string,
     locale?: Locale
@@ -74,6 +85,14 @@ export class NextDrupalPages extends NextDrupal {
     return new DrupalMenuTree<DrupalMenuItem>(links, parent)
   }
 
+  /**
+   * Gets a resource from the context.
+   *
+   * @param {string | DrupalTranslatedPath} input The input path or translated path.
+   * @param {GetStaticPropsContext} context The static props context.
+   * @param {Object} options Options for the request.
+   * @returns {Promise<T>} The fetched resource.
+   */
   async getResourceFromContext<T extends JsonApiResource>(
     input: string | DrupalTranslatedPath,
     context: GetStaticPropsContext,
@@ -157,6 +176,14 @@ export class NextDrupalPages extends NextDrupal {
     return resource
   }
 
+  /**
+   * Gets a collection of resources from the context.
+   *
+   * @param {string} type The type of the resources.
+   * @param {GetStaticPropsContext} context The static props context.
+   * @param {Object} options Options for the request.
+   * @returns {Promise<T>} The fetched collection of resources.
+   */
   async getResourceCollectionFromContext<T = JsonApiResource[]>(
     type: string,
     context: GetStaticPropsContext,
@@ -177,6 +204,14 @@ export class NextDrupalPages extends NextDrupal {
     })
   }
 
+  /**
+   * Gets a search index from the context.
+   *
+   * @param {string} name The name of the search index.
+   * @param {GetStaticPropsContext} context The static props context.
+   * @param {Object} options Options for the request.
+   * @returns {Promise<T>} The fetched search index.
+   */
   async getSearchIndexFromContext<T = JsonApiResource[]>(
     name: string,
     context: GetStaticPropsContext,
@@ -189,6 +224,13 @@ export class NextDrupalPages extends NextDrupal {
     })
   }
 
+  /**
+   * Translates a path from the context.
+   *
+   * @param {GetStaticPropsContext} context The static props context.
+   * @param {Object} options Options for the request.
+   * @returns {Promise<DrupalTranslatedPath | null>} The translated path.
+   */
   async translatePathFromContext(
     context: GetStaticPropsContext,
     options?: {
@@ -208,6 +250,13 @@ export class NextDrupalPages extends NextDrupal {
     })
   }
 
+  /**
+   * Gets the path from the context.
+   *
+   * @param {GetStaticPropsContext} context The static props context.
+   * @param {Object} options Options for the request.
+   * @returns {string} The constructed path.
+   */
   getPathFromContext(
     context: GetStaticPropsContext,
     options?: {
@@ -223,6 +272,14 @@ export class NextDrupalPages extends NextDrupal {
 
   getPathsFromContext = this.getStaticPathsFromContext
 
+  /**
+   * Gets static paths from the context.
+   *
+   * @param {string | string[]} types The types of the resources.
+   * @param {GetStaticPathsContext} context The static paths context.
+   * @param {Object} options Options for the request.
+   * @returns {Promise<GetStaticPathsResult<{ slug: string[] }>["paths"]>} The fetched static paths.
+   */
   async getStaticPathsFromContext(
     types: string | string[],
     context: GetStaticPathsContext,
@@ -291,6 +348,13 @@ export class NextDrupalPages extends NextDrupal {
     return paths.flat()
   }
 
+  /**
+   * Builds static paths from resources.
+   *
+   * @param {Object[]} resources The resources.
+   * @param {Object} options Options for the request.
+   * @returns {Object[]} The built static paths.
+   */
   buildStaticPathsFromResources(
     resources: {
       path: DrupalPathAlias
@@ -313,6 +377,13 @@ export class NextDrupalPages extends NextDrupal {
       : []
   }
 
+  /**
+   * Builds static paths parameters from paths.
+   *
+   * @param {string[]} paths The paths.
+   * @param {Object} options Options for the request.
+   * @returns {Object[]} The built static paths parameters.
+   */
   buildStaticPathsParamsFromPaths(
     paths: string[],
     options?: { pathPrefix?: PathPrefix; locale?: Locale }
@@ -342,6 +413,13 @@ export class NextDrupalPages extends NextDrupal {
     })
   }
 
+  /**
+   * Handles preview mode.
+   *
+   * @param {NextApiRequest} request The API request.
+   * @param {NextApiResponse} response The API response.
+   * @param {Object} options Options for the request.
+   */
   async preview(
     request: NextApiRequest,
     response: NextApiResponse,
@@ -411,6 +489,12 @@ export class NextDrupalPages extends NextDrupal {
     }
   }
 
+  /**
+   * Disables preview mode.
+   *
+   * @param {NextApiRequest} request The API request.
+   * @param {NextApiResponse} response The API response.
+   */
   async previewDisable(request: NextApiRequest, response: NextApiResponse) {
     // Disable both preview and draft modes.
     response.clearPreviewData()
@@ -427,6 +511,13 @@ export class NextDrupalPages extends NextDrupal {
     response.end()
   }
 
+  /**
+   * Gets the authentication configuration from the context and options.
+   *
+   * @param {GetStaticPropsContext} context The static props context.
+   * @param {JsonApiWithAuthOption} options Options for the request.
+   * @returns {NextDrupalAuth} The authentication configuration.
+   */
   getAuthFromContextAndOptions(
     context: GetStaticPropsContext,
     options: JsonApiWithAuthOption