[{"name":"Http.Detailed","comment":" **Create HTTP requests that return more detailed responses.**\r\n\r\n_I wrote a [guide explaining how to extract detailed information from HTTP responses in Elm,][Going Beyond 200 OK]\r\nboth with and without this package. Giving it a read might help you better understand\r\nthe motivation and use cases behind this module!_\r\n\r\n---\r\n\r\nThe metadata and original body of an HTTP response are often very useful.\r\nMaybe your server returns a useful error message you'd like to try and decode,\r\nor you're receiving an auth token in the header of a response.\r\n\r\nUnfortunately, this information is discarded in the responses from [`elm/http`][http].\r\nThis module lets you create HTTP requests that keep that useful information around.\r\n\r\nThe API is designed so that usage of this module is exactly the same as using [`elm/http`][http],\r\nwith the only difference being that a more detailed `Result` is returned.\r\n\r\n[http]: https://package.elm-lang.org/packages/elm/http/2.0.0\r\n[Going Beyond 200 OK]: https://medium.com/@jzxhuang/going-beyond-200-ok-a-guide-to-detailed-http-responses-in-elm-6ddd02322e\r\n\r\n\r\n# Example\r\n\r\nCreate an HTTP request like you normally would -\r\njust use this module's [`expect`](#expect) functions instead of the ones from the default package.\r\n\r\n    import Http\r\n    import Http.Detailed\r\n\r\n    type Msg\r\n        = GotText (Result (Http.Detailed.Error String) ( Http.Metadata, String ))\r\n        | ...\r\n\r\n    Http.get\r\n        { url = \"https://elm-lang.org/assets/public-opinion.txt\"\r\n        , expect = Http.Detailed.expectString GotText\r\n        }\r\n\r\nIf a successful response is received, a `Tuple` containing the metadata and expected body is returned.\r\nYou can access a header from the metadata if needed.\r\n\r\nIn case of an error, a custom [`Error`](#Error) type is returned which keeps the metadata and body around if applicable,\r\nrather than discarding them. Maybe you want to try and decode the error message!\r\n\r\nYour update function might look a bit like this:\r\n\r\n    update msg model =\r\n        case msg of\r\n            GotText detailedResponse ->\r\n                case detailedResponse of\r\n                    Ok ( metadata, text ) ->\r\n                        -- Do something with the metadata if you need!\r\n\r\n                    Err error ->\r\n                        case error of\r\n                            Http.Detailed.BadStatus metadata body ->\r\n                                -- Try to decode the body - it might be a useful error message!\r\n\r\n                            Http.Detailed.Timeout ->\r\n                                -- No metadata is given here - the request timed out\r\n\r\n                            ...\r\n\r\n            ...\r\n\r\n\r\n# Expect (Tuple)\r\n\r\nExactly like the `expect` functions from [`elm/http`][http] - usage of the API is the same.\r\nThe difference is that the `Result` is more detailed.\r\n\r\n  - On a successful response, returns a `Tuple` containing the expected body and the metadata.\r\n  - On an error, returns our custom [`Error`](#Error) type which keeps the metadata and body around if applicable.\r\n\r\nA modified version of the examples from [`elm/http`][http] are included for each function to help guide you in using this module.\r\n\r\n[http]: https://package.elm-lang.org/packages/elm/http/2.0.0\r\n\r\n@docs Error, expectString, expectJson, expectBytes, expectWhatever\r\n\r\n\r\n# Expect (Record)\r\n\r\nPrefer a record rather than a Tuple? Use these functions instead. Same as the `expect` functions above,\r\nbut on a successful response returns a record of our custom type [`Success`](#Success) instead of a Tuple.\r\n\r\n@docs Success, expectStringRecord, expectJsonRecord, expectBytesRecord\r\n\r\n\r\n# Transform\r\n\r\nThese functions transform an [`Http.Response`][httpResponse] value into the detailed `Result` that is returned in each [`expect`](#Expect) function in this module.\r\nYou can use these to build your own `expect` functions.\r\n\r\nFor example, to create [`Http.Detailed.expectJson`](#expectJson):\r\n\r\n    import Http\r\n    import Http.Detailed\r\n    import json.Decode\r\n\r\n\r\n    expectJson : (Result (Http.Detailed.Error String) ( Http.Metadata, a ) -> msg) -> Json.Decode.Decoder a -> Http.Expect msg\r\n    expectJson toMsg decoder =\r\n        Http.expectStringResponse toMsg (responseToJson decoder)\r\n\r\nUse this with [`Mock`](../Http-Mock) to mock a request with a detailed response!\r\n\r\n    import Http\r\n    import Http.Detailed\r\n    import Http.Mock\r\n\r\n\r\n    type Msg\r\n        = GotText (Result (Http.Detailed.Error String) ( Http.Metadata, String ))\r\n        | ...\r\n\r\n\r\n    -- Mock a request, with a Detailed Result!\r\n\r\n    Http.get\r\n        { url = \"https://fakeurl.com\"\r\n        , expect = Http.Mock.expectStringResponse Http.Timeout_ GotText Http.Detailed.responseToString\r\n        }\r\n\r\n[http]: https://package.elm-lang.org/packages/elm/http/2.0.0\r\n[httpResponse]: https://package.elm-lang.org/packages/elm/http/2.0.0/Http#Response\r\n\r\n@docs responseToString, responseToJson, responseToBytes, responseToWhatever\r\n\r\n","unions":[{"name":"Error","comment":" Our custom error type. Similar to [`Http.Error`][httpError], but keeps the metadata and body around\r\nin `BadStatus` and `BadBody` rather than discarding them. Maybe your API gives a useful error message you want to decode!\r\n\r\n`body` can be either `String` or `Bytes`, depending on which `expect` function you use.\r\n\r\n  - [`expectJson`](#expectJson) and [`expectString`](#expectJson) will return a `String` body\r\n  - [`expectWhatever`](#expectWhatever) and [`expectBytes`](#expectBytes) will return a `Bytes` body.\r\n\r\nThe `BadBody` state will only be entered when using [`expectJson`](#expectJson) or [`expectBytes`](#expectBytes).\r\n\r\n[httpError]: https://package.elm-lang.org/packages/elm/http/2.0.0/Http#Error\r\n\r\n","args":["body"],"cases":[["BadUrl",["String.String"]],["Timeout",[]],["NetworkError",[]],["BadStatus",["Http.Metadata","body"]],["BadBody",["Http.Metadata","body","String.String"]]]}],"aliases":[{"name":"Success","comment":" A custom type containing the full details for a successful response as a record.\r\n\r\nbody can be either String or Bytes, depending on which expect function you use.\r\n\r\n","args":["body"],"type":"{ metadata : Http.Metadata, body : body }"}],"values":[{"name":"expectBytes","comment":" Expect the response body to be binary data, and try to decode it.\r\n\r\n    import Bytes exposing (Bytes)\r\n    import Bytes.Decode\r\n    import Http\r\n    import Http.Detailed\r\n\r\n    type Msg\r\n        = GotData (Result (Http.Detailed.Error Bytes) ( Http.Metadata, Data ))\r\n\r\n    getData : Cmd Msg\r\n    getData =\r\n        Http.get\r\n            { url = \"/data\"\r\n            , expect = Http.Detailed.expectBytes GotData dataDecoder\r\n            }\r\n\r\n    dataDecoder : Bytes.Decode.Decoder Data\r\n\r\n    -- This is a Bytes decoder (not implemented)...\r\n\r\nOn success, return the a tuple containing the metadata and the decoded body. On error, return our custom [`Error`](#Error) type.\r\n\r\nIf the Bytes decoder fails, you get a `BadBody` error that just indicates that\r\n_something_ went wrong. You can try to debug by taking a look at the\r\nbytes you are getting in the browser DevTools or something.\r\n\r\n","type":"(Result.Result (Http.Detailed.Error Bytes.Bytes) ( Http.Metadata, a ) -> msg) -> Bytes.Decode.Decoder a -> Http.Expect msg"},{"name":"expectBytesRecord","comment":" ","type":"(Result.Result (Http.Detailed.Error Bytes.Bytes) (Http.Detailed.Success a) -> msg) -> Bytes.Decode.Decoder a -> Http.Expect msg"},{"name":"expectJson","comment":" Expect the response body to be JSON, and try to decode it.\r\n\r\n    import Http\r\n    import Http.Detailed\r\n    import Json.Decode exposing (Decoder, field, string)\r\n\r\n    type Msg\r\n        = GotGif (Result (Http.Detailed.Error String) ( Http.Metadata, String ))\r\n\r\n    getRandomCatGif : Cmd Msg\r\n    getRandomCatGif =\r\n        Http.get\r\n            { url = \"https://api.giphy.com/v1/gifs/random?api_key=dc6zaTOxFJmzC&tag=cat\"\r\n            , expect = Http.Detailed.expectJson GotGif gifDecoder\r\n            }\r\n\r\n    gifDecoder : Decoder String\r\n    gifDecoder =\r\n        field \"data\" (field \"image_url\" string)\r\n\r\nOn success, return a `Tuple` containing the metadata and the decoded body. On error, return our custom [`Error`](#Error) type.\r\n\r\nIf the JSON decoder fails, you get a `BadBody` error that tries to explain what went wrong.\r\n\r\n","type":"(Result.Result (Http.Detailed.Error String.String) ( Http.Metadata, a ) -> msg) -> Json.Decode.Decoder a -> Http.Expect msg"},{"name":"expectJsonRecord","comment":" ","type":"(Result.Result (Http.Detailed.Error String.String) (Http.Detailed.Success a) -> msg) -> Json.Decode.Decoder a -> Http.Expect msg"},{"name":"expectString","comment":" Expect the response body to be a `String`.\r\n\r\n    import Http\r\n    import Http.Detailed\r\n\r\n    type Msg\r\n        = GotText (Result (Http.Detailed.Error String) ( Http.Metadata, String ))\r\n\r\n    getPublicOpinion : Cmd Msg\r\n    getPublicOpinion =\r\n        Http.get\r\n            { url = \"https://elm-lang.org/assets/public-opinion.txt\"\r\n            , expect = Http.Detailed.expectString GotText\r\n            }\r\n\r\nOn success, return a `Tuple` containing the metadata and the body as a `String`. On error, return our custom [`Error`](#Error) type.\r\n\r\nWhen using this, the error will never be of type `BadBody`.\r\n\r\n","type":"(Result.Result (Http.Detailed.Error String.String) ( Http.Metadata, String.String ) -> msg) -> Http.Expect msg"},{"name":"expectStringRecord","comment":" ","type":"(Result.Result (Http.Detailed.Error String.String) (Http.Detailed.Success String.String) -> msg) -> Http.Expect msg"},{"name":"expectWhatever","comment":" Expect the response body to be whatever. It does not matter. Ignore it!\r\n\r\n    import Http\r\n    import Http.Detailed\r\n\r\n    type Msg\r\n        = Uploaded (Result (Http.Detailed.Error Bytes) ())\r\n\r\n    upload : File -> Cmd Msg\r\n    upload file =\r\n        Http.post\r\n            { url = \"/upload\"\r\n            , body = Http.fileBody file\r\n            , expect = Http.Detailed.expectWhatever Uploaded\r\n            }\r\n\r\nThe server may be giving back a response body, but we do not care about it.\r\n\r\nOn error, return our custom [`Error`](#Error) type. It will never be `BadBody`.\r\n\r\n","type":"(Result.Result (Http.Detailed.Error Bytes.Bytes) () -> msg) -> Http.Expect msg"},{"name":"responseToBytes","comment":" ","type":"Bytes.Decode.Decoder a -> Http.Response Bytes.Bytes -> Result.Result (Http.Detailed.Error Bytes.Bytes) ( Http.Metadata, a )"},{"name":"responseToJson","comment":" ","type":"Json.Decode.Decoder a -> Http.Response String.String -> Result.Result (Http.Detailed.Error String.String) ( Http.Metadata, a )"},{"name":"responseToString","comment":" ","type":"Http.Response String.String -> Result.Result (Http.Detailed.Error String.String) ( Http.Metadata, String.String )"},{"name":"responseToWhatever","comment":" ","type":"Http.Response Bytes.Bytes -> Result.Result (Http.Detailed.Error Bytes.Bytes) ()"}],"binops":[]},{"name":"Http.Extras","comment":" **Convenience functions for creating HTTP requests and interpreting an HTTP response.**\r\n\r\n\r\n# Requests\r\n\r\nHelpers for creating HTTP requests.\r\n\r\n@docs Request, listToHeaders, listToQuery\r\n\r\n\r\n# Responses\r\n\r\nHelpers for interpreting an [`Http.Response`][httpResponse] value.\r\n\r\n[httpResponse]: https://package.elm-lang.org/packages/elm/http/2.0.0/Http#Response\r\n\r\n\r\n## Transform\r\n\r\nTransform an [`Http.Response`][httpResponse] value into the respective `Result` that is returned\r\nin each `expect` function from [`elm/http`][http]. Used for building custom `expect` functions.\r\n\r\nFor example, you could replicate [`Http.expectString`](https://package.elm-lang.org/packages/elm/http/2.0.0/Http#expectString) like so:\r\n\r\n    import Http\r\n    import Http.Extras\r\n\r\n    expectString : (Result Http.Error String -> msg) -> Http.Expect msg\r\n    expectString toMsg =\r\n        Http.expectStringResponse toMsg Http.Extras.responseToString\r\n\r\n[http]: https://package.elm-lang.org/packages/elm/http/2.0.0\r\n[httpResponse]: https://package.elm-lang.org/packages/elm/http/2.0.0/Http#Response\r\n\r\n@docs responseToString, responseToJson, responseToBytes, responseToWhatever\r\n\r\n\r\n## Getters\r\n\r\nConvenience functions for extracting information like the header, status code, url, etc. from a [`Http.Response`][httpResponse] value.\r\nOn an error, a short string will be returned describing why the error occurred. For example:\r\n\r\n    getStatusCode Http.Timeout_\r\n        == Err \"Timeout\"\r\n\r\nThese functions are primarily concerned with accessing the metadata of a response.\r\nSo, these functions will return a successful `Result` if the response is `GoodStatus_` or `BadStatus_`.\r\nOtherwise, the `Result` will be an error.\r\n\r\n[httpResponse]: https://package.elm-lang.org/packages/elm/http/2.0.0/Http#Response\r\n\r\n@docs getUrl, getStatusCode, getStatusText, getHeaders, getMetadata, getBody, isSuccess\r\n\r\n\r\n# Miscellaneous\r\n\r\n@docs State\r\n\r\n","unions":[{"name":"State","comment":" A custom type for keeping track of the state of a HTTP requests in your program's Model. This is just a suggested pattern\r\nto use in your development. It's included primarily for my own convenience - here's an example of how it would be used.\r\n\r\n    type alias Model =\r\n        { apiCats : State ( CatsResponseType, Http.Metadata ) (Http.Detailed.Error String)\r\n        }\r\n\r\n    type Msg =\r\n        APICatsResponse\r\n        | ...\r\n\r\n    init =\r\n        ( { apiCats = NotRequested }, Cmd.none )\r\n\r\n    update msg model =\r\n        case msg of\r\n            APICatsResponse httpResponse ->\r\n                case httpResponse of\r\n                    Ok (response, metadata) ->\r\n                        ( { model | apiCats = Success (response, metadata) }\r\n                        , Cmd.none )\r\n\r\n                    Err httpError ->\r\n                        ( { model | apiCats = Error httpError }\r\n                        , Cmd.none )\r\n\r\n        ...\r\n\r\n**Note:** It's been brought to my attention that this is the almost the exact same thing as the popular [RemoteData](https://package.elm-lang.org/packages/krisajenkins/remotedata/latest/) -\r\nwhen I created this package, I had never heard about RemoteData, yet I had been using the same design pattern.\r\n\r\nI will leave this type here to avoid breaking API changes, but I would recommend checking out RemoteData -\r\nit integrates fairly easily with this package. It offers a lot of handy helper functions too!\r\n\r\nTo replicate their `WebData` type, you would use something like so:\r\n\r\n    type alias WebDataDetailed err success =\r\n        RemoteData (Http.Detailed.Error err) success\r\n\r\n","args":["success","error"],"cases":[["NotRequested",[]],["Fetching",[]],["Success",["success"]],["Error",["error"]]]}],"aliases":[{"name":"Request","comment":" The type that needs to be passed into [`Http.request`](https://package.elm-lang.org/packages/elm/http/2.0.0/Http#request).\r\nIt's never actually defined as a type in [`elm/http`][http], so this is just the type definition for it.\r\n\r\n[http]: https://package.elm-lang.org/packages/elm/http/2.0.0\r\n\r\n","args":["msg"],"type":"{ method : String.String, headers : List.List Http.Header, url : String.String, body : Http.Body, expect : Http.Expect msg, timeout : Maybe.Maybe Basics.Float, tracker : Maybe.Maybe String.String }"}],"values":[{"name":"getBody","comment":" ","type":"Http.Response body -> Result.Result String.String body"},{"name":"getHeaders","comment":" ","type":"Http.Response body -> Result.Result String.String (Dict.Dict String.String String.String)"},{"name":"getMetadata","comment":" ","type":"Http.Response body -> Result.Result String.String Http.Metadata"},{"name":"getStatusCode","comment":" ","type":"Http.Response body -> Result.Result String.String Basics.Int"},{"name":"getStatusText","comment":" ","type":"Http.Response body -> Result.Result String.String String.String"},{"name":"getUrl","comment":" Note that this only tries to return the url from the metadata - it does not return the url if\r\nthe response is `BadUrl_`\r\n","type":"Http.Response body -> Result.Result String.String String.String"},{"name":"isSuccess","comment":" Returns the status code if 200 <= status code < 300\r\n","type":"Http.Response body -> Result.Result String.String Basics.Int"},{"name":"listToHeaders","comment":" Convenience function to generate a list of [`Http.Headers`](https://package.elm-lang.org/packages/elm/http/2.0.0/Http#Header)\r\nfrom a `List ( String, String )`.\r\n\r\n    listToHeaders [ ( \"Max-Forwards\", \"10\" ), ( \"Authorization\", \"Basic pw123\" ) ]\r\n        == [ Http.Header \"Max-Forwards\" \"10\", Http.Header \"Authorization\" \"Basic pw123\" ]\r\n\r\n","type":"List.List ( String.String, String.String ) -> List.List Http.Header"},{"name":"listToQuery","comment":" Convenience function to generate a [percent-encoded](https://tools.ietf.org/html/rfc3986#section-2.1)\r\nquery string from a `List ( String, String )`. The string includes the `?` at the beginning.\r\n\r\n    listToQuery [ ( \"foo\", \"abc 123\" ), ( \"bar\", \"xyz\" ) ]\r\n        == \"?foo=abc%20123&bar=xyz\"\r\n\r\n**Note:** A more appropriate place for this function would probably be a package like `Url.Extras`.\r\nHowever, such a package doesn't exist, and I use this function quite frequently, so I've included it here.\r\n\r\n","type":"List.List ( String.String, String.String ) -> String.String"},{"name":"responseToBytes","comment":" ","type":"Bytes.Decode.Decoder a -> Http.Response Bytes.Bytes -> Result.Result Http.Error a"},{"name":"responseToJson","comment":" ","type":"Json.Decode.Decoder a -> Http.Response String.String -> Result.Result Http.Error a"},{"name":"responseToString","comment":" ","type":"Http.Response String.String -> Result.Result Http.Error String.String"},{"name":"responseToWhatever","comment":" ","type":"Http.Response Bytes.Bytes -> Result.Result Http.Error ()"}],"binops":[]},{"name":"Http.Mock","comment":" **Mock an HTTP response from within Elm.**\r\n\r\n_I wrote a [guide on HTTP mocking in Elm,][Oh the Mockery]\r\nboth with and without this package. Giving it a read might help you better understand\r\nthe motivation and use cases behind this module!_\r\n\r\n---\r\n\r\nSpecify exactly what you'd like the response of an HTTP request to be.\r\nThe actual response of the HTTP request is ignored - the response will be exactly what you want to be mocked!\r\n\r\nHere's some ways this can be useful.\r\n\r\n[Oh the Mockery]: https://medium.com/@jzxhuang/oh-the-mockery-a-guide-to-http-mocking-in-elm-f625c2a56c9f\r\n\r\n\r\n# Testing your code\r\n\r\nNot sure how your code handles an HTTP request that results in a `Timeout`? Test it by mocking a Timeout response!\r\n\r\n    import Http\r\n    import Http.Mock\r\n\r\n    type Msg\r\n        = MyResponseHandler (Result Http.Error String)\r\n\r\n    testTimeout =\r\n        Http.get\r\n            { url = \"https://fakeurl.com\"\r\n            , expect = Http.Mock.expectString Http.Timeout_ MyResponseHandler\r\n            }\r\n\r\nYour update logic doesn't change - mock a `Timeout` response and make sure your application handles it correctly!\r\nNotice that we put in a dummy URL here - It doesn't matter request you make, as the response of the request will be exactly what you specify.\r\n\r\n\r\n# Mocking an API\r\n\r\nNeed to quickly mock an API locally? Don't waste time setting up a fake HTTP server for testing - just mock the response directly from within Elm!\r\n\r\n    import Http\r\n    import Http.Mock\r\n\r\n    type Msg\r\n        = MyResponseHandler (Result Http.Error String)\r\n\r\n    -- This is our mocked response.\r\n    -- You would actually put metadata and a body!\r\n\r\n    mockResponse =\r\n        Http.GoodStatus_ <metadata> <body>\r\n\r\n    sendRequestWithMockedResponse =\r\n        Http.get\r\n            { url = \"https://fakeurl.com\"\r\n            , expect = Http.Mock.expectString mockResponse MyResponseHandler\r\n            }\r\n\r\nAgain, your update logic should not change, and it doesn't matter what type of request you make -\r\nthe response is discarded and replaced with the mocked response.\r\n\r\nWhen using this module, it would be a good idea to store all your mock responses in a separate file!\r\n\r\n\r\n# Mock\r\n\r\nThe API is designed so that usage of this module is almost identical to using [elm/http][http].\r\nSimply specify exactly what you want the response to be - everything else looks the same.\r\n\r\nThe `Result` is identical to the ones in [elm/http][http]. You can use the `Transform` functions in [`Detailed`](../Http-Detailed)\r\nif you'd like the detailed responses.\r\n\r\n[http]: https://package.elm-lang.org/packages/elm/http/2.0.0\r\n\r\n@docs expectString, expectJson, expectBytes, expectWhatever, expectStringResponse, expectBytesResponse\r\n\r\n","unions":[],"aliases":[],"values":[{"name":"expectBytes","comment":" ","type":"Http.Response Bytes.Bytes -> (Result.Result Http.Error a -> msg) -> Bytes.Decode.Decoder a -> Http.Expect msg"},{"name":"expectBytesResponse","comment":" ","type":"Http.Response Bytes.Bytes -> (Result.Result x a -> msg) -> (Http.Response Bytes.Bytes -> Result.Result x a) -> Http.Expect msg"},{"name":"expectJson","comment":" ","type":"Http.Response String.String -> (Result.Result Http.Error a -> msg) -> Json.Decode.Decoder a -> Http.Expect msg"},{"name":"expectString","comment":" ","type":"Http.Response String.String -> (Result.Result Http.Error String.String -> msg) -> Http.Expect msg"},{"name":"expectStringResponse","comment":" ","type":"Http.Response String.String -> (Result.Result x a -> msg) -> (Http.Response String.String -> Result.Result x a) -> Http.Expect msg"},{"name":"expectWhatever","comment":" ","type":"Http.Response Bytes.Bytes -> (Result.Result Http.Error () -> msg) -> Http.Expect msg"}],"binops":[]}]