API docs parity: Node.js / TypeScript

Inizia leggendo l’epic principale #1653 e la discussione della issue su TSDoc, TypeDoc, tsdocs.dev, GitHub Pages e i file .d.ts pubblicati. La issue non indica file del repository, test o un punto di ingresso per l’implementazione; il lavoro è completo solo quando l’approccio alla documentazione dell’API del progetto e il deliverable sono chiaramente definiti.

Node.js / TypeScript API Docs

Parent epic: #1653

Doc format: TSDoc / TypeDoc comments (/** ... */ with @param, @returns, etc.). TypeDoc generates HTML from these.

Culture: Weaker than Java. npm does not require a docs artifact to publish. Many packages ship only a README + inline types (the .d.ts files are the docs for many TS consumers via IDE hover). Publishing standalone API docs is opt-in.

Hosting analogues:

Key difference from Java: No registry-mandated doc artifact. tsdocs.dev synthesizes docs from published .d.ts type declarations rather than a pre-built doc jar.

Additional research: tsdocs.dev fragility

As of 2026-06-13, tsdocs.dev returns 502 Bad Gateway across the board — both the homepage and package-specific URLs (e.g. https://tsdocs.dev/docs/@github/copilot-sdk). The service is completely down, not just a homepage glitch.

This reinforces the fragility of the TypeScript ecosystem's doc hosting: tsdocs.dev is a volunteer-run third-party project, not backed by npm or Microsoft. It has had reliability issues before. There is no npm Inc. or TypeScript team commitment keeping it running — unlike docs.rs (Rust team) or pkg.go.dev (Go team), which are first-party infrastructure with SLAs.

In practice, for the @github/copilot-sdk npm package, the realistic API-docs options are:

1. Self-host TypeDoc output (e.g., GitHub Pages from CI) — most reliable
2. Rely on .d.ts hover docs in IDEs — what most TS consumers actually use day-to-day
3. tsdocs.dev — when it's up, which apparently is not guaranteed

As a Java Champion perspective: Java's Maven Central mandate for javadoc jars means API docs are a first-class, always-available artifact. This is particularly important in an era where AI is writing code — maintainability depends on discoverable, reliably-hosted documentation. The TypeScript ecosystem lacks this guarantee, making self-hosted docs a necessity rather than optional.