minifetch-api 1.5.1 → 1.7.0

package/README.md

@@ -5,7 +5,7 @@
   </a>
 </div>
 
-**[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.
+**[Minifetch](https://minifetch.com) is a hosted toolkit for web developers and AI agents. Search, scrape, extract & SEO audit web pages.** Pay per fetch, no subscription.
 
 - ✅ **Always pay-per-fetch at competitive prices.**
 - ✅ [Sign up](https://minifetch.com/dashboard) for an account & get free starter credits. 🎉🎉
@@ -72,17 +72,15 @@ 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 /example- directories](https://github.com/Niche-Networks/minifetch-api/).
 
+All API methods default to POST unless you set options to `{ method: 'GET' }` and pass in as the second argument.
+
 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).
 
 ```js
-await client.checkAndRunSeoPageAudit(url);
-// Price: $0.01
-// Runs a full technical SEO audit on your URL. Combines data from
-// the other API endpoints and runs checks that each return a PASS/
-// WARN/ FAIL result with no black-box scoring. Just deterministic,
-// composable signal you can act on or pipe into an agent.
-// Audit rules are documented in the skill file:
-// https://minifetch.com/skills/seo-page-audit/SKILL.md
+await client.searchByKeyword("green tea");
+// Price: $0.002
+// Keyword web search by Ceramic.ai that returns ranked results as
+// structured JSON: a title, URL, and text snippet per result.
 
 await client.checkAndExtractUrlMetadata(url, options);
 // Price: $0.002
@@ -106,36 +104,45 @@ await client.checkAndExtractUrlLinks(url);
 // anchor text variants used for each) and top external domains by
 // link count.
 
-await client.checkAndExtractUrlPreview(url);
-// Price: $0.002
-// Extracts all fields used for a page's share previews: the lightweight
-// cards that represent the page on social platforms, chat apps, and AI.
-
 await client.checkAndExtractUrlContent(url, options);
 // Price: $0.002
 // For site owners auditing AI readability: returns the clean markdown
 // an LLM extracts from your page after nav, ads, & scripts are stripped.
 // See what survives for AEO and AI search; respects robots.txt.
 // Options: { includeMediaUrls: true } - defaults to false.
+
+await client.checkAndExtractUrlPreview(url);
+// Price: $0.002
+// Extracts all fields used for a page's share previews: the lightweight
+// cards that represent the page on social platforms, chat apps, and AI.
+
+await client.checkAndRunSeoPageAudit(url);
+// Price: $0.01
+// Runs a full technical SEO audit on your URL. Combines data from
+// the other API endpoints and runs checks that each return a PASS/
+// WARN/ FAIL result with no black-box scoring. Just deterministic,
+// composable signal you can act on or pipe into an agent.
+// Audit rules are documented in the skill file:
+// https://minifetch.com/skills/seo-page-audit/SKILL.md
 ```
 
 For max control, you can also use the following methods directly:
 ```js
 await client.preflightCheck(url, options);
-// Free: check if `minfetch` user agent can access target via robots.txt
+// Free: check if `minfetch` user agent can access target URL via robots.txt
 // Options: { "fresh": true } - bypass 24hr robots.txt cache, defaults to false
 
 // Paid methods:
-await client.runSeoPageAudit(url);
 await client.extractUrlMetadata(url, options); // same options as above
 await client.extractUrlLinks(url);
-await client.extractUrlPreview(url);
 await client.extractUrlContent(url, options); // same options as above
+await client.extractUrlPreview(url);
+await client.runSeoPageAudit(url);
 ```
 ---
 
 ### Error Types
-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.
+When you wrap the functions above in a try/catch, here are some of the errors you may encounter. You are never charged for target URLs that are blocked or error.
 
 - **"InvalidURLError: Invalid url ${url}"**
   - The URL is malformed in some way, correct it and try again.

package/dist/esm/client.js

@@ -1,12 +1,18 @@
 import { initConfig } from "./init.js";
-import { validateAndNormalizeUrl } from "./utils/validation.js";
+import { validateAndNormalizeUrl, validateAndNormalizeQuery } from "./utils/validation.js";
 import { handlePayment, handleApiKeyRequest } from "./utils/payment.js";
-import { InvalidUrlError, RobotsBlockedError, PaymentFailedError, ExtractionFailedError, NetworkError, } from "./types/errors.js";
+import { InvalidUrlError, InvalidQueryError, RobotsBlockedError, PaymentFailedError, ExtractionFailedError, SearchFailedError, 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;
@@ -18,23 +24,57 @@ export class MinifetchClient {
         this.config = initConfig(config);
         this.baseUrl = this.config.apiBaseUrl;
     }
+    /**
+     * Search the web by keyword (paid endpoint).
+     *
+     * Unlike the URL-based methods, this takes a search query rather than a URL and
+     * proxies to Minifetch's keyword search. Returns ranked results, each with a
+     * title, URL, and text snippet. `limit` and `descriptionLength` are convenience
+     * knobs the server clamps into range; the effective values (after clamping) are
+     * echoed back on `queryParameters`.
+     *
+     * @param query - keyword(s) to search for (1-50 characters)
+     * @param options
+     * @param options.limit - number of results, 1-10 (default 10). Out-of-range values are clamped.
+     * @param options.descriptionLength - max characters per snippet, 0-5000 (default 750, 0 = titles/URLs only). Out-of-range values are clamped.
+     * @param options.method - "GET" or "POST" (default POST)
+     * @throws {InvalidQueryError} if the query is empty or exceeds 50 characters
+     * @throws {SearchFailedError} if the search request fails
+     * @throws {PaymentFailedError} if x402 payment fails
+     * @throws {NetworkError} various reasons, check README
+     */
+    async searchByKeyword(query, options) {
+        try {
+            const cleanQuery = validateAndNormalizeQuery(query);
+            const params = { query: cleanQuery };
+            if (options?.limit !== undefined)
+                params.limit = options.limit;
+            if (options?.descriptionLength !== undefined)
+                params.descriptionLength = options.descriptionLength;
+            return await this._makeSearchRequest(params, options?.method);
+        }
+        catch (error) {
+            return this._rethrowSearchError(error, query, "Keyword search");
+        }
+    }
     /**
      * Check if URL is allowed by robots.txt (free preflight check — no auth required)
      *
      * @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}`);
             }
@@ -48,23 +88,34 @@ export class MinifetchClient {
         }
     }
     /**
-     * Run SEO page audit (paid endpoint)
+     * 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
-     * @throws {InvalidUrlError} if URL is invalid
-     * @throws {ExtractionFailedError} various reasons, check README
-     * @throws {PaymentFailedError} if x402 payment fails
-     * @throws {NetworkError} various reasons, check README
+     * @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 runSeoPageAudit(url) {
+    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 = 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 };
+            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, "Run SEO page audit");
+            return this._rethrowError(error, url, "Paid URL check");
         }
     }
     /**
@@ -75,6 +126,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 +135,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 +152,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 +173,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 +196,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,25 +205,47 @@ 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");
         }
     }
+    /**
+     * 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, options) {
+        try {
+            const normalizedUrl = validateAndNormalizeUrl(url);
+            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");
+        }
+    }
     /**
      * 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)
      */
-    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 +256,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 +267,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 +293,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 +313,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 +360,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}`);
             }
@@ -256,6 +369,45 @@ export class MinifetchClient {
             return { success: data.success, results: data.results };
         }
     }
+    /**
+     * Search-specific request path. Mirrors {@link _makeRequest} but for the
+     * keyword search endpoint: there is no URL, non-OK responses surface as
+     * SearchFailedError (carrying the query), and the server's clamped
+     * `queryParameters` echo is preserved rather than dropped.
+     *
+     * @param params - request params (query + optional limit/descriptionLength)
+     * @param method - "GET" or "POST" (default POST)
+     */
+    async _makeSearchRequest(params, method = DEFAULT_METHOD) {
+        const query = String(params.query);
+        const { url, init } = this._buildRequest(this._paidPath("/search/keyword"), params, method);
+        if (this.config.authMode === "x402") {
+            const { response, payment } = await handlePayment(url, this.config, init);
+            if (!response.ok) {
+                throw new SearchFailedError(query, `Keyword search failed: ${response.status} ${response.statusText}`, response.status);
+            }
+            const data = (await response.json());
+            return {
+                success: data.success,
+                queryParameters: data.queryParameters,
+                results: data.results,
+                payment,
+            };
+        }
+        else {
+            const { response } = await handleApiKeyRequest(url, this.config, init);
+            if (!response.ok) {
+                throw new SearchFailedError(query, `Keyword search failed: ${response.status} ${response.statusText}`, response.status);
+            }
+            const data = (await response.json());
+            // payment field intentionally omitted for apiKey auth — not applicable
+            return {
+                success: data.success,
+                queryParameters: data.queryParameters,
+                results: data.results,
+            };
+        }
+    }
     /**
      * Preflight check helper — throws RobotsBlockedError if not allowed
      *
@@ -284,4 +436,21 @@ export class MinifetchClient {
         }
         throw new ExtractionFailedError(url, `${label} failed: ${error instanceof Error ? error.message : "Unknown error"}`);
     }
+    /**
+     * Search sibling of {@link _rethrowError}: re-throw known search error types,
+     * wrapping anything else in SearchFailedError (which carries the query, not a URL).
+     *
+     * @param error
+     * @param query
+     * @param label
+     */
+    _rethrowSearchError(error, query, label) {
+        if (error instanceof InvalidQueryError ||
+            error instanceof SearchFailedError ||
+            error instanceof PaymentFailedError ||
+            error instanceof NetworkError) {
+            throw error;
+        }
+        throw new SearchFailedError(query, `${label} failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
 }

package/dist/esm/types/errors.js

@@ -120,3 +120,47 @@ export class NetworkError extends MinifetchError {
         Object.setPrototypeOf(this, NetworkError.prototype);
     }
 }
+/**
+ * Thrown when keyword-search query validation fails (empty, or over 50 chars).
+ * The query sibling of {@link InvalidUrlError} — searchByKeyword takes a query,
+ * not a URL, so bad input surfaces here instead.
+ */
+export class InvalidQueryError extends MinifetchError {
+    query;
+    /**
+     *
+     * @param query
+     * @param message
+     */
+    constructor(query, message) {
+        super(message || `Invalid query: ${query}`);
+        this.name = "InvalidQueryError";
+        this.query = query;
+        Object.setPrototypeOf(this, InvalidQueryError.prototype);
+    }
+}
+/**
+ * Thrown when a keyword search fails (non-OK response or unexpected error).
+ * The search sibling of {@link ExtractionFailedError}: it carries the `query`
+ * rather than a `url`, since search has no target URL.
+ */
+export class SearchFailedError extends MinifetchError {
+    query;
+    statusCode;
+    originalError;
+    /**
+     *
+     * @param query
+     * @param message
+     * @param statusCode
+     * @param originalError
+     */
+    constructor(query, message, statusCode, originalError) {
+        super(message);
+        this.name = "SearchFailedError";
+        this.query = query;
+        this.statusCode = statusCode;
+        this.originalError = originalError;
+        Object.setPrototypeOf(this, SearchFailedError.prototype);
+    }
+}

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/esm/utils/validation.js

@@ -1,8 +1,13 @@
-import { InvalidUrlError } from "../types/errors.js";
+import { InvalidUrlError, InvalidQueryError } from "../types/errors.js";
 /**
  * Maximum allowed URL length
  */
 const MAX_URL_LENGTH = 2048;
+/**
+ * Maximum allowed search-query length. Mirrors Ceramic's hard cap on the server
+ * so we fail fast client-side instead of spending a paid call on a 400.
+ */
+const MAX_QUERY_LENGTH = 50;
 /**
  * Allowed URL protocols
  */
@@ -77,6 +82,27 @@ export function validateAndNormalizeUrl(url) {
     }
     return normalized;
 }
+/**
+ * Validate and normalize a keyword-search query.
+ * Mirrors the server: strips null bytes, normalizes unicode, trims, then enforces
+ * the same non-empty / 50-char rules so bad input fails before a paid call.
+ *
+ * @param query
+ * @throws {InvalidQueryError} if the query is empty or exceeds 50 characters
+ */
+export function validateAndNormalizeQuery(query) {
+    if (!query || typeof query !== "string") {
+        throw new InvalidQueryError(String(query ?? ""), "Query must be a non-empty string");
+    }
+    const cleaned = query.replace(/\0/g, "").normalize("NFC").trim();
+    if (!cleaned) {
+        throw new InvalidQueryError(query, "Query must not be empty");
+    }
+    if (cleaned.length > MAX_QUERY_LENGTH) {
+        throw new InvalidQueryError(cleaned, `Query exceeds maximum length of ${MAX_QUERY_LENGTH} characters`);
+    }
+    return cleaned;
+}
 /**
  * Check if hostname is localhost or private IP
  *

package/dist/types/client.d.ts

@@ -1,10 +1,14 @@
-import type { ClientConfig } from "./types/config.js";
-import type { PreflightCheckResponse, PaidEndpointResponse } from "./types/responses.js";
+import type { ClientConfig, HttpMethod } from "./types/config.js";
+import type { PreflightCheckResponse, PaidEndpointResponse, SearchKeywordResponse } 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;
@@ -13,28 +17,64 @@ export declare class MinifetchClient {
      * @param config - Either { network, privateKey } for x402 or { apiKey } for API key auth
      */
     constructor(config: ClientConfig);
+    /**
+     * Search the web by keyword (paid endpoint).
+     *
+     * Unlike the URL-based methods, this takes a search query rather than a URL and
+     * proxies to Minifetch's keyword search. Returns ranked results, each with a
+     * title, URL, and text snippet. `limit` and `descriptionLength` are convenience
+     * knobs the server clamps into range; the effective values (after clamping) are
+     * echoed back on `queryParameters`.
+     *
+     * @param query - keyword(s) to search for (1-50 characters)
+     * @param options
+     * @param options.limit - number of results, 1-10 (default 10). Out-of-range values are clamped.
+     * @param options.descriptionLength - max characters per snippet, 0-5000 (default 750, 0 = titles/URLs only). Out-of-range values are clamped.
+     * @param options.method - "GET" or "POST" (default POST)
+     * @throws {InvalidQueryError} if the query is empty or exceeds 50 characters
+     * @throws {SearchFailedError} if the search request fails
+     * @throws {PaymentFailedError} if x402 payment fails
+     * @throws {NetworkError} various reasons, check README
+     */
+    searchByKeyword(query: string, options?: {
+        limit?: number;
+        descriptionLength?: number;
+        method?: HttpMethod;
+    }): Promise<SearchKeywordResponse>;
     /**
      * Check if URL is allowed by robots.txt (free preflight check — no auth required)
      *
      * @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>;
     /**
-     * Run SEO page audit (paid endpoint)
+     * 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
-     * @throws {InvalidUrlError} if URL is invalid
-     * @throws {ExtractionFailedError} various reasons, check README
-     * @throws {PaymentFailedError} if x402 payment fails
-     * @throws {NetworkError} various reasons, check README
+     * @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
      */
-    runSeoPageAudit(url: string): Promise<PaidEndpointResponse>;
+    _exercisePaidUrlCheck(url: string, options?: {
+        fresh?: boolean;
+        method?: HttpMethod;
+    }): Promise<PaidEndpointResponse>;
     /**
      * Extract URL metadata (paid endpoint)
      *
@@ -43,6 +83,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 +93,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 +137,33 @@ export declare class MinifetchClient {
      */
     extractUrlContent(url: string, options?: {
         includeMediaUrls?: 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, options?: {
+        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 +173,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 +210,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,15 +225,38 @@ 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;
+    /**
+     * Search-specific request path. Mirrors {@link _makeRequest} but for the
+     * keyword search endpoint: there is no URL, non-OK responses surface as
+     * SearchFailedError (carrying the query), and the server's clamped
+     * `queryParameters` echo is preserved rather than dropped.
+     *
+     * @param params - request params (query + optional limit/descriptionLength)
+     * @param method - "GET" or "POST" (default POST)
+     */
+    private _makeSearchRequest;
     /**
      * Preflight check helper — throws RobotsBlockedError if not allowed
      *
@@ -166,4 +271,13 @@ export declare class MinifetchClient {
      * @param label
      */
     private _rethrowError;
+    /**
+     * Search sibling of {@link _rethrowError}: re-throw known search error types,
+     * wrapping anything else in SearchFailedError (which carries the query, not a URL).
+     *
+     * @param error
+     * @param query
+     * @param label
+     */
+    private _rethrowSearchError;
 }

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/types/errors.d.ts

@@ -84,3 +84,35 @@ export declare class NetworkError extends MinifetchError {
      */
     constructor(message: string, originalError?: Error);
 }
+/**
+ * Thrown when keyword-search query validation fails (empty, or over 50 chars).
+ * The query sibling of {@link InvalidUrlError} — searchByKeyword takes a query,
+ * not a URL, so bad input surfaces here instead.
+ */
+export declare class InvalidQueryError extends MinifetchError {
+    readonly query: string;
+    /**
+     *
+     * @param query
+     * @param message
+     */
+    constructor(query: string, message?: string);
+}
+/**
+ * Thrown when a keyword search fails (non-OK response or unexpected error).
+ * The search sibling of {@link ExtractionFailedError}: it carries the `query`
+ * rather than a `url`, since search has no target URL.
+ */
+export declare class SearchFailedError extends MinifetchError {
+    readonly query: string;
+    readonly statusCode?: number;
+    readonly originalError?: Error;
+    /**
+     *
+     * @param query
+     * @param message
+     * @param statusCode
+     * @param originalError
+     */
+    constructor(query: string, message: string, statusCode?: number, originalError?: Error);
+}

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

@@ -48,3 +48,38 @@ export interface PaymentInfo {
     /** Link to view transaction on block explorer **/
     explorerLink: string;
 }
+/**
+ * A single keyword-search result.
+ */
+export interface SearchKeywordResult {
+    /** Title of the result page */
+    title: string;
+    /** URL of the result page */
+    url: string;
+    /** Text snippet from the result page, trimmed to the requested descriptionLength */
+    description: string;
+}
+/**
+ * Response from the keyword search endpoint.
+ *
+ * Unlike PaidEndpointResponse, this preserves `queryParameters` — the effective
+ * request params after the server clamps `limit`/`descriptionLength` into range.
+ * That echo is how a caller learns what actually ran (no black box).
+ */
+export interface SearchKeywordResponse {
+    /** Minifetch API success (200, ok) */
+    success: boolean;
+    /** Effective params after server-side clamping. */
+    queryParameters: {
+        query: string;
+        limit: number;
+        descriptionLength: number;
+    };
+    /** Ranked search results. */
+    results: Array<{
+        data: SearchKeywordResult;
+        error?: Record<string, any>;
+    }>;
+    /** Payment information — only present for paid x402 requests. */
+    payment?: PaymentInfo;
+}

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/dist/types/utils/validation.d.ts

@@ -6,3 +6,12 @@
  * @throws {InvalidUrlError} if URL is invalid
  */
 export declare function validateAndNormalizeUrl(url: string): string;
+/**
+ * Validate and normalize a keyword-search query.
+ * Mirrors the server: strips null bytes, normalizes unicode, trims, then enforces
+ * the same non-empty / 50-char rules so bad input fails before a paid call.
+ *
+ * @param query
+ * @throws {InvalidQueryError} if the query is empty or exceeds 50 characters
+ */
+export declare function validateAndNormalizeQuery(query: string): string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "minifetch-api",
-  "version": "1.5.1",
-  "description": "Minifetch.com API Client. Scrape, extract and audit web pages. Pay per URL, no subscription.",
+  "version": "1.7.0",
+  "description": "Minifetch.com API Client. Search, scrape, extract and SEO audit web pages. Pay per fetch, no subscription.",
   "type": "module",
   "main": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
@@ -25,6 +25,8 @@
     "metadata extraction",
     "content extraction",
     "link extraction",
+    "search",
+    "keyword search",
     "hosted",
     "meta tags",
     "open graph",