@api-wrappers/api-core 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 1.0.2 - 2026-05-14
+
+- Broadened the TypeScript peer dependency range to support TypeScript 6.
+- Added clearer README guidance for developers building wrapper libraries.
+
+## 1.0.1 - 2026-05-14
+
+- Fixed cache keys so array and nullish query params match the actual transport URL serialization.
+- Fixed `afterResponse` status handling so plugins can replace the final response.
+- Fixed GraphQL requests so callers cannot accidentally override the JSON content type.
+- Added structured JSON content-type support for `application/*+json` responses and request bodies.
+- Added retry attempt normalization and accurate `retryCount` values when retry plugins override `maxAttempts`.
+- Added native `HeadersInit` support for default, per-request, and GraphQL headers.
+- Added error guard helpers for ergonomic TypeScript error handling.
+- Added a one-command `verify` script, package metadata cleanup, package export for `package.json`, and an MIT license file.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TDanks2000
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,7 @@
 # @api-wrappers/api-core
 
+![GitHub Repo stars](https://img.shields.io/github/stars/api-wrappers/api-core)
+
 Shared TypeScript HTTP runtime for API wrapper libraries.
 
 `@api-wrappers/api-core` gives wrapper packages a small, predictable foundation
@@ -20,6 +22,8 @@ their internal HTTP layer consistent and testable.
 - Deterministic plugin lifecycle with `setup`, `beforeRequest`,
   `afterResponse`, `onError`, and `dispose`.
 - Built-in auth, cache, logger, rate-limit, retry, and timeout plugins.
+- Native `HeadersInit` support for default, per-request, and GraphQL headers.
+- Type guards for ergonomic `unknown` error handling in TypeScript.
 - Fetch transport with JSON bodies, raw string bodies, abort signals, and
   timeout handling.
 - Response parsing for JSON, text, and binary payloads.
@@ -360,22 +364,22 @@ contract.
 
 ```ts
 import {
-	ApiError,
-	GraphQLRequestError,
-	RateLimitError,
-	TimeoutError,
+	isApiError,
+	isGraphQLRequestError,
+	isRateLimitError,
+	isTimeoutError,
 } from "@api-wrappers/api-core";
 
 try {
 	await client.get("/resource");
 } catch (error) {
-	if (error instanceof RateLimitError) {
+	if (isRateLimitError(error)) {
 		console.log(error.retryAfterMs);
-	} else if (error instanceof TimeoutError) {
+	} else if (isTimeoutError(error)) {
 		console.log("timed out");
-	} else if (error instanceof GraphQLRequestError) {
+	} else if (isGraphQLRequestError(error)) {
 		console.log(error.graphqlErrors);
-	} else if (error instanceof ApiError) {
+	} else if (isApiError(error)) {
 		console.log(error.status, error.responseBody);
 	}
 }
@@ -424,15 +428,23 @@ import {
 	createTimeoutPlugin,
 	gql,
 	GraphQLRequestError,
+	isApiCoreError,
+	isApiError,
+	isGraphQLRequestError,
+	isRateLimitError,
+	isTimeoutError,
 	MemoryStore,
 	RateLimitError,
 	TimeoutError,
 } from "@api-wrappers/api-core";
 
 import type {
+	ApiCoreError,
 	ApiPlugin,
 	ApiResponse,
 	ClientConfig,
+	FetchLike,
+	HeaderInput,
 	QueryParams,
 	RequestContext,
 	RequestOptions,
@@ -465,10 +477,12 @@ The package publishes:
 
 ```bash
 bun install
+bun run verify
 bun run check
+bun run typecheck
 bun test
 bun run build
-npm pack --dry-run
+bun run pack:dry-run
 ```
 
 `dist` is generated by `tsdown`. The published package includes `dist`, `docs`,

package/dist/index.cjs

@@ -209,6 +209,12 @@ function buildUrl(base, query) {
 	return `${base}${base.includes("?") ? base.endsWith("?") || base.endsWith("&") ? "" : "&" : "?"}${qs}`;
 }
 //#endregion
+//#region src/utils/isJsonContentType.ts
+function isJsonContentType(contentType) {
+	const mediaType = contentType?.split(";", 1)[0]?.trim().toLowerCase();
+	return mediaType === "application/json" || mediaType?.endsWith("+json") === true;
+}
+//#endregion
 //#region src/utils/isPlainObject.ts
 function isPlainObject(value) {
 	if (typeof value !== "object" || value === null) return false;
@@ -226,9 +232,9 @@ const defaultFetch = (input, init) => {
 *
 * ```ts
 * import nodeFetch from "node-fetch";
-* createClient({ fetch: nodeFetch as typeof globalThis.fetch });
+* createClient({ fetch: nodeFetch as FetchLike });
 * // — or set it directly on the transport:
-* const transport = createFetchTransport(nodeFetch as typeof globalThis.fetch);
+* const transport = createFetchTransport(nodeFetch as FetchLike);
 * ```
 */
 function createFetchTransport(fetchFn = defaultFetch) {
@@ -280,8 +286,7 @@ function createFetchTransport(fetchFn = defaultFetch) {
 const fetchTransport = createFetchTransport();
 function serializeRequestBody(body, headers) {
 	if (isBodyInit(body)) return body;
-	const contentType = headers["content-type"] ?? "";
-	if (isPlainObject(body) || Array.isArray(body) || contentType.includes("json")) return JSON.stringify(body);
+	if (isPlainObject(body) || Array.isArray(body) || isJsonContentType(headers["content-type"])) return JSON.stringify(body);
 	return String(body);
 }
 function isBodyInit(body) {
@@ -304,10 +309,29 @@ function mergeHeaders(...sources) {
 	const result = {};
 	for (const source of sources) {
 		if (!source) continue;
-		for (const [key, value] of Object.entries(source)) result[key.toLowerCase()] = value;
+		if (isHeaders(source)) {
+			source.forEach((value, key) => {
+				result[key.toLowerCase()] = value;
+			});
+			continue;
+		}
+		if (Array.isArray(source)) {
+			for (const [key, value] of source) result[key.toLowerCase()] = value;
+			continue;
+		}
+		for (const [key, value] of Object.entries(source)) result[key.toLowerCase()] = String(value);
 	}
 	return result;
 }
+function isHeaders(source) {
+	return typeof Headers !== "undefined" && source instanceof Headers;
+}
+//#endregion
+//#region src/utils/normalizeRetryMaxAttempts.ts
+function normalizeRetryMaxAttempts(value) {
+	if (value === void 0 || !Number.isFinite(value)) return 1;
+	return Math.max(1, Math.floor(value));
+}
 //#endregion
 //#region src/utils/resolveUrl.ts
 /**
@@ -416,7 +440,7 @@ var BaseHttpClient = class {
 		await this.init();
 		const transport = this.config.transport ?? (this.config.fetch ? createFetchTransport(this.config.fetch) : fetchTransport);
 		const retryCfg = this.config.retry;
-		let maxAttempts = retryCfg?.maxAttempts ?? 1;
+		let maxAttempts = normalizeRetryMaxAttempts(retryCfg?.maxAttempts);
 		let baseDelay = retryCfg?.delayMs ?? 500;
 		let jitter = retryCfg?.jitter ?? true;
 		let retriableCodes = retryCfg?.retriableStatusCodes ?? DEFAULT_RETRIABLE_STATUS_CODES;
@@ -443,10 +467,15 @@ var BaseHttpClient = class {
 				await this.pluginManager.onError(err, getPluginErrorContext(err) ?? baseCtx);
 				throw err;
 			}
-			if (ctx.meta["retry.maxAttempts"] !== void 0) maxAttempts = ctx.meta["retry.maxAttempts"];
+			if (ctx.meta["retry.maxAttempts"] !== void 0) maxAttempts = normalizeRetryMaxAttempts(ctx.meta["retry.maxAttempts"]);
 			if (ctx.meta["retry.delayMs"] !== void 0) baseDelay = ctx.meta["retry.delayMs"];
 			if (ctx.meta["retry.jitter"] !== void 0) jitter = ctx.meta["retry.jitter"];
 			if (ctx.meta["retry.retriableStatusCodes"] !== void 0) retriableCodes = ctx.meta["retry.retriableStatusCodes"];
+			const retryCount = maxAttempts - 1 - attempt;
+			if (ctx.retryCount !== retryCount) ctx = {
+				...ctx,
+				retryCount
+			};
 			let rawResponse;
 			if (ctx.syntheticResponse) rawResponse = ctx.syntheticResponse;
 			else try {
@@ -473,16 +502,17 @@ var BaseHttpClient = class {
 				await this.pluginManager.onError(err, ctx);
 				throw err;
 			}
-			if (!rawResponse.ok) {
-				if (retriableCodes.includes(rawResponse.status) && attempt < maxAttempts - 1) {
-					if (rawResponse.status === 429) {
-						const wait = readRetryAfterMs(rawResponse);
+			const finalResponse = resCtx.response;
+			if (!finalResponse.ok) {
+				if (retriableCodes.includes(finalResponse.status) && attempt < maxAttempts - 1) {
+					if (finalResponse.status === 429) {
+						const wait = readRetryAfterMs(finalResponse);
 						await this.waitForRetry(attempt, wait ?? baseDelay, false);
 					} else await this.waitForRetry(attempt, baseDelay, jitter);
-					lastError = normalizeHttpError(rawResponse, resCtx.parsedBody);
+					lastError = normalizeHttpError(finalResponse, resCtx.parsedBody);
 					continue;
 				}
-				const err = normalizeHttpError(rawResponse, resCtx.parsedBody);
+				const err = normalizeHttpError(finalResponse, resCtx.parsedBody);
 				await this.pluginManager.onError(err, ctx);
 				throw err;
 			}
@@ -586,7 +616,7 @@ var BaseHttpClient = class {
 				...variables !== void 0 && { variables },
 				...operationName !== void 0 && { operationName }
 			},
-			headers,
+			headers: mergeHeaders(headers, { "content-type": "application/json" }),
 			signal,
 			timeoutMs,
 			cacheKey,
@@ -610,7 +640,7 @@ async function parseBody(response, responseType = "auto") {
 	if (responseType === "text") return text;
 	if (!text) return void 0;
 	if (responseType === "json") return JSON.parse(text);
-	if ((response.headers.get("content-type") ?? "").includes("application/json")) return JSON.parse(text);
+	if (isJsonContentType(response.headers.get("content-type"))) return JSON.parse(text);
 	return text;
 }
 function normalizeHttpError(response, body) {
@@ -646,6 +676,23 @@ function createClient(config) {
 	return new BaseHttpClient(config);
 }
 //#endregion
+//#region src/errors/guards.ts
+function isApiError(error) {
+	return error instanceof ApiError;
+}
+function isRateLimitError(error) {
+	return error instanceof RateLimitError;
+}
+function isTimeoutError(error) {
+	return error instanceof TimeoutError;
+}
+function isGraphQLRequestError(error) {
+	return error instanceof GraphQLRequestError;
+}
+function isApiCoreError(error) {
+	return isApiError(error) || isTimeoutError(error);
+}
+//#endregion
 //#region src/plugins/auth/authPlugin.ts
 /**
 * Adds an auth token header before each request. The token can be static or
@@ -723,7 +770,7 @@ function createCachePlugin(options = {}) {
 			const key = ctx.cacheKey ?? generateKey(ctx);
 			const cached = await store.get(key);
 			if (cached !== void 0) {
-				const syntheticResponse = new Response(JSON.stringify(cached), {
+				const syntheticResponse = new Response(serializeCachedBody(cached), {
 					status: 200,
 					headers: { "content-type": "application/json" }
 				});
@@ -784,8 +831,14 @@ function createCachePlugin(options = {}) {
 	};
 }
 function defaultCacheKey(ctx) {
-	const queryStr = ctx.query ? new URLSearchParams(Object.fromEntries(Object.entries(ctx.query).filter(([, v]) => v !== void 0).map(([k, v]) => [k, String(v)]))).toString() : "";
-	return `${ctx.method}:${ctx.url}${queryStr ? `?${queryStr}` : ""}`;
+	return `${ctx.method}:${buildUrl(ctx.url, ctx.query)}`;
+}
+function serializeCachedBody(value) {
+	try {
+		return JSON.stringify(value) ?? null;
+	} catch {
+		return null;
+	}
 }
 //#endregion
 //#region src/plugins/logger/loggerPlugin.ts
@@ -933,11 +986,20 @@ function createRetryPlugin(options = {}) {
 		name: "retry",
 		priority: 5,
 		beforeRequest(ctx) {
-			if (options.maxAttempts !== void 0) ctx.meta["retry.maxAttempts"] = options.maxAttempts;
-			if (options.delayMs !== void 0) ctx.meta["retry.delayMs"] = options.delayMs;
-			if (options.jitter !== void 0) ctx.meta["retry.jitter"] = options.jitter;
-			if (options.retriableStatusCodes !== void 0) ctx.meta["retry.retriableStatusCodes"] = options.retriableStatusCodes;
-			return ctx;
+			const meta = { ...ctx.meta };
+			let retryCount = ctx.retryCount;
+			if (options.maxAttempts !== void 0) {
+				meta["retry.maxAttempts"] = options.maxAttempts;
+				retryCount = normalizeRetryMaxAttempts(options.maxAttempts) - 1 - ctx.attempt;
+			}
+			if (options.delayMs !== void 0) meta["retry.delayMs"] = options.delayMs;
+			if (options.jitter !== void 0) meta["retry.jitter"] = options.jitter;
+			if (options.retriableStatusCodes !== void 0) meta["retry.retriableStatusCodes"] = options.retriableStatusCodes;
+			return {
+				...ctx,
+				meta,
+				retryCount
+			};
 		}
 	};
 }
@@ -1055,7 +1117,12 @@ exports.createRetryPlugin = createRetryPlugin;
 exports.createTimeoutPlugin = createTimeoutPlugin;
 exports.fetchTransport = fetchTransport;
 exports.gql = gql;
+exports.isApiCoreError = isApiCoreError;
+exports.isApiError = isApiError;
+exports.isGraphQLRequestError = isGraphQLRequestError;
 exports.isPlainObject = isPlainObject;
+exports.isRateLimitError = isRateLimitError;
+exports.isTimeoutError = isTimeoutError;
 exports.mergeHeaders = mergeHeaders;
 exports.resolveUrl = resolveUrl;
 exports.sleep = sleep;