From 4a69884b3268b00bdf17808796d1d03ba9cc801a Mon Sep 17 00:00:00 2001 From: Justin Hall Date: Wed, 8 Nov 2023 21:53:49 -0700 Subject: [PATCH] fix: add descriptions to each config option (#428) --- .changeset/fair-beds-sneeze.md | 5 +++++ src/breach.ts | 8 ++++++++ src/breached-account.ts | 21 +++++++++++++++++++++ src/breaches.ts | 11 +++++++++++ src/data-classes.ts | 8 ++++++++ src/paste-account.ts | 11 +++++++++++ src/pwned-password-range.ts | 27 +++++++++++++++++++++------ src/pwned-password.ts | 18 +++++++++++++++--- src/search.ts | 18 ++++++++++++++++++ src/subscription-status.ts | 11 +++++++++++ 10 files changed, 129 insertions(+), 9 deletions(-) create mode 100644 .changeset/fair-beds-sneeze.md diff --git a/.changeset/fair-beds-sneeze.md b/.changeset/fair-beds-sneeze.md new file mode 100644 index 00000000..177afefd --- /dev/null +++ b/.changeset/fair-beds-sneeze.md @@ -0,0 +1,5 @@ +--- +'hibp': patch +--- + +Add descriptions to each config option for a better IDE experience. diff --git a/src/breach.ts b/src/breach.ts index 6ee6943c..1ad268de 100644 --- a/src/breach.ts +++ b/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 `) + */ userAgent?: string; } = {}, ): Promise { diff --git a/src/breached-account.ts b/src/breached-account.ts index 9d2959ea..9b9ae131 100644 --- a/src/breached-account.ts +++ b/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 `) + */ userAgent?: string; } = {}, ): Promise { diff --git a/src/breaches.ts b/src/breaches.ts index d052a62b..36366b85 100644 --- a/src/breaches.ts +++ b/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 `) + */ userAgent?: string; } = {}, ): Promise { diff --git a/src/data-classes.ts b/src/data-classes.ts index 151a0a3b..94833983 100644 --- a/src/data-classes.ts +++ b/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 `) + */ userAgent?: string; } = {}, ): Promise { diff --git a/src/paste-account.ts b/src/paste-account.ts index 0bfe0064..57bc5d7e 100644 --- a/src/paste-account.ts +++ b/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 `) + */ userAgent?: string; } = {}, ): Promise { diff --git a/src/pwned-password-range.ts b/src/pwned-password-range.ts index e20b4749..f9e64c34 100644 --- a/src/pwned-password-range.ts +++ b/src/pwned-password-range.ts @@ -22,14 +22,14 @@ export type PwnedPasswordSuffixes = Record; * @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 `) * @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 `) * @returns {Promise} 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; 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 `) + */ + userAgent?: string; } = {}, ): Promise { const { baseUrl, userAgent, addPadding = false, mode = 'sha1' } = options; diff --git a/src/pwned-password.ts b/src/pwned-password.ts index aad81c3e..bc87dafd 100644 --- a/src/pwned-password.ts +++ b/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 `) - * @param {boolean} [options.addPadding] ask the remote API to add padding to - * the response to obscure the password prefix (default: `false`) * @returns {Promise} 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 `) + */ userAgent?: string; - addPadding?: boolean; } = {}, ): Promise { /* eslint-disable */ diff --git a/src/search.ts b/src/search.ts index 76a29832..08044d53 100644 --- a/src/search.ts +++ b/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 `) + */ userAgent?: string; } = {}, ): Promise { diff --git a/src/subscription-status.ts b/src/subscription-status.ts index a943b410..8ba95f32 100644 --- a/src/subscription-status.ts +++ b/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 `) + */ userAgent?: string; } = {}, ) {