@sequenzy/better-auth

Better Auth plugin for Sequenzy - automatically sync your authenticated users with your email marketing platform.

When users sign up (via email/password or OAuth), they are automatically added as subscribers to Sequenzy, enabling you to send welcome emails, onboarding sequences, and more.

Installation

npm install @sequenzy/better-auth
# or
bun add @sequenzy/better-auth
# or
pnpm add @sequenzy/better-auth

Quick Start

1. Server Setup

Add the Sequenzy plugin to your Better Auth configuration:

// auth.ts
import { betterAuth } from "better-auth";
import { sequenzy } from "@sequenzy/better-auth";

export const auth = betterAuth({
  // ... your auth config
  plugins: [
    sequenzy({
      apiKey: process.env.SEQUENZY_API_KEY!,
    }),
  ],
});

2. Client Setup (Optional)

Add the client plugin for type inference:

// auth-client.ts
import { createAuthClient } from "better-auth/client";
import { sequenzyClient } from "@sequenzy/better-auth/client";

export const authClient = createAuthClient({
  plugins: [sequenzyClient()],
});

That's it! New users will now be automatically synced to Sequenzy.

Configuration Options

sequenzy({
  // Required: Your Sequenzy API key
  apiKey: process.env.SEQUENZY_API_KEY!,

  // Optional: API URL (default: "https://api.sequenzy.com")
  apiUrl: "https://api.sequenzy.com",

  // Optional: Add subscribers to specific lists
  // If not provided, subscribers are added to all lists
  listIds: ["list_welcome", "list_newsletter"],

  // Optional: Tags to assign to new subscribers
  tags: ["signup", "better-auth"],

  // Optional: Enroll in automation sequences (default: true)
  enrollInSequences: true,

  // Optional: Extract custom attributes from the user
  getCustomAttributes: (user) => ({
    authProvider: "better-auth",
    signupDate: new Date().toISOString(),
  }),

  // Optional: Callback when subscriber is created
  onSubscriberCreated: ({ userId, email, subscriberId }) => {
    console.log(`User ${email} synced to Sequenzy as ${subscriberId}`);
  },

  // Optional: Error handler
  onError: (error, user) => {
    console.error(`Failed to sync ${user.email}:`, error.message);
  },
});

How It Works

The plugin hooks into Better Auth's authentication flow:

1. Email/Password Sign-up: When a user registers via /sign-up/email, they are added to Sequenzy
2. OAuth Sign-up: When a user signs up via OAuth (Google, GitHub, etc.), they are added to Sequenzy

The plugin extracts:

• Email: From the authenticated user
• First/Last Name: Parsed from the user's name field
• Custom Attributes: Via the optional getCustomAttributes function

List Assignment

By default, new subscribers are added to all lists in your Sequenzy account. To add them to specific lists only:

sequenzy({
  apiKey: process.env.SEQUENZY_API_KEY!,
  listIds: ["list_abc123", "list_def456"],
});

To add subscribers without assigning to any list, pass an empty array:

sequenzy({
  apiKey: process.env.SEQUENZY_API_KEY!,
  listIds: [], // No list assignment
});

Automation Sequences

When enrollInSequences is true (default), new subscribers will be enrolled in any automations with "Contact Added" triggers. This is perfect for:

• Welcome email sequences
• Onboarding drip campaigns
• New user education series

To disable automation enrollment:

sequenzy({
  apiKey: process.env.SEQUENZY_API_KEY!,
  enrollInSequences: false,
});

Error Handling

The plugin is designed to be non-blocking. If Sequenzy is unavailable or returns an error, authentication will still succeed. Use the onError callback to monitor failures:

sequenzy({
  apiKey: process.env.SEQUENZY_API_KEY!,
  onError: (error, user) => {
    // Log to your error tracking service
    Sentry.captureException(error, {
      extra: { userEmail: user.email },
    });
  },
});

TypeScript Support

This package is fully typed. The plugin options and callbacks are strongly typed for a great developer experience.

Requirements

• Better Auth >= 1.0.0
• A Sequenzy account with an API key

Getting Your API Key

1. Go to Sequenzy Dashboard
2. Navigate to Settings > API Keys
3. Create a new API key
4. Add it to your environment variables

Documentation

• Sequenzy Documentation
• Better Auth Plugin Guide
• Better Auth Documentation

License

MIT