Implement URL threat detection in GoogleSafeBrowsing.

This update introduces a new method to detect threats from URLs using the Google Safe Browsing API. It includes enhanced error handling with more descriptive error messages and updates to the README.md with usage examples. Additionally, tests have been added to confirm the correct detection of malicious links.

README.md

@@ -21,6 +21,9 @@ Finds the threat entries that match the Safe Browsing lists.
 ```ts
 import { GoogleSafeBrowsing } from '@hckhanh/google-safe-browsing'
 
+// Initialize Google Safe Browsing client with API key and required identifiers
+// clientId: Unique identifier for your application instance
+// clientVersion: Current version of your application
 const client = new GoogleSafeBrowsing('apiKey', {
   clientId: 'uniqueClientId',
   clientVersion: '1.0.0',
@@ -35,7 +38,26 @@ const result = await client.findThreatMatches({
   ],
 })
 
-const hasRisk = result.matches !== undefined && result.matches.length > 0
+const hasRisk = result.matches?.length > 0
+```
+
+### Find threat entries from urls
+
+Finds the threat entries that match the Safe Browsing lists from the input urls
+
+```ts
+import { GoogleSafeBrowsing } from '@hckhanh/google-safe-browsing'
+
+const client = new GoogleSafeBrowsing('apiKey', {
+  clientId: 'uniqueClientId',
+  clientVersion: '1.0.0',
+})
+
+const result = await client.findThreatMatchesFromUrls([
+  'http://malware.testing.google.test/testing/malware/',
+])
+
+const hasRisk = result.matches?.length > 0
 ```
 
 ## Release Notes

src/GoogleSafeBrowsing.test.ts

@@ -35,4 +35,24 @@ describe('GoogleSafeBrowsing', () => {
       ],
     })
   })
+
+  it('should detect malicious link from urls', async () => {
+    await expect(
+      client.findThreatMatchesFromUrls([
+        'http://malware.testing.google.test/testing/malware/',
+      ]),
+    ).resolves.toEqual({
+      matches: [
+        {
+          threatType: 'MALWARE',
+          platformType: 'ANY_PLATFORM',
+          threat: {
+            url: 'http://malware.testing.google.test/testing/malware/',
+          },
+          cacheDuration: '300s',
+          threatEntryType: 'URL',
+        },
+      ],
+    })
+  })
 })

src/GoogleSafeBrowsing.ts

@@ -73,7 +73,7 @@ export class GoogleSafeBrowsing {
    *   ],
    * })
    *
-   * const hasRisk = result.matches !== undefined && result.matches.length > 0
+   * const hasRisk = result.matches?.length > 0
    * ```
    *
    * @param threatInfo The lists and entries to be checked for matches.
@@ -100,11 +100,50 @@ export class GoogleSafeBrowsing {
         throw new Error('Rate limit exceeded for Google Safe Browsing API')
       }
 
-      throw new Error(`API request failed with status ${res.status}`)
+      const errorBody = await res.text()
+      throw new Error(
+        `API request failed with status ${res.status}: ${errorBody}`,
+      )
     }
 
     return res.json()
   }
+
+  /**
+   * Finds threat matches from urls using Google Safe Browsing API.
+   *
+   * @example
+   * ```ts
+   * const client = new GoogleSafeBrowsing('apiKey', {
+   *  clientId: 'uniqueClientId',
+   *  clientVersion: '1.0.0',
+   * })
+   * const result = await client.findThreatMatchesFromUrls([
+   *   'http://malware.testing.google.test/testing/malware/'
+   * ])
+   *
+   * const hasRisk = result.matches?.length > 0
+   * ```
+   *
+   * @param urls The list of urls to be checked for matches.
+   *
+   * @return A promise that resolves to the response object containing the list of {@link ThreatMatch}.
+   */
+  async findThreatMatchesFromUrls(
+    urls: string[],
+  ): Promise<FindThreatMatchesResponse> {
+    return this.findThreatMatches({
+      threatTypes: [
+        'MALWARE',
+        'UNWANTED_SOFTWARE',
+        'SOCIAL_ENGINEERING',
+        'POTENTIALLY_HARMFUL_APPLICATION',
+      ],
+      platformTypes: ['ANY_PLATFORM'],
+      threatEntryTypes: ['URL'],
+      threatEntries: urls.map((url) => ({ url })),
+    })
+  }
 }
 
 /**