@tspvivek/baasix-sdk 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,942 @@
+# @tspvivek/baasix-sdk
+
+Official JavaScript/TypeScript SDK for [Baasix](https://www.baasix.com) Backend-as-a-Service.
+
+[![npm version](https://img.shields.io/npm/v/@tspvivek/baasix-sdk.svg)](https://www.npmjs.com/package/@tspvivek/baasix-sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@tspvivek/baasix-sdk.svg)](https://www.npmjs.com/package/@tspvivek/baasix-sdk)
+[![license](https://img.shields.io/npm/l/@tspvivek/baasix-sdk.svg)](https://github.com/tspvivek/baasix-sdk/blob/main/LICENSE)
+
+## Features
+
+- 🌐 **Universal** - Works in browsers, Node.js, and React Native
+- 🔐 **Flexible Auth** - JWT tokens, HTTP-only cookies, OAuth (Google, Facebook, Apple, GitHub)
+- 💾 **Customizable Storage** - LocalStorage, AsyncStorage, or custom adapters
+- 📝 **Type-Safe** - Full TypeScript support with generics
+- 🔄 **Auto Token Refresh** - Seamless token management
+- 🏢 **Multi-Tenant** - Built-in tenant switching and invitation support
+- ⚡ **Query Builder** - Fluent API for complex queries with 50+ filter operators
+- 📡 **Realtime** - WebSocket subscriptions for live data updates
+- 📁 **File Management** - Upload, download, and transform assets
+- 🔀 **Workflows** - Execute and monitor workflow executions
+- 👥 **User & Role Management** - Admin operations for users and roles
+- 📊 **Reports** - Generate reports with aggregations
+
+## Installation
+
+```bash
+npm install @tspvivek/baasix-sdk
+# or
+yarn add @tspvivek/baasix-sdk
+# or
+pnpm add @tspvivek/baasix-sdk
+```
+
+## Quick Start
+
+```typescript
+import { createBaasix } from '@tspvivek/baasix-sdk';
+
+// Create client
+const baasix = createBaasix({
+  url: 'https://your-baasix-instance.com',
+});
+
+// Login
+const { user, token } = await baasix.auth.login({
+  email: 'user@example.com',
+  password: 'password123',
+});
+
+// Query items
+const { data: products } = await baasix.items('products').find({
+  filter: { status: { eq: 'active' } },
+  sort: { createdAt: 'desc' },
+  limit: 10,
+});
+
+// Create item
+const productId = await baasix.items('products').create({
+  name: 'New Product',
+  price: 29.99,
+});
+```
+
+## Configuration
+
+### Basic Configuration
+
+```typescript
+import { createBaasix } from '@tspvivek/baasix-sdk';
+
+const baasix = createBaasix({
+  url: 'https://api.example.com',        // Required: Your Baasix URL
+  authMode: 'jwt',                        // 'jwt' (default) or 'cookie'
+  timeout: 30000,                         // Request timeout in ms (default: 30000)
+  autoRefresh: true,                      // Auto-refresh tokens (default: true)
+  onAuthStateChange: (event, user) => {   // Auth state callback
+    console.log('Auth changed:', event, user);
+  },
+});
+```
+
+### React Native Setup
+
+```typescript
+import { createBaasix, AsyncStorageAdapter } from '@tspvivek/baasix-sdk';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+const baasix = createBaasix({
+  url: 'https://api.example.com',
+  storage: new AsyncStorageAdapter(AsyncStorage),
+});
+```
+
+### Cookie Mode (Web with HTTP-only cookies)
+
+```typescript
+const baasix = createBaasix({
+  url: 'https://api.example.com',
+  authMode: 'cookie',
+  credentials: 'include', // Required for cookies
+});
+```
+
+### Server-Side / Service Account
+
+```typescript
+const baasix = createBaasix({
+  url: 'https://api.example.com',
+  token: 'your-service-account-token', // Static token
+});
+```
+
+## Authentication
+
+### Register
+
+```typescript
+const { user, token } = await baasix.auth.register({
+  email: 'newuser@example.com',
+  password: 'securepassword',
+  firstName: 'John',
+  lastName: 'Doe',
+});
+```
+
+### Login
+
+```typescript
+const { user, token } = await baasix.auth.login({
+  email: 'user@example.com',
+  password: 'password123',
+});
+
+// With tenant (multi-tenant mode)
+const result = await baasix.auth.login({
+  email: 'user@example.com',
+  password: 'password123',
+  tenantId: 'tenant-uuid',
+});
+```
+
+### Get Current User
+
+```typescript
+// From server (makes API call)
+const user = await baasix.auth.getUser();
+
+// From cache (no API call)
+const cachedUser = await baasix.auth.getCachedUser();
+```
+
+### Logout
+
+```typescript
+await baasix.auth.logout();
+```
+
+### Check Authentication
+
+```typescript
+if (await baasix.auth.isAuthenticated()) {
+  // User is logged in
+}
+```
+
+### Magic Link Login
+
+```typescript
+// Send magic link
+await baasix.auth.sendMagicLink({
+  email: 'user@example.com',
+  redirectUrl: 'https://myapp.com/auth/callback',
+});
+
+// Verify (after user clicks link)
+const { user, token } = await baasix.auth.verifyMagicLink('verification-token');
+```
+
+### Password Reset
+
+```typescript
+// Request reset
+await baasix.auth.forgotPassword({
+  email: 'user@example.com',
+  redirectUrl: 'https://myapp.com/reset-password',
+});
+
+// Reset password
+await baasix.auth.resetPassword('reset-token', 'newpassword123');
+```
+
+### Multi-Tenant
+
+```typescript
+// Get available tenants
+const tenants = await baasix.auth.getTenants();
+
+// Switch tenant
+const { user, token } = await baasix.auth.switchTenant('tenant-uuid');
+```
+
+## Items (CRUD Operations)
+
+### Query Items
+
+```typescript
+const items = baasix.items('products');
+
+// Basic find
+const { data, totalCount } = await items.find();
+
+// With parameters
+const { data: activeProducts } = await items.find({
+  filter: { status: { eq: 'active' } },
+  sort: { createdAt: 'desc' },
+  limit: 20,
+  page: 1,
+  fields: ['id', 'name', 'price', 'category.*'],
+});
+
+// Find one by ID
+const product = await items.findOne('product-uuid');
+
+// With related data
+const product = await items.findOne('product-uuid', {
+  fields: ['*', 'category.*', 'reviews.*'],
+});
+```
+
+### Query Builder
+
+```typescript
+const results = await baasix.items('posts')
+  .query()
+  .select('*', 'author.*', 'comments.*')
+  .filter({
+    AND: [
+      { status: { eq: 'published' } },
+      { createdAt: { gte: '$NOW-DAYS_30' } },
+    ],
+  })
+  .sort({ createdAt: 'desc' })
+  .limit(10)
+  .page(1)
+  .get();
+
+// First result only
+const post = await baasix.items('posts')
+  .query()
+  .filter({ slug: { eq: 'my-post' } })
+  .first();
+
+// Count
+const count = await baasix.items('products')
+  .query()
+  .filter({ inStock: { eq: true } })
+  .count();
+```
+
+### Create Items
+
+```typescript
+// Single item
+const id = await baasix.items('products').create({
+  name: 'New Product',
+  price: 29.99,
+  status: 'draft',
+});
+
+// Multiple items
+const ids = await baasix.items('products').createMany([
+  { name: 'Product 1', price: 10 },
+  { name: 'Product 2', price: 20 },
+]);
+```
+
+### Update Items
+
+```typescript
+// Single item
+await baasix.items('products').update('product-uuid', {
+  price: 24.99,
+  status: 'published',
+});
+
+// Multiple items
+await baasix.items('products').updateMany(
+  ['id1', 'id2', 'id3'],
+  { status: 'archived' }
+);
+
+// Upsert (create or update)
+const id = await baasix.items('products').upsert(
+  { sku: { eq: 'SKU-001' } },
+  { name: 'Widget', price: 29.99, sku: 'SKU-001' }
+);
+```
+
+### Delete Items
+
+```typescript
+// Single item
+await baasix.items('products').delete('product-uuid');
+
+// Multiple items
+await baasix.items('products').deleteMany(['id1', 'id2', 'id3']);
+
+// Soft delete (if paranoid mode enabled)
+await baasix.items('products').softDelete('product-uuid');
+
+// Restore soft-deleted
+await baasix.items('products').restore('product-uuid');
+```
+
+### Aggregation
+
+```typescript
+const results = await baasix.items('orders').aggregate({
+  aggregate: {
+    totalRevenue: { function: 'sum', field: 'total' },
+    orderCount: { function: 'count', field: 'id' },
+    avgOrderValue: { function: 'avg', field: 'total' },
+  },
+  groupBy: ['status', 'category'],
+  filter: { createdAt: { gte: '$NOW-DAYS_30' } },
+});
+```
+
+## Filter Operators
+
+Baasix supports 50+ filter operators:
+
+```typescript
+// Comparison
+{ field: { eq: value } }        // Equal
+{ field: { ne: value } }        // Not equal
+{ field: { gt: value } }        // Greater than
+{ field: { gte: value } }       // Greater than or equal
+{ field: { lt: value } }        // Less than
+{ field: { lte: value } }       // Less than or equal
+
+// Collection
+{ field: { in: [1, 2, 3] } }    // In list
+{ field: { notIn: [1, 2, 3] } } // Not in list
+
+// String
+{ field: { like: 'pattern' } }        // LIKE (case-sensitive)
+{ field: { iLike: 'pattern' } }       // ILIKE (case-insensitive)
+{ field: { startsWith: 'prefix' } }   // Starts with
+{ field: { endsWith: 'suffix' } }     // Ends with
+{ field: { contains: 'substring' } }  // Contains
+
+// Range
+{ field: { between: [10, 100] } }     // Between
+
+// Null
+{ field: { isNull: true } }           // Is null
+{ field: { isNotNull: true } }        // Is not null
+
+// Array (PostgreSQL)
+{ tags: { arraycontains: ['js', 'api'] } }
+
+// JSONB
+{ metadata: { jsonbHasKey: 'discount' } }
+{ metadata: { jsonbKeyEquals: { key: 'status', value: 'active' } } }
+
+// Logical
+{ AND: [{ status: { eq: 'active' } }, { price: { gt: 0 } }] }
+{ OR: [{ status: { eq: 'featured' } }, { views: { gt: 1000 } }] }
+
+// Relation filtering
+{ 'author.name': { like: 'John' } }
+
+// Dynamic variables
+{ author_Id: { eq: '$CURRENT_USER' } }
+{ createdAt: { gte: '$NOW-DAYS_30' } }
+```
+
+## Files
+
+### Upload Files
+
+```typescript
+// Browser
+const fileMetadata = await baasix.files.upload(fileInput.files[0], {
+  title: 'Product Image',
+  folder: 'products',
+  isPublic: true,
+  onProgress: (progress) => console.log(`${progress}% uploaded`),
+});
+
+// React Native with expo-image-picker
+const metadata = await baasix.files.upload({
+  uri: result.uri,
+  name: 'photo.jpg',
+  type: 'image/jpeg',
+});
+```
+
+### Get Asset URLs
+
+```typescript
+// Original file
+const url = baasix.files.getAssetUrl('file-uuid');
+
+// With transformations
+const thumbnailUrl = baasix.files.getAssetUrl('file-uuid', {
+  width: 200,
+  height: 200,
+  fit: 'cover',
+  quality: 80,
+  format: 'webp',
+});
+```
+
+### File Operations
+
+```typescript
+// List files
+const { data: files } = await baasix.files.find({
+  filter: { mimeType: { startsWith: 'image/' } },
+});
+
+// Get file info
+const file = await baasix.files.findOne('file-uuid');
+
+// Download file
+const blob = await baasix.files.download('file-uuid');
+
+// Delete file
+await baasix.files.delete('file-uuid');
+```
+
+## Schemas
+
+### Create Collection
+
+```typescript
+await baasix.schemas.create({
+  collectionName: 'products',
+  schema: {
+    name: 'Product',
+    timestamps: true,
+    paranoid: true, // Soft deletes
+    fields: {
+      id: {
+        type: 'UUID',
+        primaryKey: true,
+        defaultValue: { type: 'UUIDV4' },
+      },
+      name: {
+        type: 'String',
+        allowNull: false,
+        values: { length: 255 },
+      },
+      price: {
+        type: 'Decimal',
+        values: { precision: 10, scale: 2 },
+        defaultValue: 0,
+      },
+      tags: {
+        type: 'Array',
+        values: { type: 'String' },
+        defaultValue: [],
+      },
+      metadata: {
+        type: 'JSONB',
+        defaultValue: {},
+      },
+    },
+  },
+});
+```
+
+### Relationships
+
+```typescript
+// Many-to-One (BelongsTo)
+await baasix.schemas.createRelationship('products', {
+  type: 'M2O',
+  target: 'categories',
+  name: 'category',
+  alias: 'products',
+});
+
+// Many-to-Many
+await baasix.schemas.createRelationship('products', {
+  type: 'M2M',
+  target: 'tags',
+  name: 'tags',
+  alias: 'products',
+});
+```
+
+### Indexes
+
+```typescript
+await baasix.schemas.createIndex('products', {
+  name: 'idx_products_sku',
+  fields: ['sku'],
+  unique: true,
+});
+```
+
+## Reports & Analytics
+
+```typescript
+// Generate report
+const report = await baasix.reports.generate('orders', {
+  aggregate: {
+    revenue: { function: 'sum', field: 'total' },
+    orders: { function: 'count', field: 'id' },
+  },
+  groupBy: 'category',
+  filter: { status: { eq: 'completed' } },
+  dateRange: {
+    start: '2025-01-01',
+    end: '2025-12-31',
+  },
+});
+
+// Quick count
+const activeUsers = await baasix.reports.count('users', {
+  status: { eq: 'active' },
+});
+```
+
+## Workflows
+
+```typescript
+// Execute workflow
+const result = await baasix.workflows.execute('workflow-uuid', {
+  orderId: 'order-123',
+});
+
+// Get execution history
+const { data: executions } = await baasix.workflows.getExecutions('workflow-uuid');
+
+// Subscribe to execution updates (requires realtime)
+const unsubscribe = baasix.realtime.subscribeToExecution(executionId, (update) => {
+  console.log('Execution progress:', update.progress, '%');
+  if (update.status === 'complete') {
+    console.log('Workflow finished!', update.result);
+  }
+});
+```
+
+## Realtime Subscriptions
+
+The SDK supports real-time data updates via WebSocket connections.
+
+### Setup
+
+```typescript
+// Install socket.io-client separately
+npm install socket.io-client
+
+// Initialize realtime
+import { io } from 'socket.io-client';
+
+// Set the socket client
+baasix.realtime.setSocketClient(io);
+
+// Connect to realtime server
+await baasix.realtime.connect();
+```
+
+### Subscribe to Collections
+
+```typescript
+// Subscribe to all changes on a collection
+const unsubscribe = baasix.realtime.subscribe('products', (payload) => {
+  console.log(`Product ${payload.action}:`, payload.data);
+  // payload.action: 'create' | 'update' | 'delete'
+  // payload.data: the created/updated/deleted item
+  // payload.timestamp: ISO timestamp
+});
+
+// Subscribe to specific events only
+const unsubscribe = baasix.realtime.on('orders', 'create', (data) => {
+  console.log('New order received:', data);
+});
+
+// Unsubscribe when done
+unsubscribe();
+```
+
+### Supabase-style Channel API
+
+```typescript
+const channel = baasix.realtime
+  .channel('products')
+  .on('INSERT', (payload) => console.log('New:', payload))
+  .on('UPDATE', (payload) => console.log('Updated:', payload))
+  .on('DELETE', (payload) => console.log('Deleted:', payload))
+  .subscribe();
+
+// Later
+channel.unsubscribe();
+```
+
+### Connection Management
+
+```typescript
+// Check connection status
+if (baasix.realtime.isConnected) {
+  console.log('Connected to realtime server');
+}
+
+// Listen for connection changes
+baasix.realtime.onConnectionChange((connected) => {
+  console.log('Realtime:', connected ? 'online' : 'offline');
+});
+
+// Disconnect
+baasix.realtime.disconnect();
+```
+
+## OAuth / Social Login
+
+```typescript
+// Redirect to OAuth provider
+const url = baasix.auth.getOAuthUrl({
+  provider: 'google', // 'google' | 'facebook' | 'apple' | 'github'
+  redirectUrl: 'https://myapp.com/auth/callback',
+});
+window.location.href = url;
+
+// In your callback page
+const params = new URLSearchParams(window.location.search);
+const token = params.get('token');
+
+if (token) {
+  const { user } = await baasix.auth.handleOAuthCallback(token);
+  console.log('Logged in as:', user.email);
+}
+```
+
+## Invitation System (Multi-tenant)
+
+```typescript
+// Send invitation
+await baasix.auth.sendInvite({
+  email: 'newuser@example.com',
+  roleId: 'editor-role-uuid',
+  tenantId: 'tenant-uuid',
+  redirectUrl: 'https://myapp.com/accept-invite',
+});
+
+// Verify invitation token (in callback page)
+const result = await baasix.auth.verifyInvite(token);
+if (result.valid) {
+  // Show registration form with pre-filled email
+  console.log('Invite for:', result.email);
+}
+
+// Register with invitation
+const { user } = await baasix.auth.registerWithInvite({
+  email: 'newuser@example.com',
+  password: 'password123',
+  firstName: 'John',
+  lastName: 'Doe',
+  inviteToken: token,
+});
+```
+
+## Users Management (Admin)
+
+```typescript
+// List users
+const { data: users } = await baasix.users.find({
+  filter: { status: { eq: 'active' } },
+  limit: 20,
+});
+
+// Create user
+const userId = await baasix.users.create({
+  email: 'user@example.com',
+  password: 'password123',
+  firstName: 'John',
+  role_Id: 'role-uuid',
+});
+
+// Update user
+await baasix.users.update(userId, { firstName: 'Jane' });
+
+// Admin password change
+await baasix.users.changePassword(userId, 'newPassword123');
+
+// Suspend/Activate user
+await baasix.users.suspend(userId);
+await baasix.users.activate(userId);
+```
+
+## Roles Management
+
+```typescript
+// List roles
+const { data: roles } = await baasix.roles.find();
+
+// Find by name
+const adminRole = await baasix.roles.findByName('Administrator');
+
+// Create role
+const roleId = await baasix.roles.create({
+  name: 'Editor',
+  description: 'Content editors',
+  appAccess: true,
+});
+
+// Update role
+await baasix.roles.update(roleId, { description: 'Updated description' });
+```
+
+## CSV/JSON Import
+
+```typescript
+// Import from CSV file
+const result = await baasix.items('products').importCSV(csvFile, {
+  delimiter: ',',
+  skipFirstRow: true,
+});
+console.log(`Created: ${result.created}, Errors: ${result.errors.length}`);
+
+// Import from JSON file
+const result = await baasix.items('products').importJSON(jsonFile);
+
+// Import from data array
+const result = await baasix.items('products').importData([
+  { name: 'Product 1', price: 29.99 },
+  { name: 'Product 2', price: 39.99 },
+]);
+```
+
+## Migrations (Admin)
+
+```typescript
+// Check migration status
+const status = await baasix.migrations.status();
+console.log(`Pending: ${status.pendingCount}`);
+
+// Run pending migrations
+if (status.hasPending) {
+  const result = await baasix.migrations.run();
+  console.log(`Ran ${result.migrationsRun.length} migrations`);
+}
+
+// Rollback last batch
+const rollback = await baasix.migrations.rollbackLast();
+```
+
+## Notifications
+
+```typescript
+// Get notifications
+const { data } = await baasix.notifications.find({
+  limit: 20,
+  seen: false,
+});
+
+// Mark as seen
+await baasix.notifications.markAsSeen('notification-uuid');
+await baasix.notifications.markAllSeen();
+
+// Get unread count
+const count = await baasix.notifications.getUnreadCount();
+```
+
+## Custom Storage Adapter
+
+Create a custom storage adapter for any environment:
+
+```typescript
+import { StorageAdapter } from '@tspvivek/baasix-sdk';
+
+class MyCustomStorage implements StorageAdapter {
+  async get(key: string): Promise<string | null> {
+    // Your implementation
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    // Your implementation
+  }
+
+  async remove(key: string): Promise<void> {
+    // Your implementation
+  }
+
+  async clear(): Promise<void> {
+    // Your implementation
+  }
+}
+
+const baasix = createBaasix({
+  url: 'https://api.example.com',
+  storage: new MyCustomStorage(),
+});
+```
+
+## Error Handling
+
+```typescript
+import { BaasixError } from '@tspvivek/baasix-sdk';
+
+try {
+  await baasix.items('products').create({ name: 'Product' });
+} catch (error) {
+  if (error instanceof BaasixError) {
+    console.error('Status:', error.status);
+    console.error('Code:', error.code);
+    console.error('Message:', error.message);
+    console.error('Details:', error.details);
+
+    if (error.status === 401) {
+      // Handle unauthorized
+    }
+    if (error.status === 403) {
+      // Handle forbidden
+    }
+    if (error.isRetryable) {
+      // Can retry request
+    }
+  }
+}
+```
+
+## TypeScript Support
+
+Use generics for type-safe operations:
+
+```typescript
+interface Product {
+  id: string;
+  name: string;
+  price: number;
+  category_Id: string;
+  createdAt: string;
+}
+
+// Typed items module
+const products = baasix.items<Product>('products');
+
+// Type inference
+const { data } = await products.find();
+// data is Product[]
+
+const product = await products.findOne('uuid');
+// product is Product
+
+await products.create({
+  name: 'Widget',
+  price: 29.99,
+  category_Id: 'cat-uuid',
+}); // Type-checked
+```
+
+## React Example
+
+```tsx
+import { createBaasix } from '@tspvivek/baasix-sdk';
+import { useEffect, useState } from 'react';
+
+const baasix = createBaasix({
+  url: process.env.REACT_APP_BAASIX_URL!,
+  onAuthStateChange: (event, user) => {
+    console.log('Auth:', event, user);
+  },
+});
+
+function App() {
+  const [user, setUser] = useState(null);
+  const [products, setProducts] = useState([]);
+
+  useEffect(() => {
+    // Initialize auth on mount
+    baasix.auth.initialize().then((state) => {
+      setUser(state.user);
+    });
+  }, []);
+
+  useEffect(() => {
+    // Fetch products
+    baasix.items('products')
+      .find({ filter: { status: { eq: 'active' } } })
+      .then(({ data }) => setProducts(data));
+  }, []);
+
+  const handleLogin = async (email, password) => {
+    const { user } = await baasix.auth.login({ email, password });
+    setUser(user);
+  };
+
+  const handleLogout = async () => {
+    await baasix.auth.logout();
+    setUser(null);
+  };
+
+  return (
+    <div>
+      {user ? (
+        <>
+          <p>Welcome, {user.email}</p>
+          <button onClick={handleLogout}>Logout</button>
+        </>
+      ) : (
+        <LoginForm onSubmit={handleLogin} />
+      )}
+      <ProductList products={products} />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### `createBaasix(config)`
+
+Creates a new Baasix SDK instance.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | `string` | Required | Your Baasix server URL |
+| `authMode` | `'jwt' \| 'cookie'` | `'jwt'` | Authentication mode |
+| `storage` | `StorageAdapter` | Auto-detected | Token storage adapter |
+| `token` | `string` | - | Static auth token |
+| `timeout` | `number` | `30000` | Request timeout (ms) |
+| `autoRefresh` | `boolean` | `true` | Auto-refresh tokens |
+| `headers` | `object` | `{}` | Custom headers |
+| `tenantId` | `string` | - | Multi-tenant ID |
+| `credentials` | `RequestCredentials` | Based on authMode | Fetch credentials |
+| `onAuthStateChange` | `function` | - | Auth state callback |
+| `onError` | `function` | - | Global error handler |
+
+### Storage Adapters
+
+- `LocalStorageAdapter` - Browser localStorage (default for web)
+- `MemoryStorageAdapter` - In-memory (default for SSR/Node.js)
+- `AsyncStorageAdapter` - React Native AsyncStorage
+
+## License
+
+MIT © [Vivek Palanisamy](https://www.baasix.com)