weatherfeeder/docs/consumers/api.md

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:

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.SchemaWeatherOutlookV2:
		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.
• Public constants package: pkg-standards.md.
• JSON event wire contract: ../integrations/events.md.
• Postgres table contract: ../integrations/postgres.md.
• Runtime and adapter architecture: ../policy/architecture.md.