Registry / auth-security / better-auth-openmeter-plugin

better-auth-openmeter-plugin

library0.5.0jsnpmunverified

Better Auth plugin for OpenMeter usage metering, entitlements, API key tracking, organization customers, React hooks, and billing provider bridges (Stripe, Polar, Razorpay, Creem, Dodo Payments, Autumn). Current stable version 0.5.0, released monthly. Key differentiators: seamless OpenMeter integration with Better Auth auth lifecycle, support for both greenfield runtime and catalog/helper modes, built-in billing catalog DSL with recurring-first plans/add-ons/top-ups, and provider-aware compilation for multiple billing providers.

auth-security payments observability

npm install better-auth-openmeter-plugin

github ↗package ↗

INSTALL

IMPORT

SIG · BETTER-AUTH-OPENME

better-auth-openmeter-plugin

auth-securityjavascriptv0.5.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

openmeterPlugin

✓ import { openmeterPlugin } from 'better-auth-openmeter-plugin'

✗ import openmeterPlugin from 'better-auth-openmeter-plugin'

Named export only. Default export does not exist.

openmeterClientPlugin

✓ import { openmeterClientPlugin } from 'better-auth-openmeter-plugin/client'

✗ import { openmeterClientPlugin } from 'better-auth-openmeter-plugin'

Client plugin is a separate subpath export. Import from the /client path.

applyCatalogTopupGrant

✓ import { applyCatalogTopupGrant } from 'better-auth-openmeter-plugin'

OpenMeter

✓ import { OpenMeter } from '@openmeter/sdk'

✗ import { OpenMeter } from 'better-auth-openmeter-plugin'

OpenMeter SDK client is from the separate @openmeter/sdk package.

Server-side setup of Better Auth with the OpenMeter plugin, including customer creation on sign-up and event tracking.

import { betterAuth } from 'better-auth'; import { openmeterPlugin } from 'better-auth-openmeter-plugin'; const auth = betterAuth({ plugins: [ openmeterPlugin({ apiKey: process.env.OPENMETER_API_KEY ?? '', baseUrl: 'https://openmeter.cloud', createCustomerOnSignUp: true, syncCustomerOnUserUpdate: true, trackAuthEvents: true, customer: { resolveKey: ({ user }) => user.id, resolveSubject: ({ user }) => user.id, resolveProfile: ({ user, defaults }) => ({ ...defaults, description: `Better Auth user ${user.id}`, billingAddress: { country: 'US', }, metadata: { ...defaults.metadata, source: 'better-auth', }, }), }, }), ], });

Debug

Known issues

gotchaThe plugin modifies the Better Auth user schema to add an openmeterCustomerId field. You must run a database migration after enabling the plugin to create this column.

fix

Run your Better Auth migration/generation step after adding the plugin to your auth config.

affects: >=0.0.0

breakingIn v0.3.0, the billing catalog DSL was introduced with a different shape for plans and add-ons. If you used an earlier version without the catalog, you will need to refactor your billing configuration.

fix

Update plugin configuration to use the catalog DSL: define plans with recurring, add-ons, and top-ups as described in the README.

affects: <0.3.0

deprecatedThe client plugin import path changed. In v0.3.0 and earlier, client plugin was available at 'better-auth-openmeter-plugin/client'.

fix

Use import { openmeterClientPlugin } from 'better-auth-openmeter-plugin/client'.

affects: <0.4.0

gotchaThe package requires Node.js >=20 and only supports ESM. Using require() or older Node versions will break.

fix

Ensure your project runs on Node >=20 and uses ESM (type: 'module' in package.json).

affects: >=0.0.0

gotchaThe OpenMeter client must be configured with a valid API key or base URL. Passing only an apiKey without baseUrl defaults to https://openmeter.cloud, which may not be appropriate for all environments.

fix

Explicitly set baseUrl to your OpenMeter instance URL (e.g., https://openmeter.cloud or http://127.0.0.1:8888 for local dev).

affects: >=0.0.0

Errors

Common errors & fixes

Cannot find module 'better-auth-openmeter-plugin/client'

Using an older version of the package that does not have the /client subpath export.

fix

Update to v0.4.0 or later: npm install better-auth-openmeter-plugin@latest

TypeError: openmeterPlugin is not a function

Importing the module as default import instead of named import.

fix

Use import { openmeterPlugin } from 'better-auth-openmeter-plugin'

The field 'openmeterCustomerId' does not exist on type 'User'

Database schema has not been migrated after enabling the plugin.

fix

Run your database migration (e.g., npx better-auth generate && npx better-auth migrate) to add the openmeterCustomerId column.

OpenMeterError: unauthorized - invalid API key

The provided apiKey is incorrect or missing.

fix

Ensure OPENMETER_API_KEY environment variable is set and valid. In local dev, use openmeterClient with a mock or local server.

Upgrade

Version history

0.5.0latest on npm

Audit

Dependencies

@openmeter/sdkrequiredRequired peer dependency for interacting with the OpenMeter API

@better-auth/corerequiredPeer dependency for Better Auth core types and functionality

better-authrequiredPeer dependency for the Better Auth server package

reactoptionalPeer dependency for React Query hooks

@tanstack/react-queryoptionalPeer dependency for React Query hooks

Agent activity

45 hits · last 30 days

node

Perplexity

OpenAI (training)

Resources

githubhttps://github.com/kaustubhkagrawal/better-auth-openmeter-plugin ↗

packagehttps://www.npmjs.com/package/better-auth-openmeter-plugin ↗