underpost 3.1.2 → 3.2.0

package/src/client/components/core/SocketIoHandler.js

@@ -0,0 +1,75 @@
+/**
+ * Shared factory for app-specific WebSocket event handlers.
+ * Eliminates duplication across per-app SocketIo*.js modules by providing
+ * common channel event handling (chat, email-confirmed, etc.).
+ *
+ * @module client/core/SocketIoHandler
+ * @namespace SocketIoHandlerProvider
+ */
+import { Account } from './Account.js';
+import { Chat } from './Chat.js';
+import { s4 } from './CommonJs.js';
+import { loggerFactory } from './Logger.js';
+import { SocketIo } from './SocketIo.js';
+import { s } from './VanillaJs.js';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * @class SocketIoHandlerProvider
+ * @classdesc Provides a static factory method to create app-specific SocketIo event handlers
+ * from an {@link AppStore} instance. Handles common channel events (chat, email-confirmed)
+ * and wires connect/disconnect lifecycle.
+ * @memberof SocketIoHandlerProvider
+ */
+class SocketIoHandlerProvider {
+  /**
+   * Creates a standard SocketIo event initialization object for an app module.
+   *
+   * @static
+   * @param {import('./AppStore.js').AppStore} appStore - The app-specific AppStore instance.
+   * @returns {{ Init: function(): Promise<void> }} An object with an `Init` method for SocketIo event registration.
+   */
+  static create(appStore) {
+    return {
+      Init() {
+        return new Promise((resolve) => {
+          for (const type of Object.keys(appStore.Data)) {
+            SocketIo.Event[type][s4()] = async (args) => {
+              args = JSON.parse(args[0]);
+              switch (type) {
+                case 'chat':
+                  {
+                    const idModal = 'modal-chat';
+                    if (s(`.${idModal}-chat-box`)) Chat.appendChatBox({ idModal, ...args });
+                  }
+                  break;
+
+                default:
+                  break;
+              }
+              const { status } = args;
+
+              switch (status) {
+                case 'email-confirmed': {
+                  const newUser = { ...appStore.Data.user.main.model.user, emailConfirmed: true };
+                  Account.renderVerifyEmailStatus(newUser);
+                  Account.triggerUpdateEvent({ user: newUser });
+                  break;
+                }
+
+                default:
+                  break;
+              }
+            };
+          }
+          SocketIo.Event.connect[s4()] = async (reason) => {};
+          SocketIo.Event.disconnect[s4()] = async (reason) => {};
+          return resolve();
+        });
+      },
+    };
+  }
+}
+
+export { SocketIoHandlerProvider };

package/src/client/components/core/Stream.js

@@ -1,113 +1,161 @@
+/**
+ * Client-side WebRTC stream manager backed by PeerJS.
+ * Handles peer creation, media capture, and room-based A/V streaming.
+ *
+ * @module client/core/Stream
+ * @see https://peerjs.com/docs/
+ */
+
 import { loggerFactory } from './Logger.js';
 import { getProxyPath } from './Router.js';
 
-// https://peerjs.com/docs/
-
 const logger = loggerFactory(import.meta);
 
-const Stream = {
-  Data: {},
-  createPeerServer: function ({ id }) {
-    const peerOptions = {
-      host: location.hostname, // '/'
+/**
+ * @class Stream
+ * @classdesc Static manager for PeerJS connections and MediaStream lifecycle.
+ * Supports multiple concurrent peer sessions keyed by an arbitrary `id`.
+ */
+class Stream {
+  /** @type {Object.<string, { peer: Peer, options: Object }>} Active peer sessions keyed by session id. */
+  static #sessions = {};
+
+  /**
+   * Builds PeerJS connection options from current page location.
+   * @returns {{ host: string, port: number, path: string, secure: boolean }}
+   */
+  static #buildPeerOptions() {
+    return {
+      host: location.hostname,
       port: location.protocol === 'https:' ? 443 : location.port ? parseInt(location.port) + 1 : 80,
       path: `${getProxyPath()}peer`,
       secure: location.protocol === 'https:',
     };
-    logger.info('peerOptions', peerOptions);
-    this.Data[id] = {
-      peer: {
-        peerOptions,
-        server: new Peer(undefined, peerOptions),
-      },
-    };
-    return this.Data[id].peer;
-  },
-  connectToNewUser: function (
-    mediaType,
-    id,
-    userId,
-    stream,
-    onConnectStream = (mediaElement) => null,
-    onDisconnectStream = (mediaElement) => null,
-  ) {
-    // This runs when someone joins our room
-    const call = this.Data[id].peer.server.call(userId, stream); // Call the user who just joined
-    const mediaElement = this.createMediaElement(mediaType);
+  }
 
-    call.on('stream', (userMediaStream) => {
-      onConnectStream(this.renderElementStream(mediaElement, userMediaStream));
-    });
-    // If they leave, remove their video
-    call.on('close', () => {
-      onDisconnectStream(mediaElement);
-    });
-    return { call, mediaElement };
-  },
-  handlePeerDisconnect({ id }) {
-    // manually close the peer connections
-    for (let conns in this.Data[id].peer.server.connections) {
-      this.Data[id].peer.server.connections[conns].forEach((conn, index, array) => {
-        console.log(`closing ${conn.connectionId} peerConnection (${index + 1}/${array.length})`, conn.peerConnection);
-        if (conn.peerConnection && conn.peerConnection.close) conn.peerConnection.close();
+  /**
+   * Creates a PeerJS client for the given session id.
+   * @param {string} id - Unique session identifier.
+   * @returns {{ peer: Peer, options: Object }} The Peer instance and its options.
+   */
+  static createPeer(id) {
+    this.destroyPeer(id);
+    const options = this.#buildPeerOptions();
+    logger.info('peerOptions', options);
+    const peer = new Peer(undefined, options);
+    this.#sessions[id] = { peer, options };
+    return this.#sessions[id];
+  }
+
+  /**
+   * Returns an existing session or `undefined`.
+   * @param {string} id
+   * @returns {{ peer: Peer, options: Object }|undefined}
+   */
+  static getSession(id) {
+    return this.#sessions[id];
+  }
 
-        // close it using peerjs methods
-        if (conn.close) conn.close();
-      });
+  /**
+   * Destroys a peer session — closes all connections and the peer itself.
+   * @param {string} id - Session identifier.
+   */
+  static destroyPeer(id) {
+    const session = this.#sessions[id];
+    if (!session) return;
+    const { peer } = session;
+    if (peer) {
+      for (const key in peer.connections) {
+        for (const conn of peer.connections[key]) {
+          if (conn.peerConnection?.close) conn.peerConnection.close();
+          if (conn.close) conn.close();
+        }
+      }
+      if (!peer.destroyed) peer.destroy();
     }
-  },
-  renderElementStream: function (mediaElement, stream) {
-    mediaElement.srcObject = stream;
-    mediaElement.addEventListener('loadedmetadata', () => {
-      // Play the video as it loads
-      mediaElement.play();
-    });
-    return mediaElement;
-    // use example:
-    // videoGrid.append(mediaElement); // Append video element to videoGrid
-  },
-  // Access the user's video and audio
-  getMediaStream: function (
-    options = {
-      video: true,
-      audio: true,
-    },
-  ) {
-    return new Promise((resolve) => {
-      navigator.mediaDevices
-        .getUserMedia(options)
-        .then((stream) => resolve(stream))
-        .catch((error) => {
-          logger.error(error);
-          resolve(undefined);
-        });
-    });
-  },
-  removeMediaStream: function (stream) {
-    // later you can do below
-    // stop both video and audio
-    stream.getTracks().forEach((track) => {
-      track.stop();
+    delete this.#sessions[id];
+  }
+
+  /**
+   * Calls a remote peer and streams local media to them.
+   * @param {string} id - Session identifier.
+   * @param {string} remotePeerId - The remote peer's ID.
+   * @param {MediaStream} localStream - Local media stream to send.
+   * @param {Object} [callbacks]
+   * @param {function(HTMLMediaElement): void} [callbacks.onStream] - Called when remote stream arrives.
+   * @param {function(HTMLMediaElement): void} [callbacks.onClose] - Called when the call closes.
+   * @returns {{ call: import('peerjs').MediaConnection, element: HTMLVideoElement }}
+   */
+  static callPeer(id, remotePeerId, localStream, { onStream, onClose } = {}) {
+    const session = this.#sessions[id];
+    if (!session) throw new Error(`No peer session "${id}"`);
+    const call = session.peer.call(remotePeerId, localStream);
+    const element = this.createVideoElement();
+    call.on('stream', (remoteStream) => {
+      this.attachStream(element, remoteStream);
+      onStream?.(element);
     });
-    // stop only audio
-    // stream.getAudioTracks()[0].stop();
-    // stop only video
-    // stream.getVideoTracks()[0].stop();
-  },
-  createMediaElement: function (mediaType) {
-    let mediaElement;
-    switch (mediaType) {
-      case 'audio-video':
-        mediaElement = document.createElement('video'); // Create a new audio/video tag to show our audio/video
-        // mediaElement.muted = true; // Mute ourselves on our end so there is no feedback loop
+    call.on('close', () => onClose?.(element));
+    return { call, element };
+  }
+
+  // ── Media helpers ────────────────────────────────────────────────
 
-        break;
+  /**
+   * Requests user media (camera / microphone) with graceful fallback.
+   * Falls back to video-only if audio is unavailable (NotReadableError).
+   * @param {{ video?: boolean|MediaTrackConstraints, audio?: boolean|MediaTrackConstraints }} [constraints]
+   * @returns {Promise<MediaStream|undefined>}
+   */
+  static async getMediaStream(constraints = { video: true, audio: true }) {
+    const fallbacks = [
+      constraints,
+      constraints.audio ? { video: constraints.video, audio: false } : null,
+      constraints.video ? { video: false, audio: constraints.audio } : null,
+    ].filter(Boolean);
 
-      default:
-        break;
+    for (const c of fallbacks) {
+      try {
+        return await navigator.mediaDevices.getUserMedia(c);
+      } catch (err) {
+        logger.warn(`getUserMedia failed (${err.name}): ${err.message}`, c);
+      }
     }
-    return mediaElement;
-  },
-};
+    logger.error('All media capture attempts failed');
+    return undefined;
+  }
+
+  /**
+   * Stops all tracks of a MediaStream.
+   * @param {MediaStream} stream
+   */
+  static stopStream(stream) {
+    if (!stream) return;
+    stream.getTracks().forEach((track) => track.stop());
+  }
+
+  /**
+   * Creates a `<video>` element pre-configured for inline autoplay.
+   * @returns {HTMLVideoElement}
+   */
+  static createVideoElement() {
+    const video = document.createElement('video');
+    video.playsInline = true;
+    video.autoplay = true;
+    return video;
+  }
+
+  /**
+   * Attaches a MediaStream to a media element and starts playback.
+   * @param {HTMLMediaElement} element
+   * @param {MediaStream} stream
+   * @returns {HTMLMediaElement}
+   */
+  static attachStream(element, stream) {
+    element.srcObject = stream;
+    element.addEventListener('loadedmetadata', () => element.play());
+    return element;
+  }
+}
 
 export { Stream };

package/src/client/components/core/Webhook.js

@@ -1,7 +1,31 @@
+/**
+ * WebSocket session registration bridge.
+ * Registers and unregisters the authenticated user's identity with the server-side
+ * WebSocket management layer, enabling targeted real-time pushes (e.g. email confirmation).
+ *
+ * @module client/core/Webhook
+ * @namespace WebhookProvider
+ */
 import { SocketIo } from './SocketIo.js';
 
-const Webhook = {
-  register: async function (options = { user: {} }) {
+/**
+ * @class WebhookProvider
+ * @classdesc Provides static methods to register/unregister the authenticated user
+ * with the server-side WebSocket session management channels.
+ * @memberof WebhookProvider
+ */
+class WebhookProvider {
+  /**
+   * Registers the authenticated user with the server-side WebSocket channels.
+   * Creates a user↔socket mapping on the server, enabling targeted events.
+   *
+   * @static
+   * @async
+   * @param {Object} options - Registration options.
+   * @param {Object} options.user - The authenticated user object to register.
+   * @returns {Promise<void>}
+   */
+  static async register(options = { user: {} }) {
     const { user } = options;
     SocketIo.Emit('mailer', {
       status: 'register-user',
@@ -11,15 +35,24 @@ const Webhook = {
       status: 'register-user',
       user,
     });
-  },
-  unregister: async function () {
+  }
+
+  /**
+   * Unregisters the current user from server-side WebSocket channels.
+   * Cleans up the user↔socket mapping on the server.
+   *
+   * @static
+   * @async
+   * @returns {Promise<void>}
+   */
+  static async unregister() {
     SocketIo.Emit('mailer', {
       status: 'unregister-user',
     });
     SocketIo.Emit('user', {
       status: 'unregister-user',
     });
-  },
-};
+  }
+}
 
-export { Webhook };
+export { WebhookProvider };

package/src/client/components/default/AppStoreDefault.js

@@ -0,0 +1,5 @@
+import { AppStore } from '../core/AppStore.js';
+
+const AppStoreDefault = AppStore.create();
+
+export { AppStoreDefault };

package/src/client/components/default/LogInDefault.js

@@ -1,14 +1,14 @@
 import { Auth } from '../core/Auth.js';
 import { LogIn } from '../core/LogIn.js';
-import { ElementsDefault } from './ElementsDefault.js';
+import { AppStoreDefault } from './AppStoreDefault.js';
 
 const LogInDefault = async function () {
   LogIn.Event['LogInDefault'] = async (options) => {
     const { token, user } = options;
-    ElementsDefault.Data.user.main.model.user = user;
+    AppStoreDefault.Data.user.main.model.user = user;
   };
   const { user } = await Auth.sessionIn();
-  ElementsDefault.Data.user.main.model.user = user;
+  AppStoreDefault.Data.user.main.model.user = user;
 };
 
 export { LogInDefault };

package/src/client/components/default/LogOutDefault.js

@@ -1,9 +1,9 @@
 import { LogOut } from '../core/LogOut.js';
-import { ElementsDefault } from './ElementsDefault.js';
+import { AppStoreDefault } from './AppStoreDefault.js';
 
 const LogOutDefault = async function () {
   LogOut.Event['LogOutDefault'] = async (result = { user: { _id: '' } }) => {
-    ElementsDefault.Data.user.main.model.user = result.user;
+    AppStoreDefault.Data.user.main.model.user = result.user;
   };
 };
 

package/src/client/components/default/MenuDefault.js

@@ -10,7 +10,7 @@ import { SignUp } from '../core/SignUp.js';
 import { Translate } from '../core/Translate.js';
 import { htmls, s } from '../core/VanillaJs.js';
 import { extractUsernameFromPath, getProxyPath, getQueryParams } from '../core/Router.js';
-import { ElementsDefault } from './ElementsDefault.js';
+import { AppStoreDefault } from './AppStoreDefault.js';
 import Sortable from 'sortablejs';
 import { RouterDefault, BannerAppTemplate } from './RoutesDefault.js';
 import { SettingsDefault } from './SettingsDefault.js';
@@ -551,7 +551,7 @@ const MenuDefault = {
         html: async () =>
           await Account.Render({
             idModal: 'modal-account',
-            user: ElementsDefault.Data.user.main.model.user,
+            user: AppStoreDefault.Data.user.main.model.user,
             disabled: [],
           }),
         handleType: 'bar',
@@ -565,7 +565,7 @@ const MenuDefault = {
     EventsUI.onClick(`.main-btn-public-profile`, async () => {
       const { barConfig } = await Themes[Css.currentTheme]();
       const idModal = 'modal-public-profile';
-      const user = ElementsDefault.Data.user.main.model.user;
+      const user = AppStoreDefault.Data.user.main.model.user;
 
       // Check if modal already exists
       const existingModal = s(`.${idModal}`);
@@ -635,7 +635,7 @@ const MenuDefault = {
           text: Translate.Render('recover'),
         }),
         html: async () =>
-          await Recover.Render({ idModal: 'modal-recover', user: ElementsDefault.Data.user.main.model.user }),
+          await Recover.Render({ idModal: 'modal-recover', user: AppStoreDefault.Data.user.main.model.user }),
         handleType: 'bar',
         maximize: true,
         mode: 'view',
@@ -723,7 +723,7 @@ const MenuDefault = {
             await PanelForm.instance({
               idPanel: 'default-blog',
               defaultUrlImage: `${getProxyPath()}android-chrome-96x96.png`,
-              Elements: ElementsDefault,
+              appStore: AppStoreDefault,
               parentIdModal: idModal,
               scrollClassContainer: `html-${idModal}`,
               route: routeModal,

package/src/client/components/default/SocketIoDefault.js

@@ -1,54 +1,6 @@
-import { Account } from '../core/Account.js';
-import { Chat } from '../core/Chat.js';
-import { s4 } from '../core/CommonJs.js';
-import { loggerFactory } from '../core/Logger.js';
-import { SocketIo } from '../core/SocketIo.js';
-import { s } from '../core/VanillaJs.js';
-import { ElementsDefault } from './ElementsDefault.js';
+import { SocketIoHandlerProvider } from '../core/SocketIoHandler.js';
+import { AppStoreDefault } from './AppStoreDefault.js';
 
-const logger = loggerFactory(import.meta);
-
-const SocketIoDefault = {
-  Init: function () {
-    return new Promise((resolve) => {
-      for (const type of Object.keys(ElementsDefault.Data)) {
-        SocketIo.Event[type][s4()] = async (args) => {
-          args = JSON.parse(args[0]);
-          switch (type) {
-            case 'chat':
-              {
-                const idModal = 'modal-chat';
-                if (s(`.${idModal}-chat-box`)) Chat.appendChatBox({ idModal, ...args });
-              }
-              break;
-
-            default:
-              break;
-          }
-          const { status } = args;
-
-          switch (status) {
-            case 'email-confirmed': {
-              const newUser = { ...ElementsDefault.Data.user.main.model.user, emailConfirmed: true };
-              Account.renderVerifyEmailStatus(newUser);
-              Account.triggerUpdateEvent({ user: newUser });
-              break;
-            }
-
-            default:
-              break;
-          }
-        };
-      }
-      SocketIo.Event.connect[s4()] = async (reason) => {
-        // ElementsDefault.Init({ type, id, element });
-      };
-      SocketIo.Event.disconnect[s4()] = async (reason) => {
-        // ElementsDefault.removeAll();
-      };
-      return resolve();
-    });
-  },
-};
+const SocketIoDefault = SocketIoHandlerProvider.create(AppStoreDefault);
 
 export { SocketIoDefault };

package/src/client/services/core/core.service.js

@@ -17,6 +17,19 @@ const endpoint = 'core';
 
 // https://developer.mozilla.org/en-US/docs/Web/API/AbortController
 
+/**
+ * Returns the normalized proxy path from renderPayload (always trailing `/`).
+ * Falls back to `null` when no apiBaseProxyPath is set.
+ * @memberof CoreServiceClient
+ * @return {string|null}
+ */
+const getApiBaseProxyPath = () =>
+  window.renderPayload?.apiBaseProxyPath
+    ? window.renderPayload.apiBaseProxyPath === '/'
+      ? window.renderPayload.apiBaseProxyPath
+      : `${window.renderPayload.apiBaseProxyPath}/`
+    : null;
+
 /**
  * Gets the base host for API requests.
  * Uses the apiBaseHost from renderPayload if available, otherwise falls back to location.host.
@@ -35,13 +48,7 @@ const getBaseHost = () => (window.renderPayload?.apiBaseHost ? window.renderPayl
  */
 const getApiBasePath = (options) =>
   `${
-    options?.proxyPath
-      ? `/${options.proxyPath}/`
-      : window.renderPayload?.apiBaseProxyPath
-        ? window.renderPayload.apiBaseProxyPath == '/'
-          ? window.renderPayload.apiBaseProxyPath
-          : `${window.renderPayload.apiBaseProxyPath}/`
-        : getProxyPath()
+    options?.proxyPath ? `/${options.proxyPath}/` : getApiBaseProxyPath() || getProxyPath()
   }${window.renderPayload?.apiBasePath ? window.renderPayload.apiBasePath : 'api'}/`;
 
 /**
@@ -65,7 +72,11 @@ const getApiBaseUrl = (options = { id: '', endpoint: '', proxyPath: '' }) =>
  * @memberof CoreServiceClient
  * @return {string} The WebSocket base path.
  */
-const getWsBasePath = () => (getProxyPath() !== '/' ? `${getProxyPath()}socket.io/` : '/socket.io/');
+const getWsBasePath = () => {
+  const proxyPath = getApiBaseProxyPath();
+  if (proxyPath) return proxyPath !== '/' ? `${proxyPath}socket.io/` : '/socket.io/';
+  return getProxyPath() !== '/' ? `${getProxyPath()}socket.io/` : '/socket.io/';
+};
 
 /**
  * Constructs the full WebSocket base URL for connections.
@@ -321,6 +332,7 @@ export {
   payloadFactory,
   buildQueryUrl,
   getBaseHost,
+  getApiBaseProxyPath,
   getApiBasePath,
   getApiBaseUrl,
   getWsBasePath,

package/src/client/services/user/user.management.js

@@ -2,8 +2,8 @@ import { DefaultManagement } from '../default/default.management.js';
 import { UserService } from './user.service.js';
 
 const UserManagement = {
-  RenderTable: async ({ Elements }) => {
-    const user = Elements.Data.user.main.model.user;
+  RenderTable: async ({ appStore }) => {
+    const user = appStore.Data.user.main.model.user;
     const { role } = user;
     return await DefaultManagement.RenderTable({
       idModal: 'modal-user-management',

package/src/client/ssr/body/404.js

@@ -47,9 +47,12 @@ const main = () => {
         a {
           color: black;
         }
+        .main-body-ssr-404 {
+          top: 45%;
+        }
       </style>
 
-      <div class="abs center" style="top: 45%">
+      <div class="abs center main-body-ssr-404">
         ${icon}
         <br />
         <br />
@@ -57,17 +60,18 @@ const main = () => {
         <br />
         <br />${Translate.Render('page-not-found')} <br />
         <br />
-        <a href="${location.origin}">${Translate.Render('back')}</a>
+        <a target="_top" href="${location.origin}">${Translate.Render('back')}</a>
       </div>`,
   );
 };
 
-SrrComponent = () => html`<script>
-  {
-    const s = ${s};
-    const append = ${append};
-    const getLang = ${getLang};
-    const main = ${main};
-    window.onload = main;
-  }
-</script>`;
+SrrComponent = () =>
+  html`<script>
+    {
+      const s = ${s};
+      const append = ${append};
+      const getLang = ${getLang};
+      const main = ${main};
+      window.onload = main;
+    }
+  </script>`;