better-auth

Automatically assign your free plan to new users

In order for entitlements to work, all your users should have a plan assigned. We recommend automatically assigning your free plan to every new user in your auth system.

Requirements

You must have an active free plan. If you don't, create one at Plans.

Installation

npm install @getlumen/better-auth

Usage

Basic Usage

import { betterAuth } from "better-auth";
import { LumenPlugin } from "@getlumen/better-auth";

export const auth = betterAuth({
  // ... your other Better Auth configuration

  plugins: [
    LumenPlugin({
      apiKey: process.env.LUMEN_API_KEY!,
    }),
  ],
});

Advanced Usage with Callbacks

import { betterAuth } from "better-auth";
import { LumenPlugin } from "@getlumen/better-auth";

export const auth = betterAuth({
  // ... your other Better Auth configuration

  plugins: [
    LumenPlugin({
      apiUrl: process.env.API_URL, // you can put http://localhost:backend_port for development
      apiKey: process.env.LUMEN_API_KEY!,
      enabled: true,
      prodOnly: process.env.NODE_ENV !== "development",
      onSuccess: (user, subscription) => {
        console.log(
          `Free subscription created for ${user.email}:`,
          subscription
        );
        // Optional: Send notification, update analytics, etc.
      },
      onError: (user, error) => {
        console.error(
          `Failed to create free subscription for ${user.email}:`,
          error
        );
        // Optional: Send error notification, log to monitoring service, etc.
      },
      logger: (message, ...args) => {
        console.log(`[FreeSubscription] ${message}`, ...args);
      },
    }),
  ],
});

Integration with Other Plugins

If you have other plugins, you can combine them:

import { betterAuth } from "better-auth";
import { LumenPlugin } from "@getlumen/better-auth";
import { someOtherPlugin } from "some-other-plugin";

export const auth = betterAuth({
  // ... your other Better Auth configuration

  plugins: [
    someOtherPlugin(),
    LumenPlugin({
      apiUrl: process.env.API_URL || "https://api.getlumen.dev",
      apiKey: process.env.LUMEN_API_KEY!,
      enabled: true,
      prodOnly: true,
    }),
  ],
});

Configuration Options

Option	Type	Default	Description
`apiUrl`	`string`	`https://api.getlumen.dev`	The base URL of your API service, you can put `http://localhost:backend_port` for development
`apiKey`	`string`	Required	API key for authenticating with the subscription service
`enabled`	`boolean`	`true`	Whether the plugin is enabled
`prodOnly`	`boolean`	`false`	Whether to only run in production/staging environments
`onSuccess`	`function`	Optional	Callback function called when subscription is created successfully
`onError`	`function`	Optional	Callback function called when subscription creation fails
`logger`	`function`	`console.log`	Custom logger function for debugging

How It Works

The plugin hooks into the Better Auth after hook with a matcher
It checks if the current request is a sign-in endpoint (email login or social callback)
If a new session is created, it automatically calls the /v1/subscriptions/create-free-subscription endpoint
The subscription is created with the user's email, name, and ID
Success/error callbacks are triggered accordingly

Error Handling

The plugin includes comprehensive error handling:

Missing API key will skip subscription creation
Network errors are caught and logged
API errors are parsed and passed to the error callback
Errors don't block user authentication (fail gracefully)

Development vs Production

When prodOnly is set to true, the plugin will skip execution in development mode. This is useful for preventing test subscriptions from being created during development.

better-auth

On this page