@smoregg/sdk 0.4.0 → 0.5.0

package/dist/umd/smore-sdk-vanilla.umd.js

@@ -1,9 +1,28 @@
 (function (global, factory) {
   typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
   typeof define === 'function' && define.amd ? define(['exports'], factory) :
-  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.SmoreSDKIframe = {}));
+  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.SmoreSDK = {}));
 })(this, (function (exports) { 'use strict';
 
+  class DirectTransport {
+    constructor(socket) {
+      this.socket = socket;
+    }
+    emit(event, ...args) {
+      this.socket.emit(event, ...args);
+    }
+    on(event, handler) {
+      this.socket.on(event, handler);
+    }
+    off(event, handler) {
+      if (handler) {
+        this.socket.off(event, handler);
+      } else {
+        this.socket.off(event);
+      }
+    }
+  }
+
   const SMORE_MSG_PREFIX = "smore:";
   function isSmoreMessage(data) {
     return data && typeof data === "object" && typeof data.type === "string" && data.type.startsWith(SMORE_MSG_PREFIX);
@@ -75,150 +94,557 @@
     }
   }
 
-  const RESERVED_PREFIXES = ["room:", "game:"];
-  function validateEventName(event) {
-    for (const prefix of RESERVED_PREFIXES) {
-      if (event.startsWith(prefix)) {
-        console.error(`[SDK] Event name "${event}" uses reserved prefix "${prefix}". Game events must not use system prefixes.`);
-        return false;
-      }
+  const SYSTEM_PREFIX$1 = "smore:";
+  const SYSTEM_EVENTS$1 = {
+    PLAYER_JOIN: `${SYSTEM_PREFIX$1}player-join`,
+    PLAYER_LEAVE: `${SYSTEM_PREFIX$1}player-leave`,
+    GAME_OVER: `${SYSTEM_PREFIX$1}game-over`
+  };
+  const EVENT_NAME_REGEX$1 = /^[a-zA-Z]([a-zA-Z_-]*[a-zA-Z])?$/;
+  function validateEventName$1(event) {
+    if (!EVENT_NAME_REGEX$1.test(event)) {
+      throw new Error(
+        `[SmoreHost] Invalid event name "${event}". Event names must:
+  - Only contain letters (a-z, A-Z), hyphens (-), and underscores (_)
+  - Start and end with a letter (no leading/trailing - or _)`
+      );
     }
-    return true;
   }
-  function createHostBridge(options) {
-    const { parentOrigin = "*", gameId, listeners, onPlayerJoin, onPlayerLeave, onReady } = options;
-    let transport = null;
-    window.parent.postMessage({ type: "smore:ready" }, parentOrigin);
-    const messageHandler = (e) => {
-      if (parentOrigin !== "*" && e.origin !== parentOrigin) return;
-      const msg = e.data;
-      if (!isSmoreMessage(msg)) return;
-      if (msg.type === "smore:init") {
-        const { side, roomCode, players, leaderId } = msg.payload;
-        if (side !== "host") {
-          console.error("[HostBridge] Received init for wrong side:", side);
-          return;
+  class SmoreHost {
+    transport = null;
+    config;
+    _players = [];
+    _roomCode = "";
+    _leaderIndex = -1;
+    _isReady = false;
+    _isDestroyed = false;
+    boundMessageHandler = null;
+    registeredHandlers = [];
+    constructor(config = {}) {
+      this.config = config;
+      if (config.listeners) {
+        for (const event of Object.keys(config.listeners)) {
+          validateEventName$1(event);
         }
-        transport = new PostMessageTransport(parentOrigin);
-        if (listeners) {
-          Object.keys(listeners).forEach((event) => {
-            validateEventName(event);
-            const handler = listeners[event];
-            transport.on(event, handler);
-          });
+      }
+      if (config.socket) {
+        this.initBundled(config);
+      } else {
+        this.initIframe(config);
+      }
+    }
+    // ---------------------------------------------------------------------------
+    // Initialization
+    // ---------------------------------------------------------------------------
+    initBundled(config) {
+      if (!config.socket) {
+        throw new Error("[SmoreHost] socket is required for bundled games");
+      }
+      this.transport = new DirectTransport(config.socket);
+      this._roomCode = config.roomCode || "";
+      this._players = config.players || [];
+      this._leaderIndex = config.leaderIndex ?? -1;
+      this.setupEventHandlers();
+      this._isReady = true;
+      this.config.onReady?.();
+    }
+    initIframe(config) {
+      const parentOrigin = config.parentOrigin || "*";
+      window.parent.postMessage({ type: "smore:ready" }, parentOrigin);
+      this.boundMessageHandler = (e) => {
+        if (parentOrigin !== "*" && e.origin !== parentOrigin) return;
+        const msg = e.data;
+        if (!isSmoreMessage(msg)) return;
+        if (msg.type === "smore:init") {
+          const initData = msg.payload;
+          if (initData.side !== "host") {
+            console.error("[SmoreHost] Received init for wrong side:", initData.side);
+            return;
+          }
+          this.transport = new PostMessageTransport(parentOrigin);
+          this._roomCode = initData.roomCode;
+          this._players = this.mapPlayersFromInit(initData.players);
+          this._leaderIndex = this.findLeaderIndex(initData.players, initData.leaderId);
+          this.setupEventHandlers();
+          this._isReady = true;
+          this.config.onReady?.();
+        } else if (msg.type === "smore:update") {
+          const updateData = msg.payload;
+          if (updateData.players) {
+            this._players = this.mapPlayersFromInit(updateData.players);
+          }
+          if (updateData.leaderId !== void 0) {
+            this._leaderIndex = this.findLeaderIndex(this._players, updateData.leaderId);
+          }
         }
-        if (onPlayerJoin) {
-          transport.on("player:joined", (payload) => {
-            onPlayerJoin(payload.sessionId);
-          });
+      };
+      window.addEventListener("message", this.boundMessageHandler);
+    }
+    mapPlayersFromInit(players) {
+      return players.map((p, index) => ({
+        playerIndex: p.playerIndex ?? index,
+        nickname: p.nickname || `Player ${index + 1}`,
+        connected: p.connected !== false,
+        appearance: p.appearance
+      }));
+    }
+    findLeaderIndex(players, leaderId) {
+      if (!leaderId) return -1;
+      const idx = players.findIndex((p) => p.sessionId === leaderId);
+      return idx >= 0 ? idx : -1;
+    }
+    setupEventHandlers() {
+      if (!this.transport) return;
+      this.registerHandler(SYSTEM_EVENTS$1.PLAYER_JOIN, (data) => {
+        const playerIndex = data.player?.playerIndex;
+        if (playerIndex !== void 0) {
+          this.config.onPlayerJoin?.(playerIndex);
         }
-        if (onPlayerLeave) {
-          transport.on("player:left", (payload) => {
-            onPlayerLeave(payload.sessionId);
-          });
+      });
+      this.registerHandler(SYSTEM_EVENTS$1.PLAYER_LEAVE, (data) => {
+        if (data.playerIndex !== void 0) {
+          this.config.onPlayerLeave?.(data.playerIndex);
         }
-        if (onReady) {
-          onReady({ roomCode, players, leaderId });
+      });
+      this.registerHandler("room:player-joined", (data) => {
+        const playerIndex = data?.player?.playerIndex ?? data?.playerIndex;
+        if (playerIndex !== void 0) {
+          this.config.onPlayerJoin?.(playerIndex);
         }
-      }
-    };
-    window.addEventListener("message", messageHandler);
-    return {
-      broadcast: (event, data) => {
-        if (!transport) {
-          console.warn("[HostBridge] Cannot broadcast before init");
-          return;
+      });
+      this.registerHandler("room:player-left", (data) => {
+        const playerIndex = data?.playerIndex ?? data?.player?.playerIndex;
+        if (playerIndex !== void 0) {
+          this.config.onPlayerLeave?.(playerIndex);
         }
-        validateEventName(event);
-        transport.emit(event, data);
-      },
-      sendToPlayer: (playerId, event, data) => {
-        if (!transport) {
-          console.warn("[HostBridge] Cannot sendToPlayer before init");
-          return;
+      });
+      if (this.config.listeners) {
+        for (const [event, handler] of Object.entries(this.config.listeners)) {
+          if (!handler) continue;
+          this.registerHandler(event, (data) => {
+            const { playerIndex, ...rest } = data;
+            if (playerIndex !== void 0) {
+              handler(playerIndex, rest);
+            }
+          });
         }
-        transport.emit(event, { targetSessionId: playerId, ...data });
-      },
-      emitGameOver: (results) => {
-        if (!transport) {
-          console.warn("[HostBridge] Cannot emitGameOver before init");
-          return;
+      }
+    }
+    registerHandler(event, handler) {
+      if (!this.transport) return;
+      this.transport.on(event, handler);
+      this.registeredHandlers.push({ event, handler });
+    }
+    // ---------------------------------------------------------------------------
+    // Public Properties
+    // ---------------------------------------------------------------------------
+    /**
+     * Get all players in the room.
+     * Returns a copy to prevent external mutation.
+     */
+    get players() {
+      return [...this._players];
+    }
+    /**
+     * Get the room code.
+     */
+    get roomCode() {
+      return this._roomCode;
+    }
+    /**
+     * Get the leader's player index (-1 if no leader).
+     */
+    get leaderIndex() {
+      return this._leaderIndex;
+    }
+    /**
+     * Check if the host is initialized and ready.
+     */
+    get isReady() {
+      return this._isReady;
+    }
+    // ---------------------------------------------------------------------------
+    // Public Methods
+    // ---------------------------------------------------------------------------
+    /**
+     * Broadcast an event to all players.
+     *
+     * @param event - Event name (no colons allowed)
+     * @param data - Optional data payload
+     *
+     * @example
+     * ```ts
+     * host.broadcast('phase-update', { phase: 'playing' });
+     * host.broadcast('timer-tick', { remaining: 30 });
+     * ```
+     */
+    broadcast(event, data) {
+      this.ensureReady("broadcast");
+      validateEventName$1(event);
+      this.transport.emit(event, data);
+    }
+    /**
+     * Send an event to a specific player.
+     *
+     * @param playerIndex - Target player index (0, 1, 2, ...)
+     * @param event - Event name (no colons allowed)
+     * @param data - Optional data payload
+     *
+     * @example
+     * ```ts
+     * host.sendToPlayer(0, 'your-turn', { timeLimit: 30 });
+     * host.sendToPlayer(1, 'wait', { message: 'Not your turn' });
+     * ```
+     */
+    sendToPlayer(playerIndex, event, data) {
+      this.ensureReady("sendToPlayer");
+      validateEventName$1(event);
+      this.transport.emit(event, {
+        targetPlayerIndex: playerIndex,
+        ...data && typeof data === "object" ? data : { data }
+      });
+    }
+    /**
+     * Signal game over with results.
+     * This will broadcast the game over event to all players.
+     *
+     * @param results - Game results (scores, winner, etc.)
+     *
+     * @example
+     * ```ts
+     * host.gameOver({
+     *   scores: { 0: 100, 1: 75, 2: 50 },
+     *   winner: 0,
+     * });
+     * ```
+     */
+    gameOver(results) {
+      this.ensureReady("gameOver");
+      this.transport.emit(SYSTEM_EVENTS$1.GAME_OVER, { results });
+    }
+    /**
+     * Add a listener for a specific event after construction.
+     *
+     * @param event - Event name (no colons allowed)
+     * @param handler - Handler function (playerIndex, data) => void
+     * @returns Cleanup function to remove the listener
+     *
+     * @example
+     * ```ts
+     * const cleanup = host.on('tap', (playerIndex, data) => {
+     *   console.log(`Player ${playerIndex} tapped`);
+     * });
+     *
+     * // Later
+     * cleanup();
+     * ```
+     */
+    on(event, handler) {
+      validateEventName$1(event);
+      const wrappedHandler = (data) => {
+        const { playerIndex, ...rest } = data;
+        if (playerIndex !== void 0) {
+          handler(playerIndex, rest);
         }
-        transport.emit("game-over", results);
-      },
-      setLoaded: () => {
-        window.parent.postMessage({ type: "smore:loaded" }, parentOrigin);
-      },
-      destroy: () => {
-        window.removeEventListener("message", messageHandler);
-        transport?.destroy();
-        transport = null;
-      }
-    };
+      };
+      if (this.transport) {
+        this.transport.on(event, wrappedHandler);
+        this.registeredHandlers.push({ event, handler: wrappedHandler });
+      }
+      return () => {
+        this.transport?.off(event, wrappedHandler);
+        this.registeredHandlers = this.registeredHandlers.filter(
+          (h) => h.event !== event || h.handler !== wrappedHandler
+        );
+      };
+    }
+    /**
+     * Clean up all resources.
+     * Call this when unmounting/destroying the game.
+     */
+    destroy() {
+      if (this._isDestroyed) return;
+      this._isDestroyed = true;
+      this._isReady = false;
+      for (const { event, handler } of this.registeredHandlers) {
+        this.transport?.off(event, handler);
+      }
+      this.registeredHandlers = [];
+      if (this.transport instanceof PostMessageTransport) {
+        this.transport.destroy();
+      }
+      this.transport = null;
+      if (this.boundMessageHandler) {
+        window.removeEventListener("message", this.boundMessageHandler);
+        this.boundMessageHandler = null;
+      }
+    }
+    // ---------------------------------------------------------------------------
+    // Private Helpers
+    // ---------------------------------------------------------------------------
+    ensureReady(method) {
+      if (!this._isReady || !this.transport) {
+        throw new Error(`[SmoreHost] Cannot call ${method}() before host is ready. Wait for onReady callback.`);
+      }
+      if (this._isDestroyed) {
+        throw new Error(`[SmoreHost] Cannot call ${method}() after destroy()`);
+      }
+    }
   }
-  function createPlayerBridge(options) {
-    const { parentOrigin = "*", gameId, listeners, onReady } = options;
-    let transport = null;
-    window.parent.postMessage({ type: "smore:ready" }, parentOrigin);
-    const messageHandler = (e) => {
-      if (parentOrigin !== "*" && e.origin !== parentOrigin) return;
-      const msg = e.data;
-      if (!isSmoreMessage(msg)) return;
-      if (msg.type === "smore:init") {
-        const { side, roomCode, mySessionId, isLeader } = msg.payload;
-        if (side !== "player") {
-          console.error("[PlayerBridge] Received init for wrong side:", side);
-          return;
-        }
-        if (!mySessionId) {
-          console.error("[PlayerBridge] Missing mySessionId in init payload");
-          return;
+
+  const SYSTEM_PREFIX = "smore:";
+  const SYSTEM_EVENTS = {
+    PLAYER_JOIN: `${SYSTEM_PREFIX}player-join`,
+    PLAYER_LEAVE: `${SYSTEM_PREFIX}player-leave`
+  };
+  const EVENT_NAME_REGEX = /^[a-zA-Z]([a-zA-Z_-]*[a-zA-Z])?$/;
+  function validateEventName(event) {
+    if (!EVENT_NAME_REGEX.test(event)) {
+      throw new Error(
+        `[SmorePlayer] Invalid event name "${event}". Event names must:
+  - Only contain letters (a-z, A-Z), hyphens (-), and underscores (_)
+  - Start and end with a letter (no leading/trailing - or _)`
+      );
+    }
+  }
+  class SmorePlayer {
+    transport = null;
+    config;
+    _roomCode = "";
+    _myIndex = -1;
+    _isLeader = false;
+    _isReady = false;
+    _isDestroyed = false;
+    boundMessageHandler = null;
+    registeredHandlers = [];
+    constructor(config = {}) {
+      this.config = config;
+      if (config.listeners) {
+        for (const event of Object.keys(config.listeners)) {
+          validateEventName(event);
         }
-        transport = new PostMessageTransport(parentOrigin);
-        if (listeners) {
-          Object.keys(listeners).forEach((event) => {
-            validateEventName(event);
-            const handler = listeners[event];
-            transport.on(event, handler);
-          });
+      }
+      if (config.socket) {
+        this.initBundled(config);
+      } else {
+        this.initIframe(config);
+      }
+    }
+    // ---------------------------------------------------------------------------
+    // Initialization
+    // ---------------------------------------------------------------------------
+    initBundled(config) {
+      if (!config.socket) {
+        throw new Error("[SmorePlayer] socket is required for bundled games");
+      }
+      this.transport = new DirectTransport(config.socket);
+      this._roomCode = config.roomCode || "";
+      this._myIndex = config.myIndex ?? -1;
+      this._isLeader = config.isLeader ?? false;
+      this.setupEventHandlers();
+      this._isReady = true;
+      this.config.onReady?.();
+    }
+    initIframe(config) {
+      const parentOrigin = config.parentOrigin || "*";
+      window.parent.postMessage({ type: "smore:ready" }, parentOrigin);
+      this.boundMessageHandler = (e) => {
+        if (parentOrigin !== "*" && e.origin !== parentOrigin) return;
+        const msg = e.data;
+        if (!isSmoreMessage(msg)) return;
+        if (msg.type === "smore:init") {
+          const initData = msg.payload;
+          if (initData.side !== "player") {
+            console.error("[SmorePlayer] Received init for wrong side:", initData.side);
+            return;
+          }
+          if (initData.myIndex === void 0) {
+            console.error("[SmorePlayer] Missing myIndex in init payload");
+            return;
+          }
+          this.transport = new PostMessageTransport(parentOrigin);
+          this._roomCode = initData.roomCode;
+          this._myIndex = initData.myIndex;
+          this._isLeader = initData.isLeader ?? false;
+          this.setupEventHandlers();
+          this._isReady = true;
+          this.config.onReady?.();
+        } else if (msg.type === "smore:update") {
+          const updateData = msg.payload;
+          if (updateData.leaderId !== void 0) ;
         }
-        if (onReady) {
-          onReady({ roomCode, isLeader: !!isLeader, mySessionId });
+      };
+      window.addEventListener("message", this.boundMessageHandler);
+    }
+    setupEventHandlers() {
+      if (!this.transport) return;
+      this.registerHandler(SYSTEM_EVENTS.PLAYER_JOIN, (data) => {
+        const playerIndex = data.player?.playerIndex ?? data.playerIndex;
+        if (playerIndex !== void 0) {
+          this.config.onPlayerJoin?.(playerIndex);
         }
-      }
-    };
-    window.addEventListener("message", messageHandler);
-    return {
-      emit: (event, data) => {
-        if (!transport) {
-          console.warn("[PlayerBridge] Cannot emit before init");
-          return;
+      });
+      this.registerHandler(SYSTEM_EVENTS.PLAYER_LEAVE, (data) => {
+        const playerIndex = data.player?.playerIndex ?? data.playerIndex;
+        if (playerIndex !== void 0) {
+          this.config.onPlayerLeave?.(playerIndex);
         }
-        validateEventName(event);
-        transport.emit(event, data);
-      },
-      onEvent: (event, handler) => {
-        if (!transport) {
-          console.warn("[PlayerBridge] Cannot onEvent before init");
-          return () => {
-          };
+      });
+      if (this.config.listeners) {
+        for (const [event, handler] of Object.entries(this.config.listeners)) {
+          if (!handler) continue;
+          this.registerHandler(event, handler);
         }
-        validateEventName(event);
-        transport.on(event, handler);
-        return () => {
-          transport?.off(event, handler);
-        };
-      },
-      destroy: () => {
-        window.removeEventListener("message", messageHandler);
-        transport?.destroy();
-        transport = null;
-      }
-    };
+      }
+    }
+    registerHandler(event, handler) {
+      if (!this.transport) return;
+      this.transport.on(event, handler);
+      this.registeredHandlers.push({ event, handler });
+    }
+    // ---------------------------------------------------------------------------
+    // Public Properties
+    // ---------------------------------------------------------------------------
+    /**
+     * Get my player index (0, 1, 2, ...).
+     */
+    get myIndex() {
+      return this._myIndex;
+    }
+    /**
+     * Check if I am the room leader.
+     */
+    get isLeader() {
+      return this._isLeader;
+    }
+    /**
+     * Get the room code.
+     */
+    get roomCode() {
+      return this._roomCode;
+    }
+    /**
+     * Check if the player is initialized and ready.
+     */
+    get isReady() {
+      return this._isReady;
+    }
+    // ---------------------------------------------------------------------------
+    // Public Methods
+    // ---------------------------------------------------------------------------
+    /**
+     * Send an event to the host.
+     *
+     * @param event - Event name (no colons allowed)
+     * @param data - Optional data payload
+     *
+     * @example
+     * ```ts
+     * player.send('tap', { timestamp: Date.now() });
+     * player.send('answer', { choice: 2 });
+     * ```
+     */
+    send(event, data) {
+      this.ensureReady("send");
+      validateEventName(event);
+      this.transport.emit(event, data);
+    }
+    /**
+     * Add a listener for a specific event after construction.
+     *
+     * @param event - Event name (no colons allowed)
+     * @param handler - Handler function (data) => void
+     * @returns Cleanup function to remove the listener
+     *
+     * @example
+     * ```ts
+     * const cleanup = player.on('phase-update', (data) => {
+     *   console.log('New phase:', data.phase);
+     * });
+     *
+     * // Later
+     * cleanup();
+     * ```
+     */
+    on(event, handler) {
+      validateEventName(event);
+      if (this.transport) {
+        this.transport.on(event, handler);
+        this.registeredHandlers.push({ event, handler });
+      }
+      return () => {
+        this.transport?.off(event, handler);
+        this.registeredHandlers = this.registeredHandlers.filter(
+          (h) => h.event !== event || h.handler !== handler
+        );
+      };
+    }
+    /**
+     * Clean up all resources.
+     * Call this when unmounting/destroying the game.
+     */
+    destroy() {
+      if (this._isDestroyed) return;
+      this._isDestroyed = true;
+      this._isReady = false;
+      for (const { event, handler } of this.registeredHandlers) {
+        this.transport?.off(event, handler);
+      }
+      this.registeredHandlers = [];
+      if (this.transport instanceof PostMessageTransport) {
+        this.transport.destroy();
+      }
+      this.transport = null;
+      if (this.boundMessageHandler) {
+        window.removeEventListener("message", this.boundMessageHandler);
+        this.boundMessageHandler = null;
+      }
+    }
+    // ---------------------------------------------------------------------------
+    // Private Helpers
+    // ---------------------------------------------------------------------------
+    ensureReady(method) {
+      if (!this._isReady || !this.transport) {
+        throw new Error(`[SmorePlayer] Cannot call ${method}() before player is ready. Wait for onReady callback.`);
+      }
+      if (this._isDestroyed) {
+        throw new Error(`[SmorePlayer] Cannot call ${method}() after destroy()`);
+      }
+    }
+  }
+
+  const SMORE_EVENTS = {
+    // 게임 lifecycle
+    READY: "smore:ready",
+    GAME_OVER: "smore:game-over",
+    RETURN_TO_LOBBY: "smore:return-to-lobby",
+    // 플레이어 관리
+    PLAYER_JOIN: "smore:player-join",
+    PLAYER_LEAVE: "smore:player-leave",
+    // 특정 플레이어에게 전송 (내부용)
+    SEND_TO_PLAYER: "smore:send-to-player",
+    // 초기화
+    INIT: "smore:init",
+    UPDATE: "smore:update"
+  };
+  function validateUserEvent(event) {
+    if (event.includes(":")) {
+      throw new Error(
+        `Invalid event name "${event}": User events cannot contain ':'. Use '_' or '-' instead. System events use 'smore:' prefix.`
+      );
+    }
+  }
+  function isSystemEvent(event) {
+    return event.startsWith("smore:");
   }
 
-  exports.createHostBridge = createHostBridge;
-  exports.createPlayerBridge = createPlayerBridge;
+  exports.DirectTransport = DirectTransport;
+  exports.PostMessageTransport = PostMessageTransport;
+  exports.SMORE_EVENTS = SMORE_EVENTS;
+  exports.SmoreHost = SmoreHost;
+  exports.SmorePlayer = SmorePlayer;
+  exports.isSystemEvent = isSystemEvent;
+  exports.validateUserEvent = validateUserEvent;
 
 }));
 //# sourceMappingURL=smore-sdk-vanilla.umd.js.map