weatherreporter/docs/internal/collect.md

# Collection Internals

`internal/collect` is the small application-facing boundary that obtains one
normalized Weather API bundle. The external HTTP contract belongs in the
[Weather API integration guide](../integrations/weatherapi.md); normalized
source values belong in [weather-data internals](weather-data.md).

## Contract

`Run` receives a context and effective configuration in `Request`. It creates
the Weather API adapter, calls `FetchBundle`, and returns the adapter's
normalized bundle in `Result`. Adapter construction errors are wrapped as
weather-collection setup errors and fetch errors as bundle-collection errors.

The package neither chooses reports nor derives facts, builds modules, invokes
Promptkit, writes files, or sends notifications. Request scheduling, endpoint
retrieval, response limits, and source-level warnings belong to the Weather
API adapter and its integration contract.

## Application Use

`internal/app` owns the `Collector` interface used by report workflows and
tests. Its default implementation delegates to `collect.Run`; callers may
substitute a collector at that boundary. Application orchestration owns
collection timing, reuse across a workflow, and the handling of nil collection
results. See [app orchestration internals](app-orchestration.md) for that
flow.

## Verification

Focused package tests cover a successful fetch and wrapping failures from
adapter construction and bundle retrieval:

```sh
go test ./internal/collect
```