@zaisma/game-server 1.0.0 → 1.2.0

package/bin/node-parts.js

@@ -12,14 +12,29 @@ const MAXIMUM_PROFILE_COUNT = 10_000;
 /** The format the runner's saved room states are written in. A file with another is dropped, and rooms start fresh. */
 const ROOM_STATES_FORMAT_VERSION_NUMBER = 1;
 
-/** Fetch the public keys a JWKS URL publishes, caching them for an hour (fetched again at once when asked to refresh). */
+/** A refresh asked for by a pass with a key ID not in the cache waits this long after the last fetch, so passes with made-up key IDs can't make this fetch on every hello. */
+const MINIMUM_REFRESH_INTERVAL_MS = 30_000;
+
+/**
+ * Fetch the public keys a JWKS URL publishes, caching them for an hour (fetched again at once when asked to refresh,
+ * at most once in MINIMUM_REFRESH_INTERVAL_MS). A fetch that fails keeps answering with the keys already held.
+ */
 function keysFrom(jwksUrl) {
   let cache = null;
+  let fetchedAtMs = 0;
   return async (isRefreshing = false) => {
-    if (cache && !isRefreshing && Date.now() - cache.fetchedAtMs < KEYS_KEPT_MS) return cache.keys;
-    const response = await fetch(jwksUrl);
-    if (!response.ok) throw new Error(`Couldn't load Zaisma's keys from ${jwksUrl}`);
-    cache = { fetchedAtMs: Date.now(), keys: (await response.json()).keys };
+    const nowMs = Date.now();
+    if (cache && !isRefreshing && nowMs - cache.fetchedAtMs < KEYS_KEPT_MS) return cache.keys;
+    if (cache && isRefreshing && nowMs - fetchedAtMs < MINIMUM_REFRESH_INTERVAL_MS) return cache.keys;
+    fetchedAtMs = nowMs;
+    try {
+      const response = await fetch(jwksUrl);
+      if (!response.ok) throw new Error(`Couldn't load Zaisma's keys from ${jwksUrl}`);
+      cache = { fetchedAtMs: nowMs, keys: (await response.json()).keys };
+    } catch (error) {
+      if (cache) return cache.keys;
+      throw error;
+    }
     return cache.keys;
   };
 }
@@ -273,7 +288,7 @@ export function secretsFromEnvironment() {
   return Object.freeze(Object.fromEntries(Object.entries(process.env).filter(([, environmentValue]) => typeof environmentValue === "string")));
 }
 
-const OPTION_NAMES = ["gameServer", "gameSlug", "port", "origins", "issuerUrl", "loadPassKeys", "loadReceiptKeys", "loadProfile", "database", "secrets", "webhookSigningSecret", "roomStateFile"];
+const OPTION_NAMES = ["gameServer", "gameSlug", "port", "origins", "issuerUrl", "loadPassKeys", "loadReceiptKeys", "loadProfile", "database", "secrets", "webhookSigningSecret", "roomStateFile", "zaismaKey", "developerApiUrl"];
 
 /**
  * Check what startServer was given: unknown options and options of the wrong kind are a GameServerError,
@@ -307,5 +322,7 @@ export function checkedStartServerOptions(given, issuerUrlDefault) {
   if (options.secrets !== undefined && (options.secrets === null || typeof options.secrets !== "object" || Array.isArray(options.secrets))) throw bad("secrets", "an object of secrets", "Give an object of text values by name, like { STRIPE_KEY: \"…\" }.");
   if (options.webhookSigningSecret !== undefined && typeof options.webhookSigningSecret !== "string") throw bad("webhookSigningSecret", "text", "Give the signing_secret of the webhook whose events come to /v1/webhooks, as text.");
   if (options.roomStateFile !== undefined && options.roomStateFile !== null && !isText(options.roomStateFile)) throw bad("roomStateFile", "a file path", "Give a file path as text, like \"zaisma-room-states.sqlite\", or null to keep no states.");
+  if (options.zaismaKey !== undefined && !isText(options.zaismaKey)) throw bad("zaismaKey", "an API key", "Give an API key with purchase_access write for this game as text, or leave it out to use ZAISMA_KEY.");
+  if (options.developerApiUrl !== undefined && (!isText(options.developerApiUrl) || !URL.canParse(options.developerApiUrl))) throw bad("developerApiUrl", "a URL", 'Give the address of Zaisma\'s developer API, like "https://zaisma.com/api/dev".');
   return options;
 }

package/bin/node.d.ts

@@ -27,6 +27,10 @@ export interface StartServerOptions {
   webhookSigningSecret?: string;
   /** Where rooms save their states, so a restart brings matches back. Default zaisma-room-states.sqlite; null keeps none. */
   roomStateFile?: string | null;
+  /** An API key with purchase_access write for this game, which onPurchase and onRefund need. Default: the ZAISMA_KEY environment variable. */
+  zaismaKey?: string;
+  /** Zaisma's developer API, which marks purchases handled. Default: https://zaisma.com/api/dev. */
+  developerApiUrl?: string;
 }
 
 export interface RunningServer {

package/bin/node.js

@@ -23,8 +23,12 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { resolve } from "node:path";
 import { realpathSync } from "node:fs";
 import { BUSY_CLOSE_CODE, ENDED_CLOSE_CODE, ERROR_TEXT, NO_ANSWER_CLOSE_CODE, PASS_ISSUER_URL, PassError, ReceiptError, REMOVED_CLOSE_CODE, REQUEST_ERROR_HTTP_STATUS, REQUEST_LIMITS, ROOM_LIMITS, ROOM_TUNING, WEBHOOK_LIMITS, GameServerError, RoomCore, restoreInfoOf, passesAreFriends, passesHaveBlockBetween, answerRequest, startSchedules, checkRoomData, clientIdle, defineGameServer, errorMessage, isRoomCode, readRequestBody, relay, requestError, runWebhook, tidyRoomInfo, verifyPass, verifyReceipt, verifyWebhook } from "../src/internal.js";
+import { OutsideCallError } from "../src/outside-calls.js";
 import { checkedStartServerOptions, localDatabase, localRoomStates, passKeysFrom, profilesFrom, receiptKeysFrom, secretsFromEnvironment } from "./node-parts.js";
 
+// Code that names OutsideCallError, as Zaisma's sandbox lets it, moves unchanged: nothing here refuses a call, so instanceof is simply false.
+globalThis.OutsideCallError ??= OutsideCallError;
+
 const HELLO_MS = 5000;
 /**
  * How often rooms check on their players (idle, hidden, held seats, players whose time to reconnect ran
@@ -61,13 +65,21 @@ const CATCH_UP_MS = 50;
  * database (room.database and server.database; by default a local file, zaisma-database.sqlite, made the
  * first time the game uses it), secrets (room.secrets and server.secrets; by default this process's
  * environment variables), webhookSigningSecret (the whsec_ secret of the webhook whose events come to
- * /v1/webhooks; by default the ZAISMA_WEBHOOK_SIGNING_SECRET environment variable) and roomStateFile (where
- * rooms save their states, so a restart brings matches back; by default zaisma-room-states.sqlite, null to keep none).
+ * /v1/webhooks; by default the ZAISMA_WEBHOOK_SIGNING_SECRET environment variable), roomStateFile (where
+ * rooms save their states, so a restart brings matches back; by default zaisma-room-states.sqlite, null to keep none),
+ * zaismaKey (an API key with purchase_access write for this game, which onPurchase and onRefund need; by default
+ * the ZAISMA_KEY environment variable) and developerApiUrl (Zaisma's developer API; by default https://zaisma.com/api/dev).
  * Answers { close(), httpServer }: close() saves every room first and finishes once the server has stopped.
  */
 export function startServer(options) {
-  const { gameServer, gameSlug, port: portNumber, origins, issuerUrl, loadPassKeys = passKeysFrom(`${issuerUrl}/.well-known/jwks.json`), loadReceiptKeys = receiptKeysFrom(`${issuerUrl}/.well-known/receipt-jwks.json`), loadProfile = profilesFrom(issuerUrl), database = localDatabase("zaisma-database.sqlite"), secrets = secretsFromEnvironment(), webhookSigningSecret = process.env.ZAISMA_WEBHOOK_SIGNING_SECRET, roomStateFile = "zaisma-room-states.sqlite" } = checkedStartServerOptions(options, PASS_ISSUER_URL);
+  const { gameServer, gameSlug, port: portNumber, origins, issuerUrl, loadPassKeys = passKeysFrom(`${issuerUrl}/.well-known/jwks.json`), loadReceiptKeys = receiptKeysFrom(`${issuerUrl}/.well-known/receipt-jwks.json`), loadProfile = profilesFrom(issuerUrl), database = localDatabase("zaisma-database.sqlite"), secrets = secretsFromEnvironment(), webhookSigningSecret = process.env.ZAISMA_WEBHOOK_SIGNING_SECRET, roomStateFile = "zaisma-room-states.sqlite", zaismaKey = process.env.ZAISMA_KEY, developerApiUrl = "https://zaisma.com/api/dev" } = checkedStartServerOptions(options, PASS_ISSUER_URL);
   const definition = defineGameServer(gameServer);
+  // Exactly once needs Zaisma's record of what's handled: without a key, purchases would come twice, so it doesn't start.
+  if ((definition.onPurchase || definition.onRefund) && !zaismaKey) {
+    const hook = definition.onPurchase ? "onPurchase" : "onRefund";
+    throw new GameServerError("bad_option", "zaismaKey", `${hook} needs zaismaKey, so each purchase is delivered once.`, "Give an API key with purchase_access write for this game as zaismaKey, or set ZAISMA_KEY.");
+  }
+  const purchaseHandling = definition.onPurchase || definition.onRefund ? ownServerPurchaseHandling(gameSlug, zaismaKey, developerApiUrl) : undefined;
   const roomStates = roomStateFile === null ? null : localRoomStates(roomStateFile);
   const stateSaveIntervalMs = (definition.stateSaveIntervalSec ?? ROOM_LIMITS.defaultStateSaveIntervalSec) * 1000;
   // Schedules run while this server is up; one that's down when a run is due misses that run.
@@ -242,6 +254,7 @@ export function startServer(options) {
         database,
         secrets,
         verifyReceipt: receiptClaims,
+        purchaseHandling,
         send: (id, text) => sockets.get(id)?.send(text),
         sendBytes: (id, frame) => sockets.get(id)?.send(frame, { binary: true }),
         isBackedUp: (id) => (sockets.get(id)?.bufferedAmount ?? 0) >= BACKED_UP_SIZE_BYTES,
@@ -438,7 +451,7 @@ export function startServer(options) {
     const helloTimer = setTimeout(() => playerId || refuse("no_hello"), HELLO_MS);
     ws.zaismaSeenAtMs = Date.now();
 
-    ws.on("message", async (received, isBinary) => {
+    const onMessage = async (received, isBinary) => {
       const text = isBinary ? null : received.toString();
       ws.zaismaSeenAtMs = Date.now();
       // Games ping every 25 seconds or so, so a connection that stops answering can be dropped.
@@ -509,6 +522,13 @@ export function startServer(options) {
       playerId = player.id;
       room.waiting = false;
       pace(code, room);
+    };
+    // Whatever a message hits, it ends that connection or that message, never the process and the matches on it.
+    ws.on("message", (received, isBinary) => {
+      onMessage(received, isBinary).catch((error) => {
+        console.error("Couldn't handle a message:", error);
+        if (!playerId) refuse("busy");
+      });
     });
 
     // A frame over the size limit (or a broken one) is an error on this one socket: it closes and the close handler below takes it out, the runner keeps going.
@@ -553,6 +573,83 @@ function stateKeyOf(stateJson, matchPlayers, isKept) {
   return `${isKept ? "kept " : ""}${matchPlayers.map((player) => player.id).join(" ")}\n${stateJson}`;
 }
 
+/** How long this server holds a purchase while its hook runs, as Zaisma rooms do; and how long it remembers one it handled. */
+const HANDLING_LEASE_MS = 60 * 1000;
+const HANDLED_KEPT_MS = 10 * 60 * 1000;
+/** How long this server keeps the game's purchase_delivery before reading it again. */
+const DELIVERY_KEPT_MS = 60 * 1000;
+
+/** A purchase from the developer API, as onPurchase and onRefund get it. */
+function purchaseOf(answered) {
+  return {
+    id: answered.id,
+    itemName: answered.item_name,
+    itemKind: answered.item_kind,
+    itemCount: answered.item_count,
+    purchaseSource: answered.purchase_source,
+    purchaseStatus: answered.purchase_status,
+    gameAccountId: answered.game_account_id,
+    paidMinorUnits: answered.paid_minor_units,
+    currencyCode: answered.currency_code,
+    purchasedAt: answered.purchased_at,
+    refundedAt: answered.refunded_at,
+    receipt: answered.receipt,
+  };
+}
+
+/**
+ * Handing purchases over on your own server: Zaisma's record of what's handled, through the developer API
+ * with the developer's key, so a purchase comes once across restarts and Zaisma's own rooms. Rooms on this
+ * server don't race each other for one: each is held here while its hook runs. An API that can't be reached,
+ * or a key that ended, hands nothing over, and the player's next join tries again.
+ */
+function ownServerPurchaseHandling(gameSlug, zaismaKey, developerApiUrl) {
+  const heldUntilMs = new Map(); // "<purchase id> purchase|refund" -> when this server lets go of it
+  const keyOf = (purchase) => `${purchase.id} ${purchase.purchaseStatus === "completed" ? "purchase" : "refund"}`;
+  async function callApi(method, path) {
+    const response = await fetch(`${developerApiUrl}${path}`, { method, headers: { authorization: `Bearer ${zaismaKey}`, "content-type": "application/json" }, body: method === "POST" ? "{}" : undefined });
+    const answer = await response.json().catch(() => null);
+    return { status: response.status, answer };
+  }
+  const failure = (what, { status, answer }) => new Error(`Zaisma's developer API answered ${status} ${what}${answer?.error ? `: ${answer.error.code}, ${answer.error.message} ${answer.error.fix}` : "."}`);
+  // Where the game's purchases go, read again at most once a minute: only game_server hands them to this server,
+  // so a game whose page or own backend takes them never races it for them.
+  let delivery = { purchaseDelivery: null, readAtMs: 0 };
+  async function isDeliveredHere() {
+    if (Date.now() - delivery.readAtMs >= DELIVERY_KEPT_MS) {
+      const answered = await callApi("GET", `/games/${encodeURIComponent(gameSlug)}/items`);
+      if (answered.status !== 200) throw failure("for the game's purchase settings", answered);
+      delivery = { purchaseDelivery: answered.answer.purchase_delivery, readAtMs: Date.now() };
+    }
+    return delivery.purchaseDelivery === "game_server";
+  }
+  return {
+    isReceiptNeeded: true,
+    async unhandledFor(playerId) {
+      if (!(await isDeliveredHere())) return [];
+      const answered = await callApi("GET", `/games/${encodeURIComponent(gameSlug)}/players/${encodeURIComponent(playerId)}/items`);
+      if (answered.status !== 200) throw failure(`for ${playerId}'s purchases`, answered);
+      return (answered.answer.unhandled_purchases ?? []).map(purchaseOf);
+    },
+    async startHandling(playerId, purchase) {
+      const nowMs = Date.now();
+      for (const [key, untilMs] of heldUntilMs) if (untilMs <= nowMs) heldUntilMs.delete(key);
+      if (heldUntilMs.has(keyOf(purchase))) return false;
+      heldUntilMs.set(keyOf(purchase), nowMs + HANDLING_LEASE_MS);
+      return true;
+    },
+    async finishHandling(playerId, purchase) {
+      // Remembered here first, so a room on this server can't hand it over again while the call is on its way.
+      heldUntilMs.set(keyOf(purchase), Date.now() + HANDLED_KEPT_MS);
+      const answered = await callApi("POST", `/games/${encodeURIComponent(gameSlug)}/purchases/${encodeURIComponent(purchase.id)}/handled`);
+      if (answered.status !== 200 && answered.answer?.error?.code !== "already_handled") throw failure(`marking ${purchase.id} handled`, answered);
+    },
+    async releaseHandling(playerId, purchase) {
+      heldUntilMs.delete(keyOf(purchase));
+    },
+  };
+}
+
 /** A binary frame from ws (a Buffer, an ArrayBuffer or a fragmented frame's pieces) as a Uint8Array of its own. */
 function binaryBytes(received) {
   if (Array.isArray(received)) return new Uint8Array(Buffer.concat(received));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaisma/game-server",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Run your Zaisma game server: the same rooms on Zaisma or on your own server.",
   "license": "MIT",
   "homepage": "https://zaisma.com",

package/src/index.d.ts

@@ -1,4 +1,4 @@
-export { BUSY_CLOSE_CODE, ENDED_CLOSE_CODE, GAME_SERVER_OPTIONS, GameServerError, NO_ANSWER_CLOSE_CODE, REMOVED_CLOSE_CODE, ROOM_LIMITS, SEAT_GONE_CLOSE_CODE, VERSION_UPDATE_CLOSE_CODE, defineGameServer, type Audience, type AwayInfo, type AwayMode, type AwayReason, type BroadcastOptions, type Delivery, type GameServer, type GameServerErrorCode, type HandlerResult, type IdleCheck, type JoinAnswer, type JoinInfo, type KickOptions, type LeaveInfo, type LeaveReason, type MoveOptions, type MoveResult, type Player, type Refusal, type ReserveOptions, type RestoreInfo, type Room, type RoomErrorCode, type RoomInfo, type SendOptions, type VersionUpdate, } from "./room.ts";
+export { BUSY_CLOSE_CODE, ENDED_CLOSE_CODE, GAME_SERVER_OPTIONS, GameServerError, NO_ANSWER_CLOSE_CODE, REMOVED_CLOSE_CODE, ROOM_LIMITS, SEAT_GONE_CLOSE_CODE, VERSION_UPDATE_CLOSE_CODE, defineGameServer, type Audience, type AwayInfo, type AwayMode, type AwayReason, type BroadcastOptions, type Delivery, type GameServer, type GameServerErrorCode, type HandlerResult, type IdleCheck, type JoinAnswer, type JoinInfo, type KickOptions, type LeaveInfo, type LeaveReason, type MoveOptions, type MoveResult, type Player, type Purchase, type Refusal, type ReserveOptions, type RestoreInfo, type Room, type RoomErrorCode, type RoomInfo, type SendOptions, type VersionUpdate, } from "./room.ts";
 export { REQUEST_LIMITS, type RequestErrorCode, type Server } from "./requests.ts";
 export { SCHEDULE_LIMITS, type Schedule, type ScheduledRun } from "./schedules.ts";
 export { WEBHOOK_LIMITS, verifyWebhook, type WebhookError, type WebhookErrorCode, type WebhookEvent, type WebhookEventKind, type WebhookHeaders } from "./webhooks.ts";

package/src/room.d.ts

@@ -26,6 +26,46 @@ export interface Player {
      */
     ownedItemNames?: string[];
 }
+/**
+ * A purchase or grant as onPurchase and onRefund get it: the developer API's purchase, in camelCase.
+ * purchaseStatus is "completed" in onPurchase, and "refunded" or "charged_back" in onRefund.
+ * receipt is its signed receipt (room.verifyReceipt checks one), for your own records.
+ */
+export interface Purchase {
+    id: string;
+    itemName: string;
+    itemKind: "permanent" | "consumable";
+    /** How many: 1 for a permanent item. */
+    itemCount: number;
+    purchaseSource: "sale" | "grant";
+    purchaseStatus: "completed" | "refunded" | "charged_back";
+    /** Your game's own account ID for the player, when the game gave one to buy or grant_item; else null. */
+    gameAccountId: string | null;
+    /** What it paid, in the currency's minor units (cents); null for a grant. */
+    paidMinorUnits: number | null;
+    currencyCode: string | null;
+    /** When it was bought or granted, an ISO time. */
+    purchasedAt: string | null;
+    /** When the item was taken back (a full refund or a chargeback), an ISO time; null in onPurchase, and for a partial refund, which leaves the item owned. */
+    refundedAt: string | null;
+    receipt: string;
+}
+/**
+ * How a room hands purchases over (onPurchase, onRefund), from Zaisma's record of them: Zaisma rooms read
+ * it themselves, and the Node runner through the developer API with ZAISMA_KEY. Exactly once: a room hands
+ * a purchase over only after winning it (startHandling), and marks it handled after the hook, or lets go
+ * of it when the hook threw, so the player's next join tries again.
+ */
+export interface PurchaseHandling {
+    /** The player's purchases and refunds still to hand over, oldest first. */
+    unhandledFor(playerId: string): Promise<Purchase[]>;
+    /** Wins the purchase (or its refund) for this room; false when another room has it, or it was handled. */
+    startHandling(playerId: string, purchase: Purchase): Promise<boolean>;
+    finishHandling(playerId: string, purchase: Purchase): Promise<void>;
+    releaseHandling(playerId: string, purchase: Purchase): Promise<void>;
+    /** Whether a zaisma:purchase message must carry the purchase's receipt, checked before anything is asked (your own server). */
+    isReceiptNeeded?: boolean;
+}
 export interface Room {
     /**
      * This room's code, like K7Q2MX: the code players join it by. Use it to treat rooms differently, like
@@ -449,6 +489,21 @@ export interface GameServer<S = any> {
     onAway?(state: S, player: Player, room: Room, awayInfo: AwayInfo): HandlerResult<S>;
     onBack?(state: S, player: Player, room: Room): HandlerResult<S>;
     onMessage?(state: S, player: Player, room: Room, message: unknown): HandlerResult<S>;
+    /**
+     * A player bought or was granted an item: add it to their state, like a revive or 500 coins. It comes
+     * exactly once, within a second when the player is in a room (their game tells it, after Zaisma.items.buy),
+     * or the next time they join. Only with purchase_delivery "game_server" (set_purchase_settings). If it
+     * throws, it isn't handled: it comes again on the player's next join, and you see the error with the
+     * game server's others. Without onPurchase, a room never takes a purchase. On your own server, the Node
+     * runner needs ZAISMA_KEY for it.
+     */
+    onPurchase?(state: S, player: Player, room: Room, purchase: Purchase): HandlerResult<S>;
+    /**
+     * A purchase onPurchase got was refunded or charged back (purchase.purchaseStatus says which): take back
+     * what your refund policy says, like a revive not used yet. Permanent items leave player.ownedItemNames by
+     * themselves. Comes once, on the player's next join (and to webhooks at once, as purchase_refunded).
+     */
+    onRefund?(state: S, player: Player, room: Room, purchase: Purchase): HandlerResult<S>;
     /**
      * Bytes a player's game sent (room.sendBytes), like a compact input, under the same limits as
      * messages: up to 16 KB each, 30 a second. Read them with a DataView; they're a copy, yours to keep.
@@ -532,7 +587,7 @@ export declare function readJoinAnswer(answer: unknown): {
     mistake: GameServerError;
 };
 /** Everything a game server object may have, in the order the docs give them. Anything else is refused. */
-export declare const GAME_SERVER_OPTIONS: readonly ["maximumPlayerCount", "maximumSpectatorCount", "ticksPerSec", "hostControlsEnabled", "idleCheck", "idleTimeoutSec", "awayMode", "seatHoldDurationSec", "stateSyncEnabled", "reconnectTimeoutSec", "stateSaveIntervalSec", "setup", "onJoin", "canJoin", "onMoved", "onLeave", "onSpectatorJoin", "onSpectatorLeave", "onAway", "onBack", "onMessage", "onBytes", "onTick", "onEnding", "onRestored", "stateView", "onVersionUpdate", "onRequest", "schedules", "onSchedule", "onWebhook"];
+export declare const GAME_SERVER_OPTIONS: readonly ["maximumPlayerCount", "maximumSpectatorCount", "ticksPerSec", "hostControlsEnabled", "idleCheck", "idleTimeoutSec", "awayMode", "seatHoldDurationSec", "stateSyncEnabled", "reconnectTimeoutSec", "stateSaveIntervalSec", "setup", "onJoin", "canJoin", "onMoved", "onLeave", "onSpectatorJoin", "onSpectatorLeave", "onAway", "onBack", "onMessage", "onBytes", "onPurchase", "onRefund", "onTick", "onEnding", "onRestored", "stateView", "onVersionUpdate", "onRequest", "schedules", "onSchedule", "onWebhook"];
 export declare const ROOM_LIMITS: {
     /** Players in one room: what one room carries at 60 ticks a second (test/load/room-load.test.ts). */
     readonly maximumPlayerCount: 100;
@@ -682,6 +737,11 @@ export interface RoomSettings {
  * of the match with their seat held gets {type: "away"}, and once the seat is no longer held, their
  * connection closes with SEAT_GONE_CLOSE_CODE.
  *
+ * Purchases: after Zaisma.items.buy, a game whose purchases go to its game server sends {type:
+ * "zaisma:purchase", purchaseId, receipt?} on each room it's in. It only says "look now": the room reads
+ * Zaisma's record itself and hands the player's unhandled purchases to onPurchase, as it does on every
+ * join. Each purchase ID counts once per player per room; on your own server, receipt is checked first.
+ *
  * Ping and the room's clock (docs/DECISIONS.md, "Rooms under lag"): the room sends {type: "probe",
  * probeNumber, serverTimeMs, pingDurationMs} right after welcome and again once it's answered (so the
  * client hears its first ping), every welcome.probeIntervalSec while
@@ -793,6 +853,10 @@ export type ClientMessage = {
 } | {
     type: "message";
     data: unknown;
+} | {
+    type: "zaisma:purchase";
+    purchaseId: string;
+    receipt?: string;
 } | {
     type: "room";
     room: Partial<RoomSettings>;
@@ -912,6 +976,8 @@ export interface Transport {
     applyVersionUpdate?(): void;
     /** Whether a player's connection holds ROOM_TUNING.backedUpSizeBytes or more not yet sent. Without it, the room judges by its probes. */
     isBackedUp?(playerId: string): boolean;
+    /** Where the room hands purchases over (onPurchase, onRefund). Without it, purchases never reach the room. */
+    purchaseHandling?: PurchaseHandling;
 }
 /** room.secrets and server.secrets where a game has none. */
 export declare const NO_SECRETS: Readonly<Record<string, string>>;
@@ -1123,6 +1189,13 @@ export declare class RoomCore<S = any> {
     /** Handlers running right now, and what waits for them to finish (a kicked player's onLeave). */
     private depth;
     private afterHandler;
+    /** Players whose purchases are being handed over now, and those to look at again once that's done. */
+    private readonly purchasePlayerIds;
+    private readonly purchaseAgainPlayerIds;
+    /** The purchase IDs each player's zaisma:purchase messages named, so a client can't spin the room on one. */
+    private readonly toldPurchaseIds;
+    /** Hand-overs running now, for settled(). */
+    private purchaseDeliveries;
     /**
      * startOptions.start makes a reserved room: closed, open only to the players it was made for, and
      * set up with its setup data. A saved room (startOptions.room) wakes as it was, with
@@ -1446,6 +1519,21 @@ export declare class RoomCore<S = any> {
     private take;
     /** A handler's answer becomes the state if it is one (a plain object or an array); nothing keeps the state, and anything else is a mistake that leaves it. */
     private keepAnswer;
+    /**
+     * A player's game says it bought something (after Zaisma.items.buy). The message only says "look now":
+     * the room reads Zaisma's record itself, and each purchase ID counts once per player per room. On your
+     * own server (isReceiptNeeded), the purchase's receipt must check out first, so a lying client can't
+     * make the server spend calls to Zaisma.
+     */
+    private purchaseTold;
+    /**
+     * Hands a player's unhandled purchases to onPurchase and their refunds to onRefund, exactly once: each
+     * only after this room wins it, marked handled after the hook, and let go when the hook threw, so their
+     * next join tries again. One hand-over per player at a time; a call meanwhile looks again after it.
+     */
+    private deliverPurchases;
+    /** Runs onPurchase or onRefund like any handler, answering whether it finished without throwing. */
+    private runPurchaseHook;
     /**
      * Run a game server handler. A crash in game code is logged and never takes the room down. State sync's
      * round follows a turn-based room's handlers and a real-time room's tick (isTick).

package/src/room.js

@@ -72,6 +72,8 @@ export const GAME_SERVER_OPTIONS = [
     "onBack",
     "onMessage",
     "onBytes",
+    "onPurchase",
+    "onRefund",
     "onTick",
     "onEnding",
     "onRestored",
@@ -284,6 +286,10 @@ export const ERROR_TEXT = {
 };
 /** What players are told when Zaisma ends a match at room.endsAt. */
 export const HOSTING_PAUSED_END_MESSAGE = "This game's hosting is paused, so this match has ended. New rooms open again when the month resets or its developer adds credit.";
+/** A zaisma:purchase message's purchaseId, at most: longer is no purchase's. */
+const MAXIMUM_PURCHASE_ID_CHARACTER_COUNT = 80;
+/** The purchase IDs one player's zaisma:purchase messages count in one room; past that they're ignored, and joins still bring purchases. */
+const MAXIMUM_TOLD_PURCHASE_COUNT = 200;
 /** How long a room holds a seat for a player another room is sending. */
 const SEAT_MS = 60_000;
 /** room.secrets and server.secrets where a game has none. */
@@ -505,6 +511,13 @@ export class RoomCore {
     /** Handlers running right now, and what waits for them to finish (a kicked player's onLeave). */
     depth = 0;
     afterHandler = [];
+    /** Players whose purchases are being handed over now, and those to look at again once that's done. */
+    purchasePlayerIds = new Set();
+    purchaseAgainPlayerIds = new Set();
+    /** The purchase IDs each player's zaisma:purchase messages named, so a client can't spin the room on one. */
+    toldPurchaseIds = new Map();
+    /** Hand-overs running now, for settled(). */
+    purchaseDeliveries = new Set();
     /**
      * startOptions.start makes a reserved room: closed, open only to the players it was made for, and
      * set up with its setup data. A saved room (startOptions.room) wakes as it was, with
@@ -846,10 +859,14 @@ export class RoomCore {
     }
     /** Resolves once every handler started so far has finished (at once for game servers that answer at once). */
     async settled() {
-        while (this.queue) {
+        while (this.queue || this.purchaseDeliveries.size) {
+            if (this.purchaseDeliveries.size)
+                await Promise.all([...this.purchaseDeliveries]);
             const queued = this.queue;
+            if (!queued)
+                continue;
             await queued;
-            if (this.queue === queued)
+            if (this.queue === queued && !this.purchaseDeliveries.size)
                 return;
         }
     }
@@ -1071,6 +1088,8 @@ export class RoomCore {
         // A turn-based room has no tick to bring a returning connection its copy of the state.
         if (isRejoin && !this.ticking)
             this.syncSoon();
+        // Every join looks for purchases the player hasn't had yet: ones bought while away, or whose hand-over failed.
+        this.deliverPurchases(player.id);
         return { isAllowed: true, isRejoin };
     }
     /**
@@ -1386,6 +1405,9 @@ export class RoomCore {
             case "message":
                 this.input(() => this.server.onMessage?.(this.state, player, this.api, message.data), "onMessage");
                 return null;
+            case "zaisma:purchase":
+                this.purchaseTold(playerId, message);
+                return null;
             case "block":
                 return this.sessionBlock(playerId, message, true);
             case "unblock":
@@ -2084,6 +2106,107 @@ export class RoomCore {
         else
             console.error("Game server error:", badHandlerAnswer(handlerName, answer));
     }
+    /**
+     * A player's game says it bought something (after Zaisma.items.buy). The message only says "look now":
+     * the room reads Zaisma's record itself, and each purchase ID counts once per player per room. On your
+     * own server (isReceiptNeeded), the purchase's receipt must check out first, so a lying client can't
+     * make the server spend calls to Zaisma.
+     */
+    purchaseTold(playerId, message) {
+        const handling = this.transport.purchaseHandling;
+        if (!handling || (!this.server.onPurchase && !this.server.onRefund))
+            return;
+        const purchaseId = message.purchaseId;
+        if (typeof purchaseId !== "string" || !purchaseId || purchaseId.length > MAXIMUM_PURCHASE_ID_CHARACTER_COUNT)
+            return;
+        const told = this.toldPurchaseIds.get(playerId) ?? new Set();
+        if (told.has(purchaseId) || told.size >= MAXIMUM_TOLD_PURCHASE_COUNT)
+            return;
+        // Counted as told only once it's believed, so a forged receipt can't use up a real purchase's ID.
+        const believed = () => {
+            told.add(purchaseId);
+            this.toldPurchaseIds.set(playerId, told);
+            this.deliverPurchases(playerId);
+        };
+        if (!handling.isReceiptNeeded)
+            return believed();
+        const receipt = message.receipt;
+        if (typeof receipt !== "string" || !this.transport.verifyReceipt)
+            return;
+        this.transport.verifyReceipt(receipt).then((claims) => {
+            if (claims.sub === playerId && claims.purchase_id === purchaseId && !told.has(purchaseId))
+                believed();
+        }, () => undefined);
+    }
+    /**
+     * Hands a player's unhandled purchases to onPurchase and their refunds to onRefund, exactly once: each
+     * only after this room wins it, marked handled after the hook, and let go when the hook threw, so their
+     * next join tries again. One hand-over per player at a time; a call meanwhile looks again after it.
+     */
+    deliverPurchases(playerId) {
+        const handling = this.transport.purchaseHandling;
+        if (!handling || (!this.server.onPurchase && !this.server.onRefund))
+            return;
+        // Guests own nothing: their IDs last only for their pass.
+        if (this.players.get(playerId)?.kind !== "account")
+            return;
+        if (this.purchasePlayerIds.has(playerId)) {
+            this.purchaseAgainPlayerIds.add(playerId);
+            return;
+        }
+        this.purchasePlayerIds.add(playerId);
+        const delivery = (async () => {
+            do {
+                this.purchaseAgainPlayerIds.delete(playerId);
+                for (const purchase of await handling.unhandledFor(playerId)) {
+                    const hookName = purchase.purchaseStatus === "completed" ? "onPurchase" : "onRefund";
+                    const hook = this.server[hookName];
+                    if (!hook)
+                        continue;
+                    if (!this.players.has(playerId) || this.ended)
+                        return;
+                    if (!(await handling.startHandling(playerId, purchase)))
+                        continue;
+                    const player = this.players.get(playerId);
+                    const isHandled = player && !this.ended ? await this.runPurchaseHook(() => hook.call(this.server, this.state, player, this.api, purchase), hookName) : false;
+                    await (isHandled ? handling.finishHandling(playerId, purchase) : handling.releaseHandling(playerId, purchase));
+                }
+            } while (this.purchaseAgainPlayerIds.has(playerId));
+        })()
+            .catch((error) => console.error("Couldn't hand purchases over:", error))
+            .finally(() => {
+            this.purchasePlayerIds.delete(playerId);
+            this.purchaseDeliveries.delete(delivery);
+        });
+        this.purchaseDeliveries.add(delivery);
+    }
+    /** Runs onPurchase or onRefund like any handler, answering whether it finished without throwing. */
+    runPurchaseHook(hook, hookName) {
+        // A hook that answers at once runs at once, so a game server that never returns a promise doesn't start queueing.
+        return new Promise((resolve) => {
+            this.run(() => {
+                let next;
+                try {
+                    next = hook();
+                }
+                catch (error) {
+                    resolve(false);
+                    throw error;
+                }
+                if (!isPromise(next)) {
+                    resolve(true);
+                    return next;
+                }
+                return next.then((answered) => {
+                    resolve(true);
+                    return answered;
+                }, (error) => {
+                    resolve(false);
+                    throw error;
+                });
+            }, hookName);
+        });
+    }
     /**
      * Run a game server handler. A crash in game code is logged and never takes the room down. State sync's
      * round follows a turn-based room's handlers and a real-time room's tick (isTick).

package/src/schedules.js

@@ -159,7 +159,9 @@ const MAXIMUM_TIMER_MS = 24 * 3_600_000;
 export function startSchedules(handler, server, onFailure) {
     const timers = new Set();
     let isStopped = false;
-    for (const schedule of handler.schedules ?? []) {
+    // Run from the checked list, so run.cron is the tidied cron on every runtime (get_stats lists it that way too).
+    const read = readSchedules(handler.schedules, typeof handler.onSchedule === "function");
+    for (const schedule of "schedules" in read ? read.schedules : []) {
         const plan = (afterMs) => {
             const atMs = nextRunAtMs(schedule.cron, afterMs);
             if (atMs === null || isStopped)

package/src/webhooks.d.ts

@@ -13,7 +13,7 @@ import type { Server } from "./requests.ts";
  * Every kind of event Zaisma sends today. A WebhookEvent's kind is one of these or a kind added later,
  * so a game server switches on the ones it knows and skips the rest.
  */
-export type WebhookEventKind = "bug_reported" | "player_reported" | "scan_status_changed" | "live_version_changed" | "review_status_changed" | "country_blocks_changed" | "game_server_error_found" | "alert_raised" | "account_deleted" | "security_alert" | "test";
+export type WebhookEventKind = "bug_reported" | "player_reported" | "scan_status_changed" | "live_version_changed" | "review_status_changed" | "country_blocks_changed" | "game_server_error_found" | "alert_raised" | "account_deleted" | "security_alert" | "purchase_completed" | "purchase_refunded" | "test";
 /** Who deleted their Zaisma account, on an account_deleted event. */
 export interface AccountDeletion {
     /** The player who deleted their Zaisma account. */
@@ -51,6 +51,8 @@ export interface WebhookEvent {
     sign_in_app: Record<string, unknown> | null;
     /** The developer's own account event as get_activity lists it; null unless kind is security_alert. */
     security_event: Record<string, unknown> | null;
+    /** The purchase as get_purchase answers it, with its receipt and game_account_id; null unless kind is purchase_completed or purchase_refunded. */
+    purchase: Record<string, unknown> | null;
 }
 export declare const WEBHOOK_LIMITS: {
     /** How long onWebhook may take, awaiting the database and outside calls included, before the try fails and waits for the next. */