MishkaPay.RawRequest (Mishka Pay v0.0.1)

Copy Markdown View Source

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.

Summary

Types

t()

The struct that builder/1 returns.

Functions

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

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.

Types

t()

@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.

FieldTypeRequiredDefaultDescriptionDerives
:providerString.t()yessanitize(trim) validate(not_nil_value, string, not_empty)
:tenantterm() | nilno
:method:get | :post | :put | :patch | :delete | nilno:getvalidate(not_nil_value, enum=Atom[get::post::put::patch::delete])<br>validator {MishkaPay.RawRequest, :method}
:pathString.t()yesvalidate(not_nil_value, string, not_empty)<br>validator {MishkaPay.Client, :path}
:paramsmap() | keyword() | nilnovalidate(either=[map, list])
:referenceString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=200)
:optionsMishkaPay.RawRequest.Options.t() | nilno

Functions

builder(attrs_or_input, error \\ false)

enforce_keys()

enforce_keys(field)

example()

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

idempotency_key(call)

@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(field)