diff --git a/PokitDok.hs b/PokitDok.hs --- a/PokitDok.hs +++ b/PokitDok.hs @@ -1,42 +1,20 @@ ----------------------------------------------------------------------------- -- | -- Module : PokitDok --- Version : PokitDok Platform API v4 -- Copyright : (c) PokitDok Inc., 2011-2015 --- License : see LICENSE.txt --- +-- License : MIT -- Maintainer : gage.swenson@pokitdok.com -- Stability : internal --- Portability : non-portable -- --- Exports every call in the --- PokitDok.Client module. +-- The PokitDok module enables a Haskell programmer to make PokitDok API +-- calls from within the Haskell platform. The usage principles are concise +-- and easy to implement. -- ------------------------------------------------------------------------------ +---------------------------------------------------------------------------- --- The PokitDok module enables a Haskell programmer to make PokitDok API --- calls from within the Haskell platform. The usage principles are concise --- and easy to implement. --- --- 1. A client creates an @'OAuth2'@ by calling @'keyWithIdSecret'@, --- given their API secret key and credentials. This datum stores an id, --- secret, callback url, and access token, along with the lesser meddled --- with authorize endpoint and access token endpoint. --- --- 2. A client refreshes their OAuth's access token by calling @'refresh'@ --- With an id and secret, one can fetch access token data from the API. --- To call the API, a fresh (not expired) access token is required. --- @'keyModCallback'@, @'authorizationUrl'@, and @'authenticateCode'@ --- are helpful for developers working with PokitDok accounts in context. --- --- 3. Make API calls with the refreshed OAuth2. Most tokens last for 3600 --- seconds. It is safe to call refresh before every API call because a --- token will only refresh if it is expired. If you authenticated with --- a code and have a refresh token, it is more safe to store the result --- of every @'refresh'@ so that you use the latest issued token. --- --- --- Sample usage: +{- +SAMPLE USAGE + -- > -- > -- Each call returns an IO String. -- > -- Each string contains a json object @@ -68,9 +46,11 @@ -- > -- an example of a persistent refresh -- > pd1 <- refresh pd -- > return () --- +-} + module PokitDok ( module PokitDok.Client ) where + import PokitDok.Client diff --git a/PokitDok/Client.hs b/PokitDok/Client.hs --- a/PokitDok/Client.hs +++ b/PokitDok/Client.hs @@ -7,8 +7,9 @@ import PokitDok.OAuth2 import PokitDok.Paths +-- * Credentials --- | Generates a new key with a given id and secret. +-- | Generates a new key with the given id and secret. keyWithIdSecret :: String -> String -> OAuth2 keyWithIdSecret id secret = OAuth2 { oauthClientId = id @@ -19,13 +20,13 @@ , oauthAccessToken = Nothing } --- | Modifies the given key's callback url with the given @'Maybe'@ @'String'@'s value. +-- | Modifies the given key's callback url with the given @Maybe String@. keyModCallback :: OAuth2 -> Maybe String -> OAuth2 keyModCallback oauth n@Nothing = oauth { oauthCallback = n } keyModCallback oauth j = oauth { oauthCallback = j } -- | A url where a user can obtain an access token. --- Throws an error unless @keyModCallback@ is used on the credential. +-- Throws an error unless @keyModCallback@ is used on the credential first. authorizationUrl :: OAuth2 -> String authorizationUrl (OAuth2 id sec _ (Just authEP) (Just cb) _) = authEP `appendParams` authorizationUrlParams @@ -47,13 +48,14 @@ refresh :: OAuth2 -> IO OAuth2 refresh auth = isExpired auth >>= refreshExpired auth --- | Authenticate's an OAuth2 with the given authorization code. +-- | Authenticate's an @OAuth2@ given an authorization code. authenticateCode :: OAuth2 -> String -> IO OAuth2 authenticateCode = activateKeyWithAuthCode +-- * API Calls -- | Call the activities endpoint for a specific activityId. --- See docs here: https://platform.pokitdok.com/documentation/v4#/#activities +-- See docs here: activitiesWithId :: OAuth2 -- ^ Credentials with a valid @'AccessToken'@ -> String -- ^ Activity identifier. @@ -63,9 +65,9 @@ where url = path ++ apiEndpointActivities ++ id -- | Call the activities endpoint to get a listing of current activities, --- a query string parameter ‘parent_id’ may also be used with this API to get information about +-- a query string parameter @parent_id@ may also be used with this API to get information about -- sub-activities that were initiated from a batch file upload. --- See docs here: https://platform.pokitdok.com/documentation/v4#/#activities +-- See docs here: activities :: OAuth2 -> Parameters -- ^ _id, name, callback_url, file_url, history, state, transition_path... @@ -75,8 +77,8 @@ where url = path ++ apiEndpointActivities -- | Return a list of cash prices for a given procedure --- (by CPT Code) in a given region (by ZIP Code). --- See docs here: https://platform.pokitdok.com/documentation/v4#/#cashprices +-- code in a given region (by ZIP Code). +-- See docs here: pricesCash :: OAuth2 -> Parameters -- ^ cpt_code, zip_code (wthin with to search) @@ -85,9 +87,9 @@ pokitdokGetRequest auth url params >>= getJSONIO where url = path ++ apiEndpointPriceCash --- | Return a list of insurance prices for a given procedure --- (by CPT Code) in a given region (by ZIP Code). --- See docs here: https://platform.pokitdok.com/documentation/v4#/#insuranceprices +-- | Return a list of insurance prices for a given procedure code +-- in a given region (by ZIP Code). +-- See docs here: pricesInsurance :: OAuth2 -> Parameters -- ^ cpt_code, zip_code @@ -97,7 +99,7 @@ where url = path ++ apiEndpointPriceInsurance -- | Create a new claim, via the filing of an EDI 837 Professional Claims, to the designated Payer. --- See docs here: https://platform.pokitdok.com/documentation/v4#/#claims +-- See docs here: claims :: OAuth2 -> String -- ^ Dictionary representing JSON post data. @@ -107,14 +109,14 @@ where url = path ++ apiEndpointClaims -- | Ascertain the status of the specified claim, via the filing of an EDI 276 Claims Status. --- See docs here: https://platform.pokitdok.com/documentation/v4#/#claimstatus +-- See docs here: claimsStatus :: OAuth2 -> String -> IO String claimsStatus auth json = assertValid auth >> pokitdokPostRequest auth url json >>= getJSONIO where url = path ++ apiEndpointClaimsStatus -- | Determine eligibility via an EDI 270 Request For Eligibility. --- See docs here: https://platform.pokitdok.com/documentation/v4#/#eligibility +-- See docs here: eligibility :: OAuth2 -> String -- Dictionary representing an EDI 270 Request For Eligibility, JSON. @@ -124,7 +126,7 @@ where url = path ++ apiEndpointEligibility -- | File an EDI 834 benefit enrollment. --- See docs here: https://platform.pokitdok.com/documentation/v4#/#enrollment +-- See docs here: enrollment :: OAuth2 -> String -- ^ Post data, JSON. @@ -133,8 +135,8 @@ pokitdokPostRequest auth url json >>= getJSONIO where url = path ++ apiEndpointEnrollment --- | Retrieve providers data matching specified query parameters --- See docs here: https://platform.pokitdok.com/documentation/v4#/#providers +-- | Retrieve providers data matching specified query parameters. +-- See docs here: providers :: OAuth2 -> Parameters -- ^ organization_name, first_name, last_name, specialty, city, state, radius... @@ -144,7 +146,7 @@ where url = path ++ apiEndpointProviders -- | Retrieve the data for a specified provider. --- See docs here: https://platform.pokitdok.com/documentation/v4#/#providers +-- See docs here: providersWithNpi :: OAuth2 -> String -- Provider NPI identifier, JSON. @@ -154,7 +156,7 @@ where url = path ++ apiEndpointProviders++npi -- | Retrieve data on plans based on the parameters given. --- See docs here: https://platform.pokitdok.com/documentation/v4#/#plans +-- See docs here: plans :: OAuth2 -> Parameters -- ^ trading_partner_id, country, state, plan_id, plan_type, plan_name... @@ -163,9 +165,9 @@ pokitdokGetRequest auth url params >>= getJSONIO where url = path ++ apiEndpointPlans --- | Use the /payers/ API to determine available payer_id values for use with other endpoints --- The Payers endpoint will be deprecated in v5. Use Trading Partners instead. --- See docs here: https://platform.pokitdok.com/documentation/v4#/#payers +-- | Use the /payers/ API to determine available @payer_id@ values for use with other endpoints. +-- This endpoint will be deprecated in v5. Use /Trading Partners/ instead. +-- See docs here: payers :: OAuth2 -> IO String payers auth = assertValid auth >> pokitdokGetRequest auth url [] >>= getJSONIO @@ -173,7 +175,7 @@ -- | Retrieve a list of trading partners or submit an id to get info for a -- specific trading partner. Empty string is a valid parameter. --- See docs here: https://platform.pokitdok.com/documentation/v4#/#tradingpartners +-- See docs here: tradingPartners :: OAuth2 -> String -- Trading Partner Identifier, can be empty. @@ -182,8 +184,8 @@ pokitdokGetRequest auth url [] >>= getJSONIO where url = path++apiEndpointTradingPartners++id --- | Submit X12 formatted EDI file for batch processing. --- If the callback url is not nothing in the @'OAuth2'@, it will be included. +-- | Submit an X12 formatted EDI file for batch processing. +-- If the callback url is not nothing in the @OAuth2@, it will be included. files :: OAuth2 -> String -- ^ Trading_partner_id. @@ -198,14 +200,14 @@ where url = path ++ apiEndpointFiles -- | Request approval for a referral to another health care provider. --- See docs here: https://platform.pokitdok.com/documentation/v4#/#referrals +-- See docs here: referrals :: OAuth2 -> String -> IO String referrals auth json = assertValid auth >> pokitdokPostRequest auth url json >>= getJSONIO where url = path ++ apiEndpointReferrals -- | Submit an authorization request. --- See docs here: https://platform.pokitdok.com/documentation/v4#/#authorizations +-- See docs here: authorizations :: OAuth2 -> String -- Dictionary representing JSON post data. @@ -214,10 +216,10 @@ pokitdokPostRequest auth url json >>= getJSONIO where url = path ++ apiEndpointAuthorizations --- | Get a list of supported scheduling systems and their UUIDs and descriptions. +-- | Get a list of supported scheduling systems and their UUIDs & descriptions. schedulers :: OAuth2 - -> String -- ^ Optional (can be ""), retrieve the data for a specified scheduling system. + -> String -- ^ Empty string valid, retrieve the data for a specified scheduling system. -> IO String schedulers auth uuid = assertValid auth >> pokitdokGetRequest auth url [] >>= getJSONIO @@ -226,7 +228,7 @@ -- | Get a list of appointment types, their UUIDs, and descriptions. appointmentTypes :: OAuth2 - -> String -- ^ Optional (""), retrieve the data for a specified appointment type. + -> String -- ^ Empty string valid, retrieve the data for a specified appointment type. -> IO String appointmentTypes auth uuid = assertValid auth >> pokitdokGetRequest auth url [] >>= getJSONIO @@ -242,8 +244,8 @@ where url = path ++ apiEndpointSlots -- | Query for an open appointment slot or a booked appointment given a --- specific pd_appointment_uuid, the (PokitDok unique appointment identifier). --- See https://platform.pokitdok.com/documentation +-- specific @pd_appointment_uuid@, the PokitDok unique appointment identifier. +-- See appointmentsWithId :: OAuth2 -> String -- ^ The PokitDok unique appointment identifier. @@ -252,9 +254,9 @@ pokitdokGetRequest auth url [] >>= getJSONIO where url = path ++ apiEndpointAppointments ++ uuid --- | Query for open appointment slots (using pd_provider_uuid and location) --- or booked appointments (using patient_uuid) given query parameters. --- See https://platform.pokitdok.com/documentation +-- | Query for open appointment slots (using @pd_provider_uuid@ and @location@) +-- or booked appointments (using @patient_uuid@2) given query parameters. +-- See appointments :: OAuth2 -> Parameters -> IO String appointments auth params = assertValid auth >> pokitdokGetRequest auth url params >>= getJSONIO @@ -262,7 +264,7 @@ -- | Book appointment for an open slot. Post data contains patient -- attributes and description. --- See https://platform.pokitdok.com/documentation +-- See bookAppointment :: OAuth2 -> String -- ^ The PokitDok unique appointment identifier. @@ -273,14 +275,14 @@ where url = path ++ apiEndpointAppointments ++ uuid -- | Update appointment description. --- See https://platform.pokitdok.com/documentation +-- See updateAppointment :: OAuth2 -> String -> String -> IO String updateAppointment auth uuid json = assertValid auth >> pokitdokPutRequest auth url json >>= getJSONIO where url = path ++ apiEndpointAppointments ++ uuid --- | Cancel appointment given its pd_appointment_uuid. --- See https://platform.pokitdok.com/documentation +-- | Cancel appointment given its @pd_appointment_uuid@. +-- See cancelAppointment :: OAuth2 -> String -> IO String cancelAppointment auth uuid = assertValid auth >> pokitdokDeleteRequest auth url >>= getJSONIO diff --git a/PokitDok/OAuth2.hs b/PokitDok/OAuth2.hs --- a/PokitDok/OAuth2.hs +++ b/PokitDok/OAuth2.hs @@ -57,6 +57,8 @@ import Data.Aeson import Data.Maybe (fromJust) +-- * Data Types + type Parameters = [(String, String)] type Headers = [(String, String)] @@ -75,7 +77,7 @@ data AccessToken = AccessToken { accessToken :: String , refreshToken :: Maybe String - , expires :: Maybe Int -- ^ POSIX seconds. + , expires :: Maybe Int -- ^ measured in POSIX seconds. , expiresIn :: Maybe Int , token_type :: Maybe String } deriving (Show, Eq) @@ -97,7 +99,7 @@ tt = o .: T.pack "token_type" parseJSON _ = mzero --- Functions dealing with authorization, access tokens, and authentication. +-- * Credentials -- | Modifies the given key's @AccessToken@ with the given @'Maybe'@ @AccessToken@'s value. keyModAccessToken :: OAuth2 -> Maybe AccessToken -> OAuth2 @@ -155,7 +157,7 @@ , ("scope" , "user_schedle") ] --- Functions that perform network calls. +-- * Network Calls -- | Perform a GET request given request headers, a url, and query parameters. getRequest :: Headers -> String -> Parameters -> IO ResponseData @@ -174,8 +176,7 @@ req <- makePostRequest url $ makeHeaders headers handleRequest $ req { requestBody = RequestBodyBS $ BS.pack body } --- | Performs a multipart request given a body and a boundary --- separating the requests in the body. +-- | Performs a multipart request file upload with the given parameters. multipartRequest :: Headers -- ^ Some headers, must include authorization. -> String -- ^ Request URL. @@ -212,7 +213,7 @@ getResponse :: Request -> IO (Response BSL.ByteString) getResponse = withManager . httpLbs --- Auxiliary functions for headers and parameters. +-- * Headers and Parameters -- | Makes a header out of a given header name and value tuple. makeHeader :: (String, String) -> Header diff --git a/PokitDok/Requests.hs b/PokitDok/Requests.hs --- a/PokitDok/Requests.hs +++ b/PokitDok/Requests.hs @@ -4,7 +4,7 @@ -- of the OAuth2 module. -- -- It also includes auxiliary funtions for handling --- its main return type: ResponseData. +-- its main return type: @ResponseData@. module PokitDok.Requests ( pokitdokGetRequest @@ -32,9 +32,9 @@ import PokitDok.OAuth2 --- Middle man network calls that provide headers to OAuth2.hs calls. +-- * Middleman Network Calls --- | Sends a get request to the server with the given query parameters. +-- | Sends a GET request to the server with the given query parameters. pokitdokGetRequest :: OAuth2 -- ^ An OAuth2 credential. -> String -- ^ The request url path. @@ -43,7 +43,7 @@ pokitdokGetRequest key = getRequest headers where headers = [bearerH . fromJust $ oauthAccessToken key, userAgentH] --- | Sends a get request to the server with the given query parameters. +-- | Sends a DELETE request to the server with the given query parameters. pokitdokDeleteRequest :: OAuth2 -- ^ A credential. -> String -- ^ The request url path. @@ -51,7 +51,7 @@ pokitdokDeleteRequest key = deleteRequest headers where headers = [bearerH . fromJust $ oauthAccessToken key, userAgentH] --- | Sends a post request to the server and posts the json string. +-- | Sends a POST request to the server and posts the json string. pokitdokPostRequest :: OAuth2 -- ^ Credentials. -> String -- ^ The request url path. @@ -60,7 +60,7 @@ pokitdokPostRequest key = postRequest headers where headers = [bearerH . fromJust $ oauthAccessToken key, userAgentH] --- | Sends a put request with JSON data. +-- | Sends a PUT request with JSON data. pokitdokPutRequest :: OAuth2 -- ^ Credentials. -> String -- ^ The request url path. @@ -69,7 +69,7 @@ pokitdokPutRequest key = putRequest headers where headers = [bearerH . fromJust $ oauthAccessToken key, userAgentH] --- | Makes a multipart request that uploads a file with the given: +-- | A multipart request that uploads a file. pokitdokMultipartRequest :: OAuth2 -- ^ Credentials. -> String -- ^ The request url path. @@ -90,7 +90,7 @@ format file@('/':_) = return file format file = getCurrentDirectory >>= return . (++ [osChar] ++ file) --- Functions auxiliary to those defined above. +-- * Auxiliary Functions -- The boundary of the PD multipart file upload. multipartBoundary :: IO String @@ -114,20 +114,19 @@ userAgentH :: (String, String) userAgentH = makeUserAgentHeader $ "haskell-pokitdok/" ++ httpPackageVersion --- | Pulls the JSON response @String@ from a @ResponseData@ datum, +-- | Pulls the JSON response @String@ from a @ResponseDat@um, -- and lifts the result to an IO monad. getJSONIO :: ResponseData -> IO String getJSONIO = return . getJSON --- Extracts the JSON r +-- Extracts the JSON response from ResponseData. getJSON :: ResponseData -> String getJSON (ResponseData _ body _) = body --- Supplementary functions that don't need to be exported by Client.hs, --- or that need PD network headers. +-- * Supplementary Client Functions --- | Takes an @'Oauth2'@ & an authorization code, +-- | Takes an @OAuth2@ & an authorization code, -- and returns an @OAuth2@ with a refreshed @AccessToken@. activateKeyWithAuthCode :: OAuth2 -> String -> IO OAuth2 activateKeyWithAuthCode auth code = do @@ -158,6 +157,4 @@ assertValid (OAuth2 _ _ _ _ _ Nothing) = error "Access token has not been initialized." assertValid (OAuth2 _ _ _ _ _ (Just t)) = do dead <- isExpired' t - if dead - then error "Access token is expired." - else return () + if dead then error "Access token is expired." else return () diff --git a/pokitdok.cabal b/pokitdok.cabal --- a/pokitdok.cabal +++ b/pokitdok.cabal @@ -10,7 +10,7 @@ -- PVP summary: +-+------- breaking API changes -- | | +----- non-breaking API additions -- | | | +--- code changes with no API change -version: 4.1.0.0 +version: 4.1.0.1 -- A short (one-line) description of the package. synopsis: PokitDok Platform API Client for Haskell