@usions/sdk 2.10.0 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usions/sdk",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "Usion Mini App SDK for iframe games and services",
   "type": "module",
   "main": "src/modules/index.js",

package/src/browser.js

@@ -4359,6 +4359,74 @@ var Usion = (function () {
     };
   }
 
+  /**
+   * Usion SDK Cloud — server-persisted KV storage for mini-apps.
+   *
+   * Unlike `Usion.storage` (device-local), cloud values live on the backend and
+   * survive reinstall / device switch. Enabled for every service, bounded by
+   * quotas (64 KB per value, 200 keys / 1 MB per bucket, 60 ops/min).
+   * Rides the unified backend channel, so it works standalone AND embedded.
+   *
+   * Per-user scope (each user sees only their own data):
+   *   await Usion.cloud.set('save', { level: 3 });
+   *   const save = await Usion.cloud.get('save');   // null if absent
+   *   await Usion.cloud.remove('save');
+   *   const keys = await Usion.cloud.keys();
+   *
+   * Shared scope (one bucket per app — ALL users read and write):
+   *   await Usion.cloud.shared.set('motd', 'hello');
+   *   const plays = await Usion.cloud.shared.incr('plays');  // atomic counter
+   *
+   * Keys: 1-128 chars of A-Za-z0-9_.-:/
+   */
+  function createCloudModule(Usion) {
+    function serviceId(opts) {
+      return (opts && opts.serviceId) || (Usion.config && Usion.config.serviceId);
+    }
+
+    function emit(event, scope, extra, opts) {
+      var payload = Object.assign({ service_id: serviceId(opts), scope: scope }, extra);
+      return Usion._backendEmit(event, payload);
+    }
+
+    function scopeApi(scope) {
+      return {
+        /** Get a value; resolves to null when the key doesn't exist. */
+        get: function (key, opts) {
+          return emit('kv:get', scope, { key: key }, opts)
+            .then(function (r) { return r && r.exists ? r.value : null; });
+        },
+
+        /** Set a JSON-serializable value (max 64 KB). */
+        set: function (key, value, opts) {
+          return emit('kv:set', scope, { key: key, value: value }, opts);
+        },
+
+        /** Remove a key. Resolves to { success, removed }. */
+        remove: function (key, opts) {
+          return emit('kv:remove', scope, { key: key }, opts);
+        },
+
+        /** List keys in this scope's bucket. */
+        keys: function (opts) {
+          return emit('kv:keys', scope, {}, opts)
+            .then(function (r) { return (r && r.keys) || []; });
+        },
+      };
+    }
+
+    var cloud = scopeApi('user');
+    cloud.shared = scopeApi('shared');
+
+    /** Atomically increment a shared numeric value (default delta 1). Resolves to the new value. */
+    cloud.shared.incr = function (key, delta, opts) {
+      return emit('kv:incr', 'shared', { key: key, delta: delta == null ? 1 : delta }, opts)
+        .then(function (r) { return r && r.value; });
+    };
+
+    return cloud;
+  }
+
   /**
    * Usion SDK Matchmaking — pair up with online strangers ("quick match").
    *
@@ -4552,6 +4620,7 @@ var Usion = (function () {
   applyBackendChannel(Usion);
   Usion.lobby = createLobbyModule(Usion);
   Usion.leaderboard = createLeaderboardModule(Usion);
+  Usion.cloud = createCloudModule(Usion);
   Usion.matchmaking = createMatchmakingModule(Usion);
 
   // Netcode toolkit (transport-agnostic, zero-dependency).

package/src/modules/cloud.js

@@ -0,0 +1,67 @@
+/**
+ * Usion SDK Cloud — server-persisted KV storage for mini-apps.
+ *
+ * Unlike `Usion.storage` (device-local), cloud values live on the backend and
+ * survive reinstall / device switch. Enabled for every service, bounded by
+ * quotas (64 KB per value, 200 keys / 1 MB per bucket, 60 ops/min).
+ * Rides the unified backend channel, so it works standalone AND embedded.
+ *
+ * Per-user scope (each user sees only their own data):
+ *   await Usion.cloud.set('save', { level: 3 });
+ *   const save = await Usion.cloud.get('save');   // null if absent
+ *   await Usion.cloud.remove('save');
+ *   const keys = await Usion.cloud.keys();
+ *
+ * Shared scope (one bucket per app — ALL users read and write):
+ *   await Usion.cloud.shared.set('motd', 'hello');
+ *   const plays = await Usion.cloud.shared.incr('plays');  // atomic counter
+ *
+ * Keys: 1-128 chars of A-Za-z0-9_.-:/
+ */
+export function createCloudModule(Usion) {
+  function serviceId(opts) {
+    return (opts && opts.serviceId) || (Usion.config && Usion.config.serviceId);
+  }
+
+  function emit(event, scope, extra, opts) {
+    var payload = Object.assign({ service_id: serviceId(opts), scope: scope }, extra);
+    return Usion._backendEmit(event, payload);
+  }
+
+  function scopeApi(scope) {
+    return {
+      /** Get a value; resolves to null when the key doesn't exist. */
+      get: function (key, opts) {
+        return emit('kv:get', scope, { key: key }, opts)
+          .then(function (r) { return r && r.exists ? r.value : null; });
+      },
+
+      /** Set a JSON-serializable value (max 64 KB). */
+      set: function (key, value, opts) {
+        return emit('kv:set', scope, { key: key, value: value }, opts);
+      },
+
+      /** Remove a key. Resolves to { success, removed }. */
+      remove: function (key, opts) {
+        return emit('kv:remove', scope, { key: key }, opts);
+      },
+
+      /** List keys in this scope's bucket. */
+      keys: function (opts) {
+        return emit('kv:keys', scope, {}, opts)
+          .then(function (r) { return (r && r.keys) || []; });
+      },
+    };
+  }
+
+  var cloud = scopeApi('user');
+  cloud.shared = scopeApi('shared');
+
+  /** Atomically increment a shared numeric value (default delta 1). Resolves to the new value. */
+  cloud.shared.incr = function (key, delta, opts) {
+    return emit('kv:incr', 'shared', { key: key, delta: delta == null ? 1 : delta }, opts)
+      .then(function (r) { return r && r.value; });
+  };
+
+  return cloud;
+}

package/src/modules/index.js

@@ -27,6 +27,7 @@ import { createFileStorageModule } from './file-storage.js';
 import { createGameModule } from './game-core.js';
 import { createLobbyModule } from './lobby.js';
 import { createLeaderboardModule } from './leaderboard.js';
+import { createCloudModule } from './cloud.js';
 import { createMatchmakingModule } from './matchmaking.js';
 import { applyBackendChannel } from './backend-channel.js';
 import { netcode } from './netcode/index.js';
@@ -47,6 +48,7 @@ Usion.game = createGameModule(Usion);
 applyBackendChannel(Usion);
 Usion.lobby = createLobbyModule(Usion);
 Usion.leaderboard = createLeaderboardModule(Usion);
+Usion.cloud = createCloudModule(Usion);
 Usion.matchmaking = createMatchmakingModule(Usion);
 
 // Netcode toolkit (transport-agnostic, zero-dependency).