API docs parity: Node.js / TypeScript

[edburns]

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:

Service	How it works
typedoc.org	Generator, not host
tsdocs.dev	Closest to javadoc.io — auto-generates docs from any npm package's types on demand
GitHub Pages / custom	Many projects self-host (e.g. docs/ folder or CI-published site)

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.

[github-actions]

Documentation Gap Analysis

Thanks for filing this as part of the API docs parity epic (#1653)!

What's Missing

The Node.js/TypeScript SDK (nodejs/) currently lacks:

1. TSDoc/TypeDoc inline comments on public APIs — the @param, @returns, @example, and @remarks annotations that TypeDoc needs to generate HTML reference docs
2. TypeDoc configuration (typedoc.json or equivalent in package.json) to drive doc generation
3. A hosted API reference — either self-hosted via GitHub Pages or a reliable third-party service

Affected Files / Sections

Area	What's needed
nodejs/src/client.ts	TSDoc comments on all exported classes, methods, and types
nodejs/src/ (all public exports)	Full TSDoc annotation pass
nodejs/package.json	typedoc devDependency + docs / generate:docs script
nodejs/typedoc.json	TypeDoc configuration (entry points, output dir, theme)
.github/workflows/	CI step to build and publish docs to GitHub Pages

Recommended Path Forward

As the issue notes, tsdocs.dev is unreliable (currently returning 502). The most robust solution is self-hosting TypeDoc output via GitHub Pages, analogous to how Java Javadoc jars are published to Maven Central. This would:

• Run npx typedoc in CI on every release/main push
• Publish the output to the gh-pages branch (or docs/ folder)
• Provide a stable, first-party URL for the SDK's API reference

This brings the Node.js SDK documentation story in line with the Java SDK's Javadoc coverage and ensures AI coding tools and IDE consumers have reliable, discoverable API reference docs.

Generated by Documentation Handler for issue #1654 · sonnet46 439.7K · ◷

[edburns]

I wasn't able to find any reports of tsdocs.dev being permanently shut down. Based on what I can see:

• The site's landing page still appears in search indexes, and it's maintained by a single developer, Shubham Kanodia (pastelsky), who funds about $90/month in hosting costs through GitHub Sponsors.
• The GitHub repo's open issues are all from December 2023 and none mention a permanent shutdown.

That said, solo-maintained community projects like this are prone to intermittent outages — and pastelsky's other project, bundlephobia, has had its share of downtime incidents over the years. If you're hitting errors right now, it's most likely a temporary issue rather than a permanent closure.

Are you getting a specific error when you try to load it (502, timeout, etc.)?