@scrapa/sdk 0.2.2 → 0.4.0

package/src/generated/params.ts

@@ -6,36 +6,64 @@
 
 /** Arguments for `scrape()`. */
 export interface ScrapeParams {
-    /** The page to read. An http(s) URL — private and loopback hosts are refused. */
+    /** The page to read. An http(s) URL. Private and loopback hosts are refused. */
     url: string;
     /** How to read it. "fetch" is a plain HTTP request; "browser" renders the page in a real
-     *  Chromium; "auto" fetches first and escalates to the browser when the body turns out to be a
-     *  JavaScript shell, billing whichever engine answered. */
+     *  Chromium; "auto" (the default) fetches first and escalates to the browser when the body
+     *  turns out to be a JavaScript shell, billing whichever engine answered. A POST and "raw"
+     *  always use "fetch", so leave it out for them. */
     engine?: "auto" | "fetch" | "browser";
-    /** Whether to try again a different way when the first attempt is blocked. `false` stops after
-     *  one try — the site's refusal is your answer, and it costs nothing. It is how you bound a
-     *  call: with `auto`, trying again is what charges the browser price instead of the fetch one. */
+    /** Whether to try again a different way when the first attempt is blocked. On by default.
+     *  `false` stops after one try. The site's refusal is your answer, and it costs nothing. It is
+     *  how you bound a call: with `auto`, trying again is what charges the browser price instead of
+     *  the fetch one. A POST is sent once, so it is off for a POST. */
     escalate?: boolean;
+    /** The HTTP method. "POST" sends `body` to the URL, for a search form or a JSON query. It is
+     *  sent once: never retried and never sent again another way, because sending it twice could
+     *  repeat what it did. */
+    method?: "GET" | "POST";
+    /** What a POST sends, at most 64 KB. Set its type in `headers`: `{"content-type":
+     *  "application/json"}` for JSON, or `application/x-www-form-urlencoded` for a form. If the
+     *  site redirects, a 301, 302 or 303 reads the next page with GET and without the body; a 307
+     *  or 308 sends it again only if the protocol, host and port stay the same, and otherwise stops
+     *  and names the new address. */
+    body?: string;
     /** How many extra tries to give a page the site blocks, each from a different address. 0 (the
      *  default) takes the site's first no as the answer. A blocked page costs nothing, so a try
-     *  that is blocked again is free — but it takes as long as the first one did, so the call can
+     *  that is blocked again is free, but it takes as long as the first one did, so the call can
      *  run that many times longer. */
     retry?: number;
     /** What to hand back. "screenshot" and "pdf" come back as base64 and need the browser engine;
      *  asking for both costs no more than one. "extract" is the page read into fields by a model,
-     *  and needs an `extract` block saying which ones. */
-    formats?: ("markdown" | "html" | "text" | "links" | "screenshot" | "pdf" | "extract")[];
+     *  and needs an `extract` block saying which ones. A link to a PDF or a Word (.docx) file is
+     *  read into text, so the text formats work on it too. We read files up to 25 MB and the first
+     *  200 pages, at the fetch price. "raw" is the file exactly as the site sent it, as base64 with
+     *  its content type: a PDF report, an image, a spreadsheet. It uses the fetch engine and holds
+     *  up to 5 MB; a larger file answers FILE_TOO_LARGE at no charge, never cut short. */
+    formats?: ("markdown" | "html" | "text" | "links" | "screenshot" | "pdf" | "extract" | "raw")[];
+    /** Read only the page's main content into `markdown`, `text` and `extract`: the article or the
+     *  product, without the menus, ads and related links around it. On by default. Set `false` for
+     *  the whole page. When the main content is under 50 words, you get the whole page instead.
+     *  `html` and `links` always hold the whole page. */
+    onlyMainContent?: boolean;
+    /** CSS selectors for the parts of the page to keep, such as `["h1", ".price"]`. `markdown`,
+     *  `text` and `extract` then hold only what they match, in page order, and `onlyMainContent` no
+     *  longer applies. Hidden parts are never kept. Up to 20 selectors, 256 characters each. */
+    includeTags?: string[];
+    /** CSS selectors for the parts of the page to leave out of `markdown`, `text` and `extract`,
+     *  such as `[".comments", "#newsletter"]`. Up to 20 selectors, 256 characters each. */
+    excludeTags?: string[];
     /** What the page should answer with. Set `"json"` when you are reading an API: anything else
-     *  that comes back — a maintenance notice, a "checking your browser" page, a login form — is
-     *  then not your answer. It costs nothing, and we try again from another address instead of
-     *  handing you a page you cannot parse. Without it, whatever the page returns is your answer. */
+     *  that comes back (a maintenance notice, a "checking your browser" page, a login form) is then
+     *  not your answer. It costs nothing, and we try again from another address instead of handing
+     *  you a page you cannot parse. Without it, whatever the page returns is your answer. */
     expect?: "json";
     /** What to pull out of the page, for the "extract" format. A model reads the page and fills in
-     *  the shape you asked for — give it a JSON Schema, a sentence, or both. It reads what the page
+     *  the shape you asked for. Give it a JSON Schema, a sentence, or both. It reads what the page
      *  says; it does not do arithmetic over it, so ask for the numbers and add them up in your own
      *  code. */
     extract?: {
-        /** The shape you want back, as JSON Schema — an object whose properties are the fields you
+        /** The shape you want back, as JSON Schema: an object whose properties are the fields you
          *  need. A field the page does not mention comes back null; nothing is invented to fill it. */
         schema?: Record<string, unknown>;
         /** What to pull out, in your own words: `the price, the author and the date it was
@@ -46,7 +74,7 @@ export interface ScrapeParams {
     /** Where the request leaves from. Defaults to the managed residential pool. */
     proxy?: {
         /** Which exit to leave through. "residential" is the managed pool, metered by the megabyte;
-         *  "custom" is your own proxy — free on every plan, bytes never billed. */
+         *  "custom" is your own proxy, free on every plan, bytes never billed. */
         pool?: "residential" | "custom";
         /** Your own proxy, `http(s)://[user:pass@]host:port`. Required for pool "custom", refused
          *  for the managed one. */
@@ -66,7 +94,7 @@ export interface ScrapeParams {
          *  charge; ask for the state or the country alone. */
         city?: string;
     };
-    /** How to render it. Only the browser engine reads these — with `auto` they apply if the page
+    /** How to render it. Only the browser engine reads these. With `auto` they apply if the page
      *  turns out to need one. */
     browser?: {
         /** When the page counts as loaded. "load" (the default) waits for images and stylesheets;
@@ -74,9 +102,9 @@ export interface ScrapeParams {
          *  page stops asking for things. Every page gets a short settle after this whichever you
          *  pick. */
         waitUntil?: "load" | "domcontentloaded" | "networkidle";
-        /** Wait until this CSS selector is on the page — the dependable way to read something a
-         *  script draws. If it never shows up the call comes back as a timeout at no charge, rather
-         *  than the half-built page. */
+        /** Wait until this CSS selector is on the page. It is the dependable way to read something
+         *  a script draws. If it never shows up, the call comes back as a timeout at no charge,
+         *  rather than the half-built page. */
         waitForSelector?: string;
         /** Wait this many milliseconds after the page settles, for the scripts no selector
          *  describes. It comes out of `timeoutMs`, never on top of it. */
@@ -88,11 +116,11 @@ export interface ScrapeParams {
             height: number;
         };
         /** Screenshot the whole scrollable page instead of just the window. A long page makes a
-         *  large answer — the image comes back as base64 inside the response. */
+         *  large answer: the image comes back as base64 inside the response. */
         fullPage?: boolean;
     };
-    /** Extra request headers to send to the page — an authorization token, a cookie, a custom user
-     *  agent. The connection's own headers cannot be set. */
+    /** Extra request headers to send to the page, such as an authorization token, a cookie or a
+     *  custom user agent. The connection's own headers cannot be set. */
     headers?: Record<string, string>;
     /** How long to give the page before giving up, in milliseconds. A page that never arrives is a
      *  free outcome. */
@@ -101,36 +129,64 @@ export interface ScrapeParams {
 
 /** Arguments for `quote()`. */
 export interface QuoteScrapeParams {
-    /** The page to read. An http(s) URL — private and loopback hosts are refused. */
+    /** The page to read. An http(s) URL. Private and loopback hosts are refused. */
     url: string;
     /** How to read it. "fetch" is a plain HTTP request; "browser" renders the page in a real
-     *  Chromium; "auto" fetches first and escalates to the browser when the body turns out to be a
-     *  JavaScript shell, billing whichever engine answered. */
+     *  Chromium; "auto" (the default) fetches first and escalates to the browser when the body
+     *  turns out to be a JavaScript shell, billing whichever engine answered. A POST and "raw"
+     *  always use "fetch", so leave it out for them. */
     engine?: "auto" | "fetch" | "browser";
-    /** Whether to try again a different way when the first attempt is blocked. `false` stops after
-     *  one try — the site's refusal is your answer, and it costs nothing. It is how you bound a
-     *  call: with `auto`, trying again is what charges the browser price instead of the fetch one. */
+    /** Whether to try again a different way when the first attempt is blocked. On by default.
+     *  `false` stops after one try. The site's refusal is your answer, and it costs nothing. It is
+     *  how you bound a call: with `auto`, trying again is what charges the browser price instead of
+     *  the fetch one. A POST is sent once, so it is off for a POST. */
     escalate?: boolean;
+    /** The HTTP method. "POST" sends `body` to the URL, for a search form or a JSON query. It is
+     *  sent once: never retried and never sent again another way, because sending it twice could
+     *  repeat what it did. */
+    method?: "GET" | "POST";
+    /** What a POST sends, at most 64 KB. Set its type in `headers`: `{"content-type":
+     *  "application/json"}` for JSON, or `application/x-www-form-urlencoded` for a form. If the
+     *  site redirects, a 301, 302 or 303 reads the next page with GET and without the body; a 307
+     *  or 308 sends it again only if the protocol, host and port stay the same, and otherwise stops
+     *  and names the new address. */
+    body?: string;
     /** How many extra tries to give a page the site blocks, each from a different address. 0 (the
      *  default) takes the site's first no as the answer. A blocked page costs nothing, so a try
-     *  that is blocked again is free — but it takes as long as the first one did, so the call can
+     *  that is blocked again is free, but it takes as long as the first one did, so the call can
      *  run that many times longer. */
     retry?: number;
     /** What to hand back. "screenshot" and "pdf" come back as base64 and need the browser engine;
      *  asking for both costs no more than one. "extract" is the page read into fields by a model,
-     *  and needs an `extract` block saying which ones. */
-    formats?: ("markdown" | "html" | "text" | "links" | "screenshot" | "pdf" | "extract")[];
+     *  and needs an `extract` block saying which ones. A link to a PDF or a Word (.docx) file is
+     *  read into text, so the text formats work on it too. We read files up to 25 MB and the first
+     *  200 pages, at the fetch price. "raw" is the file exactly as the site sent it, as base64 with
+     *  its content type: a PDF report, an image, a spreadsheet. It uses the fetch engine and holds
+     *  up to 5 MB; a larger file answers FILE_TOO_LARGE at no charge, never cut short. */
+    formats?: ("markdown" | "html" | "text" | "links" | "screenshot" | "pdf" | "extract" | "raw")[];
+    /** Read only the page's main content into `markdown`, `text` and `extract`: the article or the
+     *  product, without the menus, ads and related links around it. On by default. Set `false` for
+     *  the whole page. When the main content is under 50 words, you get the whole page instead.
+     *  `html` and `links` always hold the whole page. */
+    onlyMainContent?: boolean;
+    /** CSS selectors for the parts of the page to keep, such as `["h1", ".price"]`. `markdown`,
+     *  `text` and `extract` then hold only what they match, in page order, and `onlyMainContent` no
+     *  longer applies. Hidden parts are never kept. Up to 20 selectors, 256 characters each. */
+    includeTags?: string[];
+    /** CSS selectors for the parts of the page to leave out of `markdown`, `text` and `extract`,
+     *  such as `[".comments", "#newsletter"]`. Up to 20 selectors, 256 characters each. */
+    excludeTags?: string[];
     /** What the page should answer with. Set `"json"` when you are reading an API: anything else
-     *  that comes back — a maintenance notice, a "checking your browser" page, a login form — is
-     *  then not your answer. It costs nothing, and we try again from another address instead of
-     *  handing you a page you cannot parse. Without it, whatever the page returns is your answer. */
+     *  that comes back (a maintenance notice, a "checking your browser" page, a login form) is then
+     *  not your answer. It costs nothing, and we try again from another address instead of handing
+     *  you a page you cannot parse. Without it, whatever the page returns is your answer. */
     expect?: "json";
     /** What to pull out of the page, for the "extract" format. A model reads the page and fills in
-     *  the shape you asked for — give it a JSON Schema, a sentence, or both. It reads what the page
+     *  the shape you asked for. Give it a JSON Schema, a sentence, or both. It reads what the page
      *  says; it does not do arithmetic over it, so ask for the numbers and add them up in your own
      *  code. */
     extract?: {
-        /** The shape you want back, as JSON Schema — an object whose properties are the fields you
+        /** The shape you want back, as JSON Schema: an object whose properties are the fields you
          *  need. A field the page does not mention comes back null; nothing is invented to fill it. */
         schema?: Record<string, unknown>;
         /** What to pull out, in your own words: `the price, the author and the date it was
@@ -141,7 +197,7 @@ export interface QuoteScrapeParams {
     /** Where the request leaves from. Defaults to the managed residential pool. */
     proxy?: {
         /** Which exit to leave through. "residential" is the managed pool, metered by the megabyte;
-         *  "custom" is your own proxy — free on every plan, bytes never billed. */
+         *  "custom" is your own proxy, free on every plan, bytes never billed. */
         pool?: "residential" | "custom";
         /** Your own proxy, `http(s)://[user:pass@]host:port`. Required for pool "custom", refused
          *  for the managed one. */
@@ -161,7 +217,7 @@ export interface QuoteScrapeParams {
          *  charge; ask for the state or the country alone. */
         city?: string;
     };
-    /** How to render it. Only the browser engine reads these — with `auto` they apply if the page
+    /** How to render it. Only the browser engine reads these. With `auto` they apply if the page
      *  turns out to need one. */
     browser?: {
         /** When the page counts as loaded. "load" (the default) waits for images and stylesheets;
@@ -169,9 +225,9 @@ export interface QuoteScrapeParams {
          *  page stops asking for things. Every page gets a short settle after this whichever you
          *  pick. */
         waitUntil?: "load" | "domcontentloaded" | "networkidle";
-        /** Wait until this CSS selector is on the page — the dependable way to read something a
-         *  script draws. If it never shows up the call comes back as a timeout at no charge, rather
-         *  than the half-built page. */
+        /** Wait until this CSS selector is on the page. It is the dependable way to read something
+         *  a script draws. If it never shows up, the call comes back as a timeout at no charge,
+         *  rather than the half-built page. */
         waitForSelector?: string;
         /** Wait this many milliseconds after the page settles, for the scripts no selector
          *  describes. It comes out of `timeoutMs`, never on top of it. */
@@ -183,23 +239,85 @@ export interface QuoteScrapeParams {
             height: number;
         };
         /** Screenshot the whole scrollable page instead of just the window. A long page makes a
-         *  large answer — the image comes back as base64 inside the response. */
+         *  large answer: the image comes back as base64 inside the response. */
         fullPage?: boolean;
     };
-    /** Extra request headers to send to the page — an authorization token, a cookie, a custom user
-     *  agent. The connection's own headers cannot be set. */
+    /** Extra request headers to send to the page, such as an authorization token, a cookie or a
+     *  custom user agent. The connection's own headers cannot be set. */
     headers?: Record<string, string>;
     /** How long to give the page before giving up, in milliseconds. A page that never arrives is a
      *  free outcome. */
     timeoutMs?: number;
 }
 
+/** Arguments for `map()`. */
+export interface MapSiteParams {
+    /** The site to map, as any http(s) URL on it. Private and loopback hosts are refused. */
+    url: string;
+    /** How many URLs to hand back at most, 1 to 30,000. The price is the same whatever you ask for. */
+    limit?: number;
+    /** Only URLs that contain this text, upper or lower case alike: `blog` keeps `/blog/` and
+     *  `/Blog-post`. */
+    search?: string;
+    /** Also keep URLs on other hosts of the same domain, like `blog.example.com` for `example.com`.
+     *  Off by default: only the host you named, with or without `www.`. */
+    includeSubdomains?: boolean;
+    /** Where to look. "include" reads the site's sitemaps and the links on the page you named;
+     *  "only" reads the sitemaps alone; "skip" reads the page's links alone. */
+    sitemap?: "include" | "only" | "skip";
+    /** Where the map's requests leave from. Every file it reads goes through the same exit. */
+    proxy?: {
+        /** Which exit to leave through. "residential" is the managed pool, metered by the megabyte;
+         *  "custom" is your own proxy, free on every plan, bytes never billed. */
+        pool?: "residential" | "custom";
+        /** Your own proxy, `http(s)://[user:pass@]host:port`. Required for pool "custom", refused
+         *  for the managed one. */
+        server?: string;
+        /** Where the call should look like it comes from, ISO 3166-1 alpha-2 (`us`, `br`). Name one
+         *  and the managed pool leaves from that country. Leave it out and the page sees a US
+         *  browser, from an address we pick. The browser's clock and languages follow the country
+         *  on every pool. */
+        country?: string;
+    };
+}
+
+/** Arguments for `quoteMap()`. */
+export interface QuoteMapParams {
+    /** The site to map, as any http(s) URL on it. Private and loopback hosts are refused. */
+    url: string;
+    /** How many URLs to hand back at most, 1 to 30,000. The price is the same whatever you ask for. */
+    limit?: number;
+    /** Only URLs that contain this text, upper or lower case alike: `blog` keeps `/blog/` and
+     *  `/Blog-post`. */
+    search?: string;
+    /** Also keep URLs on other hosts of the same domain, like `blog.example.com` for `example.com`.
+     *  Off by default: only the host you named, with or without `www.`. */
+    includeSubdomains?: boolean;
+    /** Where to look. "include" reads the site's sitemaps and the links on the page you named;
+     *  "only" reads the sitemaps alone; "skip" reads the page's links alone. */
+    sitemap?: "include" | "only" | "skip";
+    /** Where the map's requests leave from. Every file it reads goes through the same exit. */
+    proxy?: {
+        /** Which exit to leave through. "residential" is the managed pool, metered by the megabyte;
+         *  "custom" is your own proxy, free on every plan, bytes never billed. */
+        pool?: "residential" | "custom";
+        /** Your own proxy, `http(s)://[user:pass@]host:port`. Required for pool "custom", refused
+         *  for the managed one. */
+        server?: string;
+        /** Where the call should look like it comes from, ISO 3166-1 alpha-2 (`us`, `br`). Name one
+         *  and the managed pool leaves from that country. Leave it out and the page sees a US
+         *  browser, from an address we pick. The browser's clock and languages follow the country
+         *  on every pool. */
+        country?: string;
+    };
+}
+
 /** Arguments for `search()`. */
 export interface SearchParams {
-    /** What to search for, in plain words — the same thing you would type. */
+    /** What to search for, in plain words: the same thing you would type. */
     query: string;
     /** How many results to hand back at most, 1–20. Billed per 10, so asking for more than 10 costs
-     *  a second row. Fewer can come back than you asked for — an index has what it has, and
+     *  a second row. Fewer can come back than you asked for: an index has what it has, and
      *  `includeDomains` filters what it returns. */
     limit?: number;
     /** What kind of results. "general" is the web; "news" is dated journalism, and the only topic
@@ -207,18 +325,18 @@ export interface SearchParams {
     topic?: "general" | "news";
     /** Only pages from the last day, week, month or year. Absent is any time. */
     timeRange?: "day" | "week" | "month" | "year";
-    /** Only results on these hosts, bare (`linkedin.com`) — subdomains included. Asked of the
+    /** Only results on these hosts, bare (`linkedin.com`). Subdomains are included. Asked of the
      *  search front AND enforced on the answer, so what comes back is on your list whatever the
      *  front did with it. */
     includeDomains?: string[];
     /** Also write a short paragraph answering the query from the results, in the query's language.
      *  Costs one extra credit; leave it off when your own model reads the snippets. */
     answer?: boolean;
-    /** Where the search leaves from. `country` picks the exit AND the market the front answers for
-     *  — `br` gets Brazilian results in Portuguese. */
+    /** Where the search leaves from. `country` picks the exit AND the market the front answers for.
+     *  `br` gets Brazilian results in Portuguese. */
     proxy?: {
         /** Which exit to leave through. "residential" is the managed pool, metered by the megabyte;
-         *  "custom" is your own proxy — free on every plan, bytes never billed. */
+         *  "custom" is your own proxy, free on every plan, bytes never billed. */
         pool?: "residential" | "custom";
         /** Your own proxy, `http(s)://[user:pass@]host:port`. Required for pool "custom", refused
          *  for the managed one. */
@@ -234,33 +352,51 @@ export interface SearchParams {
 /** Arguments for `batches.create()`. */
 export interface CreateBatchParams {
     /** How to read it. "fetch" is a plain HTTP request; "browser" renders the page in a real
-     *  Chromium; "auto" fetches first and escalates to the browser when the body turns out to be a
-     *  JavaScript shell, billing whichever engine answered. */
+     *  Chromium; "auto" (the default) fetches first and escalates to the browser when the body
+     *  turns out to be a JavaScript shell, billing whichever engine answered. A POST and "raw"
+     *  always use "fetch", so leave it out for them. */
     engine?: "auto" | "fetch" | "browser";
-    /** Whether to try again a different way when the first attempt is blocked. `false` stops after
-     *  one try — the site's refusal is your answer, and it costs nothing. It is how you bound a
-     *  call: with `auto`, trying again is what charges the browser price instead of the fetch one. */
+    /** Whether to try again a different way when the first attempt is blocked. On by default.
+     *  `false` stops after one try. The site's refusal is your answer, and it costs nothing. It is
+     *  how you bound a call: with `auto`, trying again is what charges the browser price instead of
+     *  the fetch one. A POST is sent once, so it is off for a POST. */
     escalate?: boolean;
     /** How many extra tries to give a page the site blocks, each from a different address. 0 (the
      *  default) takes the site's first no as the answer. A blocked page costs nothing, so a try
-     *  that is blocked again is free — but it takes as long as the first one did, so the call can
+     *  that is blocked again is free, but it takes as long as the first one did, so the call can
      *  run that many times longer. */
     retry?: number;
     /** What to hand back. "screenshot" and "pdf" come back as base64 and need the browser engine;
      *  asking for both costs no more than one. "extract" is the page read into fields by a model,
-     *  and needs an `extract` block saying which ones. */
-    formats?: ("markdown" | "html" | "text" | "links" | "screenshot" | "pdf" | "extract")[];
+     *  and needs an `extract` block saying which ones. A link to a PDF or a Word (.docx) file is
+     *  read into text, so the text formats work on it too. We read files up to 25 MB and the first
+     *  200 pages, at the fetch price. "raw" is the file exactly as the site sent it, as base64 with
+     *  its content type: a PDF report, an image, a spreadsheet. It uses the fetch engine and holds
+     *  up to 5 MB; a larger file answers FILE_TOO_LARGE at no charge, never cut short. */
+    formats?: ("markdown" | "html" | "text" | "links" | "screenshot" | "pdf" | "extract" | "raw")[];
+    /** Read only the page's main content into `markdown`, `text` and `extract`: the article or the
+     *  product, without the menus, ads and related links around it. On by default. Set `false` for
+     *  the whole page. When the main content is under 50 words, you get the whole page instead.
+     *  `html` and `links` always hold the whole page. */
+    onlyMainContent?: boolean;
+    /** CSS selectors for the parts of the page to keep, such as `["h1", ".price"]`. `markdown`,
+     *  `text` and `extract` then hold only what they match, in page order, and `onlyMainContent` no
+     *  longer applies. Hidden parts are never kept. Up to 20 selectors, 256 characters each. */
+    includeTags?: string[];
+    /** CSS selectors for the parts of the page to leave out of `markdown`, `text` and `extract`,
+     *  such as `[".comments", "#newsletter"]`. Up to 20 selectors, 256 characters each. */
+    excludeTags?: string[];
     /** What the page should answer with. Set `"json"` when you are reading an API: anything else
-     *  that comes back — a maintenance notice, a "checking your browser" page, a login form — is
-     *  then not your answer. It costs nothing, and we try again from another address instead of
-     *  handing you a page you cannot parse. Without it, whatever the page returns is your answer. */
+     *  that comes back (a maintenance notice, a "checking your browser" page, a login form) is then
+     *  not your answer. It costs nothing, and we try again from another address instead of handing
+     *  you a page you cannot parse. Without it, whatever the page returns is your answer. */
     expect?: "json";
     /** What to pull out of the page, for the "extract" format. A model reads the page and fills in
-     *  the shape you asked for — give it a JSON Schema, a sentence, or both. It reads what the page
+     *  the shape you asked for. Give it a JSON Schema, a sentence, or both. It reads what the page
      *  says; it does not do arithmetic over it, so ask for the numbers and add them up in your own
      *  code. */
     extract?: {
-        /** The shape you want back, as JSON Schema — an object whose properties are the fields you
+        /** The shape you want back, as JSON Schema: an object whose properties are the fields you
          *  need. A field the page does not mention comes back null; nothing is invented to fill it. */
         schema?: Record<string, unknown>;
         /** What to pull out, in your own words: `the price, the author and the date it was
@@ -271,7 +407,7 @@ export interface CreateBatchParams {
     /** Where the request leaves from. Defaults to the managed residential pool. */
     proxy?: {
         /** Which exit to leave through. "residential" is the managed pool, metered by the megabyte;
-         *  "custom" is your own proxy — free on every plan, bytes never billed. */
+         *  "custom" is your own proxy, free on every plan, bytes never billed. */
         pool?: "residential" | "custom";
         /** Your own proxy, `http(s)://[user:pass@]host:port`. Required for pool "custom", refused
          *  for the managed one. */
@@ -291,7 +427,7 @@ export interface CreateBatchParams {
          *  charge; ask for the state or the country alone. */
         city?: string;
     };
-    /** How to render it. Only the browser engine reads these — with `auto` they apply if the page
+    /** How to render it. Only the browser engine reads these. With `auto` they apply if the page
      *  turns out to need one. */
     browser?: {
         /** When the page counts as loaded. "load" (the default) waits for images and stylesheets;
@@ -299,9 +435,9 @@ export interface CreateBatchParams {
          *  page stops asking for things. Every page gets a short settle after this whichever you
          *  pick. */
         waitUntil?: "load" | "domcontentloaded" | "networkidle";
-        /** Wait until this CSS selector is on the page — the dependable way to read something a
-         *  script draws. If it never shows up the call comes back as a timeout at no charge, rather
-         *  than the half-built page. */
+        /** Wait until this CSS selector is on the page. It is the dependable way to read something
+         *  a script draws. If it never shows up, the call comes back as a timeout at no charge,
+         *  rather than the half-built page. */
         waitForSelector?: string;
         /** Wait this many milliseconds after the page settles, for the scripts no selector
          *  describes. It comes out of `timeoutMs`, never on top of it. */
@@ -313,11 +449,11 @@ export interface CreateBatchParams {
             height: number;
         };
         /** Screenshot the whole scrollable page instead of just the window. A long page makes a
-         *  large answer — the image comes back as base64 inside the response. */
+         *  large answer: the image comes back as base64 inside the response. */
         fullPage?: boolean;
     };
-    /** Extra request headers to send to the page — an authorization token, a cookie, a custom user
-     *  agent. The connection's own headers cannot be set. */
+    /** Extra request headers to send to the page, such as an authorization token, a cookie or a
+     *  custom user agent. The connection's own headers cannot be set. */
     headers?: Record<string, string>;
     /** How long to give the page before giving up, in milliseconds. A page that never arrives is a
      *  free outcome. */
@@ -334,8 +470,8 @@ export interface CreateBatchParams {
         url: string;
         /** What to call about. "batch.completed" fires once: when every URL has a verdict, or when
          *  we could not finish the batch. `batch.status` says which: `completed` or `failed`.
-         *  "batch.item.completed" fires per URL — one request from us per item, which is what makes
-         *  a long batch usable before it ends, so ask for it deliberately. */
+         *  "batch.item.completed" fires per URL, with one request from us per item. That makes a
+         *  long batch usable before it ends, so ask for it deliberately. */
         events?: ("batch.completed" | "batch.item.completed")[];
     };
 }
@@ -343,33 +479,51 @@ export interface CreateBatchParams {
 /** Arguments for `batches.quote()`. */
 export interface QuoteBatchParams {
     /** How to read it. "fetch" is a plain HTTP request; "browser" renders the page in a real
-     *  Chromium; "auto" fetches first and escalates to the browser when the body turns out to be a
-     *  JavaScript shell, billing whichever engine answered. */
+     *  Chromium; "auto" (the default) fetches first and escalates to the browser when the body
+     *  turns out to be a JavaScript shell, billing whichever engine answered. A POST and "raw"
+     *  always use "fetch", so leave it out for them. */
     engine?: "auto" | "fetch" | "browser";
-    /** Whether to try again a different way when the first attempt is blocked. `false` stops after
-     *  one try — the site's refusal is your answer, and it costs nothing. It is how you bound a
-     *  call: with `auto`, trying again is what charges the browser price instead of the fetch one. */
+    /** Whether to try again a different way when the first attempt is blocked. On by default.
+     *  `false` stops after one try. The site's refusal is your answer, and it costs nothing. It is
+     *  how you bound a call: with `auto`, trying again is what charges the browser price instead of
+     *  the fetch one. A POST is sent once, so it is off for a POST. */
     escalate?: boolean;
     /** How many extra tries to give a page the site blocks, each from a different address. 0 (the
      *  default) takes the site's first no as the answer. A blocked page costs nothing, so a try
-     *  that is blocked again is free — but it takes as long as the first one did, so the call can
+     *  that is blocked again is free, but it takes as long as the first one did, so the call can
      *  run that many times longer. */
     retry?: number;
     /** What to hand back. "screenshot" and "pdf" come back as base64 and need the browser engine;
      *  asking for both costs no more than one. "extract" is the page read into fields by a model,
-     *  and needs an `extract` block saying which ones. */
-    formats?: ("markdown" | "html" | "text" | "links" | "screenshot" | "pdf" | "extract")[];
+     *  and needs an `extract` block saying which ones. A link to a PDF or a Word (.docx) file is
+     *  read into text, so the text formats work on it too. We read files up to 25 MB and the first
+     *  200 pages, at the fetch price. "raw" is the file exactly as the site sent it, as base64 with
+     *  its content type: a PDF report, an image, a spreadsheet. It uses the fetch engine and holds
+     *  up to 5 MB; a larger file answers FILE_TOO_LARGE at no charge, never cut short. */
+    formats?: ("markdown" | "html" | "text" | "links" | "screenshot" | "pdf" | "extract" | "raw")[];
+    /** Read only the page's main content into `markdown`, `text` and `extract`: the article or the
+     *  product, without the menus, ads and related links around it. On by default. Set `false` for
+     *  the whole page. When the main content is under 50 words, you get the whole page instead.
+     *  `html` and `links` always hold the whole page. */
+    onlyMainContent?: boolean;
+    /** CSS selectors for the parts of the page to keep, such as `["h1", ".price"]`. `markdown`,
+     *  `text` and `extract` then hold only what they match, in page order, and `onlyMainContent` no
+     *  longer applies. Hidden parts are never kept. Up to 20 selectors, 256 characters each. */
+    includeTags?: string[];
+    /** CSS selectors for the parts of the page to leave out of `markdown`, `text` and `extract`,
+     *  such as `[".comments", "#newsletter"]`. Up to 20 selectors, 256 characters each. */
+    excludeTags?: string[];
     /** What the page should answer with. Set `"json"` when you are reading an API: anything else
-     *  that comes back — a maintenance notice, a "checking your browser" page, a login form — is
-     *  then not your answer. It costs nothing, and we try again from another address instead of
-     *  handing you a page you cannot parse. Without it, whatever the page returns is your answer. */
+     *  that comes back (a maintenance notice, a "checking your browser" page, a login form) is then
+     *  not your answer. It costs nothing, and we try again from another address instead of handing
+     *  you a page you cannot parse. Without it, whatever the page returns is your answer. */
     expect?: "json";
     /** What to pull out of the page, for the "extract" format. A model reads the page and fills in
-     *  the shape you asked for — give it a JSON Schema, a sentence, or both. It reads what the page
+     *  the shape you asked for. Give it a JSON Schema, a sentence, or both. It reads what the page
      *  says; it does not do arithmetic over it, so ask for the numbers and add them up in your own
      *  code. */
     extract?: {
-        /** The shape you want back, as JSON Schema — an object whose properties are the fields you
+        /** The shape you want back, as JSON Schema: an object whose properties are the fields you
          *  need. A field the page does not mention comes back null; nothing is invented to fill it. */
         schema?: Record<string, unknown>;
         /** What to pull out, in your own words: `the price, the author and the date it was
@@ -380,7 +534,7 @@ export interface QuoteBatchParams {
     /** Where the request leaves from. Defaults to the managed residential pool. */
     proxy?: {
         /** Which exit to leave through. "residential" is the managed pool, metered by the megabyte;
-         *  "custom" is your own proxy — free on every plan, bytes never billed. */
+         *  "custom" is your own proxy, free on every plan, bytes never billed. */
         pool?: "residential" | "custom";
         /** Your own proxy, `http(s)://[user:pass@]host:port`. Required for pool "custom", refused
          *  for the managed one. */
@@ -400,7 +554,7 @@ export interface QuoteBatchParams {
          *  charge; ask for the state or the country alone. */
         city?: string;
     };
-    /** How to render it. Only the browser engine reads these — with `auto` they apply if the page
+    /** How to render it. Only the browser engine reads these. With `auto` they apply if the page
      *  turns out to need one. */
     browser?: {
         /** When the page counts as loaded. "load" (the default) waits for images and stylesheets;
@@ -408,9 +562,9 @@ export interface QuoteBatchParams {
          *  page stops asking for things. Every page gets a short settle after this whichever you
          *  pick. */
         waitUntil?: "load" | "domcontentloaded" | "networkidle";
-        /** Wait until this CSS selector is on the page — the dependable way to read something a
-         *  script draws. If it never shows up the call comes back as a timeout at no charge, rather
-         *  than the half-built page. */
+        /** Wait until this CSS selector is on the page. It is the dependable way to read something
+         *  a script draws. If it never shows up, the call comes back as a timeout at no charge,
+         *  rather than the half-built page. */
         waitForSelector?: string;
         /** Wait this many milliseconds after the page settles, for the scripts no selector
          *  describes. It comes out of `timeoutMs`, never on top of it. */
@@ -422,11 +576,11 @@ export interface QuoteBatchParams {
             height: number;
         };
         /** Screenshot the whole scrollable page instead of just the window. A long page makes a
-         *  large answer — the image comes back as base64 inside the response. */
+         *  large answer: the image comes back as base64 inside the response. */
         fullPage?: boolean;
     };
-    /** Extra request headers to send to the page — an authorization token, a cookie, a custom user
-     *  agent. The connection's own headers cannot be set. */
+    /** Extra request headers to send to the page, such as an authorization token, a cookie or a
+     *  custom user agent. The connection's own headers cannot be set. */
     headers?: Record<string, string>;
     /** How long to give the page before giving up, in milliseconds. A page that never arrives is a
      *  free outcome. */
@@ -443,8 +597,8 @@ export interface QuoteBatchParams {
         url: string;
         /** What to call about. "batch.completed" fires once: when every URL has a verdict, or when
          *  we could not finish the batch. `batch.status` says which: `completed` or `failed`.
-         *  "batch.item.completed" fires per URL — one request from us per item, which is what makes
-         *  a long batch usable before it ends, so ask for it deliberately. */
+         *  "batch.item.completed" fires per URL, with one request from us per item. That makes a
+         *  long batch usable before it ends, so ask for it deliberately. */
         events?: ("batch.completed" | "batch.item.completed")[];
     };
 }
@@ -483,7 +637,7 @@ export interface CreateSessionParams {
      *  pool. */
     proxy?: {
         /** Which exit to leave through. "residential" is the managed pool, metered by the megabyte;
-         *  "custom" is your own proxy — free on every plan, bytes never billed. */
+         *  "custom" is your own proxy, free on every plan, bytes never billed. */
         pool?: "residential" | "custom";
         /** Your own proxy, `http(s)://[user:pass@]host:port`. Required for pool "custom", refused
          *  for the managed one. */
@@ -515,7 +669,7 @@ export interface QuoteSessionParams {
      *  pool. */
     proxy?: {
         /** Which exit to leave through. "residential" is the managed pool, metered by the megabyte;
-         *  "custom" is your own proxy — free on every plan, bytes never billed. */
+         *  "custom" is your own proxy, free on every plan, bytes never billed. */
         pool?: "residential" | "custom";
         /** Your own proxy, `http(s)://[user:pass@]host:port`. Required for pool "custom", refused
          *  for the managed one. */