scavio 0.14.0 → 0.16.0

package/README.md

@@ -1,6 +1,20 @@
 # Scavio
 
-TypeScript SDK for the [Scavio Search API](https://scavio.dev) — real-time Google, Amazon, Walmart, YouTube, Reddit, TikTok, TikTok Shop, Instagram, X, and LinkedIn data.
+TypeScript SDK for the [Scavio API](https://scavio.dev) — real-time web scraping
+and data extraction across 31 platforms on one API key, plus `extract()` to read
+any URL as clean Markdown.
+
+Structured JSON in, structured JSON out. No proxies, no headless browsers, no
+per-site parsers to maintain.
+
+- **Search and SERP** — Google (organic, news, maps, shopping, flights, hotels, trends, AI Mode)
+- **E-commerce** — Amazon, Walmart, eBay, Target, Home Depot, TikTok Shop
+- **Real estate and travel** — Zillow, Redfin, Booking, Airbnb, Tripadvisor
+- **Reviews and local** — Yelp, G2, Capterra, Glassdoor, App Store, Google Play
+- **Jobs and companies** — Indeed, Glassdoor, SEC EDGAR, Companies House
+- **Ads transparency** — Google Ads Transparency Center, Meta Ad Library
+- **Social and video** — YouTube, TikTok, Instagram, Threads, X, LinkedIn, Reddit, Kuaishou
+- **Any other page** — `extract()` turns a URL into Markdown, plain text or raw HTML
 
 ## Install
 
@@ -21,6 +35,9 @@ const results = await client.search({ query: "web scraping api" });
 // Amazon product lookup
 const product = await client.amazon.product({ asin: "B09V3KXJPB" });
 
+// Read any page as Markdown
+const page = await client.extract({ url: "https://example.com/pricing" });
+
 // Check usage
 const usage = await client.getUsage();
 ```
@@ -32,7 +49,7 @@ const client = new Scavio({
   apiKey: "sk_...",               // or set SCAVIO_API_KEY env var
   baseUrl: "https://api.scavio.dev", // default
   timeout: 30_000,                   // ms, default
-  maxRequestsPerSecond: 1,           // 1-10, default 1
+  maxRequestsPerSecond: 1,           // 1-50, default 1
   maxRetries: 2,                     // default 2, set 0 to disable
 });
 ```
@@ -41,15 +58,48 @@ const client = new Scavio({
 only to transient failures — HTTP 429, 500, 502, 503, 504 and network or timeout
 errors. Backoff is exponential with full jitter, capped at 8s, and a
 `Retry-After` header is honored when the API sends one. Non-transient errors
-(400, 401, 402, 404) are never retried.
+(400, 401, 402, 404, 422) are never retried.
 
 `maxRequestsPerSecond` throttles the client so it never sends more than N
 requests in any one-second window. Your plan also has a server-side concurrency
-limit on simultaneous in-flight requests: 1 on free and pay-as-you-go, 2 on
-Project, 3 on Bootstrap, 5 on Startup, 10 on Growth.
+limit on simultaneous in-flight requests: 1 on free and pay-as-you-go, 5 on
+Project, 10 on Bootstrap, 15 on Startup, 50 on Growth, and unlimited on
+Enterprise.
 
 ## API Reference
 
+### Extract (any URL)
+
+`extract()` is a core endpoint, not a platform, so it lives on the client itself.
+It reads any page and hands it back as readability Markdown, plain text or raw
+HTML — the read-a-page primitive an agent or a RAG ingest needs.
+
+```typescript
+const page = await client.extract({
+  url: "https://example.com/pricing",
+  format: "markdown",   // "html" | "markdown" | "text", default "markdown"
+  mode: "normal",       // "normal" | "advanced" | "ultra", default "normal"
+});
+
+page.content;        // the page body
+page.content_length; // characters returned
+```
+
+Credits depend on `mode`, not on a flat per-call price: `normal` costs 1,
+`advanced` costs 1, `ultra` costs 2. Billing happens only on a successful
+extraction — a dead link, bot wall or timeout costs nothing.
+
+- `normal` is a plain datacenter fetch. Start here.
+- `advanced` renders the page in a headless browser. Use it when the content is
+  built client-side.
+- `ultra` goes through residential IPs. Use it only when a bot wall blocks the
+  other two.
+
+`html` is the raw page. `markdown` is a readability extraction with the
+boilerplate stripped. `text` is that markdown flattened to plain text. URLs are
+http(s) only, a bare host is upgraded to https, and loopback, private,
+link-local and cloud-metadata hosts are rejected with a 400.
+
 ### Google
 
 Each method hits its own `/api/v2/google*` endpoint and returns Google's full
@@ -128,20 +178,47 @@ instead of the previous raw provider payload.
 
 ### Walmart
 
+Seven endpoints. `search` and `product` changed shape in 0.15.0 and the other
+five are new.
+
 ```typescript
-// Search products
 await client.walmart.search({
   query: "tv",
-  min_price: 100,          // optional
-  max_price: 500,          // optional
+  domain: "com",           // "com" | "ca" | "com.mx"
+  page: 2,                 // 1-indexed
+  sort_by: "rating_high",
+  min_price: 100,
+  max_price: 500,
 });
 
-// Get product by ID
-await client.walmart.product({
-  product_id: "123456",
-});
+await client.walmart.product({ product_id: "13544111159" });
+await client.walmart.reviews({ product_id: "13544111159", page: 2 });
+await client.walmart.category({ category_id: "3944_133251_1095191" });
+await client.walmart.offers({ product_id: "13544111159" });
+await client.walmart.seller({ seller_id: "101138578" });
+await client.walmart.sellerProducts({ seller_id: "101138578" });
 ```
 
+Credits are a function of the body on `search` and `category`: `domain` "com" and
+"ca" cost 1 credit, "com.mx" costs 2. The other five endpoints always cost 1.
+
+#### Walmart changed in 0.15.0 (breaking)
+
+- `device`, `delivery_zip` and `store_id` are retired. Sending one still returns
+  200, with a top-level `warnings` array naming what was ignored.
+- `domain` is **not** retired — it is the price-bearing param, and it is accepted
+  on `search` and `category` only. Walmart.ca product pages cannot be fetched, so
+  every product-keyed endpoint is walmart.com only.
+- `page` (1-indexed) is the paging param; `start_page` remains a deprecated alias.
+- `sort_by` gained `rating_high` and `new`.
+- `fulfillment_speed` is `today` or `tomorrow` only. There is deliberately no
+  `2_days` (it leaks 3-4 day items) and no `anytime` — omit the param instead.
+- `offers` returns the **buy-box seller only**, not the full offer list.
+- `seller_id` must be the numeric catalog id (`seller_catalog_id`, returned by
+  `product` and `offers`). The GUID form of the id returns 404.
+- `sellerProducts` has **no pagination** — roughly the first 40 server-rendered
+  items. `total_count` reports the seller's real catalog size.
+
 ### YouTube
 
 Credit cost varies by endpoint: `transcript` costs 8; `streams` costs 3;
@@ -431,6 +508,389 @@ await client.instagram.userFollowers({ username: "instagram", count: 50 });
 await client.instagram.userFollowings({ username: "instagram" });
 ```
 
+### Threads
+
+Six endpoints, and the credit cost is a function of the body: **2 credits when
+you address a user by `user_id`, 4 when you address them by `username`.** The
+upstream handle lookup is dead, so a handle buys a second call. Only `profile`,
+`userPosts` and `userReplies` are username-keyed; `post`, `postComments` and
+`searchUsers` always cost 2.
+
+```typescript
+// Resolve the handle once, then stay on the cheap path
+const found = await client.threads.searchUsers({ query: "zuck" });
+
+await client.threads.profile({ user_id: "63625256886" });
+await client.threads.userPosts({ user_id: "63625256886", cursor });
+await client.threads.userReplies({ user_id: "63625256886" });
+await client.threads.post({ url: "https://www.threads.net/@zuck/post/..." });
+await client.threads.postComments({ post_id: "3141..." });
+```
+
+There is no Threads content search — `searchUsers` is people search and it is
+the only search Threads exposes. Missing or conflicting identifiers return 422,
+not 400; no match returns 404.
+
+### Kuaishou
+
+Fourteen endpoints, priced **per endpoint** rather than flat: `videosBatch`
+costs 40, `profile` and the four `search*` methods cost 10, `video` costs 2, and
+everything else costs 1.
+
+```typescript
+await client.kuaishou.userResolve({ share_link: "https://v.kuaishou.com/..." }); // 1
+await client.kuaishou.userPosts({ user_id: "3xabc..." });                // 1
+await client.kuaishou.tagFeed({ tag: "美食" });                           // 1
+await client.kuaishou.video({ photo_id: "3xdef..." });                   // 2
+await client.kuaishou.searchVideos({ keyword: "coffee" });               // 10
+await client.kuaishou.videosBatch({ photo_ids: ["3xdef...", "3xghi..."] }); // 40
+```
+
+`videosBatch` costs 40 whether you send 1 id or 20, so fill the batch. If all
+you have is a share link, `userResolve()` turns it into a user id for 1 credit
+rather than paying 10 for `profile()`. Missing identifiers return 422.
+
+### eBay
+
+```typescript
+await client.ebay.search({ query: "airpods pro", sold: true, per_page: 120 });
+await client.ebay.search({ seller: "musicmagpie" });  // no keyword needed
+await client.ebay.product({ item_id: "126543210987" });
+await client.ebay.seller({ seller: "musicmagpie" });
+```
+
+1 credit per call. `sold: true` searches completed listings that actually sold —
+the price-research view; eBay publishes no headline count there, so
+`total_results` comes back null. `per_page` accepts only 60, 120 or 240. `seller`
+is a profile endpoint and cannot enumerate a catalogue — page a seller's
+inventory through `search({ seller })` instead.
+
+### Target
+
+```typescript
+await client.target.search({ keyword: "office chair", store_id: "1234" });
+await client.target.category({ category_id: "5xtg6" });
+await client.target.product({ tcin: "82291396" });
+await client.target.reviews({ tcin: "82291396" });
+```
+
+1 credit per call, but these are the slowest endpoints in the SDK: product about
+4s, search about 9s, category about 37s, reviews about 40s. Raise `timeout`
+accordingly. `reviews` returns at most 8 review bodies whatever `review_count`
+says, and `limit` only trims — there is no paging. `seller_*` is null on
+first-party stock, which means "sold by Target"; only Target Plus marketplace
+listings name a vendor.
+
+### Home Depot
+
+```typescript
+await client.homeDepot.search({ query: "cordless drill", page: 2 });
+await client.homeDepot.product({ item_id: "313159056" });
+await client.homeDepot.reviews({ item_id: "313159056", page: 2 });
+```
+
+2 credits per call. Search page size is fixed at 12, so paging is the only way
+to read further; reviews are 30 per page and a page past `total_pages` is a 404.
+`product` carries only a 10-review preview — `reviews` is the paginated surface.
+
+### Zillow
+
+```typescript
+await client.zillow.search({
+  location: "Austin, TX",
+  listing_status: "for_rent",
+  min_price: 1500,        // MONTHLY RENT on for_rent
+  max_price: 3000,
+});
+await client.zillow.property({ zpid: "29433327" });
+await client.zillow.agentReviews({ screen_name: "jane-doe" });
+```
+
+1 credit per call. A bare ZIP works on its own but cannot be combined with a
+filter or a sort — Zillow then geolocates the request and answers about another
+city, so pass the city name whenever you filter. On `listing_status: "for_rent"`,
+`min_price`/`max_price` mean monthly rent. `agentReviews` addresses an agent
+profile, not a property, and returns the five reviews Zillow server-renders
+(`total_review_count` is the real total). An unresolvable region is a 404.
+
+### Redfin
+
+```typescript
+await client.redfin.search({ location: "https://www.redfin.com/city/30749/TX/Austin" });
+await client.redfin.search({ region_id: 30749, region_type: 6 });  // 6 = city
+await client.redfin.property({ property_id: "185301234" });
+await client.redfin.market({ region_id: 30749, region_type: 6 });
+```
+
+1 credit per call. **City names are not accepted** on `location` — pass a
+redfin.com region URL (`/city/`, `/neighborhood/`, `/county/`, `/zipcode/`) or
+`region_id` plus `region_type`, which must be sent together. `region_id` is not
+a ZIP code. `sold_within_days` is only valid with `listing_status: "sold"`.
+`days_on_market` is always null in the response — do not build on it.
+
+### Booking
+
+```typescript
+await client.booking.search({
+  destination: "Lisbon",
+  checkin: "2026-09-10",
+  checkout: "2026-09-13",   // send both or neither
+  adults: 2,
+  currency: "USD",
+});
+await client.booking.hotel({ hotel: "the-independente" });
+await client.booking.reviews({ hotel: "the-independente" });
+```
+
+1 credit per call. `checkin` and `checkout` must be sent together — Booking
+ignores a lone check-in and prices its own date range. `hotel` and `reviews`
+take dates for the same reason: Booking prices a stay, and the response echoes
+whichever dates were used. `currency` defaults to USD; without it Booking prices
+off the proxy exit and two identical requests disagree. A search with neither
+`destination` nor `dest_id` returns Booking's homepage and still costs a credit.
+
+### Airbnb
+
+```typescript
+await client.airbnb.search({
+  location: "Barcelona",
+  check_in: "2026-09-10",
+  check_out: "2026-09-15",  // send both or neither
+  currency: "USD",
+});
+await client.airbnb.listing({ listing_id: "1234567890" });
+await client.airbnb.reviews({ listing_id: "1234567890", limit: 50, offset: 50 });
+```
+
+1 credit per call. **Prices are search-only** — the listing page carries no
+nightly rate under any parameters. A dateless search defaults to +30d for 5
+nights and Airbnb A/Bs both the window and the prices, so the response flags it
+as `dates_are_defaulted`; send real dates for anything you intend to compare.
+The rating breakdown and review tags live on `listing`, while `reviews` returns
+the review bodies with `limit`/`offset` paging.
+
+### Tripadvisor
+
+**Start with `locations()`.** Every other endpoint is keyed by ids that exist
+only inside TripAdvisor's own URLs.
+
+```typescript
+const places = await client.tripadvisor.locations({ query: "Le Bernardin" });
+await client.tripadvisor.search({ geo_id: "60763", category: "restaurants" });
+await client.tripadvisor.location({ location_id: "426986", geo_id: "60763" });
+await client.tripadvisor.reviews({ location_id: "426986", geo_id: "60763", page: 2 });
+```
+
+2 credits per call. A geo row from `locations()` gives the `geo_id` that
+`search()` takes; a business row gives the `geo_id` + `location_id` pair that
+`location()` and `reviews()` take. Page 1 of the reviews already ships inside
+`location()`, so use `reviews()` to page past it. Review page size differs by
+family (15 restaurants, 10 hotels and attractions), consecutive pages can repeat
+one review at the boundary (de-duplicate on `review_id`), and a page past the
+last is a 404.
+
+### Yelp
+
+```typescript
+await client.yelp.search({ term: "ramen", location: "Seattle, WA" });
+await client.yelp.business({ business_id: "..." });
+await client.yelp.reviews({ business_id: "...", page: 2 });  // page 2, not 1
+```
+
+2 credits per call. `location` is effectively required — without it Yelp
+geolocates off the proxy exit and the same request answers about a different
+metro run to run. **Reviews page 1 is redundant**: it re-fetches the document
+`business()` already returned and costs another 2 credits, so start at page 2.
+Page size is fixed at 10 and a page past the last is a 404.
+
+### Indeed
+
+```typescript
+await client.indeed.search({
+  query: "data engineer",
+  location: "Remote",
+  radius: 25,          // 0, 5, 10, 15, 25, 35, 50 or 100 only
+  max_age_days: 7,     // 1, 3, 7 or 14 only
+});
+await client.indeed.job({ job_id: "a1b2c3d4e5f6" });
+await client.indeed.company({ company: "Stripe" });
+await client.indeed.companyReviews({ company: "Stripe", page: 2 });
+```
+
+2 credits per call. `radius` and `max_age_days` are closed sets — Indeed ignores
+anything else and silently returns the unfiltered set, so an unsupported radius
+bills you for a search covering fifty miles. `min_salary` filters on Indeed's own
+estimate for the role, not on a posted figure, so postings that publish no salary
+still match. A location-only search (no `query`) is valid. Search is 10 postings
+per page, company reviews 20.
+
+### Glassdoor
+
+**Start with `companies()`.** The other three are keyed by an `employer_id` that
+only exists inside Glassdoor's `/Overview/` URLs.
+
+```typescript
+const hits = await client.glassdoor.companies({ query: "Stripe" });
+const company = await client.glassdoor.company({ employer_id: "671932" });
+
+// Pass the URLs the company response returns - halves the upstream work
+await client.glassdoor.reviews({ url: company.reviews_url as string });
+await client.glassdoor.salaries({ url: company.salaries_url as string });
+```
+
+1 credit per call. Glassdoor's login wall caps `reviews` at **three reviews per
+response** — there is deliberately no `page` param; move the window with
+`category` and `employment_status` and read `filtered_review_count` to see how
+many match. Addressing `reviews` or `salaries` by `employer_id` costs two
+upstream fetches because the slugs are case-sensitive and must be read off the
+profile, so prefer the `reviews_url` / `salaries_url` the company response hands
+back. These endpoints are slow and flaky by nature (company about 3-47s, reviews
+about 75s, salaries about 41s) — raise `timeout` and keep retries on.
+
+### App Store
+
+```typescript
+await client.appStore.search({ term: "meditation", limit: 100, country: "us" });
+await client.appStore.app({ app_id: "com.apple.Pages" });  // or the numeric id
+await client.appStore.reviews({ app_id: "361309726", page: 2, sort: "most_helpful" });
+```
+
+1 credit per call. **Search has no pagination** — `limit` (1-200) is the only
+lever; every offset spelling is silently ignored. `app` accepts both a numeric
+App Store id and a bundle id; `reviews` is numeric-only. Reviews hard-stop at
+page 10 (50 per page), which is Apple's anonymous ceiling — reach further by
+asking a different `country`. Reviews cannot 404: an unknown id and an app with
+zero reviews return the same empty feed.
+
+### Google Play
+
+```typescript
+await client.googlePlay.search({ query: "meditation", hl: "en", gl: "us" });
+await client.googlePlay.app({ app_id: "com.spotify.music" });
+await client.googlePlay.reviews({ app_id: "com.spotify.music", sort: "newest", count: 200 });
+```
+
+2 credits per call. **Search does not paginate** — one shelf of about 30 apps.
+`hl` changes the storefront, not just the strings: title, description, install
+formatting and content rating all move with it. The reviews `cursor` is opaque,
+single-use, and encodes the sort as well as the position, so send it back with
+the same `sort` it came from; a cursor past the last review is a 404. `app`
+already returns the 20 reviews Play server-renders, plus the real install count
+Play publishes but never displays.
+
+### G2
+
+```typescript
+await client.g2.search({ query: "crm", rating: 4 });
+await client.g2.product({ product_id: "notion" });
+await client.g2.reviews({ product_id: "notion", page: 2, company_size: "enterprise" });
+```
+
+**5 credits per call — the most expensive platform in the SDK**, because g2.com
+bills 25 upstream credits per fetch. Retries are deliberately conservative for
+that reason, and a bot wall arrives as a billed 200 rather than an error. G2
+loads review text in a separate frame, so `product` carries no reviews — call
+`reviews`, which is also the only place with exact per-star counts, pros/cons by
+theme, and company-size / role / industry / region facets.
+
+### Capterra
+
+```typescript
+const hits = await client.capterra.search({ query: "project management" });
+await client.capterra.product({ product_id: "186596", slug: "Notion" });
+await client.capterra.reviews({ product_id: "186596", slug: "Notion", page: 2 });
+```
+
+2 credits per call. **Search does not paginate** — Capterra fixes the result set
+at 20, so there is no `page` param. `slug` is cosmetic on `product` but
+load-bearing and case-sensitive on `reviews`: a wrong one silently serves page 1
+under a billed 200, so pass back the `slug` or `reviews_url` that `search` or
+`product` returned. Reviews are 25 per page, capped at page 100, and page 1
+already ships inside `product`. `vendor` is null on the product profile —
+Capterra does not publish it there.
+
+### SEC EDGAR
+
+**Start with `lookup()`.** Callers hold a ticker; EDGAR is keyed by CIK.
+
+```typescript
+const match = await client.sec.lookup({ query: "AAPL" });
+await client.sec.company({ ticker: "AAPL" });
+await client.sec.filings({ ticker: "AAPL", form: "10-K", include_history: true });
+await client.sec.facts({ ticker: "AAPL", query: "revenue" });
+await client.sec.concept({ ticker: "AAPL", concept: "NetIncomeLoss" });
+await client.sec.search({ query: "climate risk", form: "10-K" });
+```
+
+1 credit per call, including `include_history: true`, which is the one call that
+can buy up to 10 upstream fetches. Both `cik` and `ticker` accept either
+spelling. XBRL concept tags are **case-sensitive** — `netincomeloss` is a 404
+upstream, so use `facts()` to see what a filer actually reports. EDGAR's
+"recent" block is not a fixed window: a decade for a quiet filer, about a year
+for a prolific one.
+
+### Companies House
+
+```typescript
+const hits = await client.companiesHouse.search({ query: "Monzo" });
+await client.companiesHouse.company({ company_number: "09446231" });
+await client.companiesHouse.officers({ company_number: "09446231", page: 2 });
+await client.companiesHouse.filingHistory({ company_number: "SC090312" });
+```
+
+1 credit per call. `company_number` is deliberately loose — the register 404s on
+numbers that lost their leading zeros or arrived lower-cased, so the transport
+pads and upper-cases before asking. SC, NI, OC, SO, NC, FC, BR and CE prefixes
+are all supported. Search is 20 per page and capped at page 50: the register
+serves a 1000-result window per term whatever hit count it advertises, and page
+51 is an HTTP 416. Officers and filing history have no upper page bound — past
+the last page you get an ordinary empty list.
+
+### Google Ads Transparency
+
+```typescript
+const advertisers = await client.googleAds.advertisers({ query: "nike" });
+const page1 = await client.googleAds.search({ advertiser_id: "AR123...", region: "DE" });
+const page2 = await client.googleAds.search({
+  advertiser_id: "AR123...",
+  region: "DE",
+  cursor: page1.next_cursor as string,   // re-send the SAME filters
+});
+await client.googleAds.creative({ advertiser_id: "AR123...", creative_id: "CR456..." });
+```
+
+1 credit per call. `search` paginates by `cursor` / `next_cursor` at 100 per
+page — re-send the same filters alongside the cursor. `limit` is capped at 100 by
+Google itself, which answers a larger request with zero rows rather than an
+error. `advertisers` and `creative` do not paginate. **Impressions and reach are
+EEA-only**: US creatives return null for `impressions_min`, `impressions_max` and
+`first_shown` because Google only publishes reach where the DSA compels it. The
+text, image and video format sets are disjoint — an advertiser's creatives never
+overlap between them.
+
+### Meta Ad Library
+
+```typescript
+const page1 = await client.metaAds.search({ query: "protein powder", country: "US" });
+const page2 = await client.metaAds.search({
+  query: "protein powder",
+  cursor: page1.next_cursor as string,
+});
+await client.metaAds.advertiser({ page_id: "10150125871..." });
+await client.metaAds.ad({ ad_archive_id: "1234567890123456" });
+```
+
+1 credit per call. `search` and `advertiser` paginate all the way through: page 1
+returns 30 ads, then 10 per page via `next_cursor` — walk `has_next_page` to pull
+a whole query or advertiser. The cursor is a self-contained opaque blob, so
+paging is stateless and **the other filters are ignored when a cursor is
+present**, so re-sending `query` alongside it is harmless and satisfies the
+schema — the cursor already carries the filters. `total_results` caps at 50000 with
+`total_is_capped: true`, because Meta only reports "more than 50,000". Spend,
+reach, impressions and the paid-for-by disclosure exist on political and issue
+ads only — set `ad_type: "political_and_issue_ads"` to expose them; commercial
+ads leave those fields null.
+
 ### Usage
 
 ```typescript
@@ -460,13 +920,18 @@ All error classes:
 | `MissingAPIKeyError` | — | No API key provided |
 | `ScavioConnectionError` | — | Request never reached the API (DNS, reset, TLS) |
 | `ScavioTimeoutError` | — | Request exceeded the configured `timeout` |
-| `BadRequestError` | 400 | Invalid request parameters |
+| `BadRequestError` | 400, 422 | Invalid request parameters |
 | `InvalidAPIKeyError` | 401 | Invalid API key |
 | `InsufficientCreditsError` | 402 | No credits remaining |
 | `NotFoundError` | 404 | No data upstream for that id (see TikTok Shop above) |
 | `RateLimitError` | 429 | Rate limit exceeded |
 | `ScavioAPIError` | other | Catch-all (has `.statusCode`) |
 
+Threads and Kuaishou answer a missing or conflicting identifier with **422**, not
+400 — those routes have no 400 at all. Both map to `BadRequestError`, so one
+`catch (e) { if (e instanceof BadRequestError) }` covers validation failures on
+every platform. `e.statusCode` still reports whichever status the API sent.
+
 Every class extends `ScavioError`, so `catch (e) { if (e instanceof ScavioError) }`
 matches all of them. All except `MissingAPIKeyError`, `ScavioConnectionError` and
 `ScavioTimeoutError` carry `.statusCode` and `.responseBody`.
@@ -486,14 +951,24 @@ MIT
 
 ## About Scavio
 
-[Scavio](https://scavio.dev) is a unified [search API for AI agents](https://scavio.dev/search-api-for-ai-agents) — one API key, structured JSON, no scraping or proxies. A real-time [Tavily alternative](https://scavio.dev/alternatives/tavily) and [SerpAPI alternative](https://scavio.dev/alternatives/serpapi) with data from:
+[Scavio](https://scavio.dev) is a unified web data and
+[search API for AI agents](https://scavio.dev/search-api-for-ai-agents) — one API
+key, structured JSON, no proxies or browser farms to run. It is a real-time
+[Tavily alternative](https://scavio.dev/alternatives/tavily) and
+[SerpAPI alternative](https://scavio.dev/alternatives/serpapi), and with
+`extract()` it also covers the read-any-URL job people reach for Firecrawl to do.
+
+What teams build on it:
 
-- [Google Search API](https://scavio.dev/google-search-api) — SERP results, news, images, maps, and knowledge graph
-- [Amazon Product API](https://scavio.dev/amazon-product-api) and [Walmart Product API](https://scavio.dev/walmart-product-api) — product search and details
-- [YouTube API](https://scavio.dev/youtube-transcript-api), [TikTok API](https://scavio.dev/tiktok-api), and [Instagram API](https://scavio.dev/instagram-api) — video and social media data
-- [Reddit API](https://scavio.dev/reddit-api) — posts and threaded comments
-- [X API](https://scavio.dev/docs/x-search) and [LinkedIn API](https://scavio.dev/docs/linkedin-person) — tweets, profiles, companies, and jobs
+- **SERP and answer engines** — [Google Search API](https://scavio.dev/google-search-api) for organic results, news, images, maps and the knowledge graph
+- **Price and catalog monitoring** — [Amazon Product API](https://scavio.dev/amazon-product-api), [Walmart Product API](https://scavio.dev/walmart-product-api), eBay, Target and Home Depot product, review and seller data
+- **Real estate and travel pipelines** — Zillow and Redfin listings and market stats, Booking, Airbnb and Tripadvisor rates and reviews
+- **Review mining and competitive research** — Yelp, G2, Capterra, Glassdoor, App Store and Google Play reviews on one shape
+- **Recruiting and company intelligence** — Indeed jobs, Glassdoor salaries, SEC EDGAR filings and XBRL facts, UK Companies House officers and filing history
+- **Ad and creative intelligence** — Google Ads Transparency Center and Meta Ad Library creatives
+- **Social listening** — [YouTube API](https://scavio.dev/youtube-transcript-api), [TikTok API](https://scavio.dev/tiktok-api), [Instagram API](https://scavio.dev/instagram-api), [Reddit API](https://scavio.dev/reddit-api), [X API](https://scavio.dev/docs/x-search), [LinkedIn API](https://scavio.dev/docs/linkedin-person), Threads and Kuaishou
+- **RAG ingestion** — `extract()` reads any URL and hands back readability Markdown ready to chunk and embed
 
 Teams choosing between providers can [compare Scavio vs alternatives](https://scavio.dev/compare) side by side.
 
-Get a free [API key](https://dashboard.scavio.dev) and explore the [documentation](https://scavio.dev/docs/introduction).
+Get a free [API key](https://dashboard.scavio.dev/sign-up) and explore the [documentation](https://scavio.dev/docs/introduction).