@zaisma/game-server 1.12.0 → 1.14.0

package/sdk/zaisma.d.ts

@@ -26,7 +26,9 @@
  *
  * Player passes, for rooms and your own servers, need the game played on its zaisma.com page, which
  * checks the browser on Play: joining fails with `error.code` "unchecked" when it couldn't, or when the
- * game was opened anywhere else, and "not_on_zaisma" when the game isn't hosted on Zaisma at all.
+ * game was opened anywhere else. A game played off Zaisma (exported, on another site, wrapped for a store)
+ * plays online against your own game server only: call {@link Zaisma.setUpOffZaisma} first, and give
+ * joinRoom and server.request a serverUrl; without them they fail with "not_on_zaisma".
  *
  * @example
  * const room = await Zaisma.joinRoom();         // joins ?room=CODE if the link has one, else makes a room
@@ -140,8 +142,9 @@ declare namespace Zaisma {
    * refused (the game server's canJoin said no; the message is its refusalMessage), hosting_paused (the
    * game's hosting is paused this month: its free allowance or its developer's budget or credit is used). No player pass: unchecked, or account_needed for a
    * guest when the game needs accounts (see Zaisma.player.getPass()). The
-   * call is set up wrong: unknown_option, bad_room_code, bad_server_url, bad_transport, not_on_zaisma (the game isn't hosted
-   * on Zaisma, serverUrl or not; serverUrl points a game hosted on Zaisma at your own server). Or connection_closed (the connection closed first, say the game left or the player
+   * call is set up wrong: unknown_option, bad_room_code, bad_server_url, bad_transport, not_on_zaisma (the game is played
+   * off Zaisma without a serverUrl, or before {@link setUpOffZaisma}). Off Zaisma, bad_player_token: your server
+   * didn't take the playerToken (get the player a new one and call setUpOffZaisma again). Or connection_closed (the connection closed first, say the game left or the player
    * joined from another tab) and request_failed (Zaisma didn't answer). {@link ErrorCode} has them all.
    *
    * @example
@@ -154,6 +157,40 @@ declare namespace Zaisma {
    */
   function joinRoom(joinOptions?: JoinOptions): Promise<Room>;
 
+  /**
+   * Set up a game played off Zaisma (exported, on another site, wrapped for a store) to play online against
+   * your own game server. Off Zaisma there's no Zaisma pass, so joinRoom and server.request with a serverUrl
+   * send the playerToken in its place, and your server says who the player is (startServer's identifyPlayer):
+   * a Sign in with Zaisma ID token (same player ID and name as on Zaisma), your game's own token, or null for
+   * a guest when your server lets guests in (outsideGuestsEnabled). They join with kind "outside_zaisma",
+   * in the same rooms as players from your Zaisma page.
+   *
+   * On a Zaisma page it changes nothing and resolves { isOffZaisma: false }, so the same code runs in both
+   * places. Call it again to replace the token (a new sign-in, or signing out); rooms use the newest one when
+   * they reconnect. Off Zaisma there's no Zaisma bar, saves, buy sheet, friends or room lists.
+   *
+   * Fails with error.code unknown_option, bad_game_slug (not a game slug) and bad_player_token (not text up to 8 KB, or null).
+   *
+   * @example
+   * await Zaisma.setUpOffZaisma({ gameSlug: "star-raiders", playerToken: idToken });
+   * const room = await Zaisma.joinRoom({ serverUrl: "wss://play.example.com" });
+   */
+  function setUpOffZaisma(setUpOptions: SetUpOffZaismaOptions): Promise<OffZaismaSetup>;
+
+  /** Options for {@link setUpOffZaisma}. */
+  interface SetUpOffZaismaOptions {
+    /** Your game's slug, as its Zaisma link names it, like "star-raiders": the address your server's rooms and requests take. */
+    gameSlug: string;
+    /** The player's token for your own server, text up to 8 KB: a Sign in with Zaisma ID token or your game's own. Null or left out for a guest. */
+    playerToken?: string | null;
+  }
+
+  /** What {@link setUpOffZaisma} answers. */
+  interface OffZaismaSetup {
+    /** False on a Zaisma page (nothing changed); true elsewhere, where joins and requests now carry the playerToken. */
+    isOffZaisma: boolean;
+  }
+
   /** Room browsing: the game's listed rooms, which show on its Zaisma page and to the game itself. */
   const rooms: Rooms;
 
@@ -982,8 +1019,9 @@ declare namespace Zaisma {
      * seconds; you see why with the game server's errors), hosting_paused (the game's hosting
      * on Zaisma is paused this month: its free allowance or its developer's budget or credit is used), too_big, bad_request (not plain JSON), slow_down
      * (over about 120 a minute from one address), bad_pass, account_needed, unchecked,
-     * game_unavailable, bad_origin, busy, bad_server_url, not_on_zaisma (the game isn't hosted
-     * on Zaisma, serverUrl or not), unknown_option and request_failed.
+     * game_unavailable, bad_origin, busy, bad_server_url, not_on_zaisma (the game is played off
+     * Zaisma without a serverUrl, or before {@link Zaisma.setUpOffZaisma}), bad_player_token (off Zaisma,
+     * your server didn't take the playerToken), unknown_option and request_failed.
      *
      * @example
      * const top = await Zaisma.server.request({ type: "leaderboard" });
@@ -1347,6 +1385,15 @@ declare namespace Zaisma {
      * room.on("versionUpdate", ({ appliesAt }) => showBanner(`Updating at ${new Date(appliesAt).toLocaleTimeString()}`));
      */
     versionUpdate: (versionUpdate: VersionUpdate) => void;
+    /**
+     * A room message reached this room and its game server has no onRoomMessage, so every player's game hears
+     * it: from another room of the game (senderKind "room", fromRoomCode), its game server outside rooms
+     * ("server") or the developer (the API and MCP, "developer"), like an announcement or a live event starting.
+     * Zaisma shows nothing: your game decides. A game server with onRoomMessage takes it instead.
+     * @example
+     * room.on("roomMessage", ({ message }) => { if (message.kind === "blood_moon") startBloodMoon(); });
+     */
+    roomMessage?: (roomMessage: RoomMessage) => void;
     /**
      * Another player's chat message reached this player ({@link Room.chat}). Messages from players this
      * player muted or blocked never come. hasSwearing and hasSlur flag what Zaisma allows: hide or blur
@@ -1438,6 +1485,18 @@ declare namespace Zaisma {
     answerTimeoutSec: number;
   }
 
+  /** A room message, as the room's "roomMessage" event hands it over. */
+  interface RoomMessage {
+    /** The message as sent: plain JSON, up to 16 KB. */
+    message: unknown;
+    /** Who sent it: another room's game server, the game server outside rooms, or the developer. */
+    senderKind: "room" | "server" | "developer";
+    /** The code of the room that sent it, or null unless senderKind is "room". */
+    fromRoomCode: string | null;
+    /** When it was sent, an ISO time. */
+    sentAt: string;
+  }
+
   /** A match moving to a version published "now" (the room's "versionUpdate" event). */
   interface VersionUpdate {
     /** The version it moves to, like "version_k2v9q4x7m1p3w8r5t6y0". */
@@ -1467,8 +1526,11 @@ declare namespace Zaisma {
     awayReason: "idle" | "hidden" | "lost" | null;
   }
 
-  /** A signed-in Zaisma account, or a guest. More values may come; treat an unknown one as "guest". */
-  type PlayerKind = "guest" | "account";
+  /**
+   * A signed-in Zaisma account, a guest, or a player your own server let in from outside Zaisma
+   * (outside_zaisma: a game played off Zaisma, {@link setUpOffZaisma}). More values may come; treat an unknown one as "guest".
+   */
+  type PlayerKind = "guest" | "account" | "outside_zaisma";
 
   /** What anyone sees of an account on its profile, zaisma.com/@username ({@link player.getProfile}). */
   interface PlayerProfile {
@@ -1606,6 +1668,7 @@ declare namespace Zaisma {
    * - game_not_open_to_player: the account is younger than the game's minimum age (set on the dashboard); the game never learns its age.
    * - game_unavailable: the game can't be played right now.
    * - bad_pass: the player pass wasn't accepted (the SDK gets a new one and tries once more).
+   * - bad_player_token: off Zaisma, your own server didn't take the playerToken ({@link setUpOffZaisma}); the game gets the player a new one.
    * - bad_origin: the connection didn't come from the game's own page.
    * - too_big: a message over 16 KB, or joinData over 4 KB.
    * - too_fast: more messages than the room takes (about 30 a second).
@@ -1621,6 +1684,8 @@ declare namespace Zaisma {
    * - chat_not_allowed, chat_empty, chat_too_long, chat_too_fast: {@link Room.chat} refused (they reject its promise, not the "error" event); chat_not_here: the room's server doesn't take chat.
    *
    * More codes may come within v1: handle one you don't know like an error you can show (its message).
+   *
+   * More values may come; treat an unknown one as "request_failed".
    */
   type RoomErrorCode =
     | "room_full"
@@ -1633,6 +1698,7 @@ declare namespace Zaisma {
     | "game_not_open_to_player"
     | "game_unavailable"
     | "bad_pass"
+    | "bad_player_token"
     | "bad_origin"
     | "too_big"
     | "too_fast"
@@ -1658,6 +1724,7 @@ declare namespace Zaisma {
    * - bad_request: not plain JSON with the player's pass.
    * - too_big: a request over 16 KB.
    * - bad_pass: the player pass wasn't accepted (the SDK gets a new one and tries once more).
+   * - bad_player_token: off Zaisma, your own server didn't take the playerToken ({@link setUpOffZaisma}); the game gets the player a new one.
    * - account_needed: the player is a guest, and the game needs a Zaisma account for multiplayer or the whole game.
    * - game_not_open_to_player: the account is younger than the game's minimum age (set on the dashboard); the game never learns its age.
    * - game_unavailable: the game can't be played right now.
@@ -1667,11 +1734,14 @@ declare namespace Zaisma {
    * - slow_down: too many requests from this address; try again in a minute.
    * - bad_origin: the request didn't come from the game's own page.
    * - busy: Zaisma couldn't answer right now; try again soon.
+   *
+   * More values may come; treat an unknown one as "request_failed".
    */
   type RequestErrorCode =
     | "bad_request"
     | "too_big"
     | "bad_pass"
+    | "bad_player_token"
     | "account_needed"
     | "game_not_open_to_player"
     | "game_unavailable"
@@ -1690,7 +1760,8 @@ declare namespace Zaisma {
    * - zaisma_rooms_not_used: the game doesn't use Zaisma rooms.
    * - bad_report: a report whose reason isn't a {@link ReportReason}, or whose player ID isn't one.
    * - bad_origin: the call didn't come from the game's own page.
-   * - not_on_zaisma: the game isn't hosted on Zaisma, so it has no player passes, sign-in or room lists, and joinRoom needs a serverUrl.
+   * - not_on_zaisma: the game is played off Zaisma, so it has no player passes, sign-in or room lists; joinRoom and server.request need {@link setUpOffZaisma} and a serverUrl.
+   * - bad_game_slug: {@link setUpOffZaisma}'s gameSlug isn't a game slug: 1 to 40 lowercase letters, digits or hyphens.
    * - sign_in_declined: the player chose Not now when the game asked them to sign in ({@link player.signIn}) or showed the "Keep your progress" card ({@link player.offerAccount}).
    * - account_offer_too_soon: the "Keep your progress" card already showed this visit, or the player chose Not now in the last 3 days ({@link player.offerAccount}).
    * - cloud_saves_off: the game has cloud saves off, so it has no saves on players' accounts ({@link saves}).
@@ -1731,6 +1802,7 @@ declare namespace Zaisma {
     | "bad_report"
     | "bad_origin"
     | "not_on_zaisma"
+    | "bad_game_slug"
     | "sign_in_declined"
     | "account_offer_too_soon"
     | "cloud_saves_off"

package/sdk/zaisma.js

@@ -6,8 +6,11 @@
  * together; test/node/sdk-types.test.ts checks that they match.
  *
  * On Zaisma, the games Worker defines __ZAISMA__ before this file with the rooms address, the game and
- * the site. A game that isn't hosted on Zaisma gets "not_on_zaisma" for online play, serverUrl or not; serverUrl points a
- * game hosted on Zaisma at your own server.
+ * the site; serverUrl points a game played there at your own server. Played anywhere else (exported, on
+ * another site, wrapped for a store), a game plays online against your own server only: after
+ * Zaisma.setUpOffZaisma({ gameSlug, playerToken }), joinRoom and server.request with a serverUrl send the
+ * playerToken in place of a Zaisma pass, and your server says who that is (its identifyPlayer). Saves, the buy
+ * sheet, friends and room lists stay on Zaisma, and so does the Zaisma bar.
  */
 (function () {
   "use strict";
@@ -18,6 +21,7 @@
   var OWN_SERVER_URL = /^(wss|https):\/\/[^/]/;
 
   // What each call takes. Anything else is refused, so a misspelled or old option never goes quietly unused.
+  var SET_UP_OFF_ZAISMA_OPTIONS = ["gameSlug", "playerToken"];
   var JOIN_OPTIONS = ["roomCode", "serverUrl", "transport", "isListed", "friendJoinsEnabled", "name", "labels", "joinData", "idleTimeoutSec", "idleCheckEnabled", "isSpectator"];
   // quickJoin finds Zaisma rooms, so it takes no serverUrl.
   var QUICK_JOIN_OPTIONS = ["isListed", "friendJoinsEnabled", "name", "labels", "joinData", "idleTimeoutSec", "idleCheckEnabled", "region"];
@@ -33,7 +37,7 @@
   /** A fast lane that isn't up in this long gives way to the WebSocket, for the rest of the room's life. */
   var FAST_LANE_CONNECT_TIMEOUT_MS = 3000;
   var ROOM_INFO_FIELDS = ["name", "labels"];
-  var ROOM_EVENTS = ["message", "bytes", "state", "players", "connectionStatus", "ended", "ending", "endingCancelled", "kicked", "settings", "move", "moved", "idle", "away", "back", "muted", "error", "versionUpdate", "chat"];
+  var ROOM_EVENTS = ["message", "bytes", "state", "players", "connectionStatus", "ended", "ending", "endingCancelled", "kicked", "settings", "move", "moved", "idle", "away", "back", "muted", "error", "versionUpdate", "chat", "roomMessage"];
   /** Chat (room.chat): the longest message, the lines a room keeps in memory for reports, and how many of them a report carries. */
   var MAXIMUM_CHAT_CHARACTER_COUNT = 2000;
   var KEPT_CHAT_LINE_COUNT = 50;
@@ -76,6 +80,13 @@
   var DEFAULT_SMOOTHING_DELAY_MS = 100;
   var KEPT_VIEWS_DURATION_MS = 1000;
 
+  /** A game's slug, as its Zaisma link names it. */
+  var GAME_SLUG = /^[a-z0-9-]{1,40}$/;
+  /** The longest playerToken a game off Zaisma sends its own server, as UTF-8. */
+  var MAXIMUM_PLAYER_TOKEN_SIZE_BYTES = 8 * 1024;
+  /** Off Zaisma, after Zaisma.setUpOffZaisma: { gameSlug, playerToken } for joins and requests to the game's own server. */
+  var offZaisma = null;
+
   /** An Error with a code, as the SDK's errors all have. */
   function codedError(code, message) {
     var error = new Error(message);
@@ -88,6 +99,36 @@
     return codedError("not_on_zaisma", message);
   }
 
+  /**
+   * Off Zaisma, the game's own server can't take a Zaisma pass: what to do instead, or null when it can go ahead
+   * (on Zaisma, or set up off it). serverUrl: the call's own server, which off Zaisma it needs.
+   */
+  function offZaismaRefusal(serverUrl, call) {
+    if (config.rooms) return null;
+    if (!serverUrl) return notOnZaisma("Zaisma's rooms serve games played on Zaisma; off Zaisma, give serverUrl, the address of your own game server, to " + call + ".");
+    if (!offZaisma) return notOnZaisma("Off Zaisma, call Zaisma.setUpOffZaisma({ gameSlug, playerToken }) first: your own server knows the player by the playerToken, and serverUrl points " + call + " at it.");
+    return null;
+  }
+
+  /**
+   * Set up a game played off Zaisma (zaisma.d.ts: Zaisma.setUpOffZaisma). On a Zaisma page it changes nothing,
+   * so the same code runs in both places; elsewhere it keeps the game's slug and its player's token for joins
+   * and requests to the game's own server. Called again, it replaces the token (a new sign-in, or signing out).
+   */
+  function setUpOffZaisma(setUpOptions) {
+    var refused = unknownOption(setUpOptions, SET_UP_OFF_ZAISMA_OPTIONS, "Zaisma.setUpOffZaisma");
+    if (refused) return Promise.reject(refused);
+    if (config.rooms) return Promise.resolve({ isOffZaisma: false });
+    setUpOptions = setUpOptions || {};
+    var gameSlug = setUpOptions.gameSlug;
+    if (typeof gameSlug !== "string" || !GAME_SLUG.test(gameSlug)) return Promise.reject(codedError("bad_game_slug", "gameSlug is your game's slug, as its Zaisma link names it: 1 to 40 lowercase letters, digits or hyphens, like \"my-game\"."));
+    var playerToken = setUpOptions.playerToken === undefined ? null : setUpOptions.playerToken;
+    var isToken = typeof playerToken === "string" && playerToken.length > 0 && new TextEncoder().encode(playerToken).length <= MAXIMUM_PLAYER_TOKEN_SIZE_BYTES;
+    if (playerToken !== null && !isToken) return Promise.reject(codedError("bad_player_token", "playerToken is the player's token for your own server, as text up to 8 KB (a Sign in with Zaisma ID token, or your game's own), or null for a guest."));
+    offZaisma = { gameSlug: gameSlug, playerToken: playerToken };
+    return Promise.resolve({ isOffZaisma: true });
+  }
+
   /** The error for options a call doesn't take, naming the ones it does, or null when they're all fine. */
   function unknownOption(given, valid, call) {
     if (given === undefined || given === null) return null;
@@ -435,6 +476,8 @@
     // What this connection uses now: "webtransport" once the fast lane opens, else "websocket".
     this.transport = "websocket";
     this._pass = setup.pass;
+    // Off Zaisma: the hello carries the playerToken Zaisma.setUpOffZaisma holds now, so a reconnect uses a refreshed one.
+    this._isOffZaisma = setup.isOffZaisma === true;
     this._made = { isListed: this.isListed, friendJoinsEnabled: setup.friendJoinsEnabled === false ? false : undefined, name: setup.name, labels: setup.labels };
     this._joinData = setup.joinData === undefined ? null : setup.joinData;
     this._serverUrl = setup.serverUrl;
@@ -653,7 +696,7 @@
   };
 
   // Codes that mean this room won't take the player, so joining fails instead of trying again.
-  var REFUSED = ["room_full", "room_closed", "ended", "bad_pass", "too_big", "game_unavailable", "kept_out", "refused", "hosting_paused", "account_needed", "game_not_open_to_player", "blocked_player_here", "other_version", "spectators_full", "room_not_running", "already_playing", "bad_origin"];
+  var REFUSED = ["room_full", "room_closed", "ended", "bad_pass", "bad_player_token", "too_big", "game_unavailable", "kept_out", "refused", "hosting_paused", "account_needed", "game_not_open_to_player", "blocked_player_here", "other_version", "spectators_full", "room_not_running", "already_playing", "bad_origin"];
 
   /**
    * Whether a Zaisma room on another version (other_version) has the page reload the game at it: on the
@@ -685,7 +728,9 @@
       room.transport = isFastLane ? "webtransport" : "websocket";
       room._pingAtMs = room._pongAtMs = room._heardAtMs = Date.now();
       room._probeIntervalSec = null;
-      var hello = { type: "hello", protocolVersionNumber: PROTOCOL_VERSION_NUMBER, pass: room._pass, room: room._made, joinData: room._joinData, idleTimeoutSec: room._clientIdle.idleTimeoutSec, idleCheckEnabled: room._clientIdle.idleCheckEnabled };
+      var hello = { type: "hello", protocolVersionNumber: PROTOCOL_VERSION_NUMBER, room: room._made, joinData: room._joinData, idleTimeoutSec: room._clientIdle.idleTimeoutSec, idleCheckEnabled: room._clientIdle.idleCheckEnabled };
+      if (room._isOffZaisma) hello.playerToken = offZaisma.playerToken;
+      else hello.pass = room._pass;
       // quickJoin's first try at a room: rather another room than one with someone this player blocked.
       if (room._avoidsBlockedPlayers) hello.avoidBlockedPlayers = true;
       // Any quickJoin: Zaisma learns the game joins players by itself, for its Rooms tab.
@@ -795,6 +840,10 @@
       } else if (message.type === "ending_cancelled") {
         room.endsAt = null;
         room._emit("endingCancelled");
+      } else if (message.type === "room_message") {
+        // A room message for a room whose game server has no onRoomMessage: another room, the game server or the developer sent it.
+        var roomMessage = message.roomMessage || {};
+        room._emit("roomMessage", { message: roomMessage.message, senderKind: roomMessage.senderKind, fromRoomCode: roomMessage.fromRoomCode || null, sentAt: roomMessage.sentAt });
       } else if (message.type === "version_update") {
         var versionUpdate = { versionId: message.versionId, appliesAt: message.appliesAt, isReloading: message.isReloading === true };
         if (message.step === "now") room._isReloadingForVersion = versionUpdate.isReloading;
@@ -1523,7 +1572,9 @@
 
   function connect(roomCode, joinOptions, isRetry) {
     var serverUrl = joinOptions.serverUrl ? String(joinOptions.serverUrl).replace(/\/+$/, "") : null;
-    if (!serverUrl && !config.rooms) return Promise.reject(notOnZaisma("Player passes come from Zaisma, so rooms work only in games hosted on Zaisma, in Zaisma rooms or on your own server (serverUrl)."));
+    var offRefusal = offZaismaRefusal(serverUrl, "Zaisma.joinRoom");
+    if (offRefusal) return Promise.reject(offRefusal);
+    var isOffZaisma = !config.rooms;
     var idleTimeoutSec = joinOptions.idleTimeoutSec;
     if (idleTimeoutSec !== undefined && !(typeof idleTimeoutSec === "number" && idleTimeoutSec >= MINIMUM_IDLE_TIMEOUT_SEC && idleTimeoutSec <= MAXIMUM_IDLE_TIMEOUT_SEC)) return Promise.reject(codedError("bad_idle_timeout", "idleTimeoutSec runs from " + MINIMUM_IDLE_TIMEOUT_SEC + " to " + MAXIMUM_IDLE_TIMEOUT_SEC + "."));
     if (serverUrl && !SERVER_URL.test(serverUrl)) return Promise.reject(codedError("bad_server_url", "serverUrl takes a full address starting with wss://, ws://, https:// or http://, like \"wss://play.example.com\"."));
@@ -1535,12 +1586,14 @@
       : serverUrl
         ? Promise.resolve(randomRoomCode())
         : post("/v1/rooms", { gameSlug: config.game }).then(function (answer) { return answer.roomCode; });
-    return Promise.all([roomCodeReady, getPass()]).then(function (ready) {
+    // Off Zaisma there's no pass: the hello carries the playerToken instead.
+    return Promise.all([roomCodeReady, isOffZaisma ? null : getPass()]).then(function (ready) {
       var base = (serverUrl || config.rooms).replace(/^http/, "ws");
-      var path = "/v1/rooms/" + config.game + "/" + ready[0];
+      var path = "/v1/rooms/" + (isOffZaisma ? offZaisma.gameSlug : config.game) + "/" + ready[0];
       var room = new Room({
         roomCode: ready[0],
-        pass: ready[1].pass,
+        pass: isOffZaisma ? null : ready[1].pass,
+        isOffZaisma: isOffZaisma,
         url: base + path,
         // The fast lane reaches only the game's own secure servers: Zaisma's rooms take the WebSocket, whatever transport says.
         fastLaneUrl: joinOptions.transport === "webtransport" && serverUrl && OWN_SERVER_URL.test(serverUrl) ? serverUrl.replace(/^wss:/, "https:") + path : null,
@@ -1562,8 +1615,8 @@
         room._ready = { resolve: resolve, reject: reject };
         room._connect();
       }).catch(function (error) {
-        // A pass this tab kept from before Zaisma changed its keys: get a new one and try once more.
-        if (error.code !== "bad_pass" || isRetry) throw error;
+        // A pass this tab kept from before Zaisma changed its keys: get a new one and try once more. Off Zaisma, only the game can get a new token.
+        if (error.code !== "bad_pass" || isRetry || isOffZaisma) throw error;
         try { sessionStorage.removeItem(passKey); } catch (storageError) { /* fine */ }
         return connect(room.roomCode, joinOptions, true);
       });
@@ -1766,13 +1819,15 @@
 
   /**
    * A request to the game's own game server, its onRequest, outside any room: what it answered
-   * (zaisma.d.ts: Zaisma.server.request). The player's pass goes with it, so the server knows who's asking.
+   * (zaisma.d.ts: Zaisma.server.request). The player's pass goes with it, so the server knows who's asking;
+   * off Zaisma, the playerToken Zaisma.setUpOffZaisma holds.
    */
   function serverRequest(request, requestOptions, isRetry) {
     var refused = unknownOption(requestOptions, REQUEST_OPTIONS, "Zaisma.server.request");
     if (refused) return Promise.reject(refused);
     var serverUrl = requestOptions && requestOptions.serverUrl ? String(requestOptions.serverUrl).replace(/\/+$/, "") : null;
-    if (!serverUrl && !config.rooms) return Promise.reject(notOnZaisma("Player passes come from Zaisma, so Zaisma.server.request works only in games hosted on Zaisma, to Zaisma's servers or to your own (serverUrl)."));
+    var offRefusal = offZaismaRefusal(serverUrl, "Zaisma.server.request");
+    if (offRefusal) return Promise.reject(offRefusal);
     if (serverUrl && !SERVER_URL.test(serverUrl)) return Promise.reject(codedError("bad_server_url", "serverUrl takes a full address starting with https://, http://, wss:// or ws://, like \"https://play.example.com\"."));
     var requestText;
     try {
@@ -1783,13 +1838,17 @@
     if (requestText === undefined) return Promise.reject(codedError("bad_request", "A request is plain JSON: numbers, text, true or false, null, lists and plain objects, like { type: \"buy\", itemId: \"sword\" }."));
     if (new TextEncoder().encode(requestText).length > MAXIMUM_REQUEST_SIZE_BYTES) return Promise.reject(codedError("too_big", "Requests are up to 16 KB as JSON."));
     var base = (serverUrl || config.rooms).replace(/^ws/, "http");
-    return getPass().then(function (mine) {
-      return fetch(base + "/v1/requests/" + config.game, { method: "POST", headers: { "Content-Type": "text/plain" }, body: JSON.stringify({ pass: mine.pass, request: JSON.parse(requestText) }) }).then(answered, requestFailed);
+    var isOffZaisma = !config.rooms;
+    // Off Zaisma there's no pass: the playerToken goes in its place.
+    var sender = isOffZaisma ? Promise.resolve({ playerToken: offZaisma.playerToken }) : getPass().then(function (mine) { return { pass: mine.pass }; });
+    return sender.then(function (who) {
+      who.request = JSON.parse(requestText);
+      return fetch(base + "/v1/requests/" + (isOffZaisma ? offZaisma.gameSlug : config.game), { method: "POST", headers: { "Content-Type": "text/plain" }, body: JSON.stringify(who) }).then(answered, requestFailed);
     }).then(function (answer) {
       return answer.answer;
     }, function (error) {
-      // A pass this tab kept from before Zaisma changed its keys: get a new one and try once more.
-      if (error.code !== "bad_pass" || isRetry) throw error;
+      // A pass this tab kept from before Zaisma changed its keys: get a new one and try once more. Off Zaisma, only the game can get a new token.
+      if (error.code !== "bad_pass" || isRetry || isOffZaisma) throw error;
       try { sessionStorage.removeItem(passKey); } catch (storageError) { /* fine */ }
       return serverRequest(request, requestOptions, true);
     });
@@ -2694,5 +2753,5 @@
   });
 
   var friends = { list: listFriends, setRoom: setOwnRoom, sendRequest: sendFriendRequest };
-  window.Zaisma = { sdkVersionNumber: 1, gameSlug: config.game || null, player: player, joinRoom: joinRoom, rooms: rooms, server: server, invite: invite, checkChat: checkChat, openPlayersPanel: openPlayersPanel, links: links, items: items, friends: friends, saves: saves, versions: versions, page: zaismaPage };
+  window.Zaisma = { sdkVersionNumber: 1, gameSlug: config.game || null, player: player, setUpOffZaisma: setUpOffZaisma, joinRoom: joinRoom, rooms: rooms, server: server, invite: invite, checkChat: checkChat, openPlayersPanel: openPlayersPanel, links: links, items: items, friends: friends, saves: saves, versions: versions, page: zaismaPage };
 })();

package/src/chat.d.ts

@@ -9,6 +9,11 @@
  * checkChat sends the players' passes (as your server received them) and the sender's last few messages to
  * Zaisma (POST <issuer>/v1/chat/check), so a phone number sent a few digits at a time is caught too.
  *
+ * A player your server let in from outside Zaisma (kind outside_zaisma) has no pass: give null in their place.
+ * Zaisma counts them as strangers of unknown age, so a message between one and an under-18 account is stopped
+ * (not_allowed_to_chat); between them and adults it's checked as between adults. A message among players from
+ * outside Zaisma only is allowed without asking Zaisma: none of its players is in it, so your own rules apply.
+ *
  * It's for your own server only. In Zaisma rooms the room filters the chat it delivers itself, so a game
  * server running there never sees passes, and checkChat throws a ChatCheckError (own_server_only).
  */
@@ -36,10 +41,10 @@ export interface ChatCheck {
 export interface ChatCheckOptions {
     /** The message. */
     text: string;
-    /** The sender's player pass, the signed token as your server received it. */
-    senderPass: string;
-    /** The passes of everyone it would reach, up to 50. */
-    receiverPasses: string[];
+    /** The sender's player pass, the signed token as your server received it; null for a player from outside Zaisma. */
+    senderPass: string | null;
+    /** The passes of everyone it would reach, up to 50; null for each player from outside Zaisma. */
+    receiverPasses: (string | null)[];
     /** Check chat between adults too, as for under-18s; each message Zaisma's AI looks at counts on your hosting meter. False by default. */
     isAdultFilterEnabled?: boolean;
 }

package/src/chat.js

@@ -9,6 +9,11 @@
  * checkChat sends the players' passes (as your server received them) and the sender's last few messages to
  * Zaisma (POST <issuer>/v1/chat/check), so a phone number sent a few digits at a time is caught too.
  *
+ * A player your server let in from outside Zaisma (kind outside_zaisma) has no pass: give null in their place.
+ * Zaisma counts them as strangers of unknown age, so a message between one and an under-18 account is stopped
+ * (not_allowed_to_chat); between them and adults it's checked as between adults. A message among players from
+ * outside Zaisma only is allowed without asking Zaisma: none of its players is in it, so your own rules apply.
+ *
  * It's for your own server only. In Zaisma rooms the room filters the chat it delivers itself, so a game
  * server running there never sees passes, and checkChat throws a ChatCheckError (own_server_only).
  */
@@ -84,15 +89,26 @@ function rememberText(senderPlayerId, text, nowMs) {
 export async function checkChat({ text, senderPass, receiverPasses }) {
     // Read apart from the destructuring, which is v1's signature as it's locked (test/contracts).
     const isAdultFilterEnabled = arguments[0]?.isAdultFilterEnabled === true;
-    const claims = readClaims(String(senderPass ?? ""));
-    if (typeof claims.sub !== "string" || !isZaismaIssuer(claims.iss) || !Array.isArray(receiverPasses))
+    if (!Array.isArray(receiverPasses) || !receiverPasses.every((pass) => pass === null || typeof pass === "string") || !(senderPass === null || typeof senderPass === "string"))
         return UNCHECKED;
     const message = String(text ?? "");
     if (message.length > CHAT_CHECK_LIMITS.maximumMessageCharacterCount)
         return TOO_LONG;
+    // Among players from outside Zaisma only: no Zaisma player is in it, so the server's own rules apply, and Zaisma never hears of it.
+    const firstPass = [senderPass, ...receiverPasses].find((pass) => typeof pass === "string");
+    if (firstPass === undefined)
+        return { isAllowed: true, reason: null, message: null, hasSwearing: false, hasSlur: false };
+    // Where to ask comes from a pass, the sender's when they have one: they all come from the same issuer for the same game.
+    const claims = readClaims(firstPass);
+    const senderClaims = senderPass === null ? null : readClaims(senderPass);
+    if (typeof claims.sub !== "string" || !isZaismaIssuer(claims.iss) || (senderClaims && typeof senderClaims.sub !== "string"))
+        return UNCHECKED;
     const nowMs = Date.now();
-    const recentTexts = (recentBySender.get(claims.sub) ?? []).filter((sent) => nowMs - sent.sentAtMs < CHAT_CHECK_LIMITS.recentTextDurationMs).map((sent) => sent.text);
-    rememberText(claims.sub, message, nowMs);
+    // A sender from outside Zaisma has no player ID Zaisma knows, so their last messages aren't sent along.
+    const senderPlayerId = senderClaims ? senderClaims.sub : null;
+    const recentTexts = senderPlayerId ? (recentBySender.get(senderPlayerId) ?? []).filter((sent) => nowMs - sent.sentAtMs < CHAT_CHECK_LIMITS.recentTextDurationMs).map((sent) => sent.text) : [];
+    if (senderPlayerId)
+        rememberText(senderPlayerId, message, nowMs);
     try {
         const response = await fetch(`${claims.iss}/v1/chat/check`, {
             method: "POST",

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 ChatAnswer, type ChatInfo, 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 { BUSY_CLOSE_CODE, ENDED_CLOSE_CODE, GAME_SERVER_OPTIONS, GameServerError, NO_ANSWER_CLOSE_CODE, REMOVED_CLOSE_CODE, ROOM_LIMITS, ROOM_MESSAGE_LIMITS, ROOM_MESSAGE_SENDER_KINDS, 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 ChatAnswer, type ChatInfo, type JoinInfo, type KickOptions, type LiveRoom, 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 RoomMessage, type RoomMessageSenderKind, type RoomPlayer, type RoomSelection, 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";
@@ -7,4 +7,5 @@ export { OUTSIDE_CALL_LIMITS, OutsideCallError, type OutsideCallErrorCode } from
 export { PASS_ISSUER_URL, PASS_TOKEN_TYPE, PASS_VERSION_NUMBER, PassError, RECEIPT_ISSUER_URL, RECEIPT_TOKEN_TYPE, RECEIPT_VERSION_NUMBER, ReceiptError, canChat, passesAreFriends, passesHaveBlockBetween, verifyPass, verifyReceipt, type PassClaims, type PassErrorCode, type PassExpectations, type PlayerKind, type PublicKey, type ReceiptClaims, type ReceiptErrorCode, type ReceiptExpectations, type WhoCanChat } from "./pass.ts";
 export { CHAT_CHECK_LIMITS, CHAT_ROOM_LIMITS, ChatCheckError, checkChat, type ChatCheck, type ChatCheckOptions, type ChatCheckReason } from "./chat.ts";
 export { guestName, isRoomCode } from "./names.ts";
+export { guestPlayer, signInWithZaismaPlayers, type IdentifyPlayer, type OutsidePlayer, type SignInWithZaismaPlayersOptions } from "./outside-players.ts";
 export { relay } from "./relay.ts";

package/src/index.js

@@ -1,6 +1,6 @@
 // What @zaisma/game-server gives developers, named one by one: from v1 it only grows (test/contracts).
 // Zaisma's own parts of the package, never locked, are in ./internal.
-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, } from "./room.js";
+export { BUSY_CLOSE_CODE, ENDED_CLOSE_CODE, GAME_SERVER_OPTIONS, GameServerError, NO_ANSWER_CLOSE_CODE, REMOVED_CLOSE_CODE, ROOM_LIMITS, ROOM_MESSAGE_LIMITS, ROOM_MESSAGE_SENDER_KINDS, SEAT_GONE_CLOSE_CODE, VERSION_UPDATE_CLOSE_CODE, defineGameServer, } from "./room.js";
 export { REQUEST_LIMITS } from "./requests.js";
 export { SCHEDULE_LIMITS } from "./schedules.js";
 export { WEBHOOK_LIMITS, verifyWebhook } from "./webhooks.js";
@@ -9,4 +9,5 @@ export { OUTSIDE_CALL_LIMITS, OutsideCallError } from "./outside-calls.js";
 export { PASS_ISSUER_URL, PASS_TOKEN_TYPE, PASS_VERSION_NUMBER, PassError, RECEIPT_ISSUER_URL, RECEIPT_TOKEN_TYPE, RECEIPT_VERSION_NUMBER, ReceiptError, canChat, passesAreFriends, passesHaveBlockBetween, verifyPass, verifyReceipt } from "./pass.js";
 export { CHAT_CHECK_LIMITS, CHAT_ROOM_LIMITS, ChatCheckError, checkChat } from "./chat.js";
 export { guestName, isRoomCode } from "./names.js";
+export { guestPlayer, signInWithZaismaPlayers } from "./outside-players.js";
 export { relay } from "./relay.js";

package/src/internal.d.ts

@@ -5,6 +5,7 @@ export * from "./database.ts";
 export * from "./dump.ts";
 export * from "./requests.ts";
 export * from "./outside-calls.ts";
+export * from "./outside-players.ts";
 export * from "./schedules.ts";
 export * from "./webhooks.ts";
 export * from "./pass.ts";

package/src/internal.js

@@ -7,6 +7,7 @@ export * from "./database.js";
 export * from "./dump.js";
 export * from "./requests.js";
 export * from "./outside-calls.js";
+export * from "./outside-players.js";
 export * from "./schedules.js";
 export * from "./webhooks.js";
 export * from "./pass.js";

package/src/outside-players.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Players from outside Zaisma, for a game server on your own server: a game played anywhere but its Zaisma
+ * page (exported, on another site, wrapped for a store) has no Zaisma pass, so its game sends a playerToken
+ * instead (Zaisma.setUpOffZaisma) and your server says who that is with startServer's identifyPlayer. Such a
+ * player joins with kind "outside_zaisma", in the same rooms as players from the Zaisma page.
+ *
+ * signInWithZaismaPlayers makes an identifyPlayer for players signed in with Zaisma (Sign in with Zaisma's ID
+ * tokens): the same player ID and name as on Zaisma. guestPlayer is who a player with no token is, when
+ * startServer's outsideGuestsEnabled lets them in: a temporary ID and a generated name, like Zaisma's guests.
+ */
+import { type PublicKey } from "./pass.ts";
+/** Who a player from outside Zaisma is, as identifyPlayer answers: an ID your server keeps for them, and the name others see. */
+export interface OutsidePlayer {
+    /** 1 to 100 characters: a Zaisma player ID for a player signed in with Zaisma, or your own accounts' IDs. */
+    id: string;
+    /** 1 to 40 characters, as other players see it. */
+    name: string;
+}
+/** startServer's identifyPlayer: who a playerToken is, or null when it isn't one your server takes. */
+export type IdentifyPlayer = (playerToken: string, connection: {
+    origin: string | null;
+}) => Promise<OutsidePlayer | null>;
+export interface SignInWithZaismaPlayersOptions {
+    /** Your sign-in apps' IDs (sign_in_app_…), 1 to 20: an ID token for any other app is refused. */
+    signInAppIds: string[];
+    /** Where Sign in with Zaisma runs, the ID tokens' iss: https://zaisma.com unless a local preview of Zaisma. */
+    siteUrl?: string;
+    /** async (isRefreshing) => the ID token keys; by default from <siteUrl>/.well-known/jwks.json, fetched again once on a key it doesn't know. */
+    loadKeys?: (isRefreshing: boolean) => Promise<PublicKey[]>;
+    /** async (playerId) => an account's public profile or null, for a token with no name (signed in without the profile scope). */
+    loadProfile?: (playerId: string) => Promise<{
+        name: string;
+    } | null>;
+}
+export declare const OUTSIDE_PLAYER_LIMITS: {
+    readonly maximumIdCharacterCount: 100;
+    readonly maximumSignInAppCount: 20;
+    /** How far an ID token's exp may be past, for clocks that differ a little. */
+    readonly clockLeewaySec: 60;
+    /** How long the keys and profiles are kept before they're fetched again. */
+    readonly keysKeptMs: 3600000;
+    readonly profileKeptMs: 300000;
+    /** A refresh for a key ID it doesn't know waits this long after the last fetch, so made-up key IDs can't make it fetch on every token. */
+    readonly minimumRefreshIntervalMs: 30000;
+    readonly maximumProfileCount: 10000;
+};
+/**
+ * An identifyPlayer for players signed in with Zaisma: the game signs them in with Sign in with Zaisma and
+ * sends the ID token as its playerToken. The token is checked like any OpenID Connect ID token: RS256 only,
+ * signed by Zaisma's published key, its iss the siteUrl, its aud one of signInAppIds, not expired. The player
+ * is { id, name }: the account's Zaisma player ID, the same as on Zaisma, and its name from the token (or its
+ * public profile when the token has none). Answers null for any token that doesn't check out, and for an
+ * account deleted since; throws only when Zaisma's keys or profiles can't be reached (the runner answers busy).
+ *
+ *   startServer({ gameServer, gameSlug, identifyPlayer: signInWithZaismaPlayers({ signInAppIds: ["sign_in_app_8f3k2m"] }) });
+ */
+export declare function signInWithZaismaPlayers(options: SignInWithZaismaPlayersOptions): IdentifyPlayer;
+/** A player with no token, when startServer's outsideGuestsEnabled lets them in: a temporary player ID and a generated name, as Zaisma's guests have. */
+export declare function guestPlayer(): OutsidePlayer;
+/** What identifyPlayer answered, checked for the runner: the player, with their name tidied, or what was wrong with it. */
+export declare function checkedOutsidePlayer(given: unknown): {
+    player: OutsidePlayer;
+} | {
+    mistake: string;
+};