# API reference

> Reference for linkpeek's preview() and parseHTML(): presets, every option, the typed result fields, HTTP error handling and the error codes.

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

## Fetch a URL

`preview(url, options?)` returns `Promise<PreviewResult>`.

Fetch an HTTP(S) URL, validate redirects, enforce timeout and byte limits, then extract preview metadata. Invalid input, policy failures, timeouts and network failures throw `LinkpeekError`; a caller abort rethrows the signal's reason.

HTML responses with an HTTP error status still resolve with extracted metadata. Check `result.statusCode` before caching or displaying a successful card. Direct image, video and audio responses populate the corresponding media URL field.

```ts
import { preview } from "linkpeek";

const result = await preview("https://example.com/article");
if (result.statusCode < 400) {
  console.log(result.title ?? result.siteName);
}
```

## Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `timeout` | `number` | `8000` | Deadline in milliseconds for the whole call (redirects, body read and any meta-refresh hop), from 0 to 2,147,483,647. Throws `LinkpeekError` code `TIMEOUT` when elapsed; invalid values throw `INVALID_OPTIONS` |
| `maxBytes` | `number` | `30_000` | Maximum decoded response-body bytes to retain. `result.truncated` reports when the limit cut the head (or the document, with `includeBodyContent`) |
| `userAgent` | `string` | `"Twitterbot/1.0"` | User-Agent sent with requests |
| `followRedirects` | `boolean` | `true` | Follow HTTP redirects after validating each target |
| `maxRedirects` | `number` | `10` | Maximum redirects per call, HTTP and meta refresh combined. Must be a non-negative integer; invalid values throw `INVALID_OPTIONS` |
| `headers` | `Record<string, string>` | `{}` | Extra non-sensitive request headers. Common credential-bearing headers are rejected; custom headers are not forwarded on cross-origin redirects |
| `allowPrivateIPs` | `boolean` | `false` | Allow private/internal IP targets |
| `resolveHost` | `(hostname) => Promise<string[]>` | none | Opt-in DNS check on the first request and every redirect hop; private answers throw `PRIVATE_NETWORK_BLOCKED`, lookup errors and empty answers throw `FETCH_FAILED` (a `LinkpeekError`, resolver error in `cause`). Example in [DNS checks](https://linkpeek.js.org/security/#dns) |
| `signal` | `AbortSignal` | none | Cancel the request from the caller side |
| `fetch` | `typeof fetch` | `globalThis.fetch` | Custom fetch implementation. It must honor manual redirects and the supplied abort signal; a `response.url` it reports is validated too |
| `followMetaRefresh` | `boolean` | `false` | Follow one `<head>` `<meta http-equiv="refresh">` redirect with a delay of 10s or less |
| `includeBodyContent` | `boolean` | `false` | Continue scanning `<body>` for JSON-LD and image fallbacks |

## Result fields

All result fields are present. Optional metadata uses `null` when unavailable; titles and images are not guaranteed.

Extracted resource URLs are resolved against the document base and limited to HTTP(S). Text fields are trimmed with whitespace runs collapsed; blank values count as missing. JSON-LD fields all come from one entity: the first article, product or similar content entity, else a page entity, never a site-wide `Organization` or `WebSite`. For every field the first usable tag wins.

| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | Final fetched URL; `parseHTML()` returns the canonical URL |
| `statusCode` | `number` | HTTP status code. `parseHTML()` returns `0` |
| `title` | `string \| null` | `og:title` -\> `twitter:title` -\> Dublin Core -\> `<title>` -\> JSON-LD headline or name of the page's main entity |
| `description` | `string \| null` | `og:description` -\> `twitter:description` -\> `meta[name=description]` -\> JSON-LD -\> Dublin Core |
| `image` | `string \| null` | Preview image URL |
| `imageAlt` | `string \| null` | Image alt text |
| `imageWidth` | `number \| null` | `og:image:width` |
| `imageHeight` | `number \| null` | `og:image:height` |
| `siteName` | `string` | `og:site_name` -\> JSON-LD publisher -\> JSON-LD `WebSite` name -\> hostname |
| `favicon` | `string \| null` | Declared favicon, or the origin’s /favicon.ico as a fallback guess |
| `mediaType` | `string` | `og:type`, defaults to `"website"` |
| `canonicalUrl` | `string` | Canonical URL, `og:url`, or fetched URL |
| `author` | `string \| null` | JSON-LD author, author meta, or Dublin Core creator |
| `locale` | `string \| null` | `og:locale` |
| `lang` | `string \| null` | HTML language, content-language, or locale prefix |
| `publishedDate` | `string \| null` | Article, JSON-LD, or Dublin Core date |
| `keywords` | `string[] \| null` | `meta[name=keywords]` |
| `video` | `string \| null` | Safe `og:video` URL |
| `videoType` | `string \| null` | `og:video:type` MIME type, or the content type of a direct video URL; `null` without a video |
| `audio` | `string \| null` | Safe `og:audio` URL |
| `twitterCard` | `string \| null` | Twitter card type |
| `twitterSite` | `string \| null` | Twitter site handle |
| `twitterCreator` | `string \| null` | Twitter creator handle |
| `twitterPlayer` | `string \| null` | `twitter:player` embed URL (an iframe page), http(s) only |
| `twitterPlayerStream` | `string \| null` | `twitter:player:stream` raw media URL, http(s) only |
| `themeColor` | `string \| null` | Theme color |
| `oEmbedUrl` | `string \| null` | Discovered oEmbed endpoint URL. Not fetched |
| `truncated` | `boolean` | `maxBytes` cut the response before the end of `<head>` (or of the document with `includeBodyContent`); raise `maxBytes` to read later tags. `parseHTML()` returns `false` |

## Parse existing HTML

`parseHTML(html, baseUrl, options?)` returns `PreviewResult` synchronously, with `statusCode: 0`. It makes no network requests. `baseUrl` must be an absolute HTTP(S) URL; anything else throws `LinkpeekError` code `INVALID_URL` rather than inventing a site name, favicon and canonical URL. Both `url` and `canonicalUrl` contain the resolved canonical URL. The options object accepts `includeBodyContent`; fetch options such as `maxBytes` do not limit a supplied HTML string.

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

```ts
import { LinkpeekError, preview } from "linkpeek";

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. A caller abort rethrows the signal's reason as-is; every other failure is a `LinkpeekError`.

| Code | Meaning |
| --- | --- |
| `INVALID_URL` | URL could not be parsed or contains credentials |
| `UNSUPPORTED_PROTOCOL` | URL does not use HTTP(S) |
| `PRIVATE_NETWORK_BLOCKED` | Target matches a blocked hostname or literal address |
| `SENSITIVE_HEADER` | Custom headers include a prohibited credential-bearing name |
| `INVALID_OPTIONS` | An option fails validation |
| `TOO_MANY_REDIRECTS` | The redirect limit was reached |
| `TIMEOUT` | The call exceeded its timeout |
| `FETCH_FAILED` | The network request, body read or `resolveHost` lookup failed; the original error is `cause` |

## Presets

`presets.fast` is the default: `maxBytes: 30_000`, `includeBodyContent: false`, `followMetaRefresh: false`. `presets.quality` uses `maxBytes: 200_000` and enables both flags. Spread a preset to override individual options.

```ts
import { preview, presets } from "linkpeek";

await preview(url, { ...presets.quality, timeout: 5_000 });
```

## URL validation helpers

`validateUrl(url, allowPrivateIPs?)` returns `void` on success or throws `LinkpeekError`. `isPrivateHost(hostname)` returns a boolean for hostnames and literal IPs covered by the blocklist. It normalises the host the way `fetch()` does, so shorthand IPv4 such as `127.1`, `2130706433` or `0x7f000001` is caught, and it blocks internal names (`localhost`, `*.internal`, `*.local`, `*.localdomain`, `*.intranet`, `*.private`, `*.corp`, `*.home`, `*.lan`, `*.home.arpa`, single-label names such as `metadata`). Neither helper performs DNS resolution.

```ts
import { isPrivateHost, validateUrl } from "linkpeek";

isPrivateHost("127.0.0.1"); // true
isPrivateHost("2130706433"); // true (127.0.0.1)
isPrivateHost("metadata.google.internal"); // true
validateUrl("http://169.254.169.254/"); // throws PRIVATE_NETWORK_BLOCKED
```

## TypeScript and CommonJS

The root export includes `PreviewOptions`, `PreviewResult` and `LinkpeekErrorCode` types. Requires Node.js 22.12+; ESM and CommonJS each have their own declarations.

```ts
import type { PreviewOptions, PreviewResult } from "linkpeek";

// CommonJS:
const { preview } = require("linkpeek");
```

Related: [Quick start](https://linkpeek.js.org/quick-start/) · [Open Graph parser](https://linkpeek.js.org/guides/open-graph-parser/) · [Security model](https://linkpeek.js.org/security/) · [Troubleshooting](https://linkpeek.js.org/guides/troubleshooting/)
