@emulators/slack 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @emulators/slack
 
-Fully stateful Slack Web API emulation with channels, messages, threads, reactions, OAuth v2, and incoming webhooks.
+Fully stateful Slack Web API emulation with channels, messages, threads, reactions, user profiles, presence, modern file uploads, pins, bookmarks, views, 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. View writes support App Home publishing and modal stacks. OAuth installs create bot users and installation records. OAuth exchanges and explicit token seeds create scoped token records. Supported write state changes dispatch Slack `event_callback` payloads to configured webhook URLs.
 
 Part of [emulate](https://github.com/vercel-labs/emulate) — local drop-in replacement services for CI and no-network sandboxes.
 
@@ -14,38 +14,88 @@ npm install @emulators/slack
 
 ### Auth & Chat
 - `POST /api/auth.test` — test authentication
-- `POST /api/chat.postMessage` — post message (supports threads via `thread_ts`)
-- `POST /api/chat.update` — update message
+- `POST /api/chat.postMessage` — post message with text or rich payload fields (supports threads via `thread_ts` and DM user IDs)
+- `POST /api/chat.postEphemeral` — post ephemeral message outside channel history
+- `POST /api/chat.update` — update message text and rich payload fields
 - `POST /api/chat.delete` — delete message
+- `GET /api/chat.getPermalink` / `POST /api/chat.getPermalink` — get message permalink
+- `POST /api/chat.scheduleMessage` — schedule pending message
+- `POST /api/chat.deleteScheduledMessage` — delete pending scheduled message
+- `POST /api/chat.scheduledMessages.list` — list pending scheduled messages
 - `POST /api/chat.meMessage` — /me message
 
 ### Conversations
-- `POST /api/conversations.list` — list channels (cursor pagination)
+- `POST /api/conversations.list` — list conversations (cursor pagination, `types`, `exclude_archived`)
 - `POST /api/conversations.info` — get channel info
 - `POST /api/conversations.create` — create channel
-- `POST /api/conversations.history` — channel history
-- `POST /api/conversations.replies` — thread replies
+- `POST /api/conversations.archive` / `conversations.unarchive` — archive/restore channel
+- `POST /api/conversations.rename` — rename channel
+- `POST /api/conversations.setTopic` / `conversations.setPurpose` — update topic/purpose
+- `POST /api/conversations.history` — channel history with rich message fields
+- `POST /api/conversations.replies` — thread replies with rich message fields
 - `POST /api/conversations.join` / `conversations.leave` — join/leave
+- `POST /api/conversations.invite` / `conversations.kick` — manage membership
+- `POST /api/conversations.open` / `conversations.close` — open/close DMs and MPIMs
+- `POST /api/conversations.mark` — mark read cursor
 - `POST /api/conversations.members` — list members
 
 ### Users & Reactions
 - `POST /api/users.list` — list users (cursor pagination)
 - `POST /api/users.info` — get user info
 - `POST /api/users.lookupByEmail` — lookup by email
+- `GET /api/users.profile.get` / `POST /api/users.profile.get` — get user profile fields
+- `POST /api/users.profile.set` — update profile fields, status, and custom fields
+- `GET /api/users.getPresence` / `POST /api/users.getPresence` — get active or away presence
+- `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
+- `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
+
+### Views
+- `POST /api/views.publish` — publish or update an App Home view for a user
+- `POST /api/views.open` — open a modal view
+- `POST /api/views.update` — update a view by `view_id` or `external_id`
+- `POST /api/views.push` — push a modal view onto the current modal stack
+- `POST /api/views.generateTriggerId` — local helper for tests that need a modal trigger id
+
+Modal opens and pushes require values from `/api/views.generateTriggerId`. Pass the returned value as `trigger_id` or `interactivity_pointer`; generate push values with an existing `view_id` and use them within 3 seconds.
+
 ### Team, Bots & Webhooks
 - `POST /api/team.info` — workspace info
 - `POST /api/bots.info` — bot info
-- `POST /services/:teamId/:botId/:webhookId` — incoming webhook
+- `POST /services/:teamId/:botId/:webhookId` — incoming webhook with text or rich payload fields
 
 ### OAuth
 - `GET /oauth/v2/authorize` — authorization (shows user picker)
+- `POST /oauth/v2/authorize/callback` — local user picker callback that creates the auth code
 - `POST /api/oauth.v2.access` — token exchange
 
+### Inspector
+- `GET /` — tabbed local inspector for conversations, messages, files, views, auth records, incoming webhooks, event subscriptions, and event deliveries
+
 ## Auth
 
-All Web API endpoints require `Authorization: Bearer <token>`. OAuth v2 flow with user picker UI.
+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. Strict mode checks `chat:write`, `channels:read`, `channels:history`, `channels:join`, `channels:manage`, `channels:write`, `groups:read`, `groups:history`, `groups:write`, `im:read`, `im:history`, `im:write`, `mpim:read`, `mpim:history`, `mpim:write`, `users:read`, `users:read.email`, `users.profile:read`, `users.profile:write`, `users:write`, `files:read`, `files:write`, `pins:read`, `pins:write`, `bookmarks:read`, `bookmarks:write`, `reactions:read`, `reactions:write`, and `team:read`. Slack lists no method-specific scopes for `views.publish`, `views.open`, `views.update`, or `views.push`, so the emulator requires auth but does not add strict-scope checks for those methods.
+
+## Current Limits
+
+Slack Connect, Enterprise Grid admin APIs, Audit Logs API, SCIM, Legal Holds, Socket Mode, slash command and interaction simulation, user groups, reminders, stars, calls, canvases, lists, functions, workflows, chat streaming, legacy `files.upload`, exact rate limiting, and paid-plan behavior are not implemented.
 
 ## Seed Configuration
 
@@ -58,6 +108,11 @@ slack:
     - name: developer
       real_name: Developer
       email: dev@example.com
+      profile:
+        title: Local Developer
+        status_text: Testing locally
+        status_emoji: ":computer:"
+      presence: active
   channels:
     - name: general
       topic: General discussion
@@ -68,9 +123,78 @@ slack:
   oauth_apps:
     - client_id: "12345.67890"
       client_secret: example_client_secret
+      app_id: A000000001
       name: My Slack App
       redirect_uris:
         - http://localhost:3000/api/auth/callback/slack
+      scopes:
+        - chat:write
+        - channels:read
+        - channels:history
+        - channels:join
+        - channels:manage
+        - channels:write
+        - groups:read
+        - groups:history
+        - groups:write
+        - im:read
+        - im:history
+        - im:write
+        - mpim:read
+        - mpim:history
+        - mpim:write
+        - users:read
+        - users:read.email
+        - users.profile:read
+        - users.profile:write
+        - users:write
+        - files:read
+        - files:write
+        - pins:read
+        - pins:write
+        - bookmarks:read
+        - bookmarks:write
+        - reactions:read
+        - reactions:write
+        - team:read
+      user_scopes:
+        - users:read
+        - users.profile:read
+      bot_name: my-bot
+  tokens:
+    - token: xoxb-local-test
+      user: developer
+      scopes:
+        - chat:write
+        - channels:read
+        - channels:history
+        - channels:join
+        - channels:manage
+        - channels:write
+        - groups:read
+        - groups:history
+        - groups:write
+        - im:read
+        - im:history
+        - im:write
+        - mpim:read
+        - mpim:history
+        - mpim:write
+        - users:read
+        - users:read.email
+        - users.profile:read
+        - users.profile:write
+        - users:write
+        - files:read
+        - files:write
+        - pins:read
+        - pins:write
+        - bookmarks:read
+        - bookmarks:write
+        - reactions:read
+        - reactions:write
+        - team:read
+  strict_scopes: false
 ```
 
 ## Links

package/dist/index.d.ts

@@ -5,6 +5,40 @@ interface SlackTeam extends Entity {
     name: string;
     domain: string;
 }
+interface SlackUserProfile {
+    display_name: string;
+    real_name: string;
+    email: string;
+    image_48: string;
+    image_192: string;
+    title?: string;
+    phone?: string;
+    skype?: string;
+    real_name_normalized?: string;
+    display_name_normalized?: string;
+    fields?: Record<string, {
+        value: string;
+        alt?: string;
+        label?: string;
+    }>;
+    status_text?: string;
+    status_emoji?: string;
+    status_emoji_display_info?: Record<string, unknown>[];
+    status_expiration?: number;
+    avatar_hash?: string;
+    start_date?: string;
+    pronouns?: string;
+    huddle_state?: string;
+    huddle_state_expiration_ts?: number;
+    first_name?: string;
+    last_name?: string;
+    image_24?: string;
+    image_32?: string;
+    image_72?: string;
+    image_512?: string;
+}
+type SlackPresence = "active" | "away";
+type SlackManualPresence = "auto" | "away";
 interface SlackUser extends Entity {
     user_id: string;
     team_id: string;
@@ -14,13 +48,11 @@ interface SlackUser extends Entity {
     is_admin: boolean;
     is_bot: boolean;
     deleted: boolean;
-    profile: {
-        display_name: string;
-        real_name: string;
-        email: string;
-        image_48: string;
-        image_192: string;
-    };
+    profile: SlackUserProfile;
+    presence?: SlackPresence;
+    manual_presence?: SlackManualPresence;
+    connection_count?: number;
+    last_activity?: number;
 }
 interface SlackChannel extends Entity {
     channel_id: string;
@@ -28,6 +60,11 @@ interface SlackChannel extends Entity {
     name: string;
     is_channel: boolean;
     is_private: boolean;
+    is_im?: boolean;
+    is_mpim?: boolean;
+    is_open?: boolean;
+    is_open_by_user?: Record<string, boolean>;
+    user?: string;
     is_archived: boolean;
     topic: {
         value: string;
@@ -42,7 +79,9 @@ interface SlackChannel extends Entity {
     members: string[];
     creator: string;
     num_members: number;
+    last_read?: Record<string, string>;
 }
+type SlackJsonObject = Record<string, unknown>;
 interface SlackMessage extends Entity {
     ts: string;
     channel_id: string;
@@ -50,6 +89,31 @@ interface SlackMessage extends Entity {
     text: string;
     type: "message";
     subtype?: string;
+    files?: SlackFile[];
+    upload?: boolean;
+    blocks?: SlackJsonObject[];
+    attachments?: SlackJsonObject[];
+    metadata?: SlackJsonObject;
+    mrkdwn?: boolean;
+    parse?: string;
+    link_names?: boolean;
+    unfurl_links?: boolean;
+    unfurl_media?: boolean;
+    username?: string;
+    icon_url?: string;
+    icon_emoji?: string;
+    bot_id?: string;
+    app_id?: string;
+    client_msg_id?: string;
+    reply_broadcast?: boolean;
+    topic?: string;
+    purpose?: string;
+    old_name?: string;
+    name?: string;
+    edited?: {
+        user: string;
+        ts: string;
+    };
     thread_ts?: string;
     reply_count: number;
     reply_users: string[];
@@ -59,8 +123,39 @@ interface SlackMessage extends Entity {
         count: number;
     }>;
 }
+interface SlackEphemeralMessage extends SlackMessage {
+    target_user: string;
+}
+interface SlackScheduledMessage extends Entity {
+    scheduled_message_id: string;
+    channel_id: string;
+    user: string;
+    text: string;
+    type: "delayed_message";
+    subtype: "bot_message";
+    blocks?: SlackJsonObject[];
+    attachments?: SlackJsonObject[];
+    metadata?: SlackJsonObject;
+    mrkdwn?: boolean;
+    parse?: string;
+    link_names?: boolean;
+    unfurl_links?: boolean;
+    unfurl_media?: boolean;
+    username?: string;
+    icon_url?: string;
+    icon_emoji?: string;
+    bot_id?: string;
+    app_id?: string;
+    client_msg_id?: string;
+    reply_broadcast?: boolean;
+    thread_ts?: string;
+    post_at: number;
+    date_created: number;
+}
 interface SlackBot extends Entity {
     bot_id: string;
+    app_id?: string;
+    user_id?: string;
     name: string;
     deleted: boolean;
     icons: {
@@ -68,10 +163,42 @@ interface SlackBot extends Entity {
     };
 }
 interface SlackOAuthApp extends Entity {
+    app_id?: string;
     client_id: string;
     client_secret: string;
     name: string;
     redirect_uris: string[];
+    scopes?: string[];
+    user_scopes?: string[];
+    bot_id?: string;
+    bot_user_id?: string;
+    bot_name?: string;
+}
+interface SlackInstallation extends Entity {
+    installation_id: string;
+    app_id: string;
+    client_id: string;
+    team_id: string;
+    app_name: string;
+    installer_user_id: string;
+    bot_id: string;
+    bot_user_id: string;
+    scopes: string[];
+    user_scopes: string[];
+}
+type SlackTokenType = "bot" | "user" | "test";
+interface SlackToken extends Entity {
+    token: string;
+    token_type: SlackTokenType;
+    team_id: string;
+    user_id: string;
+    scopes: string[];
+    app_id?: string;
+    client_id?: string;
+    installation_id?: string;
+    bot_id?: string;
+    bot_user_id?: string;
+    authed_user_id?: string;
 }
 interface SlackIncomingWebhook extends Entity {
     token: string;
@@ -81,15 +208,150 @@ interface SlackIncomingWebhook extends Entity {
     label: string;
     url: string;
 }
+interface SlackFileShare {
+    ts: string;
+    channel_name?: string;
+    team_id: string;
+    share_user_id: string;
+    source: "UNKNOWN" | "UPLOAD";
+    thread_ts?: string;
+    latest_reply?: string;
+    reply_count: number;
+    reply_users: string[];
+    reply_users_count: number;
+    is_silent_share: boolean;
+}
+interface SlackFile extends Entity {
+    file_id: string;
+    team_id: string;
+    user: string;
+    name: string;
+    title: string;
+    mimetype: string;
+    filetype: string;
+    pretty_type: string;
+    mode: "hosted" | "snippet";
+    size: number;
+    created: number;
+    timestamp: number;
+    url_private: string;
+    url_private_download: string;
+    permalink: string;
+    is_external: boolean;
+    external_type: string;
+    is_public: boolean;
+    public_url_shared: boolean;
+    display_as_bot: boolean;
+    editable: boolean;
+    deleted: boolean;
+    channels: string[];
+    groups: string[];
+    ims: string[];
+    shares: {
+        public?: Record<string, SlackFileShare[]>;
+        private?: Record<string, SlackFileShare[]>;
+    };
+    initial_comment?: string;
+    thread_ts?: string;
+    alt_txt?: string;
+    snippet_type?: string;
+    content_base64?: string;
+}
+interface SlackFileUploadSession extends Entity {
+    file_id: string;
+    team_id: string;
+    user: string;
+    filename: string;
+    title: string;
+    length: number;
+    upload_url: string;
+    alt_txt?: string;
+    snippet_type?: string;
+    uploaded: boolean;
+    uploaded_size?: number;
+    content_base64?: string;
+    completed: boolean;
+}
+interface SlackPin extends Entity {
+    pin_id: string;
+    team_id: string;
+    channel_id: string;
+    message_ts: string;
+    created: number;
+    created_by: string;
+}
+interface SlackBookmark extends Entity {
+    bookmark_id: string;
+    team_id: string;
+    channel_id: string;
+    title: string;
+    type: "link";
+    link: string;
+    emoji: string;
+    icon_url: string;
+    entity_id: string | null;
+    date_created: number;
+    date_updated: number;
+    rank: string;
+    last_updated_by_user_id: string;
+    last_updated_by_team_id: string;
+    shortcut_id: string | null;
+    app_id: string | null;
+    access_level?: "read" | "write";
+    parent_id?: string;
+}
+type SlackViewType = "home" | "modal";
+interface SlackView extends Entity {
+    view_id: string;
+    team_id: string;
+    user_id: string;
+    type: SlackViewType;
+    blocks: SlackJsonObject[];
+    private_metadata: string;
+    callback_id: string;
+    external_id: string;
+    title: SlackJsonObject | null;
+    submit: SlackJsonObject | null;
+    close: SlackJsonObject | null;
+    state: SlackJsonObject;
+    hash: string;
+    clear_on_close: boolean;
+    notify_on_close: boolean;
+    root_view_id: string;
+    previous_view_id?: string;
+    app_id: string;
+    bot_id: string;
+    created: number;
+    updated: number;
+}
+interface SlackViewTrigger extends Entity {
+    trigger_id: string;
+    team_id: string;
+    user_id: string;
+    app_id: string;
+    expires_at: number;
+    used: boolean;
+    view_id?: string;
+}
 
 interface SlackStore {
     teams: Collection<SlackTeam>;
     users: Collection<SlackUser>;
     channels: Collection<SlackChannel>;
     messages: Collection<SlackMessage>;
+    ephemeralMessages: Collection<SlackEphemeralMessage>;
+    scheduledMessages: Collection<SlackScheduledMessage>;
     bots: Collection<SlackBot>;
     oauthApps: Collection<SlackOAuthApp>;
+    installations: Collection<SlackInstallation>;
+    tokens: Collection<SlackToken>;
     incomingWebhooks: Collection<SlackIncomingWebhook>;
+    files: Collection<SlackFile>;
+    fileUploadSessions: Collection<SlackFileUploadSession>;
+    pins: Collection<SlackPin>;
+    bookmarks: Collection<SlackBookmark>;
+    views: Collection<SlackView>;
+    viewTriggers: Collection<SlackViewTrigger>;
 }
 declare function getSlackStore(store: Store): SlackStore;
 
@@ -104,6 +366,8 @@ interface SlackSeedConfig {
         real_name?: string;
         email?: string;
         is_admin?: boolean;
+        profile?: Partial<SlackUserProfile>;
+        presence?: SlackPresence;
     }>;
     channels?: Array<{
         name: string;
@@ -115,18 +379,40 @@ interface SlackSeedConfig {
         name: string;
     }>;
     oauth_apps?: Array<{
+        app_id?: string;
         client_id: string;
         client_secret: string;
         name: string;
         redirect_uris: string[];
+        scopes?: string[] | string;
+        user_scopes?: string[] | string;
+        bot_id?: string;
+        bot_user_id?: string;
+        bot_name?: string;
+    }>;
+    tokens?: Array<{
+        token: string;
+        type?: SlackTokenType;
+        user?: string;
+        user_id?: string;
+        scopes?: string[] | string;
+        app_id?: string;
+        client_id?: string;
+        team_id?: string;
+        bot_id?: string;
+        bot_user_id?: string;
+        authed_user_id?: string;
     }>;
     incoming_webhooks?: Array<{
         channel: string;
         label?: string;
     }>;
+    strict_scopes?: boolean;
     signing_secret?: string;
 }
 declare function seedFromConfig(store: Store, _baseUrl: string, config: SlackSeedConfig): void;
 declare const slackPlugin: ServicePlugin;
 
-export { type SlackBot, type SlackChannel, type SlackIncomingWebhook, type SlackMessage, type SlackOAuthApp, type SlackSeedConfig, type SlackStore, type SlackTeam, type SlackUser, slackPlugin as default, getSlackStore, seedFromConfig, slackPlugin };
+declare function normalizeScopes(value: string[] | string | undefined, fallback?: string[]): string[];
+
+export { type SlackBookmark, type SlackBot, type SlackChannel, type SlackEphemeralMessage, type SlackFile, type SlackFileShare, type SlackFileUploadSession, type SlackIncomingWebhook, type SlackInstallation, type SlackJsonObject, type SlackManualPresence, type SlackMessage, type SlackOAuthApp, type SlackPin, type SlackPresence, type SlackScheduledMessage, type SlackSeedConfig, type SlackStore, type SlackTeam, type SlackToken, type SlackTokenType, type SlackUser, type SlackUserProfile, type SlackView, type SlackViewTrigger, type SlackViewType, slackPlugin as default, getSlackStore, normalizeScopes, seedFromConfig, slackPlugin };