Add Slack modern file upload parity

- Add stateful Slack external upload sessions, file records, reads, lists, and deletes.

- Share uploaded files as Slack file_share messages with file events and inspector visibility.

- Cover SDK uploadV2, binary upload, routes, docs, and coverage matrix updates.

Author: ctate

README.md

@@ -265,13 +265,13 @@ slack:
       name: My Slack App
       redirect_uris:
         - http://localhost:3000/api/auth/callback/slack
-      scopes: [chat:write, channels:read, users.profile:read, users.profile:write, users:write]
+      scopes: [chat:write, channels:read, users.profile:read, users.profile:write, users:write, files:read, files:write]
       user_scopes: [users:read, users.profile:read]
       bot_name: my-bot
   tokens:
     - token: xoxb-local-test
       user: developer
-      scopes: [chat:write, channels:read, users.profile:read, users.profile:write, users:write]
+      scopes: [chat:write, channels:read, users.profile:read, users.profile:write, users:write, files:read, files:write]
   strict_scopes: false
 
 apple:
@@ -612,7 +612,7 @@ OAuth 2.0, OpenID Connect, and mutable Google Workspace-style surfaces for local
 
 ## Slack API
 
-Fully stateful Slack Web API emulation with channels, messages, threads, reactions, user profiles, presence, OAuth v2, and incoming webhooks. Chat writes preserve common rich message fields such as `blocks`, `attachments`, `metadata`, formatting flags, unfurl flags, and client message ids. Conversation writes update archive state, names, topics, purposes, membership, DMs, MPIMs, and read cursors. User writes update profile fields, status, custom fields, and deterministic active or away presence. Seeded OAuth apps and OAuth installs create bot users and installation records. OAuth exchanges and explicit token seeds create scoped token records.
+Fully stateful Slack Web API emulation with channels, messages, threads, reactions, user profiles, presence, modern file uploads, OAuth v2, and incoming webhooks. Chat writes preserve common rich message fields such as `blocks`, `attachments`, `metadata`, formatting flags, unfurl flags, and client message ids. Conversation writes update archive state, names, topics, purposes, membership, DMs, MPIMs, and read cursors. User writes update profile fields, status, custom fields, and deterministic active or away presence. File writes support the current external upload flow with local upload URLs, file share messages, reads, lists, downloads, and deletes. Seeded OAuth apps and OAuth installs create bot users and installation records. OAuth exchanges and explicit token seeds create scoped token records.
 
 ### Auth & Chat
 - `POST /api/auth.test` - test authentication
@@ -651,6 +651,14 @@ Fully stateful Slack Web API emulation with channels, messages, threads, reactio
 - `POST /api/users.setPresence` - set the authed user to away or automatic presence
 - `POST /api/reactions.add` / `reactions.remove` / `reactions.get` - manage reactions
 
+### Files
+- `POST /api/files.getUploadURLExternal` - create a local external upload session
+- `POST /upload/v1/:fileId` - receive raw uploaded file bytes
+- `POST /api/files.completeUploadExternal` - complete uploads and optionally share file messages
+- `GET /api/files.info` / `POST /api/files.info` - get file metadata
+- `GET /api/files.list` / `POST /api/files.list` - list completed files
+- `POST /api/files.delete` - delete a completed file
+
 ### Team, Bots & Webhooks
 - `POST /api/team.info` - workspace info
 - `POST /api/bots.info` - bot info
@@ -660,7 +668,7 @@ Fully stateful Slack Web API emulation with channels, messages, threads, reactio
 - `GET /oauth/v2/authorize` - authorization (shows user picker)
 - `POST /api/oauth.v2.access` - token exchange
 
-Slack scope checks are relaxed by default so local tests can use simple bearer tokens. Set `slack.strict_scopes: true` in seed config to make supported Web API methods return Slack-style `missing_scope` errors with `needed` and `provided` fields. Supported user and presence checks include `users:read`, `users:read.email`, `users.profile:read`, `users.profile:write`, and `users:write`.
+Slack scope checks are relaxed by default so local tests can use simple bearer tokens. Set `slack.strict_scopes: true` in seed config to make supported Web API methods return Slack-style `missing_scope` errors with `needed` and `provided` fields. Supported user, presence, and file checks include `users:read`, `users:read.email`, `users.profile:read`, `users.profile:write`, `users:write`, `files:read`, and `files:write`.
 
 ## Apple Sign In
 

apps/web/app/docs/slack/page.mdx

@@ -1,12 +1,12 @@
 # Slack API
 
-Fully stateful Slack Web API emulation with channels, messages, threads, reactions, user profiles, presence, OAuth v2, and incoming webhooks. Chat writes preserve common rich message fields such as `blocks`, `attachments`, `metadata`, formatting flags, unfurl flags, and client message ids. Conversation writes update archive state, names, topics, purposes, membership, DMs, MPIMs, and read cursors. User writes update profile fields, status, custom fields, and deterministic active or away presence. Seeded OAuth apps and OAuth installs create bot users and installation records. OAuth exchanges and explicit token seeds create scoped token records. State changes dispatch `event_callback` payloads to configured webhook URLs.
+Fully stateful Slack Web API emulation with channels, messages, threads, reactions, user profiles, presence, modern file uploads, OAuth v2, and incoming webhooks. Chat writes preserve common rich message fields such as `blocks`, `attachments`, `metadata`, formatting flags, unfurl flags, and client message ids. Conversation writes update archive state, names, topics, purposes, membership, DMs, MPIMs, and read cursors. User writes update profile fields, status, custom fields, and deterministic active or away presence. File writes support the current external upload flow with local upload URLs, file share messages, reads, lists, downloads, and deletes. Seeded OAuth apps and OAuth installs create bot users and installation records. OAuth exchanges and explicit token seeds create scoped token records. State changes dispatch `event_callback` payloads to configured webhook URLs.
 
 ## Auth
 
 - `POST /api/auth.test` - test authentication
 
-Scope checks are relaxed by default for local development. Set `slack.strict_scopes: true` in seed config to make supported Web API methods return Slack-style `missing_scope` errors with `needed` and `provided` fields. Supported user and presence checks include `users:read`, `users:read.email`, `users.profile:read`, `users.profile:write`, and `users:write`.
+Scope checks are relaxed by default for local development. Set `slack.strict_scopes: true` in seed config to make supported Web API methods return Slack-style `missing_scope` errors with `needed` and `provided` fields. Supported user, presence, and file checks include `users:read`, `users:read.email`, `users.profile:read`, `users.profile:write`, `users:write`, `files:read`, and `files:write`.
 
 ## Chat
 
@@ -57,6 +57,15 @@ Scope checks are relaxed by default for local development. Set `slack.strict_sco
 - `POST /api/reactions.remove` - remove reaction
 - `POST /api/reactions.get` - get reactions for a message
 
+## Files
+
+- `POST /api/files.getUploadURLExternal` - create a local external upload session
+- `POST /upload/v1/:fileId` - receive raw uploaded file bytes
+- `POST /api/files.completeUploadExternal` - complete uploads and optionally share file messages
+- `GET /api/files.info` / `POST /api/files.info` - get file metadata
+- `GET /api/files.list` / `POST /api/files.list` - list completed files
+- `POST /api/files.delete` - delete a completed file
+
 ## Team
 
 - `POST /api/team.info` - get workspace info
@@ -94,3 +103,5 @@ When messages are posted, updated, deleted, or reactions change, the emulator di
 - `im_created`, `im_open`, `im_close`, `im_marked`, and group open/close/marked events for DM and MPIM writes
 - `user_change` on profile writes
 - `presence_change` on presence writes
+- `file_created`, `file_shared`, and `file_deleted` on file writes
+- `message` with `subtype: file_share` on shared file uploads

packages/@emulators/slack/README.md

@@ -1,6 +1,6 @@
 # @emulators/slack
 
-Fully stateful Slack Web API emulation with channels, messages, threads, reactions, user profiles, presence, OAuth v2, and incoming webhooks. Chat writes preserve common rich message fields such as `blocks`, `attachments`, `metadata`, formatting flags, unfurl flags, and client message ids. Conversation writes update archive state, names, topics, purposes, membership, DMs, MPIMs, and read cursors. User writes update profile fields, status, custom fields, and deterministic active or away presence. OAuth installs create bot users and installation records. OAuth exchanges and explicit token seeds create scoped token records.
+Fully stateful Slack Web API emulation with channels, messages, threads, reactions, user profiles, presence, modern file uploads, OAuth v2, and incoming webhooks. Chat writes preserve common rich message fields such as `blocks`, `attachments`, `metadata`, formatting flags, unfurl flags, and client message ids. Conversation writes update archive state, names, topics, purposes, membership, DMs, MPIMs, and read cursors. User writes update profile fields, status, custom fields, and deterministic active or away presence. File writes support the current external upload flow with local upload URLs, file share messages, reads, lists, downloads, and deletes. OAuth installs create bot users and installation records. OAuth exchanges and explicit token seeds create scoped token records.
 
 Part of [emulate](https://github.com/vercel-labs/emulate) — local drop-in replacement services for CI and no-network sandboxes.
 
@@ -49,6 +49,14 @@ npm install @emulators/slack
 - `POST /api/users.setPresence` — set the authed user to away or automatic presence
 - `POST /api/reactions.add` / `reactions.remove` / `reactions.get` — manage reactions
 
+### Files
+- `POST /api/files.getUploadURLExternal` — create a local external upload session
+- `POST /upload/v1/:fileId` — receive raw uploaded file bytes
+- `POST /api/files.completeUploadExternal` — complete uploads and optionally share file messages
+- `GET /api/files.info` / `POST /api/files.info` — get file metadata
+- `GET /api/files.list` / `POST /api/files.list` — list completed files
+- `POST /api/files.delete` — delete a completed file
+
 ### Team, Bots & Webhooks
 - `POST /api/team.info` — workspace info
 - `POST /api/bots.info` — bot info
@@ -60,7 +68,7 @@ npm install @emulators/slack
 
 ## Auth
 
-All Web API endpoints require `Authorization: Bearer <token>`. Seeded OAuth apps create local installation state, and the OAuth v2 flow with user picker UI returns Slack-style bot tokens. Scope checks are relaxed by default for local development. Set `strict_scopes: true` in Slack seed config to return Slack-style `missing_scope` errors when a token lacks the required method scope. Supported user and presence checks include `users:read`, `users:read.email`, `users.profile:read`, `users.profile:write`, and `users:write`.
+All Web API endpoints require `Authorization: Bearer <token>`. Seeded OAuth apps create local installation state, and the OAuth v2 flow with user picker UI returns Slack-style bot tokens. Scope checks are relaxed by default for local development. Set `strict_scopes: true` in Slack seed config to return Slack-style `missing_scope` errors when a token lacks the required method scope. Supported user, presence, and file checks include `users:read`, `users:read.email`, `users.profile:read`, `users.profile:write`, `users:write`, `files:read`, and `files:write`.
 
 ## Seed Configuration
 
@@ -98,6 +106,8 @@ slack:
         - users.profile:read
         - users.profile:write
         - users:write
+        - files:read
+        - files:write
       user_scopes:
         - users:read
         - users.profile:read
@@ -111,6 +121,8 @@ slack:
         - users.profile:read
         - users.profile:write
         - users:write
+        - files:read
+        - files:write
   strict_scopes: false
 ```
 

packages/@emulators/slack/src/__tests__/coverage.test.ts

@@ -40,9 +40,7 @@ describe("Slack coverage matrix", () => {
 
   it("keeps planned gaps explicit", () => {
     const planned = slackCoverageMatrix.filter((entry) => entry.status === "not_started");
-    expect(planned.map((entry) => entry.method)).toEqual(
-      expect.arrayContaining(["files.getUploadURLExternal", "views.publish"]),
-    );
+    expect(planned.map((entry) => entry.method)).toEqual(expect.arrayContaining(["views.publish"]));
     for (const entry of planned) {
       expect(entry.notes).toMatch(/Planned|future/i);
     }

packages/@emulators/slack/src/__tests__/slack-coverage.ts

@@ -384,9 +384,57 @@ export const slackCoverageMatrix: SlackCoverageEntry[] = [
     family: "files",
     method: "files.getUploadURLExternal",
     route: "POST /api/files.getUploadURLExternal",
-    status: "not_started",
-    testedBy: [],
-    notes: "Planned for SLACK-8.",
+    status: "partial",
+    testedBy: ["slack.test.ts", "slack-sdk.test.ts"],
+    notes: "Creates a local upload session and returns an emulator upload URL plus file id.",
+  },
+  {
+    family: "files",
+    method: "files.completeUploadExternal",
+    route: "POST /api/files.completeUploadExternal",
+    status: "partial",
+    testedBy: ["slack.test.ts", "slack-sdk.test.ts", "slack-events.test.ts"],
+    notes: "Completes uploaded bytes into file records, optional file_share messages, and file events.",
+  },
+  {
+    family: "files",
+    method: "files.info",
+    route: ["GET /api/files.info", "POST /api/files.info"],
+    status: "partial",
+    testedBy: ["slack.test.ts", "slack-sdk.test.ts"],
+    notes: "Returns completed local file records.",
+  },
+  {
+    family: "files",
+    method: "files.list",
+    route: ["GET /api/files.list", "POST /api/files.list"],
+    status: "partial",
+    testedBy: ["slack.test.ts", "slack-sdk.test.ts"],
+    notes: "Lists completed local files with simple channel, user, type, time, and paging filters.",
+  },
+  {
+    family: "files",
+    method: "files.delete",
+    route: "POST /api/files.delete",
+    status: "partial",
+    testedBy: ["slack.test.ts", "slack-sdk.test.ts"],
+    notes: "Marks local files deleted and dispatches file_deleted events.",
+  },
+  {
+    family: "files",
+    method: "upload_url",
+    route: "POST /upload/v1/:fileId",
+    status: "partial",
+    testedBy: ["slack.test.ts", "slack-sdk.test.ts"],
+    notes: "Receives raw upload bytes for files.getUploadURLExternal sessions.",
+  },
+  {
+    family: "files",
+    method: "files.private_download",
+    route: "GET /files-pri/:fileId/:filename",
+    status: "partial",
+    testedBy: ["slack.test.ts"],
+    notes: "Serves bytes for emulator url_private and url_private_download file links.",
   },
   {
     family: "views",

packages/@emulators/slack/src/__tests__/slack-events.test.ts

@@ -251,6 +251,58 @@ describe("Slack plugin - event dispatch baseline", () => {
     });
   });
 
+  it("dispatches file upload and file share events", async () => {
+    const { app, store, webhooks } = createSlackTestApp();
+    const capture = captureFetchRequests();
+    registerSlackEventSubscription(webhooks, ["file_created", "file_shared", "message"]);
+
+    const channel = getSlackStore(store).channels.findOneBy("name", "general")!.channel_id;
+    const urlRes = await app.request(`${base}/api/files.getUploadURLExternal`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({ filename: "events.txt", length: 12 }),
+    });
+    const upload = (await urlRes.json()) as any;
+    await app.request(upload.upload_url, { method: "POST", body: "event file" });
+
+    await app.request(`${base}/api/files.completeUploadExternal`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({
+        files: [{ id: upload.file_id, title: "Event File" }],
+        channel_id: channel,
+        initial_comment: "File event",
+      }),
+    });
+
+    expect(capture.requests).toHaveLength(3);
+    expect(capture.jsonBodies()).toEqual([
+      expect.objectContaining({
+        event: expect.objectContaining({
+          type: "file_created",
+          file_id: upload.file_id,
+          file: expect.objectContaining({ id: upload.file_id, title: "Event File" }),
+        }),
+      }),
+      expect.objectContaining({
+        event: expect.objectContaining({
+          type: "file_shared",
+          file_id: upload.file_id,
+          channel_id: channel,
+        }),
+      }),
+      expect.objectContaining({
+        event: expect.objectContaining({
+          type: "message",
+          subtype: "file_share",
+          channel,
+          text: "File event",
+          files: [expect.objectContaining({ id: upload.file_id })],
+        }),
+      }),
+    ]);
+  });
+
   it("dispatches message_changed events for chat.update", async () => {
     const { app, store, webhooks } = createSlackTestApp();
     const capture = captureFetchRequests();

packages/@emulators/slack/src/__tests__/slack-sdk.test.ts

@@ -386,4 +386,33 @@ describe("Slack plugin - real @slack/web-api WebClient baseline", () => {
     expect(bot.ok).toBe(true);
     expect(bot.bot?.name).toBe("test-bot");
   });
+
+  it("uploads files through the Slack SDK uploadV2 helper", async () => {
+    expect(emulator).toBeDefined();
+    const channel = getSlackStore(emulator!.store).channels.findOneBy("name", "general")!.channel_id;
+
+    const uploaded = (await client.files.uploadV2({
+      channel_id: channel,
+      content: "SDK upload body",
+      filename: "sdk-upload.txt",
+      title: "SDK Upload",
+      initial_comment: "SDK file upload",
+    })) as any;
+    expect(uploaded.ok).toBe(true);
+    const completed = (uploaded.files as any[])[0];
+    const file = completed.files[0];
+    expect(file.title).toBe("SDK Upload");
+    expect(file.channels).toContain(channel);
+
+    const info = await client.files.info({ file: file.id });
+    expect(info.ok).toBe(true);
+    expect(info.file?.title).toBe("SDK Upload");
+
+    const list = await client.files.list({ channel });
+    expect(list.ok).toBe(true);
+    expect(list.files?.map((item) => item.id)).toContain(file.id);
+
+    const deleted = await client.files.delete({ file: file.id! });
+    expect(deleted.ok).toBe(true);
+  });
 });