defmodule StarkInfra.IssuingCard do
alias __MODULE__, as: IssuingCard
alias StarkInfra.IssuingRule
alias StarkInfra.Utils.Rest
alias StarkInfra.Utils.API
alias StarkInfra.Utils.Check
alias StarkInfra.User.Project
alias StarkInfra.User.Organization
alias StarkInfra.Error
@moduledoc """
Groups IssuingCard related functions
"""
@doc """
The IssuingCard struct displays the information of the cards created in your Workspace.
Sensitive information will only be returned when the "expand" parameter is used, to avoid security concerns.
## Parameters (required):
- `:holder_name` [string]: card holder name. ex: "Tony Stark"
- `:holder_tax_id` [string]: card holder tax ID. ex: "012.345.678-90"
- `:holder_external_id` [string] card holder unique id, generated by the user to avoid duplicated holders. ex: "my-entity/123"
## Parameters (optional):
- `:display_name` [string, default nil]: card displayed name. ex: "ANTHONY STARK"
- `:rules` [list of IssuingRule, default nil]: [EXPANDABLE] list of card spending rules.
- `:bin_id` [string, default nil]: BIN ID to which the card is bound. ex: "53810200"
- `:tags` [list of strings]: list of strings for tagging. ex: ["travel", "food"]
- `:street_line_1` [string, default nil]: card holder main address. ex: "Av. Paulista, 200"
- `:street_line_2` [string, default nil]: card holder address complement. ex: "Apto. 123"
- `:district` [string]: card holder address district / neighbourhood. ex: "Bela Vista"
- `:city` [string, default nil]: card holder address city. ex: "Rio de Janeiro"
- `:state_code` [string, default nil]: card holder address state. ex: "GO"
- `:zip_code` [string]: card holder address zip code. ex: "01311-200"
## Attributes (return-only):
- `:id` [string]: unique id returned when IssuingCard is created. ex: "5656565656565656"
- `:holder_id` [string]: card holder unique id. ex: "5656565656565656"
- `:type` [string]: card type. ex: "virtual"
- `:status` [string]: current IssuingCard status. ex: "canceled" or "active"
- `:number` [string]: [EXPANDABLE] masked card number. Expand to unmask the value. ex: "123".
- `:security_code` [string]: [EXPANDABLE] masked card verification value (cvv). Expand to unmask the value. ex: "123".
- `:expiration` [string]: [EXPANDABLE] masked card expiration datetime. Expand to unmask the value. ex: '2020-03-10 10:30:00.000'.
- `:updated` [DateTime]: latest update DateTime for the IssuingCard. ex: ~U[2020-3-10 10:30:0:0]
- `:created` [DateTime]: creation datetime for the IssuingCard. ex: ~U[2020-03-10 10:30:0:0]
"""
@enforce_keys [
:holder_name,
:holder_tax_id,
:holder_external_id
]
defstruct [
:holder_name,
:holder_tax_id,
:holder_external_id,
:display_name,
:rules,
:bin_id,
:tags,
:street_line_1,
:street_line_2,
:district,
:city,
:state_code,
:zip_code,
:id,
:holder_id,
:type,
:status,
:number,
:security_code,
:expiration,
:updated,
:created
]
@type t() :: %__MODULE__{}
@doc """
Send a list of IssuingCard structs for creation in the Stark Infra API.
## Parameters (required):
- `:cards` [list of IssuingCard structs]: list of IssuingCard structs to be created in the API
## Options:
- `:expand` [list of strings, default []]: fields to expand information. ex: ["rules", "security_code", "number", "expiration"]
- `:user` [Organization/Project, default nil]: Organization or Project struct returned from StarkInfra.project(). Only necessary if default project or organization has not been set in configs.
## Return:
- list of IssuingCard structs with updated attributes
"""
@spec create(
[IssuingCard.t() | map],
expand: [binary] | nil,
user: Organization.t() | Project.t() | nil
) ::
{:ok, [IssuingCard.t()]} |
{:error, [Error.t()]}
def create(cards, options \\ []) do
Rest.post(
resource(),
cards,
options
)
end
@doc """
Same as create(), but it will unwrap the error tuple and raise in case of errors.
"""
@spec create!(
[IssuingCard.t() | map],
expand: [binary] | nil,
user: Organization.t() | Project.t() | nil
) :: any
def create!(cards, options \\ []) do
Rest.post!(
resource(),
cards,
options
)
end
@doc """
Receive a stream of IssuingCards structs previously created in the Stark Infra API.
## Options:
- `:status` [string, default nil]: filter for status of retrieved structs. ex: "paid" or "registered"
- `:types` [list of strings, default nil]: card type. ex: ["virtual"]
- `:holder_ids` [list of strings]: card holder IDs. ex: ["5656565656565656", "4545454545454545"]
- `:after` [Date or string, default nil]: date filter for structs created only after specified date. ex: ~D[2020-03-25]
- `:before` [Date or string, default nil]: date filter for structs created only before specified date. ex: ~D[2020-03-25]
- `:tags` [list of strings, default nil]: tags to filter retrieved structs. ex: ["tony", "stark"]
- `:ids` [list of strings, default nil]: list of ids to filter retrieved structs. ex: ["5656565656565656", "4545454545454545"]
- `:limit` [integer, default nil]: maximum number of structs to be retrieved. Unlimited if nil. ex: 35
- `:expand` [list of strings, default []]: fields to expand information. ex: ["rules", "security_code", "number", "expiration"]
- `:user` [Organization/Project, default nil]: Organization or Project struct returned from StarkInfra.project(). Only necessary if default project or organization has not been set in configs.
## Return:
- stream of IssuingCards structs with updated attributes
"""
@spec query(
status: binary,
types: [binary],
holder_ids: [binary],
after: Date.t() | binary,
before: Date.t() | binary,
tags: [binary],
ids: [binary],
limit: integer,
expand: [binary],
user: (Organization.t() | Project.t() | nil)
) ::
{:ok, [IssuingCard.t()]} |
{:error, [Error.t()]}
def query(options \\ []) do
Rest.get_list(
resource(),
options
)
end
@doc """
Same as query(), but it will unwrap the error tuple and raise in case of errors.
"""
@spec query!(
status: binary,
types: [binary],
holder_ids: [binary],
after: Date.t() | binary,
before: Date.t() | binary,
tags: [binary],
ids: [binary],
limit: integer,
expand: [binary],
user: (Organization.t() | Project.t() | nil)
) :: any
def query!(options \\ []) do
Rest.get_list!(
resource(),
options
)
end
@doc """
Receive a list of IssuingCards structs previously created in the Stark Infra API and the cursor to the next page.
## Options:
- `:status` [string, default nil]: filter for status of retrieved structs. ex: "paid" or "registered"
- `:types` [list of strings, default nil]: card type. ex: ["virtual"]
- `:holder_ids` [list of strings, default nil]: card holder IDs. ex: ["5656565656565656", "4545454545454545"]
- `:after` [Date or string, default nil]: date filter for structs created only after specified date. ex: ~D[2020-03-25]
- `:before` [Date or string, default nil]: date filter for structs created only before specified date. ex: ~D[2020-03-25]
- `:tags` [list of strings, default nil]: tags to filter retrieved structs. ex: ["tony", "stark"]
- `:ids` [list of strings, default nil]: list of ids to filter retrieved structs. ex: ["5656565656565656", "4545454545454545"]
- `:limit` [integer, default 100]: maximum number of structs to be retrieved. Unlimited if nil. ex: 35
- `:cursor` [string, default nil]: cursor returned on the previous page function call
- `:expand` [list of strings, default []]: fields to expand information. ex: ["rules", "security_code", "number", "expiration"]
- `:user` [Organization/Project, default nil]: Organization or Project struct returned from StarkInfra.project(). Only necessary if default project or organization has not been set in configs.
## Return:
- list of IssuingCards structs with updated attributes
- cursor to retrieve the next page of IssuingCards structs
"""
@spec page(
status: binary,
types: [binary],
holder_ids: [binary],
after: Date.t() | binary,
before: Date.t() | binary,
tags: [binary],
ids: [binary],
limit: integer,
cursor: binary,
expand: [binary],
user: (Organization.t() | Project.t() | nil)
) ::
{:ok, {binary, [IssuingCard.t()]}} |
{:error, [Error.t()]}
def page(options \\ []) do
Rest.get_page(
resource(),
options
)
end
@doc """
Same as page(), but it will unwrap the error tuple and raise in case of errors.
"""
@spec page!(
status: binary,
types: [binary],
holder_ids: [binary],
after: Date.t() | binary,
before: Date.t() | binary,
tags: [binary],
ids: [binary],
limit: integer,
cursor: binary,
expand: [binary],
user: (Organization.t() | Project.t() | nil)
) :: any
def page!(options \\ []) do
Rest.get_page!(
resource(),
options
)
end
@doc """
Receive a single IssuingCards struct previously created in the Stark Infra API by its id.
## Parameters (required):
- `:id` [string]: struct unique id. ex: "5656565656565656"
## Options:
- `:expand` [list of strings, default nil]: fields to expand information. ex: ["rules"]
- `:user` [Organization/Project, default nil]: Organization or Project struct returned from StarkInfra.project(). Only necessary if default project or organization has not been set in configs.
## Return:
- IssuingCards struct with updated attributes
"""
@spec get(
id: binary,
expand: [binary] | nil,
user: (Organization.t() | Project.t() | nil)
) ::
{:ok, IssuingCard.t()} |
{:error, [Error.t()]}
def get(id, options \\ []) do
Rest.get_id(
resource(),
id,
options
)
end
@doc """
Same as get(), but it will unwrap the error tuple and raise in case of errors.
"""
@spec get!(
id: binary,
expand: [binary] | nil,
user: (Organization.t() | Project.t() | nil)
) :: any
def get!(id, options \\ []) do
Rest.get_id!(
resource(),
id,
options
)
end
@doc """
Update an IssuingCard by passing id.
## Parameters (required):
- `:id` [string]: IssuingCard id. ex: '5656565656565656'
## Parameters (Optional):
- `:status` [string]: You may block the IssuingCard by passing 'blocked' in the status
- `:display_name` [string, default nil]: card displayed name
- `:rules` [list of dictionaries, default nil]: list of dictionaries with "amount": int, "currencyCode": string, "id": string, "interval": string, "name": string pairs.
- `:tags` [list of strings, default nil]: list of strings for tagging
- `:user` [Organization/Project, default nil]: Organization or Project struct returned from StarkInfra.project(). Only necessary if default project or organization has not been set in configs.
## Return:
- target IssuingCard with updated attributes
"""
@spec update(
id: binary,
status: binary,
display_name: binary,
rules: [IssuingRule.t()],
tags: [binary],
user: (Organization.t() | Project.t() | nil)
) ::
{:ok, IssuingCard.t()} |
{:error, [Error.t()]}
def update(id, parameters \\ []) do
Rest.patch_id(
resource(),
id,
parameters
)
end
@doc """
Same as update(), but it will unwrap the error tuple and raise in case of errors.
"""
@spec update!(
id: binary,
status: binary,
display_name: binary,
rules: [IssuingRule.t()],
tags: [binary],
user: (Organization.t() | Project.t() | nil)
) :: any
def update!(id, parameters \\ []) do
Rest.patch_id!(
resource(),
id,
parameters
)
end
@doc """
Cancel an IssuingCard entity previously created in the Stark Infra API.
## Parameters (required):
- `:id` [string]: IssuingCard unique id. ex: "5656565656565656"
## Options:
- `:user` [Organization/Project, default nil]: Organization or Project struct returned from StarkInfra.project(). Only necessary if default project or organization has not been set in configs.
## Return:
- canceled IssuingCard struct
"""
@spec cancel(
id: binary,
user: (Organization.t() | Project.t() | nil)
) ::
{:ok, IssuingCard.t()} |
{:error, [Error.t()]}
def cancel(id, options \\ []) do
Rest.delete_id(
resource(),
id,
options
)
end
@doc """
Same as cancel(), but it will unwrap the error tuple and raise in case of errors.
"""
@spec cancel!(
id: binary,
user: (Organization.t() | Project.t() | nil)
) :: any
def cancel!(id, options \\ []) do
Rest.delete_id!(
resource(),
id,
options
)
end
@doc false
def resource() do
{
"IssuingCard",
&resource_maker/1
}
end
@doc false
def resource_maker(json) do
%IssuingCard{
holder_name: json[:holder_name],
holder_tax_id: json[:holder_tax_id],
holder_external_id: json[:holder_external_id],
display_name: json[:display_name],
bin_id: json[:bin_id],
tags: json[:tags],
street_line_1: json[:street_line_1],
street_line_2: json[:street_line_2],
district: json[:district],
city: json[:city],
state_code: json[:state_code],
zip_code: json[:zip_code],
rules: json[:rules] |> Enum.map(fn rule -> API.from_api_json(rule, &IssuingRule.resource_maker/1) end),
id: json[:id],
holder_id: json[:holder_id],
type: json[:type],
status: json[:status],
number: json[:number],
security_code: json[:security_code],
expiration: json[:expiration],
updated: json[:updated] |> Check.datetime(),
created: json[:created] |> Check.datetime()
}
end
end
