tessl/npm-link-preview-js

JavaScript module to extract and fetch HTTP link information from blocks of text via OpenGraph and meta tag parsing.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Link Preview Extraction

Name: tessl/npm-link-preview-js
Author: tessl

Comprehensive link preview generation from URLs or text containing URLs with automatic URL detection, HTTP fetching, and rich metadata extraction.

Capabilities

getLinkPreview Function

Parses text to find the first valid HTTP(S) URL, fetches the content, and extracts comprehensive link preview metadata including titles, descriptions, images, videos, and favicons.

/**
 * Parses text to find first HTTP(S) URL, fetches content, and extracts link preview metadata
 * @param text - URL or text containing a URL to be parsed
 * @param options - Configuration options for request and parsing
 * @returns Promise resolving to preview information object
 * @throws Error if no valid URL found, request timeout, or parsing fails
 */
function getLinkPreview(
  text: string,
  options?: ILinkPreviewOptions
): Promise<ILinkPreviewResponse>;

Basic Usage:

import { getLinkPreview } from "link-preview-js";

// Direct URL
const preview = await getLinkPreview("https://www.example.com");

// Text containing URL
const textPreview = await getLinkPreview(
  "Check out this site: https://www.example.com - it's amazing!"
);

// URL with newlines
const cleanPreview = await getLinkPreview(`
  https://www.example.com
`);

Advanced Usage with Options:

import { getLinkPreview } from "link-preview-js";

// Custom headers and timeout
const preview = await getLinkPreview("https://www.example.com", {
  headers: {
    "User-Agent": "MyBot/1.0",
    "Accept-Language": "en-US"
  },
  timeout: 5000,
  imagesPropertyType: "og"
});

// Using proxy
const proxyPreview = await getLinkPreview("https://www.example.com", {
  proxyUrl: "https://cors-proxy.example.com/",
  headers: {
    "Origin": "https://myapp.com"
  }
});

// With custom response processing
const customPreview = await getLinkPreview("https://www.example.com", {
  onResponse: (response, doc, url) => {
    // Add custom logic for specific sites
    if (url?.hostname === "example.com") {
      response.siteName = "Custom Example Site";
    }
    
    // Fallback description from first paragraph
    if (!response.description) {
      response.description = doc('p').first().text();
    }
    
    return response;
  }
});

URL Detection and Validation

The function automatically detects and validates URLs using sophisticated regex patterns that:

Match HTTP and HTTPS protocols only
Exclude private network IP ranges (10.x.x.x, 192.168.x.x, 172.16-31.x.x, 127.x.x.x)
Validate domain names and TLD requirements
Support international domain names
Allow port numbers and URL paths

Supported URL Formats:

// These URLs will be detected and processed:
"https://www.example.com"
"http://subdomain.example.org:8080/path?query=value"
"https://例え.テスト"  // International domains
"Text before https://example.com text after"  // URLs in text

// These will be rejected:
"https://192.168.1.1"     // Private IP
"https://127.0.0.1"       // Loopback
"ftp://example.com"       // Unsupported protocol
"example.com"             // Missing protocol

Content Type Handling

The function handles different content types automatically:

HTML/Text Content:

Extracts OpenGraph tags (og:title, og:description, og:image, etc.)
Falls back to standard HTML meta tags
Parses Twitter Card metadata
Extracts favicon links and provides default fallback

Media Files:

Images: Returns media type "image" with content type and default favicon
Audio: Returns media type "audio" with content type and default favicon
Video: Returns media type "video" with content type and default favicon
Applications: Returns media type "application" with content type and default favicon

Error Handling

The function throws descriptive errors for various failure scenarios:

// Error examples
try {
  await getLinkPreview("no url here");
} catch (error) {
  // "link-preview-js did not receive a valid a url or text"
}

try {
  await getLinkPreview("https://slow-site.com", { timeout: 1000 });
} catch (error) {
  // "Request timeout"
}

try {
  await getLinkPreview("https://redirect-site.com", { 
    followRedirects: "manual" 
    // Missing handleRedirects function
  });
} catch (error) {
  // "link-preview-js followRedirects is set to manual, but no handleRedirects function was provided"
}

Response Structure

interface ILinkPreviewResponse {
  /** The resolved URL that was processed */
  url: string;
  /** Page title from meta tags or HTML title element */
  title: string;
  /** Site name from og:site_name meta tag */
  siteName: string | undefined;
  /** Description from meta tags */
  description: string | undefined;
  /** Type of content (website, image, video, audio, application) */
  mediaType: string;
  /** HTTP Content-Type header value */
  contentType: string | undefined;
  /** Array of image URLs found in meta tags or img elements */
  images: string[];
  /** Array of video objects from og:video meta tags */
  videos: IVideoType[];
  /** Array of favicon URLs */
  favicons: string[];
  /** Character encoding parsed from Content-Type header (optional) */
  charset?: string;
}

Example Responses:

HTML Page:

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up",
  "siteName": "YouTube",
  "description": "The official video for Rick Astley's 1987 hit...",
  "mediaType": "video.other",
  "contentType": "text/html",
  "images": ["https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"],
  "videos": [],
  "favicons": ["https://www.youtube.com/favicon.ico"],
  "charset": "utf-8"
}

Image File:

{
  "url": "https://example.com/image.jpg",
  "mediaType": "image",
  "contentType": "image/jpeg",
  "favicons": ["https://example.com/favicon.ico"]
}