@openclaw-china/shared 0.1.0

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@openclaw-china/shared",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}

package/src/http/client.ts

@@ -0,0 +1,141 @@
+/**
+ * 通用 HTTP 客户端封装
+ *
+ * 提供带超时和错误处理的 HTTP 请求功能
+ */
+
+/**
+ * HTTP 请求选项
+ */
+export interface HttpRequestOptions {
+  /** 请求超时时间（毫秒），默认 30000 */
+  timeout?: number;
+  /** 请求头 */
+  headers?: Record<string, string>;
+}
+
+/**
+ * HTTP 错误
+ */
+export class HttpError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly body?: string
+  ) {
+    super(message);
+    this.name = "HttpError";
+  }
+}
+
+/**
+ * 超时错误
+ */
+export class TimeoutError extends Error {
+  constructor(message: string, public readonly timeoutMs: number) {
+    super(message);
+    this.name = "TimeoutError";
+  }
+}
+
+/**
+ * 发送 HTTP POST 请求
+ *
+ * @param url 请求 URL
+ * @param body 请求体
+ * @param options 请求选项
+ * @returns 响应数据
+ *
+ * @example
+ * ```ts
+ * const data = await httpPost("https://api.example.com/token", { key: "value" }, { timeout: 10000 });
+ * ```
+ */
+export async function httpPost<T = unknown>(
+  url: string,
+  body: unknown,
+  options?: HttpRequestOptions
+): Promise<T> {
+  const { timeout = 30000, headers = {} } = options ?? {};
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...headers,
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const responseBody = await response.text().catch(() => "");
+      throw new HttpError(
+        `HTTP ${response.status}: ${response.statusText}`,
+        response.status,
+        responseBody
+      );
+    }
+
+    return (await response.json()) as T;
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new TimeoutError(`Request timeout after ${timeout}ms`, timeout);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+/**
+ * 发送 HTTP GET 请求
+ *
+ * @param url 请求 URL
+ * @param options 请求选项
+ * @returns 响应数据
+ *
+ * @example
+ * ```ts
+ * const data = await httpGet("https://api.example.com/data", { timeout: 10000 });
+ * ```
+ */
+export async function httpGet<T = unknown>(
+  url: string,
+  options?: HttpRequestOptions
+): Promise<T> {
+  const { timeout = 30000, headers = {} } = options ?? {};
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      headers,
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const responseBody = await response.text().catch(() => "");
+      throw new HttpError(
+        `HTTP ${response.status}: ${response.statusText}`,
+        response.status,
+        responseBody
+      );
+    }
+
+    return (await response.json()) as T;
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new TimeoutError(`Request timeout after ${timeout}ms`, timeout);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}

package/src/http/index.ts

@@ -0,0 +1,2 @@
+export * from "./client.js";
+export * from "./retry.js";

package/src/http/retry.ts

@@ -0,0 +1,110 @@
+/**
+ * HTTP 重试策略
+ *
+ * 提供可配置的重试逻辑
+ */
+
+/**
+ * 重试选项
+ */
+export interface RetryOptions {
+  /** 最大重试次数，默认 3 */
+  maxRetries?: number;
+  /** 初始延迟时间（毫秒），默认 1000 */
+  initialDelay?: number;
+  /** 最大延迟时间（毫秒），默认 10000 */
+  maxDelay?: number;
+  /** 延迟倍数（指数退避），默认 2 */
+  backoffMultiplier?: number;
+  /** 判断是否应该重试的函数 */
+  shouldRetry?: (error: unknown, attempt: number) => boolean;
+}
+
+/**
+ * 默认的重试判断函数
+ * 对于网络错误和 5xx 错误进行重试
+ */
+export function defaultShouldRetry(error: unknown): boolean {
+  if (error instanceof Error) {
+    // 网络错误
+    if (error.name === "TypeError" || error.name === "TimeoutError") {
+      return true;
+    }
+    // HTTP 5xx 错误
+    if ("status" in error && typeof (error as { status: number }).status === "number") {
+      const status = (error as { status: number }).status;
+      return status >= 500 && status < 600;
+    }
+  }
+  return false;
+}
+
+/**
+ * 计算延迟时间（指数退避）
+ */
+function calculateDelay(
+  attempt: number,
+  initialDelay: number,
+  maxDelay: number,
+  backoffMultiplier: number
+): number {
+  const delay = initialDelay * Math.pow(backoffMultiplier, attempt - 1);
+  return Math.min(delay, maxDelay);
+}
+
+/**
+ * 延迟执行
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * 带重试的异步函数执行器
+ *
+ * @param fn 要执行的异步函数
+ * @param options 重试选项
+ * @returns 函数执行结果
+ *
+ * @example
+ * ```ts
+ * const result = await withRetry(
+ *   () => httpPost(url, body),
+ *   { maxRetries: 3, initialDelay: 1000 }
+ * );
+ * ```
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options?: RetryOptions
+): Promise<T> {
+  const {
+    maxRetries = 3,
+    initialDelay = 1000,
+    maxDelay = 10000,
+    backoffMultiplier = 2,
+    shouldRetry = defaultShouldRetry,
+  } = options ?? {};
+
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      // 如果是最后一次尝试或不应该重试，直接抛出错误
+      if (attempt > maxRetries || !shouldRetry(error, attempt)) {
+        throw error;
+      }
+
+      // 计算延迟并等待
+      const delay = calculateDelay(attempt, initialDelay, maxDelay, backoffMultiplier);
+      await sleep(delay);
+    }
+  }
+
+  // 理论上不会到达这里，但为了类型安全
+  throw lastError;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+// @openclaw-china/shared
+// 共享工具模块
+
+export * from "./logger/index.js";
+export * from "./policy/index.js";
+export * from "./http/index.js";
+export * from "./types/common.js";

package/src/logger/index.ts

@@ -0,0 +1 @@
+export * from "./logger.js";

package/src/logger/logger.ts

@@ -0,0 +1,51 @@
+/**
+ * 通用日志工具
+ *
+ * 提供分级日志功能:
+ * - info: 关键业务日志（默认显示）
+ * - debug: 调试日志（带 [DEBUG] 标记）
+ * - error: 错误日志
+ * - warn: 警告日志
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface Logger {
+  debug: (msg: string) => void;
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+}
+
+export interface LoggerOptions {
+  log?: (msg: string) => void;
+  error?: (msg: string) => void;
+}
+
+/**
+ * 创建带前缀的日志器
+ *
+ * @param prefix 日志前缀（如 "dingtalk", "feishu"）
+ * @param opts 可选的日志输出函数
+ * @returns Logger 实例
+ *
+ * @example
+ * ```ts
+ * const logger = createLogger("dingtalk");
+ * logger.debug("connecting..."); // [dingtalk] [DEBUG] connecting...
+ * logger.info("connected");      // [dingtalk] connected
+ * logger.warn("slow response");  // [dingtalk] [WARN] slow response
+ * logger.error("failed");        // [dingtalk] [ERROR] failed
+ * ```
+ */
+export function createLogger(prefix: string, opts?: LoggerOptions): Logger {
+  const logFn = opts?.log ?? console.log;
+  const errorFn = opts?.error ?? console.error;
+
+  return {
+    debug: (msg: string) => logFn(`[${prefix}] [DEBUG] ${msg}`),
+    info: (msg: string) => logFn(`[${prefix}] ${msg}`),
+    warn: (msg: string) => logFn(`[${prefix}] [WARN] ${msg}`),
+    error: (msg: string) => errorFn(`[${prefix}] [ERROR] ${msg}`),
+  };
+}

package/src/policy/dm-policy.ts

@@ -0,0 +1,82 @@
+/**
+ * DM 策略引擎
+ *
+ * 实现 open/pairing/allowlist 策略检查
+ */
+
+/**
+ * DM 策略类型
+ * - open: 允许所有单聊消息
+ * - pairing: 配对模式（允许所有，配对逻辑由上层处理）
+ * - allowlist: 仅允许白名单中的发送者
+ */
+export type DmPolicyType = "open" | "pairing" | "allowlist";
+
+/**
+ * 策略检查结果
+ */
+export interface PolicyCheckResult {
+  /** 是否允许处理该消息 */
+  allowed: boolean;
+  /** 拒绝原因（如果被拒绝） */
+  reason?: string;
+}
+
+/**
+ * DM 策略检查参数
+ */
+export interface DmPolicyCheckParams {
+  /** DM 策略类型 */
+  dmPolicy: DmPolicyType;
+  /** 发送者 ID */
+  senderId: string;
+  /** 白名单（allowlist 策略时使用） */
+  allowFrom?: string[];
+}
+
+/**
+ * 检查单聊策略
+ *
+ * @param params 检查参数
+ * @returns 策略检查结果
+ *
+ * @example
+ * ```ts
+ * // 开放策略
+ * checkDmPolicy({ dmPolicy: "open", senderId: "user1" });
+ * // => { allowed: true }
+ *
+ * // 白名单策略
+ * checkDmPolicy({ dmPolicy: "allowlist", senderId: "user1", allowFrom: ["user1", "user2"] });
+ * // => { allowed: true }
+ *
+ * checkDmPolicy({ dmPolicy: "allowlist", senderId: "user3", allowFrom: ["user1", "user2"] });
+ * // => { allowed: false, reason: "sender user3 not in DM allowlist" }
+ * ```
+ */
+export function checkDmPolicy(params: DmPolicyCheckParams): PolicyCheckResult {
+  const { dmPolicy, senderId, allowFrom = [] } = params;
+
+  switch (dmPolicy) {
+    case "open":
+      // 开放策略：允许所有单聊消息
+      return { allowed: true };
+
+    case "pairing":
+      // 配对策略：允许所有单聊消息（配对逻辑由上层处理）
+      return { allowed: true };
+
+    case "allowlist":
+      // 白名单策略：仅允许 allowFrom 中的发送者
+      if (allowFrom.includes(senderId)) {
+        return { allowed: true };
+      }
+      return {
+        allowed: false,
+        reason: `sender ${senderId} not in DM allowlist`,
+      };
+
+    default:
+      return { allowed: true };
+  }
+}

package/src/policy/group-policy.ts

@@ -0,0 +1,93 @@
+/**
+ * 群组策略引擎
+ *
+ * 实现 open/allowlist/disabled 策略检查
+ */
+
+import type { PolicyCheckResult } from "./dm-policy.js";
+
+/**
+ * 群组策略类型
+ * - open: 允许所有群聊消息
+ * - allowlist: 仅允许白名单中的群组
+ * - disabled: 禁用所有群聊消息
+ */
+export type GroupPolicyType = "open" | "allowlist" | "disabled";
+
+/**
+ * 群组策略检查参数
+ */
+export interface GroupPolicyCheckParams {
+  /** 群组策略类型 */
+  groupPolicy: GroupPolicyType;
+  /** 会话 ID（群组 ID） */
+  conversationId: string;
+  /** 群组白名单（allowlist 策略时使用） */
+  groupAllowFrom?: string[];
+  /** 是否要求 @提及机器人 */
+  requireMention: boolean;
+  /** 是否 @提及了机器人 */
+  mentionedBot: boolean;
+}
+
+/**
+ * 检查群聊策略
+ *
+ * @param params 检查参数
+ * @returns 策略检查结果
+ *
+ * @example
+ * ```ts
+ * // 禁用策略
+ * checkGroupPolicy({ groupPolicy: "disabled", conversationId: "g1", requireMention: false, mentionedBot: false });
+ * // => { allowed: false, reason: "group messages disabled" }
+ *
+ * // 开放策略 + 要求 @提及
+ * checkGroupPolicy({ groupPolicy: "open", conversationId: "g1", requireMention: true, mentionedBot: false });
+ * // => { allowed: false, reason: "message did not mention bot" }
+ *
+ * // 白名单策略
+ * checkGroupPolicy({ groupPolicy: "allowlist", conversationId: "g1", groupAllowFrom: ["g1"], requireMention: false, mentionedBot: false });
+ * // => { allowed: true }
+ * ```
+ */
+export function checkGroupPolicy(params: GroupPolicyCheckParams): PolicyCheckResult {
+  const { groupPolicy, conversationId, groupAllowFrom = [], requireMention, mentionedBot } = params;
+
+  // 首先检查群聊策略
+  switch (groupPolicy) {
+    case "disabled":
+      // 禁用策略：拒绝所有群聊消息
+      return {
+        allowed: false,
+        reason: "group messages disabled",
+      };
+
+    case "allowlist":
+      // 白名单策略：仅允许 groupAllowFrom 中的群组
+      if (!groupAllowFrom.includes(conversationId)) {
+        return {
+          allowed: false,
+          reason: `group ${conversationId} not in allowlist`,
+        };
+      }
+      break;
+
+    case "open":
+      // 开放策略：允许所有群聊
+      break;
+
+    default:
+      break;
+  }
+
+  // 然后检查 @提及要求
+  if (requireMention && !mentionedBot) {
+    return {
+      allowed: false,
+      reason: "message did not mention bot",
+    };
+  }
+
+  return { allowed: true };
+}

package/src/policy/index.ts

@@ -0,0 +1,2 @@
+export * from "./dm-policy.js";
+export * from "./group-policy.js";

package/src/types/common.ts

@@ -0,0 +1,24 @@
+// 共享类型定义
+
+export type DmPolicy = "open" | "pairing" | "allowlist";
+export type GroupPolicy = "open" | "allowlist" | "disabled";
+
+export interface ParsedMessage {
+  chatId: string;
+  messageId: string;
+  senderId: string;
+  senderName?: string;
+  chatType: "direct" | "group";
+  content: string;
+  contentType: string;
+  mentionedBot: boolean;
+  replyToMessageId?: string;
+  timestamp: number;
+}
+
+export interface HistoryEntry {
+  sender: string;
+  body: string;
+  timestamp: number;
+  messageId: string;
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}