Skip to main content

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​

MemberDescription
playersPlayers' names, and who deleted their account, a module of its own
ticketsChecks the tickets your game sends, a module of its own
valuesThe game's values, a module of its own
isArcadibleErrorWhether 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:

VariableValueNeeded for
ARCADIBLE_KEYOne of your game's keys. A key is for one game and one channelplayers and values
ARCADIBLE_SERVEThe address arc serve prints, in development onlyUnder arc serve
  • tickets.check needs 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, players and values fail with invalid, and nothing is sent. With one Arcadible doesn't take, revoked or not a key, they fail with unauthorized.
  • On Cloudflare Workers, turn on the nodejs_compat flag, with a compatibility date from 2025-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.

FieldValue
codeWhat failed. Arcadible's own pass through as it said them, so a newer Arcadible may answer with one your copy doesn't know
retryWhether to try again: "yes", the same call after a moment; "later", once something changes; "no", not as it is
conflictsOn a conflict only: the items whose revision had moved on (Values)
CodeMeansretryWhat to do
invalidNot a ticket for this server, game, and channel; no key; or something a call doesn't takenoRefuse the request; set ARCADIBLE_KEY; pass what the call takes
expiredA ticket that was good, and isn't any morelaterHave your game get another ticket
unauthorizedA key Arcadible doesn't take: revoked, or not onenoSet ARCADIBLE_KEY to a key of the game's
too_manyMore players, or more items, than a call takesnoAsk for fewer at once
deniedArcadible doesn't allow it: writing the developer's values, or a player not yoursnoWrite to a scope a server writes
conflictA value was written since the revision the call named. Nothing was writtenlaterRead the value again, then write
too_largeA value, or a call's values together, past what one may benoKeep less in one value, or in one call
fullThe scope's storage is used uplaterRemove values first
limit_reachedAn allowance is spent, until its window renewslaterTry again once it renews
busyToo many calls for the game in a minuteyesSlow down, and try again
unavailableArcadible couldn't be reached in time, answered with a 5xx, or its answer couldn't be read; its keys couldn't be readyesTry again
internalArcadible failed on its own sideyesTry again
not_found, method_not_allowed, not_acceptableA request Arcadible couldn't route or answer: a copy of the SDK too old for ArcadiblenoUpdate the SDK
  • New codes may be added, each with its retry: code that handles retry handles them.
  • A refusal that names no code, such as a proxy's on the way, is read by its status: 403 is denied, 409 conflict, 413 too_large, 429 busy, 507 full, any 5xx unavailable, and any other 4xx invalid.

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 instanceof wouldn'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. isArcadibleError asks the error itself, never its class.
  • In TypeScript, it narrows the error to an ArcadibleError: with a code, to that code; without one, its code stays any string, so a switch over it keeps a default.
  • conflicts is on an error whose code is conflict, and on no other: the items a values call 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 is local, whatever channel names, and none of Arcadible's; players and values ask arc 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.read knows only the players arc serve's tickets named in this run, and players.deleted is 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 while arc serve runs.