Node library

Call any Bowmark site or capability from your own TypeScript or JavaScript with @bowmark/web.

Install

npm i @bowmark/web

Create 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

ErrorWhenWhat to do
BowmarkNeedsUserErrorA call is waiting for a sign-inOpen err.handoff.url, then call again
BowmarkError, code: "no_api_key"No key was foundSet BOWMARK_API_KEY or pass apiKey
BowmarkError, code: "bad_argument"An argument does not match the functionFix it; the message names the field
BowmarkError, code: "unknown_function"The function is not in this versionCheck the name, or upgrade the package
BowmarkError, any other codeThe call failedBranch 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.