Arcadible Function SDK
What a game's function calls: the server code Arcadible runs beside your game, named in arcadible.toml's [function] table. The package is @arcadible/function-sdk. With it, a function gets these from Arcadible, with no key and nothing to set up:
- Who sent a request, which Arcadible checked before your code ran.
- Players' names.
- Values: the game's data kept on Arcadible, which a server of your own reaches too.
- Wires: live messages to the game's players, sent as the server.
It runs in a function alone, on Arcadible or under arc serve. A server of your own uses the Arcadible Server 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, values, wires, isArcadibleError } from "@arcadible/function-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 | Who sent a request, and players' names, a module of its own |
values | The game's values, a module of its own |
wires | Live messages to the game's players |
isArcadibleError | Whether what you caught is an ArcadibleError |
Including it
npm install @arcadible/function-sdk
arc build bundles it with your function. It has no dependencies, reads no environment variable, and takes no key: Arcadible stands in for one.
import { players, values } from "@arcadible/function-sdk";
export default {
async fetch(request: Request): Promise<Response> {
const me = players.primary(request);
if (me === null || me.guest) return Response.json({ code: "guest" }, { status: 403 });
const [best] = await values.read([{ scope: me, key: "best" }]);
return Response.json({ best: best?.value ?? 0 });
},
};
Codes
Every call that fails rejects with an ArcadibleError, and nothing else. Act on its code, a string such as "conflict", 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 | Something a call doesn't take, a wire that isn't the game's, or a call made outside a function | no | Pass what the call takes |
unauthorized | A call made over a minute after its request came, which Arcadible no longer takes | no | Call while the request is answered |
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 function 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, a call's values together, or a wire's message, 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 | Answer without it, and try again once it renews |
busy | Too many calls to Arcadible 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 | 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. Arcadible takes a function's calls for a minute from when its request came, so a call left running after the function answered, such as one in ctx.waitUntil(), may fail past it. The limits are in Limits.
A fetch of your function's own to a host that function.outbound_hosts doesn't name isn't sent: it answers 403, with { "code": "host_undeclared", "message": "…" } saying which host, as a Response, not an error. Add the host to outbound_hosts.
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).
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 function's code and a library it uses each bundle 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, and PageOptions, and each module's own, Players, Values, and Wires, so your code's dependencies can be typed from the SDK and change when it does:
import type { Values } from "@arcadible/function-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 runs your function beside your game, as Arcadible does, and every call goes to arc serve itself: nothing reaches Arcadible. It differs in three ways:
players.readknows only the players who've played in this run.- The limits on how often your function is called, and calls Arcadible, aren't enforced.
- A call isn't held to a minute from its request.