@bowmark/web 1.23.0 → 1.24.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: 33a70781b68188bc68feb315e91e0c61cb56ecb49e10d82f223e4feb9d6b3399
-// 50 capabilities, 418 providers, 1121 typed functions, 20 refused.
+// Manifest version: 0d8827f7a99d497bd9259feb3f5bd13b057c5a6793454c543b7ac1b7c784b9e2
+// 50 capabilities, 419 providers, 1129 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
@@ -225,9 +225,10 @@ type CallOptions = {
     /**
      * 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`.
+     * turn spends real vendor money, charged to the account. Your account may hold up to 3
+     * concurrent sessions; call `list()` before starting if looping over multiple tasks. 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`. Always `stop()` a session when done.
      */
     start(options: StartBrowserAgentOptions): Promise<StartBrowserAgentResult>;
 
@@ -247,15 +248,17 @@ type CallOptions = {
     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.
+     * Stops the agent and shuts its browser; the watch link stops working. Always `stop()` a
+     * session when you are done with it — an open browser keeps costing money until Bowmark closes
+     * it after 20 idle minutes, and the session counts against your 3-session concurrent limit
+     * even while idle.
      */
     stop(id: string): Promise<StopBrowserAgentResult>;
 
     /**
-     * Lists this account's browser agent sessions, open ones by default — how to recover an id you
-     * lost.
+     * Lists this account's browser agent sessions (open ones by default) — check how many you're
+     * holding before starting a new one, especially when looping. Idle sessions count against the
+     * 3-session concurrent limit until you `stop()` them.
      */
     list(options?: ListBrowserAgentsOptions): Promise<ListBrowserAgentsResult>;
 
@@ -5204,6 +5207,36 @@ interface AppleRefurbishedCatalog {
   category: "mac" | "ipad" | "iphone" | "watch" | "appletv" | "homepod" | "airpods" | "accessories";
   listings: AppleRefurbishedListing[];
 }
+interface AppleAccessoryListing {
+  partNumber: string;
+  name: string;
+  price: number | null;
+  priceCurrency: string | null;
+  url: string;
+  image: string | null;
+}
+interface AppleAccessoryCatalog {
+  category:
+    | "cases-protection"
+    | "chargers-adapters"
+    | "headphones-speakers"
+    | "drives-storage"
+    | "mice-keyboards"
+    | "gaming"
+    | "office"
+    | "travel-essentials"
+    | "college-essentials"
+    | "software"
+    | "homekit"
+    | "content-creation"
+    | "health-fitness"
+    | "new-arrivals"
+    | "made-by-apple"
+    | "accessibility";
+  page: number;
+  hasMore: boolean;
+  listings: AppleAccessoryListing[];
+}
 interface AppleTradeInEstimate {
   device: string;
   upToUsd: number;
@@ -5429,6 +5462,15 @@ interface AppleCompareModels {
      */
     listRefurbished(category: "mac" | "ipad" | "iphone" | "watch" | "appletv" | "homepod" | "airpods" | "accessories"): Promise<AppleRefurbishedCatalog>;
 
+    /**
+     * Everything Apple sells that is not a device, browsable by the sixteen categories apple.com's
+     * own accessories store uses — cases, chargers, headphones, drives, keyboards and the rest —
+     * each listing with its real name, current price and the part number that resolves it straight
+     * through getProductByPartNumber. Apple paginates this store server-side (up to 30 listings a
+     * page); `hasMore` says whether another page exists, since apple.com publishes no total count.
+     */
+    listAccessories(category: "cases-protection" | "chargers-adapters" | "headphones-speakers" | "drives-storage" | "mice-keyboards" | "gaming" | "office" | "travel-essentials" | "college-essentials" | "software" | "homekit" | "content-creation" | "health-fitness" | "new-arrivals" | "made-by-apple" | "accessibility", page?: number): Promise<AppleAccessoryCatalog>;
+
     /**
      * Reads apple.com's own trade-in value table and returns the CEILING ("up to $X")
      * cash-or-credit estimate it publishes for one device — a human name ("iPhone 14 Pro") or the
@@ -7607,8 +7649,11 @@ interface FormField {
     /** List BionicPO inquiry and service categories from the inquiry-services page. */
     listInquiryServices(): Promise<{ services: InquiryService[]; warnings: string[] }>;
 
-    /** Get a BionicPO inquiry service's form fields and details. */
-    getInquiryServiceDetails(serviceName: string): Promise<ServiceDetails>;
+    /**
+     * Look up one BionicPO inquiry service by name or id and return the site's own description for
+     * it.
+     */
+    getInquiryServiceDetails(service: string): Promise<ServiceDetails>;
   }
 }
 
@@ -16976,14 +17021,19 @@ interface GoogleNewsFullCoverage {
 
     /**
      * Everything Google News has indexed from one publisher — `publisher` is a domain like
-     * "reuters.com" or "apnews.com" — newest first, optionally narrowed with `query` the same way
-     * `searchNews` takes one. Built on the search door with a `site:` filter
+     * "reuters.com" or a name like "Reuters" — newest first, optionally narrowed with `query` the
+     * same way `searchNews` takes one. Built on the search door with a `site:` filter
      * (`/rss/search?q=site:<publisher> <query>`), NOT on the route that looks like its own:
      * `/rss/headlines/section/publication/<NAME>` answers 200 with the Top stories feed
      * byte-for-byte for a name it cannot resolve, so it would look like it worked and be wrong for
-     * every publisher. Measured 2026-09-15: `site:reuters.com tesla` returned 100 items of which
-     * 100 carried a `<source>` domain on `reuters.com`. `locale` — `{ hl, gl, ceid }` — asks for
-     * another country/language edition; omitted, the US English one.
+     * every publisher. `site:` takes a DOMAIN, so a NAME is resolved to one through the search
+     * door first (the host dominating that name's own search results) rather than passed straight
+     * to `site:`, where it is mis-parsed as a TLD plus a keyword (measured 2026-09-17: "Al
+     * Jazeera" returned 100 rows, all from the .al ccTLD) — a name the door cannot resolve is
+     * refused rather than answered with the wrong newsroom. Measured 2026-09-15: `site:reuters.com
+     * tesla` returned 100 items of which 100 carried a `<source>` domain on `reuters.com`.
+     * `locale` — `{ hl, gl, ceid }` — asks for another country/language edition; omitted, the US
+     * English one.
      */
     listPublisherHeadlines(publisher: string, query?: string, locale?: GoogleNewsLocaleArg): Promise<GoogleNewsPublisherHeadlines>;
 
@@ -19098,6 +19148,124 @@ interface HellotendService {
   }
 }
 
+declare namespace BowmarkProvider_higgsfield {
+  // ── Higgsfield — the unit's own declarations, verbatim ──
+interface higgsfieldModel {
+  id: string;
+  path: string;
+  kind: "image" | "video";
+  needsInputImage: boolean;
+  family: string;
+  measuredUsd: number;
+}
+
+interface higgsfieldEstimate {
+  model: string;
+  credits: number;
+  usd: number;
+  discountUsd: number | null;
+}
+
+interface higgsfieldRequest {
+  requestId: string;
+  status: "queued" | "in_progress" | "completed" | "failed" | "nsfw" | "canceled";
+  imageUrls: string[];
+  videoUrl: string | null;
+  error: string | null;
+  statusUrl: string | null;
+  cancelUrl: string | null;
+}
+
+interface higgsfieldGeneration extends higgsfieldRequest {
+  model: string;
+  estimate: higgsfieldEstimate;
+  settled: boolean;
+  files: higgsfieldSavedFile[];   // the same media, kept in YOUR account — Higgsfield's own links expire
+  warnings: string[];
+}
+
+// Bowmark's own saved-file handle (`SavedFile`), spelled out here because the
+// published surface has to stand alone. Manage these with `bowmark.files.*`;
+// `url` is presigned and `bowmark.files.url(id)` mints a fresh one.
+interface higgsfieldSavedFile {
+  id: string;
+  name: string;
+  contentType: string;
+  bytes: number;
+  url: string;
+  expiresAt: string;
+}
+
+  /**
+   * Higgsfield's own documented generation API — turns a text prompt (or a prompt plus an input
+   * image) into images or video across 25 models live on this account, including Kling 2.5
+   * Turbo, MiniMax Hailuo 02/2.3, WAN 2.5 and Higgsfield's own Soul and DoP. Every call is
+   * quoted by Higgsfield before it is submitted, and only a generation watched to completion is
+   * charged.
+   */
+  interface Unit {
+    /**
+     * Lists every generation model Bowmark's Higgsfield account can actually call, with what each
+     * one produces, whether it needs an input image, and what one call was measured to cost.
+     * Measured against the live API on 2026-09-16 by estimating all 48 endpoints Higgsfield's
+     * OpenAPI document publishes: 25 answered, and the rest refused as model_not_found,
+     * model_blocked or model_disabled — so this is the callable set, not the documented one. Takes
+     * no arguments and makes no request.
+     */
+    listModels(): Promise<higgsfieldModel[]>;
+
+    /**
+     * Asks Higgsfield what one generation will cost, for exactly the parameters you would submit,
+     * before submitting it — the vendor's own credit and US-dollar figure for this account, with
+     * any discount already applied. Generates nothing, produces no media and costs nothing.
+     * `model` defaults to `soul`. This is the same quote the generate functions take internally
+     * and charge from, so it is the honest answer to "what am I about to spend".
+     */
+    estimateCost(args: { prompt: string; model?: string; [param: string]: unknown }): Promise<higgsfieldEstimate>;
+
+    /**
+     * Generates one or more images from a text prompt and waits for them, returning the finished
+     * image URLs together with what Higgsfield quoted. `model` defaults to `soul` ($0.094
+     * measured); `listModels()` has the rest. Any other key — `aspect_ratio`, `num_images`,
+     * `input_images`, `output_format` — is passed to Higgsfield untouched, since each model takes
+     * its own. Waits up to `waitMs` (default 120000) for a terminal state; pass 0 to submit and
+     * return the handle immediately. **The finished images are copied into your Bowmark account
+     * automatically and come back on `files` — use those URLs, not `imageUrls`.** Higgsfield
+     * deletes its own copy after about seven days; a file in your account is yours until you
+     * delete it, and costs storage while you keep it. Pass `save: false` to skip the copy and take
+     * the expiring links. Uses Bowmark's Higgsfield key and charges the generation to your
+     * account; send your own key as the `x-bowmark-vendor-key-higgsfield` header instead.
+     */
+    generateImage(args: string | { prompt: string; model?: string; waitMs?: number; save?: boolean; [param: string]: unknown }): Promise<higgsfieldGeneration>;
+
+    /**
+     * Generates a video from a text prompt — or from a prompt plus an input image on the
+     * image-to-video models — and waits for it, returning the finished video URL together with
+     * what Higgsfield quoted. `model` defaults to `hailuo-02-standard` ($0.090 measured, the
+     * cheapest live video model); Kling 2.1 Master is $1.400, so check `listModels()` or
+     * `estimateCost` before reaching for a big one. Any other key (`duration`, `resolution`,
+     * `input_images`) is passed to Higgsfield untouched. Waits up to `waitMs` (default 240000);
+     * pass 0 to submit and poll with `getRequestStatus` yourself. **A call that waits copies the
+     * finished video into your Bowmark account and returns it on `files` — use that URL, not
+     * `videoUrl`**, because Higgsfield deletes its own copy after about seven days. Pass `save:
+     * false` to skip the copy. A call with `waitMs: 0` saves nothing, since nothing has rendered
+     * yet.
+     */
+    generateVideo(args: string | { prompt: string; model?: string; waitMs?: number; save?: boolean; [param: string]: unknown }): Promise<higgsfieldGeneration>;
+
+    /**
+     * Checks one submitted generation by its `requestId` and returns its current state plus any
+     * finished media. Use it after a generate call that returned `settled: false`, which means the
+     * wait ran out while the generation was still running. `status` is Higgsfield's own: `queued`,
+     * `in_progress`, `completed`, `failed`, `nsfw` (refused by moderation — reword the prompt) or
+     * `canceled`. This is a free read and it never charges you, even for a generation it finds
+     * completed — and for the same reason it never copies the media into your account either, so
+     * the URLs it returns are Higgsfield's own and expire after about seven days.
+     */
+    getRequestStatus(args: string | { requestId: string }): Promise<higgsfieldRequest>;
+  }
+}
+
 declare namespace BowmarkProvider_highlandhomes {
   // ── Highland Homes — the unit's own declarations, verbatim ──
 interface HighlandHomesSearchFilter {
@@ -34873,6 +35041,34 @@ interface YoutubeSearchVideo {
   thumbnail: string | null;
 }
 
+interface YoutubeChannelRef {
+  channelId: string;
+  url: string;
+  handle: string | null; // only set when the source we found it through carries one
+  title: string | null;  // only set coming off search; resolve_url gives no title
+  subscriberCountText: string | null;
+  thumbnail: string | null;
+}
+
+interface YoutubeVideo {
+  videoId: string;
+  title: string;
+  channel: string;
+  channelId: string;
+  description: string;       // the full watch-page description, not a truncated snippet
+  viewCount: number;
+  likeCount: number | null;  // null when the site itself hides it on this video
+  lengthSeconds: number;
+  publishDate: string | null; // ISO 8601
+  uploadDate: string | null;  // ISO 8601
+  category: string | null;
+  keywords: string[];
+  isLiveNow: boolean;         // live RIGHT NOW
+  isLiveContent: boolean;     // live now, or ever was (stays true for a finished stream's VOD)
+  isUnlisted: boolean;
+  thumbnails: { url: string; width: number; height: number }[];
+}
+
   /**
    * 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;
@@ -34894,6 +35090,26 @@ interface YoutubeSearchVideo {
      * the video has no caption track at all.
      */
     getTranscript(input: { video: string }): Promise<YoutubeTranscript>;
+
+    /**
+     * Resolves a channel `@handle`, a channel/handle URL, or a plain channel name to its canonical
+     * id — the door every other channel function here takes a channelId through. An `@handle` or
+     * URL goes through YouTube's own `navigation/resolve_url` and returns just the id and
+     * canonical URL (no title — that costs a second call, which `getChannel` makes). A plain name
+     * runs a channel-filtered search and returns the first, best-matching channel with its title,
+     * subscriber count and thumbnail. Returns null when nothing resolves — not a real answer to
+     * build a `getChannel` call on.
+     */
+    findChannel(input: { query: string }): Promise<YoutubeChannelRef | null>;
+
+    /**
+     * Everything the watch page says about one video without playing it: title, channel name and
+     * id, full description, view count, like count, length in seconds, publish and upload dates,
+     * category, the uploader's own keywords, every thumbnail size, and whether it is live now, was
+     * ever live, or is unlisted. `video` is a bare 11-character video id or any
+     * watch/shorts/embed/live/youtu.be URL, exactly as `getTranscript` takes it.
+     */
+    getVideo(input: { video: string }): Promise<YoutubeVideo>;
   }
 }
 
@@ -36004,6 +36220,7 @@ interface BowmarkProviders {
   heatherwood: BowmarkProvider_heatherwood.Unit;
   hellofresh: BowmarkProvider_hellofresh.Unit;
   hellotend: BowmarkProvider_hellotend.Unit;
+  higgsfield: BowmarkProvider_higgsfield.Unit;
   highlandhomes: BowmarkProvider_highlandhomes.Unit;
   hilton: BowmarkProvider_hilton.Unit;
   historymaker: BowmarkProvider_historymaker.Unit;

package/dist/generated/validators.js

@@ -5,10 +5,10 @@
 // declares no readable argument shape — not an absent one, which is what the
 // guard fails closed on.
 //
-// Manifest version: 33a70781b68188bc68feb315e91e0c61cb56ecb49e10d82f223e4feb9d6b3399
-// 1103 checked, 20 unchecked.
+// Manifest version: 0d8827f7a99d497bd9259feb3f5bd13b057c5a6793454c543b7ac1b7c784b9e2
+// 1111 checked, 20 unchecked.
 export const VALIDATORS = {
-    "version": "33a70781b68188bc68feb315e91e0c61cb56ecb49e10d82f223e4feb9d6b3399",
+    "version": "0d8827f7a99d497bd9259feb3f5bd13b057c5a6793454c543b7ac1b7c784b9e2",
     "units": {
         "booking_links": {
             "defs": {
@@ -5462,6 +5462,88 @@ export const VALIDATORS = {
                         "optional": false
                     }
                 ],
+                "listAccessories": [
+                    {
+                        "name": "category",
+                        "schema": {
+                            "k": "union",
+                            "of": [
+                                {
+                                    "k": "literal",
+                                    "v": "cases-protection"
+                                },
+                                {
+                                    "k": "literal",
+                                    "v": "chargers-adapters"
+                                },
+                                {
+                                    "k": "literal",
+                                    "v": "headphones-speakers"
+                                },
+                                {
+                                    "k": "literal",
+                                    "v": "drives-storage"
+                                },
+                                {
+                                    "k": "literal",
+                                    "v": "mice-keyboards"
+                                },
+                                {
+                                    "k": "literal",
+                                    "v": "gaming"
+                                },
+                                {
+                                    "k": "literal",
+                                    "v": "office"
+                                },
+                                {
+                                    "k": "literal",
+                                    "v": "travel-essentials"
+                                },
+                                {
+                                    "k": "literal",
+                                    "v": "college-essentials"
+                                },
+                                {
+                                    "k": "literal",
+                                    "v": "software"
+                                },
+                                {
+                                    "k": "literal",
+                                    "v": "homekit"
+                                },
+                                {
+                                    "k": "literal",
+                                    "v": "content-creation"
+                                },
+                                {
+                                    "k": "literal",
+                                    "v": "health-fitness"
+                                },
+                                {
+                                    "k": "literal",
+                                    "v": "new-arrivals"
+                                },
+                                {
+                                    "k": "literal",
+                                    "v": "made-by-apple"
+                                },
+                                {
+                                    "k": "literal",
+                                    "v": "accessibility"
+                                }
+                            ]
+                        },
+                        "optional": false
+                    },
+                    {
+                        "name": "page",
+                        "schema": {
+                            "k": "number"
+                        },
+                        "optional": true
+                    }
+                ],
                 "getTradeInEstimate": [
                     {
                         "name": "model",
@@ -7325,7 +7407,7 @@ export const VALIDATORS = {
                 "listInquiryServices": [],
                 "getInquiryServiceDetails": [
                     {
-                        "name": "serviceName",
+                        "name": "service",
                         "schema": {
                             "k": "string"
                         },
@@ -16837,6 +16919,166 @@ export const VALIDATORS = {
                 ]
             }
         },
+        "providers.higgsfield": {
+            "defs": {},
+            "functions": {
+                "listModels": [],
+                "estimateCost": [
+                    {
+                        "name": "args",
+                        "schema": {
+                            "k": "object",
+                            "props": [
+                                {
+                                    "name": "prompt",
+                                    "schema": {
+                                        "k": "string"
+                                    },
+                                    "optional": false
+                                },
+                                {
+                                    "name": "model",
+                                    "schema": {
+                                        "k": "string"
+                                    },
+                                    "optional": true
+                                }
+                            ],
+                            "index": {
+                                "k": "any"
+                            }
+                        },
+                        "optional": false
+                    }
+                ],
+                "generateImage": [
+                    {
+                        "name": "args",
+                        "schema": {
+                            "k": "union",
+                            "of": [
+                                {
+                                    "k": "string"
+                                },
+                                {
+                                    "k": "object",
+                                    "props": [
+                                        {
+                                            "name": "prompt",
+                                            "schema": {
+                                                "k": "string"
+                                            },
+                                            "optional": false
+                                        },
+                                        {
+                                            "name": "model",
+                                            "schema": {
+                                                "k": "string"
+                                            },
+                                            "optional": true
+                                        },
+                                        {
+                                            "name": "waitMs",
+                                            "schema": {
+                                                "k": "number"
+                                            },
+                                            "optional": true
+                                        },
+                                        {
+                                            "name": "save",
+                                            "schema": {
+                                                "k": "boolean"
+                                            },
+                                            "optional": true
+                                        }
+                                    ],
+                                    "index": {
+                                        "k": "any"
+                                    }
+                                }
+                            ]
+                        },
+                        "optional": false
+                    }
+                ],
+                "generateVideo": [
+                    {
+                        "name": "args",
+                        "schema": {
+                            "k": "union",
+                            "of": [
+                                {
+                                    "k": "string"
+                                },
+                                {
+                                    "k": "object",
+                                    "props": [
+                                        {
+                                            "name": "prompt",
+                                            "schema": {
+                                                "k": "string"
+                                            },
+                                            "optional": false
+                                        },
+                                        {
+                                            "name": "model",
+                                            "schema": {
+                                                "k": "string"
+                                            },
+                                            "optional": true
+                                        },
+                                        {
+                                            "name": "waitMs",
+                                            "schema": {
+                                                "k": "number"
+                                            },
+                                            "optional": true
+                                        },
+                                        {
+                                            "name": "save",
+                                            "schema": {
+                                                "k": "boolean"
+                                            },
+                                            "optional": true
+                                        }
+                                    ],
+                                    "index": {
+                                        "k": "any"
+                                    }
+                                }
+                            ]
+                        },
+                        "optional": false
+                    }
+                ],
+                "getRequestStatus": [
+                    {
+                        "name": "args",
+                        "schema": {
+                            "k": "union",
+                            "of": [
+                                {
+                                    "k": "string"
+                                },
+                                {
+                                    "k": "object",
+                                    "props": [
+                                        {
+                                            "name": "requestId",
+                                            "schema": {
+                                                "k": "string"
+                                            },
+                                            "optional": false
+                                        }
+                                    ]
+                                }
+                            ]
+                        },
+                        "optional": false
+                    }
+                ]
+            }
+        },
         "providers.highlandhomes": {
             "defs": {
                 "HighlandHomesSearchFilter": {
@@ -32994,6 +33236,42 @@ export const VALIDATORS = {
                         },
                         "optional": false
                     }
+                ],
+                "findChannel": [
+                    {
+                        "name": "input",
+                        "schema": {
+                            "k": "object",
+                            "props": [
+                                {
+                                    "name": "query",
+                                    "schema": {
+                                        "k": "string"
+                                    },
+                                    "optional": false
+                                }
+                            ]
+                        },
+                        "optional": false
+                    }
+                ],
+                "getVideo": [
+                    {
+                        "name": "input",
+                        "schema": {
+                            "k": "object",
+                            "props": [
+                                {
+                                    "name": "video",
+                                    "schema": {
+                                        "k": "string"
+                                    },
+                                    "optional": false
+                                }
+                            ]
+                        },
+                        "optional": false
+                    }
                 ]
             }
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bowmark/web",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "type": "module",
   "description": "The public client for the Bowmark capability library — real TypeScript for the whole bowmark.* surface, with no Bowmark source on the caller's disk. ZERO runtime dependencies, deliberately and permanently.",
   "license": "MIT",