asa-api-client 0.2.0__tar.gz → 0.3.0__tar.gz

{asa_api_client-0.2.0 → asa_api_client-0.3.0}/.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
         python-version: ["3.13"]
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
@@ -24,6 +24,9 @@ jobs:
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
 
+      - name: Check uv.lock is up to date
+        run: uv lock --check
+
       - name: Install dependencies
         run: uv sync --extra dev
 
@@ -40,7 +43,7 @@ jobs:
         run: uv run pytest --cov=asa_api_client --cov-report=xml
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v7
         with:
           file: ./coverage.xml
           fail_ci_if_error: false

{asa_api_client-0.2.0 → asa_api_client-0.3.0}/.github/workflows/docs.yml

@@ -18,10 +18,10 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v7
         with:
           version: "latest"
 
@@ -35,10 +35,10 @@ jobs:
         run: uv run mkdocs build
 
       - name: Setup Pages
-        uses: actions/configure-pages@v4
+        uses: actions/configure-pages@v6
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v5
         with:
           path: site
 
@@ -51,4 +51,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

{asa_api_client-0.2.0 → asa_api_client-0.3.0}/.github/workflows/publish.yml

@@ -12,7 +12,7 @@ jobs:
       id-token: write  # Required for trusted publishing
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7

{asa_api_client-0.2.0 → asa_api_client-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: asa-api-client
-Version: 0.2.0
+Version: 0.3.0
 Summary: A modern Python client for the Apple Search Ads API with full type safety and async support
 Project-URL: Homepage, https://github.com/SamPetherbridge/asa-api-client
 Project-URL: Documentation, https://asa-api-client.peth.au
@@ -23,8 +23,14 @@ Requires-Dist: httpx>=0.27.0
 Requires-Dist: pydantic-settings>=2.6.0
 Requires-Dist: pydantic>=2.10.0
 Requires-Dist: pyjwt[crypto]>=2.9.0
+Provides-Extra: cli
+Requires-Dist: pandas>=2.2.0; extra == 'cli'
+Requires-Dist: rich>=13.0.0; extra == 'cli'
+Requires-Dist: typer>=0.15.0; extra == 'cli'
+Requires-Dist: xlsxwriter>=3.2.0; extra == 'cli'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: openpyxl>=3.1.0; extra == 'dev'
 Requires-Dist: pandas-stubs>=2.2.0; extra == 'dev'
 Requires-Dist: pandas>=2.2.0; extra == 'dev'
 Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
@@ -32,7 +38,11 @@ Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
 Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
 Requires-Dist: pytest-httpx>=0.34.0; extra == 'dev'
 Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: rich>=13.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: typer>=0.15.0; extra == 'dev'
+Requires-Dist: types-openpyxl>=3.1.0; extra == 'dev'
+Requires-Dist: xlsxwriter>=3.2.0; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
 Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
@@ -48,7 +58,7 @@ Description-Content-Type: text/markdown
 [![License](https://img.shields.io/github/license/SamPetherbridge/asa-api-client.svg)](https://github.com/SamPetherbridge/asa-api-client/blob/main/LICENSE)
 [![CI](https://github.com/SamPetherbridge/asa-api-client/actions/workflows/ci.yml/badge.svg)](https://github.com/SamPetherbridge/asa-api-client/actions/workflows/ci.yml)
 
-A modern, fully-typed Python client for the Apple Search Ads API with async support and Pydantic models.
+A modern, fully-typed Python client for the Apple Ads APIs with async support and Pydantic models — covering both the new **Apple Ads Platform API v1** and the legacy Campaign Management API v5 (sunset January 26, 2027).
 
 ## Features
 
@@ -105,6 +115,35 @@ with client:
         print(f"{campaign.name}: {campaign.status}")
 ```
 
+## Platform API v1
+
+Apple's new [Platform API v1](https://developer.apple.com/documentation/apple-ads-platform-api) replaces v5 (which stops working on **2027-01-26**). The v1 client ships alongside the v5 client with the same credentials — just add your ad account ID:
+
+```python
+from asa_api_client import AppleAdsClient
+from asa_api_client.v1 import Query
+
+client = AppleAdsClient.from_env()  # reads ASA_* plus ASA_AD_ACCOUNT_ID
+
+with client:
+    # Flat query-based API with typed filters
+    enabled = client.campaigns.query(Query().where("status", "EQUALS", "ENABLED"))
+
+    # v1-only features
+    recs = client.recommendations
+    popularity = client.insights
+    history = client.change_history
+    bulk = client.bulk
+```
+
+Don't know your ad account ID? Run the read-only smoke check — it discovers accounts and validates the whole integration against the live API:
+
+```bash
+asa v1-smoke
+```
+
+See the [Platform API v1 guide](https://asa-api-client.peth.au/guide/platform-api-v1/) for the full migration crib and resource reference. Import v1 symbols from the package root (`AppleAdsClient`) — internal layout may change when v5 is removed.
+
 ## Environment Variables
 
 ```bash
@@ -113,6 +152,7 @@ export ASA_TEAM_ID="SEARCHADS.your-team-id"
 export ASA_KEY_ID="your-key-id"
 export ASA_ORG_ID="123456"
 export ASA_PRIVATE_KEY_PATH="/path/to/private-key.pem"
+export ASA_AD_ACCOUNT_ID="123456"  # Platform API v1 only
 ```
 
 Or use a `.env` file:
@@ -123,6 +163,7 @@ ASA_TEAM_ID=SEARCHADS.your-team-id
 ASA_KEY_ID=your-key-id
 ASA_ORG_ID=123456
 ASA_PRIVATE_KEY_PATH=private-key.pem
+ASA_AD_ACCOUNT_ID=123456  # Platform API v1 only
 ```
 
 ## Resources
@@ -223,14 +264,15 @@ asyncio.run(main())
 
 ## CLI
 
-For a command-line interface, install [asa-api-cli](https://github.com/SamPetherbridge/asa-api-cli):
+Generate a formatted Excel analysis workbook with the included `asa analyze` CLI:
 
 ```bash
-uv tool install asa-api-cli
-# or
-pip install asa-api-cli
+pip install "asa-api-client[cli]"
+asa analyze --period 90d --output report.xlsx
 ```
 
+The workbook includes a summary sheet with KPIs and trends, formatted analysis sheets per reporting level, and raw daily data for pivoting. For details, see the [CLI guide](https://asa-api-client.peth.au/guide/cli/).
+
 ## License
 
 MIT License - Copyright (c) 2025 Peth Pty Ltd

{asa_api_client-0.2.0 → asa_api_client-0.3.0}/README.md

@@ -5,7 +5,7 @@
 [![License](https://img.shields.io/github/license/SamPetherbridge/asa-api-client.svg)](https://github.com/SamPetherbridge/asa-api-client/blob/main/LICENSE)
 [![CI](https://github.com/SamPetherbridge/asa-api-client/actions/workflows/ci.yml/badge.svg)](https://github.com/SamPetherbridge/asa-api-client/actions/workflows/ci.yml)
 
-A modern, fully-typed Python client for the Apple Search Ads API with async support and Pydantic models.
+A modern, fully-typed Python client for the Apple Ads APIs with async support and Pydantic models — covering both the new **Apple Ads Platform API v1** and the legacy Campaign Management API v5 (sunset January 26, 2027).
 
 ## Features
 
@@ -62,6 +62,35 @@ with client:
         print(f"{campaign.name}: {campaign.status}")
 ```
 
+## Platform API v1
+
+Apple's new [Platform API v1](https://developer.apple.com/documentation/apple-ads-platform-api) replaces v5 (which stops working on **2027-01-26**). The v1 client ships alongside the v5 client with the same credentials — just add your ad account ID:
+
+```python
+from asa_api_client import AppleAdsClient
+from asa_api_client.v1 import Query
+
+client = AppleAdsClient.from_env()  # reads ASA_* plus ASA_AD_ACCOUNT_ID
+
+with client:
+    # Flat query-based API with typed filters
+    enabled = client.campaigns.query(Query().where("status", "EQUALS", "ENABLED"))
+
+    # v1-only features
+    recs = client.recommendations
+    popularity = client.insights
+    history = client.change_history
+    bulk = client.bulk
+```
+
+Don't know your ad account ID? Run the read-only smoke check — it discovers accounts and validates the whole integration against the live API:
+
+```bash
+asa v1-smoke
+```
+
+See the [Platform API v1 guide](https://asa-api-client.peth.au/guide/platform-api-v1/) for the full migration crib and resource reference. Import v1 symbols from the package root (`AppleAdsClient`) — internal layout may change when v5 is removed.
+
 ## Environment Variables
 
 ```bash
@@ -70,6 +99,7 @@ export ASA_TEAM_ID="SEARCHADS.your-team-id"
 export ASA_KEY_ID="your-key-id"
 export ASA_ORG_ID="123456"
 export ASA_PRIVATE_KEY_PATH="/path/to/private-key.pem"
+export ASA_AD_ACCOUNT_ID="123456"  # Platform API v1 only
 ```
 
 Or use a `.env` file:
@@ -80,6 +110,7 @@ ASA_TEAM_ID=SEARCHADS.your-team-id
 ASA_KEY_ID=your-key-id
 ASA_ORG_ID=123456
 ASA_PRIVATE_KEY_PATH=private-key.pem
+ASA_AD_ACCOUNT_ID=123456  # Platform API v1 only
 ```
 
 ## Resources
@@ -180,14 +211,15 @@ asyncio.run(main())
 
 ## CLI
 
-For a command-line interface, install [asa-api-cli](https://github.com/SamPetherbridge/asa-api-cli):
+Generate a formatted Excel analysis workbook with the included `asa analyze` CLI:
 
 ```bash
-uv tool install asa-api-cli
-# or
-pip install asa-api-cli
+pip install "asa-api-client[cli]"
+asa analyze --period 90d --output report.xlsx
 ```
 
+The workbook includes a summary sheet with KPIs and trends, formatted analysis sheets per reporting level, and raw daily data for pivoting. For details, see the [CLI guide](https://asa-api-client.peth.au/guide/cli/).
+
 ## License
 
 MIT License - Copyright (c) 2025 Peth Pty Ltd

{asa_api_client-0.2.0 → asa_api_client-0.3.0}/asa_api_client/__init__.py

@@ -29,22 +29,26 @@ from asa_api_client.exceptions import (
     AuthenticationError,
     ConfigurationError,
     NotFoundError,
+    PartialFailureError,
     RateLimitError,
     ValidationError,
 )
 from asa_api_client.logging import configure_logging
 from asa_api_client.settings import Settings
+from asa_api_client.v1.client import AppleAdsClient
 
 __all__ = [
+    "AppleAdsClient",
     "AppleSearchAdsClient",
     "AppleSearchAdsError",
     "AuthenticationError",
     "ConfigurationError",
     "NotFoundError",
+    "PartialFailureError",
     "RateLimitError",
     "Settings",
     "ValidationError",
     "configure_logging",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{asa_api_client-0.2.0 → asa_api_client-0.3.0}/asa_api_client/auth.py

@@ -446,11 +446,15 @@ class Authenticator:
             errors = e.errors()
             if errors:
                 first_error = errors[0]
-                field = first_error.get("loc", ["unknown"])[0]
+                # Model-level validators (e.g. the private-key source check)
+                # report an empty loc tuple.
+                loc = first_error.get("loc") or ()
                 msg = first_error.get("msg", "validation error")
-                raise ConfigurationError(
-                    f"Configuration error for ASA_{str(field).upper()}: {msg}"
-                ) from e
+                if loc:
+                    raise ConfigurationError(
+                        f"Configuration error for ASA_{str(loc[0]).upper()}: {msg}"
+                    ) from e
+                raise ConfigurationError(f"Configuration error: {msg}") from e
             raise ConfigurationError(f"Configuration error: {e}") from e
 
         return cls(

asa_api_client-0.3.0/asa_api_client/cli/__init__.py

@@ -0,0 +1,20 @@
+"""Console entry point for the ``asa`` CLI.
+
+The CLI's dependencies (typer, rich, pandas, xlsxwriter) are an optional
+extra.  ``main`` guards the import so a bare install gets a clean install
+hint instead of a traceback.
+"""
+
+import sys
+
+_INSTALL_HINT = 'Install the CLI extra: pip install "asa-api-client[cli]"'
+
+
+def main() -> None:
+    """Run the ``asa`` command-line interface."""
+    try:
+        from asa_api_client.cli.analyze import app
+    except ImportError:
+        sys.stderr.write(_INSTALL_HINT + "\n")
+        raise SystemExit(1) from None
+    app()

asa_api_client-0.3.0/asa_api_client/cli/analyze.py

@@ -0,0 +1,235 @@
+"""The ``asa analyze`` command: options, orchestration, presentation."""
+
+import asyncio
+from datetime import UTC, date, datetime
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import pandas as pd
+import typer
+from rich.console import Console
+from rich.progress import BarColumn, Progress, TaskID, TextColumn
+from xlsxwriter.exceptions import XlsxWriterException
+
+from asa_api_client.cli import dates, fetch, metrics, v1_smoke
+from asa_api_client.cli.v1_adapter import V1FetchAdapter
+from asa_api_client.cli.workbook import SummaryData, write_workbook
+from asa_api_client.client import AppleSearchAdsClient
+from asa_api_client.exceptions import AppleSearchAdsError, ConfigurationError
+from asa_api_client.v1.client import AppleAdsClient
+
+app = typer.Typer(no_args_is_help=True, add_completion=False)
+app.command("v1-smoke")(v1_smoke.command)
+_err = Console(stderr=True)
+
+
+@app.callback()
+def _root() -> None:
+    """Apple Search Ads analysis toolkit."""
+
+
+class Period(StrEnum):
+    """Preset reporting periods."""
+
+    D30 = "30d"
+    D90 = "90d"
+    D365 = "365d"
+
+
+class ApiVersion(StrEnum):
+    """Selectable Apple Ads API backends."""
+
+    V5 = "v5"
+    V1 = "v1"
+
+
+_CURRENCY_FORMATS = {
+    "USD": "$#,##0.00",
+    "AUD": "$#,##0.00",
+    "CAD": "$#,##0.00",
+    "NZD": "$#,##0.00",
+    "EUR": "€#,##0.00",
+    "GBP": "£#,##0.00",
+    "JPY": "¥#,##0",
+}
+
+
+def _currency_format(code: str | None) -> str:
+    """Map an ISO currency code to an Excel number format."""
+    if code is None:
+        return "$#,##0.00"
+    return _CURRENCY_FORMATS.get(code, f'"{code} "#,##0.00')
+
+
+def _currency_symbol(currency_format: str) -> str:
+    """First non-format character of the currency format, for the headline."""
+    head = currency_format[0]
+    return head if head not in '#0["' else "$"
+
+
+def _fail(message: str) -> "typer.Exit":
+    """Print a clean one-line error and exit 1."""
+    _err.print(f"[red]Error:[/red] {message}")
+    return typer.Exit(code=1)
+
+
+async def _fetch(
+    client: fetch.FetchClient,
+    meta: pd.DataFrame,
+    start: date,
+    end: date,
+    timezone: str,
+    progress: Progress,
+) -> fetch.FetchResult:
+    """Run fetch_all wired to the rich progress display."""
+    tasks: dict[str, TaskID] = {
+        key: progress.add_task(label, total=None) for key, label in fetch.LEVELS
+    }
+
+    def on_progress(key: str, done: int, total: int) -> None:
+        progress.update(tasks[key], completed=done, total=total)
+
+    try:
+        return await fetch.fetch_all(
+            client,
+            meta,
+            start,
+            end,
+            timezone=timezone,
+            today=datetime.now(tz=UTC).date(),
+            on_progress=on_progress,
+        )
+    finally:
+        await client.aclose()
+
+
+@app.command()
+def analyze(
+    app_ids: Annotated[
+        list[int] | None,
+        typer.Option("--app", "-a", help="Adam ID to scope to; repeatable."),
+    ] = None,
+    period: Annotated[
+        Period, typer.Option("--period", "-p", help="Preset range ending yesterday.")
+    ] = Period.D30,
+    from_date: Annotated[
+        datetime | None,
+        typer.Option("--from", formats=["%Y-%m-%d"], help="Explicit start date."),
+    ] = None,
+    to_date: Annotated[
+        datetime | None,
+        typer.Option("--to", formats=["%Y-%m-%d"], help="Explicit end date."),
+    ] = None,
+    output: Annotated[
+        Path | None, typer.Option("--output", "-o", help="Output .xlsx path.")
+    ] = None,
+    timezone: Annotated[str, typer.Option("--timezone", help="Reporting timezone.")] = "UTC",
+    currency_format: Annotated[
+        str | None,
+        typer.Option("--currency-format", help="Excel number format for money."),
+    ] = None,
+    api_version: Annotated[
+        ApiVersion,
+        typer.Option("--api-version", help="Apple Ads API version to fetch with."),
+    ] = ApiVersion.V5,
+) -> None:
+    """Generate an Excel performance analysis workbook."""
+    today = datetime.now(tz=UTC).date()
+    try:
+        start, end = dates.resolve_range(
+            period.value,
+            from_date.date() if from_date else None,
+            to_date.date() if to_date else None,
+            today=today,
+        )
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    client: AppleSearchAdsClient | V1FetchAdapter
+    try:
+        if api_version is ApiVersion.V1:
+            client = V1FetchAdapter(AppleAdsClient.from_env())
+        else:
+            client = AppleSearchAdsClient.from_env()
+    except ConfigurationError as exc:
+        raise _fail(str(exc)) from exc
+
+    try:
+        meta, currency = fetch.resolve_scope(client, app_ids)
+        with Progress(
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            TextColumn("{task.completed}/{task.total}"),
+        ) as progress:
+            result = asyncio.run(_fetch(client, meta, start, end, timezone, progress))
+    except fetch.ScopeError as exc:
+        raise _fail(str(exc)) from exc
+    except fetch.LevelFetchError as exc:
+        raise _fail(str(exc)) from exc
+    except AppleSearchAdsError as exc:
+        raise _fail(str(exc)) from exc
+    finally:
+        client.close()
+
+    for warning in result.warnings:
+        _err.print(f"[yellow]Warning:[/yellow] {warning}")
+
+    daily_frames = {key: metrics.normalize(lv.daily) for key, lv in result.levels.items()}
+    analysis = {
+        key: metrics.aggregate(daily_frames[key], metrics.LEVEL_KEYS[key]) for key in daily_frames
+    }
+    campaign_daily = daily_frames["campaigns"]
+    current_kpis = metrics.kpis(campaign_daily)
+    prior_kpis = (
+        metrics.kpis(metrics.normalize(result.prior_campaigns))
+        if not result.prior_campaigns.empty
+        else None
+    )
+
+    apps_in_scope = sorted(meta["adam_id"].unique().tolist())
+    if app_ids and len(apps_in_scope) == 1:
+        scope_label = meta["app_name"].iloc[0]
+        file_scope = str(apps_in_scope[0])
+    else:
+        scope_label = "All apps"
+        file_scope = "org"
+    day_count = (end - start).days + 1
+    fmt = currency_format or _currency_format(currency)
+
+    summary = SummaryData(
+        title=f"{scope_label} · Apple Search Ads performance",
+        period_label=f"{start} – {end} ({day_count} days)",  # noqa: RUF001
+        timezone=timezone,
+        generated_at=datetime.now(tz=UTC),
+        kpis=current_kpis,
+        prior_kpis=prior_kpis,
+        daily=metrics.daily_series(campaign_daily),
+        per_app=metrics.per_app(campaign_daily) if len(apps_in_scope) > 1 else None,
+        top_keywords=metrics.top_keywords(analysis["keywords"]),
+        wasted=metrics.wasted_spend(analysis["keywords"]),
+    )
+
+    out_path = output or Path(f"asa-analysis-{file_scope}-{today:%Y-%m-%d}.xlsx")
+    notes = {key: lv.notes for key, lv in result.levels.items()}
+    try:
+        write_workbook(
+            out_path,
+            summary=summary,
+            analysis=analysis,
+            daily=daily_frames,
+            notes=notes,
+            currency_format=fmt,
+        )
+    except (OSError, XlsxWriterException) as exc:
+        raise _fail(f"Could not write {out_path}: {exc}") from exc
+
+    symbol = _currency_symbol(fmt)
+    spend = current_kpis["spend"]
+    installs = int(current_kpis["installs"])
+    cpa = current_kpis["cpa"]
+    cpa_text = f"{symbol}{cpa:,.2f} CPA" if cpa == cpa else "— CPA"
+    typer.echo(str(out_path))
+    typer.echo(
+        f"{symbol}{spend:,.0f} spend · {installs} installs · {cpa_text} over {day_count} days"
+    )

asa_api_client-0.3.0/asa_api_client/cli/dates.py

@@ -0,0 +1,95 @@
+"""Pure date arithmetic for the analyze command.
+
+Stdlib-only so it can be imported and unit-tested without the ``cli``
+extra installed.
+"""
+
+from datetime import date, timedelta
+
+PERIODS: dict[str, int] = {"30d": 30, "90d": 90, "365d": 365}
+MAX_LOOKBACK_DAYS = 730
+MAX_DAILY_WINDOW = 90
+SEARCH_TERM_LOOKBACK = 90
+
+
+def resolve_range(
+    period: str,
+    from_date: date | None,
+    to_date: date | None,
+    *,
+    today: date,
+) -> tuple[date, date]:
+    """Resolve CLI options into an inclusive (start, end) date range.
+
+    Args:
+        period: Preset key from :data:`PERIODS` (used when no explicit dates).
+        from_date: Explicit start date; overrides the preset.
+        to_date: Explicit end date; defaults to yesterday when only
+            ``from_date`` is given.
+        today: The current date (injected for testability).
+
+    Returns:
+        Inclusive ``(start, end)`` dates.
+
+    Raises:
+        ValueError: If the preset is unknown, the range is reversed, ends
+            in the future, or starts beyond the API lookback.
+    """
+    yesterday = today - timedelta(days=1)
+
+    if from_date is None and to_date is None:
+        if period not in PERIODS:
+            raise ValueError(f"Unknown period {period!r}; choose one of {sorted(PERIODS)}")
+        end = yesterday
+        start = end - timedelta(days=PERIODS[period] - 1)
+    else:
+        if from_date is None:
+            raise ValueError("--to requires --from")
+        start = from_date
+        end = to_date if to_date is not None else yesterday
+
+    if start > end:
+        raise ValueError(f"--from ({start}) must be before --to ({end})")
+    if end > yesterday:
+        raise ValueError(f"--to ({end}) must not be in the future; latest full day is {yesterday}")
+    if start < today - timedelta(days=MAX_LOOKBACK_DAYS):
+        raise ValueError(f"--from ({start}) is beyond the API lookback of {MAX_LOOKBACK_DAYS} days")
+
+    return start, end
+
+
+def chunk_windows(
+    start: date, end: date, max_days: int = MAX_DAILY_WINDOW
+) -> list[tuple[date, date]]:
+    """Split an inclusive date range into contiguous windows of at most ``max_days``.
+
+    Args:
+        start: Range start (inclusive).
+        end: Range end (inclusive).
+        max_days: Maximum days per window (the API caps DAILY reports at 90).
+
+    Returns:
+        Ordered list of inclusive ``(start, end)`` windows tiling the range.
+    """
+    windows: list[tuple[date, date]] = []
+    cursor = start
+    while cursor <= end:
+        window_end = min(cursor + timedelta(days=max_days - 1), end)
+        windows.append((cursor, window_end))
+        cursor = window_end + timedelta(days=1)
+    return windows
+
+
+def prior_window(start: date, end: date) -> tuple[date, date]:
+    """Return the equal-length window immediately preceding ``start``-``end``.
+
+    Args:
+        start: Current range start (inclusive).
+        end: Current range end (inclusive).
+
+    Returns:
+        Inclusive ``(start, end)`` of the preceding window.
+    """
+    length = (end - start).days
+    prior_end = start - timedelta(days=1)
+    return prior_end - timedelta(days=length), prior_end