Initial importv0.1.0

1 files changed, 83 insertions, 0 deletions

diff --git a/lib/cepis.rb b/lib/cepis.rb
new file mode 100644
index 0000000..7b2cc5a
--- /dev/null
+++ b/lib/cepis.rb
@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "cepis/version"
+require_relative "cepis/errors"
+require_relative "cepis/models"
+require_relative "cepis/client"
+
+# Ruby client for the public CEP API at https://cep.is.
+#
+# For a script, the module-level methods are enough:
+#
+#   require "cepis"
+#
+#   address = Cepis.lookup("01001-000")
+#   puts "#{address.localidade} #{address.uf}"   # São Paulo SP
+#
+# In an application, build a {Cepis::Client} once and reuse it:
+#
+#   client = Cepis::Client.new(timeout: 5.0, total_timeout: 15.0)
+#   address = client.lookup("01001000")
+#
+# Pointing at a local instance (the API repo brings one up with `just up`):
+#
+#   client = Cepis::Client.new(base_url: "http://localhost:8080")
+#
+# Errors are explicit and split by decision — whether retrying helps or not:
+#
+#   begin
+#     address = Cepis.lookup(cep_from_form)
+#   rescue Cepis::CEPNotFound
+#     # the CEP does not exist: ask the user for another
+#   rescue Cepis::Error
+#     # network, server, rate limit: retry later
+#   end
+#
+# Note on field names: the API surface is English, but the **data fields keep
+# the API's own Portuguese names** (`logradouro`, `bairro`, `localidade`). What
+# you read in the JSON is what you read on the object.
+module Cepis
+  class << self
+    # The client behind the module-level methods.
+    #
+    # It is built once because {Client} keeps no state between calls and is
+    # safe to share across threads. It applies process-wide, including to
+    # third-party libraries that also use this module — anyone needing
+    # different settings should build their own {Client}.
+    #
+    # @return [Client]
+    def default_client
+      @default_client ||= Client.new
+    end
+
+    # Look up a CEP using the default configuration.
+    #
+    # Shorthand for `Cepis.default_client.lookup(cep)`. See {Client#lookup}.
+    #
+    # @param cep [String]
+    # @return [Address]
+    def lookup(cep)
+      default_client.lookup(cep)
+    end
+
+    # Look up many CEPs in one batch, using the default configuration.
+    #
+    # Shorthand for {Client#lookup_many} — read that one, especially the
+    # warning that batches carry no coordinate.
+    #
+    # @param ceps [Array<String>]
+    # @return [Array<Address, nil>]
+    def lookup_many(ceps)
+      default_client.lookup_many(ceps)
+    end
+
+    # Query the API's health using the default configuration.
+    #
+    # Shorthand for {Client#health}.
+    #
+    # @return [Health]
+    def health
+      default_client.health
+    end
+  end
+end