# `MishkaPay.Usage`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/lib/mishka_pay/usage.ex#L5)

One report of what a customer used, sent with `MishkaPay.report_usage/1` to the
`MishkaPay.Meter` that counts its `:event_name`. A price on that meter bills it at the end of
the period. A guarded_struct.

What the caller gives:

  * `:provider`, `:tenant`: which provider, with whose keys.
  * `:event_name`: the meter's event name.
  * `:customer_id`: the provider customer who used it (`MishkaPay.create_customer/1`).
  * `:value`: how much, 1 by default: an integer, a `Decimal` or a number in a string. A
    negative value takes back usage reported by mistake.
  * `:at`: when it was used, a `DateTime`; now when left out.
  * `:reference`: the caller's own id for this use, such as a request id. It makes the
    provider's id of the report and its idempotency key, so the same reference never counts
    twice.
  * `:stream`: `true` sends the report through the provider's path for high volume (Stripe's
    meter event stream, up to 10,000 reports a second in live mode). The provider checks
    such a report after it answers, so a report it cannot count (an unknown customer or event
    name) is not refused in the answer: it comes back later as the provider's error event.
    `false` (the default) sends it the usual way, checked before the answer.

What the provider fills in: `:id`, its own id of the report.

# `t`

```elixir
@type t() :: %MishkaPay.Usage{
  at: DateTime.t() | nil,
  cancellation: MishkaPay.Usage.Cancellation.t() | nil,
  customer_id: String.t(),
  event_name: String.t(),
  id: String.t() | nil,
  provider: String.t(),
  reference: String.t() | nil,
  stream: boolean() | nil,
  summary: MishkaPay.Usage.Summary.t() | nil,
  tenant: term() | nil,
  value: (integer() | Decimal.t()) | nil
}
```

The struct that `builder/1` returns.

| Field | Type | Required | Default | Description | Derives |
| --- | --- | --- | --- | --- | --- |
| `:provider` | `String.t()` | yes |  |  | `sanitize(trim) validate(not_nil_value, string, not_empty)` |
| `:tenant` | `term()` \| `nil` | no |  |  |  |
| `:event_name` | `String.t()` | yes |  |  | `sanitize(trim) validate(not_nil_value, string, not_empty, max_len=100)` |
| `:customer_id` | `String.t()` | yes |  |  | `sanitize(trim) validate(not_nil_value, string, not_empty)` |
| `:value` | `integer()` \| `Decimal.t()` \| `nil` | no | `1` |  | validator `{MishkaPay.Usage, :value}` |
| `:at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:reference` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=200)` |
| `:stream` | `boolean()` \| `nil` | no | `false` |  | `validate(not_nil_value, boolean)` |
| `:id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:summary` | [`MishkaPay.Usage.Summary.t()`](`t:MishkaPay.Usage.Summary.t/0`) \| `nil` | no |  | What a meter counted for one customer over a window of time, read with `MishkaPay.usage_summary/6`. A guarded_struct the provider fills in. |  |
| `:cancellation` | [`MishkaPay.Usage.Cancellation.t()`](`t:MishkaPay.Usage.Cancellation.t/0`) \| `nil` | no |  | Takes back one usage report sent by mistake, with `MishkaPay.cancel_usage/1`: the meter then counts it as if it was never reported. A guarded_struct. |  |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

---

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