Development and release

Set up the repository

Run commands from the repository root. On Linux or in an Amp orb:

.agents/setup

Setup installs uv 0.12.9 and Python 3.12, restores locked dependencies and checks imports. It needs no API credentials and makes no Vatly calls.

Run tests

uv run pytest --cov
uv run python scripts/generate.py --check

Tests use local HTTP and signed webhook fixtures, not a Vatly account. The second command checks that generated models, resources, clients and the API inventory match the pinned specification. CI runs these checks on Python 3.10–3.14.

Check formatting and types

uv run ruff check .
uv run ruff format --check .
uv run mypy

Build and check the package

uv build
uv run twine check dist/*
uv run python scripts/check_package.py

The last command installs the built wheel in a fresh environment and checks imports and py.typed. These commands build and validate; they do not publish.

Update the API specification

Replace openapi.yaml deliberately from the production specification, update its provenance below, then regenerate:

uv run python scripts/generate.py

Review the generated diff and rerun the checks above. Do not hand-edit generated models, resources, clients or docs/API.md.

Output models preserve extra fields and keep URLs and emails as strings. The generator handles two observed API differences: metadata [] becomes {}, and response product types accept values such as digital_download. Request validation still follows the pinned schema. Invalid responses raise VatlyApiError; avoid logging response bodies that may contain personal data.

Pinned source

The checked-in specification is byte-identical to that source and to the bundle published by Vatly's production release. Its SHA-256 is:

5e648169e101edc8b3e088dc0e28d0f0a293e8a0ed057014c7336057d986def9

The specification's generated-at date is not its retrieval date.

Documentation sync

Edit the flat Markdown guides in docs/; keep relative links portable. The API inventory is generated from scripts/generate.py, including its description.

Pushes to main affecting docs/** notify vatly/vatly-docs. The notifier needs the Actions secret VATLY_DOCS_DISPATCH_TOKEN with Contents: write access to that repository. The sync uses an explicit frontmatter description when present, otherwise the page's introductory sentence.

Prepare a release

The published package is vatly-api-python; the import name is vatly. Update the package version, src/vatly/_version.py and changelog, then run all checks. Publish the SDK before matching Fluent and Django versions, only after review and approval.

Publication starts only from a published GitHub release whose tag matches v plus the package version. Mark alphas as pre-releases. Never reuse a published version or move a release tag.

Pushing main does not publish. Restrict release access: trusted publishing uses GitHub OIDC, with no environment approval gate or PyPI token. PyPI artifacts, including packaged source and docs, are public even if the GitHub repo is private.

Resource guides · API inventory