@api-wrappers/api-core 0.0.1

package/docs/guides/rest-requests.md

@@ -0,0 +1,113 @@
+# REST Requests
+
+The client exposes convenience methods for common HTTP verbs and a generic
+`request` method for custom cases.
+
+## Methods
+
+```ts
+client.get<T>(path, options);
+client.post<T>(path, body, options);
+client.put<T>(path, body, options);
+client.patch<T>(path, body, options);
+client.delete<T>(path, options);
+client.head<T>(path, options);
+client.options<T>(path, options);
+client.request<T>(path, { method: "POST", body });
+```
+
+`path` may start with `/` or omit it. Both are joined safely with `baseUrl`.
+Absolute URLs are also supported.
+
+## Request Options
+
+```ts
+await client.get("/movies", {
+	query: {
+		page: 1,
+		language: "en-US",
+		with_genres: [28, 12],
+		ignored: undefined,
+	},
+	headers: {
+		accept: "application/json",
+	},
+	timeoutMs: 10_000,
+	signal: abortController.signal,
+	cacheKey: "movies:page:1",
+	tags: ["movies"],
+});
+```
+
+| Option | Description |
+| --- | --- |
+| `method` | HTTP method for `request`. Convenience methods set this for you. |
+| `headers` | Per-request headers. These override `defaultHeaders`. |
+| `body` | Request body. Objects/arrays are JSON encoded; strings are sent as-is. |
+| `query` | Query string values. Arrays become repeated query parameters. |
+| `timeoutMs` | Per-request timeout override. |
+| `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. |
+
+## Response Metadata
+
+Use `requestWithResponse` when the wrapper needs headers, status, request data,
+or plugin metadata.
+
+```ts
+const result = await client.requestWithResponse<MoviePage>("/movie/popular");
+
+result.data;
+result.response.status;
+result.response.headers.get("x-ratelimit-remaining");
+result.request.url;
+result.meta["cache.served"];
+```
+
+`requestWithResponse` has the same retry, timeout, parsing, plugin, and error
+behavior as `request`.
+
+## Text Body APIs
+
+Some APIs expect a custom text query language rather than JSON. Pass a string
+body and override `content-type`.
+
+```ts
+const games = await client.post<Game[]>(
+	"/games",
+	"fields name,rating; sort rating desc; limit 10;",
+	{
+		headers: {
+			"content-type": "text/plain",
+			accept: "application/json",
+		},
+	},
+);
+```
+
+## Custom Fetch Or Transport
+
+Use `fetch` when you only need to swap the fetch implementation:
+
+```ts
+const client = createClient({
+	baseUrl: "https://api.example.com",
+	fetch: customFetch,
+});
+```
+
+Use `transport` when you want full control over execution:
+
+```ts
+const client = createClient({
+	baseUrl: "https://api.example.com",
+	transport: {
+		execute: async (ctx) => {
+			return new Response(JSON.stringify({ url: ctx.url }), {
+				headers: { "content-type": "application/json" },
+			});
+		},
+	},
+});
+```

package/docs/guides/testing.md

@@ -0,0 +1,88 @@
+# Testing
+
+Use a custom transport to test wrapper behavior without network calls.
+
+## Basic Mock Transport
+
+```ts
+import { BaseHttpClient } from "@api-wrappers/api-core";
+
+const client = new BaseHttpClient({
+	baseUrl: "https://api.example.com",
+	transport: {
+		execute: async (ctx) =>
+			new Response(JSON.stringify({ url: ctx.url, method: ctx.method }), {
+				headers: { "content-type": "application/json" },
+			}),
+	},
+});
+```
+
+## Assert Request Shape
+
+```ts
+let capturedUrl: string | undefined;
+let capturedHeaders: Record<string, string> | undefined;
+
+const client = new BaseHttpClient({
+	baseUrl: "https://api.example.com",
+	defaultHeaders: { accept: "application/json" },
+	transport: {
+		execute: async (ctx) => {
+			capturedUrl = ctx.url;
+			capturedHeaders = ctx.headers;
+			return new Response(JSON.stringify({ ok: true }), {
+				headers: { "content-type": "application/json" },
+			});
+		},
+	},
+});
+
+await client.get("/users/1");
+```
+
+## Test Errors
+
+```ts
+const client = new BaseHttpClient({
+	baseUrl: "https://api.example.com",
+	transport: {
+		execute: async () =>
+			new Response(JSON.stringify({ message: "not found" }), {
+				status: 404,
+				headers: { "content-type": "application/json" },
+			}),
+	},
+});
+
+await expect(client.get("/missing")).rejects.toThrow();
+```
+
+## Test Plugins
+
+Register the same plugins your wrapper uses in production. The transport stays
+mocked, but auth, cache, retry, timeout, and custom plugin behavior still runs.
+
+```ts
+const cache = createCachePlugin({ ttlMs: 60_000 });
+
+const client = new BaseHttpClient({
+	baseUrl: "https://api.example.com",
+	plugins: [createAuthPlugin("token"), cache],
+	transport: {
+		execute: async () =>
+			new Response(JSON.stringify({ ok: true }), {
+				headers: { "content-type": "application/json" },
+			}),
+	},
+});
+```
+
+## Smoke Test A Built Package
+
+After `bun run build`, verify both module formats:
+
+```bash
+node --input-type=module -e "const m = await import('./dist/index.mjs'); if (!m.createClient) throw new Error('missing ESM export')"
+node -e "const m = require('./dist/index.cjs'); if (!m.createClient) throw new Error('missing CJS export')"
+```

package/docs/reference/client.md

@@ -0,0 +1,53 @@
+# Client API
+
+## `createClient(config)`
+
+Creates a `BaseHttpClient`.
+
+```ts
+const client = createClient({
+	baseUrl: "https://api.example.com",
+});
+```
+
+## `BaseHttpClient`
+
+Use `BaseHttpClient` directly when building wrapper-specific classes.
+
+```ts
+class MyApiClient extends BaseHttpClient {
+	getUser(id: string) {
+		return this.get<User>(`/users/${id}`);
+	}
+}
+```
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `request<T>(path, options)` | Execute a request and return the parsed body. |
+| `requestWithResponse<T>(path, options)` | Execute a request and return body, response, request context, and metadata. |
+| `get<T>(path, options)` | GET request. |
+| `post<T>(path, body, options)` | POST request. |
+| `put<T>(path, body, options)` | PUT request. |
+| `patch<T>(path, body, options)` | PATCH request. |
+| `delete<T>(path, options)` | DELETE request. |
+| `head<T>(path, options)` | HEAD request. |
+| `options<T>(path, options)` | OPTIONS request. |
+| `graphql<TData, TVariables>(path, options)` | GraphQL POST request returning `data`. |
+| `init()` | Initialize plugins. Called lazily before the first request. |
+| `dispose()` | Run plugin cleanup hooks. |
+
+## `ApiResponse<T>`
+
+Returned by `requestWithResponse`.
+
+```ts
+interface ApiResponse<T = unknown> {
+	data: T;
+	response: Response;
+	request: RequestContext;
+	meta: Record<string, unknown>;
+}
+```

package/docs/reference/configuration.md

@@ -0,0 +1,83 @@
+# Configuration Reference
+
+## `ClientConfig`
+
+```ts
+interface ClientConfig {
+	baseUrl: string;
+	defaultHeaders?: Record<string, string>;
+	plugins?: ApiPlugin[];
+	transport?: Transport;
+	fetch?: typeof globalThis.fetch;
+	timeoutMs?: number;
+	retry?: RetryConfig;
+	logger?: LoggerInterface;
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `baseUrl` | Base URL prepended to relative request paths. |
+| `defaultHeaders` | Headers merged into every request. |
+| `plugins` | Plugins registered for the client lifetime. |
+| `transport` | Custom request executor. Takes precedence over `fetch`. |
+| `fetch` | Custom fetch implementation used by the default transport. |
+| `timeoutMs` | Default timeout for every request. |
+| `retry` | Global retry policy. |
+| `logger` | Logger used for internal diagnostics. |
+
+## `RequestOptions`
+
+```ts
+interface RequestOptions {
+	method?: HttpMethod;
+	headers?: Record<string, string>;
+	body?: unknown;
+	query?: QueryParams;
+	signal?: AbortSignal;
+	timeoutMs?: number;
+	cacheKey?: string;
+	tags?: string[];
+}
+```
+
+## `RetryConfig`
+
+```ts
+interface RetryConfig {
+	maxAttempts: number;
+	delayMs?: number;
+	jitter?: boolean;
+	retriableStatusCodes?: number[];
+}
+```
+
+`maxAttempts` includes the first attempt. A value of `1` means no retry.
+
+## Query Types
+
+```ts
+type QueryPrimitive = string | number | boolean;
+
+type QueryValue =
+	| QueryPrimitive
+	| null
+	| undefined
+	| readonly (QueryPrimitive | null | undefined)[];
+
+type QueryParams = Record<string, QueryValue>;
+```
+
+Nullish query values are skipped. Array query values are emitted as repeated
+query parameters.
+
+## `Transport`
+
+```ts
+interface Transport {
+	execute(ctx: RequestContext): Promise<Response>;
+}
+```
+
+Custom transports are useful for tests, tracing, custom networking layers, or
+non-fetch runtimes.

package/docs/reference/exports.md

@@ -0,0 +1,74 @@
+# Exports
+
+## Client
+
+- `createClient`
+- `BaseHttpClient`
+- `RequestOptions`
+- `ApiResponse`
+- `ClientConfig`
+- `LoggerInterface`
+- `RetryConfig`
+
+## Context
+
+- `RequestContext`
+- `ResponseContext`
+
+## Errors
+
+- `ApiError`
+- `RateLimitError`
+- `TimeoutError`
+- `GraphQLRequestError`
+
+## Plugin System
+
+- `ApiPlugin`
+- `PluginManager`
+
+## Built-In Plugins
+
+- `createAuthPlugin`
+- `AuthPluginOptions`
+- `createCachePlugin`
+- `CachePlugin`
+- `CachePluginOptions`
+- `CacheStore`
+- `MemoryStore`
+- `createLoggerPlugin`
+- `LoggerPluginOptions`
+- `createRateLimitPlugin`
+- `RateLimitPluginOptions`
+- `createRetryPlugin`
+- `RetryPluginOptions`
+- `createTimeoutPlugin`
+- `TimeoutPluginOptions`
+
+## GraphQL
+
+- `GraphQLErrorDetail`
+- `GraphQLRequestOptions`
+- `GraphQLResponse`
+
+## Transport
+
+- `Transport`
+- `createFetchTransport`
+- `fetchTransport`
+
+## Shared Types
+
+- `HttpMethod`
+- `MaybePromise`
+- `QueryParams`
+- `QueryPrimitive`
+- `QueryValue`
+
+## Utilities
+
+- `buildUrl`
+- `isPlainObject`
+- `mergeHeaders`
+- `resolveUrl`
+- `sleep`

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@api-wrappers/api-core",
+	"version": "0.0.1",
+	"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.",
+	"type": "module",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.mts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.mts",
+				"default": "./dist/index.mjs"
+			},
+			"require": {
+				"types": "./dist/index.d.cts",
+				"default": "./dist/index.cjs"
+			}
+		}
+	},
+	"files": [
+		"dist",
+		"docs"
+	],
+	"keywords": [
+		"http",
+		"client",
+		"fetch",
+		"plugin",
+		"cache",
+		"retry",
+		"api",
+		"wrapper",
+		"typescript"
+	],
+	"license": "MIT",
+	"scripts": {
+		"build": "tsdown",
+		"test": "bun test",
+		"check": "biome check --write .",
+		"check:ci": "biome check ."
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.9",
+		"@types/bun": "1.3.11",
+		"tsdown": "0.21.7"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	}
+}