fix(core): axiosAdapter(axios) typechecks against real axios (#708)

CHANGELOG.md

@@ -571,6 +571,11 @@ npm release are grouped under the in-development version that introduced them.
 
 ### Fixed
 
+- **`axiosAdapter(axios)` — the adapter's own documented snippet — now typechecks against real
+  axios.** ([#708](https://github.com/rejifald/StitchAPI/issues/708)) `AxiosLikeConfig.responseType`
+  was `string`, which axios types as its narrower `ResponseType` union, so passing `axios` (or
+  `axios.create()`) failed with `TS2345` under `exactOptionalPropertyTypes`. The type-level test
+  missed it by casting a client through `AxiosLike`; it now asserts against real `axios` types.
 - **A truncated LLM completion is no longer a silent success.** ([#699](https://github.com/rejifald/StitchAPI/issues/699))
   `finishReason` was lifted by both provider mappings and read by nothing, so a completion cut short
   at the token cap resolved `ok: true` with `findings: []`. It now sets a normalised `truncated` on

packages/core/package.json

@@ -328,6 +328,7 @@
         "@types/node": "^22.10.0",
         "@vitest/coverage-v8": "^4.1.10",
         "@vitest/eslint-plugin": "^1.6.24",
+        "axios": "^1.19.0",
         "esbuild": "^0.28.1",
         "eslint": "^9.39.4",
         "eslint-config-prettier": "^10.1.8",

packages/core/src/axios-adapter.ts

@@ -34,7 +34,11 @@ export interface AxiosLikeConfig {
     method: string;
     headers?: Record<string, string>;
     data?: unknown;
-    responseType?: string;
+    // Narrower than `string` on purpose: axios types this as its own `ResponseType` union, and a
+    // plain `string` makes `AxiosLikeConfig` unassignable to `AxiosRequestConfig` — which made
+    // `axiosAdapter(axios)` itself fail to typecheck against real axios (#708). The adapter only
+    // ever sends 'arraybuffer' (below), so narrowing to a subset of axios's union costs nothing.
+    responseType?: 'arraybuffer' | 'json' | 'text';
     signal?: AbortSignal;
     validateStatus?: ((status: number) => boolean) | null;
     onUploadProgress?: (e: AxiosLikeProgressEvent) => void;

packages/core/test-d/adapter-capabilities.test-d.ts

@@ -12,6 +12,7 @@ import type {
     AxiosLike,
 } from '../src';
 
+import axios from 'axios';
 import { expectAssignable, expectError, expectType } from 'tsd';
 
 // A plain transport function — no `capabilities` — still satisfies Adapter (backward compatible).
@@ -33,9 +34,20 @@ expectType<AdapterCapabilities | undefined>(fetchAdapter().capabilities);
 // Every built-in resolves to Adapter.
 expectAssignable<Adapter>(fetchAdapter());
 expectAssignable<Adapter>(xhrAdapter());
+
+// The axios seam is structural, so any hand-rolled client that satisfies it is accepted...
 const client = null as unknown as AxiosLike;
 expectAssignable<Adapter>(axiosAdapter(client));
 
+// ...but the assertion that matters is against REAL axios, because that is what the documented
+// snippet passes. The `as unknown as AxiosLike` cast above cannot make it: it ASSERTS the client is
+// an AxiosLike rather than testing whether axios actually is one, so #708 — `AxiosLikeConfig` being
+// unassignable to axios's own `AxiosRequestConfig`, via a too-wide `responseType?: string` — passed
+// this file while `axiosAdapter(axios)` failed to compile for every user. Pin all three call forms.
+expectAssignable<Adapter>(axiosAdapter(axios));
+expectAssignable<Adapter>(axiosAdapter(axios.create()));
+expectAssignable<Adapter>(axiosAdapter(axios, { timeout: 5 }));
+
 // `supports` is a list of the known capability tags; `name` is optional.
 expectAssignable<AdapterCapabilities>({ supports: [] });
 expectAssignable<AdapterCapabilities>({