API inventory

Everything Aurora Meter Pro offers a host application, with a stability class per entry. It is the authority for what the support policy covers: see Support policy.

If something is not on this page, it is not part of the supported surface, even when the module or function happens to be public in the compiled code.

test/aurora_meter/pro/api_inventory_test.exs checks this page against the code on every mix test. Every Module.function/arity below must exist, no internal module may be listed, every telemetry event and PubSub tag must appear verbatim in lib/, and the core version requirement in section 12 must match mix.exs.

Aurora Meter Pro is a commercial package. The free core has an inventory of its own, and this page never restates it: core entries are core’s promise, not Pro’s.

How to read this page

Since is the package version that introduced the entry. Pro 0.4.0 was never published, so everything written for it carries 1.0.0, the release that shipped it.

Test helpers (AuroraMeter.Pro.Stripe.Fake, AuroraMeter.Pro.Credits.StripeClient.Fake) are stable, but they are for host test suites. Nothing in production should depend on them, and the support policy governs them under its own heading rather than by SemVer on every helper name.

1. Facade functions

1.1 AuroraMeter.Pro

1.2 Prepaid credit top-ups

Pro sells credit; the core ledger holds it. Every grant goes through AuroraMeter.Credits.grant/3 keyed on the Stripe PaymentIntent id, so two deliveries of one payment fund the account exactly once.

1.3 Subscriptions, checkout and the webhook

AuroraMeter.Pro.Webhook is also a Plug (stable since 0.1.0; :path since 1.2.0). Mount it in the endpoint, above Plug.Parsers, because the signature is over the raw body: plug AuroraMeter.Pro.Webhook, path: "/webhooks/stripe". With :path it handles only a POST to exactly that path and passes every other request through untouched; a :path that is not a string starting with / raises ArgumentError at init/1. Without :path every request that reaches it is treated as a Stripe event, which suits only a pipeline that sees nothing else. A router forward cannot work: it runs after the endpoint’s parsers have consumed the body. handle_event/1 answers {:refused, :untenanted_subscription} (since 1.2.0) for a subscription event whose subscription carries no tenant_key metadata; the plug turns it into a 200.

1.4 Usage reporting, reconciliation, rollups and export

1.5 Alerts

1.6 Request audit log

AuroraMeter.Pro.Plugs.AuditLog is the Plug. Everything host-shaped arrives as a resolver function of the conn (:tenant, :actor, :metadata), so the package never guesses at a host’s schema. A :tenant resolver returning nil skips the write, which is how unauthenticated requests stay out of the log: put the plug after your authentication, not before.

1.7 Dashboard

1.8 Configuration accessors

1.9 The source cutover

Moving a feature from buffered reporting to event reporting, once, at a period boundary. The reporter stages a buffered window only while period_start < w and the outbox accepts an event only while period_start >= w, so a period belongs to exactly one path. See the cutover guide.

1.10 Guarded recovery

What an operator may do to a financial record that is stuck. Every mutation takes the subject first and one keyword list second, carrying expected: (the state the operator believes they are acting on), reason: and evidence:. A mutation writes exactly one aurora_meter_recovery_actions row whether it applies or refuses. There is no force: option. Nothing here calls a provider. See Recovery.

1.11 Periods and migrations

AuroraMeter.Pro.Period implements the whole AuroraMeter.Period behaviour. Configure it with config :aurora_meter, period_source: AuroraMeter.Pro.Period; c:AuroraMeter.Period.current/2 is a callback and is not called directly.

1.12 Telemetry

The Pro event catalogue as data, and the Telemetry.Metrics presets over it. The tag rules themselves are core’s: see AuroraMeter.Telemetry.tag_allow_list/0 and Telemetry.

1.13 AuroraMeter.Pro.Telemetry.Metrics (optional dependency)

Without telemetry_metrics installed the module is not defined at all. Every Pro event is still emitted and AuroraMeter.Pro.Telemetry still works.

1.14 AuroraMeter.Pro.LiveDashboard.Page (optional dependency)

A Phoenix.LiveDashboard page for Pro’s commercial operations: the export backlog, uncertain and quarantined items, leases, open reconciliation differences, pending payments, the recovery audit trail and the provider mapping.

:authorized_by is required and there is no default. This page refuses authorized_by: :host_route, which AuroraMeter.LiveDashboard.Page accepts: every section here renders tenant keys, subject references and payment state, and “the route is authenticated” is not a basis for showing one customer’s payment state to whoever reached the dashboard. The accepted forms are in AuroraMeter.LiveDashboard.Auth.

The page is read-only. It renders the recovery audit trail and the exact AuroraMeter.Pro.Recovery call to paste, and ships no button that performs one: those mutations require an expected: map and an evidence: string that a one-click button cannot supply honestly.

2. Behaviours and their callbacks

Pro implements two core behaviours:

3. Structs and public types

Named types a host will meet in a spec: t:AuroraMeter.Pro.AuditLog.event/0, t:AuroraMeter.Pro.AuditLog.page/0, t:AuroraMeter.Pro.AuditLog.stats/0 and t:AuroraMeter.Pro.AuditLog.status_class/0, t:AuroraMeter.Pro.Credits.AutoTopUpWorker.skip/0, and t:AuroraMeter.Pro.Subscriptions.result/0.

4. Return values and error tuples

Pro returns {:ok, value} | {:error, reason} almost everywhere, and the two places it does not are worth knowing.

• AuroraMeter.Pro.Credits.AutoTopUpWorker.attempt/2 has a third outcome, {:skip, reason}: the guards said no (no account, disabled, no saved payment method, still inside the cooldown, balance already above the threshold). A skip is not a failure and does not count against :auto_top_up_max_failures.
• AuroraMeter.Pro.Reconcile.run/1 returns %{local_drift: [drift], items_open: integer}. There is no :ok wrapper, because a map with two keys is the answer. It returned a bare list before 1.0.0.
• AuroraMeter.Pro.Recovery‘s mutations return {:error, {:expected_state_mismatch, current}} where current holds the present values of exactly the keys the caller claimed, so the call can be re-issued from the refusal itself. The other refusals are {:missing_evidence, :reason | :evidence | :provider_ref}, :not_found, :intent_known, :not_a_payment_intent, :mapping_changed, {:still_ineligible, check}, :staged_link_changed, :not_scheduled, :in_the_past, :not_a_period_start and {:already_effective, counts}. A missing expected:, reason: or evidence: raises: it is a call that never reached the API’s semantics, and it is the one failure that writes no audit row.

Money crosses the provider boundary in minor units (amount_cents), and lives in the core ledger in micro-dollars. Every Pro entry that names an amount says which. AuroraMeter.Credits.Money converts, and nothing rounds inside a transaction.

Idempotency keys: Pro keys a credit grant on the Stripe PaymentIntent id and passes it to the core ledger as reference:. A charge carries a Stripe idempotency key of its own, stored on the account row, so a retried charge is one charge at Stripe as well as one grant locally.

A webhook handler that returns {:error, reason} makes the plug answer 500, so Stripe retries the event. That is deliberate: a top-up whose grant failed on a transient database error must not be dropped.

5. Configuration keys

Read from the :aurora_meter_pro application environment. {:system, "VAR"} is accepted wherever the notes say so, and is resolved at read time.

Every key above is declared in a schema and validated once, by AuroraMeter.Pro.validate!/0, which AuroraMeter.Pro runs from the host’s supervision tree. {:system, "VAR"} is resolved at validation, not at read time: a variable unset after boot no longer changes what a running node does. An unknown key logs a warning in this release and stops the boot in 1.0.

A host that does not add AuroraMeter.Pro to its tree keeps working: the first accessor validates lazily and logs one warning naming the module. If that lazy validation fails it is logged and the raw value is used, rather than raised: a configuration problem belongs at boot, not on a metering call with money in flight.

6. Telemetry events

The Matched in lib/ column holds the exact source text the inventory test greps for, so a renamed event fails the build.

Three of the four sit in the core’s [:aurora_meter, ...] namespace without being core events, and the core’s telemetry guide does not list them, because the core does not know Pro exists. This page is where a host attaching handlers reads them. New Pro events use the [:aurora_meter, :pro, ...] prefix; the three historical names are kept, because renaming them would silently detach every handler already attached.

tenant_key is metadata, never a metric tag: the cardinality is unbounded. The closed set of names a metric may tag on is core’s AuroraMeter.Telemetry.tag_allow_list/0, stated once there rather than twice; AuroraMeter.Pro.Telemetry.events/0 names the tags each event offers, and Telemetry gives the reason for each.

[:aurora_meter, :pro, :retention, :prune] is listed here since 1.0.0, the release that first emitted it. It is emitted through a module attribute, and the guard that checks this page against lib/ matched only a literal event name, so the event could not be found and could not be documented without failing that guard. The guard now reads the parsed source.

7. PubSub messages

Aurora Meter Pro broadcasts nothing. There is no Pro PubSub message and no Pro topic. Live usage and credit balance updates come from the core (AuroraMeter.Broadcaster.topic/1 and AuroraMeter.Credits.topic/1), which is what AuroraMeter.Pro.Live.Dashboard subscribes to.

8. Mix tasks

9. Migration entry points

Section 1.9 lists them. The schema-version contract is the core’s, restated: versions are additive during 1.x, every version is idempotent, and a host calls them from its own Ecto migration. Pro schema version 11 pairs with core schema version 10 in this release, and the two migrations must both run.

10. Test helpers

Supported, and shipped in the Hex tarball, so a host test suite may depend on them. They are governed by the test-helper heading of the support policy rather than by SemVer on every name, and nothing in production should call them.

11. Internal modules

Not part of the supported surface. Each carries a stability banner at the top of its module docs where it has module docs at all, and each renders under the “Internal” group in the generated documentation.

The inventory test holds this list as a module attribute and fails when a module on it appears anywhere in the tables above, and when this list and the groups_for_modules “Internal” group in mix.exs disagree.

A function carrying @doc false inside any module is internal for the same reason, whether or not its module is on this list. That includes every Oban.Worker callback (perform/1, new/2, backoff/1, timeout/1), every Plug callback (init/1, call/2), every Phoenix.LiveView callback, and every AuroraMeter.Billing.Provider and AuroraMeter.Pro.Credits.StripeClient callback implementation. Call the named entry point instead: report_all/0 rather than perform/1.

12. Core dependency

Pro consumes the free core through its public API only. It never copies a core schema definition, and the core never references Pro.

The core entries Pro relies on, all of them stable in the core’s own inventory: the facade (usage/2, usage_all/1, history/3, period/1, plan/1, quota/2, check/2, entitled?/2, feature_value/3); AuroraMeter.Storage.load_counter/3, get_subscription/1, put_subscription/1, load_history_range/4 and stream_counters/1; everything in AuroraMeter.Credits and AuroraMeter.Credits.Money; AuroraMeter.Plans.get/1 and AuroraMeter.Plan; AuroraMeter.Subscriptions.get/1 and invalidate/1; AuroraMeter.Period.current!/2; AuroraMeter.Clock.now/0 and db_now/0; AuroraMeter.Flusher.flush/0; AuroraMeter.Test; and the behaviours AuroraMeter.Billing.Provider and AuroraMeter.Period.

12.1 Direct core-table reads that remain

Two places still build an Ecto query against a core schema module rather than going through a core function. They are recorded here because an undocumented coupling is worse than a documented one, and recording them is not endorsing them: each is internal and each is scheduled for removal. Until then, a core schema change can break Pro in a way the core’s own inventory does not warn about.

The alerts sweep’s is gone as of 1.0.0: it walks AuroraMeter.Storage.list_subscriptions/2 in pages instead, which also stops it loading every subscription in the installation into one list. Pro’s lib/ now builds no query against AuroraMeter.Schema.Subscription at all.

The usage reporter’s two are gone as of 1.0.0: subscriptions come from AuroraMeter.Storage.list_subscriptions/2 and counters from AuroraMeter.Storage.load_counter/3. The file still names AuroraMeter.Schema.Subscription, and that is not coupling: it calls entitled?/1 and entitled_statuses/0, which are pure functions over a struct the core hands back. See the note at the end of this section.

The inventory test asserts each of these is still there, by matching the query text rather than a line number, so the list cannot quietly rot before the work lands.

The “Replaced by” column is plain text rather than code, because the core functions it names do not exist yet. A code span would make mix docs warn on every build, which is how a real broken reference gets missed.

Reading a core struct is not on this list and is not coupling: the schema modules are public structs in the core’s inventory. What is recorded here is building a query against one.