Skip to main content

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​

MemberDescription
playersWho sent a request, and players' names, a module of its own
valuesThe game's values, a module of its own
wiresLive messages to the game's players
isArcadibleErrorWhether 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.

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
invalidSomething a call doesn't take, a wire that isn't the game's, or a call made outside a functionnoPass what the call takes
unauthorizedA call made over a minute after its request came, which Arcadible no longer takesnoCall while the request is answered
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 function writes
conflictA value was written since the revision the call named. Nothing was writtenlaterRead the value again, then write
too_largeA value, a call's values together, or a wire's message, 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 renewslaterAnswer without it, and try again once it renews
busyToo many calls to Arcadible in a minuteyesSlow down, and try again
unavailableArcadible couldn't be reached in time, answered with a 5xx, or its answer 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. 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 instanceof wouldn'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. 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, 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.read knows 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.