Arcadible Server SDK
What a server of your own calls: a server you run for your game, anywhere. The package is @arcadible/server-sdk. With it, your server gets these from Arcadible:
- Tickets checked: proof, signed by Arcadible, that a request comes from your game, and of who's playing.
- Players' names, and who deleted their account, with one of your game's keys.
- Values: the game's data kept on Arcadible, with the same key, which your game's function reaches too.
A game's function, which Arcadible runs, uses the Arcadible Function SDK, and a game the Arcadible SDK.
Every failure says whether to try again. A call that fails rejects with an ArcadibleError: its code says what failed, and its retry what to do about it, "yes", "later", or "no", for every code, including one your copy of the SDK doesn't know.
import { players, tickets, values, isArcadibleError } from "@arcadible/server-sdk";
interface ArcadibleError extends Error {
readonly name: "ArcadibleError";
readonly code: Code | string;
readonly retry: "yes" | "later" | "no";
readonly conflicts?: readonly Conflict[]; // on a conflict, the items it names
}
function isArcadibleError(error: unknown, code?: string): error is ArcadibleError;
Members
| Member | Description |
|---|---|
players | Players' names, and who deleted their account, a module of its own |
tickets | Checks the tickets your game sends, a module of its own |
values | The game's values, a module of its own |
isArcadibleError | Whether what you caught is an ArcadibleError |
Including it
npm install @arcadible/server-sdk
It has no dependencies, and runs wherever fetch and Web Crypto do: Node 22 and later, Cloudflare Workers, Deno, and Bun. It reads two environment variables, and takes neither as an argument, so neither is ever in your code:
| Variable | Value | Needed for |
|---|---|---|
ARCADIBLE_KEY | One of your game's keys. A key is for one game and one channel | players and values |
ARCADIBLE_SERVE | The address arc serve prints, in development only | Under arc serve |
tickets.checkneeds no key. It checks a ticket against Arcadible's published keys, which it fetches and keeps for as long as Arcadible says, from a minute to a day.- Without
ARCADIBLE_KEY,playersandvaluesfail withinvalid, and nothing is sent. With one Arcadible doesn't take, revoked or not a key, they fail withunauthorized. - On Cloudflare Workers, turn on the
nodejs_compatflag, with a compatibility date from2025-04-01, so your Worker's variables reach the SDK. Checking a ticket needs neither.
Codes
Every call that fails rejects with an ArcadibleError, and nothing else. Act on its code, a string such as "expired", and on its retry for a code you don't handle. Its message is for your logs, and can change.
| Field | Value |
|---|---|
code | What failed. Arcadible's own pass through as it said them, so a newer Arcadible may answer with one your copy doesn't know |
retry | Whether to try again: "yes", the same call after a moment; "later", once something changes; "no", not as it is |
conflicts | On a conflict only: the items whose revision had moved on (Values) |
| Code | Means | retry | What to do |
|---|---|---|---|
invalid | Not a ticket for this server, game, and channel; no key; or something a call doesn't take | no | Refuse the request; set ARCADIBLE_KEY; pass what the call takes |
expired | A ticket that was good, and isn't any more | later | Have your game get another ticket |
unauthorized | A key Arcadible doesn't take: revoked, or not one | no | Set ARCADIBLE_KEY to a key of the game's |
too_many | More players, or more items, than a call takes | no | Ask for fewer at once |
denied | Arcadible doesn't allow it: writing the developer's values, or a player not yours | no | Write to a scope a server writes |
conflict | A value was written since the revision the call named. Nothing was written | later | Read the value again, then write |
too_large | A value, or a call's values together, past what one may be | no | Keep less in one value, or in one call |
full | The scope's storage is used up | later | Remove values first |
limit_reached | An allowance is spent, until its window renews | later | Try again once it renews |
busy | Too many calls for the game in a minute | yes | Slow down, and try again |
unavailable | Arcadible couldn't be reached in time, answered with a 5xx, or its answer couldn't be read; its keys couldn't be read | yes | Try again |
internal | Arcadible failed on its own side | yes | Try again |
not_found, method_not_allowed, not_acceptable | A request Arcadible couldn't route or answer: a copy of the SDK too old for Arcadible | no | Update the SDK |
- New codes may be added, each with its
retry: code that handlesretryhandles them. - A refusal that names no code, such as a proxy's on the way, is read by its status:
403isdenied,409conflict,413too_large,429busy,507full, any5xxunavailable, and any other4xxinvalid.
A call waits up to 15 seconds for Arcadible, then fails with unavailable; tickets.check waits up to 10 for Arcadible's keys, when it holds none, or none current, or none that signed the ticket. The limits are in Limits.
Every time is the same shape: an ISO 8601 time, in UTC, to the millisecond, such as 2026-11-10T03:12:00.000Z. A property that holds one ends in At (updatedAt, expiresAt).
isArcadibleError(error, code)
isArcadibleError(error: unknown, code?: string): error is ArcadibleError
Whether what you caught is an ArcadibleError, and, with code, one with that code.
try {
await values.write(items);
} catch (err) {
if (!isArcadibleError(err, "conflict")) throw err;
// … err.conflicts: the items someone else wrote first …
}
- It holds across bundles, where
instanceofwouldn't: when your server's code and a library it uses each hold a copy of the SDK, an error made by one isn't an instance of the other's class.isArcadibleErrorasks the error itself, never its class. - In TypeScript, it narrows the error to an
ArcadibleError: with acode, to that code; without one, itscodestays any string, so aswitchover it keeps adefault. conflictsis on an error whose code isconflict, and on no other: the items avaluescall named whose revision had moved on.
Types
The package exports the type of everything it takes and gives, each on its module's page: the shared ones, ArcadibleError, Code, Retry, Conflict, Player, TicketPlayer, Page, PageOptions, and Feed, and each module's own, Players, DeletedPlayer, DeletedOptions, Tickets, and Values, so your code's dependencies can be typed from the SDK and change when it does:
import type { Values } from "@arcadible/server-sdk";
// what this code needs of values, and what a test may stand in for
type Store = Pick<Values, "read" | "write">;
Under arc serve
arc serve makes tickets on your own machine. Once your game lists a server in client.server_origins, or you start it with --player, it prints the variable that points your server at it, under For your server. It's the play page's address, so a server on your own machine, which needs no listing, sets it the same way without the line:
ARCADIBLE_SERVE=http://localhost:4100 node server.js
- With it set, your server takes
arc serve's tickets, whose channel islocal, whateverchannelnames, and none of Arcadible's;playersandvaluesaskarc serve, with no key. - Set it only in development. It must name your own machine: with any other value, every call fails with
invalid, saying so. players.readknows only the playersarc serve's tickets named in this run, andplayers.deletedis always empty.- The limits on how often you call aren't enforced.
- Only a server is answered: a request from a browser, which says the page it's sent from, is refused (
denied), so a page on another site can't change your local values whilearc serveruns.