@eleven-am/launchpad-auth

TypeScript SDK for integrating Launchpad authentication into client applications.

Installation

npm install @eleven-am/launchpad-auth

Quick Start

import { LaunchpadAuth } from '@eleven-am/launchpad-auth'

const auth = new LaunchpadAuth({
  baseUrl: 'https://auth.myapp.com'
})

// Sign up
const { user } = await auth.signUp({
  email: '[email protected]',
  password: 'password123',
  name: 'John Doe'
})

// Sign in
const result = await auth.signIn({ email, password })
if ('twoFactorRequired' in result) {
  const { user } = await auth.verifyLoginCode(result.challengeToken, code)
} else {
  console.log('Logged in as', result.user.email)
}

// Check auth state
if (auth.isAuthenticated()) {
  console.log(auth.getUser())
}

Configuration

interface LaunchpadAuthConfig {
  baseUrl: string                                    // Launchpad server URL
  storage?: 'localStorage' | 'memory' | TokenStorage // Token storage (default: localStorage)
  onTokenChange?: (token: string | null) => void     // Token change callback
}

API Reference

Email/Password Authentication

// Sign up a new user
auth.signUp({ email, password, name? }): Promise<AuthResult>

// Sign in an existing user
auth.signIn({ email, password }): Promise<AuthResult | TwoFactorChallenge>

// Sign out the current user
auth.signOut(): void

// Request password reset email
auth.forgotPassword(email): Promise<void>

// Reset password with token
auth.resetPassword({ token, password }): Promise<void>

OAuth Authentication

// Get available OAuth providers
auth.getProviders(): Promise<string[]>

// Start OAuth flow (redirects browser)
auth.beginOAuth(provider, redirectUri?): void

// Handle OAuth callback (call on redirect page)
auth.handleOAuthCallback(): AuthResult

Two-Factor Authentication

// Enable 2FA for current user
auth.enable2FA(): Promise<TwoFactorSetup>

// Verify and activate 2FA
auth.verify2FA(code): Promise<void>

// Disable 2FA
auth.disable2FA(code): Promise<void>

// Complete login with 2FA code
auth.verifyLoginCode(challengeToken, code): Promise<AuthResult>

// Complete login with backup code
auth.verifyBackupCode(challengeToken, code): Promise<AuthResult>

// Regenerate backup codes
auth.regenerateBackupCodes(code): Promise<string[]>

Passkey (WebAuthn) Authentication

// Check if passkeys are supported
auth.isPasskeySupported(): boolean

// Register a new passkey (requires authentication)
auth.registerPasskey(name?): Promise<void>

// List user's passkeys (requires authentication)
auth.listPasskeys(): Promise<Passkey[]>

// Delete a passkey (requires authentication)
auth.deletePasskey(id): Promise<void>

// Start passkey authentication (requires challengeToken from sign-in)
auth.beginPasskeyAuth(challengeToken): Promise<PasskeyChallenge>

// Complete passkey authentication
auth.completePasskeyAuth(challenge): Promise<AuthResult>

Token Management

// Get current JWT token
auth.getToken(): string | null

// Get current user (decoded from token)
auth.getUser(): User | null

// Check if user is authenticated
auth.isAuthenticated(): boolean

// Subscribe to auth state changes (returns unsubscribe function)
auth.onAuthStateChange(callback): () => void

Types

interface AuthResult {
  token: string
  user: User
}

interface User {
  id: string
  email: string
  name: string
  emailVerified: boolean
  provider: string
}

interface TwoFactorChallenge {
  twoFactorRequired: true
  challengeToken: string
}

interface TwoFactorSetup {
  secret: string
  qrCodeUrl: string
  backupCodes: string[]
}

interface PasskeyChallenge {
  challengeToken: string
  options: PublicKeyCredentialRequestOptions
}

interface Passkey {
  id: string
  name: string
  createdAt: string
}

Error Handling

The SDK throws typed errors for different failure scenarios:

import {
  LaunchpadError,
  AuthenticationError,
  ValidationError,
  NetworkError
} from '@eleven-am/launchpad-auth'

try {
  await auth.signIn({ email, password })
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid credentials')
  } else if (error instanceof ValidationError) {
    console.log('Invalid input:', error.message)
  } else if (error instanceof NetworkError) {
    console.log('Network error:', error.message)
  }
}

Custom Storage

Implement the TokenStorage interface for custom storage solutions:

interface TokenStorage {
  get(): string | null
  set(token: string): void
  remove(): void
}

// Example: Cookie storage
const cookieStorage: TokenStorage = {
  get: () => document.cookie.match(/token=([^;]+)/)?.[1] ?? null,
  set: (token) => { document.cookie = `token=${token}; path=/` },
  remove: () => { document.cookie = 'token=; expires=Thu, 01 Jan 1970' }
}

const auth = new LaunchpadAuth({
  baseUrl: 'https://auth.myapp.com',
  storage: cookieStorage
})

Auth State Subscription

Subscribe to authentication state changes:

const unsubscribe = auth.onAuthStateChange((user) => {
  if (user) {
    console.log('User logged in:', user.email)
  } else {
    console.log('User logged out')
  }
})

// Later, to stop listening
unsubscribe()

License

MIT