@nanotoolkit/game-sdk 0.1.7 → 0.1.9

package/Lib/Bridge/GameBridge.js

@@ -1,6 +1,7 @@
 import { parseWireJSON, stringifyWireJSON } from './WireJSON.js';
+import { GameState } from './GameState.js';
 
-export const SDK_VERSION = '0.1.7';
+export const SDK_VERSION = '0.1.9';
 
 const REQUEST_TIMEOUT_MS = 10000;
 
@@ -34,6 +35,7 @@ export class SdkError extends Error {
         super(message);
         this.name = 'SdkError';
         this.code = code;
+        this.errorMessage = message;
         this.retryable = RETRYABLE.has(code);
     }
 }
@@ -231,7 +233,8 @@ export function on(event, handler) {
 }
 
 const KEEP_KEYS = 64;
-const issues = new Map();
+let gameState = new GameState();
+const cachedIssue = (id) => lastEntry && gameState.get(lastEntry.gameId, lastEntry.gameRoomId, id);
 const betKeys = new Map();
 const betStates = new Map();
 const actionCounts = new Map();
@@ -248,60 +251,31 @@ function remember(map, id, key) {
     return true;
 }
 
-const issueKey = (issue) => stringifyWireJSON({ ...issue, serverTime: undefined });
 const betKey = (bet) => stringifyWireJSON({ ...bet, serverTime: undefined });
 
-const RANK = Object.freeze({ betting: 0, running: 1, shown: 2, ended: 3 });
-let unknownStatusNoticed = false;
-
-function issueRank(r, prev) {
-    switch (r.status) {
-        case 'betting':
-            return RANK.betting;
-        case 'running':
-            return r.result == null ? RANK.running : RANK.shown;
-        case 'settled':
-        case 'voided':
-            return RANK.ended;
-    }
-
-    if (!unknownStatusNoticed) {
-        unknownStatusNoticed = true;
-        console.warn(`[game-sdk] invalid status: ${r.status}`);
-    }
-    return prev ? prev.rank : RANK.betting;
+function noteIssue(issue, publish, recovery, live = true) {
+    if (!issue || typeof issue !== 'object' || !issue.id || !inRoom(issue)) return false;
+    const accepted = gameState.noteIssue(issue, recovery);
+    if (gameState.conflicts.size) recoverState();
+    if (!accepted.changed) return false;
+    issue = accepted.issue;
+    reconcileEntryState();
+    if (live) afterIssue(issue, publish);
+    return true;
 }
 
-function noteIssue(issue, publish) {
-    if (!issue || typeof issue !== 'object' || !issue.id) return false;
-    if (!inRoom(issue)) return false;
-    const prev = issues.get(issue.id);
-    const rank = issueRank(issue, prev);
-    const key = issueKey(issue);
-    if (
-        prev &&
-        (rank < prev.rank ||
-            (prev.issue.settlementCompleted && !issue.settlementCompleted) ||
-            key === prev.key)
-    )
-        return false;
-    touch(issues, issue.id, { key, rank, issue });
-    if (issue.result == null && issue.display?.rulesId && lastEntry?.rulesId !== issue.display.rulesId)
+function afterIssue(issue, publish) {
+    if (publish) gameState.expectIssue(issue);
+    if (publish && issue.result == null &&
+        (lastEntry?.issue?.id !== issue.id ||
+            (issue.display?.rulesId && lastEntry?.rulesId !== issue.display.rulesId)))
         refreshEntry();
     if (issue.ruleType === 'crash' && issue.flowType === 'timed') {
-        const old = [...issues.values()]
-            .reverse()
-            .find(
-                (state) =>
-                    state.issue.id !== issue.id &&
-                    state.issue.gameRoomId === issue.gameRoomId &&
-                    state.issue.ruleType === 'crash',
-            );
-        if (old) recoverCashouts(old.issue);
+        const current = lastEntry?.issue;
+        if (publish && current?.ruleType === 'crash' && current.id !== issue.id) recoverCashouts(current);
         recoverCashouts(issue);
     }
     if (publish) emitLocal('issue', issue);
-    return true;
 }
 
 const STALL_MS = 300;
@@ -319,10 +293,8 @@ function noteHeartbeat(beat) {
     const cashoutState = mergeCashouts(beat);
     if (cashoutState && cashoutState.cursor < (beat.cashoutCount ?? 0))
         recoverCashouts({ ...beat, id: beat.issueId });
-    const state = issues.get(beat.issueId);
-    if (state?.rank !== RANK.running) return;
-
-    touch(issues, beat.issueId, state);
+    const state = cachedIssue(beat.issueId);
+    if (state?.status !== 'running' || state.result != null) return;
 
     const behind =
         lastHeartbeat?.issueId === beat.issueId && beat.elapsedMillis < lastHeartbeat.elapsedMillis;
@@ -339,8 +311,13 @@ function noteHeartbeat(beat) {
     });
 }
 
-function noteBet(bet, publish, trackActions = true) {
+function noteBet(bet, publish, trackActions = true, recovery) {
     if (!bet || typeof bet !== 'object' || !bet.id || !inRoom(bet)) return;
+    if (bet.issue) {
+        bet = gameState.normalizeBet(bet, recovery);
+        reconcileEntryState();
+        if (gameState.conflicts.size) recoverState();
+    }
     const previous = betStates.get(bet.id);
     if (!trackActions && !previous) return;
     if (
@@ -360,11 +337,15 @@ function noteBet(bet, publish, trackActions = true) {
     if (remember(betKeys, bet.id, betKey(bet)) && publish) emitLocal('bet', bet);
 }
 
-function noteIssueInfo(info, publish) {
+function noteIssueInfo(info, publish, recovery, trackActions = true) {
     if (!info || typeof info !== 'object') return info;
-    noteIssue(info.issue, publish);
-    if (Array.isArray(info.bets)) for (const bet of info.bets) noteBet(bet, publish);
-    return info;
+    noteIssue(info.issue, publish, recovery, trackActions);
+    if (Array.isArray(info.bets)) for (const bet of info.bets) noteBet(bet, publish, trackActions, recovery);
+    return {
+        ...info,
+        issue: inRoom(info.issue) ? cachedIssue(info.issue.id) ?? info.issue : info.issue,
+        bets: Array.isArray(info.bets) ? info.bets.map((bet) => normalizeBet(bet)) : info.bets,
+    };
 }
 
 function ensureStateListeners() {
@@ -411,25 +392,15 @@ function ensureStateListeners() {
     });
     subscribe('game:flow', (msg) => {
         if (!roomMatches(msg.flow)) return;
-        const previous = lastEntry?.issue;
-        if (msg.flow.issue && previous && msg.flow.issue.id < previous.id) return;
-        if (flowRegresses(msg.flow, lastEntry)) return;
-        if (lastEntry)
-            Object.assign(lastEntry, {
-                flow: msg.flow.flow,
-                issue: msg.flow.issue,
-                lastOpenedIssue: msg.flow.lastOpenedIssue,
-                serverTime: msg.flow.serverTime ?? lastEntry.serverTime,
-                bets: (lastEntry.bets ?? []).filter((bet) => bet.issueId === msg.flow.issue?.id),
-            });
-        noteIssue(msg.flow.issue, true);
-        noteIssue(msg.flow.lastOpenedIssue, true);
-        reconcileEntryState();
+        const entry = acceptEntry({ gameId: lastEntry.gameId, ...msg.flow }, false, undefined, true);
+        if (!entry) return;
         emitLocal('flow', {
             ...msg.flow,
-            issue: lastEntry.issue,
-            lastOpenedIssue: lastEntry.lastOpenedIssue,
+            flow: publicEntry(entry).flow,
+            issue: entry.issue,
+            lastOpenedIssue: entry.lastOpenedIssue,
         });
+        refreshEntry();
     });
     subscribe('game:snapshot', (msg) => {
         if (inRoom(msg.snapshot)) acceptEntry(msg.snapshot, true);
@@ -472,35 +443,35 @@ function boundRoom(args = {}) {
     };
 }
 
-function flowRegresses(next, previous) {
-    return (
-        next.issue?.id === previous?.issue?.id &&
-        previous?.flow?.phase > 0 &&
-        next.flow?.phase > 0 &&
-        next.flow.phase < previous.flow.phase &&
-        next.flow.phaseEndsAt <= previous.flow.phaseEndsAt
-    );
+function publicEntry(entry) {
+    return gameState.conflicts.size || gameState.configurationPending
+        ? { ...entry, flow: { ...entry.flow, bettingOpen: false } }
+        : entry;
 }
 
-function acceptEntry(entry, publish = false) {
-    const changed =
-        lastEntry && (entry.gameRoomId !== lastEntry.gameRoomId || entry.gameId !== lastEntry.gameId);
+function acceptEntry(entry, publish = false, recovery, publishIssues = publish) {
+    const changed = lastEntry && (entry.gameRoomId !== lastEntry.gameRoomId || entry.gameId !== lastEntry.gameId);
+    const previousCurrent = lastEntry?.issue;
     if (changed) {
-        for (const { issue } of issues.values())
+        for (const issue of [lastEntry.issue, lastEntry.lastOpenedIssue].filter(Boolean))
             if (issue.ruleType === 'crash' && issue.flowType === 'timed') recoverCashouts(issue);
-        issues.clear();
+        gameState = new GameState();
         betKeys.clear();
         betStates.clear();
         actionCounts.clear();
         lastHeartbeat = null;
         roomFeed = null;
     }
-
-    if (!changed && entry.issue && lastEntry?.issue && entry.issue.id < lastEntry.issue.id) return lastEntry;
-
-    const flow = !changed && flowRegresses(entry, lastEntry) ? lastEntry.flow : entry.flow;
-
-    lastEntry = { ...(changed ? {} : lastEntry), ...entry, flow };
+    const previousIssues = [entry.issue, entry.lastOpenedIssue].filter(Boolean)
+        .map((issue) => gameState.get(issue.gameId, issue.gameRoomId, issue.id));
+    const accepted = gameState.merge(entry, recovery);
+    if (!accepted) {
+        if (lastEntry) recoverState();
+        return lastEntry;
+    }
+    lastEntry = accepted;
+    if (!changed && previousCurrent?.id !== accepted.issue?.id && previousCurrent?.ruleType === 'crash')
+        recoverCashouts(previousCurrent);
     if (entry.rooms)
         roomDirectory = {
             gameId: entry.gameId,
@@ -508,33 +479,88 @@ function acceptEntry(entry, publish = false) {
             rooms: entry.rooms,
             serverTime: entry.serverTime,
         };
-    noteIssueInfo({ issue: entry.issue, bets: entry.bets }, publish);
-    noteIssue(entry.lastOpenedIssue, publish);
+    for (const [index, issue] of [entry.issue, entry.lastOpenedIssue].filter(Boolean).entries()) {
+        if (!inRoom(issue)) continue;
+        const known = cachedIssue(issue.id);
+        if (known && known !== previousIssues[index]) afterIssue(known, publishIssues);
+    }
+    if (Array.isArray(accepted.bets)) for (const bet of accepted.bets) noteBet(bet, publish, true, recovery);
     reconcileEntryState();
-    if (publish) emitLocal('snapshot', lastEntry);
-    return lastEntry;
+    if (gameState.conflicts.size) recoverState();
+    const result = publicEntry(lastEntry);
+    if (publish && !gameState.configurationPending) emitLocal('snapshot', result);
+    return result;
 }
 
 function reconcileEntryState() {
-    lastEntry.issue = issues.get(lastEntry.issue?.id)?.issue ?? lastEntry.issue;
-    lastEntry.lastOpenedIssue = issues.get(lastEntry.lastOpenedIssue?.id)?.issue ?? lastEntry.lastOpenedIssue;
-    const latestBets = new Map((lastEntry.bets ?? []).map((bet) => [bet.id, betStates.get(bet.id) ?? bet]));
+    if (!lastEntry) return;
+    lastEntry.issue = cachedIssue(lastEntry.issue?.id) ?? lastEntry.issue;
+    lastEntry.lastOpenedIssue = cachedIssue(lastEntry.lastOpenedIssue?.id) ?? lastEntry.lastOpenedIssue;
+    const latestBets = new Map((lastEntry.bets ?? [])
+        .filter((bet) => bet.issueId === lastEntry.issue?.id)
+        .map((bet) => [bet.id, betStates.get(bet.id) ?? bet]));
     for (const bet of betStates.values())
         if (bet.issueId === lastEntry.issue?.id) latestBets.set(bet.id, bet);
     lastEntry.bets = [...latestBets.values()];
 }
+
+function normalizeBet(bet) {
+    if (!bet || !inRoom(bet)) return bet;
+    const value = betStates.get(bet.id) ?? bet;
+    const issue = gameState.get(value.gameId, value.gameRoomId, value.issueId);
+    return issue ? { ...value, issue } : value;
+}
+
+let stateRecovery = null;
+function recoverState() {
+    if (lastEntry && !gameState.configurationPending && gameState.conflicts.size)
+        emitLocal('snapshot', publicEntry(lastEntry));
+    if (!lastEntry || !gameState.conflicts.size || stateRecovery?.state === gameState) return;
+    const task = { state: gameState, attempted: new Map() };
+    stateRecovery = task;
+    (async () => {
+        while (task.state === gameState) {
+            if (refreshingEntry) await refreshingEntry;
+            if (task.state !== gameState) break;
+            const recovery = gameState.recovery();
+            const pending = [...recovery].filter(([key, version]) => task.attempted.get(key) !== version);
+            if (!pending.length) break;
+            for (const [key, version] of pending) task.attempted.set(key, version);
+            const targets = pending.map(([key]) => gameState.conflictIssues.get(key)).filter(Boolean).filter(inRoom);
+            await Promise.all(targets.map((issue) => invoke('getGameIssue', boundRoom({ issueId: issue.id }))
+                .then((info) => {
+                    if (task.state === gameState) noteIssueInfo(info, false, recovery, false);
+                }).catch(() => {})));
+            if (task.state === gameState) await refreshEntry();
+        }
+    })().finally(() => {
+        if (stateRecovery === task) stateRecovery = null;
+    });
+}
+
 let refreshingEntry = null;
+let refreshAgain = false;
 function refreshEntry() {
-    if (!lastEntry || refreshingEntry) return refreshingEntry;
+    if (!lastEntry) return;
+    if (refreshingEntry) {
+        refreshAgain = true;
+        return refreshingEntry;
+    }
     const room = lastEntry.gameRoomId;
-    refreshingEntry = enterGame({ gameRoomId: room })
+    const pending = enterGame({ gameRoomId: room });
+    const generation = entrySeq;
+    refreshingEntry = pending
         .then((entry) => {
-            if (entry.gameRoomId === lastEntry?.gameRoomId) emitLocal('snapshot', entry);
+            if (generation !== entrySeq || entry.gameRoomId !== lastEntry?.gameRoomId) return;
+            if (!gameState.configurationPending) emitLocal('snapshot', publicEntry(entry));
             return Promise.all([getGameBets({ gameRoomId: entry.gameRoomId }), getGameRoomFeed()]);
         })
         .catch(() => {})
         .finally(() => {
             refreshingEntry = null;
+            const repeat = refreshAgain && generation === entrySeq && room === lastEntry?.gameRoomId;
+            refreshAgain = false;
+            if (repeat) refreshEntry();
         });
     return refreshingEntry;
 }
@@ -721,8 +747,10 @@ export const storage = {
 
 function toSdkError(error) {
     const code = typeof error?.code === 'string' ? error.code : ErrorCode.SERVER;
-    const message = typeof error?.message === 'string' && error.message.length > 0 ? error.message : code;
+    const text = error?.errorMessage ?? error?.message;
+    const message = typeof text === 'string' && text.length > 0 ? text : code;
     const result = new SdkError(code, message);
+    if (Number.isInteger(error?.serverCode) && error.serverCode < 0) result.serverCode = error.serverCode;
     if (error?.details) result.details = error.details;
     return result;
 }
@@ -849,9 +877,11 @@ export function enterGame({ gameRoomId } = {}) {
     if (gameRoomId != null && !(Number.isSafeInteger(gameRoomId) && gameRoomId >= 0))
         return badRequest('enterGame', 'invalid gameRoomId');
     const seq = ++entrySeq;
+    const recovery = gameState.recovery();
     return invoke('enterGame', gameRoomId != null ? { gameRoomId } : {}).then((entry) => {
-        if (seq !== entrySeq) return entry;
-        const accepted = acceptEntry(entry);
+        if (seq !== entrySeq) throw new SdkError(ErrorCode.CONFLICT, 'context changed');
+        const accepted = acceptEntry(entry, false, recovery);
+        if (!accepted || gameState.conflicts.size || gameState.configurationPending) throw new SdkError(ErrorCode.CONFLICT, 'invalid state');
         if (watching && !watchPaused) pollWatch();
         return accepted;
     });
@@ -871,6 +901,7 @@ function placeWith(params) {
 }
 
 export function placeGameBet({ issueId, bets, clientRequestId } = {}) {
+    if (gameState.conflicts.size || gameState.configurationPending) return badRequest('placeGameBet', 'state unavailable');
     const picked = pickBets(bets);
     if (!picked) return badRequest('placeGameBet', `invalid bets: 1-${MAX_BETS}`);
     if (issueId != null && issueId !== 0 && !isId(issueId))
@@ -937,6 +968,7 @@ function submitAction(key, request, confirm = false) {
 }
 
 export function actGameBet({ betId, action, params } = {}) {
+    if (gameState.conflicts.size || gameState.configurationPending) return badRequest('actGameBet', 'state unavailable');
     if (!isId(betId)) return badRequest('actGameBet', 'invalid betId');
     if (typeof action !== 'string' || action.length === 0) return badRequest('actGameBet', 'invalid action');
     if (params != null && !isPlainObject(params)) return badRequest('actGameBet', 'invalid params');
@@ -952,6 +984,7 @@ export function actGameBet({ betId, action, params } = {}) {
     return queueAction(key, actQueues.get(key), (queued) => {
         if (gameId !== lastEntry?.gameId || room !== lastEntry?.gameRoomId)
             return badRequest('actGameBet', 'context changed');
+        if (gameState.conflicts.size || gameState.configurationPending) return badRequest('actGameBet', 'state unavailable');
         const request = {
             gameRoomId: room,
             betId,
@@ -967,8 +1000,12 @@ export function actGameBet({ betId, action, params } = {}) {
 export function getGameIssue({ issueId } = {}) {
     if (issueId != null && issueId !== 0 && !isId(issueId))
         return badRequest('getGameIssue', 'invalid issueId');
+    const state = gameState;
+    const generation = entrySeq;
+    const recovery = state.recovery();
     return invoke('getGameIssue', boundRoom(issueId != null ? { issueId } : {})).then((info) =>
-        noteIssueInfo(info, false),
+        state === gameState && generation === entrySeq ? noteIssueInfo(info, false, recovery)
+            : Promise.reject(new SdkError(ErrorCode.CONFLICT, 'context changed')),
     );
 }
 
@@ -977,10 +1014,16 @@ export function getGameBets({ earliestId, pageSize, gameRoomId } = {}) {
     if (earliestId != null) params.earliestId = earliestId;
     if (pageSize != null) params.pageSize = pageSize;
     if (gameRoomId != null) params.gameRoomId = gameRoomId;
+    const state = gameState;
+    const generation = entrySeq;
+    const recovery = state.recovery();
     return invoke('getGameBets', params).then((bets) => {
         const list = Array.isArray(bets) ? bets : [];
-        for (const bet of list) noteBet(bet, false, false);
-        return list;
+        if (state !== gameState || generation !== entrySeq) return list;
+        for (const bet of list) noteBet(bet, false, false, recovery);
+        const normalized = list.map((bet) => normalizeBet(bet));
+        if (gameState.conflicts.size) recoverState();
+        return normalized;
     });
 }
 
@@ -995,7 +1038,14 @@ export function getGameRoomFeed() {
 }
 
 export function getGameIssues(args = {}) {
-    return invoke('getGameIssues', boundRoom(args)).then((list) => (Array.isArray(list) ? list : []));
+    const state = gameState;
+    const generation = entrySeq;
+    const recovery = state.recovery();
+    return invoke('getGameIssues', boundRoom(args)).then((list) => {
+        if (!Array.isArray(list)) return [];
+        if (state !== gameState || generation !== entrySeq) return list;
+        return list.map((info) => inRoom(info.issue) ? noteIssueInfo(info, false, recovery, false) : info);
+    });
 }
 
 export function getGameRooms() {
@@ -1010,8 +1060,12 @@ export function getGameRooms() {
 }
 export function getGameBet({ betId, gameRoomId } = {}) {
     if (!isId(betId)) return badRequest('getGameBet', 'invalid betId');
+    const state = gameState;
+    const generation = entrySeq;
+    const recovery = state.recovery();
     return invoke('getGameBet', boundRoom({ betId, gameRoomId })).then((bet) => {
-        noteBet(bet, false);
+        if (state !== gameState || generation !== entrySeq) throw new SdkError(ErrorCode.CONFLICT, 'context changed');
+        noteBet(bet, false, true, recovery);
         const key = actionKey(bet?.gameId, bet?.gameRoomId, bet?.id);
         const queued = actQueues.get(key);
         const request = queued?.request;
@@ -1025,7 +1079,7 @@ export function getGameBet({ betId, gameRoomId } = {}) {
             sameIntent(confirmed.params, request.params)
         )
             actQueues.delete(key);
-        return bet;
+        return normalizeBet(bet);
     });
 }
 export function getGameCashouts(args = {}) {
@@ -1100,7 +1154,7 @@ async function pollWatch() {
     noteIssueInfo(info, true);
 
     const id = info?.issue?.id;
-    scheduleWatch(id ? issues.get(id)?.issue ?? info.issue : null);
+    scheduleWatch(id ? cachedIssue(id) ?? info.issue : null);
 }
 
 function pauseWatch() {

package/Lib/Bridge/GameState.js

@@ -0,0 +1,277 @@
+export const validRevision = (value) =>
+    (typeof value === 'bigint' && value >= 0n && value <= 9223372036854775807n) ||
+    (Number.isSafeInteger(value) && value >= 0);
+
+const sameId = (a, b) => a != null && b != null && String(a) === String(b);
+const issueKey = (value) => `${value.gameId}:${value.gameRoomId}:${value.id}`;
+const flowFields = ['phase', 'phaseEndsAt', 'currentIssueId', 'lastOpenedIssueId'];
+
+function canonical(value) {
+    if (value === null || typeof value !== 'object')
+        return typeof value === 'bigint' ? value.toString() : JSON.stringify(value);
+    if (Array.isArray(value)) return '[' + value.map(canonical).join(',') + ']';
+    return (
+        '{' +
+        Object.keys(value)
+            .sort()
+            .filter((key) => value[key] !== undefined)
+            .map((key) => JSON.stringify(key) + ':' + canonical(value[key]))
+            .join(',') +
+        '}'
+    );
+}
+
+const issueContent = (value) => canonical({ ...value, serverTime: undefined });
+const flowContent = (value) =>
+    canonical(Object.fromEntries(flowFields.map((key) => [key, value[key]])));
+
+export class GameState {
+    constructor() {
+        this.entry = null;
+        this.issues = new Map();
+        this.conflicts = new Map();
+        this.conflictIssues = new Map();
+        this.sequence = 0;
+        this.configIssueId = undefined;
+        this.expectedIssueId = null;
+    }
+
+    recovery() {
+        return new Map(this.conflicts);
+    }
+
+    conflict(key, issue) {
+        if (!this.conflicts.has(key)) this.conflicts.set(key, ++this.sequence);
+        if (issue && key !== 'flow') this.conflictIssues.set(key, issue);
+    }
+
+    recovered(key, recovery) {
+        return recovery?.has(key) && recovery.get(key) === this.conflicts.get(key);
+    }
+
+    clearConflict(key) {
+        this.conflicts.delete(key);
+        this.conflictIssues.delete(key);
+    }
+
+    get(gameId, gameRoomId, id) {
+        return this.issues.get(issueKey({ gameId, gameRoomId, id }));
+    }
+
+    noteIssue(incoming, recovery) {
+        if (!incoming) return { issue: null, changed: false };
+        const key = issueKey(incoming);
+        const previous = this.issues.get(key);
+        if (
+            !validRevision(incoming.revision) ||
+            !validRevision(incoming.targetTime) ||
+            !validRevision(incoming.id) ||
+            incoming.id <= 0 ||
+            !Number.isInteger(incoming.gameId) ||
+            !Number.isInteger(incoming.gameRoomId) ||
+            !['betting', 'running', 'settled', 'voided'].includes(incoming.status)
+        ) {
+            this.conflict(key, incoming);
+            return { issue: previous ?? null, changed: false };
+        }
+        if (previous) {
+            if (incoming.revision < previous.revision) return { issue: previous, changed: false };
+            if (
+                incoming.revision == previous.revision &&
+                issueContent(incoming) === issueContent(previous)
+            ) {
+                if (this.recovered(key, recovery)) this.clearConflict(key);
+                return { issue: previous, changed: false };
+            }
+            if (
+                (incoming.revision == previous.revision && !this.recovered(key, recovery)) ||
+                (previous.settlementCompleted &&
+                    (!incoming.settlementCompleted ||
+                        incoming.status !== previous.status ||
+                        canonical(incoming.result) !== canonical(previous.result))) ||
+                (previous.status === 'voided' && incoming.status !== 'voided') ||
+                (previous.result != null && incoming.result == null && incoming.status !== 'voided')
+            ) {
+                this.conflict(key, incoming);
+                return { issue: previous, changed: false };
+            }
+        }
+        this.issues.delete(key);
+        this.issues.set(key, incoming);
+        if (this.recovered(key, recovery) || (previous && incoming.revision > previous.revision))
+            this.clearConflict(key);
+        if (this.issues.size > 256) {
+            const pinned = [this.entry?.issue, this.entry?.lastOpenedIssue]
+                .filter(Boolean)
+                .map(issueKey);
+            const oldest = [...this.issues.keys()].find(
+                (item) => !pinned.includes(item) && !this.conflicts.has(item),
+            );
+            if (oldest) this.issues.delete(oldest);
+        }
+        return { issue: incoming, changed: true };
+    }
+
+    normalizeBet(bet, recovery) {
+        if (!bet?.issue || typeof bet.issue !== 'object') return bet;
+        const issue = bet.issue;
+        if (
+            !sameId(issue.id, bet.issueId) ||
+            issue.gameId !== bet.gameId ||
+            issue.gameRoomId !== bet.gameRoomId
+        ) {
+            const expected = { gameId: bet.gameId, gameRoomId: bet.gameRoomId, id: bet.issueId };
+            this.conflict(issueKey(expected), expected);
+            return { ...bet, issue: null };
+        }
+        return { ...bet, issue: this.noteIssue(issue, recovery).issue };
+    }
+
+    expectIssue(issue) {
+        if (
+            this.entry &&
+            issue.result == null &&
+            ['betting', 'running'].includes(issue.status) &&
+            (this.entry.issue == null || issue.id > this.entry.issue.id)
+        )
+            this.expectedIssueId =
+                this.expectedIssueId == null || issue.id > this.expectedIssueId
+                    ? issue.id
+                    : this.expectedIssueId;
+    }
+
+    get configurationPending() {
+        return (
+            this.expectedIssueId != null ||
+            (this.entry != null && !sameId(this.configIssueId, this.entry.issue?.id ?? 0))
+        );
+    }
+
+    merge(incoming, recovery) {
+        const previous = this.entry;
+        if (
+            previous &&
+            (incoming.gameId !== previous.gameId || incoming.gameRoomId !== previous.gameRoomId)
+        )
+            throw new TypeError('context changed');
+        const nested = [incoming.issue, incoming.lastOpenedIssue].filter(Boolean);
+        const scoped = nested.every(
+            (issue) => issue.gameId === incoming.gameId && issue.gameRoomId === incoming.gameRoomId,
+        );
+        if (scoped) for (const issue of nested) this.noteIssue(issue, recovery);
+        const bets = Array.isArray(incoming.bets)
+            ? incoming.bets.map((bet) => this.normalizeBet(bet, recovery))
+            : incoming.bets;
+        incoming = { ...incoming, ...(bets !== undefined ? { bets } : {}) };
+        const flow = incoming.flow;
+        const aligned =
+            incoming.param?.alignedCycle ??
+            previous?.param?.alignedCycle ??
+            (previous?.flow && 'revision' in previous.flow);
+        let accept = scoped;
+        if (!scoped) this.conflict('flow');
+        const changedMode =
+            previous?.param?.alignedCycle != null &&
+            incoming.param?.alignedCycle != null &&
+            incoming.param.alignedCycle !== previous.param.alignedCycle;
+        const unknownMode =
+            previous?.param?.alignedCycle === false &&
+            incoming.param == null &&
+            flow &&
+            'revision' in flow;
+        if ((changedMode && !recovery) || unknownMode) {
+            accept = false;
+            this.conflict('flow');
+        }
+        if (aligned || (flow && 'revision' in flow)) {
+            const valid =
+                flow &&
+                [-2, -1, 1, 2, 3].includes(flow.phase) &&
+                Number.isSafeInteger(flow.phaseEndsAt) &&
+                flow.phaseEndsAt >= 0 &&
+                typeof flow.bettingOpen === 'boolean' &&
+                (validRevision(flow.revision) || flow.revision === null) &&
+                validRevision(flow.currentIssueId) &&
+                validRevision(flow.lastOpenedIssueId) &&
+                sameId(flow.currentIssueId, incoming.issue?.id ?? 0) &&
+                sameId(flow.lastOpenedIssueId, incoming.lastOpenedIssue?.id ?? 0) &&
+                (flow.revision !== null ||
+                    (flow.currentIssueId == 0 &&
+                        flow.lastOpenedIssueId == 0 &&
+                        flow.phase === -2 &&
+                        flow.phaseEndsAt === 0 &&
+                        flow.bettingOpen === false));
+            if (!valid) {
+                accept = false;
+                this.conflict('flow');
+            } else if (
+                previous?.flow?.revision != null &&
+                (flow.revision === null || flow.revision < previous.flow.revision)
+            ) {
+                accept = false;
+            } else if (
+                previous?.flow &&
+                flow.revision === previous.flow.revision &&
+                flowContent(flow) !== flowContent(previous.flow) &&
+                !this.recovered('flow', recovery)
+            ) {
+                accept = false;
+                this.conflict('flow');
+            } else if (
+                accept &&
+                (this.recovered('flow', recovery) ||
+                    (flow.revision != null &&
+                        previous?.flow?.revision != null &&
+                        flow.revision > previous.flow.revision))
+            )
+                this.clearConflict('flow');
+        } else if (previous?.issue && incoming.issue && incoming.issue.id < previous.issue.id) {
+            accept = false;
+        } else if (accept && this.recovered('flow', recovery)) {
+            this.clearConflict('flow');
+        }
+        const independent = Object.fromEntries(
+            [
+                'bets',
+                'admission',
+                'rooms',
+                'roomsTopic',
+                'bundleId',
+                'serverTime',
+                'currency',
+                'usdRate',
+            ]
+                .filter((key) => incoming[key] !== undefined)
+                .map((key) => [key, incoming[key]]),
+        );
+        const entry = accept
+            ? { ...previous, ...incoming }
+            : previous
+            ? { ...previous, ...independent }
+            : null;
+        if (entry) {
+            for (const field of ['issue', 'lastOpenedIssue']) {
+                const id =
+                    entry.flow && 'revision' in entry.flow
+                        ? entry.flow[field === 'issue' ? 'currentIssueId' : 'lastOpenedIssueId']
+                        : entry[field]?.id;
+                entry[field] =
+                    id == null || id == 0
+                        ? null
+                        : this.get(entry.gameId, entry.gameRoomId, id) ?? null;
+                if (id != null && id != 0 && !entry[field]) this.conflict('flow');
+            }
+            this.entry = entry;
+            if (accept && (incoming.param != null || incoming.rulesId != null)) {
+                this.configIssueId = entry.issue?.id ?? 0;
+                if (
+                    this.expectedIssueId == null ||
+                    entry.issue?.id >= this.expectedIssueId ||
+                    (entry.issue == null && entry.flow?.phase <= 0)
+                )
+                    this.expectedIssueId = null;
+            }
+        }
+        return entry;
+    }
+}

package/index.d.ts

@@ -28,6 +28,8 @@ export type SdkErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode] | string;
 export class SdkError extends Error {
     readonly name: 'SdkError';
     readonly code: SdkErrorCode;
+    readonly serverCode?: number;
+    readonly errorMessage: string;
 
     readonly retryable: boolean;
 
@@ -92,6 +94,9 @@ export interface GameRooms {
     serverTime: number;
 }
 export interface GameFlow {
+    revision: WireId | null;
+    currentIssueId: WireId;
+    lastOpenedIssueId: WireId;
     phase: -2 | -1 | 1 | 2 | 3;
     phaseEndsAt: number;
     bettingOpen: boolean;
@@ -116,6 +121,8 @@ export interface GameEntry {
         showSeconds?: number;
         intervalSeconds?: number;
         alignedCycle?: boolean;
+        cycleSeconds?: number;
+        readySeconds?: number;
         allowAdditionalBatches?: boolean;
         limitsZeroMeansUnlimited?: boolean;
         [key: string]: unknown;
@@ -132,6 +139,8 @@ export interface GameEntry {
     serverTime: number;
 }
 export interface GameIssue {
+    revision: WireId;
+    targetTime: number;
     id: WireId;
     issue: WireId;
     gameId: number;
@@ -147,7 +156,6 @@ export interface GameIssue {
     cashoutCount: number;
     showMillis: number;
     createAt: number | null;
-    openAt?: number | null;
     closeAt: number | null;
     startAt: number | null;
     resultPublishedAt: number | null;
@@ -263,7 +271,7 @@ export function actGameBet(args: {
     params?: Record<string, any>;
 }): Promise<IssueInfo>;
 export function getGameIssue(args?: { issueId?: WireId }): Promise<IssueInfo | null>;
-export function getGameIssues(args?: { earliestId?: WireId; pageSize?: number }): Promise<IssueInfo[]>;
+export function getGameIssues(args?: { gameRoomId?: number; earliestId?: WireId; pageSize?: number }): Promise<IssueInfo[]>;
 export function getGameBet(args: { betId: WireId; gameRoomId?: number }): Promise<GameBet>;
 
 export function getGameBets(args?: {
@@ -313,7 +321,7 @@ export interface EventPayloads {
     };
     flow: {
         gameRoomId: number;
-        flow: GameFlow;
+        flow: Partial<GameFlow>;
         issue: GameIssue | null;
         lastOpenedIssue: GameIssue | null;
         serverTime: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanotoolkit/game-sdk",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "private": false,
   "license": "UNLICENSED",
   "type": "module",