@cuylabs/channel-slack 0.1.0

package/dist/setup.js

@@ -0,0 +1,453 @@
+import {
+  inspectSlackConnection
+} from "./chunk-FX2JOVX5.js";
+
+// src/setup/requirements.ts
+var DEFAULT_EVENTS_PATH = "/slack/events";
+var slackSetupFeaturePresets = {
+  assistant: ["assistant", "feedback"],
+  "channel-adapter": ["app-mentions", "direct-messages"],
+  "agent-app": ["assistant", "app-mentions", "direct-messages", "feedback"]
+};
+var FEATURE_REQUIREMENTS = {
+  assistant: {
+    botScopes: ["assistant:write", "chat:write"],
+    botEvents: ["assistant_thread_started", "assistant_thread_context_changed"],
+    assistantView: true
+  },
+  "app-mentions": {
+    botScopes: ["app_mentions:read", "chat:write"],
+    botEvents: ["app_mention"]
+  },
+  "direct-messages": {
+    botScopes: ["chat:write", "im:history", "im:read"],
+    botEvents: ["message.im"]
+  },
+  "channel-messages": {
+    botScopes: ["channels:history", "chat:write", "groups:history"],
+    botEvents: ["message.channels", "message.groups"]
+  },
+  history: {
+    botScopes: [
+      "channels:history",
+      "groups:history",
+      "im:history",
+      "mpim:history"
+    ]
+  },
+  interactivity: {
+    botScopes: ["chat:write"],
+    interactivity: true
+  },
+  feedback: {
+    botScopes: ["chat:write"],
+    interactivity: true
+  },
+  "user-profiles": {
+    botScopes: ["users:read"],
+    optionalBotScopes: ["users:read.email"]
+  },
+  "user-emails": {
+    botScopes: ["users:read", "users:read.email"]
+  }
+};
+function getSlackSetupRequirements(options = {}) {
+  const features = resolveSetupFeatures(options);
+  const transport = options.transport ?? "http";
+  const eventsPath = normalizeSlackEventsPath(
+    options.eventsPath ?? DEFAULT_EVENTS_PATH
+  );
+  const requestUrl = resolveRequestUrl(options.baseUrl, eventsPath);
+  const botScopes = [];
+  const optionalBotScopes = [];
+  const botEvents = [];
+  let assistantView = false;
+  let interactivity = false;
+  for (const feature of features) {
+    const requirement = FEATURE_REQUIREMENTS[feature];
+    if (!requirement) {
+      throw new Error(`Unknown Slack setup feature: ${feature}`);
+    }
+    collect(requirement.botScopes, botScopes);
+    collect(requirement.optionalBotScopes, optionalBotScopes);
+    collect(requirement.botEvents, botEvents);
+    assistantView ||= requirement.assistantView === true;
+    interactivity ||= requirement.interactivity === true;
+  }
+  collect(options.extraBotScopes, botScopes);
+  collect(options.extraOptionalBotScopes, optionalBotScopes);
+  collect(options.extraBotEvents, botEvents);
+  const normalizedBotScopes = uniqueSorted(botScopes);
+  const normalizedBotEvents = uniqueSorted(botEvents);
+  const requiredScopeKeys = new Set(
+    normalizedBotScopes.map((scope) => scope.toLowerCase())
+  );
+  const normalizedOptionalBotScopes = uniqueSorted(
+    optionalBotScopes.filter(
+      (scope) => !requiredScopeKeys.has(scope.trim().toLowerCase())
+    )
+  );
+  const settings = {
+    assistantView,
+    eventSubscriptions: normalizedBotEvents.length > 0,
+    interactivity,
+    socketMode: transport === "socket"
+  };
+  const environment = resolveEnvironment({
+    botScopes: normalizedBotScopes,
+    settings,
+    transport
+  });
+  return {
+    features,
+    transport,
+    eventsPath,
+    ...requestUrl ? { requestUrl } : {},
+    botScopes: normalizedBotScopes,
+    optionalBotScopes: normalizedOptionalBotScopes,
+    appTokenScopes: transport === "socket" ? ["connections:write"] : [],
+    botEvents: normalizedBotEvents,
+    settings,
+    environment
+  };
+}
+function resolveSetupFeatures(options) {
+  const preset = options.preset ?? "agent-app";
+  if (preset === false) {
+    return uniqueFeatures(options.features ?? []);
+  }
+  const presetFeatures = slackSetupFeaturePresets[preset];
+  if (!presetFeatures) {
+    throw new Error(`Unknown Slack setup preset: ${preset}`);
+  }
+  return uniqueFeatures([
+    ...presetFeatures ?? [],
+    ...options.features ?? []
+  ]);
+}
+function resolveEnvironment(context) {
+  const environment = [];
+  if (context.botScopes.length > 0) {
+    environment.push({
+      name: "SLACK_BOT_TOKEN",
+      purpose: "Bot OAuth token used by single-workspace direct mode and setup inspection."
+    });
+  }
+  if (context.transport === "http" && (context.settings.eventSubscriptions || context.settings.interactivity)) {
+    environment.push({
+      name: "SLACK_SIGNING_SECRET",
+      purpose: "Signing secret used by Bolt to verify inbound Slack requests."
+    });
+  }
+  if (context.transport === "socket") {
+    environment.push({
+      name: "SLACK_APP_TOKEN",
+      purpose: "App-level token with connections:write used by Socket Mode transport."
+    });
+  }
+  return environment;
+}
+function normalizeSlackEventsPath(path) {
+  const trimmed = path.trim();
+  if (!trimmed) {
+    throw new Error("Slack events path must not be empty.");
+  }
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+function resolveRequestUrl(baseUrl, eventsPath) {
+  const trimmed = trimString(baseUrl);
+  if (!trimmed) return void 0;
+  return `${trimmed.replace(/\/+$/, "")}${eventsPath}`;
+}
+function collect(source, target) {
+  if (!source) return;
+  for (const value of source) {
+    const trimmed = value.trim();
+    if (trimmed) target.push(trimmed);
+  }
+}
+function uniqueSorted(values) {
+  const unique = /* @__PURE__ */ new Map();
+  for (const value of values) {
+    const trimmed = value.trim();
+    if (trimmed) {
+      unique.set(trimmed.toLowerCase(), trimmed);
+    }
+  }
+  return [...unique.values()].sort((a, b) => a.localeCompare(b));
+}
+function uniqueFeatures(values) {
+  const unique = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    if (!FEATURE_REQUIREMENTS[value]) {
+      throw new Error(`Unknown Slack setup feature: ${value}`);
+    }
+    unique.add(value);
+  }
+  return [...unique];
+}
+function trimString(value) {
+  const trimmed = value?.trim();
+  return trimmed || void 0;
+}
+
+// src/setup/manifest.ts
+function createSlackAppManifest(options) {
+  const requirements = getSlackSetupRequirements(options);
+  const name = options.name.trim();
+  if (!name) {
+    throw new Error("Slack app manifest name is required.");
+  }
+  const description = trimString2(options.description);
+  const backgroundColor = trimString2(options.backgroundColor);
+  const assistantDescription = trimString2(options.assistantDescription);
+  const botDisplayName = trimString2(options.botDisplayName) ?? name;
+  const displayInformation = {
+    name
+  };
+  if (description) displayInformation.description = description;
+  if (backgroundColor) displayInformation.background_color = backgroundColor;
+  const features = {
+    bot_user: {
+      display_name: botDisplayName,
+      always_online: options.alwaysOnline ?? true
+    }
+  };
+  if (requirements.settings.assistantView) {
+    if (options.appHome !== false) {
+      features.app_home = {
+        home_tab_enabled: options.appHome?.home_tab_enabled ?? true,
+        messages_tab_enabled: options.appHome?.messages_tab_enabled ?? true,
+        messages_tab_read_only_enabled: options.appHome?.messages_tab_read_only_enabled ?? false
+      };
+    }
+    features.assistant_view = {
+      ...assistantDescription ? { assistant_description: assistantDescription } : {},
+      ...options.suggestedPrompts ? { suggested_prompts: [...options.suggestedPrompts] } : {}
+    };
+  }
+  const settings = {
+    socket_mode_enabled: requirements.settings.socketMode,
+    token_rotation_enabled: options.tokenRotationEnabled ?? false
+  };
+  if (requirements.settings.eventSubscriptions) {
+    settings.event_subscriptions = {
+      ...requirements.requestUrl && requirements.transport === "http" ? { request_url: requirements.requestUrl } : {},
+      bot_events: requirements.botEvents
+    };
+  }
+  if (requirements.settings.interactivity) {
+    settings.interactivity = {
+      is_enabled: true,
+      ...requirements.requestUrl && requirements.transport === "http" ? { request_url: requirements.requestUrl } : {}
+    };
+  }
+  if (options.orgDeployEnabled !== void 0) {
+    settings.org_deploy_enabled = options.orgDeployEnabled;
+  }
+  if (options.isMcpEnabled !== void 0) {
+    settings.is_mcp_enabled = options.isMcpEnabled;
+  }
+  const userScopes = uniqueSorted2(options.extraUserScopes ?? []);
+  return {
+    display_information: displayInformation,
+    features,
+    oauth_config: {
+      scopes: {
+        bot: requirements.botScopes,
+        ...userScopes.length > 0 ? { user: userScopes } : {}
+      }
+    },
+    settings
+  };
+}
+function compareSlackAppManifest(manifest, requirements) {
+  const findings = [];
+  const manifestRecord = readRecord(manifest);
+  const oauthConfig = readRecord(manifestRecord?.oauth_config);
+  const scopes = readRecord(oauthConfig?.scopes);
+  const settings = readRecord(manifestRecord?.settings);
+  const eventSubscriptions = readRecord(settings?.event_subscriptions);
+  const botScopes = readStringArray(scopes?.bot);
+  const botEvents = readStringArray(eventSubscriptions?.bot_events);
+  const missingBotScopes = missingValues(requirements.botScopes, botScopes);
+  const missingOptionalBotScopes = missingValues(
+    requirements.optionalBotScopes,
+    botScopes
+  );
+  const missingBotEvents = missingValues(requirements.botEvents, botEvents);
+  if (missingBotScopes.length > 0) {
+    findings.push({
+      severity: "error",
+      code: "missing-bot-scopes",
+      message: `Slack manifest is missing required bot scope(s): ${missingBotScopes.join(
+        ", "
+      )}.`,
+      path: "oauth_config.scopes.bot",
+      expected: requirements.botScopes,
+      actual: botScopes
+    });
+  }
+  if (missingOptionalBotScopes.length > 0) {
+    findings.push({
+      severity: "warning",
+      code: "missing-optional-bot-scopes",
+      message: `Slack manifest is missing optional bot scope(s): ${missingOptionalBotScopes.join(
+        ", "
+      )}.`,
+      path: "oauth_config.scopes.bot",
+      expected: requirements.optionalBotScopes,
+      actual: botScopes
+    });
+  }
+  if (missingBotEvents.length > 0) {
+    findings.push({
+      severity: "error",
+      code: "missing-bot-events",
+      message: `Slack manifest is missing required bot event(s): ${missingBotEvents.join(
+        ", "
+      )}.`,
+      path: "settings.event_subscriptions.bot_events",
+      expected: requirements.botEvents,
+      actual: botEvents
+    });
+  }
+  compareSettings(manifest, requirements, findings);
+  return {
+    ok: findings.every((finding) => finding.severity !== "error"),
+    missingBotScopes,
+    missingOptionalBotScopes,
+    missingBotEvents,
+    findings
+  };
+}
+function compareSettings(manifest, requirements, findings) {
+  const manifestRecord = readRecord(manifest);
+  const features = readRecord(manifestRecord?.features);
+  const settings = readRecord(manifestRecord?.settings);
+  const eventSubscriptions = readRecord(settings?.event_subscriptions);
+  const interactivity = readRecord(settings?.interactivity);
+  if (requirements.settings.assistantView && !readRecord(features?.assistant_view)) {
+    findings.push({
+      severity: "error",
+      code: "assistant-view-disabled",
+      message: "Slack manifest must enable Assistant view for Assistant features.",
+      path: "features.assistant_view",
+      expected: true,
+      actual: false
+    });
+  }
+  if (requirements.settings.eventSubscriptions && !Array.isArray(eventSubscriptions?.bot_events)) {
+    findings.push({
+      severity: "error",
+      code: "event-subscriptions-disabled",
+      message: "Slack manifest must configure event subscriptions for selected features.",
+      path: "settings.event_subscriptions.bot_events",
+      expected: requirements.botEvents,
+      actual: void 0
+    });
+  }
+  if (requirements.settings.interactivity && readBoolean(interactivity?.is_enabled) !== true) {
+    findings.push({
+      severity: "error",
+      code: "interactivity-disabled",
+      message: "Slack manifest must enable interactivity for selected features.",
+      path: "settings.interactivity.is_enabled",
+      expected: true,
+      actual: readBoolean(interactivity?.is_enabled) ?? false
+    });
+  }
+  if (requirements.settings.socketMode && readBoolean(settings?.socket_mode_enabled) !== true) {
+    findings.push({
+      severity: "error",
+      code: "socket-mode-disabled",
+      message: "Slack manifest must enable Socket Mode for socket transport.",
+      path: "settings.socket_mode_enabled",
+      expected: true,
+      actual: readBoolean(settings?.socket_mode_enabled) ?? false
+    });
+  }
+  if (requirements.requestUrl && requirements.transport === "http" && requirements.settings.eventSubscriptions && readString(eventSubscriptions?.request_url) !== requirements.requestUrl) {
+    findings.push({
+      severity: "error",
+      code: "event-request-url-mismatch",
+      message: `Slack manifest event request URL must be ${requirements.requestUrl}.`,
+      path: "settings.event_subscriptions.request_url",
+      expected: requirements.requestUrl,
+      actual: readString(eventSubscriptions?.request_url)
+    });
+  }
+  if (requirements.requestUrl && requirements.transport === "http" && requirements.settings.interactivity && readString(interactivity?.request_url) !== requirements.requestUrl) {
+    findings.push({
+      severity: "error",
+      code: "interactivity-request-url-mismatch",
+      message: `Slack manifest interactivity request URL must be ${requirements.requestUrl}.`,
+      path: "settings.interactivity.request_url",
+      expected: requirements.requestUrl,
+      actual: readString(interactivity?.request_url)
+    });
+  }
+}
+function trimString2(value) {
+  const trimmed = value?.trim();
+  return trimmed || void 0;
+}
+function missingValues(expected, actual) {
+  const actualSet = new Set(
+    actual.map((value) => value.trim().toLowerCase()).filter(Boolean)
+  );
+  return expected.filter((value) => !actualSet.has(value.trim().toLowerCase()));
+}
+function uniqueSorted2(values) {
+  const unique = /* @__PURE__ */ new Map();
+  for (const value of values) {
+    const trimmed = value.trim();
+    if (trimmed) {
+      unique.set(trimmed.toLowerCase(), trimmed);
+    }
+  }
+  return [...unique.values()].sort((a, b) => a.localeCompare(b));
+}
+function readRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function readStringArray(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return uniqueSorted2(
+    value.filter((entry) => typeof entry === "string")
+  );
+}
+function readString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function readBoolean(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+
+// src/setup/inspection.ts
+async function inspectSlackAppSetup(options = {}) {
+  const requirements = getSlackSetupRequirements(options);
+  const connection = await inspectSlackConnection({
+    token: options.token,
+    client: options.client,
+    requestTimeoutMs: options.requestTimeoutMs,
+    inspectScopes: options.inspectScopes,
+    scopeMethods: options.scopeMethods,
+    requiredScopes: requirements.botScopes,
+    optionalScopes: requirements.optionalBotScopes
+  });
+  return {
+    ok: connection.ok,
+    requirements,
+    connection
+  };
+}
+export {
+  compareSlackAppManifest,
+  createSlackAppManifest,
+  getSlackSetupRequirements,
+  inspectSlackAppSetup,
+  slackSetupFeaturePresets
+};

package/dist/shared.d.ts

@@ -0,0 +1,2 @@
+export { S as SlackActivityInfo, a as SlackChannelType, b as SlackUserIdentity } from './activity-ByrD9Ftr.js';
+export { ExtractSlackMessageTextOptions, RawSlackActionTokenPayload, RawSlackAppMentionPayload, RawSlackAssistantThreadPayload, RawSlackMessagePayload, SlackAmbientTurnContext, SlackApprovalRequest, SlackAssistantStatusUpdate, SlackAssistantSuggestedPrompt, SlackAssistantSuggestedPrompts, SlackAssistantTaskDisplayMode, SlackAssistantThreadContext, SlackAssistantUtilities, SlackAuthContext, SlackChatStreamStartArgs, SlackEventInteractiveRequestHandler, SlackHumanInputRequest, SlackInteractiveMessage, SlackInteractiveMessageRef, SlackInteractiveRequest, SlackInteractiveRequestBaseContext, SlackInteractiveRequestContext, SlackInteractiveRequestHandler, SlackInteractiveRequestKind, SlackInteractiveResponder, SlackMessageAuthorshipOptions, SlackMessageFormatter, SlackMessageFormattingOptions, SlackMessageTextPayload, SlackThreadStatusSetter, SlackTurnPreparation, SlackTurnRequestContext, currentSlackTurnContext, extractSlackActionToken, extractSlackAttachmentsText, extractSlackAuthContext, extractSlackBlocksText, extractSlackMessageText, extractSlackUserIdentity, formatSlackAttributedFollowUp, isProcessableMessage, markdownToSlackMrkdwn, parseSlackMentionActivity, parseSlackMessageActivity, resolveSlackChannelType, resolveSlackMessageFormatter, resolveThreadAwareSlackSessionId, runWithSlackTurnContext, stripLeadingMentions } from './core.js';

package/dist/shared.js

@@ -0,0 +1,43 @@
+import "./chunk-NE57BLLU.js";
+import {
+  currentSlackTurnContext,
+  formatSlackAttributedFollowUp,
+  markdownToSlackMrkdwn,
+  resolveSlackMessageFormatter,
+  resolveThreadAwareSlackSessionId,
+  runWithSlackTurnContext
+} from "./chunk-JZG4IETE.js";
+import {
+  extractSlackActionToken,
+  extractSlackAuthContext,
+  extractSlackUserIdentity,
+  parseSlackMentionActivity,
+  parseSlackMessageActivity
+} from "./chunk-TWJGVDA2.js";
+import {
+  extractSlackAttachmentsText,
+  extractSlackBlocksText,
+  extractSlackMessageText,
+  isProcessableMessage,
+  resolveSlackChannelType,
+  stripLeadingMentions
+} from "./chunk-FPCE5V5Y.js";
+export {
+  currentSlackTurnContext,
+  extractSlackActionToken,
+  extractSlackAttachmentsText,
+  extractSlackAuthContext,
+  extractSlackBlocksText,
+  extractSlackMessageText,
+  extractSlackUserIdentity,
+  formatSlackAttributedFollowUp,
+  isProcessableMessage,
+  markdownToSlackMrkdwn,
+  parseSlackMentionActivity,
+  parseSlackMessageActivity,
+  resolveSlackChannelType,
+  resolveSlackMessageFormatter,
+  resolveThreadAwareSlackSessionId,
+  runWithSlackTurnContext,
+  stripLeadingMentions
+};

package/dist/targets.d.ts

@@ -0,0 +1,113 @@
+type SlackTargetKind = "channel" | "user";
+type SlackTargetValueKind = "id" | "name";
+type SlackTargetSource = "prefixed" | "mention" | "link" | "id" | "name";
+interface SlackTarget {
+    input: string;
+    kind: SlackTargetKind;
+    valueKind: SlackTargetValueKind;
+    value: string;
+    source: SlackTargetSource;
+    id?: string;
+    name?: string;
+    label?: string;
+}
+interface ParseSlackTargetOptions {
+    /**
+     * Interpret bare non-ID values as this target kind.
+     *
+     * @example `parseSlackTarget("general", { defaultKind: "channel" })`
+     */
+    defaultKind?: SlackTargetKind;
+    /**
+     * Whether bare non-ID values may be parsed through `defaultKind`.
+     *
+     * @default Boolean(defaultKind)
+     */
+    allowBareNames?: boolean;
+}
+interface ParseSlackTargetsResult {
+    targets: SlackTarget[];
+    invalid: string[];
+}
+declare function parseSlackTarget(input: string, options?: ParseSlackTargetOptions): SlackTarget | undefined;
+declare function parseSlackTargets(inputs: string | readonly string[], options?: ParseSlackTargetOptions): ParseSlackTargetsResult;
+
+interface SlackTargetResolutionClient {
+    conversations?: {
+        list(args?: Record<string, unknown>): Promise<unknown>;
+    };
+    users?: {
+        list(args?: Record<string, unknown>): Promise<unknown>;
+    };
+}
+interface SlackResolvedTarget {
+    input: string;
+    kind: SlackTargetKind;
+    id: string;
+    valueKind: "id" | "name";
+    name?: string;
+    label?: string;
+    raw?: unknown;
+}
+type SlackTargetResolutionErrorCode = "invalid-target" | "target-kind-mismatch" | "missing-client-method" | "not-found" | "api-error";
+interface SlackTargetResolutionError {
+    input: string;
+    code: SlackTargetResolutionErrorCode;
+    message: string;
+    kind?: SlackTargetKind;
+    name?: string;
+    error?: unknown;
+}
+interface SlackTargetResolutionResult {
+    resolved: SlackResolvedTarget[];
+    unresolved: SlackTargetResolutionError[];
+}
+interface ResolveSlackChannelTargetsOptions {
+    client: SlackTargetResolutionClient;
+    targets: readonly (string | SlackTarget)[];
+    token?: string;
+    /**
+     * Conversation types passed to `conversations.list`.
+     *
+     * @default "public_channel,private_channel"
+     */
+    types?: string;
+    /** Include archived channels while resolving names. @default false */
+    includeArchived?: boolean;
+    /** Slack API page size. @default 200 */
+    limit?: number;
+}
+interface ResolveSlackUserTargetsOptions {
+    client: SlackTargetResolutionClient;
+    targets: readonly (string | SlackTarget)[];
+    token?: string;
+    /** Include deleted users while resolving names. @default false */
+    includeDeleted?: boolean;
+    /** Include bot users while resolving names. @default false */
+    includeBots?: boolean;
+    /** Slack API page size. @default 200 */
+    limit?: number;
+}
+interface ResolveSlackAllowedChannelIdsOptions extends Omit<ResolveSlackChannelTargetsOptions, "client" | "targets"> {
+    /**
+     * Human-friendly channel targets from policy config, such as `C123`,
+     * `#engineering`, `<#C123|engineering>`, or `channel:engineering`.
+     */
+    targets: readonly (string | SlackTarget)[];
+    /**
+     * Slack Web API client used when a target needs name resolution. Direct
+     * channel IDs do not require a client.
+     */
+    client?: SlackTargetResolutionClient;
+}
+interface SlackAllowedChannelIdsResolution {
+    ok: boolean;
+    allowedChannelIds: string[];
+    resolved: SlackResolvedTarget[];
+    unresolved: SlackTargetResolutionError[];
+}
+declare function resolveSlackChannelTargets(options: ResolveSlackChannelTargetsOptions): Promise<SlackTargetResolutionResult>;
+declare function resolveSlackUserTargets(options: ResolveSlackUserTargetsOptions): Promise<SlackTargetResolutionResult>;
+declare function resolveSlackAllowedChannelIds(options: ResolveSlackAllowedChannelIdsOptions): Promise<SlackAllowedChannelIdsResolution>;
+
+export { type ParseSlackTargetOptions, type ParseSlackTargetsResult, type ResolveSlackAllowedChannelIdsOptions, type ResolveSlackChannelTargetsOptions, type ResolveSlackUserTargetsOptions, type SlackAllowedChannelIdsResolution, type SlackResolvedTarget, type SlackTarget, type SlackTargetKind, type SlackTargetResolutionClient, type SlackTargetResolutionError, type SlackTargetResolutionErrorCode, type SlackTargetResolutionResult, type SlackTargetSource, type SlackTargetValueKind, parseSlackTarget, parseSlackTargets, resolveSlackAllowedChannelIds, resolveSlackChannelTargets, resolveSlackUserTargets };