@usions/sdk 2.0.1 → 2.1.0

package/src/modules/game-socket.js

@@ -0,0 +1,195 @@
+/**
+ * Usion SDK Game Socket — Socket.IO connection management
+ */
+
+/**
+ * Add Socket.IO connection methods to game module
+ * @param {object} game - The game module object
+ * @param {object} Usion - Reference to the main Usion object
+ */
+export function applyGameSocket(game, Usion) {
+  /**
+   * Initialize socket connection
+   * @private
+   */
+  game._initSocket = function(socketUrl, token, resolve, reject) {
+    const self = this;
+
+    // Prevent creating duplicate sockets
+    if (self.socket && self.socket.connected) {
+      self._connecting = false;
+      resolve();
+      return;
+    }
+
+    // Clean up any existing disconnected socket
+    if (self.socket) {
+      self.socket.disconnect();
+      self.socket = null;
+    }
+
+    try {
+      self.socket = io(socketUrl, {
+        path: '/socket.io',
+        transports: ['websocket', 'polling'],
+        auth: { token: token },
+        autoConnect: true,
+        reconnection: true,
+        reconnectionAttempts: 50,
+        reconnectionDelay: 1000,
+        reconnectionDelayMax: 10000
+      });
+
+      self.socket.on('connect', function() {
+        self.connected = true;
+        self._connecting = false;
+        Usion.log('Game socket connected');
+
+        // Start heartbeat to keep game session alive
+        if (self._heartbeatInterval) clearInterval(self._heartbeatInterval);
+        self._heartbeatInterval = setInterval(function() {
+          if (self.socket && self.connected && self.roomId) {
+            self.socket.emit('game:heartbeat', { room_id: self.roomId });
+          }
+        }, 25000);
+
+        // Re-join room after reconnect
+        if (self.roomId) {
+          self._joined = false;
+          self._joinPromise = null;
+          self.join(self.roomId)
+            .then(function() {
+              Usion.log('Reconnected - joined room ' + self.roomId);
+              self.requestSync(self._lastSequence || 0);
+            })
+            .catch(function(err) {
+              Usion.log('Rejoin failed: ' + (err && err.message ? err.message : String(err)));
+            });
+        }
+
+        resolve();
+      });
+
+      self.socket.on('connect_error', function(err) {
+        self._connecting = false;
+        Usion.log('Game socket error: ' + err.message);
+        if (self._eventHandlers.connectionError) {
+          self._eventHandlers.connectionError(err);
+        }
+        reject(err);
+      });
+
+      self.socket.on('disconnect', function(reason) {
+        self.connected = false;
+        self._joined = false;
+        self._joinPromise = null;
+        if (self._heartbeatInterval) {
+          clearInterval(self._heartbeatInterval);
+          self._heartbeatInterval = null;
+        }
+        Usion.log('Game socket disconnected: ' + reason);
+        if (self._eventHandlers.disconnect) {
+          self._eventHandlers.disconnect(reason);
+        }
+      });
+
+      self.socket.on('reconnect', function(attemptNumber) {
+        Usion.log('Game socket reconnected after ' + attemptNumber + ' attempts');
+        if (self._eventHandlers.reconnect) {
+          self._eventHandlers.reconnect(attemptNumber);
+        }
+      });
+
+      // Game event handlers
+      self.socket.on('game:joined', function(data) {
+        if (data.sequence !== undefined) {
+          self._lastSequence = data.sequence;
+        }
+        if (self._eventHandlers.joined) {
+          self._eventHandlers.joined(data);
+        }
+      });
+
+      self.socket.on('game:player_joined', function(data) {
+        if (self._eventHandlers.playerJoined) {
+          self._eventHandlers.playerJoined(data);
+        }
+      });
+
+      self.socket.on('game:player_left', function(data) {
+        if (self._eventHandlers.playerLeft) {
+          self._eventHandlers.playerLeft(data);
+        }
+      });
+
+      self.socket.on('game:state', function(data) {
+        if (data.sequence !== undefined) {
+          self._lastSequence = Math.max(self._lastSequence, data.sequence);
+        }
+        if (self._eventHandlers.stateUpdate) {
+          self._eventHandlers.stateUpdate(data);
+        }
+      });
+
+      self.socket.on('game:sync', function(data) {
+        if (data.sequence !== undefined) {
+          self._lastSequence = data.sequence;
+        }
+        if (self._eventHandlers.sync) {
+          self._eventHandlers.sync(data);
+        }
+        // Also trigger stateUpdate for backwards compat
+        if (self._eventHandlers.stateUpdate) {
+          self._eventHandlers.stateUpdate(data);
+        }
+      });
+
+      self.socket.on('game:action', function(data) {
+        if (data.sequence !== undefined) {
+          self._lastSequence = Math.max(self._lastSequence, data.sequence);
+        }
+        if (self._eventHandlers.action) {
+          self._eventHandlers.action(data);
+        }
+      });
+
+      self.socket.on('game:realtime', function(data) {
+        if (self._eventHandlers.realtime) {
+          self._eventHandlers.realtime(data);
+        }
+      });
+
+      self.socket.on('game:finished', function(data) {
+        if (data.sequence !== undefined) {
+          self._lastSequence = data.sequence;
+        }
+        if (self._eventHandlers.finished) {
+          self._eventHandlers.finished(data);
+        }
+      });
+
+      self.socket.on('game:error', function(data) {
+        Usion.log('Game error: ' + (data.message || data.code));
+        if (self._eventHandlers.error) {
+          self._eventHandlers.error(data);
+        }
+      });
+
+      self.socket.on('game:rematch_request', function(data) {
+        if (self._eventHandlers.rematchRequest) {
+          self._eventHandlers.rematchRequest(data);
+        }
+      });
+
+      self.socket.on('game:restarted', function(data) {
+        self._lastSequence = 0; // Reset sequence on rematch
+        if (self._eventHandlers.restarted) {
+          self._eventHandlers.restarted(data);
+        }
+      });
+
+    } catch (err) {
+      reject(err);
+    }
+  };
+}

package/src/modules/index.js

@@ -0,0 +1,54 @@
+/**
+ * Usion Mini App SDK v2.1
+ *
+ * JavaScript utilities for Mini Apps (Iframe Games & Services)
+ * Import via: <script src="https://usions.com/usion-sdk.js"></script>
+ *
+ * Features:
+ * - User info and authentication
+ * - Persistent storage (per-user, per-service)
+ * - Wallet/payment integration
+ * - Session management
+ * - Real-time game support via Socket.IO
+ */
+
+import { core } from './core.js';
+import { createUserModule } from './user.js';
+import { createStorageModule } from './storage.js';
+import { createWalletModule } from './wallet.js';
+import { createSessionModule } from './session.js';
+import { createChatModule } from './chat.js';
+import { createBotModule } from './bot.js';
+import { createResultsMethods } from './results.js';
+import { createBackButtonMethods } from './back-button.js';
+import { uiMethods } from './ui.js';
+import { miscMethods } from './misc.js';
+import { createFileStorageModule } from './file-storage.js';
+import { createGameModule } from './game-core.js';
+
+// Build the Usion object from core
+const Usion = Object.assign({}, core);
+
+// Attach sub-modules (these reference Usion internally)
+Usion.user = createUserModule(Usion);
+Usion.storage = createStorageModule(Usion);
+Usion.wallet = createWalletModule(Usion);
+Usion.session = createSessionModule(Usion);
+Usion.chat = createChatModule(Usion);
+Usion.bot = createBotModule(Usion);
+Usion.fileStorage = createFileStorageModule(Usion);
+Usion.game = createGameModule(Usion);
+
+// Attach results methods directly on Usion
+Object.assign(Usion, createResultsMethods(Usion));
+
+// Attach back button methods directly on Usion
+Object.assign(Usion, createBackButtonMethods(Usion));
+
+// Attach UI utilities directly on Usion
+Object.assign(Usion, uiMethods);
+
+// Attach misc methods (submit, error, exit, share, log, on, requestPayment)
+Object.assign(Usion, miscMethods);
+
+export default Usion;

package/src/modules/misc.js

@@ -0,0 +1,123 @@
+/**
+ * Usion SDK Misc — submit, error, exit, share, log, on, requestPayment (legacy)
+ */
+
+export const miscMethods = {
+  /**
+   * Request payment from user (legacy method)
+   * @deprecated Use Usion.wallet.requestPayment instead
+   */
+  requestPayment: function(amount, reason, data) {
+    return this.wallet.requestPayment(amount, reason, data);
+  },
+
+  /**
+   * Submit result and signal completion
+   * @param {object} data - Result data to send to parent
+   */
+  submit: function(data) {
+    this._post({
+      type: 'SUBMIT',
+      data: data
+    });
+  },
+
+  /**
+   * Report an error to parent app
+   * @param {string} message - Error message
+   */
+  error: function(message) {
+    this._post({
+      type: 'ERROR',
+      message: message
+    });
+  },
+
+  /**
+   * Request to close the mini app
+   * @param {object} [options] - Optional exit options
+   * @param {number} [options.backCount] - Number of screens to go back (default 1)
+   */
+  exit: function(options) {
+    var msg = { type: 'EXIT' };
+    if (options && typeof options.backCount === 'number' && options.backCount > 1) {
+      msg.backCount = options.backCount;
+    }
+    this._post(msg);
+  },
+
+  /**
+   * Share content through the app's native share and optionally post to Usions feed
+   *
+   * @param {string} contentType - Type of content: 'audio' | 'image' | 'video' | 'text' | 'mixed'
+   * @param {object} data - Content data to share:
+   *   - text: Optional text/caption for the post
+   *   - audioUrl: URL for audio content (when contentType is 'audio')
+   *   - imageUrl: URL for image content (when contentType is 'image')
+   *   - videoUrl: URL for video content (when contentType is 'video')
+   *   - thumbnailUrl: Optional thumbnail URL for video/audio
+   *   - width: Optional width for image/video
+   *   - height: Optional height for image/video
+   *   - duration: Optional duration in seconds for audio/video
+   *   - media: Array of media items for 'mixed' content type
+   *     - Each item: { type: 'image'|'video'|'audio', url: string, thumbnailUrl?, width?, height?, duration? }
+   */
+  share: function(contentType, data) {
+    var shareData = Object.assign({}, data, {
+      contentType: contentType,
+      serviceId: this.config.serviceId,
+      serviceName: this.config.serviceName
+    });
+
+    this._post({
+      type: 'SHARE',
+      contentType: contentType,
+      data: shareData
+    });
+  },
+
+  /**
+   * Download a file to the device's storage / gallery.
+   * @param {string} url - URL of the file to download
+   * @param {string} [filename] - Optional filename (default: 'download.mp4')
+   * @returns {Promise<{success: boolean, error?: string}>}
+   */
+  download: function(url, filename) {
+    return this._request('DOWNLOAD_FILE', {
+      url: url,
+      filename: filename || 'download.mp4'
+    });
+  },
+
+  /**
+   * Log message to native console (for debugging)
+   * @param {string} msg - Message to log
+   */
+  log: function(msg) {
+    this._post({
+      type: 'LOG',
+      msg: msg
+    });
+    console.log('[Usion]', msg);
+  },
+
+  /**
+   * Listen for messages from parent app
+   * @param {string} type - Message type to listen for
+   * @param {function} callback - Handler function
+   */
+  on: function(type, callback) {
+    window.addEventListener('message', function(event) {
+      let data;
+      try {
+        data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
+      } catch (e) {
+        return;
+      }
+
+      if (data.type === type) {
+        callback(data);
+      }
+    });
+  }
+};

package/src/modules/results.js

@@ -0,0 +1,34 @@
+/**
+ * Usion SDK Results — server-side result persistence across devices
+ */
+
+export function createResultsMethods(Usion) {
+  return {
+    /**
+     * Save a result to server-side storage (persists across devices).
+     * @param {string} data - Result string (URL, JSON, etc.)
+     * @param {object} [metadata] - Optional metadata (thumbnail_url, title, type)
+     * @returns {Promise<object>} The saved result document
+     */
+    saveResult: function(data, metadata) {
+      return Usion._request('SAVE_RESULT', { data: data, metadata: metadata || {} }, 15000);
+    },
+
+    /**
+     * Delete a saved result by ID.
+     * @param {string} resultId - The result ID to delete
+     * @returns {Promise<void>}
+     */
+    deleteResult: function(resultId) {
+      return Usion._request('DELETE_RESULT', { resultId: resultId });
+    },
+
+    /**
+     * Get all saved results for this service (populated from INIT config).
+     * @returns {Array} Array of result objects
+     */
+    getResults: function() {
+      return Usion._results || [];
+    }
+  };
+}

package/src/modules/session.js

@@ -0,0 +1,62 @@
+/**
+ * Usion SDK Session Module — ephemeral session data management
+ */
+
+/**
+ * @param {object} Usion - Reference to the main Usion object
+ */
+export function createSessionModule(Usion) {
+  return {
+    _id: null,
+    _data: {},
+
+    /**
+     * Get the current session ID
+     * @returns {string|null}
+     */
+    getId: function() {
+      return this._id || Usion.config.sessionId || null;
+    },
+
+    /**
+     * Get session data
+     * @param {string} key - Optional key to get specific value
+     * @returns {any} Session data or specific value
+     */
+    getData: function(key) {
+      if (key) {
+        return this._data[key];
+      }
+      return this._data;
+    },
+
+    /**
+     * Set session data (ephemeral, cleared on session end)
+     * @param {string|object} keyOrData - Key or object of data to set
+     * @param {any} value - Value if key is string
+     */
+    setData: function(keyOrData, value) {
+      if (typeof keyOrData === 'object') {
+        Object.assign(this._data, keyOrData);
+      } else {
+        this._data[keyOrData] = value;
+      }
+
+      // Notify parent of session data change
+      Usion._post({
+        type: 'SESSION_DATA_UPDATE',
+        data: this._data
+      });
+    },
+
+    /**
+     * Clear session data
+     */
+    clear: function() {
+      this._data = {};
+      Usion._post({
+        type: 'SESSION_DATA_CLEAR'
+      });
+    }
+  };
+}

package/src/modules/storage.js

@@ -0,0 +1,64 @@
+/**
+ * Usion SDK Storage Module — persistent storage (per-user, per-service)
+ */
+
+/**
+ * @param {object} Usion - Reference to the main Usion object
+ */
+export function createStorageModule(Usion) {
+  return {
+    /**
+     * Get a stored value
+     * @param {string} key - Storage key
+     * @returns {Promise<any>} Stored value or null
+     */
+    get: function(key) {
+      return Usion._request('STORAGE_GET', { key: key }).then(function(response) {
+        return response.value;
+      });
+    },
+
+    /**
+     * Set a stored value
+     * @param {string} key - Storage key
+     * @param {any} value - Value to store (will be JSON serialized)
+     * @returns {Promise<void>}
+     */
+    set: function(key, value) {
+      return Usion._request('STORAGE_SET', { key: key, value: value }).then(function() {
+        return;
+      });
+    },
+
+    /**
+     * Remove a stored value
+     * @param {string} key - Storage key
+     * @returns {Promise<void>}
+     */
+    remove: function(key) {
+      return Usion._request('STORAGE_REMOVE', { key: key }).then(function() {
+        return;
+      });
+    },
+
+    /**
+     * Clear all stored values for this service
+     * @returns {Promise<void>}
+     */
+    clear: function() {
+      return Usion._request('STORAGE_CLEAR', {}).then(function() {
+        return;
+      });
+    },
+
+    /**
+     * Get all keys
+     * @returns {Promise<string[]>}
+     */
+    keys: function() {
+      return Usion._request('STORAGE_KEYS', {}).then(function(response) {
+        return response.keys || [];
+      });
+    }
+  };
+}

package/src/modules/ui.js

@@ -0,0 +1,111 @@
+/**
+ * Usion SDK UI Utilities — DOM helpers for mini apps
+ */
+
+export const uiMethods = {
+  /**
+   * Set button to loading state
+   * @param {HTMLElement|string} btn - Button element or selector
+   * @param {boolean} loading - Whether to show loading state
+   */
+  setLoading: function(btn, loading) {
+    const el = typeof btn === 'string' ? document.querySelector(btn) : btn;
+    if (!el) return;
+
+    if (loading) {
+      el.classList.add('usion-btn-loading');
+      el.disabled = true;
+      el.dataset.originalText = el.textContent;
+    } else {
+      el.classList.remove('usion-btn-loading');
+      el.disabled = false;
+      if (el.dataset.originalText) {
+        el.textContent = el.dataset.originalText;
+      }
+    }
+  },
+
+  /**
+   * Show/hide an element
+   * @param {HTMLElement|string} el - Element or selector
+   * @param {boolean} show - Whether to show or hide
+   */
+  toggle: function(el, show) {
+    const element = typeof el === 'string' ? document.querySelector(el) : el;
+    if (!element) return;
+
+    if (show) {
+      element.classList.remove('usion-hidden', 'hidden');
+      element.classList.add('usion-visible');
+    } else {
+      element.classList.add('usion-hidden');
+      element.classList.remove('usion-visible');
+    }
+  },
+
+  /**
+   * Update character count display
+   * @param {HTMLElement|string} input - Input element or selector
+   * @param {HTMLElement|string} counter - Counter element or selector
+   * @param {number} max - Maximum characters
+   */
+  charCount: function(input, counter, max) {
+    const inputEl = typeof input === 'string' ? document.querySelector(input) : input;
+    const counterEl = typeof counter === 'string' ? document.querySelector(counter) : counter;
+
+    if (!inputEl || !counterEl) return;
+
+    function update() {
+      const count = inputEl.value.length;
+      counterEl.textContent = count + ' / ' + max;
+
+      counterEl.classList.remove('warning', 'error');
+      if (count > max * 0.9) {
+        counterEl.classList.add('error');
+      } else if (count > max * 0.7) {
+        counterEl.classList.add('warning');
+      }
+    }
+
+    inputEl.addEventListener('input', update);
+    update();
+  },
+
+  /**
+   * Create a selection handler for grid items
+   * @param {string} containerSelector - Container selector
+   * @param {string} itemSelector - Item selector
+   * @param {function} onChange - Callback when selection changes
+   */
+  selectionGrid: function(containerSelector, itemSelector, onChange) {
+    const container = document.querySelector(containerSelector);
+    if (!container) return;
+
+    let selected = null;
+
+    container.querySelectorAll(itemSelector).forEach(function(item) {
+      item.addEventListener('click', function() {
+        // Remove selection from all
+        container.querySelectorAll(itemSelector).forEach(function(i) {
+          i.classList.remove('selected');
+        });
+
+        // Select this one
+        item.classList.add('selected');
+        selected = item.dataset.value || item.dataset.id;
+
+        if (onChange) onChange(selected, item);
+      });
+    });
+
+    return {
+      getSelected: function() { return selected; },
+      clear: function() {
+        container.querySelectorAll(itemSelector).forEach(function(i) {
+          i.classList.remove('selected');
+        });
+        selected = null;
+      }
+    };
+  }
+};

package/src/modules/user.js

@@ -0,0 +1,61 @@
+/**
+ * Usion SDK User Module — user info and authentication
+ */
+
+/**
+ * @param {object} Usion - Reference to the main Usion object
+ */
+export function createUserModule(Usion) {
+  return {
+    _id: null,
+    _name: null,
+    _avatar: null,
+    _token: null,
+
+    /**
+     * Get the current user's ID
+     * @returns {string|null}
+     */
+    getId: function() {
+      return this._id || Usion.config.userId || null;
+    },
+
+    /**
+     * Get the current user's display name
+     * @returns {string|null}
+     */
+    getName: function() {
+      return this._name || Usion.config.userName || null;
+    },
+
+    /**
+     * Get the current user's avatar URL
+     * @returns {string|null}
+     */
+    getAvatar: function() {
+      return this._avatar || Usion.config.userAvatar || null;
+    },
+
+    /**
+     * Get the user's auth token for socket connections
+     * @returns {string|null}
+     */
+    getToken: function() {
+      return this._token || Usion.config.authToken || null;
+    },
+
+    /**
+     * Get full user profile
+     * @returns {Promise<object>} User profile with id, name, avatar
+     */
+    getProfile: function() {
+      return Usion._request('GET_USER_PROFILE', {}).then(function(response) {
+        return response.profile || {
+          id: Usion.user.getId(),
+          name: Usion.user.getName(),
+          avatar: Usion.user.getAvatar()
+        };
+      });
+    }
+  };
+}