@nextclaw/channel-plugin-feishu 0.2.14 → 0.2.15

package/src/nextclaw-sdk/core-pairing.ts

@@ -0,0 +1,224 @@
+import { normalizeAccountId } from "./account-id.js";
+import type { LogFn, PluginRuntime } from "./types.js";
+
+export const PAIRING_APPROVED_MESSAGE =
+  "NextClaw access approved. Send a message to start chatting.";
+
+const NEXTCLAW_DOCS_ROOT = "https://docs.nextclaw.io";
+
+export function buildAgentMediaPayload(
+  mediaList: Array<{ path: string; contentType?: string | null }>,
+): {
+  MediaPath?: string;
+  MediaType?: string;
+  MediaUrl?: string;
+  MediaPaths?: string[];
+  MediaUrls?: string[];
+  MediaTypes?: string[];
+} {
+  const first = mediaList[0];
+  const mediaPaths = mediaList.map((media) => media.path);
+  const mediaTypes = mediaList.map((media) => media.contentType).filter(Boolean) as string[];
+  return {
+    MediaPath: first?.path,
+    MediaType: first?.contentType ?? undefined,
+    MediaUrl: first?.path,
+    MediaPaths: mediaPaths.length > 0 ? mediaPaths : undefined,
+    MediaUrls: mediaPaths.length > 0 ? mediaPaths : undefined,
+    MediaTypes: mediaTypes.length > 0 ? mediaTypes : undefined,
+  };
+}
+
+export function formatDocsLink(path: string, label?: string): string {
+  const trimmed = path.trim();
+  const url = trimmed.startsWith("http")
+    ? trimmed
+    : `${NEXTCLAW_DOCS_ROOT}${trimmed.startsWith("/") ? trimmed : `/${trimmed}`}`;
+  return label ? `${label} (${url})` : url;
+}
+
+function buildPairingReply(params: {
+  channel: string;
+  idLine: string;
+  code: string;
+}): string {
+  return [
+    "NextClaw: access not configured.",
+    "",
+    params.idLine,
+    "",
+    `Pairing code: ${params.code}`,
+    "",
+    "Ask the bot owner to approve with:",
+    `nextclaw pairing approve ${params.channel} ${params.code}`,
+  ].join("\n");
+}
+
+export async function issuePairingChallenge(params: {
+  channel: string;
+  senderId: string;
+  senderIdLine: string;
+  meta?: Record<string, string | undefined>;
+  upsertPairingRequest: (params: {
+    id: string;
+    meta?: Record<string, string | undefined>;
+  }) => Promise<{ code: string; created: boolean }>;
+  sendPairingReply: (text: string) => Promise<void>;
+  buildReplyText?: (params: { code: string; senderIdLine: string }) => string;
+  onCreated?: (params: { code: string }) => void;
+  onReplyError?: (err: unknown) => void;
+}): Promise<{ created: boolean; code?: string }> {
+  const { code, created } = await params.upsertPairingRequest({
+    id: params.senderId,
+    meta: params.meta,
+  });
+  if (!created) {
+    return { created: false };
+  }
+  params.onCreated?.({ code });
+  const replyText =
+    params.buildReplyText?.({ code, senderIdLine: params.senderIdLine }) ??
+    buildPairingReply({
+      channel: params.channel,
+      idLine: params.senderIdLine,
+      code,
+    });
+  try {
+    await params.sendPairingReply(replyText);
+  } catch (error) {
+    params.onReplyError?.(error);
+  }
+  return { created: true, code };
+}
+
+export function createScopedPairingAccess(params: {
+  core: PluginRuntime;
+  channel: string;
+  accountId: string;
+}) {
+  const accountId = normalizeAccountId(params.accountId);
+  return {
+    accountId,
+    readAllowFromStore: () =>
+      params.core.channel.pairing.readAllowFromStore({
+        channel: params.channel,
+        accountId,
+      }),
+    readStoreForDmPolicy: (provider: string, providerAccountId: string) =>
+      params.core.channel.pairing.readAllowFromStore({
+        channel: provider,
+        accountId: normalizeAccountId(providerAccountId),
+      }),
+    upsertPairingRequest: (input: {
+      id: string;
+      meta?: Record<string, string | undefined>;
+    }) =>
+      params.core.channel.pairing.upsertPairingRequest({
+        channel: params.channel,
+        accountId,
+        ...input,
+      }),
+  };
+}
+
+export function createReplyPrefixContext() {
+  const prefixContext: Record<string, unknown> = {};
+  return {
+    prefixContext,
+    responsePrefix: undefined as string | undefined,
+    enableSlackInteractiveReplies: undefined as boolean | undefined,
+    responsePrefixContextProvider: () => prefixContext,
+    onModelSelected: (_ctx: Record<string, unknown>) => {},
+  };
+}
+
+export function logTypingFailure(params: {
+  log: LogFn;
+  channel: string;
+  target?: string;
+  action?: "start" | "stop";
+  error: unknown;
+}): void {
+  const target = params.target ? ` target=${params.target}` : "";
+  const action = params.action ? ` action=${params.action}` : "";
+  params.log(`${params.channel} typing${action} failed${target}: ${String(params.error)}`);
+}
+
+export function createTypingCallbacks(params: {
+  start: () => Promise<void>;
+  stop?: () => Promise<void>;
+  onStartError: (err: unknown) => void;
+  onStopError?: (err: unknown) => void;
+  keepaliveIntervalMs?: number;
+  maxConsecutiveFailures?: number;
+  maxDurationMs?: number;
+}) {
+  const keepaliveIntervalMs = params.keepaliveIntervalMs ?? 3_000;
+  const maxConsecutiveFailures = Math.max(1, params.maxConsecutiveFailures ?? 2);
+  const maxDurationMs = params.maxDurationMs ?? 60_000;
+  let interval: ReturnType<typeof setInterval> | undefined;
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  let closed = false;
+  let stopSent = false;
+  let consecutiveFailures = 0;
+
+  const cleanupTimers = () => {
+    if (interval) {
+      clearInterval(interval);
+      interval = undefined;
+    }
+    if (timeout) {
+      clearTimeout(timeout);
+      timeout = undefined;
+    }
+  };
+
+  const fireStop = () => {
+    cleanupTimers();
+    closed = true;
+    if (!params.stop || stopSent) {
+      return;
+    }
+    stopSent = true;
+    void params.stop().catch((error) => (params.onStopError ?? params.onStartError)(error));
+  };
+
+  const fireStart = async () => {
+    if (closed) {
+      return;
+    }
+    try {
+      await params.start();
+      consecutiveFailures = 0;
+    } catch (error) {
+      consecutiveFailures += 1;
+      params.onStartError(error);
+      if (consecutiveFailures >= maxConsecutiveFailures) {
+        fireStop();
+      }
+    }
+  };
+
+  return {
+    onReplyStart: async () => {
+      closed = false;
+      stopSent = false;
+      consecutiveFailures = 0;
+      cleanupTimers();
+      await fireStart();
+      if (closed) {
+        return;
+      }
+      interval = setInterval(() => {
+        void fireStart();
+      }, keepaliveIntervalMs);
+      if (maxDurationMs > 0) {
+        timeout = setTimeout(() => {
+          fireStop();
+        }, maxDurationMs);
+      }
+    },
+    onIdle: fireStop,
+    onCleanup: fireStop,
+  };
+}

package/src/nextclaw-sdk/core.ts

@@ -0,0 +1,26 @@
+export { DEFAULT_ACCOUNT_ID, normalizeAccountId, normalizeAgentId, normalizeOptionalAccountId } from "./account-id.js";
+export {
+  collectAllowlistProviderRestrictSendersWarnings,
+  createDefaultChannelRuntimeState,
+  emptyPluginConfigSchema,
+  evaluateSenderGroupAccessForPolicy,
+  formatAllowFromLowercase,
+  listDirectoryGroupEntriesFromMapKeysAndAllowFrom,
+  listDirectoryUserEntriesFromAllowFromAndMapKeys,
+  mapAllowFromEntries,
+  resolveDefaultGroupPolicy,
+  resolveOpenProviderRuntimeGroupPolicy,
+  warnMissingProviderGroupPolicyFallbackOnce,
+  buildProbeChannelStatusSummary,
+  buildRuntimeAccountStatusSnapshot,
+} from "./core-channel.js";
+export {
+  buildAgentMediaPayload,
+  createReplyPrefixContext,
+  createScopedPairingAccess,
+  createTypingCallbacks,
+  formatDocsLink,
+  issuePairingChallenge,
+  logTypingFailure,
+  PAIRING_APPROVED_MESSAGE,
+} from "./core-pairing.js";

package/src/nextclaw-sdk/dedupe.ts

@@ -0,0 +1,246 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function pruneMapToMaxSize<K, V>(map: Map<K, V>, maxSize: number): void {
+  while (map.size > maxSize) {
+    const firstKey = map.keys().next().value;
+    if (firstKey === undefined) {
+      break;
+    }
+    map.delete(firstKey);
+  }
+}
+
+export function createDedupeCache(options: {
+  ttlMs: number;
+  maxSize: number;
+}): {
+  check: (key: string | undefined | null, now?: number) => boolean;
+  peek: (key: string | undefined | null, now?: number) => boolean;
+  delete: (key: string | undefined | null) => void;
+  clear: () => void;
+  size: () => number;
+} {
+  const ttlMs = Math.max(0, options.ttlMs);
+  const maxSize = Math.max(0, Math.floor(options.maxSize));
+  const cache = new Map<string, number>();
+
+  const touch = (key: string, now: number) => {
+    cache.delete(key);
+    cache.set(key, now);
+  };
+
+  const prune = (now: number) => {
+    const cutoff = ttlMs > 0 ? now - ttlMs : undefined;
+    if (cutoff !== undefined) {
+      for (const [key, seenAt] of cache) {
+        if (seenAt < cutoff) {
+          cache.delete(key);
+        }
+      }
+    }
+    if (maxSize <= 0) {
+      cache.clear();
+      return;
+    }
+    pruneMapToMaxSize(cache, maxSize);
+  };
+
+  const hasUnexpired = (key: string, now: number, touchOnRead: boolean): boolean => {
+    const seenAt = cache.get(key);
+    if (seenAt === undefined) {
+      return false;
+    }
+    if (ttlMs > 0 && now - seenAt >= ttlMs) {
+      cache.delete(key);
+      return false;
+    }
+    if (touchOnRead) {
+      touch(key, now);
+    }
+    return true;
+  };
+
+  return {
+    check: (key, now = Date.now()) => {
+      if (!key) {
+        return false;
+      }
+      if (hasUnexpired(key, now, true)) {
+        return true;
+      }
+      touch(key, now);
+      prune(now);
+      return false;
+    },
+    peek: (key, now = Date.now()) => {
+      if (!key) {
+        return false;
+      }
+      return hasUnexpired(key, now, false);
+    },
+    delete: (key) => {
+      if (key) {
+        cache.delete(key);
+      }
+    },
+    clear: () => cache.clear(),
+    size: () => cache.size,
+  };
+}
+
+export async function readJsonFileWithFallback<T>(
+  filePath: string,
+  fallback: T,
+): Promise<{ value: T; exists: boolean }> {
+  try {
+    const raw = await fs.promises.readFile(filePath, "utf-8");
+    return { value: JSON.parse(raw) as T, exists: true };
+  } catch (error) {
+    const code = (error as { code?: string }).code;
+    if (code === "ENOENT") {
+      return { value: fallback, exists: false };
+    }
+    return { value: fallback, exists: false };
+  }
+}
+
+async function writeJsonFileAtomically(filePath: string, value: unknown): Promise<void> {
+  await fs.promises.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await fs.promises.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  await fs.promises.rename(tempPath, filePath);
+}
+
+export function createPersistentDedupe(options: {
+  ttlMs: number;
+  memoryMaxSize: number;
+  fileMaxEntries: number;
+  resolveFilePath: (namespace: string) => string;
+  onDiskError?: (error: unknown) => void;
+}) {
+  const ttlMs = Math.max(0, Math.floor(options.ttlMs));
+  const fileMaxEntries = Math.max(1, Math.floor(options.fileMaxEntries));
+  const memory = createDedupeCache({
+    ttlMs,
+    maxSize: Math.max(0, Math.floor(options.memoryMaxSize)),
+  });
+  const inflight = new Map<string, Promise<boolean>>();
+
+  const sanitize = (value: unknown): Record<string, number> => {
+    if (!value || typeof value !== "object") {
+      return {};
+    }
+    const out: Record<string, number> = {};
+    for (const [key, timestamp] of Object.entries(value as Record<string, unknown>)) {
+      if (typeof timestamp === "number" && Number.isFinite(timestamp) && timestamp > 0) {
+        out[key] = timestamp;
+      }
+    }
+    return out;
+  };
+
+  const pruneData = (data: Record<string, number>, now: number) => {
+    if (ttlMs > 0) {
+      for (const [key, timestamp] of Object.entries(data)) {
+        if (now - timestamp >= ttlMs) {
+          delete data[key];
+        }
+      }
+    }
+    const keys = Object.keys(data);
+    if (keys.length > fileMaxEntries) {
+      keys
+        .toSorted((left, right) => data[left] - data[right])
+        .slice(0, keys.length - fileMaxEntries)
+        .forEach((key) => {
+          delete data[key];
+        });
+    }
+  };
+
+  const checkAndRecordInner = async (
+    key: string,
+    namespace: string,
+    scopedKey: string,
+    now: number,
+    onDiskError?: (error: unknown) => void,
+  ): Promise<boolean> => {
+    if (memory.check(scopedKey, now)) {
+      return false;
+    }
+
+    const filePath = options.resolveFilePath(namespace);
+    try {
+      const { value } = await readJsonFileWithFallback<Record<string, number>>(filePath, {});
+      const data = sanitize(value);
+      const seenAt = data[key];
+      if (seenAt != null && (ttlMs <= 0 || now - seenAt < ttlMs)) {
+        return false;
+      }
+      data[key] = now;
+      pruneData(data, now);
+      await writeJsonFileAtomically(filePath, data);
+      return true;
+    } catch (error) {
+      onDiskError?.(error);
+      memory.check(scopedKey, now);
+      return true;
+    }
+  };
+
+  return {
+    async checkAndRecord(
+      key: string,
+      dedupeOptions?: {
+        namespace?: string;
+        now?: number;
+        onDiskError?: (error: unknown) => void;
+      },
+    ): Promise<boolean> {
+      const trimmed = key.trim();
+      if (!trimmed) {
+        return true;
+      }
+      const namespace = dedupeOptions?.namespace?.trim() || "global";
+      const scopedKey = `${namespace}:${trimmed}`;
+      if (inflight.has(scopedKey)) {
+        return false;
+      }
+      const work = checkAndRecordInner(
+        trimmed,
+        namespace,
+        scopedKey,
+        dedupeOptions?.now ?? Date.now(),
+        dedupeOptions?.onDiskError ?? options.onDiskError,
+      );
+      inflight.set(scopedKey, work);
+      try {
+        return await work;
+      } finally {
+        inflight.delete(scopedKey);
+      }
+    },
+    async warmup(namespace = "global", onError?: (error: unknown) => void): Promise<number> {
+      const filePath = options.resolveFilePath(namespace);
+      try {
+        const { value } = await readJsonFileWithFallback<Record<string, number>>(filePath, {});
+        const now = Date.now();
+        let loaded = 0;
+        for (const [key, timestamp] of Object.entries(sanitize(value))) {
+          if (ttlMs > 0 && now - timestamp >= ttlMs) {
+            continue;
+          }
+          memory.check(`${namespace}:${key}`, timestamp);
+          loaded += 1;
+        }
+        return loaded;
+      } catch (error) {
+        onError?.(error);
+        return 0;
+      }
+    },
+    clearMemory: () => memory.clear(),
+    memorySize: () => memory.size(),
+  };
+}

package/src/nextclaw-sdk/feishu.ts

@@ -0,0 +1,77 @@
+export type {
+  AllowlistMatch,
+  AnyAgentTool,
+  BaseProbeResult,
+  ChannelGroupContext,
+  ChannelMeta,
+  ChannelOnboardingAdapter,
+  ChannelOnboardingDmPolicy,
+  ChannelOutboundAdapter,
+  ChannelPlugin,
+  ClawdbotConfig,
+  DmPolicy,
+  GroupToolPolicyConfig,
+  HistoryEntry,
+  OpenClawConfig,
+  OpenClawPluginApi,
+  PluginRuntime,
+  ReplyPayload,
+  RuntimeEnv,
+  SecretInput,
+  WizardPrompter,
+} from "./types.js";
+export {
+  buildAgentMediaPayload,
+  buildProbeChannelStatusSummary,
+  buildRuntimeAccountStatusSnapshot,
+  collectAllowlistProviderRestrictSendersWarnings,
+  createDefaultChannelRuntimeState,
+  createReplyPrefixContext,
+  createScopedPairingAccess,
+  createTypingCallbacks,
+  emptyPluginConfigSchema,
+  evaluateSenderGroupAccessForPolicy,
+  formatAllowFromLowercase,
+  formatDocsLink,
+  issuePairingChallenge,
+  listDirectoryGroupEntriesFromMapKeysAndAllowFrom,
+  listDirectoryUserEntriesFromAllowFromAndMapKeys,
+  logTypingFailure,
+  mapAllowFromEntries,
+  PAIRING_APPROVED_MESSAGE,
+  resolveDefaultGroupPolicy,
+  resolveOpenProviderRuntimeGroupPolicy,
+  warnMissingProviderGroupPolicyFallbackOnce,
+} from "./core.js";
+export { DEFAULT_ACCOUNT_ID, normalizeAgentId } from "./account-id.js";
+export { createDedupeCache, createPersistentDedupe, readJsonFileWithFallback } from "./dedupe.js";
+export {
+  buildPendingHistoryContextFromMap,
+  clearHistoryEntriesIfEnabled,
+  DEFAULT_GROUP_HISTORY_LIMIT,
+  recordPendingHistoryEntryIfEnabled,
+} from "./history.js";
+export {
+  applyBasicWebhookRequestGuards,
+  createFixedWindowRateLimiter,
+  createWebhookAnomalyTracker,
+  fetchWithSsrFGuard,
+  installRequestBodyLimitGuard,
+  readJsonBodyWithLimit,
+  WEBHOOK_ANOMALY_COUNTER_DEFAULTS,
+  WEBHOOK_RATE_LIMIT_DEFAULTS,
+  withTempDownloadPath,
+} from "./network.js";
+export {
+  buildSecretInputSchema,
+  buildSingleChannelSecretPromptState,
+  hasConfiguredSecretInput,
+  mergeAllowFromEntries,
+  normalizeResolvedSecretInputString,
+  normalizeSecretInputString,
+  promptSingleChannelSecretInput,
+  setTopLevelChannelAllowFrom,
+  setTopLevelChannelDmPolicyWithAllowFrom,
+  setTopLevelChannelGroupPolicy,
+  splitOnboardingEntries,
+} from "./secrets.js";

package/src/nextclaw-sdk/history.ts

@@ -0,0 +1,127 @@
+import type { HistoryEntry } from "./types.js";
+
+export const HISTORY_CONTEXT_MARKER = "[Chat messages since your last reply - for context]";
+export const CURRENT_MESSAGE_MARKER = "[Current message]";
+export const DEFAULT_GROUP_HISTORY_LIMIT = 50;
+const MAX_HISTORY_KEYS = 1_000;
+
+function evictOldHistoryKeys<T>(historyMap: Map<string, T[]>, maxKeys = MAX_HISTORY_KEYS): void {
+  if (historyMap.size <= maxKeys) {
+    return;
+  }
+  const keysToDelete = historyMap.size - maxKeys;
+  const iterator = historyMap.keys();
+  for (let index = 0; index < keysToDelete; index += 1) {
+    const key = iterator.next().value;
+    if (key !== undefined) {
+      historyMap.delete(key);
+    }
+  }
+}
+
+function buildHistoryContext(params: {
+  historyText: string;
+  currentMessage: string;
+  lineBreak?: string;
+}): string {
+  const lineBreak = params.lineBreak ?? "\n";
+  if (!params.historyText.trim()) {
+    return params.currentMessage;
+  }
+  return [
+    HISTORY_CONTEXT_MARKER,
+    params.historyText,
+    "",
+    CURRENT_MESSAGE_MARKER,
+    params.currentMessage,
+  ].join(lineBreak);
+}
+
+function appendHistoryEntry<T extends HistoryEntry>(params: {
+  historyMap: Map<string, T[]>;
+  historyKey: string;
+  entry: T;
+  limit: number;
+}): T[] {
+  if (params.limit <= 0) {
+    return [];
+  }
+  const history = params.historyMap.get(params.historyKey) ?? [];
+  history.push(params.entry);
+  while (history.length > params.limit) {
+    history.shift();
+  }
+  if (params.historyMap.has(params.historyKey)) {
+    params.historyMap.delete(params.historyKey);
+  }
+  params.historyMap.set(params.historyKey, history);
+  evictOldHistoryKeys(params.historyMap);
+  return history;
+}
+
+function buildHistoryContextFromEntries(params: {
+  entries: HistoryEntry[];
+  currentMessage: string;
+  formatEntry: (entry: HistoryEntry) => string;
+  lineBreak?: string;
+  excludeLast?: boolean;
+}): string {
+  const lineBreak = params.lineBreak ?? "\n";
+  const entries = params.excludeLast === false ? params.entries : params.entries.slice(0, -1);
+  if (entries.length === 0) {
+    return params.currentMessage;
+  }
+  return buildHistoryContext({
+    historyText: entries.map(params.formatEntry).join(lineBreak),
+    currentMessage: params.currentMessage,
+    lineBreak,
+  });
+}
+
+export function recordPendingHistoryEntryIfEnabled<T extends HistoryEntry>(params: {
+  historyMap: Map<string, T[]>;
+  historyKey: string;
+  entry?: T | null;
+  limit: number;
+}): T[] {
+  if (!params.entry || params.limit <= 0) {
+    return [];
+  }
+  return appendHistoryEntry({
+    historyMap: params.historyMap,
+    historyKey: params.historyKey,
+    entry: params.entry,
+    limit: params.limit,
+  });
+}
+
+export function buildPendingHistoryContextFromMap(params: {
+  historyMap: Map<string, HistoryEntry[]>;
+  historyKey: string;
+  limit: number;
+  currentMessage: string;
+  formatEntry: (entry: HistoryEntry) => string;
+  lineBreak?: string;
+}): string {
+  if (params.limit <= 0) {
+    return params.currentMessage;
+  }
+  return buildHistoryContextFromEntries({
+    entries: params.historyMap.get(params.historyKey) ?? [],
+    currentMessage: params.currentMessage,
+    formatEntry: params.formatEntry,
+    lineBreak: params.lineBreak,
+    excludeLast: false,
+  });
+}
+
+export function clearHistoryEntriesIfEnabled(params: {
+  historyMap: Map<string, HistoryEntry[]>;
+  historyKey: string;
+  limit: number;
+}): void {
+  if (params.limit <= 0) {
+    return;
+  }
+  params.historyMap.set(params.historyKey, []);
+}