[tomasr78]

Summary

• ConvertApi.auth() also takes the host as a URL. A leading https:// or http:// and trailing slashes are removed, so
  ConvertApi.auth('api-token', 'https://eu-v2.convertapi.com/') sends requests to
  https://eu-v2.convertapi.com/convert/.... The bare host goes into this.host, so createParams() and the upload
  URLs in src/file-param.ts use it too. Requests always use https.
• The auth() JSDoc describes the API token and the host name. It described the retired secret or apiKey and
  token object.
• dist/*.d.ts keep their JSDoc, so editors show it. Until now the build removed it (see below).
• Result.duration's JSDoc says it returns the conversion cost (ConversionCost), not a duration in seconds. That
  comment now ships too (second commit).
• A CHANGELOG entry under Unreleased. README.md is unchanged: README: pass a bare host name to ConvertApi.auth #34
  fixes its example.

Why

From 2023-07-04 until #34, the README's "Alternative domain"
example passed 'https://eu-v2.convertapi.com/'. The library builds https://${host}/..., so it requested
https://https://eu-v2.convertapi.com//convert/..., and fetch failed (ENOTFOUND, host https) before any request
reached ConvertAPI. https://www.convertapi.com/llms.txt still shows that form, and code copied or generated from it
fails the same way. With this change, that code works.

JSDoc in the type declarations

tsconfig.json has had removeComments: true since 2020, and TypeScript applies it to the declarations too. No
published version has had any JSDoc in dist/*.d.ts (checked 1.1.9 and 1.1.11 on unpkg), so fixing the auth() text
alone would change nothing users see. npm run build now runs tsc, then tsc --emitDeclarationOnly --removeComments false:

• The JavaScript in dist/ has no comments, as before. Only dist/convertapi.js changes, for the host fix; the other
  six files are byte-identical with a build of main.
• The declarations have the same public types as before (compared with the comments removed). They only gain the JSDoc:
  dist/*.d.ts grow from 3,856 to 7,600 bytes in all.
• build.yml and publish.yml both build with npm run build, so releases get it too.
• Turning comments on everywhere (removeComments: false) would have grown the JavaScript from 7,962 to 11,400 bytes.

I read the other comments that now ship. The Params.add link https://www.convertapi.com/conversions redirects to
https://www.convertapi.com/api (200). Result.duration said "conversion duration seconds", but it returns
ConversionCost, which the API spec describes as "This amount will be deducted from your balance after the
conversion." The second commit fixes that comment.

This part is separate from the host fix and can be dropped. It consists of the package.json and tsconfig.json lines,
the last test, the second CHANGELOG bullet and the second commit.

Tests

• npm ci && npm test on Node 24.20.0: 12 pass. The 3 live tests are skipped without a token. Three of the unit tests
  are new:

  • the stripped forms: https://, HTTPS://, http://, one or two trailing slashes, a bare host,
    http://localhost:8080/ (the port stays), and new ConvertApi();
  • with the host 'https://example.test/', the file upload, the URL upload and the conversion all go to
    https://example.test/...;
  • dist/convertapi.d.ts contains the auth() JSDoc.

  Against a build of main, those three fail and the other nine pass.

• node --test test/live.test.js with a staging token passes 3 of 3 with CONVERT_API_HOST=stag-v2.convertapi.com,
  and 3 of 3 with CONVERT_API_HOST=https://stag-v2.convertapi.com/. With a build of main, the URL form fails with
  fetch failed (ENOTFOUND https).

Not in this PR

• No release. Publishing it is a separate GitHub Release (see RELEASING.md).
• https://www.convertapi.com/llms.txt line 534 still shows the old form and needs its own fix on the site. Once a
  release with this change is out, that line works with it.
• src/worker.ts uploads to https://v2.convertapi.com whatever host is set. It is not exported from the package
  entry, so it is left alone.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

No active review issues are recorded for the host normalization and declaration documentation changes.

No open issues 🎉

What changed in this PR

This PR lets the JavaScript client accept URL-form API hosts and preserves JSDoc in published type declarations so editors can display it.

Changes:

• Normalize hosts by removing HTTP(S) prefixes and trailing slashes while keeping requests on HTTPS.
• Update authentication documentation and emit declarations with comments without changing JavaScript comment removal.
• Add regression tests for host normalization, upload and conversion URLs, and declaration JSDoc.

File	Description
tsconfig.json	Explain the separate comment settings for JavaScript and declarations.
test/​convertapi.test.js	Test URL-form hosts, request destinations, and preserved JSDoc.
src/​convertapi.ts	Normalize hosts in the constructor and clarify authentication documentation.
package.json	Add a declaration-only build pass that preserves comments.
CHANGELOG.md	Document host normalization and declaration documentation improvements.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues are reported for the host-normalization and declaration-documentation changes.

No open issues 🎉

_{Review effort: Balanced}