emulate 0.5.0 → 0.6.0

package/README.md

@@ -22,25 +22,25 @@ All services start with sensible defaults. No config file needed:
 
 ```bash
 # Start all services (zero-config)
-emulate
+npx emulate
 
 # Start specific services
-emulate --service vercel,github
+npx emulate --service vercel,github
 
 # Custom port
-emulate --port 3000
+npx emulate --port 3000
 
 # Use a seed config file
-emulate --seed config.yaml
+npx emulate --seed config.yaml
 
 # Generate a starter config
-emulate init
+npx emulate init
 
 # Generate config for a specific service
-emulate init --service vercel
+npx emulate init --service vercel
 
 # List available services
-emulate list
+npx emulate list
 ```
 
 ### Options
@@ -64,7 +64,7 @@ The port can also be set via `EMULATE_PORT` or `PORT` environment variables.
 portless proxy start
 
 # Start emulate with portless integration
-emulate start --portless
+npx emulate start --portless
 ```
 
 Each service registers as a portless alias and gets a named HTTPS URL:
@@ -82,7 +82,7 @@ The `--portless` flag overwrites any existing portless aliases matching `*.emula
 For a custom base URL without portless (any reverse proxy), use `--base-url` or the `EMULATE_BASE_URL` env var:
 
 ```bash
-emulate start --base-url "https://{service}.myproxy.test"
+npx emulate start --base-url "https://{service}.myproxy.test"
 ```
 
 The `PORTLESS_URL` env var is automatically set by the `portless` CLI wrapper when running a command through it (e.g. `portless github.emulate emulate start`), typically to a value like `https://{service}.emulate.localhost`. It supports `{service}` interpolation, just like `--base-url` and `EMULATE_BASE_URL`. When no explicit `baseUrl` is provided, it is used as a fallback.
@@ -156,7 +156,7 @@ afterAll(() => Promise.all([github.close(), vercel.close()]))
 
 ## Configuration
 
-Configuration is optional. The CLI auto-detects config files in this order: `emulate.config.yaml` / `.yml`, `emulate.config.json`, `service-emulator.config.yaml` / `.yml`, `service-emulator.config.json`. Or pass `--seed <file>` explicitly. Run `emulate init` to generate a starter file.
+Configuration is optional. The CLI auto-detects config files in this order: `emulate.config.yaml` / `.yml`, `emulate.config.json`, `service-emulator.config.yaml` / `.yml`, `service-emulator.config.json`. Or pass `--seed <file>` explicitly. Run `npx emulate init` to generate a starter file.
 
 ```yaml
 tokens:
@@ -246,6 +246,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
@@ -256,9 +261,76 @@ 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
 
 apple:
   users:
@@ -598,39 +670,89 @@ 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, 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. Seeded OAuth apps and 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.
 
 ### 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
+
+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. 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 Slack 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.
+
 ## Apple Sign In
 
 Sign in with Apple emulation with authorization code flow, PKCE support, RS256 ID tokens, and OIDC discovery.
@@ -821,7 +943,7 @@ apps/
   web/              # Documentation site (Next.js)
 ```
 
-The core provides a generic `Store` with typed `Collection<T>` instances supporting CRUD, indexing, filtering, and pagination. Each service plugin registers its routes on the shared Hono app and uses the store for state.
+The core provides a generic `Store` with typed `Collection<T>` instances supporting CRUD, indexing, filtering, and pagination. Each service plugin registers its routes with the shared internal app and uses the store for state.
 
 ## Auth
 
@@ -833,7 +955,7 @@ Tokens are configured in the seed config and map to users. Pass them as `Authori
 
 **Google**: Standard OAuth 2.0 authorization code flow. Configure clients in the seed config.
 
-**Slack**: All Web API endpoints require `Authorization: Bearer <token>`. OAuth v2 flow with user picker UI.
+**Slack**: All Web API endpoints require `Authorization: Bearer <token>`. Seeded OAuth apps create local installation records, and OAuth v2 flow with user picker UI creates scoped bot tokens. Optional strict scope mode returns `missing_scope` when a token lacks a required method scope.
 
 **Apple**: OIDC authorization code flow with RS256 ID tokens. On first auth per user/client pair, a `user` JSON blob is included.