@7365admin1/layer-common 4.39.1 → 4.41.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @iservice365/layer-common
 
+## 4.41.0
+
+### Minor Changes
+
+- 7052a86: Notification bell: every notification now opens its page. Rows route on `params.kind` (else their `module`) to the matching page — work order, feedback, incident, visitors, cameras, patrol logs, documents, emergency contacts, events, facility bookings, online forms, bulletin board, inventory, service providers, marketplace orders, and the Seven365 staff robot/client pages — in this app when it has the page, otherwise in the app that does (by its `APP_*` URL), with the organisation and site in the link. Rows with nowhere to go are no longer drawn as links. New `chooseNavigation`, `notificationKind`, `WEB_TARGET_KINDS`.
+
+## 4.40.1
+
+### Patch Changes
+
+- 783ffe2: Edit Camera: the device password is write-only. On edit the Password field is optional, starts blank with the placeholder "Saved · leave blank to keep", and is sent only when a new one is typed, so an admin can switch a camera's Status without re-typing its login. A status-only change now enables Submit. Password stays required when adding a camera.
+
+## 4.40.0
+
+### Minor Changes
+
+- 3a96438: Client invitations: an accepted invitation whose site never reached the company's Sites list now says so in plain words and offers "Add <site> to your Sites" (`linkInvitationSite`, `PUT /service-provider-invitations/:id/link-site`). Needs core 3.100.0.
+
 ## 4.39.1
 
 ### Patch Changes
@@ -1453,11 +1471,11 @@
   `utils/console-tier.ts` + `composables/useConsoleTier.ts` mirror the server's
   own rule from two endpoints the console already calls, unprojected:
 
-                                                                                                                                                                                                GET /api/members/user/:user/app/admin    the Seven365 staff membership
-                                                                                                                                                                                                GET /api/roles/id/:role                  that membership's role document
+                                                                                                                                                                                                      GET /api/members/user/:user/app/admin    the Seven365 staff membership
+                                                                                                                                                                                                      GET /api/roles/id/:role                  that membership's role document
 
-                                                                                                                                                                                                owner  = member.type === "admin" && role.type === "admin" && role.default === true
-                                                                                                                                                                                                staff  = member.type === "admin" && role.type === "admin"
+                                                                                                                                                                                                      owner  = member.type === "admin" && role.type === "admin" && role.default === true
+                                                                                                                                                                                                      staff  = member.type === "admin" && role.type === "admin"
 
   `role.default` is the marker because it is the only property of a platform
   staff role no API caller can set - `role.controller.ts` validates create and

package/components/CameraForm.vue

@@ -161,14 +161,21 @@
           </v-col>
 
           <v-col v-if="isANPR" cols="12">
-            <InputLabel class="text-capitalize" title="Password" required />
+            <!-- Write-only: the saved password is never sent to the browser, so
+                 on edit a blank field keeps it. Required only for a new camera. -->
+            <InputLabel
+              class="text-capitalize"
+              title="Password"
+              :required="!isEdit"
+            />
             <v-text-field
               v-model.trim="camera.password"
               type="password"
+              autocomplete="new-password"
               class="filter-field"
               density="comfortable"
-              :rules="[requiredRule]"
-              placeholder="Enter password"
+              :rules="isEdit ? [] : [requiredRule]"
+              :placeholder="isEdit ? 'Saved · leave blank to keep' : 'Enter password'"
             />
           </v-col>
 
@@ -419,8 +426,12 @@ const camera = ref<TSiteCamera>({
 
 camera.value.site = prop.site;
 
-if (prop.mode === "edit") {
+const isEdit = prop.mode === "edit";
+
+if (isEdit) {
   camera.value = JSON.parse(JSON.stringify(prop.camera));
+  // Never pre-filled: blank means "keep the saved password".
+  camera.value.password = "";
 }
 camera.value.site = prop.site;
 camera.value.type = prop.type;
@@ -576,7 +587,9 @@ const hasChanges = computed(() => {
     return (
       camera.value.host !== prop.camera.host ||
       camera.value.username !== prop.camera.username ||
-      camera.value.password !== prop.camera.password ||
+      // A typed password is a change; blank keeps the saved one.
+      !!camera.value.password ||
+      camera.value.status !== prop.camera.status ||
       camera.value.category !== prop.camera.category ||
       camera.value.guardPost !== prop.camera.guardPost ||
       camera.value.direction !== prop.camera.direction ||
@@ -895,7 +908,8 @@ async function save(
       const res = await updateSiteCamera(camera.value._id ?? "", {
         ...addressPayload(),
         username: camera.value.username,
-        password: camera.value.password,
+        // Sent only when typed; left out, the server keeps the saved one.
+        ...(camera.value.password ? { password: camera.value.password } : {}),
         category: camera.value.category,
         guardPost: camera.value.guardPost,
         direction: camera.value.direction,

package/components/ClientInvitations.vue

@@ -78,7 +78,17 @@
           </div>
 
           <div v-else-if="item.status === 'complete'" class="px-4 pb-4">
-            <NuxtLink v-if="item.onThisOrg" :to="`/org/${org}/sites`">Open Sites</NuxtLink>
+            <v-btn
+              v-if="item.needsSiteLink"
+              variant="flat"
+              class="screen-btn-primary"
+              :loading="working[item._id] === 'link'"
+              :disabled="Boolean(working[item._id])"
+              @click="addToSites(item)"
+            >
+              Add {{ item.siteName }} to your Sites
+            </v-btn>
+            <NuxtLink v-else-if="item.onThisOrg" :to="`/org/${org}/sites`">Open Sites</NuxtLink>
             <NuxtLink
               v-else-if="item.providerOrgId && item.providerOrgId !== org"
               :to="`/org/${item.providerOrgId}/sites`"
@@ -124,8 +134,13 @@ const tabs: Array<{ value: Tab; label: string }> = [
 ];
 
 const route = useRoute();
-const { getReceivedInvitations, getInvitation, acceptInvitation, declineInvitation } =
-  useServiceProviderInvitation();
+const {
+  getReceivedInvitations,
+  getInvitation,
+  acceptInvitation,
+  declineInvitation,
+  linkInvitationSite,
+} = useServiceProviderInvitation();
 
 const tab = ref<Tab>("pending");
 const items = ref<TReceivedServiceProviderInvitation[]>([]);
@@ -180,6 +195,9 @@ function stateLine(item: TReceivedServiceProviderInvitation) {
       if (item.onThisOrg) {
         return `Accepted${on(item.answeredAt)} — ${item.siteName} is on your Sites list as a site you serve for ${item.orgName}.`;
       }
+      if (item.needsSiteLink) {
+        return "This invitation was accepted, but the site wasn't added to your Sites. Add it now.";
+      }
       if (!item.providerOrgId || item.providerOrgId === props.org) {
         return `Accepted${on(item.answeredAt)}, but ${item.siteName} is not on this company's Sites list. Please contact Seven365 support so we can add it.`;
       }
@@ -228,6 +246,20 @@ async function answer(item: TReceivedServiceProviderInvitation, action: "accept"
   }
 }
 
+/** Accepted but never added to the Sites list: add it now, then show it. */
+async function addToSites(item: TReceivedServiceProviderInvitation) {
+  errors[item._id] = "";
+  working[item._id] = "link";
+  try {
+    await linkInvitationSite(item._id, props.org);
+    await load();
+  } catch (err: any) {
+    errors[item._id] = err?.data?.message || "Could not add this site to your Sites.";
+  } finally {
+    working[item._id] = "";
+  }
+}
+
 // Opened from the bell: start on the tab the linked invitation is in.
 if (linked.value) {
   try {

package/components/NotificationBell.vue

@@ -70,7 +70,10 @@
               :key="item._id"
               type="button"
               class="notif-card"
-              :class="{ 'notif-card--unread': !item.hasRead }"
+              :class="{
+                'notif-card--unread': !item.hasRead,
+                'notif-card--plain': !targetFor(item),
+              }"
               @click="openNotification(item)"
             >
               <div class="notif-card__top">
@@ -134,7 +137,7 @@ import {
   timeAgo,
   type TInboxItem,
 } from "../utils/notification-inbox";
-import { externalTargetUrl, notificationTarget } from "../utils/notification-target";
+import { chooseNavigation, notificationTarget } from "../utils/notification-target";
 
 /**
  * The top-bar notification feed for the web, in every signed-in app.
@@ -304,26 +307,59 @@ function markRead(item: Record<string, any>) {
  * layer: the ten apps that have no order queue simply do not match it, and the
  * click there stays what it always was.
  */
-async function goToSubject(item: Record<string, any>) {
-  const target = notificationTarget(item as any, {
+function targetFor(item: Record<string, any>) {
+  return notificationTarget(item as any, {
     // The org app nests under `organization`; the service apps under `org`.
-    organization: String(route.params?.organization ?? route.params?.org ?? ""),
+    // Staff pages and the org app have neither, so the person's own default
+    // organisation builds a service-app link from there.
+    organization: String(
+      route.params?.organization ?? route.params?.org ?? currentUser.value?.defaultOrg ?? "",
+    ),
+    site: String(route.params?.site ?? ""),
   });
-  if (!target) return;
-
-  if (typeof router.hasRoute !== "function" || !router.hasRoute(target.name)) {
-    // The page lives in another web app (the invitation is answered in the
-    // organisation app): go there by URL, or stay put if it is not configured.
-    const href = externalTargetUrl(target, { org: String(appConfig?.public?.APP_ORG ?? "") });
-    if (!href) return;
-    open.value = false;
-    window.location.assign(href);
-    return;
+}
+
+/** A path this app really has a page for (every app has a 404 fallback, so check the match). */
+function hasLocalPage(path: string) {
+  try {
+    const resolved = router.resolve(path);
+    return resolved.matched.length > 0 && !resolved.matched.some((m) => m.path.includes("pathMatch"));
+  } catch {
+    return false;
   }
+}
+
+/** Every web app's URL, keyed like `TAppKey`, from the layer's runtime config. */
+function appUrls() {
+  const p = appConfig?.public ?? {};
+  return {
+    org: String(p.APP_ORG ?? ""),
+    security: String(p.APP_SECURITY ?? ""),
+    "property-management": String(p.APP_PROPERTY_MANAGEMENT ?? ""),
+    hygiene: String(p.APP_HYGIENE ?? ""),
+    "mechanical-electrical": String(p.APP_MECHANICAL_ELECTRICAL ?? ""),
+    "pest-control": String(p.APP_PEST_CONTROL ?? ""),
+    landscaping: String(p.APP_LANDSCAPING ?? ""),
+    "pool-maintenance": String(p.APP_POOL_MAINTENANCE ?? ""),
+  };
+}
+
+/** The decision is `chooseNavigation` (unit-tested); this only carries it out. */
+async function goToSubject(item: Record<string, any>) {
+  const nav = chooseNavigation(targetFor(item), {
+    hasRoute: (name) => typeof router.hasRoute === "function" && router.hasRoute(name),
+    hasPage: hasLocalPage,
+    appUrls: appUrls(),
+  });
+  if (!nav) return;
 
   open.value = false;
+  if (nav.type === "href") {
+    window.location.assign(nav.href);
+    return;
+  }
   try {
-    await router.push({ name: target.name, params: target.params, query: target.query });
+    await router.push(nav.to as any);
   } catch {
     // A cancelled or duplicate navigation is not worth an error in the top bar.
   }
@@ -462,6 +498,11 @@ onBeforeUnmount(() => {
   background: var(--hover);
 }
 
+/* Nothing to open: still marks read on click, but does not look like a link. */
+.notif-card--plain {
+  cursor: default;
+}
+
 .notif-card__top {
   display: flex;
   align-items: baseline;

package/composables/useServiceProviderInvitation.ts

@@ -48,6 +48,8 @@ export type TReceivedServiceProviderInvitation = {
   providerOrgName?: string;
   /** Accepted AND on the Sites list of the company on screen. */
   onThisOrg?: boolean;
+  /** Accepted, but the site is on no company's Sites list: offer to add it. */
+  needsSiteLink?: boolean;
 };
 
 /** The words on screen. Kept beside the server's own list on purpose — a
@@ -171,6 +173,17 @@ export default function useServiceProviderInvitation() {
     });
   }
 
+  /**
+   * An accepted invitation whose site never reached this company's Sites
+   * list: add it now. Safe to repeat - the server adds it once.
+   */
+  function linkInvitationSite(id: string, org: string) {
+    return useNuxtApp().$api<{ message: string }>(`${base}/${id}/link-site`, {
+      method: "PUT",
+      body: { org },
+    });
+  }
+
   /**
    * "Client invitations": one tab of the invitations sent to the signed-in
    * account, plus the count in every tab. `org` is the company on screen.
@@ -200,6 +213,7 @@ export default function useServiceProviderInvitation() {
     getInvitation,
     declineInvitation,
     acceptInvitation,
+    linkInvitationSite,
     getReceivedInvitations,
   };
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "4.39.1",
+  "version": "4.41.0",
   "author": "7365admin1",
   "main": "./nuxt.config.ts",
   "//files": "What a consumer extending this layer actually loads. Without this npm ships the whole working tree - the changesets, the CI workflows, the render harness in tools/ and any scratch directory that happened to exist at publish time. Nuxt resolves a layer by directory, so every runtime directory below has to stay listed; adding a new top-level runtime directory means adding it here too.",

package/utils/notification-target.ts

@@ -24,33 +24,68 @@
  * Eleven web apps render this bell and only `iservice365-web-app-org` has an
  * order queue. Rather than make eleven apps configure a map, the name is
  * written down once here and the bell asks its own router whether the route
- * exists before pushing — so in the ten apps without the page the click stays
- * exactly what it was: mark as read, go nowhere.
+ * exists before pushing.
+ *
+ * EVERY KIND SINCE 2026-09-24 (owner: "the notification never routes me")
+ * Each row names what it is about (`params.kind`, else its `module`), and the
+ * tables below say which web apps have that page. The bell opens this app's
+ * own page when it has one and otherwise jumps to the app that does, by its
+ * `APP_*` URL, with the organisation and site in the path.
  */
 
 /** Only the fields a destination is decided from. */
 export type TTargetRow = {
   module?: string;
   screen?: string;
-  params?: { id?: string; org?: string } | null;
+  title?: string;
+  appSlug?: string;
+  siteId?: string | null;
+  /**
+   * `kind` is the click-through target every sender sets since 2026-09-24
+   * (core `withNotificationKind`); `site` stands in for `siteId` on rows kept
+   * unscoped on purpose. Older rows have neither and are read from `module`.
+   */
+  params?: { id?: string; org?: string; kind?: string; site?: string } | null;
 };
 
 /** What the surrounding app knows that the stored row does not. */
 export type TTargetContext = {
   /** The organization in the current URL. Org routes are all nested under it. */
   organization?: string;
+  /** The site in the current URL, used when the row names none. */
+  site?: string;
 };
 
+/** The web apps a click can land in, keyed like their `APP_*` runtime URLs. */
+export type TAppKey =
+  | "org"
+  | "security"
+  | "property-management"
+  | "hygiene"
+  | "mechanical-electrical"
+  | "pest-control"
+  | "landscaping"
+  | "pool-maintenance";
+
+/** One place the record can be opened: a path inside one web app. */
+export type TCandidate = { app: TAppKey; path: string };
+
 export type TNotificationTarget = {
-  name: string;
-  params: Record<string, string>;
+  /** A route name in the current app, tried first (the two original targets). */
+  name?: string;
+  params?: Record<string, string>;
   query?: Record<string, string>;
   /**
    * Set when the page lives in another web app. The bell opens
    * `<that app's URL><path>` when its own router has no route by `name`.
    */
-  app?: "org";
+  app?: TAppKey;
   path?: string;
+  /**
+   * Every page that shows the record, best first. The bell opens the first one
+   * its own router has; otherwise it jumps to the first whose app URL is set.
+   */
+  candidates?: TCandidate[];
 };
 
 /** Nuxt's generated names for `pages/org/[organization]/marketplace/orders/`. */
@@ -73,13 +108,138 @@ export const VENDOR_ORDER_MODULE = "marketplace-vendor-order";
 export const SP_INVITATION_SCREEN = "/service-provider-invitation";
 export const INVITATIONS_ROUTE = "org-organization-client-invitations";
 
+/**
+ * What a row is about. `params.kind` when the sender set it; for older rows the
+ * `module`, except where the module is shared: `platform` (a new client, an
+ * accepted invitation, a robot) and `other` (both halves of a service-provider
+ * invitation) are told apart by the fixed titles their senders use.
+ */
+export function notificationKind(item: TTargetRow | null | undefined): string {
+  const kind = String(item?.params?.kind ?? "").trim();
+  if (kind) return kind;
+  const module = String(item?.module ?? "");
+  const title = String(item?.title ?? "");
+  if (String(item?.screen ?? "") === SP_INVITATION_SCREEN) return "serviceProviderInvite";
+  if (module === "platform") {
+    if (/^robot /i.test(title)) return "robot";
+    if (/^new client/i.test(title)) return "client";
+    if (/^invitation accepted/i.test(title)) return "clientInvitation";
+    return "";
+  }
+  if (module === "other") {
+    return /(accepted|declined) your invitation$/i.test(title) ? "serviceProviderInviteAnswer" : "";
+  }
+  return module;
+}
+
+/**
+ * The web app a mobile-tagged row's work lives in. A work order sent to the
+ * iClean365 app is managed in the Hygiene web app, and so on; anything from the
+ * resident or iMA365 apps is the property manager's.
+ */
+const APP_FOR_SLUG: Record<string, TAppKey> = {
+  "iservice365-hygiene-mobile-app": "hygiene",
+  "iservice365-m-and-e-mobile-app": "mechanical-electrical",
+  "iservice365-pest-control-mobile-app": "pest-control",
+  "iservice365-pool-maintenance-mobile-app": "pool-maintenance",
+  "iservice365-landscaping-mobile-app": "landscaping",
+  "iservice365-landscape-mobile-app": "landscaping",
+};
+
+const SERVICE_APPS: TAppKey[] = [
+  "property-management",
+  "security",
+  "hygiene",
+  "mechanical-electrical",
+  "pest-control",
+  "landscaping",
+  "pool-maintenance",
+];
+
+/**
+ * Site pages, `/<org>/<site>/<page>` in the service web apps, and which apps
+ * have them. "any" = every service app has the page; the row's own app leads.
+ */
+type TSitePage = { apps: TAppKey[] | "any"; page: (id: string) => string };
+const withId = (list: string) => (id: string) => (id ? `${list}/${id}` : list);
+const SITE_PAGES: Record<string, TSitePage[]> = {
+  workOrder: [{ apps: "any", page: withId("work-orders") }],
+  feedback: [{ apps: "any", page: withId("feedbacks") }],
+  bulletinBoard: [{ apps: "any", page: () => "bulletin-board" }],
+  inventory: [{ apps: "any", page: () => "inventory" }],
+  event: [{ apps: ["property-management"], page: () => "event-mgmt" }],
+  facilityBooking: [{ apps: ["property-management"], page: () => "facility-booking" }],
+  onlineForm: [{ apps: ["property-management"], page: () => "online-forms" }],
+  documentExpiry: [{ apps: ["property-management"], page: () => "document-mgmt" }],
+  emergencyContact: [{ apps: ["property-management"], page: () => "emergency-contacts" }],
+  incidentReport: [{ apps: ["security", "property-management"], page: withId("incident-reports") }],
+  visitors: [
+    { apps: ["security"], page: () => "visitor-management" },
+    { apps: ["property-management"], page: () => "visitor-mgmt" },
+  ],
+  virtualPatrol: [{ apps: ["security"], page: () => "virtual-patrol/logs" }],
+  cameraFault: [
+    { apps: ["security"], page: () => "virtual-patrol/cctv" },
+    { apps: ["property-management"], page: () => "cctv" },
+  ],
+  serviceProviderInviteAnswer: [
+    { apps: SERVICE_APPS.filter((a) => a !== "hygiene"), page: () => "service-providers" },
+  ],
+};
+SITE_PAGES.myVisitors = SITE_PAGES.visitors;
+
+/** Every kind the web can open, for tests and for anyone asking "is this clickable?". */
+export const WEB_TARGET_KINDS = [
+  ...Object.keys(SITE_PAGES),
+  "serviceProviderInvite",
+  VENDOR_ORDER_MODULE,
+  "robot",
+  "client",
+  "clientInvitation",
+];
+
+function sitePageTarget(
+  kind: string,
+  item: TTargetRow,
+  organization: string,
+  site: string,
+): TNotificationTarget | null {
+  const pages = SITE_PAGES[kind];
+  if (!pages || !organization || !site) return null;
+  const id = encodeURIComponent(String(item.params?.id ?? "").trim());
+  const home = APP_FOR_SLUG[String(item.appSlug ?? "")] ?? "property-management";
+  const base = `/${encodeURIComponent(organization)}/${encodeURIComponent(site)}/`;
+  const candidates: TCandidate[] = [];
+  for (const { apps, page } of pages) {
+    const list = apps === "any" ? [home, ...SERVICE_APPS.filter((a) => a !== home)] : apps;
+    for (const app of list) candidates.push({ app, path: base + page(id) });
+  }
+  return { candidates };
+}
+
+/** Seven365 staff pages, in the organisation app. */
+function staffTarget(kind: string, item: TTargetRow): TNotificationTarget | null {
+  const id = String(item.params?.id ?? "").trim();
+  if (kind === "robot") return { candidates: [{ app: "org", path: "/super-admin/robots" }] };
+  if (kind === "clientInvitation") {
+    return { candidates: [{ app: "org", path: "/super-admin/client-list" }] };
+  }
+  if (kind === "client") {
+    return id
+      ? { candidates: [{ app: "org", path: "/super-admin/client-details" }], query: { org: id } }
+      : { candidates: [{ app: "org", path: "/super-admin/client-list" }] };
+  }
+  return null;
+}
+
 export function notificationTarget(
   item: TTargetRow | null | undefined,
   context: TTargetContext = {},
 ): TNotificationTarget | null {
   const organization = String(context.organization ?? "").trim();
+  const kind = notificationKind(item);
 
-  if (String(item?.screen ?? "") === SP_INVITATION_SCREEN) {
+  if (kind === "serviceProviderInvite") {
     // The invited company's organisation when the row names it (the invitation
     // belongs there), otherwise the one on screen. The list on that page is
     // keyed on the signed-in account, so either shows the invitation.
@@ -96,7 +256,14 @@ export function notificationTarget(
     };
   }
 
-  if (String(item?.module ?? "") !== VENDOR_ORDER_MODULE) return null;
+  if (!item) return null;
+  const staff = staffTarget(kind, item);
+  if (staff) return staff;
+
+  if (kind !== VENDOR_ORDER_MODULE) {
+    const site = String(item.siteId ?? item.params?.site ?? context.site ?? "").trim();
+    return sitePageTarget(kind, item, organization, site);
+  }
 
   // Every order route is nested under the organization. Without one there is no
   // URL to build, and guessing an organization for somebody who belongs to
@@ -104,12 +271,23 @@ export function notificationTarget(
   if (!organization) return null;
 
   const id = String(item?.params?.id ?? "").trim();
+  const orders = `/org/${encodeURIComponent(organization)}/marketplace/orders`;
 
   // No id — an older row, or one whose params were dropped — still has an
   // honest destination: the queue the order is sitting in.
-  if (!id) return { name: ORDER_QUEUE_ROUTE, params: { organization } };
+  if (!id) {
+    return {
+      name: ORDER_QUEUE_ROUTE,
+      params: { organization },
+      candidates: [{ app: "org", path: orders }],
+    };
+  }
 
-  return { name: ORDER_DETAIL_ROUTE, params: { organization, id } };
+  return {
+    name: ORDER_DETAIL_ROUTE,
+    params: { organization, id },
+    candidates: [{ app: "org", path: `${orders}/${encodeURIComponent(id)}` }],
+  };
 }
 
 /**
@@ -118,11 +296,49 @@ export function notificationTarget(
  */
 export function externalTargetUrl(
   target: TNotificationTarget | null | undefined,
-  appUrls: { org?: string } = {},
+  appUrls: Partial<Record<TAppKey, string>> = {},
 ): string {
-  if (!target?.app || !target.path) return "";
-  const base = String(appUrls[target.app] ?? "").trim().replace(/\/+$/, "");
-  if (!base) return "";
-  const qs = new URLSearchParams(target.query ?? {}).toString();
-  return `${base}${target.path}${qs ? `?${qs}` : ""}`;
+  const options: TCandidate[] = [
+    ...(target?.app && target.path ? [{ app: target.app, path: target.path }] : []),
+    ...(target?.candidates ?? []),
+  ];
+  const qs = new URLSearchParams(target?.query ?? {}).toString();
+  for (const { app, path } of options) {
+    const base = String(appUrls[app] ?? "").trim().replace(/\/+$/, "");
+    if (base) return `${base}${path}${qs ? `?${qs}` : ""}`;
+  }
+  return "";
+}
+
+/** What the bell does with a click: move inside this app, open another app, or nothing. */
+export type TNavigation =
+  | {
+      type: "route";
+      to: { name?: string; params?: Record<string, string>; path?: string; query?: Record<string, string> };
+    }
+  | { type: "href"; href: string }
+  | null;
+
+/**
+ * This app's own page first — by route name, then by path (the site is in the
+ * path, so opening it switches the site) — else the first app that has the
+ * page and whose URL is configured. The page itself still checks the person may
+ * see it: a link grants nothing.
+ */
+export function chooseNavigation(
+  target: TNotificationTarget | null | undefined,
+  app: {
+    hasRoute: (name: string) => boolean;
+    hasPage: (path: string) => boolean;
+    appUrls?: Partial<Record<TAppKey, string>>;
+  },
+): TNavigation {
+  if (!target) return null;
+  if (target.name && app.hasRoute(target.name)) {
+    return { type: "route", to: { name: target.name, params: target.params, query: target.query } };
+  }
+  const local = target.candidates?.find((c) => app.hasPage(c.path));
+  if (local) return { type: "route", to: { path: local.path, query: target.query } };
+  const href = externalTargetUrl(target, app.appUrls);
+  return href ? { type: "href", href } : null;
 }