feat(httpclient): initial stable release v0.9.0

Resilient HTTP client with circuit breaking, exponential-backoff retry, X-Request-ID propagation, and a generic typed JSON helper.

What's included:
- Client interface with Do(req) method; New(logger, cfg) and NewWithDefaults(logger) constructors
- Config struct with env-tag support for timeout, dial timeout, retry, and circuit breaker parameters
- Retry via avast/retry-go/v4 with BackOffDelay; triggers only on network errors and HTTP 5xx
- Circuit breaker via sony/gobreaker wrapping the full retry loop; open circuit → xerrors.ErrUnavailable
- X-Request-ID header propagated automatically from context via logz.GetRequestID on every attempt
- DoJSON[T](ctx, client, req) generic helper for typed JSON request/response with xerrors error mapping
- MapStatusToError(code, msg) exported function mapping HTTP status codes to xerrors types

Tested-via: todo-api POC integration
Reviewed-against: docs/adr/

helpers.go

@@ -0,0 +1,57 @@
+package httpclient
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+
+	"code.nochebuena.dev/go/xerrors"
+)
+
+// DoJSON executes req and decodes the JSON response body into T.
+// Returns a xerrors-typed error for HTTP 4xx/5xx responses.
+func DoJSON[T any](ctx context.Context, client Client, req *http.Request) (*T, error) {
+	req = req.WithContext(ctx)
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode >= 400 {
+		return nil, MapStatusToError(resp.StatusCode, "external API error")
+	}
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, xerrors.New(xerrors.ErrInternal, "failed to read response body").WithError(err)
+	}
+
+	var data T
+	if err := json.Unmarshal(body, &data); err != nil {
+		return nil, xerrors.New(xerrors.ErrInternal, "failed to decode JSON response").WithError(err)
+	}
+
+	return &data, nil
+}
+
+// MapStatusToError maps an HTTP status code to the matching xerrors type.
+func MapStatusToError(code int, msg string) error {
+	switch code {
+	case http.StatusNotFound:
+		return xerrors.New(xerrors.ErrNotFound, msg)
+	case http.StatusBadRequest:
+		return xerrors.New(xerrors.ErrInvalidInput, msg)
+	case http.StatusUnauthorized:
+		return xerrors.New(xerrors.ErrUnauthorized, msg)
+	case http.StatusForbidden:
+		return xerrors.New(xerrors.ErrPermissionDenied, msg)
+	case http.StatusConflict:
+		return xerrors.New(xerrors.ErrAlreadyExists, msg)
+	case http.StatusTooManyRequests:
+		return xerrors.New(xerrors.ErrUnavailable, msg)
+	default:
+		return xerrors.New(xerrors.ErrInternal, msg)
+	}
+}