Core API

Fetch a page or work directly with HTML.

resolve(input, options)#

import { resolve } from '@linkoi/core'

const metadata = await resolve('https://example.com', {
  maxBytes: 2_097_152,
  timeoutMs: 5000,
  selfHosts: ['metadata.example.com'],
})

Accepts a URL string or a URL object. Returns Promise<Metadata>. Redirect targets are checked before fetching.

Option	Default	Meaning
maxBytes	2,097,152	Positive integer HTML download cap in bytes.
timeoutMs	5,000	Positive integer timeout per upstream HTML fetch, in milliseconds. Not a total extraction deadline.
selfHosts	[]	Hostnames to reject, for example your own API hostname.
fallback	true	Deprecated and ignored since 0.1.1. Extraction always uses Linkoi’s own parser.
youtubeApiKey	unset	Optional YouTube Data API key. Keep it on the server.

fromHtml(html, url, options)#

const metadata = await fromHtml(html, 'https://example.com', {
  fallback: false,
})

The URL must pass the URL guard and provides the base for resolving relative metadata URLs. The only option is fallback. Disabling it keeps parsing offline.

Errors and fallbacks#

Unsafe targets throw UnsafeUrlError. Invalid limits throw RangeError. HTML fetching can throw FetchHtmlError. A failed YouTube API request falls back to fetching HTML.

import { resolve, UnsafeUrlError, FetchHtmlError } from '@linkoi/core'

try {
  const page = await resolve('https://example.com')
  console.log(page.title)
} catch (error) {
  if (error instanceof UnsafeUrlError) {
    console.error('URL rejected')
  } else if (error instanceof FetchHtmlError) {
    console.error(error.status, error.message)
  } else {
    throw error
  }
}

YouTube metadata#

Provide youtubeApiKey to use the YouTube Data API for recognised video URLs. This supplies video metadata, not a download URL or playable embed. The API path returns logo: null and lang: null.