hibp 15.2.0 → 16.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/API.md +433 -126
  2. package/CHANGELOG.md +50 -0
  3. package/MIGRATION.md +7 -5
  4. package/README.md +53 -27
  5. package/dist/browser/hibp.module.js +2 -2
  6. package/dist/esm/api/base-fetch.d.ts +3 -1
  7. package/dist/esm/api/base-fetch.js +20 -7
  8. package/dist/esm/api/base-fetch.js.map +1 -1
  9. package/dist/esm/api/haveibeenpwned/fetch-from-api.d.ts +1 -1
  10. package/dist/esm/api/haveibeenpwned/fetch-from-api.js +71 -24
  11. package/dist/esm/api/haveibeenpwned/fetch-from-api.js.map +1 -1
  12. package/dist/esm/api/haveibeenpwned/package-info.d.ts +1 -1
  13. package/dist/esm/api/haveibeenpwned/package-info.js +1 -1
  14. package/dist/esm/api/haveibeenpwned/post-to-api.d.ts +1 -0
  15. package/dist/esm/api/haveibeenpwned/post-to-api.js +31 -0
  16. package/dist/esm/api/haveibeenpwned/post-to-api.js.map +1 -0
  17. package/dist/esm/api/haveibeenpwned/responses.js +8 -7
  18. package/dist/esm/api/haveibeenpwned/responses.js.map +1 -1
  19. package/dist/esm/api/haveibeenpwned/types.d.ts +22 -2
  20. package/dist/esm/api/pwnedpasswords/fetch-from-api.js +4 -4
  21. package/dist/esm/api/pwnedpasswords/fetch-from-api.js.map +1 -1
  22. package/dist/esm/api/pwnedpasswords/responses.js +1 -1
  23. package/dist/esm/breach.d.ts +8 -1
  24. package/dist/esm/breach.js +8 -1
  25. package/dist/esm/breach.js.map +1 -1
  26. package/dist/esm/breached-account-range.d.ts +73 -0
  27. package/dist/esm/breached-account-range.js +60 -0
  28. package/dist/esm/breached-account-range.js.map +1 -0
  29. package/dist/esm/breached-account.d.ts +56 -45
  30. package/dist/esm/breached-account.js +4 -76
  31. package/dist/esm/breached-account.js.map +1 -1
  32. package/dist/esm/breached-domain.d.ts +2 -3
  33. package/dist/esm/breached-domain.js +2 -3
  34. package/dist/esm/breached-domain.js.map +1 -1
  35. package/dist/esm/breaches.d.ts +9 -2
  36. package/dist/esm/breaches.js +10 -5
  37. package/dist/esm/breaches.js.map +1 -1
  38. package/dist/esm/data-class-descriptions.d.ts +55 -0
  39. package/dist/esm/data-class-descriptions.js +39 -0
  40. package/dist/esm/data-class-descriptions.js.map +1 -0
  41. package/dist/esm/data-classes.js +2 -2
  42. package/dist/esm/data-classes.js.map +1 -1
  43. package/dist/esm/generate-dns-token.d.ts +67 -0
  44. package/dist/esm/generate-dns-token.js +48 -0
  45. package/dist/esm/generate-dns-token.js.map +1 -0
  46. package/dist/esm/hibp.d.ts +28 -18
  47. package/dist/esm/hibp.js +23 -18
  48. package/dist/esm/hibp.js.map +1 -1
  49. package/dist/esm/latest-breach.d.ts +1 -1
  50. package/dist/esm/latest-breach.js +2 -2
  51. package/dist/esm/latest-breach.js.map +1 -1
  52. package/dist/esm/paste-account.d.ts +8 -8
  53. package/dist/esm/paste-account.js +8 -8
  54. package/dist/esm/paste-account.js.map +1 -1
  55. package/dist/esm/pwned-password-range.d.ts +1 -1
  56. package/dist/esm/pwned-password-range.js +4 -4
  57. package/dist/esm/pwned-password-range.js.map +1 -1
  58. package/dist/esm/pwned-password.js +6 -6
  59. package/dist/esm/pwned-password.js.map +1 -1
  60. package/dist/esm/search.d.ts +57 -40
  61. package/dist/esm/search.js +3 -72
  62. package/dist/esm/search.js.map +1 -1
  63. package/dist/esm/send-email.d.ts +69 -0
  64. package/dist/esm/send-email.js +49 -0
  65. package/dist/esm/send-email.js.map +1 -0
  66. package/dist/esm/stealer-logs-by-email-domain.d.ts +8 -9
  67. package/dist/esm/stealer-logs-by-email-domain.js +8 -9
  68. package/dist/esm/stealer-logs-by-email-domain.js.map +1 -1
  69. package/dist/esm/stealer-logs-by-email.d.ts +4 -5
  70. package/dist/esm/stealer-logs-by-email.js +5 -6
  71. package/dist/esm/stealer-logs-by-email.js.map +1 -1
  72. package/dist/esm/stealer-logs-by-website-domain.d.ts +4 -5
  73. package/dist/esm/stealer-logs-by-website-domain.js +5 -6
  74. package/dist/esm/stealer-logs-by-website-domain.js.map +1 -1
  75. package/dist/esm/subscribed-domains.d.ts +2 -3
  76. package/dist/esm/subscribed-domains.js +3 -4
  77. package/dist/esm/subscribed-domains.js.map +1 -1
  78. package/dist/esm/subscription-status.d.ts +11 -6
  79. package/dist/esm/subscription-status.js +12 -7
  80. package/dist/esm/subscription-status.js.map +1 -1
  81. package/dist/esm/verify-dns-token.d.ts +60 -0
  82. package/dist/esm/verify-dns-token.js +41 -0
  83. package/dist/esm/verify-dns-token.js.map +1 -0
  84. package/package.json +74 -75
package/API.md CHANGED
@@ -4,22 +4,34 @@
4
4
  <dt><a href="#breach">breach(breachName, [options])</a> ⇒ <code><a href="#breach--object">Promise.&lt;Breach&gt;</a></code> | <code>Promise.&lt;null&gt;</code></dt>
5
5
  <dd><p>Fetches data for a specific breach event.</p>
6
6
  </dd>
7
- <dt><a href="#breachedAccount">breachedAccount(account, [options])</a> ⇒ <code><a href="#breach--object">Promise.&lt;Array.&lt;Breach&gt;&gt;</a></code> | <code>Promise.&lt;null&gt;</code></dt>
8
- <dd><p>Fetches breach data for a specific account.</p>
9
- <p>🔑 <code>haveibeenpwned.com</code> requires an API key from
10
- <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a> for the <code>breachedaccount</code> endpoint. The
11
- <code>apiKey</code> option here is not explicitly required, but direct requests made
7
+ <dt><a href="#breachedAccountRange">breachedAccountRange(prefix, [options])</a> ⇒ <code><a href="#breachedaccountrangeresult--object">Promise.&lt;Array.&lt;BreachedAccountRangeResult&gt;&gt;</a></code> | <code>Promise.&lt;null&gt;</code></dt>
8
+ <dd><p>Fetches breached email hash suffixes for a six-character SHA-1 email hash
9
+ prefix.</p>
10
+ <p>Requires a Pro or High RPM API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>.
11
+ The <code>apiKey</code> option here is not explicitly required, but direct requests made
12
12
  without it will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts
13
13
  a valid API key on your behalf).</p>
14
+ <p>Compare suffixes locally against the intended email hash. Per the
15
+ haveibeenpwned.com terms of use, discard unrelated results immediately
16
+ without storing or further processing them.</p>
14
17
  </dd>
15
- <dt><a href="#breachedDomain">breachedDomain(domain, [options])</a> ⇒ <code><a href="#breach--objectedDomainsByEmailAlias">Promise.&lt;BreachedDomainsByEmailAlias&gt;</a></code> | <code>Promise.&lt;null&gt;</code></dt>
18
+ <dt><a href="#breachedAccount">breachedAccount(account, [options])</a> ⇒ <code><a href="#breach--object">Promise.&lt;Array.&lt;Breach&gt;&gt;</a></code> | <code>Promise.&lt;null&gt;</code></dt>
19
+ <dd><p>Fetches breach data for a specific account.</p>
20
+ <p>Results contain only <code>Name</code> by default; pass <code>truncate: false</code> for full
21
+ breaches.</p>
22
+ <p>Requires a Core, Pro, or High RPM API key from
23
+ <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code> option here is not
24
+ explicitly required, but direct requests made without it will fail (unless
25
+ you specify a <code>baseUrl</code> to a proxy that inserts a valid API key on your
26
+ behalf).</p>
27
+ </dd>
28
+ <dt><a href="#breachedDomain">breachedDomain(domain, [options])</a> ⇒ <code><a href="#BreachedDomainsByEmailAlias">Promise.&lt;BreachedDomainsByEmailAlias&gt;</a></code> | <code>Promise.&lt;null&gt;</code></dt>
16
29
  <dd><p>Fetches all breached email addresses for a domain.</p>
17
30
  <p>The result maps email aliases (the local-part before the &#39;@&#39;) to an array of
18
31
  breach names. For example, querying <code>example.com</code> could return an object like
19
32
  <code>{ &quot;john&quot;: [&quot;Adobe&quot;], &quot;jane&quot;: [&quot;Adobe&quot;, &quot;Gawker&quot;] }</code>, corresponding to
20
33
  <code>john@example.com</code> and <code>jane@example.com</code>.</p>
21
- <p>🔑 <code>haveibeenpwned.com</code> requires an API key from
22
- <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a> for the <code>breacheddomain</code> endpoint. The
34
+ <p>Requires a Core or Pro API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The
23
35
  <code>apiKey</code> option here is not explicitly required, but direct requests made
24
36
  without it will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts
25
37
  a valid API key on your behalf).</p>
@@ -27,19 +39,31 @@ a valid API key on your behalf).</p>
27
39
  <dt><a href="#breaches">breaches([options])</a> ⇒ <code><a href="#breach--object">Promise.&lt;Array.&lt;Breach&gt;&gt;</a></code></dt>
28
40
  <dd><p>Fetches all breach events in the system.</p>
29
41
  </dd>
42
+ <dt><a href="#dataClassDescriptions">dataClassDescriptions([options])</a> ⇒ <code><a href="#dataclassdescription--object">Promise.&lt;Array.&lt;DataClassDescription&gt;&gt;</a></code> | <code>Promise.&lt;null&gt;</code></dt>
43
+ <dd><p>Fetches all data class names and descriptions.</p>
44
+ </dd>
30
45
  <dt><a href="#dataClasses">dataClasses([options])</a> ⇒ <code>Promise.&lt;Array.&lt;string&gt;&gt;</code> | <code>Promise.&lt;null&gt;</code></dt>
31
46
  <dd><p>Fetches all data classes in the system.</p>
32
47
  </dd>
48
+ <dt><a href="#generateDnsToken">generateDnsToken(domain, [options])</a> ⇒ <code><a href="#DnsToken">Promise.&lt;DnsToken&gt;</a></code></dt>
49
+ <dd><p>Generates a domain-specific DNS verification token.</p>
50
+ <p>Publish <code>txtRecordValue</code> as a TXT record on the domain, then call
51
+ <code>verifyDnsToken</code> after DNS propagation.</p>
52
+ <p>Requires a Pro API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code>
53
+ option here is not explicitly required, but direct requests made without it
54
+ will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts a valid API
55
+ key on your behalf).</p>
56
+ </dd>
33
57
  <dt><a href="#latestBreach">latestBreach([options])</a> ⇒ <code><a href="#breach--object">Promise.&lt;Breach&gt;</a></code> | <code>Promise.&lt;null&gt;</code></dt>
34
58
  <dd><p>Fetches the most recently added breach.</p>
35
59
  </dd>
36
60
  <dt><a href="#pasteAccount">pasteAccount(email, [options])</a> ⇒ <code><a href="#paste--object">Promise.&lt;Array.&lt;Paste&gt;&gt;</a></code> | <code>Promise.&lt;null&gt;</code></dt>
37
61
  <dd><p>Fetches paste data for a specific account (email address).</p>
38
- <p>🔑 <code>haveibeenpwned.com</code> requires an API key from
39
- <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a> for the <code>pasteaccount</code> endpoint. The
40
- <code>apiKey</code> option here is not explicitly required, but direct requests made
41
- without it will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts
42
- a valid API key on your behalf).</p>
62
+ <p>Requires a Core, Pro, or High RPM API key from
63
+ <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code> option here is not
64
+ explicitly required, but direct requests made without it will fail (unless
65
+ you specify a <code>baseUrl</code> to a proxy that inserts a valid API key on your
66
+ behalf).</p>
43
67
  </dd>
44
68
  <dt><a href="#pwnedPasswordRange">pwnedPasswordRange(prefix, [options])</a> ⇒ <code><a href="#PwnedPasswordSuffixes">Promise.&lt;PwnedPasswordSuffixes&gt;</a></code></dt>
45
69
  <dd><p>Fetches the SHA-1 or NTLM hash suffixes for the given 5-character hash
@@ -63,61 +87,78 @@ provided account is not a valid email address, only breach data is queried
63
87
  and the &quot;pastes&quot; field of the resulting object will always be null. This is
64
88
  exactly how searching via the current web interface behaves, which this
65
89
  convenience method is designed to mimic.</p>
66
- <p>🔑 <code>haveibeenpwned.com</code> requires an API key from
67
- <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a> for the <code>breachedaccount</code> and
68
- <code>pasteaccount</code> endpoints. The <code>apiKey</code> option here is not explicitly
69
- required, but direct requests made without it will fail (unless you specify a
70
- <code>baseUrl</code> to a proxy that inserts a valid API key on your behalf).</p>
90
+ <p>Breaches contain only <code>Name</code> by default; pass <code>truncate: false</code> for full
91
+ breaches.</p>
92
+ <p>Requires a Core, Pro, or High RPM API key from
93
+ <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code> option here is not
94
+ explicitly required, but direct requests made without it will fail (unless
95
+ you specify a <code>baseUrl</code> to a proxy that inserts a valid API key on your
96
+ behalf).</p>
97
+ </dd>
98
+ <dt><a href="#sendEmail">sendEmail(domain, emailAlias, [options])</a> ⇒ <code>Promise.&lt;void&gt;</code></dt>
99
+ <dd><p>Requests a domain verification approval email.</p>
100
+ <p>Follow the link sent to the chosen alias at the domain to complete
101
+ verification.</p>
102
+ <p>Requires a Pro API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code>
103
+ option here is not explicitly required, but direct requests made without it
104
+ will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts a valid API
105
+ key on your behalf).</p>
71
106
  </dd>
72
107
  <dt><a href="#stealerLogsByEmailDomain">stealerLogsByEmailDomain(emailDomain, [options])</a> ⇒ <code><a href="#StealerLogDomainsByEmailAlias">Promise.&lt;StealerLogDomainsByEmailAlias&gt;</a></code> | <code>Promise.&lt;null&gt;</code></dt>
73
108
  <dd><p>Fetches all stealer log email aliases for an email domain.</p>
74
109
  <p>The result maps email aliases (the local-part before the &#39;@&#39;) to an array of
75
- email domains found in stealer logs. For example, querying <code>example.com</code>
110
+ website domains found in stealer logs. For example, querying <code>example.com</code>
76
111
  could return an object like <code>{ &quot;andy&quot;: [&quot;netflix.com&quot;], &quot;jane&quot;: [&quot;netflix.com&quot;, &quot;spotify.com&quot;] }</code>, corresponding to <code>andy@example.com</code> and <code>jane@example.com</code>.</p>
77
- <p>🔑 <code>haveibeenpwned.com</code> requires an API key from
78
- <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a> for the <code>stealerlogsbyemaildomain</code> endpoint.
79
- The <code>apiKey</code> option here is not explicitly required, but direct requests made
80
- without it will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts
81
- a valid API key on your behalf).</p>
112
+ <p>Requires a Pro API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code>
113
+ option here is not explicitly required, but direct requests made without it
114
+ will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts a valid API
115
+ key on your behalf).</p>
82
116
  </dd>
83
117
  <dt><a href="#stealerLogsByEmail">stealerLogsByEmail(emailAddress, [options])</a> ⇒ <code>Promise.&lt;Array.&lt;string&gt;&gt;</code> | <code>Promise.&lt;null&gt;</code></dt>
84
118
  <dd><p>Fetches all stealer log domains for an email address.</p>
85
119
  <p>Returns an array of domains for which stealer logs contain entries for the
86
120
  supplied email address.</p>
87
- <p>🔑 <code>haveibeenpwned.com</code> requires an API key from
88
- <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a> for the <code>stealerlogsbyemail</code> endpoint. The
89
- <code>apiKey</code> option here is not explicitly required, but direct requests made
90
- without it will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts
91
- a valid API key on your behalf).</p>
121
+ <p>Requires a Pro API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code>
122
+ option here is not explicitly required, but direct requests made without it
123
+ will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts a valid API
124
+ key on your behalf).</p>
92
125
  </dd>
93
126
  <dt><a href="#stealerLogsByWebsiteDomain">stealerLogsByWebsiteDomain(websiteDomain, [options])</a> ⇒ <code>Promise.&lt;Array.&lt;string&gt;&gt;</code> | <code>Promise.&lt;null&gt;</code></dt>
94
127
  <dd><p>Fetches all stealer log email addresses for a website domain.</p>
95
128
  <p>The result is an array of strings representing email addresses found in
96
129
  stealer logs for the specified website domain (e.g., &quot;example.com&quot;).</p>
97
- <p>🔑 <code>haveibeenpwned.com</code> requires an API key from
98
- <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a> for the <code>stealerlogsbywebsitedomain</code>
99
- endpoint. The <code>apiKey</code> option here is not explicitly required, but direct
100
- requests made without it will fail (unless you specify a <code>baseUrl</code> to a proxy
101
- that inserts a valid API key on your behalf).</p>
130
+ <p>Requires a Pro API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code>
131
+ option here is not explicitly required, but direct requests made without it
132
+ will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts a valid API
133
+ key on your behalf).</p>
102
134
  </dd>
103
135
  <dt><a href="#subscribedDomains">subscribedDomains([options])</a> ⇒ <code><a href="#subscribeddomain--object">Promise.&lt;Array.&lt;SubscribedDomain&gt;&gt;</a></code></dt>
104
136
  <dd><p>Fetches all subscribed domains for your HIBP account.</p>
105
137
  <p>Returns domains that have been successfully added to the Domain Search dashboard
106
138
  after verifying control. Each domain includes metadata about breach counts and
107
139
  the next renewal date, where available.</p>
108
- <p>🔑 <code>haveibeenpwned.com</code> requires an API key from
109
- <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a> for the <code>subscribeddomains</code> endpoint. The
140
+ <p>Requires a Core or Pro API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The
110
141
  <code>apiKey</code> option here is not explicitly required, but direct requests made
111
142
  without it will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts
112
143
  a valid API key on your behalf).</p>
113
144
  </dd>
114
145
  <dt><a href="#subscriptionStatus">subscriptionStatus([options])</a> ⇒ <code><a href="#subscriptionstatus--object">Promise.&lt;SubscriptionStatus&gt;</a></code></dt>
115
146
  <dd><p>Fetches the current status of your HIBP subscription (API key).</p>
116
- <p>🔑 <code>haveibeenpwned.com</code> requires an API key from
117
- <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a> for the <code>subscription/status</code> endpoint.
118
- The <code>apiKey</code> option here is not explicitly required, but direct requests made
119
- without it will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts
120
- a valid API key on your behalf).</p>
147
+ <p>Requires a Core, Pro, or High RPM API key from
148
+ <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code> option here is not
149
+ explicitly required, but direct requests made without it will fail (unless
150
+ you specify a <code>baseUrl</code> to a proxy that inserts a valid API key on your
151
+ behalf).</p>
152
+ </dd>
153
+ <dt><a href="#verifyDnsToken">verifyDnsToken(domain, [options])</a> ⇒ <code>Promise.&lt;void&gt;</code></dt>
154
+ <dd><p>Verifies a domain&#39;s published HIBP TXT record.</p>
155
+ <p>Generate the value with <code>generateDnsToken</code>, publish it at your DNS provider,
156
+ and allow time for DNS propagation first. The record can be removed after
157
+ verification succeeds.</p>
158
+ <p>Requires a Pro API key from <a href="https://haveibeenpwned.com/API/Key">https://haveibeenpwned.com/API/Key</a>. The <code>apiKey</code>
159
+ option here is not explicitly required, but direct requests made without it
160
+ will fail (unless you specify a <code>baseUrl</code> to a proxy that inserts a valid API
161
+ key on your behalf).</p>
121
162
  </dd>
122
163
  </dl>
123
164
 
@@ -126,11 +167,23 @@ a valid API key on your behalf).</p>
126
167
  <dl>
127
168
  <dt><a href="#breach--object">Breach</a> : <code>object</code></dt>
128
169
  <dd><p>An object representing a breach.</p>
170
+ <p><code>Attribution</code> and <code>DisclosureUrl</code> may be null. See the
171
+ <a href="https://haveibeenpwned.com/API/v3#BreachModel">breach model</a> and the
172
+ <a href="https://haveibeenpwned.com/api/v3/breaches">breach catalogue</a>.</p>
173
+ </dd>
174
+ <dt><a href="#BreachedAccountRangeResult">BreachedAccountRangeResult</a> : <code>Object</code></dt>
175
+ <dd><p>A breached email hash suffix and the breach names associated with it.</p>
129
176
  </dd>
130
- <dt><a href="#breach--objectedDomainsByEmailAlias">BreachedDomainsByEmailAlias</a> : <code>Object.&lt;string, Array.&lt;string&gt;&gt;</code></dt>
177
+ <dt><a href="#BreachedDomainsByEmailAlias">BreachedDomainsByEmailAlias</a> : <code>Object.&lt;string, Array.&lt;string&gt;&gt;</code></dt>
131
178
  <dd><p>An object mapping an email alias (local-part before the &#39;@&#39;) to the list of
132
179
  breach names that alias has appeared in for the specified domain.</p>
133
180
  </dd>
181
+ <dt><a href="#dataclassdescription--object">DataClassDescription</a> : <code>object</code></dt>
182
+ <dd><p>A data class name and its description.</p>
183
+ </dd>
184
+ <dt><a href="#DnsToken">DnsToken</a> : <code>object</code></dt>
185
+ <dd><p>The TXT record value to publish at your DNS provider.</p>
186
+ </dd>
134
187
  <dt><a href="#Paste">Paste</a> : <code>object</code></dt>
135
188
  <dd><p>An object representing a paste.</p>
136
189
  </dd>
@@ -141,10 +194,13 @@ hash prefix) to how many times it occurred in the Pwned Passwords repository.</p
141
194
  <dt><a href="#SearchResults">SearchResults</a> : <code>object</code></dt>
142
195
  <dd><p>An object representing search results.</p>
143
196
  </dd>
197
+ <dt><a href="#EmailAlias">EmailAlias</a> : <code>&quot;admin&quot;</code> | <code>&quot;hostmaster&quot;</code> | <code>&quot;info&quot;</code> | <code>&quot;security&quot;</code> | <code>&quot;webmaster&quot;</code></dt>
198
+ <dd><p>An administrative alias supported for domain verification emails.</p>
199
+ </dd>
144
200
  <dt><a href="#StealerLogDomainsByEmailAlias">StealerLogDomainsByEmailAlias</a> : <code>Object.&lt;string, Array.&lt;string&gt;&gt;</code></dt>
145
201
  <dd><p>An object mapping an email alias (local-part before the &#39;@&#39;) to the list of
146
- email domains that alias has appeared in within stealer logs for the specified
147
- email domain.</p>
202
+ website domains that alias has appeared against in stealer logs for the
203
+ specified email domain.</p>
148
204
  </dd>
149
205
  <dt><a href="#SubscribedDomain">SubscribedDomain</a> : <code>object</code></dt>
150
206
  <dd><p>An object representing a subscribed domain.</p>
@@ -186,21 +242,67 @@ try {
186
242
  // ...
187
243
  }
188
244
  ```
245
+ <a name="breachedAccountRange"></a>
246
+
247
+ ## breachedAccountRange(prefix, [options]) ⇒ <code><a href="#breachedaccountrangeresult--object">Promise.&lt;Array.&lt;BreachedAccountRangeResult&gt;&gt;</a></code> \| <code>Promise.&lt;null&gt;</code>
248
+ Fetches breached email hash suffixes for a six-character SHA-1 email hash
249
+ prefix.
250
+
251
+ Requires a Pro or High RPM API key from https://haveibeenpwned.com/API/Key.
252
+ The `apiKey` option here is not explicitly required, but direct requests made
253
+ without it will fail (unless you specify a `baseUrl` to a proxy that inserts
254
+ a valid API key on your behalf).
255
+
256
+ Compare suffixes locally against the intended email hash. Per the
257
+ haveibeenpwned.com terms of use, discard unrelated results immediately
258
+ without storing or further processing them.
259
+
260
+ **Kind**: global function
261
+ **Returns**: <code><a href="#breachedaccountrangeresult--object">Promise.&lt;Array.&lt;BreachedAccountRangeResult&gt;&gt;</a></code> \| <code>Promise.&lt;null&gt;</code> - a Promise
262
+ which resolves to an array of range results (or null if none were found), or
263
+ rejects with an Error
264
+ **See**: https://haveibeenpwned.com/API/v3#BreachesForHashRange
265
+
266
+ | Param | Type | Description |
267
+ | --- | --- | --- |
268
+ | prefix | <code>string</code> | the first six characters of a SHA-1 email hash (case-insensitive) |
269
+ | [options] | <code>object</code> | a configuration object |
270
+ | [options.apiKey] | <code>string</code> | an API key from https://haveibeenpwned.com/API/Key (default: undefined) |
271
+ | [options.baseUrl] | <code>string</code> | a custom base URL for the haveibeenpwned.com API endpoints (default: `https://haveibeenpwned.com/api/v3`) |
272
+ | [options.timeoutMs] | <code>number</code> | timeout for the request in milliseconds (default: none) |
273
+ | [options.signal] | <code>AbortSignal</code> | an AbortSignal to cancel the request (default: none) |
274
+ | [options.userAgent] | <code>string</code> | a custom string to send as the User-Agent field in the request headers (default: `hibp <version>`) |
275
+
276
+ **Example**
277
+ ```js
278
+ try {
279
+ const data = await breachedAccountRange("6B5917", { apiKey: "my-api-key" });
280
+ const match = data?.find(
281
+ ({ hashSuffix }) => hashSuffix === "C6C0AADE0C085843D66E4944E108C4A4CD",
282
+ );
283
+ // match?.websites: ["Adobe", "Gawker", "Stratfor"] in the documented example
284
+ } catch (err) {
285
+ // ...
286
+ }
287
+ ```
189
288
  <a name="breachedAccount"></a>
190
289
 
191
290
  ## breachedAccount(account, [options]) ⇒ <code><a href="#breach--object">Promise.&lt;Array.&lt;Breach&gt;&gt;</a></code> \| <code>Promise.&lt;null&gt;</code>
192
291
  Fetches breach data for a specific account.
193
292
 
194
- 🔑 `haveibeenpwned.com` requires an API key from
195
- https://haveibeenpwned.com/API/Key for the `breachedaccount` endpoint. The
196
- `apiKey` option here is not explicitly required, but direct requests made
197
- without it will fail (unless you specify a `baseUrl` to a proxy that inserts
198
- a valid API key on your behalf).
293
+ Results contain only `Name` by default; pass `truncate: false` for full
294
+ breaches.
295
+
296
+ Requires a Core, Pro, or High RPM API key from
297
+ https://haveibeenpwned.com/API/Key. The `apiKey` option here is not
298
+ explicitly required, but direct requests made without it will fail (unless
299
+ you specify a `baseUrl` to a proxy that inserts a valid API key on your
300
+ behalf).
199
301
 
200
302
  **Kind**: global function
201
- **Returns**: <code><a href="#breach--object">Promise.&lt;Array.&lt;Breach&gt;&gt;</a></code> \| <code>Promise.&lt;null&gt;</code> - a Promise which resolves to an
202
- array of breach objects (or null if no breaches were found), or rejects with
203
- an Error
303
+ **Returns**: <code><a href="#breach--object">Promise.&lt;Array.&lt;Breach&gt;&gt;</a></code> \| <code>Promise.&lt;null&gt;</code> - a Promise which
304
+ resolves to name-only breaches by default, full breaches with
305
+ `truncate: false`, or null if no breaches were found; rejects with an Error
204
306
 
205
307
  | Param | Type | Description |
206
308
  | --- | --- | --- |
@@ -264,7 +366,7 @@ try {
264
366
  ```
265
367
  <a name="breachedDomain"></a>
266
368
 
267
- ## breachedDomain(domain, [options]) ⇒ [<code>Promise.&lt;BreachedDomainsByEmailAlias&gt;</code>](#breach--objectedDomainsByEmailAlias) \| <code>Promise.&lt;null&gt;</code>
369
+ ## breachedDomain(domain, [options]) ⇒ [<code>Promise.&lt;BreachedDomainsByEmailAlias&gt;</code>](#BreachedDomainsByEmailAlias) \| <code>Promise.&lt;null&gt;</code>
268
370
  Fetches all breached email addresses for a domain.
269
371
 
270
372
  The result maps email aliases (the local-part before the '@') to an array of
@@ -272,14 +374,13 @@ breach names. For example, querying `example.com` could return an object like
272
374
  `{ "john": ["Adobe"], "jane": ["Adobe", "Gawker"] }`, corresponding to
273
375
  `john@example.com` and `jane@example.com`.
274
376
 
275
- 🔑 `haveibeenpwned.com` requires an API key from
276
- https://haveibeenpwned.com/API/Key for the `breacheddomain` endpoint. The
377
+ Requires a Core or Pro API key from https://haveibeenpwned.com/API/Key. The
277
378
  `apiKey` option here is not explicitly required, but direct requests made
278
379
  without it will fail (unless you specify a `baseUrl` to a proxy that inserts
279
380
  a valid API key on your behalf).
280
381
 
281
382
  **Kind**: global function
282
- **Returns**: [<code>Promise.&lt;BreachedDomainsByEmailAlias&gt;</code>](#breach--objectedDomainsByEmailAlias) \| <code>Promise.&lt;null&gt;</code> - a Promise which
383
+ **Returns**: [<code>Promise.&lt;BreachedDomainsByEmailAlias&gt;</code>](#BreachedDomainsByEmailAlias) \| <code>Promise.&lt;null&gt;</code> - a Promise which
283
384
  resolves to an object mapping aliases to breach name arrays (or null if no
284
385
  results were found), or rejects with an Error
285
386
 
@@ -319,6 +420,7 @@ objects (an empty array if no breaches were found), or rejects with an Error
319
420
  | --- | --- | --- |
320
421
  | [options] | <code>object</code> | a configuration object |
321
422
  | [options.domain] | <code>string</code> | a domain by which to filter the results (default: all domains) |
423
+ | [options.isSpamList] | <code>boolean</code> | true for only spam-list breaches, false for only non-spam-list breaches (default: no spam-list filter) |
322
424
  | [options.baseUrl] | <code>string</code> | a custom base URL for the haveibeenpwned.com API endpoints (default: `https://haveibeenpwned.com/api/v3`) |
323
425
  | [options.timeoutMs] | <code>number</code> | timeout for the request in milliseconds (default: none) |
324
426
  | [options.signal] | <code>AbortSignal</code> | an AbortSignal to cancel the request (default: none) |
@@ -340,7 +442,38 @@ try {
340
442
  **Example**
341
443
  ```js
342
444
  try {
343
- const data = await breaches({ domain: "adobe.com" });
445
+ const data = await breaches({ domain: "adobe.com", isSpamList: false });
446
+ if (data) {
447
+ // ...
448
+ } else {
449
+ // ...
450
+ }
451
+ } catch (err) {
452
+ // ...
453
+ }
454
+ ```
455
+ <a name="dataClassDescriptions"></a>
456
+
457
+ ## dataClassDescriptions([options]) ⇒ <code><a href="#dataclassdescription--object">Promise.&lt;Array.&lt;DataClassDescription&gt;&gt;</a></code> \| <code>Promise.&lt;null&gt;</code>
458
+ Fetches all data class names and descriptions.
459
+
460
+ **Kind**: global function
461
+ **Returns**: <code><a href="#dataclassdescription--object">Promise.&lt;Array.&lt;DataClassDescription&gt;&gt;</a></code> \| <code>Promise.&lt;null&gt;</code> - a Promise which
462
+ resolves to an array of data class objects (or null if no data classes were
463
+ found), or rejects with an Error
464
+
465
+ | Param | Type | Description |
466
+ | --- | --- | --- |
467
+ | [options] | <code>object</code> | a configuration object |
468
+ | [options.baseUrl] | <code>string</code> | a custom base URL for the haveibeenpwned.com API endpoints (default: `https://haveibeenpwned.com/api/v3`) |
469
+ | [options.timeoutMs] | <code>number</code> | timeout for the request in milliseconds (default: none) |
470
+ | [options.signal] | <code>AbortSignal</code> | an AbortSignal to cancel the request (default: none) |
471
+ | [options.userAgent] | <code>string</code> | a custom string to send as the User-Agent field in the request headers (default: `hibp <version>`) |
472
+
473
+ **Example**
474
+ ```js
475
+ try {
476
+ const data = await dataClassDescriptions();
344
477
  if (data) {
345
478
  // ...
346
479
  } else {
@@ -381,6 +514,45 @@ try {
381
514
  // ...
382
515
  }
383
516
  ```
517
+ <a name="generateDnsToken"></a>
518
+
519
+ ## generateDnsToken(domain, [options]) ⇒ [<code>Promise.&lt;DnsToken&gt;</code>](#DnsToken)
520
+ Generates a domain-specific DNS verification token.
521
+
522
+ Publish `txtRecordValue` as a TXT record on the domain, then call
523
+ `verifyDnsToken` after DNS propagation.
524
+
525
+ Requires a Pro API key from https://haveibeenpwned.com/API/Key. The `apiKey`
526
+ option here is not explicitly required, but direct requests made without it
527
+ will fail (unless you specify a `baseUrl` to a proxy that inserts a valid API
528
+ key on your behalf).
529
+
530
+ **Kind**: global function
531
+ **Returns**: [<code>Promise.&lt;DnsToken&gt;</code>](#DnsToken) - a Promise which resolves to the TXT record
532
+ value, or rejects with an Error containing the upstream failure reason
533
+ **See**: https://haveibeenpwned.com/API/v3#VerifyDomainViaDns
534
+
535
+ | Param | Type | Description |
536
+ | --- | --- | --- |
537
+ | domain | <code>string</code> | the domain to verify (e.g., "example.com") |
538
+ | [options] | <code>object</code> | a configuration object |
539
+ | [options.apiKey] | <code>string</code> | an API key from https://haveibeenpwned.com/API/Key (default: undefined) |
540
+ | [options.baseUrl] | <code>string</code> | a custom base URL for the haveibeenpwned.com API endpoints (default: `https://haveibeenpwned.com/api/v3`) |
541
+ | [options.timeoutMs] | <code>number</code> | timeout for the request in milliseconds (default: none) |
542
+ | [options.signal] | <code>AbortSignal</code> | an AbortSignal to cancel the request (default: none) |
543
+ | [options.userAgent] | <code>string</code> | a custom string to send as the User-Agent field in the request headers (default: `hibp <version>`) |
544
+
545
+ **Example**
546
+ ```js
547
+ try {
548
+ const { txtRecordValue } = await generateDnsToken("example.com", {
549
+ apiKey: "my-api-key",
550
+ });
551
+ // Publish txtRecordValue as a TXT record on example.com.
552
+ } catch (err) {
553
+ // ...
554
+ }
555
+ ```
384
556
  <a name="latestBreach"></a>
385
557
 
386
558
  ## latestBreach([options]) ⇒ [<code>Promise.&lt;Breach&gt;</code>](#breach--object) \| <code>Promise.&lt;null&gt;</code>
@@ -417,11 +589,11 @@ try {
417
589
  ## pasteAccount(email, [options]) ⇒ <code><a href="#paste--object">Promise.&lt;Array.&lt;Paste&gt;&gt;</a></code> \| <code>Promise.&lt;null&gt;</code>
418
590
  Fetches paste data for a specific account (email address).
419
591
 
420
- 🔑 `haveibeenpwned.com` requires an API key from
421
- https://haveibeenpwned.com/API/Key for the `pasteaccount` endpoint. The
422
- `apiKey` option here is not explicitly required, but direct requests made
423
- without it will fail (unless you specify a `baseUrl` to a proxy that inserts
424
- a valid API key on your behalf).
592
+ Requires a Core, Pro, or High RPM API key from
593
+ https://haveibeenpwned.com/API/Key. The `apiKey` option here is not
594
+ explicitly required, but direct requests made without it will fail (unless
595
+ you specify a `baseUrl` to a proxy that inserts a valid API key on your
596
+ behalf).
425
597
 
426
598
  **Kind**: global function
427
599
  **Returns**: <code><a href="#paste--object">Promise.&lt;Array.&lt;Paste&gt;&gt;</a></code> \| <code>Promise.&lt;null&gt;</code> - a Promise which resolves to an
@@ -567,11 +739,14 @@ and the "pastes" field of the resulting object will always be null. This is
567
739
  exactly how searching via the current web interface behaves, which this
568
740
  convenience method is designed to mimic.
569
741
 
570
- 🔑 `haveibeenpwned.com` requires an API key from
571
- https://haveibeenpwned.com/API/Key for the `breachedaccount` and
572
- `pasteaccount` endpoints. The `apiKey` option here is not explicitly
573
- required, but direct requests made without it will fail (unless you specify a
574
- `baseUrl` to a proxy that inserts a valid API key on your behalf).
742
+ Breaches contain only `Name` by default; pass `truncate: false` for full
743
+ breaches.
744
+
745
+ Requires a Core, Pro, or High RPM API key from
746
+ https://haveibeenpwned.com/API/Key. The `apiKey` option here is not
747
+ explicitly required, but direct requests made without it will fail (unless
748
+ you specify a `baseUrl` to a proxy that inserts a valid API key on your
749
+ behalf).
575
750
 
576
751
  **Kind**: global function
577
752
  **Returns**: [<code>Promise.&lt;SearchResults&gt;</code>](#SearchResults) - a Promise which resolves to an object
@@ -621,21 +796,61 @@ try {
621
796
  // ...
622
797
  }
623
798
  ```
799
+ <a name="sendEmail"></a>
800
+
801
+ ## sendEmail(domain, emailAlias, [options]) ⇒ <code>Promise.&lt;void&gt;</code>
802
+ Requests a domain verification approval email.
803
+
804
+ Follow the link sent to the chosen alias at the domain to complete
805
+ verification.
806
+
807
+ Requires a Pro API key from https://haveibeenpwned.com/API/Key. The `apiKey`
808
+ option here is not explicitly required, but direct requests made without it
809
+ will fail (unless you specify a `baseUrl` to a proxy that inserts a valid API
810
+ key on your behalf).
811
+
812
+ **Kind**: global function
813
+ **Returns**: <code>Promise.&lt;void&gt;</code> - a Promise which resolves without parsing the
814
+ response body when the approval email request succeeds, or rejects with an
815
+ Error containing the upstream failure reason
816
+ **See**: https://haveibeenpwned.com/API/v3#VerifyDomainViaEmail
817
+
818
+ | Param | Type | Description |
819
+ | --- | --- | --- |
820
+ | domain | <code>string</code> | the domain to verify (e.g., "example.com") |
821
+ | emailAlias | [<code>EmailAlias</code>](#EmailAlias) | the administrative alias to receive the email |
822
+ | [options] | <code>object</code> | a configuration object |
823
+ | [options.apiKey] | <code>string</code> | an API key from https://haveibeenpwned.com/API/Key (default: undefined) |
824
+ | [options.baseUrl] | <code>string</code> | a custom base URL for the haveibeenpwned.com API endpoints (default: `https://haveibeenpwned.com/api/v3`) |
825
+ | [options.timeoutMs] | <code>number</code> | timeout for the request in milliseconds (default: none) |
826
+ | [options.signal] | <code>AbortSignal</code> | an AbortSignal to cancel the request (default: none) |
827
+ | [options.userAgent] | <code>string</code> | a custom string to send as the User-Agent field in the request headers (default: `hibp <version>`) |
828
+
829
+ **Example**
830
+ ```js
831
+ try {
832
+ await sendEmail("example.com", "security", {
833
+ apiKey: "my-api-key",
834
+ });
835
+ // Follow the link in the email sent to security@example.com.
836
+ } catch (err) {
837
+ // ...
838
+ }
839
+ ```
624
840
  <a name="stealerLogsByEmailDomain"></a>
625
841
 
626
842
  ## stealerLogsByEmailDomain(emailDomain, [options]) ⇒ [<code>Promise.&lt;StealerLogDomainsByEmailAlias&gt;</code>](#StealerLogDomainsByEmailAlias) \| <code>Promise.&lt;null&gt;</code>
627
843
  Fetches all stealer log email aliases for an email domain.
628
844
 
629
845
  The result maps email aliases (the local-part before the '@') to an array of
630
- email domains found in stealer logs. For example, querying `example.com`
846
+ website domains found in stealer logs. For example, querying `example.com`
631
847
  could return an object like `{ "andy": ["netflix.com"], "jane": ["netflix.com",
632
848
  "spotify.com"] }`, corresponding to `andy@example.com` and `jane@example.com`.
633
849
 
634
- 🔑 `haveibeenpwned.com` requires an API key from
635
- https://haveibeenpwned.com/API/Key for the `stealerlogsbyemaildomain` endpoint.
636
- The `apiKey` option here is not explicitly required, but direct requests made
637
- without it will fail (unless you specify a `baseUrl` to a proxy that inserts
638
- a valid API key on your behalf).
850
+ Requires a Pro API key from https://haveibeenpwned.com/API/Key. The `apiKey`
851
+ option here is not explicitly required, but direct requests made without it
852
+ will fail (unless you specify a `baseUrl` to a proxy that inserts a valid API
853
+ key on your behalf).
639
854
 
640
855
  **Kind**: global function
641
856
  **Returns**: [<code>Promise.&lt;StealerLogDomainsByEmailAlias&gt;</code>](#StealerLogDomainsByEmailAlias) \| <code>Promise.&lt;null&gt;</code> - a Promise
@@ -673,11 +888,10 @@ Fetches all stealer log domains for an email address.
673
888
  Returns an array of domains for which stealer logs contain entries for the
674
889
  supplied email address.
675
890
 
676
- 🔑 `haveibeenpwned.com` requires an API key from
677
- https://haveibeenpwned.com/API/Key for the `stealerlogsbyemail` endpoint. The
678
- `apiKey` option here is not explicitly required, but direct requests made
679
- without it will fail (unless you specify a `baseUrl` to a proxy that inserts
680
- a valid API key on your behalf).
891
+ Requires a Pro API key from https://haveibeenpwned.com/API/Key. The `apiKey`
892
+ option here is not explicitly required, but direct requests made without it
893
+ will fail (unless you specify a `baseUrl` to a proxy that inserts a valid API
894
+ key on your behalf).
681
895
 
682
896
  **Kind**: global function
683
897
  **Returns**: <code>Promise.&lt;Array.&lt;string&gt;&gt;</code> \| <code>Promise.&lt;null&gt;</code> - a Promise which resolves to an
@@ -730,11 +944,10 @@ Fetches all stealer log email addresses for a website domain.
730
944
  The result is an array of strings representing email addresses found in
731
945
  stealer logs for the specified website domain (e.g., "example.com").
732
946
 
733
- 🔑 `haveibeenpwned.com` requires an API key from
734
- https://haveibeenpwned.com/API/Key for the `stealerlogsbywebsitedomain`
735
- endpoint. The `apiKey` option here is not explicitly required, but direct
736
- requests made without it will fail (unless you specify a `baseUrl` to a proxy
737
- that inserts a valid API key on your behalf).
947
+ Requires a Pro API key from https://haveibeenpwned.com/API/Key. The `apiKey`
948
+ option here is not explicitly required, but direct requests made without it
949
+ will fail (unless you specify a `baseUrl` to a proxy that inserts a valid API
950
+ key on your behalf).
738
951
 
739
952
  **Kind**: global function
740
953
  **Returns**: <code>Promise.&lt;Array.&lt;string&gt;&gt;</code> \| <code>Promise.&lt;null&gt;</code> - a Promise which resolves to an
@@ -788,8 +1001,7 @@ Returns domains that have been successfully added to the Domain Search dashboard
788
1001
  after verifying control. Each domain includes metadata about breach counts and
789
1002
  the next renewal date, where available.
790
1003
 
791
- 🔑 `haveibeenpwned.com` requires an API key from
792
- https://haveibeenpwned.com/API/Key for the `subscribeddomains` endpoint. The
1004
+ Requires a Core or Pro API key from https://haveibeenpwned.com/API/Key. The
793
1005
  `apiKey` option here is not explicitly required, but direct requests made
794
1006
  without it will fail (unless you specify a `baseUrl` to a proxy that inserts
795
1007
  a valid API key on your behalf).
@@ -832,11 +1044,11 @@ try {
832
1044
  ## subscriptionStatus([options]) ⇒ [<code>Promise.&lt;SubscriptionStatus&gt;</code>](#subscriptionstatus--object)
833
1045
  Fetches the current status of your HIBP subscription (API key).
834
1046
 
835
- 🔑 `haveibeenpwned.com` requires an API key from
836
- https://haveibeenpwned.com/API/Key for the `subscription/status` endpoint.
837
- The `apiKey` option here is not explicitly required, but direct requests made
838
- without it will fail (unless you specify a `baseUrl` to a proxy that inserts
839
- a valid API key on your behalf).
1047
+ Requires a Core, Pro, or High RPM API key from
1048
+ https://haveibeenpwned.com/API/Key. The `apiKey` option here is not
1049
+ explicitly required, but direct requests made without it will fail (unless
1050
+ you specify a `baseUrl` to a proxy that inserts a valid API key on your
1051
+ behalf).
840
1052
 
841
1053
  **Kind**: global function
842
1054
  **Returns**: [<code>Promise.&lt;SubscriptionStatus&gt;</code>](#subscriptionstatus--object) - a Promise which resolves to a
@@ -871,33 +1083,92 @@ try {
871
1083
  // ...
872
1084
  }
873
1085
  ```
1086
+ <a name="verifyDnsToken"></a>
1087
+
1088
+ ## verifyDnsToken(domain, [options]) ⇒ <code>Promise.&lt;void&gt;</code>
1089
+ Verifies a domain's published HIBP TXT record.
1090
+
1091
+ Generate the value with `generateDnsToken`, publish it at your DNS provider,
1092
+ and allow time for DNS propagation first. The record can be removed after
1093
+ verification succeeds.
1094
+
1095
+ Requires a Pro API key from https://haveibeenpwned.com/API/Key. The `apiKey`
1096
+ option here is not explicitly required, but direct requests made without it
1097
+ will fail (unless you specify a `baseUrl` to a proxy that inserts a valid API
1098
+ key on your behalf).
1099
+
1100
+ **Kind**: global function
1101
+ **Returns**: <code>Promise.&lt;void&gt;</code> - a Promise which resolves without parsing the
1102
+ response body when verification succeeds, or rejects with an Error
1103
+ containing the upstream failure reason
1104
+ **See**: https://haveibeenpwned.com/API/v3#VerifyDomainViaDns
1105
+
1106
+ | Param | Type | Description |
1107
+ | --- | --- | --- |
1108
+ | domain | <code>string</code> | the domain to verify (e.g., "example.com") |
1109
+ | [options] | <code>object</code> | a configuration object |
1110
+ | [options.apiKey] | <code>string</code> | an API key from https://haveibeenpwned.com/API/Key (default: undefined) |
1111
+ | [options.baseUrl] | <code>string</code> | a custom base URL for the haveibeenpwned.com API endpoints (default: `https://haveibeenpwned.com/api/v3`) |
1112
+ | [options.timeoutMs] | <code>number</code> | timeout for the request in milliseconds (default: none) |
1113
+ | [options.signal] | <code>AbortSignal</code> | an AbortSignal to cancel the request (default: none) |
1114
+ | [options.userAgent] | <code>string</code> | a custom string to send as the User-Agent field in the request headers (default: `hibp <version>`) |
1115
+
1116
+ **Example**
1117
+ ```js
1118
+ try {
1119
+ await verifyDnsToken("example.com", { apiKey: "my-api-key" });
1120
+ // ...
1121
+ } catch (err) {
1122
+ // ...
1123
+ }
1124
+ ```
874
1125
  <a name="Breach"></a>
875
1126
 
876
1127
  ## Breach : <code>object</code>
877
1128
  An object representing a breach.
878
1129
 
1130
+ `Attribution` and `DisclosureUrl` may be null. See the
1131
+ [breach model](https://haveibeenpwned.com/API/v3#BreachModel) and the
1132
+ [breach catalogue](https://haveibeenpwned.com/api/v3/breaches).
1133
+
879
1134
  **Kind**: global typedef
880
1135
  **Properties**
881
1136
 
882
- | Name | Type |
883
- | --- | --- |
884
- | Name | <code>string</code> |
885
- | Title | <code>string</code> |
886
- | Domain | <code>string</code> |
887
- | BreachDate | <code>string</code> |
888
- | AddedDate | <code>string</code> |
889
- | ModifiedDate | <code>string</code> |
890
- | PwnCount | <code>number</code> |
891
- | Description | <code>string</code> |
892
- | DataClasses | <code>Array.&lt;string&gt;</code> |
893
- | IsVerified | <code>boolean</code> |
894
- | IsFabricated | <code>boolean</code> |
895
- | IsSensitive | <code>boolean</code> |
896
- | IsRetired | <code>boolean</code> |
897
- | IsSpamList | <code>boolean</code> |
898
- | IsMalware | <code>boolean</code> |
899
- | IsSubscriptionFree | <code>boolean</code> |
900
- | LogoPath | <code>string</code> |
1137
+ | Name | Type | Description |
1138
+ | --- | --- | --- |
1139
+ | Name | <code>string</code> | |
1140
+ | Title | <code>string</code> | |
1141
+ | Domain | <code>string</code> | |
1142
+ | BreachDate | <code>string</code> | |
1143
+ | AddedDate | <code>string</code> | |
1144
+ | ModifiedDate | <code>string</code> | |
1145
+ | PwnCount | <code>number</code> | |
1146
+ | Description | <code>string</code> | |
1147
+ | DataClasses | <code>Array.&lt;string&gt;</code> | |
1148
+ | IsVerified | <code>boolean</code> | |
1149
+ | IsFabricated | <code>boolean</code> | |
1150
+ | IsSensitive | <code>boolean</code> | |
1151
+ | IsRetired | <code>boolean</code> | |
1152
+ | IsSpamList | <code>boolean</code> | |
1153
+ | IsMalware | <code>boolean</code> | |
1154
+ | IsStealerLog | <code>boolean</code> | whether the breach is sourced from stealer logs |
1155
+ | IsSubscriptionFree | <code>boolean</code> | |
1156
+ | LogoPath | <code>string</code> | |
1157
+ | Attribution | <code>string</code> \| <code>null</code> | credit requested by the data provider, or null |
1158
+ | DisclosureUrl | <code>string</code> \| <code>null</code> | breach disclosure URL, or null |
1159
+
1160
+ <a name="BreachedAccountRangeResult"></a>
1161
+
1162
+ ## BreachedAccountRangeResult : <code>Object</code>
1163
+ A breached email hash suffix and the breach names associated with it.
1164
+
1165
+ **Kind**: global typedef
1166
+ **Properties**
1167
+
1168
+ | Name | Type | Description |
1169
+ | --- | --- | --- |
1170
+ | hashSuffix | <code>string</code> | the remaining 34 characters of a SHA-1 email hash |
1171
+ | websites | <code>Array.&lt;string&gt;</code> | breach names, not website domains or URLs |
901
1172
 
902
1173
  <a name="BreachedDomainsByEmailAlias"></a>
903
1174
 
@@ -906,6 +1177,31 @@ An object mapping an email alias (local-part before the '@') to the list of
906
1177
  breach names that alias has appeared in for the specified domain.
907
1178
 
908
1179
  **Kind**: global typedef
1180
+ <a name="DataClassDescription"></a>
1181
+
1182
+ ## DataClassDescription : <code>object</code>
1183
+ A data class name and its description.
1184
+
1185
+ **Kind**: global typedef
1186
+ **Properties**
1187
+
1188
+ | Name | Type | Description |
1189
+ | --- | --- | --- |
1190
+ | name | <code>string</code> | the data class name |
1191
+ | description | <code>string</code> | a description of the compromised data |
1192
+
1193
+ <a name="DnsToken"></a>
1194
+
1195
+ ## DnsToken : <code>object</code>
1196
+ The TXT record value to publish at your DNS provider.
1197
+
1198
+ **Kind**: global typedef
1199
+ **Properties**
1200
+
1201
+ | Name | Type | Description |
1202
+ | --- | --- | --- |
1203
+ | txtRecordValue | <code>string</code> | the complete TXT record value |
1204
+
909
1205
  <a name="Paste"></a>
910
1206
 
911
1207
  ## Paste : <code>object</code>
@@ -914,13 +1210,13 @@ An object representing a paste.
914
1210
  **Kind**: global typedef
915
1211
  **Properties**
916
1212
 
917
- | Name | Type |
918
- | --- | --- |
919
- | Id | <code>string</code> |
920
- | Source | <code>string</code> |
921
- | Title | <code>string</code> |
922
- | Date | <code>string</code> |
923
- | EmailCount | <code>number</code> |
1213
+ | Name | Type | Description |
1214
+ | --- | --- | --- |
1215
+ | Id | <code>string</code> | |
1216
+ | Source | <code>string</code> | |
1217
+ | [Title] | <code>string</code> | omitted when the source has no title |
1218
+ | Date | <code>string</code> \| <code>null</code> | null when the source has no posting date |
1219
+ | EmailCount | <code>number</code> | |
924
1220
 
925
1221
  <a name="PwnedPasswordSuffixes"></a>
926
1222
 
@@ -942,12 +1238,18 @@ An object representing search results.
942
1238
  | breaches | [<code>Array.&lt;Breach&gt;</code>](#breach--object) \| <code>null</code> |
943
1239
  | pastes | [<code>Array.&lt;Paste&gt;</code>](#Paste) \| <code>null</code> |
944
1240
 
1241
+ <a name="EmailAlias"></a>
1242
+
1243
+ ## EmailAlias : <code>&quot;admin&quot;</code> \| <code>&quot;hostmaster&quot;</code> \| <code>&quot;info&quot;</code> \| <code>&quot;security&quot;</code> \| <code>&quot;webmaster&quot;</code>
1244
+ An administrative alias supported for domain verification emails.
1245
+
1246
+ **Kind**: global typedef
945
1247
  <a name="StealerLogDomainsByEmailAlias"></a>
946
1248
 
947
1249
  ## StealerLogDomainsByEmailAlias : <code>Object.&lt;string, Array.&lt;string&gt;&gt;</code>
948
1250
  An object mapping an email alias (local-part before the '@') to the list of
949
- email domains that alias has appeared in within stealer logs for the specified
950
- email domain.
1251
+ website domains that alias has appeared against in stealer logs for the
1252
+ specified email domain.
951
1253
 
952
1254
  **Kind**: global typedef
953
1255
  <a name="SubscribedDomain"></a>
@@ -974,12 +1276,17 @@ An object representing the status of your HIBP subscription.
974
1276
  **Kind**: global typedef
975
1277
  **Properties**
976
1278
 
977
- | Name | Type |
978
- | --- | --- |
979
- | SubscriptionName | <code>string</code> |
980
- | Description | <code>string</code> |
981
- | SubscribedUntil | <code>string</code> |
982
- | Rpm | <code>number</code> |
983
- | DomainSearchMaxBreachedAccounts | <code>number</code> |
984
- | IncludesStealerLogs | <code>boolean</code> |
1279
+ | Name | Type | Description |
1280
+ | --- | --- | --- |
1281
+ | SubscriptionName | <code>string</code> | |
1282
+ | Description | <code>string</code> | |
1283
+ | SubscribedUntil | <code>string</code> | |
1284
+ | Rpm | <code>number</code> | |
1285
+ | DomainSearchMaxBreachedAccounts | <code>number</code> | |
1286
+ | MaxBreachedDomains | <code>number</code> \| <code>null</code> | maximum domains that can be added; null means no limit |
1287
+ | IncludesStealerLogs | <code>boolean</code> | |
1288
+ | IncludesBulkDomainAdd | <code>boolean</code> | access to APIs for adding domains in bulk |
1289
+ | IncludesAutoSubdomainVerification | <code>boolean</code> | automatic verification of subdomains of a verified apex domain |
1290
+ | IncludesCustomerDomains | <code>boolean</code> | permission to add customer domains |
1291
+ | IncludesKAnon | <code>boolean</code> | access to email address searches using k-anonymity |
985
1292