hibp 0.0.0-dev.9896b89a → 0.0.0-dev.d74e2ad2

package/dist/cjs/hibp.d.cts

@@ -0,0 +1,663 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/**
+ * Custom error thrown when the haveibeenpwned.com API responds with 429 Too
+ * Many Requests. See the `retryAfterSeconds` property for the number of seconds
+ * to wait before attempting the request again.
+ *
+ * @see https://haveibeenpwned.com/API/v3#RateLimiting
+ */
+export declare class RateLimitError extends Error {
+	/**
+	 * The number of seconds to wait before attempting the request again. May be
+	 * `undefined` if the API does not provide a `retry-after` header, but this
+	 * should never happen.
+	 */
+	retryAfterSeconds: number | undefined;
+	constructor(retryAfter: ReturnType<Headers["get"]>, message: string | undefined, options?: ErrorOptions);
+}
+export interface Breach {
+	Name: string;
+	Title: string;
+	Domain: string;
+	BreachDate: string;
+	AddedDate: string;
+	ModifiedDate: string;
+	PwnCount: number;
+	Description: string;
+	DataClasses: string[];
+	IsVerified: boolean;
+	IsFabricated: boolean;
+	IsSensitive: boolean;
+	IsRetired: boolean;
+	IsSpamList: boolean;
+	IsMalware: boolean;
+	IsSubscriptionFree: boolean;
+	LogoPath: string;
+}
+export interface Paste {
+	Id: string;
+	Source: string;
+	Title: string;
+	Date: string;
+	EmailCount: number;
+}
+export interface SubscriptionStatus {
+	SubscriptionName: string;
+	Description: string;
+	SubscribedUntil: string;
+	Rpm: number;
+	DomainSearchMaxBreachedAccounts: number;
+}
+/**
+ * An object representing a breach.
+ *
+ * @typedef {object} Breach
+ * @property {string} Name
+ * @property {string} Title
+ * @property {string} Domain
+ * @property {string} BreachDate
+ * @property {string} AddedDate
+ * @property {string} ModifiedDate
+ * @property {number} PwnCount
+ * @property {string} Description
+ * @property {string[]} DataClasses
+ * @property {boolean} IsVerified
+ * @property {boolean} IsFabricated
+ * @property {boolean} IsSensitive
+ * @property {boolean} IsRetired
+ * @property {boolean} IsSpamList
+ * @property {boolean} IsMalware
+ * @property {boolean} IsSubscriptionFree
+ * @property {string} LogoPath
+ */
+/**
+ * Fetches data for a specific breach event.
+ *
+ * @param {string} breachName the name of a breach in the system
+ * @param {object} [options] a configuration object
+ * @param {string} [options.baseUrl] a custom base URL for the
+ * haveibeenpwned.com API endpoints (default:
+ * `https://haveibeenpwned.com/api/v3`)
+ * @param {string} [options.userAgent] a custom string to send as the User-Agent
+ * field in the request headers (default: `hibp <version>`)
+ * @returns {(Promise<Breach>|Promise<null>)} a Promise which resolves to an
+ * object representing a breach (or null if no breach was found), or rejects
+ * with an Error
+ * @example
+ * try {
+ *   const data = await breach("Adobe");
+ *   if (data) {
+ *     // ...
+ *   } else {
+ *     // ...
+ *   }
+ * } catch (err) {
+ *   // ...
+ * }
+ */
+export declare 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>;
+/**
+ * Fetches breach data for a specific account.
+ *
+ * 🔑 `haveibeenpwned.com` requires an API key from
+ * https://haveibeenpwned.com/API/Key for the `breachedaccount` endpoint. The
+ * `apiKey` option here is not explicitly required, but direct requests made
+ * without it will fail (unless you specify a `baseUrl` to a proxy that inserts
+ * a valid API key on your behalf).
+ *
+ * @param {string} account a username or email address
+ * @param {object} [options] a configuration object
+ * @param {string} [options.apiKey] an API key from
+ * https://haveibeenpwned.com/API/Key (default: undefined)
+ * @param {string} [options.domain] a domain by which to filter the results
+ * (default: all domains)
+ * @param {boolean} [options.includeUnverified] include "unverified" breaches in
+ * the results (default: true)
+ * @param {boolean} [options.truncate] truncate the results to only include
+ * the name of each breach (default: true)
+ * @param {string} [options.baseUrl] a custom base URL for the
+ * haveibeenpwned.com API endpoints (default:
+ * `https://haveibeenpwned.com/api/v3`)
+ * @param {string} [options.userAgent] a custom string to send as the User-Agent
+ * field in the request headers (default: `hibp <version>`)
+ * @returns {(Promise<Breach[]> | Promise<null>)} a Promise which resolves to an
+ * array of breach objects (or null if no breaches were found), or rejects with
+ * an Error
+ * @example
+ * try {
+ *   const data = await breachedAccount("foo", { apiKey: "my-api-key" });
+ *   if (data) {
+ *     // ...
+ *   } else {
+ *     // ...
+ *   }
+ * } catch (err) {
+ *   // ...
+ * }
+ * @example
+ * try {
+ *   const data = await breachedAccount("bar", {
+ *     includeUnverified: false,
+ *     baseUrl: "https://my-hibp-proxy:8080",
+ *   });
+ *   if (data) {
+ *     // ...
+ *   } else {
+ *     // ...
+ *   }
+ * } catch (err) {
+ *   // ...
+ * }
+ * @example
+ * try {
+ *   const data = await breachedAccount("baz", {
+ *     apiKey: "my-api-key",
+ *     domain: "adobe.com",
+ *     truncate: false,
+ *     userAgent: "my-app 1.0",
+ *   });
+ *   if (data) {
+ *     // ...
+ *   } else {
+ *     // ...
+ *   }
+ * } catch (err) {
+ *   // ...
+ * }
+ */
+export declare 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>;
+/**
+ * Fetches all breach events in the system.
+ *
+ * @param {object} [options] a configuration object
+ * @param {string} [options.domain] a domain by which to filter the results
+ * (default: all domains)
+ * @param {string} [options.baseUrl] a custom base URL for the
+ * haveibeenpwned.com API endpoints (default:
+ * `https://haveibeenpwned.com/api/v3`)
+ * @param {string} [options.userAgent] a custom string to send as the User-Agent
+ * field in the request headers (default: `hibp <version>`)
+ * @returns {Promise<Breach[]>} a Promise which resolves to an array of breach
+ * objects (an empty array if no breaches were found), or rejects with an Error
+ * @example
+ * try {
+ *   const data = await breaches();
+ *   if (data) {
+ *     // ...
+ *   } else {
+ *     // ...
+ *   }
+ * } catch (err) {
+ *   // ...
+ * }
+ * @example
+ * try {
+ *   const data = await breaches({ domain: "adobe.com" });
+ *   if (data) {
+ *     // ...
+ *   } else {
+ *     // ...
+ *   }
+ * } catch (err) {
+ *   // ...
+ * }
+ */
+export declare 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[]>;
+/**
+ * Fetches all data classes in the system.
+ *
+ * @param {object} [options] a configuration object
+ * @param {string} [options.baseUrl] a custom base URL for the
+ * haveibeenpwned.com API endpoints (default:
+ * `https://haveibeenpwned.com/api/v3`)
+ * @param {string} [options.userAgent] a custom string to send as the User-Agent
+ * field in the request headers (default: `hibp <version>`)
+ * @returns {(Promise<string[]> | Promise<null>)} a Promise which resolves to an
+ * array of strings (or null if no data classes were found), or rejects with an
+ * Error
+ * @example
+ * try {
+ *   const data = await dataClasses();
+ *   if (data) {
+ *     // ...
+ *   } else {
+ *     // ...
+ *   }
+ * } catch (err) {
+ *   // ...
+ * }
+ */
+export declare 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>;
+/**
+ * An object representing a paste.
+ *
+ * @typedef {object} Paste
+ * @property {string} Id
+ * @property {string} Source
+ * @property {string} Title
+ * @property {string} Date
+ * @property {number} EmailCount
+ */
+/**
+ * Fetches paste data for a specific account (email address).
+ *
+ * 🔑 `haveibeenpwned.com` requires an API key from
+ * https://haveibeenpwned.com/API/Key for the `pasteaccount` endpoint. The
+ * `apiKey` option here is not explicitly required, but direct requests made
+ * without it will fail (unless you specify a `baseUrl` to a proxy that inserts
+ * a valid API key on your behalf).
+ *
+ * @param {string} email the email address to query
+ * @param {object} [options] a configuration object
+ * @param {string} [options.apiKey] an API key from
+ * https://haveibeenpwned.com/API/Key (default: undefined)
+ * @param {string} [options.baseUrl] a custom base URL for the
+ * haveibeenpwned.com API endpoints (default:
+ * `https://haveibeenpwned.com/api/v3`)
+ * @param {string} [options.userAgent] a custom string to send as the User-Agent
+ * field in the request headers (default: `hibp <version>`)
+ * @returns {(Promise<Paste[]> | Promise<null>)} a Promise which resolves to an
+ * array of paste objects (or null if no pastes were found), or rejects with an
+ * Error
+ * @example
+ * try {
+ *   const data = await pasteAccount("foo@bar.com", { apiKey: "my-api-key" });
+ *   if (data) {
+ *     // ...
+ *   } else {
+ *     // ...
+ *   }
+ * } catch (err) {
+ *   // ...
+ * }
+ * @example
+ * try {
+ *   const data = await pasteAccount("foo@bar.com", {
+ *     baseUrl: "https://my-hibp-proxy:8080",
+ *   });
+ *   if (data) {
+ *     // ...
+ *   } else {
+ *     // ...
+ *   }
+ * } catch (err) {
+ *   // ...
+ * }
+ */
+export declare 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>;
+/**
+ * Fetches the number of times the the given password has been exposed in a
+ * breach (0 indicating no exposure). The password is given in plain text, but
+ * only the first 5 characters of its SHA-1 hash will be submitted to the API.
+ *
+ * @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>`)
+ * @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
+ * try {
+ *   const numPwns = await pwnedPassword("f00b4r");
+ *   // truthy check or numeric condition
+ *   if (numPwns) {
+ *     // ...
+ *   } else {
+ *     // ...
+ *   }
+ * } catch (err) {
+ *   // ...
+ * }
+ * @see https://haveibeenpwned.com/api/v3#PwnedPasswords
+ */
+export declare 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;
+}): Promise<number>;
+export type PwnedPasswordSuffixes = Record<string, number>;
+/**
+ * An object mapping an exposed password hash suffix (corresponding to a given
+ * hash prefix) to how many times it occurred in the Pwned Passwords repository.
+ *
+ * @typedef {Object.<string, number>} PwnedPasswordSuffixes
+ */
+/**
+ * Fetches the SHA-1 or NTLM hash suffixes for the given 5-character hash
+ * prefix.
+ *
+ * When a password hash with the same first 5 characters is found in the Pwned
+ * Passwords repository, the API will respond with an HTTP 200 and include the
+ * suffix of every hash beginning with the specified prefix, followed by a count
+ * of how many times it appears in the data set. This function parses the
+ * response and returns a more structured format.
+ *
+ * @param {string} prefix the first 5 characters of a password hash (case
+ * insensitive)
+ * @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 {'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
+ * password data set, or rejects with an Error
+ *
+ * @example
+ * try {
+ *   const results = await pwnedPasswordRange("5BAA6");
+ *   // results will have the following shape:
+ *   // {
+ *   //   "003D68EB55068C33ACE09247EE4C639306B": 3,
+ *   //   "012C192B2F16F82EA0EB9EF18D9D539B0DD": 1,
+ *   //   ...
+ *   // }
+ * } catch (err) {
+ *   // ...
+ * }
+ * @example
+ * try {
+ *   const suffix = "1E4C9B93F3F0682250B6CF8331B7EE68FD8";
+ *   const results = await pwnedPasswordRange("5BAA6");
+ *   const numPwns = results[suffix] || 0;
+ * } catch (err) {
+ *   // ...
+ * }
+ * @see https://haveibeenpwned.com/api/v3#SearchingPwnedPasswordsByRange
+ */
+export declare function pwnedPasswordRange(prefix: string, options?: {
+	/**
+	 * 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>;
+export interface SearchResults {
+	breaches: Breach[] | null;
+	pastes: Paste[] | null;
+}
+/**
+ * An object representing search results.
+ *
+ * @typedef {object} SearchResults
+ * @property {(Breach[] | null)} breaches
+ * @property {(Paste[] | null)} pastes
+ */
+/**
+ * Fetches all breaches and all pastes associated with the provided account
+ * (email address or username). Note that the remote API does not support
+ * querying pastes by username (only email addresses), so in the event the
+ * provided account is not a valid email address, only breach data is queried
+ * and the "pastes" field of the resulting object will always be null. This is
+ * exactly how searching via the current web interface behaves, which this
+ * convenience method is designed to mimic.
+ *
+ * 🔑 `haveibeenpwned.com` requires an API key from
+ * https://haveibeenpwned.com/API/Key for the `breachedaccount` and
+ * `pasteaccount` endpoints. The `apiKey` option here is not explicitly
+ * required, but direct requests made without it will fail (unless you specify a
+ * `baseUrl` to a proxy that inserts a valid API key on your behalf).
+ *
+ * @param {string} account an email address or username
+ * @param {object} [options] a configuration object
+ * @param {string} [options.apiKey] an API key from
+ * https://haveibeenpwned.com/API/Key (default: undefined)
+ * @param {string} [options.domain] a domain by which to filter the breach
+ * results (default: all domains)
+ * @param {boolean} [options.truncate] truncate the breach results to only
+ * include the name of each breach (default: true)
+ * @param {string} [options.baseUrl] a custom base URL for the
+ * haveibeenpwned.com API endpoints (default:
+ * `https://haveibeenpwned.com/api/v3`)
+ * @param {string} [options.userAgent] a custom string to send as the
+ * User-Agent field in the request headers (default: `hibp <version>`)
+ * @returns {Promise<SearchResults>} a Promise which resolves to an object
+ * containing a "breaches" key (which can be null or an array of breach objects)
+ * and a "pastes" key (which can be null or an array of paste objects), or
+ * rejects with an Error
+ * @example
+ * try {
+ *   const data = await search("foo", { apiKey: "my-api-key" });
+ *   if (data.breaches || data.pastes) {
+ *     // ...
+ *   } else {
+ *     // ...
+ *   }
+ * } catch (err) {
+ *   // ...
+ * }
+ * @example
+ * try {
+ *   const data = await search("nobody@nowhere.com", {
+ *     baseUrl: "https://my-hibp-proxy:8080",
+ *     truncate: false,
+ *   });
+ *   if (data.breaches || data.pastes) {
+ *     // ...
+ *   } else {
+ *     // ...
+ *   }
+ * } catch (err) {
+ *   // ...
+ * }
+ * @see https://haveibeenpwned.com/
+ */
+export declare 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>;
+/**
+ * An object representing the status of your HIBP subscription.
+ *
+ * @typedef {object} SubscriptionStatus
+ * @property {string} SubscriptionName
+ * @property {string} Description
+ * @property {string} SubscribedUntil
+ * @property {number} Rpm
+ * @property {number} DomainSearchMaxBreachedAccounts
+ */
+/**
+ * Fetches the current status of your HIBP subscription (API key).
+ *
+ * 🔑 `haveibeenpwned.com` requires an API key from
+ * https://haveibeenpwned.com/API/Key for the `subscription/status` endpoint.
+ * The `apiKey` option here is not explicitly required, but direct requests made
+ * without it will fail (unless you specify a `baseUrl` to a proxy that inserts
+ * a valid API key on your behalf).
+ *
+ * @param {object} [options] a configuration object
+ * @param {string} [options.apiKey] an API key from
+ * https://haveibeenpwned.com/API/Key (default: undefined)
+ * @param {string} [options.baseUrl] a custom base URL for the
+ * haveibeenpwned.com API endpoints (default:
+ * `https://haveibeenpwned.com/api/v3`)
+ * @param {string} [options.userAgent] a custom string to send as the User-Agent
+ * field in the request headers (default: `hibp <version>`)
+ * @returns {Promise<SubscriptionStatus>} a Promise which resolves to a
+ * subscription status object, or rejects with an Error
+ * @example
+ * try {
+ *   const data = await subscriptionStatus({ apiKey: "my-api-key" });
+ *   // ...
+ * } catch (err) {
+ *   // ...
+ * }
+ * @example
+ * try {
+ *   const data = await subscriptionStatus({
+ *     baseUrl: "https://my-hibp-proxy:8080",
+ *   });
+ *   // ...
+ * } catch (err) {
+ *   // ...
+ * }
+ */
+export declare 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;
+}): Promise<SubscriptionStatus>;
+export interface HIBP {
+	breach: typeof breach;
+	breachedAccount: typeof breachedAccount;
+	breaches: typeof breaches;
+	dataClasses: typeof dataClasses;
+	pasteAccount: typeof pasteAccount;
+	pwnedPassword: typeof pwnedPassword;
+	pwnedPasswordRange: typeof pwnedPasswordRange;
+	search: typeof search;
+	subscriptionStatus: typeof subscriptionStatus;
+	RateLimitError: typeof RateLimitError;
+}
+
+export as namespace hibp;
+
+export {};

package/dist/cjs/{package.json.js → package.json.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
 const name = "hibp";
-const version = "0.0.0-dev.9896b89a";
+const version = "0.0.0-dev.d74e2ad2";
 exports.name = name;
 exports.version = version;
-//# sourceMappingURL=package.json.js.map
+//# sourceMappingURL=package.json.cjs.map

package/dist/cjs/package.json.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.json.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;"}