Skip to content

v11.3.0

Latest

Choose a tag to compare

@github-actions github-actions released this 24 Aug 11:12
KoolbaseError: one canonical error type across the whole SDK

Catch anything, call KoolbaseError.from(e), branch on code. The 44 typed
exceptions are unchanged; this sits above them so an app can branch on what a
failure MEANS without knowing the SDK's internal taxonomy.

Found by measuring: across 14,732 lines, four places in the entire SDK catch a
transport failure. A database read that loses connection has been throwing a
raw SocketException straight through to the caller — on a phone with patchy
signal, the most common failure there is, and the one with no typed home.

Normalization is total: an unmapped server code, a bare string, an integer all
become a KoolbaseError rather than escaping. This runs in error paths, where a
second failure has nowhere to go.

Eleven codes. The bar for adding one is that an application could reasonably do
something DIFFERENT because of it — rateLimited because waiting is not
retrying, contactNotVerified because it routes to "resend verification" not
"check your password". retryable is derived from code, never stored, so the two
cannot disagree. details carries structured context through rather than
flattening it, including the server's current record on a revision mismatch.

message is developer diagnostic data and must never reach an end user. Written
into the doc comment, not just the changelog.

Also fixes the README's first auth example, which called a method that does not
exist (Koolbase.auth.register). signUp appeared nowhere in 1382 lines, so the
front page had no correct path to creating a user — including no mention of
SignUpResult.verificationRequired, where the account exists but no session was
issued.

Additive only. Nothing throws differently, no signature moved.