@moshaver/cmb-activity 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mobin Karam
+
+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/README.md

@@ -0,0 +1,14 @@
+# `@moshaver/cmb-activity`
+
+Generic presence normalization, heartbeat de-duplication, projection, and activity paging. Moshaver event vocabulary, student/task persistence, attention signals, and access policy remain product-owned.
+
+## Install and use
+
+```bash
+npm install @moshaver/cmb-activity
+```
+
+```js
+const { normalizePresenceState, shouldPersistPresence } = require("@moshaver/cmb-activity");
+const state = normalizePresenceState("online");
+```

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@moshaver/cmb-activity",
+  "version": "0.1.0",
+  "description": "Composable Modular Backend activity primitives.",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "require": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "cmb",
+    "modular-backend",
+    "backend",
+    "framework-agnostic",
+    "activity"
+  ],
+  "engines": {
+    "node": ">=22.13.0 <23"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mobin-Karam/moshaver.git",
+    "directory": "packages/cmb/activity"
+  },
+  "bugs": {
+    "url": "https://github.com/Mobin-Karam/moshaver/issues"
+  },
+  "homepage": "https://github.com/Mobin-Karam/moshaver/tree/main/packages/cmb",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "dependencies": {
+    "@moshaver/cmb-kernel": "^0.1.0"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,6 @@
+export const ACTIVITY_MODULE: Readonly<{ id: "activity"; version: string; kind: "platform"; dependencies: readonly string[] }>;
+export const DEFAULT_PRESENCE_STATES: readonly string[];
+export function normalizePresenceState(value: unknown, allowedStates?: readonly string[], fallback?: string): string;
+export function shouldPersistPresence(previous: { state: string; resourceId?: string | null; lastSeenAt: Date } | null | undefined, next: { state: string; resourceId?: string | null }, now?: Date, debounceMs?: number): boolean;
+export function projectPresence(row: { state: string; lastSeenAt: Date; resource?: { id: string; title: string } | null }, now?: Date, onlineWindowMs?: number): { online: boolean; state: string; lastSeenAt: Date; currentTask: { id: string; title: string } | null };
+export function clampActivityLimit(value: unknown, fallback?: number, maximum?: number): number;

package/src/index.js

@@ -0,0 +1,9 @@
+"use strict";
+const { defineModule } = require("@moshaver/cmb-kernel");
+const ACTIVITY_MODULE = defineModule({ id: "activity", version: "0.1.0", kind: "platform", dependencies: ["kernel"] });
+const DEFAULT_PRESENCE_STATES = Object.freeze(["idle", "studying", "quiz", "exam", "offline"]);
+function normalizePresenceState(value, allowedStates = DEFAULT_PRESENCE_STATES, fallback = "idle") { const state = String(value ?? ""); return allowedStates.includes(state) ? state : fallback; }
+function shouldPersistPresence(previous, next, now = new Date(), debounceMs = 30_000) { if (!previous) return true; return previous.state !== next.state || (previous.resourceId ?? null) !== (next.resourceId ?? null) || now.getTime() - previous.lastSeenAt.getTime() >= debounceMs; }
+function projectPresence(row, now = new Date(), onlineWindowMs = 90_000) { const online = now.getTime() - row.lastSeenAt.getTime() <= onlineWindowMs; return { online, state: online ? row.state : "offline", lastSeenAt: row.lastSeenAt, currentTask: row.resource ? { id: row.resource.id, title: row.resource.title } : null }; }
+function clampActivityLimit(value, fallback = 50, maximum = 100) { return Math.min(Math.max(Number(value) || fallback, 1), maximum); }
+module.exports = { ACTIVITY_MODULE, DEFAULT_PRESENCE_STATES, normalizePresenceState, shouldPersistPresence, projectPresence, clampActivityLimit };