Error reporting — `see()`

The Kotlin SDK ships the see() structured-error surface (parity with @shipeasy/sdk and the Python reference). It reports a handled error along with its product consequence — not just a stack trace — fire-and-forget to /collect. Reporting never blocks and never throws into your request path.

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

Package-level see()

see() reports against the SDK configured by configure() — no object to pass:

import ai.shipeasy.see

try {
    chargeCard(order)
} catch (e: Exception) {
    see(e)
        .causesThe("checkout")
        .extras(mapOf("order_id" to order.id))
        .to("use the backup processor")
}

The chain:

• causesThe(subject) — names the thing affected (the consequence subject).
• extras(map) — structured context (String / finite Number / Boolean only; truncated, capped at 20 keys).
• to(outcome) — terminal: builds the wire event and fires the report. If you never call to(), nothing is sent. Calling to() twice is a no-op.

causesThe() and extras() may be called in any order before to().

Non-exception problems — seeViolation

The name is a stable fingerprint key — put variable data in extras(), never in the name:

import ai.shipeasy.seeViolation

seeViolation("negative_inventory")
    .extras(mapOf("sku" to sku))
    .to("clamp to zero")

Expected control flow — controlFlowException

Mark an exception as expected control flow; it reports nothing. .extras() is stored for local debugging only.

import ai.shipeasy.controlFlowException

controlFlowException(e).because("retryable timeout — handled by the retry loop")

Notes

• A per-process spam guard collapses identical reports within a 30s window and caps total sends per process.
• Configured privateAttributes are stripped from extras().
• env (from configure()) is tagged onto every event.
• Calling see() before configure() ran logs a warning and is a no-op.