@rei-standard/amsg-shared 0.1.0 → 0.2.0

package/README.md

@@ -48,6 +48,30 @@ origin** (`'instant'` for `amsg-instant`, `'scheduled'` for any
 
 ---
 
+## Notification directive
+
+`ContentPush` and `ToolRequestPush` can carry an optional
+`notification` object. It is a producer-side hint consumed by
+`@rei-standard/amsg-sw` before rendering a system notification.
+
+| Field                | Type                                      | Notes |
+|----------------------|-------------------------------------------|-------|
+| `show`               | `'auto' \| 'always' \| 'when-hidden' \| false` | Display policy. `auto` follows SW defaults. |
+| `title`              | `string?`                                | Notification title override. |
+| `body`               | `string?`                                | Notification body override. |
+| `icon`               | `string?`                                | Notification icon URL. |
+| `badge`              | `string?`                                | Notification badge URL. |
+| `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. |
+| `data`               | `Record<string, unknown>?`               | Custom data passed to the notification. |
+
+Unknown fields are preserved for forward compatibility, but the known
+fields above are validated by the builders when present.
+
+---
+
 ## Per-kind fields
 
 ### `ContentPush` — final user-facing content

package/dist/index.cjs

@@ -159,7 +159,7 @@ function validateNotificationArg(kind, value) {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a string when present`);
     }
   }
-  for (const f of ["renotify", "requireInteraction"]) {
+  for (const f of ["renotify", "requireInteraction", "silent"]) {
     if (n[f] !== void 0 && typeof n[f] !== "boolean") {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a boolean when present`);
     }

package/dist/index.d.cts

@@ -200,10 +200,10 @@ export function isErrorPush(value: unknown): value is ErrorPush;
 /**
  * Slice a string into UTF-8 byte chunks no larger than `maxBytes`,
  * always cutting at codepoint boundaries (never inside a multi-byte
- * char). Designed for the {@link ReasoningPush} byte-chunking path
- * in amsg-instant — producers facing the ~3 KB Web Push payload
- * limit slice oversized reasoning into N pushes with
- * `chunkIndex` / `totalChunks`, the SW reassembles by concat.
+ * char). This is a generic byte-safe string helper retained for
+ * callers that need deterministic UTF-8 chunking around small Web Push
+ * payload budgets; current amsg-instant oversized payload delivery uses
+ * BlobStore / generic multipart instead of reasoning-only wire fields.
  *
  * Algorithm: TextEncoder → Uint8Array → backward scan from each
  * candidate cut index until the byte is a UTF-8 lead byte (any byte
@@ -361,18 +361,21 @@ export type AmsgPushCommon = {
 };
 /**
  * SW-rendering directive. Mirrors the fields that `amsg-sw`'s
- * `createNotificationFromPayload` consumes (`notification.{title,body,icon,badge,tag,renotify,requireInteraction,data}`)
- * — typing all fields so callers don't lose IDE checking and slip back into the untyped-spread footgun.
+ * `createNotificationFromPayload` consumes (`notification.{show,title,body,icon,badge,tag,renotify,requireInteraction,silent,data}`)
+ * so producers get builder validation for the fields the SW actually reads.
  *
- * Routing in SW (kept here so producers don't have to cross-check):
+ * Routing in SW:
  *   - By default (`show: "auto"` or omitted), `messageKind: 'content'` (and legacy un-kinded payloads)
  *     will display a system notification. `reasoning` / `tool_request` / `error` will dispatch silently.
  *   - `show: "always"`, `"when-hidden"`, or `false` overrides this default.
- *   - When rendering, `notification.*` is consulted, with per-field fallback to
- *     the top-level `title` / `avatarUrl` / `messageId` and finally
- *     to the SW's `defaultIcon` / `defaultBadge` options. Everything
- *     else (`tag`, `renotify`, `requireInteraction`) has no top-level
- *     fallback — set them under `notification` or accept the SW default.
+ *   - 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`,
+ *     `renotify`, `requireInteraction`, `silent`, `data`), and finally to
+ *     the SW's `defaultIcon` / `defaultBadge` options (boolean knobs
+ *     default to `false` at the SW). Prefer setting overrides under
+ *     `notification` for explicitness; top-level fallback exists so that
+ *     legacy un-namespaced payloads keep working byte-for-byte.
  */
 export type NotificationDirective = {
     /**
@@ -380,35 +383,39 @@ export type NotificationDirective = {
      */
     show?: "auto" | "always" | "when-hidden" | false;
     /**
-     * - Notification title override.
+     * - Notification title override (falls back to top-level `title`, then `来自 {contactName}`).
      */
     title?: string;
     /**
-     * - Notification body override.
+     * - Notification body override (falls back to top-level `body`, then `message`).
      */
     body?: string;
     /**
-     * - Icon URL override (falls back to top-level `avatarUrl` then SW `defaultIcon`).
+     * - Icon URL override (falls back to top-level `icon`/`avatarUrl`, then SW `defaultIcon`).
      */
     icon?: string;
     /**
-     * - Badge URL override (falls back to SW `defaultBadge`).
+     * - Badge URL override (falls back to top-level `badge`, then SW `defaultBadge`).
      */
     badge?: string;
     /**
-     * - Notification grouping tag; matching tag replaces the prior notification.
+     * - Notification grouping tag; matching tag replaces the prior notification (falls back to top-level `tag`, then `messageId`, then a generated unique tag).
      */
     tag?: string;
     /**
-     * - When tag matches, still vibrate/sound. Default false at SW.
+     * - When tag matches, still vibrate/sound (falls back to top-level `renotify`, default false at SW).
      */
     renotify?: boolean;
     /**
-     * - Notification stays until user dismisses. Default false at SW.
+     * - Notification stays until user dismisses (falls back to top-level `requireInteraction`, default false at SW).
      */
     requireInteraction?: boolean;
     /**
-     * - Custom payload data to attach to the notification.
+     * - Suppress sound and vibration (falls back to top-level `silent`, default false at SW).
+     */
+    silent?: boolean;
+    /**
+     * - Custom payload data to attach to the notification (falls back to top-level `data`).
      */
     data?: Record<string, unknown>;
 };

package/dist/index.d.ts

@@ -200,10 +200,10 @@ export function isErrorPush(value: unknown): value is ErrorPush;
 /**
  * Slice a string into UTF-8 byte chunks no larger than `maxBytes`,
  * always cutting at codepoint boundaries (never inside a multi-byte
- * char). Designed for the {@link ReasoningPush} byte-chunking path
- * in amsg-instant — producers facing the ~3 KB Web Push payload
- * limit slice oversized reasoning into N pushes with
- * `chunkIndex` / `totalChunks`, the SW reassembles by concat.
+ * char). This is a generic byte-safe string helper retained for
+ * callers that need deterministic UTF-8 chunking around small Web Push
+ * payload budgets; current amsg-instant oversized payload delivery uses
+ * BlobStore / generic multipart instead of reasoning-only wire fields.
  *
  * Algorithm: TextEncoder → Uint8Array → backward scan from each
  * candidate cut index until the byte is a UTF-8 lead byte (any byte
@@ -361,18 +361,21 @@ export type AmsgPushCommon = {
 };
 /**
  * SW-rendering directive. Mirrors the fields that `amsg-sw`'s
- * `createNotificationFromPayload` consumes (`notification.{title,body,icon,badge,tag,renotify,requireInteraction,data}`)
- * — typing all fields so callers don't lose IDE checking and slip back into the untyped-spread footgun.
+ * `createNotificationFromPayload` consumes (`notification.{show,title,body,icon,badge,tag,renotify,requireInteraction,silent,data}`)
+ * so producers get builder validation for the fields the SW actually reads.
  *
- * Routing in SW (kept here so producers don't have to cross-check):
+ * Routing in SW:
  *   - By default (`show: "auto"` or omitted), `messageKind: 'content'` (and legacy un-kinded payloads)
  *     will display a system notification. `reasoning` / `tool_request` / `error` will dispatch silently.
  *   - `show: "always"`, `"when-hidden"`, or `false` overrides this default.
- *   - When rendering, `notification.*` is consulted, with per-field fallback to
- *     the top-level `title` / `avatarUrl` / `messageId` and finally
- *     to the SW's `defaultIcon` / `defaultBadge` options. Everything
- *     else (`tag`, `renotify`, `requireInteraction`) has no top-level
- *     fallback — set them under `notification` or accept the SW default.
+ *   - 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`,
+ *     `renotify`, `requireInteraction`, `silent`, `data`), and finally to
+ *     the SW's `defaultIcon` / `defaultBadge` options (boolean knobs
+ *     default to `false` at the SW). Prefer setting overrides under
+ *     `notification` for explicitness; top-level fallback exists so that
+ *     legacy un-namespaced payloads keep working byte-for-byte.
  */
 export type NotificationDirective = {
     /**
@@ -380,35 +383,39 @@ export type NotificationDirective = {
      */
     show?: "auto" | "always" | "when-hidden" | false;
     /**
-     * - Notification title override.
+     * - Notification title override (falls back to top-level `title`, then `来自 {contactName}`).
      */
     title?: string;
     /**
-     * - Notification body override.
+     * - Notification body override (falls back to top-level `body`, then `message`).
      */
     body?: string;
     /**
-     * - Icon URL override (falls back to top-level `avatarUrl` then SW `defaultIcon`).
+     * - Icon URL override (falls back to top-level `icon`/`avatarUrl`, then SW `defaultIcon`).
      */
     icon?: string;
     /**
-     * - Badge URL override (falls back to SW `defaultBadge`).
+     * - Badge URL override (falls back to top-level `badge`, then SW `defaultBadge`).
      */
     badge?: string;
     /**
-     * - Notification grouping tag; matching tag replaces the prior notification.
+     * - Notification grouping tag; matching tag replaces the prior notification (falls back to top-level `tag`, then `messageId`, then a generated unique tag).
      */
     tag?: string;
     /**
-     * - When tag matches, still vibrate/sound. Default false at SW.
+     * - When tag matches, still vibrate/sound (falls back to top-level `renotify`, default false at SW).
      */
     renotify?: boolean;
     /**
-     * - Notification stays until user dismisses. Default false at SW.
+     * - Notification stays until user dismisses (falls back to top-level `requireInteraction`, default false at SW).
      */
     requireInteraction?: boolean;
     /**
-     * - Custom payload data to attach to the notification.
+     * - Suppress sound and vibration (falls back to top-level `silent`, default false at SW).
+     */
+    silent?: boolean;
+    /**
+     * - Custom payload data to attach to the notification (falls back to top-level `data`).
      */
     data?: Record<string, unknown>;
 };

package/dist/index.mjs

@@ -122,7 +122,7 @@ function validateNotificationArg(kind, value) {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a string when present`);
     }
   }
-  for (const f of ["renotify", "requireInteraction"]) {
+  for (const f of ["renotify", "requireInteraction", "silent"]) {
     if (n[f] !== void 0 && typeof n[f] !== "boolean") {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a boolean when present`);
     }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@rei-standard/amsg-shared",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "ReiStandard Active Messaging shared types and push builders — the lowest layer (no deps on other amsg packages)",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Tosd0/ReiStandard",
+    "url": "git+https://github.com/Tosd0/ReiStandard.git",
     "directory": "packages/rei-standard-amsg/shared"
   },
   "license": "MIT",