@rei-standard/amsg-server 2.1.1 → 2.3.1

package/dist/index.d.ts

@@ -101,6 +101,112 @@ function isValidUUIDv4(uuid) {
   return uuidV4Regex.test(uuid);
 }
 
+const VALID_LLM_MESSAGE_ROLES = new Set(['system', 'user', 'assistant', 'tool']);
+
+const AVATAR_URL_MAX_LENGTH = 2048;
+
+/**
+ * Validate the optional `avatarUrl` field. Rejects `data:` URIs (typically
+ * base64-encoded inline images) and anything longer than 2048 chars, both
+ * of which are the dominant trigger for downstream 413 / Web Push 4 KB
+ * payload errors. Returns an error message string, or null when valid.
+ *
+ * Mirrors @rei-standard/amsg-instant's `validateAvatarUrl` (kept in lockstep
+ * on purpose — both packages forward `avatarUrl` to the same SW push payload).
+ *
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+function validateAvatarUrl(value) {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== 'string') {
+    return 'avatarUrl 必须是字符串';
+  }
+  if (/^data:/i.test(value)) {
+    return '头像不支持传入 data: URI，请改为公网可访问的 https:// 图片 URL';
+  }
+  if (value.length > AVATAR_URL_MAX_LENGTH) {
+    return `头像 URL 长度 ${value.length} 字符超过 ${AVATAR_URL_MAX_LENGTH} 上限，请改为更短的图片 URL`;
+  }
+  if (!isValidUrl(value)) {
+    return 'avatarUrl 不是合法 URL';
+  }
+  return null;
+}
+
+const SPLIT_PATTERN_MAX_LENGTH = 200;
+const SPLIT_PATTERN_MAX_ITEMS = 10;
+
+/**
+ * Validate the optional `splitPattern` field. Mirrors
+ * @rei-standard/amsg-instant's `validateSplitPattern` (kept in lockstep).
+ * Accepts `string`, `string[]`, or absent/null. Returns an error message
+ * string, or null when valid.
+ *
+ * Limits (per-item length ≤ 200, array ≤ 10 items, must compile via
+ * `new RegExp(item)`) are an **input-size guard**, NOT a ReDoS defense —
+ * a 6-character pattern like `(a+)+$` is enough to trigger catastrophic
+ * backtracking. The real backstop is Worker / runtime CPU limits + the
+ * fact that splitPattern is stored under the user's own encrypted task
+ * and matched against output from the user's own LLM API key, so the
+ * blast radius is self-inflicted only (no cross-tenant attack surface).
+ *
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+function validateSplitPattern(value) {
+  if (value === undefined || value === null) return null;
+  const isArray = Array.isArray(value);
+  const items = isArray ? value : [value];
+  if (isArray && items.length === 0) return null;          // empty array = use default
+  if (items.length > SPLIT_PATTERN_MAX_ITEMS) {
+    return `splitPattern 数组最多 ${SPLIT_PATTERN_MAX_ITEMS} 项`;
+  }
+  for (let i = 0; i < items.length; i++) {
+    const s = items[i];
+    const label = isArray ? `splitPattern[${i}]` : 'splitPattern';
+    if (typeof s !== 'string') return `${label} 必须是字符串`;
+    if (s.length > SPLIT_PATTERN_MAX_LENGTH) {
+      return `${label} 不能超过 ${SPLIT_PATTERN_MAX_LENGTH} 字符`;
+    }
+    try { new RegExp(s); }
+    catch (_) { return `${label} 不是有效正则表达式`; }
+  }
+  return null;
+}
+
+/**
+ * Validate an OpenAI-style messages array. Same shape contract as
+ * `@rei-standard/amsg-instant` (kept in lockstep on purpose — both packages
+ * end up forwarding this to the same LLM body).
+ *
+ * @param {unknown} messages
+ * @returns {string | null}   Error message, or null if valid.
+ */
+function validateLlmMessagesArray(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    return 'messages must be a non-empty array';
+  }
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    if (!m || typeof m !== 'object' || Array.isArray(m)) {
+      return `messages[${i}] must be an object`;
+    }
+    if (!VALID_LLM_MESSAGE_ROLES.has(m.role)) {
+      return `messages[${i}].role must be one of system / user / assistant / tool`;
+    }
+    if (typeof m.content === 'string') {
+      if (!m.content) return `messages[${i}].content must be a non-empty string`;
+    } else if (Array.isArray(m.content)) {
+      if (m.content.length === 0) return `messages[${i}].content array must be non-empty`;
+      // Element schema is intentionally not enforced — passed through to LLM as-is.
+    } else {
+      return `messages[${i}].content must be a non-empty string or a non-empty array`;
+    }
+  }
+  return null;
+}
+
 /**
  * Validate the schedule-message request payload.
  *
@@ -146,9 +252,40 @@ function validateScheduleMessagePayload(payload) {
     }
   }
 
+  // ─── Prompt schema (shared by prompted / auto / instant AI configs) ──
+  //
+  // Callers provide *exactly one of* `completePrompt` (string) or `messages`
+  // (OpenAI-style array). Same contract as @rei-standard/amsg-instant; the
+  // server's LLM path forwards either verbatim.
+  const promptCheck = (() => {
+    const hasCompletePrompt = payload.completePrompt !== undefined && payload.completePrompt !== null && payload.completePrompt !== '';
+    const hasMessages = payload.messages !== undefined && payload.messages !== null;
+    if (hasCompletePrompt && hasMessages) {
+      return {
+        error: { code: 'INVALID_PARAMETERS', message: 'exactly one of `completePrompt` or `messages` must be provided（两者不能同时出现）', details: { invalidFields: ['completePrompt', 'messages'] } },
+        hasCompletePrompt: true, hasMessages: true,
+      };
+    }
+    if (hasMessages) {
+      const err = validateLlmMessagesArray(payload.messages);
+      if (err) {
+        return {
+          error: { code: 'INVALID_PARAMETERS', message: err, details: { invalidFields: ['messages'] } },
+          hasCompletePrompt: false, hasMessages: true,
+        };
+      }
+    }
+    return { error: null, hasCompletePrompt, hasMessages };
+  })();
+
+  if (promptCheck.error) {
+    return { valid: false, errorCode: promptCheck.error.code, errorMessage: promptCheck.error.message, details: promptCheck.error.details };
+  }
+  const hasPrompt = promptCheck.hasCompletePrompt || promptCheck.hasMessages;
+
   if (payload.messageType === 'prompted' || payload.messageType === 'auto') {
     const missingAiFields = [];
-    if (!payload.completePrompt) missingAiFields.push('completePrompt');
+    if (!hasPrompt) missingAiFields.push('completePrompt or messages');
     if (!payload.apiUrl) missingAiFields.push('apiUrl');
     if (!payload.apiKey) missingAiFields.push('apiKey');
     if (!payload.primaryModel) missingAiFields.push('primaryModel');
@@ -161,15 +298,24 @@ function validateScheduleMessagePayload(payload) {
     if (payload.recurrenceType && payload.recurrenceType !== 'none') {
       return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: 'instant 类型的 recurrenceType 必须为 none', details: { invalidFields: ['recurrenceType (must be "none" for instant type)'] } };
     }
-    const hasAiConfig = payload.completePrompt && payload.apiUrl && payload.apiKey && payload.primaryModel;
+    const hasAiConfig = hasPrompt && payload.apiUrl && payload.apiKey && payload.primaryModel;
     const hasUserMessage = payload.userMessage;
     if (!hasAiConfig && !hasUserMessage) {
-      return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: 'instant 类型必须提供 userMessage 或完整的 AI 配置', details: { missingFields: ['userMessage or (completePrompt + apiUrl + apiKey + primaryModel)'] } };
+      return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: 'instant 类型必须提供 userMessage 或完整的 AI 配置', details: { missingFields: ['userMessage or ((completePrompt | messages) + apiUrl + apiKey + primaryModel)'] } };
     }
   }
 
-  if (payload.avatarUrl && !isValidUrl(payload.avatarUrl)) {
-    return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { invalidFields: ['avatarUrl (invalid URL format)'] } };
+  if (
+    payload.temperature !== undefined &&
+    payload.temperature !== null &&
+    (typeof payload.temperature !== 'number' || !Number.isFinite(payload.temperature))
+  ) {
+    return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { invalidFields: ['temperature (must be a finite number)'] } };
+  }
+
+  const avatarErr = validateAvatarUrl(payload.avatarUrl);
+  if (avatarErr) {
+    return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: avatarErr, details: { invalidFields: ['avatarUrl'] } };
   }
   if (payload.uuid && !isValidUUID(payload.uuid)) {
     return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { invalidFields: ['uuid (invalid UUID format)'] } };
@@ -185,6 +331,11 @@ function validateScheduleMessagePayload(payload) {
     return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { invalidFields: ['messageSubtype'] } };
   }
 
+  const splitErr = validateSplitPattern(payload.splitPattern);
+  if (splitErr) {
+    return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: splitErr, details: { invalidFields: ['splitPattern'] } };
+  }
+
   return { valid: true };
 }
 
@@ -650,6 +801,55 @@ function isUniqueViolation(error) {
  */
 
 
+const DEFAULT_SPLIT_REGEX = /([。！？!?]+)/;
+
+/**
+ * Split a single chunk by one regex; on no-match return [chunk] so a later
+ * regex in a cascade can still take a swing at it.
+ */
+function splitOnceByRegex(chunk, regex) {
+  const out = chunk
+    .split(regex)
+    .reduce((acc, part, i, arr) => {
+      if (i % 2 === 0 && part.trim()) {
+        const punctuation = arr[i + 1] || '';
+        acc.push(part.trim() + punctuation);
+      }
+      return acc;
+    }, [])
+    .filter(s => s.length > 0);
+  return out.length > 0 ? out : [chunk];
+}
+
+/**
+ * Sentence splitter — kept byte-for-byte equivalent to
+ * `@rei-standard/amsg-instant`'s `splitMessageIntoSentences`. Server carries
+ * its own copy to avoid an architectural dependency on the instant package.
+ * Name matches the instant export on purpose so cross-package grep finds
+ * both copies; if you fix a bug here, fix it in the instant copy too.
+ *
+ * @param {string} messageContent
+ * @param {string | string[] | null} [splitPattern=null]
+ * @returns {string[]}
+ */
+function splitMessageIntoSentences(messageContent, splitPattern = null) {
+  const sources =
+    splitPattern == null ? null :
+    Array.isArray(splitPattern) ? splitPattern :
+    [splitPattern];
+
+  const regexes = (sources && sources.length > 0)
+    ? sources.map(s => new RegExp(s))
+    : [DEFAULT_SPLIT_REGEX];
+
+  let chunks = [messageContent];
+  for (const regex of regexes) {
+    chunks = chunks.flatMap(c => splitOnceByRegex(c, regex));
+  }
+
+  return chunks.length > 0 ? chunks : [messageContent];
+}
+
 /**
  * @typedef {Object} ProcessorContext
  * @property {Object}  webpush           - The web-push module instance (already VAPID-configured).
@@ -681,7 +881,8 @@ async function processSingleMessage(task, ctx, providedMasterKey) {
       messageContent = decryptedPayload.userMessage;
 
     } else if (decryptedPayload.messageType === 'instant') {
-      if (decryptedPayload.completePrompt && decryptedPayload.apiUrl && decryptedPayload.apiKey && decryptedPayload.primaryModel) {
+      const hasPrompt = !!decryptedPayload.completePrompt || (Array.isArray(decryptedPayload.messages) && decryptedPayload.messages.length > 0);
+      if (hasPrompt && decryptedPayload.apiUrl && decryptedPayload.apiKey && decryptedPayload.primaryModel) {
         messageContent = await _callAI(decryptedPayload);
       } else if (decryptedPayload.userMessage) {
         messageContent = decryptedPayload.userMessage;
@@ -695,19 +896,12 @@ async function processSingleMessage(task, ctx, providedMasterKey) {
       throw new Error('Invalid message configuration: no content source available');
     }
 
-    // Sentence splitting
-    const sentences = messageContent
-      .split(/([。！？!?]+)/)
-      .reduce((acc, part, i, arr) => {
-        if (i % 2 === 0 && part.trim()) {
-          const punctuation = arr[i + 1] || '';
-          acc.push(part.trim() + punctuation);
-        }
-        return acc;
-      }, [])
-      .filter(s => s.length > 0);
-
-    const messages = sentences.length > 0 ? sentences : [messageContent];
+    // Sentence splitting (mirrors @rei-standard/amsg-instant
+    // splitMessageIntoSentences — keep in lockstep; do not drift). Caller may
+    // override the default regex via decryptedPayload.splitPattern (string
+    // for a single regex, string[] for a cascade). Validation already enforces
+    // length cap + RegExp compilability upstream.
+    const messages = splitMessageIntoSentences(messageContent, decryptedPayload.splitPattern ?? null);
 
     if (!ctx.vapid.email || !ctx.vapid.publicKey || !ctx.vapid.privateKey) {
       throw new Error('VAPID configuration missing - push notifications cannot be sent');
@@ -887,12 +1081,29 @@ async function _callAI(payload) {
  * @returns {Object}
  */
 function buildAiRequestBody(payload) {
+  // messages mode (added in v2.2.0): forward the caller's OpenAI-style array
+  // verbatim — same contract as @rei-standard/amsg-instant 0.5.0+. No auto
+  // role injection, no concatenation back to a single user message. Lets
+  // the upstream app preserve system / multi-turn context byte-for-byte
+  // across the schedule-message path.
+  const llmMessages = Array.isArray(payload.messages) && payload.messages.length > 0
+    ? payload.messages
+    : [{ role: 'user', content: payload.completePrompt }];
+
   const requestBody = {
     model: payload.primaryModel,
-    messages: [{ role: 'user', content: payload.completePrompt }],
-    temperature: 0.8
+    messages: llmMessages,
   };
 
+  // Match the instant package's behavior: only inject default temperature
+  // for the legacy completePrompt path; messages mode forwards whatever the
+  // upstream app set (or nothing) so behavior matches their main chat path.
+  if (payload.temperature !== undefined && payload.temperature !== null) {
+    requestBody.temperature = payload.temperature;
+  } else if (!Array.isArray(payload.messages)) {
+    requestBody.temperature = 0.8;
+  }
+
   if (payload.maxTokens === undefined || payload.maxTokens === null) {
     return requestBody;
   }
@@ -1052,8 +1263,17 @@ function createScheduleMessageHandler(ctx) {
       apiUrl: payload.apiUrl || null,
       apiKey: payload.apiKey || null,
       primaryModel: payload.primaryModel || null,
+      // Prompt is one-of: legacy completePrompt (string) OR messages (OpenAI-
+      // style array). Validation has already enforced exactly-one-of, so
+      // exactly one of these will be non-null when an AI config is provided.
       completePrompt: payload.completePrompt || null,
+      messages: Array.isArray(payload.messages) ? payload.messages : null,
       maxTokens: payload.maxTokens ?? null,
+      temperature: payload.temperature ?? null,
+      // 0.6.0+: optional caller-provided regex (string or string[]) used by
+      // the message processor to chunk LLM output into individual pushes.
+      // null → processor falls back to the default /([。！？!?]+)/ regex.
+      splitPattern: payload.splitPattern ?? null,
       pushSubscription: payload.pushSubscription,
       metadata: payload.metadata || {}
     };
@@ -1450,6 +1670,42 @@ function createUpdateMessageHandler(ctx) {
       return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: '更新数据格式错误', details: { invalidFields: ['maxTokens'] } } } };
     }
 
+    // Reject updates that try to set both completePrompt and messages at
+    // once. We don't enforce one-of-required here (callers may patch other
+    // fields), but the two prompt sources are mutually exclusive and must
+    // stay that way in storage too.
+    if (
+      updates.completePrompt &&
+      updates.messages !== undefined && updates.messages !== null
+    ) {
+      return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: 'completePrompt 与 messages 不能同时更新（二选一）', details: { invalidFields: ['completePrompt', 'messages'] } } } };
+    }
+    if (updates.messages !== undefined && updates.messages !== null) {
+      const msgErr = validateLlmMessagesArray(updates.messages);
+      if (msgErr) {
+        return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: msgErr, details: { invalidFields: ['messages'] } } } };
+      }
+    }
+    if (
+      Object.prototype.hasOwnProperty.call(updates, 'temperature') &&
+      updates.temperature !== null &&
+      (typeof updates.temperature !== 'number' || !Number.isFinite(updates.temperature))
+    ) {
+      return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: '更新数据格式错误', details: { invalidFields: ['temperature'] } } } };
+    }
+    if (Object.prototype.hasOwnProperty.call(updates, 'splitPattern')) {
+      const splitErr = validateSplitPattern(updates.splitPattern);
+      if (splitErr) {
+        return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: splitErr, details: { invalidFields: ['splitPattern'] } } } };
+      }
+    }
+    if (Object.prototype.hasOwnProperty.call(updates, 'avatarUrl')) {
+      const avatarErr = validateAvatarUrl(updates.avatarUrl);
+      if (avatarErr) {
+        return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: avatarErr, details: { invalidFields: ['avatarUrl'] } } } };
+      }
+    }
+
     // Fetch existing task
     const existingTask = await db.getTaskByUuid(taskUuid, userId);
 
@@ -1463,14 +1719,31 @@ function createUpdateMessageHandler(ctx) {
 
     const existingData = JSON.parse(decryptFromStorage(existingTask.encrypted_payload, userKey));
 
+    // When the caller switches prompt source (completePrompt ↔ messages),
+    // null out the other so storage stays one-of (matches schedule-message
+    // shape and prevents buildAiRequestBody from accidentally seeing both).
+    const promptUpdates = {};
+    if (updates.completePrompt) {
+      promptUpdates.completePrompt = updates.completePrompt;
+      promptUpdates.messages = null;
+    } else if (updates.messages !== undefined && updates.messages !== null) {
+      promptUpdates.messages = updates.messages;
+      promptUpdates.completePrompt = null;
+    }
+
     const updatedData = {
       ...existingData,
-      ...(updates.completePrompt && { completePrompt: updates.completePrompt }),
+      ...promptUpdates,
       ...(updates.userMessage && { userMessage: updates.userMessage }),
       ...(updates.recurrenceType && { recurrenceType: updates.recurrenceType }),
       ...(updates.avatarUrl && { avatarUrl: updates.avatarUrl }),
       ...(updates.metadata && { metadata: updates.metadata }),
-      ...(Object.prototype.hasOwnProperty.call(updates, 'maxTokens') && { maxTokens: updates.maxTokens ?? null })
+      ...(Object.prototype.hasOwnProperty.call(updates, 'maxTokens') && { maxTokens: updates.maxTokens ?? null }),
+      ...(Object.prototype.hasOwnProperty.call(updates, 'temperature') && { temperature: updates.temperature ?? null }),
+      // splitPattern: hasOwnProperty so that explicit `null` (= revert to
+      // default) doesn't get swallowed by truthy-spread the way the optional
+      // string fields above are.
+      ...(Object.prototype.hasOwnProperty.call(updates, 'splitPattern') && { splitPattern: updates.splitPattern ?? null })
     };
 
     const encryptedPayload = encryptForStorage(JSON.stringify(updatedData), userKey);
@@ -2204,4 +2477,4 @@ async function createReiServer(config) {
   };
 }
 
-export { createAdapter, createReiServer, createTenantToken, decryptFromStorage, decryptPayload, deriveUserEncryptionKey, encryptForStorage, isValidISO8601, isValidUUID, isValidUUIDv4, isValidUrl, validateScheduleMessagePayload, verifyTenantToken };
+export { createAdapter, createReiServer, createTenantToken, decryptFromStorage, decryptPayload, deriveUserEncryptionKey, encryptForStorage, isValidISO8601, isValidUUID, isValidUUIDv4, isValidUrl, validateAvatarUrl, validateLlmMessagesArray, validateScheduleMessagePayload, validateSplitPattern, verifyTenantToken };