Merge pull request #2 from Ziptastic/initial-version

ziptastic-client version 0.2.0.0

cabal.project

@@ -0,0 +1,3 @@
+packages:
+  ziptastic-core/
+  ziptastic-client/

ziptastic-client/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.2.0.0
+
+  * For failures, provide full `ServantError` instead converting it to `String`.
+  * Add version bounds.
+  * Clean up documentation and meta information.
+  * Add change log.
+
+## 0.1.0.0
+
+  * Initial release.

ziptastic-client/src/Ziptastic/Client.hs

@@ -36,42 +36,49 @@ import           Data.Text (Text)
 import           Network.HTTP.Client (Manager)
 import           Servant.API ((:<|>)(..))
 import           Servant.Client
-  ( BaseUrl(..), ClientEnv(..), ClientM, Scheme(..)
+  ( BaseUrl(..), ClientEnv(..), ClientM, Scheme(..), ServantError
   , client, runClientM
   )
 
 import           Ziptastic.Core (ApiKey, ForApi(..), LocaleInfo)
 import qualified Ziptastic.Core as Core
 
+-- | Performs a forward geocode lookup at the given country and postal code.
+--
+-- The success result is a list because in rare cases you may receive multiple records.
+-- If the request fails the result will be 'Left' with an error.
 forwardGeocode :: ApiKey
                -> Manager      -- ^ HTTP connection manager
                -> CountryCode  -- ^ country
                -> Text         -- ^ postal code
-               -> IO (Either String [LocaleInfo])
-forwardGeocode apiKey manager countryCode postalCode = strLeft <$> runClientM func (ClientEnv manager baseUrl)
+               -> IO (Either ServantError [LocaleInfo])
+forwardGeocode apiKey manager countryCode postalCode = runClientM func (ClientEnv manager baseUrl)
   where func = forwardGeocode' (apiClient apiKey) (ForApi countryCode) postalCode
 
 -- | Performs a reverse geocode lookup at the given coordinates using a default radius of 5000 meters.
+--
+-- The success result is a list because in rare cases you may receive multiple records.
+-- If the request fails the result will be 'Left' with an error.
 reverseGeocode :: ApiKey
                -> Manager -- ^ HTTP connection manager
                -> Double  -- ^ latitude
                -> Double  -- ^ longitude
-               -> IO (Either String [LocaleInfo])
+               -> IO (Either ServantError [LocaleInfo])
 reverseGeocode apiKey manager lat long = reverseGeocodeWithRadius apiKey manager lat long 5000
 
 -- | Performs a reverse geocode lookup at the given coordinates using a specified radius in meters.
+--
+-- The success result is a list because in rare cases you may receive multiple records.
+-- If the request fails the result will be 'Left' with an error.
 reverseGeocodeWithRadius :: ApiKey
                          -> Manager -- ^ HTTP connection manager
                          -> Double  -- ^ latitude
                          -> Double  -- ^ longitude
                          -> Int     -- ^ radius (in meters)
-                         -> IO (Either String [LocaleInfo])
-reverseGeocodeWithRadius apiKey manager lat long radius = strLeft <$> runClientM func (ClientEnv manager baseUrl)
+                         -> IO (Either ServantError [LocaleInfo])
+reverseGeocodeWithRadius apiKey manager lat long radius = runClientM func (ClientEnv manager baseUrl)
   where func = reverseGeocodeWithRadius' (mkReverseGeocode (apiClient apiKey) lat long) radius
 
-strLeft :: Show e => Either e a -> Either String a
-strLeft (Left e)  = Left (show e)
-strLeft (Right a) = Right a
 
 data ApiClient = ApiClient
   { forwardGeocode'  :: ForApi CountryCode -> Text -> ClientM [LocaleInfo]

ziptastic-client/ziptastic-client.cabal

@@ -1,13 +1,13 @@
 name:                ziptastic-client
-version:             0.1.0.0
+version:             0.2.0.0
 synopsis:
-  Core Servant specification for the Ziptastic API (https://www.getziptastic.com) for doing forward and reverse geocoding.
+  A type-safe client for the Ziptastic API for doing forward and reverse geocoding.
 description:
-  This package provides a type-safe Servant specification for the Ziptastic
-  (https://www.getziptastic.com) API for doing forward and reverse geocoding
-  via zip/postal code, latitude, and longitude.
+  A convenient and type-safe client library for the
+  Ziptastic (<https://www.getziptastic.com/>) API providing forward and reverse
+  geocoding via country, zip code (postal code), latitude, and longitude.
   .
-  This package is maintained by Grafted-In (https://www.graftedin.io/).
+  This package is maintained by Grafted-In (<https://www.graftedin.io/>).
 homepage:            https://github.com/Ziptastic/ziptastic-haskell#readme
 license:             BSD3
 license-file:        LICENSE
@@ -19,25 +19,23 @@ build-type:          Simple
 extra-source-files:  README.md
 cabal-version:       >=1.10
 tested-with:         GHC==8.0.2
+extra-source-files:
+  CHANGELOG.md
+  README.md
 
 library
   hs-source-dirs:  src
   exposed-modules: Ziptastic.Client
   build-depends:
-      base >= 4.7 && < 5
-    , bytestring
-    , aeson
-    , http-api-data
+      base                  >= 4.7 && < 5
     , http-client
-    , http-client-tls
     , iso3166-country-codes
-    , servant
-    , servant-client
+    , servant               >= 0.9 && <= 0.11
+    , servant-client        >= 0.9 && <= 0.11
     , text
-    , tz
-    , ziptastic-core
+    , ziptastic-core        == 0.1.0.1
   default-language: Haskell2010
-  extensions:
+  other-extensions:
     DataKinds
     TypeOperators
     OverloadedStrings

ziptastic-core/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0.1
+
+  * Add version bounds.
+  * Clean up documentation and meta information.
+  * Add change log.
+
+## 0.1.0.0
+
+  * Initial release.

ziptastic-core/ziptastic-core.cabal

@@ -1,15 +1,15 @@
 name:                ziptastic-core
-version:             0.1.0.0
+version:             0.1.0.1
 synopsis:
-  Core Servant specification for the Ziptastic API (https://www.getziptastic.com) for doing forward and reverse geocoding.
+  Core Servant specification for the Ziptastic API for doing forward and reverse geocoding.
 description:
   This package provides a type-safe Servant specification for the Ziptastic
-  (https://www.getziptastic.com) API for doing forward and reverse geocoding
+  (<https://www.getziptastic.com>) API for doing forward and reverse geocoding
   via zip/postal code, latitude, and longitude.
   .
-  If you want to use the Ziptastic API in your application, try the ziptastic-client package.
+  If you want to use the Ziptastic API in your application, try the @ziptastic-client@ package.
   .
-  This package is maintained by Grafted-In (https://www.graftedin.io/).
+  This package is maintained by Grafted-In (<https://www.graftedin.io/>).
 homepage:            https://github.com/Ziptastic/ziptastic-haskell#readme
 license:             BSD3
 license-file:        LICENSE
@@ -21,21 +21,24 @@ build-type:          Simple
 extra-source-files:  README.md
 cabal-version:       >=1.10
 tested-with:         GHC==8.0.2
+extra-source-files:
+  CHANGELOG.md
+  README.md
 
 library
   hs-source-dirs:  src
   exposed-modules: Ziptastic.Core
   build-depends:
-      aeson
-    , base >= 4.7 && < 5
-    , bytestring
-    , http-api-data
-    , iso3166-country-codes
-    , servant
-    , text
-    , tz
+      aeson                 >= 0.7 && < 1.2
+    , base                  >= 4.7 && < 5
+    , bytestring            == 0.10.*
+    , http-api-data         == 0.3.*
+    , iso3166-country-codes >= 0.20140203.8
+    , servant               >= 0.9 && < 0.11
+    , text                  >= 0.11
+    , tz                    == 0.1.*
   default-language: Haskell2010
-  extensions:
+  other-extensions:
     DataKinds
     DeriveGeneric
     FlexibleInstances