@spec cast_each(map(), atom() | [atom()], (any() -> any())) :: map()

Applies the given function over a list present in the data.

Provide either a single atom key or a list of atom keys whose values are lists. Each element of such a list will be mapped using the function passed.

For example, if there is a field :fee_details which is a list of maps, each containing a :type key whose value we want to cast to an atom, then we write:

data
|> cast_each(:fee_details, &cast_to_atom(&1, :type))

If a key is not set or the value is nil, no transformation occurs.

@spec cast_path(map(), [atom()], (any() -> any())) :: map()

Applies the given function to a field accessed via the path provided.

Provide a path (identical to that used by the Access protocol) to the field to be modified, and a function to be applied to its value. For example, if the field :fraud_details contains a map whose keys are :user_report and :stripe_report we wish to convert to atoms, then we write:

data
|> cast_path([:fraud_details], &cast_to_atom(&1, [:user_report, :stripe_report]))

Unlike Kernel.update_in/2, if the path to the key does not exist, or if the value is nil, then no transformation occurs.

@spec cast_to_atom(map(), atom() | [atom()]) :: map()

Cast the value of the given key or keys to an atom.

Provide either a single atom key or a list of atom keys whose values should be converted from binaries to atoms. Used commonly to convert "enum" values (values which belong to a predefined set) in Stripe responses, for example a :status field.

If a key is not set or the value is nil, no transformation occurs.

Specifies logic that transforms data from Stripe to our Stripe object.

The Stripe API docs specify that:

JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

To this end, sometimes it is desirable to make changes to the raw data received from the Stripe API, to aid its conversion into an appropriate Elixir data struct.

One example is the convention of converting "enum" values (for example "status" values of "succeeded" or "failed") into atoms instead of keeping them as strings.

This macro is used in modules implementing the Stripe.Entity behaviour in order to specify this extra logic.

Its use is optional, and the default is no transformation; i.e. the received JSON keys are merely converted to atoms and cast to the struct defined by the module.

The macro is used like this:

from_json data do
  data
  |> cast_to_atom([:type, :status])
  |> cast_each(:fee_details, &cast_to_atom(&1, :type))
end

It takes a parameter name to which the data received from Stripe is bound, and a do block which should return the transformed data. The transformation receives the JSON response from Stripe, with all keys converted to atoms (apart from keys inside a metadata map, which remain binaries) and should return a map which is ready to be cast to the struct the module defines.

The helper cast_* functions defined in this module are automatically imported into the scope of this macro.

The helper functions are all nil/missing key-safe, meaning that they will not magically add fields or error on fields which are missing or unset. You should therefore write your transformation assuming all possible data is actually present.