Add Notion connector (per-user OAuth)

[SwathiMystery]

Add a Notion connector so users can ask questions across each employee's Notion workspace. Per-user OAuth (each user grants townsquare access to their Notion); the federation router will fan queries to each user's token automatically.

Why this is a good first issue

The contract for new connectors is well-defined and there are two reference implementations to copy from:

• src/townsquare/connectors/slack.py — closest analogue. Slack and Notion both use OAuth-via-our-app + xo*p style user tokens.
• src/townsquare/connectors/github.py — simpler shape (single REST endpoint).

You don't need to know the agent loop, the LLM, or the federation internals. A connector is a small, self-contained module.

What to build

1. src/townsquare/connectors/notion.py — implements the Connector protocol:
   • source_id = \"notion\"
   • required_scopes = [...]
   • async def search(query, access_token, limit) — call Notion's POST /v1/search API with the user's bearer token, return a list of Item.
   • async def fetch(item_id, access_token) — call POST /v1/blocks/{block_id}/children (optional in v1; can return None initially).
2. OAuth flow in src/townsquare/web/routes/connections_oauth.py:
   • GET /connections/notion/connect — redirect to Notion's authorize URL
   • GET /connections/notion/callback — exchange code, store via upsert_connection(...)
   • POST /connections/notion/disconnect — deactivate_connection(...)
3. Register in src/townsquare/connectors/registry.py's default_registry().
4. Connections UI entry in src/townsquare/web/routes/connections.py's SOURCE_CATALOG — change connect_url from None to /connections/notion/connect.
5. Tests in tests/test_connectors_slack_github.py (or split out test_connectors_notion.py):
   • Scope advertisement
   • Mocked HTTP — auth-fail returns []
   • Payload parsing returns the expected Item shape
6. Settings in src/townsquare/settings.py already has NOTION_CLIENT_ID / NOTION_CLIENT_SECRET. Wire them through.
7. example.env — add OAuth setup walkthrough lines like the Slack ones.

References

• Notion API auth docs
• Notion search API

Tips

• Notion bearer tokens look like secret_…; store them via upsert_connection exactly like Slack/GitHub.
• Only return text-bearing blocks in search v1. Page rendering can come later.
• Run make test and make lint before opening the PR. Both must pass before merge (CI enforces).

Reach out

Comment here before starting if you want feedback on your approach. Happy to review early.