@nextclaw/channel-plugin-feishu 0.2.14 → 0.2.16

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

@@ -0,0 +1,296 @@
+import type { GroupPolicy, OpenClawConfig } from "./types.js";
+
+export function emptyPluginConfigSchema(): {
+  type: "object";
+  additionalProperties: false;
+  properties: Record<string, unknown>;
+} {
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties: {},
+  };
+}
+
+const warnedMissingProviderGroupPolicy = new Set<string>();
+
+export function resolveDefaultGroupPolicy(cfg: {
+  channels?: {
+    defaults?: {
+      groupPolicy?: GroupPolicy;
+    };
+  };
+}): GroupPolicy | undefined {
+  return cfg.channels?.defaults?.groupPolicy;
+}
+
+export function resolveOpenProviderRuntimeGroupPolicy(params: {
+  providerConfigPresent: boolean;
+  groupPolicy?: GroupPolicy;
+  defaultGroupPolicy?: GroupPolicy;
+}): {
+  groupPolicy: GroupPolicy;
+  providerMissingFallbackApplied: boolean;
+} {
+  const groupPolicy = params.providerConfigPresent
+    ? (params.groupPolicy ?? params.defaultGroupPolicy ?? "open")
+    : (params.groupPolicy ?? "allowlist");
+  return {
+    groupPolicy,
+    providerMissingFallbackApplied: !params.providerConfigPresent && params.groupPolicy === undefined,
+  };
+}
+
+export function warnMissingProviderGroupPolicyFallbackOnce(params: {
+  providerMissingFallbackApplied: boolean;
+  providerKey: string;
+  accountId?: string;
+  blockedLabel?: string;
+  log: (message: string) => void;
+}): boolean {
+  if (!params.providerMissingFallbackApplied) {
+    return false;
+  }
+  const key = `${params.providerKey}:${params.accountId ?? "*"}`;
+  if (warnedMissingProviderGroupPolicy.has(key)) {
+    return false;
+  }
+  warnedMissingProviderGroupPolicy.add(key);
+  const blockedLabel = params.blockedLabel?.trim() || "group messages";
+  params.log(
+    `${params.providerKey}: channels.${params.providerKey} is missing; defaulting groupPolicy to "allowlist" (${blockedLabel} blocked until explicitly configured).`,
+  );
+  return true;
+}
+
+export function evaluateSenderGroupAccessForPolicy(params: {
+  groupPolicy: GroupPolicy;
+  providerMissingFallbackApplied?: boolean;
+  groupAllowFrom: string[];
+  senderId: string;
+  isSenderAllowed: (senderId: string, allowFrom: string[]) => boolean;
+}): {
+  allowed: boolean;
+  groupPolicy: GroupPolicy;
+  providerMissingFallbackApplied: boolean;
+  reason: "allowed" | "disabled" | "empty_allowlist" | "sender_not_allowlisted";
+} {
+  if (params.groupPolicy === "disabled") {
+    return {
+      allowed: false,
+      groupPolicy: params.groupPolicy,
+      providerMissingFallbackApplied: Boolean(params.providerMissingFallbackApplied),
+      reason: "disabled",
+    };
+  }
+  if (params.groupPolicy === "allowlist") {
+    if (params.groupAllowFrom.length === 0) {
+      return {
+        allowed: false,
+        groupPolicy: params.groupPolicy,
+        providerMissingFallbackApplied: Boolean(params.providerMissingFallbackApplied),
+        reason: "empty_allowlist",
+      };
+    }
+    if (!params.isSenderAllowed(params.senderId, params.groupAllowFrom)) {
+      return {
+        allowed: false,
+        groupPolicy: params.groupPolicy,
+        providerMissingFallbackApplied: Boolean(params.providerMissingFallbackApplied),
+        reason: "sender_not_allowlisted",
+      };
+    }
+  }
+  return {
+    allowed: true,
+    groupPolicy: params.groupPolicy,
+    providerMissingFallbackApplied: Boolean(params.providerMissingFallbackApplied),
+    reason: "allowed",
+  };
+}
+
+export function createDefaultChannelRuntimeState<T extends Record<string, unknown>>(
+  accountId: string,
+  extra?: T,
+): {
+  accountId: string;
+  running: false;
+  lastStartAt: null;
+  lastStopAt: null;
+  lastError: null;
+} & T {
+  return {
+    accountId,
+    running: false,
+    lastStartAt: null,
+    lastStopAt: null,
+    lastError: null,
+    ...(extra ?? ({} as T)),
+  };
+}
+
+export function buildProbeChannelStatusSummary<TExtra extends Record<string, unknown>>(
+  snapshot: {
+    configured?: boolean | null;
+    running?: boolean | null;
+    lastStartAt?: number | null;
+    lastStopAt?: number | null;
+    lastError?: string | null;
+    probe?: unknown;
+    lastProbeAt?: number | null;
+  },
+  extra?: TExtra,
+) {
+  return {
+    configured: snapshot.configured ?? false,
+    running: snapshot.running ?? false,
+    lastStartAt: snapshot.lastStartAt ?? null,
+    lastStopAt: snapshot.lastStopAt ?? null,
+    lastError: snapshot.lastError ?? null,
+    ...(extra ?? ({} as TExtra)),
+    probe: snapshot.probe,
+    lastProbeAt: snapshot.lastProbeAt ?? null,
+  };
+}
+
+export function buildRuntimeAccountStatusSnapshot(params: {
+  runtime?: {
+    running?: boolean | null;
+    lastStartAt?: number | null;
+    lastStopAt?: number | null;
+    lastError?: string | null;
+  } | null;
+  probe?: unknown;
+}) {
+  return {
+    running: params.runtime?.running ?? false,
+    lastStartAt: params.runtime?.lastStartAt ?? null,
+    lastStopAt: params.runtime?.lastStopAt ?? null,
+    lastError: params.runtime?.lastError ?? null,
+    probe: params.probe,
+  };
+}
+
+export function mapAllowFromEntries(
+  allowFrom: Array<string | number> | null | undefined,
+): string[] {
+  return (allowFrom ?? []).map((entry) => String(entry));
+}
+
+export function formatAllowFromLowercase(params: {
+  allowFrom: Array<string | number>;
+  stripPrefixRe?: RegExp;
+}): string[] {
+  return params.allowFrom
+    .map((entry) => String(entry).trim())
+    .filter(Boolean)
+    .map((entry) => (params.stripPrefixRe ? entry.replace(params.stripPrefixRe, "") : entry))
+    .map((entry) => entry.toLowerCase());
+}
+
+function applyDirectoryQueryAndLimit(
+  ids: string[],
+  params: { query?: string | null; limit?: number | null },
+): string[] {
+  const query = params.query?.trim().toLowerCase() || "";
+  const limit = typeof params.limit === "number" && params.limit > 0 ? params.limit : undefined;
+  const filtered = ids.filter((id) => (query ? id.toLowerCase().includes(query) : true));
+  return typeof limit === "number" ? filtered.slice(0, limit) : filtered;
+}
+
+function dedupeIds(ids: string[]): string[] {
+  return Array.from(new Set(ids));
+}
+
+function collectEntryIds(params: {
+  entries?: readonly unknown[];
+  normalizeId?: (entry: string) => string | null | undefined;
+}): string[] {
+  return (params.entries ?? [])
+    .map((entry) => String(entry).trim())
+    .filter((entry) => Boolean(entry) && entry !== "*")
+    .map((entry) => {
+      const normalized = params.normalizeId ? params.normalizeId(entry) : entry;
+      return typeof normalized === "string" ? normalized.trim() : "";
+    })
+    .filter(Boolean);
+}
+
+function collectMapIds(params: {
+  map?: Record<string, unknown>;
+  normalizeId?: (entry: string) => string | null | undefined;
+}): string[] {
+  return collectEntryIds({
+    entries: Object.keys(params.map ?? {}),
+    normalizeId: params.normalizeId,
+  });
+}
+
+export function listDirectoryUserEntriesFromAllowFromAndMapKeys(params: {
+  allowFrom?: readonly unknown[];
+  map?: Record<string, unknown>;
+  query?: string | null;
+  limit?: number | null;
+  normalizeAllowFromId?: (entry: string) => string | null | undefined;
+  normalizeMapKeyId?: (entry: string) => string | null | undefined;
+}): Array<{ kind: "user"; id: string }> {
+  const ids = dedupeIds([
+    ...collectEntryIds({
+      entries: params.allowFrom,
+      normalizeId: params.normalizeAllowFromId,
+    }),
+    ...collectMapIds({
+      map: params.map,
+      normalizeId: params.normalizeMapKeyId,
+    }),
+  ]);
+  return applyDirectoryQueryAndLimit(ids, params).map((id) => ({ kind: "user", id }));
+}
+
+export function listDirectoryGroupEntriesFromMapKeysAndAllowFrom(params: {
+  groups?: Record<string, unknown>;
+  allowFrom?: readonly unknown[];
+  query?: string | null;
+  limit?: number | null;
+  normalizeMapKeyId?: (entry: string) => string | null | undefined;
+  normalizeAllowFromId?: (entry: string) => string | null | undefined;
+}): Array<{ kind: "group"; id: string }> {
+  const ids = dedupeIds([
+    ...collectMapIds({
+      map: params.groups,
+      normalizeId: params.normalizeMapKeyId,
+    }),
+    ...collectEntryIds({
+      entries: params.allowFrom,
+      normalizeId: params.normalizeAllowFromId,
+    }),
+  ]);
+  return applyDirectoryQueryAndLimit(ids, params).map((id) => ({ kind: "group", id }));
+}
+
+export function collectAllowlistProviderRestrictSendersWarnings(params: {
+  cfg: OpenClawConfig;
+  providerConfigPresent: boolean;
+  configuredGroupPolicy?: GroupPolicy | null;
+  surface: string;
+  openScope: string;
+  groupPolicyPath: string;
+  groupAllowFromPath: string;
+  mentionGated?: boolean;
+}): string[] {
+  const defaultGroupPolicy = resolveDefaultGroupPolicy(params.cfg as {
+    channels?: { defaults?: { groupPolicy?: GroupPolicy } };
+  });
+  const { groupPolicy } = resolveOpenProviderRuntimeGroupPolicy({
+    providerConfigPresent: params.providerConfigPresent,
+    groupPolicy: params.configuredGroupPolicy ?? undefined,
+    defaultGroupPolicy,
+  });
+  if (groupPolicy !== "open") {
+    return [];
+  }
+  const mentionSuffix = params.mentionGated === false ? "" : " (mention-gated)";
+  return [
+    `- ${params.surface}: groupPolicy="open" allows ${params.openScope} to trigger${mentionSuffix}. Set ${params.groupPolicyPath}="allowlist" + ${params.groupAllowFromPath} to restrict senders.`,
+  ];
+}

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";