@hellocoop/better-auth

@hellocoop/better-auth

A Better Auth plugin for seamless integration with Hellō - the simple, secure, and privacy-focused authentication service.

Installation

1. Install the plugin

npm install @hellocoop/better-auth

2. Get your Hellō Client ID

Option 1: Quick Setup (Recommended)

npx @hellocoop/quickstart

This streamlines the entire process and displays your client_id in the terminal.

Tip: The quickstart command accepts various CLI flags. See the CLI parameters documentation for details.

Option 2: Manual Setup Visit console.hello.coop to create a free application and obtain your clientId.

3. Add the plugin to your auth config

To use the Hellō Better Auth plugin, add it to your auth config.

// auth.ts
import { betterAuth } from 'better-auth'
import { hellocoop } from '@hellocoop/better-auth'

export const auth = betterAuth({
    plugins: [
        hellocoop({
            config: {
                clientId: 'app_123_xyz', // Your Hellō client ID from step 2
                scopes: ['openid', 'profile', 'email'], // Optional: customize scopes
                prompt: 'consent', // Optional: 'login' or 'consent'
            },
        }),
    ],
})

4. Add the client plugin

Include the Hellō Better Auth client plugin in your authentication client setup:

// auth-client.ts
import { createAuthClient } from 'better-auth/client'
import { hellocoopClient } from '@hellocoop/better-auth'

export const authClient = createAuthClient({
    baseURL: 'http://localhost:3000', // Your app's base URL
    plugins: [hellocoopClient()],
})

Usage

The Hellō Better Auth plugin provides secure authentication endpoints and utilities. Here's how to implement them:

Sign-In Flow

Basic Sign-In

// Initiate the sign-in process
const { data, error } = await authClient.signInWithHello({
    callbackURL: '/dashboard',
    errorCallbackURL: '/error-page',
})

if (error) {
    console.error('Sign-in failed:', error)
    return
}

// User will be redirected to Hellō for authentication

Advanced Sign-In Options

const { data, error } = await authClient.signInWithHello({
    callbackURL: '/dashboard',
    errorCallbackURL: '/error-page',
    scopes: ['openid', 'profile', 'email'],
    prompt: 'consent', // Force consent screen
    providerHint: 'google,github', // Suggest specific providers
    loginHint: '[e-mail]', // Pre-fill email
    domainHint: 'company.com', // Suggest domain for login
})

Configuration Options

Parameter	Description	Type	Default
callbackURL?	URL to redirect after successful sign-in	string	/
errorCallbackURL?	URL to redirect if an error occurs	string	/error
scopes?	Array of scopes to request. See supported scopes	string[]	['openid']
providerHint?	Comma-separated list of preferred providers to show new users	string	-
loginHint?	Pre-fill email in the login form	string	-
domainHint?	Suggest domain for user login	string	-
prompt?	login forces fresh login; consent shows consent screen for profile updates	string	-

Authentication Callback

The plugin automatically handles the OAuth callback at /api/auth/hellocoop/callback. No additional setup required.

Sign-Out

Basic Sign-Out

// Sign out the current user
await authClient.signOut()

Sign-Out with Redirect

await authClient.signOut({
    fetchOptions: {
        onSuccess: () => {
            // Redirect after successful sign-out
            window.location.href = '/login'
        },
        onError: (error) => {
            console.error('Sign-out failed:', error)
        },
    },
})

UI Components

Hellō Buttons

1. Add the Hellō CSS

Include the Hellō button styles in your HTML document:

<link rel="stylesheet" href="https://cdn.hello.coop/css/hello-btn.css" />

2. Use the ContinueButton Component

import { ContinueButton } from '@hellocoop/better-auth'

function LoginPage() {
    const handleSignIn = async () => {
        const { data, error } = await authClient.signInWithHello({
            callbackURL: '/dashboard',
            errorCallbackURL: '/error-page',
            scopes: ['openid', 'profile', 'email'],
        })

        if (error) {
            console.error('Sign-in failed:', error)
        }
    }

    return (
        <div>
            <h1>Welcome to My App</h1>
            <ContinueButton onClick={handleSignIn}>
                Continue with Hellō
            </ContinueButton>
        </div>
    )
}

3. Custom Styling

// Apply custom CSS classes
<ContinueButton
    className="hello-btn-white hello-btn-hover-flare"
    onClick={handleSignIn}
>
    Sign in with Hellō
</ContinueButton>

Available Button Styles:

• hello-btn-black - Black button (default)
• hello-btn-white - White button
• hello-btn-hover-glow - Glow effect on hover
• hello-btn-hover-flare - Flare effect on hover

See the complete button customization guide for more styling options.

Note: Advanced theming properties from @hellocoop/react are coming soon. Currently, use CSS classes via the className prop for customization.

Configuration Reference

Plugin Configuration

Configure the Hellō plugin with these options:

interface HellocoopConfig {
    /** Your Hellō application client ID (required) */
    clientId: string

    /** OAuth scopes to request (optional) */
    scopes?: string[]

    /** Authentication prompt behavior (optional) */
    prompt?: 'login' | 'consent'

    /** Enable PKCE for enhanced security (optional, defaults to true) */
    pkce?: boolean

    /** Override user info on each login (optional, defaults to true) */
    overrideUserInfo?: boolean

    /** Custom user info mapping function (optional) */
    mapProfileToUser?: (profile: Record<string, any>) => Partial<User>
}

Configuration Options Explained

Option	Type	Default	Description
clientId	string	Required	Your Hellō application client ID from console.hello.coop
scopes	string[]	['openid']	OAuth scopes to request. See available scopes
prompt	'login' | 'consent'	undefined	login forces fresh authentication; consent shows profile update screen
pkce	boolean	true	Enables PKCE (Proof Key for Code Exchange) for enhanced security

Advanced Usage

Error Handling

The plugin provides comprehensive error handling for authentication flows:

const { data, error } = await authClient.signInWithHello({
    callbackURL: '/dashboard',
    errorCallbackURL: '/auth-error',
})

if (error) {
    // Handle different error types
    switch (error.message) {
        case 'oauth_code_verification_failed':
            console.error('Invalid authorization code')
            break
        case 'user_info_is_missing':
            console.error('Could not retrieve user information')
            break
        case 'email_is_missing':
            console.error('User email not provided by Hellō')
            break
        default:
            console.error('Authentication error:', error.message)
    }
}

Common Error Codes:

• oauth_code_verification_failed - Invalid or expired authorization code
• user_info_is_missing - Unable to fetch user profile from Hellō
• email_is_missing - User email not available in the response
• name_is_missing - User name not available in the response

Environment Variables

Set up environment variables for different environments:

# .env.local
HELLOCOOP_CLIENT_ID=app_123_xyz

# .env.production
HELLOCOOP_CLIENT_ID=app_456_abc

// Use in configuration
hellocoop({
    config: {
        clientId: process.env.HELLOCOOP_CLIENT_ID!,
    },
})

Troubleshooting

Common Issues

Issue: "Invalid OAuth configuration" error

• Solution: Ensure your clientId is correct and the application is properly configured in console.hello.coop

Issue: User claims not updating

• Solution: Set overrideUserInfo: true in your configuration (this is now the default)

Issue: Callback URL not working

• Solution: Verify your redirect URI in the Hellō console matches your application's callback URL format: https://yourdomain.com/api/auth/hellocoop/callback

Issue: Button styles not loading

• Solution: Ensure you've included the Hellō CSS: <link rel="stylesheet" href="https://cdn.hello.coop/css/hello-btn.css" />

Debug Mode

Enable debug logging to troubleshoot issues:

export const auth = betterAuth({
    logger: {
        level: 'debug', // Enable debug logs
    },
    plugins: [
        hellocoop({
            /* config */
        }),
    ],
})

Examples & Resources

• Complete Demo Application
• Hellō Developer Console
• Hellō Documentation
• Button Customization Guide
• OAuth Scopes Reference

Support

• Issues: GitHub Issues
• Documentation: hello.dev/docs
• Community: Hellō Discord