ty-fetch 0.0.2-beta.7 → 0.0.2-beta.9

package/README.md

@@ -1,12 +1,13 @@
 # ty-fetch
 
-TypeScript tooling that validates API calls against OpenAPI specs. Get autocomplete, diagnostics, and fully typed responses with zero manual types.
+Automatic TypeScript types for any REST API. No codegen step, no manual types — just install, write fetch calls, and get full type safety from OpenAPI specs.
 
 ```ts
 import tf from "ty-fetch";
 
+// Fully typed response — no codegen, no manual types
 const customers = await tf.get("https://api.stripe.com/v1/customers").json();
-// customers is fully typed — data, has_more, object, url all autocomplete
+customers.data // Customer[] — autocomplete works
 
 tf.get("https://api.stripe.com/v1/cutsomers");
 //                                  ~~~~~~~~~~
@@ -14,21 +15,34 @@ tf.get("https://api.stripe.com/v1/cutsomers");
 //        Did you mean '/v1/customers'?
 ```
 
-## What it does
+## How is this different?
 
-- **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
+Most OpenAPI tools require a **codegen step** — you run a command, it generates a client, you import from the generated code. When the spec changes, you regenerate.
+
+ty-fetch has **no codegen**. The TypeScript language service plugin reads OpenAPI specs and generates typed overloads on-the-fly as you write code. Types appear instantly in your editor. You write plain fetch calls with real URLs.
+
+## Features
+
+- **Zero codegen** — types are generated on-the-fly by a TS plugin, not a build step
+- **Typed responses** — `.json()` returns the actual response type from the spec
 - **Typed request bodies** — body params validated against the spec
-- **Path & query params** — typed `params.path` and `params.query` based on the endpoint
+- **Typed path & query params** — `params.path` and `params.query` based on the endpoint
+- **Typed headers** — required headers (API keys, auth) from security schemes
+- **Path validation** — red squiggles for typos, with "did you mean?" suggestions
 - **Autocomplete** — URL path completions inside string literals, filtered by HTTP method
 - **Hover info** — hover over a URL to see available methods and descriptions
+- **JSDoc descriptions** — property descriptions from the spec show up in hover tooltips
+- **Auto-discovery** — probes well-known paths (`/openapi.json`, `/.well-known/openapi.yaml`, etc.) when no spec is configured
+- **YAML support** — specs can be JSON or YAML, local files or remote URLs
+- **Example inference** — generates types from response `example` when `schema` is missing
+- **On-demand** — only fetches specs and generates types for APIs you actually call
 
-Works as both a **TS language service plugin** (editor DX) and a **CLI** (CI validation).
+Works as both a **TS language service plugin** (editor) and a **CLI** (CI).
 
 ## Setup
 
 ```bash
-npm install github:alnorris/ty-fetch
+npm install ty-fetch
 ```
 
 Add the plugin to your `tsconfig.json`:
@@ -41,13 +55,11 @@ 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
+In VS Code, use the workspace TypeScript version: command palette > **TypeScript: Select TypeScript Version** > **Use Workspace Version**.
 
-### The `ty-fetch` client
+That's it. Start writing `tf.get("https://...")` and types appear automatically.
 
-A lightweight HTTP client (similar to [ky](https://github.com/sindresorhus/ky)) with typed methods:
+## Usage
 
 ```ts
 import tf from "ty-fetch";
@@ -69,6 +81,12 @@ const repo = await tf.get("https://api.github.com/repos/{owner}/{repo}", {
 const pets = await tf.get("https://petstore3.swagger.io/api/v3/pet/findByStatus", {
   params: { query: { status: "available" } },
 }).json();
+
+// Headers (typed from security schemes)
+const data = await tf.get("https://api.scrapecreators.com/v1/reddit/search", {
+  params: { query: { query: "typescript" } },
+  headers: { "x-api-key": process.env.API_KEY },
+}).json();
 ```
 
 Response methods:
@@ -81,26 +99,34 @@ Response methods:
 | `.arrayBuffer()` | `Promise<ArrayBuffer>` |
 | `await` directly | `T` (same as `.json()`) |
 
-### CLI
+## Spec configuration
 
-Run validation in CI or from the terminal:
+### Built-in specs (no config needed)
 
-```bash
-npx ty-fetch                    # uses ./tsconfig.json
-npx ty-fetch tsconfig.json      # explicit path
-npx ty-fetch --verbose          # show spec fetching details
-```
+These APIs are typed out of the box:
 
-```
-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'?
+| Domain | API |
+|---|---|
+| `api.stripe.com` | Stripe API |
+| `api.github.com` | GitHub REST API |
+| `petstore3.swagger.io` | Swagger Petstore |
 
-2 error(s) found.
-```
+### Auto-discovery
 
-## Custom specs
+For unknown domains, ty-fetch probes well-known paths automatically:
 
-Map domains to local files or URLs in your tsconfig plugin config:
+- `/.well-known/openapi.json`, `.yaml`, `.yml`
+- `/openapi.json`, `.yaml`, `.yml`
+- `/api/openapi.json`, `.yaml`
+- `/docs/openapi.json`, `.yaml`
+- `/swagger.json`
+- `/api-docs/openapi.json`
+
+If any of these return a valid OpenAPI spec, types are generated automatically.
+
+### Custom specs
+
+Map domains to local files or remote URLs in your tsconfig:
 
 ```jsonc
 {
@@ -109,7 +135,7 @@ 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",
+          "api.internal.company.com": "./specs/internal-api.yaml",
           "api.partner.com": "https://partner.com/openapi.json"
         }
       }
@@ -118,55 +144,43 @@ 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
+- File paths are resolved relative to the tsconfig directory
+- Supports JSON and YAML specs
 - Custom specs override built-in defaults for the same domain
+- Works in both the editor plugin and the CLI
+
+## CLI
 
-This works in both the editor plugin and the CLI.
+Validate API calls in CI:
 
-### Built-in specs
+```bash
+npx ty-fetch                    # uses ./tsconfig.json
+npx ty-fetch tsconfig.json      # explicit path
+npx ty-fetch --verbose          # show spec fetching details
+```
 
-These APIs are supported out of the box (no config needed):
+```
+src/api.ts:21:11 - error TF99001: Path '/v1/cutsomers' does not exist in Stripe API. Did you mean '/v1/customers'?
 
-| Domain | API | Paths |
-|---|---|---|
-| `api.stripe.com` | Stripe API | 414 |
-| `petstore3.swagger.io` | Swagger Petstore | 13 |
-| `api.github.com` | GitHub REST API | 551 |
+1 error(s) found.
+```
 
 ## How it works
 
-1. Plugin intercepts the TS language service (`getSemanticDiagnostics`, `getCompletionsAtPosition`, `getQuickInfoAtPosition`)
-2. Finds `fetch()` / `tf.get()` / `tf.post()` etc. calls with string literal URLs
+1. The TS plugin intercepts the language service (`getSemanticDiagnostics`, `getCompletionsAtPosition`, `getQuickInfoAtPosition`)
+2. Finds `tf.get()` / `tf.post()` / `fetch()` 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
-
-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).
+5. Generates typed overloads into `node_modules/ty-fetch/index.d.ts` via interface declaration merging — only for URLs actually used in your code
 
-## Architecture
+Spec fetching is async. On first encounter, the plugin fires a background fetch and returns no extra diagnostics. When the spec arrives, `refreshDiagnostics()` re-checks the file. Same pattern as [graphqlsp](https://github.com/0no-co/graphqlsp).
 
-```
-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
-```
+Types are generated **only for endpoints you actually use** — not the entire spec. This keeps overload counts low and TypeScript fast.
 
 ## 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:
-
-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

package/dist/core/spec-cache.js

@@ -77,26 +77,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;
 }
 /**
@@ -114,26 +131,71 @@ 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) ||

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ty-fetch",
-  "version": "0.0.2-beta.7",
+  "version": "0.0.2-beta.9",
   "main": "index.js",
   "types": "index.d.ts",
   "exports": {