Release api-core 0.0.3

Author: TDanks2000

.github/workflows/release.yml

@@ -67,6 +67,7 @@ jobs:
         run: bun run build
 
       - name: Verify tag matches package version
+        id: release
         run: |
           TAG="${GITHUB_REF_NAME}"
           if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
@@ -77,6 +78,20 @@ jobs:
             echo "Tag $TAG does not match package.json version $VERSION" >&2
             exit 1
           fi
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+
+      - name: Generate and verify release notes
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.release.outputs.tag }}
+        run: |
+          gh api "repos/${GITHUB_REPOSITORY}/releases/generate-notes" \
+            -f tag_name="$TAG" \
+            --jq '.body // ""' > release-notes.md
+          if ! grep -q '[^[:space:]]' release-notes.md; then
+            echo "GitHub generated empty release notes for ${TAG}" >&2
+            exit 1
+          fi
 
       - name: Verify package contents
         run: npm pack --dry-run --json
@@ -87,13 +102,10 @@ jobs:
       - name: Create GitHub release
         env:
           GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.release.outputs.tag }}
         run: |
-          TAG="${GITHUB_REF_NAME}"
-          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            TAG="${{ github.event.inputs.tag }}"
-          fi
           if gh release view "$TAG" >/dev/null 2>&1; then
-            echo "GitHub release $TAG already exists"
+            gh release edit "$TAG" --title "$TAG" --notes-file release-notes.md
           else
-            gh release create "$TAG" --verify-tag --generate-notes
+            gh release create "$TAG" --verify-tag --title "$TAG" --notes-file release-notes.md
           fi

README.md

@@ -22,6 +22,7 @@ their internal HTTP layer consistent and testable.
 - Built-in auth, cache, logger, rate-limit, retry, and timeout plugins.
 - Fetch transport with JSON bodies, raw string bodies, abort signals, and
   timeout handling.
+- Response parsing for JSON, text, and binary payloads.
 - Query string support for primitives and repeated array values.
 - ESM and CommonJS builds with TypeScript declarations.
 
@@ -168,6 +169,16 @@ const games = await client.post<Game[]>(
 );
 ```
 
+Binary responses can stay on the shared request path by selecting an explicit
+response type:
+
+```ts
+const bytes = await client.post<ArrayBuffer>("/games.pb", query, {
+	headers: { accept: "application/octet-stream" },
+	responseType: "arrayBuffer",
+});
+```
+
 ### Response Metadata
 
 Use `requestWithResponse` when a wrapper needs more than the parsed body:

docs/guides/rest-requests.md

@@ -49,6 +49,8 @@ await client.get("/movies", {
 | `signal` | Caller-provided abort signal. Composes with timeout handling. |
 | `cacheKey` | Explicit key for cache plugins. |
 | `tags` | Labels plugins can use for cache invalidation or metrics. |
+| `responseType` | Override response parsing with `json`, `text`, `arrayBuffer`, or `blob`. Defaults to `auto`. |
+| `errorResponseType` | Override non-2xx body parsing. Defaults to `auto`. |
 
 ## Response Metadata
 
@@ -86,6 +88,19 @@ const games = await client.post<Game[]>(
 );
 ```
 
+## Binary Responses
+
+Use `responseType: "arrayBuffer"` for endpoints that return binary payloads
+while still going through retries, plugins, timeouts, and the configured
+transport.
+
+```ts
+const bytes = await client.post<ArrayBuffer>("/games.pb", "fields id;", {
+	headers: { accept: "application/octet-stream" },
+	responseType: "arrayBuffer",
+});
+```
+
 ## Custom Fetch Or Transport
 
 Use `fetch` when you only need to swap the fetch implementation:

docs/reference/client.md

@@ -39,6 +39,18 @@ class MyApiClient extends BaseHttpClient {
 | `init()` | Initialize plugins. Called lazily before the first request. |
 | `dispose()` | Run plugin cleanup hooks. |
 
+## Response Parsing
+
+Requests parse JSON automatically when the response content type is JSON and
+fall back to text for other bodies. Pass `responseType` to override that:
+
+```ts
+await client.get<string>("/robots.txt", { responseType: "text" });
+await client.post<ArrayBuffer>("/games.pb", query, {
+	responseType: "arrayBuffer",
+});
+```
+
 ## `ApiResponse<T>`
 
 Returned by `requestWithResponse`.

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@api-wrappers/api-core",
-	"version": "0.0.2",
+	"version": "0.0.3",
 	"description": "Shared HTTP client runtime for the api-wrappers organisation. Provides request orchestration, a plugin lifecycle, transport abstraction, and built-in cache/retry/logger plugins.",
 	"repository": {
 		"type": "git",

src/__tests__/client.test.ts

@@ -94,6 +94,49 @@ describe("BaseHttpClient", () => {
 		expect(result.meta.source).toBe("test");
 	});
 
+	it("returns binary bodies when responseType is arrayBuffer", async () => {
+		const bytes = new Uint8Array([8, 1, 18, 4]);
+		const client = new BaseHttpClient({
+			baseUrl: "https://api.test",
+			transport: makeTransport(
+				async () =>
+					new Response(bytes, {
+						headers: { "content-type": "application/octet-stream" },
+					}),
+			),
+		});
+
+		const result = await client.post<ArrayBuffer>("/games.pb", "fields id;", {
+			headers: { accept: "application/octet-stream" },
+			responseType: "arrayBuffer",
+		});
+
+		expect([...new Uint8Array(result)]).toEqual([...bytes]);
+	});
+
+	it("keeps non-ok response parsing automatic for binary requests", async () => {
+		const client = new BaseHttpClient({
+			baseUrl: "https://api.test",
+			transport: makeTransport(
+				async () =>
+					new Response(JSON.stringify({ message: "bad token" }), {
+						status: 401,
+						headers: { "content-type": "application/json" },
+					}),
+			),
+		});
+
+		try {
+			await client.post<ArrayBuffer>("/games.pb", "fields id;", {
+				responseType: "arrayBuffer",
+			});
+			throw new Error("Expected request to fail");
+		} catch (err) {
+			expect(err).toBeInstanceOf(ApiError);
+			expect((err as ApiError).responseBody).toEqual({ message: "bad token" });
+		}
+	});
+
 	it("throws ApiError on non-ok response", async () => {
 		const client = new BaseHttpClient({
 			baseUrl: "https://api.test",

src/__tests__/transport.test.ts

@@ -1,7 +1,10 @@
 import { describe, expect, it } from "bun:test";
 import type { RequestContext } from "../context/RequestContext";
 import { TimeoutError } from "../errors/TimeoutError";
-import { createFetchTransport } from "../transport/fetchTransport";
+import {
+	createFetchTransport,
+	fetchTransport,
+} from "../transport/fetchTransport";
 
 function makeCtx(overrides: Partial<RequestContext> = {}): RequestContext {
 	return {
@@ -47,6 +50,24 @@ describe("fetchTransport", () => {
 		expect(captured?.body).toBe('{"query":"query { Viewer { id } }"}');
 	});
 
+	it("resolves the default global fetch at execution time", async () => {
+		const originalFetch = globalThis.fetch;
+		let called = false;
+
+		try {
+			globalThis.fetch = (async () => {
+				called = true;
+				return new Response("{}");
+			}) as typeof fetch;
+
+			await fetchTransport.execute(makeCtx({ body: undefined, method: "GET" }));
+
+			expect(called).toBe(true);
+		} finally {
+			globalThis.fetch = originalFetch;
+		}
+	});
+
 	it("throws TimeoutError when its own timeout aborts the request", async () => {
 		const transport = createFetchTransport(
 			() =>

src/client/BaseHttpClient.ts

@@ -16,6 +16,8 @@ import { sleep } from "../utils/sleep";
 import type { ClientConfig } from "./types";
 
 /** Per-request options passed to {@link BaseHttpClient.request} and the convenience methods. */
+export type ResponseType = "auto" | "json" | "text" | "arrayBuffer" | "blob";
+
 export interface RequestOptions {
 	/** HTTP method. Defaults to `"GET"`. */
 	method?: HttpMethod;
@@ -50,6 +52,16 @@ export interface RequestOptions {
 	 * these for cache invalidation, metrics grouping, or filtering.
 	 */
 	tags?: string[];
+	/**
+	 * Controls how the response body is parsed. Defaults to content-type based
+	 * parsing: JSON responses become objects, everything else becomes text.
+	 */
+	responseType?: ResponseType;
+	/**
+	 * Optional response parser for non-2xx bodies. Defaults to `"auto"` so APIs
+	 * that return binary success payloads can still surface text/JSON errors.
+	 */
+	errorResponseType?: ResponseType;
 }
 
 export interface ApiResponse<T = unknown> {
@@ -241,7 +253,12 @@ export class BaseHttpClient {
 				}
 			}
 
-			const parsedBody = await parseBody(rawResponse);
+			const parsedBody = await parseBody(
+				rawResponse,
+				rawResponse.ok
+					? options.responseType
+					: (options.errorResponseType ?? "auto"),
+			);
 
 			let resCtx: ResponseContext = {
 				request: ctx,
@@ -438,13 +455,22 @@ export class BaseHttpClient {
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
-async function parseBody(response: Response): Promise<unknown> {
+async function parseBody(
+	response: Response,
+	responseType: ResponseType = "auto",
+): Promise<unknown> {
+	if (responseType === "arrayBuffer") return response.arrayBuffer();
+	if (responseType === "blob") return response.blob();
+
 	if (response.status === 204 || response.status === 205) return undefined;
 	if (response.headers.get("content-length") === "0") return undefined;
 
 	const text = await response.text();
+	if (responseType === "text") return text;
 	if (!text) return undefined;
 
+	if (responseType === "json") return JSON.parse(text);
+
 	const contentType = response.headers.get("content-type") ?? "";
 	if (contentType.includes("application/json")) {
 		return JSON.parse(text);

src/index.ts

@@ -33,7 +33,11 @@
 
 // ─── Client ───────────────────────────────────────────────────────────────────
 
-export type { ApiResponse, RequestOptions } from "./client/BaseHttpClient";
+export type {
+	ApiResponse,
+	RequestOptions,
+	ResponseType,
+} from "./client/BaseHttpClient";
 export { BaseHttpClient } from "./client/BaseHttpClient";
 export { createClient } from "./client/createClient";
 export type {

src/transport/fetchTransport.ts

@@ -4,6 +4,10 @@ import { buildUrl } from "../utils/buildUrl";
 import { isPlainObject } from "../utils/isPlainObject";
 import type { Transport } from "./types";
 
+const defaultFetch: typeof globalThis.fetch = (input, init) => {
+	return globalThis.fetch(input, init);
+};
+
 /**
  * Creates a {@link Transport} backed by the provided `fetch` function.
  * Use this when you need a polyfill or a custom fetch interceptor:
@@ -16,7 +20,7 @@ import type { Transport } from "./types";
  * ```
  */
 export function createFetchTransport(
-	fetchFn: typeof globalThis.fetch = globalThis.fetch,
+	fetchFn: typeof globalThis.fetch = defaultFetch,
 ): Transport {
 	return {
 		async execute(ctx: RequestContext): Promise<Response> {