feat: the transport takes a signal, a fetch of your own, and stops taking a refused credential for a result

Three requests older than 6.0, all of them the same shape: the client had no seam. `fetch` was reached as a global, a
request could not be cancelled, and a response's headers were read for one thing and thrown away. None of it was
visible from outside.

Every call takes an `AbortSignal` as an optional last argument — an operation with no parameters takes it in their
place — and the signal reaches `fetch` as well as cutting short a retry back-off that until now had no bound on total
wall time. The abort reason is rethrown untouched rather than wrapped, so `error.name === 'AbortError'` and
`error === signal.reason` both hold, and a `TimeoutError` from `AbortSignal.timeout()` stays one. Fixes #406.

The `fetch` the client calls is yours to replace. It receives the URL and the `RequestInit` the client built, headers
included, and returns a `Response` — logging, tracing, a corporate proxy, fixture recording. The OAuth 2.0 token and
cloud-id calls go through it too, so a proxy covers the whole flow rather than working until the first refresh. Its
type is `(url: string, init: RequestInit) => Promise<Response>` rather than `typeof globalThis.fetch`, so undici's
fetch fits without a cast. Fixes #404.

An expired API token is an error rather than an empty result, and this changes behaviour. Around a quarter of Jira's
operations can be reached anonymously, and there a dead token does not fail the request: Jira answers as the anonymous
user and reports the refusal only in `X-Seraph-LoginReason`. Measured against a live site, `GET
/rest/api/3/project/search` with a dead token answers 200 and `{"total":0,"isLast":true,"values":[]}`. The client reads
that header now and throws `AuthError` whatever the status, recording the status that actually arrived. Fixes #418.

Two smaller ones ride along. A header set to `undefined` is left out rather than sent, and falls through to the
client-wide value instead of erasing it. And two authentication strategies for a self-hosted instance arrive with the
core rather than with the surface they serve — `src/core` is generated whole and `createClient` branches on the
strategy, so separating them would mean hand-writing a core the generator does not produce.

Riding along with the regeneration is specification drift, and one part of it breaks callers. Four operations declared
their body as `Record<string, any>` — the generator's fallback for a request body that is not an object — and now
declare what the endpoint reads: `addWatcher` and `setPreference` take a `string`, `updateEntityPropertiesValue` an
`EntityPropertyDetails[]`, and Service Management's `attachTemporaryFile` a `MultipartFile[]`. None of the four could
be called correctly through the old declaration; the live suite carried two helpers whose only job was to cast a
string past it, and both are deleted here. That cast is the break.

`updateEntityPropertiesValue` and `attachTemporaryFile` had no coverage at all, and a live run cannot give them much:
one is addressed with a Connect app's JWT, the other needs an agent licence this tenant does not hold. Both gain a
live test pinning the typed refusal, and all four gain unit coverage asserting what leaves the client — the
neighbouring `updateIssueFields` wraps its body under a key, so a bare array is a distinction worth holding.

Four generated doc comments are restored rather than regressed. The generator's HTML stripper could not tell a tag
from a placeholder — `<project ID or key>` reads as an element named `project` — and turned a format string into "The
format is `,,`" while emptying the API token out of three curl examples. Fixed upstream in apis-code-gen; regenerating
with the fix changes exactly these four files, all of them restorations to what master already says.

Author: MrRefactoring

CHANGELOG.md

@@ -2,6 +2,49 @@
 
 ## 6.3.0
 
+### The transport
+
+Three long-standing requests, all of them the same shape: the client had no seam. `fetch` was reached as a global, a request could not be cancelled, and a response's headers were read for one thing and thrown away. None of that was visible from outside, and all three issues predate 6.0.
+
+* **Every call takes an `AbortSignal`.** Each method gains an optional argument after its parameters — an operation that takes no parameters takes it in their place — and the signal reaches `fetch`. It also cuts short a retry back-off, which until now had no upper bound on total wall time. Fixes [#406](https://github.com/MrRefactoring/jira.js/issues/406).
+
+  ```ts
+  await jira.issues.getIssue({ issueIdOrKey: 'PROJ-1' }, { signal: AbortSignal.timeout(5_000) });
+  await jira.announcementBanner.getBanner({ signal });
+  ```
+
+  The abort reason is rethrown untouched rather than wrapped in a `NetworkError`: `error.name === 'AbortError'` is what the ecosystem branches on, a `TimeoutError` from `AbortSignal.timeout()` stays a `TimeoutError`, and a reason of your own comes back as the object you passed. Aborting one call never disturbs an OAuth 2.0 refresh in flight — that refresh is single-flighted and shared by every concurrent request on the client.
+
+  Nothing that compiled before stops compiling: the argument is optional and it is last.
+
+* **The `fetch` the client calls is yours to replace.** `fetch` in the client configuration receives the URL and the `RequestInit` the client built, headers included, and returns a `Response`. That covers logging, tracing, a corporate proxy and fixture recording — what `middlewares` was used for before 6.0 removed axios, and what has had no replacement since. Fixes [#404](https://github.com/MrRefactoring/jira.js/issues/404).
+
+  ```ts
+  import { fetch as undiciFetch, ProxyAgent } from 'undici';
+
+  const dispatcher = new ProxyAgent(process.env.HTTPS_PROXY!);
+
+  const jira = createCloudClient({ host, auth, fetch: (url, init) => undiciFetch(url, { ...init, dispatcher }) });
+  ```
+
+  The OAuth 2.0 token and cloud-id calls go through it too, so a proxy covers the whole flow rather than working until the first refresh an hour later. The flip side is worth stating plainly: a wrapper that logs request bodies will see `client_secret` and `refresh_token` on the token call.
+
+  Its type is `(url: string, init: RequestInit) => Promise<Response>` rather than `typeof globalThis.fetch`, so undici's `fetch` — whose `RequestInit` carries `dispatcher` and lacks `duplex` — fits without a cast.
+
+* **An expired API token is an error rather than an empty result. This changes behaviour.** Around a quarter of Jira's operations can be reached anonymously, and on those a dead or revoked token does not fail the request: Jira serves it as the anonymous user, returns a well-formed response containing whatever an anonymous visitor may see, and reports the refusal only in the `X-Seraph-LoginReason` header. Measured against a live site, `GET /rest/api/3/project/search` with a dead token answers `200` and `{"total":0,"isLast":true,"values":[]}`. Fixes [#418](https://github.com/MrRefactoring/jira.js/issues/418).
+
+  The client now reads that header and throws `AuthError` whenever it says the credentials were refused — whatever the status, because the header rides on `200`, `400` and `401` alike and the diagnosis is the same in each case. `error.status` records the status that actually arrived rather than a `401` that never happened; that is what the new `AuthErrorOptions.status` is for.
+
+  Two values count: `AUTHENTICATED_FAILED` and `AUTHENTICATION_DENIED`, both meaning the credentials were presented and refused. `AUTHORISATION_FAILED` does not — it means the user is who they claim and merely lacks a permission, which the status already carries and `ForbiddenError` already describes. A genuine permission denial was measured to send no such header at all. The check runs only when the client was given credentials, so a deliberately anonymous client is untouched, and `getAuthOn401` is offered the same single retry a plain `401` earns it.
+
+  If your code treated an empty result on a dead token as normal, it will now throw. It was reading anonymous data and calling it yours.
+
+* **A header set to `undefined` is left out rather than sent.** `SendRequestOptions.headers` accepts `string | undefined`, and the transport strips the absent entries before the request is built — the same treatment `searchParams` and a JSON body have always had. An omitted header does not shadow one set in the client configuration either, so a per-request `undefined` falls through to the client-wide value instead of erasing it.
+
+* **Two authentication strategies for a self-hosted instance.** `basic` accepts a local `username` and `password` beside the Cloud pair of `email` and `apiToken`, and `oauth2Server` is OAuth 2.0 against an instance's own authorization server — `generateServerAuthorizationUrl`, `exchangeServerAuthorizationCode`, `refreshServerOAuth2Token` and `createServerOAuth2Manager`, all of them addressed to the site's own domain with no cloud id and no gateway involved.
+
+  They arrive with the transport rather than with the surface they are for, because `src/core` is generated whole and `createClient` branches on the strategy — separating them would mean hand-writing a core the generator does not produce. No surface in this release answers to them yet.
+
 ### Features
 
 * **Request parameter types are importable again.** `CreateIssue`, `GetIssue` and the twelve hundred others appeared in no published declaration file: a surface entry point re-exports `api`, `models` and its factory, and never `parameters`. They now have a subpath of their own:
@@ -19,6 +62,28 @@
 
   `validation.notExported` makes the reference a check on the public surface besides: a type built out of something the package does not export fails the documentation build. Five symbols were in exactly that position and are exported now — `authBasicSchema`, `authBearerSchema`, `CommonClientConfig`, `ParsedClientConfig` and `ErrorKind`.
 
+### Types
+
+* **Four request bodies are typed as the shape the endpoint reads, where they were `Record<string, any>`.** Each was generated from a request body the specification declares as something other than an object, which the generator had no reading for and degraded to an object of arbitrary keys. None of the four could be called correctly through its own declaration.
+
+  | Operation | Body was | Body is |
+  | --- | --- | --- |
+  | `issueWatchers.addWatcher` | `Record<string, any>` | `string` |
+  | `myself.setPreference` | `Record<string, any>` | `string` |
+  | `appMigration.updateEntityPropertiesValue` | `Record<string, any>` | `EntityPropertyDetails[]` |
+  | `servicedesk.attachTemporaryFile` (Service Desk) | `Record<string, any>` | `MultipartFile[]` |
+
+  ```ts
+  await jira.issueWatchers.addWatcher({ issueIdOrKey: 'PROJ-1', body: '5b10ac8d82e05b22cc7d4ef5' });
+  await jira.myself.setPreference({ key: 'user.notifications.mimetype', body: 'text' });
+  ```
+
+  The two that take a lone string were the sharper break. `addWatcher` wants an account id and `setPreference` a preference value, each sent as a JSON string — and an object was never a value either would accept, so the only way to call them was to cast a string past the declaration. The live suite did exactly that, with a helper whose whole purpose was to launder a `string` into a `Record<string, unknown>`. Those casts are what stops compiling now, and deleting each one is the fix.
+
+  The two that take an array break more quietly: an array satisfies `Record<string, any>`, so a caller already passing the right thing is untouched and needs no change. A caller passing a single object, which the old declaration invited and the endpoint refused, is the one the compiler now stops.
+
+  `tests/unit/nonObjectBodies.test.ts` pins all four against the wire. It is unit rather than live because two of them cannot be reached: `updateEntityPropertiesValue` is addressed with a Connect app's JWT, and `attachTemporaryFile` needs an agent licence — so what a live run can show is the typed refusal, and what it cannot show is that the body left the client as a bare string or a top-level array rather than wrapped in a key.
+
 ### General
 
 * **The minimum TypeScript is declared, and measured.** `>=5.7`, as an optional peer dependency, in the README and here. It was never written down before, and the honest number is higher than anyone would have guessed: the declarations name `ArrayBufferView`, which became generic in 5.7, so a 5.6 compiler reads them as an error unless `skipLibCheck` hides them from it. `check:consumers` now installs exactly that version and type-checks the packed tarball with `skipLibCheck` off, so the floor moves only when someone means to move it.

eslint.config.ts

@@ -20,6 +20,7 @@ export default defineConfig([
     },
     rules: {
       'no-empty': ['error', { allowEmptyCatch: true }],
+      'no-nested-ternary': 'error',
       '@stylistic/comma-dangle': ['error', 'always-multiline'],
       '@stylistic/indent': ['error', 2],
       '@stylistic/lines-between-class-members': [

src/agile/api/backlog.ts

@@ -1,18 +1,23 @@
 import type { MoveIssuesToBacklog } from '../parameters/moveIssuesToBacklog';
 import type { MoveIssuesToBacklogForBoard } from '../parameters/moveIssuesToBacklogForBoard';
-import type { Client, SendRequestOptions } from '#/core';
+import type { Client, RequestOptions, SendRequestOptions } from '#/core';
 
 /**
  * Move issues to the backlog. This operation is equivalent to remove future and active sprints from a given set of
  * issues. At most 50 issues may be moved at once.
  */
-export async function moveIssuesToBacklog(client: Client, parameters: MoveIssuesToBacklog): Promise<void> {
+export async function moveIssuesToBacklog(
+  client: Client,
+  parameters: MoveIssuesToBacklog,
+  options?: RequestOptions,
+): Promise<void> {
   const config: SendRequestOptions<void> = {
     url: '/rest/agile/1.0/backlog/issue',
     method: 'POST',
     body: {
       issues: parameters.issues,
     },
+    signal: options?.signal,
   };
 
   return await client.sendRequest(config);
@@ -26,6 +31,7 @@ export async function moveIssuesToBacklog(client: Client, parameters: MoveIssues
 export async function moveIssuesToBacklogForBoard(
   client: Client,
   parameters: MoveIssuesToBacklogForBoard,
+  options?: RequestOptions,
 ): Promise<void> {
   const config: SendRequestOptions<void> = {
     url: `/rest/agile/1.0/backlog/${parameters.boardId}/issue`,
@@ -36,6 +42,7 @@ export async function moveIssuesToBacklogForBoard(
       rankBeforeIssue: parameters.rankBeforeIssue,
       rankCustomFieldId: parameters.rankCustomFieldId,
     },
+    signal: options?.signal,
   };
 
   return await client.sendRequest(config);