@api-wrappers/api-core 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,755 @@
+//#region src/types/common.d.ts
+type MaybePromise<T> = T | Promise<T>;
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+type QueryPrimitive = string | number | boolean;
+type QueryValue = QueryPrimitive | null | undefined | readonly (QueryPrimitive | null | undefined)[];
+type QueryParams = Record<string, QueryValue>;
+//#endregion
+//#region src/context/RequestContext.d.ts
+interface RequestContext {
+  url: string;
+  method: HttpMethod;
+  headers: Record<string, string>;
+  body?: unknown;
+  query?: QueryParams;
+  signal?: AbortSignal;
+  meta: Record<string, unknown>;
+  cacheKey?: string;
+  tags?: string[];
+  /**
+   * Number of retry attempts still available after this one.
+   * Equals `maxAttempts - 1 - attempt`, so it counts down from
+   * `maxAttempts - 1` on the first attempt to `0` on the last.
+   * Read-only from a plugin's perspective; set by BaseHttpClient.
+   */
+  retryCount: number;
+  /** Zero-based index of the current attempt (0 = first try). */
+  attempt: number;
+  timeoutMs?: number;
+  /**
+   * When set by a plugin during `beforeRequest`, `BaseHttpClient` will use
+   * this response directly and skip calling the transport altogether.
+   * Plugins that short-circuit the network (e.g. cache hits) should populate
+   * this field instead of relying solely on `meta`.
+   */
+  syntheticResponse?: Response;
+}
+//#endregion
+//#region src/graphql/types.d.ts
+/**
+ * The shape of a single error object inside a GraphQL `errors` array,
+ * as specified by the GraphQL over HTTP specification.
+ */
+interface GraphQLErrorDetail {
+  /** Human-readable error message. */
+  message: string;
+  /**
+   * Path into the response `data` tree where the error occurred.
+   * Each element is a field name (string) or list index (number).
+   */
+  path?: (string | number)[];
+  /** Source locations in the document that triggered the error. */
+  locations?: {
+    line: number;
+    column: number;
+  }[];
+  /** Arbitrary extension data attached by the server. */
+  extensions?: Record<string, unknown>;
+}
+/**
+ * Raw response envelope returned by any spec-compliant GraphQL server.
+ * `data` is absent on a request-level failure; `errors` is absent on
+ * a fully successful response.
+ */
+interface GraphQLResponse<TData = unknown> {
+  data?: TData;
+  errors?: GraphQLErrorDetail[];
+  extensions?: Record<string, unknown>;
+}
+/**
+ * Options for {@link BaseHttpClient.graphql}.
+ *
+ * @typeParam TVariables - Shape of the variables object. Defaults to
+ *   `Record<string, unknown>`. Provide a specific type for compile-time
+ *   variable checking.
+ */
+interface GraphQLRequestOptions<TVariables extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * The GraphQL query or mutation document string.
+   * @example `query GetUser($id: ID!) { user(id: $id) { name } }`
+   */
+  query: string;
+  /** Variables to substitute into the document. */
+  variables?: TVariables;
+  /**
+   * Name of the operation to execute when the document contains multiple
+   * named operations.
+   */
+  operationName?: string;
+  /**
+   * Additional headers merged on top of `ClientConfig.defaultHeaders` for
+   * this request only. `content-type: application/json` is always set.
+   */
+  headers?: Record<string, string>;
+  /**
+   * Per-request timeout override in milliseconds. Throws
+   * {@link TimeoutError} when exceeded.
+   */
+  timeoutMs?: number;
+  /**
+   * Explicit cache key for {@link createCachePlugin}. The cache plugin
+   * skips POST requests by default — provide this to opt a specific
+   * operation into caching.
+   * @example `"gql:GetUser:${userId}"`
+   */
+  cacheKey?: string;
+  /**
+   * Arbitrary string tags passed through to the `RequestContext`. Useful
+   * for metrics grouping or cache invalidation in custom plugins.
+   */
+  tags?: string[];
+}
+//#endregion
+//#region src/context/ResponseContext.d.ts
+/**
+ * Represents the result of an HTTP request as it flows through the
+ * `afterResponse` plugin chain.
+ *
+ * Plugins may return a mutated copy to transform `parsedBody` or attach
+ * state to `meta`. The final `parsedBody` value is what `client.request`
+ * returns to the caller.
+ */
+interface ResponseContext {
+  /** The request context that produced this response. */
+  request: RequestContext;
+  /** The raw `Response` object returned by the transport. */
+  response: Response;
+  /**
+   * Body parsed from the response. JSON responses are parsed with
+   * `response.json()`; everything else is returned as a string via
+   * `response.text()`. Plugins may replace this with a transformed value.
+   */
+  parsedBody?: unknown;
+  /**
+   * Arbitrary key/value store for plugins to attach response-scoped state
+   * without polluting `parsedBody`. Keys should be namespaced by plugin
+   * name (e.g. `"cache.served"`, `"logger.durationMs"`).
+   */
+  meta: Record<string, unknown>;
+}
+//#endregion
+//#region src/plugin/types.d.ts
+interface ApiPlugin {
+  /** Unique display name for debugging. */
+  name: string;
+  /** Optional stable identifier, useful if names are duplicated. */
+  id?: string;
+  /**
+   * Execution order for beforeRequest (ascending) and afterResponse
+   * (descending). Defaults to 100. Plugins with equal priority run
+   * in registration order.
+   */
+  priority?: number;
+  /** When false the plugin is skipped entirely. Defaults to true. */
+  enabled?: boolean;
+  /** Called once when the client initializes. */
+  setup?(client: unknown): MaybePromise<void>;
+  /**
+   * Called before the transport executes. Return a mutated context
+   * or void to keep the existing one.
+   */
+  beforeRequest?(ctx: RequestContext): MaybePromise<RequestContext | void>;
+  /**
+   * Called after a successful transport response. Return a mutated
+   * context or void to keep the existing one.
+   */
+  afterResponse?(ctx: ResponseContext): MaybePromise<ResponseContext | void>;
+  /** Called when the request pipeline throws. */
+  onError?(error: unknown, ctx: RequestContext): MaybePromise<void>;
+  /** Called when the client is disposed. */
+  dispose?(): MaybePromise<void>;
+}
+//#endregion
+//#region src/transport/types.d.ts
+interface Transport {
+  execute(ctx: RequestContext): Promise<Response>;
+}
+//#endregion
+//#region src/client/types.d.ts
+/**
+ * Minimal logger interface accepted by {@link ClientConfig.logger} and
+ * {@link PluginManager}. Compatible with `console` out of the box.
+ */
+interface LoggerInterface {
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Retry behaviour applied to every request made by this client.
+ * Per-request overrides are possible via {@link createRetryPlugin}.
+ */
+interface RetryConfig {
+  /**
+   * Maximum total attempts, including the first. A value of `1` means no
+   * retries (the default when `retry` is omitted from {@link ClientConfig}).
+   */
+  maxAttempts: number;
+  /** Base delay in ms between attempts before exponential backoff. Defaults to `500`. */
+  delayMs?: number;
+  /**
+   * When `true`, a random multiplier in `[0.5, 1)` is applied on top of
+   * exponential backoff so parallel clients don't all retry simultaneously.
+   * Defaults to `true`.
+   */
+  jitter?: boolean;
+  /**
+   * HTTP status codes that trigger a retry. `429` also reads the
+   * `retry-after` header. Defaults to `[429, 500, 502, 503, 504]`.
+   */
+  retriableStatusCodes?: number[];
+}
+/** Configuration passed to {@link BaseHttpClient} or {@link createClient}. */
+interface ClientConfig {
+  /**
+   * Base URL prepended to every `path` argument. No trailing slash;
+   * paths should start with `/`.
+   * @example "https://api.example.com/v1"
+   */
+  baseUrl: string;
+  /**
+   * Headers merged into every request. Per-request `headers` take
+   * precedence. `content-type: application/json` is always present as the
+   * lowest-priority default.
+   */
+  defaultHeaders?: Record<string, string>;
+  /** Plugins registered for the lifetime of this client. */
+  plugins?: ApiPlugin[];
+  /**
+   * Transport implementation for executing requests. Defaults to
+   * {@link fetchTransport}. Swap in tests to avoid real network calls.
+   * When both `transport` and `fetch` are provided, `transport` wins.
+   */
+  transport?: Transport;
+  /**
+   * Custom `fetch` implementation used by the default {@link fetchTransport}.
+   * Useful for polyfills or interceptors (e.g. `node-fetch`, `undici`).
+   * Ignored when a custom `transport` is provided.
+   * @example `import fetch from "node-fetch"; createClient({ fetch })`
+   */
+  fetch?: typeof globalThis.fetch;
+  /**
+   * Default request timeout in ms. Overridable per-request via
+   * `RequestOptions.timeoutMs`. Throws {@link TimeoutError} when exceeded.
+   */
+  timeoutMs?: number;
+  /**
+   * Global retry policy. Omitting means no retries (`maxAttempts: 1`).
+   * Per-request overrides via {@link createRetryPlugin}.
+   */
+  retry?: RetryConfig;
+  /**
+   * Logger used for internal diagnostics (e.g. plugin `onError` handler
+   * failures). Defaults to `console`. Pass a no-op logger to silence all
+   * internal output; pass a structured logger for production observability.
+   * @example `{ info: () => {}, warn: () => {}, error: () => {} }`
+   */
+  logger?: LoggerInterface;
+}
+//#endregion
+//#region src/plugin/PluginManager.d.ts
+declare class PluginManager {
+  private readonly plugins;
+  private readonly logger;
+  /**
+   * @param logger - Logger used when an `onError` handler itself throws.
+   *   Defaults to `console`. Pass a no-op object to silence all output.
+   */
+  constructor(logger?: LoggerInterface);
+  register(plugin: ApiPlugin): void;
+  getAll(): readonly ApiPlugin[];
+  setup(client: unknown): Promise<void>;
+  /**
+   * Runs `beforeRequest` in ascending priority order (lowest first).
+   * Each plugin may return a mutated context.
+   */
+  beforeRequest(ctx: RequestContext): Promise<RequestContext>;
+  /**
+   * Runs `afterResponse` in descending priority order (highest first).
+   * Each plugin may return a mutated context.
+   */
+  afterResponse(ctx: ResponseContext): Promise<ResponseContext>;
+  /**
+   * Runs `onError` on all plugins in registration order. A plugin throwing
+   * here is caught and logged via the configured logger but does not
+   * interrupt other `onError` handlers.
+   */
+  onError(error: unknown, ctx: RequestContext): Promise<void>;
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region src/client/BaseHttpClient.d.ts
+/** Per-request options passed to {@link BaseHttpClient.request} and the convenience methods. */
+interface RequestOptions {
+  /** HTTP method. Defaults to `"GET"`. */
+  method?: HttpMethod;
+  /**
+   * Additional headers merged on top of `ClientConfig.defaultHeaders`.
+   * These take precedence; `content-type: application/json` is always
+   * present and is the lowest-priority default.
+   */
+  headers?: Record<string, string>;
+  /** Request body. Serialised to JSON by {@link fetchTransport}. Ignored for GET and HEAD. */
+  body?: unknown;
+  /**
+   * Query string parameters appended to the URL. `undefined` values are
+   * omitted. Numbers and booleans are coerced to strings. Array values are
+   * emitted as repeated query parameters.
+   */
+  query?: QueryParams;
+  /** Optional caller-provided abort signal. Composes with `timeoutMs`. */
+  signal?: AbortSignal;
+  /**
+   * Per-request timeout override in milliseconds. Takes precedence over
+   * `ClientConfig.timeoutMs`. Throws {@link TimeoutError} when exceeded.
+   */
+  timeoutMs?: number;
+  /**
+   * Explicit cache key used by {@link createCachePlugin}. When omitted the
+   * plugin derives a key from the method, URL, and query string.
+   */
+  cacheKey?: string;
+  /**
+   * Arbitrary string tags attached to the request context. Plugins may use
+   * these for cache invalidation, metrics grouping, or filtering.
+   */
+  tags?: string[];
+}
+interface ApiResponse<T = unknown> {
+  data: T;
+  response: Response;
+  request: RequestContext;
+  meta: Record<string, unknown>;
+}
+/**
+ * Core HTTP client. Manages the plugin lifecycle, retry loop, and transport
+ * dispatch for all requests.
+ *
+ * Plugins are initialised lazily on the first call to {@link request} (or any
+ * convenience method). Call {@link dispose} when the client is no longer
+ * needed so plugins can release timers, connections, or cache handles.
+ *
+ * Extend this class to add domain-specific methods while keeping the plugin
+ * and transport infrastructure intact.
+ *
+ * @example
+ * ```ts
+ * // Prefer createClient() in application code:
+ * const client = createClient({ baseUrl: "https://api.example.com/v1" });
+ *
+ * // Or subclass for wrapper packages:
+ * class MyApiClient extends BaseHttpClient {
+ *   getUser(id: string) { return this.get<User>(`/users/${id}`); }
+ * }
+ * ```
+ */
+declare class BaseHttpClient {
+  protected readonly config: ClientConfig;
+  protected readonly pluginManager: PluginManager;
+  private initialized;
+  private initPromise;
+  constructor(config: ClientConfig);
+  /** Initializes all plugins. Called lazily on first request. */
+  init(): Promise<void>;
+  /** Disposes all plugins. Call when the client is no longer needed. */
+  dispose(): Promise<void>;
+  /**
+   * Executes an HTTP request through the full plugin pipeline.
+   *
+   * Lifecycle per attempt:
+   * 1. Build `RequestContext` with merged headers, query, and retry state.
+   * 2. Run `beforeRequest` hooks (ascending priority). A plugin may set
+   *    `ctx.syntheticResponse` to skip the transport entirely (e.g. cache hit).
+   * 3. Merge any `retry.*` meta written by {@link createRetryPlugin}.
+   * 4. Call transport (skipped when `syntheticResponse` is set).
+   * 5. Parse the response body (JSON or text).
+   * 6. Run `afterResponse` hooks (descending priority).
+   * 7. Retry on retriable status codes; throw on terminal failures.
+   *
+   * @param path - Path appended to `ClientConfig.baseUrl`. Should start with `/`.
+   * @param options - Per-request overrides for method, headers, body, query, etc.
+   * @returns The parsed response body cast to `T`.
+   * @throws {@link ApiError} for non-2xx responses.
+   * @throws {@link RateLimitError} for 429 responses.
+   * @throws {@link TimeoutError} when `timeoutMs` is exceeded.
+   */
+  request<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+  /**
+   * Executes a request and returns the parsed body plus the final response
+   * context. Use this in wrappers that need response headers, status, or
+   * plugin metadata while keeping the same error/retry behaviour as
+   * {@link request}.
+   */
+  requestWithResponse<T = unknown>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+  /** Sends a GET request. The response body is not cached unless a cache plugin is registered. */
+  get<T = unknown>(path: string, options?: Omit<RequestOptions, "method">): Promise<T>;
+  post<T = unknown>(path: string, body?: unknown, options?: Omit<RequestOptions, "method" | "body">): Promise<T>;
+  put<T = unknown>(path: string, body?: unknown, options?: Omit<RequestOptions, "method" | "body">): Promise<T>;
+  patch<T = unknown>(path: string, body?: unknown, options?: Omit<RequestOptions, "method" | "body">): Promise<T>;
+  delete<T = unknown>(path: string, options?: Omit<RequestOptions, "method">): Promise<T>;
+  head<T = unknown>(path: string, options?: Omit<RequestOptions, "method">): Promise<T>;
+  options<T = unknown>(path: string, options?: Omit<RequestOptions, "method">): Promise<T>;
+  /**
+   * Executes a GraphQL query or mutation against a single endpoint path.
+   *
+   * The request is a `POST` with `content-type: application/json` carrying
+   * `{ query, variables?, operationName? }` as the body. It flows through
+   * the full plugin lifecycle (beforeRequest → transport → afterResponse →
+   * onError) and respects all retry configuration, exactly like REST calls.
+   *
+   * **Error handling:**
+   * - HTTP-level failures (429, 500, timeout) throw the same error classes
+   *   as REST requests (`RateLimitError`, `ApiError`, `TimeoutError`).
+   * - A successful HTTP 200 that contains a non-empty `errors` array throws
+   *   {@link GraphQLRequestError}, which extends `ApiError`.
+   *
+   * **Caching:**
+   * The cache plugin skips `POST` requests by default. Pass an explicit
+   * `cacheKey` in options to opt a specific operation into caching.
+   *
+   * @typeParam TData - Shape of the `data` field in the GraphQL response.
+   * @typeParam TVariables - Shape of the `variables` object. Defaults to
+   *   `Record<string, unknown>`.
+   * @param path - Endpoint path, e.g. `"/graphql"`. Appended to `baseUrl`.
+   * @param options - Query document, variables, and optional per-request overrides.
+   * @returns The `data` field from the GraphQL response envelope.
+   * @throws {@link GraphQLRequestError} when `response.errors` is non-empty.
+   * @throws {@link ApiError} / {@link RateLimitError} / {@link TimeoutError} on
+   *   HTTP-level failures.
+   *
+   * @example
+   * ```ts
+   * const data = await client.graphql<GetUserQuery, GetUserQueryVariables>(
+   *   "/graphql",
+   *   { query: GET_USER, variables: { id: "123" } },
+   * );
+   * ```
+   */
+  graphql<TData = unknown, TVariables extends Record<string, unknown> = Record<string, unknown>>(path: string, options: GraphQLRequestOptions<TVariables>): Promise<TData>;
+  private waitForRetry;
+}
+//#endregion
+//#region src/client/createClient.d.ts
+/**
+ * Factory function that creates a {@link BaseHttpClient} from the given
+ * config. Prefer this over `new BaseHttpClient(config)` in application code
+ * so that the concrete class stays an implementation detail.
+ *
+ * @example
+ * ```ts
+ * const client = createClient({
+ *   baseUrl: "https://api.example.com/v1",
+ *   defaultHeaders: { "x-api-key": "secret" },
+ *   retry: { maxAttempts: 3, delayMs: 300 },
+ *   plugins: [createLoggerPlugin(), createCachePlugin({ ttlMs: 60_000 })],
+ * });
+ * ```
+ */
+declare function createClient(config: ClientConfig): BaseHttpClient;
+//#endregion
+//#region src/errors/ApiError.d.ts
+declare class ApiError extends Error {
+  readonly status: number;
+  readonly responseBody: unknown;
+  readonly cause: unknown;
+  constructor(message: string, status: number, responseBody?: unknown, cause?: unknown);
+}
+//#endregion
+//#region src/errors/RateLimitError.d.ts
+declare class RateLimitError extends ApiError {
+  readonly retryAfterMs: number | undefined;
+  constructor(retryAfterMs?: number, responseBody?: unknown, cause?: unknown);
+}
+//#endregion
+//#region src/errors/TimeoutError.d.ts
+declare class TimeoutError extends Error {
+  readonly cause: unknown;
+  constructor(message?: string, cause?: unknown);
+}
+//#endregion
+//#region src/plugins/auth/types.d.ts
+interface AuthPluginOptions {
+  /**
+   * Returns the token to attach to each request. Called per request so
+   * wrappers can refresh credentials without rebuilding the client.
+   */
+  getToken: () => MaybePromise<string | null | undefined>;
+  /** Header name to set. Defaults to `authorization`. */
+  headerName?: string;
+  /**
+   * Token scheme prefix. Defaults to `Bearer`. Pass `null` to write the raw
+   * token value without a scheme.
+   */
+  scheme?: string | null;
+}
+//#endregion
+//#region src/plugins/auth/authPlugin.d.ts
+type TokenInput = string | (() => MaybePromise<string | null | undefined>) | AuthPluginOptions;
+/**
+ * Adds an auth token header before each request. The token can be static or
+ * loaded asynchronously per request, which covers wrappers with refreshable
+ * access tokens.
+ */
+declare function createAuthPlugin(input: TokenInput): ApiPlugin;
+//#endregion
+//#region src/plugins/cache/types.d.ts
+interface CacheStore {
+  get(key: string): MaybePromise<unknown | undefined>;
+  set(key: string, value: unknown, ttlMs?: number): MaybePromise<void>;
+  delete(key: string): MaybePromise<void>;
+  clear(): MaybePromise<void>;
+}
+interface CachePluginOptions {
+  store?: CacheStore;
+  ttlMs?: number;
+  methods?: HttpMethod[];
+  generateKey?: (ctx: RequestContext) => string;
+}
+/**
+ * The object returned by {@link createCachePlugin}. Extends {@link ApiPlugin}
+ * with first-class cache invalidation methods.
+ */
+interface CachePlugin extends ApiPlugin {
+  /**
+   * Removes a single entry from the cache by its exact key.
+   * The key is either the auto-generated `"METHOD:url?query"` string or the
+   * explicit `cacheKey` passed in `RequestOptions`.
+   */
+  invalidate(key: string): Promise<void>;
+  /**
+   * Removes all cache entries that were stored with the given tag.
+   * Tags are attached to requests via `RequestOptions.tags`. Only entries
+   * cached after this plugin was registered will have tag associations.
+   */
+  invalidateByTag(tag: string): Promise<void>;
+}
+//#endregion
+//#region src/plugins/cache/cachePlugin.d.ts
+declare function createCachePlugin(options?: CachePluginOptions): CachePlugin;
+//#endregion
+//#region src/plugins/cache/memoryStore.d.ts
+declare class MemoryStore implements CacheStore {
+  private readonly store;
+  get(key: string): unknown | undefined;
+  set(key: string, value: unknown, ttlMs?: number): void;
+  delete(key: string): void;
+  clear(): void;
+}
+//#endregion
+//#region src/plugins/logger/types.d.ts
+interface LoggerInterface$1 {
+  info(message: string, data?: unknown): void;
+  warn?(message: string, data?: unknown): void;
+  error(message: string, data?: unknown): void;
+}
+interface LoggerPluginOptions {
+  logRequest?: boolean;
+  logResponse?: boolean;
+  logError?: boolean;
+  logger?: LoggerInterface$1;
+}
+//#endregion
+//#region src/plugins/logger/loggerPlugin.d.ts
+/**
+ * Creates a plugin that logs request start, response status, and errors.
+ *
+ * Log lines are prefixed with `[api-core]` and include the HTTP method, URL,
+ * attempt number (on `beforeRequest`), and status code (on `afterResponse`).
+ *
+ * Priority `10` means it runs _after_ auth or header-mutation plugins
+ * (priority < 10) so the logged URL and headers reflect the final request,
+ * but _before_ the cache plugin (priority `20`) so cache hits are still
+ * visible in the log.
+ *
+ * @example
+ * ```ts
+ * createClient({
+ *   baseUrl: "https://api.example.com",
+ *   plugins: [createLoggerPlugin({ logRequest: true, logResponse: true })],
+ * });
+ * ```
+ */
+declare function createLoggerPlugin(options?: LoggerPluginOptions): ApiPlugin;
+//#endregion
+//#region src/plugins/rateLimit/types.d.ts
+interface RateLimitPluginOptions {
+  /**
+   * Maximum number of requests allowed to run at the same time.
+   * Defaults to `Infinity`.
+   */
+  maxConcurrent?: number;
+  /**
+   * Minimum delay between request starts. Defaults to `0`.
+   */
+  minTimeMs?: number;
+  /**
+   * Maximum number of request starts allowed during `intervalMs`.
+   * Both fields must be provided to enable windowed limiting.
+   */
+  maxRequestsPerInterval?: number;
+  intervalMs?: number;
+}
+//#endregion
+//#region src/plugins/rateLimit/rateLimitPlugin.d.ts
+/**
+ * Throttles request starts before they reach the transport. Supports
+ * concurrency, minimum spacing, and fixed-window request budgets.
+ */
+declare function createRateLimitPlugin(options?: RateLimitPluginOptions): ApiPlugin;
+//#endregion
+//#region src/plugins/retry/types.d.ts
+interface RetryPluginOptions {
+  maxAttempts?: number;
+  delayMs?: number;
+  jitter?: boolean;
+  retriableStatusCodes?: number[];
+}
+//#endregion
+//#region src/plugins/retry/retryPlugin.d.ts
+/**
+ * Writes retry configuration into request context meta so the
+ * BaseHttpClient retry loop can read it. Use this when you need
+ * per-request retry overrides rather than global ClientConfig.retry.
+ */
+declare function createRetryPlugin(options?: RetryPluginOptions): ApiPlugin;
+//#endregion
+//#region src/plugins/timeout/types.d.ts
+interface TimeoutPluginOptions {
+  /**
+   * Request timeout in milliseconds. Overrides `ClientConfig.timeoutMs` and
+   * any per-request `timeoutMs` set before this plugin runs.
+   * The abort and {@link TimeoutError} are handled by the transport.
+   */
+  timeoutMs: number;
+}
+//#endregion
+//#region src/plugins/timeout/timeoutPlugin.d.ts
+/**
+ * Sets `ctx.timeoutMs` on every request so all requests made by this client
+ * abort after the configured duration. The actual abort and
+ * {@link TimeoutError} are handled by {@link fetchTransport}.
+ *
+ * Priority `1` ensures the timeout is stamped before any other plugin (e.g.
+ * logger, cache) runs — plugins that read `ctx.timeoutMs` will always see it.
+ * Use a `beforeRequest` hook with a lower priority to override per-request.
+ *
+ * Prefer `ClientConfig.timeoutMs` for a static global timeout. Use this
+ * plugin when you need to set or change the timeout through the plugin
+ * pipeline (e.g. from environment config loaded asynchronously in `setup`).
+ *
+ * @example
+ * ```ts
+ * createClient({
+ *   baseUrl: "https://api.example.com",
+ *   plugins: [createTimeoutPlugin({ timeoutMs: 5_000 })],
+ * });
+ * ```
+ */
+declare function createTimeoutPlugin(options: TimeoutPluginOptions): ApiPlugin;
+//#endregion
+//#region src/graphql/GraphQLRequestError.d.ts
+/**
+ * Thrown when a GraphQL server returns a well-formed HTTP 200 response that
+ * contains a non-empty `errors` array.
+ *
+ * Extends {@link ApiError} so that code catching `ApiError` also catches
+ * GraphQL-level failures. Callers that need to inspect the individual error
+ * objects can narrow with `instanceof GraphQLRequestError` and read
+ * `graphqlErrors`.
+ *
+ * When the server returns both `data` and `errors` (partial result), the
+ * partial data is available on `partialData` but the error is still thrown —
+ * callers must explicitly opt in to consuming partial results.
+ *
+ * @example
+ * ```ts
+ * import { GraphQLRequestError } from "@api-wrappers/api-core";
+ *
+ * try {
+ *   const data = await client.graphql<MyQuery>("/graphql", { query: QUERY });
+ * } catch (err) {
+ *   if (err instanceof GraphQLRequestError) {
+ *     for (const e of err.graphqlErrors) {
+ *       console.error(e.message, e.path);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class GraphQLRequestError extends ApiError {
+  /** The errors array from the GraphQL response envelope. */
+  readonly graphqlErrors: readonly GraphQLErrorDetail[];
+  /**
+   * Partial `data` returned alongside `errors`, if any. `undefined` when
+   * the server returned no `data` field.
+   */
+  readonly partialData: unknown;
+  constructor(errors: GraphQLErrorDetail[], partialData?: unknown, cause?: unknown);
+}
+//#endregion
+//#region src/transport/fetchTransport.d.ts
+/**
+ * Creates a {@link Transport} backed by the provided `fetch` function.
+ * Use this when you need a polyfill or a custom fetch interceptor:
+ *
+ * ```ts
+ * import nodeFetch from "node-fetch";
+ * createClient({ fetch: nodeFetch as typeof globalThis.fetch });
+ * // — or set it directly on the transport:
+ * const transport = createFetchTransport(nodeFetch as typeof globalThis.fetch);
+ * ```
+ */
+declare function createFetchTransport(fetchFn?: typeof globalThis.fetch): Transport;
+/**
+ * Default {@link Transport} backed by the global `fetch` API.
+ *
+ * Behaviour:
+ * - Builds the final URL from `ctx.url` + `ctx.query` via {@link buildUrl}.
+ * - Serialises `ctx.body` to JSON for non-GET/HEAD requests.
+ * - Wires an `AbortController` when `ctx.timeoutMs` is set; throws
+ *   {@link TimeoutError} on abort.
+ *
+ * Replace this with a custom {@link Transport} in tests, or provide a custom
+ * `fetch` function via {@link ClientConfig.fetch}.
+ */
+declare const fetchTransport: Transport;
+//#endregion
+//#region src/utils/buildUrl.d.ts
+/**
+ * Appends a query string to a URL. Skips nullish values and repeats keys for
+ * array values so APIs like TMDB can accept `with_genres=1&with_genres=2`.
+ */
+declare function buildUrl(base: string, query?: QueryParams): string;
+//#endregion
+//#region src/utils/isPlainObject.d.ts
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+//#endregion
+//#region src/utils/mergeHeaders.d.ts
+/**
+ * Merges header objects left to right. Keys are normalized to
+ * lowercase so merging is case-insensitive. Later sources win.
+ */
+declare function mergeHeaders(...sources: (Record<string, string> | undefined)[]): Record<string, string>;
+//#endregion
+//#region src/utils/resolveUrl.d.ts
+/**
+ * Joins a client base URL and request path without requiring callers to keep
+ * slashes perfectly aligned. Absolute request URLs are returned unchanged.
+ */
+declare function resolveUrl(baseUrl: string, path: string): string;
+//#endregion
+//#region src/utils/sleep.d.ts
+declare function sleep(ms: number): Promise<void>;
+//#endregion
+export { ApiError, type ApiPlugin, type ApiResponse, type AuthPluginOptions, BaseHttpClient, type CachePlugin, type CachePluginOptions, type CacheStore, type ClientConfig, type GraphQLErrorDetail, GraphQLRequestError, type GraphQLRequestOptions, type GraphQLResponse, type HttpMethod, type LoggerInterface, type LoggerPluginOptions, type MaybePromise, MemoryStore, PluginManager, type QueryParams, type QueryPrimitive, type QueryValue, RateLimitError, type RateLimitPluginOptions, type RequestContext, type RequestOptions, type ResponseContext, type RetryConfig, type RetryPluginOptions, TimeoutError, type TimeoutPluginOptions, type Transport, buildUrl, createAuthPlugin, createCachePlugin, createClient, createFetchTransport, createLoggerPlugin, createRateLimitPlugin, createRetryPlugin, createTimeoutPlugin, fetchTransport, isPlainObject, mergeHeaders, resolveUrl, sleep };
+//# sourceMappingURL=index.d.mts.map