# Node library (/docs/node)

## Install

```sh
npm i @bowmark/web
```

Create a key on the [keys page](https://bowmark.ai/dashboard/keys) and set it in your
environment. Every call reads it.

```sh
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](/sites) lists a site's functions with their arguments and return types.

```ts
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`](/docs/scripting) 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.

```ts
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](/docs/responses) instead of
throwing. Use it for `read.page` and `browser_agent`, which work only inside a script.

```ts
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](/docs/signed-in-sites).

```ts
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](/docs/python) or the [HTTP API](/docs/http-api).
