Merge pull request #6 from block/feat/art-850/enable-gha-openapi-spec-update

feat: upgrade codegen, refresh models, and add OpenAPI drift check

Author: orest-tokovenko-block

.githooks/commit-msg

@@ -0,0 +1,18 @@
+#!/bin/sh
+
+commit_msg=$(head -1 "$1")
+
+if ! echo "$commit_msg" | grep -qE '^(feat|fix|chore|docs|ci|test|refactor|perf|build|style|revert)(\(.+\))?(!)?: .+'; then
+  echo "ERROR: Commit message must follow Conventional Commits format"
+  echo ""
+  echo "  <type>[optional scope][!]: <description>"
+  echo ""
+  echo "  Types: feat, fix, chore, docs, ci, test, refactor, perf, build, style, revert"
+  echo ""
+  echo "  Examples:"
+  echo "    feat: add dashboard endpoints"
+  echo "    fix(models): handle null chart_settings"
+  echo "    feat!: rename VantageSDK to VantageClient"
+  echo ""
+  exit 1
+fi

.github/workflows/check-openapi-spec.yml

@@ -0,0 +1,50 @@
+name: Check OpenAPI Spec
+
+on:
+  schedule:
+    - cron: '0 9 * * *'  # Daily at 9am UTC
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  check-spec:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+    - name: Install the latest version of uv
+      uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+      with:
+        version: "latest"
+        enable-cache: true
+
+    - name: Fetch latest spec and regenerate models
+      run: |
+        curl -sS https://api.vantage.sh/v2/oas_v3.json -o openapi_spec.json
+        uv run datamodel-codegen
+
+    - name: Check for differences
+      id: diff
+      run: |
+        if [[ -n "$(git status --porcelain --untracked-files=all -- vantage_sdk/models/gen_models/)" ]]; then
+          echo "changed=true" >> "$GITHUB_OUTPUT"
+        else
+          echo "changed=false" >> "$GITHUB_OUTPUT"
+        fi
+
+    - name: Create pull request
+      if: steps.diff.outputs.changed == 'true'
+      uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7
+      with:
+        commit-message: "chore: update OpenAPI spec and regenerate models"
+        title: "chore: update OpenAPI spec and regenerate models"
+        body: |
+          The upstream Vantage OpenAPI spec has changed. This PR updates `openapi_spec.json` and regenerates the models in `vantage_sdk/models/gen_models/`.
+
+          Please review the generated model changes for any breaking impacts.
+        branch: chore/update-openapi-spec
+        delete-branch: true

.github/workflows/python-test.yml

@@ -7,7 +7,7 @@ on:
     branches: '*'
 
 jobs:
-  tests:
+  python-test:
     runs-on: ubuntu-latest
 
     steps:

CONTRIBUTORS.md

@@ -2,7 +2,13 @@
 
 ## Development Setup
 
-Install the sdk locally and run tests when you finish making changes:
+```bash
+just setup
+```
+
+This configures git hooks that enforce [Conventional Commits](https://www.conventionalcommits.org/) on commit messages (see [Releases](#releases)).
+
+To run all checks (format, lint, typecheck, test):
 
 ```bash
 uv run nox
@@ -78,6 +84,19 @@ Re-record cassettes when:
 - An API response schema changes (use `just test-vcr-rewrite tests/test_main.py::test_affected_test`)
 - A fixture changes the request payload (field values, resource names, etc.)
 
+## Releases
+
+Releases are automated via [release-please](https://github.com/googleapis/release-please). PR titles must use [Conventional Commits](https://www.conventionalcommits.org/) prefixes, and PRs must be squash-merged so the title becomes the commit message.
+
+| Prefix | Version bump | Example |
+|---|---|---|
+| `fix:` | Patch (1.1.1 -> 1.1.2) | `fix: handle null chart_settings in cost reports` |
+| `feat:` | Minor (1.1.1 -> 1.2.0) | `feat: add dashboard endpoints` |
+| `feat!:` | Major (1.1.1 -> 2.0.0) | `feat!: rename VantageSDK to VantageClient` |
+| `chore:`, `docs:`, `ci:` | No release | `chore: update dev dependencies` |
+
+When commits land on `main`, release-please opens (or updates) a Release PR that bumps the version in `pyproject.toml` and updates `CHANGELOG.md`. Merging that Release PR triggers the publish to PyPI. Do not manually edit the version in `pyproject.toml`.
+
 ## Regenerating Models
 
 `vantage_sdk/models/gen_models/` is generated using the `datamodel-codegen` tool. All codegen configuration lives in `pyproject.toml` under `[tool.datamodel-codegen]`.

README.md

@@ -32,7 +32,11 @@ This SDK is a Python client built around the [Vantage API], providing a streamli
 
 ```python
 from vantage_sdk import VantageSDK
-from vantage_sdk.models import CreateCostReport
+from vantage_sdk.models import (
+    CreateCostReport,
+    CreateCostReportChartType,
+    CreateCostReportDateBin,
+)
 
 vantage = VantageSDK(vantage_api_key)
 
@@ -49,9 +53,8 @@ cost_report = CreateCostReport(
     previous_period_end_date="2024-01-31",
     start_date="2024-02-01",
     end_date="2024-02-28",
-    date_interval=DateInterval.this_month,
-    chart_type=ChartType.line,
-    date_bin=DateBin.cumulative
+    chart_type=CreateCostReportChartType.line,
+    date_bin=CreateCostReportDateBin.cumulative,
 )
 
 response = vantage.create_cost_report(cost_report)

justfile

@@ -37,9 +37,21 @@ typecheck-tests:
 
 check: format lint typecheck test
 
+# --- Setup ---
+
+setup:
+  git config core.hooksPath .githooks
+
 # --- Code Generation ---
 
 generate-models:
   uv run datamodel-codegen \
     --url https://api.vantage.sh/v2/oas_v3.json \
-    --output model.py
+    --output vantage_sdk/models/gen_models/
+
+fetch-spec:
+  curl -sS https://api.vantage.sh/v2/oas_v3.json -o openapi_spec.json
+
+regenerate-models: fetch-spec
+  rm -rf vantage_sdk/models/gen_models/
+  uv run datamodel-codegen

pyproject.toml

@@ -24,7 +24,6 @@ dependencies = [
     "pydantic-settings>=2.7.1",
     "pydantic-extra-types>=2.10.2",
     "httpx>=0.28.1",
-    "pendulum>=3.0.0",
 ]
 
 [dependency-groups]
@@ -34,7 +33,7 @@ dev = [
     "ruff>=0.12.0",
     "nox>=2025.05.01",
     "pytest-mock>=3.14.0",
-    "datamodel-code-generator[http,ruff]>=0.53.0",
+    "datamodel-code-generator[http,ruff]>=0.55.0",
     "pytest-timeout>=2.4.0",
     "basedpyright>=1.29.0",
 ]
@@ -104,11 +103,14 @@ field-constraints = true
 use-annotated = true
 strict-nullable = true
 use-default-kwarg = true
+set-default-enum-member = true
+allow-population-by-field-name = true
 naming-strategy = "primary-first"
 parent-scoped-naming = true
 all-exports-scope = "recursive"
 all-exports-collision-strategy = "minimal-prefix"
 openapi-scopes = ["schemas", "paths", "parameters"]
+disable-timestamp = true
 formatters = ["ruff-format", "ruff-check"]
 
 [tool.ruff.lint]
@@ -161,4 +163,4 @@ quote-style = "double"
 
 [tool.pyproject-fmt]
 column_width = 120
-indent = 4
+indent = 4

tests/cassettes/test_update_user.yaml

@@ -0,0 +1,125 @@
+interactions:
+- request:
+    body: ''
+    headers:
+      Accept:
+      - application/json
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      Content-Type:
+      - application/json
+      Host:
+      - api.vantage.sh
+      User-Agent:
+      - python-httpx/0.28.1
+    method: GET
+    uri: https://api.vantage.sh/v2/users?page=1
+  response:
+    body:
+      string: '{"links":{"self":"https://api.vantage.sh/v2/users?page=1","first":"https://api.vantage.sh/v2/users?page=1","next":null,"last":"https://api.vantage.sh/v2/users?page=1","prev":null},"users":[{"token":"usr_3b8e93c36c581811","name":"Block
+        Open Source","email":"blockopensource@gmail.com","role":"Owner","default_dashboard_token":null,"last_seen_at":"2025-11-25"}]}'
+    headers:
+      Access-Control-Allow-Origin:
+      - '*'
+      Access-Control-Request-Method:
+      - '*'
+      Cache-Control:
+      - max-age=0, private, must-revalidate
+      Connection:
+      - keep-alive
+      Content-Security-Policy:
+      - 'default-src ''self'' https:; font-src ''self'' https: data: https://fonts.gstatic.com;
+        img-src ''self'' https: data:; object-src ''none''; script-src ''self'' https:
+        ''unsafe-inline''; style-src ''self'' https: https://fonts.googleapis.com
+        ''unsafe-inline''; connect-src ''self'' https: https://browser-intake-datadoghq.com;
+        report-uri https://browser-intake-datadoghq.com/api/v2/logs?dd-api-key=pub6a4daf9be897fccfebb14341baa5d70c&dd-evp-origin=content-security-policy&ddsource=csp-report'
+      Content-Type:
+      - application/json
+      ETag:
+      - W/"f25d06f5a4e978f3373b4424ed03435e"
+      Set-Cookie:
+      - _stratus_session=LUF1z%2BSIWHEFDGBa9rZFdsIVVvOqFjYT3qfgEzd0N7IcHL8pK%2FXqRjUFaWn01IQe%2BW%2F08LcO46sTQrWOZltgpL5ifNJQFUMy5g2JeOenn2PE9MPrUzkvY38j73tU%2FmTvl3omju0NgYdV%2F2YAczChgYY0kqJFfHSK6fXMUHrSBw%2B6DcZ3U%2FX3ZUM0nMOQBgXdwSW46M7wods%3D--cvXgs%2BI4F%2BxY2fVd--61tp8gkQszvf4D0WKVyoDw%3D%3D;
+        path=/; secure; HttpOnly; SameSite=Lax
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains
+      Vary:
+      - Accept-Encoding
+      X-Rate-Limit-Limit:
+      - '1000'
+      X-Rate-Limit-Remaining:
+      - '991'
+      X-Rate-Limit-Reset:
+      - '1773342605'
+      X-Runtime:
+      - '0.051649'
+      content-length:
+      - '360'
+    status:
+      code: 200
+      message: OK
+- request:
+    body: '{}'
+    headers:
+      Accept:
+      - application/json
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '2'
+      Content-Type:
+      - application/json
+      Cookie:
+      - _stratus_session=LUF1z%2BSIWHEFDGBa9rZFdsIVVvOqFjYT3qfgEzd0N7IcHL8pK%2FXqRjUFaWn01IQe%2BW%2F08LcO46sTQrWOZltgpL5ifNJQFUMy5g2JeOenn2PE9MPrUzkvY38j73tU%2FmTvl3omju0NgYdV%2F2YAczChgYY0kqJFfHSK6fXMUHrSBw%2B6DcZ3U%2FX3ZUM0nMOQBgXdwSW46M7wods%3D--cvXgs%2BI4F%2BxY2fVd--61tp8gkQszvf4D0WKVyoDw%3D%3D
+      Host:
+      - api.vantage.sh
+      User-Agent:
+      - python-httpx/0.28.1
+    method: PUT
+    uri: https://api.vantage.sh/v2/users/usr_3b8e93c36c581811
+  response:
+    body:
+      string: '{"token":"usr_3b8e93c36c581811","name":"Block Open Source","email":"blockopensource@gmail.com","role":"Owner","default_dashboard_token":null,"last_seen_at":"2025-11-25"}'
+    headers:
+      Access-Control-Allow-Origin:
+      - '*'
+      Access-Control-Request-Method:
+      - '*'
+      Cache-Control:
+      - max-age=0, private, must-revalidate
+      Connection:
+      - keep-alive
+      Content-Security-Policy:
+      - 'default-src ''self'' https:; font-src ''self'' https: data: https://fonts.gstatic.com;
+        img-src ''self'' https: data:; object-src ''none''; script-src ''self'' https:
+        ''unsafe-inline''; style-src ''self'' https: https://fonts.googleapis.com
+        ''unsafe-inline''; connect-src ''self'' https: https://browser-intake-datadoghq.com;
+        report-uri https://browser-intake-datadoghq.com/api/v2/logs?dd-api-key=pub6a4daf9be897fccfebb14341baa5d70c&dd-evp-origin=content-security-policy&ddsource=csp-report'
+      Content-Type:
+      - application/json
+      ETag:
+      - W/"7efcead6f0b62066feb211c8d4a6f709"
+      Set-Cookie:
+      - _stratus_session=24Qe4NLMltYtIyRoAte0R22jxIibxUDcM1NuZSplqlYQ4B8EMLseVSHkFXf3LsB2EXI%2Fyo9d6ve6sCplXhH4Q5jojWtl%2FkizyBJOYnd%2FzH9H4MOVc7f%2BerYbNkZ1ujnkdL7BK9jYvPPKYoW501su8Np%2BR3vwyLGAtPUarMaTV2l%2BCRXwieR%2F0PcSgcVUreQGhyUyxBwsAYA%3D--Wd7T0TuUk%2Bj7tMCz--VYBX43iS64r6d5YrX5pGAQ%3D%3D;
+        path=/; secure; HttpOnly; SameSite=Lax
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains
+      Vary:
+      - Accept-Encoding
+      X-Rate-Limit-Limit:
+      - '1000'
+      X-Rate-Limit-Remaining:
+      - '990'
+      X-Rate-Limit-Reset:
+      - '1773342605'
+      X-Runtime:
+      - '0.062798'
+      content-length:
+      - '169'
+    status:
+      code: 200
+      message: OK
+version: 1

tests/conftest.py

@@ -138,10 +138,14 @@ def pytest_configure(config) -> None:
     """Register custom markers"""
     config.addinivalue_line("markers", "slow: mark test as a long running test")
     config.addinivalue_line("markers", "live: mark test as requiring the live API")
+    config.addinivalue_line("markers", "vcr_only: mark test as requiring VCR cassettes (skipped against live API)")
 
 def pytest_collection_modifyitems(items):
     use_vcr = settings.vcr_enabled
     if not use_vcr:
+        for item in items:
+            if item.get_closest_marker("vcr_only"):
+                item.add_marker(pytest.mark.skip(reason="Test requires VCR cassettes, not runnable against live API"))
         return
     for item in items:
         item.add_marker(pytest.mark.vcr)