# `Shopifex.PaymentGuard`
[🔗](https://github.com/ericdude4/shopifex/blob/main/lib/shopifex/payment_guard.ex#L1)

Context behaviour responsible for fetching and using payment grants.

# `grant`

```elixir
@type grant() :: %{
  charge_id: pos_integer(),
  grants: [String.t()],
  remaining_usages: pos_integer(),
  total_usages: pos_integer()
}
```

# `guard`

```elixir
@type guard() :: String.t()
```

# `plan`

```elixir
@type plan() :: %{
  id: String.t() | pos_integer(),
  name: String.t(),
  price: String.t(),
  type: String.t(),
  test: boolean()
}
```

# `shop`

```elixir
@type shop() :: %{access_token: String.t(), scope: String.t(), url: String.t()}
```

# `create_grant`
*optional* 

```elixir
@callback create_grant(shop :: shop(), plan :: plan(), charge_id :: pos_integer()) ::
  {:ok, any()} | {:error, any()}
```

After payment has been accepted, this function is meant to persist the
payment. Default behaviour is to create a grant schema record. `charge_id` is
the external id for the Shopify charge record.

# `get_plan`
*optional* 

```elixir
@callback get_plan(plan_id :: String.t() | pos_integer()) :: plan()
```

Gets a plan with a given identifier

# `grant_for_guard`
*optional* 

```elixir
@callback grant_for_guard(shop() | [grant()], guard()) :: grant() | nil
```

Returns a payment record which grants access to the payment guard.
Default behaviour filters where `remaining_usages` is greater than
0 or has a nil value (unlimited usage). You can also provide a list of
grants in place of the first parameter in order to avoid a trip to the
database.

# `grants_for_shop`

```elixir
@callback grants_for_shop(shop()) :: [grant()]
```

Returns a list of valid grants which are associated with the store.

# `list_available_plans_for_guard`
*optional* 

```elixir
@callback list_available_plans_for_guard(shop :: shop(), guard :: guard()) :: [plan()]
```

Get a list of plans for shop based on provided guard

# `use_grant`
*optional* 

```elixir
@callback use_grant(shop(), grant()) :: grant() | nil
```

Updates the grant to reflect the usage of it in some way. Defaults to atomically
decrementing the `remaining_usages` property if it's not nil, and incrementing
`total_usages`. If it is nil, the grant has unlimited usages and only `total_usages`
is incremented. Returns the updated grant, or `nil` if 0 rows were updated.

---

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