1 files changed, 138 insertions, 0 deletions
diff --git a/lib/Cepis/Health.pm b/lib/Cepis/Health.pm
new file mode 100644
index 0000000..6782fd0
--- /dev/null
+++ b/lib/Cepis/Health.pm
@@ -0,0 +1,138 @@
+package Cepis::Health;
+
+use strict;
+use warnings;
+
+use Scalar::Util ();
+
+our $VERSION = '0.1.0';
+
+sub from_json {
+    my ( $class, $data ) = @_;
+
+    my %raw = %{ $data || {} };
+
+    return bless {
+        status         => _string( $raw{status} ),
+        dne            => _string( $raw{dne} ),
+        ceps           => _integer( $raw{ceps} ),
+        geo            => _integer( $raw{geo} ),
+        base_gerada_em => _string( $raw{base_gerada_em} ),
+        raw            => \%raw,
+    }, $class;
+}
+
+sub status         { return $_[0]->{status} }
+sub dne            { return $_[0]->{dne} }
+sub ceps           { return $_[0]->{ceps} }
+sub geo            { return $_[0]->{geo} }
+sub base_gerada_em { return $_[0]->{base_gerada_em} }
+sub raw            { return $_[0]->{raw} }
+
+sub ok { return $_[0]->{status} eq 'ok' ? 1 : 0 }
+
+sub to_hash {
+    my ($self) = @_;
+    return {
+        status         => $self->{status},
+        dne            => $self->{dne},
+        ceps           => $self->{ceps},
+        geo            => $self->{geo},
+        base_gerada_em => $self->{base_gerada_em},
+    };
+}
+
+sub _string {
+    my ($value) = @_;
+    return '' unless defined $value;
+    return '' if ref $value;
+    return "$value";
+}
+
+sub _integer {
+    my ($value) = @_;
+    return 0 unless defined $value;
+    return 0 unless Scalar::Util::looks_like_number($value);
+    return int( 0 + $value );
+}
+
+1;
+
+__END__
+
+=encoding UTF-8
+
+=head1 NAME
+
+Cepis::Health - the answer of C<GET /health>
+
+=head1 SYNOPSIS
+
+    my $h = Cepis::health();
+
+    $h->ok;                # 1
+    $h->dne;               # "26071"   identifier of the fortnightly database
+    $h->ceps;              # 1596168
+    $h->base_gerada_em;    # "2026-07-24T03:48:28Z"
+
+=head1 DESCRIPTION
+
+Good for two things: checking that the API answers, and knowing B<which version
+of the database> is live. The DNE database changes every two weeks; L</dne>
+identifies it.
+
+An API reporting itself degraded does not raise — that arrives in L</status>.
+
+=head1 CONSTRUCTOR
+
+=head2 from_json
+
+    my $health = Cepis::Health->from_json( $hashref );
+
+Builds from the decoded JSON object the API returned.
+
+=head1 ACCESSORS
+
+=head2 status
+
+C<"ok"> when the API considers itself healthy, something else otherwise.
+
+=head2 ok
+
+True when L</status> is exactly C<"ok">.
+
+=head2 dne
+
+Identifier of the DNE database currently loaded. It changes every fortnight.
+
+=head2 ceps
+
+How many CEPs the database holds.
+
+=head2 geo
+
+How many of those CEPs carry a coordinate. Note that unlike
+L<Cepis::Address/geo> this is a count, not an object — that is what the API
+sends.
+
+=head2 base_gerada_em
+
+When the database was generated, as an ISO 8601 timestamp string.
+
+=head2 raw
+
+The decoded response exactly as it arrived, as a hashref.
+
+=head2 to_hash
+
+The five named fields as a plain hashref.
+
+=head1 SEE ALSO
+
+L<Cepis>, L<Cepis::Client>
+
+=head1 LICENCE
+
+ISC. Copyright (c) 2026 Murilo Ijanc E<lt>[email protected]<gt>.
+
+=cut