API reference

One result shape across server runtimes.

The root export provides preview, parseHTML, presets, URL validation helpers, and typed errors in ESM and CommonJS.

`preview(url, options?)`

Fetch an HTTP(S) URL, validate redirects, enforce timeout and byte limits, then extract preview metadata. Network failures propagate; invalid input and policy failures throw LinkpeekError.

Options

Option	Default	Purpose
`timeout`	8000	Whole-request deadline in milliseconds
`maxBytes`	30,000	Maximum decoded response-body bytes retained
`userAgent`	Twitterbot/1.0	User-Agent sent to the target
`followRedirects`	true	Validate and follow HTTP redirects
`maxRedirects`	10	Redirect ceiling
`headers`	{}	Extra non-sensitive request headers
`allowPrivateIPs`	false	Explicit private-network opt-in
`includeBodyContent`	false	Scan body JSON-LD and image fallback
`followMetaRefresh`	false	Follow one validated fast refresh declared in the head
`signal`	—	Caller cancellation
`fetch`	global fetch	Inject a compatible fetch implementation

Result fields

The stable result includes url, statusCode, title, description, image, siteName, favicon, canonicalUrl, author/date/language fields, video/audio URLs, Twitter fields, theme color, and an optional discovered oEmbed endpoint.

Extracted resource URLs are resolved against the document base and limited to HTTP(S).

`parseHTML(html, baseUrl, options?)`

Use the parser directly when HTML is already available. Default parsing stops tokenizing at the end of the head. Set includeBodyContent: true only when body JSON-LD or image fallback is worth the extra work.

Typed errors

try {
	await preview(url);
} catch (error) {
	if (error instanceof LinkpeekError) {
		console.log(error.code); // "TIMEOUT", "PRIVATE_NETWORK_BLOCKED", …
	}
}

Use code, never message matching, for program flow.