Release v3.0.0: Answer API, Speakeasy removal, flattened API surface

.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  # The project resolves with uv and commits uv.lock; the `pip` ecosystem reads
+  # pyproject.toml but leaves the lockfile stale, so use `uv` instead.
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      dev-dependencies:
+        dependency-type: development
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5

.github/workflows/drift-check.yml

@@ -0,0 +1,118 @@
+name: drift-check
+
+on:
+  schedule:
+    # Every Monday at 9:00 UTC
+    - cron: "0 9 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: drift-check
+  cancel-in-progress: false
+
+jobs:
+  drift-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install SDK
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+
+      # Exit codes (see scripts/check_drift.py): 0 no drift, 1 drift,
+      # 2 specs unreachable, 3 the check itself is broken. Keeping these
+      # distinct is what stops a traceback from being filed as "drift".
+      - name: Run drift check
+        id: drift
+        run: |
+          set +e
+          OUTPUT=$(python scripts/check_drift.py --strict --verbose 2>&1)
+          EXIT_CODE=$?
+          echo "$OUTPUT"
+          # Random delimiter: a fixed "EOF" would break if it appeared in the output.
+          DELIM="drift_$(openssl rand -hex 8)"
+          {
+            echo "DRIFT_OUTPUT<<${DELIM}"
+            echo "$OUTPUT"
+            echo "${DELIM}"
+          } >> "$GITHUB_ENV"
+          echo "exit_code=$EXIT_CODE" >> "$GITHUB_OUTPUT"
+          exit 0
+
+      - name: Report or update drift issue
+        if: steps.drift.outputs.exit_code == '1'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DRIFT_OUTPUT: ${{ env.DRIFT_OUTPUT }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          set -euo pipefail
+          gh label create drift --color FBCA04 \
+            --description "SDK drift from OpenAPI specs" 2>/dev/null || true
+
+          # Build the body in a file so the fenced block isn't indented by the
+          # surrounding YAML block scalar (indented fences don't render).
+          {
+            echo "The drift check found differences between the You.com OpenAPI specs and the SDK."
+            echo
+            echo '```'
+            echo "${DRIFT_OUTPUT}"
+            echo '```'
+            echo
+            echo "Run \`python scripts/check_drift.py --verbose\` locally to reproduce."
+            echo
+            echo "[Workflow run](${RUN_URL})"
+          } > drift-body.md
+
+          # Update the existing issue instead of filing a duplicate every week.
+          EXISTING=$(gh issue list --label drift --state open \
+            --json number --jq '.[0].number // empty')
+          if [ -n "${EXISTING}" ]; then
+            echo "Updating existing drift issue #${EXISTING}"
+            gh issue comment "${EXISTING}" --body-file drift-body.md
+          else
+            gh issue create \
+              --title "SDK drift detected: OpenAPI specs vs SDK surface" \
+              --body-file drift-body.md \
+              --label drift
+          fi
+
+      - name: Report fetch error
+        if: steps.drift.outputs.exit_code == '2'
+        run: |
+          echo "::warning::Drift check could not fetch the OpenAPI specs (transient, not drift)."
+          echo "${DRIFT_OUTPUT}"
+        env:
+          DRIFT_OUTPUT: ${{ env.DRIFT_OUTPUT }}
+
+      # A broken checker is worse than drift: it reports "no drift" forever.
+      # Fail the job so the run goes red and someone looks at it.
+      - name: Fail on broken drift check
+        if: steps.drift.outputs.exit_code != '0' && steps.drift.outputs.exit_code != '1' && steps.drift.outputs.exit_code != '2'
+        run: |
+          echo "::error::Drift check exited ${{ steps.drift.outputs.exit_code }} — the check itself failed."
+          echo "${DRIFT_OUTPUT}"
+          exit 1
+        env:
+          DRIFT_OUTPUT: ${{ env.DRIFT_OUTPUT }}
+
+      - name: Close stale drift issues
+        if: steps.drift.outputs.exit_code == '0'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # No drift this run, so anything still open has been resolved.
+          gh issue list --label drift --state open --json number --jq '.[].number' | while read -r num; do
+            gh issue close "$num" --comment "No drift detected in the latest check. Closing."
+          done

.github/workflows/test.yml

@@ -6,12 +6,16 @@ on:
   push:
     branches: [main]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
 
@@ -27,17 +31,79 @@ jobs:
 
       - name: Install dependencies
         run: |
+          # --group needs pip >= 25.1; the upgrade above guarantees it. Reading
+          # the group from pyproject keeps CI and local dev on one dependency list.
           python -m pip install --upgrade pip
-          pip install -e ".[dev]"
-          pip install pytest pytest-asyncio
+          pip install --group dev -e .
 
       - name: Build and start mock server
         working-directory: tests/mockserver
         run: |
           go build -o mockserver .
           ./mockserver &
-          sleep 2
-          curl -sf http://localhost:18080/ || echo "mock server ready"
+          SERVER_READY=false
+          for i in $(seq 1 10); do
+            if curl -sf http://localhost:18080/_mockserver/health; then
+              echo "mock server ready"
+              SERVER_READY=true
+              break
+            fi
+            echo "waiting for mock server..."
+            sleep 1
+          done
+          if [ "$SERVER_READY" = false ]; then
+            echo "::error::mock server failed to start within 10 seconds"
+            exit 1
+          fi
+
+      - name: Run tests with coverage
+        run: pytest tests/ -v --tb=short --ignore=tests/test_live.py --ignore=tests/test_performance.py --cov=youdotcom --cov-report=term-missing
+
+      - name: Run mypy
+        run: mypy src/youdotcom/
+
+      # Errors only, and the tree is clean at 10.00/10 — so this gates rather
+      # than reporting into the void the way a continue-on-error step would.
+      - name: Run pylint
+        run: pylint src/youdotcom/ --disable=all --enable=E --rcfile=/dev/null
+
+  build-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tool
+        run: pip install build
+
+      - name: Build package
+        run: python -m build --sdist --wheel
+
+      - name: Verify dist contents
+        run: |
+          ls -la dist/
+          tar -tzf dist/*.tar.gz | head -20
+          echo "Package builds successfully"
+
+  drift-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install SDK
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
 
-      - name: Run tests
-        run: pytest tests/ -v --tb=short -x
+      - name: Run drift check (non-blocking)
+        run: python scripts/check_drift.py --verbose
+        continue-on-error: true

.gitignore

@@ -3,12 +3,13 @@ venv/
 src/*.egg-info/
 **/__pycache__/
 .pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
 .python-version
 .DS_Store
 pyrightconfig.json
-**/.speakeasy/temp/
-**/.speakeasy/logs/
-.speakeasy/reports
 .env
 .env.local
 _debug/