brewser.js SDK Reference

brewser.js is a tiny, optional SDK that gives your app cloud saves and leaderboards with almost no code. This page is the API index; the Saves & Leaderboards guide has the narrative, worked examples and gotchas.

It's a file you ship, not a runtime API

Brewser makes a point of not having proprietary brewser.* runtime globals — apps stay portable, and if it runs on Brewser it runs in Chrome. brewser.js keeps that promise: it's an ordinary script you bundle with your app, not something the runtime injects. It installs one global, brewser, and degrades gracefully everywhere:

Signed out — save()/load() still work instantly against local storage; cloud sync just waits until the user signs in. leaderboards.list() still works (it's public).
In a desktop browser — the same file runs; the cloud calls hit the same public API.

Ship it and include it before your own script:

<script src="./brewser.js"></script>
<script>
  brewser.save({ level: 3, coins: 120 });
  const data = brewser.load();   // { level: 3, coins: 120 }
</script>

The SDK auto-detects your package id from the catalogue URL (.../apps/{group}/{id}/...). If you're serving from somewhere else, set it: brewser.configure({ packageId: 'com.you.mygame' }).

The only cloud dependency is the user being signed in — nothing here needs a manifest permission.

API at a glance

Synchronous calls return immediately; the rest return Promises. Full semantics, return shapes and gotchas are in Saves & Leaderboards.

Whole-save (local-first, background cloud sync)

Call	Returns	Auth
`brewser.save(data)`	`boolean` — writes local instantly, schedules a cloud push	works signed-out (local); cloud needs sign-in
`brewser.load()`	your data or `null`	—
`brewser.info()`	`{ updatedAt }` or `null`	—
`brewser.pull(opts)`	`Promise<{ ok, data, updatedAt, reason? }>` — the account copy; `{ adopt: true }` also writes it locally	signed in
`brewser.sync()`	`Promise` — force an immediate push	signed in
`brewser.clearLocal()`	`boolean` — clears local only	—
`brewser.canSync()`	`boolean` — is a cross-device sync possible now	—

Records (CRUD over the save blob)

The SDK stamps id, createdAt, updatedAt — you never set those.

Call	Returns
`brewser.put(record)`	`string` (new `id`)
`brewser.get(id)`	record or `null`
`brewser.update(id, changes)`	updated record or `null`
`brewser.remove(id)`	`boolean`
`brewser.list(opts)`	`object[]` — `opts = { sortBy, desc }`

Leaderboards (`brewser.leaderboards`)

Call	Returns	Auth
`.config({ order })`	the leaderboards object — `'desc'` (default) or `'asc'`	—
`.order()`	`'desc' \| 'asc'`	—
`.submit(score, { name })`	`Promise<{ ok, best, rank, updated, onBoard }>` — best-kept	signed in
`.list(n = 10)`	`Promise<{ ok, order, count, top, me? }>`	public
`.aroundMe(n = 3)`	`Promise<{ ok, order, count, top, me, window }>`	signed in
`.me()`	`Promise<{ ok, me }>`	signed in
`.remove()`	`Promise<{ ok }>` — deletes your own entry	signed in

Authenticated calls that fail for lack of sign-in resolve with { ok: false, reason: 'unauth' } rather than throwing. Other failure reasons: 'offline', 'server', 'nothing-local', 'bad-score'.

`brewser.configure(opts)`

Merges options and returns brewser:

Option	Default	Purpose
`packageId`	auto from URL	Your app's save box & board.
`token`	—	Provide an auth token explicitly.
`onSync`	`null`	Sync-status callback: `'pushing' \| 'synced' \| 'offline' \| 'unauth' \| 'error'`.
`apiBase`	`https://brewser.io/wp-json/brewser/v1`	The save/leaderboard API root.
`nsPrefix`	`brewser_save_`	localStorage key prefix.
`pushDebounceMs`	`1500`	Delay before a background push coalesces writes.

Service limits

The cloud API enforces a few limits, worth designing around:

	Limit
Save blob size	256 KB per app, per user
Save writes	~60 per minute per user
Leaderboard	keeps your best; a worse score never lowers you
Leaderboard entries retained	~100 per app
Leaderboard submits	~30 per minute per user
Score range	`\|score\| ≤ 1e12`

Inside the Brewser player your app doesn't manage auth — the SDK finds the token for you, in order:

a token you passed to brewser.configure({ token });
window.__brewserAuthToken(), if the host page exposes it;
a postMessage of { type: 'brewser-token', token } from the Brewser origin.

Signature verification of the token happens on the server — the SDK and runtime never decode it.

Saves & Leaderboards — the full guide with examples.
Accounts & Sign-in — the auth the cloud parts depend on.
Manifest Reference — why these features need nothing declared.

brewser.js SDK Reference

On this page