chore: Merge 0.0.x into 0.1.x

.env.template

@@ -0,0 +1,30 @@
+# ── Required ────────────────────────────────────────────────────────────────
+# Full URL of the BigBlueButton server API (must end with /bigbluebutton/)
+BBB_URL="https://your.bbb.server/bigbluebutton/"
+
+# Shared secret of the BigBlueButton server
+BBB_SECRET="yoursupersecretkey"
+
+# ── Optional ────────────────────────────────────────────────────────────────
+# Direct URL to the plugin manifest (skips the server-side availability check).
+# Use this when the plugin is not deployed to the default BBB plugins path.
+# Example: PICK_RANDOM_USER_PLUGIN_URL="https://your.bbb.server/plugins/pick-random-user-plugin/dist/manifest.json"
+PICK_RANDOM_USER_PLUGIN_URL=""
+
+# Name of the local Docker container running BigBlueButton (only needed when
+# deploying the built plugin into a local container with the copy script).
+LOCAL_CONTAINER_NAME="bbb-local-container"
+
+# Multiply all Playwright timeouts by this factor.
+# Defaults to 2 in CI and 1 locally when not set.
+TIMEOUT_MULTIPLIER=1
+
+# Set to "true" to enable CI mode (1 worker, retries, blob reporter).
+CI="false"
+
+# Public URL of a clientSettingsOverride JSON that sets preventCloseDelaySeconds: 10.
+# Required for the countdown / close-prevention behavioural tests.
+# Must be reachable by the BBB server (a GitHub Gist raw URL works well).
+# Leave empty to skip those tests.
+# Example: PREVENT_CLOSE_DELAY_SETTINGS_URL="https://gist.githubusercontent.com/<user>/<id>/raw/<hash>/bbb-pick-random-user-prevent-close-delay.json"
+PREVENT_CLOSE_DELAY_SETTINGS_URL="https://bigbluebutton.nyc3.digitaloceanspaces.com/plugins/assets/bbb-plugin-pick-random-user/prevent-close-delay-10s.json"

.github/workflows/build-plugin-deb-package.yml

@@ -2,11 +2,11 @@
 name: "📦 Build .deb package for plugin"
 on:
   push:
-    branches: [ "main"]
+    branches: [ "v0.0.x"]
     paths-ignore:
       - debian/changelog
   pull_request:
-    branches: [ "main" ]
+    branches: [ "v0.0.x" ]
     paths-ignore:
       - debian/changelog
 

.github/workflows/publish-tag.yml

@@ -19,7 +19,7 @@ jobs:
     - name: Set up Node.js
       uses: actions/setup-node@v3
       with:
-        node-version: '20'
+        node-version-file: '.nvmrc'
 
     - name: Get triggering user's email
       run: |
@@ -34,11 +34,29 @@ jobs:
         git config user.name "${{ github.actor }}"
         git config user.email "${{ github.actor_id }}+${{ github.actor }}@users.noreply.github.com"
 
-
-    - name: Bump version and push tag
+    - name: Bump version, update manifest, commit and tag
       run: |
+        set -euo pipefail
+
         npm install
-        npm version ${{ github.event.inputs.release_type }} -m "chore: bump version to %s"
+
+        # 1) Bump package.json + package-lock.json but DO NOT commit/tag yet
+        npm version ${{ github.event.inputs.release_type }} --no-git-tag-version
+
+        # 2) Read the new version from package.json
+        NEW_VERSION=$(node -p "require('./package.json').version")
+        echo "New version is: $NEW_VERSION"
+
+        # 3) Update manifest.json's "version" field to match
+        jq --arg v "$NEW_VERSION" '.version = $v' manifest.json > manifest.json.tmp
+        mv manifest.json.tmp manifest.json
+
+        # 4) Commit everything and create an annotated tag
+        git add package.json package-lock.json manifest.json
+        git commit -m "chore: bump version to $NEW_VERSION"
+        git tag -a "v$NEW_VERSION" -m "v$NEW_VERSION"
+
+        # 5) Push commit and tag
         git push --follow-tags
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release-publish-do-spaces.yml

@@ -0,0 +1,50 @@
+name: Release - publish to DO Spaces
+on:
+  push:
+    tags:
+      - 'v*'
+jobs:
+  publish-to-do-spaces:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Check DO Spaces secrets
+        id: check-secrets
+        env:
+          S3_ACCESS_KEY: ${{ secrets.S3_ACCESS_KEY }}
+          S3_SECRET_KEY: ${{ secrets.S3_SECRET_KEY }}
+          S3_BUCKET: ${{ secrets.S3_BUCKET }}
+          S3_ENDPOINT_URL: ${{ secrets.S3_ENDPOINT_URL }}
+        run: |
+          if [ -z "$S3_ACCESS_KEY" ] || [ -z "$S3_SECRET_KEY" ] || [ -z "$S3_BUCKET" ] || [ -z "$S3_ENDPOINT_URL" ]; then
+            echo "DO Spaces secrets not configured, skipping."
+            echo "configured=false" >> $GITHUB_OUTPUT
+          else
+            echo "configured=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Install node
+        if: steps.check-secrets.outputs.configured == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+
+      - name: Install dependencies
+        if: steps.check-secrets.outputs.configured == 'true'
+        run: npm ci
+
+      - name: Build dist
+        if: steps.check-secrets.outputs.configured == 'true'
+        run: npm run build-bundle
+
+      - name: Publish dist to Digital Ocean Spaces
+        if: steps.check-secrets.outputs.configured == 'true'
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.S3_ACCESS_KEY }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.S3_SECRET_KEY }}
+        run: |
+          aws s3 sync dist/ s3://${{ secrets.S3_BUCKET }}/${{ github.ref_name }}/ \
+            --endpoint-url ${{ secrets.S3_ENDPOINT_URL }}

.github/workflows/release-upload-assets.yml

@@ -0,0 +1,33 @@
+name: Release - upload assets
+on:
+  push:
+    tags:
+      - 'v*'
+permissions:
+  contents: write
+jobs:
+  upload-assets:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Install node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build dist
+        run: npm run build-bundle
+
+      - name: Zip dist
+        run: zip -r dist.zip dist/
+
+      - name: Upload dist to GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release upload ${{ github.ref_name }} dist.zip

.github/workflows/ts-code-compilation.yml

@@ -14,7 +14,7 @@ jobs:
       - name: install node
         uses: actions/setup-node@v4
         with:
-          node-version: 20.x
+          node-version-file: '.nvmrc'
       - name: run npm install
         run: npm install
       - name: typescript code compilation

.github/workflows/ts-code-validation.yml

@@ -15,7 +15,7 @@ jobs:
       - name: install node
         uses: actions/setup-node@v4
         with:
-          node-version: 20.x
+          node-version-file: '.nvmrc'
       - name: run npm install
         run: npm install
       - name: typescript code validation with eslint

.github/workflows/unit-tests.yml

@@ -0,0 +1,28 @@
+name: Unit tests
+on: [pull_request]
+
+permissions:
+  contents: read
+jobs:
+  unit-tests:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+      - name: Merge branches
+        uses: ./.github/actions/merge-branches
+      - name: install node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+      - name: run npm install
+        run: npm install
+      - name: run unit tests
+        run: npm run test:unit:coverage
+      - name: Upload coverage report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage/

.gitignore

@@ -8,3 +8,8 @@ debian/**/copyright
 debian/**/changelog.gz
 debian/**/md5sums
 debian/**/var/www/*
+memory
+playwright-report
+test-results
+.env
+coverage/*

.nvmrc

@@ -0,0 +1 @@
+22

README.md

@@ -6,19 +6,149 @@ The Pick Random User Plugin is listed in the apps gallery for presenters to pick
 
 ![Gif of plugin demo](./public/assets/plugin.gif)
 
+## Plugin Versioning
+
+Please be aware that we have a separate branch of this plugin for each version of the SDK. This ensures that everything merged into a branch is compatible with the corresponding version of the BigBlueButton core. As of now, here’s the correspondence between the branches, SDK versions, and BigBlueButton core versions:
+
+| Repository Branch | Plugin-SDK Version | BigBlueButton Core Version |
+|------------------|--------------------|----------------------------|
+| v0.0.x           | v0.0.x             | v3.x                       |
+| v0.1.x           | v0.1.x             | v4.0.x                     |
+
+For more information about the plugin API features, see the documentation (`readme` files) within the specific branch you are interested in. We separate the branches because, going forward, `v0.1.x` is becoming more and more different from `v0.0.x`.
+
+If you have any suggestions, requirements, or questions, don’t hesitate to contact us.
+
+## Configurations
+
+Down below, we list all the possible configurations this plugin supports, and then a brief explanation:
+
+```yaml
+- name: BbbPluginPickRandomUser
+  settings:
+    pingSoundEnabled: true
+    pingSoundUrl: resources/sounds/doorbell.mp3
+    browserNotificationEnabled: true
+    pickedUserTimeWindow: 10 # seconds
+    preventCloseDelaySeconds: 3 # seconds
+    modalUiScale: 1
+```
+
+| Name                   | Description                          | Default                     |
+|------------------------|--------------------------------------|-----------------------------|
+| `pingSoundEnabled`     | Flag that decides whether the ping sound is enabled for picked user    | `true`                      |
+| `pingSoundUrl`         | URL of the ping sound file           | `resources/sounds/doorbell.mp3` |
+| `browserNotificationEnabled` | Flag that decides whether to send browser notification when user is picked | `false` |
+| `pickedUserTimeWindow` | Time window to consider a user as recently picked (users that join after that time will not see the last modal) | `10`               |
+| `preventCloseDelaySeconds` | Delay in seconds before the modal can be closed to prevent accidental closures | `3` |
+| `modalUiScale` | Multiplier applied to all font sizes and spacing values in the modal UI | `1` |
+
+
+### Size Multiplier
+
+By default, the modal uses a base set of font sizes and spacing values (`modalUiScale: 1`). You can scale all of them up or down uniformly by setting `modalUiScale` to any positive number. For example, `0.8` makes everything 20% smaller and `1.5` makes everything 50% larger.
+
+```yaml
+public:
+  # ...
+  plugins:
+    - name: BbbPluginPickRandomUser
+      settings:
+        modalUiScale: 0.8  # shrink all fonts and spacing by 20%
+```
+
+The multiplier applies to: font sizes, padding, margins, gaps, and list max-heights throughout the picked-user modal and the presenter's sidekick panel.
+
+### Prevent Close Delay
+
+By default, when the modal appears showing the picked user (the view that displays the selected user's name and avatar), it cannot be closed for 3 seconds. This prevents accidental closures from misclicks. During this time:
+- The close button (X) is disabled and grayed out
+- Clicking outside the modal does nothing
+- Pressing the Escape key does nothing
+- Visual countdown indicator:
+  - **For viewers**: A text message below the user's name: "You can close this modal in X seconds"
+  - **For presenters**: A blue progress bar (similar to YouTube's) that shrinks as time passes
+
+**Note:** This delay only applies to the picked user modal. On BigBlueButton 4.0 the presenter view (used for selecting users) lives in the plugin's sidekick panel, opened from the apps gallery, and is not affected by this delay.
+
+After the countdown finishes, all close methods become available. To change this delay, add the following settings in the `/etc/bigbluebutton/bbb-html5.yml` file:
+
+```yaml
+public:
+  # ...
+  plugins:
+    - name: BbbPluginPickRandomUser
+      settings:
+        preventCloseDelaySeconds: 5  # Set to 0 to disable the delay
+```
+
+### Notification
+
+By default, browser notification when user is randomly picked is not enabled. To enable it, add the following settings in the `/etc/bigbluebutton/bbb-html5.yml` file:
+
+```yaml
+public:
+  # ...
+  plugins:
+    - name: BbbPluginPickRandomUser 
+      settings:
+        browserNotificationEnabled: false
+```
+
+### Ping sound
+
+By default, ping sound is played for the randomly picked user. To remove this feature, one must add the following configurations in their `/etc/bigbluebutton/bbb-html5.yml` file.
+
+So within that file and in `public.plugins` add the following configurations:
+
+```yaml
+- name: BbbPluginPickRandomUser
+  settings:
+    pingSoundEnabled: false
+```
+
+The result yaml will look like:
+
+```yaml
+public:
+  # ...
+  plugins:
+    - name: BbbPluginPickRandomUser 
+      settings:
+        pingSoundEnabled: false
+```
+
+Just a minor comment: This relative URLs can only be configured if the server on which BBB is running is not a cluster setup. If that's your case, you'll need to put the whole URL into the configuration. It's also worth mentioning that the default `pingSoundUrl` will work in cluster setups, so no worries on that.
+
+Some other possible `pingSoundUrl` are (and notice that this URL can be relative, if the `mp3` sound is being served from within the BBB server - and it's not a cluster setup - as showed right below):
+- resources/sounds/alarm.mp3  
+- resources/sounds/bbb-handRaise.mp3  
+- resources/sounds/LeftCall.mp3  
+- resources/sounds/RelaxingMusic.mp3  
+- resources/sounds/aristocratDrums.mp3  
+- resources/sounds/CalmMusic.mp3  
+- resources/sounds/notify.mp3  
+- resources/sounds/ScreenshareOff.mp3  
+- resources/sounds/audioSample.mp3  
+- resources/sounds/doorbell.mp3  
+- resources/sounds/Poll.mp3  
+- resources/sounds/userJoin.mp3
+
+These are the possible `mp3` that already come within a BBB server, if you want a custom sound, just add the URL to the `mp3` file there and it will work out of the box.
+
 ## Building the Plugin
 
-First, double check what branch of the repository you are working with. At time of writing branch `main` produces a version of the plugin that is suitable with BigBlueButton 3.0. Branch `v3.1.x-release` is compatible with BigBlueButton 3.1.
+First, double check what branch of the repository you are working with — see [Plugin Versioning](#plugin-versioning) above. This branch (`v0.1.x`) is the one compatible with BigBlueButton 4.0.
 
 To build the plugin for production use, follow these steps:
 
 ```bash
-cd $HOME/src/plugin-pick-random-user-plugin
+cd $HOME/src/bbb-plugin-pick-random-user
 npm ci
 npm run build-bundle
 ```
 
-The above command will generate the `dist` folder, containing the bundled JavaScript file named `PickRandomUserPlugin.js`. This file can be hosted on any HTTPS server along with its `manifest.json`.
+The above command will generate the `dist` folder, containing the bundled JavaScript file named `BbbPluginPickRandomUser.js`, a directory of locale files and a license files. These files can be hosted on any HTTPS server along with the `manifest.json` which is also part of the `dist/` directory.
 
 If you install the Plugin separated to the manifest, remember to change the `javascriptEntrypointUrl` in the `manifest.json` to the correct endpoint.
 
@@ -28,7 +158,7 @@ To use the plugin in BigBlueButton, send this parameter along in create call:
 pluginManifests=[{"url":"<your-domain>/path/to/manifest.json"}]
 ```
 
-Or additionally, you can add this same configuration in `bbb-web`'s properties in `/etc/bigbluebutton/bbb-web.properties`
+Or additionally, you can add this same configuration in `bbb-web`'s properties in `/etc/bigbluebutton/bbb-web.properties`.
 
 
 ## Development mode