View Source Stripe.Request (stripity_stripe v3.2.0)

A module for working with requests to the Stripe API.

Requests are composed in a functional manner. The request does not happen until it is configured and passed to make_request/1.

Currently encompasses only requests to the normal Stripe API. The OAuth endpoint is not yet supported.

Generally intended to be used internally, but can also be used by end-users to work around missing endpoints (if any).

At a minimum, a request must have the endpoint and method specified to be valid.

Summary

Functions

cast_path_to_id(request, new_cast_to_id)

Specify that a given path in the parameters should be cast to a simple ID.

cast_to_id(request, new_cast_to_id)

Specify that a given set of parameters should be cast to a simple ID.

get_id!(id)

Normalise the argument to a simple Stripe ID.

make_file_upload_request(request)

Executes the request and returns the response for file uploads

make_request(request)

Executes the request and returns the response.

new_request(opts \\ [], headers \\ %{})

Creates a new request.

prefix_expansions(request)

Prefixes all :expand values provided in opts with the given prefix.

put_endpoint(request, endpoint)

Specifies an endpoint for the request.

put_method(request, method)

Specifies a method to use for the request.

put_param(request, key, value)

Specify a single param to be included in the request.

put_params(request, new_params)

Specifies the parameters to be used for the request.

Types

error_code()

@type error_code() :: :endpoint_fun_invalid_result | :invalid_endpoint

t()

@type t() :: %Stripe.Request{
  cast_to_id: MapSet.t(),
  endpoint: String.t() | nil,
  headers: map() | nil,
  method: Stripe.API.method() | nil,
  opts: Keyword.t() | nil,
  params: map()
}

Functions

cast_path_to_id(request, new_cast_to_id)

@spec cast_path_to_id(t(), [atom()]) :: t()

Specify that a given path in the parameters should be cast to a simple ID.

Acts similar to cast_to_id/2 but specifies only one parameter to be cast, by specifying its path (as in the Access protocol). Used to cast nested objects to their IDs.

cast_to_id(request, new_cast_to_id)

@spec cast_to_id(t(), [atom()]) :: t()

Specify that a given set of parameters should be cast to a simple ID.

Sometimes, it may be convenient to allow end-users to pass in structs (say, the card to charge) but the API requires only the ID of the object. This function will ensure that before the request is made, the parameters specified here will be cast to IDs – if the value of a parameter is a struct with an :id field, the value of that field will replace the struct in the parameter list.

If the function is called multiple times, the set of parameters to cast to ID is merged between the multiple calls.

get_id!(id)

@spec get_id!(Stripe.id() | struct()) :: Stripe.id()

Normalise the argument to a simple Stripe ID.

Actively extracts the ID, given a struct with an :id field, or returns the binary if one is passed in.

Useful for eagerly getting the ID of an object passed in, for example when computing the endpoint to use:

def capture(id, params, opts) do
  new_request(opts)
  |> put_endpoint(@plural_endpoint <> "/#{get_id!(id)}/capture")
  ...

make_file_upload_request(request)

@spec make_file_upload_request(t()) :: {:ok, struct()} | {:error, Stripe.Error.t()}

Executes the request and returns the response for file uploads

make_request(request)

@spec make_request(t()) :: {:ok, struct()} | {:error, Stripe.Error.t()}

Executes the request and returns the response.

new_request(opts \\ [], headers \\ %{})

@spec new_request(Stripe.options(), map()) :: t()

Creates a new request.

Optionally accepts options for the request, such as using a specific API key. See t:Stripe.options for details.

prefix_expansions(request)

@spec prefix_expansions(t()) :: t()

Prefixes all :expand values provided in opts with the given prefix.

When using object expansion on a list function for a resource, the values must be prefixed with data.. This is required because the stripe api nests the returned objects within data: {}.

For all create, update, cancel and retrieve functions this is not required.

opts = [expand: ["balance_transaction"]]
request = prefix_expansions(%Request{opts: opts})

request.opts == ["data.balance_transaction"]

put_endpoint(request, endpoint)

@spec put_endpoint(t(), String.t()) :: t()

Specifies an endpoint for the request.

The endpoint should not include the v1 prefix or an initial slash, for example put_endpoint(request, "charges").

The endpoint can be a binary or a function which takes the parameters of the query and returns an endpoint. The function is not evaluated until just before the request is made so the actual parameters can be specified after the endpoint.

put_method(request, method)

@spec put_method(t(), Stripe.API.method()) :: t()

Specifies a method to use for the request.

Accepts any of the standard HTTP methods as atoms, that is :get, :post, :put, :patch or :delete.

put_param(request, key, value)

@spec put_param(t(), atom(), any()) :: t()

Specify a single param to be included in the request.

put_params(request, new_params)

@spec put_params(t(), list()) :: t()

@spec put_params(t(), map()) :: t()

Specifies the parameters to be used for the request.

If the request is a POST request, these are encoded in the request body. Otherwise, they are encoded in the URL.

Calling this function multiple times will merge, not replace, the params currently specified.