npm package: @sequenzy/better-auth
Description: Better Auth plugin for Sequenzy - automatically sync your users with your email marketing
Author: Sequenzy
Latest version: 0.2.0

# @sequenzy/better-auth

Better Auth plugin for [Sequenzy](https://sequenzy.com) - 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

```bash
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:

```ts
// 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:

```ts
// 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

```ts
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:

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

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

```ts
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:

```ts
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:

```ts
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](https://app.sequenzy.com)
2. Navigate to Settings > API Keys
3. Create a new API key
4. Add it to your environment variables

## Documentation

- [Sequenzy Documentation](https://docs.sequenzy.com)
- [Better Auth Plugin Guide](https://docs.sequenzy.com/integrations/better-auth)
- [Better Auth Documentation](https://www.better-auth.com)

## License

MIT