feat(intid): add _check variants for Crockford Base32 and Base58Check (#76)

* feat(intid): add _check variants for Crockford Base32 and Base58Check

* test(intid): scope Base58Check round-trips to Erlang target

Author: nao1215

CHANGELOG.md

@@ -8,6 +8,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 ## [Unreleased]
 
 ### Added
+- **`yabase/intid` gains checksum-bearing `_check` variants** for the
+  Crockford Base32 and Base58Check codecs, removing the
+  `Int → BitArray → encode_check / decode_check → BitArray → Int`
+  dance every caller previously reimplemented. New helpers:
+  `encode_int_base32_crockford_check`,
+  `decode_int_base32_crockford_check[_bounded]`,
+  `encode_int_base58check`,
+  `decode_int_base58check[_bounded]`. The decoders surface
+  `Error(InvalidChecksum)` on a mistyped input — the whole reason
+  callers reach for the checksummed variant. Base58Check is fixed at
+  version byte `0` (Bitcoin mainnet P2PKH); callers who need a
+  different version still drop to `yabase/base58check` directly. (#73)
 - **`yabase/intid` and the top-level `yabase` module now re-export
   `CodecError`** as a public type alias, so callers who only
   `import yabase/intid` (or only `import yabase`) can type-annotate a

src/yabase/intid.gleam

@@ -54,6 +54,7 @@ import yabase/base32/rfc4648 as base32_rfc4648
 import yabase/base36
 import yabase/base58/bitcoin as base58_bitcoin
 import yabase/base58/flickr as base58_flickr
+import yabase/base58check
 import yabase/base62
 import yabase/core/error.{
   type CodecError as CoreCodecError, InvalidLength, Overflow,
@@ -193,6 +194,84 @@ pub fn decode_int_base58_flickr_bounded(
   bound_check(value, max)
 }
 
+/// Encode a non-negative `Int` as a Crockford Base32 string with a
+/// trailing checksum symbol (Douglas Crockford's optional check
+/// character).
+///
+/// Issue #73: same shape as `encode_int_base32_crockford` but with
+/// the typo-resistance guard the underlying codec already supports.
+/// Use the matching `decode_int_base32_crockford_check` to recover
+/// the integer; the decoder verifies the symbol and returns
+/// `Error(InvalidChecksum)` if the input was mistyped.
+pub fn encode_int_base32_crockford_check(value: Int) -> String {
+  base32_crockford.encode_check(int_to_bytes_be(value))
+}
+
+/// Decode a checksummed Crockford Base32 string back to an `Int`,
+/// verifying the trailing check symbol.
+pub fn decode_int_base32_crockford_check(
+  input: String,
+) -> Result(Int, CodecError) {
+  use input <- result.try(reject_empty(input))
+  base32_crockford.decode_check(input)
+  |> result.map(bytes_to_int)
+}
+
+/// Decode a checksummed Crockford Base32 string back to an `Int`,
+/// rejecting values greater than `max` with `Error(Overflow)`.
+pub fn decode_int_base32_crockford_check_bounded(
+  input input: String,
+  max max: Int,
+) -> Result(Int, CodecError) {
+  use value <- result.try(decode_int_base32_crockford_check(input))
+  bound_check(value, max)
+}
+
+/// Encode a non-negative `Int` as a Base58Check string (Bitcoin's
+/// double-SHA-256 checksum format).
+///
+/// Issue #73: this is the int-typed counterpart of
+/// `yabase/base58check.encode/2`. Version is fixed at `0`
+/// (Bitcoin mainnet P2PKH) — callers that need a different version
+/// should reach for `yabase/base58check.encode/2` directly with their
+/// own `BitArray` payload.
+///
+/// Returns the canonical Base58Check string. The underlying
+/// `yabase/base58check.encode` only errors on out-of-range version
+/// bytes (this helper hard-codes a valid one), so this signature
+/// does not surface a `Result`.
+pub fn encode_int_base58check(value: Int) -> String {
+  base58check.encode(0, int_to_bytes_be(value))
+  |> result.unwrap("")
+}
+
+/// Decode a Base58Check string back to an `Int`, verifying the
+/// 4-byte SHA-256 checksum.
+///
+/// Issue #73: returns the *payload* as an `Int`, ignoring the version
+/// byte (which `encode_int_base58check` always sets to `0`).
+/// Callers that need to inspect the version byte should reach for
+/// `yabase/base58check.decode/1` directly.
+pub fn decode_int_base58check(input: String) -> Result(Int, CodecError) {
+  use input <- result.try(reject_empty(input))
+  case base58check.decode(input) {
+    Error(e) -> Error(e)
+    Ok(decoded) -> Ok(bytes_to_int(decoded.payload))
+  }
+}
+
+/// Decode a Base58Check string back to an `Int`, rejecting payload
+/// values greater than `max` with `Error(Overflow)`. The checksum is
+/// verified before the bounds check, so a corrupted input fails as
+/// `InvalidChecksum` rather than `Overflow`.
+pub fn decode_int_base58check_bounded(
+  input input: String,
+  max max: Int,
+) -> Result(Int, CodecError) {
+  use value <- result.try(decode_int_base58check(input))
+  bound_check(value, max)
+}
+
 /// Encode a non-negative `Int` as a Base62 string.
 pub fn encode_int_base62(value: Int) -> String {
   base62.encode(int_to_bytes_be(value))

test/intid_test.gleam

@@ -1,4 +1,7 @@
-import yabase/core/error.{InvalidCharacter, InvalidLength, Overflow}
+import gleam/string
+import yabase/core/error.{
+  InvalidCharacter, InvalidChecksum, InvalidLength, Overflow,
+}
 import yabase/intid
 
 // === Base32 (RFC 4648) ===
@@ -359,6 +362,133 @@ pub fn decode_int_base32_crockford_bounded_above_cap_test() -> Nil {
     == Error(Overflow)
 }
 
+// === Issue #73: Crockford Base32 with check symbol ===
+
+pub fn encode_int_base32_crockford_check_zero_test() -> Nil {
+  // 0 encoded as Crockford "0" then check digit for 0 mod 37 == "0".
+  assert intid.encode_int_base32_crockford_check(0) == "00"
+}
+
+pub fn decode_int_base32_crockford_check_roundtrip_test() -> Nil {
+  let encoded = intid.encode_int_base32_crockford_check(987_654)
+  assert intid.decode_int_base32_crockford_check(encoded) == Ok(987_654)
+}
+
+pub fn decode_int_base32_crockford_check_empty_test() -> Nil {
+  assert intid.decode_int_base32_crockford_check("") == Error(InvalidLength(0))
+}
+
+pub fn decode_int_base32_crockford_check_detects_typo_test() -> Nil {
+  // Take a valid checksummed encoding and mutate one body character.
+  // The decoder must reject the typo via InvalidChecksum, which is the
+  // whole reason callers reach for the `_check` variant.
+  let encoded = intid.encode_int_base32_crockford_check(123_456)
+  let body = string_drop_last(encoded)
+  let check = string_take_last(encoded)
+  let mutated = mutate_first_body_char(body) <> check
+  assert intid.decode_int_base32_crockford_check(mutated)
+    == Error(InvalidChecksum)
+}
+
+pub fn decode_int_base32_crockford_check_bounded_within_test() -> Nil {
+  let encoded = intid.encode_int_base32_crockford_check(42)
+  assert intid.decode_int_base32_crockford_check_bounded(
+      input: encoded,
+      max: intid.int64_max,
+    )
+    == Ok(42)
+}
+
+@target(erlang)
+pub fn decode_int_base32_crockford_check_bounded_above_cap_test() -> Nil {
+  let encoded = intid.encode_int_base32_crockford_check(intid.int64_max + 1)
+  assert intid.decode_int_base32_crockford_check_bounded(
+      input: encoded,
+      max: intid.int64_max,
+    )
+    == Error(Overflow)
+}
+
+// === Issue #73: Base58Check ===
+//
+// The Base58Check round-trip tests below are `@target(erlang)` because
+// `yabase/base58check`'s round-trip is itself only exercised on Erlang
+// in this repo (see `test/base58check_test.gleam`); the JS-side
+// SHA-256 divergence is pre-existing scope and tracked separately. The
+// `decode_int_base58check_empty_test` runs on both targets because
+// empty-input rejection short-circuits before any hashing.
+
+@target(erlang)
+pub fn encode_int_base58check_zero_roundtrips_test() -> Nil {
+  let encoded = intid.encode_int_base58check(0)
+  assert intid.decode_int_base58check(encoded) == Ok(0)
+}
+
+@target(erlang)
+pub fn decode_int_base58check_roundtrip_test() -> Nil {
+  let encoded = intid.encode_int_base58check(9_999_999_999)
+  assert intid.decode_int_base58check(encoded) == Ok(9_999_999_999)
+}
+
+pub fn decode_int_base58check_empty_test() -> Nil {
+  assert intid.decode_int_base58check("") == Error(InvalidLength(0))
+}
+
+@target(erlang)
+pub fn decode_int_base58check_detects_typo_test() -> Nil {
+  // Mutate the first checksum-bearing position. Base58Check's 4-byte
+  // SHA-256 suffix means this *must* fail — that is the property the
+  // helper exists to guarantee for callers.
+  let encoded = intid.encode_int_base58check(424_242)
+  let mutated = mutate_first_body_char(encoded)
+  assert intid.decode_int_base58check(mutated) == Error(InvalidChecksum)
+}
+
+@target(erlang)
+pub fn decode_int_base58check_bounded_within_test() -> Nil {
+  let encoded = intid.encode_int_base58check(1234)
+  assert intid.decode_int_base58check_bounded(
+      input: encoded,
+      max: intid.int64_max,
+    )
+    == Ok(1234)
+}
+
+@target(erlang)
+pub fn decode_int_base58check_bounded_above_cap_test() -> Nil {
+  let encoded = intid.encode_int_base58check(intid.int64_max + 1)
+  assert intid.decode_int_base58check_bounded(
+      input: encoded,
+      max: intid.int64_max,
+    )
+    == Error(Overflow)
+}
+
+// Helpers for the typo-detection tests above. Kept in the test module so
+// the production API stays focused on Int↔string.
+fn string_drop_last(s: String) -> String {
+  let len = string.length(s)
+  string.slice(s, 0, len - 1)
+}
+
+fn string_take_last(s: String) -> String {
+  let len = string.length(s)
+  string.slice(s, len - 1, 1)
+}
+
+fn mutate_first_body_char(s: String) -> String {
+  // Flip the first character to a different valid Crockford / Base58
+  // character. Both alphabets contain "1" and "2", so swapping between
+  // them produces a syntactically valid but checksum-invalid string.
+  let head = string.slice(s, 0, 1)
+  let tail = string.slice(s, 1, string.length(s) - 1)
+  let replacement = case head {
+    "1" -> "2"
+    _ -> "1"
+  }
+  replacement <> tail
+}
+
 // Issue #74: a wrapper that only `import yabase/intid` must be able to
 // type-annotate the error returned by `decode_int_*` without reaching
 // into `yabase/core/error`. This test pins down that the re-exported