minifetch-api 1.5.0 → 1.6.0

package/README.md

@@ -24,7 +24,7 @@
 - ***Or*** an Ethereum or Solana private key for making USDC payments on Base or Solana networks.
 
 **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.
+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 credits worth up to 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!
 
 ## Install
@@ -74,6 +74,8 @@ After the Quick Start, you have the following methods to use.
 
 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 you own the site and want to allow Minifetch access or to set custom rules for it, read [How To Unblock Minifetch](https://minifetch.com/tutorials/unblock-minifetch).
 
+All API methods default to POST unless you set options to `{ method: 'GET' }` and pass in as the second argument.
+
 ```js
 await client.checkAndRunSeoPageAudit(url);
 // Price: $0.01
@@ -152,18 +154,15 @@ When you wrap the functions above in a try/catch, here are some of the errors yo
 
 ---
 
-### Service Limitations
-Minifetch only extracts publicly available metadata and content from pages accessible without authentication and javascript execution.
+### How We Fetch Web Pages
+Minifetch extracts publicly available metadata and content from pages accessible without authentication or javascript execution.
 
-What Minifetch does *NOT* do:
-- Ignore robots.txt directives
-- Create accounts or log into user sessions
-- Perform transactional actions (checkout, bidding, purchasing, form submissions)
-- Bypass paywalls or access restricted content
+Every response carries a `proxy` block: the `minifetch` user agent we sent and whether robots.txt was obeyed on the fetch. Proof of how the fetch happened, not just a promise, for regulated use-cases where provenance matters.
 
-What Minifetch does NOT do *currently* but may offer in the future as an add-on:
+Future add-ons:
+- Residential proxies for hard-to-reach pages
 - Javascript execution
-- Access authenticated or logged-in content
+- Access to authenticated or logged-in content
 
 ---
 

package/dist/esm/client.js

@@ -1,12 +1,18 @@
 import { initConfig } from "./init.js";
 import { validateAndNormalizeUrl } from "./utils/validation.js";
 import { handlePayment, handleApiKeyRequest } from "./utils/payment.js";
-import { InvalidUrlError, RobotsBlockedError, PaymentFailedError, ExtractionFailedError, NetworkError, } from "./types/errors.js";
+import { InvalidUrlError, RobotsBlockedError, PaymentFailedError, ExtractionFailedError, NetworkError, ConfigurationError, } from "./types/errors.js";
+/** Every endpoint accepts GET (query string) or POST (JSON body). POST is the default. */
+const DEFAULT_METHOD = "POST";
 /**
  * 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_...")
+ *
+ * Every request method accepts an optional `method: "GET" | "POST"` in its
+ * options; it defaults to POST (params sent as a JSON body). Pass `method: "GET"`
+ * to send params in the query string instead.
  */
 export class MinifetchClient {
     config;
@@ -24,17 +30,18 @@ export class MinifetchClient {
      * @param url
      * @param options
      * @param options.fresh
+     * @param options.method - "GET" or "POST" (default POST)
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {NetworkError} if request fails
      */
     async preflightUrlCheck(url, options) {
         try {
             const normalizedUrl = validateAndNormalizeUrl(url);
-            const params = new URLSearchParams({ url: normalizedUrl });
+            const params = { url: normalizedUrl };
             if (options?.fresh)
-                params.set("fresh", "true");
-            const requestUrl = `${this.baseUrl}/api/v1/free/preflight/url-check?${params.toString()}`;
-            const response = await fetch(requestUrl);
+                params.fresh = true;
+            const { url: requestUrl, init } = this._buildRequest("/api/v1/free/preflight/url-check", params, options?.method ?? DEFAULT_METHOD);
+            const response = await fetch(requestUrl, init);
             if (!response.ok) {
                 throw new NetworkError(`Preflight check failed: ${response.status} ${response.statusText}`);
             }
@@ -47,21 +54,53 @@ export class MinifetchClient {
             throw new NetworkError(`Preflight check failed: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
+    /**
+     * INTERNAL / UNDOCUMENTED — deliberately omitted from the README and not part
+     * of the public API. The public {@link preflightUrlCheck} hits the FREE
+     * endpoint (no payment); this hits the PAID x402 twin at
+     * `/api/v1/x402/preflight/url-check` so our own suite can generate paid
+     * traffic against it — the x402 Bazaar weights usage for ranking and this
+     * refreshes the listing. x402 auth only; there is no session/api-key route
+     * for a paid url-check.
+     *
+     * @param url
+     * @param options
+     * @param options.fresh - bypass the 24h robots.txt cache
+     * @param options.method - "GET" or "POST" (default POST)
+     * @throws {ConfigurationError} if the client is not in x402 mode
+     * @internal
+     */
+    async _exercisePaidUrlCheck(url, options) {
+        if (this.config.authMode !== "x402") {
+            throw new ConfigurationError("_exercisePaidUrlCheck requires x402 auth (network + privateKey)");
+        }
+        try {
+            const normalizedUrl = validateAndNormalizeUrl(url);
+            const params = { url: normalizedUrl };
+            if (options?.fresh)
+                params.fresh = true;
+            return await this._makeRequest("/preflight/url-check", normalizedUrl, "Paid URL check", params, options?.method);
+        }
+        catch (error) {
+            return this._rethrowError(error, url, "Paid URL check");
+        }
+    }
     /**
      * Run SEO page audit (paid endpoint)
      *
      * @param url
+     * @param options
+     * @param options.method - "GET" or "POST" (default POST)
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if x402 payment fails
      * @throws {NetworkError} various reasons, check README
      */
-    async runSeoPageAudit(url) {
+    async runSeoPageAudit(url, options) {
         try {
             const normalizedUrl = validateAndNormalizeUrl(url);
-            const params = new URLSearchParams({ url: normalizedUrl });
-            const requestUrl = `${this.baseUrl}${this._paidPath("/run/seo-page-audit")}?${params.toString()}`;
-            return await this._makeRequest(requestUrl, normalizedUrl, "Run SEO page audit");
+            const params = { url: normalizedUrl };
+            return await this._makeRequest("/run/seo-page-audit", normalizedUrl, "Run SEO page audit", params, options?.method);
         }
         catch (error) {
             return this._rethrowError(error, url, "Run SEO page audit");
@@ -75,6 +114,7 @@ export class MinifetchClient {
      * @param options.fields
      * @param options.omitEmpty
      * @param options.includeResponseBody
+     * @param options.method - "GET" or "POST" (default POST)
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if x402 payment fails
@@ -83,15 +123,14 @@ export class MinifetchClient {
     async extractUrlMetadata(url, options) {
         try {
             const normalizedUrl = validateAndNormalizeUrl(url);
-            const params = new URLSearchParams({ url: normalizedUrl });
+            const params = { url: normalizedUrl };
             if (options?.fields?.length)
-                params.set("fields", options.fields.join(","));
+                params.fields = options.fields.join(",");
             if (options?.omitEmpty)
-                params.set("omitEmpty", "true");
+                params.omitEmpty = true;
             if (options?.includeResponseBody)
-                params.set("includeResponseBody", "true");
-            const requestUrl = `${this.baseUrl}${this._paidPath("/extract/url-metadata")}?${params.toString()}`;
-            return await this._makeRequest(requestUrl, normalizedUrl, "Metadata extraction");
+                params.includeResponseBody = true;
+            return await this._makeRequest("/extract/url-metadata", normalizedUrl, "Metadata extraction", params, options?.method);
         }
         catch (error) {
             return this._rethrowError(error, url, "Metadata extraction");
@@ -101,16 +140,18 @@ export class MinifetchClient {
      * Extract URL links (paid endpoint)
      *
      * @param url
+     * @param options
+     * @param options.method - "GET" or "POST" (default POST)
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if x402 payment fails
      * @throws {NetworkError} various reasons, check README
      */
-    async extractUrlLinks(url) {
+    async extractUrlLinks(url, options) {
         try {
             const normalizedUrl = validateAndNormalizeUrl(url);
-            const requestUrl = `${this.baseUrl}${this._paidPath("/extract/url-links")}?url=${encodeURIComponent(normalizedUrl)}`;
-            return await this._makeRequest(requestUrl, normalizedUrl, "Links extraction");
+            const params = { url: normalizedUrl };
+            return await this._makeRequest("/extract/url-links", normalizedUrl, "Links extraction", params, options?.method);
         }
         catch (error) {
             return this._rethrowError(error, url, "Links extraction");
@@ -120,16 +161,18 @@ export class MinifetchClient {
      * Extract URL preview (paid endpoint)
      *
      * @param url
+     * @param options
+     * @param options.method - "GET" or "POST" (default POST)
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if x402 payment fails
      * @throws {NetworkError} various reasons, check README
      */
-    async extractUrlPreview(url) {
+    async extractUrlPreview(url, options) {
         try {
             const normalizedUrl = validateAndNormalizeUrl(url);
-            const requestUrl = `${this.baseUrl}${this._paidPath("/extract/url-preview")}?url=${encodeURIComponent(normalizedUrl)}`;
-            return await this._makeRequest(requestUrl, normalizedUrl, "Preview extraction");
+            const params = { url: normalizedUrl };
+            return await this._makeRequest("/extract/url-preview", normalizedUrl, "Preview extraction", params, options?.method);
         }
         catch (error) {
             return this._rethrowError(error, url, "Preview extraction");
@@ -141,6 +184,7 @@ export class MinifetchClient {
      * @param url
      * @param options
      * @param options.includeMediaUrls
+     * @param options.method - "GET" or "POST" (default POST)
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if x402 payment fails
@@ -149,11 +193,10 @@ export class MinifetchClient {
     async extractUrlContent(url, options) {
         try {
             const normalizedUrl = validateAndNormalizeUrl(url);
-            const params = new URLSearchParams({ url: normalizedUrl });
+            const params = { url: normalizedUrl };
             if (options?.includeMediaUrls)
-                params.set("includeMediaUrls", "true");
-            const requestUrl = `${this.baseUrl}${this._paidPath("/extract/url-content")}?${params.toString()}`;
-            return await this._makeRequest(requestUrl, normalizedUrl, "Content extraction");
+                params.includeMediaUrls = true;
+            return await this._makeRequest("/extract/url-content", normalizedUrl, "Content extraction", params, options?.method);
         }
         catch (error) {
             return this._rethrowError(error, url, "Content extraction");
@@ -164,10 +207,12 @@ export class MinifetchClient {
      * Throws RobotsBlockedError if robots.txt blocks the URL.
      *
      * @param url
+     * @param options
+     * @param options.method - "GET" or "POST" (default POST)
      */
-    async checkAndRunSeoPageAudit(url) {
+    async checkAndRunSeoPageAudit(url, options) {
         await this._preflightOrThrow(url);
-        return this.runSeoPageAudit(url);
+        return this.runSeoPageAudit(url, options);
     }
     /**
      * Check URL then extract metadata in one call.
@@ -178,6 +223,7 @@ export class MinifetchClient {
      * @param options.fields
      * @param options.omitEmpty
      * @param options.includeResponseBody
+     * @param options.method - "GET" or "POST" (default POST)
      */
     async checkAndExtractUrlMetadata(url, options) {
         await this._preflightOrThrow(url);
@@ -188,20 +234,24 @@ export class MinifetchClient {
      * Throws RobotsBlockedError if robots.txt blocks the URL.
      *
      * @param url
+     * @param options
+     * @param options.method - "GET" or "POST" (default POST)
      */
-    async checkAndExtractUrlLinks(url) {
+    async checkAndExtractUrlLinks(url, options) {
         await this._preflightOrThrow(url);
-        return this.extractUrlLinks(url);
+        return this.extractUrlLinks(url, options);
     }
     /**
      * Check URL then extract preview in one call.
      * Throws RobotsBlockedError if robots.txt blocks the URL.
      *
      * @param url
+     * @param options
+     * @param options.method - "GET" or "POST" (default POST)
      */
-    async checkAndExtractUrlPreview(url) {
+    async checkAndExtractUrlPreview(url, options) {
         await this._preflightOrThrow(url);
-        return this.extractUrlPreview(url);
+        return this.extractUrlPreview(url, options);
     }
     /**
      * Check URL then extract content in one call.
@@ -210,6 +260,7 @@ export class MinifetchClient {
      * @param url
      * @param options
      * @param options.includeMediaUrls
+     * @param options.method - "GET" or "POST" (default POST)
      */
     async checkAndExtractUrlContent(url, options) {
         await this._preflightOrThrow(url);
@@ -229,17 +280,46 @@ export class MinifetchClient {
         return this.config.authMode === "x402" ? `/api/v1/x402${endpoint}` : `/api/v1${endpoint}`;
     }
     /**
-     * Dispatch to the correct request handler based on auth mode, then
-     * normalize the response into PaidEndpointResponse.
+     * Encode a request for the wire. GET → params in the query string, no body.
+     * POST → params as a JSON body with a Content-Type header. Auth headers
+     * (Bearer / x402 payment) are added downstream, not here.
+     *
+     * @param path - absolute API path (already includes /api/v1[/x402])
+     * @param params - request params (string or boolean values)
+     * @param method - "GET" or "POST"
+     * @returns the full request URL and the fetch init (method + optional body/headers)
+     */
+    _buildRequest(path, params, method) {
+        if (method === "GET") {
+            const qs = new URLSearchParams();
+            for (const [key, value] of Object.entries(params))
+                qs.set(key, String(value));
+            return { url: `${this.baseUrl}${path}?${qs.toString()}`, init: { method: "GET" } };
+        }
+        return {
+            url: `${this.baseUrl}${path}`,
+            init: {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(params),
+            },
+        };
+    }
+    /**
+     * Build the request, dispatch to the correct auth handler, then normalize the
+     * response into PaidEndpointResponse.
      * Note: payment field is only present for x402 responses.
      *
-     * @param requestUrl
+     * @param endpoint - endpoint path segment, e.g. "/extract/url-metadata"
      * @param normalizedUrl
      * @param label - used in error messages
+     * @param params - request params (string or boolean values)
+     * @param method - "GET" or "POST" (default POST)
      */
-    async _makeRequest(requestUrl, normalizedUrl, label) {
+    async _makeRequest(endpoint, normalizedUrl, label, params, method = DEFAULT_METHOD) {
+        const { url, init } = this._buildRequest(this._paidPath(endpoint), params, method);
         if (this.config.authMode === "x402") {
-            const { response, payment } = await handlePayment(requestUrl, this.config);
+            const { response, payment } = await handlePayment(url, this.config, init);
             if (!response.ok) {
                 throw new ExtractionFailedError(normalizedUrl, `${label} failed: ${response.status} ${response.statusText}`);
             }
@@ -247,7 +327,7 @@ export class MinifetchClient {
             return { success: data.success, results: data.results, payment };
         }
         else {
-            const { response } = await handleApiKeyRequest(requestUrl, this.config);
+            const { response } = await handleApiKeyRequest(url, this.config, init);
             if (!response.ok) {
                 throw new ExtractionFailedError(normalizedUrl, `${label} failed: ${response.status} ${response.statusText}`);
             }

package/dist/esm/utils/payment.js

@@ -15,7 +15,7 @@ import { PaymentFailedError, NetworkError } from "../types/errors.js";
  * @param url
  * @param config
  */
-export async function handlePayment(url, config) {
+export async function handlePayment(url, config, init) {
     try {
         const _x402Client = new x402Client();
         let payer;
@@ -40,7 +40,8 @@ export async function handlePayment(url, config) {
             throw new PaymentFailedError(`Unsupported network: ${config.network}`);
         }
         const fetchWithPayment = wrapFetchWithPayment(fetch, _x402Client);
-        const response = await fetchWithPayment(url, { method: "GET" });
+        // Default GET when no init passed; init carries method + JSON body for POST.
+        const response = await fetchWithPayment(url, init ?? { method: "GET" });
         if (!response.ok) {
             const serverMessage = await readServerErrorMessage(response);
             throw new NetworkError(`Request failed: ${response.status} ${response.statusText}${serverMessage ? ` — ${serverMessage}` : ""}`);
@@ -72,10 +73,12 @@ export async function handlePayment(url, config) {
  * @param url
  * @param config
  */
-export async function handleApiKeyRequest(url, config) {
+export async function handleApiKeyRequest(url, config, init) {
     const response = await fetch(url, {
-        method: "GET",
+        ...init,
+        method: init?.method ?? "GET",
         headers: {
+            ...init?.headers,
             Authorization: `Bearer ${config.apiKey}`,
         },
     });

package/dist/types/client.d.ts

@@ -1,10 +1,14 @@
-import type { ClientConfig } from "./types/config.js";
+import type { ClientConfig, HttpMethod } from "./types/config.js";
 import type { PreflightCheckResponse, PaidEndpointResponse } from "./types/responses.js";
 /**
  * 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_...")
+ *
+ * Every request method accepts an optional `method: "GET" | "POST"` in its
+ * options; it defaults to POST (params sent as a JSON body). Pass `method: "GET"`
+ * to send params in the query string instead.
  */
 export declare class MinifetchClient {
     private config;
@@ -19,22 +23,48 @@ export declare class MinifetchClient {
      * @param url
      * @param options
      * @param options.fresh
+     * @param options.method - "GET" or "POST" (default POST)
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {NetworkError} if request fails
      */
     preflightUrlCheck(url: string, options?: {
         fresh?: boolean;
+        method?: HttpMethod;
     }): Promise<PreflightCheckResponse>;
+    /**
+     * INTERNAL / UNDOCUMENTED — deliberately omitted from the README and not part
+     * of the public API. The public {@link preflightUrlCheck} hits the FREE
+     * endpoint (no payment); this hits the PAID x402 twin at
+     * `/api/v1/x402/preflight/url-check` so our own suite can generate paid
+     * traffic against it — the x402 Bazaar weights usage for ranking and this
+     * refreshes the listing. x402 auth only; there is no session/api-key route
+     * for a paid url-check.
+     *
+     * @param url
+     * @param options
+     * @param options.fresh - bypass the 24h robots.txt cache
+     * @param options.method - "GET" or "POST" (default POST)
+     * @throws {ConfigurationError} if the client is not in x402 mode
+     * @internal
+     */
+    _exercisePaidUrlCheck(url: string, options?: {
+        fresh?: boolean;
+        method?: HttpMethod;
+    }): Promise<PaidEndpointResponse>;
     /**
      * Run SEO page audit (paid endpoint)
      *
      * @param url
+     * @param options
+     * @param options.method - "GET" or "POST" (default POST)
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if x402 payment fails
      * @throws {NetworkError} various reasons, check README
      */
-    runSeoPageAudit(url: string): Promise<PaidEndpointResponse>;
+    runSeoPageAudit(url: string, options?: {
+        method?: HttpMethod;
+    }): Promise<PaidEndpointResponse>;
     /**
      * Extract URL metadata (paid endpoint)
      *
@@ -43,6 +73,7 @@ export declare class MinifetchClient {
      * @param options.fields
      * @param options.omitEmpty
      * @param options.includeResponseBody
+     * @param options.method - "GET" or "POST" (default POST)
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if x402 payment fails
@@ -52,33 +83,43 @@ export declare class MinifetchClient {
         fields?: string[];
         omitEmpty?: boolean;
         includeResponseBody?: boolean;
+        method?: HttpMethod;
     }): Promise<PaidEndpointResponse>;
     /**
      * Extract URL links (paid endpoint)
      *
      * @param url
+     * @param options
+     * @param options.method - "GET" or "POST" (default POST)
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if x402 payment fails
      * @throws {NetworkError} various reasons, check README
      */
-    extractUrlLinks(url: string): Promise<PaidEndpointResponse>;
+    extractUrlLinks(url: string, options?: {
+        method?: HttpMethod;
+    }): Promise<PaidEndpointResponse>;
     /**
      * Extract URL preview (paid endpoint)
      *
      * @param url
+     * @param options
+     * @param options.method - "GET" or "POST" (default POST)
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if x402 payment fails
      * @throws {NetworkError} various reasons, check README
      */
-    extractUrlPreview(url: string): Promise<PaidEndpointResponse>;
+    extractUrlPreview(url: string, options?: {
+        method?: HttpMethod;
+    }): Promise<PaidEndpointResponse>;
     /**
      * Extract URL content as markdown (paid endpoint)
      *
      * @param url
      * @param options
      * @param options.includeMediaUrls
+     * @param options.method - "GET" or "POST" (default POST)
      * @throws {InvalidUrlError} if URL is invalid
      * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if x402 payment fails
@@ -86,14 +127,19 @@ export declare class MinifetchClient {
      */
     extractUrlContent(url: string, options?: {
         includeMediaUrls?: boolean;
+        method?: HttpMethod;
     }): Promise<PaidEndpointResponse>;
     /**
      * Check URL then run SEO page audit in one call.
      * Throws RobotsBlockedError if robots.txt blocks the URL.
      *
      * @param url
+     * @param options
+     * @param options.method - "GET" or "POST" (default POST)
      */
-    checkAndRunSeoPageAudit(url: string): Promise<PaidEndpointResponse>;
+    checkAndRunSeoPageAudit(url: string, options?: {
+        method?: HttpMethod;
+    }): Promise<PaidEndpointResponse>;
     /**
      * Check URL then extract metadata in one call.
      * Throws RobotsBlockedError if robots.txt blocks the URL.
@@ -103,26 +149,36 @@ export declare class MinifetchClient {
      * @param options.fields
      * @param options.omitEmpty
      * @param options.includeResponseBody
+     * @param options.method - "GET" or "POST" (default POST)
      */
     checkAndExtractUrlMetadata(url: string, options?: {
         fields?: string[];
         omitEmpty?: boolean;
         includeResponseBody?: boolean;
+        method?: HttpMethod;
     }): Promise<PaidEndpointResponse>;
     /**
      * Check URL then extract links in one call.
      * Throws RobotsBlockedError if robots.txt blocks the URL.
      *
      * @param url
+     * @param options
+     * @param options.method - "GET" or "POST" (default POST)
      */
-    checkAndExtractUrlLinks(url: string): Promise<PaidEndpointResponse>;
+    checkAndExtractUrlLinks(url: string, options?: {
+        method?: HttpMethod;
+    }): Promise<PaidEndpointResponse>;
     /**
      * Check URL then extract preview in one call.
      * Throws RobotsBlockedError if robots.txt blocks the URL.
      *
      * @param url
+     * @param options
+     * @param options.method - "GET" or "POST" (default POST)
      */
-    checkAndExtractUrlPreview(url: string): Promise<PaidEndpointResponse>;
+    checkAndExtractUrlPreview(url: string, options?: {
+        method?: HttpMethod;
+    }): Promise<PaidEndpointResponse>;
     /**
      * Check URL then extract content in one call.
      * Throws RobotsBlockedError if robots.txt blocks the URL.
@@ -130,9 +186,11 @@ export declare class MinifetchClient {
      * @param url
      * @param options
      * @param options.includeMediaUrls
+     * @param options.method - "GET" or "POST" (default POST)
      */
     checkAndExtractUrlContent(url: string, options?: {
         includeMediaUrls?: boolean;
+        method?: HttpMethod;
     }): Promise<PaidEndpointResponse>;
     /**
      * Returns the correct paid path segment based on auth mode.
@@ -143,13 +201,26 @@ export declare class MinifetchClient {
      */
     private _paidPath;
     /**
-     * Dispatch to the correct request handler based on auth mode, then
-     * normalize the response into PaidEndpointResponse.
+     * Encode a request for the wire. GET → params in the query string, no body.
+     * POST → params as a JSON body with a Content-Type header. Auth headers
+     * (Bearer / x402 payment) are added downstream, not here.
+     *
+     * @param path - absolute API path (already includes /api/v1[/x402])
+     * @param params - request params (string or boolean values)
+     * @param method - "GET" or "POST"
+     * @returns the full request URL and the fetch init (method + optional body/headers)
+     */
+    private _buildRequest;
+    /**
+     * Build the request, dispatch to the correct auth handler, then normalize the
+     * response into PaidEndpointResponse.
      * Note: payment field is only present for x402 responses.
      *
-     * @param requestUrl
+     * @param endpoint - endpoint path segment, e.g. "/extract/url-metadata"
      * @param normalizedUrl
      * @param label - used in error messages
+     * @param params - request params (string or boolean values)
+     * @param method - "GET" or "POST" (default POST)
      */
     private _makeRequest;
     /**

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

@@ -1,5 +1,7 @@
 export declare const VALID_NETWORKS: readonly ["base", "base-sepolia", "solana", "solana-devnet"];
 export type Network = (typeof VALID_NETWORKS)[number];
+/** HTTP method for a request. Every endpoint accepts GET (query string) or POST (JSON body). */
+export type HttpMethod = "GET" | "POST";
 /**
  * Config for x402 crypto micropayment auth
  */

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

@@ -10,7 +10,7 @@ import type { PaymentInfo } from "../types/responses.js";
  * @param url
  * @param config
  */
-export declare function handlePayment(url: string, config: InitializedConfig): Promise<{
+export declare function handlePayment(url: string, config: InitializedConfig, init?: RequestInit): Promise<{
     response: Response;
     payment?: PaymentInfo;
 }>;
@@ -21,6 +21,6 @@ export declare function handlePayment(url: string, config: InitializedConfig): P
  * @param url
  * @param config
  */
-export declare function handleApiKeyRequest(url: string, config: InitializedConfig): Promise<{
+export declare function handleApiKeyRequest(url: string, config: InitializedConfig, init?: RequestInit): Promise<{
     response: Response;
 }>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "minifetch-api",
-  "version": "1.5.0",
-  "description": "Minifetch.com API Client. Pay-per-URL SEO audits. Composable toolkit for AI agents and automation pipelines.",
+  "version": "1.6.0",
+  "description": "Minifetch.com API Client. Scrape, extract and audit web pages. Pay per URL, no subscription.",
   "type": "module",
   "main": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
@@ -17,43 +17,43 @@
     "LICENSE"
   ],
   "keywords": [
+    "html",
+    "web page",
+    "scraper",
+    "parser",
+    "metadata",
+    "metadata extraction",
+    "content extraction",
+    "link extraction",
+    "hosted",
+    "meta tags",
+    "open graph",
+    "og tags",
+    "previews",
+    "social cards",
+    "twitter cards",
+    "pay-per-fetch",
+    "pay-per-url",
+    "indexing",
+    "extract",
+    "json-ld",
+    "JSON LD",
+    "link analysis",
     "SEO",
     "SEO page audit",
     "SEO research",
     "SEO toolkit",
     "SEO skill",
     "technical SEO",
-    "pay-per-fetch",
-    "pay-per-url",
     "GEO",
     "Generative Engine Optimization",
     "AEO",
     "Answer Engine Optimization",
-    "hosted extraction",
-    "content extraction",
-    "content indexing",
-    "extract",
-    "html",
-    "html parser",
-    "json-ld",
-    "JSON LD",
-    "link analysis",
-    "link extraction",
-    "metadata",
-    "meta tags",
-    "open graph",
-    "og tags",
     "AI",
     "AI Agents",
     "AI readability",
-    "agent skills",
     "automation",
-    "monitoring",
     "LLM",
-    "previews",
-    "social cards",
-    "twitter cards",
-    "site monitoring",
     "x402",
     "micropayments",
     "usdc"