# `MishkaPay.Client`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/lib/mishka_pay/client.ex#L5)

The HTTP base every provider adapter builds on, over Req. A request is described as this
guarded_struct and sent with `request/1`:

    MishkaPay.Client.request(%{
      provider: "stripe",
      method: :post,
      base_url: "https://api.stripe.com",
      path: "/v1/refunds",
      auth: {:bearer, keys.secret_key},
      headers: %{"stripe-version" => "2026-10-28"},
      form: [payment_intent: "pi_123"],
      idempotency_header: "idempotency-key"
    })

What every provider gets from it:

  * **Retries.** A network error and the answers 408, 429, 500, 502, 503 and 504 are tried again,
    `max_retries` times (2 by default). The wait is what a whole-second `Retry-After` header says,
    or `retry_delay` milliseconds (500 by default) doubled on each try, and never more than
    `max_wait` milliseconds (ten seconds by default). A write (`post`, `put`, `patch`, `delete`) is tried again only when the provider takes
    an idempotency key, so a payment is never made twice.
  * **The provider's own word on a retry.** With `retry_header` set (Stripe's
    `"stripe-should-retry"`), an answer carrying it decides: `true` tries again even a status
    that is not on the list above (a lock held a moment too long), `false` never tries again.
    A write without its idempotency key is still never sent twice.
  * **Why the rate was limited.** With `limit_header` set (Stripe's
    `"stripe-rate-limited-reason"`), its value is the `:rate_limit_reason` of the telemetry
    below, so a site can tell a burst of its own from a limit on one endpoint.
  * **One idempotency key per call.** When `idempotency_header` is set, a write carries the key in
    that header: `idempotency_key` when the caller gives one (derived from its own operation, so a
    repeated call is the same call), a random one otherwise. Every retry sends the same key.
  * **Telemetry.** `[:mishka_pay, :request, :start | :stop | :exception]`, with `:provider`,
    `:method`, `:path` and `:idempotency_key`, and `:status` on `:stop`; and
    `[:mishka_pay, :request, :retry]` before each retry, with the `:wait` in milliseconds, the
    `:attempt`, the `:status` or network `:reason`, the `:retry_after` the provider asked
    for and its `:rate_limit_reason`. `:stop` carries the `:rate_limit_reason` of the last
    answer too (`nil` when it gave none). Never a key or a body.

`request/1` answers `{:ok, %Req.Response{}}` for any HTTP status: the adapter reads its
provider's own error body. A request that never got an answer is a
`MishkaPay.Errors.Unreachable` error, and a description that is not valid an `:invalid` one.
`inspect/1` leaves out `:auth`. `headers`, `params`, `form` and `json` reach the provider as
given: their keys are never turned into atoms.

`base_url` is an `http` or `https` address with no user, query or fragment, and `path` one plain
path from `/`: no query (`params` carries it), no control character, dot segment or encoded
slash. So a path can never send the request, and its auth, to another host or place.
Header names are compared without case.

The body is one of `form`, `json`, `json_text` or `multipart`. `json_text` is a JSON document
already encoded, sent byte for byte: for a provider that checks a message it signed against the
exact bytes it sent, such as PayPal's webhook verification. `multipart` sends `multipart/form-data`, the
way a file is uploaded: a list of `{name, value}` parts, where a value is a binary, or
`{binary, filename: "receipt.pdf", content_type: "application/pdf"}` for a file. A value is
always bytes in memory, never a path or a stream, so a request never reads a file from disk.

`:options` takes any other Req option, such as `plug: {Req.Test, MyTest}` in a test, on top of
`config :mishka_pay, req_options: [...]` (see `MishkaPay.Test.stub_http/1`). It cannot
change what this module decides: the method, address, headers, auth, body, retries and timeout.

# `t`

```elixir
@type t() :: %MishkaPay.Client{
  auth: term() | nil,
  base_url: String.t(),
  form: (map() | keyword()) | nil,
  headers: map() | nil,
  idempotency_header: String.t() | nil,
  idempotency_key: String.t() | nil,
  json: (map() | list()) | nil,
  json_text: String.t() | nil,
  limit_header: String.t() | nil,
  max_retries: non_neg_integer() | nil,
  max_wait: non_neg_integer() | nil,
  method: (:get | :post | :put | :patch | :delete) | nil,
  multipart: term() | nil,
  options: keyword() | nil,
  params: (map() | keyword()) | nil,
  path: String.t(),
  provider: String.t(),
  receive_timeout: pos_integer() | nil,
  retry_delay: non_neg_integer() | nil,
  retry_header: String.t() | nil
}
```

The struct that `builder/1` returns.

| Field | Type | Required | Default | Description | Derives |
| --- | --- | --- | --- | --- | --- |
| `:provider` | `String.t()` | yes |  |  | `validate(not_nil_value, string, not_empty)` |
| `:method` | `:get` \| `:post` \| `:put` \| `:patch` \| `:delete` \| `nil` | no | `:get` |  | `validate(not_nil_value, enum=Atom[get::post::put::patch::delete])` |
| `:base_url` | `String.t()` | yes |  |  | `sanitize(trim) validate(not_nil_value, string, not_empty)`<br>validator `{MishkaPay.Client, :base_url}` |
| `:path` | `String.t()` | yes |  |  | `validate(not_nil_value, string, not_empty)`<br>validator `{MishkaPay.Client, :path}` |
| `:auth` | `term()` \| `nil` | no |  |  |  |
| `:headers` | `map()` \| `nil` | no | `%{}` |  | `validate(map)` |
| `:params` | `map()` \| `keyword()` \| `nil` | no |  |  | `validate(either=[map, list])`<br>validator `{MishkaPay.Client, :params}` |
| `:form` | `map()` \| `keyword()` \| `nil` | no |  |  | `validate(either=[map, list])` |
| `:json` | `map()` \| `list()` \| `nil` | no |  |  | `validate(either=[map, list])` |
| `:json_text` | `String.t()` \| `nil` | no |  |  | `validate(string, not_empty)` |
| `:multipart` | `term()` \| `nil` | no |  |  | validator `{MishkaPay.Client, :multipart}` |
| `:idempotency_header` | `String.t()` \| `nil` | no |  |  | `sanitize(trim, downcase) validate(string, not_empty)` |
| `:idempotency_key` | `String.t()` \| `nil` | no |  |  | `validate(string, not_empty)` |
| `:retry_header` | `String.t()` \| `nil` | no |  |  | `sanitize(trim, downcase) validate(string, not_empty)` |
| `:limit_header` | `String.t()` \| `nil` | no |  |  | `sanitize(trim, downcase) validate(string, not_empty)` |
| `:max_retries` | `non_neg_integer()` \| `nil` | no | `2` |  | `validate(integer, min_len=0)` |
| `:retry_delay` | `non_neg_integer()` \| `nil` | no | `500` |  | `validate(integer, min_len=0)` |
| `:max_wait` | `non_neg_integer()` \| `nil` | no | `10000` |  | `validate(integer, min_len=0)` |
| `:receive_timeout` | `pos_integer()` \| `nil` | no | `30000` |  | `validate(integer, min_len=1)` |
| `:options` | `keyword()` \| `nil` | no | `[]` |  | `validate(list)` |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

A sample %MishkaPay.Client{} populated from defaults + type-based fallbacks.

# `keys`

# `keys`

# `request`

```elixir
@spec request(map()) :: {:ok, Req.Response.t()} | {:error, Splode.Error.t()}
```

Sends the request `attrs` describe. See the module doc for what it answers.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
