@hivedev/hivesdk 1.0.34 → 1.0.36

package/README.md

@@ -1 +1,987 @@
-Test
+# @hivedev/hivesdk
+
+Software development kit for microservices that integrate with the **Hive** system — a hub-and-spoke platform for educational institutions.
+
+Every service in the Hive ecosystem (NoteHive, and any future service) is built around this SDK. It handles authentication, configuration management, service registration, database connectivity, push notifications, and client-side session management — so each service only has to implement its own domain logic.
+
+---
+
+## Table of Contents
+
+- [Concepts](#concepts)
+- [Installation](#installation)
+- [Server SDK](#server-sdk)
+  - [1. Initialising the Server](#1-initialising-the-server)
+  - [2. Registering the Service](#2-registering-the-service)
+  - [3. Mounting the Middleware](#3-mounting-the-middleware)
+  - [4. Loading Configuration](#4-loading-configuration)
+  - [5. Connecting to the Database](#5-connecting-to-the-database)
+  - [6. Guarding Routes](#6-guarding-routes)
+  - [7. Sending Mail](#7-sending-mail)
+  - [8. Utility Functions](#8-utility-functions)
+  - [Full Server Bootstrap Example](#full-server-bootstrap-example)
+- [Client SDK](#client-sdk)
+  - [1. Loading the Client Bundle](#1-loading-the-client-bundle)
+  - [2. Initialising the Client](#2-initialising-the-client)
+  - [3. Login](#3-login)
+  - [4. Checking Login State](#4-checking-login-state)
+  - [Full Client Bootstrap Example](#full-client-bootstrap-example)
+- [Enumerations](#enumerations)
+- [Environment Variables Reference](#environment-variables-reference)
+- [How HivePortal Fits In](#how-hiveportal-fits-in)
+- [Known Limitations](#known-limitations)
+
+---
+
+## Concepts
+
+**HivePortal** is the central hub. It owns all user accounts, sessions, permissions, and the service registry. Every microservice is a spoke — it delegates all authentication and configuration to HivePortal via this SDK.
+
+**Service registration** is a two-step process:
+1. The service announces itself to HivePortal with its name and local/remote URLs.
+2. A HivePortal administrator approves it. Once approved, HivePortal sends back an encrypted configuration payload containing database credentials, Firebase credentials, permissions, and SMTP credentials.
+
+**Configuration** is stored encrypted on disk (AES-256-CBC, key derived via scrypt from `SERVER_PASSWORD`). It is decrypted at startup and cached in `process.env`. Credentials never sit on disk in plaintext.
+
+**Authentication** is always proxied. A service never validates a session token itself — it forwards the check to HivePortal and acts on the response.
+
+---
+
+## Installation
+
+```bash
+npm install @hivedev/hivesdk
+```
+
+The SDK ships three pre-built files:
+- `hive-server.js` — ESM bundle for Node.js backends
+- `hive-server.cjs` — CJS bundle for Node.js backends
+- `hive-client.js` — ESM bundle for browser frontends
+
+---
+
+## Server SDK
+
+### 1. Initialising the Server
+
+Call `initServer` once at the very start of your service, before anything else. It sets the service's identity and resolves the server password.
+
+```js
+// ESM
+import { initServer } from "@hivedev/hivesdk/server";
+
+await initServer({
+    serviceName: "NoteHive",       // Must match the name registered in HivePortal
+    servicePort: 49161,            // The port this service listens on
+    remoteUrl: "",                 // Public-facing URL if accessible from outside LAN, empty string if LAN-only
+    serverPassword: ""             // Optional — see password resolution below
+});
+```
+
+```js
+// CJS
+const { initServer } = require("@hivedev/hivesdk/server");
+
+await initServer({
+    serviceName: "NoteHive",
+    servicePort: 49161,
+    remoteUrl: "",
+    serverPassword: ""
+});
+```
+
+**Password resolution order:**
+
+1. The `serverPassword` argument, if provided.
+2. The `SERVER_PASSWORD` environment variable, if set.
+3. An interactive terminal prompt, if neither of the above is available — it will ask the user to create a password on first run, or enter their existing password on subsequent runs.
+
+The password is used as the encryption key for all `.dat` configuration files. Losing it means losing access to the stored configuration.
+
+> **Important:** `initServer` must only be called once. Calling it a second time is a no-op with a console warning. In a clustered setup, call it only from the primary process.
+
+---
+
+### 2. Registering the Service
+
+After `initServer`, call `registerService` to announce this service to HivePortal and receive configuration.
+
+```js
+// ESM
+import { registerService } from "@hivedev/hivesdk/server";
+
+await registerService();
+```
+
+```js
+// CJS
+const { registerService } = require("@hivedev/hivesdk/server");
+
+await registerService();
+```
+
+What this does internally:
+
+1. Sets the service's local URL (`http://<hostIp>:<servicePort>`) and remote URL in the internal registry.
+2. POSTs to HivePortal's `/RegisterService` endpoint.
+3. If HivePortal accepts the request, begins polling HivePortal's `/Configuration` endpoint every 2 seconds.
+4. Once an administrator approves the service in HivePortal, the configuration payload is received, decrypted, and saved to disk via `saveConfiguration`.
+
+**On first run**, the terminal will show:
+
+```
+Registering service...
+Service registration hasn't been approved yet. Please contact administrators!
+Service registration hasn't been approved yet. Please contact administrators!
+...
+Configuration received.
+Saving configuration...
+Service registered.
+```
+
+Once registered and approved, subsequent startups load configuration from disk directly via `loadConfiguration` and do not need to poll again, unless credentials change in HivePortal.
+
+> In a clustered setup, call `registerService` only from the primary process, after a short delay to allow workers to start up first.
+
+```js
+// ESM
+import cluster from "cluster";
+import os from "os";
+import { initServer, registerService } from "@hivedev/hivesdk/server";
+
+if (cluster.isPrimary)
+{
+    await initServer({ serviceName: "NoteHive", servicePort: 49161, remoteUrl: "" });
+
+    setTimeout(async () =>
+    {
+        await registerService();
+    }, 3000);
+
+    for (let i = 0; i < os.cpus().length; i++)
+    {
+        cluster.fork({ ...process.env });
+    }
+}
+else
+{
+    // Start your HTTP server in workers
+}
+```
+
+```js
+// CJS
+const cluster = require("cluster");
+const os = require("os");
+const { initServer, registerService } = require("@hivedev/hivesdk/server");
+
+if (cluster.isPrimary)
+{
+    await initServer({ serviceName: "NoteHive", servicePort: 49161, remoteUrl: "" });
+
+    setTimeout(async () =>
+    {
+        await registerService();
+    }, 3000);
+
+    for (let i = 0; i < os.cpus().length; i++)
+    {
+        cluster.fork({ ...process.env });
+    }
+}
+else
+{
+    // Start your HTTP server in workers
+}
+```
+
+---
+
+### 3. Mounting the Middleware
+
+`handleHiveRequests` is an Express-compatible middleware that intercepts all Hive-related routes. Mount it before your own route handlers.
+
+```js
+// ESM
+import express from "express";
+import cookieParser from "cookie-parser";
+import { handleHiveRequests } from "@hivedev/hivesdk/server";
+
+const app = express();
+
+app.use(express.json());
+app.use(cookieParser());
+app.use(handleHiveRequests);   // Must come before your own routes
+
+app.get("/my-route", (request, response) => { ... });
+```
+
+```js
+// CJS
+const express = require("express");
+const cookieParser = require("cookie-parser");
+const { handleHiveRequests } = require("@hivedev/hivesdk/server");
+
+const app = express();
+
+app.use(express.json());
+app.use(cookieParser());
+app.use(handleHiveRequests);
+
+app.get("/my-route", (request, response) => { ... });
+```
+
+**Routes handled automatically by this middleware:**
+
+| Method | Route | What it does |
+|--------|-------|--------------|
+| `POST` | `/Login` | Proxies login credentials to HivePortal, sets session cookie and/or `x-session-token` header |
+| `POST` | `/Logout` | Proxies logout to HivePortal, clears session |
+| `GET` | `/ServiceUrls` | Returns local or remote URL for a named service |
+| `POST` | `/IsLoggedIn` | Checks if the current session is valid with HivePortal |
+| `POST` | `/IsLoggedInWithPermission` | Checks session validity and a specific named permission |
+| `POST` | `/SaveUserFilter` | Saves a user-defined data filter (requires `FILTER_OPERATIONS` permission) |
+| `POST` | `/PushNotificationToken` | Registers a push notification token for the current device |
+| `GET` | `/hive-client.js` | Serves the built client-side SDK bundle (see [Client SDK](#client-sdk)) |
+
+You do not need to implement any of these routes yourself.
+
+---
+
+### 4. Loading Configuration
+
+On startup (after `initServer`), call `loadConfiguration` to decrypt and load credentials from disk into `process.env`.
+
+```js
+// ESM
+import { loadConfiguration } from "@hivedev/hivesdk/server";
+
+await loadConfiguration();
+```
+
+```js
+// CJS
+const { loadConfiguration } = require("@hivedev/hivesdk/server");
+
+await loadConfiguration();
+```
+
+This populates the following environment variables (only those with saved `.dat` files on disk are loaded):
+
+| Variable | Contents |
+|----------|----------|
+| `FIREBASE_ADMIN_CREDENTIALS` | JSON string of Firebase Admin SDK credentials |
+| `DATABASE_CREDENTIALS` | JSON string of database credentials, keyed by service name |
+| `PERMISSIONS` | JSON string of permission definitions |
+| `SMTP_CREDENTIALS` | JSON string of SMTP credentials |
+| `SMTP_PASSWORD` | Extracted SMTP password, ready for use in nodemailer |
+
+It also calls `DatabaseConnector.setCredentials` internally using the credentials stored under your service's name, so the database is ready to connect after this call.
+
+If a `.dat` file does not exist yet (e.g. first run before registration is approved), that credential is silently skipped.
+
+> Call `loadConfiguration` before `registerService`. On first run the files won't exist yet and it will skip gracefully. Once `registerService` completes and the administrator approves it, files are written to disk and will be fully loaded on the next startup.
+
+---
+
+### 5. Connecting to the Database
+
+After `loadConfiguration`, use `DatabaseConnector` to establish a MongoDB connection.
+
+```js
+// ESM — import directly from the SDK's built file
+import DatabaseConnector from "./node_modules/@hivedev/hivesdk/DatabaseConnector.js";
+
+const connected = await DatabaseConnector.connect();
+
+if (!connected)
+{
+    console.error("Failed to connect to database.");
+    process.exit(1);
+}
+
+// DatabaseConnector.databaseObject is now a live MongoDB db instance
+const collection = DatabaseConnector.databaseObject.collection("my_collection");
+```
+
+```js
+// CJS
+const DatabaseConnector = require("./node_modules/@hivedev/hivesdk/DatabaseConnector.js");
+
+const connected = await DatabaseConnector.connect();
+
+if (!connected)
+{
+    console.error("Failed to connect to database.");
+    process.exit(1);
+}
+
+const collection = DatabaseConnector.databaseObject.collection("my_collection");
+```
+
+If `loadConfiguration` was not called first, `DatabaseConnector.connect()` will attempt to call it automatically.
+
+**Disconnecting:**
+
+```js
+await DatabaseConnector.disconnect();
+```
+
+---
+
+### 6. Guarding Routes
+
+Use `isLoggedIn` and `isLoggedInWithPermission` to protect your own route handlers. Both accept the request and response objects and a `bSendResponse` boolean.
+
+When `bSendResponse` is `false`, the function returns a boolean and leaves the response untouched — use this to guard logic inside your own handlers.
+
+When `bSendResponse` is `true`, the function writes the result directly to the response — used internally by `handleHiveRequests` for the `/IsLoggedIn` and `/IsLoggedInWithPermission` endpoints.
+
+Both functions handle **session refresh transparently** — if HivePortal signals that the session token should be refreshed, a new cookie and/or `x-session-token` header is set automatically before your handler continues.
+
+**Guarding a route with a login check:**
+
+```js
+// ESM
+import { isLoggedIn } from "@hivedev/hivesdk/server";
+
+app.get("/my-protected-route", async (request, response) =>
+{
+    const loggedIn = await isLoggedIn(request, response, false);
+
+    if (!loggedIn)
+    {
+        response.statusCode = 401;
+        response.end("Unauthorized");
+        return;
+    }
+
+    response.end("Here is your protected data.");
+});
+```
+
+```js
+// CJS
+const { isLoggedIn } = require("@hivedev/hivesdk/server");
+
+app.get("/my-protected-route", async (request, response) =>
+{
+    const loggedIn = await isLoggedIn(request, response, false);
+
+    if (!loggedIn)
+    {
+        response.statusCode = 401;
+        response.end("Unauthorized");
+        return;
+    }
+
+    response.end("Here is your protected data.");
+});
+```
+
+**Guarding a route with a permission check:**
+
+The permission name must be set on `request.body.permissionName` before calling `isLoggedInWithPermission`.
+
+```js
+// ESM
+import { isLoggedInWithPermission } from "@hivedev/hivesdk/server";
+
+app.post("/admin-action", async (request, response) =>
+{
+    request.body.permissionName = "ADMIN_OPERATIONS";
+
+    const permitted = await isLoggedInWithPermission(request, response, false);
+
+    if (!permitted)
+    {
+        response.statusCode = 403;
+        response.end("Forbidden");
+        return;
+    }
+
+    response.end("Admin action performed.");
+});
+```
+
+```js
+// CJS
+const { isLoggedInWithPermission } = require("@hivedev/hivesdk/server");
+
+app.post("/admin-action", async (request, response) =>
+{
+    request.body.permissionName = "ADMIN_OPERATIONS";
+
+    const permitted = await isLoggedInWithPermission(request, response, false);
+
+    if (!permitted)
+    {
+        response.statusCode = 403;
+        response.end("Forbidden");
+        return;
+    }
+
+    response.end("Admin action performed.");
+});
+```
+
+---
+
+### 7. Sending Mail
+
+```js
+// ESM
+import { sendMail } from "@hivedev/hivesdk/server";
+
+await sendMail(
+    "sender@yourdomain.com",
+    "recipient@example.com",
+    "Subject line here",
+    "<p>HTML body here</p>"
+);
+```
+
+```js
+// CJS
+const { sendMail } = require("@hivedev/hivesdk/server");
+
+await sendMail(
+    "sender@yourdomain.com",
+    "recipient@example.com",
+    "Subject line here",
+    "<p>HTML body here</p>"
+);
+```
+
+Uses Gmail SMTP via nodemailer. The SMTP password is read from `process.env.SMTP_PASSWORD`, which is populated automatically by `loadConfiguration`. The sender Gmail address is currently hardcoded in `SendMail.js` — edit it there if needed.
+
+---
+
+### 8. Utility Functions
+
+All utilities are exported from `@hivedev/hivesdk/server`.
+
+**`getAppDataDirectory()`**
+
+Returns the platform-appropriate data directory for your service, creating it if it doesn't exist. On Windows this is `%APPDATA%\<ServiceName>`, on macOS `~/Library/Application Support/<ServiceName>`, on Linux `~/.config/<ServiceName>`.
+
+```js
+// ESM
+import { getAppDataDirectory } from "@hivedev/hivesdk/server";
+const dataDir = getAppDataDirectory();
+// e.g. "/home/user/.config/NoteHive"
+```
+
+```js
+// CJS
+const { getAppDataDirectory } = require("@hivedev/hivesdk/server");
+const dataDir = getAppDataDirectory();
+```
+
+**`getHostIp()`**
+
+Returns the first non-loopback IPv4 address of the host machine.
+
+```js
+// ESM
+import { getHostIp } from "@hivedev/hivesdk/server";
+const ip = getHostIp(); // e.g. "192.168.1.42"
+```
+
+```js
+// CJS
+const { getHostIp } = require("@hivedev/hivesdk/server");
+const ip = getHostIp();
+```
+
+**`findService(serviceName)`**
+
+Discovers another Hive service on the LAN via UDP to port 49153. Returns `{ name, urls: { local, remote } }` or `null` if not found within 3 seconds. Requires `HIVE_PORTAL_LAN_IP` environment variable to be set.
+
+```js
+// ESM
+import { findService } from "@hivedev/hivesdk/server";
+
+const service = await findService("NoteHive");
+
+if (service)
+{
+    console.log(service.urls.local); // "http://192.168.1.42:49161"
+}
+```
+
+```js
+// CJS
+const { findService } = require("@hivedev/hivesdk/server");
+
+const service = await findService("NoteHive");
+
+if (service)
+{
+    console.log(service.urls.local);
+}
+```
+
+**`extractConfigurationForService()`**
+
+Parses `process.env` and returns the configuration as structured objects, extracting the correct database credentials for the current service name.
+
+```js
+// ESM
+import { extractConfigurationForService } from "@hivedev/hivesdk/server";
+
+const { firebaseAdminCredentials, databaseCredentials, permissions, smtpCredentials } = extractConfigurationForService();
+```
+
+```js
+// CJS
+const { extractConfigurationForService } = require("@hivedev/hivesdk/server");
+
+const { firebaseAdminCredentials, databaseCredentials, permissions, smtpCredentials } = extractConfigurationForService();
+```
+
+**`encryptAndStoreFile(data, fullPath, password)`**
+
+Encrypts a string or Buffer with AES-256-CBC and writes it to disk. Creates the directory if it doesn't exist.
+
+```js
+// ESM
+import { encryptAndStoreFile } from "@hivedev/hivesdk/server";
+
+await encryptAndStoreFile("my secret data", "/path/to/file.dat", process.env.SERVER_PASSWORD);
+```
+
+```js
+// CJS
+const { encryptAndStoreFile } = require("@hivedev/hivesdk/server");
+
+await encryptAndStoreFile("my secret data", "/path/to/file.dat", process.env.SERVER_PASSWORD);
+```
+
+**`decryptFileWithPassword(fullPath, password)`**
+
+Reads and decrypts an encrypted `.dat` file. Returns the decrypted string, or `null` on failure.
+
+```js
+// ESM
+import { decryptFileWithPassword } from "@hivedev/hivesdk/server";
+
+const contents = await decryptFileWithPassword("/path/to/file.dat", process.env.SERVER_PASSWORD);
+```
+
+```js
+// CJS
+const { decryptFileWithPassword } = require("@hivedev/hivesdk/server");
+
+const contents = await decryptFileWithPassword("/path/to/file.dat", process.env.SERVER_PASSWORD);
+```
+
+**`saveConfiguration(configurationObject)` / `loadConfiguration()`**
+
+Normally called automatically by `registerService` and during startup respectively. Available for manual use if needed. `saveConfiguration` only writes keys that are present in the object — missing keys do not overwrite existing files.
+
+```js
+// ESM
+import { saveConfiguration, loadConfiguration } from "@hivedev/hivesdk/server";
+
+await saveConfiguration({
+    databaseCredentials: { NoteHive: { host: "127.0.0.1", username: "admin", password: "pass", name: "notehive" } },
+    smtpCredentials: { password: "smtp-password" }
+});
+
+await loadConfiguration();
+```
+
+```js
+// CJS
+const { saveConfiguration, loadConfiguration } = require("@hivedev/hivesdk/server");
+
+await saveConfiguration({
+    databaseCredentials: { NoteHive: { host: "127.0.0.1", username: "admin", password: "pass", name: "notehive" } },
+    smtpCredentials: { password: "smtp-password" }
+});
+
+await loadConfiguration();
+```
+
+---
+
+### Full Server Bootstrap Example
+
+This is the recommended startup sequence for any Hive microservice.
+
+```js
+// ESM
+import express from "express";
+import cookieParser from "cookie-parser";
+import cluster from "cluster";
+import os from "os";
+import { handleHiveRequests, initServer, registerService, loadConfiguration } from "@hivedev/hivesdk/server";
+import DatabaseConnector from "./node_modules/@hivedev/hivesdk/DatabaseConnector.js";
+
+const SERVICE_NAME = "NoteHive";
+const SERVICE_PORT = 49161;
+
+const app = express();
+
+app.use(express.json());
+app.use(cookieParser());
+app.use(handleHiveRequests);
+
+app.get("/", (request, response) => response.redirect("/Client/Pages/HomePage.html"));
+
+if (cluster.isPrimary)
+{
+    await initServer({
+        serviceName: SERVICE_NAME,
+        servicePort: SERVICE_PORT,
+        remoteUrl: process.env.REMOTE_URL || ""
+    });
+
+    await loadConfiguration();
+
+    setTimeout(async () =>
+    {
+        await registerService();
+    }, 3000);
+
+    for (let i = 0; i < os.cpus().length; i++)
+    {
+        cluster.fork({ ...process.env });
+    }
+
+    cluster.on("exit", (worker) =>
+    {
+        console.log(`Worker ${worker.process.pid} died. Restarting...`);
+        cluster.fork();
+    });
+}
+else
+{
+    await DatabaseConnector.connect();
+
+    app.listen(SERVICE_PORT, () =>
+    {
+        console.log(`Worker ${process.pid} listening on port ${SERVICE_PORT}`);
+    });
+}
+```
+
+```js
+// CJS
+const express = require("express");
+const cookieParser = require("cookie-parser");
+const cluster = require("cluster");
+const os = require("os");
+const { handleHiveRequests, initServer, registerService, loadConfiguration } = require("@hivedev/hivesdk/server");
+const DatabaseConnector = require("./node_modules/@hivedev/hivesdk/DatabaseConnector.js");
+
+const SERVICE_NAME = "NoteHive";
+const SERVICE_PORT = 49161;
+
+const app = express();
+
+app.use(express.json());
+app.use(cookieParser());
+app.use(handleHiveRequests);
+
+app.get("/", (request, response) => response.redirect("/Client/Pages/HomePage.html"));
+
+(async () =>
+{
+    if (cluster.isPrimary)
+    {
+        await initServer({
+            serviceName: SERVICE_NAME,
+            servicePort: SERVICE_PORT,
+            remoteUrl: process.env.REMOTE_URL || ""
+        });
+
+        await loadConfiguration();
+
+        setTimeout(async () =>
+        {
+            await registerService();
+        }, 3000);
+
+        for (let i = 0; i < os.cpus().length; i++)
+        {
+            cluster.fork({ ...process.env });
+        }
+
+        cluster.on("exit", (worker) =>
+        {
+            console.log(`Worker ${worker.process.pid} died. Restarting...`);
+            cluster.fork();
+        });
+    }
+    else
+    {
+        await DatabaseConnector.connect();
+
+        app.listen(SERVICE_PORT, () =>
+        {
+            console.log(`Worker ${process.pid} listening on port ${SERVICE_PORT}`);
+        });
+    }
+})();
+```
+
+---
+
+## Client SDK
+
+The client SDK is a browser-only ESM bundle (`hive-client.js`). There is no CJS variant — it runs exclusively in the browser.
+
+### 1. Loading the Client Bundle
+
+The `handleHiveRequests` middleware automatically serves the client bundle at `/hive-client.js` by reading it from `node_modules/@hivedev/hivesdk/hive-client.js`. **This works as long as your service's Node.js process is started from the root of the package** (i.e. the directory that contains `node_modules`), which is the recommended setup.
+
+If your service is started from a different working directory, the automatic route will fail to locate the file. In that case, serve it yourself:
+
+```js
+import path from "path";
+import { createReadStream } from "fs";
+
+app.get("/hive-client.js", (request, response) =>
+{
+    const filePath = path.join("/absolute/path/to/node_modules/@hivedev/hivesdk/hive-client.js");
+    response.setHeader("Content-Type", "application/javascript");
+    createReadStream(filePath).pipe(response);
+});
+```
+
+Include it in your HTML pages as a module script:
+
+```html
+<script type="module" src="/hive-client.js"></script>
+```
+
+Or import from it in another module script on the page:
+
+```html
+<script type="module">
+    import { login } from "/hive-client.js";
+</script>
+```
+
+---
+
+### 2. Initialising the Client
+
+Call `initClient` once on page load. It sets up in-app WebView detection, signals cookie support to the server, and starts the periodic login state checker.
+
+```js
+import { initClient } from "/hive-client.js";
+
+await initClient({});
+```
+
+`initClient` accepts one optional parameter:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `loginTokenStorageMethod` | `sessionStorageMethod` enum | `HTTP_ONLY_COOKIE` | How session tokens are stored on the client |
+
+---
+
+### 3. Login
+
+Call `login()` to open the HivePortal login page. The SDK handles the entire flow — the popup opens, the user enters their credentials, and on success the page reloads at `/`.
+
+```js
+import { login } from "/hive-client.js";
+
+login();
+```
+
+You can wire it to any element:
+
+```js
+import { login } from "/hive-client.js";
+
+document.getElementById("login-button").addEventListener("click", login);
+```
+
+When running inside the native mobile app (detected automatically), the login popup is rendered as a full-screen iframe overlay instead of a real popup window, since WebViews block `window.open`.
+
+---
+
+### 4. Checking Login State
+
+`initClient` automatically starts a periodic login check (every 30 seconds, clamped between 10 and 60 seconds). Each check fires a `login-state-changed` custom event on `window`.
+
+```js
+window.addEventListener("login-state-changed", (event) =>
+{
+    const isLoggedIn = event.detail;
+
+    document.getElementById("login-prompt").style.display = isLoggedIn ? "none" : "block";
+    document.getElementById("dashboard").style.display = isLoggedIn ? "block" : "none";
+});
+```
+
+The current login state is also available synchronously at any time:
+
+```js
+if (window.IS_LOGGED_IN)
+{
+    // Safe to load user-specific content
+}
+```
+
+---
+
+### Full Client Bootstrap Example
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>NoteHive</title>
+</head>
+<body>
+
+<div id="login-prompt">
+    <button id="login-button">Sign In</button>
+</div>
+
+<div id="dashboard" style="display: none;">
+    <h1>Welcome to NoteHive</h1>
+</div>
+
+<script type="module">
+    import { initClient, login } from "/hive-client.js";
+
+    await initClient({});
+
+    window.addEventListener("login-state-changed", (event) =>
+    {
+        const isLoggedIn = event.detail;
+        document.getElementById("login-prompt").style.display = isLoggedIn ? "none" : "block";
+        document.getElementById("dashboard").style.display = isLoggedIn ? "block" : "none";
+    });
+
+    document.getElementById("login-button").addEventListener("click", login);
+</script>
+
+</body>
+</html>
+```
+
+---
+
+## Enumerations
+
+The SDK exports several enumerations used throughout the Hive ecosystem.
+
+**`userPrivileges`** — Numeric privilege levels assigned to users.
+
+| Key | Value |
+|-----|-------|
+| `STUDENT` | 0 |
+| `CLASS_REPRESENTATIVE` | 10 |
+| `STUDENT_COORDINATOR` | 20 |
+| `ASSISTANT` | 30 |
+| `TEACHER` | 40 |
+| `COURSE_COORDINATOR` | 50 |
+| `HEAD_OF_DEPARTMENT` | 70 |
+| `MANAGEMENT` | 80 |
+| `SUPER_USER` | 100 |
+
+**`sessionStorageMethod`** — How session tokens are stored on the client.
+
+| Key | Value |
+|-----|-------|
+| `HTTP_ONLY_COOKIE` | 0 |
+| `LOCAL_STORAGE` | 1 |
+| `SESSION_STORAGE` | 2 |
+
+**`clientConnectionTypeFlags`** — Bitmask flags describing how a client is connected.
+
+| Key | Value |
+|-----|-------|
+| `LAN` | 1 |
+| `REMOTE` | 2 |
+| `SAME_SYSTEM` | 4 |
+| `UNKNOWN` | 8 |
+
+**`appWebViewInteractions`** — Message types exchanged between the web page and the native app WebView layer.
+
+| Key | Value |
+|-----|-------|
+| `REQUEST_NOTIFICATION_TOKEN` | 0 |
+| `BACK_PRESSED` | 1 |
+
+**`approvalTypes`** — Types of approval requests sent to HivePortal administrators.
+
+| Key | Value |
+|-----|-------|
+| `USER_REGISTERATION` | 0 |
+| `SERVICE_REGISTERATION` | 1 |
+
+**`filterTypes`**, **`filterOperators`**, **`userDataFetchFilterComparision`**, **`userFieldTypes`**, **`userFieldFormats`**, **`fileTreeNodeTypes`** — Domain-specific enumerations used for data querying, user field definitions, and file tree structures. Refer to their respective source files for values.
+
+---
+
+## Environment Variables Reference
+
+| Variable | Set by | Description |
+|----------|--------|-------------|
+| `SERVER_PASSWORD` | External / `setupPassword()` | Master password for encrypting/decrypting config files |
+| `SERVICE_NAME` | `initServer` | Name of this service as registered with HivePortal |
+| `SERVICE_PORT` | `initServer` | Port this service listens on |
+| `REMOTE_URL` | `initServer` | Public-facing URL of this service (empty if LAN-only) |
+| `HIVE_PORTAL_LAN_IP` | External | LAN IP of HivePortal, used by `findService` for UDP discovery |
+| `FIREBASE_ADMIN_CREDENTIALS` | `loadConfiguration` | JSON string of Firebase Admin credentials |
+| `DATABASE_CREDENTIALS` | `loadConfiguration` | JSON string of DB credentials keyed by service name |
+| `PERMISSIONS` | `loadConfiguration` | JSON string of permission definitions |
+| `SMTP_CREDENTIALS` | `loadConfiguration` | JSON string of SMTP credentials |
+| `SMTP_PASSWORD` | `loadConfiguration` | Extracted SMTP password, ready for nodemailer |
+
+---
+
+## How HivePortal Fits In
+
+```
+                          ┌─────────────────────┐
+                          │      HivePortal      │
+                          │  (hub — port 49152)  │
+                          │                      │
+                          │  - User accounts     │
+                          │  - Sessions          │
+                          │  - Permissions       │
+                          │  - Service registry  │
+                          │  - Configuration     │
+                          └────────┬─────────────┘
+                                   │
+              ┌────────────────────┼────────────────────┐
+              │                    │                     │
+   ┌──────────▼──────────┐         │         ┌──────────▼──────────┐
+   │       NoteHive       │        ...        │    FutureService    │
+   │   (port 49161)       │                   │    (port 49162)     │
+   │                      │                   │                     │
+   │  uses @hivedev/      │                   │  uses @hivedev/     │
+   │  hivesdk             │                   │  hivesdk            │
+   └──────────────────────┘                   └─────────────────────┘
+
+   Each service:
+     1. initServer()          — establish identity and password
+     2. loadConfiguration()   — decrypt credentials from disk
+     3. registerService()     — announce to HivePortal, receive config
+     4. handleHiveRequests    — mount middleware
+     5. Own domain logic      — notes, files, etc.
+```
+
+Every authentication check a service performs is a proxied call to HivePortal. HivePortal is the single source of truth for all session and permission data. Services only store and serve their own domain data.
+
+---
+
+## Known Limitations
+
+- **`ScheduleServiceUrlUpdate`** — This function is currently a stub and does nothing. It is intended for future use to periodically re-broadcast service URLs to HivePortal if the host IP changes.
+- **`loginTokenStorageMethod`** — The `LOCAL_STORAGE` and `SESSION_STORAGE` options in the `sessionStorageMethod` enum are defined but not yet implemented. Only `HTTP_ONLY_COOKIE` (with the `x-session-token` header fallback for native app clients) is fully functional.
+- **SMTP sender address** — The sender Gmail address in `SendMail.js` is hardcoded. Edit it in the SDK source if your service needs a different address.
+- **MongoDB only** — `DatabaseConnector` is built for MongoDB. There is no support for other databases.
+- **MongoDB port hardcoded** — The MongoDB port is hardcoded to `27017`. The host is configurable via credentials but the port is not.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hivedev/hivesdk",
   "type": "module",
-  "version": "1.0.34",
+  "version": "1.0.36",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "scripts": {