@vellumai/assistant 0.8.1 → 0.8.2

package/src/messaging/providers/slack/__tests__/adapter-token-routing.test.ts

@@ -24,13 +24,18 @@ mock.module("../../../../security/secure-keys.js", () => ({
 }));
 
 // OAuth helpers are exercised only when no bot_token is cached. The adapter
-// imports them at module load — route them through a stub that signals any
-// OAuth fallback with a distinctive error so tests can assert on it.
+// imports them at module load, so route them through a configurable stub.
 const OAUTH_FALLBACK_SENTINEL = "OAUTH_FALLBACK_NOT_STUBBED";
-mock.module("../../../../oauth/connection-resolver.js", () => ({
-  resolveOAuthConnection: async (): Promise<OAuthConnection> => {
+const resolveOAuthConnectionMock = mock(
+  async (
+    _provider: string,
+    _opts?: { account?: string },
+  ): Promise<OAuthConnection> => {
     throw new Error(OAUTH_FALLBACK_SENTINEL);
   },
+);
+mock.module("../../../../oauth/connection-resolver.js", () => ({
+  resolveOAuthConnection: resolveOAuthConnectionMock,
 }));
 mock.module("../../../../oauth/oauth-store.js", () => ({
   isProviderConnected: async () => false,
@@ -44,7 +49,7 @@ mock.module("../../../../contacts/contacts-write.js", () => ({
   upsertContactChannel: () => {},
 }));
 
-import { slackProvider } from "../adapter.js";
+import { slackProvider, withSlackBotToken } from "../adapter.js";
 
 // ── fetch capture ───────────────────────────────────────────────────────────
 
@@ -108,9 +113,23 @@ function fakeSlackResponse(url: string): Record<string, unknown> {
 const BOT_TOKEN = "xoxb-BOT";
 const USER_TOKEN = "xoxp-USER";
 
+function makeOAuthConnection(account: string, token: string): OAuthConnection {
+  return {
+    id: `conn-${account}`,
+    provider: "slack",
+    accountInfo: account,
+    request: async () => ({ status: 200, headers: {}, body: { ok: true } }),
+    withToken: async <T>(fn: (rawToken: string) => Promise<T>) => fn(token),
+  };
+}
+
 describe("Slack adapter token routing", () => {
   beforeEach(() => {
     captured.length = 0;
+    resolveOAuthConnectionMock.mockReset();
+    resolveOAuthConnectionMock.mockImplementation(async () => {
+      throw new Error(OAUTH_FALLBACK_SENTINEL);
+    });
     getSecureKeyAsyncMock.mockReset();
     getSecureKeyAsyncMock.mockImplementation(async (key: string) => {
       if (key === credentialKey("slack_channel", "bot_token")) return BOT_TOKEN;
@@ -279,4 +298,25 @@ describe("Slack adapter token routing", () => {
       OAUTH_FALLBACK_SENTINEL,
     );
   });
+
+  test("raw bot token helper resolves the requested OAuth account even when cache is warm", async () => {
+    getSecureKeyAsyncMock.mockImplementation(async () => null);
+    resolveOAuthConnectionMock.mockImplementation(
+      async (_provider: string, opts?: { account?: string }) => {
+        const account = opts?.account ?? "default";
+        return makeOAuthConnection(account, `token-${account}`);
+      },
+    );
+
+    await slackProvider.resolveConnection!("workspace-a");
+
+    const result = await withSlackBotToken("workspace-b", async (token) => {
+      return token;
+    });
+
+    expect(result).toBe("token-workspace-b");
+    expect(resolveOAuthConnectionMock).toHaveBeenCalledWith("slack", {
+      account: "workspace-b",
+    });
+  });
 });

package/src/messaging/providers/slack/__tests__/download.test.ts

@@ -0,0 +1,231 @@
+/**
+ * Unit tests for the assistant-side Slack file downloader used by the
+ * thread-backfill image-hydration path.
+ *
+ * The downloader has three contract-level behaviors worth pinning:
+ *  1. URL selection — `url_private_download` is preferred over `url_private`.
+ *  2. Bearer auth — the bot token MUST be sent on the initial request.
+ *  3. Manual cross-origin redirect handling — the CDN URL is signed and the
+ *     Authorization header MUST NOT be re-sent on the second hop (Slack
+ *     rejects the signed URL when an unexpected Authorization is present).
+ *  4. Returns null when no usable URL is present.
+ */
+
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+mock.module("../../../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+import { downloadSlackFile } from "../download.js";
+
+interface CapturedFetchCall {
+  url: string;
+  init: RequestInit | undefined;
+}
+
+let calls: CapturedFetchCall[];
+let responses: Response[];
+let originalFetch: typeof fetch;
+
+beforeEach(() => {
+  calls = [];
+  responses = [];
+  originalFetch = globalThis.fetch;
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    calls.push({
+      url: typeof input === "string" ? input : input.toString(),
+      init,
+    });
+    const next = responses.shift();
+    if (!next) {
+      throw new Error("downloadSlackFile test: no canned response available");
+    }
+    return next;
+  }) as typeof fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+describe("downloadSlackFile", () => {
+  test("returns null when neither url_private_download nor url_private is present", async () => {
+    const result = await downloadSlackFile(
+      { name: "screenshot.png", mimetype: "image/png" },
+      "xoxb-test",
+    );
+    expect(result).toBeNull();
+    expect(calls.length).toBe(0);
+  });
+
+  test("prefers url_private_download over url_private", async () => {
+    responses.push(
+      new Response(new Uint8Array([1, 2, 3]).buffer, {
+        status: 200,
+        headers: { "Content-Type": "image/png" },
+      }),
+    );
+    await downloadSlackFile(
+      {
+        id: "F1",
+        name: "shot.png",
+        mimetype: "image/png",
+        urlPrivateDownload: "https://files.slack.com/files-pri/T/F1/download",
+        urlPrivate: "https://files.slack.com/files-pri/T/F1/inline",
+      },
+      "xoxb-test",
+    );
+    expect(calls.length).toBe(1);
+    expect(calls[0].url).toBe(
+      "https://files.slack.com/files-pri/T/F1/download",
+    );
+  });
+
+  test("sends bot token as Bearer on the initial request and base64-encodes the body", async () => {
+    responses.push(
+      new Response(new Uint8Array([0xde, 0xad, 0xbe, 0xef]).buffer, {
+        status: 200,
+        headers: { "Content-Type": "image/png" },
+      }),
+    );
+    const result = await downloadSlackFile(
+      {
+        id: "F1",
+        name: "shot.png",
+        mimetype: "image/png",
+        urlPrivate: "https://files.slack.com/files-pri/T/F1/inline",
+      },
+      "xoxb-test-token",
+    );
+    expect(calls.length).toBe(1);
+    const auth = (calls[0].init?.headers as Record<string, string>)
+      ?.Authorization;
+    expect(auth).toBe("Bearer xoxb-test-token");
+    expect(calls[0].init?.redirect).toBe("manual");
+    expect(result).not.toBeNull();
+    expect(result?.filename).toBe("shot.png");
+    expect(result?.mimeType).toBe("image/png");
+    // 0xdeadbeef → "3q2+7w==" in base64.
+    expect(result?.data).toBe("3q2+7w==");
+  });
+
+  test("follows a 302 to the signed CDN URL without re-sending the bearer token", async () => {
+    responses.push(
+      new Response(null, {
+        status: 302,
+        headers: {
+          Location:
+            "https://files-edge.slack.com/files-tmb/T-F1-abc/cdn-signed?t=1700000000",
+        },
+      }),
+    );
+    responses.push(
+      new Response(new Uint8Array([1, 2]).buffer, {
+        status: 200,
+        headers: { "Content-Type": "image/jpeg" },
+      }),
+    );
+    const result = await downloadSlackFile(
+      {
+        id: "F1",
+        name: "photo.jpg",
+        mimetype: "image/jpeg",
+        urlPrivateDownload: "https://files.slack.com/files-pri/T/F1/download",
+      },
+      "xoxb-test",
+    );
+    expect(calls.length).toBe(2);
+    expect(calls[0].init?.redirect).toBe("manual");
+    const secondAuth = (calls[1].init?.headers as Record<string, string>)
+      ?.Authorization;
+    expect(secondAuth).toBeUndefined();
+    expect(calls[1].url).toBe(
+      "https://files-edge.slack.com/files-tmb/T-F1-abc/cdn-signed?t=1700000000",
+    );
+    expect(result?.data).toBe(Buffer.from([1, 2]).toString("base64"));
+  });
+
+  test("resolves a relative Location header against the original URL", async () => {
+    responses.push(
+      new Response(null, {
+        status: 302,
+        headers: { Location: "/files-tmb/cdn-signed?t=1700" },
+      }),
+    );
+    responses.push(
+      new Response(new Uint8Array([9]).buffer, {
+        status: 200,
+        headers: { "Content-Type": "image/png" },
+      }),
+    );
+    await downloadSlackFile(
+      {
+        id: "F1",
+        name: "x.png",
+        urlPrivateDownload: "https://files.slack.com/a/b/download",
+      },
+      "xoxb-test",
+    );
+    expect(calls[1].url).toBe(
+      "https://files.slack.com/files-tmb/cdn-signed?t=1700",
+    );
+  });
+
+  test("throws when the second hop responds non-2xx", async () => {
+    responses.push(
+      new Response(null, {
+        status: 302,
+        headers: { Location: "https://files-edge.slack.com/cdn?t=1" },
+      }),
+    );
+    responses.push(
+      new Response(null, { status: 403, statusText: "Forbidden" }),
+    );
+    await expect(
+      downloadSlackFile(
+        {
+          id: "F1",
+          name: "x.png",
+          urlPrivateDownload: "https://files.slack.com/a/b/download",
+        },
+        "xoxb-test",
+      ),
+    ).rejects.toThrow(/403/);
+  });
+
+  test("throws when a redirect has no Location header", async () => {
+    responses.push(new Response(null, { status: 302 }));
+    await expect(
+      downloadSlackFile(
+        {
+          id: "F1",
+          name: "x.png",
+          urlPrivateDownload: "https://files.slack.com/a/b/download",
+        },
+        "xoxb-test",
+      ),
+    ).rejects.toThrow(/no Location header/);
+  });
+
+  test("falls back to response Content-Type when file.mimetype is absent", async () => {
+    responses.push(
+      new Response(new Uint8Array([1]).buffer, {
+        status: 200,
+        headers: { "Content-Type": "image/webp; charset=binary" },
+      }),
+    );
+    const result = await downloadSlackFile(
+      {
+        id: "F1",
+        name: "photo.webp",
+        urlPrivate: "https://files.slack.com/files-pri/T/F1/inline",
+      },
+      "xoxb-test",
+    );
+    expect(result?.mimeType).toBe("image/webp");
+  });
+});

package/src/messaging/providers/slack/adapter.ts

@@ -99,6 +99,30 @@ function getWriteAuth(connection?: OAuthConnection): OAuthConnection | string {
   return getSlackAuth(connection);
 }
 
+/**
+ * Resolve the bot token (raw string) and pass it to `fn`. Returns the
+ * callback's result, or `null` when no Slack auth is available.
+ *
+ * Bridges the Socket Mode case (cached string token) and the OAuth case
+ * (`OAuthConnection.withToken`) for callers that need a raw token to hand
+ * to a non-Slack-client API call — currently `downloadSlackFile` for inline
+ * file/image fetches. Slack-client method calls should keep going through
+ * `getReadAuth` / `getWriteAuth` and pass the union through.
+ */
+export async function withSlackBotToken<T>(
+  account: string | undefined,
+  fn: (token: string) => Promise<T>,
+): Promise<T | null> {
+  // Resolve for this call's account even when the process cache is warm.
+  // Multi-workspace backfills can interleave, so use the returned connection
+  // directly instead of accepting any previously cached workspace token.
+  const resolvedAuth = await slackProvider.resolveConnection?.(account);
+  const auth = resolvedAuth ?? _cachedSlackWriteAuth;
+  if (!auth) return null;
+  if (typeof auth === "string") return fn(auth);
+  return auth.withToken(fn);
+}
+
 /**
  * Run a read-path Slack call, falling back to the bot token if the cached
  * user token is rejected with an auth error. On fallback, the read cache is
@@ -192,15 +216,31 @@ function mapConversation(conv: SlackConversation): Conversation {
   };
 }
 
-function mapSlackFiles(
-  files: SlackMessage["files"],
-): Array<{ id?: string; name: string; mimetype?: string }> | undefined {
+function mapSlackFiles(files: SlackMessage["files"]):
+  | Array<{
+      id?: string;
+      name: string;
+      mimetype?: string;
+      /**
+       * Transient — only present on the in-flight `ProviderMessage.metadata`.
+       * The persisted `slackFiles` shape carries `{ id, name, mimetype }` only
+       * (see `slackFileMetadataSchema`). Callers that hydrate image attachments
+       * during backfill rely on this URL; persistence strips it before write.
+       */
+      urlPrivateDownload?: string;
+      urlPrivate?: string;
+    }>
+  | undefined {
   if (!files || files.length === 0) return undefined;
   const mapped = files
     .map((file) => ({
       ...(file.id ? { id: file.id } : {}),
       name: file.name,
       ...(file.mimetype ? { mimetype: file.mimetype } : {}),
+      ...(file.url_private_download
+        ? { urlPrivateDownload: file.url_private_download }
+        : {}),
+      ...(file.url_private ? { urlPrivate: file.url_private } : {}),
     }))
     .filter((file) => file.name.length > 0);
   return mapped.length > 0 ? mapped : undefined;
@@ -419,8 +459,6 @@ export const slackProvider: MessagingProvider = {
       if (conv.type === "dm" && conv.metadata?.dmUserId) {
         const dmUserId = conv.metadata.dmUserId as string;
         conv.name = await resolveUserName(auth, dmUserId);
-
-
       }
     }
 

package/src/messaging/providers/slack/client.ts

@@ -20,8 +20,10 @@ import type {
   SlackConversationsListResponse,
   SlackConversationsOpenResponse,
   SlackPostMessageResponse,
+  SlackReactionsAddResponse,
   SlackSearchMessagesResponse,
   SlackUserInfoResponse,
+  SlackUsersListResponse,
 } from "./types.js";
 
 const SLACK_API_BASE = "https://slack.com/api";
@@ -432,3 +434,28 @@ export async function searchMessages(
     },
   );
 }
+
+export async function addReaction(
+  connectionOrToken: OAuthConnection | string,
+  channel: string,
+  timestamp: string,
+  name: string,
+): Promise<SlackReactionsAddResponse> {
+  return request<SlackReactionsAddResponse>(
+    connectionOrToken,
+    "reactions.add",
+    undefined,
+    { channel, timestamp, name },
+  );
+}
+
+export async function listUsers(
+  connectionOrToken: OAuthConnection | string,
+  limit = 200,
+  cursor?: string,
+): Promise<SlackUsersListResponse> {
+  return request<SlackUsersListResponse>(connectionOrToken, "users.list", {
+    limit: String(limit),
+    cursor,
+  });
+}

package/src/messaging/providers/slack/deep-link.ts

@@ -0,0 +1,65 @@
+export interface SlackMessageDeepLinks {
+  appUrl?: string;
+  webUrl?: string;
+}
+
+export function formatSlackPermalinkTimestamp(ts: string): string {
+  return ts.replace(".", "");
+}
+
+export function buildSlackAppMessageUrl(params: {
+  teamId?: string | null;
+  channelId: string;
+  messageTs: string;
+}): string | undefined {
+  const teamId = params.teamId?.trim();
+  if (!teamId) return undefined;
+
+  const search = new URLSearchParams({
+    team: teamId,
+    id: params.channelId,
+    message: params.messageTs,
+  });
+  return `slack://channel?${search.toString()}`;
+}
+
+function normalizeSlackTeamUrl(teamUrl?: string | null): string | undefined {
+  const trimmed = teamUrl?.trim();
+  if (!trimmed) return undefined;
+
+  try {
+    const parsed = new URL(trimmed);
+    if (parsed.protocol !== "https:") return undefined;
+    return parsed.toString().replace(/\/+$/, "");
+  } catch {
+    return undefined;
+  }
+}
+
+export function buildSlackWebMessageUrl(params: {
+  teamUrl?: string | null;
+  channelId: string;
+  messageTs: string;
+}): string | undefined {
+  const teamUrl = normalizeSlackTeamUrl(params.teamUrl);
+  if (!teamUrl) return undefined;
+
+  return `${teamUrl}/archives/${encodeURIComponent(
+    params.channelId,
+  )}/p${formatSlackPermalinkTimestamp(params.messageTs)}`;
+}
+
+export function buildSlackMessageDeepLinks(params: {
+  teamId?: string | null;
+  teamUrl?: string | null;
+  channelId: string;
+  messageTs: string;
+}): SlackMessageDeepLinks | undefined {
+  const appUrl = buildSlackAppMessageUrl(params);
+  const webUrl = buildSlackWebMessageUrl(params);
+  if (!appUrl && !webUrl) return undefined;
+  return {
+    ...(appUrl ? { appUrl } : {}),
+    ...(webUrl ? { webUrl } : {}),
+  };
+}

package/src/messaging/providers/slack/download.ts

@@ -0,0 +1,104 @@
+/**
+ * Slack file download for the assistant-side backfill path.
+ *
+ * The gateway runs the live inbound path and downloads files via its own
+ * `gateway/src/slack/download.ts`. The assistant cannot import that module
+ * (different package, different fetch infra), so the thread-backfill path
+ * has its own minimal downloader here.
+ *
+ * Both implementations target the same Slack contract:
+ *  - `url_private_download` (preferred) / `url_private` (fallback) are
+ *    Slack-hosted URLs requiring bot-token auth.
+ *  - Slack typically redirects to a CDN host (e.g. `files-edge.slack.com`)
+ *    where the signed redirect URL is self-authenticating; the WHATWG fetch
+ *    spec strips `Authorization` on cross-origin redirects, so we manually
+ *    follow the redirect without re-sending the bot token.
+ */
+
+import { getLogger } from "../../../util/logger.js";
+
+const log = getLogger("slack-download");
+
+export interface DownloadedSlackFile {
+  filename: string;
+  mimeType: string;
+  /** Base64-encoded file bytes. */
+  data: string;
+}
+
+export interface SlackFileDownloadInput {
+  id?: string;
+  name: string;
+  mimetype?: string;
+  urlPrivateDownload?: string;
+  urlPrivate?: string;
+}
+
+const DOWNLOAD_TIMEOUT_MS = 30_000;
+
+/**
+ * Download a Slack file using a raw bot token for authentication.
+ *
+ * The caller is responsible for resolving the token from the slack adapter
+ * (`withSlackBotToken`); this module stays decoupled from the auth-resolution
+ * dispatch so it remains trivially mockable in tests.
+ *
+ * Returns `null` when no usable URL is present on the file metadata — callers
+ * commonly pass file shapes that have already been sanitized for persistence
+ * (`{ id, name, mimetype }`) and have no way to download. This is treated as
+ * an expected branch rather than an error.
+ *
+ * Throws on transport / HTTP errors so the caller can decide whether to log
+ * and skip or fail the surrounding operation. The thread-backfill caller
+ * logs and proceeds with the text-only message rather than failing the whole
+ * backfill.
+ */
+export async function downloadSlackFile(
+  file: SlackFileDownloadInput,
+  token: string,
+): Promise<DownloadedSlackFile | null> {
+  const url = file.urlPrivateDownload ?? file.urlPrivate;
+  if (!url) {
+    log.debug(
+      { fileId: file.id, name: file.name },
+      "Slack file has no download URL; skipping",
+    );
+    return null;
+  }
+
+  let response = await fetch(url, {
+    headers: { Authorization: `Bearer ${token}` },
+    redirect: "manual",
+    signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+  });
+
+  if (response.status >= 300 && response.status < 400) {
+    const location = response.headers.get("Location");
+    if (!location) {
+      throw new Error(
+        `Slack file ${file.id ?? file.name} returned ${response.status} redirect with no Location header`,
+      );
+    }
+    // CDN redirect URLs are signed; no Authorization needed. Resolve
+    // relative locations against the original URL.
+    const resolvedLocation = new URL(location, url).href;
+    response = await fetch(resolvedLocation, {
+      signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+    });
+  }
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to download Slack file ${file.id ?? file.name}: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  const buffer = await response.arrayBuffer();
+  const mimeType =
+    file.mimetype ||
+    response.headers.get("Content-Type")?.split(";")[0]?.trim() ||
+    "application/octet-stream";
+  const filename = file.name || `slack_file_${file.id ?? "unknown"}`;
+  const data = Buffer.from(buffer).toString("base64");
+  return { filename, mimeType, data };
+}

package/src/messaging/providers/slack/message-metadata.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, test } from "bun:test";
 import {
   mergeSlackMetadata,
   readSlackMetadata,
+  readSlackMetadataFromMessageMetadata,
   type SlackMessageMetadata,
   writeSlackMetadata,
 } from "./message-metadata.js";
@@ -113,6 +114,7 @@ describe("readSlackMetadata", () => {
       channelTs: "1700000000.000100",
       threadTs: "1699999999.000000",
       displayName: "Alice",
+      actorExternalUserId: "U_ALICE",
       eventKind: "message",
       editedAt: 1700000123,
     };
@@ -138,6 +140,35 @@ describe("readSlackMetadata", () => {
   });
 });
 
+describe("readSlackMetadataFromMessageMetadata", () => {
+  const meta: SlackMessageMetadata = {
+    source: "slack",
+    channelId: "C123",
+    channelTs: "1700000000.000100",
+    threadTs: "1699999999.000000",
+    eventKind: "message",
+  };
+
+  test("reads nested slackMeta from a message metadata envelope", () => {
+    expect(
+      readSlackMetadataFromMessageMetadata(
+        JSON.stringify({
+          userMessageChannel: "slack",
+          slackMeta: writeSlackMetadata(meta),
+        }),
+      ),
+    ).toEqual(meta);
+  });
+
+  test("can read flat legacy Slack metadata when explicitly allowed", () => {
+    const raw = writeSlackMetadata(meta);
+    expect(readSlackMetadataFromMessageMetadata(raw)).toBeNull();
+    expect(
+      readSlackMetadataFromMessageMetadata(raw, { allowFlatLegacy: true }),
+    ).toEqual(meta);
+  });
+});
+
 describe("writeSlackMetadata", () => {
   test("round-trips through readSlackMetadata", () => {
     const meta: SlackMessageMetadata = {
@@ -146,6 +177,7 @@ describe("writeSlackMetadata", () => {
       channelTs: "1700000000.000100",
       threadTs: "1699999999.000000",
       displayName: "Alice",
+      actorExternalUserId: "U_ALICE",
       eventKind: "message",
     };
     const raw = writeSlackMetadata(meta);

package/src/messaging/providers/slack/message-metadata.ts

@@ -38,6 +38,7 @@ export const slackMessageMetadataSchema = z.object({
   channelTs: z.string(),
   threadTs: z.string().optional(),
   displayName: z.string().optional(),
+  actorExternalUserId: z.string().optional(),
   eventKind: z.enum(["message", "reaction"]),
   reaction: slackReactionMetadataSchema.optional(),
   editedAt: z.number().optional(),
@@ -75,6 +76,32 @@ export function readSlackMetadata(
   return result.success ? result.data : null;
 }
 
+export function readSlackMetadataFromMessageMetadata(
+  metadata: string | null | undefined,
+  opts?: { allowFlatLegacy?: boolean },
+): SlackMessageMetadata | null {
+  if (!metadata) return null;
+
+  let parent: Record<string, unknown> | null = null;
+  try {
+    const parsed = JSON.parse(metadata) as unknown;
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      parent = parsed as Record<string, unknown>;
+    }
+  } catch {
+    return null;
+  }
+  if (!parent) return null;
+
+  const nested = parent.slackMeta;
+  if (typeof nested === "string") {
+    const parsedNested = readSlackMetadata(nested);
+    if (parsedNested) return parsedNested;
+  }
+
+  return opts?.allowFlatLegacy ? readSlackMetadata(metadata) : null;
+}
+
 /**
  * Serialize `SlackMessageMetadata` to a JSON string suitable for a fresh
  * write to the `messages.metadata` column. Use `mergeSlackMetadata` when an