nodebb-plugin-rechavimzelaze-push

Sends NodeBB notifications (new reply, new chat message, mention, etc.) to the "רכבים זה לזה" Android app as Firebase Cloud Messaging push notifications.

Built and verified directly against the NodeBB core source (hook names, payload shapes, route helpers, CSRF handling, and the generic ACP settings mechanism were all confirmed by reading notifications.js, messaging/notifications.js, routes/helpers.js, middleware/*.js and public/src/admin/settings.js in the NodeBB repo) rather than guessed - but it has not been installed/run against a live NodeBB instance, so treat the first install as a test.

How it works

1. The Android app registers its Firebase device token by calling POST /api/plugins/rechavimzelaze-push/register-token with { "token": "..." }, from inside the WebView's JS context (so it automatically carries the logged-in user's session cookie and CSRF token - no separate auth scheme needed).
2. Whenever NodeBB pushes a notification to a user - core's own action:notification.pushed hook - this plugin looks up that user's registered tokens and sends them a push via Firebase.
3. Firebase credentials never touch a file on the server: they're entered as a pasted Service Account JSON blob in this plugin's own ACP settings page, using NodeBB's normal generic settings mechanism (meta.config) - fits an admin who only has ACP access, no shell/file access.

Publishing so it's installable from the ACP

NodeBB's "Install Plugins" screen in ACP installs by npm package name, so this needs to exist on the public npm registry first (there's no private-install path without shell access to the server):

cd nodebb-plugin-rechavimzelaze-push
npm login          # your own npm account
npm publish

After that, nodebb-plugin-rechavimzelaze-push should be installable/searchable from ACP → Extend → Plugins on your NodeBB install (it may take a little while to show up in the community plugin listing - if it doesn't appear within a day, it can still be installed directly by exact package name in most NodeBB versions).

אבחון (Diagnostics) - if notifications aren't arriving

As of v0.1.3, the plugin's own settings page (/admin/plugins/rechavimzelaze-push) shows a live "אבחון" table with:

• when the Android app last registered a device token, and for which user
• when NodeBB last fired a notification through this plugin, for which users, and what type
• whether Firebase is currently configured (a "no" here almost always means the Service Account JSON above is missing/invalid - check for a red error in the server logs about "Firebase service account JSON is invalid" or "Failed to initialize Firebase")
• how many registered device tokens were found for the notified users
• the result of the last actual send attempt (how many of the tokens succeeded, or the error)

This was added because this host's ACP log viewer doesn't reliably surface live logs, so this page is the reliable way to see what's actually happening without shell access. Just reload the page (F5) after a test notification - no save needed, it's read-only status.

Reading it top to bottom tells you exactly where the pipeline breaks:

• no "רישום מכשיר אחרון" at all → the Android app never successfully called register-token (rebuild/reinstall the app, check it's logged in)
• registration is there but no "התראה אחרונה שהתקבלה" after a real forum reply/message → the action:notification.pushed hook isn't firing for this plugin (usually means the plugin isn't active, or wasn't restarted after activating)
• hook fired but "Firebase מוגדר?" says "no" → the Service Account JSON on this settings page is missing or invalid
• Firebase is configured but "מכשירים רשומים שנמצאו" is 0 → the uid that registered a token isn't the same uid the notification was sent to
• tokens were found but "תוצאת שליחה אחרונה" shows an error → that error message is the actual Firebase-reported reason (e.g. an invalid/expired token, or a permissions issue with the service account)

Setup after installing

1. Activate the plugin in ACP → Extend → Plugins, then restart NodeBB when prompted.
2. Go to https://rechavimzelaze.ovh/admin/plugins/rechavimzelaze-push (this plugin doesn't add itself to the ACP nav menu - just visit the URL directly).
3. In Firebase Console, open your project → Project Settings → Service Accounts → "Generate new private key". Paste the entire downloaded JSON file into the textarea and click "שמור שינויים".
4. No restart needed after that - new notifications immediately start using the saved credentials.

"התוסף אינו מופיע ברשימה הלבנה" / "plugin-not-whitelisted" on install

This is normal NodeBB behavior for every install, not something specific to your hosting - verified directly in NodeBB's own source (src/plugins/install.js, Plugins.checkWhitelist, and the client-side install flow in public/src/admin/extend/plugins.js). Before letting ACP install a not-yet-installed plugin, it first calls nbbpm's suggest endpoint (https://packages.nodebb.org/api/v1/suggest?package=<id>&version=<nbbVersion>) to get a recommended version; if that returns no match, the client still attempts the install with a null version, which then fails NodeBB's own whitelist check server-side with exactly this error.

Root cause found and fixed: the compatibility field must be named "nbbpm", not "nodebb" - confirmed by inspecting the actual published package.json of nodebb-plugin-web-push (an official, actively-maintained NodeBB Inc. plugin), which uses:

"nbbpm": { "compatibility": "^4.15.0" }

The original "nodebb": { "compatibility": ... } field name was silently ignored by nbbpm's suggestion engine - it wasn't a version-range problem, it was the wrong JSON key entirely, so nbbpm saw no compatibility declaration at all ("no suggested package version was supplied by the plugin author"). Fixed in package.json as of v0.1.2.

If this ever recurs after a future change, verify directly by checking (in your own browser, since this environment can't reach packages.nodebb.org): https://packages.nodebb.org/api/v1/suggest?package=nodebb-plugin-rechavimzelaze-push&version=<your NodeBB version>

• a "code": "no-match" response means nbbpm still doesn't have a compatible version on file, most commonly because the nbbpm.compatibility range doesn't cover your exact version, or the newly-published version hasn't propagated to nbbpm's suggest index yet (this can lag behind the plain /api/v1/plugins/<id> listing by some time).