SDK reference
Every call, property, result, timing and limit in the SDK, in one place.
Calls
Every call resolves; ok tells the two 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 |
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() |
Properties
Velven.environmentvelven,site,localor 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 listing the page runs in, inside Velven; null elsewhere.
idis thespaceclaim of the player's token.
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 }withinvalid_token,expired_token,wrong_spaceorunavailable. postScore({ secret, token, value, requestId, board?, meta? })- Posts a score to a server board. Answers as the scores endpoint does. Gives up after 10 seconds.
Timing
ready()in a top-level window resolves at once.- In a frame,
ready()waits for the Velven page for up to 7 seconds, or yourdata-probe-timeout. On a claimed space it then waits up to 7 more for the first silent sign-in check, and up to 7 more for the save. With the default wait it never takes longer than 21 seconds, and usually under one. - 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
- 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 score calls a minute (
submit,top,aroundandminetogether) and 12 sign-in asks a minute. Past either, the call answersrate_limitedwithout a request. - Per account, across every space open: 60 submissions and 60 token requests a minute. Per address: 120 reads a minute.