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

One call to a provider's own API that Mishka Pay has no typed call for yet, sent with
`MishkaPay.request/1`. A guarded_struct.

  * `:provider`, `:tenant`: which provider, with whose keys.
  * `:method`: `:get` (the default), `:post`, `:put`, `:patch` or `:delete`.
  * `:path`: the provider's API path from the root, such as `"/v1/balance"` at Stripe or
    `"/v2/checkout/orders/5O190127TN364715T"` at PayPal: one plain path, never an address. A
    scheme or host (`"https://evil.test/x"`, `"//evil.test"`), a dot segment (`".."`), a
    query, a backslash, a control character or an encoded slash is refused before any request,
    so a call can never take the tenant's keys to another host or place.
  * `:params`: a map or a keyword list, nested as the provider takes it: the query of a `:get`,
    the body of a write (Stripe's form encoding, `%{"metadata" => %{"a" => "b"}}` as
    `metadata[a]=b`; PayPal's JSON). They reach the provider as given: their keys are never
    turned into atoms.
  * `:reference`: the caller's own id for a write. With the method and path it makes the
    idempotency key, so the same call sent again is one call at the provider; without it, a
    write gets a fresh key that each of its retries reuses.
  * `:options`: a `MishkaPay.RawRequest.Options`: another API version and the objects to expand.

## Options

`:options` is a `MishkaPay.RawRequest.Options`, a sub_field of this struct: what the request
asks of the provider beyond its path and params.

  * `:api_version`: the provider's API version to answer in, in place of the one its adapter
    pins (Stripe: `"2026-10-28.endive"`, sent as `Stripe-Version`). Letters, digits, `.`, `-`
    and `_` only.
  * `:expand`: the related objects to send whole instead of by id, each a dotted path such as
    `"customer"` or `"data.latest_charge"`, at most four levels deep (Stripe's limit), up to 20.

They are only ever turned into the provider's own version header and `expand` params: there is
no field for a header, so a request option can never change the auth or the idempotency key.
A provider that has no such thing refuses an option it cannot send, before any request.

The typed calls (`MishkaPay.fetch_payment/3` and the rest) take none of them: each reads the
answer in the version its adapter pins, and a struct has no field for an object it did not
ask for.

# `t`

```elixir
@type t() :: %MishkaPay.RawRequest{
  method: (:get | :post | :put | :patch | :delete) | nil,
  options: MishkaPay.RawRequest.Options.t() | nil,
  params: (map() | keyword()) | nil,
  path: String.t(),
  provider: String.t(),
  reference: String.t() | nil,
  tenant: term() | nil
}
```

The struct that `builder/1` returns.

| Field | Type | Required | Default | Description | Derives |
| --- | --- | --- | --- | --- | --- |
| `:provider` | `String.t()` | yes |  |  | `sanitize(trim) validate(not_nil_value, string, not_empty)` |
| `:tenant` | `term()` \| `nil` | no |  |  |  |
| `:method` | `:get` \| `:post` \| `:put` \| `:patch` \| `:delete` \| `nil` | no | `:get` |  | `validate(not_nil_value, enum=Atom[get::post::put::patch::delete])`<br>validator `{MishkaPay.RawRequest, :method}` |
| `:path` | `String.t()` | yes |  |  | `validate(not_nil_value, string, not_empty)`<br>validator `{MishkaPay.Client, :path}` |
| `:params` | `map()` \| `keyword()` \| `nil` | no |  |  | `validate(either=[map, list])` |
| `:reference` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=200)` |
| `:options` | [`MishkaPay.RawRequest.Options.t()`](`t:MishkaPay.RawRequest.Options.t/0`) \| `nil` | no |  |  |  |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `idempotency_key`

```elixir
@spec idempotency_key(t()) :: String.t() | nil
```

The idempotency key of `call`: its reference with its method and path, so the same reference
on another path is another call. `nil` without a reference.

# `keys`

# `keys`

---

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