undici-proxy-env 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oratis
+
+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

@@ -0,0 +1,48 @@
+# undici-proxy-env
+
+Your OpenAI / Anthropic / any-SDK call **silently fails behind a proxy** — but `curl` works fine? It's because **Node's built-in `fetch` (undici) ignores `HTTPS_PROXY` / `HTTP_PROXY`.** One call fixes it — plus the two response-mangling gotchas that local proxies like **Clash** introduce.
+
+```bash
+npm i undici-proxy-env
+```
+
+```js
+import { configureProxyFromEnv } from "undici-proxy-env";
+
+// Call once, before any fetch/SDK use. Reads HTTPS_PROXY/HTTP_PROXY.
+configureProxyFromEnv();            // → true if a proxy is now in effect
+
+// ...now the Anthropic/OpenAI SDK, LangChain, plain fetch, etc. go through it.
+```
+
+## The three problems it solves
+
+**1. `fetch` ignores the proxy env vars.** Node's `http`-module clients and `curl` honor `HTTPS_PROXY`; `fetch`/undici do not. So the SDK (which uses `fetch`) times out or 403s behind a corporate/region proxy while everything else works. `configureProxyFromEnv()` installs a global undici `ProxyAgent` from the env — every subsequent `fetch` goes through it.
+
+**2. Clash strips `Content-Encoding` but sends gzip.** Some local proxies (Clash, others) drop the `Content-Encoding: gzip` header through CONNECT tunnels while still sending gzipped bytes — undici then hands your SDK **raw gzip** that fails to JSON-parse. We force `Accept-Encoding: identity` outbound so the upstream returns plain text.
+
+**3. Clash drops the response `Content-Type`.** Without it, an SDK treats a JSON body as a string and `messages.create()` returns text instead of a parsed object. `proxyAwareFetch` re-injects `application/json` when the body looks like JSON:
+
+```js
+import { configureProxyFromEnv, proxyAwareFetch } from "undici-proxy-env";
+import Anthropic from "@anthropic-ai/sdk";
+
+configureProxyFromEnv();
+const client = new Anthropic({ fetch: proxyAwareFetch }); // survives header-stripping proxies
+```
+
+(If your proxy doesn't strip headers you don't need `proxyAwareFetch` — the global agent from step 1 is enough. It's a safe pass-through either way.)
+
+## API
+
+| Export | What it does |
+|---|---|
+| `configureProxyFromEnv(opts?)` | Install the global proxy from env. `opts.url` forces a URL; `opts.log(msg)` gets a one-line notice. Idempotent. Returns `boolean` (is a proxy now active). |
+| `isProxyInstalled()` | `true` iff a proxy was installed. |
+| `proxyAwareFetch` | A `fetch` drop-in that repairs a missing response `Content-Type`. Pass as an SDK's `fetch` option. |
+
+Node ≥ 18. Zero config beyond the standard `HTTPS_PROXY` / `HTTP_PROXY` env vars.
+
+## License
+
+MIT © oratis

package/index.d.ts

@@ -0,0 +1,24 @@
+export interface ConfigureProxyOptions {
+  /** Force a specific proxy URL instead of reading the environment. */
+  url?: string;
+  /** Called with a one-line notice when a proxy is installed (or fails to). */
+  log?: (message: string) => void;
+}
+
+/**
+ * Install a global undici ProxyAgent from HTTPS_PROXY / HTTP_PROXY (and lowercase
+ * variants), forcing `Accept-Encoding: identity` on outbound requests. No-op and
+ * returns `false` if no proxy is configured. Idempotent.
+ * @returns whether a proxy is now in effect.
+ */
+export function configureProxyFromEnv(opts?: ConfigureProxyOptions): boolean;
+
+/** True iff configureProxyFromEnv installed a proxy. */
+export function isProxyInstalled(): boolean;
+
+/**
+ * A `fetch` drop-in that re-injects a missing `application/json` response
+ * Content-Type (a Clash CONNECT-tunnel artifact) so SDKs parse JSON instead of
+ * returning a string. Pass-through when no proxy is installed.
+ */
+export const proxyAwareFetch: typeof fetch;

package/index.mjs

@@ -0,0 +1,78 @@
+// undici-proxy-env — make Node's built-in fetch honor HTTP(S)_PROXY, and survive
+// the response-mangling that local proxies (Clash, some corporate proxies) do.
+//
+// Node's global `fetch` (undici) does NOT read HTTPS_PROXY / HTTP_PROXY. So an
+// SDK that uses fetch under the hood (Anthropic, OpenAI, many others) silently
+// fails behind a proxy even when your shell `curl` works. Call
+// configureProxyFromEnv() once at startup to bridge that.
+//
+// Two real-world proxy artifacts are handled:
+//  1. Some proxies strip `Content-Encoding: gzip` on CONNECT tunnels but still
+//     send gzipped bytes — undici then hands the SDK raw gzip that fails to
+//     JSON-parse. We force `Accept-Encoding: identity` outbound to avoid it.
+//  2. Some proxies drop the response `Content-Type` header — an SDK then treats
+//     a JSON body as text and returns a string instead of a parsed object.
+//     `proxyAwareFetch` re-injects `application/json` when the body looks like JSON.
+import { ProxyAgent, setGlobalDispatcher } from "undici";
+
+let installed = false;
+
+class IdentityEncodingProxyAgent extends ProxyAgent {
+  dispatch(opts, handler) {
+    const incoming = opts.headers ?? {};
+    const merged = {};
+    if (Array.isArray(incoming)) {
+      for (let i = 0; i < incoming.length; i += 2) merged[String(incoming[i]).toLowerCase()] = String(incoming[i + 1]);
+    } else if (typeof incoming === "object") {
+      for (const [k, v] of Object.entries(incoming)) merged[k.toLowerCase()] = Array.isArray(v) ? v.join(", ") : String(v);
+    }
+    merged["accept-encoding"] = "identity";
+    return super.dispatch({ ...opts, headers: merged }, handler);
+  }
+}
+
+/**
+ * Install a global undici ProxyAgent from HTTPS_PROXY/HTTP_PROXY (and lowercase
+ * variants). No-op + returns false if none is set. Idempotent. Pass `{ url }` to
+ * force a specific proxy, or `{ log }` to get a one-line notice.
+ * @returns {boolean} whether a proxy is now in effect.
+ */
+export function configureProxyFromEnv(opts = {}) {
+  const url =
+    opts.url ??
+    process.env.HTTPS_PROXY ?? process.env.https_proxy ??
+    process.env.HTTP_PROXY ?? process.env.http_proxy;
+  if (!url) return false;
+  if (installed) return true;
+  try {
+    setGlobalDispatcher(new IdentityEncodingProxyAgent(url));
+    installed = true;
+    opts.log?.(`[proxy] outbound fetch routed through ${url} (Accept-Encoding=identity)`);
+    return true;
+  } catch (err) {
+    opts.log?.(`[proxy] failed to install ProxyAgent for ${url}: ${(err && err.message) || err}`);
+    return false;
+  }
+}
+
+/** True iff configureProxyFromEnv installed a proxy. */
+export function isProxyInstalled() {
+  return installed;
+}
+
+/**
+ * A `fetch` drop-in that repairs a missing response Content-Type (a Clash CONNECT
+ * artifact) so SDKs parse JSON instead of returning a string. Safe when no proxy
+ * is installed — it passes through untouched. Pass it as an SDK's `fetch` option.
+ * @type {typeof fetch}
+ */
+export const proxyAwareFetch = async (input, init) => {
+  const r = await fetch(input, init);
+  if (!installed) return r;
+  if (r.headers.get("content-type")) return r;
+  const text = await r.text();
+  const looksJson = text.trimStart().startsWith("{") || text.trimStart().startsWith("[");
+  const headers = new Headers(r.headers);
+  if (looksJson) headers.set("content-type", "application/json");
+  return new Response(text, { status: r.status, statusText: r.statusText, headers });
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "undici-proxy-env",
+  "version": "1.0.0",
+  "description": "Make Node's built-in fetch honor HTTP(S)_PROXY — and survive the Clash/corporate-proxy response mangling that silently breaks LLM SDKs.",
+  "type": "module",
+  "main": "index.mjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.mjs"
+    }
+  },
+  "files": [
+    "index.mjs",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "undici",
+    "fetch",
+    "proxy",
+    "https_proxy",
+    "http_proxy",
+    "clash",
+    "anthropic",
+    "openai",
+    "llm",
+    "node"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "undici": "^8.5.0"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "license": "MIT",
+  "author": "oratis",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oratis/undici-proxy-env.git"
+  },
+  "homepage": "https://github.com/oratis/undici-proxy-env#readme"
+}