minifetch-api 1.0.1 → 1.1.0

package/README.md

@@ -7,11 +7,11 @@
 
 **Fetch & extract data from web pages.** [Minifetch.com](https://minifetch.com) provides composable extraction APIs that humans and AI Agents can autonomously discover, orchestrate, and pay for— making web pages simple to access. Pay-as-you-go at competitive prices.
 
-**Full [API docs are here](https://minifetch.com/docs/api)**, including example response data & prices. For AI Agents, read the [LLMs.txt](https://minifetch.com/llms.txt).
+**Full [API docs are here](https://minifetch.com/docs/api)**, including example queries, response data & prices. For AI Agents, read the [LLMs.txt](https://minifetch.com/llms.txt) instead.
 
-**Payments** work with [x402](https://www.x402.org/) USDC stablecoin micropayments on Coinbase's Base & Solana blockchain networks. Transaction fees are free. If you'd like to use a traditional credit card & API key instead, sign up for the waitlist and we'll let you know when it's ready: [forms.gle/rkMi7T23bHJc8XFw9](https://forms.gle/rkMi7T23bHJc8XFw9)
+**Payments** work with [x402](https://www.x402.org/) USDC stablecoin micropayments on Coinbase's Base & Solana blockchain networks. Transaction fees are free. If you'd like to use a traditional credit card & API key instead, sign up for the waitlist: [forms.gle/rkMi7T23bHJc8XFw9](https://forms.gle/rkMi7T23bHJc8XFw9)
 
-**Bulk fetch and extract** for building datasets is coming soon, sign up for the waitlist and we'll let you know when it's ready: [forms.gle/rkMi7T23bHJc8XFw9](https://forms.gle/rkMi7T23bHJc8XFw9)
+**Bulk fetch and extract** for building datasets is coming soon, sign up for the waitlist: [forms.gle/rkMi7T23bHJc8XFw9](https://forms.gle/rkMi7T23bHJc8XFw9)
 
 ## Prerequisites
 
@@ -51,34 +51,38 @@ try {
 
 After you initialize the client (above), you have the following methods available to use. The "checkAndExtract" API methods provided help you avoid paying for blocked URLs and return more granular info about why a URL may or may not return data. There is no charge for blocked upstream URLs.
 
-[Price list and example data for each method is here.](https://minifetch.com/docs/api#example-data)
+**Price list** and example data for each method [is here.](https://minifetch.com/docs/api#example-data)
 
-Requests exceeding rate limits return `503` errors. This is intentional — back off and retry, max 5-10 queries per second. We'll add bulk fetch and extract in the future. Sign up for the [waitlist here](https://forms.gle/rkMi7T23bHJc8XFw9).
+**Rate limit** Requests exceeding rate limits return `503` errors. This is intentional — back off and retry, max 5-10 queries per second. We'll add bulk fetch and extract in the future. Sign up for the [waitlist](https://forms.gle/rkMi7T23bHJc8XFw9).
+
+**Code examples** can be found in the github repository under /test.
 
 - **`client.checkAndExtractUrlPreview(url)`**
   - Extracts a light, token-efficient preview of a URL: title, description, and image (only).
 
 - **`client.checkAndExtractUrlContent(url, options)`**
   - Extracts a clean, token-efficient content summary as markdown from a URL. Removes ads, nav, scripts. Much more efficient than raw HTML fetches for LLMs.
-  - Options: `{ includeMediaUrls: true }`, defaults to false
+  - Option: `{ includeMediaUrls: true }`, defaults to false
 
 - **`client.checkAndExtractUrlLinks(url)`**
   - Extracts all links from a URL categorized by type (internal/external/anchor) with SEO metadata. Detects image links, nofollow attributes, and analyzes external domain distribution.
 
 - **`client.checkAndExtractUrlMetadata(url, options)`**
-  - Extracts rich structured metadata from a URL: title, description, og/twitter tags, json-ld, images, headings, response headers, and more. Perfect for SEO research or metadata indexing & analysis. Largest response size of the client methods available.
-  - Options: `{ includeResponseBody: true }`, defaults to false
+  - Extracts rich structured metadata from a URL: title, description, og/twitter tags, json-ld, images, headings, response headers, and more. Perfect for SEO research or metadata indexing & analysis. Largest response size of the client methods available. Calling this method and setting verbosity to "full" is the drop-in replacement for the [`url-metadata`](https://www.npmjs.com/package/url-metadata) package.
+  - Option: `{ verbosity: "full" }`, defaults to "standard"
+  - Option: `{ includeResponseBody: true }`, defaults to false
 
-For maximum control, you can also use the following methods directly:
+***For maximum control, you can also use the following methods directly:***
 
 - **`client.preflightCheck(url)`**
-  - Standalone call to check if a URL is allowed to be fetched according to the website's robots.txt file. Use this free endpoint before using our other paid endpoints to avoid spending extra on un-fetchable URLs
+  - Standalone call to check if a URL is allowed to be fetched according to the website's robots.txt file. Use this free endpoint before using our other paid endpoints to help avoid spending extra on un-fetchable URLs
 - **`client.extractUrlPreview(url)`**
 - **`client.extractUrlContent(url, options)`**
-  - Options: `{ includeMediaUrls: true }`, defaults to false
+  - Option: `{ includeMediaUrls: true }`, defaults to false
 - **`client.extractUrlLinks(url)`**
 - **`client.extractUrlMetadata(url, options)`**
-  - Options: `{ includeResponseBody: true }`, defaults to false
+  - Option: `{ verbosity: "full" }`, defaults to "standard"
+  - Option: `{ includeResponseBody: true }`, defaults to false
 
 ### Error Types
 When you wrap the functions above in a try/catch, here are the errors you may encounter:

package/dist/esm/client.js

@@ -51,9 +51,11 @@ export class MinifetchClient {
      * @param url
      * @param options
      * @param options.includeResponseBody
+     * @param options.verbosity - Controls response detail level: "standard" (default) or "full"
      * @throws {InvalidUrlError} if URL is invalid
+     * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if payment fails
-     * @throws {ExtractionFailedError} if extraction fails
+     * @throws {NetworkError} various reasons, check README
      */
     async extractUrlMetadata(url, options) {
         try {
@@ -61,6 +63,9 @@ export class MinifetchClient {
             const normalizedUrl = validateAndNormalizeUrl(url);
             // Build request URL with optional params
             const params = new URLSearchParams({ url: normalizedUrl });
+            if (options?.verbosity) {
+                params.set("verbosity", options.verbosity);
+            }
             if (options?.includeResponseBody) {
                 params.set("includeResponseBody", "true");
             }
@@ -95,8 +100,9 @@ export class MinifetchClient {
      *
      * @param url
      * @throws {InvalidUrlError} if URL is invalid
+     * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if payment fails
-     * @throws {ExtractionFailedError} if extraction fails
+     * @throws {NetworkError} various reasons, check README
      */
     async extractUrlLinks(url) {
         try {
@@ -130,8 +136,9 @@ export class MinifetchClient {
      *
      * @param url
      * @throws {InvalidUrlError} if URL is invalid
+     * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if payment fails
-     * @throws {ExtractionFailedError} if extraction fails
+     * @throws {NetworkError} various reasons, check README
      */
     async extractUrlPreview(url) {
         try {
@@ -170,8 +177,9 @@ export class MinifetchClient {
      * @param options
      * @param options.includeMediaUrls
      * @throws {InvalidUrlError} if URL is invalid
+     * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if payment fails
-     * @throws {ExtractionFailedError} if extraction fails
+     * @throws {NetworkError} various reasons, check README
      */
     async extractUrlContent(url, options) {
         try {
@@ -213,7 +221,8 @@ export class MinifetchClient {
      *
      * @param url
      * @param options
-     * @param options.includeResponseBody
+     * @param options.verbosity - Controls response detail level: "standard" (default) or "full"
+     * @param options.includeResponseBody - Include raw response body in result
      */
     async checkAndExtractUrlMetadata(url, options) {
         const checkResponse = await this.preflightUrlCheck(url);

package/dist/types/client.d.ts

@@ -26,11 +26,14 @@ export declare class MinifetchClient {
      * @param url
      * @param options
      * @param options.includeResponseBody
+     * @param options.verbosity - Controls response detail level: "standard" (default) or "full"
      * @throws {InvalidUrlError} if URL is invalid
+     * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if payment fails
-     * @throws {ExtractionFailedError} if extraction fails
+     * @throws {NetworkError} various reasons, check README
      */
     extractUrlMetadata(url: string, options?: {
+        verbosity?: "standard" | "full";
         includeResponseBody?: boolean;
     }): Promise<PaidEndpointResponse>;
     /**
@@ -38,8 +41,9 @@ export declare class MinifetchClient {
      *
      * @param url
      * @throws {InvalidUrlError} if URL is invalid
+     * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if payment fails
-     * @throws {ExtractionFailedError} if extraction fails
+     * @throws {NetworkError} various reasons, check README
      */
     extractUrlLinks(url: string): Promise<PaidEndpointResponse>;
     /**
@@ -47,8 +51,9 @@ export declare class MinifetchClient {
      *
      * @param url
      * @throws {InvalidUrlError} if URL is invalid
+     * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if payment fails
-     * @throws {ExtractionFailedError} if extraction fails
+     * @throws {NetworkError} various reasons, check README
      */
     extractUrlPreview(url: string): Promise<PaidEndpointResponse>;
     /**
@@ -58,8 +63,9 @@ export declare class MinifetchClient {
      * @param options
      * @param options.includeMediaUrls
      * @throws {InvalidUrlError} if URL is invalid
+     * @throws {ExtractionFailedError} various reasons, check README
      * @throws {PaymentFailedError} if payment fails
-     * @throws {ExtractionFailedError} if extraction fails
+     * @throws {NetworkError} various reasons, check README
      */
     extractUrlContent(url: string, options?: {
         includeMediaUrls?: boolean;
@@ -70,9 +76,11 @@ export declare class MinifetchClient {
      *
      * @param url
      * @param options
-     * @param options.includeResponseBody
+     * @param options.verbosity - Controls response detail level: "standard" (default) or "full"
+     * @param options.includeResponseBody - Include raw response body in result
      */
     checkAndExtractUrlMetadata(url: string, options?: {
+        verbosity?: "standard" | "full";
         includeResponseBody?: boolean;
     }): Promise<PaidEndpointResponse>;
     /**

package/package.json

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