minifetch-api 1.1.0 → 1.2.0

package/README.md

@@ -5,18 +5,27 @@
   </a>
 </div>
 
-**Fetch & extract data from web pages.** [Minifetch.com](https://minifetch.com) provides composable extraction APIs that humans and AI Agents can autonomously discover, orchestrate, and pay for— making web pages simple to access. Pay-as-you-go at competitive prices.
+**Fetch & extract data from web pages.** [Minifetch.com](https://minifetch.com) provides composable extraction APIs for humans and AI Agents-- making web pages simple to access.
+
+- **✅ [Sign up](https://minifetch.com/dashboard) for an account and get your first 125-250 fetches for free. 🎉🎉**
+- ✅ Always pay-as-you-go at competitive prices.
+- ⛔ No charge for blocked pages (403 errors).
+
+---
+**👉 [Dashboard](https://minifetch.com/dashboard) | [Full API docs](https://minifetch.com/docs/api) | [LLMs.txt](https://minifetch.com/llms.txt) | Questions? Join our [Discord]([Discord](https://discord.gg/EM6ET8Dshm))**
 
-**Full [API docs are here](https://minifetch.com/docs/api)**, including example queries, response data & prices. For AI Agents, read the [LLMs.txt](https://minifetch.com/llms.txt) instead.
 
-**Payments** work with [x402](https://www.x402.org/) USDC stablecoin micropayments on Coinbase's Base & Solana blockchain networks. Transaction fees are free. If you'd like to use a traditional credit card & API key instead, sign up for the waitlist: [forms.gle/rkMi7T23bHJc8XFw9](https://forms.gle/rkMi7T23bHJc8XFw9)
 
-**Bulk fetch and extract** for building datasets is coming soon, sign up for the waitlist: [forms.gle/rkMi7T23bHJc8XFw9](https://forms.gle/rkMi7T23bHJc8XFw9)
+---
+**Payments.** Two ways to pay:
+1. Credit card + API key. Get started free - [visit our dashboard to Sign Up](https://minifetch.com/dashboard). Your account will be auto-loaded with 125–250 API calls. Top up with your credit card later.
+2. x402. USDC stablecoin micropayments on Coinbase's Base & Solana networks.
 
 ## Prerequisites
 
 - Node.js v18+ & NPM
-- A valid Ethereum or Solana private key for making USDC payments.
+- 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
 
@@ -27,82 +36,95 @@
 ```js
 import Minifetch from "minifetch-api";
 
-// Inititialize the client with your network choice & private key.
+// First, initialize the client with your payment choice:
+
+// 1. API Key Payments:
+const client = new Minifetch({
+  apiKey: process.env.MINIFETCH_API_KEY
+});
+
+// 2. x402 Payments:
 //   - Network options: "base" or "solana"
-//   - Use private key from account that has a small amt of USDC
+//   - Private key from wallet that has a small amt of USDC
 const client = new Minifetch({
   network: "base",
   privateKey: process.env.BASE_PRIVATE_KEY,
 });
 
+// Now you're ready to extract data from a url:
 try {
   const url = "example.com";
-  const response = await client.checkAndExtractPreview(url);
-  // 200 "ok" responses will return the data and x402 payment info:
+  const response = await client.checkAndExtractUrlPreview(url);
+  // 200 "ok" responses
   console.log("data: ", response.data);
-  console.log("payment info: ", response.payment);
 } catch (err) {
-  // No payment or charges for errors!
+  // No charge for errors or 403 blocked urls!
   console.log(err);
 }
 ```
 
-### Client Methods Available
-
-After you initialize the client (above), you have the following methods available to use. The "checkAndExtract" API methods provided help you avoid paying for blocked URLs and return more granular info about why a URL may or may not return data. There is no charge for blocked upstream URLs.
-
-**Price list** and example data for each method [is here.](https://minifetch.com/docs/api#example-data)
-
-**Rate limit** Requests exceeding rate limits return `503` errors. This is intentional — back off and retry, max 5-10 queries per second. We'll add bulk fetch and extract in the future. Sign up for the [waitlist](https://forms.gle/rkMi7T23bHJc8XFw9).
-
-**Code examples** can be found in the github repository under /test.
+### Data Extraction Methods
 
-- **`client.checkAndExtractUrlPreview(url)`**
-  - Extracts a light, token-efficient preview of a URL: title, description, and image (only).
+After the Quick Start, you have the following methods to use. The "checkAndExtract" methods help to avoid paying for blocked URLs. **Price list** & example data [is here.](https://minifetch.com/docs/api#example-data)
 
-- **`client.checkAndExtractUrlContent(url, options)`**
-  - Extracts a clean, token-efficient content summary as markdown from a URL. Removes ads, nav, scripts. Much more efficient than raw HTML fetches for LLMs.
-  - Option: `{ includeMediaUrls: true }`, defaults to false
+**Wrap** these in a **try/catch** just like in the Quickstart example above. **Code examples** can be also found in the [Github repository](https://github.com/Niche-Networks/minifetch-api/) in the /example- directories.
 
-- **`client.checkAndExtractUrlLinks(url)`**
-  - Extracts all links from a URL categorized by type (internal/external/anchor) with SEO metadata. Detects image links, nofollow attributes, and analyzes external domain distribution.
-
-- **`client.checkAndExtractUrlMetadata(url, options)`**
-  - Extracts rich structured metadata from a URL: title, description, og/twitter tags, json-ld, images, headings, response headers, and more. Perfect for SEO research or metadata indexing & analysis. Largest response size of the client methods available. Calling this method and setting verbosity to "full" is the drop-in replacement for the [`url-metadata`](https://www.npmjs.com/package/url-metadata) package.
-  - Option: `{ verbosity: "full" }`, defaults to "standard"
-  - Option: `{ includeResponseBody: true }`, defaults to false
-
-***For maximum control, you can also use the following methods directly:***
-
-- **`client.preflightCheck(url)`**
-  - Standalone call to check if a URL is allowed to be fetched according to the website's robots.txt file. Use this free endpoint before using our other paid endpoints to help avoid spending extra on un-fetchable URLs
-- **`client.extractUrlPreview(url)`**
-- **`client.extractUrlContent(url, options)`**
-  - Option: `{ includeMediaUrls: true }`, defaults to false
-- **`client.extractUrlLinks(url)`**
-- **`client.extractUrlMetadata(url, options)`**
-  - Option: `{ verbosity: "full" }`, defaults to "standard"
-  - Option: `{ includeResponseBody: true }`, defaults to false
+```js
+// Extracts a light, token-efficient preview of a URL:
+// title, description, and image (only).
+client.checkAndExtractUrlPreview(url);
+
+// Extracts a clean, token-efficient content summary as markdown from a URL.
+// Removes ads, nav, scripts. More efficient than raw HTML fetches for LLMs.
+// Options:
+// { includeMediaUrls: true }, defaults to false.
+client.checkAndExtractUrlContent(url, options);
+
+// Extracts all links from a URL categorized by type (internal/external/anchor).
+// Detects image links, nofollow attributes, analyzes external domain distribution.
+client.checkAndExtractUrlLinks(url);
+
+// Extracts rich structured metadata from a URL:
+// meta tags, json-ld, images, headings, response headers, + more.
+// Perfect for SEO research or metadata indexing & analysis. Largest
+// response size of client methods. Setting verbosity to "full" is the drop-in
+// replacement for the [`url-metadata`](https://www.npmjs.com/package/url-metadata) package.
+// Options:
+// { verbosity: "full" }, defaults to "standard"
+// { includeResponseBody: true }, defaults to false
+client.checkAndExtractUrlMetadata(url, options);
+
+// For max control, you can also use the following methods directly.
+// Free - check robots.txt:
+client.preflightCheck(url);
+// Extract data:
+client.extractUrlPreview(url);
+client.extractUrlContent(url, options); // same options as above
+client.extractUrlLinks(url);
+client.extractUrlMetadata(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:
+When you wrap the functions above in a try/catch, here are the errors you may encounter. You are never charged for errors.
 
 - **"RobotsBlockedError: URL is blocked by robots.txt"**
-  - URL is explicitly blocked by the website's robots.txt will error like this.
+  - URL is explicitly blocked by the website's robots.txt, cannot be fetched.
 - **"Network Error: 402 Payment Required"**
   - Check your wallet -- likely you ran out of USDC to pay!
+- **"Network Error: 429 Too Many Requests"**
+  - Back off and retry, max 5-10 requests per second.
 - **"Network Error: 502 Bad Gateway"**
-  - URLs that pass the robots.txt check but are blocked anyway via 403 or other tactics may error like this.
+  - URLs that pass their robots.txt check but are blocked anyway via 403 or other tactics may error like this.
 - **"503 Service Temporarily Unavailable"**
-  - Likely encountering Minifetch rate-limiting or upstream timeout errors on the target URL. You may try again but limit requests to 5-10 at a time. Bulk fetches coming soon.
+  - Likely encountering upstream timeout errors on the target URL.
 - **"InvalidURLError: Invalid url ${url}"**
-  - The URL you passed in is malformed in some way, correct it and try again.
-
+  - 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.
 
-What Minifetch does NOT do:
-
+What Minifetch does *NOT* do:
 - Ignore robots.txt directives
 - Access authenticated or logged-in content
 - Create accounts or log into user sessions
@@ -112,8 +134,8 @@ What Minifetch does NOT do:
 What Minifetch does NOT do *currently* but may offer in the future as an add-on:
 - Javascript execution
 
-## x402 Best Practices
-
+---
+### x402 Best Practices
 - LLMs & Agents should *never* have direct access to your private key. They *will* expose it!
 - Only keep a small amount of USDC in the account whose private key you use.
 - Keep that account separate from the rest of your onchain funds.

package/dist/esm/client.js

@@ -1,24 +1,25 @@
 import { initConfig } from "./init.js";
 import { validateAndNormalizeUrl } from "./utils/validation.js";
-import { handlePayment } from "./utils/payment.js";
+import { handlePayment, handleApiKeyRequest } from "./utils/payment.js";
 import { InvalidUrlError, RobotsBlockedError, PaymentFailedError, ExtractionFailedError, NetworkError, } from "./types/errors.js";
 /**
- * Main Minifetch API client
- * Provides methods to check URLs and extract metadata/links/preview/content
+ * Main Minifetch API client.
+ * Supports two auth modes:
+ *   - x402: crypto micropayments via Coinbase x402 (pass network + privateKey)
+ *   - apiKey: Stripe-backed credits (pass apiKey: "mf_prod_..." or "mf_dev_...")
  */
 export class MinifetchClient {
     config;
     baseUrl;
     /**
-     *
-     * @param config
+     * @param config - Either { network, privateKey } for x402 or { apiKey } for API key auth
      */
     constructor(config) {
         this.config = initConfig(config);
         this.baseUrl = this.config.apiBaseUrl;
     }
     /**
-     * Check if URL is allowed by robots.txt (free preflight check)
+     * Check if URL is allowed by robots.txt (free preflight check — no auth required)
      *
      * @param url
      * @throws {InvalidUrlError} if URL is invalid
@@ -26,17 +27,13 @@ export class MinifetchClient {
      */
     async preflightUrlCheck(url) {
         try {
-            // Validate and normalize URL
             const normalizedUrl = validateAndNormalizeUrl(url);
-            // Build request URL (free endpoint, no payment)
-            const endpoint = `/api/v1/free/preflight/url-check?url=${encodeURIComponent(normalizedUrl)}`;
-            const requestUrl = `${this.baseUrl}${endpoint}`;
+            const requestUrl = `${this.baseUrl}/api/v1/free/preflight/url-check?url=${encodeURIComponent(normalizedUrl)}`;
             const response = await fetch(requestUrl);
             if (!response.ok) {
                 throw new NetworkError(`Preflight check failed: ${response.status} ${response.statusText}`);
             }
-            const data = (await response.json());
-            return data;
+            return (await response.json());
         }
         catch (error) {
             if (error instanceof InvalidUrlError || error instanceof NetworkError) {
@@ -46,230 +43,208 @@ export class MinifetchClient {
         }
     }
     /**
-     * Extract URL metadata (paid, requires x402 payment)
+     * Extract URL metadata (paid endpoint)
      *
      * @param url
      * @param options
+     * @param options.verbosity - "standard" (default) or "full"
      * @param options.includeResponseBody
-     * @param options.verbosity - Controls response detail level: "standard" (default) or "full"
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
-     * @throws {PaymentFailedError} if payment fails
+     * @throws {PaymentFailedError} if x402 payment fails
      * @throws {NetworkError} various reasons, check README
      */
     async extractUrlMetadata(url, options) {
         try {
-            // Validate and normalize URL
             const normalizedUrl = validateAndNormalizeUrl(url);
-            // Build request URL with optional params
             const params = new URLSearchParams({ url: normalizedUrl });
-            if (options?.verbosity) {
+            if (options?.verbosity)
                 params.set("verbosity", options.verbosity);
-            }
-            if (options?.includeResponseBody) {
+            if (options?.includeResponseBody)
                 params.set("includeResponseBody", "true");
-            }
-            // Build request URL - convert params to string
-            const endpoint = `/api/v1/x402/extract/url-metadata?${params.toString()}`;
-            const requestUrl = `${this.baseUrl}${endpoint}`;
-            // Make request with x402 payment handling
-            const { response, payment } = await handlePayment(requestUrl, this.config);
-            // Check if extraction succeeded
-            if (!response.ok) {
-                throw new ExtractionFailedError(normalizedUrl, `Metadata extraction failed: ${response.status} ${response.statusText}`);
-            }
-            const data = (await response.json());
-            return {
-                success: data.success,
-                results: data.results,
-                payment,
-            };
+            const requestUrl = `${this.baseUrl}${this._extractPath("url-metadata")}?${params.toString()}`;
+            return await this._makeRequest(requestUrl, normalizedUrl, "Metadata extraction");
         }
         catch (error) {
-            if (error instanceof InvalidUrlError ||
-                error instanceof ExtractionFailedError ||
-                error instanceof PaymentFailedError ||
-                error instanceof NetworkError) {
-                throw error;
-            }
-            throw new ExtractionFailedError(url, `Metadata extraction failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+            return this._rethrowExtraction(error, url, "Metadata extraction");
         }
     }
     /**
-     * Extract URL links (paid, requires x402 payment)
+     * Extract URL links (paid endpoint)
      *
      * @param url
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
-     * @throws {PaymentFailedError} if payment fails
+     * @throws {PaymentFailedError} if x402 payment fails
      * @throws {NetworkError} various reasons, check README
      */
     async extractUrlLinks(url) {
         try {
             const normalizedUrl = validateAndNormalizeUrl(url);
-            const endpoint = `/api/v1/x402/extract/url-links?url=${encodeURIComponent(normalizedUrl)}`;
-            const requestUrl = `${this.baseUrl}${endpoint}`;
-            // Make request with x402 payment handling
-            const { response, payment } = await handlePayment(requestUrl, this.config);
-            if (!response.ok) {
-                throw new ExtractionFailedError(normalizedUrl, `Links extraction failed: ${response.status} ${response.statusText}`);
-            }
-            const data = (await response.json());
-            return {
-                success: data.success,
-                results: data.results,
-                payment,
-            };
+            const requestUrl = `${this.baseUrl}${this._extractPath("url-links")}?url=${encodeURIComponent(normalizedUrl)}`;
+            return await this._makeRequest(requestUrl, normalizedUrl, "Links extraction");
         }
         catch (error) {
-            if (error instanceof InvalidUrlError ||
-                error instanceof ExtractionFailedError ||
-                error instanceof PaymentFailedError ||
-                error instanceof NetworkError) {
-                throw error;
-            }
-            throw new ExtractionFailedError(url, `Links extraction failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+            return this._rethrowExtraction(error, url, "Links extraction");
         }
     }
     /**
-     * Extract URL preview (paid, requires x402 payment)
+     * Extract URL preview (paid endpoint)
      *
      * @param url
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
-     * @throws {PaymentFailedError} if payment fails
+     * @throws {PaymentFailedError} if x402 payment fails
      * @throws {NetworkError} various reasons, check README
      */
     async extractUrlPreview(url) {
         try {
-            // Validate and normalize URL
             const normalizedUrl = validateAndNormalizeUrl(url);
-            // Build request URL
-            const endpoint = `/api/v1/x402/extract/url-preview?url=${encodeURIComponent(normalizedUrl)}`;
-            const requestUrl = `${this.baseUrl}${endpoint}`;
-            // Make request with x402 payment handling
-            const { response, payment } = await handlePayment(requestUrl, this.config);
-            // Check if extraction succeeded
-            if (!response.ok) {
-                throw new ExtractionFailedError(normalizedUrl, `Preview extraction failed: ${response.status} ${response.statusText}`);
-            }
-            const data = (await response.json());
-            return {
-                success: data.success,
-                results: data.results,
-                payment,
-            };
+            const requestUrl = `${this.baseUrl}${this._extractPath("url-preview")}?url=${encodeURIComponent(normalizedUrl)}`;
+            return await this._makeRequest(requestUrl, normalizedUrl, "Preview extraction");
         }
         catch (error) {
-            if (error instanceof InvalidUrlError ||
-                error instanceof ExtractionFailedError ||
-                error instanceof PaymentFailedError ||
-                error instanceof NetworkError) {
-                throw error;
-            }
-            throw new ExtractionFailedError(url, `Preview extraction failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+            return this._rethrowExtraction(error, url, "Preview extraction");
         }
     }
     /**
-     * Extract URL content as markdown (paid, requires x402 payment)
+     * Extract URL content as markdown (paid endpoint)
      *
      * @param url
      * @param options
      * @param options.includeMediaUrls
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
-     * @throws {PaymentFailedError} if payment fails
+     * @throws {PaymentFailedError} if x402 payment fails
      * @throws {NetworkError} various reasons, check README
      */
     async extractUrlContent(url, options) {
         try {
-            // Validate and normalize URL
             const normalizedUrl = validateAndNormalizeUrl(url);
-            // Build request URL with optional params
             const params = new URLSearchParams({ url: normalizedUrl });
-            if (options?.includeMediaUrls) {
+            if (options?.includeMediaUrls)
                 params.set("includeMediaUrls", "true");
-            }
-            const endpoint = `/api/v1/x402/extract/url-content?${params.toString()}`;
-            const requestUrl = `${this.baseUrl}${endpoint}`;
-            // Make request with x402 payment handling
-            const { response, payment } = await handlePayment(requestUrl, this.config);
-            // Check if extraction succeeded
-            if (!response.ok) {
-                throw new ExtractionFailedError(normalizedUrl, `Content extraction failed: ${response.status} ${response.statusText}`);
-            }
-            const data = (await response.json());
-            return {
-                success: data.success,
-                results: data.results,
-                payment,
-            };
+            const requestUrl = `${this.baseUrl}${this._extractPath("url-content")}?${params.toString()}`;
+            return await this._makeRequest(requestUrl, normalizedUrl, "Content extraction");
         }
         catch (error) {
-            if (error instanceof InvalidUrlError ||
-                error instanceof ExtractionFailedError ||
-                error instanceof PaymentFailedError ||
-                error instanceof NetworkError) {
-                throw error;
-            }
-            throw new ExtractionFailedError(url, `Content extraction failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+            return this._rethrowExtraction(error, url, "Content extraction");
         }
     }
     /**
-     * Check URL and extract metadata in one call
-     * Throws RobotsBlockedError if robots.txt blocks the URL
+     * Check URL then extract metadata in one call.
+     * Throws RobotsBlockedError if robots.txt blocks the URL.
      *
      * @param url
      * @param options
-     * @param options.verbosity - Controls response detail level: "standard" (default) or "full"
-     * @param options.includeResponseBody - Include raw response body in result
+     * @param options.verbosity - "standard" (default) or "full"
+     * @param options.includeResponseBody
      */
     async checkAndExtractUrlMetadata(url, options) {
-        const checkResponse = await this.preflightUrlCheck(url);
-        if (!checkResponse.results[0]?.data?.allowed) {
-            throw new RobotsBlockedError(url, checkResponse.results[0]?.data?.message || "URL is blocked by robots.txt");
-        }
+        await this._preflightOrThrow(url);
         return this.extractUrlMetadata(url, options);
     }
     /**
-     * Check URL and extract links in one call
-     * Throws RobotsBlockedError if robots.txt blocks the URL
+     * Check URL then extract links in one call.
+     * Throws RobotsBlockedError if robots.txt blocks the URL.
      *
      * @param url
      */
     async checkAndExtractUrlLinks(url) {
-        const checkResponse = await this.preflightUrlCheck(url);
-        if (!checkResponse.results[0]?.data?.allowed) {
-            throw new RobotsBlockedError(url, checkResponse.results[0]?.data?.message || "URL is blocked by robots.txt");
-        }
+        await this._preflightOrThrow(url);
         return this.extractUrlLinks(url);
     }
     /**
-     * Check URL and extract preview in one call
-     * Throws RobotsBlockedError if robots.txt blocks the URL
+     * Check URL then extract preview in one call.
+     * Throws RobotsBlockedError if robots.txt blocks the URL.
      *
      * @param url
      */
     async checkAndExtractUrlPreview(url) {
-        const checkResponse = await this.preflightUrlCheck(url);
-        if (!checkResponse.results[0]?.data?.allowed) {
-            throw new RobotsBlockedError(url, checkResponse.results[0]?.data?.message || "URL is blocked by robots.txt");
-        }
+        await this._preflightOrThrow(url);
         return this.extractUrlPreview(url);
     }
     /**
-     * Check URL and extract content in one call
-     * Throws RobotsBlockedError if robots.txt blocks the URL
+     * Check URL then extract content in one call.
+     * Throws RobotsBlockedError if robots.txt blocks the URL.
      *
      * @param url
      * @param options
      * @param options.includeMediaUrls
      */
     async checkAndExtractUrlContent(url, options) {
+        await this._preflightOrThrow(url);
+        return this.extractUrlContent(url, options);
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns the correct extract path segment based on auth mode.
+     * x402 → /api/v1/x402/extract/<endpoint>
+     * apiKey → /api/v1/extract/<endpoint>
+     *
+     * @param endpoint
+     */
+    _extractPath(endpoint) {
+        return this.config.authMode === "x402"
+            ? `/api/v1/x402/extract/${endpoint}`
+            : `/api/v1/extract/${endpoint}`;
+    }
+    /**
+     * Dispatch to the correct request handler based on auth mode, then
+     * normalize the response into PaidEndpointResponse.
+     * Note: payment field is only present for x402 responses.
+     *
+     * @param requestUrl
+     * @param normalizedUrl
+     * @param label - used in error messages
+     */
+    async _makeRequest(requestUrl, normalizedUrl, label) {
+        if (this.config.authMode === "x402") {
+            const { response, payment } = await handlePayment(requestUrl, this.config);
+            if (!response.ok) {
+                throw new ExtractionFailedError(normalizedUrl, `${label} failed: ${response.status} ${response.statusText}`);
+            }
+            const data = (await response.json());
+            return { success: data.success, results: data.results, payment };
+        }
+        else {
+            const { response } = await handleApiKeyRequest(requestUrl, this.config);
+            if (!response.ok) {
+                throw new ExtractionFailedError(normalizedUrl, `${label} failed: ${response.status} ${response.statusText}`);
+            }
+            const data = (await response.json());
+            // payment field intentionally omitted for apiKey auth — not applicable
+            return { success: data.success, results: data.results };
+        }
+    }
+    /**
+     * Preflight check helper — throws RobotsBlockedError if not allowed
+     *
+     * @param url
+     */
+    async _preflightOrThrow(url) {
         const checkResponse = await this.preflightUrlCheck(url);
         if (!checkResponse.results[0]?.data?.allowed) {
             throw new RobotsBlockedError(url, checkResponse.results[0]?.data?.message || "URL is blocked by robots.txt");
         }
-        return this.extractUrlContent(url, options);
+    }
+    /**
+     * Re-throw known error types, wrapping unknowns in ExtractionFailedError
+     *
+     * @param error
+     * @param url
+     * @param label
+     */
+    _rethrowExtraction(error, url, label) {
+        if (error instanceof InvalidUrlError ||
+            error instanceof ExtractionFailedError ||
+            error instanceof PaymentFailedError ||
+            error instanceof NetworkError ||
+            error instanceof RobotsBlockedError) {
+            throw error;
+        }
+        throw new ExtractionFailedError(url, `${label} failed: ${error instanceof Error ? error.message : "Unknown error"}`);
     }
 }

package/dist/esm/init.js

@@ -1,7 +1,7 @@
 import { VALID_NETWORKS } from "./types/config.js";
 import { ConfigurationError } from "./types/errors.js";
 /**
- * Default configuration values
+ * Default configuration values for x402 mode
  * Exported for testing purposes
  */
 export const DEFAULTS = {
@@ -19,32 +19,65 @@ export const DEFAULTS = {
         solana: "https://explorer.solana.com/tx",
     },
 };
+/** Prod API key prefix */
+const PROD_KEY_PREFIX = "mf_prod_";
+/** Dev API key prefix */
+const DEV_KEY_PREFIX = "mf_dev_";
 /**
- * Validate & initialize client configuration
+ * Validate & initialize client configuration.
+ * Accepts either X402Config (network + privateKey) or ApiKeyConfig (apiKey).
  *
  * @param config
  */
 export function initConfig(config) {
-    // Validate private key is provided
+    if ("apiKey" in config) {
+        return initApiKeyConfig(config);
+    }
+    return initX402Config(config);
+}
+/**
+ * Initialize config for API key auth mode.
+ * Infers apiBaseUrl from the key prefix (mf_prod_* → prod, mf_dev_* → dev).
+ *
+ * @param config
+ */
+function initApiKeyConfig(config) {
+    const { apiKey } = config;
+    if (!apiKey || apiKey.trim() === "") {
+        throw new ConfigurationError("API key is required");
+    }
+    if (!apiKey.startsWith(PROD_KEY_PREFIX) && !apiKey.startsWith(DEV_KEY_PREFIX)) {
+        throw new ConfigurationError(`Invalid API key format: must start with "${PROD_KEY_PREFIX}" or "${DEV_KEY_PREFIX}"`);
+    }
+    const apiBaseUrl = apiKey.startsWith(PROD_KEY_PREFIX)
+        ? "https://minifetch.com"
+        : "http://localhost:4021";
+    return {
+        authMode: "apiKey",
+        apiKey,
+        apiBaseUrl,
+    };
+}
+/**
+ * Initialize config for x402 crypto payment mode.
+ *
+ * @param config
+ */
+function initX402Config(config) {
     if (!config.privateKey || config.privateKey.trim() === "") {
         throw new ConfigurationError("Private key is required");
     }
-    // Validate network
     const network = config.network || DEFAULTS.network;
     if (!VALID_NETWORKS.includes(network)) {
         throw new ConfigurationError(`Invalid network: "${network}". Must be one of: ${VALID_NETWORKS.join(", ")}`);
     }
-    // Validate private key format based on network
     validatePrivateKey(config.privateKey, network);
-    // Build initalized config
-    const apiBaseUrl = DEFAULTS.apiBaseUrls[network];
-    const explorerUrl = DEFAULTS.explorerUrls[network];
-    // console.log(`config.ts: network: ${network} apiBaseUrl: ${apiBaseUrl}`)
     return {
+        authMode: "x402",
         network,
         privateKey: config.privateKey,
-        apiBaseUrl,
-        explorerUrl,
+        apiBaseUrl: DEFAULTS.apiBaseUrls[network],
+        explorerUrl: DEFAULTS.explorerUrls[network],
     };
 }
 /**
@@ -55,13 +88,11 @@ export function initConfig(config) {
  */
 function validatePrivateKey(privateKey, network) {
     if (network === "solana" || network === "solana-devnet") {
-        // Solana: base58 encoded, typically 88 characters
         if (!/^[1-9A-HJ-NP-Za-km-z]{87,88}$/.test(privateKey)) {
             throw new ConfigurationError("Invalid Solana private key format (expected base58 string)");
         }
     }
     else {
-        // EVM: hex string, 64 characters (with or without 0x prefix)
         const cleanKey = privateKey.startsWith("0x") ? privateKey.slice(2) : privateKey;
         if (!/^[0-9a-fA-F]{64}$/.test(cleanKey)) {
             throw new ConfigurationError("Invalid EVM private key format (expected hex string that starts with 0x)");

package/dist/esm/utils/payment.js

@@ -16,50 +16,36 @@ import { PaymentFailedError, NetworkError } from "../types/errors.js";
  * @param config
  */
 export async function handlePayment(url, config) {
-    if (!config.privateKey) {
-        throw new PaymentFailedError("Private key required for payments");
-    }
     try {
-        // Create x402 client and signer based on network type
         const _x402Client = new x402Client();
         let payer;
-        const isEvm = config.network.startsWith("base");
-        const isSolana = config.network.startsWith("solana");
+        const isEvm = config.network?.startsWith("base");
+        const isSolana = config.network?.startsWith("solana");
         if (isEvm) {
-            // Initialize EVM signer and register scheme
             const signer = privateKeyToAccount(config.privateKey);
-            const evmSigner = signer; // Type assertion for EVM
+            const evmSigner = signer;
             registerExactEvmScheme(_x402Client, { signer: evmSigner });
             payer = signer.address;
         }
         else if (isSolana) {
-            // Initialize Solana signer and register scheme
+            if (!config.privateKey)
+                throw new PaymentFailedError('privateKey is required for Solana payments');
             const privateKeyBytes = bs58.decode(config.privateKey);
             const signer = await createKeyPairSignerFromBytes(privateKeyBytes);
-            const svmSigner = signer; // Type assertion for Solana
+            const svmSigner = signer;
             registerExactSvmScheme(_x402Client, { signer: svmSigner });
             payer = signer.address;
         }
         else {
             throw new PaymentFailedError(`Unsupported network: ${config.network}`);
         }
-        // Wrap fetch with payment capabilities
         const fetchWithPayment = wrapFetchWithPayment(fetch, _x402Client);
-        // Make request with payment handling
-        // console.log("Attempting to fetch w payment:", url);
-        const response = await fetchWithPayment(url, {
-            method: "GET",
-        });
+        const response = await fetchWithPayment(url, { method: "GET" });
         if (!response.ok) {
             throw new NetworkError(`Request failed: ${response.status} ${response.statusText}`);
         }
-        // Extract payment receipt from response headers
         const httpClient = new x402HTTPClient(_x402Client);
         const paymentResponse = httpClient.getPaymentSettleResponse(name => response.headers.get(name));
-        // DEBUG:
-        // console.log("Payment response:");
-        // console.log(paymentResponse);
-        // Build payment info for user
         const payment = {
             success: true,
             payer,
@@ -78,8 +64,27 @@ export async function handlePayment(url, config) {
         throw new PaymentFailedError(`Payment failed: ${error instanceof Error ? error.message : "Unknown error"}`);
     }
 }
-// Helper fn to build explorer links
 /**
+ * Handle API key auth flow — simple Bearer token request, no crypto.
+ * No payment info is returned (not applicable for this auth mode).
+ *
+ * @param url
+ * @param config
+ */
+export async function handleApiKeyRequest(url, config) {
+    const response = await fetch(url, {
+        method: "GET",
+        headers: {
+            Authorization: `Bearer ${config.apiKey}`,
+        },
+    });
+    if (!response.ok) {
+        throw new NetworkError(`Request failed: ${response.status} ${response.statusText}`);
+    }
+    return { response };
+}
+/**
+ * Build block explorer link for a transaction hash
  *
  * @param config
  * @param txHash

package/dist/types/client.d.ts

@@ -1,19 +1,20 @@
 import type { ClientConfig } from "./types/config.js";
 import type { PreflightCheckResponse, PaidEndpointResponse } from "./types/responses.js";
 /**
- * Main Minifetch API client
- * Provides methods to check URLs and extract metadata/links/preview/content
+ * Main Minifetch API client.
+ * Supports two auth modes:
+ *   - x402: crypto micropayments via Coinbase x402 (pass network + privateKey)
+ *   - apiKey: Stripe-backed credits (pass apiKey: "mf_prod_..." or "mf_dev_...")
  */
 export declare class MinifetchClient {
     private config;
     private baseUrl;
     /**
-     *
-     * @param config
+     * @param config - Either { network, privateKey } for x402 or { apiKey } for API key auth
      */
     constructor(config: ClientConfig);
     /**
-     * Check if URL is allowed by robots.txt (free preflight check)
+     * Check if URL is allowed by robots.txt (free preflight check — no auth required)
      *
      * @param url
      * @throws {InvalidUrlError} if URL is invalid
@@ -21,15 +22,15 @@ export declare class MinifetchClient {
      */
     preflightUrlCheck(url: string): Promise<PreflightCheckResponse>;
     /**
-     * Extract URL metadata (paid, requires x402 payment)
+     * Extract URL metadata (paid endpoint)
      *
      * @param url
      * @param options
+     * @param options.verbosity - "standard" (default) or "full"
      * @param options.includeResponseBody
-     * @param options.verbosity - Controls response detail level: "standard" (default) or "full"
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
-     * @throws {PaymentFailedError} if payment fails
+     * @throws {PaymentFailedError} if x402 payment fails
      * @throws {NetworkError} various reasons, check README
      */
     extractUrlMetadata(url: string, options?: {
@@ -37,69 +38,69 @@ export declare class MinifetchClient {
         includeResponseBody?: boolean;
     }): Promise<PaidEndpointResponse>;
     /**
-     * Extract URL links (paid, requires x402 payment)
+     * Extract URL links (paid endpoint)
      *
      * @param url
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
-     * @throws {PaymentFailedError} if payment fails
+     * @throws {PaymentFailedError} if x402 payment fails
      * @throws {NetworkError} various reasons, check README
      */
     extractUrlLinks(url: string): Promise<PaidEndpointResponse>;
     /**
-     * Extract URL preview (paid, requires x402 payment)
+     * Extract URL preview (paid endpoint)
      *
      * @param url
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
-     * @throws {PaymentFailedError} if payment fails
+     * @throws {PaymentFailedError} if x402 payment fails
      * @throws {NetworkError} various reasons, check README
      */
     extractUrlPreview(url: string): Promise<PaidEndpointResponse>;
     /**
-     * Extract URL content as markdown (paid, requires x402 payment)
+     * Extract URL content as markdown (paid endpoint)
      *
      * @param url
      * @param options
      * @param options.includeMediaUrls
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
-     * @throws {PaymentFailedError} if payment fails
+     * @throws {PaymentFailedError} if x402 payment fails
      * @throws {NetworkError} various reasons, check README
      */
     extractUrlContent(url: string, options?: {
         includeMediaUrls?: boolean;
     }): Promise<PaidEndpointResponse>;
     /**
-     * Check URL and extract metadata in one call
-     * Throws RobotsBlockedError if robots.txt blocks the URL
+     * Check URL then extract metadata in one call.
+     * Throws RobotsBlockedError if robots.txt blocks the URL.
      *
      * @param url
      * @param options
-     * @param options.verbosity - Controls response detail level: "standard" (default) or "full"
-     * @param options.includeResponseBody - Include raw response body in result
+     * @param options.verbosity - "standard" (default) or "full"
+     * @param options.includeResponseBody
      */
     checkAndExtractUrlMetadata(url: string, options?: {
         verbosity?: "standard" | "full";
         includeResponseBody?: boolean;
     }): Promise<PaidEndpointResponse>;
     /**
-     * Check URL and extract links in one call
-     * Throws RobotsBlockedError if robots.txt blocks the URL
+     * Check URL then extract links in one call.
+     * Throws RobotsBlockedError if robots.txt blocks the URL.
      *
      * @param url
      */
     checkAndExtractUrlLinks(url: string): Promise<PaidEndpointResponse>;
     /**
-     * Check URL and extract preview in one call
-     * Throws RobotsBlockedError if robots.txt blocks the URL
+     * Check URL then extract preview in one call.
+     * Throws RobotsBlockedError if robots.txt blocks the URL.
      *
      * @param url
      */
     checkAndExtractUrlPreview(url: string): Promise<PaidEndpointResponse>;
     /**
-     * Check URL and extract content in one call
-     * Throws RobotsBlockedError if robots.txt blocks the URL
+     * Check URL then extract content in one call.
+     * Throws RobotsBlockedError if robots.txt blocks the URL.
      *
      * @param url
      * @param options
@@ -108,4 +109,36 @@ export declare class MinifetchClient {
     checkAndExtractUrlContent(url: string, options?: {
         includeMediaUrls?: boolean;
     }): Promise<PaidEndpointResponse>;
+    /**
+     * Returns the correct extract path segment based on auth mode.
+     * x402 → /api/v1/x402/extract/<endpoint>
+     * apiKey → /api/v1/extract/<endpoint>
+     *
+     * @param endpoint
+     */
+    private _extractPath;
+    /**
+     * Dispatch to the correct request handler based on auth mode, then
+     * normalize the response into PaidEndpointResponse.
+     * Note: payment field is only present for x402 responses.
+     *
+     * @param requestUrl
+     * @param normalizedUrl
+     * @param label - used in error messages
+     */
+    private _makeRequest;
+    /**
+     * Preflight check helper — throws RobotsBlockedError if not allowed
+     *
+     * @param url
+     */
+    private _preflightOrThrow;
+    /**
+     * Re-throw known error types, wrapping unknowns in ExtractionFailedError
+     *
+     * @param error
+     * @param url
+     * @param label
+     */
+    private _rethrowExtraction;
 }

package/dist/types/init.d.ts

@@ -1,6 +1,6 @@
 import type { ClientConfig, InitializedConfig, Network } from "./types/config.js";
 /**
- * Default configuration values
+ * Default configuration values for x402 mode
  * Exported for testing purposes
  */
 export declare const DEFAULTS: {
@@ -19,7 +19,8 @@ export declare const DEFAULTS: {
     };
 };
 /**
- * Validate & initialize client configuration
+ * Validate & initialize client configuration.
+ * Accepts either X402Config (network + privateKey) or ApiKeyConfig (apiKey).
  *
  * @param config
  */

package/dist/types/types/config.d.ts

@@ -1,21 +1,31 @@
 export declare const VALID_NETWORKS: readonly ["base", "base-sepolia", "solana", "solana-devnet"];
 export type Network = (typeof VALID_NETWORKS)[number];
-export interface ClientConfig {
-    /**
-     * Blockchain network to use for payments
-     *
-     * @default 'base'
-     */
+/**
+ * Config for x402 crypto micropayment auth
+ */
+export interface X402Config {
+    /** Blockchain network to use for payments @default 'base' */
     network: Network;
-    /**
-     * Private key for signing transactions -
-     * hex string for EVM, base58 for Solana
-     */
+    /** Private key for signing transactions — hex for EVM, base58 for Solana */
     privateKey: string;
 }
+/**
+ * Config for Stripe-backed API key auth.
+ * apiBaseUrl is inferred from the key prefix:
+ *   mf_prod_* → https://minifetch.com
+ *   mf_dev_*  → http://localhost:4021
+ */
+export interface ApiKeyConfig {
+    apiKey: string;
+}
+export type ClientConfig = X402Config | ApiKeyConfig;
+/** Discriminant for internal use after init */
+export type AuthMode = "x402" | "apiKey";
 export interface InitializedConfig {
-    network: Network;
-    privateKey: string;
+    authMode: AuthMode;
+    network?: Network;
+    privateKey?: string;
+    explorerUrl?: string;
+    apiKey?: string;
     apiBaseUrl: string;
-    explorerUrl: string;
 }

package/dist/types/types/responses.d.ts

@@ -29,12 +29,12 @@ export interface PaidEndpointResponse {
     }>;
     /**
      * Payment information
-     * Only present for paid endpoints when request was successful
+     * Only present for paid x402 endpoints when request was successful
      * */
     payment?: PaymentInfo;
 }
 /**
- * Payment information included with successful paid API responses
+ * Payment information included with successful paid x402 API responses
  */
 export interface PaymentInfo {
     /** Whether the payment was successful **/

package/dist/types/utils/payment.d.ts

@@ -14,3 +14,13 @@ export declare function handlePayment(url: string, config: InitializedConfig): P
     response: Response;
     payment?: PaymentInfo;
 }>;
+/**
+ * Handle API key auth flow — simple Bearer token request, no crypto.
+ * No payment info is returned (not applicable for this auth mode).
+ *
+ * @param url
+ * @param config
+ */
+export declare function handleApiKeyRequest(url: string, config: InitializedConfig): Promise<{
+    response: Response;
+}>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minifetch-api",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Minifetch.com API Client. Fetch & extract data from web pages. For AI Agents & SEO research.",
   "type": "module",
   "main": "./dist/esm/index.js",