minifetch-api 1.6.0 → 1.7.1

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.
+**[Search, scrape, extract & SEO audit web pages. Minifetch](https://minifetch.com)** is a hosted toolkit for web developers and AI agents. 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,19 +72,18 @@ 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/).
 
-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.
 
+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", options);
+// Price: $0.002
+// Keyword web search by Ceramic.ai that returns ranked results as
+// structured JSON: a title, URL, and text snippet per result.
+// Options:
+// { limit: 10 } - defaults to 10 results, set to 1-10
+// { descriptionLength: 750 } - defaults to 750, set to 0-5000
 
 await client.checkAndExtractUrlMetadata(url, options);
 // Price: $0.002
@@ -108,36 +107,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,7 +1,7 @@
 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, ConfigurationError, } 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";
 /**
@@ -24,6 +24,39 @@ 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)
      *
@@ -85,27 +118,6 @@ export class MinifetchClient {
             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, 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");
-        }
-    }
     /**
      * Extract URL metadata (paid endpoint)
      *
@@ -202,6 +214,27 @@ export class MinifetchClient {
             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.
@@ -336,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
      *
@@ -364,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/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,5 +1,5 @@
 import type { ClientConfig, HttpMethod } from "./types/config.js";
-import type { PreflightCheckResponse, PaidEndpointResponse } from "./types/responses.js";
+import type { PreflightCheckResponse, PaidEndpointResponse, SearchKeywordResponse } from "./types/responses.js";
 /**
  * Main Minifetch API client.
  * Supports two auth modes:
@@ -17,6 +17,30 @@ 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)
      *
@@ -51,20 +75,6 @@ export declare class MinifetchClient {
         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, options?: {
-        method?: HttpMethod;
-    }): Promise<PaidEndpointResponse>;
     /**
      * Extract URL metadata (paid endpoint)
      *
@@ -129,6 +139,20 @@ export declare class MinifetchClient {
         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.
@@ -223,6 +247,16 @@ export declare class MinifetchClient {
      * @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
      *
@@ -237,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/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/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.6.0",
-  "description": "Minifetch.com API Client. Scrape, extract and audit web pages. Pay per URL, no subscription.",
+  "version": "1.7.1",
+  "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",