Metering

Documentation from vllnt/convex-metering, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.

@vllnt/convex-metering

Metered usage records — idempotent usage events rolled up per billing period, as a Convex component.

Copy codeconst metering = new Metering(components.metering);
await metering.defineMeter(ctx, "api_calls", { aggregation: "sum", unit: "requests" });
await metering.record(ctx, "api_calls", orgId, 1, {
  period: "2026-06",
  idempotencyKey: requestId, // a retry won't double-count
});
const used = await metering.usage(ctx, "api_calls", orgId, { period: "2026-06" });

Define a meter, record usage for an opaque subject into host-chosen period buckets, and read O(1) per-period rollups for billing or limit checks. Recording is idempotent, so at-least-once retries never double-count. Price it in your own tables — this owns accurate usage, not your rates.

Features

• Idempotent recording — idempotencyKey makes a retry a no-op; the dedup ledger is separate from records, so it survives pruneRecords (no double-count after pruning).
• Per-meter aggregation — sum (accumulate), max (peak), or last (gauge), locked once usage exists.
• Corrections + freeze — adjust posts signed refunds/credits (sum, never below zero); closePeriod freezes a billed period so late events can't restate it.
• Atomic limits — recordWithLimit checks a cap and records in one transaction (no read-then-write overage race).
• Reconciliation — verify recomputes the rollup from records and flags drift for billing audits.
• Lifecycle + GDPR — listMeters/listSubjectUsage discovery, batched reset, and eraseSubject (erase a subject across all meters).
• Period rollups — each (meter, subject, period) rolls up independently; reads are O(1).
• Host-owned periods — period is an opaque string you choose ("2026-06", "2026-W24", "all"); no date parsing, any calendar/timezone.
• Audit + retention — raw records back every rollup; prune old records on your schedule, rollups stay.
• Scopes — global by default, or namespace per tenant.
• Fully typed — quantities, periods, and units are concrete types end to end; no any.
• Server-sourced time — record timestamps come from the server, never the caller.

Installation

Copy codepnpm add @vllnt/convex-metering

Peer dependency: convex@^1.41.0.

Usage

Copy code// convex/convex.config.ts
import { defineApp } from "convex/server";
import metering from "@vllnt/convex-metering/convex.config";

const app = defineApp();
app.use(metering);
export default app;

Copy code// convex/usage.ts — host owns auth; pass an opaque subjectRef + period in.
import { components } from "./_generated/api";
import { mutation } from "./_generated/server";
import { v } from "convex/values";
import { Metering } from "@vllnt/convex-metering";

const metering = new Metering(components.metering);

export const meterApiCall = mutation({
  args: { orgId: v.string(), requestId: v.string() },
  handler: async (ctx, { orgId, requestId }) => {
    return metering.record(ctx, "api_calls", orgId, 1, {
      period: "2026-06",
      idempotencyKey: requestId, // safe under retries
    });
  },
});

Read usage(ctx, "api_calls", orgId, { period }) for a limit check, or bill from it at your own rate in your own table — see example/convex/example.ts.

API Reference

Full reference: docs/API.md.

React

Optional, tree-shakeable hooks via @vllnt/convex-metering/react (react is an optional peer dep). Each wraps useQuery over a query reference you re-export from your app — the component never owns your api. useUsage derives a progress-bar view from an optional limit.

Copy code// convex/usage.ts — re-export a host wrapper (auth gated)
// export const myUsage = query({ args: { orgId: v.string() },
//   handler: (ctx, { orgId }) => metering.usage(ctx, "api_calls", orgId, { period: "2026-06" }) });

import { useUsage } from "@vllnt/convex-metering/react";
import { api } from "@/convex/_generated/api";

function UsageBar({ orgId }: { orgId: string }) {
  const u = useUsage(api.usage.myUsage, { meter: "api_calls", subjectRef: orgId, period: "2026-06" }, { limit: 10000 });
  if (u.isLoading) return <Spinner />;
  return <Meter value={u.fraction} label={`${u.value} / ${u.limit}`} warn={u.exceeded} />;
}

Security

• Auth-agnostic — the host resolves identity and decides who may define meters, record, reset, or read.
• Tables sandboxed — reached only through the exported functions; subjectRef, scope, and period stay opaque.
• Server-sourced timestamps — a caller cannot supply record time.

See docs/API.md.

Testing

Copy codepnpm test           # single run
pnpm test:coverage  # enforced 100% on covered files

Tests run against the real component runtime via convex-test (@edge-runtime/vm), not mocks.

Contributing

See CONTRIBUTING.md.

Author

Built by bntvllnt · bntvllnt.com · X @bntvllnt

Part of the @vllnt Convex component fleet — vllnt.com

If this is useful, sponsor the work.

License

MIT — see LICENSE.