Add Slack pins and bookmarks parity (#161)

* Add Slack pins and bookmarks parity

- Add stateful pins and link bookmark APIs with scope checks and inspector visibility

- Cover route, SDK, event, coverage matrix, docs, and skill updates

* Fix Slack orphaned pins

* Fix Slack bookmark ordering

Sort bookmarks by rank with stable fallbacks and avoid rank reuse after deletion.

* Fix Slack seeded token identity handling

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, files:read, files:write]
+      scopes: [chat:write, channels:read, users.profile:read, users.profile:write, users:write, files:read, files:write, pins:read, pins:write, bookmarks:read, bookmarks: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, files:read, files:write]
+      scopes: [chat:write, channels:read, users.profile:read, users.profile:write, users:write, files:read, files:write, pins:read, pins:write, bookmarks:read, bookmarks: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, 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.
+Fully stateful Slack Web API emulation with channels, messages, threads, reactions, user profiles, presence, modern file uploads, pins, bookmarks, 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. Pin and bookmark writes support channel message pins and link bookmarks. 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
@@ -660,6 +660,15 @@ Fully stateful Slack Web API emulation with channels, messages, threads, reactio
 - `GET /files-pri/:fileId/:filename` - download file bytes with a bearer token that can access the file
 - `POST /api/files.delete` - delete a completed file
 
+### Pins & Bookmarks
+- `POST /api/pins.add` - pin a message to a channel
+- `GET /api/pins.list` / `POST /api/pins.list` - list pinned message items for a channel
+- `POST /api/pins.remove` - remove a message pin from a channel
+- `POST /api/bookmarks.add` - add a link bookmark to a channel
+- `POST /api/bookmarks.edit` - update a link bookmark
+- `POST /api/bookmarks.list` - list channel bookmarks
+- `POST /api/bookmarks.remove` - remove a bookmark from a channel
+
 ### Team, Bots & Webhooks
 - `POST /api/team.info` - workspace info
 - `POST /api/bots.info` - bot info
@@ -669,7 +678,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, presence, and file checks include `users:read`, `users:read.email`, `users.profile:read`, `users.profile:write`, `users:write`, `files:read`, and `files: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, file, pin, and bookmark checks include `users:read`, `users:read.email`, `users.profile:read`, `users.profile:write`, `users:write`, `files:read`, `files:write`, `pins:read`, `pins:write`, `bookmarks:read`, and `bookmarks:write`.
 
 ## Apple Sign In
 

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

@@ -224,6 +224,10 @@ slack:
         - users:write
         - files:read
         - files:write
+        - pins:read
+        - pins:write
+        - bookmarks:read
+        - bookmarks:write
   tokens:
     - token: xoxb-local-test
       user: developer
@@ -235,6 +239,10 @@ slack:
         - users:write
         - files:read
         - files:write
+        - pins:read
+        - pins:write
+        - bookmarks:read
+        - bookmarks:write
   incoming_webhooks:
     - channel: general
       label: CI Notifications

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, 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.
+Fully stateful Slack Web API emulation with channels, messages, threads, reactions, user profiles, presence, modern file uploads, pins, bookmarks, 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. Pin and bookmark writes support channel message pins and link bookmarks. 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, presence, and file checks include `users:read`, `users:read.email`, `users.profile:read`, `users.profile:write`, `users:write`, `files:read`, and `files: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, file, pin, and bookmark checks include `users:read`, `users:read.email`, `users.profile:read`, `users.profile:write`, `users:write`, `files:read`, `files:write`, `pins:read`, `pins:write`, `bookmarks:read`, and `bookmarks:write`.
 
 ## Chat
 
@@ -67,6 +67,16 @@ Scope checks are relaxed by default for local development. Set `slack.strict_sco
 - `GET /files-pri/:fileId/:filename` - download file bytes with a bearer token that can access the file
 - `POST /api/files.delete` - delete a completed file
 
+## Pins And Bookmarks
+
+- `POST /api/pins.add` - pin a message to a channel
+- `GET /api/pins.list` / `POST /api/pins.list` - list pinned message items for a channel
+- `POST /api/pins.remove` - remove a message pin from a channel
+- `POST /api/bookmarks.add` - add a link bookmark to a channel
+- `POST /api/bookmarks.edit` - update a link bookmark
+- `POST /api/bookmarks.list` - list channel bookmarks
+- `POST /api/bookmarks.remove` - remove a bookmark from a channel
+
 ## Team
 
 - `POST /api/team.info` - get workspace info
@@ -88,13 +98,14 @@ Scope checks are relaxed by default for local development. Set `slack.strict_sco
 
 ## Event Dispatching
 
-When messages are posted, updated, deleted, or reactions change, the emulator dispatches `event_callback` payloads to configured webhook URLs matching Slack's Events API format:
+When messages are posted, updated, deleted, reactions change, pins change, or files change, the emulator dispatches `event_callback` payloads to configured webhook URLs matching Slack's Events API format:
 
 - `message` events on `chat.postMessage`
 - `message` with `subtype: message_changed` on `chat.update`
 - `message` with `subtype: message_deleted` on `chat.delete`
 - rich message fields are included on posted `message` events when present
 - `reaction_added` / `reaction_removed` events on `reactions.add` / `reactions.remove`
+- `pin_added` / `pin_removed` events on `pins.add` / `pins.remove`
 - `message` with `subtype: bot_message` on incoming webhook posts
 - `channel_archive` / `channel_unarchive` for public lifecycle archive writes
 - `group_archive` / `group_unarchive` for private lifecycle archive writes

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, 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.
+Fully stateful Slack Web API emulation with channels, messages, threads, reactions, user profiles, presence, modern file uploads, pins, bookmarks, 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. Pin and bookmark writes support channel message pins and link bookmarks. 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.
 
@@ -58,6 +58,15 @@ npm install @emulators/slack
 - `GET /files-pri/:fileId/:filename` — download file bytes with a bearer token that can access the file
 - `POST /api/files.delete` — delete a completed file
 
+### Pins & Bookmarks
+- `POST /api/pins.add` — pin a message to a channel
+- `GET /api/pins.list` / `POST /api/pins.list` — list pinned message items for a channel
+- `POST /api/pins.remove` — remove a message pin from a channel
+- `POST /api/bookmarks.add` — add a link bookmark to a channel
+- `POST /api/bookmarks.edit` — update a link bookmark
+- `POST /api/bookmarks.list` — list channel bookmarks
+- `POST /api/bookmarks.remove` — remove a bookmark from a channel
+
 ### Team, Bots & Webhooks
 - `POST /api/team.info` — workspace info
 - `POST /api/bots.info` — bot info
@@ -69,7 +78,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, presence, and file checks include `users:read`, `users:read.email`, `users.profile:read`, `users.profile:write`, `users:write`, `files:read`, and `files: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, file, pin, and bookmark checks include `users:read`, `users:read.email`, `users.profile:read`, `users.profile:write`, `users:write`, `files:read`, `files:write`, `pins:read`, `pins:write`, `bookmarks:read`, and `bookmarks:write`.
 
 ## Seed Configuration
 
@@ -109,6 +118,10 @@ slack:
         - users:write
         - files:read
         - files:write
+        - pins:read
+        - pins:write
+        - bookmarks:read
+        - bookmarks:write
       user_scopes:
         - users:read
         - users.profile:read
@@ -124,6 +137,10 @@ slack:
         - users:write
         - files:read
         - files:write
+        - pins:read
+        - pins:write
+        - bookmarks:read
+        - bookmarks:write
   strict_scopes: false
 ```
 

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

@@ -323,6 +323,62 @@ export const slackCoverageMatrix: SlackCoverageEntry[] = [
     testedBy: ["slack.test.ts", "slack-sdk.test.ts"],
     notes: "Returns reactions for message items only.",
   },
+  {
+    family: "pins",
+    method: "pins.add",
+    route: "POST /api/pins.add",
+    status: "partial",
+    testedBy: ["slack.test.ts", "slack-sdk.test.ts", "slack-events.test.ts"],
+    notes: "Pins message items to channels and dispatches pin_added events.",
+  },
+  {
+    family: "pins",
+    method: "pins.list",
+    route: ["GET /api/pins.list", "POST /api/pins.list"],
+    status: "partial",
+    testedBy: ["slack.test.ts", "slack-sdk.test.ts"],
+    notes: "Lists pinned message items for a channel.",
+  },
+  {
+    family: "pins",
+    method: "pins.remove",
+    route: "POST /api/pins.remove",
+    status: "partial",
+    testedBy: ["slack.test.ts", "slack-sdk.test.ts", "slack-events.test.ts"],
+    notes: "Removes message pins from channels and dispatches pin_removed events.",
+  },
+  {
+    family: "bookmarks",
+    method: "bookmarks.add",
+    route: "POST /api/bookmarks.add",
+    status: "partial",
+    testedBy: ["slack.test.ts", "slack-sdk.test.ts"],
+    notes: "Adds link bookmarks to channels.",
+  },
+  {
+    family: "bookmarks",
+    method: "bookmarks.edit",
+    route: "POST /api/bookmarks.edit",
+    status: "partial",
+    testedBy: ["slack.test.ts", "slack-sdk.test.ts"],
+    notes: "Updates local link bookmark title, link, and emoji fields.",
+  },
+  {
+    family: "bookmarks",
+    method: "bookmarks.list",
+    route: "POST /api/bookmarks.list",
+    status: "partial",
+    testedBy: ["slack.test.ts", "slack-sdk.test.ts"],
+    notes: "Lists local link bookmarks for a channel.",
+  },
+  {
+    family: "bookmarks",
+    method: "bookmarks.remove",
+    route: "POST /api/bookmarks.remove",
+    status: "partial",
+    testedBy: ["slack.test.ts", "slack-sdk.test.ts"],
+    notes: "Removes local link bookmarks from channels.",
+  },
   {
     family: "team",
     method: "team.info",
@@ -378,7 +434,7 @@ export const slackCoverageMatrix: SlackCoverageEntry[] = [
     route: "GET /",
     status: "partial",
     testedBy: ["slack.test.ts"],
-    notes: "Shows channels and recent messages.",
+    notes: "Shows channels, recent messages, scheduled messages, ephemeral messages, pins, and bookmarks.",
   },
   {
     family: "files",

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

@@ -197,6 +197,60 @@ describe("Slack plugin - event dispatch baseline", () => {
     ]);
   });
 
+  it("dispatches pin add and remove events", async () => {
+    const { app, store, webhooks } = createSlackTestApp();
+    const capture = captureFetchRequests();
+    registerSlackEventSubscription(webhooks, ["pin_added", "pin_removed"]);
+
+    const ch = getSlackStore(store).channels.findOneBy("name", "general")!;
+    const postRes = await app.request(`${base}/api/chat.postMessage`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({ channel: ch.channel_id, text: "pin event baseline" }),
+    });
+    const posted = (await postRes.json()) as { ts: string };
+
+    await app.request(`${base}/api/pins.add`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({ channel: ch.channel_id, timestamp: posted.ts }),
+    });
+
+    await app.request(`${base}/api/pins.remove`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({ channel: ch.channel_id, timestamp: posted.ts }),
+    });
+
+    expect(capture.requests).toHaveLength(2);
+    expect(capture.jsonBodies()).toEqual([
+      expect.objectContaining({
+        event: expect.objectContaining({
+          type: "pin_added",
+          user: "U000000001",
+          channel_id: ch.channel_id,
+          item: expect.objectContaining({
+            type: "message",
+            channel: ch.channel_id,
+            message: expect.objectContaining({ text: "pin event baseline", pinned_to: [ch.channel_id] }),
+          }),
+        }),
+      }),
+      expect.objectContaining({
+        event: expect.objectContaining({
+          type: "pin_removed",
+          user: "U000000001",
+          channel_id: ch.channel_id,
+          has_pins: false,
+          item: expect.objectContaining({
+            type: "message",
+            channel: ch.channel_id,
+          }),
+        }),
+      }),
+    ]);
+  });
+
   it("dispatches user_change events for profile writes", async () => {
     const { app, webhooks } = createSlackTestApp();
     const capture = captureFetchRequests();