@xmanrui/dsh-im 4.0.0 → 4.1.0

package/plugin-src/host/channels/whatsapp/index.mjs

@@ -9,13 +9,18 @@ export async function apply(ctx, config = {}) {
     return installWhatsappRpc(ctx, config.controller, config.rpcOptions, config.rpcAuthority);
   }
   const production = await createProductionController(ctx, config, config.internals ?? {});
+  const unregisterDelivery = config.deliveryService && production.deliveryAdapter
+    ? config.deliveryService.registerAdapter(production.deliveryAdapter) : undefined;
   const disposeRpc = installWhatsappRpc(
     ctx,
     production.controller,
     config.rpcOptions,
     config.rpcAuthority,
   );
-  ctx.effect(() => async () => production.close(), 'dsh-im: close WhatsApp Web connections');
+  ctx.effect(() => async () => {
+    await unregisterDelivery?.();
+    await production.close();
+  }, 'dsh-im: close WhatsApp Web connections');
   return disposeRpc;
 }
 

package/plugin-src/host/channels/whatsapp/production.mjs

@@ -15,6 +15,7 @@ import {
   observeBotWorkspaceRemovals,
 } from '../../../../src/channels/shared/bot-workspace-store.mjs';
 import { listAgentPresetCatalog } from '../../../../src/channels/shared/agent-preset.mjs';
+import { createDeliveryAdapter } from '../../delivery-adapter.mjs';
 import { createTokenConnectionSupervisor } from '../shared/connection-supervisor.mjs';
 import { createHarnessCommandExecutor } from '../../harness-command-executor.mjs';
 import { harnessConnection } from '../../harness-connection.mjs';
@@ -151,6 +152,9 @@ export async function createProductionController(ctx, config = {}, internals = {
   }).start();
   return {
     controller,
+    deliveryAdapter: createDeliveryAdapter({
+      channel: 'whatsapp', workspaces, coreController, stateFor,
+    }),
     ready: supervisor.ready,
     async close() {
       await supervisor.close();

package/plugin-src/host/delivery-adapter.mjs

@@ -0,0 +1,179 @@
+import { deliverySuggestionsFromSessions } from './delivery-suggestions.mjs';
+
+const CHANNELS = new Set([
+  'weixin',
+  'feishu',
+  'dingtalk',
+  'wecom',
+  'qq',
+  'slack',
+  'telegram',
+  'discord',
+  'whatsapp',
+]);
+
+export function supportsDeliveryChannel(channel) {
+  return CHANNELS.has(channel);
+}
+
+function invalidTarget(message) {
+  const error = new Error(message);
+  error.code = 'invalid-target';
+  return error;
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function exactKeys(value, allowed, label) {
+  if (!isRecord(value)) throw invalidTarget(`${label} must be an object`);
+  const extra = Object.keys(value).find((key) => !allowed.includes(key));
+  if (extra !== undefined) throw invalidTarget(`${label} contains an unknown field`);
+}
+
+function requiredString(value, label) {
+  if (typeof value !== 'string' || !value || value.trim() !== value) {
+    throw invalidTarget(`${label} must be a non-empty string without surrounding whitespace`);
+  }
+  return value;
+}
+
+function targetName(value) {
+  if (typeof value !== 'string' || !value.trim() || value.trim().length > 80) {
+    throw invalidTarget('target.name must contain 1 to 80 characters');
+  }
+  return value.trim();
+}
+
+function routeWithStrings(route, fields) {
+  exactKeys(route, fields, 'route');
+  const normalized = {};
+  for (const field of fields) normalized[field] = requiredString(route[field], `route.${field}`);
+  return normalized;
+}
+
+function oneOf(value, choices) {
+  if (!choices.includes(value)) throw invalidTarget('target kind is not supported by this channel');
+  return value;
+}
+
+function normalizeRoute(channel, kind, route) {
+  switch (channel) {
+    case 'weixin':
+      oneOf(kind, ['user']);
+      return routeWithStrings(route, ['toUserId']);
+    case 'feishu':
+      oneOf(kind, ['user', 'group']);
+      return routeWithStrings(route, kind === 'user' ? ['openId'] : ['chatId']);
+    case 'dingtalk':
+      oneOf(kind, ['user', 'group']);
+      return routeWithStrings(route, kind === 'user' ? ['userId'] : ['openConversationId']);
+    case 'wecom':
+      oneOf(kind, ['user', 'group']);
+      return routeWithStrings(route, ['chatId']);
+    case 'qq':
+      oneOf(kind, ['user', 'group']);
+      return routeWithStrings(route, kind === 'user' ? ['userOpenId'] : ['groupOpenId']);
+    case 'slack': {
+      oneOf(kind, ['conversation', 'thread']);
+      const normalized = routeWithStrings(
+        route,
+        kind === 'conversation' ? ['channelId'] : ['channelId', 'threadTs'],
+      );
+      return normalized;
+    }
+    case 'telegram': {
+      oneOf(kind, ['chat', 'topic']);
+      exactKeys(route, kind === 'chat' ? ['chatId'] : ['chatId', 'messageThreadId'], 'route');
+      const chatId = requiredString(route.chatId, 'route.chatId');
+      if (!/^-?\d+$/.test(chatId)) throw invalidTarget('route.chatId must be a decimal string');
+      if (kind === 'chat') return { chatId };
+      if (!Number.isSafeInteger(route.messageThreadId) || route.messageThreadId <= 0) {
+        throw invalidTarget('route.messageThreadId must be a positive integer');
+      }
+      return { chatId, messageThreadId: route.messageThreadId };
+    }
+    case 'discord':
+      oneOf(kind, ['channel']);
+      return routeWithStrings(route, ['channelId']);
+    case 'whatsapp': {
+      oneOf(kind, ['user', 'group']);
+      const normalized = routeWithStrings(route, ['jid']);
+      const valid = kind === 'user'
+        ? /^\d{5,32}@(s\.whatsapp\.net|lid)$/.test(normalized.jid)
+        : /^\d{5,32}(?:-\d{1,32})?@g\.us$/.test(normalized.jid);
+      if (!valid) {
+        throw invalidTarget(`route.jid must be a ${kind} WhatsApp JID`);
+      }
+      return normalized;
+    }
+    default:
+      throw new TypeError(`Unsupported delivery channel: ${channel}`);
+  }
+}
+
+/** Strictly validate and copy one channel delivery target. */
+export function normalizeDeliveryTarget(channel, value, { targetIdRequired = true } = {}) {
+  if (!supportsDeliveryChannel(channel)) throw new TypeError(`Unsupported delivery channel: ${channel}`);
+  exactKeys(
+    value,
+    targetIdRequired ? ['targetId', 'name', 'kind', 'route'] : ['name', 'kind', 'route'],
+    'target',
+  );
+  const normalized = {};
+  if (targetIdRequired) normalized.targetId = requiredString(value.targetId, 'target.targetId');
+  if (value.name !== undefined) normalized.name = targetName(value.name);
+  normalized.kind = requiredString(value.kind, 'target.kind');
+  normalized.route = normalizeRoute(channel, normalized.kind, value.route);
+  return normalized;
+}
+
+/** Bind one channel's existing workspace store and unwrapped controller to DeliveryService. */
+export function createDeliveryAdapter({ channel, workspaces, coreController, stateFor }) {
+  if (!supportsDeliveryChannel(channel)) throw new TypeError(`Unsupported delivery channel: ${channel}`);
+  if (!workspaces || typeof workspaces !== 'object') {
+    throw new TypeError('delivery adapter requires a workspace store');
+  }
+  if (!coreController || typeof coreController !== 'object') {
+    throw new TypeError('delivery adapter requires a proactive text controller');
+  }
+  if (typeof stateFor !== 'function') {
+    throw new TypeError('delivery adapter requires a bot state getter');
+  }
+  return Object.freeze({
+    channel,
+    ownsBot: (botId) => workspaces.has(botId),
+    listTargets: (botId) => workspaces.listDeliveryTargets(botId),
+    async listSuggestions(botId) {
+      const state = await stateFor(botId);
+      if (!state || typeof state.snapshot !== 'function') {
+        throw new TypeError('delivery suggestion state cannot be inspected');
+      }
+      const suggestions = deliverySuggestionsFromSessions(channel, state.snapshot()?.sessions);
+      return suggestions.map((suggestion) => normalizeDeliveryTarget(
+        channel,
+        suggestion,
+        { targetIdRequired: false },
+      ));
+    },
+    createTarget: (botId, target) => workspaces.createDeliveryTarget(
+      botId,
+      normalizeDeliveryTarget(channel, target),
+    ),
+    updateTarget: (botId, targetId, replacement) => workspaces.updateDeliveryTarget(
+      botId,
+      targetId,
+      normalizeDeliveryTarget(channel, replacement, { targetIdRequired: false }),
+    ),
+    deleteTarget: (botId, targetId) => workspaces.deleteDeliveryTarget(botId, targetId),
+    async sendText(botId, target, text, options = {}) {
+      const normalized = normalizeDeliveryTarget(channel, target);
+      if (typeof coreController.sendProactiveText !== 'function') {
+        throw new TypeError('delivery controller cannot send proactive text');
+      }
+      await coreController.sendProactiveText(botId, normalized, text, options);
+      return { sent: true };
+    },
+  });
+}

package/plugin-src/host/delivery-http.mjs

@@ -0,0 +1,132 @@
+import { createDeliveryRpcHandler, DELIVERY_ENDPOINTS } from './delivery-rpc.mjs';
+
+export const DELIVERY_HTTP_PATH = '/api/dsh-im/delivery/messages';
+
+const MAX_BODY_BYTES = 1024 * 1024;
+
+const DELIVERY_ERROR_STATUS = Object.freeze({
+  'bad-request': 400,
+  'unknown-bot': 404,
+  'unknown-target': 404,
+  'target-conflict': 409,
+  'invalid-target': 422,
+  'bot-not-connected': 503,
+  'target-rejected': 422,
+  'delivery-failed': 502,
+  cancelled: 408,
+});
+
+class HttpRequestError extends Error {
+  constructor(status, code) {
+    super(code);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+function json(response, status, value, headers = {}) {
+  if (response.destroyed || response.writableEnded) return;
+  const body = JSON.stringify(value);
+  response.writeHead(status, {
+    'cache-control': 'no-store',
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': String(Buffer.byteLength(body)),
+    ...headers,
+  });
+  response.end(body);
+}
+
+function isJsonContentType(value) {
+  return typeof value === 'string'
+    && value.split(';', 1)[0].trim().toLowerCase() === 'application/json';
+}
+
+async function readJsonBody(request) {
+  const declaredLength = Number(request.headers['content-length']);
+  if (Number.isFinite(declaredLength) && declaredLength > MAX_BODY_BYTES) {
+    throw new HttpRequestError(413, 'payload-too-large');
+  }
+
+  const chunks = [];
+  let length = 0;
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    length += buffer.length;
+    if (length > MAX_BODY_BYTES) {
+      throw new HttpRequestError(413, 'payload-too-large');
+    }
+    chunks.push(buffer);
+  }
+
+  try {
+    return JSON.parse(Buffer.concat(chunks, length).toString('utf8'));
+  } catch {
+    throw new HttpRequestError(400, 'bad-request');
+  }
+}
+
+export function createDeliveryHttpHandler(service) {
+  const dispatch = createDeliveryRpcHandler(service);
+  return async (request, response) => {
+    if (request.method !== 'POST') {
+      json(response, 405, {
+        error: { code: 'method-not-allowed', message: 'method-not-allowed', details: {} },
+      }, { allow: 'POST' });
+      return;
+    }
+    if (!isJsonContentType(request.headers['content-type'])) {
+      json(response, 415, {
+        error: { code: 'unsupported-media-type', message: 'unsupported-media-type', details: {} },
+      });
+      return;
+    }
+
+    const abort = new AbortController();
+    const cancel = () => abort.abort();
+    const cancelClosedResponse = () => {
+      if (!response.writableEnded) cancel();
+    };
+    request.once('aborted', cancel);
+    response.once('close', cancelClosedResponse);
+    try {
+      const payload = await readJsonBody(request);
+      const result = await dispatch(DELIVERY_ENDPOINTS.send, payload, abort.signal);
+      if (result.ok) {
+        json(response, 200, result.value);
+        return;
+      }
+      json(response, DELIVERY_ERROR_STATUS[result.error.code] ?? 500, {
+        error: result.error,
+      });
+    } catch (error) {
+      if (error instanceof HttpRequestError) {
+        json(response, error.status, {
+          error: { code: error.code, message: error.code, details: {} },
+        });
+        return;
+      }
+      json(response, 500, {
+        error: { code: 'delivery-failed', message: 'delivery-failed', details: {} },
+      });
+    } finally {
+      request.off('aborted', cancel);
+      response.off('close', cancelClosedResponse);
+    }
+  };
+}
+
+export function installDeliveryHttp(ctx, service) {
+  if (!ctx?.webServer || typeof ctx.webServer.register !== 'function'
+    || typeof ctx.effect !== 'function') {
+    throw new TypeError('DSH Host WebServer is required');
+  }
+  const route = {
+    kind: 'exact',
+    path: DELIVERY_HTTP_PATH,
+    handler: createDeliveryHttpHandler(service),
+  };
+  return ctx.effect(
+    () => ctx.webServer.register(route),
+    `dsh-im: ${DELIVERY_HTTP_PATH}`,
+  );
+}

package/plugin-src/host/delivery-rpc.mjs

@@ -0,0 +1,158 @@
+import { resolveRpcAuthority } from './rpc-authority.mjs';
+
+export const DELIVERY_RPC_CHANNEL = '/dsh-im-delivery';
+export const DELIVERY_TEST_MESSAGE = 'DSH-IM 主动投递测试成功。';
+export const DELIVERY_ENDPOINTS = Object.freeze({
+  send: 'message.send',
+  listTargets: 'target.list',
+  listSuggestions: 'target.suggestion.list',
+  createTarget: 'target.create',
+  updateTarget: 'target.update',
+  deleteTarget: 'target.delete',
+  testTarget: 'target.test',
+});
+
+const ENDPOINTS = new Set(Object.values(DELIVERY_ENDPOINTS));
+const PUBLIC_ERRORS = new Set([
+  'bad-request',
+  'unknown-bot',
+  'unknown-target',
+  'target-conflict',
+  'invalid-target',
+  'bot-not-connected',
+  'target-rejected',
+  'delivery-failed',
+  'cancelled',
+]);
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function exactKeys(value, keys) {
+  return isRecord(value)
+    && Object.keys(value).length === keys.length
+    && Object.keys(value).every((key) => keys.includes(key));
+}
+
+function validBotId(value) {
+  return typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(value);
+}
+
+function validTargetId(value) {
+  return typeof value === 'string' && /^[A-Za-z0-9._:@-]{1,128}$/.test(value);
+}
+
+function validTarget(value, { targetId }) {
+  const keys = targetId ? ['targetId', 'name', 'kind', 'route'] : ['name', 'kind', 'route'];
+  if (!isRecord(value) || Object.keys(value).some((key) => !keys.includes(key))) return false;
+  if (targetId && !validTargetId(value.targetId)) return false;
+  if (value.name !== undefined
+    && (typeof value.name !== 'string' || !value.name.trim() || value.name.trim().length > 80)) return false;
+  return typeof value.kind === 'string' && /^[a-z][a-z0-9-]{0,31}$/.test(value.kind)
+    && isRecord(value.route);
+}
+
+function validDraftTarget(value) {
+  return exactKeys(value, ['kind', 'route'])
+    && typeof value.kind === 'string' && /^[a-z][a-z0-9-]{0,31}$/.test(value.kind)
+    && isRecord(value.route);
+}
+
+function validPayload(endpoint, payload) {
+  if (!ENDPOINTS.has(endpoint) || !isRecord(payload)) return false;
+  if (endpoint === DELIVERY_ENDPOINTS.send) {
+    return exactKeys(payload, ['botId', 'targetId', 'text'])
+      && validBotId(payload.botId) && validTargetId(payload.targetId)
+      && typeof payload.text === 'string' && Boolean(payload.text.trim());
+  }
+  if (endpoint === DELIVERY_ENDPOINTS.listTargets
+    || endpoint === DELIVERY_ENDPOINTS.listSuggestions) {
+    return exactKeys(payload, ['botId']) && validBotId(payload.botId);
+  }
+  if (endpoint === DELIVERY_ENDPOINTS.createTarget) {
+    return exactKeys(payload, ['botId', 'target'])
+      && validBotId(payload.botId) && validTarget(payload.target, { targetId: true });
+  }
+  if (endpoint === DELIVERY_ENDPOINTS.updateTarget) {
+    return exactKeys(payload, ['botId', 'targetId', 'target'])
+      && validBotId(payload.botId) && validTargetId(payload.targetId)
+      && validTarget(payload.target, { targetId: false });
+  }
+  if (endpoint === DELIVERY_ENDPOINTS.testTarget) {
+    return (exactKeys(payload, ['botId', 'targetId'])
+        && validBotId(payload.botId) && validTargetId(payload.targetId))
+      || (exactKeys(payload, ['botId', 'target'])
+        && validBotId(payload.botId) && validDraftTarget(payload.target));
+  }
+  return exactKeys(payload, ['botId', 'targetId'])
+    && validBotId(payload.botId) && validTargetId(payload.targetId);
+}
+
+function publicError(error) {
+  const code = PUBLIC_ERRORS.has(error?.code) ? error.code : 'delivery-failed';
+  return { code, message: code, details: {} };
+}
+
+export function createDeliveryRpcHandler(service) {
+  for (const method of [
+    'send',
+    'listTargets',
+    'listSuggestions',
+    'createTarget',
+    'updateTarget',
+    'deleteTarget',
+  ]) {
+    if (typeof service?.[method] !== 'function') {
+      throw new TypeError(`A complete delivery service is required (${method})`);
+    }
+  }
+  return async (endpoint, payload, signal) => {
+    if (!validPayload(endpoint, payload)) {
+      return {
+        ok: false,
+        error: { code: 'bad-request', message: 'Invalid delivery request.', details: {} },
+      };
+    }
+    if (signal?.aborted) {
+      return { ok: false, error: { code: 'cancelled', message: 'cancelled', details: {} } };
+    }
+    try {
+      let value;
+      if (endpoint === DELIVERY_ENDPOINTS.send) {
+        value = await service.send(payload.botId, payload.targetId, payload.text, { signal });
+      } else if (endpoint === DELIVERY_ENDPOINTS.listTargets) {
+        value = await service.listTargets(payload.botId);
+      } else if (endpoint === DELIVERY_ENDPOINTS.listSuggestions) {
+        value = await service.listSuggestions(payload.botId);
+      } else if (endpoint === DELIVERY_ENDPOINTS.createTarget) {
+        value = await service.createTarget(payload.botId, payload.target);
+      } else if (endpoint === DELIVERY_ENDPOINTS.updateTarget) {
+        value = await service.updateTarget(payload.botId, payload.targetId, payload.target);
+      } else if (endpoint === DELIVERY_ENDPOINTS.deleteTarget) {
+        value = await service.deleteTarget(payload.botId, payload.targetId);
+      } else {
+        value = await service.send(
+          payload.botId,
+          Object.hasOwn(payload, 'target') ? payload.target : payload.targetId,
+          DELIVERY_TEST_MESSAGE,
+          { signal },
+        );
+      }
+      return { ok: true, value };
+    } catch (error) {
+      return { ok: false, error: publicError(error) };
+    }
+  };
+}
+
+export function installDeliveryRpc(ctx, service, { authority } = {}) {
+  if (!ctx?.connection?.rpc || typeof ctx.connection.rpc.handle !== 'function') {
+    throw new TypeError('DSH Host Connection RPC is required');
+  }
+  return ctx.connection.rpc.handle(
+    DELIVERY_RPC_CHANNEL,
+    createDeliveryRpcHandler(service),
+    { authority: resolveRpcAuthority(authority) },
+  );
+}