@zaisma/game-server 1.5.0 → 1.7.0

package/src/index.js

@@ -7,6 +7,6 @@ export { WEBHOOK_LIMITS, verifyWebhook } from "./webhooks.js";
 export { DATABASE_LIMITS, DatabaseError } from "./database.js";
 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, ChatCheckError, checkChat } from "./chat.js";
+export { CHAT_CHECK_LIMITS, CHAT_ROOM_LIMITS, ChatCheckError, checkChat } from "./chat.js";
 export { guestName, isRoomCode } from "./names.js";
 export { relay } from "./relay.js";

package/src/pass.d.ts

@@ -28,9 +28,9 @@ export interface PassClaims {
      */
     who_can_chat?: WhoCanChat | (string & {});
     /**
-     * For accounts that chat with anyone, the group they can chat in (chat_group_…): two such players
-     * chat when their groups match (canChat). Opaque and different in every game, so it never says an
-     * age; a game could guess which group is the younger one from its size.
+     * For accounts that chat at all (friends or anyone), the group they can chat in (chat_group_…): two
+     * players chat only when their groups match (canChat), friends included. Opaque and different in every
+     * game, so it never says an age; a game could guess which group is the younger one from its size.
      */
     chat_group_id?: string;
     /**
@@ -88,11 +88,12 @@ export declare function passesHaveBlockBetween(first: PassClaims, second: PassCl
  */
 export declare function passesAreFriends(first: PassClaims, second: PassClaims): boolean;
 /**
- * Whether two players may chat, by the passes your server checked (verifyPass): both accounts, no block
- * between them, neither letting nobody chat, and either friends or both letting anyone chat, in the same
- * chat group. Guests and accounts set to nobody never chat; accounts set to friends chat only with
- * friends (passesAreFriends). Use it on every message your own server delivers, text or voice; Zaisma's
- * chat check (checkChat) applies the same rule, and Zaisma rooms will do the same for you.
+ * Whether two players may chat, by the passes your server checked (verifyPass): both accounts in the same
+ * chat group, no block between them, neither letting nobody chat, and either friends or both letting
+ * anyone chat. Guests and accounts set to nobody never chat; accounts set to friends chat only with
+ * friends (passesAreFriends); friends in different chat groups don't chat. Use it on every message your
+ * own server delivers, text or voice; Zaisma's chat check (checkChat) applies the same rule, and so do
+ * rooms (room.chat), on Zaisma and in the runner.
  */
 export declare function canChat(first: PassClaims, second: PassClaims): boolean;
 export type PublicKey = JsonWebKey & {

package/src/pass.js

@@ -44,11 +44,12 @@ export function passesAreFriends(first, second) {
     return lists(first, second) && lists(second, first);
 }
 /**
- * Whether two players may chat, by the passes your server checked (verifyPass): both accounts, no block
- * between them, neither letting nobody chat, and either friends or both letting anyone chat, in the same
- * chat group. Guests and accounts set to nobody never chat; accounts set to friends chat only with
- * friends (passesAreFriends). Use it on every message your own server delivers, text or voice; Zaisma's
- * chat check (checkChat) applies the same rule, and Zaisma rooms will do the same for you.
+ * Whether two players may chat, by the passes your server checked (verifyPass): both accounts in the same
+ * chat group, no block between them, neither letting nobody chat, and either friends or both letting
+ * anyone chat. Guests and accounts set to nobody never chat; accounts set to friends chat only with
+ * friends (passesAreFriends); friends in different chat groups don't chat. Use it on every message your
+ * own server delivers, text or voice; Zaisma's chat check (checkChat) applies the same rule, and so do
+ * rooms (room.chat), on Zaisma and in the runner.
  */
 export function canChat(first, second) {
     mustBePasses(first, second, "canChat");
@@ -59,9 +60,10 @@ export function canChat(first, second) {
     const isOpenTo = (whoCanChat) => whoCanChat === "friends" || whoCanChat === "anyone";
     if (!isOpenTo(first.who_can_chat) || !isOpenTo(second.who_can_chat))
         return false;
-    if (passesAreFriends(first, second))
-        return true;
-    return first.who_can_chat === "anyone" && second.who_can_chat === "anyone" && typeof first.chat_group_id === "string" && first.chat_group_id === second.chat_group_id;
+    // Chat never leaves a chat group, friends included.
+    if (typeof first.chat_group_id !== "string" || first.chat_group_id !== second.chat_group_id)
+        return false;
+    return passesAreFriends(first, second) || (first.who_can_chat === "anyone" && second.who_can_chat === "anyone");
 }
 // Plain class fields (no TypeScript-only syntax) so Node can run this file directly.
 export class PassError extends Error {

package/src/room.d.ts

@@ -7,7 +7,7 @@
  * running one copy of the game server. Names follow docs/NAMING.md.
  */
 import { type GameDatabase } from "./database.ts";
-import type { PlayerKind, ReceiptClaims } from "./pass.ts";
+import type { PassClaims, PlayerKind, ReceiptClaims } from "./pass.ts";
 import type { Server } from "./requests.ts";
 import { type Schedule, type ScheduledRun } from "./schedules.ts";
 import { type StateChange } from "./state-sync.ts";
@@ -409,6 +409,13 @@ export interface GameServer<S = any> {
      * Off by default. The state goes as JSON, so keep it plain; cut what each player sees with stateView.
      */
     stateSyncEnabled?: boolean;
+    /**
+     * Check chat between adults (room.chat) with Zaisma's filter too: contact details, moving apps or
+     * meeting up, personal details and sexual content are stopped, as they always are for under-18s. Off by
+     * default, when chat between adults is only flagged (hasSwearing, hasSlur) and your game decides. Each
+     * message the filter's AI looks at counts on your hosting meter (adult_chat_checks).
+     */
+    adultChatFilterEnabled?: boolean;
     /**
      * How often a real-time room saves its state, in seconds: 1 to 60, default 5. A restarted room comes
      * back with the last saved state (onRestored). Turn-based rooms save after every change and ignore it.
@@ -473,6 +480,16 @@ export interface GameServer<S = any> {
      * joinInfo.fromRoomCode, and not again when they arrive.
      */
     canJoin?(state: S, player: Player, room: Room, joinData: unknown, joinInfo: JoinInfo): JoinAnswer | Promise<JoinAnswer>;
+    /**
+     * A player sent a chat message (room.chat in their game), before Zaisma's filter checks it: answer true
+     * to send it, false to stop it (the sender's room.chat fails with chat_stopped, reason stopped_by_game),
+     * or { toPlayerIds } to send it to only some of chatInfo.toPlayerIds, like a team chat or a player your
+     * moderators muted. chatInfo.toPlayerIds are the players the sender's game sent it to; whatever you
+     * answer, it reaches only those of them who may chat with the sender, never anyone else. Only decide
+     * here, as in canJoin: room can be read, not changed. Without onChat every message goes on to the
+     * filter. If it throws or answers anything else, the message is stopped and the mistake is logged.
+     */
+    onChat?(state: S, player: Player, room: Room, chatInfo: ChatInfo): ChatAnswer | Promise<ChatAnswer>;
     /** After room.moveTo: who the other room took, and who it turned away and why. */
     onMoved?(state: S, moveResult: MoveResult, room: Room): HandlerResult<S>;
     /**
@@ -581,6 +598,29 @@ export declare function restoreInfoOf(savedAtMs: number, nowMs?: number, savedVe
 export type JoinAnswer = boolean | {
     refusalMessage: string;
 };
+/** A chat message as onChat sees it: what the player typed, and the players their game sent it to. */
+export interface ChatInfo {
+    text: string;
+    toPlayerIds: string[];
+}
+/**
+ * What onChat answers: true sends the message on to Zaisma's filter; false stops it; { toPlayerIds }
+ * sends it to only those of chatInfo.toPlayerIds (it can narrow who reads it, never widen it).
+ */
+export type ChatAnswer = boolean | {
+    toPlayerIds: string[];
+};
+/** What the sender hears when the game server's onChat stopped their message. */
+export declare const STOPPED_BY_GAME_MESSAGE = "Your message wasn't sent.";
+/** onChat's answer as the room acts on it: send (to toPlayerIds, or all it was sent to when null), or stop. Anything else is a mistake, and stops it. */
+export declare function readChatAnswer(answer: unknown): {
+    isAllowed: true;
+    toPlayerIds: string[] | null;
+} | {
+    isAllowed: false;
+} | {
+    mistake: GameServerError;
+};
 /**
  * canJoin's answer as the room acts on it: let in, or turn away with a refusalMessage (null for the
  * usual one). Answering nothing or anything else is a mistake (bad_handler_answer), described for the game server's errors.
@@ -594,7 +634,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", "maximumRoomCountPerPlayer", "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 GAME_SERVER_OPTIONS: readonly ["maximumPlayerCount", "maximumSpectatorCount", "ticksPerSec", "hostControlsEnabled", "idleCheck", "idleTimeoutSec", "awayMode", "seatHoldDurationSec", "stateSyncEnabled", "adultChatFilterEnabled", "reconnectTimeoutSec", "maximumRoomCountPerPlayer", "stateSaveIntervalSec", "setup", "onJoin", "canJoin", "onChat", "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;
@@ -774,6 +814,13 @@ export interface RoomSettings {
  * isSpectator: true, and they get the players, the state and every message sent to everyone, but they send
  * nothing: only probe answers, and anything else gets spectator_cannot_send. welcome and every "room"
  * message carry spectatorCount, and a "room" message goes out whenever it changes.
+ *
+ * Chat (room.chat): a client sends {type: "chat", chatNumber, text, toPlayerIds?}, which the room's host
+ * handles before the game's messages (readChatMessage, then startChat, Zaisma's filter, and deliverChat
+ * or stopChat). Each player it reaches gets {type: "chat", fromPlayerId, text, hasSwearing, hasSlur,
+ * sentAt}; the sender gets {type: "chat_sent", chatNumber, sentAt}, {type: "chat_stopped", chatNumber,
+ * reason, message}, or an error with its chatNumber (chat_not_allowed, chat_empty, chat_too_long,
+ * chat_too_fast). chat_sent never says who read it. welcome says canChat: whether this player can chat at all.
  */
 export type ServerMessage = {
     type: "welcome";
@@ -787,6 +834,7 @@ export type ServerMessage = {
     endsAt: string | null;
     probeIntervalSec: number | null;
     protocolVersionNumber: number;
+    canChat: boolean;
 } | {
     type: "probe";
     probeNumber: number;
@@ -835,11 +883,28 @@ export type ServerMessage = {
 } | {
     type: "blocks";
     playerIds: string[];
+} | {
+    type: "chat";
+    fromPlayerId: string;
+    text: string;
+    hasSwearing: boolean;
+    hasSlur: boolean;
+    sentAt: string;
+} | {
+    type: "chat_sent";
+    chatNumber: number;
+    sentAt: string;
+} | {
+    type: "chat_stopped";
+    chatNumber: number;
+    reason: string;
+    message: string;
 } | {
     type: "error";
     code: RoomErrorCode;
     message: string;
     versionId?: string;
+    chatNumber?: number;
 } | {
     type: "ended";
     message: string;
@@ -863,6 +928,11 @@ export type ClientMessage = {
 } | {
     type: "message";
     data: unknown;
+} | {
+    type: "chat";
+    chatNumber: number;
+    text: string;
+    toPlayerIds?: string[];
 } | {
     type: "zaisma:purchase";
     purchaseId: string;
@@ -902,7 +972,7 @@ export type ClientMessage = {
  * the game became unavailable, its kept room was deleted, or no players were left for its spectators.
  */
 export type EndReason = "game" | "hosting_paused" | "game_server_stopped" | "game_unavailable" | "kept_room_deleted" | "no_players";
-export type RoomErrorCode = "room_full" | "room_closed" | "ended" | "too_big" | "too_fast" | "bad_message" | "bad_pass" | "no_hello" | "not_allowed" | "game_unavailable" | "busy" | "kept_out" | "refused" | "room_not_running" | "hosting_paused" | "account_needed" | "game_not_open_to_player" | "blocked_player_here" | "other_version" | "spectators_full" | "spectator_cannot_send" | "already_playing" | "bad_origin" | "send_queue_full";
+export type RoomErrorCode = "room_full" | "room_closed" | "ended" | "too_big" | "too_fast" | "bad_message" | "bad_pass" | "no_hello" | "not_allowed" | "game_unavailable" | "busy" | "kept_out" | "refused" | "room_not_running" | "hosting_paused" | "account_needed" | "game_not_open_to_player" | "blocked_player_here" | "other_version" | "spectators_full" | "spectator_cannot_send" | "already_playing" | "bad_origin" | "send_queue_full" | "chat_not_here" | "chat_not_allowed" | "chat_empty" | "chat_too_long" | "chat_too_fast";
 export declare const ERROR_TEXT: Record<RoomErrorCode, string>;
 /** What players are told when Zaisma ends a match at room.endsAt. */
 export declare 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.";
@@ -928,6 +998,8 @@ export interface SavedRoom extends RoomSettings {
     sessionBlocks?: [string, string][];
     /** Friendships between the room's players, as pairs of player IDs. */
     friendships?: [string, string][];
+    /** Who each account player the room remembers may chat with, by player ID. */
+    chatSettings?: Record<string, PlayerChatSettings>;
     /** When Zaisma will end the match (room.endsAt), once it's set. */
     endsAt?: string;
     /** Kept (room.setKept): it sleeps with its state when everyone leaves, instead of going a day later. */
@@ -1011,7 +1083,33 @@ export declare function checkRoomData(given: unknown, maximumSizeBytes: number):
  */
 export declare function errorMessage(code: RoomErrorCode, message?: string, details?: {
     versionId: string;
+} | {
+    chatNumber: number;
 }): string;
+/**
+ * Who an account player may chat with, from their pass (who_can_chat and chat_group_id): kept by the
+ * room's host, never shown to the game. A guest has none and chats with nobody.
+ */
+export interface PlayerChatSettings {
+    whoCanChat: "nobody" | "friends" | "anyone";
+    chatGroupId: string | null;
+}
+/** A checked pass's chat settings, for RoomCore.setChatSettings: null for a guest. A setting this version doesn't know chats with nobody. */
+export declare function chatSettingsOf(claims: PassClaims): PlayerChatSettings | null;
+/** A chat message from a client as readChatMessage found it, for startChat to check. */
+export interface ChatClientMessage {
+    chatNumber: number;
+    text: unknown;
+    toPlayerIds: unknown;
+    sizeBytes: number;
+}
+/** Room traffic of chat, in the room's message types. */
+export declare const CHAT_MESSAGE_TYPE = "(chat)";
+/**
+ * A client's chat message ({type: "chat"}), or null for any other text, which goes to receive. The
+ * room's host handles chat before receive, since Zaisma's filter runs between the room and the players.
+ */
+export declare function readChatMessage(text: string): ChatClientMessage | null;
 /** Whether a player may come in, and if not, why. */
 export type Admission = {
     isAllowed: true;
@@ -1163,6 +1261,12 @@ export declare class RoomCore<S = any> {
     private readonly sessionBlocks;
     /** Friendships between players from their accounts (Zaisma's own record, or passes on your own server): pairKey(first, second). */
     private readonly friendships;
+    /** Who each account player may chat with, from their pass: never in Player, so games never see it. */
+    private readonly chatSettings;
+    /** When each player sent their chat messages in the last CHAT_ROOM_LIMITS.chatWindowDurationMs. */
+    private readonly chatSentAtMs;
+    /** Each player's last chat messages, for Zaisma's filter to read pieces together: in memory only. */
+    private readonly recentChats;
     /** The blocks each player was last told of, so they're told again only when theirs change. */
     private readonly toldBlocks;
     /** When each player in the match was last heard from, when their game was hidden, and the idle check their game asked for. */
@@ -1190,6 +1294,8 @@ export declare class RoomCore<S = any> {
     private readonly api;
     /** The room as canJoin and stateView see it: reading works, and any call that changes or sends throws room_call_unavailable. */
     private readonly canJoinRoom;
+    /** The room as onChat sees it: reading only, like canJoin. */
+    private readonly chatRoom;
     private readonly stateViewRoom;
     readonly server: GameServer<S>;
     private readonly transport;
@@ -1259,6 +1365,45 @@ export declare class RoomCore<S = any> {
      * room knew of that player's, so a friend removed since is gone. Call before join.
      */
     setFriends(playerId: string, friendPlayerIds: readonly string[]): void;
+    /** A player's chat settings from their pass, before join: null for a guest, who chats with nobody. */
+    setChatSettings(playerId: string, settings: PlayerChatSettings | null): void;
+    /** Whether a player can chat at all: an account whose setting isn't nobody, with a chat group. */
+    canChat(playerId: string): boolean;
+    /**
+     * Whether one player's chat may reach another, canChat's rule on passes (pass.ts): two accounts in the
+     * same chat group with no block either way, friends unless both chat with anyone.
+     */
+    private mayChat;
+    /** Who a player's chat may reach: the players in the match (or those of toPlayerIds in it), never spectators, kept only where they may chat. */
+    chatReceivers(senderPlayerId: string, toPlayerIds?: readonly string[]): string[];
+    /**
+     * A chat message from a player (readChatMessage), checked by the room: the sender, the text, their pace,
+     * then the game server's onChat with the players their game sent it to. When it goes no further the room
+     * answers the sender itself (an error, or chat_stopped with stopped_by_game) and this is null. Otherwise
+     * it's the text, who may read it (chatReceivers, which may be nobody) and the sender's last messages, for
+     * the host to run Zaisma's filter and then deliverChat or stopChat.
+     */
+    startChat(playerId: string, chat: ChatClientMessage): Promise<{
+        text: string;
+        receiverPlayerIds: string[];
+        recentTexts: string[];
+    } | null>;
+    /**
+     * Send a chat message Zaisma's filter let through to its receivers, and tell the sender it went
+     * (chat_sent), even when it reached nobody: the sender never learns who can't read them.
+     */
+    deliverChat(senderPlayerId: string, chatNumber: number, receiverPlayerIds: readonly string[], chat: {
+        text: string;
+        hasSwearing: boolean;
+        hasSlur: boolean;
+    }): void;
+    /** Tell the sender their chat message was stopped: reason is the filter's, or stopped_by_game; message is what they see. */
+    stopChat(senderPlayerId: string, chatNumber: number, reason: string, message: string): void;
+    /** A player's chat messages from the last CHAT_CHECK_LIMITS.recentTextDurationMs, oldest first, up to recentTextCount. */
+    recentChatTexts(playerId: string): string[];
+    private rememberChat;
+    /** Whether a player may send another chat message: CHAT_ROOM_LIMITS.maximumChatMessageCount in any chatWindowDurationMs. */
+    private takeChat;
     /** Whether two players have a block between them, either way: from their accounts, or one a player's game said it made. */
     hasBlockBetween(firstPlayerId: string, secondPlayerId: string): boolean;
     /**