anyapi-mcp-server 1.6.0 → 1.7.0

package/README.md

@@ -8,276 +8,196 @@ Traditional MCP servers hand-pick a handful of endpoints and call it a day — l
 
 `anyapi-mcp-server` is a universal [MCP](https://modelcontextprotocol.io) server that connects **any REST API** to AI assistants like Claude, Cursor, and other LLM-powered tools — just point it at an OpenAPI spec or Postman collection. Every endpoint the API provides becomes available instantly, with **GraphQL-style field selection** and automatic schema inference. No custom server code, no artificial limits.
 
-Works with services like **Datadog**, **PostHog**, **Metabase**, **Cloudflare**, **Stripe**, **GitHub**, **Slack**, **Twilio**, **Shopify**, **HubSpot**, and anything else with a REST API — if it has an API, it just works.
-
-## Features
-
-- **Works with any REST API** — provide an OpenAPI (JSON/YAML) or Postman Collection v2.x spec as a local file or HTTPS URL
-- **Remote spec caching** — HTTPS spec URLs are fetched once and cached locally in ``~/.cache/anyapi-mcp/` (Linux/macOS) or `%LOCALAPPDATA%\anyapi-mcp\` (Windows)`
-- **GraphQL-style queries** — select only the fields you need from API responses
-- **Automatic schema inference** — calls an endpoint once, infers the response schema, then lets you query specific fields
-- **Multi-sample merging** — samples up to 10 array elements to build richer schemas that capture fields missing from individual items
-- **Mutation support** — POST/PUT/DELETE/PATCH endpoints with OpenAPI request body schemas get GraphQL mutation types with typed inputs
-- **Smart query suggestions** — `call_api` returns ready-to-use GraphQL queries based on the inferred schema
-- **Shape-aware schema caching** — schemas are cached by response structure (not just endpoint), so the same path returning different shapes gets distinct schemas; `shapeHash` is returned for cache-aware workflows
-- **Response caching** — 30-second TTL cache prevents duplicate HTTP calls across consecutive `call_api` → `query_api` flows
-- **Retry with backoff** — automatic retries with exponential backoff and jitter for 429/5xx errors, honoring `Retry-After` headers
-- **Multi-format responses** — parses JSON, XML, CSV, and plain text responses automatically
-- **Built-in pagination** — API-level pagination via `params`; client-side slicing with top-level `limit`/`offset`
-- **Spec documentation lookup** — `explain_api` returns rich endpoint docs (parameters, response codes, deprecation, request body schema) without making HTTP requests
-- **Concurrent batch queries** — `batch_query` fetches data from up to 10 endpoints in parallel, returning all results in one tool call
-- **Per-request headers** — override default headers on individual `call_api`/`query_api`/`batch_query` calls
-- **Environment variable interpolation** — use `${ENV_VAR}` in base URLs and headers
-- **Rich error context** — API errors return structured messages (parses RFC 7807, `{ error: { message, code } }`, `{ errors: [...] }`, and more), status-specific suggestions (e.g. "Authentication required" for 401), and relevant spec info (required parameters, request body schema) for 400/422 errors so the LLM can self-correct
-- **Request logging** — optional NDJSON request/response log with sensitive header masking
-
 [![npm](https://img.shields.io/npm/v/anyapi-mcp-server)](https://www.npmjs.com/package/anyapi-mcp-server)
 
-## Installation
+## Quick start
+
+**1. Install**
 
 ```bash
 npm install -g anyapi-mcp-server
 ```
 
-### Required arguments
-
-| Flag | Description |
-|------|-------------|
-| `--name` | Server name (e.g. `petstore`) |
-| `--spec` | Path or HTTPS URL to OpenAPI spec (JSON or YAML) or Postman Collection. HTTPS URLs are cached locally in ``~/.cache/anyapi-mcp/` (Linux/macOS) or `%LOCALAPPDATA%\anyapi-mcp\` (Windows)`. Supports `${ENV_VAR}` interpolation. |
-| `--base-url` | API base URL (e.g. `https://api.example.com`). Supports `${ENV_VAR}` interpolation. |
-
-### Optional arguments
-
-| Flag | Description |
-|------|-------------|
-| `--header` | HTTP header as `"Key: Value"` (repeatable). Supports `${ENV_VAR}` interpolation in values. |
-| `--log` | Path to request/response log file (NDJSON format). Sensitive headers are masked automatically. |
-
-### Example: Cursor / Claude Desktop configuration
-
-Add to your MCP configuration (e.g. `~/.cursor/mcp.json` or Claude Desktop config):
-
-#### Cloudflare API
+**2. Add to your MCP client** (Cursor, Claude Desktop, etc.)
 
 ```json
 {
   "mcpServers": {
-    "cloudflare": {
+    "your-api": {
       "command": "npx",
       "args": [
         "-y",
         "anyapi-mcp-server",
-        "--name", "cloudflare",
-        "--spec", "https://raw.githubusercontent.com/cloudflare/api-schemas/main/openapi.json",
-        "--base-url", "https://api.cloudflare.com/client/v4",
-        "--header", "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}"
+        "--name", "your-api",
+        "--spec", "path/to/openapi.json",
+        "--base-url", "https://api.example.com",
+        "--header", "Authorization: Bearer ${API_KEY}"
       ],
       "env": {
-        "CLOUDFLARE_API_TOKEN": "your-cloudflare-api-token"
+        "API_KEY": "your-api-key"
       }
     }
   }
 }
 ```
 
-#### Datadog API
+**3. Use the tools** — discover endpoints with `list_api`, inspect schemas with `call_api`, fetch data with `query_api`.
 
-```json
-{
-  "mcpServers": {
-    "datadog": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "anyapi-mcp-server",
-        "--name", "datadog",
-        "--spec", "https://raw.githubusercontent.com/DataDog/datadog-api-client-typescript/master/.generator/schemas/v1/openapi.yaml",
-        "--base-url", "https://api.datadoghq.com",
-        "--header", "DD-API-KEY: ${DD_API_KEY}",
-        "--header", "DD-APPLICATION-KEY: ${DD_APP_KEY}"
-      ],
-      "env": {
-        "DD_API_KEY": "your-datadog-api-key",
-        "DD_APP_KEY": "your-datadog-app-key"
-      }
-    }
-  }
-}
-```
+## Provider examples
 
-#### Metabase API
+Ready-to-use configurations for popular APIs:
 
-```json
-{
-  "mcpServers": {
-    "metabase": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "anyapi-mcp-server",
-        "--name", "metabase",
-        "--base-url", "https://your-metabase-instance.com/api",
-        "--header", "x-api-key: ${METABASE_API_KEY}"
-      ],
-      "env": {
-        "METABASE_API_KEY": "your-metabase-api-key"
-      }
-    }
-  }
-}
-```
+| Provider | Auth |
+|----------|------|
+| [Cloudflare](docs/cloudflare.md) | API Token or Key + Email |
+| [Datadog](docs/datadog.md) | API Key + App Key |
+| [GitHub](docs/github.md) | Personal Access Token |
+| [Google Workspace](docs/google-workspace.md) | OAuth 2.0 |
+| [Metabase](docs/metabase.md) | API Key |
+| [PostHog](docs/posthog.md) | Personal API Key |
+| [Slack](docs/slack.md) | Bot/User Token |
 
-## Tools
+These work with any API that has an OpenAPI or Postman spec — the above are just examples. Stripe, Twilio, Shopify, HubSpot, and anything else with a REST API will work the same way.
 
-The server exposes five MCP tools:
+## CLI reference
 
-### `list_api`
+### Required flags
 
-Browse and search available API endpoints from the spec.
+| Flag | Description |
+|------|-------------|
+| `--name` | Server name (e.g. `cloudflare`) |
+| `--spec` | Path or HTTPS URL to an OpenAPI spec (JSON/YAML) or Postman Collection. Remote URLs are cached locally. Supports `${ENV_VAR}`. |
+| `--base-url` | API base URL (e.g. `https://api.example.com`). Supports `${ENV_VAR}`. |
 
-- Call with no arguments to see all categories/tags
-- Provide `category` to list endpoints in a tag
-- Provide `search` to search across paths and descriptions
-- Results are paginated with `limit` (default 20) and `offset`
-- GraphQL selection for categories:
-  ```graphql
-  {
-    items {
-      tag
-      endpointCount
-    }
-    _count
-  }
-  ```
-- GraphQL selection for endpoints:
-  ```graphql
-  {
-    items {
-      method
-      path
-      summary
-    }
-    _count
-  }
-  ```
+### Optional flags
 
-### `call_api`
+| Flag | Description |
+|------|-------------|
+| `--header` | HTTP header as `"Key: Value"` (repeatable). Supports `${ENV_VAR}` in values. |
+| `--log` | Path to NDJSON request/response log. Sensitive headers are masked automatically. |
 
-Inspect an API endpoint by making a real request and returning the inferred GraphQL schema (SDL). No response data is returned — use `query_api` to fetch actual data.
+### OAuth flags
 
-- Returns the full schema SDL showing all available fields and types
-- Returns accepted parameters (name, location, required) from the API spec
-- Returns `suggestedQueries` — ready-to-use GraphQL queries generated from the schema
-- Returns `shapeHash` — a structural fingerprint of the response for cache-aware workflows
-- Returns `bodyHash` for write operations when a request body is provided
-- Accepts optional `headers` to override defaults for this request
-- For write operations (POST/PUT/DELETE/PATCH) with request body schemas, the schema includes a Mutation type
+For APIs that use OAuth 2.0 instead of static tokens. If any of the three required flags is provided, all three are required. All flags support `${ENV_VAR}`.
 
-### `query_api`
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--oauth-client-id` | Yes* | OAuth client ID |
+| `--oauth-client-secret` | Yes* | OAuth client secret |
+| `--oauth-token-url` | Yes* | Token endpoint URL |
+| `--oauth-auth-url` | No | Authorization endpoint (auto-detected from spec if available) |
+| `--oauth-scopes` | No | Comma-separated scopes |
+| `--oauth-flow` | No | `authorization_code` (default) or `client_credentials` |
+| `--oauth-param` | No | Extra token parameter as `key=value` (repeatable) |
 
-Fetch data from an API endpoint, returning only the fields you select via GraphQL.
+See the [Google Workspace guide](docs/google-workspace.md) for a complete OAuth example.
 
-- Object responses:
-  ```graphql
-  {
-    id
-    name
-    collection {
-      id
-      name
-    }
-  }
-  ```
-- Array responses:
-  ```graphql
-  {
-    items {
-      id
-      name
-    }
-    _count
-  }
-  ```
-- Mutation syntax for writes:
-  ```graphql
-  mutation {
-    post_endpoint(input: { ... }) {
-      id
-      name
-    }
-  }
-  ```
-- Supports `limit` and `offset` for client-side slicing of already-fetched data
-- For API-level pagination, pass limit/offset inside `params` instead
-- Accepts optional `headers` to override defaults for this request
-- Response includes `_shapeHash` (and `_bodyHash` for writes) for tracking schema identity
+## Tools
+
+The server exposes four tools (plus `auth` when OAuth is configured):
+
+### `list_api` — Browse endpoints
+
+Discover what the API offers. Call with no arguments to see all categories, provide `category` to list endpoints in a tag, or `search` to find endpoints by keyword.
+
+### `call_api` — Inspect an endpoint
+
+Makes a real HTTP request and returns the **inferred GraphQL schema** (SDL) — not the data itself. Use this to discover the response shape and get `suggestedQueries` you can copy into `query_api`. Also returns per-field token costs (`fieldTokenCosts`) and a `dataKey` for cache reuse.
 
-### `explain_api`
+### `query_api` — Fetch data
 
-Get detailed documentation for an endpoint directly from the spec — no HTTP request is made.
+Fetches data and returns **only the fields you select** via a GraphQL query. Supports both reads and writes (mutations for POST/PUT/DELETE/PATCH). Pass a `dataKey` from `call_api` to reuse cached data with zero HTTP calls.
 
-- Returns summary, description, operationId, deprecation status, tag
-- Lists all parameters with name, location (`path`/`query`/`header`), required flag, and description
-- Shows request body schema with property types, required fields, and descriptions
-- Lists response status codes with descriptions (e.g. `200 OK`, `404 Not Found`)
-- Includes external docs link when available
+```graphql
+# Read
+{ items { id name status } _count }
 
-### `batch_query`
+# Write
+mutation { post_endpoint(input: { name: "example" }) { id } }
+```
+
+Key parameters:
+- **`maxTokens`** — token budget for the response (default 4000). Arrays are truncated to fit.
+- **`dataKey`** — reuse cached data from a previous `call_api` or `query_api` response.
+- **`jsonFilter`** — dot-path to extract nested values after the GraphQL query (e.g. `"data[].attributes.name"`).
+
+### `explain_api` — Read the docs
 
-Fetch data from multiple endpoints concurrently in a single tool call.
+Returns spec documentation for an endpoint (parameters, request body schema, response codes) **without making an HTTP request**.
 
-- Accepts an array of 1–10 requests, each with `method`, `path`, `params`, `body`, `query`, and optional `headers`
-- All requests execute in parallel via `Promise.allSettled` — one failure does not affect the others
-- Each request follows the `query_api` flow: HTTP fetch → schema inference → GraphQL field selection
-- Returns an array of results: `{ method, path, data, shapeHash }` on success or a structured error with status, suggestion, and spec context on failure
-- Run `call_api` first on each endpoint to discover the schema field names
+### `auth` — OAuth authentication
 
-## Workflow
+Only available when `--oauth-*` flags are configured. Manages the OAuth flow:
+- `action: "start"` — returns an authorization URL (or exchanges credentials for `client_credentials`)
+- `action: "exchange"` — completes the authorization code flow (callback is captured automatically)
+- `action: "status"` — shows current token status
 
-1. **Discover** endpoints with `list_api`
-2. **Understand** an endpoint with `explain_api` to see its parameters, request body, and response codes
-3. **Inspect** a specific endpoint with `call_api` to see the inferred response schema and suggested queries
-4. **Query** the endpoint with `query_api` to fetch exactly the fields you need
-5. **Batch** multiple queries with `batch_query` when you need data from several endpoints at once
+Tokens are persisted and refreshed automatically.
 
-## How It Works
+## Typical workflow
+
+```
+list_api          → discover what's available
+     ↓
+explain_api       → read the docs for an endpoint
+     ↓
+call_api          → inspect the response schema (returns dataKey)
+     ↓
+query_api         → fetch exactly the fields you need (pass dataKey for zero HTTP calls)
+     ↓
+query_api         → re-query with different fields using the same dataKey
+```
+
+## How it works
 
 ```
 OpenAPI/Postman spec
         │
         ▼
-   ┌─────────┐  ┌─────────────┐  ┌──────────┐  ┌───────────┐  ┌─────────────┐
-   │list_api │  │ explain_api │  │ call_api │  │ query_api │  │ batch_query │
-   │(browse) │  │   (docs)    │  │ (schema) │  │  (data)   │  │ (parallel)  │
-   └─────────┘  └─────────────┘  └──────────┘  └───────────┘  └─────────────┘
-        │          │ no HTTP          │               │             │
-        ▼          ▼ request          ▼               ▼             ▼
-   Spec index   Spec index     REST API call    REST API call  N concurrent
-   (tags,       (params,       (with retry      (cached if     REST API calls
-    paths)       responses,     + caching)       same as        + GraphQL
-                 body schema)       │            call_api)      execution
-                                    ▼               │
-                               Infer GraphQL        ▼
-                               schema from     Execute GraphQL
-                               JSON response   query against
-                                               response data
+   ┌─────────┐  ┌─────────────┐  ┌──────────┐  ┌───────────┐
+   │list_api │  │ explain_api │  │ call_api │  │ query_api │
+   │(browse) │  │   (docs)    │  │ (schema) │  │  (data)   │
+   └─────────┘  └─────────────┘  └──────────┘  └───────────┘
+        │          │ no HTTP          │               │
+        ▼          ▼ request          ▼               ▼
+   Spec index   Spec index     REST API call    dataKey cache
+   (tags,       (params,       (with retry)     hit → no HTTP
+    paths)       responses,         │            miss → fetch
+                 body schema)       ▼               │
+                               Infer schema +       ▼
+                               return dataKey   Execute GraphQL
+                                                + token budget
+                                                  truncation
 ```
 
-1. The spec is loaded at startup (from a local file or fetched from an HTTPS URL with filesystem caching) and parsed into an endpoint index with tags, paths, parameters, and request body schemas
-2. `call_api` makes a real HTTP request, infers a GraphQL schema from the JSON response, and caches both the response (30s TTL) and the schema. Schemas are keyed by endpoint + response shape, so the same path returning different structures gets distinct schemas
-3. `query_api` re-uses the cached response if called within 30s, executes your GraphQL field selection against the data, and returns only the fields you asked for. Includes `_shapeHash` in the response for tracking schema identity
-4. Write operations (POST/PUT/DELETE/PATCH) with OpenAPI request body schemas get a Mutation type with typed `GraphQLInputObjectType` inputs
-5. When an API call fails, the error response includes a parsed error message (extracted from common formats like RFC 7807 Problem Details, `{ error: { message } }`, GraphQL-style `{ errors: [...] }`), the HTTP status code, a status-specific suggestion for what to try next, and — for validation errors (400/422) — the full parameter list and request body schema from the spec
+## Features
 
-## Supported Spec Formats
+- **Any REST API** — provide an OpenAPI (JSON/YAML) or Postman Collection v2.x spec as a file or URL
+- **Remote spec caching** — HTTPS specs are fetched once and cached to `~/.cache/anyapi-mcp/`
+- **GraphQL field selection** — query only the fields you need from any response
+- **Schema inference** — automatically builds GraphQL schemas from live API responses
+- **Multi-sample merging** — samples up to 10 array elements for richer schemas
+- **Mutation support** — write operations get typed GraphQL mutations from OpenAPI body schemas
+- **Smart suggestions** — `call_api` returns ready-to-use queries based on the inferred schema
+- **Response caching** — filesystem-based cache with 5-min TTL; `dataKey` tokens let `query_api` reuse data with zero HTTP calls
+- **Token budget** — `query_api` accepts `maxTokens` (default 4000) and truncates array results to fit via binary search
+- **Per-field token costs** — `call_api` returns a `fieldTokenCosts` tree so the LLM can make informed field selections
+- **Rate limit tracking** — parses `X-RateLimit-*` headers and warns when limits are nearly exhausted
+- **Pagination detection** — auto-detects cursor, next-page-token, and link-based pagination patterns in responses
+- **JSON filter** — `query_api` accepts a `jsonFilter` dot-path for post-query extraction (e.g. `"data[].name"`)
+- **Retry with backoff** — automatic retries for 429/5xx with exponential backoff and `Retry-After` support
+- **Multi-format** — parses JSON, XML, CSV, and plain text responses
+- **Rich errors** — structured error messages with status-specific suggestions and spec context for self-correction
+- **OAuth 2.0** — Authorization Code (with PKCE) and Client Credentials flows with automatic token refresh
+- **Env var interpolation** — `${ENV_VAR}` in base URLs, headers, and spec paths
+- **Request logging** — optional NDJSON log with sensitive header masking
+
+## Supported spec formats
 
 - **OpenAPI 3.x** (JSON or YAML)
 - **OpenAPI 2.0 / Swagger** (JSON or YAML)
 - **Postman Collection v2.x** (JSON)
 
-`$ref` resolution is supported for OpenAPI request body schemas. Postman `:param` path variables are converted to OpenAPI-style `{param}` automatically.
-
 ## License
 
 Proprietary Non-Commercial. Free for personal and educational use. Commercial use requires written permission. See [LICENSE](LICENSE) for details.

package/build/api-client.js

@@ -1,8 +1,45 @@
 import { withRetry, RetryableError, isRetryableStatus } from "./retry.js";
-import { buildCacheKey, consumeCached, setCache } from "./response-cache.js";
 import { logEntry, isLoggingEnabled } from "./logger.js";
 import { parseResponse } from "./response-parser.js";
 import { ApiError } from "./error-context.js";
+import { getValidAccessToken, refreshTokens } from "./oauth.js";
+import { waitIfNeeded, trackRateLimit } from "./rate-limit-tracker.js";
+function tryParseInt(val) {
+    if (!val)
+        return null;
+    const n = parseInt(val, 10);
+    return isNaN(n) ? null : n;
+}
+export function parseRateLimits(headers) {
+    const lower = {};
+    for (const [k, v] of Object.entries(headers)) {
+        lower[k.toLowerCase()] = v;
+    }
+    const remaining = tryParseInt(lower["x-ratelimit-remaining"]) ??
+        tryParseInt(lower["ratelimit-remaining"]) ??
+        tryParseInt(lower["x-rate-limit-remaining"]);
+    const limit = tryParseInt(lower["x-ratelimit-limit"]) ??
+        tryParseInt(lower["ratelimit-limit"]) ??
+        tryParseInt(lower["x-rate-limit-limit"]);
+    const resetRaw = lower["x-ratelimit-reset"] ??
+        lower["ratelimit-reset"] ??
+        lower["x-rate-limit-reset"];
+    if (remaining === null && limit === null && !resetRaw)
+        return null;
+    let resetAt = null;
+    if (resetRaw) {
+        const asNumber = parseInt(resetRaw, 10);
+        if (!isNaN(asNumber)) {
+            resetAt = asNumber > 1_000_000_000
+                ? new Date(asNumber * 1000).toISOString()
+                : `${asNumber}s`;
+        }
+        else {
+            resetAt = resetRaw;
+        }
+    }
+    return { remaining, limit, resetAt };
+}
 const TIMEOUT_MS = 30_000;
 function interpolatePath(pathTemplate, params) {
     const remaining = { ...params };
@@ -16,22 +53,7 @@ function interpolatePath(pathTemplate, params) {
     });
     return { url, remainingParams: remaining };
 }
-/**
- * @param cacheMode
- *   - "populate" — skip cache read, always fetch, store result (used by call_api)
- *   - "consume"  — read-and-evict cache, fetch on miss, do NOT re-store (used by query_api)
- *   - "none"     — no caching at all (default)
- */
-export async function callApi(config, method, pathTemplate, params, body, extraHeaders, cacheMode = "none") {
-    // --- Cache check (consume mode only) ---
-    const cacheKey = cacheMode !== "none"
-        ? buildCacheKey(method, pathTemplate, params, body, extraHeaders)
-        : "";
-    if (cacheMode === "consume") {
-        const cached = consumeCached(cacheKey);
-        if (cached !== undefined)
-            return cached;
-    }
+export async function callApi(config, method, pathTemplate, params, body, extraHeaders) {
     // --- URL construction ---
     const { url: interpolatedPath, remainingParams } = interpolatePath(pathTemplate, params ?? {});
     let fullUrl = `${config.baseUrl}${interpolatedPath}`;
@@ -44,75 +66,112 @@ export async function callApi(config, method, pathTemplate, params, body, extraH
         }
         fullUrl += `?${qs.toString()}`;
     }
-    const mergedHeaders = {
-        "Content-Type": "application/json",
+    // Check if an explicit Authorization header was provided by the caller
+    const hasExplicitAuth = Object.keys({
         ...config.headers,
         ...extraHeaders,
-    };
-    // --- Retry-wrapped fetch ---
-    const result = await withRetry(async () => {
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
-        const startTime = Date.now();
-        try {
-            const fetchOptions = {
-                method,
-                headers: mergedHeaders,
-                signal: controller.signal,
-            };
-            if (body && method !== "GET") {
-                fetchOptions.body = JSON.stringify(body);
+    }).some((k) => k.toLowerCase() === "authorization");
+    const doRequest = async () => {
+        const mergedHeaders = {
+            "Content-Type": "application/json",
+            ...config.headers,
+            ...extraHeaders,
+        };
+        // Inject OAuth bearer token if no explicit Authorization header
+        if (!hasExplicitAuth) {
+            const accessToken = await getValidAccessToken(config.oauth);
+            if (accessToken) {
+                mergedHeaders["Authorization"] = `Bearer ${accessToken}`;
             }
-            const response = await fetch(fullUrl, fetchOptions);
-            const durationMs = Date.now() - startTime;
-            const bodyText = await response.text();
-            const responseHeaders = {};
-            response.headers.forEach((v, k) => {
-                responseHeaders[k] = v;
-            });
-            // Log request/response
-            if (isLoggingEnabled()) {
-                await logEntry({
-                    timestamp: new Date().toISOString(),
+        }
+        return withRetry(async () => {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+            const startTime = Date.now();
+            try {
+                const fetchOptions = {
                     method,
-                    url: fullUrl,
-                    requestHeaders: mergedHeaders,
-                    requestBody: body,
-                    responseStatus: response.status,
-                    responseHeaders,
-                    responseBody: bodyText,
-                    durationMs,
+                    headers: mergedHeaders,
+                    signal: controller.signal,
+                };
+                if (body && method !== "GET") {
+                    fetchOptions.body = JSON.stringify(body);
+                }
+                const response = await fetch(fullUrl, fetchOptions);
+                const durationMs = Date.now() - startTime;
+                const bodyText = await response.text();
+                const responseHeaders = {};
+                response.headers.forEach((v, k) => {
+                    responseHeaders[k] = v;
                 });
-            }
-            if (!response.ok) {
-                if (isRetryableStatus(response.status)) {
-                    const msg = `API error ${response.status} ${response.statusText}: ${bodyText}`;
-                    let retryAfterMs;
-                    const retryAfter = response.headers.get("retry-after");
-                    if (retryAfter) {
-                        const seconds = parseInt(retryAfter, 10);
-                        if (!isNaN(seconds))
-                            retryAfterMs = seconds * 1000;
+                // Log request/response
+                if (isLoggingEnabled()) {
+                    await logEntry({
+                        timestamp: new Date().toISOString(),
+                        method,
+                        url: fullUrl,
+                        requestHeaders: mergedHeaders,
+                        requestBody: body,
+                        responseStatus: response.status,
+                        responseHeaders,
+                        responseBody: bodyText,
+                        durationMs,
+                    });
+                }
+                // Track rate limit headers from every response
+                trackRateLimit(parseRateLimits(responseHeaders));
+                if (!response.ok) {
+                    if (isRetryableStatus(response.status)) {
+                        const msg = `API error ${response.status} ${response.statusText}: ${bodyText}`;
+                        let retryAfterMs;
+                        const retryAfter = response.headers.get("retry-after");
+                        if (retryAfter) {
+                            const seconds = parseInt(retryAfter, 10);
+                            if (!isNaN(seconds))
+                                retryAfterMs = seconds * 1000;
+                        }
+                        throw new RetryableError(msg, response.status, retryAfterMs);
                     }
-                    throw new RetryableError(msg, response.status, retryAfterMs);
+                    throw new ApiError(`API error ${response.status} ${response.statusText}`, response.status, response.statusText, bodyText, responseHeaders);
                 }
-                throw new ApiError(`API error ${response.status} ${response.statusText}`, response.status, response.statusText, bodyText, responseHeaders);
+                const parsedData = parseResponse(response.headers.get("content-type"), bodyText);
+                return { data: parsedData, responseHeaders };
             }
-            return parseResponse(response.headers.get("content-type"), bodyText);
-        }
-        catch (error) {
-            if (error instanceof DOMException && error.name === "AbortError") {
-                throw new Error(`Request to ${method} ${pathTemplate} timed out after ${TIMEOUT_MS / 1000}s`);
+            catch (error) {
+                if (error instanceof DOMException && error.name === "AbortError") {
+                    throw new Error(`Request to ${method} ${pathTemplate} timed out after ${TIMEOUT_MS / 1000}s`);
+                }
+                throw error;
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        });
+    };
+    // --- Rate limit pre-check ---
+    await waitIfNeeded();
+    // --- Execute with 401 refresh-and-retry ---
+    let result;
+    try {
+        result = await doRequest();
+    }
+    catch (error) {
+        if (error instanceof ApiError &&
+            error.status === 401 &&
+            config.oauth &&
+            !hasExplicitAuth) {
+            // Refresh token and retry once
+            try {
+                await refreshTokens(config.oauth);
+                result = await doRequest();
+            }
+            catch {
+                throw error; // Throw the original 401
             }
-            throw error;
         }
-        finally {
-            clearTimeout(timeout);
+        else {
+            throw error;
         }
-    });
-    // --- Cache store (populate mode only) ---
-    if (cacheMode === "populate") {
-        setCache(cacheKey, result);
     }
     return result;
 }