nodebb-plugin-internalnotes 1.0.0

package/.github/workflows/publish-npm.yml

@@ -0,0 +1,33 @@
+name: Lint and publish to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  lint-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Publish to npm
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BrutalBirdie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NODEBB_STANDARDS_AUDIT.md

@@ -0,0 +1,153 @@
+# NodeBB Plugin Standards Audit
+
+This document audits **nodebb-plugin-internalnotes** against [NodeBB upstream documentation](https://docs.nodebb.org/development/) and the [nodebb-plugin-quickstart](https://github.com/NodeBB/nodebb-plugin-quickstart) template. References: [development](https://docs.nodebb.org/development/), [quickstart](https://docs.nodebb.org/development/quickstart/), [plugins](https://docs.nodebb.org/development/plugins/), [plugin.json](https://docs.nodebb.org/development/plugins/plugin.json/), [hooks](https://docs.nodebb.org/development/plugins/hooks/), [statics](https://docs.nodebb.org/development/plugins/statics/), [libraries](https://docs.nodebb.org/development/plugins/libraries/), [i18n](https://docs.nodebb.org/development/i18n/), [style guide](https://docs.nodebb.org/development/style-guide/).
+
+---
+
+## 1. plugin.json
+
+| Requirement | Status | Notes |
+|-------------|--------|--------|
+| **id** | ✅ | `nodebb-plugin-internalnotes` (unique, matches npm package name) |
+| **url** | ✅ | Absolute URL to repo |
+| **library** | ✅ | `./library.js` – entry point loaded when plugin is active |
+| **hooks** | ✅ | All hooks have `hook` and `method`; optional `priority` omitted (default 10) |
+| **scss** | ✅ | `scss/internalnotes.scss` |
+| **scripts** | ✅ | `public/lib/main.js` (forum client) |
+| **acpScripts** | ✅ | `public/lib/acp-main.js` (ACP client) |
+| **modules** | ✅ | `../admin/plugins/internalnotes.js` → `./public/lib/admin.js` (ACP page module) |
+| **templates** | ✅ | `templates` |
+| **languages** | ✅ | `languages` |
+| **staticDirs** | ⚪ | Not required; no public static assets |
+| **upgrades** | ⚪ | Optional; add when introducing DB migrations |
+
+**Verdict:** Compliant.
+
+---
+
+## 2. package.json & nbbpm
+
+| Requirement | Status | Notes |
+|-------------|--------|--------|
+| **name** | ✅ | `nodebb-plugin-internalnotes` (must be prefixed `nodebb-plugin-` for npm and NodeBB) |
+| **main** | ✅ | `library.js` |
+| **nbbpm.compatibility** | ✅ | `^3.0.0` – required for nbbpm listing and installs |
+| **repository / bugs** | ✅ | Present |
+| **keywords** | ✅ | Include `nodebb`, `plugin` |
+| **.npmignore** | ✅ | Added (node_modules, .git, .DS_Store, etc.) so only publishable files are shipped |
+
+**Verdict:** Compliant.
+
+---
+
+## 3. Library (library.js)
+
+| Requirement | Status | Notes |
+|-------------|--------|-------|
+| **Hook methods** | ✅ | Each hook in `plugin.json` has a matching exported method |
+| **require.main.require** | ✅ | NodeBB modules loaded via `require.main.require('./src/...')` |
+| **Async hooks** | ✅ | `init`, `addRoutes`, filters use async/callbacks appropriately |
+| **formatApiResponse** | ✅ | API routes use `helpers.formatApiResponse()` (and `controllerHelpers` once for 403) |
+| **Route helpers** | ✅ | `routeHelpers.setupAdminPageRoute`, `routeHelpers.setupApiRoute` used correctly |
+
+**API route paths:** Routes are registered under `/internalnotes/...`. The client and README use `/plugins/internalnotes/...`. In NodeBB 3, plugin API routes are typically mounted under `/api/v3/plugins/<plugin-id>`; the router passed to `static:api.routes` may be scoped per plugin, so `/internalnotes/:tid` can resolve to `/api/v3/plugins/internalnotes/:tid`. **Ensure the router you receive is the plugin-scoped one**; if the client calls `api.get('/plugins/internalnotes/' + tid)` and the request goes to `/api/v3/plugins/internalnotes/:tid`, the server must serve that path (either by registering `/internalnotes/...` on a router already mounted at `.../plugins/internalnotes`, or by registering `/plugins/internalnotes/...` on the main API router). No code change if your environment already matches; otherwise align server route prefix with client.
+
+**Verdict:** Compliant; verify API base path in your NodeBB version.
+
+---
+
+## 4. Client-side (scripts / acpScripts / modules)
+
+| Requirement | Status | Notes |
+|-------------|--------|--------|
+| **Forum script** | ✅ | `public/lib/main.js` – loaded via `scripts` |
+| **ACP script** | ✅ | `public/lib/acp-main.js` – loaded via `acpScripts` |
+| **Admin module** | ✅ | `modules` maps `../admin/plugins/internalnotes.js` to admin script; template `admin/plugins/internalnotes` triggers `require('admin/plugins/internalnotes')` and `init()` |
+| **ES5 / minification** | ⚠️ | Style guide recommends ES5 for client code for minification. `main.js` uses async/await and template literals (ES6+). NodeBB 3 build may transpile; if not, consider ES5 or confirm build supports ES6+ |
+| **Admin ES modules** | ✅ | `admin.js` uses `import { save, load } from 'settings'` – ACP is typically built with module support |
+
+**Verdict:** Compliant for structure; confirm client build/minification for ES6+ if you hit issues.
+
+---
+
+## 5. Templates
+
+| Requirement | Status | Notes |
+|-------------|--------|--------|
+| **Admin template** | ✅ | `templates/admin/plugins/internalnotes.tpl`; controller uses `res.render('admin/plugins/internalnotes', ...)` |
+| **Naming** | ✅ | Matches quickstart pattern `admin/plugins/<name>` |
+
+**Verdict:** Compliant.
+
+---
+
+## 6. i18n (languages)
+
+| Requirement | Status | Notes |
+|-------------|--------|--------|
+| **Directory** | ✅ | `languages/en-GB/internalnotes.json` |
+| **plugin.json** | ✅ | `"languages": "languages"` |
+| **Usage** | ✅ | Keys like `[[internalnotes:menu.assigned]]` in templates and server; client uses `translator.translate('[[internalnotes:' + key + ']]', ...)` |
+| **defaultLang** | ⚪ | Optional; only needed if you want a non–en-GB fallback |
+
+**Verdict:** Compliant.
+
+---
+
+## 7. Hooks usage
+
+| Hook | Purpose | Status |
+|------|---------|--------|
+| **static:app.load** | Init, page and admin routes | ✅ |
+| **static:api.routes** | REST API routes (notes, assign, group search) | ✅ |
+| **filter:admin.header.build** | ACP nav item | ✅ |
+| **filter:navigation.available** | “Assigned” nav item | ✅ |
+| **filter:topic.get** | Add notes/assignee to single topic | ✅ |
+| **filter:topics.get** | Add notes/assignee to topic lists | ✅ |
+| **filter:topic.thread_tools** | Thread tools entries | ✅ |
+| **action:topic.purge** | Clean up notes/assignee on topic purge | ✅ |
+
+**Verdict:** All hooks used correctly; filters return data in the expected shape.
+
+---
+
+## 8. Static directories & security
+
+- No `staticDirs` – no public static assets. Sensitive data is not exposed via static routes.
+- API routes use `middleware.ensureLoggedIn` and custom `ensurePrivileged` (notes visibility).  
+**Verdict:** Compliant.
+
+---
+
+## 9. Database
+
+- Uses NodeBB `database` API (`getObject`, `setObject`, `sortedSetAdd`, etc.).
+- Keys documented in README; no custom migrations yet (no `upgrades` in plugin.json).  
+**Verdict:** Compliant; add `upgrades` when you introduce schema changes.
+
+---
+
+## 10. Style guide
+
+- Core follows Airbnb JS + ESLint; third-party plugins are encouraged but not required to follow.
+- This plugin has `"lint": "eslint ."` in package.json but no local eslint config in the repo; lint may rely on global or NodeBB env.  
+**Verdict:** Optional; adding an `eslint.config.mjs` (or similar) would align with best practice.
+
+---
+
+## Summary
+
+| Area | Result |
+|------|--------|
+| plugin.json | ✅ Compliant |
+| package.json / nbbpm | ✅ Compliant (.npmignore added) |
+| library.js | ✅ Compliant (verify API path) |
+| Client / ACP | ✅ Compliant (confirm ES5/ES6 build) |
+| Templates | ✅ Compliant |
+| i18n | ✅ Compliant |
+| Hooks | ✅ Compliant |
+| Security | ✅ Compliant |
+| Database | ✅ Compliant |
+| Style / lint | ✅ eslint.config.mjs added (optional; run `npm install -D eslint` for lint) |
+
+**Done:** `.npmignore` and a minimal `eslint.config.mjs` were added. For production, confirm in your NodeBB 3 instance that API requests from the client (e.g. `api.get('/plugins/internalnotes/' + tid)`) hit the routes your plugin registers; adjust server route prefix if your NodeBB mounts plugin routes differently.

package/README.md

@@ -0,0 +1,104 @@
+# nodebb-plugin-internalnotes
+
+A NodeBB plugin that adds **internal staff notes** and **topic assignment** to forum topics. By default only administrators can see and manage notes and assignments; you can optionally allow global moderators and/or category moderators in the plugin settings. They are completely invisible to everyone else.
+
+**Version:** 1.0.0 · **NodeBB:** 4.x (tested on 4.8.1)
+
+## Features
+
+- **Internal Notes** — Add, view, and delete private notes on any topic. Notes are stored per-topic and include the author and timestamp.
+- **Topic Assignment (User or Group)** — Assign a topic to a specific user or an entire group. All members of an assigned group receive a notification.
+- **"Assign to myself"** — The first option in the assignment modal lets the current user instantly assign the topic to themselves.
+- **Permission-based visibility** — Notes, assignment badges, and the thread tool buttons are completely invisible to regular users. By default only admins can see them; you can enable global moderators and/or category moderators in the plugin settings. No DOM elements are rendered for unprivileged users.
+- **Thread Tools integration** — "Internal Notes" and "Assign Topic" options appear in the topic thread tools dropdown for privileged users only.
+- **Admin settings page** — Configure who can access notes: allow global moderators and/or category moderators (ACP > Plugins > Internal Notes & Assignments).
+
+## Installation
+
+```bash
+cd /path/to/nodebb
+npm install nodebb-plugin-internalnotes
+```
+
+Then activate the plugin from the **Admin Control Panel > Extend > Plugins**.
+
+### For development
+
+```bash
+cd /path/to/nodebb
+npm link /path/to/nodebb-plugin-internalnotes
+./nodebb build
+./nodebb dev
+```
+
+## Configuration
+
+Navigate to **ACP > Plugins > Internal Notes & Assignments** to configure:
+
+- **Allow global moderators** — Enable to let global moderators view and manage internal notes and assignments (default: off; only admins have access).
+- **Allow category moderators** — Enable to let category moderators view and manage internal notes in their categories (default: off).
+
+## Usage
+
+1. Navigate to any topic as a user who has access (admin, or global/category moderator if enabled in settings).
+2. Open the **Thread Tools** dropdown (the wrench icon).
+3. Click **Internal Notes** to open the notes side panel, or **Assign Topic** to assign the topic.
+
+### Notes panel
+
+- View all existing notes for the topic
+- Add new notes (supports Ctrl+Enter to submit)
+- Delete notes
+- See current assignee (user or group) and unassign
+
+### Assignment modal
+
+- **Assign to myself** — one-click self-assignment (first option)
+- **User tab** — search and select any user by username
+- **Group tab** — search and select any group by name
+
+## Database Keys
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `internalnote:<noteId>` | Hash | Individual note (noteId, tid, uid, content, timestamp) |
+| `internalnotes:tid:<tid>` | Sorted Set | Note IDs for a topic (score = timestamp) |
+| `topic:<tid>` → `assignee` | Object Field | UID (for user) or group name (for group) |
+| `topic:<tid>` → `assigneeType` | Object Field | `"user"` or `"group"` |
+| `global` → `nextInternalNoteId` | Object Field | Auto-incrementing note ID counter |
+
+## API Endpoints
+
+All endpoints require authentication and privileged access.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/v3/plugins/internalnotes/:tid` | Get all notes for a topic |
+| `POST` | `/api/v3/plugins/internalnotes/:tid` | Create a note (`{ content }`) |
+| `DELETE` | `/api/v3/plugins/internalnotes/:tid/:noteId` | Delete a note |
+| `GET` | `/api/v3/plugins/internalnotes/:tid/assign` | Get topic assignee |
+| `PUT` | `/api/v3/plugins/internalnotes/:tid/assign` | Assign topic (`{ type: "user"\|"group", id: uid\|groupName }`) |
+| `DELETE` | `/api/v3/plugins/internalnotes/:tid/assign` | Unassign topic |
+| `GET` | `/api/v3/plugins/internalnotes/groups/search?query=...` | Search groups by name |
+
+## Compatibility
+
+NodeBB v3.x and v4.x (`nbbpm.compatibility`: `^3.0.0 || ^4.0.0`). Tested on NodeBB 4.8.1.
+
+## Development
+
+- The plugin follows [NodeBB plugin standards](https://docs.nodebb.org/development/plugins/); see [NODEBB_STANDARDS_AUDIT.md](NODEBB_STANDARDS_AUDIT.md) for a full audit.
+- Lint: `npm run lint` (ESLint).
+
+## Publishing to npm
+
+A GitHub Action (`.github/workflows/publish-npm.yml`) runs lint and publishes to [npm](https://www.npmjs.com/~brutalbirdie) when:
+
+- A **release** is published on GitHub, or
+- The workflow is run manually (**Actions → Lint and publish to npm → Run workflow**).
+
+**One-time setup:** In this repo, go to **Settings → Secrets and variables → Actions** and add a secret named `NPM_TOKEN` with an [npm access token](https://www.npmjs.com/settings/brutalbirdie/tokens) (Automation type is recommended). The workflow will only publish if `npm run lint` passes.
+
+## License
+
+MIT

package/eslint.config.mjs

@@ -0,0 +1,55 @@
+// Minimal ESLint config for NodeBB plugin (style guide: https://docs.nodebb.org/development/style-guide/)
+// Run: npm run lint
+export default [
+	{ ignores: ['eslint.config.mjs'] },
+	// Node/CommonJS (library, lib/*.js) — default
+	{
+		languageOptions: {
+			ecmaVersion: 2022,
+			sourceType: 'script',
+			globals: {
+				require: 'readonly',
+				module: 'readonly',
+				exports: 'writable',
+				__dirname: 'readonly',
+				__filename: 'readonly',
+				process: 'readonly',
+				Buffer: 'readonly',
+				setTimeout: 'readonly',
+				clearTimeout: 'readonly',
+				setInterval: 'readonly',
+				clearInterval: 'readonly',
+				Promise: 'readonly',
+				Array: 'readonly',
+				Object: 'readonly',
+				parseInt: 'readonly',
+				parseFloat: 'readonly',
+			},
+		},
+		rules: {
+			'no-unused-vars': ['warn', { argsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_' }],
+		},
+	},
+	// ES modules (config, public scripts) — override for these files
+	{
+		files: ['**/*.mjs', 'public/lib/**/*.js'],
+		languageOptions: {
+			ecmaVersion: 2022,
+			sourceType: 'module',
+			globals: {
+				$: 'readonly',
+				alerts: 'readonly',
+				app: 'readonly',
+				bootbox: 'readonly',
+				config: 'readonly',
+				socket: 'readonly',
+				t: 'readonly',
+				translator: 'readonly',
+				Promise: 'readonly',
+			},
+		},
+		rules: {
+			'no-unused-vars': ['warn', { argsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_' }],
+		},
+	},
+];

package/languages/en-GB/internalnotes.json

@@ -0,0 +1,33 @@
+{
+    "menu.assigned": "Assigned",
+    "panel-title": "Internal Notes",
+    "placeholder": "Write an internal note…",
+    "add-note": "Add Note",
+    "delete-note": "Delete",
+    "no-notes": "No internal notes yet.",
+    "error-loading": "Could not load notes.",
+    "note-added": "Note added successfully.",
+    "note-deleted": "Note deleted.",
+    "confirm-delete": "Are you sure you want to delete this note?",
+    "thread-tool-notes": "Internal Notes",
+    "thread-tool-assign": "Assign Topic",
+    "not-assigned": "Not assigned",
+    "assign-change": "Assign / Change",
+    "assigned-to": "Assigned to:",
+    "unassign": "Unassign",
+    "unassigned": "Topic unassigned.",
+    "assign-modal-title": "Assign Topic",
+    "assign-to-myself": "Assign to myself",
+    "assign-no-one": "Assign to no one",
+    "tab-user": "User",
+    "tab-group": "Group",
+    "search-user-placeholder": "Search for a user…",
+    "search-group-placeholder": "Search for a group…",
+    "selected": "Selected",
+    "assign-confirm": "Assign",
+    "assigned-success": "Topic assigned successfully.",
+    "select-target-first": "Please select a user or group first.",
+    "cancel": "Cancel",
+    "notif-assigned-user": "You have been assigned to the topic: %1",
+    "notif-assigned-group": "Your group %2 has been assigned to the topic: %1"
+}

package/lib/controllers.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const Controllers = module.exports;
+
+Controllers.renderAdminPage = function (req, res) {
+	res.render('admin/plugins/internalnotes', {
+		title: 'Internal Notes & Assignments',
+	});
+};