Add auto name-to-UUID resolution, LinearServerError, and smoke workflow

Author: eli-the-wizard

.github/workflows/publish.yml

@@ -54,8 +54,15 @@ jobs:
           name: dist
           path: dist/
 
-  publish:
+  smoke:
     needs: [test, build]
+    uses: ./.github/workflows/smoke.yml
+    if: github.event_name == 'release'
+    secrets:
+      LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}
+
+  publish:
+    needs: [test, build, smoke]
     if: github.event_name == 'release'
     runs-on: ubuntu-latest
     environment:

.github/workflows/smoke.yml

@@ -0,0 +1,35 @@
+name: Smoke Tests
+
+on:
+  workflow_call:
+    inputs:
+      team-id:
+        description: "Linear team UUID for the smoke test"
+        required: false
+        type: string
+    secrets:
+      LINEAR_API_KEY:
+        required: true
+  workflow_dispatch:
+    inputs:
+      team-id:
+        description: "Linear team UUID for the smoke test (optional, auto-detected if omitted)"
+        required: false
+        type: string
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Run smoke tests
+        env:
+          LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}
+          LINEAR_TEAM_ID: ${{ inputs.team-id }}
+        run: uv run python scripts/smoke_test.py

README.md

@@ -74,10 +74,10 @@ with LinearClient() as client:
     issue = client.issue(IssueRequest(id="ENG-123")).issue
     print(issue.title, issue.state.name)
 
-    # Create an issue
+    # Create an issue — team name, key, or UUID all work
     created = client.create_issue(
         IssueCreateRequest(
-            team_id="9cfb482a-81e3-4154-b5b9-2c805e70a02d",
+            team_id="Engineering",
             title="New exception",
             description="More detailed error report in **markdown**",
             priority=2,
@@ -162,32 +162,37 @@ for child in detail.children:
     print("sub-issue:", child.identifier, child.title)
 ```
 
-## Looking things up by name (instead of UUIDs)
+## Passing names instead of UUIDs
 
-Most calls take UUIDs. Use the `find_*` resolvers to turn a human name/key/email into
-the entity (and its `.id`) first:
+`create_issue` and `update_issue` automatically resolve non-UUID strings to UUIDs, so
+you can pass human-readable names without a separate lookup:
 
 ```python
-from linear_python_client import (
-    FindTeamRequest, FindUserRequest, FindProjectRequest, FindLabelRequest,
-    IssueCreateRequest,
-)
-
-team = client.find_team(FindTeamRequest(key="RAV")).team        # or name="Ravens"
-assignee = client.find_user(FindUserRequest(name="Elijah Winter")).user  # or email=...
-bug = client.find_label(FindLabelRequest(name="bug", team_id=team.id)).label
+from linear_python_client import IssueCreateRequest
 
 client.create_issue(IssueCreateRequest(
-    team_id=team.id,
+    team_id="Engineering",            # team display name, or "ENG" for the key
     title="New issue",
-    assignee_id=assignee.id,
-    label_ids=[bug.id],
+    assignee_id="alice@example.com",  # email, or display name
+    label_ids=["bug", "urgent"],      # label names
+    project_id="Roadmap",             # project name
+    state_id="In Progress",           # workflow state name (create only)
 ))
 ```
 
-Each resolver returns the matching entity, or `None` if nothing matches. Name matching
-is case-insensitive; team `key` is matched exactly. `find_workflow_state` (for statuses)
-works the same way.
+UUID values are passed through untouched. For everything else, the `find_*` resolvers
+turn a name/key/email into the entity (and its `.id`) explicitly:
+
+```python
+from linear_python_client import FindTeamRequest, FindUserRequest, FindLabelRequest
+
+team = client.find_team(FindTeamRequest(key="RAV")).team              # or name="Ravens"
+user = client.find_user(FindUserRequest(name="Elijah Winter")).user   # or email=...
+bug  = client.find_label(FindLabelRequest(name="bug", team_id=team.id)).label
+```
+
+Each resolver returns the entity or `None`. Name matching is case-insensitive; team
+`key` is exact.
 
 ## Escape hatch: raw GraphQL
 
@@ -212,18 +217,26 @@ All exceptions subclass `LinearError`:
 
 | Exception | Raised when |
 |-----------|-------------|
-| `LinearAuthenticationError` | Credentials are rejected (HTTP 401/403 or auth error code) |
-| `LinearRateLimitError` | A rate limit is hit (`RATELIMITED`); carries the `X-RateLimit-*` header values |
+| `LinearAuthenticationError` | Credentials are rejected (HTTP 401/403, or `AUTHENTICATION_ERROR` / `UNAUTHENTICATED` / `FORBIDDEN` error code) |
+| `LinearRateLimitError` | A rate limit is hit; carries all `X-RateLimit-*` header values including endpoint-level limits |
 | `LinearGraphQLError` | The API returns GraphQL `errors`; exposes `.errors` and `.code` |
-| `LinearNetworkError` | The request never produced a usable response |
+| `LinearNetworkError` | The request never produced a usable response (connection error, non-JSON body) |
+| `LinearServerError` | Linear returned HTTP 5xx; exposes `.status_code` and `.body_preview` |
+
+Error messages include the error code, Linear's `userPresentableMessage`, and any
+field-level validation details.
 
 ```python
-from linear_python_client import LinearClient, LinearRateLimitError, IssuesRequest
+from linear_python_client import LinearClient, LinearRateLimitError, LinearServerError, IssuesRequest
 
 try:
     client.issues(IssuesRequest(first=100))
 except LinearRateLimitError as exc:
     print("Rate limited; resets at", exc.requests_reset)
+    if exc.endpoint_name:
+        print(f"  endpoint {exc.endpoint_name!r}: {exc.endpoint_requests_remaining} remaining")
+except LinearServerError as exc:
+    print(f"Linear server error HTTP {exc.status_code}")
 ```
 
 ## Available client methods
@@ -281,19 +294,28 @@ prints after each run — add `--cov-report=html` for an annotated HTML report i
 
 ### Live smoke test
 
-`scripts/smoke_test.py` exercises **every** client method against the real Linear API
-and, after each mutation, re-pulls the issue to confirm the change landed (create →
-update → set status → add/remove label → comment → full details). It creates one
-clearly-labelled test issue and archives it at the end, so it cleans up after itself.
+`scripts/smoke_test.py` exercises **every** client method against the real Linear API.
+It covers:
+
+- All read-only endpoints (viewer, users, teams, projects, labels, states, comments, pagination)
+- Resolvers both ways: `find_*` by UUID **and** by name/key/email
+- Auto-resolution end-to-end: `create_issue` with team name, assignee name, and label names
+- `issue()` by UUID **and** by human identifier (e.g. `"ENG-123"`)
+- All mutations (create → update → set status → add/remove label → comment → full details)
+
+After each mutation it re-pulls the issue to confirm the change landed. It creates
+clearly-labelled test issues and archives them at the end.
 
 ```sh
 LINEAR_API_KEY=lin_api_... uv run python scripts/smoke_test.py
 # optionally pin the team (defaults to the first one):
 LINEAR_API_KEY=... LINEAR_TEAM_ID=<uuid> uv run python scripts/smoke_test.py
 ```
 
-It prints a ✓/✗ per check and exits non-zero if any fail. Because it writes to your
-workspace, it's a manual script — it is not part of `pytest`.
+It prints a ✓/✗ per check and exits non-zero if any fail. The smoke test is also run
+automatically as part of the release pipeline via
+[`.github/workflows/smoke.yml`](.github/workflows/smoke.yml), which can be triggered
+manually via `workflow_dispatch` or is called by `publish.yml` on every release.
 
 ### Building & releasing
 
@@ -307,8 +329,10 @@ uvx twine check dist/*  # validate metadata / README rendering
 Releases are automated by [`.github/workflows/publish.yml`](.github/workflows/publish.yml).
 On every push and PR it lints, tests (with the coverage gate), builds the sdist + wheel,
 validates the metadata, and smoke-tests that the wheel installs and imports. When a
-**GitHub Release is published**, it additionally publishes the build to PyPI — after
-which `pip install linear-python-client` and `uv add linear-python-client` work.
+**GitHub Release is published**, it additionally runs the live smoke test suite against
+the real Linear API (requires a `LINEAR_API_KEY` repository secret) and then publishes
+to PyPI — only if all checks pass. After publishing, `pip install linear-python-client`
+and `uv add linear-python-client` work.
 
 Publishing uses [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
 (OIDC), so no API token or secret is stored. One-time setup:

docs/api/errors.md

@@ -13,3 +13,4 @@ Every exception raised by the client subclasses
         - LinearRateLimitError
         - LinearGraphQLError
         - LinearNetworkError
+        - LinearServerError

docs/index.md

@@ -18,9 +18,11 @@ Built against the [Linear developer docs](https://linear.app/developers).
 - **Pydantic models.** Snake_case attributes with camelCase aliases; validation and
   serialisation come for free.
 - **Both auth methods.** Personal API keys and OAuth 2.0 access tokens.
+- **Names instead of UUIDs.** Pass a team name, user email, or label name directly to
+  `create_issue` / `update_issue` — UUIDs are resolved automatically.
 - **Pagination made trivial.** `paginate()` follows the cursor for you.
-- **Real error handling.** Auth, rate-limit, and GraphQL errors map to typed
-  exceptions.
+- **Real error handling.** Auth, rate-limit, server (5xx), and GraphQL errors map to
+  typed exceptions with full context.
 - **No lock-in.** `execute()` runs any raw GraphQL query or mutation.
 
 ## Install
@@ -43,7 +45,7 @@ with LinearClient(api_key="lin_api_...") as client:
 
     created = client.create_issue(
         IssueCreateRequest(
-            team_id="9cfb482a-81e3-4154-b5b9-2c805e70a02d",
+            team_id="Engineering",  # name, key, or UUID — all accepted
             title="New exception",
             priority=2,
         )

docs/usage.md

@@ -160,6 +160,30 @@ Any field accepted by Linear's `IssueCreateInput` / `IssueUpdateInput` can be pa
 as an extra keyword argument using its camelCase API name (e.g. `dueDate="2026-01-01"`),
 even if it isn't an explicit field on the request model.
 
+### Passing names instead of UUIDs
+
+`create_issue` automatically resolves non-UUID strings to UUIDs before sending the
+request, so you can pass human-readable names directly without a separate `find_*` call:
+
+```python
+created = client.create_issue(
+    IssueCreateRequest(
+        team_id="Engineering",         # team display name  (or "ENG" for the key)
+        title="New exception",
+        assignee_id="alice@example.com",  # email, or display name
+        label_ids=["bug", "urgent"],      # label names
+        project_id="Roadmap",             # project name
+        state_id="In Progress",           # workflow state name
+    )
+)
+```
+
+UUID values are passed through untouched, so you can freely mix UUIDs and names.
+
+`update_issue` resolves `assignee_id`, `project_id`, and `label_ids` the same way.
+`state_id` in an update requires a UUID (no team context is available to look up a
+state by name; use `find_workflow_state` first if you only have the name).
+
 ## Labels
 
 `update_issue(IssueUpdateRequest(id=..., label_ids=[...]))` replaces an issue's whole
@@ -216,16 +240,20 @@ labels = client.issue_labels(IssueLabelsRequest(first=100))
 
 ## Resolving names to UUIDs
 
-Most methods take UUIDs. The `find_*` resolvers turn a human name/key/email into the
-entity (read its `.id` to pass elsewhere). Each returns the matching entity or `None`;
+For `create_issue` and `update_issue`, the client resolves non-UUID strings
+automatically — see [Passing names instead of UUIDs](#passing-names-instead-of-uuids)
+above.
+
+For everything else, use the `find_*` resolvers to turn a human name/key/email into
+an entity (read `.id` to pass elsewhere). Each returns the matching entity or `None`;
 name matching is case-insensitive, team `key` is exact.
 
 ```python
 from linear_python_client import (
     FindTeamRequest, FindUserRequest, FindProjectRequest, FindLabelRequest,
 )
 
-team = client.find_team(FindTeamRequest(key="RAV")).team           # or name="Ravens"
+team = client.find_team(FindTeamRequest(key="RAV")).team             # or name="Ravens"
 user = client.find_user(FindUserRequest(name="Elijah Winter")).user  # or email="..."
 project = client.find_project(FindProjectRequest(name="Roadmap")).project
 bug = client.find_label(FindLabelRequest(name="bug", team_id=team.id)).label
@@ -259,24 +287,51 @@ All exceptions subclass [`LinearError`][linear_python_client.LinearError]:
 
 | Exception | Raised when |
 |-----------|-------------|
-| [`LinearAuthenticationError`][linear_python_client.LinearAuthenticationError] | Credentials are rejected (HTTP 401/403 or an auth error code) |
-| [`LinearRateLimitError`][linear_python_client.LinearRateLimitError] | A rate limit is hit (`RATELIMITED`); carries the `X-RateLimit-*` header values |
+| [`LinearAuthenticationError`][linear_python_client.LinearAuthenticationError] | Credentials are rejected (HTTP 401/403, or `AUTHENTICATION_ERROR` / `UNAUTHENTICATED` / `FORBIDDEN` error code) |
+| [`LinearRateLimitError`][linear_python_client.LinearRateLimitError] | A rate limit is hit (`RATELIMITED`); carries all `X-RateLimit-*` header values including endpoint-level limits |
 | [`LinearGraphQLError`][linear_python_client.LinearGraphQLError] | The API returns GraphQL `errors`; exposes `.errors` and `.code` |
-| [`LinearNetworkError`][linear_python_client.LinearNetworkError] | The request never produced a usable response |
+| [`LinearNetworkError`][linear_python_client.LinearNetworkError] | The request never produced a usable response (connection error, non-JSON body) |
+| [`LinearServerError`][linear_python_client.LinearServerError] | Linear returned an HTTP 5xx response; exposes `.status_code` and `.body_preview` |
+
+Error messages include the error code, Linear's `userPresentableMessage` when
+available, and any field-level validation details from `extensions.errors`.
 
 ```python
-from linear_python_client import LinearClient, LinearRateLimitError, IssuesRequest
+from linear_python_client import (
+    LinearClient,
+    LinearRateLimitError,
+    LinearServerError,
+    IssuesRequest,
+)
 
 try:
     client.issues(IssuesRequest(first=100))
 except LinearRateLimitError as exc:
     print("Rate limited; resets at", exc.requests_reset)
+    # Endpoint-specific limit (e.g. issueCreate has a tighter cap):
+    if exc.endpoint_name:
+        print(f"  endpoint {exc.endpoint_name!r}: {exc.endpoint_requests_remaining} remaining")
+except LinearServerError as exc:
+    print(f"Linear server error HTTP {exc.status_code}: {exc.body_preview}")
 ```
 
 ## Rate limits
 
 Linear allows roughly **5,000 requests/hour** for API keys and OAuth apps, with a
-separate complexity budget. The client surfaces the relevant `X-RateLimit-*` header
-values on [`LinearRateLimitError`][linear_python_client.LinearRateLimitError] when a limit is
-hit. See the [rate limiting docs](https://linear.app/developers/rate-limiting) for the
-full details.
+separate complexity budget. Some endpoints have their own tighter per-endpoint caps.
+The client surfaces all `X-RateLimit-*` header values on
+[`LinearRateLimitError`][linear_python_client.LinearRateLimitError] when a limit is hit:
+
+| Attribute | Header |
+|-----------|--------|
+| `requests_limit` | `X-RateLimit-Requests-Limit` |
+| `requests_remaining` | `X-RateLimit-Requests-Remaining` |
+| `requests_reset` | `X-RateLimit-Requests-Reset` (ms epoch) |
+| `query_complexity` | `X-Complexity` |
+| `endpoint_requests_limit` | `X-RateLimit-Endpoint-Requests-Limit` |
+| `endpoint_requests_remaining` | `X-RateLimit-Endpoint-Requests-Remaining` |
+| `endpoint_requests_reset` | `X-RateLimit-Endpoint-Requests-Reset` (ms epoch) |
+| `endpoint_name` | `X-RateLimit-Endpoint-Name` |
+
+See the [rate limiting docs](https://linear.app/developers/rate-limiting) for the full
+details.