fix(adapters): api_url custom-endpoint config (Slack/Discord/GitHub/Linear) + GitHub public get_installation_id (#150)

* fix(adapters): api_url custom-endpoint config (Slack/Discord/GitHub/Linear) + GitHub public get_installation_id

Pre-existing parity gaps ported faithfully from upstream chat@4.30.0.

(A) api_url custom-endpoint config (upstream 4.27.0, 6b17c60) — every
high-level adapter reads `config.apiUrl ?? <ADAPTER>_API_URL` env and
routes it into the underlying API client. Add the field (+ env fallback,
default unchanged when unset) to the four adapters that were missing it:

- Slack (index.ts:617,576-577,620-621): new `api_url` (+ SLACK_API_URL).
  Passed as `base_url` to BOTH the async AsyncWebClient cache and the
  synchronous web_client escape hatch. Omitted entirely when unset
  (slack_sdk rejects base_url=None and keeps its built-in default).
- Discord (types.ts:18-19, index.ts:142): new `api_url` (+ DISCORD_API_URL)
  replacing the hardcoded DISCORD_API_BASE in `_discord_fetch` — the single
  funnel all Discord HTTP goes through.
- GitHub (index.ts:201,217): new `api_url` (+ GITHUB_API_URL) for GitHub
  Enterprise Server. Threaded into `_github_api_request` and the
  installation-token exchange URL (the two hardcoded api.github.com sites).
- Linear (index.ts:221,239,249, types.ts:51): new `api_url`
  (+ LINEAR_API_URL) overriding the GraphQL endpoint in `_graphql_query`.

(B) GitHub public get_installation_id (index.ts:458-480) — add the public
`get_installation_id(thread|str)` returning the fixed id (single-tenant
app), the cached repo installation (multi-tenant), or None (PAT mode);
raises when multi-tenant and uninitialized. Keeps the private
`_get_installation_id(owner, repo)` helper it delegates to.

Tests: tests/test_adapter_api_url_config.py (31) — per-adapter custom-url
used / default-unchanged / env-fallback / config-wins-over-env, plus the
six get_installation_id auth-mode branches. The usage-site assertions were
verified to fail against the pre-fix sources.

* fix(adapters): run api_url tests in CI + empty-string falls back to default endpoint

The api_url config test module guarded every test behind a module-level
pytest.importorskip("slack_sdk"). Since slack_sdk lives only in the optional
slack/all extras (not the dev group CI installs), the whole file collected as
a single skip -- silently disabling the Discord/GitHub/Linear api_url tests and
the get_installation_id regression tests in CI (falsely green).

Stub slack_sdk into sys.modules (mirroring tests/test_slack_client_cache.py) so
the module imports without the real package and the Slack tests run too. The
file now reports 34 passed, 1 skipped (the lone skip is the genuine-sdk
end-to-end test, intentionally skipped when stubbed) instead of 1 skipped.

Empty-string api_url now falls back to the default endpoint, matching upstream's
truthy spread ...(this.apiUrl ? {...} : {}):
- Slack: empty apiUrl/env resolves to None, so base_url is omitted and slack_sdk
  keeps https://slack.com/api/ (never passes base_url="").
- Linear: empty resolves to LINEAR_API_URL instead of POSTing to an empty URL.
- GitHub: empty resolves to https://api.github.com; fixed the misleading inline
  comment that claimed the is-not-None check honored empty string.
- Discord: empty resolves to DISCORD_API_BASE instead of a relative request URL.

Added a per-adapter empty-string regression test (Slack/Discord/GitHub/Linear).

Author: patrick-chinchill

src/chat_sdk/adapters/discord/adapter.py

@@ -121,6 +121,15 @@ def __init__(self, config: DiscordAdapterConfig | None = None) -> None:
                 "application_id is required. Set DISCORD_APPLICATION_ID or provide it in config.",
             )
 
+        # Custom Discord API base URL (proxy / mock / self-host). Port of
+        # upstream's coalescing chain ``config.apiUrl ?? process.env.DISCORD_API_URL
+        # ?? DISCORD_API_BASE`` (index.ts:142). Unlike Slack/GitHub/Linear --
+        # which feed clients via a truthy spread -- ``_discord_fetch`` joins
+        # ``f"{base}{path}"`` directly, so an empty ``apiUrl`` would yield a
+        # broken relative URL. We use a truthy fallback so an empty string (or
+        # env) resolves to the ``DISCORD_API_BASE`` default, matching the
+        # empty-string-is-default contract shared by the other adapters.
+        self._api_base_url: str = config.api_url or os.environ.get("DISCORD_API_URL") or DISCORD_API_BASE
         self._name = "discord"
         self._bot_token = bot_token
         self._public_key = public_key.strip().lower()
@@ -1494,7 +1503,7 @@ async def _discord_fetch(
         """
         import aiohttp  # lazy import (needed for FormData)
 
-        url = f"{DISCORD_API_BASE}{path}"
+        url = f"{self._api_base_url}{path}"
         headers: dict[str, str] = {
             "Authorization": f"Bot {self._bot_token}",
         }

src/chat_sdk/adapters/discord/types.py

@@ -26,6 +26,11 @@ class DiscordAdapterConfig:
     See: https://discord.com/developers/docs/getting-started
     """
 
+    # Override the Discord API base URL. Defaults to the DISCORD_API_URL env
+    # var, then to "https://discord.com/api/v10". Mirrors upstream
+    # ``config.apiUrl ?? process.env.DISCORD_API_URL ?? DISCORD_API_BASE``
+    # (vercel/chat adapter-discord index.ts:142).
+    api_url: str | None = None
     # Discord application ID. Defaults to DISCORD_APPLICATION_ID env var.
     application_id: str | None = None
     # Discord bot token. Defaults to DISCORD_BOT_TOKEN env var.

src/chat_sdk/adapters/github/adapter.py

@@ -57,13 +57,20 @@
     RawMessage,
     StreamChunk,
     StreamOptions,
+    Thread,
     ThreadInfo,
     ThreadSummary,
     UserInfo,
     WebhookOptions,
     _parse_iso,
 )
 
+# Default GitHub REST API base URL. Overridable per-adapter via
+# ``config["api_url"]`` / ``GITHUB_API_URL`` for GitHub Enterprise Server
+# (mirrors upstream Octokit ``baseUrl``). Stored without a trailing slash so
+# ``f"{base}{path}"`` joins cleanly with leading-slash paths.
+GITHUB_API_BASE_URL = "https://api.github.com"
+
 REVIEW_COMMENT_THREAD_PATTERN = re.compile(r"^([^/]+)/([^:]+):(\d+):rc:(\d+)$")
 ISSUE_THREAD_PATTERN = re.compile(r"^([^/]+)/([^:]+):issue:(\d+)$")
 PR_THREAD_PATTERN = re.compile(r"^([^/]+)/([^:]+):(\d+)$")
@@ -114,6 +121,19 @@ def __init__(self, config: GitHubAdapterConfig | None = None) -> None:
         self._chat: ChatInstance | None = None
         self._format_converter = GitHubFormatConverter()
 
+        # Custom GitHub API base URL (e.g. GitHub Enterprise Server). Upstream
+        # threads ``config.apiUrl ?? process.env.GITHUB_API_URL`` into every
+        # Octokit ``baseUrl`` via the truthy spread ``...(this.apiUrl ? { baseUrl }
+        # : {})`` (index.ts:201/217/...), so an empty string falls back to the
+        # default. We have no Octokit -- our REST calls go through
+        # ``_github_api_request`` and the installation-token exchange -- so we
+        # normalize the override (strip a trailing slash so ``f"{base}{path}"``
+        # joins cleanly) and substitute it for the hardcoded
+        # ``https://api.github.com`` at both sites. The truthy fallback means an
+        # empty ``apiUrl`` (or env) uses the default endpoint.
+        api_url_raw = config.get("api_url") or os.environ.get("GITHUB_API_URL")
+        self._api_url = api_url_raw.rstrip("/") if api_url_raw else GITHUB_API_BASE_URL
+
         # Auth configuration
         self._auth_token: str | None = None
         self._app_credentials: dict[str, str] | None = None
@@ -1098,7 +1118,7 @@ async def _get_installation_token(self, installation_id: int) -> str:
                     return token
 
             app_jwt = self._generate_app_jwt()
-            url = f"https://api.github.com/app/installations/{installation_id}/access_tokens"
+            url = f"{self._api_url}/app/installations/{installation_id}/access_tokens"
             headers = {
                 "Accept": "application/vnd.github+json",
                 "Authorization": f"Bearer {app_jwt}",
@@ -1169,7 +1189,7 @@ async def _github_api_request(
         if auth_token:
             headers["Authorization"] = f"Bearer {auth_token}"
 
-        url = f"https://api.github.com{path}" if path.startswith("/") else path
+        url = f"{self._api_url}{path}" if path.startswith("/") else path
 
         session = await self._get_http_session()
         kwargs: dict[str, Any] = {"headers": headers}
@@ -1208,6 +1228,40 @@ async def _get_installation_id(self, owner: str, repo: str) -> int | None:
         key = f"github:install:{owner}/{repo}"
         return await self._chat.get_state().get(key)
 
+    async def get_installation_id(self, thread: Thread | str) -> int | None:
+        """Get the GitHub App installation ID associated with a thread.
+
+        Returns the fixed installation ID in single-tenant app mode, the cached
+        repository installation in multi-tenant mode, or ``None`` in PAT mode.
+
+        Faithful port of upstream ``getInstallationId`` (index.ts:458-480).
+        ``thread`` may be a :class:`Thread` or a raw thread-ID string. The
+        private :meth:`_get_installation_id` (owner/repo) is retained as the
+        storage-keyed helper this method delegates to in multi-tenant mode.
+
+        Raises:
+            ValidationError: In multi-tenant mode when the adapter has not been
+                initialized via ``chat.initialize()`` (no state store to read).
+        """
+        # Single-tenant GitHub App mode: a fixed installation was configured.
+        if self._installation_id is not None:
+            return self._installation_id
+
+        # PAT mode (or any non-multi-tenant config): no installation concept.
+        if not self.is_multi_tenant:
+            return None
+
+        thread_id = thread if isinstance(thread, str) else thread.id
+        decoded = self.decode_thread_id(thread_id)
+
+        if not self._chat:
+            raise ValidationError(
+                "github",
+                "Adapter not initialized. Ensure chat.initialize() has been called first.",
+            )
+
+        return await self._get_installation_id(decoded.owner, decoded.repo)
+
     @staticmethod
     async def _get_request_body(request: Any) -> str:
         """Extract body text from a request object."""

src/chat_sdk/adapters/github/types.py

@@ -16,6 +16,11 @@ class GitHubAdapterBaseConfig(TypedDict, total=False):
     """Base configuration options shared by all auth methods.
 
     Attributes:
+        api_url: Override the GitHub API base URL (e.g. a GitHub Enterprise
+            Server endpoint like "https://github.example.com/api/v3"). Mirrors
+            upstream ``config.apiUrl`` → Octokit ``baseUrl`` (index.ts:201,217).
+            Defaults to the GITHUB_API_URL env var, then to
+            "https://api.github.com".
         bot_user_id: Bot's GitHub user ID (numeric). Used for self-message
             detection. If not provided, will be fetched on first API call.
         logger: Logger instance for error reporting. Defaults to ConsoleLogger.
@@ -27,6 +32,7 @@ class GitHubAdapterBaseConfig(TypedDict, total=False):
             Defaults to GITHUB_WEBHOOK_SECRET env var.
     """
 
+    api_url: str
     bot_user_id: int
     logger: Logger
     user_name: str

src/chat_sdk/adapters/linear/adapter.py

@@ -119,6 +119,17 @@ def __init__(self, config: LinearAdapterConfig | None = None) -> None:
             )
 
         self._name = "linear"
+        # Custom Linear GraphQL endpoint (proxy / mock / self-host). Faithful
+        # port of upstream ``config.apiUrl ?? process.env.LINEAR_API_URL``
+        # (index.ts:239), consumed via the truthy spread
+        # ``...(this.apiUrl ? { apiUrl } : {})`` at every ``LinearClient``
+        # construction — so an empty string falls back to the default endpoint.
+        # We have no LinearClient -- ``_graphql_query`` POSTs raw GraphQL -- so
+        # the override substitutes for the module-level ``LINEAR_API_URL``
+        # default. The truthy check means an empty ``apiUrl`` (or env) uses the
+        # default rather than POSTing to an empty/relative URL.
+        config_api_url = getattr(config, "api_url", None)
+        self._api_url: str = config_api_url or os.environ.get("LINEAR_API_URL") or LINEAR_API_URL
         self._webhook_secret = webhook_secret
         self._logger: Logger = getattr(config, "logger", None) or ConsoleLogger("info", prefix="linear")
         self._user_name = getattr(config, "user_name", None) or os.environ.get("LINEAR_BOT_USERNAME", "linear-bot")
@@ -1168,7 +1179,7 @@ async def _graphql_query(
 
         session = await self._get_http_session()
         async with session.post(
-            LINEAR_API_URL,
+            self._api_url,
             headers=headers,
             json=payload,
         ) as response:

src/chat_sdk/adapters/linear/types.py

@@ -20,6 +20,12 @@
 class LinearAdapterBaseConfig:
     """Base configuration options shared by all auth methods."""
 
+    # Override the Linear GraphQL API base URL. Defaults to the LINEAR_API_URL
+    # env var, then to "https://api.linear.app/graphql". Mirrors upstream
+    # ``config.apiUrl ?? process.env.LINEAR_API_URL`` → ``LinearClient.apiUrl``
+    # (vercel/chat adapter-linear index.ts:239, types.ts:51). Useful for
+    # proxies, mocks, or self-hosted GraphQL gateways.
+    api_url: str | None = None
     # Logger instance for error reporting. Defaults to ConsoleLogger.
     logger: Logger | None = None
     # Bot display name for @-mention detection.

src/chat_sdk/adapters/slack/adapter.py

@@ -540,6 +540,18 @@ def __init__(self, config: SlackAdapterConfig | None = None) -> None:
         if encryption_key_raw:
             self._encryption_key = decode_key(encryption_key_raw)
 
+        # Custom Slack Web API base URL (e.g. proxy, mock, Enterprise routing).
+        # ``config.apiUrl ?? process.env.SLACK_API_URL`` upstream (index.ts:617),
+        # consumed via the truthy spread ``...(this.slackApiUrl ? {...} : {})``
+        # at every client construction — so an empty string falls back to the
+        # built-in default. We mirror that here: an empty ``apiUrl`` (or env)
+        # resolves to ``None``. When ``None`` we omit ``base_url`` from the
+        # client constructors entirely, so slack_sdk keeps its built-in
+        # ``https://slack.com/api/`` default (it rejects ``base_url=None``).
+        # Threaded into BOTH the async ``AsyncWebClient`` cache and the
+        # synchronous ``web_client`` escape hatch.
+        self._slack_api_url: str | None = (config.api_url or os.environ.get("SLACK_API_URL")) or None
+
     # ------------------------------------------------------------------
     # Properties (Adapter protocol)
     # ------------------------------------------------------------------
@@ -852,7 +864,14 @@ def _get_client(self, token: str | None = None) -> Any:
 
         from slack_sdk.web.async_client import AsyncWebClient
 
-        client = AsyncWebClient(token=resolved_token)
+        # Only pass ``base_url`` when a truthy override is configured — slack_sdk
+        # rejects ``base_url=None`` (it requires a string), and an empty string
+        # must fall back to the built-in default, so mirroring upstream's truthy
+        # spread keeps the default otherwise.
+        client_kwargs: dict[str, Any] = {"token": resolved_token}
+        if self._slack_api_url:
+            client_kwargs["base_url"] = self._slack_api_url
+        client = AsyncWebClient(**client_kwargs)
         self._client_cache[resolved_token] = client
         if len(self._client_cache) > self._client_cache_max:
             # Evict oldest (LRU).  We intentionally do NOT close the evicted
@@ -895,7 +914,12 @@ def _get_web_client_for_token(self, token: str) -> Any:
         if client is None:
             from slack_sdk import WebClient
 
-            client = WebClient(token=token)
+            # Same truthy ``base_url`` rule as ``_get_client`` — pass the
+            # override only when truthy so slack_sdk keeps its default.
+            web_client_kwargs: dict[str, Any] = {"token": token}
+            if self._slack_api_url:
+                web_client_kwargs["base_url"] = self._slack_api_url
+            client = WebClient(**web_client_kwargs)
             self._web_client_cache[token] = client
         return client
 

src/chat_sdk/adapters/slack/types.py

@@ -41,6 +41,14 @@
 class SlackAdapterConfig:
     """Configuration for the Slack adapter."""
 
+    # Override the Slack Web API base URL (passed as ``base_url`` to every
+    # ``slack_sdk`` client the adapter builds — the default client, the
+    # per-token async cache, and the synchronous ``web_client`` escape hatch).
+    # Defaults to the ``SLACK_API_URL`` env var, then to slack_sdk's built-in
+    # ``https://slack.com/api/``. Mirrors upstream ``config.apiUrl`` →
+    # ``slackApiUrl`` (vercel/chat 6b17c60). Useful for proxies, Slack-API
+    # mocks in tests, or Enterprise-routed deployments.
+    api_url: str | None = None
     # App-level token (xapp-...). Required when ``mode == "socket"``.
     app_token: str | None = None
     # Bot token (xoxb-...). Required for single-workspace mode. Omit for multi-workspace.