create-astram-app 0.13.1 → 0.14.1

package/template/frontend/src/shell/notificationsView.test.mjs

@@ -6,7 +6,11 @@
 import { test, describe } from 'node:test';
 import assert from 'node:assert/strict';
 import {
+  DROPDOWN_LIMIT,
   POLL_MS,
+  moreText,
+  severityInfo,
+  viewAllHref,
   announcementsBadgeCount,
   badgeLabel,
   badgeText,
@@ -180,3 +184,37 @@ describe('shouldPoll', () => {
     assert.equal(POLL_MS, 60_000);
   });
 });
+
+describe('dropdown footer (G-035)', () => {
+  test('loads 20 unread', () => {
+    assert.equal(DROPDOWN_LIMIT, 20);
+  });
+  test('25 unread, 20 shown ⇒ "5 more" (spec §12)', () => {
+    assert.equal(moreText(25, 20), '5 more');
+  });
+  test('all shown, or not counts ⇒ no "N more"', () => {
+    assert.equal(moreText(20, 20), '');
+    assert.equal(moreText(3, 3), '');
+    assert.equal(moreText(0, 0), '');
+    assert.equal(moreText(undefined, 0), '');
+    assert.equal(moreText(5, NaN), '');
+  });
+  test('View all links to the category tab', () => {
+    assert.equal(viewAllHref('personal'), '/notifications?tab=personal');
+    assert.equal(viewAllHref('announcement'), '/notifications?tab=announcement');
+    assert.equal(viewAllHref('anything'), '/notifications?tab=personal');
+  });
+});
+
+describe('severityInfo', () => {
+  test('theme-token dot and an sr label per severity', () => {
+    assert.deepEqual({ ...severityInfo('info') }, { label: 'Info', dotClass: 'bg-primary' });
+    assert.deepEqual({ ...severityInfo('success') }, { label: 'Success', dotClass: 'bg-ok' });
+    assert.deepEqual({ ...severityInfo('warning') }, { label: 'Warning', dotClass: 'bg-warn' });
+  });
+  test('unknown or missing ⇒ info (the default)', () => {
+    for (const s of [undefined, null, '', 'error', 'toString']) {
+      assert.equal(severityInfo(s).label, 'Info');
+    }
+  });
+});

package/template/server/_env.example

@@ -190,7 +190,9 @@ NODE_ENV=development
 
 # --- OPTIONAL: in-app notification retention ---
 # Read notices are deleted after the first value (days, 1-3650), every notice after the second
-# (at least the first, at most 3650), counted from when the notice was posted.
+# (at least the first, at most 3650), counted from when the notice was posted. Archived notices
+# follow the same rule (archiving never keeps a notice longer). Unset ⇒ 90 and 365; an invalid
+# value stops the server at start-up naming the setting. A clean-up runs every hour.
 # NOTIFICATION_READ_RETENTION_DAYS=90
 # NOTIFICATION_MAX_RETENTION_DAYS=365
 

package/template/server/package.json

@@ -21,13 +21,13 @@
     "postinstall": "node scripts/sync-astram-guide.mjs"
   },
   "dependencies": {
-    "@astram/core": "1.14.0",
-    "@astram/engine": "0.16.2",
-    "@astram/guard": "0.26.0",
+    "@astram/core": "1.15.0",
+    "@astram/engine": "0.17.0",
+    "@astram/guard": "0.28.0",
     "@astram/guide": "^0.2.8",
-    "@astram/identity": "0.24.0",
-    "@astram/messaging": "0.1.12",
-    "@astram/migrate": "0.7.4",
+    "@astram/identity": "0.26.0",
+    "@astram/messaging": "0.1.14",
+    "@astram/migrate": "0.7.5",
     "@astram/sdk": "^0.2.0",
     "@nestjs/common": "^11.2.7",
     "@nestjs/core": "^11.2.7",

package/template/server/src/app.module.ts

@@ -109,6 +109,19 @@ import { DemoController } from './health/demo.controller';
  *        ],
  *   The frontend ships the matching pages/widget (RecordPoliciesPage, ShareDialog)
  *   already wired to `useAuth().recordPolicy` / `.recordShare`.
+ *
+ * OPTIONAL — YOUR OWN NOTIFICATIONS (with `auth: true`): register each kind you post, then post
+ *   with `src/notifications/app-notifications.service.ts` (an example to copy). `personal` kinds
+ *   show in the bell, `announcement` kinds under the Announcements icon; users see `label` as the
+ *   type (≤ 40 characters; unset ⇒ made from the kind) and `severity` (info | success | warning)
+ *   as a coloured dot. Kinds are dotted lower-case names; `shield.` is reserved:
+ *        ShieldModule.forRoot({ auth: true, logoutRequiresProof: true,
+ *          notificationKinds: [
+ *            { kind: 'app.task_assigned', category: 'personal', label: 'Task assigned', severity: 'warning' },
+ *            { kind: 'app.release_news', category: 'announcement', label: 'Release news' },
+ *          ] }),
+ *   How long notices are kept: NOTIFICATION_READ_RETENTION_DAYS / NOTIFICATION_MAX_RETENTION_DAYS
+ *   in `.env` (see `_env.example`).
  */
 @Module({
   // Enforcement-only by default (boots with no config). For real login + the identity

package/template/server/src/main.ts

@@ -22,7 +22,13 @@ export async function bootstrap(): Promise<void> {
   await resolveBootSecrets();
   const { AppModule } = await import('./app.module');
   const config = loadAppConfig();
-  const app = await NestFactory.create<NestExpressApplication>(AppModule, { bufferLogs: false });
+  // `rawBody: true` keeps the request bytes in `req.rawBody` beside the parsed JSON. `@astram/agent`
+  // parses its own bodies from those bytes (strict JSON, duplicate keys refused); without it every
+  // agent POST answers 503 agent_unavailable. Other routes are unaffected.
+  const app = await NestFactory.create<NestExpressApplication>(AppModule, {
+    bufferLogs: false,
+    rawBody: true,
+  });
   // On SIGTERM/SIGINT (PM2 restart, deploy) run the framework's shutdown hooks: background jobs
   // stop, the HTTP server finishes its in-flight requests, then every DB pool and Redis client
   // closes. Without this line Node exits with no hook run. Give your process manager a stop

package/template/server/src/notifications/app-notifications.service.spec.ts

@@ -0,0 +1,26 @@
+import type { NotificationService } from '@astram/guard';
+import { AppNotificationsService } from './app-notifications.service';
+
+describe('AppNotificationsService (example)', () => {
+  it('posts the kind, title, body and link to the given users in the given company', async () => {
+    const post = vi.fn().mockResolvedValue({ created: 2, skipped: 0 });
+    const svc = new AppNotificationsService({ post } as unknown as NotificationService);
+
+    const result = await svc.notifyUsers('company-1', ['user-1', 'user-2'], {
+      kind: 'app.task_assigned',
+      title: 'Order 123 needs your approval',
+      link: '/orders/123',
+    });
+
+    expect(result).toEqual({ created: 2, skipped: 0 });
+    expect(post).toHaveBeenCalledWith({
+      tenantId: 'company-1',
+      recipients: ['user-1', 'user-2'],
+      kind: 'app.task_assigned',
+      title: 'Order 123 needs your approval',
+      body: null,
+      link: '/orders/123',
+      dedupeKey: null,
+    });
+  });
+});

package/template/server/src/notifications/app-notifications.service.ts

@@ -0,0 +1,41 @@
+import { Inject, Injectable } from '@nestjs/common';
+import { SHIELD_NOTIFICATIONS, type NotificationService } from '@astram/guard';
+
+/**
+ * EXAMPLE — send your own notices to the bell and Announcements menus (copy and extend).
+ *
+ * Not registered by default: add `AppNotificationsService` to a module's `providers` once
+ * `ShieldModule.forRoot({ auth: true, notificationKinds: [...] })` is on (`SHIELD_NOTIFICATIONS`
+ * exists only with `auth: true`). Register every kind you post in `notificationKinds`
+ * (see `app.module.ts`): `category: 'personal'` shows in the bell, `'announcement'` under the
+ * Announcements icon; `label` is what users see as the type, `severity` colours the dot.
+ *
+ * Rules:
+ * - `tenantId` comes from the session (`principal.tenantId`) or the record you just saved, never
+ *   from a request body or query.
+ * - `link` is an app path (`/orders/123`): clicking the notice opens it. The target page still
+ *   checks access itself — a notice never grants anything.
+ * - Notices are plain text: no passwords, tokens or other users' data in the title or body.
+ * - Only active users with an active membership in `tenantId` receive it; the rest are skipped.
+ */
+@Injectable()
+export class AppNotificationsService {
+  constructor(@Inject(SHIELD_NOTIFICATIONS) private readonly notifications: NotificationService) {}
+
+  /** Post one notice to each user ⇒ `{ created, skipped }` (1–1000 users per call). */
+  async notifyUsers(
+    tenantId: string,
+    userIds: readonly string[],
+    notice: { kind: string; title: string; body?: string; link?: string; dedupeKey?: string },
+  ): Promise<{ created: number; skipped: number }> {
+    return this.notifications.post({
+      tenantId,
+      recipients: userIds,
+      kind: notice.kind,
+      title: notice.title,
+      body: notice.body ?? null,
+      link: notice.link ?? null,
+      dedupeKey: notice.dedupeKey ?? null,
+    });
+  }
+}