plunk-integration

Plunk Integration Guide

Overview

Plunk is integrated for user event tracking and analytics. The system tracks authentication-related events including OTP sending, user signups, and password resets.

Core Components

Plunk Client

The main client is in src/lib/plunk/client.ts:

• PlunkClient class with singleton pattern via getPlunkClient()
• Base URL: https://api.useplunk.com/v1
• Methods: trackEvent() for analytics, sendEmail() for transactional emails
• Automatic API key validation and error handling

Event Tracking Functions

Pre-defined tracking functions in src/lib/plunk/events.ts:

Email Verification OTP

trackEmailVerificationOTP(email: string, otpCode: string)

• Event: "user-otp"
• Subscribed: false (doesn't affect subscription status)
• Data structure: { otp: { value: "123456", persistent: false } }

Password Reset OTP

trackPasswordResetOTP(email: string, otpCode: string)

• Event: "reset-otp"
• Subscribed: false
• Data structure: { otp: { value: "123456", persistent: false } }

User Signup

trackUserSignup(email: string, fullName?: string)

• Event: "user-signup"
• Subscribed: true (new users are subscribed by default)
• Data structure: { fullName: "John Doe" }

Integration Points

Better Auth Server

In src/lib/auth/server.ts:

• sendVerificationOTP callback tracks OTP events automatically
• databaseHooks.user.create.after tracks user signups
• Non-blocking error handling prevents auth flow interruption

Authentication Pages

Event tracking is integrated into:

• src/app/(auth)/sign-up/page.tsx - User signup tracking
• src/app/(auth)/forgot-password/page.tsx - Password reset tracking

Event Data Standards

OTP Events

All OTP-related events follow this structure:

{
  event: "user-otp" | "reset-otp",
  email: "[email protected]",
  subscribed: false,
  data: {
    otp: {
      value: "123456",
      persistent: false
    }
  }
}