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, aDecimalor a number in a string. A negative value takes back usage reported by mistake.:at: when it was used, aDateTime; 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:truesends 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.
Summary
Functions
A sample %MishkaPay.Usage{} populated from defaults + type-based fallbacks.
Types
@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() | 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() | 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. |