api-client

Skill: api-client — canonical Go API client pattern

Use when implementing ANY HTTP/API client, connection pool, streaming consumer, or client-side data transform in Go. Mandatory before writing such code (AGENTS.md, code standard #4).

First-class example: https://github.com/eSlider/go-ollama (client.go). Typed CRUD reference: go-onlyoffice tasks.go (CreateProjectTask, UpdateProjectTask, GetTasks).

go-onlyoffice split (AGENTS.md, #81): primitives live in the lib — one typed client method per OO API call (CreatePerson, AddHistoryNote, BuildContactEmailIndex, …). Flows (reconcile, interaction import) live in 2dph bin/onlyoffice/* and only orchestrate those primitives. Never inline raw OO calls in 2dph; add the capability in go-onlyoffice first.

Shape (mandatory)

1. type Client struct { hc *http.Client; cfg Config } — one handle; state concurrency expectations in the doc comment.
2. Typed Config/DSN struct (URL, token, timeouts) resolved from the go-config stack (etc/brain/config.yml → local → .env → env). Never hardcoded URLs/tokens; nil-safe constructor New(cfg *Config) *Client.
3. One transport core on receiver:
   • doJSON(ctx, method, path, body, dest): sets headers/auth, non-2xx → wrapped error incl. body snippet, decodes into typed dest;
   • doStream(ctx, …): NDJSON/SSE variant with onItem func(T) error. Public methods stay thin: func (c *Client) X(ctx context.Context, req XRequest) (*XResponse, error).
4. Per endpoint: {Name}Request / {Name}Response structs. Optional fields = pointers + omitempty; wire quirks get custom MarshalJSON. No map[string]any in or out; platform payloads convert at the boundary via mapstructure/v2 (WeakDecode pattern).
5. Errors: fmt.Errorf("context: %w", err); typed sentinel errors where callers branch.

Concurrency (hard rules)

• Public API synchronous; channels internal only, never in signatures.
• ctx first param everywhere; every send/receive selects on <-ctx.Done(); workers exit on cancel — zero leaked or stuck goroutines (wg-accounted).
• Bounded parallelism: worker pool caps in-flight calls (rate limiting).
• Sender closes channels. Errors ride inside Result{val, err} or return synchronously — never ignored.
• Fan-out/fan-in to merge multi-source fetches; errgroup.WithContext when first-error-cancel fits.