Better Auth Apso Adapter


A production-ready database adapter for Better Auth that seamlessly interfaces with Apso-generated CRUD REST endpoints. This adapter enables Better Auth to work with any REST API following Apso/nestjsx/crud conventions, providing enterprise-grade authentication for modern applications.

Key Features

- 🔒 Complete Better Auth Integration - Full compliance with Better Auth adapter interface
- 🚀 Production-Ready - Built-in retry logic, circuit breakers, and connection pooling
- ⚡ High Performance - Optimized for speed with caching and batch operations
- 🔧 TypeScript First - Comprehensive type definitions and strict type checking
- 📧 Email Normalization - Automatic email processing and validation
- 🏗️ Multi-Tenant Support - Built-in multi-tenancy with scope isolation
- 📊 Observability - Comprehensive metrics, tracing, and logging
- 🛡️ Security Focused - Input validation, sanitization, and secure defaults
- 🔄 Flexible Configuration - Extensive customization options
- 📈 Scalable - Connection pooling and bulk operations for high throughput

Installation

``bash
npm install @apso/better-auth-adapter
`

`bash
yarn add @apso/better-auth-adapter
`

`bash
pnpm add @apso/better-auth-adapter
`

Quick Start

`typescript
import { betterAuth } from 'better-auth';
import { apsoAdapter } from '@apso/better-auth-adapter';

export const auth = betterAuth({
database: apsoAdapter({
baseUrl: process.env.APSO_BASE_URL!,
apiKey: process.env.APSO_API_KEY,
}),
emailAndPassword: {
enabled: true,
},
session: {
expiresIn: 60 60 24 * 7, // 7 days
},
});
`

$3

Create a .env.local file in your project root:

`env
APSO_BASE_URL=https://your-apso-api.com
APSO_API_KEY=your-secret-api-key
`

Advanced Configuration

$3

`typescript
import { apsoAdapter } from '@apso/better-auth-adapter';

const adapter = apsoAdapter({
baseUrl: process.env.APSO_BASE_URL!,
apiKey: process.env.APSO_API_KEY,

// Retry configuration for resilience
retryConfig: {
maxRetries: 3,
initialDelayMs: 1000,
maxDelayMs: 10000,
retryableStatuses: [429, 500, 502, 503, 504],
},

// Performance optimization
cacheConfig: {
enabled: true,
ttlMs: 300000, // 5 minutes
maxSize: 1000,
},

// Batch operations
batchConfig: {
batchSize: 100,
concurrency: 5,
delayBetweenBatches: 100,
},

// Request timeout
timeout: 30000, // 30 seconds

// Email normalization
emailNormalization: true,

// Observability
observability: {
metricsEnabled: true,
tracingEnabled: true,
logLevel: 'info',
},
});
`

$3

`typescript
const adapter = apsoAdapter({
baseUrl: process.env.APSO_BASE_URL!,
apiKey: process.env.APSO_API_KEY,

multiTenancy: {
enabled: true,
scopeField: 'tenantId',
getScopeValue: async () => {
// Get tenant ID from context, headers, etc.
return getCurrentTenantId();
},
},
});
`

$3

`typescript
import { createHighThroughputApsoAdapter } from '@apso/better-auth-adapter';

const adapter = createHighThroughputApsoAdapter({
baseUrl: process.env.APSO_BASE_URL!,
apiKey: process.env.APSO_API_KEY,

// Optimized for high volume
batchConfig: {
batchSize: 500,
concurrency: 10,
},

// Connection pooling
fetchImpl: new HttpClient({
connectionPool: {
maxConnections: 100,
maxConnectionsPerHost: 20,
keepAlive: true,
},
}),
});
`

Framework Integration

$3

`typescript
// app/lib/auth.ts
import { betterAuth } from 'better-auth';
import { apsoAdapter } from '@apso/better-auth-adapter';

export const auth = betterAuth({
database: apsoAdapter({
baseUrl: process.env.APSO_BASE_URL!,
apiKey: process.env.APSO_API_KEY,
}),
emailAndPassword: {
enabled: true,
},
trustedOrigins: [process.env.NEXT_PUBLIC_APP_URL!],
});
`

`typescript
// app/api/auth/[...auth]/route.ts
import { auth } from '@/lib/auth';

export const { GET, POST } = auth.handler;
`

$3

`typescript
// server.ts
import express from 'express';
import { betterAuth } from 'better-auth';
import { apsoAdapter } from '@apso/better-auth-adapter';

const app = express();

const auth = betterAuth({
database: apsoAdapter({
baseUrl: process.env.APSO_BASE_URL!,
apiKey: process.env.APSO_API_KEY,
}),
emailAndPassword: {
enabled: true,
},
});

app.use('/api/auth/*', auth.handler);
`

API Reference

$3

Creates a Better Auth adapter that interfaces with Apso CRUD APIs.

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| baseUrl | string | ✅ | Base URL of your Apso API |
| apiKey | string | ❌ | API key for authentication |
| timeout | number | ❌ | Request timeout in milliseconds (default: 10000) |
| retryConfig | RetryConfig | ❌ | Retry configuration for failed requests |
| cacheConfig | CacheConfig | ❌ | Response caching configuration |
| batchConfig | BatchConfig | ❌ | Batch operations configuration |
| multiTenancy | MultiTenancyConfig | ❌ | Multi-tenancy settings |
| observability | ObservabilityConfig | ❌ | Metrics and tracing configuration |
| emailNormalization | boolean | ❌ | Enable email normalization (default: true) |
| debugMode | boolean | ❌ | Enable debug logging (default: false) |

$3

`typescript
// Reliable adapter with enhanced retry logic
const reliableAdapter = createReliableApsoAdapter(config);

// High-throughput adapter optimized for performance
const fastAdapter = createHighThroughputApsoAdapter(config);
`

$3

`typescript
// Check adapter health
const isHealthy = await checkAdapterHealth(adapter);

// Get adapter metrics
const metrics = adapter.getMetrics();
console.log(Success rate: ${metrics.successfulRequests / metrics.totalRequests * 100}%);

// Close all adapters (useful for graceful shutdown)
await closeAllAdapters();
`

Authentication Flows

$3

`typescript
import { auth } from './lib/auth';

// Sign up new user
const result = await auth.api.signUpEmail({
body: {
email: 'user@example.com',
password: 'securePassword123',
name: 'John Doe',
},
});

if (result.data?.user) {
console.log('User created:', result.data.user.id);
}
`

$3

`typescript
// Sign in user
const result = await auth.api.signInEmail({
body: {
email: 'user@example.com',
password: 'securePassword123',
},
});

if (result.data?.session) {
console.log('Session created:', result.data.session.token);
}
`

$3

`typescript
// Request password reset
await auth.api.forgetPassword({
body: {
email: 'user@example.com',
redirectTo: 'https://yourdomain.com/reset-password',
},
});

// Reset password with token
await auth.api.resetPassword({
body: {
token: 'reset-token',
password: 'newSecurePassword123',
},
});
`

Error Handling

The adapter provides comprehensive error handling with specific error codes:

`typescript
import { AdapterError, AdapterErrorCode } from '@apso/better-auth-adapter';

try {
await auth.api.signInEmail({
body: { email: 'invalid', password: 'wrong' }
});
} catch (error) {
if (error instanceof AdapterError) {
switch (error.code) {
case AdapterErrorCode.VALIDATION_ERROR:
console.error('Invalid input:', error.details);
break;
case AdapterErrorCode.NOT_FOUND:
console.error('User not found');
break;
case AdapterErrorCode.UNAUTHORIZED:
console.error('Invalid credentials');
break;
case AdapterErrorCode.RATE_LIMIT:
console.error('Too many requests, retry after:', error.details.retryAfter);
break;
default:
console.error('Unexpected error:', error.message);
}
}
}
`

Performance Optimization

$3

`typescript
const adapter = apsoAdapter({
baseUrl: process.env.APSO_BASE_URL!,
cacheConfig: {
enabled: true,
ttlMs: 600000, // 10 minutes
maxSize: 2000,
},
});

// Clear cache when needed
adapter.clearCache();
`

$3

`typescript
// Batch create users
const users = await adapter.createMany({
model: 'user',
data: [
{ email: 'user1@example.com', name: 'User 1' },
{ email: 'user2@example.com', name: 'User 2' },
{ email: 'user3@example.com', name: 'User 3' },
],
});
`

$3

`typescript
import { HttpClient } from '@apso/better-auth-adapter';

const httpClient = new HttpClient({
connectionPool: {
maxConnections: 50,
maxConnectionsPerHost: 10,
keepAlive: true,
keepAliveTimeout: 30000,
},
});

const adapter = apsoAdapter({
baseUrl: process.env.APSO_BASE_URL!,
fetchImpl: httpClient,
});
`

Security Best Practices

$3

Never hardcode sensitive values. Always use environment variables:

`typescript
// ✅ Good
const adapter = apsoAdapter({
baseUrl: process.env.APSO_BASE_URL!,
apiKey: process.env.APSO_API_KEY,
});

// ❌ Bad
const adapter = apsoAdapter({
baseUrl: 'https://api.example.com',
apiKey: 'secret-key-123',
});
`

$3

The adapter automatically validates and sanitizes all inputs:

`typescript
// Email normalization is enabled by default
const adapter = apsoAdapter({
baseUrl: process.env.APSO_BASE_URL!,
emailNormalization: true, // Converts emails to lowercase, trims whitespace
});
`

$3

Always use HTTPS endpoints in production:

`typescript
// ✅ Good
const adapter = apsoAdapter({
baseUrl: 'https://api.example.com',
});

// ❌ Bad (HTTP in production)
const adapter = apsoAdapter({
baseUrl: 'http://api.example.com',
});
`

Monitoring and Observability

$3

`typescript
const adapter = apsoAdapter({
baseUrl: process.env.APSO_BASE_URL!,
observability: {
metricsEnabled: true,
tracingEnabled: true,
logLevel: 'info',
},
});

// Get detailed metrics
const metrics = adapter.getMetrics();
console.log({
totalRequests: metrics.totalRequests,
successRate: metrics.successfulRequests / metrics.totalRequests,
averageLatency: metrics.averageLatency,
p95Latency: metrics.p95Latency,
cacheHitRate: metrics.cacheHitRate,
});
`

$3

`typescript
import { Logger } from '@apso/better-auth-adapter';

const customLogger: Logger = {
debug: (message, meta) => console.debug(message, meta),
info: (message, meta) => console.info(message, meta),
warn: (message, meta) => console.warn(message, meta),
error: (message, meta) => console.error(message, meta),
};

const adapter = apsoAdapter({
baseUrl: process.env.APSO_BASE_URL!,
logger: customLogger,
});
`

Migration Guide

See our comprehensive Migration Guide for detailed instructions on:

- Migrating from AWS Cognito
- Migrating from Prisma adapter
- Migrating from Drizzle adapter
- Data export and import procedures

Troubleshooting

Common issues and solutions can be found in our Troubleshooting Guide.

$3

Connection timeout errors:
`typescript
const adapter = apsoAdapter({
baseUrl: process.env.APSO_BASE_URL!,
timeout: 30000, // Increase timeout to 30 seconds
});
`

Rate limiting issues:
`typescript
const adapter = apsoAdapter({
baseUrl: process.env.APSO_BASE_URL!,
retryConfig: {
maxRetries: 5,
initialDelayMs: 2000,
maxDelayMs: 30000,
},
});
``

Examples

For complete working examples, see:

- Next.js App Router Example
- Next.js Pages Router Example
- Express.js Example
- Multi-tenant Application
- High-Performance Setup

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

- Setting up the development environment
- Running tests and code quality checks
- Submitting pull requests
- Code style guidelines

Changelog

See CHANGELOG.md for a detailed history of changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

- Documentation: Full API Reference
- Configuration: Configuration Guide
- Examples: Usage Examples
- Issues: GitHub Issues
- Discussions: GitHub Discussions

Related Projects

- Better Auth - Modern authentication library
- Apso SDK - TypeScript SDK for Apso APIs
- nestjsx/crud - CRUD operations for NestJS applications

---

Made with ❤️ by the Mavric Team