ty-fetch 0.0.2-beta.1 → 0.0.2-beta.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alister Norris
+
+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,37 +1,70 @@
-# ty-fetch
+# ⚡ ty-fetch
 
-TypeScript tooling that validates API calls against OpenAPI specs. Get autocomplete, diagnostics, and fully typed responses with zero manual types.
+[![npm version](https://img.shields.io/npm/v/ty-fetch.svg)](https://www.npmjs.com/package/ty-fetch)
+[![license](https://img.shields.io/npm/l/ty-fetch.svg)](https://github.com/alnorris/ty-fetch/blob/main/LICENSE)
+[![CI](https://github.com/alnorris/ty-fetch/actions/workflows/ci.yml/badge.svg)](https://github.com/alnorris/ty-fetch/actions/workflows/ci.yml)
+
+**Type-safe fetch from OpenAPI specs. No codegen, no build step.**
+
+```bash
+npm install ty-fetch
+```
+
+```jsonc
+// tsconfig.json — that's the entire setup
+{
+  "compilerOptions": {
+    "plugins": [{ "name": "ty-fetch/plugin" }]
+  }
+}
+```
 
 ```ts
 import tf from "ty-fetch";
 
-const customers = await tf.get("https://api.stripe.com/v1/customers").json();
-// customers is fully typed — data, has_more, object, url all autocomplete
-
-tf.get("https://api.stripe.com/v1/cutsomers");
-//                                  ~~~~~~~~~~
-// Error: Path '/v1/cutsomers' does not exist in Stripe API.
-//        Did you mean '/v1/customers'?
+const data = await tf.get("https://api.mycompany.com/v1/users").json();
+//    ^ fully typed from your OpenAPI spec — autocomplete, hover docs, everything
 ```
 
-## What it does
+If your API serves an OpenAPI spec at `/openapi.json` (or any well-known path), ty-fetch finds it automatically. No config, no codegen, no generated files. Just types.
+
+---
+
+## 🤔 How does it work?
+
+ty-fetch is a **TypeScript language service plugin**. When you write a `tf.get("https://...")` call:
+
+1. 🔍 It extracts the domain from the URL
+2. 📡 Fetches the OpenAPI spec (checks `/openapi.json`, `/.well-known/openapi.yaml`, etc.)
+3. 🏗️ Generates typed overloads on-the-fly — response types, query params, headers, everything
+4. ✅ Validates your API paths and suggests corrections for typos
+
+Types appear in your editor instantly. When the spec changes, types update automatically. No build step ever.
+
+### Compared to other tools
 
-- **Path validation** — red squiggles for typos in API URLs, with "did you mean?" suggestions
-- **Typed responses** — response types generated from OpenAPI schemas, no manual `as` casts
-- **Typed request bodies** — body params validated against the spec
-- **Path & query params** — typed `params.path` and `params.query` based on the endpoint
-- **Autocomplete** — URL path completions inside string literals, filtered by HTTP method
-- **Hover info** — hover over a URL to see available methods and descriptions
+| | ty-fetch | [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) | [openapi-fetch](https://github.com/openapi-ts/openapi-typescript/tree/main/packages/openapi-fetch) | [orval](https://github.com/orval-labs/orval) |
+|---|---|---|---|---|
+| **Codegen step** | None | `npx openapi-typescript ...` | Needs openapi-typescript first | `npx orval` |
+| **Build step** | None | Required | Required | Required |
+| **Generated files** | None | `.d.ts` files | `.d.ts` files | Full client |
+| **Spec changes** | Auto-updates | Re-run codegen | Re-run codegen | Re-run codegen |
+| **Editor integration** | TS plugin (autocomplete, hover, diagnostics) | Types only | Types only | Types only |
+| **Path validation** | Typo detection with suggestions | None | None | None |
+| **Auto-discovery** | Probes well-known paths | Manual | Manual | Manual |
+| **Runtime** | Lightweight fetch wrapper | None (types only) | Fetch wrapper | Axios/fetch client |
 
-Works as both a **TS language service plugin** (editor DX) and a **CLI** (CI validation).
+---
 
-## Setup
+## 📦 Quick start
+
+### 1. Install
 
 ```bash
-npm install github:alnorris/ty-fetch
+npm install ty-fetch
 ```
 
-Add the plugin to your `tsconfig.json`:
+### 2. Add the plugin to tsconfig.json
 
 ```jsonc
 {
@@ -41,66 +74,43 @@ Add the plugin to your `tsconfig.json`:
 }
 ```
 
-In VS Code, make sure you're using the workspace TypeScript version (not the built-in one). Open the command palette and run **TypeScript: Select TypeScript Version** > **Use Workspace Version**.
-
-## Usage
+### 3. Use workspace TypeScript in VS Code
 
-### The `ty-fetch` client
+**Command Palette** → **TypeScript: Select TypeScript Version** → **Use Workspace Version**
 
-A lightweight HTTP client (similar to [ky](https://github.com/sindresorhus/ky)) with typed methods:
+### 4. Start fetching
 
 ```ts
 import tf from "ty-fetch";
 
-// GET with typed response
-const customers = await tf.get("https://api.stripe.com/v1/customers").json();
-
-// POST with typed body
-const customer = await tf.post("https://api.stripe.com/v1/customers", {
-  body: { name: "Jane Doe", email: "jane@example.com" },
-}).json();
-
-// Path params
-const repo = await tf.get("https://api.github.com/repos/{owner}/{repo}", {
-  params: { path: { owner: "anthropics", repo: "claude-code" } },
-}).json();
-
-// Query params
-const pets = await tf.get("https://petstore3.swagger.io/api/v3/pet/findByStatus", {
-  params: { query: { status: "available" } },
-}).json();
+// If your API has a spec at /openapi.json — types just work
+const users = await tf.get("https://api.mycompany.com/v1/users").json();
 ```
 
-Response methods:
+That's it. ✨
 
-| Method | Returns |
-|---|---|
-| `.json()` | `Promise<T>` (typed from spec) |
-| `.text()` | `Promise<string>` |
-| `.blob()` | `Promise<Blob>` |
-| `.arrayBuffer()` | `Promise<ArrayBuffer>` |
-| `await` directly | `T` (same as `.json()`) |
+---
 
-### CLI
+## 🔍 Spec discovery
 
-Run validation in CI or from the terminal:
+### Auto-discovery (zero config)
 
-```bash
-npx ty-fetch                    # uses ./tsconfig.json
-npx ty-fetch tsconfig.json      # explicit path
-npx ty-fetch --verbose          # show spec fetching details
-```
+When you call `tf.get("https://api.example.com/...")`, ty-fetch automatically probes the domain for an OpenAPI spec at these well-known paths:
 
 ```
-example.ts:21:11 - error TF99001: Path '/v1/cutsomers' does not exist in Stripe API. Did you mean '/v1/customers'?
-example.ts:57:11 - error TF99001: Path '/pets' does not exist in Swagger Petstore. Did you mean '/pet'?
-
-2 error(s) found.
+/.well-known/openapi.json    /.well-known/openapi.yaml
+/openapi.json                /openapi.yaml
+/api/openapi.json            /docs/openapi.json
+/swagger.json                /api-docs/openapi.json
 ```
 
-## Custom specs
+If any path returns a valid OpenAPI spec, types are generated automatically.
+
+**This means if your internal API serves a spec, ty-fetch will find it with zero configuration.**
 
-Map domains to local files or URLs in your tsconfig plugin config:
+### Point to specific specs
+
+For APIs that don't serve specs at standard paths, or for local spec files:
 
 ```jsonc
 {
@@ -109,7 +119,13 @@ Map domains to local files or URLs in your tsconfig plugin config:
       {
         "name": "ty-fetch/plugin",
         "specs": {
-          "api.internal.company.com": "./specs/internal-api.json",
+          // Remote spec URL
+          "api.mycompany.com": "https://api.mycompany.com/docs/v2/openapi.json",
+
+          // Local file (resolved relative to tsconfig)
+          "payments.internal.com": "./specs/payments.yaml",
+
+          // Third-party API
           "api.partner.com": "https://partner.com/openapi.json"
         }
       }
@@ -118,55 +134,103 @@ Map domains to local files or URLs in your tsconfig plugin config:
 }
 ```
 
-- **File paths** are resolved relative to the tsconfig directory
-- **URLs** are fetched over HTTPS
-- Custom specs override built-in defaults for the same domain
+JSON and YAML specs both supported. Custom specs override auto-discovery for the same domain.
 
-This works in both the editor plugin and the CLI.
+---
 
-### Built-in specs
+## 🔧 Usage
 
-These APIs are supported out of the box (no config needed):
+```ts
+import tf from "ty-fetch";
 
-| Domain | API | Paths |
-|---|---|---|
-| `api.stripe.com` | Stripe API | 414 |
-| `petstore3.swagger.io` | Swagger Petstore | 13 |
-| `api.github.com` | GitHub REST API | 551 |
+// 📥 GET — response is fully typed
+const users = await tf.get("https://api.mycompany.com/v1/users").json();
 
-## How it works
+// 📤 POST — body is validated against the spec
+const user = await tf.post("https://api.mycompany.com/v1/users", {
+  body: { name: "Jane Doe", email: "jane@example.com" },
+}).json();
 
-1. Plugin intercepts the TS language service (`getSemanticDiagnostics`, `getCompletionsAtPosition`, `getQuickInfoAtPosition`)
-2. Finds `fetch()` / `tf.get()` / `tf.post()` etc. calls with string literal URLs
-3. Extracts the domain and fetches the OpenAPI spec on-demand (cached after first fetch)
-4. Validates paths against the spec, suggests corrections via Levenshtein distance
-5. Generates typed overloads into `node_modules/ty-fetch/index.d.ts` using interface declaration merging — only for URLs actually used in your code
+// 🔗 Path params — typed from the spec's {param} placeholders
+const user = await tf.get("https://api.mycompany.com/v1/users/{id}", {
+  params: { path: { id: "123" } },
+}).json();
+
+// 🔍 Query params — typed from the spec's parameter definitions
+const results = await tf.get("https://api.mycompany.com/v1/users", {
+  params: { query: { role: "admin", limit: 10 } },
+}).json();
 
-Spec fetching is async. On first encounter of a domain, the plugin fires a background fetch and returns no extra diagnostics. When the spec arrives, `refreshDiagnostics()` triggers the editor to re-check. This follows the same pattern as [graphqlsp](https://github.com/0no-co/graphqlsp).
+// 🔑 Headers — required API keys typed from security schemes
+const data = await tf.get("https://api.mycompany.com/v1/data", {
+  headers: { "x-api-key": process.env.API_KEY },
+}).json();
+```
 
-## Architecture
+### Response methods
 
+| Method | Returns |
+|---|---|
+| `.json()` | `Promise<T>` — typed from spec |
+| `.text()` | `Promise<string>` |
+| `.blob()` | `Promise<Blob>` |
+| `.arrayBuffer()` | `Promise<ArrayBuffer>` |
+| `await` directly | `T` — same as `.json()` |
+
+---
+
+## 🚀 Features
+
+- 🔮 **Zero codegen** — types generated on-the-fly by a TS plugin, not a build step
+- 🔍 **Auto-discovery** — finds OpenAPI specs at well-known paths automatically
+- 📦 **Typed responses** — `.json()` returns the actual response type
+- ✏️ **Typed request bodies** — body params validated against the schema
+- 🔗 **Typed path & query params** — based on the endpoint definition
+- 🔑 **Typed headers** — required API keys from security schemes
+- 🚨 **Path validation** — red squiggles for typos, with "did you mean?" suggestions
+- 💡 **Autocomplete** — URL path completions inside string literals
+- 📖 **JSDoc descriptions** — property descriptions from the spec in hover tooltips
+- 📄 **YAML + JSON** — specs can be either format, local files or remote URLs
+- 🧠 **Example inference** — generates types from response `example` when `schema` is missing
+- ⚡ **On-demand** — only fetches specs for APIs you actually call in your code
+
+---
+
+## 🖥️ CLI
+
+Validate API calls in CI — catches typos and bad paths without running the app:
+
+```bash
+npx ty-fetch                    # uses ./tsconfig.json
+npx ty-fetch tsconfig.json      # explicit path
+npx ty-fetch --verbose          # show spec fetching details
 ```
-src/
-  plugin/index.ts      TS language service plugin (diagnostics, completions, hover)
-  cli/index.ts         CLI entry point for CI validation
-  core/                Shared logic (URL parsing, spec cache, path matching, body validation)
-  generate-types.ts    OpenAPI schema -> TypeScript type declarations
-test-project/          Example project using the plugin
-test/                  Unit tests
+
 ```
+src/api.ts:21:11 - error TF99001: Path '/v1/uusers' does not exist.
+                   Did you mean '/v1/users'?
 
-## Development
+1 error(s) found.
+```
+
+---
+
+## 🧪 Development
 
 ```bash
 npm run build          # compile TypeScript
 npm run watch          # compile in watch mode
-npm test               # run unit tests
+npm test               # run unit tests (74 tests)
 ```
 
-To test the editor experience:
+## Roadmap
+
+- [ ] Record demo GIF showing autocomplete + typo detection in VS Code
+- [ ] Spec caching to disk (avoid re-fetching on TS server restart)
+- [ ] `ty-fetch generate` CLI command to generate `.d.ts` for `tsc` compatibility
+- [ ] Support OpenAPI 2.0 (Swagger) specs
+- [ ] Request/response interceptors and middleware
+
+## License
 
-1. Open `test-project/` in VS Code
-2. Select the workspace TypeScript version
-3. Restart the TS server (`TypeScript: Restart TS Server`)
-4. Edit `test-project/example.ts` and observe diagnostics/completions
+MIT

package/base.d.ts

@@ -6,12 +6,14 @@ export interface Options<
   TBody = never,
   TPathParams = never,
   TQueryParams = never,
-> extends Omit<RequestInit, 'body'> {
+  THeaders extends Record<string, string> = Record<string, string>,
+> extends Omit<RequestInit, 'body' | 'headers'> {
   body?: TBody;
   params?: {
     path?: TPathParams;
     query?: TQueryParams;
   };
+  headers?: THeaders & Record<string, string>;
   prefixUrl?: string;
 }
 
@@ -23,16 +25,19 @@ export interface ResponsePromise<T = unknown> extends PromiseLike<T> {
   formData(): Promise<FormData>;
 }
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type BaseOptions = Options<any, Record<string, any>, Record<string, any>>;
+
 export interface TyFetch {
-  (url: string, options?: Options): ResponsePromise;
-  get(url: string, options?: Options): ResponsePromise;
-  post(url: string, options?: Options): ResponsePromise;
-  put(url: string, options?: Options): ResponsePromise;
-  patch(url: string, options?: Options): ResponsePromise;
-  delete(url: string, options?: Options): ResponsePromise;
-  head(url: string, options?: Options): ResponsePromise;
-  create(defaults?: Options<unknown>): TyFetch;
-  extend(defaults?: Options<unknown>): TyFetch;
+  (url: string, options?: BaseOptions): ResponsePromise<any>;
+  get(url: string, options?: BaseOptions): ResponsePromise<any>;
+  post(url: string, options?: BaseOptions): ResponsePromise<any>;
+  put(url: string, options?: BaseOptions): ResponsePromise<any>;
+  patch(url: string, options?: BaseOptions): ResponsePromise<any>;
+  delete(url: string, options?: BaseOptions): ResponsePromise<any>;
+  head(url: string, options?: BaseOptions): ResponsePromise<any>;
+  create(defaults?: BaseOptions): TyFetch;
+  extend(defaults?: BaseOptions): TyFetch;
   HTTPError: typeof HTTPError;
 }
 

package/dist/cli/index.js

@@ -39,6 +39,16 @@ const path = __importStar(require("path"));
 const core_1 = require("../core");
 async function main() {
     const args = process.argv.slice(2);
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(`Usage: ty-fetch [tsconfig.json] [--verbose]
+
+Validate API calls against OpenAPI specs.
+
+Options:
+  --verbose    Show spec fetching details
+  --help, -h   Show this help message`);
+        process.exit(0);
+    }
     const tsconfigPath = args[0] ?? "tsconfig.json";
     const configFile = ts.readConfigFile(path.resolve(tsconfigPath), ts.sys.readFile);
     if (configFile.error) {

package/dist/core/spec-cache.js

@@ -32,17 +32,17 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.specCache = exports.KNOWN_SPECS = void 0;
 exports.registerSpecs = registerSpecs;
 exports.ensureSpec = ensureSpec;
 exports.ensureSpecSync = ensureSpecSync;
 exports.fetchSpecForDomain = fetchSpecForDomain;
-exports.KNOWN_SPECS = {
-    "api.stripe.com": "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json",
-    "petstore3.swagger.io": "https://petstore3.swagger.io/api/v3/openapi.json",
-    "api.github.com": "https://api.apis.guru/v2/specs/github.com/api.github.com/1.1.4/openapi.json",
-};
+const js_yaml_1 = __importDefault(require("js-yaml"));
+exports.KNOWN_SPECS = {};
 exports.specCache = new Map();
 /**
  * Register user-provided spec mappings (from tsconfig plugin config).
@@ -73,26 +73,43 @@ function ensureSpec(domain, log, onLoaded) {
     if (existing)
         return existing;
     const specUrl = exports.KNOWN_SPECS[domain];
-    if (!specUrl) {
-        const entry = { status: "not-found", spec: null, fetchedAt: Date.now() };
-        exports.specCache.set(domain, entry);
-        return entry;
-    }
     const entry = { status: "loading", spec: null, fetchedAt: Date.now() };
     exports.specCache.set(domain, entry);
-    log(`Fetching spec for ${domain} from ${specUrl}`);
-    fetchSpec(specUrl)
-        .then((spec) => {
-        entry.status = "loaded";
-        entry.spec = spec;
-        const pathCount = Object.keys(spec.paths || {}).length;
-        log(`Spec loaded for ${domain}: ${spec.info?.title ?? "unknown"} (${pathCount} paths)`);
-        onLoaded?.(domain, spec);
-    })
-        .catch((err) => {
-        entry.status = "not-found";
-        log(`Failed to fetch spec for ${domain}: ${err}`);
-    });
+    if (specUrl) {
+        log(`Fetching spec for ${domain} from ${specUrl}`);
+        fetchSpec(specUrl)
+            .then((spec) => {
+            entry.status = "loaded";
+            entry.spec = spec;
+            const pathCount = Object.keys(spec.paths || {}).length;
+            log(`Spec loaded for ${domain}: ${spec.info?.title ?? "unknown"} (${pathCount} paths)`);
+            onLoaded?.(domain, spec);
+        })
+            .catch((err) => {
+            entry.status = "not-found";
+            log(`Failed to fetch spec for ${domain}: ${err}`);
+        });
+    }
+    else {
+        log(`No spec configured for ${domain}, probing well-known URLs...`);
+        probeWellKnownSpecs(domain, log)
+            .then((spec) => {
+            if (spec) {
+                entry.status = "loaded";
+                entry.spec = spec;
+                const pathCount = Object.keys(spec.paths || {}).length;
+                log(`Spec discovered for ${domain}: ${spec.info?.title ?? "unknown"} (${pathCount} paths)`);
+                onLoaded?.(domain, spec);
+            }
+            else {
+                entry.status = "not-found";
+                log(`No spec found for ${domain} at well-known URLs`);
+            }
+        })
+            .catch(() => {
+            entry.status = "not-found";
+        });
+    }
     return entry;
 }
 /**
@@ -110,33 +127,86 @@ async function fetchSpecForDomain(domain, log) {
     if (existing && existing.status === "loaded")
         return existing;
     const specUrl = exports.KNOWN_SPECS[domain];
-    if (!specUrl) {
-        const entry = { status: "not-found", spec: null, fetchedAt: Date.now() };
-        exports.specCache.set(domain, entry);
-        return entry;
+    if (specUrl) {
+        log(`Fetching spec for ${domain} from ${specUrl}`);
+        try {
+            const spec = await fetchSpec(specUrl);
+            const entry = { status: "loaded", spec, fetchedAt: Date.now() };
+            exports.specCache.set(domain, entry);
+            const pathCount = Object.keys(spec.paths || {}).length;
+            log(`Spec loaded for ${domain}: ${spec.info?.title ?? "unknown"} (${pathCount} paths)`);
+            return entry;
+        }
+        catch (err) {
+            const entry = { status: "not-found", spec: null, fetchedAt: Date.now() };
+            exports.specCache.set(domain, entry);
+            log(`Failed to fetch spec for ${domain}: ${err}`);
+            return entry;
+        }
     }
-    log(`Fetching spec for ${domain} from ${specUrl}`);
-    try {
-        const spec = await fetchSpec(specUrl);
+    log(`No spec configured for ${domain}, probing well-known URLs...`);
+    const spec = await probeWellKnownSpecs(domain, log);
+    if (spec) {
         const entry = { status: "loaded", spec, fetchedAt: Date.now() };
         exports.specCache.set(domain, entry);
         const pathCount = Object.keys(spec.paths || {}).length;
-        log(`Spec loaded for ${domain}: ${spec.info?.title ?? "unknown"} (${pathCount} paths)`);
+        log(`Spec discovered for ${domain}: ${spec.info?.title ?? "unknown"} (${pathCount} paths)`);
         return entry;
     }
-    catch (err) {
-        const entry = { status: "not-found", spec: null, fetchedAt: Date.now() };
-        exports.specCache.set(domain, entry);
-        log(`Failed to fetch spec for ${domain}: ${err}`);
-        return entry;
+    const entry = { status: "not-found", spec: null, fetchedAt: Date.now() };
+    exports.specCache.set(domain, entry);
+    log(`No spec found for ${domain} at well-known URLs`);
+    return entry;
+}
+const WELL_KNOWN_PATHS = [
+    "/.well-known/openapi.json",
+    "/.well-known/openapi.yaml",
+    "/.well-known/openapi.yml",
+    "/openapi.json",
+    "/openapi.yaml",
+    "/openapi.yml",
+    "/api/openapi.json",
+    "/api/openapi.yaml",
+    "/docs/openapi.json",
+    "/docs/openapi.yaml",
+    "/swagger.json",
+    "/api-docs/openapi.json",
+];
+async function probeWellKnownSpecs(domain, log) {
+    // Try HTTPS first, then HTTP for local/dev servers
+    const protocols = domain.startsWith("127.0.0.1") || domain.startsWith("localhost")
+        ? ["http"] : ["https", "http"];
+    for (const proto of protocols) {
+        for (const path of WELL_KNOWN_PATHS) {
+            const url = `${proto}://${domain}${path}`;
+            try {
+                const spec = await fetchSpec(url);
+                if (spec?.openapi || spec?.swagger) {
+                    log(`Found spec at ${url}`);
+                    return spec;
+                }
+            }
+            catch {
+                // try next
+            }
+        }
+    }
+    return null;
+}
+function parseSpec(data, source) {
+    const isYaml = /\.ya?ml$/i.test(source) ||
+        (!source.endsWith(".json") && !data.trimStart().startsWith("{"));
+    if (isYaml) {
+        return js_yaml_1.default.load(data);
     }
+    return JSON.parse(data);
 }
 async function fetchSpec(urlOrPath) {
     // Local file path — read from disk
     if (!urlOrPath.startsWith("http://") && !urlOrPath.startsWith("https://")) {
         const fs = require("fs");
         const data = fs.readFileSync(urlOrPath, "utf-8");
-        return JSON.parse(data);
+        return parseSpec(data, urlOrPath);
     }
     // Remote URL — fetch via HTTPS/HTTP
     const mod = urlOrPath.startsWith("https://") ? await Promise.resolve().then(() => __importStar(require("https"))) : await Promise.resolve().then(() => __importStar(require("http")));
@@ -146,17 +216,21 @@ async function fetchSpec(urlOrPath) {
                 fetchSpec(res.headers.location).then(resolve, reject);
                 return;
             }
+            if (res.statusCode && (res.statusCode < 200 || res.statusCode >= 300)) {
+                reject(new Error(`HTTP ${res.statusCode}`));
+                return;
+            }
             let data = "";
             res.on("data", (chunk) => (data += chunk));
             res.on("end", () => {
                 try {
-                    resolve(JSON.parse(data));
+                    resolve(parseSpec(data, urlOrPath));
                 }
-                catch {
-                    reject(new Error("Invalid JSON"));
+                catch (err) {
+                    reject(new Error(`Failed to parse spec: ${err}`));
                 }
             });
             res.on("error", reject);
-        });
+        }).on("error", reject);
     });
 }

package/dist/core/types.d.ts

@@ -1,4 +1,6 @@
 export interface OpenAPISpec {
+    openapi?: string;
+    swagger?: string;
     paths: Record<string, Record<string, any>>;
     info?: {
         title?: string;
@@ -10,6 +12,7 @@ export interface OpenAPISpec {
     components?: {
         schemas?: Record<string, any>;
     };
+    security?: Array<Record<string, string[]>>;
 }
 export interface SpecEntry {
     status: "loading" | "loaded" | "not-found";

package/dist/generate-types.d.ts

@@ -20,6 +20,7 @@ interface OpenAPIOperation {
     responses?: Record<string, {
         content?: Record<string, {
             schema?: OpenAPISchema;
+            example?: unknown;
         }>;
         description?: string;
     }>;
@@ -42,7 +43,14 @@ interface FullOpenAPISpec {
     paths: Record<string, Record<string, OpenAPIOperation>>;
     components?: {
         schemas?: Record<string, OpenAPISchema>;
+        securitySchemes?: Record<string, {
+            type?: string;
+            in?: string;
+            name?: string;
+            description?: string;
+        }>;
     };
+    security?: Array<Record<string, string[]>>;
     servers?: Array<{
         url?: string;
     }>;

package/dist/generate-types.js

@@ -81,15 +81,20 @@ function generateDtsContent(domainSpecs) {
                 if (!operation?.responses)
                     continue;
                 const successResp = operation.responses["200"] ?? operation.responses["201"];
-                if (!successResp?.content?.["application/json"]?.schema)
+                const jsonContent = successResp?.content?.["application/json"];
+                if (!jsonContent?.schema && !jsonContent?.example)
                     continue;
-                const schema = successResp.content["application/json"].schema;
+                const schema = jsonContent.schema ?? inferSchemaFromExample(jsonContent.example);
                 const fullUrl = `${baseUrl}${basePath}${path}`;
                 const baseName = sanitizeTypeName(domain, path, method);
                 const count = typeNameCounter.get(baseName) ?? 0;
                 typeNameCounter.set(baseName, count + 1);
                 const typeName = count > 0 ? `${baseName}_${count}` : baseName;
                 const typeBody = schemaToType(schema, resolver, 1);
+                const opDesc = operation.summary ?? operation.description;
+                if (opDesc) {
+                    typeDefinitions.push(`  /** ${method.toUpperCase()} ${path} — ${opDesc.replace(/\*\//g, "* /")} */`);
+                }
                 typeDefinitions.push(`  type ${typeName} = ${typeBody};`);
                 // ── Body type ──
                 const reqBodySchema = operation.requestBody?.content?.["application/json"]?.schema ??
@@ -124,26 +129,64 @@ function generateDtsContent(domainSpecs) {
                             : paramSchema?.type === "number" ? "number"
                                 : paramSchema?.type === "boolean" ? "boolean"
                                     : "string";
-                        queryParams.push({ name: resolved.name, type: tsType, required: !!resolved.required });
+                        queryParams.push({ name: resolved.name, type: tsType, required: !!resolved.required, description: resolved.description });
                     }
                 }
                 let queryParamsArg = "never";
                 if (queryParams.length > 0) {
                     const queryParamsTypeName = `${typeName}_QueryParams`;
-                    const queryProps = queryParams
-                        .map((q) => `${safePropName(q.name)}${q.required ? "" : "?"}: ${q.type}`)
-                        .join("; ");
-                    typeDefinitions.push(`  type ${queryParamsTypeName} = { ${queryProps} };`);
+                    const queryPropLines = [];
+                    for (const q of queryParams) {
+                        if (q.description)
+                            queryPropLines.push(`/** ${q.description.replace(/\*\//g, "* /")} */`);
+                        queryPropLines.push(`${safePropName(q.name)}${q.required ? "" : "?"}: ${q.type};`);
+                    }
+                    typeDefinitions.push(`  type ${queryParamsTypeName} = { ${queryPropLines.join(" ")} };`);
                     queryParamsArg = queryParamsTypeName;
                 }
-                const optionsType = `Options<${bodyTypeArg}, ${pathParamsArg}, ${queryParamsArg}>`;
+                // ── Headers type (from security schemes + header params) ──
+                const headerProps = [];
+                // Collect from header parameters
+                for (const param of allParams) {
+                    const resolved = param.$ref ? resolveRef(spec, param.$ref) : param;
+                    if (resolved?.in === "header") {
+                        headerProps.push({ name: resolved.name, description: resolved.description, required: !!resolved.required });
+                    }
+                }
+                // Collect from security schemes
+                const opSecurity = operation.security ?? spec.security;
+                if (opSecurity && spec.components?.securitySchemes) {
+                    for (const req of opSecurity) {
+                        for (const schemeName of Object.keys(req)) {
+                            const scheme = spec.components.securitySchemes[schemeName];
+                            if (scheme?.type === "apiKey" && scheme.in === "header" && scheme.name) {
+                                if (!headerProps.some((h) => h.name === scheme.name)) {
+                                    headerProps.push({ name: scheme.name, description: scheme.description, required: true });
+                                }
+                            }
+                        }
+                    }
+                }
+                let headersArg = "Record<string, string>";
+                if (headerProps.length > 0) {
+                    const headersTypeName = `${typeName}_Headers`;
+                    const headerPropLines = [];
+                    for (const h of headerProps) {
+                        if (h.description)
+                            headerPropLines.push(`/** ${h.description.replace(/\*\//g, "* /")} */`);
+                        headerPropLines.push(`${safePropName(h.name)}${h.required ? "" : "?"}: string;`);
+                    }
+                    typeDefinitions.push(`  type ${headersTypeName} = { ${headerPropLines.join(" ")} };`);
+                    headersArg = headersTypeName;
+                }
+                const optionsType = `Options<${bodyTypeArg}, ${pathParamsArg}, ${queryParamsArg}, ${headersArg}>`;
                 overloads.push(`    ${method}(url: \`${escapeTemplateUrl(fullUrl)}\`, options?: ${optionsType}): ResponsePromise<${typeName}>;`);
                 // Don't break — emit an overload per HTTP method
             }
         }
     }
     lines.push("// Response types");
-    lines.push(...typeDefinitions.map((l) => l.replace(/^  /, "export ")));
+    lines.push(...typeDefinitions.map((l) => l.startsWith("  type ") ? l.replace(/^  /, "export ") : l.replace(/^  /, "")));
     lines.push("");
     lines.push("export interface TyFetch {");
     lines.push(...overloads.map((l) => l.replace(/^    /, "  ")));
@@ -157,9 +200,31 @@ function resolveRef(spec, ref) {
         return undefined;
     return spec.components?.schemas?.[match[1]];
 }
+/** Infer an OpenAPI schema from a JSON example value. */
+function inferSchemaFromExample(example) {
+    if (example === null || example === undefined)
+        return { type: "string" };
+    if (typeof example === "string")
+        return { type: "string" };
+    if (typeof example === "number")
+        return { type: "number" };
+    if (typeof example === "boolean")
+        return { type: "boolean" };
+    if (Array.isArray(example)) {
+        return { type: "array", items: example.length > 0 ? inferSchemaFromExample(example[0]) : { type: "string" } };
+    }
+    if (typeof example === "object") {
+        const properties = {};
+        for (const [key, value] of Object.entries(example)) {
+            properties[key] = inferSchemaFromExample(value);
+        }
+        return { type: "object", properties };
+    }
+    return { type: "string" };
+}
 function schemaToType(schema, resolver, depth) {
     // Depth limit to avoid huge nested types
-    if (depth > 2)
+    if (depth > 4)
         return "any";
     const indent = "  ".repeat(depth + 1);
     const outerIndent = "  ".repeat(depth);
@@ -195,6 +260,9 @@ function schemaToType(schema, resolver, depth) {
         for (const [key, propSchema] of Object.entries(props)) {
             const optional = required.has(key) ? "" : "?";
             const propType = schemaToType(propSchema, resolver, depth + 1);
+            if (propSchema.description) {
+                propLines.push(`${indent}/** ${propSchema.description.replace(/\*\//g, "* /")} */`);
+            }
             propLines.push(`${indent}${safePropName(key)}${optional}: ${propType};`);
         }
         if (schema.additionalProperties) {

package/index.d.ts

@@ -6,12 +6,14 @@ export interface Options<
   TBody = never,
   TPathParams = never,
   TQueryParams = never,
-> extends Omit<RequestInit, 'body'> {
+  THeaders extends Record<string, string> = Record<string, string>,
+> extends Omit<RequestInit, 'body' | 'headers'> {
   body?: TBody;
   params?: {
     path?: TPathParams;
     query?: TQueryParams;
   };
+  headers?: THeaders & Record<string, string>;
   prefixUrl?: string;
 }
 
@@ -23,16 +25,19 @@ export interface ResponsePromise<T = unknown> extends PromiseLike<T> {
   formData(): Promise<FormData>;
 }
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type BaseOptions = Options<any, Record<string, any>, Record<string, any>>;
+
 export interface TyFetch {
-  (url: string, options?: Options): ResponsePromise;
-  get(url: string, options?: Options): ResponsePromise;
-  post(url: string, options?: Options): ResponsePromise;
-  put(url: string, options?: Options): ResponsePromise;
-  patch(url: string, options?: Options): ResponsePromise;
-  delete(url: string, options?: Options): ResponsePromise;
-  head(url: string, options?: Options): ResponsePromise;
-  create(defaults?: Options<unknown>): TyFetch;
-  extend(defaults?: Options<unknown>): TyFetch;
+  (url: string, options?: BaseOptions): ResponsePromise<any>;
+  get(url: string, options?: BaseOptions): ResponsePromise<any>;
+  post(url: string, options?: BaseOptions): ResponsePromise<any>;
+  put(url: string, options?: BaseOptions): ResponsePromise<any>;
+  patch(url: string, options?: BaseOptions): ResponsePromise<any>;
+  delete(url: string, options?: BaseOptions): ResponsePromise<any>;
+  head(url: string, options?: BaseOptions): ResponsePromise<any>;
+  create(defaults?: BaseOptions): TyFetch;
+  extend(defaults?: BaseOptions): TyFetch;
   HTTPError: typeof HTTPError;
 }
 

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "ty-fetch",
-  "version": "0.0.2-beta.1",
+  "version": "0.0.2-beta.11",
+  "description": "Automatic TypeScript types for any REST API. No codegen, no manual types — just fetch.",
+  "license": "MIT",
+  "keywords": [
+    "typescript",
+    "fetch",
+    "openapi",
+    "types",
+    "api",
+    "swagger",
+    "codegen-free"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alnorris/ty-fetch.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "main": "index.js",
   "types": "index.d.ts",
   "exports": {
@@ -22,16 +40,23 @@
     "base.d.ts",
     "index.js",
     "index.d.ts",
-    "plugin.js"
+    "plugin.js",
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/*.test.mjs",
+    "test": "tsx --test test/*.test.ts",
     "build": "tsc -p tsconfig.build.json",
     "watch": "tsc -p tsconfig.build.json --watch",
     "prepublishOnly": "cp base.d.ts index.d.ts && npm run build"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.5.2",
+    "tsx": "^4.21.0",
     "typescript": "^5.5.0"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.1"
   }
 }