@scrapa/sdk 0.2.1 → 0.3.0

package/src/generated/params.ts

@@ -6,36 +6,51 @@
 
 /** 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. "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")[];
     /** 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 +61,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 +81,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 +89,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 +103,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 +116,51 @@ 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. "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")[];
     /** 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 +171,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 +191,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 +199,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,11 +213,11 @@ 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. */
@@ -196,10 +226,10 @@ export interface QuoteScrapeParams {
 
 /** 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 +237,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 +264,38 @@ 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. "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")[];
     /** 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 +306,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 +326,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 +334,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 +348,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. */
@@ -332,9 +367,10 @@ export interface CreateBatchParams {
         /** Where to POST when something happens. An https URL you control; private and loopback
          *  hosts are refused, the same as any other URL we fetch. */
         url: string;
-        /** What to call about. "batch.completed" fires once, when every URL has a verdict.
-         *  "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. */
+        /** 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, 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")[];
     };
 }
@@ -342,33 +378,38 @@ 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. "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")[];
     /** 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
@@ -379,7 +420,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. */
@@ -399,7 +440,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;
@@ -407,9 +448,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. */
@@ -421,11 +462,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. */
@@ -440,9 +481,10 @@ export interface QuoteBatchParams {
         /** Where to POST when something happens. An https URL you control; private and loopback
          *  hosts are refused, the same as any other URL we fetch. */
         url: string;
-        /** What to call about. "batch.completed" fires once, when every URL has a verdict.
-         *  "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. */
+        /** 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, 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")[];
     };
 }
@@ -481,7 +523,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. */
@@ -513,7 +555,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. */

package/src/generated/retry.ts

@@ -49,9 +49,9 @@ const DEFAULT_MAX_WAIT_SECS = 10;
 /**
  * Should this failure be retried?
  *
- *     if (attempt < 3 && shouldRetry(error, { repeatable: method === "GET" || !!key }))
+ *     if (attempt < 3 && isRetryable(error, { repeatable: method === "GET" || !!key }))
  */
-export function shouldRetry(error: unknown, options: RetryOptions): boolean {
+export function isRetryable(error: unknown, options: RetryOptions): boolean {
     const { repeatable, durableCodes = [], maxWaitSecs = DEFAULT_MAX_WAIT_SECS } = options;
     const status = statusOf(error);
     // No answer at all: nothing about it is a refusal, but a write may have landed before the
@@ -145,7 +145,7 @@ export function parseRetryAfter(value: string | null | undefined): number | unde
  * frees when another job ends. Present-and-`null` is the whole test; an absent key said nothing.
  *
  * Not exported. It is not "is this refusal durable?": it knows nothing of `durableCodes` or of a
- * wait too long to hold, so a screen branching on it would disagree with `shouldRetry`.
+ * wait too long to hold, so a screen branching on it would disagree with `isRetryable`.
  */
 function waitingNeverHelps(error: unknown): boolean {
     const details = field(error, "details");

package/src/generated/transport.ts

@@ -24,7 +24,7 @@
  * - **The header is read first, in both its forms.** Two copies read the body's wait before the
  *   `Retry-After` header, and read the header only as seconds, so an HTTP date was no wait at all.
  */
-import { parseRetryAfter, retryDelayMs, shouldRetry } from "./retry.ts";
+import { parseRetryAfter, retryDelayMs, isRetryable } from "./retry.ts";
 
 /** What a generated method tells the transport about its operation. */
 export interface RequestSpec {
@@ -193,7 +193,7 @@ export async function send<T = unknown, M = unknown>(
         };
         const again =
             attempt < maxRetries &&
-            shouldRetry(answer, { repeatable, durableCodes: transport.durableCodes });
+            isRetryable(answer, { repeatable, durableCodes: transport.durableCodes });
         if (!again) throw transport.error(failure);
         await sleep(retryDelayMs(attempt, answer), signal);
     }