feat: minor tweaks to plugin extensibility (#1221)

## 🧰 Changes

Minor updates to make plugin creation a little friendlier.

* [x] Ability to supply `handleAPIRes` a type generic for the response
coming out of our public API.
* [x] Ability to load in and extend our base command class, which has a
number of helpful utilities and error handling.

---------

Co-authored-by: Kanad Gupta <git@kanad.dev>

Author: erunion

src/lib/baseCommand.ts

@@ -9,7 +9,7 @@ import chalk from 'chalk';
 import debugPkg from 'debug';
 
 import { isGHA, isTest } from './isCI.js';
-import { handleAPIv2Res, readmeAPIv2Fetch } from './readmeAPIFetch.js';
+import { handleAPIv2Res, readmeAPIv2Fetch, type ResponseBody } from './readmeAPIFetch.js';
 
 type Flags<T extends typeof OclifCommand> = Interfaces.InferredFlags<(typeof BaseCommand)['baseFlags'] & T['flags']>;
 type Args<T extends typeof OclifCommand> = Interfaces.InferredArgs<T['args']>;
@@ -116,8 +116,8 @@ export default abstract class BaseCommand<T extends typeof OclifCommand> extends
   /**
    * Wrapper around `handleAPIv2Res` that binds the context of the class to the function.
    */
-  public async handleAPIRes(...args: Parameters<typeof handleAPIv2Res>) {
-    return handleAPIv2Res.call(this, ...args);
+  public async handleAPIRes<R extends ResponseBody = ResponseBody>(...args: Parameters<typeof handleAPIv2Res>) {
+    return handleAPIv2Res.call(this, ...args) as Promise<R>;
   }
 
   /**

src/lib/readmeAPIFetch.ts

@@ -57,6 +57,9 @@ export interface Mappings {
   parentPages: Record<string, string>;
 }
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface ResponseBody extends Record<string, any> {}
+
 export const emptyMappings: Mappings = { categories: {}, parentPages: {} };
 
 /**
@@ -371,7 +374,7 @@ export async function handleAPIv1Res(
  *
  * If we receive non-JSON responses, we consider them errors and throw them.
  */
-export async function handleAPIv2Res<T extends Hook.Context = Hook.Context>(
+export async function handleAPIv2Res<R extends ResponseBody = ResponseBody, T extends Hook.Context = Hook.Context>(
   /**
    * `this` does not have to be a hook, it can also be a Command class.
    * This type ensures that `this` has the `config` and `debug` properties.
@@ -383,25 +386,23 @@ export async function handleAPIv2Res<T extends Hook.Context = Hook.Context>(
    * we can skip parsing the JSON body using this flag.
    */
   skipJsonParsing = false,
-) {
+): Promise<R> {
   const contentType = res.headers.get('content-type') || '';
   const extension = mime.extension(contentType) || contentType.includes('json') ? 'json' : false;
   if (res.status === SUCCESS_NO_CONTENT) {
     // to prevent a memory leak, we should still consume the response body? even though we don't use it?
     // https://x.com/cramforce/status/1762142087930433999
     const body = await res.text();
     this.debug(`received status code ${res.status} from ${res.url} with no content: ${body}`);
-    return {};
+    return {} as R;
   } else if (skipJsonParsing) {
     // to prevent a memory leak, we should still consume the response body? even though we don't use it?
     // https://x.com/cramforce/status/1762142087930433999
     const body = await res.text();
     this.debug(`received status code ${res.status} from ${res.url} and not parsing JSON b/c of flag: ${body}`);
-    return {};
+    return {} as R;
   } else if (extension === 'json') {
-    // TODO: type this better
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const body = (await res.json()) as any;
+    const body = (await res.json()) as R;
     this.debug(`received status code ${res.status} from ${res.url} with JSON response: ${JSON.stringify(body)}`);
     if (!res.ok) {
       throw new APIv2Error(body as APIv2ErrorResponse);

src/lib/types/index.ts

@@ -15,6 +15,7 @@ type guidesRequestBodySchema =
 
 type projectSchema =
   (typeof readmeAPIv2Oas)['paths']['/projects/me']['get']['responses']['200']['content']['application/json']['schema'];
+
 /**
  * Derived from our API documentation, this is the schema for the `guides` object
  * as we send it to the ReadMe API.

src/types.ts

@@ -1,3 +1,4 @@
-export type { GuidesRequestRepresentation } from './lib/types/index.js';
+export type { GuidesRequestRepresentation, ProjectRepresentation } from './lib/types/index.js';
 export type { PageMetadata } from './lib/readPage.js';
 export type { PluginHooks } from './lib/hooks/exported.js';
+export type { ResponseBody } from './lib/readmeAPIFetch.js';

src/utils.ts

@@ -1 +1,4 @@
+import BaseCommand from './lib/baseCommand.js';
+
+export { BaseCommand };
 export { readmeAPIv2Fetch, handleAPIv2Res } from './lib/readmeAPIFetch.js';