Node library
Call any Bowmark site or capability from your own TypeScript or JavaScript with @bowmark/web.
Install
npm i @bowmark/webCreate a key on the keys page and set it in your environment. Every call reads it.
export BOWMARK_API_KEY=bmk_...Top-level await needs ESM: add "type": "module" to package.json, or name the file
app.mts.
Call one function
bowmark reaches every function in the library by its path. Each
site page lists a site's functions with their arguments and return types.
import { bowmark } from "@bowmark/web";
const { results } = await bowmark.providers.steam.searchGames({ query: "portal" });
const { game } = await bowmark.providers.steam.getGameDetails({ appid: results[0].appid });
console.log(game.name, game.price);Capabilities that search several sites at once sit at the top level, for example
bowmark.flights.search(...). Ask get_library to find them.
Several calls in one session
Two bowmark calls get two separate sessions. When a flow has a second step that depends on
the first (a cart, a sign-in), use session() so every call shares one.
import { session } from "@bowmark/web";
const itemCount = await session(async (bm) => {
const found = await bm.providers.gymshark.search({ query: "hoodie" });
await bm.providers.gymshark.addToCart({ variantId: found.products[0].variantId });
return (await bm.providers.gymshark.getCart()).itemCount;
});The session closes when the callback returns or throws.
Run a script
run() sends a whole script and returns the response envelope instead of
throwing. Use it for read.page and browser_agent, which work only inside a script.
import { run } from "@bowmark/web";
const envelope = await run(`return await bowmark.read.page("https://example.com")`);
if (!envelope.ok) throw new Error(envelope.error ?? "run failed");
console.log(envelope.result.title);Sites that need a sign-in
A call to a signed-in function pauses until the person signs in. It throws
BowmarkNeedsUserError with a link. Open it, sign in, and call again: the session is still
open. See Signed-in sites.
import { BowmarkNeedsUserError, session } from "@bowmark/web";
await session(async (bm) => {
try {
return await bm.providers.steam.viewFriends({});
} catch (err) {
if (err instanceof BowmarkNeedsUserError) console.log("Sign in:", err.handoff?.url);
throw err;
}
});Errors
| Error | When | What to do |
|---|---|---|
BowmarkNeedsUserError | A call is waiting for a sign-in | Open err.handoff.url, then call again |
BowmarkError, code: "no_api_key" | No key was found | Set BOWMARK_API_KEY or pass apiKey |
BowmarkError, code: "bad_argument" | An argument does not match the function | Fix it; the message names the field |
BowmarkError, code: "unknown_function" | The function is not in this version | Check the name, or upgrade the package |
BowmarkError, any other code | The call failed | Branch on code; message explains it |
Options
Every entry point takes { apiKey, baseUrl, headers, signal, onLog }. Without apiKey it
reads BOWMARK_API_KEY at call time.
No Node? Use the Python library or the HTTP API.