@rei-standard/amsg-shared 0.4.0-next.7 → 0.4.0-next.8

package/README.md

@@ -78,7 +78,7 @@ omit all four.
 | `tag`                | `string?`                                | Notification grouping tag. |
 | `renotify`           | `boolean?`                               | Re-alert when a matching `tag` replaces an existing notification. |
 | `requireInteraction` | `boolean?`                               | Keep the notification visible until the user dismisses it. |
-| `silent`             | `boolean?`                               | Suppress notification sound and vibration. |
+| `silent`             | `(boolean \| 'when-visible')?`            | Suppress notification sound and vibration — see [选哪个 `silent`](#选哪个-silent). |
 | `data`               | `Record<string, unknown>?`               | Custom data passed to the notification. |
 
 Unknown fields are preserved for forward compatibility, but the known
@@ -101,6 +101,18 @@ fields above are validated by the builders when present.
 
 完整取舍见 [`@rei-standard/amsg-sw` README 的「不展示通知的代价」](https://github.com/Tosd0/ReiStandard/blob/main/packages/rei-standard-amsg/sw/README.md#不展示通知的代价)。
 
+### 选哪个 `silent`
+
+`silent` 管的是「响不响铃、震不震」，跟弹不弹（`show`）是两件独立的事——通知照样进通知中心，只是安静地进。
+
+| 值 | SW 那边 | 什么时候用 |
+|---|---|---|
+| 不配 / `false` | 正常响铃震动 | 默认 |
+| `true` | 一律不响 | 一串连着来的通知配 `tag` 折叠，只想在通知中心留个痕迹 |
+| `'when-visible'` | 有可见窗口就静音，没有就照常响 | 页面自己会把内容画出来的那类消息：用户正看着页面就别再响一声，人切后台了照样叫得动 |
+
+`'when-visible'` 只能由 Service Worker 当场算：发送端发推那一刻并不知道用户此刻在不在前台，写死 `silent: true` 的话，用户切到后台收到的那条也不会响。判定用的是跟 `show: 'when-hidden'` 同一套窗口可见性口径，一条 payload 只算一次。
+
 ### `notificationIntent(payload)`
 
 把上面这套规则算成一个值，`'always'` / `'when-hidden'` / `'never'`：`notification.show` 说了算，没说才按 `messageKind` 走默认。两端读同一份——SW 拿它决定要不要 `showNotification`，发送端拿它决定这条值不值得占用推送通道（`'never'` 的 payload 推过去不会有任何可见反馈，`@rei-standard/amsg-server` 只把它落进收件箱，等客户端上线 `GET /outbox?since=` 补拉）。

package/dist/index.cjs

@@ -964,11 +964,14 @@ function validateNotificationArg(kind, value) {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a string when present`);
     }
   }
-  for (const f of ["renotify", "requireInteraction", "silent"]) {
+  for (const f of ["renotify", "requireInteraction"]) {
     if (n[f] !== void 0 && typeof n[f] !== "boolean") {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a boolean when present`);
     }
   }
+  if (n.silent !== void 0 && typeof n.silent !== "boolean" && n.silent !== "when-visible") {
+    throw new Error(`[amsg-shared] ${kind}: 'notification.silent' must be true, false, or "when-visible"`);
+  }
   if (n.data !== void 0 && (n.data === null || typeof n.data !== "object" || Array.isArray(n.data))) {
     throw new Error(`[amsg-shared] ${kind}: 'notification.data' must be a plain object when present`);
   }

package/dist/index.d.cts

@@ -39,6 +39,10 @@
  *     un-kinded payloads) will display a system notification. `reasoning` / `tool_request` /
  *     `error` will dispatch silently.
  *   - `show: "always"`, `"when-hidden"`, or `false` overrides this default.
+ *   - `silent: "when-visible"` is resolved by the SW at render time from the
+ *     same window-visibility check `show: "when-hidden"` uses: silent while a
+ *     `visibilityState === "visible"` window client exists, audible otherwise.
+ *     `true` / `false` stay literal.
  *   - When rendering, `notification.*` is consulted first, with per-field
  *     fallback to the matching top-level payload fields (`title`,
  *     `body`/`message`, `icon`/`avatarUrl`, `badge`, `tag`/`messageId`,
@@ -55,6 +59,11 @@
  * 码不选。`show: false` 在两端也不是同一件事——有收件箱的发送端见到它根本不发
  * 这条 push，SW 压根收不到。
  *
+ * 想要「前台安静、切后台照常响」就配 `silent: "when-visible"`：`show` 照旧
+ * `"always"`（通知一定弹出来，那笔账不欠），响不响铃由 SW 收到时看有没有可见
+ * 窗口现算。发送端定不了这件事——它发推那一刻并不知道用户在不在前台，写死
+ * `silent: true` 的结果是切后台也不响。
+ *
  * 各档取舍见本包 README 的「选哪个 `show`」与 `@rei-standard/amsg-sw` README
  * 的「不展示通知的代价」。
  *
@@ -67,7 +76,7 @@
  * @property {string}  [tag]                - Notification grouping tag; matching tag replaces the prior notification (falls back to top-level `tag`, then `messageId`, then a generated unique tag).
  * @property {boolean} [renotify]           - When tag matches, still vibrate/sound (falls back to top-level `renotify`, default false at SW).
  * @property {boolean} [requireInteraction] - Notification stays until user dismisses (falls back to top-level `requireInteraction`, default false at SW).
- * @property {boolean} [silent]             - Suppress sound and vibration (falls back to top-level `silent`, default false at SW).
+ * @property {boolean | "when-visible"} [silent] - Suppress sound and vibration. `true` / `false` are literal; `"when-visible"` is decided by the SW at render time — silent while a window client is visible, audible otherwise (falls back to top-level `silent`, default false at SW).
  * @property {Record<string, unknown>} [data] - Custom payload data to attach to the notification (falls back to top-level `data`).
  */
 /**
@@ -674,6 +683,10 @@ export type AmsgPushCommon = {
  *     un-kinded payloads) will display a system notification. `reasoning` / `tool_request` /
  *     `error` will dispatch silently.
  *   - `show: "always"`, `"when-hidden"`, or `false` overrides this default.
+ *   - `silent: "when-visible"` is resolved by the SW at render time from the
+ *     same window-visibility check `show: "when-hidden"` uses: silent while a
+ *     `visibilityState === "visible"` window client exists, audible otherwise.
+ *     `true` / `false` stay literal.
  *   - When rendering, `notification.*` is consulted first, with per-field
  *     fallback to the matching top-level payload fields (`title`,
  *     `body`/`message`, `icon`/`avatarUrl`, `badge`, `tag`/`messageId`,
@@ -690,6 +703,11 @@ export type AmsgPushCommon = {
  * 码不选。`show: false` 在两端也不是同一件事——有收件箱的发送端见到它根本不发
  * 这条 push，SW 压根收不到。
  *
+ * 想要「前台安静、切后台照常响」就配 `silent: "when-visible"`：`show` 照旧
+ * `"always"`（通知一定弹出来，那笔账不欠），响不响铃由 SW 收到时看有没有可见
+ * 窗口现算。发送端定不了这件事——它发推那一刻并不知道用户在不在前台，写死
+ * `silent: true` 的结果是切后台也不响。
+ *
  * 各档取舍见本包 README 的「选哪个 `show`」与 `@rei-standard/amsg-sw` README
  * 的「不展示通知的代价」。
  */
@@ -727,9 +745,9 @@ export type NotificationDirective = {
      */
     requireInteraction?: boolean;
     /**
-     * - Suppress sound and vibration (falls back to top-level `silent`, default false at SW).
+     * - Suppress sound and vibration. `true` / `false` are literal; `"when-visible"` is decided by the SW at render time — silent while a window client is visible, audible otherwise (falls back to top-level `silent`, default false at SW).
      */
-    silent?: boolean;
+    silent?: boolean | "when-visible";
     /**
      * - Custom payload data to attach to the notification (falls back to top-level `data`).
      */

package/dist/index.d.ts

@@ -39,6 +39,10 @@
  *     un-kinded payloads) will display a system notification. `reasoning` / `tool_request` /
  *     `error` will dispatch silently.
  *   - `show: "always"`, `"when-hidden"`, or `false` overrides this default.
+ *   - `silent: "when-visible"` is resolved by the SW at render time from the
+ *     same window-visibility check `show: "when-hidden"` uses: silent while a
+ *     `visibilityState === "visible"` window client exists, audible otherwise.
+ *     `true` / `false` stay literal.
  *   - When rendering, `notification.*` is consulted first, with per-field
  *     fallback to the matching top-level payload fields (`title`,
  *     `body`/`message`, `icon`/`avatarUrl`, `badge`, `tag`/`messageId`,
@@ -55,6 +59,11 @@
  * 码不选。`show: false` 在两端也不是同一件事——有收件箱的发送端见到它根本不发
  * 这条 push，SW 压根收不到。
  *
+ * 想要「前台安静、切后台照常响」就配 `silent: "when-visible"`：`show` 照旧
+ * `"always"`（通知一定弹出来，那笔账不欠），响不响铃由 SW 收到时看有没有可见
+ * 窗口现算。发送端定不了这件事——它发推那一刻并不知道用户在不在前台，写死
+ * `silent: true` 的结果是切后台也不响。
+ *
  * 各档取舍见本包 README 的「选哪个 `show`」与 `@rei-standard/amsg-sw` README
  * 的「不展示通知的代价」。
  *
@@ -67,7 +76,7 @@
  * @property {string}  [tag]                - Notification grouping tag; matching tag replaces the prior notification (falls back to top-level `tag`, then `messageId`, then a generated unique tag).
  * @property {boolean} [renotify]           - When tag matches, still vibrate/sound (falls back to top-level `renotify`, default false at SW).
  * @property {boolean} [requireInteraction] - Notification stays until user dismisses (falls back to top-level `requireInteraction`, default false at SW).
- * @property {boolean} [silent]             - Suppress sound and vibration (falls back to top-level `silent`, default false at SW).
+ * @property {boolean | "when-visible"} [silent] - Suppress sound and vibration. `true` / `false` are literal; `"when-visible"` is decided by the SW at render time — silent while a window client is visible, audible otherwise (falls back to top-level `silent`, default false at SW).
  * @property {Record<string, unknown>} [data] - Custom payload data to attach to the notification (falls back to top-level `data`).
  */
 /**
@@ -674,6 +683,10 @@ export type AmsgPushCommon = {
  *     un-kinded payloads) will display a system notification. `reasoning` / `tool_request` /
  *     `error` will dispatch silently.
  *   - `show: "always"`, `"when-hidden"`, or `false` overrides this default.
+ *   - `silent: "when-visible"` is resolved by the SW at render time from the
+ *     same window-visibility check `show: "when-hidden"` uses: silent while a
+ *     `visibilityState === "visible"` window client exists, audible otherwise.
+ *     `true` / `false` stay literal.
  *   - When rendering, `notification.*` is consulted first, with per-field
  *     fallback to the matching top-level payload fields (`title`,
  *     `body`/`message`, `icon`/`avatarUrl`, `badge`, `tag`/`messageId`,
@@ -690,6 +703,11 @@ export type AmsgPushCommon = {
  * 码不选。`show: false` 在两端也不是同一件事——有收件箱的发送端见到它根本不发
  * 这条 push，SW 压根收不到。
  *
+ * 想要「前台安静、切后台照常响」就配 `silent: "when-visible"`：`show` 照旧
+ * `"always"`（通知一定弹出来，那笔账不欠），响不响铃由 SW 收到时看有没有可见
+ * 窗口现算。发送端定不了这件事——它发推那一刻并不知道用户在不在前台，写死
+ * `silent: true` 的结果是切后台也不响。
+ *
  * 各档取舍见本包 README 的「选哪个 `show`」与 `@rei-standard/amsg-sw` README
  * 的「不展示通知的代价」。
  */
@@ -727,9 +745,9 @@ export type NotificationDirective = {
      */
     requireInteraction?: boolean;
     /**
-     * - Suppress sound and vibration (falls back to top-level `silent`, default false at SW).
+     * - Suppress sound and vibration. `true` / `false` are literal; `"when-visible"` is decided by the SW at render time — silent while a window client is visible, audible otherwise (falls back to top-level `silent`, default false at SW).
      */
-    silent?: boolean;
+    silent?: boolean | "when-visible";
     /**
      * - Custom payload data to attach to the notification (falls back to top-level `data`).
      */

package/dist/index.mjs

@@ -879,11 +879,14 @@ function validateNotificationArg(kind, value) {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a string when present`);
     }
   }
-  for (const f of ["renotify", "requireInteraction", "silent"]) {
+  for (const f of ["renotify", "requireInteraction"]) {
     if (n[f] !== void 0 && typeof n[f] !== "boolean") {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a boolean when present`);
     }
   }
+  if (n.silent !== void 0 && typeof n.silent !== "boolean" && n.silent !== "when-visible") {
+    throw new Error(`[amsg-shared] ${kind}: 'notification.silent' must be true, false, or "when-visible"`);
+  }
   if (n.data !== void 0 && (n.data === null || typeof n.data !== "object" || Array.isArray(n.data))) {
     throw new Error(`[amsg-shared] ${kind}: 'notification.data' must be a plain object when present`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rei-standard/amsg-shared",
-  "version": "0.4.0-next.7",
+  "version": "0.4.0-next.8",
   "description": "ReiStandard Active Messaging shared types and push builders — the lowest layer (no deps on other amsg packages)",
   "repository": {
     "type": "git",