Implement v2 API support

.github/workflows/docs.yml

@@ -3,14 +3,25 @@ name: build mkdocs
 on:
   release:
     types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: write
 
 jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - name: Install uv
         uses: astral-sh/setup-uv@v6
-      - name: Install docs dependencies
-        run: uv sync --group docs
-      - run: uv run mkdocs gh-deploy --force --clean --verbose
+      - name: Configure git for mike
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+      # docs/deploy.sh is the single source of truth for versions, titles,
+      # and aliases — the same script serves the local preview.
+      - name: Deploy versioned docs (v1 + v2)
+        run: ./docs/deploy.sh deploy

.github/workflows/tests_main.yml

@@ -4,17 +4,47 @@ on:
   pull_request:
     branches: [ main ]
 
-env:
-    FASTFUELS_API_KEY: ${{ secrets.FASTFUELS_API_KEY }}
-
+# v1 and v2 are separate live deployments with separate API keys, so each
+# suite runs as its own job with its own secret mapped to FASTFUELS_API_KEY
+# (the variable both SDKs read). While v2 is a beta preview, make only
+# `test-v1` a required status check in branch protection — `test-v2` runs
+# and reports on every PR but is intentionally NOT required, so v2-API
+# flakiness does not block v1-only changes.
 jobs:
-  test:
+  test-v1:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.12"]
+    env:
+      FASTFUELS_API_KEY: ${{ secrets.FASTFUELS_API_KEY }}
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        python-version: ${{ matrix.python-version }}
+        enable-cache: true
+    - name: Install dependencies
+      run: uv sync
+    - name: Run v1 tests
+      env:
+        TEST_ENV: local
+      run: |
+        cd tests/
+        uv run pytest v1
+
+  test-v2:
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
         python-version: ["3.12"]
+    env:
+      FASTFUELS_API_KEY: ${{ secrets.FASTFUELS_API_KEY_V2 }}
     steps:
     - uses: actions/checkout@v4
     - name: Install uv
@@ -24,9 +54,9 @@ jobs:
         enable-cache: true
     - name: Install dependencies
       run: uv sync
-    - name: Run pytest
+    - name: Run v2 tests
       env:
         TEST_ENV: local
       run: |
         cd tests/
-        uv run pytest
+        uv run pytest v2

.pre-commit-config.yaml

@@ -1,9 +1,12 @@
-exclude: ^fastfuels_sdk/v1/client_library/
+exclude: ^fastfuels_sdk/(v1|v2)/client_library/
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.6.0
     hooks:
       - id: check-yaml
+        # mkdocs.yml uses mkdocs' !ENV tag, which plain yaml.safe_load
+        # cannot construct; --unsafe still checks syntax
+        args: [--unsafe]
       - id: end-of-file-fixer
       - id: trailing-whitespace
       - id: detect-private-key

CLAUDE.md

@@ -4,3 +4,84 @@
 
 Do NOT add "Co-Authored-By: Claude", "Generated with Claude Code", or any other
 AI-attribution lines to commit messages, PR descriptions, or GitHub issues.
+
+## Live API testing
+
+- Local live-test credentials are stored in the repository-root `.env`, which
+  is ignored by Git. The SDK authenticates with the `FASTFUELS_API_KEY` value
+  from that file.
+- Before running live tests, load `.env` into the current shell without
+  printing its contents: `set -a; source .env; set +a`.
+- Check and load `.env` before concluding that live API credentials are
+  unavailable or asking the user to provide them.
+- Never print, stage, commit, or copy credential values from `.env` into code,
+  documentation, logs, commit messages, pull requests, or issues.
+
+## Documentation
+
+FastFuels has two documentation properties that must stay in concert:
+
+- **This repo (`docs/`)** — the Python SDK docs (mkdocs-material + mike,
+  published to silvxlabs.github.io/fastfuels-sdk-python). Scope: how to use
+  FastFuels **from Python** — SDK how-to guides, SDK tutorials, migration
+  guides, and the mkdocstrings API reference.
+- **FastFuels-Web `documentation/`** (sibling repo) — the platform docs at
+  docs.fastfuels.silvxlabs.com (Astro/Starlight). Scope: the web
+  application, the HTTP API (language-agnostic: curl + raw requests), and
+  **all concept explanations**.
+
+Division of responsibility: platform concepts (what a domain is, how grids
+work, why a design is the way it is) are explained once, in the platform
+docs — the SDK docs link to docs.fastfuels.silvxlabs.com rather than
+duplicating them. The SDK docs own Python idioms, signatures, and
+SDK-specific behavior. Cross-link in both directions; never copy content
+between the two.
+
+### Diátaxis
+
+Both properties follow the Diátaxis framework (reference copy:
+`FastFuels-Web/documentation/diataxis.rst`). Every page is exactly ONE of
+four kinds — decide which before writing; if a page wants to be two kinds,
+split it:
+
+- **Tutorial** — learning by doing. First-person plural ("we'll create…"),
+  prerequisites up front, expected output shown at each step, reliable
+  end-to-end. No explanation digressions — link instead.
+- **How-to guide** — a goal, for a competent user. Conditional imperatives
+  ("To create a domain from a file, …"). Action only: no teaching, no
+  background. Opens with a short Prerequisites section.
+- **Reference** — neutral facts. In this repo it is generated from
+  docstrings via mkdocstrings; do not hand-write opinions into it.
+- **Explanation** — the "why". Belongs in the platform docs unless it is
+  SDK-specific (e.g. the v1→v2 migration guide's what-changed sections).
+
+### Docstrings are user-facing reference documentation
+
+mkdocstrings renders docstrings directly into the published Reference
+pages. A docstring describes what the object does, parameters, returns,
+raises, and examples — nothing else. No editorial or comparative
+commentary (no v1-vs-v2 asides, no GitHub issue references, no design
+rationale). Migration notes belong in `docs/v2/guides/migration.md`;
+rationale and issue references belong in `#` code comments.
+
+### Conventions
+
+- Version labels mirror the platform docs: **"v1"** (alias `latest`) and
+  **"v2 (Beta)"** — set as mike titles in `docs/deploy.sh`, the single
+  entry point for both the local preview (`./docs/deploy.sh`) and the
+  gh-pages deploy (`./docs/deploy.sh deploy`, run by the docs workflow).
+- One `mkdocs.yml` builds both versions: `DOCS_DIR` selects `docs/v1`
+  (default) or `docs/v2`; each tree owns its nav in a `SUMMARY.md`
+  (literate-nav). Versions deploy as independent mike snapshots picked
+  from the header version selector.
+- `docs/v1/stylesheets/extra.css` and `docs/v2/stylesheets/extra.css` are
+  duplicates by construction — edit both or the version snapshots diverge.
+- Code examples must be real: verified against the live API (the live test
+  suite in `tests/` is the verification path), with realistic output —
+  never hand-written response shapes.
+- Use admonitions (`!!! tip` / `warning` / `danger`) instead of bold
+  "Note:" prose; use content tabs (`=== "v1"` / `=== "v2"`) for
+  side-by-side variants; v2 pages open with the `!!! warning "Beta"`
+  admonition.
+- `docs/v1/` is frozen alongside the v1 SDK (bugfix-level edits only);
+  new documentation lands in `docs/v2/`.

docs/README.md

@@ -0,0 +1,51 @@
+# FastFuels SDK documentation
+
+This site is built with [mkdocs-material](https://squidfunk.github.io/mkdocs-material/)
+and versioned with [mike](https://github.com/jimporter/mike). The header
+has a version dropdown with two entries, mirroring the FastFuels
+platform docs: **v1** (the current default SDK, alias `latest`) and
+**v2 (Beta)** (the `fastfuels_sdk.v2` subpackage).
+
+## Layout
+
+| Path | What it is |
+|---|---|
+| `docs/v1/` | v1 SDK docs — frozen alongside the v1 SDK (bugfix-level edits only) |
+| `docs/v2/` | v2 SDK docs — new documentation lands here |
+| `docs/v1/SUMMARY.md`, `docs/v2/SUMMARY.md` | Each version's nav (mkdocs-literate-nav) |
+| `docs/v1/stylesheets/extra.css`, `docs/v2/stylesheets/extra.css` | Duplicates by construction — edit both |
+| `mkdocs.yml` (repo root) | One config for both versions: `DOCS_DIR` picks the tree (default `docs/v1`) |
+| `docs/deploy.sh` | The docs entry point: build, serve, deploy |
+
+## Launch the docs server
+
+The full site, version dropdown included, at <http://localhost:8000>:
+
+```bash
+./docs/deploy.sh
+```
+
+This builds both versions onto your **local** `gh-pages` branch and
+serves it with mike (`git branch -D gh-pages` discards the preview).
+
+For quick edits to one version, plain mkdocs gives live reload:
+
+```bash
+uv run mkdocs serve                     # v1
+DOCS_DIR=docs/v2 uv run mkdocs serve    # v2
+```
+
+> [!NOTE]
+> The version dropdown only exists under mike — plain `mkdocs serve`
+> shows a single version and logs a `versions.json` 404. That's
+> expected, not a bug.
+
+## Deploy
+
+```bash
+./docs/deploy.sh deploy
+```
+
+Publishes both versions to `gh-pages` on origin. The docs workflow
+(`.github/workflows/docs.yml`) runs the same command on each GitHub
+release (or manually via workflow_dispatch).

docs/deploy.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+#
+# Build the versioned docs — v1 and v2 mike snapshots — and serve or publish.
+#
+#   ./docs/deploy.sh          build both versions, then serve the full site
+#                              (version selector included) at localhost:8000
+#   ./docs/deploy.sh deploy   publish both versions to gh-pages on origin
+#
+# mike snapshots each version onto the gh-pages branch and maintains the
+# versions.json that powers the header version selector; plain
+# `mkdocs serve` can only ever show one version (and 404s versions.json).
+# Without `deploy`, the snapshots are committed to your local gh-pages
+# branch only — `git branch -D gh-pages` discards them.
+#
+# Version labels mirror the FastFuels-Web docs (docs.fastfuels.silvxlabs.com).
+
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+push=""
+case "${1:-serve}" in
+  serve) ;;
+  deploy) push="--push" ;;
+  *)
+    echo "usage: $0 [deploy]" >&2
+    exit 1
+    ;;
+esac
+
+uv run --group docs mike deploy $push --update-aliases v1 latest --title "v1"
+DOCS_DIR=docs/v2 uv run --group docs mike deploy $push v2 --title "v2 (Beta)"
+uv run --group docs mike set-default $push latest
+
+if [[ -z "$push" ]]; then
+  uv run --group docs mike serve
+fi

docs/v1/SUMMARY.md

@@ -0,0 +1,12 @@
+* [Home](index.md)
+* How-To Guides
+    * [Authentication](guides/authentication.md)
+    * [Domains](guides/domains.md)
+    * [Inventories](guides/inventories.md)
+    * [Point Clouds](guides/point_clouds.md)
+    * [Features](guides/features.md)
+    * [Grids](guides/grids.md)
+* Tutorials
+    * [Export to QUIC-Fire](tutorials/export_to_quicfire.md)
+    * [ALS Point Cloud](tutorials/point_cloud_example.md)
+* [Reference](reference.md)

docs/v1/stylesheets/extra.css

@@ -0,0 +1,55 @@
+/* Version selector (mike + mkdocs-material). The stock theme renders the
+   selector as bare header text; style it as an explicit control.
+   (Duplicated in docs/v1 and docs/v2 — each version's site builds from its
+   own docs_dir.) */
+.md-version {
+  margin-left: 0.8rem;
+}
+
+.md-version__current {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.3rem;
+  background-color: rgba(0, 0, 0, 0.18);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 2rem;
+  padding: 0.25rem 0.8rem;
+  font-size: 0.65rem;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  cursor: pointer;
+  transition: background-color 125ms, border-color 125ms;
+}
+
+.md-version__current:hover,
+.md-version__current:focus {
+  background-color: rgba(0, 0, 0, 0.32);
+  border-color: rgba(255, 255, 255, 0.6);
+}
+
+.md-version__list {
+  margin-top: 0.5rem;
+  border-radius: 0.3rem;
+  box-shadow: var(--md-shadow-z3);
+  overflow: hidden;
+  min-width: 8rem;
+}
+
+.md-version__item {
+  line-height: 1;
+}
+
+.md-version__link {
+  display: block;
+  width: 100%;
+  padding: 0.6rem 1rem;
+  font-size: 0.7rem;
+  color: var(--md-default-fg-color);
+  transition: background-color 125ms, color 125ms;
+}
+
+.md-version__link:hover,
+.md-version__link:focus {
+  background-color: var(--md-default-fg-color--lightest);
+  color: var(--md-typeset-a-color);
+}

docs/v2/SUMMARY.md

@@ -0,0 +1,17 @@
+* [Home](index.md)
+* [Migrating from v1](guides/migration.md)
+* Tutorials
+    * [Export QUIC-Fire inputs](tutorials/export_to_quicfire.md)
+* How-To Guides
+    * [Domains](guides/domains.md)
+    * [Features](guides/features.md)
+    * Grids
+        * [Creating grids](guides/creating-grids.md)
+        * [Composing grids](guides/composing-grids.md)
+        * [Working with grids](guides/working-with-grids.md)
+    * [Inventories](guides/inventories.md)
+    * [Modify and treat inventories](guides/modify-treat-inventories.md)
+    * [Point clouds](guides/point-clouds.md)
+    * [Exports](guides/exports.md)
+    * [Quotas and usage](guides/quotas.md)
+* [Reference](reference.md)