API reference

Import the Node.js HTTP checker from meodp/check. ESM, CommonJS, and TypeScript declarations are provided. This entry does not require a browser.

Check URLs

import { checkLinks, checkSitemap, readSitemapUrls } from 'meodp/check'

const links = await checkLinks(['https://example.com/'], { observer: 'ci' })
const pages = await checkSitemap('https://example.com/', { discover: true })
const urls = await readSitemapUrls('https://example.com/sitemap.xml')

Function	Input	Returns
`checkLinks(input, options?)`	Readonly array of strings or `LinkTarget` objects; `CheckOptions`	`Promise<CheckReport>`
`checkSitemap(source, options?)`	Sitemap/site URL; `SitemapOptions`	`Promise<CheckReport>`
`readSitemapUrls(source, options?)`	Sitemap/site URL; `SitemapOptions`	`Promise<string[]>` without probing pages

checkLinks() validates the full input before sending requests. Results retain the normalized input order. Request failures become observations; invalid input/options or errors from your onResult callback reject the run. readSitemapUrls() makes discovery requests only; history and result callbacks concern the page-checking phase.

Check options

Option	Default	Range or behavior
`concurrency`	`5`	Integer 1–100
`timeoutMs`	`10000`	Integer 1–300000, per request including the body
`retries`	`1`	Integer 0–5, for transport errors and 5xx
`maxRedirects`	`5`	Integer 0–20 per attempt
`observer`	OS hostname	Nonempty environment identifier
`previousReport`	None	Prior `CheckReport` with the same observer
`onResult`	None	Sync or async callback after each URL completes; completion order can differ from input order

SitemapOptions extends these with discover, maxUrls, maxSitemaps, and maxSitemapBytes. See the sitemap guide for defaults, bounds, and discovery error handling.

Report helpers

import { checkLinks, formatReport, writeReports, writeReportSite } from 'meodp/check'

const report = await checkLinks(['https://example.com/'])
const markdown = formatReport(report)
await writeReports(report, 'reports/links')
await writeReportSite(report, 'reports/site')
await writeReportSite(undefined, 'reports/viewer', { dataUrl: './latest.json' })

Function	Result
`formatReport(report, format?)`	String; format is `markdown` (default), `json`, or `html`
`writeReports(report, directory)`	Promise of `{ json, markdown, html }` file paths
`writeReportSite(reportOrUndefined, directory, options?)`	Promise of `{ index, json? }`; `ReportSiteOptions.dataUrl` selects hosted JSON
`readReport(path)`	Promise of validated `CheckReport`, or `undefined` for a missing file
`saveReport(report, path)`	Promise completing after atomic history replacement
`parseReport(data)`	Validate unknown parsed JSON and return `CheckReport`; invalid data throws

parseReport() verifies that the supplied summary matches the validated results. For imported JSON, parse it with JSON.parse() before calling this helper. See reports and history for interpretation and viewer behavior.

Configuration and notifications

meodp/config exports defineConfig and configuration types; meodp/notify exports the pure createNotification function. Use meodp/notify/feishu for cards and delivery, or meodp/notify/email for mail. waitForReport(report, { url, attempts?, delayMs? }) from meodp/check verifies published JSON and viewer availability. See configuration and notifications for options, policies, and examples.

writeReporters(report, reporter, options?) selects JSON, Markdown, or HTML files/sites through names and tuples, returning { reporter, files }[]. ReporterConfig and related types are exported from meodp/check. See reporter options.

Exported data types

The following declarations are included directly from the package source so their fields stay aligned with the implementation.

Link targets, observations, reports, and check options

export interface LinkTarget {
  url: string
  name?: string
}

export type Availability = 'reachable' | 'restricted' | 'unavailable'
export type FailureReason = 'http' | 'dns' | 'tls' | 'timeout' | 'network' | 'redirect'

export interface LinkObservation extends LinkTarget {
  status: Availability
  checkedAt: string
  durationMs: number
  attempts: number
  finalUrl: string
  httpStatus?: number
  redirects: { url: string, status: number, location: string }[]
  reason?: FailureReason
  detail?: string
  consecutiveFailures: number
  firstFailureAt?: string
  lastSuccessAt?: string
  changed: boolean
  recovered: boolean
}

export interface CheckReport {
  schemaVersion: 1
  observer: string
  startedAt: string
  completedAt: string
  summary: Record<Availability, number> & { total: number, redirected: number, recovered: number }
  results: LinkObservation[]
}

export interface CheckOptions {
  /** Maximum simultaneous site checks. Default: 5. */
  concurrency?: number
  /** Timeout for each HTTP request, including its body. Default: 10000 ms. */
  timeoutMs?: number
  /** Retries for transport errors and 5xx responses. Default: 1; 429 is not retried. */
  retries?: number
  /** Maximum followed redirects per attempt. Default: 5. */
  maxRedirects?: number
  /** Identifies the network/environment. Must match previousReport.observer. */
  observer?: string
  previousReport?: CheckReport
  onResult?: (result: LinkObservation) => void | Promise<void>
}

export interface SitemapOptions extends CheckOptions {
  /** Treat the input as a site URL: read robots.txt, falling back to /sitemap.xml. */
  discover?: boolean
  /** Reject before page checks if discovery exceeds this many unique pages. Default: 10000. */
  maxUrls?: number
  /** Maximum number of unique sitemap documents to read. Default: 100. */
  maxSitemaps?: number
  /** Maximum downloaded and decompressed size per discovery document. Default: 10 MiB. */
  maxSitemapBytes?: number
}

The package root entry meodp retains the experimental browser APIs. New HTTP integrations should use meodp/check; the older checkSiteMap() is a separate experimental API.

API reference ​

Check URLs ​

Check options ​

Report helpers ​

Configuration and notifications ​