@cuylabs/channel-slack 0.1.0

package/dist/targets.js

@@ -0,0 +1,484 @@
+// src/targets/parse.ts
+var CHANNEL_PREFIXES = /* @__PURE__ */ new Set(["channel", "conversation", "room"]);
+var USER_PREFIXES = /* @__PURE__ */ new Set(["user", "member"]);
+var CHANNEL_ID_PATTERN = /^[CDG](?=[A-Z0-9]*\d)[A-Z0-9]{2,}$/i;
+var USER_ID_PATTERN = /^[UW](?=[A-Z0-9]*\d)[A-Z0-9]{2,}$/i;
+var CHANNEL_MENTION_PATTERN = /^<#([CDG][A-Z0-9]+)(?:\|([^>]+))?>$/i;
+var USER_MENTION_PATTERN = /^<@([UW][A-Z0-9]+)(?:\|([^>]+))?>$/i;
+var CHANNEL_ARCHIVE_URL_PATTERN = /\/archives\/([CDG][A-Z0-9]+)/i;
+function parseSlackTarget(input, options = {}) {
+  const normalizedInput = input.trim();
+  if (!normalizedInput) {
+    return void 0;
+  }
+  const channelMention = CHANNEL_MENTION_PATTERN.exec(normalizedInput);
+  if (channelMention) {
+    return idTarget({
+      input: normalizedInput,
+      kind: "channel",
+      id: channelMention[1],
+      label: channelMention[2],
+      source: "mention"
+    });
+  }
+  const userMention = USER_MENTION_PATTERN.exec(normalizedInput);
+  if (userMention) {
+    return idTarget({
+      input: normalizedInput,
+      kind: "user",
+      id: userMention[1],
+      label: userMention[2],
+      source: "mention"
+    });
+  }
+  const archiveUrl = CHANNEL_ARCHIVE_URL_PATTERN.exec(normalizedInput);
+  if (archiveUrl) {
+    return idTarget({
+      input: normalizedInput,
+      kind: "channel",
+      id: archiveUrl[1],
+      source: "link"
+    });
+  }
+  const prefixed = parsePrefixedTarget(normalizedInput);
+  if (prefixed) {
+    return prefixed;
+  }
+  if (normalizedInput.startsWith("#")) {
+    return parseDecoratedTarget(normalizedInput, "channel");
+  }
+  if (normalizedInput.startsWith("@")) {
+    return parseDecoratedTarget(normalizedInput, "user");
+  }
+  if (isChannelId(normalizedInput)) {
+    return idTarget({
+      input: normalizedInput,
+      kind: "channel",
+      id: normalizedInput,
+      source: "id"
+    });
+  }
+  if (isUserId(normalizedInput)) {
+    return idTarget({
+      input: normalizedInput,
+      kind: "user",
+      id: normalizedInput,
+      source: "id"
+    });
+  }
+  const allowBareNames = options.allowBareNames ?? Boolean(options.defaultKind);
+  if (allowBareNames && options.defaultKind) {
+    return nameTarget({
+      input: normalizedInput,
+      kind: options.defaultKind,
+      name: normalizedInput,
+      source: "name"
+    });
+  }
+  return void 0;
+}
+function parseSlackTargets(inputs, options = {}) {
+  const values = Array.isArray(inputs) ? inputs : [inputs];
+  const targets = [];
+  const invalid = [];
+  for (const input of values) {
+    const target = parseSlackTarget(input, options);
+    if (target) {
+      targets.push(target);
+    } else {
+      const trimmed = input.trim();
+      if (trimmed) {
+        invalid.push(trimmed);
+      }
+    }
+  }
+  return { targets, invalid };
+}
+function parsePrefixedTarget(input) {
+  const separator = input.indexOf(":");
+  if (separator <= 0) {
+    return void 0;
+  }
+  const prefix = input.slice(0, separator).trim().toLowerCase();
+  const value = input.slice(separator + 1).trim();
+  if (!value) {
+    return void 0;
+  }
+  if (CHANNEL_PREFIXES.has(prefix)) {
+    return valueTarget(input, "channel", stripLeading(value, "#"), "prefixed");
+  }
+  if (USER_PREFIXES.has(prefix)) {
+    return valueTarget(input, "user", stripLeading(value, "@"), "prefixed");
+  }
+  return void 0;
+}
+function parseDecoratedTarget(input, kind) {
+  const value = input.slice(1).trim();
+  if (!value) {
+    return void 0;
+  }
+  return valueTarget(input, kind, value, "name");
+}
+function valueTarget(input, kind, value, source) {
+  if (kind === "channel" && isChannelId(value)) {
+    return idTarget({ input, kind, id: value, source });
+  }
+  if (kind === "user" && isUserId(value)) {
+    return idTarget({ input, kind, id: value, source });
+  }
+  return nameTarget({ input, kind, name: value, source });
+}
+function idTarget(params) {
+  const id = normalizeSlackId(params.id);
+  return {
+    input: params.input,
+    kind: params.kind,
+    valueKind: "id",
+    value: id,
+    source: params.source,
+    id,
+    ...params.label ? { label: params.label } : {}
+  };
+}
+function nameTarget(params) {
+  const name = normalizeTargetName(params.name);
+  return {
+    input: params.input,
+    kind: params.kind,
+    valueKind: "name",
+    value: name,
+    source: params.source,
+    name
+  };
+}
+function stripLeading(value, leading) {
+  return value.startsWith(leading) ? value.slice(1).trim() : value;
+}
+function normalizeSlackId(value) {
+  return value.trim().toUpperCase();
+}
+function normalizeTargetName(value) {
+  return value.trim().replace(/^[@#]+/, "").trim();
+}
+function isChannelId(value) {
+  return CHANNEL_ID_PATTERN.test(value.trim());
+}
+function isUserId(value) {
+  return USER_ID_PATTERN.test(value.trim());
+}
+
+// src/targets/resolve.ts
+var DEFAULT_LIMIT = 200;
+async function resolveSlackChannelTargets(options) {
+  const result = collectDirectTargets(options.targets, "channel");
+  if (result.pending.length === 0) {
+    return {
+      resolved: result.resolved,
+      unresolved: result.unresolved
+    };
+  }
+  if (!options.client.conversations?.list) {
+    return {
+      resolved: result.resolved,
+      unresolved: [
+        ...result.unresolved,
+        ...result.pending.map(
+          (pending) => resolutionError(
+            pending.target,
+            "missing-client-method",
+            "Slack client does not expose conversations.list."
+          )
+        )
+      ]
+    };
+  }
+  const pendingByName = toPendingMap(result.pending);
+  try {
+    let cursor;
+    do {
+      const response = await options.client.conversations.list({
+        limit: options.limit ?? DEFAULT_LIMIT,
+        types: options.types ?? "public_channel,private_channel",
+        exclude_archived: options.includeArchived === true ? false : true,
+        ...cursor ? { cursor } : {},
+        ...options.token ? { token: options.token } : {}
+      });
+      assertSlackListOk(response, "conversations.list");
+      for (const channel of readArray(readRecord(response)?.channels)) {
+        const record = readRecord(channel);
+        if (!record) continue;
+        const names = channelLookupNames(record);
+        for (const name of names) {
+          const matches = pendingByName.get(name);
+          if (!matches) continue;
+          for (const pending of matches) {
+            result.resolved.push(resolvedFromRecord(pending.target, record));
+          }
+          pendingByName.delete(name);
+        }
+        if (pendingByName.size === 0) {
+          break;
+        }
+      }
+      cursor = readNextCursor(response);
+    } while (cursor && pendingByName.size > 0);
+    return finalizeResolution(result, pendingByName);
+  } catch (error) {
+    return {
+      resolved: result.resolved,
+      unresolved: [
+        ...result.unresolved,
+        ...result.pending.map(
+          (pending) => resolutionError(
+            pending.target,
+            "api-error",
+            "Slack channel target resolution failed.",
+            error
+          )
+        )
+      ]
+    };
+  }
+}
+async function resolveSlackUserTargets(options) {
+  const result = collectDirectTargets(options.targets, "user");
+  if (result.pending.length === 0) {
+    return {
+      resolved: result.resolved,
+      unresolved: result.unresolved
+    };
+  }
+  if (!options.client.users?.list) {
+    return {
+      resolved: result.resolved,
+      unresolved: [
+        ...result.unresolved,
+        ...result.pending.map(
+          (pending) => resolutionError(
+            pending.target,
+            "missing-client-method",
+            "Slack client does not expose users.list."
+          )
+        )
+      ]
+    };
+  }
+  const pendingByName = toPendingMap(result.pending);
+  try {
+    let cursor;
+    do {
+      const response = await options.client.users.list({
+        limit: options.limit ?? DEFAULT_LIMIT,
+        ...cursor ? { cursor } : {},
+        ...options.token ? { token: options.token } : {}
+      });
+      assertSlackListOk(response, "users.list");
+      for (const member of readArray(readRecord(response)?.members)) {
+        const record = readRecord(member);
+        if (!record || shouldSkipUser(record, options)) continue;
+        const names = userLookupNames(record);
+        for (const name of names) {
+          const matches = pendingByName.get(name);
+          if (!matches) continue;
+          for (const pending of matches) {
+            result.resolved.push(resolvedFromRecord(pending.target, record));
+          }
+          pendingByName.delete(name);
+        }
+        if (pendingByName.size === 0) {
+          break;
+        }
+      }
+      cursor = readNextCursor(response);
+    } while (cursor && pendingByName.size > 0);
+    return finalizeResolution(result, pendingByName);
+  } catch (error) {
+    return {
+      resolved: result.resolved,
+      unresolved: [
+        ...result.unresolved,
+        ...result.pending.map(
+          (pending) => resolutionError(
+            pending.target,
+            "api-error",
+            "Slack user target resolution failed.",
+            error
+          )
+        )
+      ]
+    };
+  }
+}
+async function resolveSlackAllowedChannelIds(options) {
+  const result = await resolveSlackChannelTargets({
+    ...options,
+    client: options.client ?? {}
+  });
+  return {
+    ok: result.unresolved.length === 0,
+    allowedChannelIds: uniqueIds(result.resolved.map((target) => target.id)),
+    resolved: result.resolved,
+    unresolved: result.unresolved
+  };
+}
+function collectDirectTargets(inputs, expectedKind) {
+  const resolved = [];
+  const unresolved = [];
+  const pending = [];
+  for (const input of inputs) {
+    const target = typeof input === "string" ? parseSlackTarget(input, { defaultKind: expectedKind }) : input;
+    const originalInput = typeof input === "string" ? input.trim() : input.input;
+    if (!target) {
+      if (originalInput) {
+        unresolved.push({
+          input: originalInput,
+          code: "invalid-target",
+          message: `Could not parse Slack ${expectedKind} target: ${originalInput}`
+        });
+      }
+      continue;
+    }
+    if (target.kind !== expectedKind) {
+      unresolved.push({
+        input: target.input,
+        kind: target.kind,
+        code: "target-kind-mismatch",
+        message: `Expected Slack ${expectedKind} target but received ${target.kind} target.`
+      });
+      continue;
+    }
+    if (target.id) {
+      resolved.push({
+        input: target.input,
+        kind: target.kind,
+        id: target.id,
+        valueKind: target.valueKind,
+        ...target.name ? { name: target.name } : {},
+        ...target.label ? { label: target.label } : {}
+      });
+      continue;
+    }
+    if (target.name) {
+      pending.push({
+        target,
+        lookupName: normalizeLookupName(target.name)
+      });
+    }
+  }
+  return { resolved, unresolved, pending };
+}
+function finalizeResolution(result, pendingByName) {
+  const unresolved = [...result.unresolved];
+  for (const pending of pendingByName.values()) {
+    for (const entry of pending) {
+      unresolved.push(
+        resolutionError(
+          entry.target,
+          "not-found",
+          `Slack ${entry.target.kind} target was not found: ${entry.target.name}`
+        )
+      );
+    }
+  }
+  return {
+    resolved: result.resolved,
+    unresolved
+  };
+}
+function toPendingMap(pending) {
+  const map = /* @__PURE__ */ new Map();
+  for (const entry of pending) {
+    const existing = map.get(entry.lookupName);
+    if (existing) {
+      existing.push(entry);
+    } else {
+      map.set(entry.lookupName, [entry]);
+    }
+  }
+  return map;
+}
+function resolvedFromRecord(target, record) {
+  const id = readString(record.id) ?? target.id ?? target.value;
+  const name = target.name ?? readString(record.name) ?? readString(readRecord(record.profile)?.display_name) ?? readString(record.real_name);
+  return {
+    input: target.input,
+    kind: target.kind,
+    id,
+    valueKind: target.valueKind,
+    ...name ? { name } : {},
+    ...target.label ? { label: target.label } : {},
+    raw: record
+  };
+}
+function resolutionError(target, code, message, error) {
+  return {
+    input: target.input,
+    code,
+    message,
+    kind: target.kind,
+    ...target.name ? { name: target.name } : {},
+    ...error ? { error } : {}
+  };
+}
+function channelLookupNames(record) {
+  return uniqueLookupNames([
+    readString(record.name),
+    readString(record.name_normalized)
+  ]);
+}
+function userLookupNames(record) {
+  const profile = readRecord(record.profile);
+  return uniqueLookupNames([
+    readString(record.name),
+    readString(record.real_name),
+    readString(profile?.display_name),
+    readString(profile?.display_name_normalized),
+    readString(profile?.real_name),
+    readString(profile?.real_name_normalized)
+  ]);
+}
+function uniqueLookupNames(values) {
+  return [...new Set(values.map(normalizeLookupName).filter(Boolean))];
+}
+function uniqueIds(values) {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
+function normalizeLookupName(value) {
+  return value?.trim().replace(/^[@#]+/, "").toLowerCase() ?? "";
+}
+function shouldSkipUser(record, options) {
+  if (options.includeDeleted !== true && record.deleted === true) {
+    return true;
+  }
+  if (options.includeBots !== true && record.is_bot === true) {
+    return true;
+  }
+  return false;
+}
+function assertSlackListOk(response, method) {
+  const record = readRecord(response);
+  if (record?.ok === false) {
+    const code = readString(record.error);
+    throw new Error(`${method} failed${code ? `: ${code}` : ""}.`);
+  }
+}
+function readNextCursor(response) {
+  const metadata = readRecord(readRecord(response)?.response_metadata);
+  return readString(metadata?.next_cursor);
+}
+function readArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+function readRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function readString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+export {
+  parseSlackTarget,
+  parseSlackTargets,
+  resolveSlackAllowedChannelIds,
+  resolveSlackChannelTargets,
+  resolveSlackUserTargets
+};

package/dist/users.d.ts

@@ -0,0 +1,109 @@
+interface SlackUserProfile {
+    userId: string;
+    displayName?: string;
+    realName?: string;
+    email?: string;
+}
+interface SlackUsersInfoClient {
+    users: {
+        info(args: {
+            user: string;
+            token?: string;
+        }): Promise<unknown>;
+    };
+}
+interface SlackUserProfileResolverInput {
+    userId: string;
+    teamId?: string;
+    botToken?: string;
+}
+interface SlackUserProfileLookupErrorContext extends SlackUserProfileResolverInput {
+    error: unknown;
+}
+interface CreateSlackUserProfileResolverOptions {
+    botToken?: string;
+    client?: SlackUsersInfoClient;
+    clientFactory?: (botToken: string) => SlackUsersInfoClient;
+    /**
+     * Maximum cached profile entries.
+     *
+     * @default 5000
+     */
+    maxEntries?: number;
+    /**
+     * Successful lookup cache TTL.
+     *
+     * @default 1800000
+     */
+    ttlMs?: number;
+    /**
+     * Failed lookup fallback cache TTL.
+     *
+     * @default min(ttlMs, 300000)
+     */
+    errorTtlMs?: number;
+    onLookupError?: (context: SlackUserProfileLookupErrorContext) => void;
+}
+interface SlackUserProfileResolver {
+    resolve(input: SlackUserProfileResolverInput): Promise<SlackUserProfile>;
+    clear(): void;
+}
+declare function createSlackUserProfileResolver(options?: CreateSlackUserProfileResolverOptions): SlackUserProfileResolver;
+
+interface SlackUserMentionEnrichmentInput {
+    text: string;
+    teamId?: string;
+    botToken?: string;
+}
+interface SlackUserMentionLabelContext {
+    userId: string;
+    mention: string;
+    profile: SlackUserProfile;
+}
+type SlackUserMentionLabelFormatter = (context: SlackUserMentionLabelContext) => string | undefined;
+interface SlackUserMentionEnrichmentErrorContext {
+    userId: string;
+    teamId?: string;
+    error: unknown;
+}
+interface EnrichSlackUserMentionsOptions extends CreateSlackUserProfileResolverOptions {
+    /**
+     * Reusable profile resolver. Prefer passing one created by
+     * `createSlackUserProfileResolver(...)` so profile cache entries are shared
+     * across messages.
+     */
+    profileResolver?: Pick<SlackUserProfileResolver, "resolve">;
+    /**
+     * Maximum distinct user mention IDs to look up for one input message.
+     *
+     * @default 20
+     */
+    maxLookups?: number;
+    /**
+     * Maximum concurrent profile lookups for one input message.
+     *
+     * @default 4
+     */
+    concurrency?: number;
+    /**
+     * Format the model-visible mention label. Return `undefined` to leave the
+     * mention unchanged.
+     *
+     * @default `<@U123> (Display Name)`
+     */
+    formatLabel?: SlackUserMentionLabelFormatter;
+    /**
+     * Called when the profile resolver throws. Does not include message text.
+     */
+    onResolveError?: (context: SlackUserMentionEnrichmentErrorContext) => void;
+}
+interface SlackUserMentionEnrichmentResult {
+    text: string;
+    lookedUpUserIds: string[];
+    enrichedUserIds: string[];
+    unresolvedUserIds: string[];
+    skippedUserIds: string[];
+}
+declare function enrichSlackUserMentions(input: string | SlackUserMentionEnrichmentInput, options?: EnrichSlackUserMentionsOptions): Promise<SlackUserMentionEnrichmentResult>;
+
+export { type CreateSlackUserProfileResolverOptions, type EnrichSlackUserMentionsOptions, type SlackUserMentionEnrichmentErrorContext, type SlackUserMentionEnrichmentInput, type SlackUserMentionEnrichmentResult, type SlackUserMentionLabelContext, type SlackUserMentionLabelFormatter, type SlackUserProfile, type SlackUserProfileLookupErrorContext, type SlackUserProfileResolver, type SlackUserProfileResolverInput, type SlackUsersInfoClient, createSlackUserProfileResolver, enrichSlackUserMentions };