diff --git a/AGENT_SETUP.md b/AGENT_SETUP.md index c171962..eba6e4f 100644 --- a/AGENT_SETUP.md +++ b/AGENT_SETUP.md @@ -18,7 +18,8 @@ PyPI yet). Repo: `https://github.com/AJFrio/Bild-Python.git`. ## What to ask the human -Ask these in the human's language. Do not invent answers. +Ask **only** these two things, in the human's language. Do not invent +answers. Do not add extra setup questions. ### 1. Bild API token (required) @@ -30,8 +31,7 @@ Prompt: > commit it or print it again. If they do not have a token, stop. Tell them to have an admin issue one in -the Bild app, then come back. Do not guess a token. Do not ask for their -Bild password — this SDK only accepts a JWT. +the Bild app, then come back. Do not guess a token. ### 2. Install location (required if you are not already in this repo) @@ -43,12 +43,20 @@ Prompt: Default clone URL: `https://github.com/AJFrio/Bild-Python.git` -### 3. API host (optional) +## Do not invent a host or auth scheme -Default: `https://api.getbild.com` +The host is always `https://api.getbild.com`. Auth is always a Bearer JWT +personal access token (`BILD_API_KEY` / `token=`). -Only ask if they mention a custom or non-production host. If they give one, -you will pass `base_url=...` into `BildClient`. Otherwise omit it. +Do **not** ask about: + +- which host or endpoint to use +- AWS Lambda, staging, or any other URL +- OAuth, passwords, API keys that are not this JWT, or "custom auth" + +If the human volunteers a different host or auth method, tell them this +SDK only talks to `https://api.getbild.com` with a Bild JWT, then continue +with the token they paste. ## Install @@ -94,9 +102,6 @@ Rules: - Prefer `.env` over putting the token in the shell, so later `BildClient()` calls work without the human pasting it again. -If they gave a custom host, you do not need to store it unless they ask; -pass it only when constructing the client. - ## Handshake (required) From the repo root, with the venv active, run this exact code: @@ -109,15 +114,8 @@ result = client.verify() print(result) ``` -If they gave a custom host: - -```python -client = BildClient(base_url="https://their-host.example") -result = client.verify() -``` - -`verify()` is read-only. It calls `users.list` and `projects.list` and -returns a dict shaped like: +Do not pass `base_url`. `verify()` is read-only. It calls `users.list` and +`projects.list` and returns a dict shaped like: ```python { @@ -146,8 +144,8 @@ Use this shape. Include the real `result` value. Do not omit it. | Error | Meaning | What you do | | --- | --- | --- | | `ValueError: Missing token` | `.env` not loaded or empty | Fix `.env`, retry `verify()` | -| `BildAuthError` (401/403) | Token invalid, expired, or wrong host | Ask for a new token; do not retry blindly | -| Other `BildAPIError` | Host or API problem | Show `status_code` and `payload`; ask the human | +| `BildAuthError` (401/403) | Token invalid or expired | Ask for a new token; do not retry blindly | +| Other `BildAPIError` | API problem | Show `status_code` and `payload`; ask the human | Do not declare setup complete without a successful `verify()` return value. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 975a8cd..28e4936 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -53,7 +53,7 @@ Each `*API` class holds a `client: BildClient` and only issues HTTP via ## HTTP contract -- Default host: `https://api.getbild.com` +- Host: `https://api.getbild.com` - Auth: `Authorization: Bearer ` on every request - `Accept: application/json` is set on the session - `Content-Type` is **not** set on the session. `requests` adds it only when diff --git a/README.md b/README.md index 328f03f..79fd42c 100644 --- a/README.md +++ b/README.md @@ -54,8 +54,6 @@ client = BildClient(token="YOUR_JWT_TOKEN") `BildClient()` with no arguments reads `BILD_API_KEY`. A missing token raises `ValueError`. Invalid or expired tokens raise `BildAuthError` (HTTP 401/403). Other failed responses raise `BildAPIError`. -Default API host: `https://api.getbild.com`. - ## 3) Basic usage ```python @@ -162,12 +160,6 @@ These map to the groups in the [Bild External API reference](https://bildexterna --- -## Advanced: custom base URL - -```python -client = BildClient(token="YOUR_JWT_TOKEN", base_url="https://api.getbild.com") -``` - ## Escape hatch for unwrapped endpoints ```python diff --git a/docs/design-docs/http-client.md b/docs/design-docs/http-client.md index 594f4d9..9f7ab7f 100644 --- a/docs/design-docs/http-client.md +++ b/docs/design-docs/http-client.md @@ -19,7 +19,7 @@ when `json=` is passed to `session.request`. ## URL building `{base_url}/{path}` with `base_url` stripped of a trailing slash and `path` -stripped of a leading slash. Default `base_url` is `https://api.getbild.com`. +stripped of a leading slash. The host is `https://api.getbild.com`. ## Resolvers diff --git a/docs/references/bild-api.md b/docs/references/bild-api.md index 025bc21..380ef63 100644 --- a/docs/references/bild-api.md +++ b/docs/references/bild-api.md @@ -4,7 +4,7 @@ Upstream reference (wins on path, method, and payload shape): https://bildexternalapi.portledocs.com/#/docs/apireference?api_page=introduction&product_version=77 -Default host used by this SDK: `https://api.getbild.com`. +Host used by this SDK: `https://api.getbild.com`. When the reference and this client disagree, change the client and tests first, then the README examples. diff --git a/tests/test_docs.py b/tests/test_docs.py index e9f6528..74c395f 100644 --- a/tests/test_docs.py +++ b/tests/test_docs.py @@ -18,6 +18,16 @@ def test_architecture_describes_layers(self): self.assertIn("bild/errors.py", text) self.assertIn("Content-Type", text) + def test_agent_setup_does_not_invite_alternate_host_or_auth(self): + text = (ROOT / "AGENT_SETUP.md").read_text(encoding="utf-8") + lowered = text.lower() + self.assertIn("https://api.getbild.com", text) + self.assertIn("jwt", lowered) + self.assertIn("do not invent", lowered) + self.assertIn("ask about", lowered) + for banned in ("custom host", "non-production", "their-host"): + self.assertNotIn(banned, lowered) + if __name__ == "__main__": unittest.main()