@spec check(channel_id :: binary(), account_id :: binary()) ::
  :ok | {:rate_limited, non_neg_integer()}

Check if a message can be sent (non-consuming check for initial queue decision).

Returns :ok if allowed, {:rate_limited, wait_ms} if rate limited. This does NOT consume a token - use consume/2 for that.

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec consume(channel_id :: binary(), account_id :: binary()) ::
  :ok | {:rate_limited, non_neg_integer()}

Atomically check and consume a rate limit token.

Returns :ok if token was consumed, {:rate_limited, wait_ms} if rate limited. This is the primary function to use when actually sending a message.

@spec record(channel_id :: binary(), account_id :: binary()) :: :ok

Record that a message was sent (decrements token count).

@spec status(channel_id :: binary(), account_id :: binary()) :: map()

Get the current rate limit status for a channel/account.