!feat: use fetch instead of superagent (closes #552)

.github/workflows/ci.yml

@@ -11,9 +11,9 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: extractions/setup-just@v3
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@v7
+      - uses: extractions/setup-just@v4
+      - uses: actions/setup-node@v7
         with:
           node-version: 24
       - run: EASYPOST_TEST_API_KEY=123 EASYPOST_PROD_API_KEY=123 just install install-styleguide build test
@@ -23,25 +23,25 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [16.x, 17.x, 18.x, 19.x, 20.x, 21.x, 22.x, 23.x, 24.x, 25.x]
+        node-version: [18.x, 19.x, 20.x, 21.x, 22.x, 23.x, 24.x, 25.x, 26.x]
     steps:
-      - uses: actions/checkout@v6
-      - uses: extractions/setup-just@v3
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@v7
+      - uses: extractions/setup-just@v4
+      - uses: actions/setup-node@v7
         with:
           node-version: 24
       - run: EASYPOST_TEST_API_KEY=123 EASYPOST_PROD_API_KEY=123 just install install-styleguide build
-      - uses: actions/setup-node@v6
+      - uses: actions/setup-node@v7
         with:
           node-version: ${{ matrix.node-version }}
       - run: EASYPOST_TEST_API_KEY=123 EASYPOST_PROD_API_KEY=123 just test-node-compatibility
   # typescript checks that the our Typescript definitions can be compiled without errors
   typescript:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: extractions/setup-just@v3
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@v7
+      - uses: extractions/setup-just@v4
+      - uses: actions/setup-node@v7
         with:
           node-version: 24
       - run: |
@@ -52,18 +52,18 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: extractions/setup-just@v3
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@v7
+      - uses: extractions/setup-just@v4
+      - uses: actions/setup-node@v7
         with:
           node-version: 24
       - run: just install install-styleguide build lint
   coverage:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: extractions/setup-just@v3
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@v7
+      - uses: extractions/setup-just@v4
+      - uses: actions/setup-node@v7
         with:
           node-version: 24
       - run: just install install-styleguide build
@@ -77,9 +77,9 @@ jobs:
     if: github.ref == 'refs/heads/master'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: extractions/setup-just@v3
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@v7
+      - uses: extractions/setup-just@v4
+      - uses: actions/setup-node@v7
         with:
           node-version: 24
       - name: Install Dependencies

CHANGELOG.md

@@ -2,7 +2,15 @@
 
 ## v9.0.0 (Unreleased)
 
+- Breaking: Node 18+ is now required (built-in `fetch`)
 - Breaking: API resource responses are now plain JSON-compatible objects rather than model class instances
+- Breaking: HTTP transport migrated from `superagent` to fetch-compatible transport
+  - `superagent` runtime dependency removed
+  - Breaking: `superagentMiddleware` renamed to `httpMiddleware`
+  - Breaking: `fetchClient` renamed to `httpClient`
+  - Breaking: `makeApiCall` now accepts `delete` (the `del` alias was removed)
+  - `requestMiddleware` compatibility preserved using a fetch-era compatibility request object
+  - Default `User-Agent` retains structured runtime metadata fields (`Nodejs/`, `OS/`, `OSVersion/`, `OSArch/`) via runtime-safe detection
 
 ## v8.9.0 (2026-06-25)
 

README.md

@@ -111,7 +111,8 @@ const client = new EasyPostClient(process.env.EASYPOST_API_KEY, {
   timeout: 120000,
   baseUrl: 'https://api.easypost.com/v2/',
   useProxy: false,
-  superagentMiddleware: (s) => s,
+  httpMiddleware: (f) => f,
+  httpClient: fetch,
   requestMiddleware: (r) => r,
 });
 ```
@@ -130,30 +131,35 @@ from a frontend through a server.
 Disable using the API key. Useful if you proxy requests from a frontend through
 a server.
 
-#### superagentMiddleware
+#### httpMiddleware
 
-Function that takes `superagent` and returns `superagent`. Useful if you need
-to wrap superagent in a function, such as many superagent libraries do.
+Function that wraps the underlying HTTP transport function.
 
 ```javascript
-import superagentLib from 'some-superagent-lib';
+const wrapFetch = (f) => (input, init) => {
+  // custom behavior here
+  return f(input, init);
+};
 
 const client = new EasyPostClient('my-key', {
-  superagentMiddleware: (s) => superagentLib(s),
+  httpMiddleware: wrapFetch,
 });
 ```
 
+#### httpClient
+
+Function used for HTTP requests. Defaults to built-in `fetch` (Node 18+).
+You can override this for custom environments, testing, or instrumentation.
+
 #### requestMiddleware
 
-Function that takes a superagent `request` and returns that request. Useful if
-you need to hook into a request:
+Function that takes a compatibility request object and returns it. Existing
+middleware patterns that use `auth`, `query`, and `send` are still supported.
 
 ```javascript
-import superagentLib from 'some-superagent-lib';
-
 const client = new EasyPostClient('my-key', {
   requestMiddleware: (r) => {
-    r.someLibFunction(SOME_CONFIG_VALUE);
+    r.set({ 'X-Custom-Header': 'my-value' });
     return r;
   },
 });

UPGRADE_GUIDE.md

@@ -14,6 +14,7 @@ Use the following guide to assist in the upgrade process of the `easypost-node`
 ### 9.0 High Impact Changes
 
 - [Response Objects Are Now Plain JSON Objects](#90-response-objects-are-now-plain-json-objects)
+- [HTTP Transport Migrated to Fetch](#90-http-transport-migrated-to-fetch)
 
 ### 9.0 Response Objects Are Now Plain JSON Objects
 
@@ -30,6 +31,42 @@ const boughtShipment = await client.Shipment.buy(shipment.id, shipment.lowestRat
 
 This change improves compatibility with serializers and SSR frameworks that require plain objects.
 
+### 9.0 HTTP Transport Migrated to Fetch
+
+Likelihood of Impact: **Medium**
+
+The internal HTTP transport has moved from `superagent` to `fetch`.
+
+What stayed compatible:
+
+- Existing service APIs are unchanged.
+- `requestMiddleware` is still supported via a compatibility request object.
+
+What changed:
+
+- `superagent` is no longer a runtime dependency.
+- Node 18+ is now required (built-in `fetch`).
+- `superagentMiddleware` has been removed and replaced by `httpMiddleware`.
+- `fetchClient` has been renamed to `httpClient`.
+- `makeApiCall` now uses `delete` only (the `del` alias was removed).
+- Middleware relying on superagent-only request internals (private properties or plugin APIs) must be updated.
+- The default `User-Agent` retains the prior structured format (`Nodejs/`, `OS/`, `OSVersion/`, `OSArch/`) while collecting values in a runtime-safe way.
+
+Migration examples:
+
+```javascript
+// After
+const client = new EasyPostClient('api_key', {
+  httpMiddleware: (httpFn) => httpFn,
+  httpClient: fetch,
+});
+```
+
+```javascript
+// Updated method name
+await client.makeApiCall('delete', '/trackers/trk_123');
+```
+
 ## Upgrading from 7.x to 8.0
 
 ### 8.0 High Impact Changes