Error reporting — `see()`

This SDK ships the see() error-reporting surface (parity with the TS SDK). Use it to report a handled throwable (or a non-exception "violation") to Shipeasy as fire-and-forget telemetry, while you keep your normal control flow.

Shipeasy\see() is package-level — it reports against the SDK from Shipeasy\configure(). It NEVER throws: before configure() runs it logs a warning and returns a no-op chain. Assumes Shipeasy\configure() ran at startup — see Installation.

Report a caught throwable

use function Shipeasy\see;

try {
    chargeCard($order);
} catch (\Throwable $e) {
    see($e)
        ->causesThe('checkout')        // the subject — what the error affected (default: 'app')
        ->extras(['order_id' => $id])  // local debug context (never transmitted)
        ->to('failed to charge');      // terminal: the consequence (default: 'hit an error')

    return back()->withError('Payment failed');
}

The chain is see($problem)->causesThe($subject)->extras($extras)->to($outcome):

• causesThe(string $subject) — what the error affected (default 'app').
• extras(array $extras) — debug context stored locally only, never sent.
• to(string $outcome) — terminal; builds the event and fire-and-forgets the report. Idempotent (a second to() is a no-op). The default outcome is 'hit an error'. causesThe() and extras() are chainable in any order before to().

Report a non-exception violation

use function Shipeasy\seeViolation;

seeViolation('cart_total_mismatch')   // the name is a STABLE fingerprint — keep variable data in extras
    ->causesThe('checkout')
    ->to('blocked the order');

seeViolation($name) wraps the name in a Shipeasy\Violation and reports it the same way.

Mark expected control flow (report nothing)

When a throwable is expected control flow and should NOT be reported, stamp it so any enclosing see() ignores it. This works even before configure() runs — it only stamps the throwable:

use function Shipeasy\controlFlowException;

try {
    return $cache->getOrThrow($key);
} catch (\Throwable $e) {
    controlFlowException($e)
        ->because('cache miss is normal')
        ->extras(['key' => $key]);   // local-only debug; never sent
    return rebuild($key);
}

controlFlowException($e)->because($reason) returns a tail with ->extras(...).

Notes

• Reporting is best-effort and must never raise into caller code — every terminal is wrapped in try/catch.
• see() is server-key telemetry: it travels over the configured transport, no extra setup.