maxio-apiroute 0.1.0__tar.gz

maxio_apiroute-0.1.0/.agent/skills/apiroute-client.md

@@ -0,0 +1,199 @@
+---
+name: apiroute-client
+description: Create, set up and maintain a GitHub repository that publishes apiroute-generated Python clients for an API described by OpenAPI/Swagger specs, WSDLs or a GraphQL schema (with hand-written operations). Covers gathering the specs and documentation links, the repository layout, the apis.yaml generation config, hand-written auth base classes, the README, CI/Build/Release workflows (the Build workflow regenerates and commits changes), PyPI publishing (only if the user wants it), and ongoing maintenance.
+---
+
+# apiroute client repositories
+
+Use this skill when asked to create a client repository for an API ("make a <api>-apiroute repo", e.g. `stripe-apiroute`), or to maintain one: adding or removing an API, a spec change that broke generation, upgrading apiroute, or setting up releases.
+
+A client repository holds generated code that is never edited by hand. It is the output of [apiroute](https://github.com/dougyouch/apiroute)'s generator (`apiroute generate openapi|wsdl|graphql`), applied to specs listed in one config file, and refreshed by a scheduled workflow. The one exception is GraphQL: its `.graphql` operation files are hand-written inputs, kept in `operations/` (see below). A worked example is **[ebay-apiroute](https://github.com/dougyouch/ebay-apiroute)**; the examples below use it, but nothing here is specific to eBay. Copy its files and adapt them rather than writing new ones; the sections below say what to change.
+
+## 1. Gather before creating anything
+
+Ask the user (an AskUserQuestion-style prompt with choices works well), and confirm what you find:
+
+1. **Names:**
+   - the repository (`<api>-apiroute`)
+   - the PyPI name (the same)
+   - the Python package (`<api>_apiroute`)
+   - the GitHub owner
+2. **Which APIs to cover.** Offer "everything with a published spec" as the default; lazy loading makes unused APIs free.
+3. **Will it be released to PyPI?** Always ask; never assume. If yes, the repo gets `release.yml` and the user must create a PyPI pending publisher (step 6). If no, skip `release.yml`, and the README says to install from GitHub (`pip install git+https://github.com/<owner>/<repo>`).
+4. **Public or private.** Releasing to PyPI implies public.
+5. **Auth model:** OAuth bearer tokens, API keys, Basic auth, request signing, SOAP header credentials, or extra per-call parameters. This decides the auth base class (step 4).
+6. **For a GraphQL API, which operations.** A GraphQL schema doesn't say what to fetch, so the repository holds the queries and mutations to generate. Ask what the user needs (or start from the API's documented examples), and write them as `.graphql` files. Also ask whether introspecting the schema needs a token, and the name of the environment variable that holds it.
+
+Then find each API's machine-readable description and its documentation page:
+
+- **Download every spec and check its content, not the HTTP status.** Some sites (eBay's, for example) answer unknown URLs with a normal 200 page. A spec must parse as JSON/YAML with an `openapi` or `swagger` key, or as XML with `definitions` (WSDL).
+- **For GraphQL, introspect the endpoint** with `apiroute fetch-schema <endpoint> -o /tmp/x.graphql -H "Authorization: Bearer $TOKEN"`. Some APIs also publish the schema as a file (GitHub's `schema.docs.graphql`), which works without a token.
+- **Treat documentation links the same way.** Some sites serve an error page to `curl` but the real page to browsers. A page's `<title>` that says "Error" or "Not Found" means "try another URL or a web search", not "it doesn't exist". Every API in the README table needs a working documentation link.
+- **Probe URL patterns** when a site publishes many specs (eBay, as an example: `/api-docs/master/<group>/<api>/openapi/3/<group>_<api>_<version>_oas3.json`), but keep only the ones whose content validates.
+- **Generate each spec into a scratch directory** before committing to it: `apiroute generate openapi <url> -o /tmp/x --models`, or for GraphQL `apiroute generate graphql /tmp/x.graphql --operations <dir> -o /tmp/x --models`, which reports every operation that doesn't match the schema as `file:line:column`. Note any spec the generator can't handle, and either fix apiroute or leave that API out, telling the user which.
+
+## 2. Repository layout
+
+```text
+<repo>/
+  apis.yaml                     the source of truth: one entry per API (hand-written)
+  specs/                        committed copies of the specs (written by --fetch; SDL for GraphQL)
+  operations/<api>/             GraphQL operations, one folder per API (hand-written)
+  scripts/generate.py           fetch specs, run apiroute generate, write the README table
+  scripts/next_release.py       each release's version, notes and changelog entry, from the commits (if releasing)
+  src/<package>/
+    __init__.py                 package docstring (hand-written)
+    auth.py                     auth base classes the generated clients extend (hand-written)
+    <group>/__init__.py         written by scripts/generate.py
+    <group>/<api>/              generated by apiroute (never edited)
+  tests/                        config checks, auth behaviour, one call per protocol
+  .github/workflows/            ci.yml, build.yml, release.yml (if releasing)
+  AGENT.md  CLAUDE.md           agent guidance; CLAUDE.md imports AGENT.md with "@AGENT.md"
+  .agent/skills/apiroute-client.md   this skill (copy it into the new repository)
+  README.md  CHANGELOG.md  LICENSE  pyproject.toml  uv.lock
+```
+
+`apis.yaml`, one entry per API (shown with ebay-apiroute's values as an example):
+
+```yaml
+package: ebay_apiroute
+apis:
+  - name: sell_inventory            # unique; also the spec file name in specs/
+    title: Inventory API            # shown in the README table
+    format: openapi                 # openapi (covers Swagger 2.0) or wsdl
+    spec: https://.../sell_inventory_v1_oas3.json
+    docs: https://developer.ebay.com/api-docs/sell/static/api-inventory.html
+    module: sell.inventory          # -> src/ebay_apiroute/sell/inventory/
+    client: SellInventoryApi
+    base_class: ebay_apiroute.auth:EbayAuth   # optional; owns auth
+    models: true                    # optional, default true: the typed .models layer
+    nullable_fields: false          # optional: --nullable-fields, when the spec says fields are never null but the API sends null
+    open_enums: false               # optional: --open-enums, when the API sends enum values the spec doesn't list
+    operation_names: specs/sell_inventory.names.json   # optional: --operation-names, operation ID -> dotted section.method
+    pagination: specs/sell_inventory.pagination.yaml   # optional: --pagination rules adding <name>_all methods
+  - name: github                    # a GraphQL API
+    title: GitHub GraphQL API
+    format: graphql
+    spec: https://api.github.com/graphql      # introspected by --fetch into specs/github.graphql
+    spec_headers:                   # optional, for introspection; values name environment variables
+      Authorization: "Bearer ${GITHUB_TOKEN}"
+    operations: operations/github   # hand-written .graphql files; subfolders become sections
+    endpoint: https://api.github.com/graphql  # --endpoint: base_url and path
+    scalars:                        # optional --scalar mappings
+      DateTime: datetime:datetime
+    persisted_queries: false        # optional: --persisted-queries, for servers with APQ
+    docs: https://docs.github.com/en/graphql
+    module: github
+    client: GitHubApi
+    base_class: github_apiroute.auth:GitHubAuth
+```
+
+`scripts/generate.py`: copy an existing one, such as [ebay-apiroute's](https://github.com/dougyouch/ebay-apiroute/blob/main/scripts/generate.py). It does the following:
+
+- `--fetch` downloads each spec, validates it, and re-indents JSON (keeping key order) so diffs stay readable. For `format: graphql` it runs `apiroute fetch-schema <spec> -o specs/<name>.graphql`, expanding `${VAR}` in `spec_headers` from the environment and passing each as `-H`. Never write a token to a file.
+- It runs `apiroute generate <format> specs/<name> -o src/<package>/<module> --client-name ... --models --base-class ...` for each API, adding `--nullable-fields` when an API sets `nullable_fields`, `--open-enums` when it sets `open_enums`, `--base-url` when it sets `base_url` (for a spec without servers), `--operation-names` when it sets `operation_names`, and `--pagination` when it sets `pagination`, and `--operations`, `--endpoint`, `--scalar` and `--persisted-queries` for GraphQL. [github-apiroute's script](https://github.com/dougyouch/github-apiroute/blob/main/scripts/generate.py) has the GraphQL support; ebay-apiroute's predates it.
+- It writes the group packages' `__init__.py`, marked "Generated by scripts/generate.py".
+- It rewrites the README table between `<!-- apis:start -->` and `<!-- apis:end -->`.
+- `--only NAME` limits the run to the named APIs.
+- When the API pages its lists, write a `--pagination` rules file in `specs/` (see the apiroute README's code generation notes): one rule per paging style, matched by response shape and parameters rather than listing operations, so new list operations are picked up when the spec changes. Check the generator's per-rule match counts after each regeneration, and add a live test that pages past the first page with a small page size.
+- When a spec's tags and operationIds make poor names, pass `--operation-names` a JSON map of operation ID to dotted name (`customers.create`, `issuing.cards.list`): sections nest. An operation without an operationId is keyed by its method and path as the spec writes them (`"GET /api/data/metar": "metar"`). Keep the map in `specs/` so its diffs are reviewed with the spec's. If the spec carries better names in vendor extensions, have `generate.py` write the map from them on every run; [stripe-apiroute](https://github.com/dougyouch/stripe-apiroute) builds it from Stripe's `x-stripeOperations`.
+
+ebay-apiroute's script also has an eBay-specific `_write_trading_version`. Drop it, or adapt it if your auth class must read a value from a spec.
+
+`pyproject.toml`:
+- Depend on `apiroute>=<current>` (add `apiroute[soap]` when any API is a WSDL; GraphQL clients need nothing extra at run time) and `pydantic>=2.6` (generated models fail on pydantic 2.1–2.5). Put `apiroute[codegen]`, `pytest` and `ruff` in the `dev` dependency group.
+- Set ruff's `line-length = 100` and `extend-exclude = ["specs"]`.
+- Keep `specs/` out of the sdist.
+- If releasing, take the version from the git tag: `dynamic = ["version"]`, `requires = ["hatchling", "hatch-vcs"]` and `[tool.hatch.version] source = "vcs"`. Nothing in the repository holds the version; a release commits only its CHANGELOG.md entry.
+
+## 3. Generate, lint, import
+
+```bash
+uv sync
+uv run python scripts/generate.py --fetch
+uv run ruff check . && uv run ruff format --check .   # generated code passes both
+```
+
+Then import every module and build every model, on the lowest and highest supported Python versions. A Python 3.10 import catches annotation problems that 3.14's deferred annotations hide. The checks live in `tests/test_apis_config.py`:
+
+- every `apis.yaml` entry has a spec file, a documentation link, an importable client and the configured base class
+- every route compiles
+
+## 4. Auth base class (hand-written, in `auth.py`)
+
+Every generated root client extends the `base_class` from `apis.yaml`, and apiroute then generates no auth of its own. Write the class once, by subclassing `apiroute.Client`. Sections inherit its `headers` and `query_params`, and they use its hooks.
+
+| Need | How |
+| --- | --- |
+| Bearer token | `headers = {"Authorization": lambda self: f"Bearer {self.current_token()}" if self._token else None}`; accept a string or a function returning one (for refreshing OAuth helpers) |
+| API key in a header or query | an entry in `headers` or `query_params` reading an attribute |
+| Request signing | `on_request(self, request)` returning `dataclasses.replace(request, headers=...)` |
+| Per-call parameters | `on_request`, with `request.operation` (the spec's operationId or WSDL operation name) |
+| Retrying safe operations | apiroute 2 only retries `GET`, `HEAD` and `OPTIONS` after a read timeout. Override `idempotent(self, request)` to return `True` for operations that are safe to repeat, by `request.operation` (a SOAP API's `Get*` calls) or `request.method`, and `None` for the rest. Set `idempotency_key = "Idempotency-Key"` instead for APIs that honor that header |
+| SOAP header credentials | `soap_header(self, operation) -> dict`, in the same xmltodict shape as bodies |
+| Sandbox or region hosts | an `__init__` flag that sets `kwargs["base_url"]` from `type(self)._config.base_url` |
+
+Test each behaviour in `tests/` with `apiroute.testing`: inside `with mock_transport() as mock:`, call the client and assert on `mock.last`, which records the operation, the header or parameter on the wire, the sandbox host, and a SOAP header if any. Match responses by operation with `mock.on(operation=...)`.
+
+## 5. README (generate it as part of setup)
+
+It must have:
+- a one-paragraph description with CI and Build badges
+- installation instructions (PyPI, or from GitHub when not releasing)
+- usage per protocol: dict and typed calls, `.aio`, auth arguments and sandbox
+- **links to the API's documentation and its auth or token guide**
+- the generated API table, with a docs link per API
+- **how the repository stays up to date:**
+  - the Build schedule
+  - the `specs/` snapshot and `git log -p specs/`
+  - apiroute as the generator
+  - the commit types and the releases they produce
+  - what CI checks
+- development commands, and how to add an API
+
+Use an existing client repository's README (ebay-apiroute's, for example) as the template.
+
+## 6. Workflows
+
+Copy them from an existing client repository ([github-apiroute](https://github.com/dougyouch/github-apiroute), for example) and change the names, the PyPI project and the schedule.
+
+- **`ci.yml`** runs on pull requests and `workflow_call` (release.yml runs it before every release):
+  - Lint: `ruff check` and `ruff format --check`.
+  - `generated-is-current`: runs `scripts/generate.py` without `--fetch` and fails on any `git status` difference. This catches hand edits, and specs out of step with the code.
+  - Tests on every supported Python version.
+- **`build.yml`** runs on a schedule and `workflow_dispatch`:
+  1. `uv lock --upgrade-package apiroute`, then `uv sync`.
+  2. `scripts/generate.py --fetch`.
+  3. Lint and test.
+  4. If `git status` shows changes, commit and push to main:
+     - `feat(specs): update clients from <API>'s latest specs` when `specs/` changed (a minor release)
+     - otherwise `fix(codegen): regenerate clients with apiroute <version>` (a patch)
+
+  It needs `permissions: contents: write`. If `main` is protected, give the workflow a bypass or have it open a PR instead. A GraphQL API whose introspection needs a token gets it from a repository secret, exposed to the fetch step as the environment variable `spec_headers` names.
+- **`release.yml`**, only if the user said yes to PyPI, releases every push to main; there's no release PR. It runs CI, then `scripts/next_release.py` works out the version from the conventional commits since the last `vX.Y.Z` tag (`feat!:` or a `BREAKING CHANGE:` footer: major, `feat:` minor, anything else patch) and the notes. It commits the notes to CHANGELOG.md as `chore(release): vX.Y.Z` (which the next release's notes leave out), tags that commit and pushes both at once, then builds (hatch-vcs reads the version from the tag), publishes with `uv publish --trusted-publishing always` in the `pypi` environment, and creates the GitHub release with the notes and distributions. Each step skips what's already done (the tag, the PyPI version, the release), so rerunning a failed release finishes it, and a run on an already-tagged commit changes nothing. A run whose commit is no longer main's newest leaves the release to the newer push, which includes it. The release commit is pushed with `GITHUB_TOKEN`, so it triggers nothing; `main` may forbid force pushes but must accept the workflow's fast-forward push. Besides `push` and `workflow_dispatch`, trigger it on `workflow_run` of Build: commits pushed with `GITHUB_TOKEN` don't trigger other workflows. Copy apiroute's or github-apiroute's `release.yml` and `scripts/next_release.py`.
+
+Each repository needs these GitHub and PyPI settings:
+
+- Delete branches on merge: `gh repo edit --delete-branch-on-merge`.
+- If releasing:
+  - The user creates a PyPI **pending publisher**: the project name, the repository owner and name, workflow `release.yml`, environment `pypi`.
+  - The first push to main releases `0.1.0` (no tag yet); every later push releases the next version.
+
+## 7. Maintenance
+
+- **Routine:** none. Build commits changes, and every commit on main is tested, tagged and published on its own. The tests are the gate, so keep them meaningful: config checks, auth behaviour, and one call per protocol.
+- **A spec change breaks generation:** Build fails before committing, and the last good code stays on main. Reproduce with `scripts/generate.py --fetch --only <name>`, then fix apiroute (preferred) or the auth class. Never patch `specs/` or generated files by hand.
+- **A GraphQL schema change breaks an operation:** Build fails listing each broken operation as `file:line:column`. The operations are yours: update them in `operations/<api>/` (a renamed or removed field), regenerate and commit (`feat!:` if a released method's result changed shape). Deprecation warnings in the Build log say what to move off before the API removes it.
+- **Add a GraphQL operation:** add a `.graphql` file (or a query to one), `generate.py --only <name>`, test and commit (`feat:`).
+- **Lists:** for a Relay connection the user wants in full, put `@paginate` on the connection field and give the operation a `$after: String` variable. The generated method then iterates every item across pages. Leave it off where one page (with `totalCount`) is what's wanted, because adding it later changes the method's return type.
+- **Add an API:** add an `apis.yaml` entry, verifying its spec and docs as in step 1, then `generate.py --fetch --only <name>`, then test and commit (`feat:`).
+- **Remove an API:** delete its entry, its spec and its folder, then regenerate and commit (`feat!:` if it was released).
+- **apiroute adds a feature you need:** release apiroute, raise the minimum in `pyproject.toml`, `uv lock`, regenerate, commit.
+
+## 8. Before handing over
+
+- [ ] Every API has a working spec and a working docs link (checked by content, not by status).
+- [ ] `ruff check`, `ruff format --check`, the tests, and a Python 3.10 import of every module all pass.
+- [ ] CI, Build (run it once by hand) and, if releasing, Release are green.
+- [ ] Branch auto-delete is on. If releasing, the pending publisher exists, or the user knows to create it.
+- [ ] README, AGENT.md, CLAUDE.md (importing AGENT.md) and this skill are in the repository.

maxio_apiroute-0.1.0/.github/workflows/build.yml

@@ -0,0 +1,65 @@
+name: Build
+
+# Keeps the client current: fetches Maxio's latest OpenAPI spec, upgrades apiroute,
+# regenerates, checks (live too, on a Maxio test site), and commits any difference to main.
+# A changed spec is committed as feat(specs) (a minor release); output that changed only
+# because apiroute did, as fix(codegen) (a patch).
+on:
+  schedule:
+    - cron: "37 8 * * 1" # Mondays 08:37 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: write # commit regenerated clients
+
+concurrency:
+  group: build
+  cancel-in-progress: false
+
+jobs:
+  regenerate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+      - name: Use the newest apiroute
+        run: uv lock --upgrade-package apiroute
+      - run: uv sync
+      - name: Fetch the latest spec and regenerate
+        run: uv run python scripts/generate.py --fetch
+      - name: Check
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+          uv run pytest
+      # Requests and typed models against what Maxio actually accepts and sends, on a test
+      # site, before anything is committed. Skipped without the MAXIO_API_KEY and MAXIO_SITE
+      # secrets (a site that isn't a test site is refused).
+      - name: Live tests
+        env:
+          MAXIO_API_KEY: ${{ secrets.MAXIO_API_KEY }}
+          MAXIO_SITE: ${{ secrets.MAXIO_SITE }}
+          MAXIO_REGION: ${{ secrets.MAXIO_REGION || 'us' }}
+        run: uv run pytest tests/live
+      - name: Commit changes
+        run: |
+          if [ -z "$(git status --porcelain)" ]; then
+            echo "Specs and generated clients are unchanged."
+            exit 0
+          fi
+          specs=$(git status --porcelain -- specs | awk '{print $2}' | xargs -r -n1 basename | sed 's/\..*$//' | sort -u | paste -sd ' ' -)
+          if [ -n "$specs" ]; then
+            subject="feat(specs): update the client from Maxio's latest API spec"
+            body="Changed specs: $specs"
+          else
+            version=$(uv run python -c "import importlib.metadata as m; print(m.version('apiroute'))")
+            subject="fix(codegen): regenerate clients with apiroute $version"
+            body="No spec changed; the generated code did, with the newer apiroute."
+          fi
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git add -A
+          git commit -m "$subject" -m "$body"
+          git push

maxio_apiroute-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  pull_request:
+  workflow_call: # release.yml runs it on every push to main, before releasing
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  # The committed code must be exactly what the committed specs generate: nothing in src/
+  # is edited by hand, and specs/ and src/ never drift apart.
+  generated-is-current:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+      - run: uv sync
+      - run: uv run python scripts/generate.py
+      - name: Check for differences
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            git status --short
+            echo "::error::Generated code differs from the committed specs. Run 'uv run python scripts/generate.py' and commit the result."
+            exit 1
+          fi
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run pytest

maxio_apiroute-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,103 @@
+name: Release
+
+# Every push to main is a release. CI runs first; then scripts/next_release.py works out the
+# version from the conventional commits since the last tag (feat: minor, ! or BREAKING CHANGE:
+# major, anything else: patch). A release commit adds those commits to CHANGELOG.md and is
+# tagged, built (hatch-vcs reads the version from the tag), published to PyPI and given a
+# GitHub release with the same notes. Every step skips what's already done, so rerunning a
+# failed release finishes it, and a run on a commit that's already released changes nothing.
+# It also runs after Build, whose commits (pushed with GITHUB_TOKEN) trigger no push event.
+on:
+  push:
+    branches: [main]
+  workflow_run:
+    workflows: [Build]
+    types: [completed]
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  ci:
+    # after Build only when it succeeded (a failed Build committed nothing)
+    if: github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success'
+    uses: ./.github/workflows/ci.yml
+
+  release:
+    needs: ci
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/maxio-apiroute/
+    permissions:
+      contents: write # the tag and the GitHub release
+      id-token: write # PyPI trusted publishing (OIDC)
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0 # every commit and tag, for the version
+      - uses: astral-sh/setup-uv@v6
+
+      # A rerun of a release whose tag exists finishes that release from its tag. A push that
+      # newer pushes have overtaken is left to them: the newest releases every commit since
+      # the last tag, so nothing is skipped and main isn't pushed to from behind.
+      - name: Work out the version
+        run: |
+          version=$(python3 scripts/next_release.py)
+          echo "VERSION=$version" >> "$GITHUB_ENV"
+          echo "TAG=v$version" >> "$GITHUB_ENV"
+          python3 scripts/next_release.py --notes > "$RUNNER_TEMP/notes.md"
+          if git rev-parse -q --verify "refs/tags/v$version" > /dev/null; then
+            echo "STATE=tagged" >> "$GITHUB_ENV"
+          elif [ "$(git rev-parse origin/main)" != "$(git rev-parse HEAD)" ]; then
+            echo "STATE=overtaken" >> "$GITHUB_ENV"
+            echo "::notice::main has moved on; the newer push releases this commit with it."
+          else
+            echo "STATE=new" >> "$GITHUB_ENV"
+          fi
+
+      # The release commit adds the notes to CHANGELOG.md; the tag goes on it, so the package
+      # carries its own changelog entry. Pushed with GITHUB_TOKEN, it starts no workflow.
+      - name: Commit the changelog and tag
+        if: env.STATE == 'new'
+        run: |
+          python3 scripts/next_release.py --changelog CHANGELOG.md
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git commit -m "chore(release): $TAG" CHANGELOG.md
+          git tag "$TAG"
+          git push --atomic origin HEAD:main "$TAG"
+
+      - name: Check out the tag
+        if: env.STATE == 'tagged'
+        run: git checkout "$TAG"
+
+      - name: Build
+        if: env.STATE != 'overtaken'
+        run: uv build
+
+      - name: Publish to PyPI
+        if: env.STATE != 'overtaken'
+        run: |
+          if curl -sf "https://pypi.org/pypi/maxio-apiroute/$VERSION/json" > /dev/null; then
+            echo "maxio-apiroute $VERSION is already published"
+          else
+            uv publish --trusted-publishing always
+          fi
+
+      - name: GitHub release
+        if: env.STATE != 'overtaken'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if gh release view "$TAG" > /dev/null 2>&1; then
+            gh release upload "$TAG" dist/* --clobber
+          else
+            gh release create "$TAG" dist/* --title "$TAG" --notes-file "$RUNNER_TEMP/notes.md"
+          fi

maxio_apiroute-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.mypy_cache/

maxio_apiroute-0.1.0/AGENT.md

@@ -0,0 +1,51 @@
+# AGENT.md
+
+Guidance for AI coding agents (and people) working in this repository.
+
+## What this repository is
+
+`maxio-apiroute` publishes a Python client for Maxio Advanced Billing (formerly Chargify). [apiroute](https://github.com/dougyouch/apiroute) **generates** the client from the OpenAPI 3.1 spec that Maxio's developer portal exports (`developers.maxio.com/static/exports/maxio-advanced-billing-openapi31json.json`). Methods keep the spec's operation names, as Maxio's own SDKs do. The weekly Build workflow keeps the client current, and it's released to PyPI as `maxio-apiroute`.
+
+## Layout
+
+| Path | What it is | Edit by hand? |
+| --- | --- | --- |
+| `apis.yaml` | The API: spec URL, docs URL, module, client class, auth base class, pagination rules | **yes**: this is the source of truth |
+| `specs/advanced_billing.json` | The committed copy of the spec, written by `scripts/generate.py --fetch` | no (fetch it) |
+| `specs/advanced_billing.pagination.yaml` | Which list operations get `_all` methods, and how they page | yes |
+| `scripts/generate.py` | Fetches the spec, writes `spec_info.py`, runs `apiroute generate`, writes the README table | yes |
+| `scripts/next_release.py` | Each release's version, notes and CHANGELOG.md entry, from the commits since the last tag | yes |
+| `src/maxio_apiroute/auth.py` | `MaxioAuth`: Basic auth with the API key, the site's host by region, 429 retries, the events host | **yes** |
+| `src/maxio_apiroute/__init__.py` | Package docstring | yes |
+| `src/maxio_apiroute/spec_info.py` | The operations served from another host (event ingestion), written by `generate.py` | never |
+| `src/maxio_apiroute/advanced_billing/` | The generated client (every file starts with `# Generated by apiroute`) | **never** |
+| `tests/` | Config checks, auth, pagination; `tests/live/` against a Maxio test site | yes |
+| `.github/workflows/` | `ci.yml`, `build.yml` (regenerate, live-test and commit), `release.yml` (every push to main: tag, PyPI, GitHub release) | yes |
+| `.agent/skills/apiroute-client.md` | Skill for creating and maintaining repos like this one | yes |
+
+## Rules
+
+- **Never edit generated code.** CI regenerates from `specs/` and fails on any difference. To change generated output:
+  - Edit `apis.yaml`, `auth.py` or the pagination rules, and regenerate.
+  - If the generator itself is wrong, fix apiroute; the Build workflow picks up its next release.
+- **Regenerate after any change** to `apis.yaml`, the pagination rules or the scripts: `uv run python scripts/generate.py`. Add `--fetch` to download the latest spec first. Commit the specs and the generated code together.
+- **Live tests use a test site only.** They read `MAXIO_API_KEY`, `MAXIO_SITE` and optionally `MAXIO_REGION`, and refuse a site whose `test` flag isn't set. Never print a key or write one to a file. Clean up what a test creates.
+- **Every merge to main is a release.** There's no release PR; `release.yml` tests, tags and publishes each push to main, Build's commits included.
+- **Use conventional commits.** The version comes from the commits since the last tag:
+  - `feat!:` (or a `BREAKING CHANGE:` footer) is a major release
+  - `feat:` is a minor release
+  - anything else (`fix:`, `docs:`, `chore:` ...) is a patch
+- **The version lives in the git tag**, not `pyproject.toml` (hatch-vcs). Never tag by hand; the release workflow does.
+- **Don't edit CHANGELOG.md by hand;** the release commits write it.
+- **Before committing:** `uv run ruff check .`, `uv run ruff format --check .` and `uv run pytest`. After regenerating, also run the live tests if you have a test site: `MAXIO_API_KEY=... MAXIO_SITE=... uv run pytest tests/live`.
+
+## Common tasks
+
+- **A new list operation has no `_all` method:** its response's list key has no rule yet. Add one to `specs/advanced_billing.pagination.yaml` and regenerate; the generator prints each rule's match count.
+- **A spec change broke generation:** the Build workflow fails before committing anything. Reproduce with `scripts/generate.py --fetch`, then fix apiroute, the pagination rules or `auth.py`. Patching `specs/` by hand would be overwritten by the next fetch.
+- **A live test fails after a spec update:** the spec and Maxio's responses disagree, or a typed model is wrong. Check the failing response. Fix apiroute if the generator is at fault. Set `nullable_fields: true` in `apis.yaml` if the spec says a field is never null when Maxio sends null, or `open_enums: true` if Maxio sends enum values the spec doesn't list.
+- **Release:** nothing to do. Every push to main, and every Build commit, is tested, released and published.
+
+## Skill
+
+`.agent/skills/apiroute-client.md` describes how to create, set up and maintain a client repository like this one for any API with OpenAPI/Swagger specs, WSDLs or GraphQL schemas. Read it before restructuring this repo or creating a sibling.

maxio_apiroute-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 (2026-10-29)
+
+### Features
+
+- feat: Maxio Advanced Billing client generated with apiroute (bad6e16)
+

maxio_apiroute-0.1.0/CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+This repository's guidance for coding agents lives in AGENT.md, imported here:
+
+@AGENT.md
+
+Skills for this repository are in `.agent/skills/`. Read `.agent/skills/apiroute-client.md` before creating or restructuring an apiroute client repository for any API.

maxio_apiroute-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dougyouch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.