insitukit 0.1.0__tar.gz

insitukit-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,3 @@
+Read `/AGENTS.md` in this repository first; it is the canonical guide for agents.
+Then apply the shared rules in `$HOME/.agents/global-rules.md`.
+Never commit or push without the maintainer's explicit approval of the diff and message.

insitukit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,55 @@
+name: Publish to PyPI
+
+# Pushing a tag vX.Y.Z builds the sdist and wheel and publishes them to PyPI through trusted publishing (OIDC): no API
+# token is stored anywhere. PyPI must list this repository, this workflow file and the `pypi` environment as a
+# trusted publisher for insitukit.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Check the tag matches both version strings
+        run: |
+          version=$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
+          init=$(sed -n 's/^__version__ = "\(.*\)"$/\1/p' src/insitukit/__init__.py)
+          if [ "v$version" != "$GITHUB_REF_NAME" ] || [ "$init" != "$version" ]; then
+            echo "Tag $GITHUB_REF_NAME, pyproject.toml $version and __version__ $init must agree" >&2
+            exit 1
+          fi
+
+      - name: Test
+        run: uv sync --dev --all-extras && uv run pytest
+
+      - name: Build
+        run: uv build
+
+      - name: Check the distributions
+        run: uvx twine check --strict dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/insitukit
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

insitukit-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,33 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  unit:
+    name: Unit tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python }}
+
+      - name: Sync dependencies
+        run: uv sync --dev --all-extras
+
+      # The pinned hooks from .pre-commit-config.yaml, so CI and a local commit apply the same ruff.
+      - name: Lint
+        run: uv run pre-commit run --all-files --show-diff-on-failure
+
+      - name: Unit tests
+        run: uv run pytest --durations=10

insitukit-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.vscode/
+
+# Planning ledger files stay out of public repositories
+task.md
+implementation_plan.md
+walkthrough.md

insitukit-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-toml
+      - id: detect-private-key
+
+  # Pinned deliberately, as in forcingkit: CI runs these same hooks, and the rule selection is pinned alongside in
+  # pyproject.toml [tool.ruff.lint]. Linting only: no formatter, so the modules keep the layout they came with.
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.9
+    hooks:
+      - id: ruff-check

insitukit-0.1.0/AGENTS.md

@@ -0,0 +1,34 @@
+# AGENTS.md
+
+Context for AI developer agents working in `lhzn-io/insitukit`. Human entry point: `README.md`.
+
+## Architecture
+
+- `src/insitukit/`: `coops.py` (NOAA CO-OPS; an HTTP 200 with an error body or "No data was found" is an empty
+  result), `erddap.py` (ERDDAP tabledap with a per-instance budget and unreachable flag), `stats.py`, `series.py`
+  (the JSON series form), `store.py` (directory, Workers KV or GCS behind a name and size guard), and `identify` in
+  `__init__.py`.
+- `tests/`: offline unit tests; HTTP calls are replaced.
+- Dependencies stay small: numpy, pandas, requests. Anything heavier is an optional extra (`gcs`).
+
+## Rules
+
+- **Public repository and package.** Name only public data sources. No site-, partner- or project-specific code,
+  defaults or examples beyond public stations; those belong in the projects that use the library.
+- **Polite clients.** Every request is paced and identified; never remove the pacing, budget or retry limits.
+- **Stable formats.** `series` output is read by web pages; change it only in a way old readers still handle, and
+  note it in the release.
+- Style: no emojis, no em dashes, plain technical language. Organisation name: Long Horizon Observatory.
+- **Releases.** Bump `version` in `pyproject.toml` and `__version__` together; a `v<version>` tag publishes to PyPI
+  through `.github/workflows/publish.yml` (trusted publishing, no token).
+- **Commits.** Author and commit as the human contributor (`git config` user). Record the agent harness and model as
+  a plain-text line at the end of the body, for example `Collaborated with Claude Code (Opus 5.5).` Never a
+  `Co-Authored-By:` trailer.
+
+## Commands
+
+```bash
+uv sync --dev
+uv run pytest
+uv run pre-commit run --all-files
+```

insitukit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Long Horizon Observatory
+
+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.

insitukit-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: insitukit
+Version: 0.1.0
+Summary: Fetch, summarise and publish in situ ocean observations: NOAA CO-OPS and ERDDAP clients, record statistics, and a compact JSON time-series format.
+Project-URL: Issues, https://github.com/lhzn-io/insitukit/issues
+Project-URL: Source, https://github.com/lhzn-io/insitukit
+Author-email: Long Horizon Observatory <dfry@lhzn.io>
+License: MIT License
+        
+        Copyright (c) 2026 Long Horizon Observatory
+        
+        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
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.2
+Requires-Dist: requests>=2.32
+Provides-Extra: gcs
+Requires-Dist: google-cloud-storage>=2.18; extra == 'gcs'
+Description-Content-Type: text/markdown
+
+# insitukit
+
+[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Fetch, summarise and publish in situ ocean observations: NOAA CO-OPS and ERDDAP clients, record statistics, and a
+compact JSON time-series format.
+
+forcingkit prepares what drives a coastal model and topobathykit builds the ground it runs on; insitukit handles what
+the instruments in the water actually measured. It reads tide gauges and buoys from NOAA CO-OPS and any ERDDAP server
+with care for the provider: requests are paced, budgeted and identified, and an empty window is an empty result, not
+an error. It reduces long records to the summaries people read: daily means only where a day is at least half
+covered, exceedance curves, joint histograms, and marine heatwave climatologies after Hobday et al. (2016). And it
+writes them as small JSON series behind a guard that refuses unexpected object names or sizes, so a web page can draw
+years of data from a few files.
+
+## Install
+
+```bash
+pip install insitukit            # CO-OPS, ERDDAP, statistics, the JSON form, local and Workers KV storage
+pip install "insitukit[gcs]"     # also Google Cloud Storage
+```
+
+## Use
+
+```python
+from datetime import datetime, timezone
+
+import insitukit
+from insitukit import coops, series, stats
+from insitukit.erddap import Erddap
+
+insitukit.identify("my-site/1.0 (+https://example.org; data@example.org)", application="my-site")
+
+start, end = datetime(2026, 10, 1, tzinfo=timezone.utc), datetime(2026, 11, 1, tzinfo=timezone.utc)
+
+# Observed water level and the station's own predictions; their difference is the surge.
+level = coops.fetch("water_level", "8419870", start, end).set_index("time")["water_level"]
+surge = level - coops.predictions("8419870", start, end).reindex(level.index)
+
+# A buoy's temperature from an ERDDAP server, at most 20 requests this run.
+server = Erddap("https://data.neracoos.org/erddap", budget=20)
+temp = server.fetch("UNH_CML", start, end, ["temperature"]).set_index("time")["temperature"]
+
+daily = stats.day_means(temp, per_day=24, digits=2, tz="America/New_York")
+hourly = series.encode(surge.resample("h").mean(), unit="m", places=3)  # {"t0": ..., "step": 3600, ...}
+```
+
+## Modules
+
+| Module | Contents |
+| :--- | :--- |
+| `insitukit.coops` | `fetch` (observations; long windows split to the API's limits), `predictions` (6-minute tides), `tide_events` (highs and lows), `metadata`. Metric units and UTC throughout. |
+| `insitukit.erddap` | `Erddap(base_url, budget, min_interval)`: tabledap CSV into a DataFrame, with a per-run request budget and an unreachable flag. |
+| `insitukit.stats` | `day_means` (coverage rule), `exceedance`, `joint` (two series paired by nearest time), `climatology` (Hobday et al. 2016: 11-day window, 31-day smoothing, mean, SD, 90th percentile). |
+| `insitukit.series` | `encode` and `decode` for one series, `encode_frame` and `decode_frame` for several on one grid, `iso`. |
+| `insitukit.store` | `Store(root, writable, max_bytes)`: JSON and bytes to a directory, `kv://<account>/<namespace>` (Cloudflare Workers KV, token in `CLOUDFLARE_API_TOKEN`) or `gs://bucket/prefix`, refusing names outside `writable` and objects over `max_bytes`. |
+
+## Etiquette
+
+CO-OPS requests are at least 1 s apart, and 403 and 429 answers are treated as throttling and retried with backoff.
+ERDDAP requests are at least `min_interval` apart and stop at the run's `budget`. Both send the User-Agent given to
+`identify`; include a way for the provider to reach you.
+
+## Reference
+
+Hobday, A. J., et al. (2016). A hierarchical approach to defining marine heatwaves. *Progress in Oceanography*, 141,
+227-238. doi:10.1016/j.pocean.2015.12.014
+
+## License
+
+MIT. Copyright (c) 2026 Long Horizon Observatory.

insitukit-0.1.0/README.md

@@ -0,0 +1,72 @@
+# insitukit
+
+[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Fetch, summarise and publish in situ ocean observations: NOAA CO-OPS and ERDDAP clients, record statistics, and a
+compact JSON time-series format.
+
+forcingkit prepares what drives a coastal model and topobathykit builds the ground it runs on; insitukit handles what
+the instruments in the water actually measured. It reads tide gauges and buoys from NOAA CO-OPS and any ERDDAP server
+with care for the provider: requests are paced, budgeted and identified, and an empty window is an empty result, not
+an error. It reduces long records to the summaries people read: daily means only where a day is at least half
+covered, exceedance curves, joint histograms, and marine heatwave climatologies after Hobday et al. (2016). And it
+writes them as small JSON series behind a guard that refuses unexpected object names or sizes, so a web page can draw
+years of data from a few files.
+
+## Install
+
+```bash
+pip install insitukit            # CO-OPS, ERDDAP, statistics, the JSON form, local and Workers KV storage
+pip install "insitukit[gcs]"     # also Google Cloud Storage
+```
+
+## Use
+
+```python
+from datetime import datetime, timezone
+
+import insitukit
+from insitukit import coops, series, stats
+from insitukit.erddap import Erddap
+
+insitukit.identify("my-site/1.0 (+https://example.org; data@example.org)", application="my-site")
+
+start, end = datetime(2026, 10, 1, tzinfo=timezone.utc), datetime(2026, 11, 1, tzinfo=timezone.utc)
+
+# Observed water level and the station's own predictions; their difference is the surge.
+level = coops.fetch("water_level", "8419870", start, end).set_index("time")["water_level"]
+surge = level - coops.predictions("8419870", start, end).reindex(level.index)
+
+# A buoy's temperature from an ERDDAP server, at most 20 requests this run.
+server = Erddap("https://data.neracoos.org/erddap", budget=20)
+temp = server.fetch("UNH_CML", start, end, ["temperature"]).set_index("time")["temperature"]
+
+daily = stats.day_means(temp, per_day=24, digits=2, tz="America/New_York")
+hourly = series.encode(surge.resample("h").mean(), unit="m", places=3)  # {"t0": ..., "step": 3600, ...}
+```
+
+## Modules
+
+| Module | Contents |
+| :--- | :--- |
+| `insitukit.coops` | `fetch` (observations; long windows split to the API's limits), `predictions` (6-minute tides), `tide_events` (highs and lows), `metadata`. Metric units and UTC throughout. |
+| `insitukit.erddap` | `Erddap(base_url, budget, min_interval)`: tabledap CSV into a DataFrame, with a per-run request budget and an unreachable flag. |
+| `insitukit.stats` | `day_means` (coverage rule), `exceedance`, `joint` (two series paired by nearest time), `climatology` (Hobday et al. 2016: 11-day window, 31-day smoothing, mean, SD, 90th percentile). |
+| `insitukit.series` | `encode` and `decode` for one series, `encode_frame` and `decode_frame` for several on one grid, `iso`. |
+| `insitukit.store` | `Store(root, writable, max_bytes)`: JSON and bytes to a directory, `kv://<account>/<namespace>` (Cloudflare Workers KV, token in `CLOUDFLARE_API_TOKEN`) or `gs://bucket/prefix`, refusing names outside `writable` and objects over `max_bytes`. |
+
+## Etiquette
+
+CO-OPS requests are at least 1 s apart, and 403 and 429 answers are treated as throttling and retried with backoff.
+ERDDAP requests are at least `min_interval` apart and stop at the run's `budget`. Both send the User-Agent given to
+`identify`; include a way for the provider to reach you.
+
+## Reference
+
+Hobday, A. J., et al. (2016). A hierarchical approach to defining marine heatwaves. *Progress in Oceanography*, 141,
+227-238. doi:10.1016/j.pocean.2015.12.014
+
+## License
+
+MIT. Copyright (c) 2026 Long Horizon Observatory.

insitukit-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "insitukit"
+version = "0.1.0"
+description = "Fetch, summarise and publish in situ ocean observations: NOAA CO-OPS and ERDDAP clients, record statistics, and a compact JSON time-series format."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [{ name = "Long Horizon Observatory", email = "dfry@lhzn.io" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Hydrology",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+  "numpy>=1.26",
+  "pandas>=2.2",
+  "requests>=2.32",
+]
+
+[project.optional-dependencies]
+# Store.root of gs://bucket/prefix. Cloudflare Workers KV (kv://) needs only requests.
+gcs = ["google-cloud-storage>=2.18"]
+
+[project.urls]
+Issues = "https://github.com/lhzn-io/insitukit/issues"
+Source = "https://github.com/lhzn-io/insitukit"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/insitukit"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+# The rule set forcingkit pins (pyflakes and the syntax-level pycodestyle rules), chosen explicitly so a ruff
+# upgrade cannot silently change what "clean" means.
+select = ["E4", "E7", "E9", "F"]
+
+[dependency-groups]
+dev = [
+  "pre-commit>=4.5.1",
+  "pytest>=8",
+  "ruff>=0.16.9",
+]

insitukit-0.1.0/src/insitukit/__init__.py

@@ -0,0 +1,24 @@
+"""Fetch, summarise and publish in situ ocean observations.
+
+- ``insitukit.coops``: NOAA CO-OPS (Tides and Currents) observations, tide predictions and station metadata.
+- ``insitukit.erddap``: a paced, budgeted ERDDAP tabledap client for any server.
+- ``insitukit.stats``: daily means with a coverage rule, exceedance, joint histograms, marine heatwave climatology.
+- ``insitukit.series``: the compact JSON form of a regular time series, and back.
+- ``insitukit.store``: where the JSON goes (a directory, Cloudflare Workers KV or Google Cloud Storage), behind a
+  guard on object names and sizes.
+
+Call ``identify`` once at start-up so every request names your application and a contact.
+"""
+
+__version__ = "0.1.0"
+
+
+def identify(user_agent: str, application: str | None = None) -> None:
+    """Name the caller on every request: ``user_agent`` as the HTTP User-Agent (include a URL or an address a data
+    provider can reach you at), and ``application`` as CO-OPS's ``application`` parameter (default: unchanged)."""
+    from . import coops
+
+    coops.USER_AGENT = user_agent
+    coops._session.headers["User-Agent"] = user_agent
+    if application is not None:
+        coops.APPLICATION = application

insitukit-0.1.0/src/insitukit/coops.py

@@ -0,0 +1,198 @@
+"""Fetch observations and tide predictions from the NOAA CO-OPS data API (Tides and Currents).
+
+Every request asks for metric units and GMT; converting to other units is the caller's. The API answers HTTP 200 with an ``{"error": ...}`` body for a bad request, and "No data
+was found" when a station lacks the sensor or the window falls in a gap: that is an empty result,
+not a failure. Server errors and timeouts retry with backoff.
+
+Per-request range limits (checked against the live API, 2026-10):
+
+- 6-minute observations (``water_temperature``, ``air_temperature``, ``wind``, ``air_pressure``,
+  ``water_level``): 31 days. We ask for 30-day spans.
+- the same products with ``interval=h`` (the reading at the top of each hour), and ``hourly_height``:
+  365 days, compared by calendar date, so one calendar year (including a leap year) fits one request.
+
+Requests carry ``USER_AGENT`` and ``APPLICATION``; set your own with ``insitukit.identify``.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from datetime import datetime, timedelta, timezone
+
+import numpy as np
+import pandas as pd
+import requests
+
+from . import __version__
+
+BASE_URL = "https://api.tidesandcurrents.noaa.gov/api/prod/datagetter"
+META_URL = "https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi/stations/{station}.json"
+USER_AGENT = f"insitukit/{__version__} (+https://github.com/lhzn-io/insitukit)"
+APPLICATION = "insitukit"
+SIX_MINUTE_SPAN = timedelta(days=30)
+# Value fields per product, renamed to the column names returned by fetch().
+FIELDS = {
+    "wind": {"s": "wind_speed", "d": "wind_direction", "g": "wind_gust"},
+}
+DATUM_PRODUCTS = {"water_level", "hourly_height", "high_low", "predictions"}
+
+# The API sits behind a gateway that answers 403 "Forbidden" (not 429) once a client sends too many
+# requests in a short period; a burst of about 300 requests in 10 minutes was enough. We pace every
+# request and treat 403 and 429 as throttling, retried with backoff like a server error.
+MIN_INTERVAL = 1.0
+THROTTLED = {403, 429}
+
+log = logging.getLogger(__name__)
+_session = requests.Session()
+_session.headers["User-Agent"] = USER_AGENT
+_last_request = 0.0
+# Requests sent since import (or since the caller reset it); used for logging and cost checks.
+request_count = 0
+
+
+class CoopsError(RuntimeError):
+    """The API rejected the request (bad station, product or date range)."""
+
+
+def _pace() -> None:
+    """Keep at least MIN_INTERVAL seconds between requests."""
+    global _last_request
+    wait = _last_request + MIN_INTERVAL - time.monotonic()
+    if wait > 0:
+        time.sleep(wait)
+    _last_request = time.monotonic()
+
+
+def _get(params: dict, retries: int = 4, timeout: int = 120) -> dict | None:
+    """GET the data API with retries; return None when the API reports no data for the window."""
+    global request_count
+    query = {"units": "metric", "time_zone": "gmt", "format": "json", "application": APPLICATION, **params}
+    delay = 5.0
+    for attempt in range(1, retries + 1):
+        request_count += 1
+        _pace()
+        try:
+            resp = _session.get(BASE_URL, params=query, timeout=timeout)
+        except requests.RequestException as exc:
+            log.warning("request failed (%s), attempt %d: %s", exc.__class__.__name__, attempt, params)
+        else:
+            if resp.status_code == 200:
+                body = resp.json()
+                err = (body.get("error") or {}).get("message") if isinstance(body, dict) else None
+                if err is None:
+                    return body
+                if "no data was found" in err.lower():
+                    return None
+                raise CoopsError(f"{err.strip()} ({params})")
+            if resp.status_code < 500 and resp.status_code not in THROTTLED:
+                raise CoopsError(f"HTTP {resp.status_code} ({params})")
+            log.warning("HTTP %d, attempt %d: %s", resp.status_code, attempt, params)
+        if attempt < retries:
+            time.sleep(delay)
+            delay *= 2
+    raise RuntimeError(f"giving up after {retries} attempts: {params}")
+
+
+def _stamp(ts: datetime) -> str:
+    return ts.astimezone(timezone.utc).strftime("%Y%m%d %H:%M")
+
+
+def spans(start: datetime, end: datetime, hourly: bool) -> list[tuple[datetime, datetime]]:
+    """Request windows covering ``[start, end)``: calendar years for hourly data, 30 days otherwise."""
+    out = []
+    lo = start
+    while lo < end:
+        if hourly:
+            hi = min(datetime(lo.year + 1, 1, 1, tzinfo=timezone.utc), end)
+        else:
+            hi = min(lo + SIX_MINUTE_SPAN, end)
+        out.append((lo, hi))
+        lo = hi
+    return out
+
+
+def fetch(
+    product: str,
+    station: str,
+    start: datetime,
+    end: datetime,
+    interval: str | None = None,
+    datum: str = "MLLW",
+) -> pd.DataFrame:
+    """Observations for ``start <= time < end`` with a UTC ``time`` column and float value columns.
+
+    Single-value products return one column named after the product; ``wind`` returns
+    ``wind_speed`` (m/s), ``wind_direction`` (degrees true) and ``wind_gust`` (m/s). Readings the
+    API flags as missing come back as NaN. Long windows are split to respect the range limits.
+    """
+    fields = FIELDS.get(product, {"v": product})
+    hourly = interval == "h" or product == "hourly_height"
+    frames = []
+    for lo, hi in spans(start, end, hourly):
+        # The API's end_date is inclusive; stop one minute short so adjacent spans do not overlap.
+        params = {"product": product, "station": station, "begin_date": _stamp(lo), "end_date": _stamp(hi - timedelta(minutes=1))}
+        if interval:
+            params["interval"] = interval
+        if product in DATUM_PRODUCTS:
+            params["datum"] = datum
+        body = _get(params)
+        rows = (body or {}).get("data") or []
+        log.info("%s %s %s..%s: %d rows", station, product, params["begin_date"], params["end_date"], len(rows))
+        if rows:
+            frames.append(pd.DataFrame(rows))
+    cols = ["time", *fields.values()]
+    if not frames:
+        return pd.DataFrame({c: pd.Series(dtype="datetime64[ns, UTC]" if c == "time" else float) for c in cols})
+    raw = pd.concat(frames, ignore_index=True)
+    df = pd.DataFrame({"time": pd.to_datetime(raw["t"], utc=True)})
+    for key, name in fields.items():
+        df[name] = pd.to_numeric(raw[key], errors="coerce") if key in raw.columns else np.nan
+    df = df[(df["time"] >= pd.Timestamp(start)) & (df["time"] < pd.Timestamp(end))]
+    return df.sort_values("time").drop_duplicates("time").reset_index(drop=True)
+
+
+def tide_events(station: str, start: datetime, end: datetime, datum: str = "MLLW") -> list[dict]:
+    """High and low tide predictions in ``[start, end)``: ``[{"time": Timestamp, "m": float, "type": "H"|"L"}]``."""
+    params = {
+        "product": "predictions",
+        "station": station,
+        "begin_date": _stamp(start),
+        "end_date": _stamp(end - timedelta(minutes=1)),
+        "interval": "hilo",
+        "datum": datum,
+    }
+    body = _get(params) or {}
+    out = []
+    for row in body.get("predictions") or []:
+        try:
+            out.append({"time": pd.Timestamp(row["t"], tz="UTC"), "m": float(row["v"]), "type": row["type"]})
+        except (KeyError, TypeError, ValueError):
+            continue
+    return out
+
+
+def predictions(station: str, start: datetime, end: datetime, datum: str = "MLLW") -> pd.Series:
+    """6-minute tide predictions (m above ``datum``) in ``[start, end)``, indexed by UTC time. A station's own
+    predictions taken from its observed water level give the surge without the phase shift of a nearby station's."""
+    vals: dict[pd.Timestamp, float] = {}
+    for lo, hi in spans(start, end, hourly=False):
+        body = _get({"product": "predictions", "station": station, "datum": datum, "interval": "6",
+                     "begin_date": _stamp(lo), "end_date": _stamp(hi - timedelta(minutes=1))}) or {}
+        for row in body.get("predictions") or []:
+            try:
+                vals[pd.Timestamp(row["t"], tz="UTC")] = float(row["v"])
+            except (KeyError, TypeError, ValueError):
+                continue
+    s = pd.Series(vals, dtype=float).sort_index()
+    return s[(s.index >= pd.Timestamp(start)) & (s.index < pd.Timestamp(end))]
+
+
+def metadata(station: str) -> dict:
+    """Station metadata with details and sensors (name, lat, lng, established, sensor list)."""
+    global request_count
+    request_count += 1
+    _pace()
+    resp = _session.get(META_URL.format(station=station), params={"expand": "details,sensors"}, timeout=60)
+    resp.raise_for_status()
+    return resp.json()["stations"][0]