Release v2: Async client, TLS enforcement, retries/backoff, and CI upgrades

## Summary
This major release delivers a production-ready async client with robust TLS handling, resilient request logic (timeouts, retries, rate limits), and a fully wired CI pipeline (lint, type-check, tests, coverage). It replaces the legacy synchronous v1 client and prepares the project for Home Assistant and broader integration.

## Highlights
- **Async client**
  - New `FmdClient` with an async factory (`await FmdClient.create(...)`) and async context manager (`async with ...`).
  - Clean session lifecycle management and connection pooling controls.
- **TLS/SSL**
  - HTTPS-only `base_url` enforcement (rejects plain HTTP).
  - Configurable validation: `ssl=False` (dev only) or pass a custom `ssl.SSLContext`.
  - Certificate pinning example included in docs.
- **Reliability**
  - Timeouts applied across all HTTP requests.
  - Retries with exponential backoff and optional jitter for 5xx and connection errors.
  - 429 rate-limit handling with Retry-After support.
  - Safe behavior for command POSTs (no unsafe retries).
- **Features**
  - Client-side export to ZIP (locations + pictures).
  - Device helper with convenience actions (e.g., request location, play sound, take picture).
- **Safety and ergonomics**
  - Sanitized logging (no sensitive payloads); token masking helper.
  - Typed package (`py.typed`) and mypy-clean.
- **CI/CD**
  - GitHub Actions: lint (flake8), type-check (mypy), unit tests matrix (Ubuntu/Windows; Py 3.8–3.12).
  - Coverage with branch analysis and Codecov upload + badges.
  - Publish workflows for TestPyPI (non-main) and PyPI (main or Release).

## Breaking changes
- API surface moved to async:
  - Before (v1, sync): `client = FmdApi(...); client.authenticate(...); client.get_all_locations()`
  - Now (v2, async):
    - `client = await FmdClient.create(base_url, fmd_id, password, ...)`
    - `await client.get_locations(...)`, `await client.get_pictures(...)`, `await client.send_command(...)`
    - Prefer: `async with FmdClient.create(...) as client: ...`
- Transport requirements:
  - `base_url` must be HTTPS; plain HTTP raises `ValueError`.
- Python versions:
  - Targets Python 3.8+ (3.7 removed from classifiers).

## Migration guide
- Replace `FmdApi` usage with the async `FmdClient`:
  - Use `await FmdClient.create(...)` and `async with` for safe resource management.
  - Update all calls to await the async methods.
- TLS and self-signed setups:
  - For dev-only scenarios: pass `ssl=False`.
  - For proper self-signed use: pass a custom `ssl.SSLContext`.
  - For high-security setups: consider the certificate pinning example in README.
- Connection tuning:
  - Optional: `conn_limit`, `conn_limit_per_host`, `keepalive_timeout` on the TCPConnector via client init.

## Error handling and semantics
- 401 triggers one automatic re-authenticate then retries the request.
- 429 honors Retry-After, otherwise uses exponential backoff with jitter.
- Transient 5xx/connection errors are retried (except unsafe command POST replays).
- Exceptions are normalized to `FmdApiException` where appropriate; messages mask sensitive data.

## Documentation and examples
- README: TLS/self-signed guidance, warnings, and certificate pinning example.
- Debugging: `pin_cert_example.py` demonstrates secure pinning and avoids CLI secrets.

## CI/CD and release automation
- Tests: unit suite expanded; functional tests run when credentials are available.
- Coverage: ~83% overall; XML + branch coverage uploaded to Codecov (badges included).
- Workflows:
  - `test.yml`: runs on push/PR for all branches (lint, mypy, unit tests matrix, coverage, optional functional tests).
  - `publish.yml`: builds on push/releases; publishes to TestPyPI for non-main pushes, PyPI on main or release.

## Checklist
- [x] All unit tests pass
- [x] Flake8 clean
- [x] Mypy clean
- [x] Coverage collected and uploaded
- [x] README/docs updated (TLS, pinning, badges)
- [x] Packaging: sdist and wheel built; publish workflows configured

## Notes
- Use `ssl=False` sparingly and never in production.
- Consider adding Dependabot and security scanning in a follow-up.
- A `CHANGELOG.md` entry for 2.0.0 is recommended if not already included.

> BREAKING CHANGE: v2 switches to an async client, enforces HTTPS, and drops Python 3.7; synchronous v1 usage must be migrated as noted above.

Author: devinslick

.coverage

@@ -0,0 +1,16 @@
+[flake8]
+max-line-length = 120
+extend-ignore = E203, W503
+exclude =
+    .git,
+    __pycache__,
+    .venv,
+    venv,
+    build,
+    dist,
+    *.egg-info,
+    .pytest_cache,
+    .mypy_cache
+per-file-ignores =
+    # Functional tests import after path manipulation
+    tests/functional/*.py: E402

.flake8

@@ -1,14 +1,24 @@
 name: Publish Python Package
 
-# 1. Trigger the workflow when a new GitHub Release is published
+# Trigger on:
+#  - pushes to any branch (we'll publish to TestPyPI for non-main branches and to PyPI for main)
+#  - published GitHub Releases (keep existing behavior for canonical releases)
 on:
+  push:
+    branches: ["**"]
   release:
     types: [published]
 
+permissions:
+  contents: read
+  id-token: write
+
 jobs:
   build_sdist_and_wheel:
     name: Build distribution 📦
     runs-on: ubuntu-latest
+    outputs:
+      dist-path: ${{ steps.upload.outputs.artifact-path }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -18,70 +28,69 @@ jobs:
         with:
           python-version: "3.x"
 
-      # Install the 'build' tool, which creates the distribution files
-      - name: Install build dependencies
-        run: python -m pip install build
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build
 
-      # Create source and wheel distribution archives in the 'dist/' directory
       - name: Build distributions
-        run: python -m build
+        run: python -m build --sdist --wheel
 
-      # Store the built artifacts for the next jobs to download
       - name: Upload distribution artifacts
+        id: upload
         uses: actions/upload-artifact@v4
         with:
           name: python-package-distributions
           path: dist/
 
-  # --- PyPI Release Job (Secure, using OIDC) ---
-  pypi_publish:
-    name: Publish to PyPI
-    needs: [build_sdist_and_wheel] # Ensure the build job succeeds first
+  # Publish from pushes to non-main branches -> TestPyPI
+  publish_testpypi:
+    name: Publish to TestPyPI (branches except main)
     runs-on: ubuntu-latest
-    # Only publish to PyPI for full releases (not pre-releases)
-    if: github.event.release.prerelease == false
-    
-    # 2. Use the environment name you configured in PyPI (Optional, but recommended)
-    environment: pypi 
-    
-    # 3. CRITICAL: This is the mandatory permission for Trusted Publishers (OIDC)
+    needs: build_sdist_and_wheel
+    # Only run for pushes (not releases) and only for branches that are NOT main
+    if: |
+      github.event_name == 'push' &&
+      startsWith(github.ref, 'refs/heads/') &&
+      github.ref != 'refs/heads/main'
+    environment: testpypi
     permissions:
-      id-token: write 
-      contents: read # Required to read the repository contents
+      id-token: write
+      contents: read
 
     steps:
-      - name: Download all the dists
+      - name: Download dists
         uses: actions/download-artifact@v4
         with:
           name: python-package-distributions
           path: dist/
 
-      # 4. The PyPA action handles the OIDC token exchange and Twine upload securely
-      - name: Publish package distributions to PyPI
+      - name: Publish package distributions to TestPyPI
         uses: pypa/gh-action-pypi-publish@release/v1
-        
-  # --- TestPyPI Release Job (Optional, for pre-release testing) ---
-  testpypi_publish:
-    name: Publish to TestPyPI
-    needs: [build_sdist_and_wheel]
-    runs-on: ubuntu-latest
-
-    # Use the environment name you configured in TestPyPI
-    environment: testpypi 
+        with:
+          # repository-url directs upload to TestPyPI
+          repository-url: https://test.pypi.org/legacy/
 
+  # Publish from pushes to main OR when a Release is published -> Production PyPI
+  publish_pypi:
+    name: Publish to PyPI (main branch or GitHub Release)
+    runs-on: ubuntu-latest
+    needs: build_sdist_and_wheel
+    # Run when:
+    #  - push to main branch, or
+    #  - release published event (keeps existing release-based behavior)
+    if: |
+      (github.event_name == 'push' && github.ref == 'refs/heads/main') ||
+      (github.event_name == 'release' && github.event.action == 'published')
+    environment: pypi
     permissions:
       id-token: write
       contents: read
 
     steps:
-      - name: Download all the dists
+      - name: Download dists
         uses: actions/download-artifact@v4
         with:
           name: python-package-distributions
           path: dist/
-          
-      # The 'repository-url' is what makes this target TestPyPI
-      - name: Publish package distributions to TestPyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          repository-url: https://test.pypi.org/legacy/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/publish.yml

@@ -0,0 +1,85 @@
+name: Tests
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  lint:
+    name: Lint and Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run flake8
+        run: |
+          python -m flake8 fmd_api/ tests/ --count --show-source --statistics
+
+      - name: Run mypy
+        run: |
+          python -m mypy fmd_api/
+
+  test:
+    name: Test Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run unit tests with coverage
+        run: |
+          python -m pytest tests/unit --cov=fmd_api --cov-branch --cov-report=xml --cov-report=term -v
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          files: ./coverage.xml
+          flags: unittests
+          name: codecov-${{ matrix.os }}-py${{ matrix.python-version }}
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Run functional tests (if credentials available)
+        # Skip on PRs from forks where secrets aren't available
+        if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+        continue-on-error: true
+        run: |
+          python -m pytest tests/functional -v
+        env:
+          # Optional: set up test credentials as repository secrets
+          FMD_BASE_URL: ${{ secrets.FMD_BASE_URL }}
+          FMD_ID: ${{ secrets.FMD_ID }}
+          FMD_PASSWORD: ${{ secrets.FMD_PASSWORD }}

.github/workflows/test.yml

@@ -3,6 +3,12 @@ __pycache__/
 *.pyc
 *.pyo
 *.pyd
+*.zip
+
+# User configuration files
+*.env
+credentials.txt
+*.jpg
 
 # C extensions
 *.so
@@ -39,4 +45,7 @@ env/
 
 # FMD Server and android app files
 fmd-server/
-fmd-android/
+fmd-android/
+
+#credentials file
+examples/tests/credentials.txt