aiseo-auditv2.0.1

Documentation

aiseo-audit TypeScript API: analyzer, results, and renderers

In brief. This is the aiseo-audit TypeScript application programming interface for page and sitemap analysis inside Node.js code. It exposes configuration loaders, analyzers, report renderers, comparison helpers, stage results, and typed errors.

Maintained by Jeff Patterson and Agency Enterprise · Updated August 30, 2026

How the aiseo-audit TypeScript API works: overview

The API is the programmatic interface for running the same analyzer used by the command-line tool.

Load a configuration, pass a URL to an analyzer, inspect the typed result, and send that result to a terminal, JSON, Markdown, or HTML renderer.

The API and command line share one analyzer because separate scoring paths would produce conflicting results. This means an application automates audits without changing their interpretation.

aiseo-audit TypeScript API: analyzer, results, and renderers terms

TypeScript API

A TypeScript API refers to the exported functions and types used inside Node.js code.

Analyzer

An analyzer refers to the function that fetches inputs and returns a scored result.

Renderer

A renderer is defined as a function that turns a result into terminal, JSON, Markdown, or HTML output.

Audit result

An audit result means that one typed object contains the score, stages, factors, evidence, and raw measurements.

Fetch error

A fetch error refers to a typed network failure that callers handle by code.

Sitemap result

A sitemap result is a type of host-level report with page results and aggregate values.

Install

Use the API when code needs the audit result. One call takes a URL and gives back one object. The app saves that object, shows a report, or compares it with an old run. Keep the query set and tool version with each saved result.

Start with one URL and one short query set. Load the file, run the check, and keep the returned object. Save it when the run needs a base. Pass it to one report format at a time. On an error, log the code and URL before a retry.

npm install aiseo-audit

Analyze and render a page

Pass the URL and optional signalsBase, timeout, or userAgent values to the analyzer. Put query, domain, engine, and scoring settings in the configuration object.

import { analyzeUrl, loadConfig, renderReport } from "aiseo-audit";

const config = await loadConfig();
const result = await analyzeUrl({ url: "https://example.com" }, config);
const html = renderReport(result, { format: "html" });

console.log(result.overallScore, result.grade);
console.log(result.stages?.technicalEligibility.status);

Core runtime exports

  • analyzeUrl and analyzeSitemap
  • renderReport and renderSitemapReport
  • loadConfig and loadConfigWithPath
  • computeDiff, orchestrateDiff, and renderDiffReport
  • renderHistoryTimeline and loadBaselineResult
  • computeStages and makeDiagnostic

Error handling

Use FetchError and FetchErrorCode to identify network failures. Configuration and schema failures use regular errors. Handle changing responses because deterministic scores require identical fetched HTML.

How to use this reference

  1. Install aiseo-audit in the Node.js project.
  2. Load or construct the audit configuration.
  3. Call the page or sitemap analyzer.
  4. Check typed errors before reading the result.
  5. Render, store, or compare the returned report.

Key takeaways

  • The analyzer is shared with the command-line interface.
  • The result is a typed record of scores and evidence.
  • The output is separate from analysis so one result supports four report formats.
  • The error is the supported way to identify network failures.
  • The config is the source of query, profile, engine, and weight settings.

Bottom line: Use the TypeScript API when another Node.js process must own the audit result.

Official sources and verification

According to the npm package page, aiseo-audit publishes its current version and installation command [1]. According to the GitHub repository, the source code and project documentation are public [2].

According to the evidence map, every scored factor records an evidence tier and pipeline stage [3]. According to the release history, major versions document scoring changes that require new baselines [4]. According to the project license, aiseo-audit uses the MIT license[5].

  1. aiseo-audit on npm: package, version, and installation details.
  2. agencyenterprise/aiseo-audit: source code and documentation.
  3. aiseo-audit evidence map: factor tiers, stages, and research sources.
  4. aiseo-audit releases: version history and migration notes.
  5. MIT license: project license text.