Error reporting — `see()`

This SDK has see() — a structured error-reporting surface: every handled exception documents its product consequence, not just its stack. The report is a fire-and-forget POST; it never blocks or raises into the request path. It is package-level — it reports against the engine you set up with Shipeasy.configure, so there is no object to construct or pass around.

If you don't know the consequence of an exception, don't catch it.

Report a caught exception

Shipeasy.see(problem) returns a chain. Set the consequence with causes_the(subject) and terminate with .to(outcome) — .to builds the wire event and fires once:

begin
  charge_card(order)
rescue => e
  Shipeasy.see(e).causes_the("checkout").to("use the backup processor")
end

causes_the and extras are chainable setters callable in any order before .to:

Shipeasy.see(e)
  .causes_the("checkout")
  .extras({ order_id: oid })
  .to("use cached prices")

Violations (non-exception problems)

A Violation's name is a stable fingerprint — put variable data in .extras, never in the name:

Shipeasy.see_violation("inventory_negative").extras({ sku: sku }).to("clamp to zero")

Expected control flow (report nothing)

Mark an exception as expected control flow — this reports nothing; .extras is local-debug only:

Shipeasy.control_flow_exception(e).because("user cancelled").extras({ id: id })

Guarantees

• Fire-and-forget; never raises into caller code.
• Spam-guarded: identical events within 30s collapse to one send, with a hard per-process cap (the worker dedupes by fingerprint anyway).
• No-op in test/offline mode (configure_for_testing / configure_for_offline never send). A see() before any client exists warns and no-ops — it never raises.
• extras are sanitized (string/numeric/boolean only, truncated, ≤20 keys) and respect the configured private-attribute list.