fix: add descriptions to each config option (#428)

.changeset/fair-beds-sneeze.md

@@ -0,0 +1,5 @@
+---
+'hibp': patch
+---
+
+Add descriptions to each config option for a better IDE experience.

src/breach.ts

@@ -52,7 +52,15 @@ import { fetchFromApi } from './api/haveibeenpwned/fetch-from-api.js';
 export function breach(
   breachName: string,
   options: {
+    /**
+     * a custom base URL for the haveibeenpwned.com API endpoints (default:
+     * `https://haveibeenpwned.com/api/v3`)
+     */
     baseUrl?: string;
+    /**
+     * a custom string to send as the User-Agent field in the request headers
+     * (default: `hibp <version>`)
+     */
     userAgent?: string;
   } = {},
 ): Promise<Breach | null> {

src/breached-account.ts

@@ -73,11 +73,32 @@ import { fetchFromApi } from './api/haveibeenpwned/fetch-from-api.js';
 export function breachedAccount(
   account: string,
   options: {
+    /**
+     * an API key from https://haveibeenpwned.com/API/Key (default: undefined)
+     */
     apiKey?: string;
+    /**
+     * a domain by which to filter the results (default: all domains)
+     */
     domain?: string;
+    /**
+     * include "unverified" breaches in the results (default: true)
+     */
     includeUnverified?: boolean;
+    /**
+     * truncate the results to only include the name of each breach (default:
+     * true)
+     */
     truncate?: boolean;
+    /**
+     * a custom base URL for the haveibeenpwned.com API endpoints (default:
+     * `https://haveibeenpwned.com/api/v3`)
+     */
     baseUrl?: string;
+    /**
+     * a custom string to send as the User-Agent field in the request headers
+     * (default: `hibp <version>`)
+     */
     userAgent?: string;
   } = {},
 ): Promise<Breach[] | null> {

src/breaches.ts

@@ -39,8 +39,19 @@ import { fetchFromApi } from './api/haveibeenpwned/fetch-from-api.js';
  */
 export function breaches(
   options: {
+    /**
+     * a domain by which to filter the results (default: all domains)
+     */
     domain?: string;
+    /**
+     * a custom base URL for the haveibeenpwned.com API endpoints (default:
+     * `https://haveibeenpwned.com/api/v3`)
+     */
     baseUrl?: string;
+    /**
+     * a custom string to send as the User-Agent field in the request headers
+     * (default: `hibp <version>`)
+     */
     userAgent?: string;
   } = {},
 ): Promise<Breach[]> {

src/data-classes.ts

@@ -26,7 +26,15 @@ import { fetchFromApi } from './api/haveibeenpwned/fetch-from-api.js';
  */
 export function dataClasses(
   options: {
+    /**
+     * a custom base URL for the haveibeenpwned.com API endpoints (default:
+     * `https://haveibeenpwned.com/api/v3`)
+     */
     baseUrl?: string;
+    /**
+     * a custom string to send as the User-Agent field in the request headers
+     * (default: `hibp <version>`)
+     */
     userAgent?: string;
   } = {},
 ): Promise<string[] | null> {

src/paste-account.ts

@@ -61,8 +61,19 @@ import { fetchFromApi } from './api/haveibeenpwned/fetch-from-api.js';
 export function pasteAccount(
   email: string,
   options: {
+    /**
+     * an API key from https://haveibeenpwned.com/API/Key (default: undefined)
+     */
     apiKey?: string;
+    /**
+     * a custom base URL for the haveibeenpwned.com API endpoints (default:
+     * `https://haveibeenpwned.com/api/v3`)
+     */
     baseUrl?: string;
+    /**
+     * a custom string to send as the User-Agent field in the request headers
+     * (default: `hibp <version>`)
+     */
     userAgent?: string;
   } = {},
 ): Promise<Paste[] | null> {

src/pwned-password-range.ts

@@ -22,14 +22,14 @@ export type PwnedPasswordSuffixes = Record<string, number>;
  * @param {string} prefix the first 5 characters of a password hash (case
  * insensitive)
  * @param {object} [options] a configuration object
- * @param {string} [options.baseUrl] a custom base URL for the
- * pwnedpasswords.com API endpoints (default: `https://api.pwnedpasswords.com`)
- * @param {string} [options.userAgent] a custom string to send as the User-Agent
- * field in the request headers (default: `hibp <version>`)
  * @param {boolean} [options.addPadding] ask the remote API to add padding to
  * the response to obscure the password prefix (default: `false`)
  * @param {'sha1' | 'ntlm'} [options.mode] return SHA-1 or NTLM hashes
  * (default: `sha1`)
+ * @param {string} [options.baseUrl] a custom base URL for the
+ * pwnedpasswords.com API endpoints (default: `https://api.pwnedpasswords.com`)
+ * @param {string} [options.userAgent] a custom string to send as the User-Agent
+ * field in the request headers (default: `hibp <version>`)
  * @returns {Promise<PwnedPasswordSuffixes>} a Promise which resolves to an
  * object mapping the `suffix` that when matched with the prefix composes the
  * complete hash, to the `count` of how many times it appears in the breached
@@ -60,10 +60,25 @@ export type PwnedPasswordSuffixes = Record<string, number>;
 export async function pwnedPasswordRange(
   prefix: string,
   options: {
-    baseUrl?: string;
-    userAgent?: string;
+    /**
+     * ask the remote API to add padding to the response to obscure the password
+     * prefix (default: `false`)
+     */
     addPadding?: boolean;
+    /**
+     * return SHA-1 or NTLM hashes (default: `sha1`)
+     */
     mode?: 'sha1' | 'ntlm';
+    /**
+     * a custom base URL for the haveibeenpwned.com API endpoints (default:
+     * `https://haveibeenpwned.com/api/v3`)
+     */
+    baseUrl?: string;
+    /**
+     * a custom string to send as the User-Agent field in the request headers
+     * (default: `hibp <version>`)
+     */
+    userAgent?: string;
   } = {},
 ): Promise<PwnedPasswordSuffixes> {
   const { baseUrl, userAgent, addPadding = false, mode = 'sha1' } = options;

src/pwned-password.ts

@@ -8,12 +8,12 @@ import { pwnedPasswordRange } from './pwned-password-range.js';
  *
  * @param {string} password a password in plain text
  * @param {object} [options] a configuration object
+ * @param {boolean} [options.addPadding] ask the remote API to add padding to
+ * the response to obscure the password prefix (default: `false`)
  * @param {string} [options.baseUrl] a custom base URL for the
  * pwnedpasswords.com API endpoints (default: `https://api.pwnedpasswords.com`)
  * @param {string} [options.userAgent] a custom string to send as the User-Agent
  * field in the request headers (default: `hibp <version>`)
- * @param {boolean} [options.addPadding] ask the remote API to add padding to
- * the response to obscure the password prefix (default: `false`)
  * @returns {Promise<number>} a Promise which resolves to the number of times
  * the password has been exposed in a breach, or rejects with an Error
  * @example
@@ -33,9 +33,21 @@ import { pwnedPasswordRange } from './pwned-password-range.js';
 export async function pwnedPassword(
   password: string,
   options: {
+    /**
+     * ask the remote API to add padding to the response to obscure the password
+     * prefix (default: `false`)
+     */
+    addPadding?: boolean;
+    /**
+     * a custom base URL for the haveibeenpwned.com API endpoints (default:
+     * `https://haveibeenpwned.com/api/v3`)
+     */
     baseUrl?: string;
+    /**
+     * a custom string to send as the User-Agent field in the request headers
+     * (default: `hibp <version>`)
+     */
     userAgent?: string;
-    addPadding?: boolean;
   } = {},
 ): Promise<number> {
   /* eslint-disable */

src/search.ts

@@ -77,10 +77,28 @@ export interface SearchResults {
 export async function search(
   account: string,
   options: {
+    /**
+     * an API key from https://haveibeenpwned.com/API/Key (default: undefined)
+     */
     apiKey?: string;
+    /**
+     * a domain by which to filter the results (default: all domains)
+     */
     domain?: string;
+    /**
+     * truncate the results to only include the name of each breach (default:
+     * true)
+     */
     truncate?: boolean;
+    /**
+     * a custom base URL for the haveibeenpwned.com API endpoints (default:
+     * `https://haveibeenpwned.com/api/v3`)
+     */
     baseUrl?: string;
+    /**
+     * a custom string to send as the User-Agent field in the request headers
+     * (default: `hibp <version>`)
+     */
     userAgent?: string;
   } = {},
 ): Promise<SearchResults> {

src/subscription-status.ts

@@ -50,8 +50,19 @@ import { fetchFromApi } from './api/haveibeenpwned/fetch-from-api.js';
  */
 export async function subscriptionStatus(
   options: {
+    /**
+     * an API key from https://haveibeenpwned.com/API/Key (default: undefined)
+     */
     apiKey?: string;
+    /**
+     * a custom base URL for the haveibeenpwned.com API endpoints (default:
+     * `https://haveibeenpwned.com/api/v3`)
+     */
     baseUrl?: string;
+    /**
+     * a custom string to send as the User-Agent field in the request headers
+     * (default: `hibp <version>`)
+     */
     userAgent?: string;
   } = {},
 ) {