Merge pull request #170 from Alpha4615/feature/onResponse-override

Resolves #159 - Creates an onResponse c…

Author: ospfranco

README.md

@@ -95,6 +95,7 @@ Additionally, you can pass an options object which should add more functionality
 | followRedirects (**optional**) (default 'error')                                       | For security reasons, the library does not automatically follow redirects ('error' value), a malicious agent can exploit redirects to steal data, posible values: ('error', 'follow', 'manual') |
 | handleRedirects (**optional**) (with followRedirects 'manual')                         |                         When followRedirects is set to 'manual' you need to pass a function that validates if the redirectinon is secure, below you can find an example                         |
 | resolveDNSHost (**optional**)                                                          |                                                   Function that resolves the final address of the detected/parsed URL to prevent SSRF attacks                                                   |
+| onResponse (**optional**)                                                          |                                                   Function that handles the response object to allow for managing special cases                                                   |
 
 ```javascript
 getLinkPreview("https://www.youtube.com/watch?v=MejbOFk7H6c", {
@@ -159,6 +160,25 @@ await getLinkPreview(`http://google.com/`, {
 });
 ```
 
+## onResponse Use Cases
+There may be situations where you need to provide your own logic for population properties in the response object. For example, if the library is unable to detect a description because the website does not provide OpenGraph data, you might want to use the text value of the first paragraph instead. This callback gives you access to the Cheerio doc instance, as well as the URL object so you could handle cases on a site-by-site basis, if you need to. This callback must return the modified response object
+
+```javascript
+await getLinkPreview(`https://example.com/`, {
+  onResponse: (response, doc, URL) => {
+    if (URL.hostname == 'example.com') {
+        response.siteName = 'Example Website';
+    }
+
+    if (!response.description) {
+      response.description = doc('p').first().text();
+    }
+    
+    return response;
+  },
+});
+```
+
 ## Response
 
 Returns a Promise that resolves with an object describing the provided link.

__tests__/index.spec.ts

@@ -243,6 +243,23 @@ describe(`#getLinkPreview()`, () => {
     expect(response.mediaType).toEqual(`website`);
   });
 
+  it("should handle override response body using onResponse option", async () => {	
+    let firstParagraphText;
+
+    const res: any = await getLinkPreview(`https://www.example.com/`, { 
+      onResponse: (result, doc) => {
+        firstParagraphText = doc('p').first().text().split('\n').map(x=> x.trim()).join(' ');
+        result.siteName = `SiteName has been overridden`;
+        result.description = firstParagraphText;
+
+        return result;
+      }
+    });
+
+    expect(res.siteName).toEqual("SiteName has been overridden");
+    expect(res.description).toEqual(firstParagraphText);
+  });
+
   it("should handle video tags without type or secure_url tags", async () => {
     const res: any = await getLinkPreview(
       `https://newpathtitle.com/falling-markets-how-to-stop-buyer-from-getting-out/`,

index.ts

@@ -2,6 +2,26 @@ import cheerio from "cheerio";
 import urlObj from "url";
 import { CONSTANTS } from "./constants";
 
+interface ILinkPreviewResponse {
+  url: string;
+  title: string;
+  siteName: string | undefined;
+  description: string | undefined;
+  mediaType: string;
+  contentType: string | undefined;
+  images: string[];
+  videos: IVideoType[];
+  favicons: string[];
+}
+
+interface IVideoType {
+  url: string | undefined,
+  secureUrl: string | null | undefined,
+  type: string | null | undefined,
+  width: string | undefined,
+  height: string | undefined,
+};
+
 interface ILinkPreviewOptions {
   headers?: Record<string, string>;
   imagesPropertyType?: string;
@@ -10,6 +30,7 @@ interface ILinkPreviewOptions {
   followRedirects?: `follow` | `error` | `manual`;
   resolveDNSHost?: (url: string) => Promise<string>;
   handleRedirects?: (baseURL: string, forwardedURL: string) => boolean;
+  onResponse?: (response: ILinkPreviewResponse, doc: cheerio.Root, url?: URL) => ILinkPreviewResponse;
 }
 
 interface IPreFetchedResource {
@@ -272,10 +293,10 @@ function parseTextResponse(
   url: string,
   options: ILinkPreviewOptions = {},
   contentType?: string
-) {
+): ILinkPreviewResponse {
   const doc = cheerio.load(body);
 
-  return {
+  let response = {
     url,
     title: getTitle(doc),
     siteName: getSiteName(doc),
@@ -286,6 +307,23 @@ function parseTextResponse(
     videos: getVideos(doc),
     favicons: getFavicons(doc, url),
   };
+
+  if (options?.onResponse && typeof options.onResponse !== `function`) {
+    throw new Error(
+      `link-preview-js onResponse option must be a function`
+    );
+  }
+
+  if (options?.onResponse) {
+	// send in a cloned response (to avoid mutation of original response reference)
+	const clonedResponse = structuredClone(response);
+	const urlObject = new URL(url)
+    response = options.onResponse(clonedResponse, doc, urlObject);
+  }
+
+
+  return response;
+
 }
 
 function parseUnknownResponse(