@spec path_segment(String.t()) :: String.t()

Percent-encode a single URL path segment so user-supplied resource names can't inject extra path/query ("a/b" -> "a%2Fb", "x?y" -> "x%3Fy").

Raises ArgumentError on a non-binary segment — a caller/type bug (or a malformed API response), not routine input.

@spec short_name(String.t() | nil) :: String.t() | nil

Last path segment of a GCP self-link/URL (.../zones/us-central1-a -> "us-central1-a").

@spec to_datetime(String.t() | nil) :: DateTime.t() | nil

Parse a GCP RFC3339 timestamp into a DateTime (nil on failure).

@spec to_integer(String.t() | integer() | nil) :: integer() | nil

Coerce a GCP int-as-string (or int) into an integer; nil on anything malformed.