Migration guide

A note on version numbers: the published npm history for this package goes 0.3.0 → 0.3.3 → 0.4.0 → 0.5.0 — 0.3.1 and 0.3.2 exist in CHANGELOG.mdand are real, documented changes, but aren't independently installable from the registry today. If you're upgrading from 0.3.0 directly to 0.5.0, you're picking up everything below from 0.3.1 through 0.5.0 in one jump — read all of it, not just the latest section.

0.5.0 → 0.8.2

Nothing to change in existing code across any of these — v0.6.0, v0.7.0, and v0.8.0 are each documented in their own CHANGELOG entries as additive minors, and v0.8.1/v0.8.2 are a docs-only release and a bug-fix patch respectively.

• v0.6.0 — ContentAnalyzer.audit(): a new six-category AI Readiness Engine alongside the unchanged analyze(). New CLI: audit's output format changed to category bars instead of the old dimension list, but the command itself and its flags are unchanged. See the AI Readiness Engine page.
• v0.7.0 — ai-visibility/engines, /prompts, /measure: three new subpaths, two new CLI commands (discover, measure). See engine adapters and brand measurement.
• v0.8.0 — ai-visibility/citations, /competitor: two new subpaths, three new CLI commands (citations, compare, report). See citation analysis and competitor gap analysis.
• v0.8.2 — bug fixes, no new features: CLI --version now reads from package.json at runtime; the four engine adapters now throw a descriptive EngineResponseError on a malformed API response instead of a confusing downstream error (see error handling); three internal helper exports were removed from ai-visibility/measure (mean, variance, confidenceInterval, analyzeEntities, EntityOutcome) — these were never meant to be public API and are unlikely to be imported by real code, but check if you were relying on them directly. The crawler registry gained two entries — see the crawler registry.

0.4.0 → 0.5.0

Nothing to change in existing code — every addition is backward compatible.

• New: ai-visibility audit/lint CLI commands and top-level robots/llms aliases for generate robots/generate llms — see the CLI reference.
• ContentAnalyzer.analyze() gained an optional second parameter, context?: { robotsTxt?: string; hasLlmsTxt?: boolean }, feeding a new 7th scoring dimension, crawlerAccessibility. Omitting it is fully backward compatible — existing analyze(html) call sites keep working, the dimension just has less information to work with. See the scoring methodology.
• RobotsGenerator.blockAll() — a third preset alongside allowAll()/blockTraining(), additive, nothing to migrate.
• ContentAnalyzer.SCORING_WEIGHTS is now a public static, and the same weights are published as dist/scoring-weights.json for non-JS consumers — same pattern as dist/crawlers.json.

0.3.x → 0.4.0

Crawler tokens changed — check for Claude-Web

The entire crawler registry was re-verified against vendor documentation instead of third-party SEO-blog lists. Claude-Web, Anthropic's pre-2024 token, was removed and replaced by the current Claude-User. If you match on crawler User-Agent strings anywhere in your own code — not just through this package's detector — search for Claude-Web and replace it:

// Before
if (userAgent.includes("Claude-Web")) { /* ... */ }

// After
if (userAgent.includes("Claude-User")) { /* ... */ }

Six crawlers were added: OAI-SearchBot, Claude-SearchBot, Perplexity-User, Amazonbot, Amzn-SearchBot, Amzn-User — see the crawler registry reference for the full, current list of 21.

detectAndOptimize() moved (0.3.1)

If you're on 0.3.0 and importing detectAndOptimize from anywhere other than a Next.js project, the import itself was crashing — see the troubleshooting entry for the fix (import from ai-visibility/detector instead of /next). Existing ai-visibility/next imports keep working unchanged — this is additive, not a breaking rename. See the write-up on how this bug happened for the full story.

onDetect is now safely async (0.4.0)

createNextMiddleware()'s onDetect may now return a Promise<void> and gets registered with event.waitUntil() automatically. No code change required — this only matters if you had an async onDetectthat seemed to work in testing but silently dropped writes in production; it's reliable now.

Subpath type exports completed (0.4.0)

ai-visibility/schema, /generators, and /express now re-export their parameter types (ProductSchemaData, RobotsConfig, AIMiddlewareConfig, etc.), not just their classes/functions. If you were importing a type from the root barrel purely to pair with a subpath import, you can now import both from the same subpath — not required, but simplifies the import list.

0.2.x → 0.3.x

robots.txt default disallow list is now empty

The change most likely to affect you. RobotsGenerator's default disallow list used to include /_next, /admin, /api, /private, and /static — meaning every site using the defaults, Next.js apps especially, was shipping a robots.txtthat told AI crawlers not to fetch the site's own JS/CSS chunks. The default is now []. If you relied on the old default, pass your own disallow list explicitly:

new RobotsGenerator({
  allowAI: ["GPTBot", "ClaudeBot", "PerplexityBot"],
  disallow: ["/admin", "/api"], // now explicit, not implied
})

SchemaBuilder.fromHTML() is now async

fromHTML() lazily import()s cheerio on first call instead of requiring it statically, so it now returns Promise<SchemaObject> instead of SchemaObject directly. Add awaitif you weren't already using it:

// Before (0.2.x)
const schema = SchemaBuilder.fromHTML(html);

// After (0.3.0+)
const schema = await SchemaBuilder.fromHTML(html);

Subpath exports added (non-breaking)

ai-visibility/detector, /schema, /generators, /express, and /next were added alongside the root barrel, which is unchanged — every 0.2.x import path still works with no code changes. Switching to subpath imports is worth doing for edge runtimes (Cloudflare Workers, Next.js Edge Middleware) since /detector, /schema, and /generatorshave zero runtime dependencies; it's optional everywhere else.

Full entry-by-entry detail for every release is in the package's CHANGELOG.md. See recipes for current working examples and troubleshooting for gotchas specific to individual frameworks.