Better Auth Lead Plugin

Common errors

• table 'leads' does not exist

  cause The required database migration for the `leads` table was not executed after configuring the server-side plugin.
  fix Run your `better-auth` migration command, typically `npx auth@latest generate`, from your project's root directory.

• TypeError: Cannot read properties of undefined (reading 'lead')

  cause The `leadClient` plugin was not correctly initialized and added to the `createAuthClient` configuration on the client-side.
  fix Verify that `plugins: [leadClient()]` is included in your `createAuthClient` call in your client-side authentication setup file.

• 400 Bad Request - INVALID_METADATA

  cause The `metadata` object submitted via `authClient.lead.subscribe` or `authClient.lead.update` does not conform to the `metadata.validationSchema` defined on the server-side plugin configuration.
  fix Adjust the `metadata` payload on the client to match the expected structure and types defined by the server's validation schema (e.g., Zod schema).

Warnings

• breaking As a pre-1.0 package (currently 0.4.0), API surfaces and configuration options for `better-auth-lead` are subject to change without strict adherence to semantic versioning. Future minor versions (e.g., 0.5.0) may introduce breaking changes.
  Fix: Consult the latest README and changelog for specific updates and migration instructions when upgrading. Pin to exact patch versions if stability is critical.
• gotcha The `npx auth@latest generate` command must be run after installing and configuring the `better-auth-lead` plugin on the server-side to create the necessary `leads` database table. Failing to do so will result in runtime errors related to missing database tables.
  Fix: Ensure you run `npx auth@latest generate` (or `pnpm dlx auth@latest generate`, `yarn dlx auth@latest generate`, `bun x auth@latest generate`) from your project root after plugin installation and configuration.
• gotcha When implementing the `sendVerificationEmail` callback, it is crucial to include robust rate-limiting and anti-spam measures. The provided example includes a basic 1-minute cooldown, but production applications should implement more sophisticated checks to prevent abuse.
  Fix: Enhance your `sendVerificationEmail` function with more comprehensive rate-limiting based on IP, email, or other factors, and consider using dedicated email service providers that offer built-in spam protection.
• gotcha The client-side plugin `leadClient` must be imported from the specific subpath `better-auth-lead/client`. Attempting to import it directly from the package root (`better-auth-lead`) will lead to bundling issues or runtime errors indicating `leadClient` is undefined.
  Fix: Change `import { leadClient } from 'better-auth-lead';` to `import { leadClient } from 'better-auth-lead/client';` in your client-side setup file.

Install

• npm install better-auth-lead npm
• yarn add better-auth-lead yarn
• pnpm add better-auth-lead pnpm

Imports

• lead
  wrong:

  const { lead } = require('better-auth-lead');

  correct:

  import { lead } from 'better-auth-lead';

  This is the server-side plugin function for `createBetterAuth`.
• leadClient
  wrong:

  import { leadClient } from 'better-auth-lead';

  correct:

  import { leadClient } from 'better-auth-lead/client';

  The client-side plugin must be imported from the subpath `better-auth-lead/client`.
• LeadMetadata

  import type { LeadMetadata } from 'shared/lead-metadata-schema';

  This is an example type import for lead metadata, typically shared between client and server from a schema definition.

Quickstart

This code snippet demonstrates how to configure the `better-auth-lead` server plugin within `createBetterAuth`, including custom logic for sending verification emails and handling post-verification actions. It includes basic rate-limiting for email sending.

import { createBetterAuth } from '@better-auth/core';
import { lead } from 'better-auth-lead';
// Assume 'sendEmail' is a function that sends an email
// e.g., using nodemailer, resend, or a custom service.
async function sendEmail({ to, subject, text }: { to: string; subject: string; text: string }) {
  console.log(`Sending email to ${to} with subject: ${subject}`);
  console.log(`Body: ${text}`);
  // In a real application, integrate with an email sending service here.
  // Example: await resend.emails.send({ to, subject, text });
}

const betterAuth = createBetterAuth({
  plugins: [
    lead({
      sendVerificationEmail: async ({ lead, url }) => {
        const { verificationEmailSentAt } = lead;
        // Implement basic rate-limiting to prevent sending too many emails
        if (
          verificationEmailSentAt &&
          Date.now() - verificationEmailSentAt.getTime() < 60 * 1000 // 1 minute cooldown
        ) {
          console.log(
            `Skipping verification email for ${lead.email}: recent email already sent.`,
          );
          return false;
        }

        void sendEmail({
          to: lead.email,
          subject: 'Please verify your email address',
          text: `Click the link to verify your email: ${url}`,
        });

        return true; // Indicate that an email was sent
      },
      onEmailVerified: async ({ lead }) => {
        console.log(`Lead ${lead.email} has been successfully verified!`);
        // Additional logic after email verification, e.g., update CRM, send welcome email
      }
    }),
  ],
});

// To use betterAuth, you would typically export it or integrate it into an HTTP server setup.
// For example, in a Next.js API route or an Express app.
// console.log('Better Auth with Lead plugin configured.');