SDK reference

Every call, property, result, timing and limit in the SDK, in one place.

Calls

Every call resolves; ok tells the 2 shapes apart.

Call	`ok: true`	`ok: false`
`ready()`	The environment: `velven`, `site` or `local`	Never; resolves once and never rejects
`signIn(options?)`	`{ user, token, expiresAt }`	`{ error }`: sign-in codes
`onAuth(listener)`	A function that removes the listener	Never
`scores.submit(value, options?)`	`{ board, rank, value, total, improved }`	`{ error, retryAfter? }`: score codes
`scores.top(options?)`	`{ board, trust, info, rows }`	`{ error }`: score codes
`scores.around(options?)`	`{ board, trust, info, rows }`	`{ error }`: score codes
`scores.mine(options?)`	`{ board, trust, info, row }`, `row` null before a first score	`{ error }`: score codes
`scores.read(requests)`	An array: each read's own answer, in order (Read several boards)	Per read, never for the whole call; throws a `TypeError` for a mistake in any read
`data.getItem(key)`	A string, or null	Never; throws before `ready()`
`data.setItem(key, value)`	Nothing	Never; throws before `ready()`, a `RangeError` past 1 MB, a `TypeError` for `__proto__`
`data.removeItem(key)`, `data.clear()`	Nothing	Never; throws before `ready()`
`game.start()`, `game.stop()`	Nothing	Never
`onMute(handler)`	A function that removes the handler	Never; throws a `TypeError` when `handler` is not a function
`achievements.unlock(id)`	`{ achievement, title, unlocked, points, total }`	`{ error }`: achievement codes
`achievements.list()`	`{ achievements }`	`{ error }`: achievement codes
`stats.set(id, n)`, `stats.add(id, n)`	`{ stat, value, unlocked }`	`{ error }`: stat codes
`stats.get(id)`	`{ stat, value }`	`{ error }`: stat codes
`onAchievement(handler)`	A function that removes the handler	Never
`content.upload(item)`	`{ item }`	`{ error }`: content codes
`content.list(options?)`	`{ items, cursor }`	`{ error }`: content codes
`content.download(id)`	`{ item, data }`	`{ error }`: content codes
`content.remove(id)`, `content.report(id, reason)`	`{}`	`{ error }`: content codes
`rooms.create(options?)`, `rooms.join(id)`	`{ room }`	`{ error }`: room codes
`rooms.list()`	`{ rooms }`	`{ error }`: room codes
`rooms.leave()`, `kick`, `setData`, `send`, `chat`	`{}`, at once	`{ error }`: `not_in_room`, `not_host`, `too_large`, `too_long`
`rooms.invite(handle)`, `rooms.report(chat, reason)`	`{}`	`{ error }`: room codes
`rooms.inviteLink()`	A link that joins the room, or null	Never
`rooms.on(event, handler)`	A function that removes the handler	Never
`presence.set({ status })`	`{}`	`{ error }`: presence codes

Call: ready()
ok: true: The environment: velven, site or local
ok: false: Never; resolves once and never rejects

Call: signIn(options?)
ok: true: { user, token, expiresAt }
ok: false: { error }: sign-in codes

Call: onAuth(listener)
ok: true: A function that removes the listener
ok: false: Never

Call: scores.submit(value, options?)
ok: true: { board, rank, value, total, improved }
ok: false: { error, retryAfter? }: score codes

Call: scores.top(options?)
ok: true: { board, trust, info, rows }
ok: false: { error }: score codes

Call: scores.around(options?)
ok: true: { board, trust, info, rows }
ok: false: { error }: score codes

Call: scores.mine(options?)
ok: true: { board, trust, info, row }, row null before a first score
ok: false: { error }: score codes

Call: scores.read(requests)
ok: true: An array: each read's own answer, in order (Read several boards)
ok: false: Per read, never for the whole call; throws a TypeError for a mistake in any read

Call: data.getItem(key)
ok: true: A string, or null
ok: false: Never; throws before ready()

Call: data.setItem(key, value)
ok: true: Nothing
ok: false: Never; throws before ready(), a RangeError past 1 MB, a TypeError for __proto__

Call: data.removeItem(key), data.clear()
ok: true: Nothing
ok: false: Never; throws before ready()

Call: game.start(), game.stop()
ok: true: Nothing
ok: false: Never

Call: onMute(handler)
ok: true: A function that removes the handler
ok: false: Never; throws a TypeError when handler is not a function

Call: achievements.unlock(id)
ok: true: { achievement, title, unlocked, points, total }
ok: false: { error }: achievement codes

Call: achievements.list()
ok: true: { achievements }
ok: false: { error }: achievement codes

Call: stats.set(id, n), stats.add(id, n)
ok: true: { stat, value, unlocked }
ok: false: { error }: stat codes

Call: stats.get(id)
ok: true: { stat, value }
ok: false: { error }: stat codes

Call: onAchievement(handler)
ok: true: A function that removes the handler
ok: false: Never

Call: content.upload(item)
ok: true: { item }
ok: false: { error }: content codes

Call: content.list(options?)
ok: true: { items, cursor }
ok: false: { error }: content codes

Call: content.download(id)
ok: true: { item, data }
ok: false: { error }: content codes

Call: content.remove(id), content.report(id, reason)
ok: true: {}
ok: false: { error }: content codes

Call: rooms.create(options?), rooms.join(id)
ok: true: { room }
ok: false: { error }: room codes

Call: rooms.list()
ok: true: { rooms }
ok: false: { error }: room codes

Call: rooms.leave(), kick, setData, send, chat
ok: true: {}, at once
ok: false: { error }: not_in_room, not_host, too_large, too_long

Call: rooms.invite(handle), rooms.report(chat, reason)
ok: true: {}
ok: false: { error }: room codes

Call: rooms.inviteLink()
ok: true: A link that joins the room, or null
ok: false: Never

Call: rooms.on(event, handler)
ok: true: A function that removes the handler
ok: false: Never

Call: presence.set({ status })
ok: true: {}
ok: false: { error }: presence codes

Every call added in 0.7.0 answers unavailable on a site, on a space not published with a verified owner, and on an older Velven page that does not know it yet. Achievements and stats, Player content and Rooms and presence have the guides.

Properties

These properties are on the Velven object:

Velven.environmentvelven, site, local or null: Where the page is running; null before ready() settles.
Velven.user{ id, handle, avatar } or null: The signed-in player, for display.
Velven.versionString: The SDK's release, such as 0.3.0. Absent before 0.3.0.
Velven.space{ id, slug } or null: The space the page runs in, inside Velven; null elsewhere. id is the space claim of the player's token.
Velven.sandboxtrue or false: true in a preview or velven dev, where everything goes to the space's sandbox. From 0.7.0.
Velven.rooms.currentA room, or null: The room the player is in. From 0.7.0.

Options

Set on the script tag, or passed to createVelven from the npm package:

data-redirectredirect: true: Sends a page opened directly to its Velven page. See Send visitors to your Velven page. From 0.6.0.
data-probe-timeout="3000"probeTimeoutMs: 3000: How long a frame waits for Velven before it settles on site, in milliseconds: 3 to 60 seconds, 7 by default. From 0.3.0.
data-toasts="false"toasts: false: Velven draws no toast for an unlock: your space draws its own from onAchievement. From 0.7.0.

Server helpers

From @velven/sdk/server, for Node 20 and later, Deno, Bun and Cloudflare Workers:

verifyToken(token, { audience, space? }): Checks a player's token. Answers { ok: true, user, space, expiresAt }, or { ok: false, error } with invalid_token, expired_token, wrong_space or unavailable.
postScore({ secret, token, value, requestId, board?, meta?, contentId? }): Posts a score to a server board. Answers as the scores endpoint does. Gives up after 10 seconds.
unlockAchievement({ secret, token, achievement }): Unlocks an achievement, trusted. Answers { ok: true, achievement, unlocked, total }. See Unlock achievements from your server. From 0.7.0.
setStat({ secret, token, stat, value, mode? }): Sets (mode set, the default) or adds to (add) a stat. Answers { ok: true, stat, value, unlocked }. From 0.7.0.

verifyToken also answers sandbox: true for a token made in a preview or velven dev.

Timing

Most calls answer in well under a second. These are the longest waits:

ready() in a top-level window resolves at once.
In a frame, ready() first waits for the Velven page for up to 7 seconds, or your data-probe-timeout.
On a claimed space, ready() then waits up to 7 more seconds for the first silent sign-in check, and up to 7 more for the save.
With the default wait, ready() never takes longer than 21 seconds, and usually under 1.
The token lives an hour. The SDK asks for a new one when under a minute is left.
The Velven page closes a card left open for 10 minutes and answers signed_out. A score call waits 30 seconds.
A signed-in player's save is sent to Velven at most every 5 seconds.

Limits

Past these limits a call is refused, never queued:

10 boards per space. A board key is 1 to 32 lowercase letters, digits, - or _.
meta: up to 1 KB of JSON per submission.
A save: up to 1 MB as JSON per player per space.
Per space page: 40 submissions, 60 reads (top, around and mine together, each read of a scores.read counting as 1) and 12 sign-in requests a minute, each counted apart. Past any of them, the call answers rate_limited without a request; a scores.read that does not fit is refused whole.
Per space page: 30 changes of game.start() and game.stop() a minute. The Velven page ignores more until the minute clears.
Per account, across every space open: 60 submissions and 60 token requests a minute. Per address: 120 reads a minute, each read of a scores.read counting as 1.
Per space page: 120 achievement and stat calls, 60 content calls and 60 room and presence calls a minute. Per account: 60 unlocks, 120 stat writes, 30 presence lines and 30 room passes a minute, 60 uploads and 30 rooms opened an hour.
Content: 5 MB an item, 50 MB per player per space. Rooms: 2 to 16 players, 16 KB a message, 30 messages a second, 500 characters a chat line, 64 KB of room data. A presence line: 80 characters.

Calls#

Properties#

Options#

Server helpers#

Timing#

Limits#