feat: add new subscriptionStatus module (#425)

Author: wKovacs64

.bundlewatch.config.json

@@ -3,7 +3,7 @@
     {
       "//": "Pre-bundled for Browser (UMD)",
       "path": "dist/browser/hibp.umd.js",
-      "maxSize": "9 kB"
+      "maxSize": "9.2 kB"
     },
     {
       "//": "Pre-bundled for Browser (ESM)",
@@ -43,6 +43,10 @@
       "path": "dist/cjs/search.js",
       "maxSize": "1.5 kB"
     },
+    {
+      "path": "dist/cjs/subscription-status.js",
+      "maxSize": "1 kB"
+    },
     {
       "//": "Bundled with Webpack (ESM)",
       "path": "dist/esm/breach.mjs",
@@ -75,6 +79,10 @@
     {
       "path": "dist/esm/search.mjs",
       "maxSize": "1.4 kB"
+    },
+    {
+      "path": "dist/esm/subscription-status.mjs",
+      "maxSize": "1 kB"
     }
   ]
 }

.changeset/proud-carrots-cough.md

@@ -0,0 +1,5 @@
+---
+'hibp': minor
+---
+
+Add a new `subscriptionStatus` module for retrieving the current subscription status of your HIBP API key. See https://haveibeenpwned.com/API/v3#SubscriptionStatus for more information.

API.md

@@ -57,6 +57,9 @@ convenience method is designed to mimic.</p>
 required, but direct requests made without it (that is, without specifying a
 <code>baseUrl</code> to a proxy that inserts a valid API key on your behalf) will fail.</p>
 </dd>
+<dt><a href="#subscriptionStatus">subscriptionStatus(apiKey, [options])</a> ⇒ <code><a href="#subscriptionstatus--object">Promise.&lt;SubscriptionStatus&gt;</a></code></dt>
+<dd><p>Fetches the current status of your HIBP subscription (API key).</p>
+</dd>
 </dl>
 
 ## Typedefs
@@ -75,6 +78,9 @@ hash prefix) to how many times it occurred in the Pwned Passwords repository.</p
 <dt><a href="#SearchResults">SearchResults</a> : <code>object</code></dt>
 <dd><p>An object representing search results.</p>
 </dd>
+<dt><a href="#subscriptionstatus--object">SubscriptionStatus</a> : <code>object</code></dt>
+<dd><p>An object representing the status of your HIBP subscription.</p>
+</dd>
 </dl>
 
 <a name="breach"></a>
@@ -444,6 +450,31 @@ try {
   // ...
 }
 ```
+<a name="subscriptionStatus"></a>
+
+## subscriptionStatus(apiKey, [options]) ⇒ [<code>Promise.&lt;SubscriptionStatus&gt;</code>](#subscriptionstatus--object)
+Fetches the current status of your HIBP subscription (API key).
+
+**Kind**: global function  
+**Returns**: [<code>Promise.&lt;SubscriptionStatus&gt;</code>](#subscriptionstatus--object) - a Promise which resolves to a
+subscription status object, or rejects with an Error  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| apiKey | <code>string</code> | an API key from https://haveibeenpwned.com/API/Key |
+| [options] | <code>object</code> | a configuration object |
+| [options.baseUrl] | <code>string</code> | a custom base URL for the haveibeenpwned.com API endpoints (default: `https://haveibeenpwned.com/api/v3`) |
+| [options.userAgent] | <code>string</code> | a custom string to send as the User-Agent field in the request headers (default: `hibp <version>`) |
+
+**Example**  
+```js
+try {
+  const data = await subscriptionStatus("my-api-key");
+  // ...
+} catch (err) {
+  // ...
+}
+```
 <a name="Breach"></a>
 
 ## Breach : <code>object</code>
@@ -508,3 +539,19 @@ An object representing search results.
 | breaches | [<code>Array.&lt;Breach&gt;</code>](#breach--object) \| <code>null</code> | 
 | pastes | [<code>Array.&lt;Paste&gt;</code>](#Paste) \| <code>null</code> | 
 
+<a name="SubscriptionStatus"></a>
+
+## SubscriptionStatus : <code>object</code>
+An object representing the status of your HIBP subscription.
+
+**Kind**: global typedef  
+**Properties**
+
+| Name | Type |
+| --- | --- |
+| SubscriptionName | <code>string</code> | 
+| Description | <code>string</code> | 
+| SubscribedUntil | <code>string</code> | 
+| Rpm | <code>number</code> | 
+| DomainSearchMaxBreachedAccounts | <code>number</code> | 
+

README.md

@@ -46,6 +46,7 @@ use it in the browser.
   a data breach
 - Check a SHA-1 or NTLM prefix to see if it has been exposed in a data breach
 - Search for an account in both breaches and pastes at the same time 🔑
+- Get your subscription status 🔑
 - All queries return a Promise
 - Available server-side (Node.js) and client-side (browser)
 - Written in TypeScript, so all modules come fully typed
@@ -80,6 +81,7 @@ The following modules are available:
 - [pwnedPassword](API.md#pwnedpassword)
 - [pwnedPasswordRange](API.md#pwnedpasswordrange)
 - [search](API.md#search)
+- [subscriptionStatus](API.md#subscriptionstatus)
 
 Please see the [API reference](API.md) for more detailed usage information and
 examples.

docs/index.md

@@ -41,6 +41,7 @@ use it in the browser.
   check a password to see if it has been exposed in a data breach
 - Check a SHA-1 or NTLM prefix to see if it has been exposed in a data breach
 - Search for an account in both breaches and pastes at the same time 🔑
+- Get your subscription status 🔑
 - All queries return a Promise
 - Available server-side (Node.js) and client-side (browser)
 - Written in TypeScript, so all modules come fully typed
@@ -75,6 +76,7 @@ The following modules are available:
 - [pwnedPassword](https://github.com/wKovacs64/hibp/tree/main/API.md#pwnedpassword)
 - [pwnedPasswordRange](https://github.com/wKovacs64/hibp/tree/main/API.md#pwnedpasswordrange)
 - [search](https://github.com/wKovacs64/hibp/tree/main/API.md#search)
+- [subscriptionStatus](https://github.com/wKovacs64/hibp/tree/main/API.md#subscriptionstatus)
 
 Please see the
 [API reference](https://github.com/wKovacs64/hibp/tree/main/API.md) for more

scripts/fix-api-docs.js

@@ -3,10 +3,11 @@ import fs from 'node:fs';
 const filename = 'API.md';
 const generatedApiDocs = fs.readFileSync(filename, 'utf8');
 const newApiDocs = generatedApiDocs
-  // Replace the generated link to the `Breach` object with a more specific
-  // anchor name as the generated one collides with the `breach` function
-  // because anchor links are case insensitive.
+  // Replace the generated links to certain objects with more specific anchor
+  // names as the generated ones collide with functions that share a name with
+  // the objects (as anchor links are case insensitive).
   .replace(/#Breach/g, '#breach--object')
+  .replace(/#SubscriptionStatus/g, '#subscriptionstatus--object')
   // Surround all the generated Promise.<Array.<Type>> strings with links to the
   // corresponding typedef object as jsdoc2md seems to have an issue parsing the
   // syntax for a promise that resolves to an array of custom types.

src/__tests__/hibp.test.ts

@@ -13,6 +13,7 @@ describe('hibp', () => {
         "pwnedPassword": [Function],
         "pwnedPasswordRange": [Function],
         "search": [Function],
+        "subscriptionStatus": [Function],
       }
     `);
   });

src/__tests__/subscription-status.test.ts

@@ -0,0 +1,52 @@
+import { http } from 'msw';
+import { server } from '../mocks/server.js';
+import { EXAMPLE_SUBSCRIPTION_STATUS } from '../../test/fixtures.js';
+import { subscriptionStatus } from '../subscription-status.js';
+
+describe('subscriptionStatus', () => {
+  const apiKey = 'my-api-key';
+
+  describe('apiKey parameter', () => {
+    it('sets the hibp-api-key header', async () => {
+      expect.assertions(1);
+      server.use(
+        http.get('*', ({ request }) => {
+          expect(request.headers.get('hibp-api-key')).toBe(apiKey);
+          return new Response(JSON.stringify(EXAMPLE_SUBSCRIPTION_STATUS));
+        }),
+      );
+
+      return subscriptionStatus(apiKey);
+    });
+  });
+
+  describe('baseUrl option', () => {
+    it('is the beginning of the final URL', () => {
+      const baseUrl = 'https://my-hibp-proxy:8080';
+      server.use(
+        http.get(new RegExp(`^${baseUrl}`), () => {
+          return new Response(JSON.stringify(EXAMPLE_SUBSCRIPTION_STATUS));
+        }),
+      );
+
+      return expect(subscriptionStatus(apiKey, { baseUrl })).resolves.toEqual(
+        EXAMPLE_SUBSCRIPTION_STATUS,
+      );
+    });
+  });
+
+  describe('userAgent option', () => {
+    it('is passed on as a request header', () => {
+      expect.assertions(1);
+      const userAgent = 'Custom UA';
+      server.use(
+        http.get('*', ({ request }) => {
+          expect(request.headers.get('User-Agent')).toBe(userAgent);
+          return new Response(JSON.stringify(EXAMPLE_SUBSCRIPTION_STATUS));
+        }),
+      );
+
+      return subscriptionStatus(apiKey, { userAgent });
+    });
+  });
+});

src/api/haveibeenpwned/types.ts

@@ -30,6 +30,14 @@ export interface Paste {
   EmailCount: number;
 }
 
+export interface SubscriptionStatus {
+  SubscriptionName: string;
+  Description: string;
+  SubscribedUntil: string;
+  Rpm: number;
+  DomainSearchMaxBreachedAccounts: number;
+}
+
 //
 // Internal convenience types
 //
@@ -44,6 +52,7 @@ export type ApiData =
   | Breach[] // breachedaccount, breaches
   | Paste[] // pasteaccount
   | string[] // dataclasses
+  | SubscriptionStatus // subscription/status
   | null; // most endpoints can return an empty response (404, but not an error)
 
 /**

src/hibp.ts

@@ -7,6 +7,7 @@ import { pasteAccount } from './paste-account.js';
 import { pwnedPassword } from './pwned-password.js';
 import { pwnedPasswordRange } from './pwned-password-range.js';
 import { search } from './search.js';
+import { subscriptionStatus } from './subscription-status.js';
 
 /*
  * Export individual named functions to allow the following:
@@ -26,6 +27,7 @@ export {
   pwnedPassword,
   pwnedPasswordRange,
   search,
+  subscriptionStatus,
   RateLimitError,
 };
 
@@ -40,6 +42,7 @@ export interface HIBP {
   pwnedPassword: typeof pwnedPassword;
   pwnedPasswordRange: typeof pwnedPasswordRange;
   search: typeof search;
+  subscriptionStatus: typeof subscriptionStatus;
   RateLimitError: typeof RateLimitError;
 }