slack_connector
diapason.connectors.slack_connector
¶
Slack connector — bulk channel message sync via the Slack Web API.
Uses a Slack user OAuth token (xoxp-...) stored locally so the
sync sees everything the user can see — including their 1:1 DMs and
multi-person DMs with other humans. A bot token (xoxb-) cannot see
user-to-user DMs (Slack platform constraint), so this connector
explicitly rejects bot tokens with a clear error at connect time.
All network calls are isolated in module-level functions
(_slack_api_*) to make them trivially mockable in tests.
SlackConnector
¶
Bases: BaseConnector
Connector that syncs channel message history from Slack via the Web API.
Authentication is handled through Slack OAuth 2.0. Tokens are stored locally in a JSON credentials file.
Parameters¶
credentials_path:
Path to the JSON file where OAuth tokens are stored. Defaults to
~/.diapason/connectors/slack.json.
auth_url()
¶
Return a Slack OAuth consent URL requesting user-token scopes.
Uses user_scope (not scope) so the install grants a User
OAuth Token (xoxp-) — bot tokens (xoxb-) can't see human-
to-human DMs and are rejected by :func:handle_callback.
Without a stored client_id, this returns the Slack app dashboard
rather than a consent URL — the same rule the Google connectors
follow. A consent URL with an empty client_id is not degraded,
it is broken: Slack answers invalid_client_id, and the user goes
looking for the fault on their own side.
Note that unlike Google, Slack has no entry in OAUTH_PROVIDERS:
there is no server-side /oauth/start path for it, so this URL is
the only one on offer.
disconnect()
¶
Delete the stored credentials file.
handle_callback(code)
¶
Validate and persist a supplied User OAuth Token.
The connector /connect endpoint funnels manually-pasted tokens
through this method (the parameter is named code for OAuth-flow
compatibility). The token is checked two ways before it is allowed
to touch disk, so an invalid credential never overwrites a working
one:
- Shape — must start with
xoxp-(xoxb-bot tokens and any other prefix are rejected via :func:_validate_user_token). - Liveness — a live
auth.testcall must returnokso an expired or revoked token is caught at connect time.
is_connected()
¶
Return True if a credentials file with a valid token exists.
mcp_tools()
¶
Expose three MCP tool specs for real-time Slack queries.
sync(*, since=None, cursor=None)
¶
Yield :class:Document objects for every accessible Slack message.
With a user OAuth token (xoxp-) the listing returned by
conversations.list already reflects what the user can see —
no conversations.join step, no membership filtering. We
enumerate every conversation first (so the per-type count can
be logged up front), then stream history for each one.
Parameters¶
since: Not yet used (reserved for incremental sync). cursor: Not yet used (reserved for pagination resumption).
sync_status()
¶
Return sync progress from the most recent :meth:sync call.
SlackTokenError
¶
Bases: ValueError
Raised when the stored Slack token isn't a usable user token.
Surfaced via :class:SyncStatus.error so the UI can render the actual
reason (e.g. xoxb- bot token rejected) instead of an empty sync.