swagger-digest 0.1.1 → 0.1.2

package/dist/cli.js

@@ -1,18 +1,76 @@
 #!/usr/bin/env node
 import {
+  VERSION,
   defaultFilename,
   defaultOutputDirectory,
   estimateTokens,
   fetchOpenApiSpec,
   transformOpenApiToMarkdown,
   writeDigest
-} from "./chunk-UZQM2SHL.js";
+} from "./chunk-CBSDTIKN.js";
 
 // src/cli.ts
 import { input } from "@inquirer/prompts";
 import chalk from "chalk";
 import { Command } from "commander";
 import ora from "ora";
+
+// src/headers.ts
+var HEADER_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+function validateHeaderName(name) {
+  if (!name) throw new Error('Header name must not be empty. Expected "Name: value".');
+  if (/[\r\n]/.test(name)) {
+    throw new Error(`Invalid header name: header names must not contain CR/LF characters.`);
+  }
+  if (!HEADER_NAME_PATTERN.test(name)) {
+    throw new Error(`Invalid header name "${name}": use a valid HTTP header token (letters, digits and -_).`);
+  }
+}
+function validateHeaderValue(name, value) {
+  if (/[\r\n]/.test(value)) {
+    throw new Error(`Invalid value for header "${name}": values must not contain CR/LF.`);
+  }
+  if (/\0/.test(value)) {
+    throw new Error(`Invalid value for header "${name}": values must not contain NUL bytes.`);
+  }
+}
+function parseHeaderArgument(raw) {
+  const separator = raw.indexOf(":");
+  if (separator === -1) {
+    if (/[\r\n]/.test(raw)) {
+      throw new Error(`Invalid header: names and values must not contain CR/LF.`);
+    }
+    throw new Error(`Invalid header \u2014 expected "Name: value" format (for example "Authorization: Bearer <token>").`);
+  }
+  const name = raw.slice(0, separator).trim();
+  const value = raw.slice(separator + 1).trim();
+  validateHeaderName(name);
+  validateHeaderValue(name, value);
+  return { [name.toLowerCase()]: value };
+}
+function parseHeaderPairs(raw) {
+  const result = {};
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    Object.assign(result, parseHeaderArgument(line));
+  }
+  return result;
+}
+function mergeHeaders(...sources) {
+  const result = {};
+  for (const source of sources) {
+    if (!source) continue;
+    for (const [name, value] of Object.entries(source)) {
+      if (/[\r\n]/.test(name) || /[\r\n]/.test(value)) {
+        throw new Error(`Invalid header "${name}": CR/LF is not allowed in header names or values.`);
+      }
+      result[name.toLowerCase()] = value;
+    }
+  }
+  return result;
+}
+
+// src/cli.ts
 function validateUrl(value) {
   try {
     const url = new URL(value);
@@ -25,11 +83,65 @@ function validateUrl(value) {
 function isInteractive() {
   return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
+function parseMaxBytes(value) {
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0 || !Number.isInteger(parsed)) {
+    throw new Error(`Invalid --max-bytes value: ${value}. Use a positive integer number of bytes.`);
+  }
+  return parsed;
+}
+function parseMaxTokens(value) {
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0 || !Number.isInteger(parsed)) {
+    throw new Error(`Invalid --max-tokens value: ${value}. Use a positive integer number of tokens.`);
+  }
+  return parsed;
+}
+function collectOption(value, previous) {
+  return [...previous ?? [], value];
+}
+function buildRequestHeaders(options) {
+  const fromEnv = process.env.SWAGGER_DIGEST_HEADER ? parseHeaderPairs(process.env.SWAGGER_DIGEST_HEADER) : {};
+  const fromFlags = (options.headers ?? []).map(parseHeaderArgument);
+  const cookieHeader = options.cookie !== void 0 ? parseHeaderArgument(`Cookie: ${options.cookie}`) : {};
+  return mergeHeaders(fromEnv, ...fromFlags, cookieHeader);
+}
 async function main() {
   const program = new Command();
-  program.name("swagger-digest").description("Convert a Swagger UI page or OpenAPI URL into compact, AI-friendly Markdown.").version("0.1.1").option("-u, --url <url>", "Swagger UI page URL or direct OpenAPI spec URL").option("-d, --out-dir <directory>", "Directory where the Markdown digest will be saved").option("-f, --filename <filename>", "Output filename (defaults to <api-title>-digest.md)").option("--no-browser", "Disable the optional Playwright headless-browser fallback").addHelpText(
+  program.name("swagger-digest").description("Convert a Swagger UI page or OpenAPI URL into compact, AI-friendly Markdown.").version(VERSION).option("-u, --url <url>", "Swagger UI page URL or direct OpenAPI spec URL").option("-d, --out-dir <directory>", "Directory where the Markdown digest will be saved").option("-f, --filename <filename>", "Output filename (defaults to <api-title>-digest.md)").option("--no-browser", "Disable the optional Playwright headless-browser fallback").option("--max-bytes <bytes>", "Maximum response size in bytes (default 10000000 = 10 MB)", "10000000").option(
+    '-H, --header <"Name: value">',
+    "Custom request header, repeatable. Sent only to the URL you supplied.",
+    collectOption,
+    []
+  ).option("--cookie <string>", "Convenience for a Cookie request header (same-origin scoping applies)").option("--include-tag <tag>", "Keep only operations with this tag, repeatable", collectOption, []).option("--exclude-tag <tag>", "Drop operations with this tag, repeatable", collectOption, []).option("--path-prefix <prefix>", "Keep only operations whose path starts with this prefix").option("--max-tokens <n>", "Trim the digest until the approximate token estimate fits this budget").option("--spec <url>", "Explicit OpenAPI spec URL; overrides discovery from the Swagger UI page").option("--stdout", "Print the digest to standard output instead of writing a file").addHelpText(
     "after",
-    "\nExamples:\n  npx swagger-digest\n  npx swagger-digest --url https://petstore.swagger.io/ --out-dir ./docs\n  npx swagger-digest -u https://example.com/openapi.yaml -f payments-api.md"
+    [
+      "",
+      "Examples:",
+      "  npx swagger-digest",
+      "  npx swagger-digest --url https://petstore.swagger.io/ --out-dir ./docs",
+      "  npx swagger-digest -u https://example.com/openapi.yaml -f payments-api.md",
+      '  npx swagger-digest -u https://api.example.com/swagger-ui -H "Authorization: Bearer <token>"',
+      "",
+      "Authentication:",
+      "  -H/--header and --cookie values are sent ONLY to the origin of --url.",
+      '  You can also set SWAGGER_DIGEST_HEADER with newline-separated "Name: value" pairs;',
+      "  -H flags override it on conflicts. Avoid passing secrets on the command line if",
+      "  your shell saves history \u2014 prefer the environment variable.",
+      "",
+      "Filtering and token budget:",
+      "  --include-tag/--exclude-tag/--path-prefix remove operations (and the data",
+      "  models only they referenced) before rendering.",
+      "  --max-tokens trims the digest in this order until the estimate fits:",
+      "  1. drop declared example payloads \u2192 2. shorten descriptions \u2192",
+      "  3. collapse parameter/response detail per tag (lowest-priority tag first:",
+      "  the tag that appears last in the document is collapsed first) \u2192",
+      '  4. keep only the Quick index entries. A "Trimmed" note records what was',
+      "  removed. The estimator is a heuristic, NOT tokenizer-accurate \u2014 treat the",
+      "  budget as a guide, not a guarantee."
+    ].join("\n")
   );
   program.parse(process.argv);
   const options = program.opts();
@@ -42,22 +154,45 @@ async function main() {
   });
   const validUrl = validateUrl(url);
   if (validUrl !== true) throw new Error(validUrl);
-  const outputDirectory = options.outDir ?? (isInteractive() ? await input({
+  if (options.stdout && (options.outDir !== void 0 || options.filename !== void 0)) {
+    throw new Error(
+      "--stdout cannot be combined with --out-dir or --filename: it prints the digest to standard output instead of writing a file. Drop --stdout, or remove --out-dir/--filename."
+    );
+  }
+  const outputDirectory = options.outDir ?? (isInteractive() && !options.stdout ? await input({
     message: "Destination directory",
     default: defaultOutputDirectory(),
     validate: (value) => value.trim() ? true : "Enter a destination directory."
   }) : defaultOutputDirectory());
+  const maxBytes = parseMaxBytes(options.maxBytes);
+  const requestHeaders = buildRequestHeaders(options);
   const spinner = ora({ text: "Fetching and parsing OpenAPI definition\u2026", color: "cyan" }).start();
   let result;
   try {
-    result = await fetchOpenApiSpec(url, { useBrowserFallback: options.browser !== false });
+    result = await fetchOpenApiSpec(url, {
+      useBrowserFallback: options.browser !== false,
+      maxBytes,
+      headers: requestHeaders,
+      specUrl: options.spec,
+      warn: (message) => console.error(chalk.yellow(`Warning: ${message}`))
+    });
   } catch (error) {
     spinner.fail("Could not extract an OpenAPI definition");
     throw error;
   }
   const title = typeof result.spec.info?.title === "string" ? result.spec.info.title : "API";
-  const markdown = transformOpenApiToMarkdown(result.spec, result.sourceUrl);
+  const markdown = transformOpenApiToMarkdown(result.spec, result.sourceUrl, {
+    includeTags: options.includeTag,
+    excludeTags: options.excludeTag,
+    pathPrefix: options.pathPrefix,
+    maxTokens: parseMaxTokens(options.maxTokens),
+    onWarning: (message) => console.error(chalk.yellow(`Warning: ${message}`))
+  });
   spinner.succeed(`Parsed ${title} (${result.retrievalMethod})`);
+  if (options.stdout) {
+    process.stdout.write(markdown);
+    return;
+  }
   const filename = options.filename ?? (isInteractive() ? await input({
     message: "Output filename",
     default: defaultFilename(title),
@@ -71,7 +206,8 @@ async function main() {
     const endpointCount = Object.values(result.spec.paths ?? {}).reduce((count, pathItem) => {
       if (!pathItem || typeof pathItem !== "object") return count;
       const methods = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
-      return count + methods.filter((method) => pathItem[method] && typeof pathItem[method] === "object").length;
+      const operations = pathItem;
+      return count + methods.filter((method) => operations[method] && typeof operations[method] === "object").length;
     }, 0);
     const modelCount = Object.keys(result.spec.components?.schemas ?? result.spec.definitions ?? {}).length;
     console.log("");
@@ -82,7 +218,7 @@ async function main() {
     }
     console.log(`  ${chalk.dim("\u2022")} Characters:      ${chalk.dim(report.characters.toLocaleString())}`);
     console.log("");
-    console.log(chalk.bold("Estimated token usage (5 Frontier Models):"));
+    console.log(chalk.bold("Estimated token usage (approximate):"));
     for (const model of Object.values(report.models)) {
       const windowLabel = model.contextWindow >= 1e6 ? `${model.contextWindow / 1e6}M` : `${model.contextWindow / 1e3}k`;
       const paddedName = `${model.name}:`.padEnd(30, " ");

package/dist/index.d.ts

@@ -2,6 +2,29 @@ type JsonObject = Record<string, any>;
 interface FetchOptions {
     timeoutMs?: number;
     useBrowserFallback?: boolean;
+    /** Maximum response body size in bytes (default 10 MB). */
+    maxBytes?: number;
+    /** Maximum number of redirects to follow (default 5). */
+    maxRedirects?: number;
+    /** Opt-in: reject hostnames resolving to private/loopback/metadata addresses. */
+    blockPrivateNetworks?: boolean;
+    /** Timeout for fallback-path probes (default 5000ms; main requests use timeoutMs). */
+    probeTimeoutMs?: number;
+    /**
+     * Custom request headers (e.g. Authorization or Cookie). These are sent ONLY
+     * to the origin of the URL passed to fetchOpenApiSpec; cross-origin requests
+     * (including cross-origin redirects and third-party browser requests) never
+     * receive them.
+     */
+    headers?: Record<string, string>;
+    /** Receives non-fatal notices, e.g. headers withheld on a cross-origin fetch. */
+    warn?: (message: string) => void;
+    /**
+     * Explicit spec URL that overrides discovery entirely: it is fetched first
+     * (with the same header scoping as the main URL) and the page is never
+     * consulted when it parses successfully.
+     */
+    specUrl?: string;
 }
 interface FetchResult {
     spec: JsonObject;
@@ -16,8 +39,24 @@ declare function parseSpecText(text: string, source?: string): JsonObject;
 declare function fetchOpenApiSpec(input: string, options?: FetchOptions): Promise<FetchResult>;
 
 declare function toTypeScriptIdentifier(value: string): string;
+
+interface TransformOptions {
+    /** Keep only operations carrying at least one of these tags. Repeatable. */
+    includeTags?: string[];
+    /** Drop operations carrying any of these tags. Repeatable. */
+    excludeTags?: string[];
+    /** Keep only operations whose path starts with this prefix. */
+    pathPrefix?: string;
+    /**
+     * Trim the digest until the (approximate, heuristic) token estimate fits this
+     * budget. The estimator is not tokenizer-accurate; treat the budget as a guide.
+     */
+    maxTokens?: number;
+    /** Receives non-fatal notices, e.g. unknown tag names. */
+    onWarning?: (message: string) => void;
+}
 /** Convert an OpenAPI 2.0, 3.0, or 3.1 document to a compact Markdown digest. */
-declare function transformOpenApiToMarkdown(spec: JsonObject, sourceUrl?: string): string;
+declare function transformOpenApiToMarkdown(spec: JsonObject, sourceUrl?: string, options?: TransformOptions): string;
 
 interface ModelTokenEstimate {
     name: string;
@@ -36,8 +75,9 @@ interface DigestTokenReport {
     };
 }
 /**
- * Estimates token counts for Markdown/code across 5 frontier model tokenizers.
- * Accurately models differences between cl100k/o200k, Claude BPE, SentencePiece 256k, and 128k BPE.
+ * Produces ROUGH token-count estimates for Markdown/code. The numbers are a
+ * heuristic (word + symbol density with per-model multipliers), not accurate
+ * tokenizer counts — use them as an order-of-magnitude guide only.
  */
 declare function estimateTokens(text: string): DigestTokenReport;
 
@@ -52,4 +92,4 @@ declare function writeDigest(options: {
 }): Promise<string>;
 
 export { defaultFilename, defaultOutputDirectory, estimateTokens, fetchOpenApiSpec, isOpenApiSpec, normalizeFilename, parseSpecText, resolveOutputDirectory, toTypeScriptIdentifier, transformOpenApiToMarkdown, writeDigest };
-export type { DigestTokenReport, FetchOptions, FetchResult, JsonObject, ModelTokenEstimate };
+export type { DigestTokenReport, FetchOptions, FetchResult, JsonObject, ModelTokenEstimate, TransformOptions };

package/dist/index.js

@@ -10,7 +10,7 @@ import {
   toTypeScriptIdentifier,
   transformOpenApiToMarkdown,
   writeDigest
-} from "./chunk-UZQM2SHL.js";
+} from "./chunk-CBSDTIKN.js";
 export {
   defaultFilename,
   defaultOutputDirectory,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "swagger-digest",
-  "version": "0.1.1",
-  "description": "Interactive CLI that converts Swagger UI pages and OpenAPI specs into compact Markdown for AI coding agents.",
+  "version": "0.1.2",
+  "description": "Turn Swagger UI pages and OpenAPI specs into compact, AI-friendly Markdown API digests.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,7 @@
     }
   },
   "bin": {
-    "swagger-digest": "dist/cli.js"
+    "swagger-digest": "./dist/cli.js"
   },
   "author": "VladLegkowski <VladLegkowski@users.noreply.github.com>",
   "repository": {
@@ -39,10 +39,10 @@
     "lint": "eslint .",
     "prepare": "husky",
     "prepack": "npm run build",
-    "prepublishOnly": "npm run build && npm test && npm run lint"
+    "prepublishOnly": "npm test"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20"
   },
   "dependencies": {
     "@inquirer/prompts": "^7.3.2",
@@ -73,14 +73,12 @@
     }
   },
   "keywords": [
-    "swagger",
     "openapi",
-    "cli",
-    "ai",
-    "llm",
+    "swagger",
     "markdown",
-    "docs",
-    "ai-coding-agent"
+    "llm",
+    "ai-coding-agent",
+    "cli"
   ],
   "license": "MIT"
 }