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

package/dist/index.cjs

@@ -22,15 +22,18 @@ __export(src_exports, {
   MESSAGE_KIND: () => MESSAGE_KIND,
   MESSAGE_TYPE: () => MESSAGE_TYPE,
   PUSH_SOURCE: () => PUSH_SOURCE,
+  base64UrlToBytes: () => base64UrlToBytes,
   buildContentPush: () => buildContentPush,
   buildErrorPush: () => buildErrorPush,
   buildReasoningPush: () => buildReasoningPush,
   buildToolRequestPush: () => buildToolRequestPush,
   chunkReasoningByUtf8Bytes: () => chunkReasoningByUtf8Bytes,
+  concatBytes: () => concatBytes,
   isContentPush: () => isContentPush,
   isErrorPush: () => isErrorPush,
   isReasoningPush: () => isReasoningPush,
-  isToolRequestPush: () => isToolRequestPush
+  isToolRequestPush: () => isToolRequestPush,
+  toUint8: () => toUint8
 });
 module.exports = __toCommonJS(src_exports);
 var MESSAGE_KIND = Object.freeze({
@@ -91,6 +94,7 @@ function buildReasoningPush(args) {
   if (typeof args.reasoningContent !== "string" || !args.reasoningContent) {
     throw new Error("[amsg-shared] ReasoningPush: 'reasoningContent' must be a non-empty string");
   }
+  validateNotificationArg("ReasoningPush", args.notification);
   const push = {
     messageKind: "reasoning",
     messageType: args.messageType,
@@ -109,6 +113,7 @@ function buildReasoningPush(args) {
   if (args.chunkIndex !== void 0) push.chunkIndex = args.chunkIndex;
   if (args.totalChunks !== void 0) push.totalChunks = args.totalChunks;
   if (args.metadata !== void 0) push.metadata = args.metadata;
+  if (args.notification !== void 0) push.notification = args.notification;
   return push;
 }
 function buildToolRequestPush(args) {
@@ -146,6 +151,9 @@ function validateNotificationArg(kind, value) {
     /** @type {Record<string, unknown>} */
     value
   );
+  if (n.show !== void 0 && !["auto", "always", "when-hidden", false].includes(n.show)) {
+    throw new Error(`[amsg-shared] ${kind}: 'notification.show' must be "auto", "always", "when-hidden", or false`);
+  }
   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`);
@@ -156,6 +164,9 @@ function validateNotificationArg(kind, value) {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a boolean when present`);
     }
   }
+  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`);
+  }
 }
 function buildErrorPush(args) {
   requireField("ErrorPush", "messageType", args.messageType);
@@ -166,6 +177,7 @@ function buildErrorPush(args) {
   if (typeof args.message !== "string") {
     throw new Error("[amsg-shared] ErrorPush: 'message' must be a string");
   }
+  validateNotificationArg("ErrorPush", args.notification);
   const push = {
     messageKind: "error",
     messageType: args.messageType,
@@ -179,6 +191,7 @@ function buildErrorPush(args) {
   if (args.iteration !== void 0) push.iteration = args.iteration;
   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 isContentPush(value) {
@@ -225,3 +238,29 @@ function chunkReasoningByUtf8Bytes(text, maxBytes) {
   }
   return chunks;
 }
+function toUint8(buf) {
+  if (buf instanceof Uint8Array) return buf;
+  if (buf instanceof ArrayBuffer) return new Uint8Array(buf);
+  if (ArrayBuffer.isView(buf)) return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+  throw new TypeError("Expected ArrayBuffer / Uint8Array");
+}
+function base64UrlToBytes(input) {
+  const s = String(input).replace(/-/g, "+").replace(/_/g, "/");
+  const pad = (4 - s.length % 4) % 4;
+  const padded = s + "=".repeat(pad);
+  const bin = typeof atob === "function" ? atob(padded) : Buffer.from(padded, "base64").toString("binary");
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+function concatBytes(...chunks) {
+  let total = 0;
+  for (const c of chunks) total += c.byteLength;
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c instanceof Uint8Array ? c : new Uint8Array(c.buffer || c), offset);
+    offset += c.byteLength;
+  }
+  return out;
+}

package/dist/index.d.cts

@@ -153,6 +153,7 @@ export function buildToolRequestPush(args: {
  * @param {number}      [args.iteration]
  * @param {string}      [args.messageSubtype]
  * @param {Object}      [args.metadata]
+ * @param {NotificationDirective} [args.notification]
  * @returns {ErrorPush}
  */
 export function buildErrorPush(args: {
@@ -166,6 +167,7 @@ export function buildErrorPush(args: {
     iteration?: number;
     messageSubtype?: string;
     metadata?: any;
+    notification?: NotificationDirective;
 }): ErrorPush;
 /**
  * Type guard: returns true if the argument is a {@link ContentPush}.
@@ -229,6 +231,22 @@ export function isErrorPush(value: unknown): value is ErrorPush;
  * @returns {string[]}
  */
 export function chunkReasoningByUtf8Bytes(text: string, maxBytes: number): string[];
+/**
+ * Coerce ArrayBuffer | Uint8Array | view → Uint8Array (no copy when possible).
+ */
+export function toUint8(buf: any): Uint8Array<ArrayBufferLike>;
+/**
+ * Decode base64url (with or without padding) → Uint8Array.
+ * @param {string} input
+ * @returns {Uint8Array}
+ */
+export function base64UrlToBytes(input: string): Uint8Array;
+/**
+ * Concatenate Uint8Arrays into a single Uint8Array.
+ * @param {...(Uint8Array | ArrayBuffer | ArrayBufferView)} chunks
+ * @returns {Uint8Array}
+ */
+export function concatBytes(...chunks: (Uint8Array | ArrayBuffer | ArrayBufferView)[]): Uint8Array;
 /**
  * @rei-standard/amsg-shared
  *
@@ -336,30 +354,31 @@ export type AmsgPushCommon = {
      * - Caller passthrough. Packages MUST NOT write here.
      */
     metadata?: any;
+    /**
+     * - SW notification strategy.
+     */
+    notification?: NotificationDirective;
 };
 /**
- * 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.
+ * 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.
  *
  * 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
+ *   - 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 (`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.)
+ *     fallback — set them under `notification` or accept the SW default.
  */
 export type NotificationDirective = {
+    /**
+     * - Rendering strategy. Defaults to "auto" (render only if messageKind is content).
+     */
+    show?: "auto" | "always" | "when-hidden" | false;
     /**
      * - Notification title override.
      */
@@ -388,6 +407,10 @@ export type NotificationDirective = {
      * - Notification stays until user dismisses. Default false at SW.
      */
     requireInteraction?: boolean;
+    /**
+     * - Custom payload data to attach to the notification.
+     */
+    data?: Record<string, unknown>;
 };
 /**
  * Final user-facing content. Sentence-split bursts of N use
@@ -403,7 +426,6 @@ export type ContentPush = AmsgPushCommon & {
     messageIndex?: number;
     totalMessages?: number;
     taskId?: string | null;
-    notification?: NotificationDirective;
 };
 /**
  * LLM "meta-thinking" — `choices[0].message.reasoning_content` lifted
@@ -455,7 +477,6 @@ export type ToolRequestPush = AmsgPushCommon & {
     title?: string;
     contactName?: string;
     message?: string;
-    notification?: NotificationDirective;
 };
 /**
  * Producer-level error. Replaces the legacy

package/dist/index.d.ts

@@ -153,6 +153,7 @@ export function buildToolRequestPush(args: {
  * @param {number}      [args.iteration]
  * @param {string}      [args.messageSubtype]
  * @param {Object}      [args.metadata]
+ * @param {NotificationDirective} [args.notification]
  * @returns {ErrorPush}
  */
 export function buildErrorPush(args: {
@@ -166,6 +167,7 @@ export function buildErrorPush(args: {
     iteration?: number;
     messageSubtype?: string;
     metadata?: any;
+    notification?: NotificationDirective;
 }): ErrorPush;
 /**
  * Type guard: returns true if the argument is a {@link ContentPush}.
@@ -229,6 +231,22 @@ export function isErrorPush(value: unknown): value is ErrorPush;
  * @returns {string[]}
  */
 export function chunkReasoningByUtf8Bytes(text: string, maxBytes: number): string[];
+/**
+ * Coerce ArrayBuffer | Uint8Array | view → Uint8Array (no copy when possible).
+ */
+export function toUint8(buf: any): Uint8Array<ArrayBufferLike>;
+/**
+ * Decode base64url (with or without padding) → Uint8Array.
+ * @param {string} input
+ * @returns {Uint8Array}
+ */
+export function base64UrlToBytes(input: string): Uint8Array;
+/**
+ * Concatenate Uint8Arrays into a single Uint8Array.
+ * @param {...(Uint8Array | ArrayBuffer | ArrayBufferView)} chunks
+ * @returns {Uint8Array}
+ */
+export function concatBytes(...chunks: (Uint8Array | ArrayBuffer | ArrayBufferView)[]): Uint8Array;
 /**
  * @rei-standard/amsg-shared
  *
@@ -336,30 +354,31 @@ export type AmsgPushCommon = {
      * - Caller passthrough. Packages MUST NOT write here.
      */
     metadata?: any;
+    /**
+     * - SW notification strategy.
+     */
+    notification?: NotificationDirective;
 };
 /**
- * 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.
+ * 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.
  *
  * 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
+ *   - 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 (`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.)
+ *     fallback — set them under `notification` or accept the SW default.
  */
 export type NotificationDirective = {
+    /**
+     * - Rendering strategy. Defaults to "auto" (render only if messageKind is content).
+     */
+    show?: "auto" | "always" | "when-hidden" | false;
     /**
      * - Notification title override.
      */
@@ -388,6 +407,10 @@ export type NotificationDirective = {
      * - Notification stays until user dismisses. Default false at SW.
      */
     requireInteraction?: boolean;
+    /**
+     * - Custom payload data to attach to the notification.
+     */
+    data?: Record<string, unknown>;
 };
 /**
  * Final user-facing content. Sentence-split bursts of N use
@@ -403,7 +426,6 @@ export type ContentPush = AmsgPushCommon & {
     messageIndex?: number;
     totalMessages?: number;
     taskId?: string | null;
-    notification?: NotificationDirective;
 };
 /**
  * LLM "meta-thinking" — `choices[0].message.reasoning_content` lifted
@@ -455,7 +477,6 @@ export type ToolRequestPush = AmsgPushCommon & {
     title?: string;
     contactName?: string;
     message?: string;
-    notification?: NotificationDirective;
 };
 /**
  * Producer-level error. Replaces the legacy

package/dist/index.mjs

@@ -57,6 +57,7 @@ function buildReasoningPush(args) {
   if (typeof args.reasoningContent !== "string" || !args.reasoningContent) {
     throw new Error("[amsg-shared] ReasoningPush: 'reasoningContent' must be a non-empty string");
   }
+  validateNotificationArg("ReasoningPush", args.notification);
   const push = {
     messageKind: "reasoning",
     messageType: args.messageType,
@@ -75,6 +76,7 @@ function buildReasoningPush(args) {
   if (args.chunkIndex !== void 0) push.chunkIndex = args.chunkIndex;
   if (args.totalChunks !== void 0) push.totalChunks = args.totalChunks;
   if (args.metadata !== void 0) push.metadata = args.metadata;
+  if (args.notification !== void 0) push.notification = args.notification;
   return push;
 }
 function buildToolRequestPush(args) {
@@ -112,6 +114,9 @@ function validateNotificationArg(kind, value) {
     /** @type {Record<string, unknown>} */
     value
   );
+  if (n.show !== void 0 && !["auto", "always", "when-hidden", false].includes(n.show)) {
+    throw new Error(`[amsg-shared] ${kind}: 'notification.show' must be "auto", "always", "when-hidden", or false`);
+  }
   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`);
@@ -122,6 +127,9 @@ function validateNotificationArg(kind, value) {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a boolean when present`);
     }
   }
+  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`);
+  }
 }
 function buildErrorPush(args) {
   requireField("ErrorPush", "messageType", args.messageType);
@@ -132,6 +140,7 @@ function buildErrorPush(args) {
   if (typeof args.message !== "string") {
     throw new Error("[amsg-shared] ErrorPush: 'message' must be a string");
   }
+  validateNotificationArg("ErrorPush", args.notification);
   const push = {
     messageKind: "error",
     messageType: args.messageType,
@@ -145,6 +154,7 @@ function buildErrorPush(args) {
   if (args.iteration !== void 0) push.iteration = args.iteration;
   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 isContentPush(value) {
@@ -191,17 +201,46 @@ function chunkReasoningByUtf8Bytes(text, maxBytes) {
   }
   return chunks;
 }
+function toUint8(buf) {
+  if (buf instanceof Uint8Array) return buf;
+  if (buf instanceof ArrayBuffer) return new Uint8Array(buf);
+  if (ArrayBuffer.isView(buf)) return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+  throw new TypeError("Expected ArrayBuffer / Uint8Array");
+}
+function base64UrlToBytes(input) {
+  const s = String(input).replace(/-/g, "+").replace(/_/g, "/");
+  const pad = (4 - s.length % 4) % 4;
+  const padded = s + "=".repeat(pad);
+  const bin = typeof atob === "function" ? atob(padded) : Buffer.from(padded, "base64").toString("binary");
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+function concatBytes(...chunks) {
+  let total = 0;
+  for (const c of chunks) total += c.byteLength;
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c instanceof Uint8Array ? c : new Uint8Array(c.buffer || c), offset);
+    offset += c.byteLength;
+  }
+  return out;
+}
 export {
   MESSAGE_KIND,
   MESSAGE_TYPE,
   PUSH_SOURCE,
+  base64UrlToBytes,
   buildContentPush,
   buildErrorPush,
   buildReasoningPush,
   buildToolRequestPush,
   chunkReasoningByUtf8Bytes,
+  concatBytes,
   isContentPush,
   isErrorPush,
   isReasoningPush,
-  isToolRequestPush
+  isToolRequestPush,
+  toUint8
 };

package/package.json

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