@memizy/host-sdk 0.0.0-stage → 1.0.0-rc.6

package/dist/src/relay/host.d.ts

@@ -0,0 +1,156 @@
+import { CreateRoomResponse, RelayErrorCode, RoomPlayer } from '@memizy/protocol';
+import { LocalSession, PluginEndpoint } from '../session.js';
+import { PreparedSet } from '../plugin.js';
+import { RelayStatus } from './socket.js';
+import { RemoteLobbyState } from './messages.js';
+export type RelayHostEvent = {
+    type: 'status';
+    status: RelayStatus;
+} | {
+    type: 'players';
+    players: RoomPlayer[];
+}
+/** A continued game: who has which place changed. */
+ | {
+    type: 'seats';
+    seats: HostSeat[];
+} | {
+    type: 'error';
+    code: RelayErrorCode;
+    message: string;
+} | {
+    type: 'closed';
+    reason: string;
+};
+export interface RelayHostOptions {
+    /** Server base URL, e.g. `https://mp.memizy.com`. */
+    serverUrl: string;
+    fetch?: typeof fetch;
+    WebSocket?: typeof WebSocket;
+    /** How long a player device may take to load the game (default 20 s). */
+    mountTimeoutMs?: number;
+    /** Timeout of one call to a remote plugin (default 15 s). */
+    callTimeoutMs?: number;
+}
+/** A place in a continued game: an earlier player and the room player who has it now. */
+export interface HostSeat {
+    /** The player ID in the session (from the saved game). */
+    id: string;
+    name: string;
+    /** The room player on this place (`RoomPlayer.id`), or `null` when it is free. */
+    roomPlayerId: string | null;
+}
+export interface AttachOptions {
+    /**
+     * A continued (saved) game: the session's players are the places of the earlier
+     * game, with their old IDs (the game state refers to them). Room players take a
+     * place on their device (or join as new players when the game allows late joins);
+     * the host can change it with `assignSeat`. Until then a place is disconnected.
+     */
+    seats?: boolean;
+    /** Places already taken (room player ID -> session player ID), e.g. after a reload of the host page. */
+    taken?: Record<string, string>;
+}
+export declare class RelayHost {
+    readonly pin: string;
+    readonly hostToken: string;
+    players: RoomPlayer[];
+    /** The lobby/game state shown by the player apps. */
+    state: RemoteLobbyState;
+    private readonly options;
+    private readonly socket;
+    private readonly listeners;
+    private readonly channels;
+    private bundleVersion;
+    private genCounter;
+    private callCounter;
+    private session;
+    private hosting;
+    private readonly hostingWaiters;
+    private stopSession;
+    /** The place of each room player in the session: room player ID -> session player ID. */
+    private readonly seatOf;
+    /** A continued game (see `AttachOptions.seats`). */
+    private seatsMode;
+    /** The app message version of each player's app (from its `hello`; 0 = an app before versions). */
+    private readonly appVersions;
+    private constructor();
+    /** Creates a new room on the server. */
+    static create(options: RelayHostOptions): Promise<RelayHost>;
+    /** Re-attaches to an existing room (e.g. after a reload of the host page). */
+    static rejoin(options: RelayHostOptions, room: CreateRoomResponse): RelayHost;
+    /** Resolves once the server confirmed the room and sent the current players. */
+    whenHosting(): Promise<void>;
+    get status(): RelayStatus;
+    on(listener: (event: RelayHostEvent) => void): () => void;
+    private emit;
+    /**
+     * Uploads the plugin and its set for the players' devices. Only `prepared.publicSet`
+     * (items without answers, SPEC 4.4) leaves this machine: anyone with the PIN can
+     * download the bundle. Prepare the set with the seed passed as `shuffleSeed`.
+     */
+    uploadBundle(pluginHtml: string, prepared: PreparedSet): Promise<number>;
+    /** Allows or stops new players joining. */
+    setOpen(open: boolean): void;
+    kick(playerId: string): void;
+    /** Closes the room for everyone. */
+    close(): void;
+    /**
+     * Leaves the room without closing it (the page is going away). The room and its
+     * players stay on the server, so the host can come back (reload) or take it over.
+     */
+    disconnect(): void;
+    /** Updates the lobby/game state shown by the player apps. */
+    setState(update: Partial<RemoteLobbyState>): void;
+    /**
+     * Connects the session's remote players and keeps the session in sync with the
+     * room: presence, late joins, reconnects, renames and kicks. In a new game the
+     * session's players are room players (same IDs); for a continued game pass
+     * `{ seats: true }` (see `AttachOptions`).
+     */
+    attach(session: LocalSession, options?: AttachOptions): void;
+    /** Disconnects from the session; player devices return to the lobby. */
+    detach(): void;
+    /** The places of a continued game and who has them (empty for a new game). */
+    get seats(): HostSeat[];
+    /** Which room player has which place (room player ID -> session player ID); keep it to re-attach after a reload. */
+    get seatAssignments(): Record<string, string>;
+    /**
+     * A continued game: puts a room player on a place (`seatId` = a session player ID from the
+     * saved game; `null` = takes the place away). Whoever had that place before loses it.
+     */
+    assignSeat(roomPlayerId: string, seatId: string | null): void;
+    /**
+     * The app message version of a room player's app (`RELAY_APP_VERSION` of its host-sdk), or
+     * `null` before it said hello. An app below 1 cannot choose its place: the host assigns it.
+     */
+    appVersionOf(playerId: string): number | null;
+    private relayIdOf;
+    private seatState;
+    private seatsChanged;
+    /** Tells a device its place (and the place's nickname). */
+    private sendSeat;
+    private seat;
+    private unseat;
+    /** A device chose its place in a continued game (or to join as a new player). */
+    private claim;
+    private onSessionEvent;
+    private connectRemote;
+    /** A session endpoint whose plugin instance runs on the player's device. */
+    endpointFor(playerId: string): PluginEndpoint;
+    private sendMount;
+    private remotePlugin;
+    private callRemote;
+    private channel;
+    private resetChannel;
+    /** Calls to a device that went away are dropped (resolved), like messages. */
+    private settleCalls;
+    private onServer;
+    private onPresence;
+    /** A message of the device of room player `relayId`; game messages go to its place in the session. */
+    private onPlayer;
+    private sendTo;
+    /** Sends to the device on a place of the session (dropped when the place is free). */
+    private sendToSeat;
+    private broadcast;
+}

package/dist/src/relay/messages.d.ts

@@ -0,0 +1,137 @@
+import { Player, SessionResult } from '@memizy/protocol';
+/**
+ * Version of the messages between the host app and the player apps. Within one relay
+ * protocol they only change additively: receivers ignore unknown `k` and unknown fields,
+ * and an app that sends nothing is version 0. Player apps send it in `hello`, hosts in
+ * `mount`, so each side knows what the other understands (e.g. a cached older player app).
+ *
+ * 1 – places in a continued game (`seat` / `claim`), `UNKNOWN_METHOD` errors.
+ */
+export declare const RELAY_APP_VERSION = 1;
+export type RemotePhase = 'lobby' | 'loading' | 'countdown' | 'running' | 'ended';
+export interface RemoteLobbyState {
+    phase: RemotePhase;
+    appName: string | null;
+    players: Player[];
+    /** Seconds left while counting down. */
+    countdown?: number;
+    /** Whether the authority is reachable (false = "waiting for the host"). */
+    authorityConnected: boolean;
+    result?: SessionResult;
+    /**
+     * A continued (saved) game: the places of the earlier players. A device takes one
+     * (`claim`) or the host assigns it; `taken` places have a device.
+     */
+    seats?: RemoteSeat[];
+    /** A continued game: whether a device may also join as a new player (late join, space left). */
+    newPlayers?: boolean;
+}
+/** A place of a player in a continued game (the earlier player's ID and nickname). */
+export interface RemoteSeat {
+    id: string;
+    name: string;
+    taken: boolean;
+}
+export type SerializedError = {
+    message: string;
+};
+export type HostToPlayer = 
+/** Lobby / game state for the player app's own screens. */
+{
+    k: 'state';
+    state: RemoteLobbyState;
+}
+/**
+ * Create (or recreate) the plugin instance; download the bundle if its version changed.
+ * `locale` is the host's language (informational: player apps use their own); `v` = RELAY_APP_VERSION.
+ */
+ | {
+    k: 'mount';
+    gen: number;
+    bundle: number;
+    locale: string;
+    v?: number;
+}
+/** Remove the plugin instance. */
+ | {
+    k: 'unmount';
+}
+/** A continued game: the place of this device (`null` = none yet) and its nickname. */
+ | {
+    k: 'seat';
+    seat: string | null;
+    name?: string;
+}
+/** A PluginApi call. */
+ | {
+    k: 'call';
+    id: number;
+    gen: number;
+    method: string;
+    args: unknown[];
+}
+/** Result of a HostApi call. `hostNow` comes with `hello` (clock sync). */
+ | {
+    k: 'result';
+    id: number;
+    ok: true;
+    value: unknown;
+    hostNow?: number;
+} | {
+    k: 'result';
+    id: number;
+    ok: false;
+    error: SerializedError;
+};
+export type PlayerToHost = 
+/** After (re)joining: the generation of the plugin instance still alive (0 = none); `v` = RELAY_APP_VERSION. */
+{
+    k: 'hello';
+    gen: number;
+    v?: number;
+}
+/** A continued game: take the place `seat`, or join as a new player (`null`). */
+ | {
+    k: 'claim';
+    seat: string | null;
+}
+/** The plugin instance `gen` connected (Penpal handshake done). */
+ | {
+    k: 'mounted';
+    gen: number;
+} | {
+    k: 'mount-failed';
+    gen: number;
+    error: SerializedError;
+}
+/** A HostApi call of instance `gen`. */
+ | {
+    k: 'call';
+    id: number;
+    gen: number;
+    method: string;
+    args: unknown[];
+}
+/** Result of a PluginApi call. */
+ | {
+    k: 'result';
+    id: number;
+    ok: true;
+    value: unknown;
+} | {
+    k: 'result';
+    id: number;
+    ok: false;
+    error: SerializedError;
+};
+export declare function serializeError(error: unknown): SerializedError;
+/** The error for a call whose method the receiving app does not know (an older or newer version). */
+export declare function unknownMethod(method: unknown): SerializedError;
+/** Blobs (getAsset) are not JSON: they travel as base64. */
+export interface SerializedBlob {
+    $blob: string;
+    type: string;
+}
+export declare function blobToJson(blob: Blob): Promise<SerializedBlob>;
+export declare function jsonToBlob(value: SerializedBlob): Blob;
+export declare function isSerializedBlob(value: unknown): value is SerializedBlob;

package/dist/src/relay/player.d.ts

@@ -0,0 +1,127 @@
+import { HostApi, HostConfig, PluginApi, RelayErrorCode } from '@memizy/protocol';
+import { RelayStatus } from './socket.js';
+import { RemoteLobbyState } from './messages.js';
+export type RelayPlayerEvent = {
+    type: 'status';
+    status: RelayStatus;
+} | {
+    type: 'joined';
+    playerId: string;
+    token: string;
+    name: string;
+} | {
+    type: 'state';
+    state: RemoteLobbyState;
+}
+/** A continued game: this device's place (`null` = choose one with `claimSeat`). */
+ | {
+    type: 'seat';
+    seat: string | null;
+} | {
+    type: 'host';
+    connected: boolean;
+}
+/** The plugin instance was created (`true`) or removed (`false`). */
+ | {
+    type: 'frame';
+    active: boolean;
+} | {
+    type: 'error';
+    code: RelayErrorCode | 'MOUNT_FAILED';
+    message: string;
+    fatal: boolean;
+} | {
+    type: 'closed';
+    reason: 'host' | 'expired' | 'kicked';
+};
+export interface RelayPlayerOptions {
+    serverUrl: string;
+    pin: string;
+    name: string;
+    /** Token from an earlier `joined` event: rejoin as the same player. */
+    token?: string;
+    /**
+     * Passed to the host only (e.g. a signed token of a signed-in student); the relay server
+     * does not check it. At most `RELAY_LIMITS.authLength` characters.
+     */
+    auth?: string;
+    /** Where the plugin iframe goes (called when the game starts). */
+    container: () => HTMLElement | null;
+    fetch?: typeof fetch;
+    WebSocket?: typeof WebSocket;
+    callTimeoutMs?: number;
+    /** Adjusts the downloaded plugin HTML before it runs (e.g. points the SDK import to a local build). */
+    transformHtml?: (html: string) => string;
+    /**
+     * Language and theme of this device. They replace the host's values, so every
+     * player sees the game in the language and theme of their own app.
+     */
+    config?: () => Partial<HostConfig>;
+    /** Creates the plugin instance (default: a sandboxed iframe; tests connect the SDK directly). */
+    createFrame?: FrameFactory;
+}
+export type FrameFactory = (html: string, title: string, hostApi: HostApi, doc: Document) => RemoteFrame;
+export interface RemoteFrame {
+    readonly iframe: HTMLElement;
+    readonly plugin: Promise<PluginApi>;
+    destroy(): void;
+}
+export declare class RelayPlayer {
+    playerId: string | null;
+    token: string | null;
+    name: string;
+    state: RemoteLobbyState | null;
+    hostConnected: boolean;
+    /** The app message version of the host (from `mount`; 0 = a host before versions, `null` = not known yet). */
+    hostAppVersion: number | null;
+    /**
+     * A continued game: this device's place in the game (`null` = not chosen yet;
+     * the free places are in `state.seats`). `undefined` in a new game.
+     */
+    seat: string | null | undefined;
+    private readonly options;
+    private readonly socket;
+    private readonly listeners;
+    private bundle;
+    private frame;
+    private plugin;
+    private gen;
+    /** The generation of the last `mount` taken (a repeated `mount` of it loads nothing new). */
+    private mountGen;
+    private callCounter;
+    private readonly pending;
+    /** Host clock minus local clock (ms). */
+    private skewMs;
+    /** The config the host sent last (before this device's overrides). */
+    private hostConfig;
+    private mountQueue;
+    /** The current game instance was told that its session ended (`sessionEnded`). */
+    private sessionEndedSent;
+    constructor(options: RelayPlayerOptions);
+    get status(): RelayStatus;
+    on(listener: (event: RelayPlayerEvent) => void): () => void;
+    private emit;
+    /** Call when this device's language or theme changed (see `config`). */
+    refreshConfig(): void;
+    private localConfig;
+    rename(name: string): void;
+    /**
+     * A continued game: takes the place `seat` (one of `state.seats`), or joins as a new
+     * player (`null`, when `state.newPlayers`). The host answers with a `seat` event; when
+     * the place was taken meanwhile, `seat` stays `null` and the device chooses again.
+     */
+    claimSeat(seat: string | null): void;
+    /** Reconnect right away (e.g. the page became visible again). */
+    reconnectNow(): void;
+    /** Leaves (the token stays valid for a rejoin until the room closes). */
+    leave(): void;
+    private onServer;
+    private up;
+    private onHost;
+    private ensureBundle;
+    /** Tells the game that its session ended (once, with a short grace period), then removes it. */
+    private endGame;
+    private mount;
+    private hostApiFor;
+    private destroyFrame;
+}

package/dist/src/relay/socket.d.ts

@@ -0,0 +1,34 @@
+import { RelayClientMessage, RelayServerMessage } from '@memizy/protocol';
+/** `replaced`: the same host or player connected from another tab or device; this one stops. */
+export type RelayStatus = 'connecting' | 'online' | 'offline' | 'closed' | 'replaced';
+export interface RelaySocketOptions {
+    /** `ws(s)://…/ws` */
+    url: string;
+    /** The attach message sent after every (re)connect. */
+    attach: () => RelayClientMessage;
+    WebSocket?: typeof WebSocket;
+}
+export declare class RelaySocket {
+    status: RelayStatus;
+    private readonly options;
+    private ws;
+    private retry;
+    private retryTimer;
+    private pingTimer;
+    private stopped;
+    private readonly messageListeners;
+    private readonly statusListeners;
+    constructor(options: RelaySocketOptions);
+    onMessage(listener: (msg: RelayServerMessage) => void): () => void;
+    onStatus(listener: (status: RelayStatus) => void): () => void;
+    /** Sends when online; returns `false` when the message was dropped. */
+    send(msg: RelayClientMessage): boolean;
+    /** Stops for good (no reconnect). */
+    close(): void;
+    /** Reconnects right away (e.g. when the page becomes visible again). */
+    reconnectNow(): void;
+    private setStatus;
+    private open;
+}
+/** `http(s)://server` → `ws(s)://server/ws` */
+export declare function relayWebSocketUrl(serverUrl: string): string;