@bowmark/web 1.22.1 → 1.23.0

package/dist/generated/library.d.ts

@@ -5,8 +5,8 @@
 // rather than imported. An `import` or `export` at the top level of this file would
 // turn it into a module and every declaration below would stop being global.
 //
-// Manifest version: d7a4e150ac8b92a335cf1f8c899427d12236d7556bd04d8e873ba0729e5a347b
-// 49 capabilities, 416 providers, 1090 typed functions, 20 refused.
+// Manifest version: 33a70781b68188bc68feb315e91e0c61cb56ecb49e10d82f223e4feb9d6b3399
+// 50 capabilities, 418 providers, 1121 typed functions, 20 refused.
 // 51,715 family members, sharing 2 interface(s) — declared once and pointed at, never repeated per member.
 //
 // REFUSED — these functions are real and callable, and their declared arguments
@@ -155,6 +155,118 @@ type CallOptions = {
   }
 }
 
+declare namespace BowmarkCapability_browser_agent {
+  // ── Browser agent — the unit's own declarations, verbatim ──
+type BrowserAgentStatus = "running" | "needs_input" | "idle" | "failed" | "stopped" | "closed";
+interface BrowserAgentQuestion {
+  kind: "question" | "takeover";   // takeover = a person must act in watchUrl (login, captcha)
+  question: string;
+}
+interface StartBrowserAgentOptions {
+  task: string;             // plain language, name the site
+  backend?: string;         // default "browser_use"
+  model?: string;           // e.g. "claude-sonnet-5"; default "gpt-5.6-luna"
+  maxCostUsd?: number;      // vendor spend ceiling per turn, default 2, max 25
+  proxyCountry?: string;    // e.g. "us"
+  timeoutMs?: number;
+}
+interface StartBrowserAgentResult {
+  id: string;               // keep this: status/send/stop take it
+  status: BrowserAgentStatus;
+  watchUrl: string;         // private link to WATCH AND CONTROL the live browser — show it to your user only
+  backend: string;
+  model: string;
+  warnings: string[];
+}
+interface BrowserAgentStep { at: string; kind: "thinking" | "action" | "message"; text: string }
+interface BrowserAgentStatusOptions {
+  cursor?: string;          // from the previous status() — only newer steps return
+  waitMs?: number;          // wait up to this long (max 60000) for the status to change
+  timeoutMs?: number;
+}
+interface BrowserAgentStatusResult {
+  id: string;
+  status: BrowserAgentStatus;
+  question: BrowserAgentQuestion | null;   // set when status is "needs_input"
+  result: string | null;                   // the agent's answer for its last finished turn
+  error: string | null;
+  steps: BrowserAgentStep[];
+  cursor: string;
+  task: string;
+  backend: string;
+  model: string;
+  closed: boolean;
+  warnings: string[];
+}
+interface SendBrowserAgentOptions { interrupt?: boolean; timeoutMs?: number }
+interface SendBrowserAgentResult { id: string; status: BrowserAgentStatus; warnings: string[] }
+interface StopBrowserAgentResult { id: string; status: BrowserAgentStatus; warnings: string[] }
+interface BrowserAgentSummary {
+  id: string; status: BrowserAgentStatus; task: string; backend: string; model: string;
+  question: BrowserAgentQuestion | null; createdAt: string; closedAt: string | null;
+}
+interface ListBrowserAgentsOptions { open?: boolean }   // default true
+interface ListBrowserAgentsResult { sessions: BrowserAgentSummary[]; warnings: string[] }
+interface WatchLinkResult { id: string; watchUrl: string; warnings: string[] }
+
+type CallOptions = {
+  timeoutMs?: number   // per-provider budget in ms, default 30000, clamped to 1000-55000.
+                       // A provider slower than this is DROPPED from the results and
+                       // NAMED in warnings — never silently absent
+}
+
+  /**
+   * LAST RESORT, and it costs money: hands a plain-language task to a hosted AI browser agent
+   * (Browser Use) when no Bowmark function covers the site or a script against one failed.
+   * Returns a session id and a private link your user can open to watch and take over the live
+   * browser; later scripts poll it, answer its questions and stop it.
+   */
+  interface Unit {
+    /**
+     * Starts a hosted browser agent on `task` and returns at once with its session `id` and a
+     * `watchUrl`. Use ONLY after the library had nothing for this site or a function failed — each
+     * turn spends real vendor money, charged to the account. Show `watchUrl` to your user: it lets
+     * them watch the agent and take over the browser (log in, solve a captcha). Then poll with
+     * `status`.
+     */
+    start(options: StartBrowserAgentOptions): Promise<StartBrowserAgentResult>;
+
+    /**
+     * Reads a session: `running`, `needs_input` (relay `question` to your user, answer with
+     * `send`), `idle` (done — read `result`), `failed`, `stopped` or `closed`. Pass the previous
+     * `cursor` for only new steps, and `waitMs` (≤ 60000) to wait for a change instead of polling
+     * tightly.
+     */
+    status(id: string, options?: BrowserAgentStatusOptions): Promise<BrowserAgentStatusResult>;
+
+    /**
+     * Sends the agent a follow-up in the same browser: an answer to its question, the go-ahead
+     * after your user took over, or a new instruction. Runs when its current turn ends, or at once
+     * with `interrupt: true`. Each turn is billed.
+     */
+    send(id: string, message: string, options?: SendBrowserAgentOptions): Promise<SendBrowserAgentResult>;
+
+    /**
+     * Stops the agent and shuts its browser; the watch link stops working. Always stop a session
+     * you are done with — an open browser keeps costing money until Bowmark closes it after 20
+     * idle minutes.
+     */
+    stop(id: string): Promise<StopBrowserAgentResult>;
+
+    /**
+     * Lists this account's browser agent sessions, open ones by default — how to recover an id you
+     * lost.
+     */
+    list(options?: ListBrowserAgentsOptions): Promise<ListBrowserAgentsResult>;
+
+    /**
+     * Makes a NEW watch link for an open session, for when the one from `start` was lost. The
+     * previous link stops working.
+     */
+    watchLink(id: string): Promise<WatchLinkResult>;
+  }
+}
+
 declare namespace BowmarkCapability_bundles {
   // ── Check whether a set of products can be built and bought right now — the unit's own declarations, verbatim ──
 interface BundleItemAvailability {
@@ -571,23 +683,19 @@ type CallOptions = {
 }
 
   /**
-   * Actually RUNS a developer dashboard's signup flow and hands back a real, usable API key — no
-   * email verification, no CAPTCHA, for the dashboards this covers. Today: Alpha Vantage's free
-   * stock-data API. Call it directly; don't just describe the steps. If the caller gave no
-   * organization/email of their own, invent a placeholder — this is an instant, unverified
-   * free-tier signup, not an account tied to a real identity, so there is nothing to ask
-   * permission for. MAKE THE EMAIL UNIQUE PER CALL (see the worked example) — the dashboard
-   * dedupes by address, so a copied literal example email gets "Redundant origin" on the second
-   * and every later run.
+   * Actually RUNS a developer dashboard's signup flow and hands back a real, usable API key.
+   * Supports: Alpha Vantage (instant, no verification). Call it directly; don't just describe
+   * the steps. For Alpha Vantage with a placeholder identity: MAKE THE EMAIL UNIQUE PER CALL
+   * (see the worked example) — the dashboard dedupes by address, so a copied literal example
+   * email gets "Redundant origin" on the second and every later run.
    */
   interface Unit {
     /**
      * Signs up for a real developer API key on a dashboard. `service` selects which dashboard:
-     * "alphavantage" for stock data. Supported today: alphavantage — THROWS naming the supported
-     * list otherwise. Signs up instantly; `details.organization` and `details.email` required
-     * (MAKE EMAIL UNIQUE PER CALL, e.g. `qa-${Date.now()}@example.com`, dashboard rejects
-     * repeats). `details.occupation` optional. Returns real key plus confirmation.
-     * `options.timeoutMs` sets call budget (default 30000).
+     * "alphavantage" for stock data. For alphavantage: `details.organization` and `details.email`
+     * required (MAKE EMAIL UNIQUE PER CALL, e.g. `qa-${Date.now()}@example.com`);
+     * `details.occupation` optional. Returns real key plus confirmation. `options.timeoutMs` sets
+     * call budget (default 30000).
      */
     signUp(service: string, details: object, options?: CallOptions): Promise<DeveloperApiKeySignupResult>;
   }
@@ -724,6 +832,27 @@ type CallOptions = {
 
 declare namespace BowmarkCapability_flights {
   // ── Flights — the unit's own declarations, verbatim ──
+// ── "Which day is cheapest?" ── NOT a flights.* function: it is ONE provider call,
+// bowmark.providers.google_flights.getPriceGraph(query: FlightQuery): Promise<PriceGraph>,
+// typed here so no second lookup is needed. Only from/to/depart/return are read.
+// The window is Google's own: about depart-7 days to depart+52 days, not selectable,
+// so to cover a whole month from its 1st pass depart = the 8th.
+type PricePoint = {
+  date: string             // departure date, "2026-11-08"
+  returnDate: string | null // the return priced with it; null for one-way
+  price: number | null     // cheapest total that day; null where none was priced
+  currency: string
+}
+type PriceGraph = {
+  from: string
+  to: string
+  tripType: "round trip" | "one way"
+  rangeStart: string       // the window Google actually returned
+  rangeEnd: string
+  points: PricePoint[]     // ascending by date
+  cheapest: PricePoint | null // ties go to the earliest date
+  url: string
+}
 type FlightQuery = {
   from: string          // IATA ("SFO") — best for cross-provider matching
   to: string
@@ -876,7 +1005,10 @@ type FlightStatusResult = {
      * returning `flights: []`, since an empty list would otherwise be indistinguishable from a
      * route nobody flies. `options.timeoutMs` sets the per-site budget (default 30000) — a site
      * slower than that is dropped and named, so the answer arrives inside the calling client's own
-     * tool-call limit rather than not at all.
+     * tool-call limit rather than not at all. **For 'which day is cheapest' over a range of dates,
+     * do not call this once per date**: `bowmark.providers.google_flights.getPriceGraph(query:
+     * FlightQuery): Promise<PriceGraph>` (both typed above) prices every departure date from about
+     * depart-7 to depart+52 in one call.
      */
     search(query: FlightQuery, options?: CallOptions): Promise<FlightSearchResult>;
 
@@ -2591,11 +2723,12 @@ type ShippingQuery = {
 // One normalized shipping-rate quote. Same shape no matter which carrier
 // quoted it.
 type ShippingRate = {
-  source: string                              // "usps" | "ups"
+  source: string                              // "usps" | "ups" | "pirateship"
   serviceCode: string                         // the carrier's own code, verbatim
   serviceName: string                         // the carrier's own name, e.g. "UPS Ground"
   price: { amount: number; currency: string } // integer minor units (cents)
   transitDays: number | null                  // null when the carrier didn't state one
+  deliveryEstimate?: string | null            // the carrier's own delivery-date text, when stated
 }
 
 type ShippingEstimateResult = {
@@ -2613,20 +2746,23 @@ type CallOptions = {
    * Prices a domestic package across USPS and UPS for a ZIP-to-ZIP move, weight and optional
    * dimensions, and returns normalized quotes cheapest first — service name, price and transit
    * days where the carrier states one. Direct JSON, no browser. USPS needs no key and always
-   * quotes; UPS is BYOK, and a caller without a UPS developer key gets the USPS quotes plus a
-   * `warnings` line naming what was dropped rather than a silent skip.
+   * quotes. Pirate Ship (source `pirateship`) also quotes USPS AND UPS with no key, at its
+   * discounted label prices, with a delivery date. UPS direct is BYOK; without a UPS developer
+   * key that one leg is dropped and named in `warnings`.
    */
   interface Unit {
     /**
      * Prices a domestic package — `{ fromZip: "20024", toZip: "10001", weightOz: 16 }` — across
      * every USPS and UPS service that quotes it, and returns `rates` cheapest first.
      * `length`/`width`/`height` (inches) must be given together or omitted entirely. USPS needs no
-     * API key. UPS is BYOK: bring your own UPS developer key or that leg is dropped and named in
-     * `warnings` (it is never served off a fleet credential). `warnings` also names any carrier
-     * dropped for a timeout or an error. THROWS `AllProvidersFailedError` when NEITHER carrier
-     * answered, because that is a different fact from "no service quotes this shipment" and only
-     * one of them means there truly is no rate. `options.timeoutMs` sets the per-carrier budget
-     * (default 30000).
+     * API key. Pirate Ship (`source: "pirateship"`) needs none either and quotes BOTH USPS and UPS
+     * at its discounted label prices, with the carrier named in `serviceName` and a
+     * `deliveryEstimate` date; given no dimensions, it prices a 10x8x4 inch box. UPS direct is
+     * BYOK: bring your own UPS developer key or that leg is dropped and named in `warnings` (it is
+     * never served off a fleet credential). `warnings` also names any carrier dropped for a
+     * timeout or an error. THROWS `AllProvidersFailedError` when NEITHER carrier answered, because
+     * that is a different fact from "no service quotes this shipment" and only one of them means
+     * there truly is no rate. `options.timeoutMs` sets the per-carrier budget (default 30000).
      */
     estimate(query: ShippingQuery, options?: CallOptions): Promise<ShippingEstimateResult>;
   }
@@ -4691,6 +4827,7 @@ interface GetAppsResult {
 }
 interface GetAppDetailsArgs {
   app: string | number;
+  country?: string;
 }
 interface AppStoreRatingHistogram {
   average: number;
@@ -4725,6 +4862,7 @@ interface AppStoreFeaturedStory {
 }
 interface AppStoreAppDetails {
   id: string;
+  country: string;
   url: string;
   ratings: AppStoreRatingHistogram | null;
   chartPosition: AppStoreChartPosition | null;
@@ -4751,6 +4889,7 @@ interface ListTopChartsArgs {
   device?: AppStoreChartDevice;
   chart?: AppStoreChartKind;
   genreId?: string | number;
+  country?: string;
   limit?: number;
 }
 interface AppStoreChartApp {
@@ -4769,6 +4908,7 @@ interface ListTopChartsResult {
   device: AppStoreChartDevice;
   chart: AppStoreChartKind;
   genreId: string;
+  country: string;
   source: "page" | "feed";
   apps: AppStoreChartApp[];
 }
@@ -4784,6 +4924,7 @@ interface ListDeveloperAppsResult {
 }
 interface ListSimilarAppsArgs {
   app: string | number;
+  country?: string;
 }
 interface AppStoreSimilarApp {
   id: string;
@@ -4797,11 +4938,13 @@ interface AppStoreSimilarApp {
 }
 interface AppStoreSimilarAppsResult {
   id: string;
+  country: string;
   apps: AppStoreSimilarApp[];
 }
 interface GetStoryArgs {
   story: string | number;
   platform?: AppStoreChartDevice;
+  country?: string;
 }
 interface AppStoreStoryApp {
   id: string;
@@ -4816,6 +4959,7 @@ interface AppStoreStoryApp {
 }
 interface AppStoreStory {
   id: string;
+  country: string;
   url: string;
   heading: string;
   title: string;
@@ -4823,6 +4967,20 @@ interface AppStoreStory {
   body: string;
   apps: AppStoreStoryApp[];
 }
+interface ListTodayStoriesArgs {
+  device?: AppStoreChartDevice;
+  country?: string;
+}
+interface AppStoreTodayStory {
+  id: string;
+  title: string;
+  url: string;
+}
+interface ListTodayStoriesResult {
+  device: AppStoreChartDevice;
+  country: string;
+  stories: AppStoreTodayStory[];
+}
 type AppStoreReviewSort = "mostRecent" | "mostHelpful";
 interface ListReviewsArgs {
   app: string | number;
@@ -4941,6 +5099,13 @@ interface ListReviewsResult {
      * into a reason.
      */
     listReviews(args: ListReviewsArgs): Promise<ListReviewsResult>;
+
+    /**
+     * List the editorial stories Apple is featuring on the Today tab right now — the page a person
+     * actually sees when they open the App Store — each with the id and URL getStory takes. The
+     * door into getStory for an agent that holds no app yet, rather than one that already does.
+     */
+    listTodayStories(args?: ListTodayStoriesArgs): Promise<ListTodayStoriesResult>;
   }
 }
 
@@ -5000,6 +5165,24 @@ interface AppleConfigurationOptions {
   configDimensions: AppleConfigDimension[];
   configurations: AppleConfiguration[];
 }
+interface ApplePurchaseOptionTerm {
+  id: string;
+  name: string;
+  sectionHeader: string;
+  sectionFooter: string;
+}
+interface ApplePurchaseOption {
+  id: string;
+  formValue: string;
+  sectionHeader: string;
+  sectionFooter: string;
+  hideCarrier: boolean;
+  terms: ApplePurchaseOptionTerm[];
+}
+interface ApplePurchaseOptions {
+  url: string;
+  options: ApplePurchaseOption[];
+}
 interface AppleFamilyModel {
   name: string;
   startingPrice: number | null;
@@ -5130,6 +5313,34 @@ interface AppleStore {
   longitude: number | null;
   hours: AppleStoreHours[];
 }
+interface AppleNewsroomPost {
+  title: string;
+  category: string;
+  date: string;
+  url: string;
+  summary: string;
+}
+interface AppleNewsroomPostList {
+  posts: AppleNewsroomPost[];
+}
+interface AppleNewsroomArticle {
+  title: string;
+  summary: string;
+  date: string;
+  url: string;
+  body: string;
+}
+interface AppleCompareSpec {
+  label: string;
+  value: string;
+}
+interface AppleCompareModel {
+  name: string;
+  specs: AppleCompareSpec[];
+}
+interface AppleCompareModels {
+  models: AppleCompareModel[];
+}
 
   /** apple.com's own site search and product pages — no API, no login, no browser. */
   interface Unit {
@@ -5175,6 +5386,32 @@ interface AppleStore {
      */
     getConfigurationOptions(urlOrPath: string): Promise<AppleConfigurationOptions>;
 
+    /**
+     * Reads the ways apple.com will let you pay for the product a buy page has settled on — buy
+     * outright, Apple Card Monthly Installments, or the Apple Upgrade Program lease (with its 24-
+     * vs 36-month term choice) — with apple.com's own copy for each, straight off the buy page's
+     * own window.PURCHASE_OPTIONS_BOOTSTRAP. Only a page that has resolved to ONE product exposes
+     * this: every Mac family buy page has (e.g. "/shop/buy-mac/macbook-air"), an iPhone/iPad
+     * chooser page has not even at one specific part number, and this throws a caller-fixable
+     * error naming that rather than guessing. Carries no dollar figure — apple.com computes a
+     * monthly amount only after a term and trade-in are picked on the buy page itself; read a
+     * configuration's own price off getConfigurationOptions.
+     */
+    getPurchaseOptions(urlOrPath: string): Promise<ApplePurchaseOptions>;
+
+    /**
+     * Puts two or more iPhone models side by side on the specs apple.com itself compares them on —
+     * screen size, chip, camera system, battery, capacity, finish, durability rating, connectivity
+     * — straight off apple.com's own /iphone/compare/ grid. Model names must match the page's own
+     * naming exactly (e.g. "iPhone 17 Pro", not "17 Pro" or "iphone17pro"); an unmatched name
+     * throws naming the page's own list. Carries no price: apple.com's own compare page renders
+     * its Price row as an unfilled client-side template with no number in the static HTML, so this
+     * omits it rather than guess — read a price off getConfigurationOptions or getPurchaseOptions
+     * instead. A spec absent for one model (an older phone with no Dynamic Island) is simply
+     * missing from that model's own list, never a false "no".
+     */
+    compareModels(models: string[]): Promise<AppleCompareModels>;
+
     /**
      * Lists every model apple.com currently sells in one product family — the chooser page's own
      * cards (e.g. "MacBook Air", "iPad mini"), each with its starting price and the buy page that
@@ -5276,6 +5513,19 @@ interface AppleStore {
      * Takes a URL or /retail/ path, e.g. one of listStores()'s own rows.
      */
     getStore(urlOrPath: string): Promise<AppleStore>;
+
+    /**
+     * Apple's official announcements, newest first, off its own published RSS feed — every product
+     * launch, financial result and press release, with its headline, category, publish date and
+     * link. The primary source for "what did Apple just announce", with no publisher in between.
+     */
+    listNewsroomPosts(): Promise<AppleNewsroomPostList>;
+
+    /**
+     * Read one Apple press release or announcement in full from its URL — the article text itself,
+     * not the feed's one-line summary. Takes a URL straight off listNewsroomPosts()'s own rows.
+     */
+    getNewsroomPost(url: string): Promise<AppleNewsroomArticle>;
   }
 }
 
@@ -6979,18 +7229,18 @@ interface bestbuyProduct {
 }
 
   /**
-   * Best Buy's own documented Products API (api.bestbuy.com) — searches the live bestbuy.com
-   * catalog by query and returns price, availability and review data, and looks up one product
-   * by Best Buy's own SKU, without scraping bestbuy.com's search page.
+   * Searches the live bestbuy.com catalog by query and returns price, availability and review
+   * data — off bestbuy.com's own search page with no key, or Best Buy's documented Products API
+   * when a key is available — and looks up one product by Best Buy's own SKU (key required).
    */
   interface Unit {
     /**
-     * Runs a Best Buy product search the way bestbuy.com's own search box does, via Best Buy's
-     * documented Products API, and returns the matching products — name, sale/regular price,
-     * online and in-store availability, manufacturer, model number, UPC and review stats.
-     * `pageSize` caps the row count (default 10, Best Buy's own ceiling 100). Uses Bowmark's Best
-     * Buy key and charges each request to your account; send your own key as the
-     * `x-bowmark-vendor-key-bestbuy` header instead.
+     * Runs a Best Buy product search the way bestbuy.com's own search box does and returns the
+     * matching products — name, sale/regular price, online and in-store availability and review
+     * stats. With a Best Buy developer key (Bowmark's, charged to your account, or your own on the
+     * `x-bowmark-vendor-key-bestbuy` header) it reads the documented Products API and also fills
+     * manufacturer, model number and UPC. With no key it reads bestbuy.com's own search results
+     * page, where those three fields are null. `pageSize` caps the row count (default 10).
      */
     search(args: string | { query: string; pageSize?: number }): Promise<bestbuyProduct[]>;
 
@@ -8251,6 +8501,107 @@ interface BrixtonCheckoutLink {
   }
 }
 
+declare namespace BowmarkProvider_browser_use {
+  // ── Browser Use — the unit's own declarations, verbatim ──
+type BrowserUseRunStatus = "queued" | "dispatching" | "running" | "completed" | "failed" | "cancelled";
+
+interface BrowserUseCreateRunArgs {
+  task: string;
+  model?: string;             // e.g. "claude-sonnet-5"; absent = vendor default
+  sessionId?: string;         // continue a session
+  maxCostUsd?: number;
+  proxyCountryCode?: string;  // e.g. "us"
+}
+
+interface BrowserUseRunStatusReading { runId: string; status: BrowserUseRunStatus }
+interface BrowserUseCreatedRun { id: string; status: BrowserUseRunStatus; model: string; sessionId: string; workspaceId: string }
+
+interface BrowserUseRun {
+  id: string; sessionId: string; task: string; title: string | null; model: string;
+  status: BrowserUseRunStatus; result: string | null; error: string | null;
+  inputTokens: number; outputTokens: number;
+  costUsd: number;            // LLM cost only
+  createdAt: string; updatedAt: string;
+}
+
+interface BrowserUseRunList { runs: BrowserUseRun[]; hasMore: boolean }
+interface BrowserUseEvent { id: number; ts: string; type: string; data: Record<string, unknown> }
+interface BrowserUseEventsPage { events: BrowserUseEvent[]; nextAfter: number | null; hasMore: boolean }
+interface BrowserUseEventsArgs { runId: string; after?: number; limit?: number }
+
+interface BrowserUseSession { sessionId: string; latestRunId: string; status: string; title: string | null; createdAt: string; updatedAt: string }
+
+interface BrowserUseQueueArgs { sessionId: string; text: string; interrupt?: boolean }
+interface BrowserUseQueuedMessage { id: number; sessionId: string; status: string; mode: string }
+
+interface BrowserUseBrowser {
+  id: string; status: string;
+  liveUrl: string | null;     // interactive; whoever holds it drives the browser
+  agentSessionId: string | null;
+  timeoutAt: string; startedAt: string; finishedAt: string | null;
+  browserCostUsd: number; proxyCostUsd: number; proxyUsedMb: number;
+}
+
+  /**
+   * Browser Use Cloud's hosted browser agent. Not callable directly: use
+   * `bowmark.browser_agent`, which runs it for you with a private watch link and bills the
+   * session to your account.
+   */
+  interface Unit {
+    /**
+     * Starts a Browser Use agent run on a natural-language task, optionally continuing an existing
+     * session. Returns immediately; the run executes on Browser Use's cloud for seconds to
+     * minutes. Spends money.
+     */
+    createRun(args: BrowserUseCreateRunArgs): Promise<BrowserUseCreatedRun>;
+
+    /** Reads one run: status, final result or error, token totals and LLM cost. */
+    getRun(runId: string): Promise<BrowserUseRun>;
+
+    /** The cheap status poll for one run. */
+    getRunStatus(runId: string): Promise<BrowserUseRunStatusReading>;
+
+    /**
+     * A run's step-by-step event stream after a cursor — the agent's reasoning, tool calls, and
+     * the `browser.ready` event carrying the live view url.
+     */
+    listRunEvents(args: BrowserUseEventsArgs): Promise<BrowserUseEventsPage>;
+
+    /**
+     * Lists every run (agent turn) in a session, newest first, each with its status and LLM cost —
+     * how a session's whole spend is read.
+     */
+    listSessionRuns(sessionId: string): Promise<BrowserUseRunList>;
+
+    /**
+     * Cancels an in-flight run; idempotent on a finished one. The browser keeps running — stop it
+     * separately.
+     */
+    cancelRun(runId: string): Promise<BrowserUseRun>;
+
+    /** Reads a session, including the id of its latest run (a queued message becomes a new run). */
+    getSession(sessionId: string): Promise<BrowserUseSession>;
+
+    /**
+     * Sends a follow-up instruction into a session: it runs as the next turn when the current one
+     * ends, or at once with `interrupt: true`.
+     */
+    queueMessage(args: BrowserUseQueueArgs): Promise<BrowserUseQueuedMessage>;
+
+    /** The cloud browser attached to a session, with its live view url and running cost, or null. */
+    findSessionBrowser(sessionId: string): Promise<BrowserUseBrowser | null>;
+
+    /** Reads one cloud browser: status, live view url, browser and proxy cost. */
+    getBrowser(browserId: string): Promise<BrowserUseBrowser>;
+
+    /**
+     * Stops a cloud browser (cannot be undone). Its cost is then settled down to the time actually
+     * used.
+     */
+    stopBrowser(browserId: string): Promise<BrowserUseBrowser>;
+  }
+}
+
 declare namespace BowmarkProvider_builder_strucsure_com {
   // ── StrucSure Home Warranty — the unit's own declarations, verbatim ──
 interface StrucsureRegistrationState {
@@ -9038,7 +9389,10 @@ interface CamelPriceHistory {
     /**
      * Runs camelcamelcamel's own Amazon-product search and returns each hit's ASIN, title and
      * current price — the locator this provider was missing: `getPriceHistory` takes an ASIN, and
-     * this is how a caller holding only a shopper's words finds one.
+     * this is how a caller holding only a shopper's words finds one. Pass the product's name; if
+     * the full wording matches nothing it retries on its own with measurements ("24000mAh",
+     * "140W") dropped, so there is no need to re-run it with shorter queries, and no need to
+     * search Amazon as well to find the ASIN.
      */
     search(query: string): Promise<CamelSearchResult[]>;
 
@@ -9046,6 +9400,11 @@ interface CamelPriceHistory {
      * Reads camelcamelcamel's independently-tracked Amazon price history for one ASIN — the site's
      * own lowest-ever/highest-ever/current/average figures, each dated, for the Amazon,
      * 3rd-party-new and 3rd-party-used price types, plus the full-history chart image URL.
+     * `amazon.current.price` is Amazon's own price today and is null when Amazon itself is not
+     * selling it, which is an answer rather than a gap. These summary figures are ALL the history
+     * the library has: there is no month-by-month series anywhere (the chart is an image), so
+     * answer 'how has the price moved' from lowest/highest/average/current and do not look for
+     * another source.
      */
     getPriceHistory(asinOrUrl: string): Promise<CamelPriceHistory>;
   }
@@ -16868,12 +17227,52 @@ interface GoogleTranslateSpeech {
   contentType: string;
   chunkCount: number;
 }
+interface TranslateWebPageArgs {
+  url: string;
+  to: string;
+  from?: string;
+}
+interface GoogleTranslateWebPageSegment {
+  original: string;
+  translated: string;
+}
+interface GoogleTranslateWebPage {
+  url: string;
+  title: string;
+  translatedTitle: string;
+  targetLanguage: string;
+  sourceLanguage: string;
+  detected: boolean;
+  segments: GoogleTranslateWebPageSegment[];
+}
+interface TranslateDocumentArgs {
+  fileBase64: string;
+  mimeType: string;
+  to: string;
+  from?: string;
+}
+interface GoogleTranslateDocumentResult {
+  translatedBase64: string;
+  mimeType: string;
+}
+interface TranslateImageArgs {
+  imageBase64: string;
+  mimeType: string;
+  to: string;
+  from?: string;
+}
+interface GoogleTranslateImageResult {
+  translatedImageBase64: string;
+  mimeType: string;
+  sourceText: string;
+  translatedText: string;
+}
 
   /**
    * Translate text into any of 249 languages, in a batch if you have a list, and find out what
    * language something already is — plus the dictionary underneath: senses, definitions,
-   * synonyms, alternative wordings, the romanization and the spoken audio. `translate` is built;
-   * everything else is still a declared stub.
+   * synonyms, alternative wordings, the romanization and the spoken audio. Thirteen functions
+   * are built; the four account-gated ones (saved phrases, history) are still declared stubs.
    */
   interface Unit {
     /**
@@ -16976,6 +17375,41 @@ interface GoogleTranslateSpeech {
      * function must not do.
      */
     speak(args: SpeakArgs): Promise<GoogleTranslateSpeech>;
+
+    /**
+     * Read `args.url` in `args.to` — fetches the page with a plain GET (no browser; a page that
+     * renders its text client-side is out of reach), walks its rendered text nodes in reading
+     * order, and translates them through this provider's own `translate` door. Measured 2026-09-16
+     * that `<host>.translate.goog` (the site's own page-translation product) serves the ORIGINAL
+     * page plus a client-side translator script and never returns translated text browserless,
+     * which is why this fetches the caller's url directly instead. `args.from` is optional and,
+     * left out, the source is detected off the page's title. `segments` preserves the page's own
+     * reading order.
+     */
+    translateWebPage(args: TranslateWebPageArgs): Promise<GoogleTranslateWebPage>;
+
+    /**
+     * Translate a whole PDF, Word or PowerPoint file — the Documents tab. Takes `fileBase64` (the
+     * document, base64-encoded), `mimeType`, `to`, and optional `from` (left out, auto-detects),
+     * and returns `translatedBase64` + `mimeType` for the SAME document translated. Built on a
+     * real browser (rung 15): the RPC answers 200 to a bare browserless replay too, but silently
+     * returns the document UNTRANSLATED without a BotGuard token (`x-goog-batchexecute-bgr`) only
+     * a real browser produces — measured 2026-09-16, two earlier browserless-adjacent attempts
+     * read that 200 as success.
+     */
+    translateDocument(args: TranslateDocumentArgs): Promise<GoogleTranslateDocumentResult>;
+
+    /**
+     * Read the text in a picture and translate it — the Images tab. Takes `imageBase64` (the
+     * image, base64-encoded), `mimeType`, `to`, and optional `from` (left out, auto-detects), and
+     * returns `translatedImageBase64` + `mimeType` (a copy of the image with the detected text
+     * replaced in place) plus the plain `sourceText`/`translatedText` strings Google's OCR found.
+     * Shares `translateDocument`'s RPC channel and BotGuard gate (rung 15, real browser) but its
+     * own rpcid (`WqWDPb`) and upload shape — measured 2026-09-16 uploading a real PNG with
+     * rendered glyphs, verified "Hola mundo" → "Bonjour le monde" (tl=fr) and → "Hello world"
+     * (tl=en).
+     */
+    translateImage(args: TranslateImageArgs): Promise<GoogleTranslateImageResult>;
   }
 }
 
@@ -22634,7 +23068,7 @@ interface LululemonColorway {
   imageAssets: ProductImage[];
   sale: SaleEvidence;
   coordination: CoordinationMetadata;
-  /** ISO 4217, or null. Always null — see SaleEvidence.currency. */
+  /** ISO 4217 from the colourway url's own locale, or null for an unknown one. */
   currency: string | null;
   inStock: boolean;
   optionGroups: LululemonOptionGroup[];
@@ -27006,6 +27440,7 @@ interface PrimeVideoTitleDetail {
   releaseYear: number | null;
   releaseDate: string | null;
   runtime: string | null;
+  durationSeconds: number | null;
   genres: string[];
   maturityRating: string | null;
   cast: PrimeVideoCredit[];
@@ -27046,6 +27481,25 @@ interface PrimeVideoEpisode {
   isPrime: boolean;
   isAd: boolean;
 }
+interface PrimeVideoPersonCredit {
+  titleId: string | null;
+  catalogId: string;
+  title: string;
+  releaseYear: number | null;
+  runtime: string | null;
+  synopsis: string | null;
+  maturityRating: string | null;
+}
+interface PrimeVideoPerson {
+  personId: string;
+  name: string;
+  roles: string[];
+  birthPlace: string | null;
+  dateOfBirth: string | null;
+  bio: string | null;
+  imdbUrl: string | null;
+  filmography: PrimeVideoPersonCredit[];
+}
 interface PrimeVideoCategory {
   name: string;
   slug: string;
@@ -27084,6 +27538,26 @@ interface PrimeVideoLiveStation {
   group: string;
   nowPlaying: PrimeVideoLiveProgram | null;
 }
+interface PrimeVideoLiveScheduleEntry {
+  title: string;
+  seriesTitle: string | null;
+  seasonNumber: number | null;
+  episodeNumber: number | null;
+  synopsis: string | null;
+  maturityRating: string | null;
+  start: number;
+  end: number;
+}
+interface PrimeVideoLiveSportsEvent {
+  titleId: string;
+  title: string;
+  group: string;
+  status: "LIVE" | "UPCOMING" | null;
+  timeBadge: string | null;
+  venue: string | null;
+  entitled: boolean;
+  watchMessage: string | null;
+}
 
   /**
    * Search Prime Video's catalogue and read a film or series the way a viewer does — synopsis,
@@ -27091,8 +27565,8 @@ interface PrimeVideoLiveStation {
    * included with Prime, free with ads, on a named add-on channel, or rentable and buyable with
    * the real price. Plus the browse surfaces (genres, collections, the top ten, this week's
    * deals), the add-on channels, and the free live TV, news and sports schedules. searchTitles,
-   * suggestTitles, getTitle, getWatchOptions, listSeasons, listEpisodes and listCategories are
-   * built; everything else is still a declared stub.
+   * suggestTitles, getTitle, getWatchOptions, listSeasons, listEpisodes, getPerson and
+   * listCategories are built; everything else is still a declared stub.
    */
   interface Unit {
     /**
@@ -27101,13 +27575,21 @@ interface PrimeVideoLiveStation {
      * function here takes, whether it is a film or a series, the year, the maturity rating, and
      * the site's own sentence for how to watch it. THE provider's door: every titleId-taking
      * function below is fed by this one. Returns the FIRST page only — Prime Video's search page
-     * carries no pagination markers at all (measured 2026-09-15) — and the site's six refinement
-     * filters (film-or-series, how you can watch it, which channel, HD/UHD, theme, audio language)
-     * are not built here: they ride an opaque per-page `serviceToken`, not a query parameter, and
-     * a query parameter silently returns the unfiltered set rather than erroring. A query that
-     * matches nothing returns an empty array rather than throwing.
-     */
-    searchTitles(query: string): Promise<PrimeVideoTitle[]>;
+     * carries no pagination markers at all (measured 2026-09-15). `options.waysToWatch` narrows by
+     * how you can watch it — "prime" (included with a Prime membership), "channels" (an add-on
+     * subscription) or "rentOrBuy" — the commonest thing a viewer does after typing a query and
+     * the one refinement built so far. The site's other five refinement dimensions (which channel,
+     * HD/UHD, theme, subtitle language, film-or-series) are still not built here: every one of
+     * them rides the same opaque per-page `serviceToken` mechanism (rung 11 — an undocumented
+     * endpoint reached by harvesting the token off the page a search already returned), never a
+     * query parameter, and a hand-constructed query parameter silently returns the unfiltered set
+     * rather than erroring. A query that matches nothing returns an empty array rather than
+     * throwing. A filtered call whose real matches are too few can carry the site's own generic
+     * recommendations under a heading still labelled "Top results" — measured 2026-09-16, not a
+     * defect in this parser: the site does this identically on the unfiltered page's own "More to
+     * explore" row.
+     */
+    searchTitles(query: string, options?: { waysToWatch?: "prime" | "channels" | "rentOrBuy" }): Promise<PrimeVideoTitle[]>;
 
     /**
      * Ask Prime Video's own search box what it would autocomplete a prefix to — "the boy" comes
@@ -27119,12 +27601,13 @@ interface PrimeVideoLiveStation {
 
     /**
      * Read one film, series-season or episode the way a viewer reads its page: title, synopsis,
-     * year, release date, runtime, genres, maturity rating, cast, directors, studio, the Amazon
-     * customer rating and its five-star histogram, the IMDb score, which audio languages and
-     * subtitles it ships, and whether it is in UHD, HDR, Dolby Atmos or X-Ray. The core read of
-     * the whole provider. Takes a titleId or a title URL, e.g. one read off searchTitles(). THE
-     * REVIEW TEXT IS NOT HERE — the aggregate rating and histogram are real and logged out, but
-     * review bodies are amazon.com's own surface behind amazon.com's sign-in wall.
+     * year, release date, runtime (both the display string and durationSeconds), genres, maturity
+     * rating, cast, directors, studio, the Amazon customer rating and its five-star histogram, the
+     * IMDb score, which audio languages and subtitles it ships, and whether it is in UHD, HDR,
+     * Dolby Atmos or X-Ray. The core read of the whole provider. Takes a titleId or a title URL,
+     * e.g. one read off searchTitles(). THE REVIEW TEXT IS NOT HERE — the aggregate rating and
+     * histogram are real and logged out, but review bodies are amazon.com's own surface behind
+     * amazon.com's sign-in wall.
      */
     getTitle(titleId: string): Promise<PrimeVideoTitleDetail>;
 
@@ -27163,6 +27646,16 @@ interface PrimeVideoLiveStation {
      */
     listEpisodes(titleId: string): Promise<PrimeVideoEpisode[]>;
 
+    /**
+     * Read a cast member's own Prime Video page: their name, what they are credited as, when and
+     * where they were born, their biography, and the titles of theirs the catalogue carries — with
+     * each credit's own synopsis, runtime and maturity rating, not just its title. How an agent
+     * answers "what else is she in" without leaving the site. Takes a personId or a person URL —
+     * read one off getTitle().cast[].searchLink, never .directors[].searchLink, which points at a
+     * search instead: a director gets no page of their own here, only a searchTitles() fallback.
+     */
+    getPerson(personId: string): Promise<PrimeVideoPerson>;
+
     /**
      * List the ways Prime Video lets you browse — its genres (action, comedy, horror, anime,
      * documentary and more, plus kids), its editorial collections (new and upcoming, award
@@ -27297,6 +27790,25 @@ interface PrimeVideoLiveStation {
      * when the page carries no station with that id.
      */
     getLiveSchedule(section: "livetv" | "news", stationId: string): Promise<PrimeVideoLiveProgram[]>;
+
+    /**
+     * What sport is on Prime Video now and what is coming — live and upcoming EVENTS, off
+     * `/sports`, never a station (that is `listLiveChannels`'s own shape, a `LinearStationCard`,
+     * which this function ignores) and never an on-demand documentary sharing the same page. No
+     * arguments. `group` names the row the event is listed under: "Sports with a subscription" is
+     * entitlement a Prime member already carries some of, "Apple TV: Live and upcoming events" is
+     * a different provider's events entirely, and `entitled`/`watchMessage` carry the site's own
+     * per-event verdict — measured 2026-09-16, a Prime-entitled poker event on the "Sports with a
+     * subscription" row reads `entitled: true, watchMessage: "Watch for free"` beside an
+     * Unentitled squash event on the SAME row reading `entitled: false, watchMessage: "Free trial
+     * of SquashTV"`, so the row heading alone never says whether a given event is free. `status`
+     * and `timeBadge` are the site's own words ("LIVE", "Live at 7 PM EDT", "Fri, Sep 18 6:30 PM
+     * EDT") — no epoch timestamp exists on an event card the way one does on a station's
+     * `schedule[]`, so none is invented. `venue` is `null` for an event with no physical location
+     * (an online poker series, a studio broadcast) — a real and common answer, never a parse
+     * failure.
+     */
+    listLiveSports(): Promise<PrimeVideoLiveSportsEvent[]>;
   }
 }
 
@@ -32729,6 +33241,25 @@ interface TwitchHighlight {
   channel: string;
   dashboardUrl: string;
 }
+interface SetChannelArgs {
+  /** The channel title shown on the stream page. Twitch's own input field for
+   * this is called "status"; this provider takes the name the UI shows. */
+  title?: string;
+  /** ISO 639-1 language code, e.g. "en". */
+  language?: string;
+  /** Category NAME, e.g. "Wetrix" — not a category id. */
+  game?: string;
+}
+interface TwitchChannelSettings {
+  id: string;
+  /** The channel title shown on the stream page. */
+  title: string;
+  /** ISO 639-1 language code, e.g. "en". */
+  language: string;
+  /** The category. Empty strings when the channel has never set one. */
+  gameId: string;
+  gameName: string;
+}
 interface RegisterDeveloperAppArgs {
   /** Application name */
   name: string;
@@ -32770,6 +33301,21 @@ interface TwitchDeveloperApp {
      * live archive has recorded so far (retry shortly in that case).
      */
     createHighlight(args: CreateHighlightArgs): Promise<TwitchHighlight>;
+
+    /**
+     * Reads the signed-in streamer's channel settings: title, language and current game/category.
+     * Takes no arguments. NEEDS the streamer's Twitch sign-in, which only a capability can hold:
+     * call it as bowmark.stream_channel.get.
+     */
+    getChannel(): Promise<TwitchChannelSettings>;
+
+    /**
+     * Updates the signed-in streamer's channel settings: title, language and game/category.
+     * Returns the updated settings. It cannot set tags — `tags` is not a field of Twitch's own
+     * UpdateBroadcastSettingsInput. NEEDS the streamer's Twitch sign-in, which only a capability
+     * can hold: call it as bowmark.stream_channel.set.
+     */
+    setChannel(args: SetChannelArgs): Promise<TwitchChannelSettings>;
   }
 }
 
@@ -33561,6 +34107,41 @@ interface VisibleGetPlansResult {
   }
 }
 
+declare namespace BowmarkProvider_vistaprint {
+  // ── Vistaprint — the unit's own declarations, verbatim ──
+type ShippingBoxSize = "11x8.5x5.5" | "12x12x5.5" | "13x13x10";
+type ShippingBoxPrintArea = "inside-and-outside" | "outside-only";
+
+interface GetShippingBoxPriceArgs {
+  size: ShippingBoxSize;
+  printArea: ShippingBoxPrintArea;
+  quantity: number;
+}
+
+interface ShippingBoxPrice {
+  size: ShippingBoxSize;
+  printArea: ShippingBoxPrintArea;
+  quantity: number;
+  price: { amount: number; currency: string };      // real total for `quantity` units
+  unitPrice: { amount: number; currency: string };
+}
+
+  /**
+   * Prices Vistaprint's Full-Print Shipping Boxes for a real size, print area and quantity — the
+   * live, quantity-tiered price the site's own PDP configurator computes, with no browser,
+   * account or cart. Custom printed boxes, mailer boxes and packaging boxes.
+   */
+  interface Unit {
+    /**
+     * Reads Vistaprint's own live pricing service for its Full-Print Shipping Boxes — the real,
+     * quantity-tiered total and per-unit price for a chosen box size, print area and quantity, the
+     * same figure the site's PDP configurator computes as a buyer changes those inputs. THROWS a
+     * caller-fixable error for a size/printArea/quantity combination Vistaprint has no price for.
+     */
+    getShippingBoxPrice(args: GetShippingBoxPriceArgs): Promise<ShippingBoxPrice>;
+  }
+}
+
 declare namespace BowmarkProvider_voluspa {
   // ── Voluspa — the unit's own declarations, verbatim ──
 interface VoluspaQuizButton {
@@ -34279,12 +34860,34 @@ interface YoutubeTranscript {
   fullText: string;
 }
 
+interface YoutubeSearchVideo {
+  videoId: string;
+  url: string;
+  title: string;
+  channel: string | null;
+  channelId: string | null;
+  published: string | null;          // YouTube's own phrase, e.g. "4 weeks ago"
+  publishedAgeSeconds: number | null; // that phrase in seconds, to order newest-first
+  length: string | null;             // e.g. "22:28"; null for a live stream
+  views: number | null;
+  thumbnail: string | null;
+}
+
   /**
    * A YouTube video's own caption transcript, read off the site's own Transcript panel —
    * timestamped lines plus the full text as one string. Language selection is not offered yet;
    * this reads whichever track the panel shows by default.
    */
   interface Unit {
+    /**
+     * Searches YouTube the way its search box does and returns the videos on the results page —
+     * id, url, title, channel, upload age, length and views. `uploadedWithin` applies YouTube's
+     * own upload-date filter. Rows come back in YouTube's own order either way, which is NOT
+     * newest first, so sort on `publishedAgeSeconds` (smaller is newer) to find the most recent.
+     * Pass a video's `url` or `videoId` straight to `getTranscript`.
+     */
+    search(input: { query: string; uploadedWithin?: "today" | "week" | "month" | "year" }): Promise<YoutubeSearchVideo[]>;
+
     /**
      * Returns a YouTube video's own caption transcript. `video` is a bare 11-character video id or
      * any watch/shorts/embed/live/youtu.be URL. `segments` is [] — a real, honest answer — when
@@ -35260,6 +35863,7 @@ interface BowmarkProviders {
   boydsleep: BowmarkProvider_boydsleep.Unit;
   brius: BowmarkProvider_brius.Unit;
   brixton: BowmarkProvider_brixton.Unit;
+  browser_use: BowmarkProvider_browser_use.Unit;
   builder_strucsure_com: BowmarkProvider_builder_strucsure_com.Unit;
   bulletproof: BowmarkProvider_bulletproof.Unit;
   bungalow: BowmarkProvider_bungalow.Unit;
@@ -35585,6 +36189,7 @@ interface BowmarkProviders {
   viewrail: BowmarkProvider_viewrail.Unit;
   villagerealtyobx: BowmarkProvider_villagerealtyobx.Unit;
   visible: BowmarkProvider_visible.Unit;
+  vistaprint: BowmarkProvider_vistaprint.Unit;
   voluspa: BowmarkProvider_voluspa.Unit;
   vscode: BowmarkProvider_vscode.Unit;
   walkerhughes: BowmarkProvider_walkerhughes.Unit;
@@ -87324,6 +87929,7 @@ interface BowmarkProviders {
  * generated once precisely so those two cannot drift. */
 interface BowmarkLibrary {
   booking_links: BowmarkCapability_booking_links.Unit;
+  browser_agent: BowmarkCapability_browser_agent.Unit;
   bundles: BowmarkCapability_bundles.Unit;
   cable_railing_quote: BowmarkCapability_cable_railing_quote.Unit;
   cars: BowmarkCapability_cars.Unit;