aiosolaredge-one 0.2.0__tar.gz

aiosolaredge_one-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  library:
+    name: Library (aiosolaredge-one)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[dev]"
+      - name: Ruff
+        run: ruff check src tests
+      - name: Mypy (strict)
+        run: mypy src
+      - name: Pytest
+        run: pytest -q

aiosolaredge_one-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+name: Publish aiosolaredge-one
+
+# Trusted Publishing (OIDC) — no API tokens stored anywhere.
+#   * Manual run (workflow_dispatch)  -> TestPyPI  (environment: testpypi)
+#   * GitHub Release published        -> PyPI      (environment: pypi)
+# One-time PyPI/TestPyPI setup is documented in RELEASING.md.
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - name: Validate metadata
+        run: pip install twine && python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  testpypi:
+    name: Publish to TestPyPI
+    if: github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

aiosolaredge_one-0.2.0/.gitignore

@@ -0,0 +1,21 @@
+# Secrets / local env
+.env
+*.env
+
+# Claude Code local settings — may contain secrets in the permission allow-list
+.claude/settings.local.json
+
+# Unredacted API captures — never commit
+fixtures/_raw/
+
+# Python
+.venv/
+.venv-test/
+*.egg-info/
+dist/
+build/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

aiosolaredge_one-0.2.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to `aiosolaredge-one` are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-08-24
+
+### Added
+- `budget` module: credit-budget pacing math (`compute_interval`,
+  `plan_interval`, `BudgetPlan`, `project_month_end_usage`, `backoff_interval`,
+  `cpm_floor`) for remaining-budget-aware, self-correcting poll scheduling.
+
+## [0.1.0] - 2026-08-24
+
+### Added
+- Initial async client for the SolarEdge ONE (Monitoring v2) API:
+  `get_sites`, `get_site_overview`, `get_devices`, `get_energy`, `get_power`,
+  `get_alerts`, `validate`.
+- Typed models (`Site`, `SiteOverview`, `Device`, `TimeSeries`, …), typed
+  exceptions, `CreditLedger` local monthly accounting, and `RateLimit` header
+  parsing.

aiosolaredge_one-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aiosolaredge-one contributors
+
+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.

aiosolaredge_one-0.2.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.5
+Name: aiosolaredge-one
+Version: 0.2.0
+Summary: Async client for the SolarEdge ONE (Monitoring v2) API
+Project-URL: Homepage, https://github.com/CathalOConnorRH/solaredge-v2
+Project-URL: Repository, https://github.com/CathalOConnorRH/solaredge-v2
+Project-URL: Issues, https://github.com/CathalOConnorRH/solaredge-v2/issues
+Project-URL: Changelog, https://github.com/CathalOConnorRH/solaredge-v2/blob/main/CHANGELOG.md
+Author: aiosolaredge-one contributors
+License: MIT License
+        
+        Copyright (c) 2026 aiosolaredge-one contributors
+        
+        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.
+License-File: LICENSE
+Keywords: async,home-assistant,monitoring,solar,solaredge
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: publish
+Requires-Dist: build>=1.2; extra == 'publish'
+Requires-Dist: twine>=5.0; extra == 'publish'
+Description-Content-Type: text/markdown
+
+# aiosolaredge-one
+
+Async Python client for the **SolarEdge ONE** (Monitoring API v2) platform. It
+powers the
+[SolarEdge ONE Home Assistant integration](https://github.com/CathalOConnorRH/ha-solaredge-one),
+which lives in its own repo and depends on this package.
+
+Base URL: `https://monitoringapi.solaredge.com/v2` · Auth: `X-API-Key` header
+(plus optional `X-Account-Key` for Fleet accounts).
+
+> Status: **alpha**. Endpoint coverage and models are derived from Phase 0 live
+> captures. Some query-param names and the storage/battery/environmental paths
+> are still unconfirmed pending docs.
+
+## Install (dev)
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Usage
+
+```python
+import aiohttp
+from aiosolaredge_one import SolarEdgeOneClient
+
+async with aiohttp.ClientSession() as session:
+    client = SolarEdgeOneClient(session, api_key="...")
+    sites = await client.get_sites()
+    overview = await client.get_site_overview(sites[0].site_id)
+    print(overview.production.total, overview.production.unit)
+    power = await client.get_power(sites[0].site_id)
+    print("current power:", power.latest_value, power.unit)
+```
+
+## What it covers (Phase 0-confirmed endpoints)
+
+| Method | Endpoint |
+|--------|----------|
+| `get_sites()` | `GET /sites` |
+| `get_site_overview(id)` | `GET /sites/{id}/overview` |
+| `get_devices(id)` | `GET /sites/{id}/devices` |
+| `get_energy(id, ...)` | `GET /sites/{id}/energy` |
+| `get_power(id, ...)` | `GET /sites/{id}/power` |
+| `get_alerts(id)` | `GET /sites/{id}/alerts` |
+
+Rate limiting: the client exposes `client.rate_limit` (per-minute limit +
+remaining, parsed from response headers) and an optional `CreditLedger` for
+tracking the monthly quota locally (not exposed by the API).

aiosolaredge_one-0.2.0/README.md

@@ -0,0 +1,51 @@
+# aiosolaredge-one
+
+Async Python client for the **SolarEdge ONE** (Monitoring API v2) platform. It
+powers the
+[SolarEdge ONE Home Assistant integration](https://github.com/CathalOConnorRH/ha-solaredge-one),
+which lives in its own repo and depends on this package.
+
+Base URL: `https://monitoringapi.solaredge.com/v2` · Auth: `X-API-Key` header
+(plus optional `X-Account-Key` for Fleet accounts).
+
+> Status: **alpha**. Endpoint coverage and models are derived from Phase 0 live
+> captures. Some query-param names and the storage/battery/environmental paths
+> are still unconfirmed pending docs.
+
+## Install (dev)
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Usage
+
+```python
+import aiohttp
+from aiosolaredge_one import SolarEdgeOneClient
+
+async with aiohttp.ClientSession() as session:
+    client = SolarEdgeOneClient(session, api_key="...")
+    sites = await client.get_sites()
+    overview = await client.get_site_overview(sites[0].site_id)
+    print(overview.production.total, overview.production.unit)
+    power = await client.get_power(sites[0].site_id)
+    print("current power:", power.latest_value, power.unit)
+```
+
+## What it covers (Phase 0-confirmed endpoints)
+
+| Method | Endpoint |
+|--------|----------|
+| `get_sites()` | `GET /sites` |
+| `get_site_overview(id)` | `GET /sites/{id}/overview` |
+| `get_devices(id)` | `GET /sites/{id}/devices` |
+| `get_energy(id, ...)` | `GET /sites/{id}/energy` |
+| `get_power(id, ...)` | `GET /sites/{id}/power` |
+| `get_alerts(id)` | `GET /sites/{id}/alerts` |
+
+Rate limiting: the client exposes `client.rate_limit` (per-minute limit +
+remaining, parsed from response headers) and an optional `CreditLedger` for
+tracking the monthly quota locally (not exposed by the API).

aiosolaredge_one-0.2.0/RELEASING.md

@@ -0,0 +1,83 @@
+# Releasing `aiosolaredge-one`
+
+This package is published to PyPI with **Trusted Publishing** (OIDC) — GitHub
+Actions authenticates to PyPI directly, so there are **no API tokens** stored in
+the repo or in GitHub secrets.
+
+Workflow: [`.github/workflows/publish.yml`](.github/workflows/publish.yml)
+- **Manual run** (`workflow_dispatch`) → **TestPyPI** (`testpypi` environment)
+- **GitHub Release published** → **PyPI** (`pypi` environment)
+
+## 0. Prerequisites (once)
+
+The repo is at **`CathalOConnorRH/solaredge-v2`** and `[project.urls]` in
+[`pyproject.toml`](pyproject.toml) already point there. If you fork or rename,
+update those URLs and the trusted-publisher config below to match.
+
+## 1. One-time Trusted Publisher config
+
+Do this on **both** TestPyPI and PyPI. You do **not** need to create the project
+first — use a "pending" publisher and it's created on first upload.
+
+### TestPyPI
+1. Sign in at <https://test.pypi.org> → *Your account* → *Publishing*.
+2. Under **Add a new pending publisher**, enter:
+   - **PyPI Project Name:** `aiosolaredge-one`
+   - **Owner:** `CathalOConnorRH`
+   - **Repository name:** `solaredge-v2`
+   - **Workflow name:** `publish.yml`
+   - **Environment name:** `testpypi`
+
+### PyPI
+Repeat at <https://pypi.org> with the **same** values except:
+   - **Environment name:** `pypi`
+
+### GitHub environments (optional but recommended)
+In the GitHub repo → *Settings* → *Environments*, create `testpypi` and `pypi`.
+Add required reviewers on `pypi` if you want a manual approval gate before a real
+release upload.
+
+## 2. Dry run to TestPyPI
+
+GitHub → *Actions* → **Publish aiosolaredge-one** → **Run workflow** (on `main`).
+This builds, `twine check`s, and uploads to TestPyPI. Verify the install:
+
+```bash
+python -m venv /tmp/veitest && /tmp/veitest/bin/pip install \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  aiosolaredge-one==0.2.0
+/tmp/veitest/bin/python -c "import aiosolaredge_one, sys; print(aiosolaredge_one.__version__)"
+```
+
+(The `--extra-index-url` lets TestPyPI resolve real deps like `aiohttp`.)
+
+## 3. Release to PyPI
+
+1. Bump `version` in `pyproject.toml` **and** `src/aiosolaredge_one/__init__.py`
+   (`__version__`), add a `CHANGELOG.md` entry, commit.
+2. Tag and create a GitHub Release:
+   ```bash
+   git tag v0.2.0 && git push origin v0.2.0
+   gh release create v0.2.0 --title v0.2.0 --notes-from-tag
+   ```
+3. Publishing the release triggers the `pypi` job automatically.
+
+Keep the release tag (`vX.Y.Z`) in sync with the package version. The HA
+integration lives in its own repo
+([`ha-solaredge-one`](https://github.com/CathalOConnorRH/ha-solaredge-one)) and
+pins `aiosolaredge-one==<version>` in its `manifest.json`; after publishing a new
+library version, bump that pin (and the integration `version`) there so a
+released integration always installs a published library.
+
+## Manual fallback (if not using CI)
+
+Trusted Publishing is preferred, but you can upload from a laptop with an API
+token:
+
+```bash
+python -m pip install ".[publish]"
+rm -rf dist && python -m build && python -m twine check dist/*
+python -m twine upload --repository testpypi dist/*   # dry run
+python -m twine upload dist/*                          # real PyPI
+```

aiosolaredge_one-0.2.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aiosolaredge-one"
+version = "0.2.0"
+description = "Async client for the SolarEdge ONE (Monitoring v2) API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [{ name = "aiosolaredge-one contributors" }]
+keywords = ["solaredge", "solar", "monitoring", "home-assistant", "async"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["aiohttp>=3.9"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "mypy>=1.8",
+    "ruff>=0.4",
+]
+publish = [
+    "build>=1.2",
+    "twine>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/CathalOConnorRH/solaredge-v2"
+Repository = "https://github.com/CathalOConnorRH/solaredge-v2"
+Issues = "https://github.com/CathalOConnorRH/solaredge-v2/issues"
+Changelog = "https://github.com/CathalOConnorRH/solaredge-v2/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aiosolaredge_one"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unused_ignores = true

aiosolaredge_one-0.2.0/src/aiosolaredge_one/__init__.py

@@ -0,0 +1,66 @@
+"""Async client for the SolarEdge ONE (Monitoring v2) API."""
+
+from __future__ import annotations
+
+from .budget import (
+    BudgetPlan,
+    backoff_interval,
+    compute_interval,
+    plan_interval,
+    project_month_end_usage,
+)
+from .client import SolarEdgeOneClient
+from .const import (
+    DEFAULT_BASE_URL,
+    RESOLUTION_DAY,
+    RESOLUTION_HOUR,
+    RESOLUTION_QUARTER_HOUR,
+)
+from .exceptions import (
+    SolarEdgeApiError,
+    SolarEdgeAuthError,
+    SolarEdgeConnectionError,
+    SolarEdgeError,
+    SolarEdgeNotFoundError,
+    SolarEdgeRateLimitError,
+)
+from .models import (
+    ConsumptionOverview,
+    Device,
+    ProductionOverview,
+    Site,
+    SiteOverview,
+    TimeSeries,
+    TimeValue,
+)
+from .ratelimit import CreditLedger, RateLimit
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "SolarEdgeOneClient",
+    "BudgetPlan",
+    "backoff_interval",
+    "compute_interval",
+    "plan_interval",
+    "project_month_end_usage",
+    "DEFAULT_BASE_URL",
+    "RESOLUTION_DAY",
+    "RESOLUTION_HOUR",
+    "RESOLUTION_QUARTER_HOUR",
+    "SolarEdgeError",
+    "SolarEdgeApiError",
+    "SolarEdgeAuthError",
+    "SolarEdgeConnectionError",
+    "SolarEdgeNotFoundError",
+    "SolarEdgeRateLimitError",
+    "Site",
+    "SiteOverview",
+    "ProductionOverview",
+    "ConsumptionOverview",
+    "Device",
+    "TimeSeries",
+    "TimeValue",
+    "CreditLedger",
+    "RateLimit",
+]

aiosolaredge_one-0.2.0/src/aiosolaredge_one/budget.py

@@ -0,0 +1,145 @@
+"""Credit-budget pacing math (HA-agnostic, pure functions).
+
+The SolarEdge ONE API exposes only a per-minute rate limit; the monthly credit
+quota (e.g. 2000/month) is tracked locally via :class:`CreditLedger`. This module
+turns "credits remaining this month" into "how long to wait before the next poll"
+so a caller spends its budget evenly instead of burning it early.
+
+The core function, :func:`compute_interval`, is *remaining-budget aware*: it
+paces against the credits still available for the rest of the month, so it
+self-corrects. If earlier cycles overspent, later intervals lengthen; if the
+budget is nearly exhausted it backs off to ``max_interval``. This doubles as the
+budget guard — no separate "are we over budget?" branch is needed for pacing.
+
+All functions are pure (no clock, no I/O) so they can be unit-tested by feeding
+in ``remaining_credits`` / ``seconds_until_reset`` directly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Sensible defaults; the HA integration overrides these from config/options.
+DEFAULT_SAFETY_FACTOR = 0.7
+DEFAULT_NIGHT_FACTOR = 3.0
+DEFAULT_MIN_INTERVAL = 60.0  # seconds — never poll faster than once a minute
+DEFAULT_MAX_INTERVAL = 6 * 60 * 60.0  # seconds — poll at least every 6h
+
+
+def _clamp(value: float, low: float, high: float) -> float:
+    if low > high:
+        # A pathological config (floor above ceiling); prefer respecting the
+        # per-minute floor over the ceiling to avoid violating the hard limit.
+        return low
+    return max(low, min(high, value))
+
+
+def cpm_floor(credits_per_cycle: int, calls_per_minute: int) -> float:
+    """Minimum seconds between cycles so we never exceed the per-minute limit.
+
+    A cycle issues ``credits_per_cycle`` calls; spacing cycles at least this far
+    apart keeps the average call rate at or below ``calls_per_minute``.
+    """
+    cpm = max(1, calls_per_minute)
+    return 60.0 * max(1, credits_per_cycle) / cpm
+
+
+@dataclass(slots=True, frozen=True)
+class BudgetPlan:
+    """User-configurable pacing parameters for one config entry."""
+
+    monthly_budget: int
+    calls_per_minute: int = 10
+    credits_per_cycle: int = 2
+    safety_factor: float = DEFAULT_SAFETY_FACTOR
+    night_factor: float = DEFAULT_NIGHT_FACTOR
+    min_interval: float = DEFAULT_MIN_INTERVAL
+    max_interval: float = DEFAULT_MAX_INTERVAL
+
+    @property
+    def target_credits(self) -> float:
+        """Credits we actually aim to spend per month (budget × safety)."""
+        return self.monthly_budget * self.safety_factor
+
+
+def compute_interval(
+    *,
+    remaining_credits: float,
+    seconds_until_reset: float,
+    credits_per_cycle: int,
+    calls_per_minute: int,
+    min_interval: float = DEFAULT_MIN_INTERVAL,
+    max_interval: float = DEFAULT_MAX_INTERVAL,
+    is_night: bool = False,
+    night_factor: float = DEFAULT_NIGHT_FACTOR,
+) -> float:
+    """Seconds to wait before the next poll, paced to the remaining budget.
+
+    ``remaining_credits`` should already have the safety factor applied (i.e. it
+    is the *target* remaining, not the raw quota). When it drops below one
+    cycle's cost — or the month has effectively ended — this returns
+    ``max_interval`` so polling backs off instead of overspending.
+    """
+    floor = max(min_interval, cpm_floor(credits_per_cycle, calls_per_minute))
+    if remaining_credits < credits_per_cycle or seconds_until_reset <= 0:
+        return max(max_interval, floor)
+
+    cycles_left = remaining_credits / max(1, credits_per_cycle)
+    interval = seconds_until_reset / cycles_left
+    if is_night:
+        interval *= night_factor
+    return _clamp(interval, floor, max_interval)
+
+
+def plan_interval(
+    plan: BudgetPlan,
+    *,
+    used_this_month: int,
+    seconds_until_reset: float,
+    is_night: bool = False,
+) -> float:
+    """Convenience wrapper: interval for a :class:`BudgetPlan` given usage."""
+    remaining = max(0.0, plan.target_credits - used_this_month)
+    return compute_interval(
+        remaining_credits=remaining,
+        seconds_until_reset=seconds_until_reset,
+        credits_per_cycle=plan.credits_per_cycle,
+        calls_per_minute=plan.calls_per_minute,
+        min_interval=plan.min_interval,
+        max_interval=plan.max_interval,
+        is_night=is_night,
+        night_factor=plan.night_factor,
+    )
+
+
+def project_month_end_usage(
+    *, used_this_month: int, elapsed_seconds: float, total_seconds: float
+) -> float:
+    """Linear projection of end-of-month spend from usage so far.
+
+    Used to decide whether to raise a "you'll blow the budget" repair issue.
+    Returns the current usage unchanged until a little time has elapsed (avoids
+    wild extrapolation from the first few seconds of the month).
+    """
+    if elapsed_seconds <= 0 or total_seconds <= 0:
+        return float(used_this_month)
+    return used_this_month * total_seconds / elapsed_seconds
+
+
+def backoff_interval(
+    attempt: int,
+    *,
+    base: float = 60.0,
+    cap: float = 60 * 60.0,
+    retry_after: float | None = None,
+) -> float:
+    """Exponential backoff after a 429, honouring ``Retry-After`` when present.
+
+    ``attempt`` is 1-based (first failure → ``base``). The result is capped at
+    ``cap`` and never shorter than a supplied ``Retry-After``.
+    """
+    exp = base * (2.0 ** max(0, attempt - 1))
+    interval = min(exp, cap)
+    if retry_after is not None:
+        interval = max(interval, retry_after)
+    return interval