@lokiplay/sdk 0.1.1 → 0.2.0

package/dist/index.js

@@ -1,8 +1,75 @@
 import { ClientEnvelopeSchema, ServerEnvelopeSchema, PROTOCOL_VERSION, } from "@lokiplay/protocol";
 import { Client, Session } from "@heroiclabs/nakama-js";
+import { SynchronizedRoom, } from "./synchronized-room.js";
+export { SYNCHRONIZED_ROOM_ACTION_TTL_MS, SYNCHRONIZED_ROOM_COMMIT_TIMEOUT_MS, SYNCHRONIZED_ROOM_MAX_MESSAGE_BYTES, SYNCHRONIZED_ROOM_MAX_PENDING, SYNCHRONIZED_ROOM_MAX_RECENT_ACTIONS, SYNCHRONIZED_ROOM_MAX_REDUCER_MS, SynchronizedRoom, SynchronizedRoomError, } from "./synchronized-room.js";
 export const LOKI_API_ORIGIN = "https://api.lokiplay.cc";
 const textDecoder = new TextDecoder();
 const payload = (response) => response.payload;
+export async function lokiErrorFromUnknown(error) {
+    if (typeof Response !== "undefined" && error instanceof Response) {
+        const status = error.status;
+        let detail = "";
+        try {
+            const text = await error.clone().text();
+            if (text) {
+                try {
+                    const parsed = JSON.parse(text);
+                    detail = parsed.message || parsed.error || text;
+                }
+                catch {
+                    detail = text;
+                }
+            }
+        }
+        catch {
+            // The body may already have been consumed by the transport.
+        }
+        return new Error(detail
+            ? `Loki request failed (${status}): ${detail}`
+            : `Loki request failed (${status})`);
+    }
+    if (error instanceof Error) {
+        if (error.message === "[object Response]") {
+            return new Error("Loki request failed");
+        }
+        return error;
+    }
+    if (error && typeof error === "object" && "status" in error) {
+        const status = Number(error.status);
+        return new Error(Number.isFinite(status) ? `Loki request failed (${status})` : "Loki request failed");
+    }
+    return new Error("Loki request failed");
+}
+const notifyListeners = (listeners, value) => {
+    for (const listener of listeners) {
+        try {
+            listener(value);
+        }
+        catch {
+            // Listener exceptions must not prevent remaining subscribers from running.
+        }
+    }
+};
+const protocolRejectionMessage = (message) => {
+    const text = message.trim() || "action rejected";
+    return text.length > 200 ? text.slice(0, 200) : text;
+};
+const wrapLokiCall = async (operation) => {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        throw await lokiErrorFromUnknown(error);
+    }
+};
+const normalizeInviteCode = (value) => value.trim().toUpperCase();
+const requireInviteCode = (value) => {
+    const inviteCode = normalizeInviteCode(value);
+    if (!/^[A-F0-9]{16}$/.test(inviteCode)) {
+        throw new Error("INVITE_INVALID: invite codes are 16 letters or digits issued by Loki");
+    }
+    return inviteCode;
+};
 export class LokiClient {
     #transport;
     #projectId;
@@ -10,8 +77,17 @@ export class LokiClient {
     #unsubscribe;
     #playerId;
     #roomId;
+    #joining = false;
+    #joinBuffer = [];
     #sendSequence = 0;
     #receiveSequence = 0;
+    #inviteCode = "";
+    #connectionListeners = new Set();
+    #unsubscribeConnection;
+    #lifecycle = Promise.resolve();
+    #lifecycleGeneration = 0;
+    #reconnectPromise;
+    #leaveFailed = false;
     constructor(options) {
         if (!/^[0-9a-f-]{36}$/i.test(options.projectId)) {
             throw new Error("invalid project id");
@@ -19,19 +95,51 @@ export class LokiClient {
         this.#projectId = options.projectId;
         this.#transport = options.transport;
     }
+    get playerId() {
+        return this.#playerId;
+    }
+    get roomId() {
+        return this.#roomId;
+    }
+    get inviteCode() {
+        return this.#inviteCode;
+    }
     initialize() {
         if (this.#unsubscribe)
             return;
         this.#unsubscribe = this.#transport.subscribe((raw) => {
             const message = ServerEnvelopeSchema.parse(raw);
-            if (message.roomId !== this.#roomId ||
-                message.sequence < this.#receiveSequence)
+            if (this.#joining) {
+                this.#joinBuffer.push(message);
                 return;
-            this.#receiveSequence = message.sequence;
-            for (const listener of this.#listeners)
-                listener(message);
+            }
+            this.#dispatch(message);
+        });
+        this.#unsubscribeConnection = this.#transport.subscribeConnection?.((event) => {
+            notifyListeners(this.#connectionListeners, event);
         });
     }
+    createSynchronizedRoom(options) {
+        if (!this.#unsubscribe)
+            this.initialize();
+        return new SynchronizedRoom({
+            playerId: () => this.#playerId,
+            sendAction: (payload, extras) => this.sendAction(payload, extras),
+            sendHostState: (expectedVersion, state, extras) => this.sendHostState(expectedVersion, state, extras),
+            sendActionRejection: (actionId, outcome, message, extras) => this.sendActionRejection(actionId, outcome, message, extras),
+            requestSnapshot: () => this.requestSnapshot(),
+            createRoom: () => this.createRoom(),
+            joinRoom: (input) => this.joinRoom(input),
+            leaveRoom: (roomId) => this.leaveRoom(roomId),
+            reconnect: () => this.reconnect(),
+            onMessage: (listener) => this.onMessage(listener),
+            onConnection: (listener) => this.onConnection(listener),
+        }, options);
+    }
+    onConnection(listener) {
+        this.#connectionListeners.add(listener);
+        return () => this.#connectionListeners.delete(listener);
+    }
     async authenticate(token) {
         if (!this.#unsubscribe)
             this.initialize();
@@ -39,23 +147,81 @@ export class LokiClient {
         this.#playerId = session.playerId;
         return session;
     }
-    async joinRoom(roomKey) {
+    async createRoom() {
+        if (!this.#playerId)
+            throw new Error("authenticate before creating a room");
+        return this.#serialize(() => this.#enterRoom(() => this.#transport.createRoom({ projectId: this.#projectId })));
+    }
+    async joinRoom(input) {
         if (!this.#playerId)
             throw new Error("authenticate before joining a room");
-        const joined = await this.#transport.joinRoom({
+        return this.#serialize(() => this.#enterRoom(() => this.#transport.joinRoom({
             projectId: this.#projectId,
-            roomKey,
-        });
-        const snapshot = ServerEnvelopeSchema.parse(joined.snapshot);
-        if (snapshot.roomId !== joined.roomId || snapshot.type !== "snapshot") {
-            throw new Error("invalid join snapshot");
+            inviteCode: requireInviteCode(input.inviteCode),
+        })));
+    }
+    async #serialize(operation) {
+        const run = this.#lifecycle.then(operation, operation);
+        this.#lifecycle = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async #enterRoom(join) {
+        if (this.#leaveFailed) {
+            throw new Error("resolve the failed leave before joining another room");
+        }
+        const generation = ++this.#lifecycleGeneration;
+        this.#joining = true;
+        this.#joinBuffer = [];
+        let joinedRoomId = "";
+        try {
+            const joined = await join();
+            joinedRoomId = joined.roomId;
+            const snapshot = ServerEnvelopeSchema.parse(joined.snapshot);
+            if (snapshot.roomId !== joined.roomId || snapshot.type !== "snapshot") {
+                throw new Error("invalid join snapshot");
+            }
+            if (generation !== this.#lifecycleGeneration) {
+                await this.#transport.leaveRoom?.(joined.roomId).catch(() => undefined);
+                throw new Error("stale room join abandoned");
+            }
+            this.#roomId = joined.roomId;
+            this.#inviteCode = joined.inviteCode;
+            this.#sendSequence = 0;
+            this.#receiveSequence = snapshot.sequence;
+            const buffered = this.#joinBuffer;
+            this.#joinBuffer = [];
+            this.#joining = false;
+            for (const message of buffered)
+                this.#dispatch(message);
+            return {
+                roomId: joined.roomId,
+                inviteCode: joined.inviteCode,
+                snapshot,
+            };
+        }
+        catch (error) {
+            if (joinedRoomId) {
+                await this.#transport.leaveRoom?.(joinedRoomId).catch(() => undefined);
+                if (this.#roomId === joinedRoomId) {
+                    this.#roomId = undefined;
+                    this.#inviteCode = "";
+                }
+            }
+            throw error;
         }
-        this.#roomId = joined.roomId;
-        this.#sendSequence = 0;
-        this.#receiveSequence = snapshot.sequence;
-        return snapshot;
+        finally {
+            this.#joining = false;
+            this.#joinBuffer = [];
+        }
+    }
+    #dispatch(message) {
+        if (message.roomId !== this.#roomId ||
+            message.sequence < this.#receiveSequence)
+            return;
+        this.#receiveSequence = message.sequence;
+        notifyListeners(this.#listeners, message);
     }
-    async sendAction(payload) {
+    async sendAction(payload, options) {
         if (!this.#roomId)
             throw new Error("join a room before sending actions");
         const message = ClientEnvelopeSchema.parse({
@@ -64,6 +230,7 @@ export class LokiClient {
             sequence: ++this.#sendSequence,
             type: "action",
             payload,
+            actionId: options?.actionId,
         });
         await this.#transport.send(message);
     }
@@ -80,7 +247,7 @@ export class LokiClient {
         });
         await this.#transport.send(message);
     }
-    async sendHostState(expectedVersion, state) {
+    async sendHostState(expectedVersion, state, options) {
         if (!this.#roomId)
             throw new Error("join a room before sending state");
         const message = ClientEnvelopeSchema.parse({
@@ -89,10 +256,28 @@ export class LokiClient {
             sequence: ++this.#sendSequence,
             type: "host_state",
             expectedVersion,
+            expectedStateVersion: options?.expectedStateVersion,
+            actionId: options?.actionId,
+            senderId: options?.senderId,
             state,
         });
         await this.#transport.send(message);
     }
+    async sendActionRejection(actionId, outcome, message, options) {
+        if (!this.#roomId)
+            throw new Error("join a room before rejecting actions");
+        const envelope = ClientEnvelopeSchema.parse({
+            protocolVersion: PROTOCOL_VERSION,
+            roomId: this.#roomId,
+            sequence: ++this.#sendSequence,
+            type: "action_reject",
+            actionId,
+            senderId: options?.senderId,
+            outcome,
+            message: protocolRejectionMessage(message),
+        });
+        await this.#transport.send(envelope);
+    }
     async requestSnapshot() {
         await this.#sendRoomMessage({ type: "snapshot_request" });
     }
@@ -110,33 +295,56 @@ export class LokiClient {
     async resolveInvite(inviteCode) {
         if (!this.#transport.resolveInvite)
             throw new Error("invites are unsupported");
-        return this.#transport.resolveInvite(inviteCode);
+        return this.#transport.resolveInvite(requireInviteCode(inviteCode));
     }
     async matchmake(input) {
         if (!this.#playerId)
             throw new Error("authenticate before matchmaking");
         if (!this.#transport.matchmake)
             throw new Error("matchmaking is unsupported");
-        const joined = await this.#transport.matchmake(input);
-        const snapshot = ServerEnvelopeSchema.parse(joined.snapshot);
-        this.#roomId = joined.roomId;
-        this.#sendSequence = 0;
-        this.#receiveSequence = snapshot.sequence;
-        return snapshot;
-    }
-    async leaveRoom() {
-        if (!this.#roomId)
-            return;
-        await this.#transport.leaveRoom?.(this.#roomId);
-        this.#roomId = undefined;
-        this.#sendSequence = 0;
-        this.#receiveSequence = 0;
+        return this.#serialize(() => this.#enterRoom(() => this.#transport.matchmake(input)));
+    }
+    async leaveRoom(roomId) {
+        this.#lifecycleGeneration += 1;
+        return this.#serialize(async () => {
+            const target = roomId || this.#roomId;
+            if (!target)
+                return;
+            try {
+                await this.#transport.leaveRoom?.(target);
+                if (this.#roomId === target) {
+                    this.#roomId = undefined;
+                    this.#inviteCode = "";
+                    this.#sendSequence = 0;
+                    this.#receiveSequence = 0;
+                    this.#leaveFailed = false;
+                }
+            }
+            catch (error) {
+                if (this.#roomId === target || !this.#roomId) {
+                    this.#roomId = target;
+                    this.#leaveFailed = true;
+                }
+                throw error;
+            }
+        });
     }
     async reconnect() {
-        if (!this.#transport.reconnect)
-            throw new Error("reconnect is unsupported");
-        await this.#transport.reconnect();
-        await this.requestSnapshot();
+        if (this.#reconnectPromise)
+            return this.#reconnectPromise;
+        this.#reconnectPromise = this.#serialize(async () => {
+            if (!this.#transport.reconnect)
+                throw new Error("reconnect is unsupported");
+            if (this.#leaveFailed)
+                throw new Error("resolve the failed leave before reconnecting");
+            if (!this.#roomId)
+                throw new Error("join a room before reconnecting");
+            await this.#transport.reconnect();
+            await this.requestSnapshot();
+        }).finally(() => {
+            this.#reconnectPromise = undefined;
+        });
+        return this.#reconnectPromise;
     }
     async refresh() {
         if (!this.#transport.refresh)
@@ -159,9 +367,16 @@ export class LokiClient {
         await this.#transport.send(message);
     }
     async close() {
+        this.#lifecycleGeneration += 1;
+        this.#leaveFailed = false;
+        this.#roomId = undefined;
+        this.#inviteCode = "";
         this.#unsubscribe?.();
         this.#unsubscribe = undefined;
+        this.#unsubscribeConnection?.();
+        this.#unsubscribeConnection = undefined;
         this.#listeners.clear();
+        this.#connectionListeners.clear();
         await this.#transport.close();
     }
 }
@@ -178,6 +393,9 @@ export class FirstPartyTransport {
     #roomId;
     #roomKey;
     #closed = false;
+    #connectionListeners = new Set();
+    #ignoreDisconnect = false;
+    #reconnectPromise;
     constructor(options = {}) {
         this.#apiOrigin = (options.apiOrigin ?? LOKI_API_ORIGIN).replace(/\/+$/, "");
         this.#secure = options.secure ?? true;
@@ -188,16 +406,16 @@ export class FirstPartyTransport {
     async authenticate(token) {
         const value = this.#sessionProvider
             ? await this.#sessionProvider(token)
-            : await (async () => {
+            : await wrapLokiCall(async () => {
                 const response = await this.#fetch(`${this.#apiOrigin}/v1/nakama-session`, {
                     method: "POST",
                     headers: { authorization: `Bearer ${token}` },
                 });
                 if (!response.ok) {
-                    throw new Error(`Loki authentication failed (${response.status})`);
+                    throw await lokiErrorFromUnknown(response);
                 }
                 return (await response.json());
-            })();
+            });
         const checked = value;
         if (!checked.token || !checked.playerId)
             throw new Error("invalid Loki session response");
@@ -206,25 +424,68 @@ export class FirstPartyTransport {
         await this.#connectSocket();
         return { playerId: checked.playerId };
     }
-    async joinRoom(input) {
+    async createRoom(_input) {
         const session = this.#requireSession();
         const socket = await this.#connectSocket();
-        const created = payload(await this.#client.rpc(session, "loki_create_room", {
-            roomKey: input.roomKey,
-        }));
+        const created = payload(await wrapLokiCall(() => this.#client.rpc(session, "loki_create_room", {})));
+        if (!created.matchId || !created.inviteCode) {
+            throw new Error("Loki did not return a room invite");
+        }
         await socket.joinMatch(created.matchId);
-        this.#roomId = created.matchId;
-        this.#roomKey = input.roomKey;
-        return {
-            roomId: created.matchId,
-            snapshot: await this.#snapshot(created.matchId),
-        };
+        try {
+            const snapshot = await this.#snapshot(created.matchId);
+            this.#roomId = created.matchId;
+            this.#roomKey = created.roomKey;
+            return {
+                roomId: created.matchId,
+                inviteCode: created.inviteCode,
+                snapshot,
+            };
+        }
+        catch (error) {
+            await socket.leaveMatch(created.matchId).catch(() => undefined);
+            if (this.#roomId === created.matchId) {
+                this.#roomId = undefined;
+                this.#roomKey = undefined;
+            }
+            throw error;
+        }
+    }
+    async joinRoom(input) {
+        const session = this.#requireSession();
+        const socket = await this.#connectSocket();
+        const inviteCode = requireInviteCode(input.inviteCode);
+        const joined = payload(await wrapLokiCall(() => this.#client.rpc(session, "loki_join_room", { inviteCode })));
+        if (!joined.matchId)
+            throw new Error("Loki did not return a room");
+        await socket.joinMatch(joined.matchId);
+        try {
+            const snapshot = await this.#snapshot(joined.matchId);
+            this.#roomId = joined.matchId;
+            return {
+                roomId: joined.matchId,
+                inviteCode: joined.inviteCode ?? inviteCode,
+                snapshot,
+            };
+        }
+        catch (error) {
+            await socket.leaveMatch(joined.matchId).catch(() => undefined);
+            if (this.#roomId === joined.matchId)
+                this.#roomId = undefined;
+            throw error;
+        }
     }
     async resolveInvite(inviteCode) {
-        const resolved = payload(await this.#client.rpc(this.#requireSession(), "loki_resolve_invite", {
-            inviteCode,
-        }));
-        return { roomId: resolved.matchId };
+        const normalized = requireInviteCode(inviteCode);
+        const resolved = payload(await wrapLokiCall(() => this.#client.rpc(this.#requireSession(), "loki_resolve_invite", {
+            inviteCode: normalized,
+        })));
+        if (!resolved.matchId)
+            throw new Error("Loki did not return a room");
+        return {
+            roomId: resolved.matchId,
+            inviteCode: resolved.inviteCode ?? normalized,
+        };
     }
     async matchmake(input) {
         const socket = await this.#connectSocket();
@@ -240,9 +501,24 @@ export class FirstPartyTransport {
         });
         const result = await matched;
         const joined = await socket.joinMatch(result.match_id, result.token);
-        this.#roomId = joined.match_id;
-        this.#roomKey = `match-${joined.match_id.slice(0, 12).toLowerCase()}`;
-        return { roomId: joined.match_id, snapshot: await this.#snapshot(joined.match_id) };
+        try {
+            const snapshot = await this.#snapshot(joined.match_id);
+            this.#roomId = joined.match_id;
+            this.#roomKey = `match-${joined.match_id.slice(0, 12).toLowerCase()}`;
+            return {
+                roomId: joined.match_id,
+                inviteCode: "",
+                snapshot,
+            };
+        }
+        catch (error) {
+            await socket.leaveMatch(joined.match_id).catch(() => undefined);
+            if (this.#roomId === joined.match_id) {
+                this.#roomId = undefined;
+                this.#roomKey = undefined;
+            }
+            throw error;
+        }
     }
     async send(message) {
         const socket = await this.#connectSocket();
@@ -252,22 +528,32 @@ export class FirstPartyTransport {
                 ? 11
                 : message.type === "host_state"
                     ? 12
-                    : message.type === "snapshot_request"
-                        ? 13
-                        : message.type === "chat"
-                            ? 14
-                            : 15;
+                    : message.type === "action_reject"
+                        ? 16
+                        : message.type === "snapshot_request"
+                            ? 13
+                            : message.type === "chat"
+                                ? 14
+                                : 15;
         await socket.sendMatchState(message.roomId, opCode, JSON.stringify(message));
     }
     subscribe(listener) {
         this.#listeners.add(listener);
         return () => this.#listeners.delete(listener);
     }
+    subscribeConnection(listener) {
+        this.#connectionListeners.add(listener);
+        return () => this.#connectionListeners.delete(listener);
+    }
     async leaveRoom(roomId) {
-        await this.#socket?.leaveMatch(roomId);
-        if (this.#roomId === roomId) {
-            this.#roomId = undefined;
-            this.#roomKey = undefined;
+        try {
+            await this.#socket?.leaveMatch(roomId);
+        }
+        finally {
+            if (this.#roomId === roomId) {
+                this.#roomId = undefined;
+                this.#roomKey = undefined;
+            }
         }
     }
     async refresh() {
@@ -276,19 +562,39 @@ export class FirstPartyTransport {
     async reconnect() {
         if (this.#closed)
             throw new Error("transport is closed");
-        this.#socket?.disconnect(false);
+        if (this.#reconnectPromise)
+            return this.#reconnectPromise;
+        this.#reconnectPromise = this.#reconnectOnce()
+            .then(() => {
+            notifyListeners(this.#connectionListeners, "connected");
+        })
+            .finally(() => {
+            this.#reconnectPromise = undefined;
+        });
+        return this.#reconnectPromise;
+    }
+    async #reconnectOnce() {
+        this.#ignoreDisconnect = true;
+        const previous = this.#socket;
         this.#socket = undefined;
-        if (this.#session?.isexpired(Math.floor(Date.now() / 1_000)))
-            await this.refresh();
-        const socket = await this.#connectSocket();
-        if (this.#roomId)
-            await socket.joinMatch(this.#roomId);
+        try {
+            previous?.disconnect(false);
+            if (this.#session?.isexpired(Math.floor(Date.now() / 1_000)))
+                await this.refresh();
+            const socket = await this.#connectSocket();
+            if (this.#roomId)
+                await socket.joinMatch(this.#roomId);
+        }
+        finally {
+            this.#ignoreDisconnect = false;
+        }
     }
     async close() {
         this.#closed = true;
         this.#socket?.disconnect(false);
         this.#socket = undefined;
         this.#listeners.clear();
+        this.#connectionListeners.clear();
     }
     async #connectSocket() {
         if (this.#closed)
@@ -301,25 +607,33 @@ export class FirstPartyTransport {
                 return;
             try {
                 const decoded = JSON.parse(textDecoder.decode(message.data));
-                for (const listener of this.#listeners)
-                    listener(decoded);
+                notifyListeners(this.#listeners, decoded);
             }
             catch {
                 // Invalid server data is ignored and cannot reach game listeners.
             }
         };
         socket.ondisconnect = () => {
-            if (!this.#closed)
-                void this.reconnect().catch(() => undefined);
+            if (this.#socket !== socket)
+                return;
+            this.#socket = undefined;
+            if (this.#ignoreDisconnect)
+                return;
+            notifyListeners(this.#connectionListeners, "disconnected");
+            if (this.#closed || this.#reconnectPromise)
+                return;
+            void this.reconnect().catch(() => {
+                notifyListeners(this.#connectionListeners, "reconnect_failed");
+            });
         };
         await socket.connect(this.#requireSession(), true);
         this.#socket = socket;
         return socket;
     }
     async #snapshot(roomId) {
-        const state = payload(await this.#client.rpc(this.#requireSession(), "loki_room_snapshot", {
+        const state = payload(await wrapLokiCall(() => this.#client.rpc(this.#requireSession(), "loki_room_snapshot", {
             matchId: roomId,
-        }));
+        })));
         if (!state.ok)
             throw new Error("room snapshot failed");
         return ServerEnvelopeSchema.parse({
@@ -329,6 +643,8 @@ export class FirstPartyTransport {
             type: "snapshot",
             hostId: state.hostId,
             state: state.state,
+            stateVersion: state.stateVersion ?? state.version,
+            capabilities: state.capabilities,
         });
     }
     #requireSession() {