# Consumer API Guide

## Purpose

This guide is for developers and LLM coding agents integrating `weatherfeeder`
from another Go codebase.

`weatherfeeder` is primarily a daemon, not an SDK. Its public integration
surface is intentionally narrow:

- `model`: canonical weather payload structs.
- `standards`: schema strings, event kind strings, and shared WMO constants.
- JSON event output from stdout and NATS sinks.
- Postgres tables written by the optional Postgres sink.

Packages under `internal/` are implementation details and are not public
integration surfaces.

## Recommended Workflow

Consumers should switch on the event `schema` value and decode `payload` into
the matching `model` type.

Minimal example:

```go
package consumer

import (
	"encoding/json"
	"fmt"

	"gitea.maximumdirect.net/ejr/weatherfeeder/model"
	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
)

type Event struct {
	ID      string          `json:"id"`
	Kind    string          `json:"kind"`
	Schema  string          `json:"schema"`
	Payload json.RawMessage `json:"payload"`
}

func Decode(payload []byte) (any, error) {
	var evt Event
	if err := json.Unmarshal(payload, &evt); err != nil {
		return nil, err
	}

	switch evt.Schema {
	case standards.SchemaWeatherObservationV1:
		var out model.WeatherObservation
		return &out, json.Unmarshal(evt.Payload, &out)
	case standards.SchemaWeatherForecastV1:
		var out model.WeatherForecastRun
		return &out, json.Unmarshal(evt.Payload, &out)
	case standards.SchemaWeatherForecastDiscussionV1:
		var out model.WeatherForecastDiscussion
		return &out, json.Unmarshal(evt.Payload, &out)
	case standards.SchemaWeatherStoryV1:
		var out model.WeatherStoryRun
		return &out, json.Unmarshal(evt.Payload, &out)
	case standards.SchemaWeatherAlertV1:
		var out model.WeatherAlertRun
		return &out, json.Unmarshal(evt.Payload, &out)
	case standards.SchemaWeatherOutlookV1:
		var out model.WeatherOutlookRun
		return &out, json.Unmarshal(evt.Payload, &out)
	default:
		return nil, fmt.Errorf("unsupported weatherfeeder schema %q", evt.Schema)
	}
}
```

## Consumer Responsibilities

- Treat event IDs as opaque.
- Treat absent `omitempty` fields as unknown, not zero.
- Prefer schema constants from `standards` over string literals in Go code.
- Expect canonical numeric measurements to use metric units.
- Expect canonical timestamps from normalizers to be UTC unless a field-specific
  contract says otherwise.
- Handle additive fields within the same schema version.
- Do not import `internal/...` packages.

## Canonical References

- Public payload package: [`pkg-model.md`](pkg-model.md).
- Public constants package: [`pkg-standards.md`](pkg-standards.md).
- JSON event wire contract: [`../integrations/events.md`](../integrations/events.md).
- Postgres table contract: [`../integrations/postgres.md`](../integrations/postgres.md).
- Runtime and adapter architecture: [`../policy/architecture.md`](../policy/architecture.md).