@usions/sdk 2.12.0 → 2.13.0

package/package.json

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

package/src/browser.js

@@ -69,7 +69,7 @@ var Usion = (function () {
    * Core Usion object with init, _post, _request
    */
   const core = {
-    version: '2.12.0', // injected from package.json at build
+    version: '2.13.0', // injected from package.json at build
     config: {},
     _initialized: false,
     _initCallback: null,
@@ -212,6 +212,22 @@ var Usion = (function () {
       return this.config.language || 'en';
     },
 
+    /**
+     * Launch parameters the host opened this app with. Use `path` to deep-link
+     * to a specific screen — e.g. when the user taps a notification sent via
+     * `Usion.notify.send({ path })`, the app reopens and `getLaunchParams().path`
+     * returns that same path so the app can route to it.
+     * @returns {{ path: string|null, ref: string|null, roomId: string|null }}
+     */
+    getLaunchParams: function() {
+      var c = this.config || {};
+      return {
+        path: c.launchPath || null,
+        ref: c.ref || c.launchRef || null,
+        roomId: c.roomId || null,
+      };
+    },
+
     /**
      * Send message to parent app
      * @private
@@ -4835,6 +4851,77 @@ var Usion = (function () {
     };
   }
 
+  /**
+   * Usion SDK Notify — let a mini-app notify its own user.
+   *
+   * A notification reaches the user even when they aren't looking at the app:
+   *   - online elsewhere in Usion  -> in-app banner
+   *   - offline / app backgrounded -> OS push notification
+   * Tapping it re-opens THIS mini-app, optionally at a specific internal screen
+   * via `path` (read back on launch with `Usion.getLaunchParams().path`).
+   *
+   * Rides the unified backend channel, so it works standalone AND embedded.
+   * Scope & safety: a notification can only target the CURRENT user (you cannot
+   * notify other people from here), and the platform rate-limits per user per
+   * service. Users can silence a service with `setMuted(true)`.
+   *
+   *   await Usion.notify.send({
+   *     title: 'Render complete',
+   *     body: 'Your video is ready to view.',
+   *     path: '/render/abc123',     // optional — deep-links inside the app
+   *   });
+   *
+   *   await Usion.notify.setMuted(true);   // user opts out for this app
+   *   const muted = await Usion.notify.isMuted();
+   *
+   * For server-triggered notifications (e.g. a long-running job finishing while
+   * the app is closed), a mini-app's own backend calls the signed REST endpoint
+   * `POST /services/{id}/notify` instead — see the publishing reference.
+   */
+  function createNotifyModule(Usion) {
+    function serviceId(opts) {
+      return (opts && opts.serviceId) || (Usion.config && Usion.config.serviceId);
+    }
+
+    return {
+      /**
+       * Send a notification to the current user.
+       * @param {{title: string, body: string, path?: string, serviceId?: string}} opts
+       * @returns {Promise<{success: boolean, delivered?: string}>}
+       */
+      send: function (opts) {
+        opts = opts || {};
+        return Usion._backendEmit('notify:send', {
+          service_id: serviceId(opts),
+          title: opts.title,
+          body: opts.body,
+          path: opts.path,
+        });
+      },
+
+      /**
+       * Mute (or unmute) notifications from this app for the current user.
+       * @param {boolean} muted
+       * @returns {Promise<{success: boolean, muted: boolean}>}
+       */
+      setMuted: function (muted, opts) {
+        return Usion._backendEmit('notify:set_pref', {
+          service_id: serviceId(opts),
+          muted: !!muted,
+        });
+      },
+
+      /**
+       * Whether the current user has muted notifications from this app.
+       * @returns {Promise<boolean>}
+       */
+      isMuted: function (opts) {
+        return Usion._backendEmit('notify:get_pref', { service_id: serviceId(opts) })
+          .then(function (r) { return !!(r && r.muted); });
+      },
+    };
+  }
+
   /**
    * Usion SDK — unified backend channel.
    *
@@ -4972,6 +5059,7 @@ var Usion = (function () {
   Usion.leaderboard = createLeaderboardModule(Usion);
   Usion.cloud = createCloudModule(Usion);
   Usion.matchmaking = createMatchmakingModule(Usion);
+  Usion.notify = createNotifyModule(Usion);
 
   // Netcode toolkit (transport-agnostic, zero-dependency).
   Usion.netcode = netcode;

package/src/modules/core.js

@@ -209,6 +209,22 @@ export const core = {
     return this.config.language || 'en';
   },
 
+  /**
+   * Launch parameters the host opened this app with. Use `path` to deep-link
+   * to a specific screen — e.g. when the user taps a notification sent via
+   * `Usion.notify.send({ path })`, the app reopens and `getLaunchParams().path`
+   * returns that same path so the app can route to it.
+   * @returns {{ path: string|null, ref: string|null, roomId: string|null }}
+   */
+  getLaunchParams: function() {
+    var c = this.config || {};
+    return {
+      path: c.launchPath || null,
+      ref: c.ref || c.launchRef || null,
+      roomId: c.roomId || null,
+    };
+  },
+
   /**
    * Send message to parent app
    * @private

package/src/modules/index.js

@@ -29,6 +29,7 @@ import { createLobbyModule } from './lobby.js';
 import { createLeaderboardModule } from './leaderboard.js';
 import { createCloudModule } from './cloud.js';
 import { createMatchmakingModule } from './matchmaking.js';
+import { createNotifyModule } from './notify.js';
 import { applyBackendChannel } from './backend-channel.js';
 import { netcode } from './netcode/index.js';
 import { UsionError, ERROR_CODES } from './errors.js';
@@ -54,6 +55,7 @@ Usion.lobby = createLobbyModule(Usion);
 Usion.leaderboard = createLeaderboardModule(Usion);
 Usion.cloud = createCloudModule(Usion);
 Usion.matchmaking = createMatchmakingModule(Usion);
+Usion.notify = createNotifyModule(Usion);
 
 // Netcode toolkit (transport-agnostic, zero-dependency).
 Usion.netcode = netcode;

package/src/modules/notify.js

@@ -0,0 +1,70 @@
+/**
+ * Usion SDK Notify — let a mini-app notify its own user.
+ *
+ * A notification reaches the user even when they aren't looking at the app:
+ *   - online elsewhere in Usion  -> in-app banner
+ *   - offline / app backgrounded -> OS push notification
+ * Tapping it re-opens THIS mini-app, optionally at a specific internal screen
+ * via `path` (read back on launch with `Usion.getLaunchParams().path`).
+ *
+ * Rides the unified backend channel, so it works standalone AND embedded.
+ * Scope & safety: a notification can only target the CURRENT user (you cannot
+ * notify other people from here), and the platform rate-limits per user per
+ * service. Users can silence a service with `setMuted(true)`.
+ *
+ *   await Usion.notify.send({
+ *     title: 'Render complete',
+ *     body: 'Your video is ready to view.',
+ *     path: '/render/abc123',     // optional — deep-links inside the app
+ *   });
+ *
+ *   await Usion.notify.setMuted(true);   // user opts out for this app
+ *   const muted = await Usion.notify.isMuted();
+ *
+ * For server-triggered notifications (e.g. a long-running job finishing while
+ * the app is closed), a mini-app's own backend calls the signed REST endpoint
+ * `POST /services/{id}/notify` instead — see the publishing reference.
+ */
+export function createNotifyModule(Usion) {
+  function serviceId(opts) {
+    return (opts && opts.serviceId) || (Usion.config && Usion.config.serviceId);
+  }
+
+  return {
+    /**
+     * Send a notification to the current user.
+     * @param {{title: string, body: string, path?: string, serviceId?: string}} opts
+     * @returns {Promise<{success: boolean, delivered?: string}>}
+     */
+    send: function (opts) {
+      opts = opts || {};
+      return Usion._backendEmit('notify:send', {
+        service_id: serviceId(opts),
+        title: opts.title,
+        body: opts.body,
+        path: opts.path,
+      });
+    },
+
+    /**
+     * Mute (or unmute) notifications from this app for the current user.
+     * @param {boolean} muted
+     * @returns {Promise<{success: boolean, muted: boolean}>}
+     */
+    setMuted: function (muted, opts) {
+      return Usion._backendEmit('notify:set_pref', {
+        service_id: serviceId(opts),
+        muted: !!muted,
+      });
+    },
+
+    /**
+     * Whether the current user has muted notifications from this app.
+     * @returns {Promise<boolean>}
+     */
+    isMuted: function (opts) {
+      return Usion._backendEmit('notify:get_pref', { service_id: serviceId(opts) })
+        .then(function (r) { return !!(r && r.muted); });
+    },
+  };
+}

package/types/index.d.ts

@@ -24,6 +24,13 @@ export interface UsionConfig {
   serviceName?: string;
   apiUrl?: string;
   connectionMode?: 'platform' | 'direct';
+  /**
+   * Internal path the host opened this app at — set when the user taps a
+   * notification carrying a `path`. Read via `Usion.getLaunchParams().path`.
+   */
+  launchPath?: string;
+  /** Referral code the app was opened with, if any. */
+  ref?: string;
 }
 
 // ─── Payment ─────────────────────────────────────────────────────
@@ -753,6 +760,13 @@ export interface UsionSDK {
   getTheme(): 'light' | 'dark';
   getLanguage(): string;
 
+  /**
+   * Launch parameters the host opened this app with. `path` is the deep-link
+   * target (e.g. from a tapped `Usion.notify` notification); route to it after
+   * init so the user lands on the right screen.
+   */
+  getLaunchParams(): { path: string | null; ref: string | null; roomId: string | null };
+
   // Payments
   requestPayment(amount: number, reason: string, data?: Record<string, any>): Promise<PaymentResponse>;
 
@@ -831,9 +845,24 @@ export interface UsionSDK {
   leaderboard: LeaderboardModule;
   matchmaking: MatchmakingModule;
   cloud: CloudModule;
+  notify: NotifyModule;
   netcode: NetcodeModule;
 }
 
+/**
+ * Send notifications to the CURRENT user that reopen this app (in-app banner
+ * when online, OS push when offline). `path` deep-links to a screen, read back
+ * via `Usion.getLaunchParams().path`. Rate-limited per user per service.
+ */
+export interface NotifyModule {
+  /** Notify the current user. */
+  send(opts: { title: string; body: string; path?: string; serviceId?: string }): Promise<{ success: boolean; delivered?: string }>;
+  /** Mute/unmute notifications from this app for the current user. */
+  setMuted(muted: boolean, opts?: { serviceId?: string }): Promise<{ success: boolean; muted: boolean }>;
+  /** Whether the current user has muted this app's notifications. */
+  isMuted(opts?: { serviceId?: string }): Promise<boolean>;
+}
+
 /** Scoped server-persisted KV operations (per-user or shared). */
 export interface CloudScope {
   /** Get a value; resolves to null when the key doesn't exist. */