@devosurf/tesser-connectors 0.1.0-alpha.0

package/slack/index.ts

@@ -0,0 +1,587 @@
+// Slack connector — P0 exemplar: 200-with-{ok:false} error mapping inside actions,
+// slackSigning verification, url_verification challenge, MANUAL webhook registration
+// (Slack's Request URL is app-level config with no per-install API, ADR-0013).
+
+import { z } from "zod";
+import { TerminalError, RetryableError } from "@devosurf/tesser-sdk";
+import { action, apiKey, defineConnector, oauth2, trigger, verify, type ActionCtx } from "@devosurf/tesser-sdk/connector";
+import { slackProvider } from "../providers/slack.js";
+
+// Slack answers 200 with { ok: false, error } — surface it with retry semantics.
+function assertOk<T extends { ok?: boolean; error?: string }>(res: T, what: string): T {
+  if (res.ok === false) {
+    const code = res.error ?? "unknown_error";
+    if (code === "ratelimited" || code === "rate_limited") {
+      throw new RetryableError(`${what}: slack rate-limited`);
+    }
+    throw new TerminalError(`${what}: slack responded ok=false (${code})`);
+  }
+  return res;
+}
+
+// Cursor pagination: loop response_metadata.next_cursor, accumulating via `pick`, with a
+// page cap so a runaway cursor can never spin forever. Slack reads are GETs.
+async function cursorPaginate<Row>(
+  ctx: ActionCtx,
+  path: string,
+  query: Record<string, string | number>,
+  pick: (page: SlackOk) => Row[] | undefined,
+  what: string,
+  pageCap = 10,
+): Promise<Row[]> {
+  const out: Row[] = [];
+  let cursor = "";
+  for (let page = 0; page < pageCap; page++) {
+    const res = assertOk(
+      (await ctx.http.get(path, {
+        query: { ...query, ...(cursor ? { cursor } : {}) },
+      })) as SlackOk,
+      what,
+    );
+    out.push(...(pick(res) ?? []));
+    cursor = res.response_metadata?.next_cursor ?? "";
+    if (!cursor) break;
+  }
+  return out;
+}
+
+type SlackOk = {
+  ok: boolean;
+  error?: string;
+  response_metadata?: { next_cursor?: string };
+  [k: string]: unknown;
+};
+
+// ---- Stable output shapes (never the raw provider blob) ----
+
+const messageShape = z.object({
+  ts: z.string(),
+  user: z.string(),
+  text: z.string(),
+  threadTs: z.string().optional(),
+  subtype: z.string().optional(),
+});
+
+type RawMessage = {
+  ts?: string;
+  user?: string;
+  text?: string;
+  thread_ts?: string;
+  subtype?: string;
+};
+
+function mapMessage(m: RawMessage): z.infer<typeof messageShape> {
+  return {
+    ts: m.ts ?? "",
+    user: m.user ?? "",
+    text: m.text ?? "",
+    ...(m.thread_ts !== undefined ? { threadTs: m.thread_ts } : {}),
+    ...(m.subtype !== undefined ? { subtype: m.subtype } : {}),
+  };
+}
+
+const channelShape = z.object({
+  id: z.string(),
+  name: z.string(),
+  isPrivate: z.boolean(),
+  topic: z.string(),
+  purpose: z.string(),
+  numMembers: z.number().optional(),
+});
+
+type RawChannel = {
+  id?: string;
+  name?: string;
+  is_private?: boolean;
+  topic?: { value?: string };
+  purpose?: { value?: string };
+  num_members?: number;
+};
+
+function mapChannel(c: RawChannel): z.infer<typeof channelShape> {
+  return {
+    id: c.id ?? "",
+    name: c.name ?? "",
+    isPrivate: c.is_private ?? false,
+    topic: c.topic?.value ?? "",
+    purpose: c.purpose?.value ?? "",
+    ...(c.num_members !== undefined ? { numMembers: c.num_members } : {}),
+  };
+}
+
+const userShape = z.object({
+  id: z.string(),
+  name: z.string(),
+  realName: z.string(),
+  email: z.string().optional(),
+  tz: z.string(),
+  isBot: z.boolean(),
+  isAdmin: z.boolean(),
+});
+
+type RawUser = {
+  id?: string;
+  name?: string;
+  real_name?: string;
+  tz?: string;
+  is_bot?: boolean;
+  is_admin?: boolean;
+  profile?: { real_name?: string; email?: string };
+};
+
+function mapUser(u: RawUser): z.infer<typeof userShape> {
+  const email = u.profile?.email;
+  return {
+    id: u.id ?? "",
+    name: u.name ?? "",
+    realName: u.real_name ?? u.profile?.real_name ?? "",
+    ...(email !== undefined ? { email } : {}),
+    tz: u.tz ?? "",
+    isBot: u.is_bot ?? false,
+    isAdmin: u.is_admin ?? false,
+  };
+}
+
+export default defineConnector({
+  id: "slack",
+  describe: "Slack messaging",
+  provider: slackProvider,
+  auth: {
+    // message.* events require the matching *:history scope; app_mention requires
+    // app_mentions:read; reactions require reactions:read. Scopes are declared once.
+    oauth: oauth2({
+      provider: "slack",
+      scopes: [
+        "chat:write",
+        "chat:write.public",
+        "channels:read",
+        "channels:history",
+        "groups:history",
+        "im:history",
+        "mpim:history",
+        "app_mentions:read",
+        "reactions:read",
+        "users:read",
+        "users:read.email",
+      ],
+    }),
+    token: apiKey({ prefix: "Bearer ", describe: "Bot token (xoxb-…) with chat:write" }),
+  },
+  samples: {
+    "chat.postMessage": { ts: "1718000000.000100", channel: "C0TESSER01" },
+    "chat.update": { channel: "C0TESSER01", ts: "1718000000.000100", text: "edited" },
+    "chat.delete": { channel: "C0TESSER01", ts: "1718000000.000100" },
+    "chat.postEphemeral": { messageTs: "1718000000.000300" },
+    "conversations.list": [{ id: "C0TESSER01", name: "tesser-test", isPrivate: false }],
+    "conversations.history": [{ ts: "1718000000.000200", user: "U123", text: "hello" }],
+    "conversations.replies": [
+      { ts: "1718000000.000200", user: "U123", text: "parent", threadTs: "1718000000.000200" },
+      { ts: "1718000000.000400", user: "U456", text: "reply", threadTs: "1718000000.000200" },
+    ],
+    "conversations.info": {
+      id: "C0TESSER01",
+      name: "tesser-test",
+      isPrivate: false,
+      topic: "shipping tesser",
+      purpose: "the test channel",
+      numMembers: 3,
+    },
+    "reactions.add": { added: true },
+    "users.info": {
+      id: "U123",
+      name: "ada",
+      realName: "Ada Lovelace",
+      email: "ada@example.com",
+      tz: "America/New_York",
+      isBot: false,
+      isAdmin: true,
+    },
+    "users.lookupByEmail": {
+      id: "U123",
+      name: "ada",
+      realName: "Ada Lovelace",
+      email: "ada@example.com",
+      tz: "America/New_York",
+      isBot: false,
+      isAdmin: true,
+    },
+    "trigger:messagePosted": {
+      channel: "C0TESSER01",
+      user: "U123",
+      text: "hello",
+      ts: "1718000000.000200",
+    },
+    "trigger:appMention": {
+      channel: "C0TESSER01",
+      user: "U123",
+      text: "<@U0BOT> ship it",
+      ts: "1718000000.000500",
+    },
+    "trigger:reactionAdded": {
+      reaction: "thumbsup",
+      user: "U123",
+      channel: "C0TESSER01",
+      messageTs: "1718000000.000200",
+    },
+  },
+  actions: {
+    chat: {
+      postMessage: action({
+        describe: "Post a message to a channel the app is in",
+        input: z.object({
+          channel: z.string().min(1),
+          text: z.string().min(1),
+          threadTs: z.string().optional(),
+        }),
+        output: z.object({ ts: z.string(), channel: z.string() }),
+        run: async (ctx, i) => {
+          const res = assertOk(
+            (await ctx.http.post("/chat.postMessage", {
+              channel: i.channel,
+              text: i.text,
+              ...(i.threadTs !== undefined ? { thread_ts: i.threadTs } : {}),
+            })) as { ok: boolean; error?: string; ts?: string; channel?: string },
+            "chat.postMessage",
+          );
+          return { ts: res.ts ?? "", channel: res.channel ?? i.channel };
+        },
+      }),
+      // Edits only messages the same token authored. ts is a string id, never a number.
+      update: action({
+        describe: "Edit a message the app posted",
+        input: z.object({
+          channel: z.string().min(1),
+          ts: z.string().min(1),
+          text: z.string().min(1),
+        }),
+        output: z.object({ channel: z.string(), ts: z.string(), text: z.string() }),
+        run: async (ctx, i) => {
+          const res = assertOk(
+            (await ctx.http.post("/chat.update", {
+              channel: i.channel,
+              ts: i.ts,
+              text: i.text,
+            })) as { ok: boolean; error?: string; channel?: string; ts?: string; text?: string },
+            "chat.update",
+          );
+          return { channel: res.channel ?? i.channel, ts: res.ts ?? i.ts, text: res.text ?? i.text };
+        },
+      }),
+      delete: action({
+        describe: "Delete a message the app posted",
+        input: z.object({ channel: z.string().min(1), ts: z.string().min(1) }),
+        output: z.object({ channel: z.string(), ts: z.string() }),
+        run: async (ctx, i) => {
+          const res = assertOk(
+            (await ctx.http.post("/chat.delete", { channel: i.channel, ts: i.ts })) as {
+              ok: boolean;
+              error?: string;
+              channel?: string;
+              ts?: string;
+            },
+            "chat.delete",
+          );
+          return { channel: res.channel ?? i.channel, ts: res.ts ?? i.ts };
+        },
+      }),
+      // Ephemeral: only `user` sees it; returns message_ts, not channel.
+      postEphemeral: action({
+        describe: "Post a message only one user can see",
+        input: z.object({
+          channel: z.string().min(1),
+          user: z.string().min(1),
+          text: z.string().min(1),
+          threadTs: z.string().optional(),
+        }),
+        output: z.object({ messageTs: z.string() }),
+        run: async (ctx, i) => {
+          const res = assertOk(
+            (await ctx.http.post("/chat.postEphemeral", {
+              channel: i.channel,
+              user: i.user,
+              text: i.text,
+              ...(i.threadTs !== undefined ? { thread_ts: i.threadTs } : {}),
+            })) as { ok: boolean; error?: string; message_ts?: string },
+            "chat.postEphemeral",
+          );
+          return { messageTs: res.message_ts ?? "" };
+        },
+      }),
+    },
+    conversations: {
+      list: action({
+        describe: "List channels visible to the app",
+        input: z.object({ limit: z.number().int().min(1).max(1000).default(100) }),
+        output: z.array(z.object({ id: z.string(), name: z.string(), isPrivate: z.boolean() })),
+        safety: "read",
+        run: async (ctx, i) => {
+          // Filtering is post-page, so a page may return fewer than `limit` while the cursor
+          // is still non-empty — keep paging on the cursor, not the count.
+          const rows = await cursorPaginate<{ id?: string; name?: string; is_private?: boolean }>(
+            ctx,
+            "/conversations.list",
+            { limit: i.limit, types: "public_channel,private_channel" },
+            (page) => page["channels"] as Array<{ id?: string; name?: string; is_private?: boolean }> | undefined,
+            "conversations.list",
+          );
+          return rows.map((c) => ({ id: c.id ?? "", name: c.name ?? "", isPrivate: c.is_private ?? false }));
+        },
+      }),
+      history: action({
+        describe: "Read recent messages in a channel (cursor-paginated, newest first)",
+        input: z.object({
+          channel: z.string().min(1),
+          limit: z.number().int().min(1).max(999).default(100),
+          oldest: z.string().optional(),
+          latest: z.string().optional(),
+        }),
+        output: z.array(messageShape),
+        safety: "read",
+        run: async (ctx, i) => {
+          const rows = await cursorPaginate<RawMessage>(
+            ctx,
+            "/conversations.history",
+            {
+              channel: i.channel,
+              limit: i.limit,
+              ...(i.oldest !== undefined ? { oldest: i.oldest } : {}),
+              ...(i.latest !== undefined ? { latest: i.latest } : {}),
+            },
+            (page) => page["messages"] as RawMessage[] | undefined,
+            "conversations.history",
+          );
+          return rows.map(mapMessage);
+        },
+      }),
+      replies: action({
+        describe: "Read all messages in a thread (cursor-paginated)",
+        input: z.object({
+          channel: z.string().min(1),
+          ts: z.string().min(1),
+          limit: z.number().int().min(1).max(999).default(100),
+        }),
+        output: z.array(messageShape),
+        safety: "read",
+        run: async (ctx, i) => {
+          const rows = await cursorPaginate<RawMessage>(
+            ctx,
+            "/conversations.replies",
+            { channel: i.channel, ts: i.ts, limit: i.limit },
+            (page) => page["messages"] as RawMessage[] | undefined,
+            "conversations.replies",
+          );
+          return rows.map(mapMessage);
+        },
+      }),
+      info: action({
+        describe: "Fetch one channel's metadata",
+        input: z.object({ channel: z.string().min(1) }),
+        output: channelShape,
+        safety: "read",
+        run: async (ctx, i) => {
+          const res = assertOk(
+            (await ctx.http.get("/conversations.info", {
+              query: { channel: i.channel, include_num_members: "true" },
+            })) as { ok: boolean; error?: string; channel?: RawChannel },
+            "conversations.info",
+          );
+          return mapChannel(res.channel ?? {});
+        },
+      }),
+    },
+    reactions: {
+      add: action({
+        describe: "Add an emoji reaction to a message",
+        input: z.object({
+          channel: z.string().min(1),
+          name: z.string().min(1),
+          timestamp: z.string().min(1),
+        }),
+        output: z.object({ added: z.boolean() }),
+        run: async (ctx, i) => {
+          assertOk(
+            (await ctx.http.post("/reactions.add", {
+              channel: i.channel,
+              name: i.name,
+              timestamp: i.timestamp,
+            })) as { ok: boolean; error?: string },
+            "reactions.add",
+          );
+          return { added: true };
+        },
+      }),
+    },
+    users: {
+      info: action({
+        describe: "Fetch one user's profile (email needs users:read.email)",
+        input: z.object({ user: z.string().min(1) }),
+        output: userShape,
+        safety: "read",
+        run: async (ctx, i) => {
+          const res = assertOk(
+            (await ctx.http.get("/users.info", { query: { user: i.user } })) as {
+              ok: boolean;
+              error?: string;
+              user?: RawUser;
+            },
+            "users.info",
+          );
+          return mapUser(res.user ?? {});
+        },
+      }),
+      // Returns users_not_found (ok:false) when no match -> terminal via assertOk.
+      lookupByEmail: action({
+        describe: "Find a user by email (needs users:read.email)",
+        input: z.object({ email: z.string().min(3) }),
+        output: userShape,
+        safety: "read",
+        run: async (ctx, i) => {
+          const res = assertOk(
+            (await ctx.http.get("/users.lookupByEmail", { query: { email: i.email } })) as {
+              ok: boolean;
+              error?: string;
+              user?: RawUser;
+            },
+            "users.lookupByEmail",
+          );
+          return mapUser(res.user ?? {});
+        },
+      }),
+    },
+  },
+  webhook: {
+    verify: verify.slackSigning(),
+    challenge: (req) => {
+      const body = req.json as { type?: string; challenge?: string } | undefined;
+      return body?.type === "url_verification" && typeof body.challenge === "string"
+        ? body.challenge
+        : null;
+    },
+    identify: (req) => {
+      const body = req.json as
+        | {
+            type?: string;
+            event_id?: string;
+            team_id?: string;
+            event?: { type?: string };
+          }
+        | undefined;
+      if (!body || body.type !== "event_callback" || !body.event?.type) return null;
+      return {
+        event: body.event.type,
+        ...(body.event_id !== undefined ? { deliveryId: body.event_id } : {}),
+        ...(body.team_id !== undefined ? { connectionHint: body.team_id } : {}),
+        payload: body,
+      };
+    },
+  },
+  triggers: {
+    messagePosted: trigger.webhook({
+      describe: "Fires for each message posted in a channel the app is in",
+      input: z.object({ channel: z.string().optional() }),
+      output: z.object({
+        channel: z.string(),
+        user: z.string(),
+        text: z.string(),
+        ts: z.string(),
+      }),
+      event: "message",
+      map: (payload, params) => {
+        const body = payload as {
+          event?: { channel?: string; user?: string; text?: string; ts?: string; bot_id?: string; subtype?: string };
+        };
+        const e = body.event;
+        if (!e?.channel || !e.ts || e.bot_id !== undefined || e.subtype !== undefined) return null;
+        if (params.channel !== undefined && e.channel !== params.channel) return null;
+        return { channel: e.channel, user: e.user ?? "", text: e.text ?? "", ts: e.ts };
+      },
+      register: {
+        mode: "manual",
+        instructions: (reg) =>
+          [
+            "Slack delivers events to one app-level Request URL — registration is in your Slack app settings:",
+            "1. Open https://api.slack.com/apps → your app → Event Subscriptions.",
+            "2. Toggle Enable Events on.",
+            `3. Paste this Request URL: ${reg.url}`,
+            "   (Slack sends a url_verification challenge; this endpoint answers it automatically.)",
+            "4. Under Subscribe to bot events, add message.channels (and message.groups / message.im / message.mpim for private channels, DMs, and group DMs).",
+            "   Each message.* event needs its matching history scope: channels:history / groups:history / im:history / mpim:history.",
+            "   For the app-mention trigger, also add app_mention under bot events (scope app_mentions:read).",
+            "5. Save, then reinstall the app when Slack prompts you (adding any bot event scope requires a reinstall).",
+            `6. Signing secret: paste your app's Signing Secret (Settings → Basic Information) into the connect page — Tesser verifies every delivery with it.`,
+          ].join("\n"),
+      },
+    }),
+    appMention: trigger.webhook({
+      describe: "Fires when the app is @-mentioned in a channel",
+      input: z.object({ channel: z.string().optional() }),
+      output: z.object({
+        channel: z.string(),
+        user: z.string(),
+        text: z.string(),
+        ts: z.string(),
+      }),
+      event: "app_mention",
+      // app_mention never echoes the bot's own posts, so no bot_id filter is needed.
+      map: (payload, params) => {
+        const body = payload as {
+          event?: { channel?: string; user?: string; text?: string; ts?: string };
+        };
+        const e = body.event;
+        if (!e?.channel || !e.ts) return null;
+        if (params.channel !== undefined && e.channel !== params.channel) return null;
+        return { channel: e.channel, user: e.user ?? "", text: e.text ?? "", ts: e.ts };
+      },
+      register: {
+        mode: "manual",
+        instructions: (reg) =>
+          [
+            "Slack delivers events to one app-level Request URL — registration is in your Slack app settings:",
+            "1. Open https://api.slack.com/apps → your app → Event Subscriptions.",
+            "2. Toggle Enable Events on.",
+            `3. Paste this Request URL: ${reg.url}`,
+            "   (Slack sends a url_verification challenge; this endpoint answers it automatically.)",
+            "4. Under Subscribe to bot events, add app_mention (scope app_mentions:read).",
+            "5. Save, then reinstall the app when Slack prompts you (adding any bot event scope requires a reinstall).",
+            `6. Signing secret: paste your app's Signing Secret (Settings → Basic Information) into the connect page — Tesser verifies every delivery with it.`,
+          ].join("\n"),
+      },
+    }),
+    reactionAdded: trigger.webhook({
+      describe: "Fires when someone adds an emoji reaction to a message",
+      input: z.object({ channel: z.string().optional() }),
+      output: z.object({
+        reaction: z.string(),
+        user: z.string(),
+        channel: z.string(),
+        messageTs: z.string(),
+      }),
+      event: "reaction_added",
+      // item may be a file/file_comment (no channel/ts) — skip those.
+      map: (payload, params) => {
+        const body = payload as {
+          event?: { reaction?: string; user?: string; item?: { channel?: string; ts?: string } };
+        };
+        const e = body.event;
+        const item = e?.item;
+        if (!e?.reaction || !item?.channel || !item.ts) return null;
+        if (params.channel !== undefined && item.channel !== params.channel) return null;
+        return { reaction: e.reaction, user: e.user ?? "", channel: item.channel, messageTs: item.ts };
+      },
+      register: {
+        mode: "manual",
+        instructions: (reg) =>
+          [
+            "Slack delivers events to one app-level Request URL — registration is in your Slack app settings:",
+            "1. Open https://api.slack.com/apps → your app → Event Subscriptions.",
+            "2. Toggle Enable Events on.",
+            `3. Paste this Request URL: ${reg.url}`,
+            "   (Slack sends a url_verification challenge; this endpoint answers it automatically.)",
+            "4. Under Subscribe to bot events, add reaction_added (scope reactions:read).",
+            "5. Save, then reinstall the app when Slack prompts you (adding any bot event scope requires a reinstall).",
+            `6. Signing secret: paste your app's Signing Secret (Settings → Basic Information) into the connect page — Tesser verifies every delivery with it.`,
+          ].join("\n"),
+      },
+    }),
+  },
+});