ty-fetch 0.0.2-beta.0 → 0.0.2-beta.10

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,34 +1,66 @@
-# ty-fetch
+# ⚡ 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. No manual types. Just fetch.**
+
+ty-fetch is a TypeScript language service plugin that reads OpenAPI specs and gives you fully typed API calls — response types, request bodies, query params, headers, path validation, and autocomplete — all without a single line of generated code.
 
 ```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
+// ✅ Fully typed — response, query params, headers all inferred from the spec
+const data = await tf.get("https://api.stripe.com/v1/customers", {
+  params: { query: { limit: 10 } },
+}).json();
+data.data // Customer[] — autocomplete just works
 
+// ❌ Typo? Caught instantly with a suggestion
 tf.get("https://api.stripe.com/v1/cutsomers");
 //                                  ~~~~~~~~~~
 // Error: Path '/v1/cutsomers' does not exist in Stripe API.
 //        Did you mean '/v1/customers'?
 ```
 
-## What it does
+---
+
+## 🤔 Why ty-fetch?
+
+Every other OpenAPI tool makes you **run a codegen step**. You generate a client, import from generated files, and re-run the generator when the spec changes. It works, but it's friction.
+
+ty-fetch takes a completely different approach:
+
+| | Traditional codegen | ty-fetch |
+|---|---|---|
+| **Setup** | Install generator, run codegen, import client | `npm install ty-fetch` and go |
+| **When spec changes** | Re-run generator, fix imports | Types update automatically |
+| **What you write** | `client.customers.list()` | `tf.get("https://api.stripe.com/v1/customers")` |
+| **Build step** | Required | None |
+| **Generated files** | Committed to repo or `.gitignore`'d | None — types live in node_modules |
+
+**You write real URLs. The types just appear.**
 
-- **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
+---
 
-Works as both a **TS language service plugin** (editor DX) and a **CLI** (CI validation).
+## 🚀 Features
 
-## Setup
+- 🔮 **Zero codegen** — types 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 schema
+- 🔗 **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
+- 📖 **JSDoc descriptions** — property descriptions from the spec in hover tooltips
+- 🔍 **Auto-discovery** — probes well-known paths (`/openapi.json`, `/.well-known/openapi.yaml`) when no spec is configured
+- 📄 **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 and generates types for APIs you actually call
+
+---
+
+## 📦 Setup
 
 ```bash
-npm install github:alnorris/ty-fetch
+npm install ty-fetch
 ```
 
 Add the plugin to your `tsconfig.json`:
@@ -41,66 +73,75 @@ 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**.
+In VS Code, use the workspace TypeScript version:
+**Command Palette** → **TypeScript: Select TypeScript Version** → **Use Workspace Version**
 
-## Usage
+That's it. Start writing `tf.get("https://...")` and types appear automatically. ✨
 
-### The `ty-fetch` client
+---
 
-A lightweight HTTP client (similar to [ky](https://github.com/sindresorhus/ky)) with typed methods:
+## 🔧 Usage
 
 ```ts
 import tf from "ty-fetch";
 
-// GET with typed response
+// 📥 GET with typed response
 const customers = await tf.get("https://api.stripe.com/v1/customers").json();
 
-// POST with typed body
+// 📤 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
+// 🔗 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" } },
+// 🔍 Query params
+const results = await tf.get("https://hn.algolia.com/api/v1/search_by_date", {
+  params: { query: { query: "typescript", hitsPerPage: 10 } },
+}).json();
+
+// 🔑 Headers (typed from security schemes)
+const data = await tf.get("https://api.example.com/v1/data", {
+  headers: { "x-api-key": process.env.API_KEY },
 }).json();
 ```
 
-Response methods:
+### Response methods
 
 | Method | Returns |
 |---|---|
-| `.json()` | `Promise<T>` (typed from spec) |
+| `.json()` | `Promise<T>` — typed from spec |
 | `.text()` | `Promise<string>` |
 | `.blob()` | `Promise<Blob>` |
 | `.arrayBuffer()` | `Promise<ArrayBuffer>` |
-| `await` directly | `T` (same as `.json()`) |
+| `await` directly | `T` — same as `.json()` |
 
-### CLI
+---
 
-Run validation in CI or from the terminal:
+## 🔍 Spec discovery
 
-```bash
-npx ty-fetch                    # uses ./tsconfig.json
-npx ty-fetch tsconfig.json      # explicit path
-npx ty-fetch --verbose          # show spec fetching details
-```
+### Auto-discovery (zero config)
 
-```
-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'?
+When ty-fetch encounters an API domain it hasn't seen before, it automatically probes these well-known paths:
 
-2 error(s) found.
 ```
+/.well-known/openapi.json
+/.well-known/openapi.yaml
+/openapi.json
+/openapi.yaml
+/api/openapi.json
+/docs/openapi.json
+/swagger.json
+```
+
+If any return a valid OpenAPI spec → types are generated automatically. No config needed.
 
-## Custom specs
+### Custom specs
 
-Map domains to local files or URLs in your tsconfig plugin config:
+Map domains to local files or remote URLs in your tsconfig:
 
 ```jsonc
 {
@@ -109,7 +150,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 +159,53 @@ 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
+- 📁 File paths resolved relative to tsconfig directory
+- 🌐 URLs fetched over HTTPS
+- 📄 JSON and YAML both supported
+- Custom specs override auto-discovery for the same domain
+- Works in both the editor plugin and the CLI
 
-This works in both the editor plugin and the CLI.
+---
 
-### Built-in specs
+## 🖥️ CLI
 
-These APIs are supported out of the box (no config needed):
+Validate API calls in CI — no editor required:
 
-| Domain | API | Paths |
-|---|---|---|
-| `api.stripe.com` | Stripe API | 414 |
-| `petstore3.swagger.io` | Swagger Petstore | 13 |
-| `api.github.com` | GitHub REST API | 551 |
+```bash
+npx ty-fetch                    # uses ./tsconfig.json
+npx ty-fetch tsconfig.json      # explicit path
+npx ty-fetch --verbose          # show spec fetching details
+```
+
+```
+src/api.ts:21:11 - error TF99001: Path '/v1/cutsomers' does not exist in Stripe API.
+                   Did you mean '/v1/customers'?
 
-## How it works
+1 error(s) found.
+```
 
-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
+---
 
-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).
+## ⚙️ How it works
 
-## Architecture
+1. 🔌 Plugin intercepts the TS language service
+2. 🔎 Finds `tf.get()` / `tf.post()` / `fetch()` calls with string literal URLs
+3. 📡 Extracts the domain, fetches the OpenAPI spec on-demand (cached after first fetch)
+4. ✅ Validates paths, suggests corrections via Levenshtein distance
+5. 🏗️ Generates typed overloads into `node_modules/ty-fetch/index.d.ts` via declaration merging — **only for URLs you actually use**
 
-```
-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 call** — not the entire spec. A 500-path API might produce just 5 overloads if that's all you use. This keeps TypeScript fast.
+
+---
 
-## Development
+## 🧪 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:
+## 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;
     }>;