minifetch-api 1.3.4 → 1.4.0

package/README.md

@@ -5,19 +5,17 @@
   </a>
 </div>
 
-**[Minifetch](https://minifetch.com) is a hosted toolkit of extraction primitives for SEO/ GEO/ AEO.** Run them as a full technical audit or call one at a time for a fraction of the price — and a fraction of the LLM tokens. No subscription.
+**[Minifetch](https://minifetch.com) is a hosted toolkit of web page extraction primitives.** Run them as a full technical SEO audit or call one at a time for a fraction of the price — and a fraction of the LLM tokens. No subscription.
 
 - ✅ **Always pay-per-fetch at competitive prices.**
 - ✅ [Sign up](https://minifetch.com/dashboard) for an account & get free starter credits. 🎉🎉
 - ⛔ No charge for blocked pages (403 errors).
 
 ---
+
 **👉 [Full API docs](https://minifetch.com/docs/api) | [LLMs.txt](https://minifetch.com/llms.txt) and [SKILL.md](https://minifetch.com/SKILL.md) for agents | Questions? Join our [Discord](https://discord.gg/EM6ET8Dshm)**
 
 ---
-**Payments.** Two ways to pay:
-1. Credit card + API key. Get started free - [visit our dashboard to Sign Up](https://minifetch.com/dashboard). Create a Minifetch account and it will be auto-loaded with 25 free technical SEO page audits. Top up with your credit card later.
-2. USDC on Base or Solana. Just load your wallet with USDC, you're ready. No "gas token" (ETH or SOL) required. You don't need a Minifetch account either, just load your wallet and go!
 
 ## Prerequisites
 
@@ -25,9 +23,15 @@
 - A valid API key from our [dashboard](https://minifetch.com/dashboard)
 - ***Or*** an Ethereum or Solana private key for making USDC payments on Base or Solana networks.
 
-## Install
+**Payments.** Two ways to pay:
+1. Credit card + API key. Get started free - [visit our dashboard to Sign Up](https://minifetch.com/dashboard). Create a Minifetch account and it will be auto-loaded with 25 free technical SEO page audits. Top up with your credit card later.
+2. USDC on Base or Solana. Just load your wallet with USDC, you're ready. No "gas token" (ETH or SOL) required. You don't need a Minifetch account either, just load your wallet and go!
 
-`npm install minifetch-api --save`
+## Install
+Add to your project:
+```
+npm install minifetch-api --save`
+```
 
 ## Quick Start
 
@@ -66,7 +70,7 @@ try {
 
 After the Quick Start, you have the following methods to use.
 
-**Wrap** these methods in a **try/catch** just like in the Quick Start example above. **Code examples** can be also found in the [Github repository](https://github.com/Niche-Networks/minifetch-api/) /example- directories.
+**Wrap** these methods in a **try/catch** just like in the Quick Start example above. **Code examples** can be also found in the [Github repository /example- directories](https://github.com/Niche-Networks/minifetch-api/).
 
 The `checkAndExtract` methods check the target URL's `robots.txt` file to ensure its not blocked and tell us your preferred crawl delay (defaults to 1 second between requests to your domain). So fetching 10 URLs takes at least 10 seconds to complete by default. This is by design, so Minifetch never hammers your server or slows it down for your real users. If the URL is blocked, read [How To Unblock Minifetch](https://minifetch.com/tutorials/unblock-minifetch).
 
@@ -82,15 +86,15 @@ await client.checkAndRunSeoPageAudit(url);
 
 await client.checkAndExtractUrlMetadata(url, options);
 // Price: $0.002
-// Extracts rich structured metadata from your URL: favicons, title,
-// description, canonical, SEO-related meta tags, Open Graph and
-// Twitter card tags, JSON-LD and more.
-// Set verbosity option to full for more fields: redirect chain,
-// relevant response headers, performance metrics, headings, images
-// and every meta tag found on the page; verbosity "full" is the
-// drop-in replacement for the npm `url-metadata` package.
+// Extracts rich structured metadata from your URL: redirects, favicons,
+// title, description, canonical, SEO-related meta tags, Open Graph and
+// Twitter card tags, JSON-LD and more. Returns everything by default;
+// narrow the response with the `fields` query param (pass atomic field
+// names, ex: ?fields=title,description or the named groups: network,meta,
+// og,twitter and/or meta:<name> for a specific page meta tag)
 // Options:
-// { verbosity: "full" } - defaults to "standard"
+// { fields: ['canonical', 'og:url'] } - narrows to custom selected fields
+// { omitEmpty: true } - defaults to false
 // { includeResponseBody: true } - defaults to false
 
 await client.checkAndExtractUrlLinks(url);
@@ -125,10 +129,14 @@ await client.extractUrlLinks(url);
 await client.extractUrlPreview(url);
 await client.extractUrlContent(url, options); // same options as above
 ```
+
 ---
+
 ### Error Types
-When you wrap the functions above in a try/catch, here are the errors you may encounter. You are never charged for URLs that are blocked or error.
+When you wrap the functions above in a try/catch, here are some of the errors you may encounter. You are never charged for URLs that are blocked or error.
 
+- **"InvalidURLError: Invalid url ${url}"**
+  - The URL is malformed in some way, correct it and try again.
 - **"RobotsBlockedError: URL is blocked by robots.txt"**
   - Minifetch is explicitly blocked by the website's `robots.txt`, cannot be fetched. If this is your site, read our tutorial [How To Unblock Minifetch](https://minifetch.com/tutorials/unblock-minifetch)
 - **"Network Error: 402 Payment Required"**
@@ -139,9 +147,9 @@ When you wrap the functions above in a try/catch, here are the errors you may en
   - URLs that pass their robots.txt check but are blocked anyway via 403 or other tactics may error like this. No charge.
 - **"503 Service Temporarily Unavailable"**
   - Likely encountering upstream timeout errors on the target URL.
-- **"InvalidURLError: Invalid url ${url}"**
-  - The URL is malformed in some way, correct it and try again.
+
 ---
+
 ### Service Limitations
 Minifetch only extracts publicly available metadata and content from pages accessible without authentication and javascript execution.
 
@@ -156,6 +164,7 @@ What Minifetch does NOT do *currently* but may offer in the future as an add-on:
 - Access authenticated or logged-in content
 
 ---
+
 ### USDC Best Practices
 - Uses the [x402 Protocol](https://www.x402.org/). No "gas token" (ETH or SOL) required, just load your wallet with USDC on Base or Solana network.
 - LLMs & Agents should *never* have direct access to your private key. They *will* expose it!
@@ -164,6 +173,7 @@ What Minifetch does NOT do *currently* but may offer in the future as an add-on:
 - Pass your private key into the Minifetch API Client with an [environment variable](https://developer.vonage.com/en/blog/how-to-use-environment-variables-in-javascript-with-dotenv).
 
 ---
+
 **License**
 
 MIT / Copyright (c) 2026 Lauren Garcia

package/dist/esm/client.js

@@ -67,7 +67,8 @@ export class MinifetchClient {
      *
      * @param url
      * @param options
-     * @param options.verbosity - "standard" (default) or "full"
+     * @param options.fields
+     * @param options.omitEmpty
      * @param options.includeResponseBody
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
@@ -78,8 +79,10 @@ export class MinifetchClient {
         try {
             const normalizedUrl = validateAndNormalizeUrl(url);
             const params = new URLSearchParams({ url: normalizedUrl });
-            if (options?.verbosity)
-                params.set("verbosity", options.verbosity);
+            if (options?.fields?.length)
+                params.set("fields", options.fields.join(","));
+            if (options?.omitEmpty)
+                params.set("omitEmpty", "true");
             if (options?.includeResponseBody)
                 params.set("includeResponseBody", "true");
             const requestUrl = `${this.baseUrl}${this._paidPath("/extract/url-metadata")}?${params.toString()}`;
@@ -167,7 +170,8 @@ export class MinifetchClient {
      *
      * @param url
      * @param options
-     * @param options.verbosity - "standard" (default) or "full"
+     * @param options.fields
+     * @param options.omitEmpty
      * @param options.includeResponseBody
      */
     async checkAndExtractUrlMetadata(url, options) {

package/dist/esm/utils/payment.js

@@ -42,7 +42,8 @@ export async function handlePayment(url, config) {
         const fetchWithPayment = wrapFetchWithPayment(fetch, _x402Client);
         const response = await fetchWithPayment(url, { method: "GET" });
         if (!response.ok) {
-            throw new NetworkError(`Request failed: ${response.status} ${response.statusText}`);
+            const serverMessage = await readServerErrorMessage(response);
+            throw new NetworkError(`Request failed: ${response.status} ${response.statusText}${serverMessage ? ` — ${serverMessage}` : ""}`);
         }
         const httpClient = new x402HTTPClient(_x402Client);
         const paymentResponse = httpClient.getPaymentSettleResponse(name => response.headers.get(name));
@@ -79,7 +80,8 @@ export async function handleApiKeyRequest(url, config) {
         },
     });
     if (!response.ok) {
-        throw new NetworkError(`Request failed: ${response.status} ${response.statusText}`);
+        const serverMessage = await readServerErrorMessage(response);
+        throw new NetworkError(`Request failed: ${response.status} ${response.statusText}${serverMessage ? ` — ${serverMessage}` : ""}`);
     }
     return { response };
 }
@@ -101,3 +103,19 @@ function getExplorerLink(config, txHash) {
         return "";
     }
 }
+/**
+ * Best-effort read of the rich server error message from a non-ok response.
+ * Minifetch error bodies carry it at results[0].error.message.
+ *
+ * @param response - non-ok Response (body is consumed)
+ */
+async function readServerErrorMessage(response) {
+    try {
+        const body = (await response.json());
+        // TODO: revisit this approach when we scale up to multiple results per request
+        return body?.results?.[0]?.error?.message;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/types/client.d.ts

@@ -36,7 +36,8 @@ export declare class MinifetchClient {
      *
      * @param url
      * @param options
-     * @param options.verbosity - "standard" (default) or "full"
+     * @param options.fields
+     * @param options.omitEmpty
      * @param options.includeResponseBody
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
@@ -44,7 +45,8 @@ export declare class MinifetchClient {
      * @throws {NetworkError} various reasons, check README
      */
     extractUrlMetadata(url: string, options?: {
-        verbosity?: "standard" | "full";
+        fields?: string[];
+        omitEmpty?: boolean;
         includeResponseBody?: boolean;
     }): Promise<PaidEndpointResponse>;
     /**
@@ -94,11 +96,13 @@ export declare class MinifetchClient {
      *
      * @param url
      * @param options
-     * @param options.verbosity - "standard" (default) or "full"
+     * @param options.fields
+     * @param options.omitEmpty
      * @param options.includeResponseBody
      */
     checkAndExtractUrlMetadata(url: string, options?: {
-        verbosity?: "standard" | "full";
+        fields?: string[];
+        omitEmpty?: boolean;
         includeResponseBody?: boolean;
     }): Promise<PaidEndpointResponse>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minifetch-api",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "description": "Minifetch.com API Client. Pay-per-URL SEO audits. Composable toolkit for AI agents and automation pipelines.",
   "type": "module",
   "main": "./dist/esm/index.js",