Error reporting — `See()`

The Go SDK ships a structured error-reporting surface, See(), mirroring @shipeasy/sdk's see(). Every handled error documents its product consequence, not just its stack. Reports are fire-and-forget POSTs to /collect (type:"error") — they never block or panic into the request path.

Rule of thumb: if you don't know the consequence of an error, don't handle it here.

Reporting a handled error

The chain is See(problem).CausesThe(subject).Extras(map).To(outcome). The terminal .To(outcome) builds the event and sends it; CausesThe and Extras are chainable setters callable in any order before .To. A chain that never calls .To sends nothing.

if err := chargeCard(order); err != nil {
    shipeasy.See(err).
        CausesThe("checkout").
        Extras(map[string]any{"order_id": order.ID}).
        To("use the backup processor")
}

See is package-level — it reports against the configuration from Configure, so there is no client to thread through. Before Configure has run it logs a warning and returns a no-op chain — it never panics.

Violations (non-exception problems)

A Violation is a problem with no Go error value. The name is a stable fingerprint — put variable data in .Extras(), never the name:

shipeasy.SeeViolation("cart_total_negative").
    Extras(map[string]any{"cart_id": cart.ID}).
    To("clamp to zero")

Expected control flow — reports NOTHING

Mark an error as deliberate control flow so it is not reported. It only stamps the error value (and optional local-only debug extras):

if errors.Is(err, sql.ErrNoRows) {
    shipeasy.ControlFlowException(err).
        Because("because a missing row is the empty-state path").
        Extras(map[string]any{"key": key}) // local only — never transmitted
}

shipeasy.IsExpected(err) reports whether an error was marked this way (handy in tests/assertions).

Limits & safety

• Per-process spam guard: identical events within a 30s window collapse to one send; a hard cap (25/process) bounds total sends.
• Extras are sanitized: only string / finite-number / bool values, string values truncated to 200 chars, capped at 20 keys; PrivateAttributes keys are stripped.
• No-op on test/offline clients (local mode).