baseflow-client/CHANGELOG.md

Official TypeScript/JavaScript client for BaseFlow - a powerful BaaS with OAuth authentication, RPC functions, database indexes, real-time features, and Supabase-compatible API

# Changelog

All notable changes to the BaseFlow Client SDK will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.1.0] - 2025-11-07

### Added

#### OAuth Authentication
- **GitHub OAuth**: Sign in with GitHub accounts
  - `auth.signInWithOAuth('github', options?)` - Initiate GitHub OAuth flow
  - `auth.handleOAuthCallback(code, 'github')` - Handle OAuth callback
  - Automatic user creation and email confirmation
  - Profile data sync (name, email, avatar)
  
- **Google OAuth**: Sign in with Google accounts
  - `auth.signInWithOAuth('google', options?)` - Initiate Google OAuth flow
  - `auth.handleOAuthCallback(code, 'google')` - Handle OAuth callback
  - OpenID Connect support
  - Profile data sync (name, email, picture)

- **OAuth Features**:
  - CSRF protection with state parameter
  - Custom redirect URLs
  - Custom OAuth scopes
  - Automatic JWT token generation
  - Session management
  - Activity tracking

#### RPC (Remote Procedure Calls)
- **Function Execution**: Call server-side functions remotely
  - `rpc(functionName, params)` - Execute remote procedures
  - Support for JavaScript and SQL functions
  - Parameter validation and type checking
  - Return value handling
  
- **Function Management**:
  - `createFunction(name, definition, options)` - Create new functions
  - `listFunctions()` - List all available functions
  - `getFunction(name)` - Get function details
  - `deleteFunction(name)` - Remove functions
  - Support for custom parameters and return types
  - Function descriptions and metadata

#### Database Indexes
- **Index Creation**: Optimize query performance
  - `createIndex(table, columns, options)` - Create indexes
  - Support for single and composite indexes
  - Unique index constraints
  - Custom index names
  
- **Index Management**:
  - `listIndexes(table?)` - List all indexes
  - `dropIndex(name)` - Remove indexes
  - `analyzeQuery(query)` - Query performance analysis
  - Index usage statistics

#### Real-time Enhancements
- **WebSocket Improvements**:
  - Automatic reconnection with exponential backoff
  - Connection status monitoring
  - Heartbeat/ping support
  - Better error handling
  - Multiple subscription support

- **Database Triggers**:
  - Automatic change detection
  - Support for INSERT, UPDATE, DELETE events
  - Wildcard event listeners (`*`)
  - Payload includes old and new values
  - Table-specific subscriptions

#### Advanced Query Features
- **JOIN Support**:
  - Automatic foreign key detection
  - Nested relationship queries
  - Multiple JOIN levels
  - Aggregation in JOINs (count, sum, avg, etc.)
  
- **Query Enhancements**:
  - `textSearch(column, query)` - Full-text search
  - `contains(column, value)` - Array/JSON contains
  - Better error messages
  - Query result caching

### Changed

- **Authentication API**: Enhanced with OAuth support
  - `signUp()` now supports OAuth metadata
  - `signInWithPassword()` improved error handling
  - Session management unified across auth methods
  
- **Error Handling**: More detailed error messages
  - Error codes for all failure scenarios
  - Detailed error context and suggestions
  - Better network error handling

- **TypeScript Types**: Improved type definitions
  - Better generic type inference
  - More accurate return types
  - Enhanced IntelliSense support

### Fixed

- **WebSocket**: Fixed reconnection issues
- **Query Builder**: Fixed edge cases in complex queries
- **Storage**: Fixed file upload for large files
- **Authentication**: Fixed token refresh timing

### Documentation

- Added comprehensive OAuth setup guide
- Added RPC function examples
- Added index optimization guide
- Updated API reference with new methods
- Added troubleshooting section

## [1.0.1] - 2024-10-15

### Added

- **Real-time Subscriptions**: WebSocket-based live data updates
  - `realtime.connect()` - Connect to real-time server
  - `realtime.subscribe(table, callback)` - Subscribe to table changes
  - `realtime.disconnect()` - Clean disconnect
  - Automatic authentication
  - Connection status tracking

- **Storage API**: File upload and management
  - `storage.upload(path, file, options)` - Upload files
  - `storage.download(path)` - Download files
  - `storage.getUrl(path)` - Get public URLs
  - `storage.list(path)` - List files and folders
  - `storage.delete(path)` - Delete files
  - `storage.createFolder(path)` - Create folders
  - Support for multiple file types
  - Automatic MIME type detection

### Changed

- **Query Builder**: Improved performance for complex queries
- **Authentication**: Better session management
- **Error Messages**: More descriptive error messages

### Fixed

- Fixed issue with nested select queries
- Fixed authentication token expiration handling
- Fixed storage upload for binary files

## [1.0.0] - 2024-09-01

### Added

- **Initial Release**: First stable version of BaseFlow Client
  
- **Core Features**:
  - Supabase-compatible API
  - TypeScript support with full type safety
  - Universal compatibility (Node.js, browsers, edge)
  
- **Query Builder**:
  - `from(table)` - Table selection
  - `select(columns)` - Column selection
  - `insert(data)` - Insert records
  - `update(data)` - Update records
  - `delete()` - Delete records
  
- **Filter Methods**:
  - `eq()`, `neq()` - Equality filters
  - `gt()`, `gte()`, `lt()`, `lte()` - Comparison filters
  - `like()`, `ilike()` - Pattern matching
  - `in()` - Array matching
  - `is()` - NULL checks
  - `or()` - OR conditions
  
- **Query Modifiers**:
  - `order()` - Sorting
  - `limit()` - Result limiting
  - `range()` - Pagination
  - `single()` - Single row return
  - `maybeSingle()` - Optional single row
  
- **Authentication**:
  - `auth.signUp()` - User registration
  - `auth.signInWithPassword()` - Email/password login
  - `auth.signOut()` - Logout
  - `auth.getUser()` - Get current user
  - `auth.getSession()` - Get current session
  - `auth.onAuthStateChange()` - Auth event listener
  - JWT token management
  - Automatic token refresh
  
- **Schema Management**:
  - `defineSchema()` - Create tables from schema
  - `getSchema()` - Get current schema
  - `createTable()` - Create individual tables
  - Support for all SQLite data types
  - Foreign key constraints
  - Unique constraints
  - Default values
  
- **Advanced Features**:
  - `sql()` - Raw SQL queries
  - `rpc()` - Remote procedure calls (basic)
  - Request/response interceptors
  - Custom headers support
  - Custom fetch implementation

### Developer Experience

- Comprehensive TypeScript types
- Excellent IntelliSense support
- Detailed error messages
- Extensive documentation
- Example projects
- Test suite

## [0.9.0] - 2024-08-15

### Added

- **Beta Release**: Pre-release version for testing
- Core query builder functionality
- Basic authentication
- Initial TypeScript support

### Known Issues

- Limited real-time support
- No file storage
- Basic error handling

---

## Upgrade Guide

### Upgrading to 1.1.0

#### OAuth Authentication

If you want to use OAuth authentication, you need to configure OAuth providers:

```env
# .env
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
```

Then use the new OAuth methods:

```typescript
// Before (only email/password)
await baseflow.auth.signInWithPassword({ email, password });

// After (OAuth support)
const { data } = await baseflow.auth.signInWithOAuth('github');
window.location.href = data.url;
```

#### RPC Functions

New RPC methods are available:

```typescript
// Call a function
const { data } = await baseflow.rpc('my_function', { param: 'value' });

// Create a function
await baseflow.createFunction('my_function', 'return params.value * 2;', {
  language: 'javascript',
  parameters: [{ name: 'value', type: 'number' }]
});
```

#### Database Indexes

Optimize your queries with indexes:

```typescript
// Create an index
await baseflow.createIndex('users', ['email'], { unique: true });

// Analyze query performance
const { data } = await baseflow.analyzeQuery('SELECT * FROM users WHERE email = ?');
```

### Upgrading to 1.0.1

No breaking changes. New features are additive:

```typescript
// Real-time subscriptions
await baseflow.realtime.connect();
baseflow.realtime.subscribe('posts', (payload) => {
  console.log('Change:', payload);
});

// File storage
await baseflow.storage.upload('avatar.jpg', file);
```

### Upgrading to 1.0.0

If upgrading from beta (0.9.0):

- Update import paths if using internal modules
- Check authentication flow (improved session management)
- Review error handling (new error format)

---

## Breaking Changes

### Version 1.1.0
- None (fully backward compatible)

### Version 1.0.1
- None (fully backward compatible)

### Version 1.0.0
- Changed error response format from beta
- Renamed some internal TypeScript types
- Updated authentication session structure

---

## Deprecations

### Version 1.1.0
- `auth.login()` - Use `auth.signInWithPassword()` instead (still works, but deprecated)
- `auth.signup()` - Use `auth.signUp()` instead (still works, but deprecated)
- `auth.logout()` - Use `auth.signOut()` instead (still works, but deprecated)

---

## Security Updates

### Version 1.1.0
- Added CSRF protection for OAuth flows
- Improved token validation
- Enhanced session security
- Better error message sanitization

### Version 1.0.1
- Fixed potential XSS in error messages
- Improved file upload validation
- Enhanced authentication token security

### Version 1.0.0
- Initial security audit completed
- JWT token encryption
- Secure password hashing
- SQL injection prevention

---

## Performance Improvements

### Version 1.1.0
- Database indexes for faster queries (up to 100x faster)
- Optimized WebSocket reconnection
- Reduced bundle size by 15%
- Improved query caching

### Version 1.0.1
- Faster real-time subscriptions
- Optimized file uploads
- Better connection pooling

### Version 1.0.0
- Initial performance baseline
- Query optimization
- Efficient data serialization

---

## Links

- [Documentation](https://docs.baseflow.cloud)
- [GitHub](https://github.com/baseflow/baseflow)
- [NPM Package](https://www.npmjs.com/package/@baseflow/client)
- [Migration Guide](https://docs.baseflow.cloud/migration)
- [API Reference](https://docs.baseflow.cloud/api)

---

**Note**: This changelog follows [Semantic Versioning](https://semver.org/). Version numbers are in the format MAJOR.MINOR.PATCH where:
- MAJOR: Breaking changes
- MINOR: New features (backward compatible)
- PATCH: Bug fixes (backward compatible)