@devosurf/tesser-connectors 0.1.0-alpha.0

package/github/index.ts

@@ -0,0 +1,250 @@
+// GitHub connector — P0 exemplar: named auth map (OAuth + PAT), auto-registered webhook
+// trigger, poll trigger, derived retry-safety. Actions return OUR mapped stable shapes.
+
+import { z } from "zod";
+import {
+  action,
+  apiKey,
+  defineConnector,
+  oauth2,
+  trigger,
+  verify,
+} from "@devosurf/tesser-sdk/connector";
+import { githubProvider } from "../providers/github.js";
+
+const issueShape = z.object({
+  repo: z.string(),
+  number: z.number(),
+  title: z.string(),
+  url: z.string(),
+  state: z.string(),
+  author: z.string(),
+  body: z.string().nullable(),
+  labels: z.array(z.string()),
+  createdAt: z.string(),
+});
+
+type RawIssue = {
+  number: number;
+  title: string;
+  html_url: string;
+  state: string;
+  body: string | null;
+  user?: { login?: string };
+  labels?: Array<{ name?: string } | string>;
+  created_at: string;
+  repository?: { full_name?: string };
+  pull_request?: unknown;
+};
+
+function mapIssue(raw: RawIssue, repo: string): z.infer<typeof issueShape> {
+  return {
+    repo: raw.repository?.full_name ?? repo,
+    number: raw.number,
+    title: raw.title,
+    url: raw.html_url,
+    state: raw.state,
+    author: raw.user?.login ?? "unknown",
+    body: raw.body ?? null,
+    labels: (raw.labels ?? []).map((l) => (typeof l === "string" ? l : (l.name ?? ""))).filter(Boolean),
+    createdAt: raw.created_at,
+  };
+}
+
+export default defineConnector({
+  id: "github",
+  describe: "GitHub repositories, issues, and webhooks",
+  provider: githubProvider,
+  auth: {
+    oauth: oauth2({ provider: "github", scopes: ["repo"] }),
+    token: apiKey({ prefix: "Bearer ", describe: "Personal access token (repo scope)" }),
+  },
+  defaultHeaders: {
+    accept: "application/vnd.github+json",
+    "x-github-api-version": "2022-11-28",
+    "user-agent": "tesser",
+  },
+  samples: {
+    "issues.list": [
+      {
+        repo: "acme/api",
+        number: 41,
+        title: "crash on save",
+        url: "https://github.com/acme/api/issues/41",
+        state: "open",
+        author: "octocat",
+        body: "It crashes.",
+        labels: ["bug"],
+        createdAt: "2026-01-01T00:00:00Z",
+      },
+    ],
+    "issues.create": {
+      repo: "acme/api",
+      number: 42,
+      title: "sample",
+      url: "https://github.com/acme/api/issues/42",
+      state: "open",
+      author: "octocat",
+      body: null,
+      labels: [],
+      createdAt: "2026-01-01T00:00:00Z",
+    },
+    "issues.comment": { id: 1, url: "https://github.com/acme/api/issues/42#issuecomment-1" },
+    "repos.get": { fullName: "acme/api", defaultBranch: "main", private: true, description: null },
+    "trigger:issueOpened": {
+      repo: "acme/api",
+      number: 43,
+      title: "new bug",
+      url: "https://github.com/acme/api/issues/43",
+      state: "open",
+      author: "octocat",
+      body: null,
+      labels: ["bug"],
+      createdAt: "2026-01-01T00:00:00Z",
+    },
+  },
+  actions: {
+    issues: {
+      list: action({
+        describe: "List issues — across your repos, or one repo when `repo` is set",
+        input: z.object({
+          repo: z.string().optional(),
+          state: z.enum(["open", "closed", "all"]).default("open"),
+          labels: z.array(z.string()).optional(),
+          limit: z.number().int().min(1).max(100).default(30),
+        }),
+        output: z.array(issueShape),
+        safety: "read",
+        run: async (ctx, i) => {
+          const query: Record<string, string | number> = { state: i.state, per_page: i.limit };
+          if (i.labels && i.labels.length > 0) query["labels"] = i.labels.join(",");
+          const path = i.repo ? `/repos/${i.repo}/issues` : "/issues";
+          if (!i.repo) query["filter"] = "all";
+          const raw = (await ctx.http.get(path, { query })) as RawIssue[];
+          // The issues API interleaves PRs; an issues connector returns issues.
+          return raw.filter((r) => r.pull_request === undefined).map((r) => mapIssue(r, i.repo ?? ""));
+        },
+      }),
+      create: action({
+        describe: "Open an issue",
+        input: z.object({
+          repo: z.string(),
+          title: z.string().min(1),
+          body: z.string().optional(),
+          labels: z.array(z.string()).optional(),
+        }),
+        output: issueShape,
+        run: async (ctx, i) => {
+          const raw = (await ctx.http.post(`/repos/${i.repo}/issues`, {
+            title: i.title,
+            ...(i.body !== undefined ? { body: i.body } : {}),
+            ...(i.labels !== undefined ? { labels: i.labels } : {}),
+          })) as RawIssue;
+          return mapIssue(raw, i.repo);
+        },
+      }),
+      comment: action({
+        describe: "Comment on an issue",
+        input: z.object({ repo: z.string(), number: z.number().int(), body: z.string().min(1) }),
+        output: z.object({ id: z.number(), url: z.string() }),
+        run: async (ctx, i) => {
+          const raw = (await ctx.http.post(`/repos/${i.repo}/issues/${i.number}/comments`, {
+            body: i.body,
+          })) as { id: number; html_url: string };
+          return { id: raw.id, url: raw.html_url };
+        },
+      }),
+    },
+    repos: {
+      get: action({
+        describe: "Fetch one repository",
+        input: z.object({ repo: z.string() }),
+        output: z.object({
+          fullName: z.string(),
+          defaultBranch: z.string(),
+          private: z.boolean(),
+          description: z.string().nullable(),
+        }),
+        safety: "read",
+        run: async (ctx, i) => {
+          const raw = (await ctx.http.get(`/repos/${i.repo}`)) as {
+            full_name: string;
+            default_branch: string;
+            private: boolean;
+            description: string | null;
+          };
+          return {
+            fullName: raw.full_name,
+            defaultBranch: raw.default_branch,
+            private: raw.private,
+            description: raw.description ?? null,
+          };
+        },
+      }),
+    },
+  },
+  webhook: {
+    verify: verify.hmacSha256({ header: "X-Hub-Signature-256", prefix: "sha256=" }),
+    identify: (req) => {
+      const event = req.headers["x-github-event"];
+      if (!event) return null;
+      return {
+        event,
+        ...(req.headers["x-github-delivery"] !== undefined
+          ? { deliveryId: req.headers["x-github-delivery"] }
+          : {}),
+        payload: req.json,
+      };
+    },
+  },
+  triggers: {
+    issueOpened: trigger.webhook({
+      describe: "Fires when an issue is opened",
+      input: z.object({ repo: z.string() }),
+      output: issueShape,
+      event: "issues",
+      map: (payload, params) => {
+        const p = payload as { action?: string; issue?: RawIssue; repository?: { full_name?: string } };
+        if (p.action !== "opened" || !p.issue) return null;
+        const repo = p.repository?.full_name ?? params.repo;
+        if (repo !== params.repo) return null;
+        return mapIssue(p.issue, repo);
+      },
+      register: {
+        mode: "auto",
+        create: async (ctx, reg, params) => {
+          const res = (await ctx.http.post(`/repos/${params.repo}/hooks`, {
+            name: "web",
+            active: true,
+            events: ["issues"],
+            config: { url: reg.url, content_type: "json", secret: reg.secret },
+          })) as { id: number };
+          return { externalId: String(res.id) };
+        },
+        destroy: async (ctx, reg, params) => {
+          if (reg.externalId === undefined) return;
+          await ctx.http.delete(`/repos/${params.repo}/hooks/${reg.externalId}`);
+        },
+      },
+    }),
+    newIssue: trigger.poll({
+      describe: "Fires for each newly created issue (poll)",
+      input: z.object({ repo: z.string(), labels: z.array(z.string()).optional() }),
+      output: issueShape,
+      interval: { default: "2m", floor: "30s" },
+      poll: async (ctx, params) => {
+        const query: Record<string, string | number> = {
+          state: "all",
+          sort: "created",
+          direction: "desc",
+          per_page: 30,
+        };
+        if (params.labels && params.labels.length > 0) query["labels"] = params.labels.join(",");
+        const raw = (await ctx.http.get(`/repos/${params.repo}/issues`, { query })) as RawIssue[];
+        return raw.filter((r) => r.pull_request === undefined);
+      },
+      dedupeKey: (item) => String((item as RawIssue).number),
+      map: (item, params) => mapIssue(item as RawIssue, params.repo),
+    }),
+  },
+});

package/gmail/index.ts

@@ -0,0 +1,420 @@
+// Gmail connector — sits behind the shared `google` Provider (one OAuth app backs
+// gmail + google-calendar; CONTEXT.md "Provider"). Demonstrates Google's offline-access
+// refresh quirks via the provider facts.
+
+import { z } from "zod";
+import { action, defineConnector, oauth2, trigger, type ActionCtx } from "@devosurf/tesser-sdk/connector";
+import { googleProvider } from "../providers/google.js";
+
+function toBase64Url(s: string): string {
+  return Buffer.from(s).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+// RFC 2822 MIME builder → base64url, the shape Gmail's `raw` field wants. text/plain
+// unless `html` is set; threading carries In-Reply-To = the original Message-ID.
+function buildMime(opts: {
+  to: string;
+  subject: string;
+  body: string;
+  cc?: string;
+  html?: boolean;
+  inReplyTo?: string;
+}): string {
+  const lines = [`To: ${opts.to}`];
+  if (opts.cc !== undefined) lines.push(`Cc: ${opts.cc}`);
+  lines.push(`Subject: ${opts.subject}`);
+  if (opts.inReplyTo !== undefined) {
+    // In-Reply-To AND References both point at the original Message-ID (client threading).
+    lines.push(`In-Reply-To: ${opts.inReplyTo}`, `References: ${opts.inReplyTo}`);
+  }
+  lines.push(
+    `Content-Type: ${opts.html ? "text/html" : "text/plain"}; charset=utf-8`,
+    "",
+    opts.body,
+  );
+  return toBase64Url(lines.join("\r\n"));
+}
+
+const messageDetail = z.object({
+  id: z.string(),
+  threadId: z.string(),
+  from: z.string(),
+  subject: z.string(),
+  snippet: z.string(),
+  receivedAt: z.string(),
+});
+
+const labelShape = z.object({
+  id: z.string(),
+  name: z.string(),
+  type: z.string(),
+});
+
+type RawMessage = {
+  id: string;
+  threadId: string;
+  snippet?: string;
+  internalDate?: string;
+  payload?: { headers?: Array<{ name: string; value: string }> };
+};
+
+type RawLabel = { id: string; name: string; type?: string };
+
+function header(raw: RawMessage, name: string): string {
+  return raw.payload?.headers?.find((h) => h.name.toLowerCase() === name.toLowerCase())?.value ?? "";
+}
+
+function mapMessage(raw: RawMessage): z.infer<typeof messageDetail> {
+  return {
+    id: raw.id,
+    threadId: raw.threadId,
+    from: header(raw, "From"),
+    subject: header(raw, "Subject"),
+    snippet: raw.snippet ?? "",
+    receivedAt: raw.internalDate
+      ? new Date(Number(raw.internalDate)).toISOString()
+      : new Date(0).toISOString(),
+  };
+}
+
+function mapLabel(raw: RawLabel): z.infer<typeof labelShape> {
+  return { id: raw.id, name: raw.name, type: raw.type ?? "user" };
+}
+
+async function fetchMessage(ctx: ActionCtx, id: string): Promise<RawMessage> {
+  // format=metadata returns headers + snippet without the body payload.
+  return (await ctx.http.get(`/users/me/messages/${id}`, {
+    query: { format: "metadata" },
+  })) as RawMessage;
+}
+
+// Shared body for the modify family. Idempotent (re-applying the same label set is a no-op),
+// so callers set retrySafe:true.
+async function modifyMessage(
+  ctx: ActionCtx,
+  id: string,
+  change: { addLabelIds?: string[]; removeLabelIds?: string[] },
+): Promise<z.infer<typeof messageDetail>> {
+  const res = (await ctx.http.post(`/users/me/messages/${id}/modify`, {
+    addLabelIds: change.addLabelIds ?? [],
+    removeLabelIds: change.removeLabelIds ?? [],
+  })) as RawMessage;
+  // modify echoes the message metadata; map it through our stable shape.
+  return mapMessage(res);
+}
+
+export default defineConnector({
+  id: "gmail",
+  describe: "Gmail — read, send, label, draft, and organize mail as the connected account",
+  provider: googleProvider,
+  baseUrl: "https://gmail.googleapis.com/gmail/v1",
+  auth: oauth2({
+    provider: "google",
+    scopes: [
+      "https://www.googleapis.com/auth/gmail.readonly",
+      "https://www.googleapis.com/auth/gmail.send",
+      "https://www.googleapis.com/auth/gmail.modify",
+      "https://www.googleapis.com/auth/gmail.labels",
+    ],
+  }),
+  samples: {
+    "messages.list": [{ id: "18c2f0a", threadId: "18c2f0a", snippet: "sample message" }],
+    "messages.send": { id: "18c2f0b", threadId: "18c2f0b" },
+    "messages.get": {
+      id: "18c2f0a",
+      threadId: "18c2f0a",
+      from: "Ada <ada@example.com>",
+      subject: "sample subject",
+      snippet: "sample message",
+      receivedAt: "2026-01-01T00:00:00.000Z",
+    },
+    "messages.modify": {
+      id: "18c2f0a",
+      threadId: "18c2f0a",
+      from: "Ada <ada@example.com>",
+      subject: "sample subject",
+      snippet: "sample message",
+      receivedAt: "2026-01-01T00:00:00.000Z",
+    },
+    "messages.markRead": {
+      id: "18c2f0a",
+      threadId: "18c2f0a",
+      from: "Ada <ada@example.com>",
+      subject: "sample subject",
+      snippet: "sample message",
+      receivedAt: "2026-01-01T00:00:00.000Z",
+    },
+    "messages.archive": {
+      id: "18c2f0a",
+      threadId: "18c2f0a",
+      from: "Ada <ada@example.com>",
+      subject: "sample subject",
+      snippet: "sample message",
+      receivedAt: "2026-01-01T00:00:00.000Z",
+    },
+    "messages.trash": { id: "18c2f0a", threadId: "18c2f0a" },
+    "messages.attachments.get": { attachmentId: "ANGjdJ8", size: 1234, data: "aGVsbG8" },
+    "labels.list": [
+      { id: "INBOX", name: "INBOX", type: "system" },
+      { id: "Label_12", name: "Receipts", type: "user" },
+    ],
+    "labels.create": { id: "Label_42", name: "Receipts", type: "user" },
+    "drafts.create": { id: "r-123", messageId: "18c2f0d", threadId: "18c2f0d" },
+    "drafts.send": { id: "18c2f0e", threadId: "18c2f0e" },
+    "threads.get": {
+      id: "18c2f0a",
+      historyId: "99",
+      messages: [
+        {
+          id: "18c2f0a",
+          threadId: "18c2f0a",
+          from: "Ada <ada@example.com>",
+          subject: "sample subject",
+          snippet: "sample message",
+          receivedAt: "2026-01-01T00:00:00.000Z",
+        },
+      ],
+    },
+    "trigger:messageReceived": {
+      id: "18c2f0c",
+      threadId: "18c2f0c",
+      from: "Ada <ada@example.com>",
+      subject: "new mail",
+      snippet: "hello there",
+      receivedAt: "2026-01-01T00:00:00.000Z",
+    },
+  },
+  actions: {
+    messages: {
+      list: action({
+        describe: "List message ids matching a Gmail query",
+        input: z.object({
+          q: z.string().optional(),
+          maxResults: z.number().int().min(1).max(100).default(10),
+        }),
+        output: z.array(z.object({ id: z.string(), threadId: z.string(), snippet: z.string() })),
+        safety: "read",
+        run: async (ctx, i) => {
+          const res = (await ctx.http.get("/users/me/messages", {
+            query: { maxResults: i.maxResults, ...(i.q !== undefined ? { q: i.q } : {}) },
+          })) as { messages?: Array<{ id: string; threadId: string }> };
+          const out = [] as Array<{ id: string; threadId: string; snippet: string }>;
+          for (const m of res.messages ?? []) {
+            const full = (await ctx.http.get(`/users/me/messages/${m.id}`, {
+              query: { format: "metadata" },
+            })) as { snippet?: string };
+            out.push({ id: m.id, threadId: m.threadId, snippet: full.snippet ?? "" });
+          }
+          return out;
+        },
+      }),
+      send: action({
+        describe: "Send an email (plain text or HTML; optional cc and reply threading)",
+        input: z.object({
+          to: z.string().min(3),
+          subject: z.string(),
+          text: z.string(),
+          html: z.boolean().optional(),
+          cc: z.string().optional(),
+          // Reply into an existing conversation: threadId AND the original Message-ID.
+          threadId: z.string().optional(),
+          inReplyTo: z.string().optional(),
+        }),
+        output: z.object({ id: z.string(), threadId: z.string() }),
+        run: async (ctx, i) => {
+          const raw = buildMime({
+            to: i.to,
+            subject: i.subject,
+            body: i.text,
+            ...(i.cc !== undefined ? { cc: i.cc } : {}),
+            ...(i.html !== undefined ? { html: i.html } : {}),
+            ...(i.inReplyTo !== undefined ? { inReplyTo: i.inReplyTo } : {}),
+          });
+          const res = (await ctx.http.post("/users/me/messages/send", {
+            raw,
+            ...(i.threadId !== undefined ? { threadId: i.threadId } : {}),
+          })) as { id: string; threadId: string };
+          return { id: res.id, threadId: res.threadId };
+        },
+      }),
+      get: action({
+        describe: "Fetch one message's headers + snippet",
+        input: z.object({ id: z.string().min(1) }),
+        output: messageDetail,
+        safety: "read",
+        run: async (ctx, i) => mapMessage(await fetchMessage(ctx, i.id)),
+      }),
+      modify: action({
+        describe: "Add and/or remove labels on a message",
+        input: z.object({
+          id: z.string().min(1),
+          addLabelIds: z.array(z.string()).optional(),
+          removeLabelIds: z.array(z.string()).optional(),
+        }),
+        output: messageDetail,
+        // Re-applying the same label set is a no-op → safe to retry transient 5xx.
+        retrySafe: true,
+        run: async (ctx, i) =>
+          modifyMessage(ctx, i.id, {
+            ...(i.addLabelIds !== undefined ? { addLabelIds: i.addLabelIds } : {}),
+            ...(i.removeLabelIds !== undefined ? { removeLabelIds: i.removeLabelIds } : {}),
+          }),
+      }),
+      markRead: action({
+        describe: "Mark a message read (removes the UNREAD label)",
+        input: z.object({ id: z.string().min(1) }),
+        output: messageDetail,
+        retrySafe: true,
+        run: async (ctx, i) => modifyMessage(ctx, i.id, { removeLabelIds: ["UNREAD"] }),
+      }),
+      archive: action({
+        describe: "Archive a message (removes the INBOX label)",
+        input: z.object({ id: z.string().min(1) }),
+        output: messageDetail,
+        retrySafe: true,
+        run: async (ctx, i) => modifyMessage(ctx, i.id, { removeLabelIds: ["INBOX"] }),
+      }),
+      trash: action({
+        describe: "Move a message to the trash",
+        input: z.object({ id: z.string().min(1) }),
+        output: z.object({ id: z.string(), threadId: z.string() }),
+        // Trashing an already-trashed message is a no-op → retry-safe.
+        retrySafe: true,
+        run: async (ctx, i) => {
+          const res = (await ctx.http.post(`/users/me/messages/${i.id}/trash`, {})) as {
+            id: string;
+            threadId: string;
+          };
+          return { id: res.id, threadId: res.threadId };
+        },
+      }),
+      attachments: {
+        get: action({
+          describe: "Download one message attachment (base64url data)",
+          input: z.object({ messageId: z.string().min(1), id: z.string().min(1) }),
+          output: z.object({ attachmentId: z.string(), size: z.number(), data: z.string() }),
+          safety: "read",
+          run: async (ctx, i) => {
+            const res = (await ctx.http.get(
+              `/users/me/messages/${i.messageId}/attachments/${i.id}`,
+            )) as { attachmentId?: string; size?: number; data?: string };
+            return { attachmentId: res.attachmentId ?? i.id, size: res.size ?? 0, data: res.data ?? "" };
+          },
+        }),
+      },
+    },
+    labels: {
+      list: action({
+        describe: "List all labels (resolve a label name to its id)",
+        input: z.object({}),
+        output: z.array(labelShape),
+        safety: "read",
+        run: async (ctx) => {
+          const res = (await ctx.http.get("/users/me/labels")) as { labels?: RawLabel[] };
+          return (res.labels ?? []).map(mapLabel);
+        },
+      }),
+      create: action({
+        describe: "Create a user label",
+        input: z.object({
+          name: z.string().min(1),
+          labelListVisibility: z.enum(["labelShow", "labelShowIfUnread", "labelHide"]).optional(),
+          messageListVisibility: z.enum(["show", "hide"]).optional(),
+        }),
+        output: labelShape,
+        // 409 on a duplicate name (terminal); creation is NOT idempotent → no retrySafe.
+        run: async (ctx, i) => {
+          const res = (await ctx.http.post("/users/me/labels", {
+            name: i.name,
+            ...(i.labelListVisibility !== undefined ? { labelListVisibility: i.labelListVisibility } : {}),
+            ...(i.messageListVisibility !== undefined ? { messageListVisibility: i.messageListVisibility } : {}),
+          })) as RawLabel;
+          return mapLabel(res);
+        },
+      }),
+    },
+    drafts: {
+      create: action({
+        describe: "Create a draft from a plain-text or HTML message",
+        input: z.object({
+          to: z.string().min(3),
+          subject: z.string(),
+          text: z.string(),
+          html: z.boolean().optional(),
+          cc: z.string().optional(),
+          threadId: z.string().optional(),
+        }),
+        output: z.object({ id: z.string(), messageId: z.string(), threadId: z.string() }),
+        run: async (ctx, i) => {
+          const raw = buildMime({
+            to: i.to,
+            subject: i.subject,
+            body: i.text,
+            ...(i.cc !== undefined ? { cc: i.cc } : {}),
+            ...(i.html !== undefined ? { html: i.html } : {}),
+          });
+          const res = (await ctx.http.post("/users/me/drafts", {
+            message: { raw, ...(i.threadId !== undefined ? { threadId: i.threadId } : {}) },
+          })) as { id: string; message?: { id: string; threadId: string } };
+          return { id: res.id, messageId: res.message?.id ?? "", threadId: res.message?.threadId ?? "" };
+        },
+      }),
+      send: action({
+        describe: "Send an existing draft (the draft id goes in the body, not the path)",
+        input: z.object({ id: z.string().min(1) }),
+        output: z.object({ id: z.string(), threadId: z.string() }),
+        // POST /users/me/drafts/send with { id } in the body — NO {id} path segment.
+        // Sending is NOT idempotent (double-send) → no retrySafe.
+        run: async (ctx, i) => {
+          const res = (await ctx.http.post("/users/me/drafts/send", { id: i.id })) as {
+            id: string;
+            threadId: string;
+          };
+          return { id: res.id, threadId: res.threadId };
+        },
+      }),
+    },
+    threads: {
+      get: action({
+        describe: "Fetch a whole conversation (all messages in one call)",
+        input: z.object({ id: z.string().min(1) }),
+        output: z.object({
+          id: z.string(),
+          historyId: z.string(),
+          messages: z.array(messageDetail),
+        }),
+        safety: "read",
+        run: async (ctx, i) => {
+          const res = (await ctx.http.get(`/users/me/threads/${i.id}`, {
+            query: { format: "metadata" },
+          })) as { id: string; historyId?: string; messages?: RawMessage[] };
+          return {
+            id: res.id,
+            historyId: res.historyId ?? "",
+            messages: (res.messages ?? []).map(mapMessage),
+          };
+        },
+      }),
+    },
+  },
+  triggers: {
+    messageReceived: trigger.poll({
+      describe: "Fires for each new email in the connected inbox (optionally matching a Gmail query)",
+      input: z.object({ q: z.string().optional() }),
+      output: messageDetail,
+      interval: { default: "1m", floor: "30s" },
+      order: "newest-first",
+      poll: async (ctx, params) => {
+        const list = (await ctx.http.get("/users/me/messages", {
+          query: { maxResults: 15, q: params.q ?? "in:inbox" },
+        })) as { messages?: Array<{ id: string }> };
+        // Enrich here (map() has no ctx by design): 15 metadata gets per poll, worst case.
+        const out: RawMessage[] = [];
+        for (const m of list.messages ?? []) out.push(await fetchMessage(ctx, m.id));
+        return out;
+      },
+      dedupeKey: (raw) => raw.id,
+      map: (raw) => mapMessage(raw),
+    }),
+  },
+});