@usions/sdk 2.0.2 → 2.1.0

package/src/index.js

@@ -1,5 +1,5 @@
 /**
- * @usions/sdk — ES module wrapper for the Usion Mini App SDK
+ * @usions/sdk — ES module entry point for the Usion Mini App SDK
  *
  * Usage:
  *   import Usion from '@usions/sdk';
@@ -7,49 +7,4 @@
  *   import { Usion } from '@usions/sdk';
  */
 
-// Create a synthetic global for the IIFE to attach to
-const _global = {};
-
-// Execute the IIFE SDK with our synthetic global
-(function (global) {
-  'use strict';
-
-  // ---- Begin inlined SDK bootstrap ----
-  // We re-export the Usion object that the IIFE creates.
-  // Rather than duplicating the full SDK source, we dynamically load it.
-  // For the npm module path, consumers import this file;
-  // for script-tag usage, they load browser.js directly.
-  // ---- End inlined SDK bootstrap ----
-
-  // Attach a marker so consumers can detect the module version
-  global.__USION_SDK_MODULE__ = true;
-})(_global);
-
-// Dynamic import approach: read the IIFE SDK and evaluate it
-import { readFileSync } from 'fs';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Create a minimal global-like object for the IIFE
-const _sdkGlobal = {};
-const sdkSource = readFileSync(join(__dirname, 'browser.js'), 'utf-8');
-
-// Replace the IIFE's global reference to capture the Usion object
-const wrappedSource = sdkSource
-  .replace(
-    /\}\)\(typeof window !== 'undefined' \? window : this\);?\s*$/,
-    '})(_sdkGlobal);'
-  );
-
-// Execute in a function scope to avoid polluting
-const execFn = new Function('_sdkGlobal', wrappedSource);
-execFn(_sdkGlobal);
-
-/** The Usion SDK instance */
-const Usion = _sdkGlobal.Usion;
-
-export { Usion };
-export default Usion;
+export { default as Usion, default } from './modules/index.js';

package/src/modules/back-button.js

@@ -0,0 +1,26 @@
+/**
+ * Usion SDK Back Button — claim/release host back button for in-app navigation
+ */
+
+export function createBackButtonMethods(Usion) {
+  return {
+    /**
+     * Claim the host app's back button for one-time in-app navigation.
+     * When claimed, pressing back sends BACK_BUTTON_PRESSED to the mini app
+     * instead of closing it. Automatically resets after one press.
+     * @param {function} callback - Called when the user presses the claimed back button
+     */
+    claimBackButton: function(callback) {
+      Usion._backButtonCallback = callback;
+      Usion._post({ type: 'CLAIM_BACK_BUTTON' });
+    },
+
+    /**
+     * Release a previously claimed back button, restoring default close behavior.
+     */
+    releaseBackButton: function() {
+      Usion._backButtonCallback = null;
+      Usion._post({ type: 'RELEASE_BACK_BUTTON' });
+    }
+  };
+}

package/src/modules/bot.js

@@ -0,0 +1,52 @@
+/**
+ * Usion SDK Bot Bridge — for inline bot iframes
+ */
+
+export function createBotModule(Usion) {
+  return {
+    _messageHandler: null,
+
+    /**
+     * Call a bot action. Delivered as an "iframe_action" webhook to the bot's server.
+     * @param {string} action - Action name (e.g., "submit_form", "select_item")
+     * @param {object} [data] - Action payload
+     * @returns {Promise} Resolves when the host app confirms delivery
+     */
+    callAction: function(action, data) {
+      return Usion._request('CALL_BOT', { action: action, data: data || {} }, 30000);
+    },
+
+    /**
+     * Send a message as if the user typed it. Triggers the normal bot webhook flow.
+     * @param {string} text - Message text
+     */
+    sendMessage: function(text) {
+      Usion._post({ type: 'SEND_USER_MESSAGE', text: text });
+    },
+
+    /**
+     * Update context metadata visible to the bot on the next webhook delivery.
+     * @param {object} ctx - Context key/value pairs
+     */
+    updateContext: function(ctx) {
+      Usion._post({ type: 'UPDATE_CONTEXT', context: ctx });
+    },
+
+    /**
+     * Close the iframe, optionally returning a result to the bot.
+     * @param {object} [result] - Optional result data
+     */
+    close: function(result) {
+      Usion._post({ type: 'CLOSE', result: result });
+    },
+
+    /**
+     * Listen for new bot messages in the conversation.
+     * Called whenever the bot sends a message (text, components, etc.).
+     * @param {function} callback - Called with { id, content, content_type, components, sender_id }
+     */
+    onMessage: function(callback) {
+      this._messageHandler = callback;
+    }
+  };
+}

package/src/modules/chat.js

@@ -0,0 +1,35 @@
+/**
+ * Usion SDK Chat Module — messaging between users
+ */
+
+/**
+ * @param {object} Usion - Reference to the main Usion object
+ */
+export function createChatModule(Usion) {
+  return {
+    /**
+     * Request to send a message to another user.
+     * The parent app will show a confirmation prompt to the user.
+     * @param {string} recipientId - Usion user ID of the recipient
+     * @param {string} message - Message content to send
+     * @returns {Promise<{success: boolean, reason?: string}>}
+     */
+    sendMessage: function(recipientId, message) {
+      return Usion._request('SEND_MESSAGE_REQUEST', {
+        recipientId: recipientId,
+        message: message
+      });
+    },
+
+    /**
+     * Create a personal chat with another user (no message sent).
+     * @param {string} peerUserId - Usion user ID of the other user
+     * @returns {Promise<{chatId: string, peerName: string, peerUsername: string, peerAvatar: string}>}
+     */
+    createPersonalChat: function(peerUserId) {
+      return Usion._request('CREATE_PERSONAL_CHAT', {
+        peerUserId: peerUserId
+      });
+    }
+  };
+}

package/src/modules/core.js

@@ -0,0 +1,207 @@
+/**
+ * Usion SDK Core — init, _post, _request, message handling
+ */
+
+// Request ID counter for tracking async responses
+let _requestId = 0;
+export const _pendingRequests = {};
+
+export function getNextRequestId() {
+  return ++_requestId;
+}
+
+/**
+ * Core Usion object with init, _post, _request
+ */
+export const core = {
+  version: '2.1.0',
+  config: {},
+  _initialized: false,
+  _initCallback: null,
+  _messageHandlerRegistered: false,
+  _results: [],
+  _backButtonCallback: null,
+
+  /**
+   * Initialize the SDK with config from parent app
+   * @param {function} callback - Called with config when ready
+   */
+  init: function(callback) {
+    const self = this;
+
+    // Prevent double initialization - just update callback
+    if (self._initialized) {
+      if (callback) callback(self.config);
+      return;
+    }
+
+    // Store callback for when config arrives
+    self._initCallback = callback;
+
+    // Only register message handler once
+    if (self._messageHandlerRegistered) {
+      return;
+    }
+    self._messageHandlerRegistered = true;
+
+    // Setup global message handler
+    window.addEventListener('message', function(event) {
+      let data;
+      try {
+        data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
+      } catch (e) {
+        return;
+      }
+
+      // Handle INIT message
+      if (data.type === 'INIT' && data.config) {
+        // Prevent double config - only set once
+        if (self._initialized) {
+          return;
+        }
+
+        self.config = data.config;
+        self._initialized = true;
+        // We received INIT from a parent -> we are embedded (iframe or WebView)
+        self._isEmbedded = true;
+
+        // Initialize user module with config data
+        if (data.config.userId) {
+          self.user._id = data.config.userId;
+          self.user._name = data.config.userName;
+          self.user._avatar = data.config.userAvatar;
+          self.user._token = data.config.authToken;
+        }
+
+        // Initialize session module
+        if (data.config.sessionId) {
+          self.session._id = data.config.sessionId;
+          self.session._data = data.config.sessionData || {};
+        }
+
+        // Initialize wallet with balance if provided
+        if (data.config.balance !== undefined) {
+          self.wallet._balance = data.config.balance;
+        }
+
+        // Initialize results from server
+        if (data.config.results) {
+          self._results = data.config.results;
+        }
+
+        // Call the stored init callback
+        if (self._initCallback) {
+          self._initCallback(data.config);
+        }
+      }
+
+      // Handle response messages for async requests
+      if (data._requestId && _pendingRequests[data._requestId]) {
+        const { resolve, reject } = _pendingRequests[data._requestId];
+        delete _pendingRequests[data._requestId];
+
+        if (data.error) {
+          reject(new Error(data.error));
+        } else {
+          resolve(data);
+        }
+      }
+
+      // Handle balance updates
+      if (data.type === 'BALANCE_UPDATE') {
+        self.wallet._balance = data.balance;
+        if (self.wallet._balanceChangeHandler) {
+          self.wallet._balanceChangeHandler(data.balance);
+        }
+      }
+
+      // Handle back button pressed (one-time claim)
+      if (data.type === 'BACK_BUTTON_PRESSED' && self._backButtonCallback) {
+        var cb = self._backButtonCallback;
+        self._backButtonCallback = null; // one-time use
+        cb();
+      }
+
+      // Handle bot messages forwarded from host app
+      if (data.type === 'BOT_MESSAGE' && self.bot && self.bot._messageHandler) {
+        self.bot._messageHandler(data.message);
+      }
+    });
+
+    // Signal ready to parent
+    this._post({ type: 'READY' });
+  },
+
+  /**
+   * Get the current theme ('light' or 'dark')
+   * @returns {string}
+   */
+  getTheme: function() {
+    return this.config.theme || 'light';
+  },
+
+  /**
+   * Get the current language/locale (e.g. 'en', 'mn')
+   * @returns {string}
+   */
+  getLanguage: function() {
+    return this.config.language || 'en';
+  },
+
+  /**
+   * Send message to parent app
+   * @private
+   */
+  _post: function(message) {
+    const msg = JSON.stringify(message);
+
+    // React Native WebView
+    if (window.ReactNativeWebView) {
+      window.ReactNativeWebView.postMessage(msg);
+      return;
+    }
+
+    // Web iframe
+    if (window.parent !== window) {
+      window.parent.postMessage(message, '*');
+    }
+  },
+
+  /**
+   * Send async request to parent and wait for response
+   * @private
+   */
+  _request: function(type, data, timeout) {
+    const self = this;
+    timeout = timeout || 5000;
+
+    return new Promise(function(resolve, reject) {
+      const requestId = getNextRequestId();
+
+      // Setup timeout
+      const timer = setTimeout(function() {
+        delete _pendingRequests[requestId];
+        reject(new Error('Request timeout'));
+      }, timeout);
+
+      // Store pending request
+      _pendingRequests[requestId] = {
+        resolve: function(result) {
+          clearTimeout(timer);
+          resolve(result);
+        },
+        reject: function(error) {
+          clearTimeout(timer);
+          reject(error);
+        }
+      };
+
+      // Send request
+      self._post({
+        type: type,
+        _requestId: requestId,
+        ...data
+      });
+    });
+  }
+};

package/src/modules/file-storage.js

@@ -0,0 +1,46 @@
+/**
+ * Usion SDK File Storage — large binary data (IndexedDB / filesystem)
+ *
+ * Scoped per-user, per-service like regular storage.
+ * Uses IndexedDB (web) or filesystem (mobile) — no localStorage size limits.
+ */
+
+export function createFileStorageModule(sdk) {
+  return {
+    /**
+     * Store a file (base64 encoded)
+     * @param {string} key - Storage key
+     * @param {string} base64Data - Base64-encoded file content (no data: prefix)
+     * @param {string} mimeType - MIME type (e.g. 'image/png')
+     * @returns {Promise<void>}
+     */
+    set: function(key, base64Data, mimeType) {
+      return sdk._request('FILE_STORAGE_SET', {
+        key: key,
+        base64Data: base64Data,
+        mimeType: mimeType || 'application/octet-stream'
+      }, 30000).then(function() { return; });
+    },
+
+    /**
+     * Get a stored file
+     * @param {string} key - Storage key
+     * @returns {Promise<{base64Data: string, mimeType: string} | null>}
+     */
+    get: function(key) {
+      return sdk._request('FILE_STORAGE_GET', { key: key }, 30000).then(function(response) {
+        if (!response || !response.base64Data) return null;
+        return { base64Data: response.base64Data, mimeType: response.mimeType };
+      });
+    },
+
+    /**
+     * Remove a stored file
+     * @param {string} key - Storage key
+     * @returns {Promise<void>}
+     */
+    remove: function(key) {
+      return sdk._request('FILE_STORAGE_REMOVE', { key: key }).then(function() { return; });
+    }
+  };
+}

package/src/modules/game-core.js

@@ -0,0 +1,149 @@
+/**
+ * Usion SDK Game Core — game module base, connect routing, event registrations
+ */
+
+import { applyGameDirect } from './game-direct.js';
+import { applyGameSocket } from './game-socket.js';
+import { applyGameProxy } from './game-proxy.js';
+import { applyGameMethods } from './game-methods.js';
+
+/**
+ * Create the game module with all sub-modules applied
+ * @param {object} Usion - Reference to the main Usion object
+ */
+export function createGameModule(Usion) {
+  const game = {
+    socket: null,
+    directSocket: null,
+    roomId: null,
+    playerId: null,
+    connected: false,
+    directMode: false,
+    directConfig: null,
+    _directSeq: 0,
+    _eventHandlers: {},
+    _lastSequence: 0,
+    _connecting: false,
+    _connectPromise: null,
+    _joined: false,
+    _joinPromise: null,
+    _useProxy: false,
+    _proxyListenerSetup: false,
+    _heartbeatInterval: null,
+
+    /**
+     * Connect to the game socket server
+     * @param {string} socketUrl - Socket.IO server URL (optional, uses config)
+     * @param {string} token - JWT auth token (optional, uses user.getToken())
+     * @returns {Promise} Resolves when connected
+     */
+    connect: function(socketUrl, token) {
+      const self = this;
+      var connectionMode = (Usion.config && Usion.config.connectionMode) || 'platform';
+      if (connectionMode === 'direct') {
+        return self.connectDirect();
+      }
+
+      // Use config values as defaults
+      socketUrl = socketUrl || Usion.config.socketUrl;
+      token = token || Usion.user.getToken();
+
+      if (!socketUrl) {
+        return Promise.reject(new Error('No socket URL provided'));
+      }
+      if (!token) {
+        return Promise.reject(new Error('No auth token available'));
+      }
+
+      // If already connected (direct or proxy), return immediately
+      if (self._useProxy && self.connected) {
+        return Promise.resolve();
+      }
+      if (self.socket && self.connected) {
+        return Promise.resolve();
+      }
+
+      // If currently connecting, return the existing promise
+      if (self._connecting && self._connectPromise) {
+        return self._connectPromise;
+      }
+
+      // When running inside an iframe or WebView, use parent as socket proxy
+      var isInFrame = !!window.__USION_PROXY__
+                   || window.parent !== window
+                   || !!window.ReactNativeWebView
+                   || !!Usion._isEmbedded;
+
+      if (isInFrame) {
+        Usion.log('Running in iframe \u2013 using parent app as socket proxy');
+        return self._connectViaProxy();
+      }
+
+      self._connecting = true;
+      self._connectPromise = new Promise(function(resolve, reject) {
+        // Check if socket.io-client is available
+        if (typeof io === 'undefined') {
+          // Load socket.io client
+          var script = document.createElement('script');
+          script.src = '/socket.io.min.js';
+          script.onload = function() {
+            self._initSocket(socketUrl, token, resolve, reject);
+          };
+          script.onerror = function() {
+            // Local file not available, try CDN as fallback
+            var cdnScript = document.createElement('script');
+            cdnScript.src = 'https://cdn.socket.io/4.7.2/socket.io.min.js';
+            cdnScript.onload = function() {
+              self._initSocket(socketUrl, token, resolve, reject);
+            };
+            cdnScript.onerror = function() {
+              self._connecting = false;
+              reject(new Error('Failed to load Socket.IO client'));
+            };
+            document.head.appendChild(cdnScript);
+          };
+          document.head.appendChild(script);
+        } else {
+          self._initSocket(socketUrl, token, resolve, reject);
+        }
+      });
+
+      return self._connectPromise;
+    },
+
+    // Event handler registrations
+    onJoined: function(callback) { this._eventHandlers.joined = callback; },
+    onPlayerJoined: function(callback) { this._eventHandlers.playerJoined = callback; },
+    onPlayerLeft: function(callback) { this._eventHandlers.playerLeft = callback; },
+    onStateUpdate: function(callback) { this._eventHandlers.stateUpdate = callback; },
+    onSync: function(callback) { this._eventHandlers.sync = callback; },
+    onAction: function(callback) { this._eventHandlers.action = callback; },
+    onRealtime: function(callback) { this._eventHandlers.realtime = callback; },
+    onGameFinished: function(callback) { this._eventHandlers.finished = callback; },
+    onGameRestarted: function(callback) { this._eventHandlers.restarted = callback; },
+    onError: function(callback) { this._eventHandlers.error = callback; },
+    onRematchRequest: function(callback) { this._eventHandlers.rematchRequest = callback; },
+    onDisconnect: function(callback) { this._eventHandlers.disconnect = callback; },
+    onReconnect: function(callback) { this._eventHandlers.reconnect = callback; },
+    onConnectionError: function(callback) { this._eventHandlers.connectionError = callback; },
+
+    /**
+     * Register a generic event handler
+     * @param {string} event - Event name
+     * @param {function} callback - Handler function
+     */
+    on: function(event, callback) {
+      if (this.socket) {
+        this.socket.on(event, callback);
+      }
+    }
+  };
+
+  // Apply sub-modules
+  applyGameDirect(game, Usion);
+  applyGameSocket(game, Usion);
+  applyGameProxy(game, Usion);
+  applyGameMethods(game, Usion);
+
+  return game;
+}