@rei-standard/amsg-shared 0.2.0 → 0.3.0

package/README.md

@@ -1,7 +1,7 @@
 # @rei-standard/amsg-shared
 
-Lowest layer of the ReiStandard Active Messaging ecosystem. Defines
-the **three-axis push contract** that `amsg-instant`, `amsg-server`,
+Lowest layer of the ReiStandard Active Messaging stack. Defines
+the **push schema** that `amsg-instant`, `amsg-server`,
 `amsg-sw`, and `amsg-client` all conform to.
 
 Zero runtime deps. Does **not** depend on any other amsg package —
@@ -9,9 +9,9 @@ every other amsg sub-package depends on this one, never the reverse.
 
 ---
 
-## Three axes
+## Push schema
 
-A single push is described by three orthogonal axes:
+A single push is described by three independent dimensions:
 
 | Axis           | Field             | Values                                                | Defined by         |
 |----------------|-------------------|-------------------------------------------------------|--------------------|
@@ -22,7 +22,7 @@ A single push is described by three orthogonal axes:
 `messageType` answers **how this push was produced** (one-shot
 `instant` worker, scheduled `fixed` ping, AI-`prompted` reply, fully
 `auto`-generated cadence). `messageKind` answers **what it carries**.
-The two are intentionally orthogonal: any `messageType` can carry any
+The two are intentionally independent: any `messageType` can carry any
 `messageKind`.
 
 There is also `source: 'instant' | 'scheduled'` — the **routing

package/dist/index.cjs

@@ -19,6 +19,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.js
 var src_exports = {};
 __export(src_exports, {
+  AVATAR_URL_MAX_LENGTH: () => AVATAR_URL_MAX_LENGTH,
   MESSAGE_KIND: () => MESSAGE_KIND,
   MESSAGE_TYPE: () => MESSAGE_TYPE,
   PUSH_SOURCE: () => PUSH_SOURCE,
@@ -33,7 +34,12 @@ __export(src_exports, {
   isErrorPush: () => isErrorPush,
   isReasoningPush: () => isReasoningPush,
   isToolRequestPush: () => isToolRequestPush,
-  toUint8: () => toUint8
+  isValidUrl: () => isValidUrl,
+  normalizeVapidSubject: () => normalizeVapidSubject,
+  readReasoningContent: () => readReasoningContent,
+  stripReasoningTags: () => stripReasoningTags,
+  toUint8: () => toUint8,
+  validateAvatarUrl: () => validateAvatarUrl
 });
 module.exports = __toCommonJS(src_exports);
 var MESSAGE_KIND = Object.freeze({
@@ -264,3 +270,66 @@ function concatBytes(...chunks) {
   }
   return out;
 }
+function isValidUrl(value) {
+  if (typeof value !== "string") return false;
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var AVATAR_URL_MAX_LENGTH = 2048;
+function validateAvatarUrl(value) {
+  if (value === void 0 || value === null) return null;
+  if (typeof value !== "string") {
+    return "avatarUrl \u5FC5\u987B\u662F\u5B57\u7B26\u4E32";
+  }
+  if (/^data:/i.test(value)) {
+    return "\u5934\u50CF\u4E0D\u652F\u6301\u4F20\u5165 data: URI\uFF0C\u8BF7\u6539\u4E3A\u516C\u7F51\u53EF\u8BBF\u95EE\u7684 https:// \u56FE\u7247 URL";
+  }
+  if (value.length > AVATAR_URL_MAX_LENGTH) {
+    return `\u5934\u50CF URL \u957F\u5EA6 ${value.length} \u5B57\u7B26\u8D85\u8FC7 ${AVATAR_URL_MAX_LENGTH} \u4E0A\u9650\uFF0C\u8BF7\u6539\u4E3A\u66F4\u77ED\u7684\u56FE\u7247 URL`;
+  }
+  if (!isValidUrl(value)) {
+    return "avatarUrl \u4E0D\u662F\u5408\u6CD5 URL";
+  }
+  return null;
+}
+function normalizeVapidSubject(email) {
+  const trimmed = String(email || "").trim();
+  if (!trimmed) return "";
+  return /^mailto:/i.test(trimmed) || /^https?:/i.test(trimmed) ? trimmed : `mailto:${trimmed}`;
+}
+var REASONING_TAG_RE = /<(think|thinking|thought)>([\s\S]*?)<\/\1>/i;
+var REASONING_TAG_RE_G = /<(think|thinking|thought)>[\s\S]*?<\/\1>/gi;
+function readReasoningContent(llmResponse) {
+  if (!llmResponse || typeof llmResponse !== "object") return null;
+  const choices = (
+    /** @type {{ choices?: unknown }} */
+    llmResponse.choices
+  );
+  if (!Array.isArray(choices) || choices.length === 0) return null;
+  const message = (
+    /** @type {{ message?: { reasoning_content?: unknown, content?: unknown } }} */
+    choices[0]?.message
+  );
+  const raw = message?.reasoning_content;
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (trimmed.length > 0) return trimmed;
+  }
+  const content = message?.content;
+  if (typeof content === "string") {
+    const match = content.match(REASONING_TAG_RE);
+    if (match) {
+      const trimmed = match[2].trim();
+      if (trimmed.length > 0) return trimmed;
+    }
+  }
+  return null;
+}
+function stripReasoningTags(content) {
+  if (typeof content !== "string" || !content.includes("<")) return content;
+  return content.replace(REASONING_TAG_RE_G, "").trim();
+}

package/dist/index.d.cts

@@ -247,6 +247,56 @@ export function base64UrlToBytes(input: string): Uint8Array;
  * @returns {Uint8Array}
  */
 export function concatBytes(...chunks: (Uint8Array | ArrayBuffer | ArrayBufferView)[]): Uint8Array;
+/**
+ * True when `value` parses as an absolute URL.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isValidUrl(value: unknown): boolean;
+/**
+ * Validate the optional `avatarUrl` field. Rejects `data:` URIs (typically
+ * base64-encoded inline images) and anything longer than
+ * {@link AVATAR_URL_MAX_LENGTH} chars — both the dominant trigger for
+ * downstream 413 / Web Push 4 KB payload errors — plus anything that doesn't
+ * parse as a URL. Returns an error message string, or null when valid.
+ *
+ * Pure: callers decide how to act on a non-null result (amsg-server /
+ * amsg-instant / amsg-client soft-strip + console.warn; see standards §6.2).
+ *
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function validateAvatarUrl(value: unknown): string | null;
+/**
+ * Normalize a VAPID `sub` (subject) claim. Web Push (RFC 8292) accepts a
+ * `mailto:` address or an `http(s):` URL; a bare contact like
+ * `you@example.com` is prefixed with `mailto:`. An already-prefixed
+ * `mailto:` / `http(s):` value is returned untouched. Empty / blank → `''`.
+ *
+ * @param {unknown} email
+ * @returns {string}
+ */
+export function normalizeVapidSubject(email: unknown): string;
+/**
+ * Read `choices[0].message.reasoning_content` as a non-empty trimmed string,
+ * or null when absent / empty. Falls back to the first `<think>` span inside
+ * `message.content` when a provider inlines reasoning there. Many providers
+ * return an empty string instead of omitting the field — treated the same as
+ * missing so callers don't emit an empty ReasoningPush.
+ *
+ * @param {unknown} llmResponse
+ * @returns {string | null}
+ */
+export function readReasoningContent(llmResponse: unknown): string | null;
+/**
+ * Drop any `<think>` / `<thinking>` / `<thought>` spans from a user-facing
+ * content string, so private chain-of-thought leaking through `message.content`
+ * does not also ship inside the ContentPush burst.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function stripReasoningTags(content: string): string;
 /**
  * @rei-standard/amsg-shared
  *
@@ -316,6 +366,8 @@ export const PUSH_SOURCE: Readonly<{
     INSTANT: "instant";
     SCHEDULED: "scheduled";
 }>;
+/** Max accepted `avatarUrl` length, in characters. */
+export const AVATAR_URL_MAX_LENGTH: 2048;
 /**
  * Fields present on every push, regardless of kind. Discriminator
  * fields (`messageKind`) and kind-specific fields live on the kind
@@ -439,24 +491,24 @@ export type ContentPush = AmsgPushCommon & {
  * out of the upstream response into its own push. Emitted **before**
  * the matching {@link ContentPush} burst when present and non-empty.
  *
- * Reasoning carries two orthogonal "multi-part" axes, both optional —
- * they are *omitted* when the part count is 1 so the wire stays
- * byte-for-byte compatible with single-shot ReasoningPush callers:
+ * Reasoning carries two optional "multi-part" axes, both *omitted* when
+ * the part count is 1 so the wire stays byte-for-byte compatible with
+ * single-shot callers. The type reserves them for forward compatibility;
+ * current producers emit a single ReasoningPush and set neither — oversized
+ * reasoning rides the generic multipart transport, not a reasoning-only
+ * chunk format.
  *
- *   - `messageIndex` / `totalMessages` — set when a semantic
- *     splitter (`reasoningSplitPattern` in amsg-instant) has cut the
- *     reasoning into multiple sentences for typing-bubble UX.
+ *   - `messageIndex` / `totalMessages` — a 1-based part index when a producer
+ *     splits reasoning into multiple sentences for typing-bubble UX.
  *
- *   - `chunkIndex` / `totalChunks` — set when a single segment was
- *     too large for the Web Push payload limit and the producer had
- *     to slice it across multiple pushes at UTF-8 byte boundaries.
- *     Transport-only; SW reassembles the original `reasoningContent`
- *     by sorting on `chunkIndex` within a `(sessionId, messageIndex)`
- *     bucket. See `chunkReasoningByUtf8Bytes` for the safe-edge
- *     splitter helper.
+ *   - `chunkIndex` / `totalChunks` — transport-only slicing when a single
+ *     segment exceeds the Web Push payload limit; SW would reassemble the
+ *     original `reasoningContent` by sorting on `chunkIndex` within a
+ *     `(sessionId, messageIndex)` bucket. See `chunkReasoningByUtf8Bytes`
+ *     for the safe-edge splitter helper.
  *
- * Both axes can coexist on the same push when a sentence-split
- * segment is itself oversized.
+ * Both axes can coexist on the same push when a sentence-split segment is
+ * itself oversized.
  */
 export type ReasoningPush = AmsgPushCommon & {
     messageKind: "reasoning";

package/dist/index.d.ts

@@ -247,6 +247,56 @@ export function base64UrlToBytes(input: string): Uint8Array;
  * @returns {Uint8Array}
  */
 export function concatBytes(...chunks: (Uint8Array | ArrayBuffer | ArrayBufferView)[]): Uint8Array;
+/**
+ * True when `value` parses as an absolute URL.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isValidUrl(value: unknown): boolean;
+/**
+ * Validate the optional `avatarUrl` field. Rejects `data:` URIs (typically
+ * base64-encoded inline images) and anything longer than
+ * {@link AVATAR_URL_MAX_LENGTH} chars — both the dominant trigger for
+ * downstream 413 / Web Push 4 KB payload errors — plus anything that doesn't
+ * parse as a URL. Returns an error message string, or null when valid.
+ *
+ * Pure: callers decide how to act on a non-null result (amsg-server /
+ * amsg-instant / amsg-client soft-strip + console.warn; see standards §6.2).
+ *
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function validateAvatarUrl(value: unknown): string | null;
+/**
+ * Normalize a VAPID `sub` (subject) claim. Web Push (RFC 8292) accepts a
+ * `mailto:` address or an `http(s):` URL; a bare contact like
+ * `you@example.com` is prefixed with `mailto:`. An already-prefixed
+ * `mailto:` / `http(s):` value is returned untouched. Empty / blank → `''`.
+ *
+ * @param {unknown} email
+ * @returns {string}
+ */
+export function normalizeVapidSubject(email: unknown): string;
+/**
+ * Read `choices[0].message.reasoning_content` as a non-empty trimmed string,
+ * or null when absent / empty. Falls back to the first `<think>` span inside
+ * `message.content` when a provider inlines reasoning there. Many providers
+ * return an empty string instead of omitting the field — treated the same as
+ * missing so callers don't emit an empty ReasoningPush.
+ *
+ * @param {unknown} llmResponse
+ * @returns {string | null}
+ */
+export function readReasoningContent(llmResponse: unknown): string | null;
+/**
+ * Drop any `<think>` / `<thinking>` / `<thought>` spans from a user-facing
+ * content string, so private chain-of-thought leaking through `message.content`
+ * does not also ship inside the ContentPush burst.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function stripReasoningTags(content: string): string;
 /**
  * @rei-standard/amsg-shared
  *
@@ -316,6 +366,8 @@ export const PUSH_SOURCE: Readonly<{
     INSTANT: "instant";
     SCHEDULED: "scheduled";
 }>;
+/** Max accepted `avatarUrl` length, in characters. */
+export const AVATAR_URL_MAX_LENGTH: 2048;
 /**
  * Fields present on every push, regardless of kind. Discriminator
  * fields (`messageKind`) and kind-specific fields live on the kind
@@ -439,24 +491,24 @@ export type ContentPush = AmsgPushCommon & {
  * out of the upstream response into its own push. Emitted **before**
  * the matching {@link ContentPush} burst when present and non-empty.
  *
- * Reasoning carries two orthogonal "multi-part" axes, both optional —
- * they are *omitted* when the part count is 1 so the wire stays
- * byte-for-byte compatible with single-shot ReasoningPush callers:
+ * Reasoning carries two optional "multi-part" axes, both *omitted* when
+ * the part count is 1 so the wire stays byte-for-byte compatible with
+ * single-shot callers. The type reserves them for forward compatibility;
+ * current producers emit a single ReasoningPush and set neither — oversized
+ * reasoning rides the generic multipart transport, not a reasoning-only
+ * chunk format.
  *
- *   - `messageIndex` / `totalMessages` — set when a semantic
- *     splitter (`reasoningSplitPattern` in amsg-instant) has cut the
- *     reasoning into multiple sentences for typing-bubble UX.
+ *   - `messageIndex` / `totalMessages` — a 1-based part index when a producer
+ *     splits reasoning into multiple sentences for typing-bubble UX.
  *
- *   - `chunkIndex` / `totalChunks` — set when a single segment was
- *     too large for the Web Push payload limit and the producer had
- *     to slice it across multiple pushes at UTF-8 byte boundaries.
- *     Transport-only; SW reassembles the original `reasoningContent`
- *     by sorting on `chunkIndex` within a `(sessionId, messageIndex)`
- *     bucket. See `chunkReasoningByUtf8Bytes` for the safe-edge
- *     splitter helper.
+ *   - `chunkIndex` / `totalChunks` — transport-only slicing when a single
+ *     segment exceeds the Web Push payload limit; SW would reassemble the
+ *     original `reasoningContent` by sorting on `chunkIndex` within a
+ *     `(sessionId, messageIndex)` bucket. See `chunkReasoningByUtf8Bytes`
+ *     for the safe-edge splitter helper.
  *
- * Both axes can coexist on the same push when a sentence-split
- * segment is itself oversized.
+ * Both axes can coexist on the same push when a sentence-split segment is
+ * itself oversized.
  */
 export type ReasoningPush = AmsgPushCommon & {
     messageKind: "reasoning";

package/dist/index.mjs

@@ -227,7 +227,71 @@ function concatBytes(...chunks) {
   }
   return out;
 }
+function isValidUrl(value) {
+  if (typeof value !== "string") return false;
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var AVATAR_URL_MAX_LENGTH = 2048;
+function validateAvatarUrl(value) {
+  if (value === void 0 || value === null) return null;
+  if (typeof value !== "string") {
+    return "avatarUrl \u5FC5\u987B\u662F\u5B57\u7B26\u4E32";
+  }
+  if (/^data:/i.test(value)) {
+    return "\u5934\u50CF\u4E0D\u652F\u6301\u4F20\u5165 data: URI\uFF0C\u8BF7\u6539\u4E3A\u516C\u7F51\u53EF\u8BBF\u95EE\u7684 https:// \u56FE\u7247 URL";
+  }
+  if (value.length > AVATAR_URL_MAX_LENGTH) {
+    return `\u5934\u50CF URL \u957F\u5EA6 ${value.length} \u5B57\u7B26\u8D85\u8FC7 ${AVATAR_URL_MAX_LENGTH} \u4E0A\u9650\uFF0C\u8BF7\u6539\u4E3A\u66F4\u77ED\u7684\u56FE\u7247 URL`;
+  }
+  if (!isValidUrl(value)) {
+    return "avatarUrl \u4E0D\u662F\u5408\u6CD5 URL";
+  }
+  return null;
+}
+function normalizeVapidSubject(email) {
+  const trimmed = String(email || "").trim();
+  if (!trimmed) return "";
+  return /^mailto:/i.test(trimmed) || /^https?:/i.test(trimmed) ? trimmed : `mailto:${trimmed}`;
+}
+var REASONING_TAG_RE = /<(think|thinking|thought)>([\s\S]*?)<\/\1>/i;
+var REASONING_TAG_RE_G = /<(think|thinking|thought)>[\s\S]*?<\/\1>/gi;
+function readReasoningContent(llmResponse) {
+  if (!llmResponse || typeof llmResponse !== "object") return null;
+  const choices = (
+    /** @type {{ choices?: unknown }} */
+    llmResponse.choices
+  );
+  if (!Array.isArray(choices) || choices.length === 0) return null;
+  const message = (
+    /** @type {{ message?: { reasoning_content?: unknown, content?: unknown } }} */
+    choices[0]?.message
+  );
+  const raw = message?.reasoning_content;
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (trimmed.length > 0) return trimmed;
+  }
+  const content = message?.content;
+  if (typeof content === "string") {
+    const match = content.match(REASONING_TAG_RE);
+    if (match) {
+      const trimmed = match[2].trim();
+      if (trimmed.length > 0) return trimmed;
+    }
+  }
+  return null;
+}
+function stripReasoningTags(content) {
+  if (typeof content !== "string" || !content.includes("<")) return content;
+  return content.replace(REASONING_TAG_RE_G, "").trim();
+}
 export {
+  AVATAR_URL_MAX_LENGTH,
   MESSAGE_KIND,
   MESSAGE_TYPE,
   PUSH_SOURCE,
@@ -242,5 +306,10 @@ export {
   isErrorPush,
   isReasoningPush,
   isToolRequestPush,
-  toUint8
+  isValidUrl,
+  normalizeVapidSubject,
+  readReasoningContent,
+  stripReasoningTags,
+  toUint8,
+  validateAvatarUrl
 };

package/package.json

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