feat: add organization and social account events for Better Auth

New events:
- organization-invitation-sent: When a user is invited to join an org
- organization-invitation-accepted: When an invite is accepted
- organization-member-removed: When a member is removed from an org
- organization-role-changed: When a member's role is updated
- social-account-linked: When a social provider is connected
- social-account-unlinked: When a social provider is disconnected

Includes:
- Type definitions for all new event contexts
- Plugin hooks for organization and social endpoints
- Default HTML templates for each event
- 6 new React Email templates with consistent design
- Updated exports in react-email/index.ts
- Documentation for all new events and templates

Author: R44VC0RP

src/integrations/better-auth/index.ts

@@ -49,6 +49,14 @@ export type {
   PasswordResetRequestedContext,
   TwoFactorContext,
   DeviceInfo,
+  // Organization event contexts
+  OrganizationInvitationSentContext,
+  OrganizationInvitationAcceptedContext,
+  OrganizationMemberRemovedContext,
+  OrganizationRoleChangedContext,
+  // Social account event contexts
+  SocialAccountLinkedContext,
+  SocialAccountUnlinkedContext,
 } from './types';
 
 /**
@@ -136,6 +144,17 @@ function resolveOptions(options: InboundEmailPluginOptions): ResolvedPluginOptio
       'password-reset-requested': { enabled: false, ...options.events?.['password-reset-requested'] },
       'two-factor-enabled': { enabled: true, ...options.events?.['two-factor-enabled'] },
       'two-factor-disabled': { enabled: true, ...options.events?.['two-factor-disabled'] },
+      // Organization events (disabled by default, requires organization plugin)
+      'organization-invitation-sent': { enabled: true, ...options.events?.['organization-invitation-sent'] },
+      'organization-invitation-accepted': {
+        enabled: true,
+        ...options.events?.['organization-invitation-accepted'],
+      },
+      'organization-member-removed': { enabled: true, ...options.events?.['organization-member-removed'] },
+      'organization-role-changed': { enabled: true, ...options.events?.['organization-role-changed'] },
+      // Social account events
+      'social-account-linked': { enabled: true, ...options.events?.['social-account-linked'] },
+      'social-account-unlinked': { enabled: true, ...options.events?.['social-account-unlinked'] },
     },
   };
 }
@@ -231,6 +250,26 @@ function isNewDevice(userId: string, ipAddress?: string | null, userAgent?: stri
   return true;
 }
 
+/**
+ * Format a provider ID to a display name.
+ * e.g., "google" -> "Google", "github" -> "GitHub"
+ */
+function formatProviderName(providerId: string): string {
+  const providerNames: Record<string, string> = {
+    google: 'Google',
+    github: 'GitHub',
+    apple: 'Apple',
+    facebook: 'Facebook',
+    twitter: 'Twitter',
+    discord: 'Discord',
+    microsoft: 'Microsoft',
+    linkedin: 'LinkedIn',
+    spotify: 'Spotify',
+    twitch: 'Twitch',
+  };
+  return providerNames[providerId.toLowerCase()] ?? providerId.charAt(0).toUpperCase() + providerId.slice(1);
+}
+
 /**
  * Creates a Better Auth plugin that sends transactional emails via Inbound
  * for important authentication events.
@@ -442,6 +481,271 @@ export function inboundEmailPlugin(options: InboundEmailPluginOptions): BetterAu
             });
           },
         },
+        // Organization invitation sent handler
+        {
+          matcher: (ctx) =>
+            (ctx.path === '/organization/invite-member' || ctx.path === '/organization/send-invitation') &&
+            ctx.method === 'POST',
+          handler: async (ctx: unknown) => {
+            const context = ctx as {
+              context?: {
+                session?: { user?: { email?: string; name?: string; id?: string } };
+                returned?: { status?: number; body?: { inviteLink?: string; expiresAt?: string } };
+              };
+              body?: {
+                email?: string;
+                role?: string;
+                organizationId?: string;
+              };
+            };
+
+            const session = context.context?.session;
+            const returned = context.context?.returned;
+            const body = context.body;
+
+            if (returned?.status !== 200 || !body?.email || !body?.organizationId) {
+              return;
+            }
+
+            // We need to get organization name - for now use ID as fallback
+            await sendAuthEmail(resolvedOptions, 'organization-invitation-sent', {
+              email: body.email,
+              inviterName: session?.user?.name ?? null,
+              inviterEmail: session?.user?.email ?? null,
+              organizationName: body.organizationId, // Would be replaced with actual name if available
+              organizationId: body.organizationId,
+              role: body.role ?? 'member',
+              inviteLink: returned.body?.inviteLink,
+              timestamp: new Date().toISOString(),
+              expiresAt: returned.body?.expiresAt,
+            });
+          },
+        },
+        // Organization invitation accepted handler
+        {
+          matcher: (ctx) =>
+            (ctx.path === '/organization/accept-invitation' || ctx.path.includes('/accept-invite')) &&
+            ctx.method === 'POST',
+          handler: async (ctx: unknown) => {
+            const context = ctx as {
+              context?: {
+                newSession?: { user?: { email?: string; name?: string; id?: string } };
+                returned?: {
+                  status?: number;
+                  body?: {
+                    organization?: { id?: string; name?: string };
+                    member?: { role?: string };
+                  };
+                };
+              };
+            };
+
+            const newSession = context.context?.newSession;
+            const returned = context.context?.returned;
+
+            if (returned?.status !== 200 || !newSession?.user?.email) {
+              return;
+            }
+
+            const org = returned.body?.organization;
+            if (!org?.id) {
+              return;
+            }
+
+            // Note: In a real implementation, you'd fetch the org admins to notify
+            // For now, this sends to the user who accepted
+            await sendAuthEmail(resolvedOptions, 'organization-invitation-accepted', {
+              email: newSession.user.email,
+              name: newSession.user.name ?? null,
+              userId: newSession.user.id ?? '',
+              organizationName: org.name ?? org.id,
+              organizationId: org.id,
+              role: returned.body?.member?.role ?? 'member',
+              timestamp: new Date().toISOString(),
+              notifyEmail: newSession.user.email, // Would be org admin email in production
+            });
+          },
+        },
+        // Organization member removed handler
+        {
+          matcher: (ctx) =>
+            (ctx.path === '/organization/remove-member' || ctx.path.includes('/remove-member')) &&
+            ctx.method === 'POST',
+          handler: async (ctx: unknown) => {
+            const context = ctx as {
+              context?: {
+                session?: { user?: { email?: string; name?: string; id?: string } };
+                returned?: {
+                  status?: number;
+                  body?: {
+                    member?: { email?: string; name?: string; id?: string };
+                    organization?: { id?: string; name?: string };
+                  };
+                };
+              };
+            };
+
+            const session = context.context?.session;
+            const returned = context.context?.returned;
+
+            if (returned?.status !== 200) {
+              return;
+            }
+
+            const member = returned.body?.member;
+            const org = returned.body?.organization;
+
+            if (!member?.email || !org?.id) {
+              return;
+            }
+
+            await sendAuthEmail(resolvedOptions, 'organization-member-removed', {
+              email: member.email,
+              name: member.name ?? null,
+              userId: member.id ?? '',
+              organizationName: org.name ?? org.id,
+              organizationId: org.id,
+              removedByName: session?.user?.name ?? null,
+              timestamp: new Date().toISOString(),
+            });
+          },
+        },
+        // Organization role changed handler
+        {
+          matcher: (ctx) =>
+            (ctx.path === '/organization/update-member-role' || ctx.path.includes('/update-role')) &&
+            ctx.method === 'POST',
+          handler: async (ctx: unknown) => {
+            const context = ctx as {
+              context?: {
+                session?: { user?: { email?: string; name?: string; id?: string } };
+                returned?: {
+                  status?: number;
+                  body?: {
+                    member?: { email?: string; name?: string; id?: string };
+                    organization?: { id?: string; name?: string };
+                    previousRole?: string;
+                    newRole?: string;
+                  };
+                };
+              };
+              body?: { role?: string };
+            };
+
+            const session = context.context?.session;
+            const returned = context.context?.returned;
+
+            if (returned?.status !== 200) {
+              return;
+            }
+
+            const member = returned.body?.member;
+            const org = returned.body?.organization;
+
+            if (!member?.email || !org?.id) {
+              return;
+            }
+
+            await sendAuthEmail(resolvedOptions, 'organization-role-changed', {
+              email: member.email,
+              name: member.name ?? null,
+              userId: member.id ?? '',
+              organizationName: org.name ?? org.id,
+              organizationId: org.id,
+              previousRole: returned.body?.previousRole ?? 'member',
+              newRole: returned.body?.newRole ?? context.body?.role ?? 'member',
+              changedByName: session?.user?.name ?? null,
+              timestamp: new Date().toISOString(),
+            });
+          },
+        },
+        // Social account linked handler
+        {
+          matcher: (ctx) =>
+            (ctx.path === '/link-social' ||
+              ctx.path === '/callback' ||
+              ctx.path.includes('/link-social-account')) &&
+            ctx.method === 'POST',
+          handler: async (ctx: unknown) => {
+            const context = ctx as {
+              context?: {
+                session?: { user?: { email?: string; name?: string; id?: string } };
+                returned?: {
+                  status?: number;
+                  body?: {
+                    provider?: string;
+                    providerAccountId?: string;
+                    linked?: boolean;
+                  };
+                };
+              };
+            };
+
+            const session = context.context?.session;
+            const returned = context.context?.returned;
+
+            // Only proceed if this was a successful link operation
+            if (returned?.status !== 200 || !returned.body?.linked || !session?.user?.email) {
+              return;
+            }
+
+            const providerId = returned.body.provider;
+            if (!providerId) {
+              return;
+            }
+
+            await sendAuthEmail(resolvedOptions, 'social-account-linked', {
+              email: session.user.email,
+              name: session.user.name ?? null,
+              userId: session.user.id ?? '',
+              providerName: formatProviderName(providerId),
+              providerId,
+              providerAccountId: returned.body.providerAccountId,
+              timestamp: new Date().toISOString(),
+            });
+          },
+        },
+        // Social account unlinked handler
+        {
+          matcher: (ctx) =>
+            (ctx.path === '/unlink-social' || ctx.path.includes('/unlink-social-account')) &&
+            ctx.method === 'POST',
+          handler: async (ctx: unknown) => {
+            const context = ctx as {
+              context?: {
+                session?: { user?: { email?: string; name?: string; id?: string } };
+                returned?: {
+                  status?: number;
+                  body?: {
+                    provider?: string;
+                  };
+                };
+              };
+              body?: { providerId?: string };
+            };
+
+            const session = context.context?.session;
+            const returned = context.context?.returned;
+
+            if (returned?.status !== 200 || !session?.user?.email) {
+              return;
+            }
+
+            const providerId = returned.body?.provider ?? context.body?.providerId;
+            if (!providerId) {
+              return;
+            }
+
+            await sendAuthEmail(resolvedOptions, 'social-account-unlinked', {
+              email: session.user.email,
+              name: session.user.name ?? null,
+              userId: session.user.id ?? '',
+              providerName: formatProviderName(providerId),
+              providerId,
+              timestamp: new Date().toISOString(),
+            });
+          },
+        },
       ],
     },
   };

src/integrations/better-auth/react-email/index.ts

@@ -33,18 +33,38 @@
 // Design system
 export { betterAuthDesignSystem } from './better-auth-design-system';
 
-// Email templates
+// Email templates - Authentication
 export { BetterAuthPasswordChanged } from './password-changed';
 export { BetterAuthEmailChanged } from './email-changed';
 export { BetterAuthNewDeviceSignin } from './new-device-signin';
 export { BetterAuthMagicLink } from './magic-link';
 export { BetterAuthPasswordReset } from './password-reset';
 export { BetterAuthVerifyEmail } from './verify-email';
 
-// Default exports for convenience
+// Email templates - Organization
+export { BetterAuthOrganizationInvitation } from './organization-invitation';
+export { BetterAuthOrganizationMemberJoined } from './organization-member-joined';
+export { BetterAuthOrganizationMemberRemoved } from './organization-member-removed';
+export { BetterAuthOrganizationRoleChanged } from './organization-role-changed';
+
+// Email templates - Social Accounts
+export { BetterAuthSocialAccountLinked } from './social-account-linked';
+export { BetterAuthSocialAccountUnlinked } from './social-account-unlinked';
+
+// Default exports for convenience - Authentication
 export { default as PasswordChangedEmail } from './password-changed';
 export { default as EmailChangedEmail } from './email-changed';
 export { default as NewDeviceSigninEmail } from './new-device-signin';
 export { default as MagicLinkEmail } from './magic-link';
 export { default as PasswordResetEmail } from './password-reset';
 export { default as VerifyEmailEmail } from './verify-email';
+
+// Default exports for convenience - Organization
+export { default as OrganizationInvitationEmail } from './organization-invitation';
+export { default as OrganizationMemberJoinedEmail } from './organization-member-joined';
+export { default as OrganizationMemberRemovedEmail } from './organization-member-removed';
+export { default as OrganizationRoleChangedEmail } from './organization-role-changed';
+
+// Default exports for convenience - Social Accounts
+export { default as SocialAccountLinkedEmail } from './social-account-linked';
+export { default as SocialAccountUnlinkedEmail } from './social-account-unlinked';