@rei-standard/amsg-shared 0.1.0-next.2 → 0.1.0-next.3

package/dist/index.cjs

@@ -62,6 +62,7 @@ function buildContentPush(args) {
   if (typeof args.message !== "string") {
     throw new Error("[amsg-shared] ContentPush: 'message' must be a string");
   }
+  validateNotificationArg("ContentPush", args.notification);
   const push = {
     messageKind: "content",
     messageType: args.messageType,
@@ -79,6 +80,7 @@ function buildContentPush(args) {
   if (args.totalMessages !== void 0) push.totalMessages = args.totalMessages;
   if (args.taskId !== void 0) push.taskId = args.taskId;
   if (args.metadata !== void 0) push.metadata = args.metadata;
+  if (args.notification !== void 0) push.notification = args.notification;
   return push;
 }
 function buildReasoningPush(args) {
@@ -117,6 +119,7 @@ function buildToolRequestPush(args) {
   if (!Array.isArray(args.toolCalls) || args.toolCalls.length === 0) {
     throw new Error("[amsg-shared] ToolRequestPush: 'toolCalls' must be a non-empty array");
   }
+  validateNotificationArg("ToolRequestPush", args.notification);
   const push = {
     messageKind: "tool_request",
     messageType: args.messageType,
@@ -131,8 +134,29 @@ function buildToolRequestPush(args) {
   if (args.message !== void 0) push.message = args.message;
   if (args.messageSubtype !== void 0) push.messageSubtype = args.messageSubtype;
   if (args.metadata !== void 0) push.metadata = args.metadata;
+  if (args.notification !== void 0) push.notification = args.notification;
   return push;
 }
+function validateNotificationArg(kind, value) {
+  if (value === void 0) return;
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`[amsg-shared] ${kind}: 'notification' must be a plain object`);
+  }
+  const n = (
+    /** @type {Record<string, unknown>} */
+    value
+  );
+  for (const f of ["title", "body", "icon", "badge", "tag"]) {
+    if (n[f] !== void 0 && typeof n[f] !== "string") {
+      throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a string when present`);
+    }
+  }
+  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`);
+    }
+  }
+}
 function buildErrorPush(args) {
   requireField("ErrorPush", "messageType", args.messageType);
   requireField("ErrorPush", "source", args.source);

package/dist/index.d.cts

@@ -18,6 +18,12 @@
  * @param {number}      [args.totalMessages]
  * @param {string | null} [args.taskId]
  * @param {Object}      [args.metadata]
+ * @param {NotificationDirective} [args.notification]
+ *                       - SW-side `showNotification` overrides for content
+ *                         (and for ToolRequestPush prefix chunks that get
+ *                         demoted to `content` during sentence-split). All
+ *                         fields optional; see {@link NotificationDirective}
+ *                         for the SW fallback chain.
  * @returns {ContentPush}
  */
 export function buildContentPush(args: {
@@ -35,6 +41,7 @@ export function buildContentPush(args: {
     totalMessages?: number;
     taskId?: string | null;
     metadata?: any;
+    notification?: NotificationDirective;
 }): ContentPush;
 /**
  * Build a {@link ReasoningPush}. Producers emit this **before** any
@@ -104,6 +111,15 @@ export function buildReasoningPush(args: {
  * @param {string}      [args.message]
  * @param {string}      [args.messageSubtype]
  * @param {Object}      [args.metadata]
+ * @param {NotificationDirective} [args.notification]
+ *                       - SW notification overrides. Used after the
+ *                         splitter demotes prefix chunks to `content`
+ *                         (where `messageKind: 'content'` triggers
+ *                         `showNotification`). On the un-demoted last
+ *                         chunk (`messageKind: 'tool_request'`) the
+ *                         SW dispatches silently and the field is
+ *                         ignored — typed here purely so the demoted
+ *                         chunks inherit it via the splitter's spread.
  * @returns {ToolRequestPush}
  */
 export function buildToolRequestPush(args: {
@@ -118,6 +134,7 @@ export function buildToolRequestPush(args: {
     message?: string;
     messageSubtype?: string;
     metadata?: any;
+    notification?: NotificationDirective;
 }): ToolRequestPush;
 /**
  * Build an {@link ErrorPush}. Replaces the legacy
@@ -320,6 +337,58 @@ export type AmsgPushCommon = {
      */
     metadata?: any;
 };
+/**
+ * SW-rendering directive carried on `ContentPush` / `ToolRequestPush`.
+ * Mirrors the seven fields that `amsg-sw`'s `createNotificationFromPayload`
+ * actually consumes (`notification.{title,body,icon,badge,tag,renotify,requireInteraction}`)
+ * — typing all seven (rather than just `title` / `body`) so callers
+ * don't lose IDE checking on the other five and slip back into the
+ * untyped-spread footgun this typedef was added to close.
+ *
+ * Routing in SW (kept here so producers don't have to cross-check):
+ *   - `messageKind: 'content'` (and legacy un-kinded payloads) →
+ *     `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 (`messageId`-derived tag, no renotify, no requireInteraction).
+ *   - `messageKind: 'reasoning'` / `'tool_request'` / `'error'` →
+ *     dispatched silently to controlled clients. `notification` is
+ *     ignored. (It's still typed on `ToolRequestPush` because the
+ *     splitter demotes prefix chunks to `messageKind: 'content'`, at
+ *     which point the field starts mattering.)
+ */
+export type NotificationDirective = {
+    /**
+     * - Notification title override.
+     */
+    title?: string;
+    /**
+     * - Notification body override.
+     */
+    body?: string;
+    /**
+     * - Icon URL override (falls back to top-level `avatarUrl` then SW `defaultIcon`).
+     */
+    icon?: string;
+    /**
+     * - Badge URL override (falls back to SW `defaultBadge`).
+     */
+    badge?: string;
+    /**
+     * - Notification grouping tag; matching tag replaces the prior notification.
+     */
+    tag?: string;
+    /**
+     * - When tag matches, still vibrate/sound. Default false at SW.
+     */
+    renotify?: boolean;
+    /**
+     * - Notification stays until user dismisses. Default false at SW.
+     */
+    requireInteraction?: boolean;
+};
 /**
  * Final user-facing content. Sentence-split bursts of N use
  * `messageIndex` (1-based) + `totalMessages` so the client can
@@ -334,6 +403,7 @@ export type ContentPush = AmsgPushCommon & {
     messageIndex?: number;
     totalMessages?: number;
     taskId?: string | null;
+    notification?: NotificationDirective;
 };
 /**
  * LLM "meta-thinking" — `choices[0].message.reasoning_content` lifted
@@ -385,6 +455,7 @@ export type ToolRequestPush = AmsgPushCommon & {
     title?: string;
     contactName?: string;
     message?: string;
+    notification?: NotificationDirective;
 };
 /**
  * Producer-level error. Replaces the legacy

package/dist/index.d.ts

@@ -18,6 +18,12 @@
  * @param {number}      [args.totalMessages]
  * @param {string | null} [args.taskId]
  * @param {Object}      [args.metadata]
+ * @param {NotificationDirective} [args.notification]
+ *                       - SW-side `showNotification` overrides for content
+ *                         (and for ToolRequestPush prefix chunks that get
+ *                         demoted to `content` during sentence-split). All
+ *                         fields optional; see {@link NotificationDirective}
+ *                         for the SW fallback chain.
  * @returns {ContentPush}
  */
 export function buildContentPush(args: {
@@ -35,6 +41,7 @@ export function buildContentPush(args: {
     totalMessages?: number;
     taskId?: string | null;
     metadata?: any;
+    notification?: NotificationDirective;
 }): ContentPush;
 /**
  * Build a {@link ReasoningPush}. Producers emit this **before** any
@@ -104,6 +111,15 @@ export function buildReasoningPush(args: {
  * @param {string}      [args.message]
  * @param {string}      [args.messageSubtype]
  * @param {Object}      [args.metadata]
+ * @param {NotificationDirective} [args.notification]
+ *                       - SW notification overrides. Used after the
+ *                         splitter demotes prefix chunks to `content`
+ *                         (where `messageKind: 'content'` triggers
+ *                         `showNotification`). On the un-demoted last
+ *                         chunk (`messageKind: 'tool_request'`) the
+ *                         SW dispatches silently and the field is
+ *                         ignored — typed here purely so the demoted
+ *                         chunks inherit it via the splitter's spread.
  * @returns {ToolRequestPush}
  */
 export function buildToolRequestPush(args: {
@@ -118,6 +134,7 @@ export function buildToolRequestPush(args: {
     message?: string;
     messageSubtype?: string;
     metadata?: any;
+    notification?: NotificationDirective;
 }): ToolRequestPush;
 /**
  * Build an {@link ErrorPush}. Replaces the legacy
@@ -320,6 +337,58 @@ export type AmsgPushCommon = {
      */
     metadata?: any;
 };
+/**
+ * SW-rendering directive carried on `ContentPush` / `ToolRequestPush`.
+ * Mirrors the seven fields that `amsg-sw`'s `createNotificationFromPayload`
+ * actually consumes (`notification.{title,body,icon,badge,tag,renotify,requireInteraction}`)
+ * — typing all seven (rather than just `title` / `body`) so callers
+ * don't lose IDE checking on the other five and slip back into the
+ * untyped-spread footgun this typedef was added to close.
+ *
+ * Routing in SW (kept here so producers don't have to cross-check):
+ *   - `messageKind: 'content'` (and legacy un-kinded payloads) →
+ *     `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 (`messageId`-derived tag, no renotify, no requireInteraction).
+ *   - `messageKind: 'reasoning'` / `'tool_request'` / `'error'` →
+ *     dispatched silently to controlled clients. `notification` is
+ *     ignored. (It's still typed on `ToolRequestPush` because the
+ *     splitter demotes prefix chunks to `messageKind: 'content'`, at
+ *     which point the field starts mattering.)
+ */
+export type NotificationDirective = {
+    /**
+     * - Notification title override.
+     */
+    title?: string;
+    /**
+     * - Notification body override.
+     */
+    body?: string;
+    /**
+     * - Icon URL override (falls back to top-level `avatarUrl` then SW `defaultIcon`).
+     */
+    icon?: string;
+    /**
+     * - Badge URL override (falls back to SW `defaultBadge`).
+     */
+    badge?: string;
+    /**
+     * - Notification grouping tag; matching tag replaces the prior notification.
+     */
+    tag?: string;
+    /**
+     * - When tag matches, still vibrate/sound. Default false at SW.
+     */
+    renotify?: boolean;
+    /**
+     * - Notification stays until user dismisses. Default false at SW.
+     */
+    requireInteraction?: boolean;
+};
 /**
  * Final user-facing content. Sentence-split bursts of N use
  * `messageIndex` (1-based) + `totalMessages` so the client can
@@ -334,6 +403,7 @@ export type ContentPush = AmsgPushCommon & {
     messageIndex?: number;
     totalMessages?: number;
     taskId?: string | null;
+    notification?: NotificationDirective;
 };
 /**
  * LLM "meta-thinking" — `choices[0].message.reasoning_content` lifted
@@ -385,6 +455,7 @@ export type ToolRequestPush = AmsgPushCommon & {
     title?: string;
     contactName?: string;
     message?: string;
+    notification?: NotificationDirective;
 };
 /**
  * Producer-level error. Replaces the legacy

package/dist/index.mjs

@@ -28,6 +28,7 @@ function buildContentPush(args) {
   if (typeof args.message !== "string") {
     throw new Error("[amsg-shared] ContentPush: 'message' must be a string");
   }
+  validateNotificationArg("ContentPush", args.notification);
   const push = {
     messageKind: "content",
     messageType: args.messageType,
@@ -45,6 +46,7 @@ function buildContentPush(args) {
   if (args.totalMessages !== void 0) push.totalMessages = args.totalMessages;
   if (args.taskId !== void 0) push.taskId = args.taskId;
   if (args.metadata !== void 0) push.metadata = args.metadata;
+  if (args.notification !== void 0) push.notification = args.notification;
   return push;
 }
 function buildReasoningPush(args) {
@@ -83,6 +85,7 @@ function buildToolRequestPush(args) {
   if (!Array.isArray(args.toolCalls) || args.toolCalls.length === 0) {
     throw new Error("[amsg-shared] ToolRequestPush: 'toolCalls' must be a non-empty array");
   }
+  validateNotificationArg("ToolRequestPush", args.notification);
   const push = {
     messageKind: "tool_request",
     messageType: args.messageType,
@@ -97,8 +100,29 @@ function buildToolRequestPush(args) {
   if (args.message !== void 0) push.message = args.message;
   if (args.messageSubtype !== void 0) push.messageSubtype = args.messageSubtype;
   if (args.metadata !== void 0) push.metadata = args.metadata;
+  if (args.notification !== void 0) push.notification = args.notification;
   return push;
 }
+function validateNotificationArg(kind, value) {
+  if (value === void 0) return;
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`[amsg-shared] ${kind}: 'notification' must be a plain object`);
+  }
+  const n = (
+    /** @type {Record<string, unknown>} */
+    value
+  );
+  for (const f of ["title", "body", "icon", "badge", "tag"]) {
+    if (n[f] !== void 0 && typeof n[f] !== "string") {
+      throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a string when present`);
+    }
+  }
+  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`);
+    }
+  }
+}
 function buildErrorPush(args) {
   requireField("ErrorPush", "messageType", args.messageType);
   requireField("ErrorPush", "source", args.source);

package/package.json

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