@vaiftechnologies/vaif-client 0.1.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 VAIF Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,554 @@
+# @vaiftechnologies/vaif-client
+
+[![npm version](https://img.shields.io/npm/v/@vaiftechnologies/vaif-client)](https://www.npmjs.com/package/@vaiftechnologies/vaif-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-4.7+-blue)](https://www.typescriptlang.org/)
+
+The official JavaScript/TypeScript SDK for VAIF Studio - the AI-powered backend platform. Database, auth, realtime, storage, functions, AI generation, and more.
+
+## Installation
+
+```bash
+npm install @vaiftechnologies/vaif-client
+# or
+pnpm add @vaiftechnologies/vaif-client
+# or
+yarn add @vaiftechnologies/vaif-client
+```
+
+## Quick Start
+
+```typescript
+import { createClient } from '@vaiftechnologies/vaif-client';
+
+const vaif = createClient({
+  projectId: 'your-project-id',
+  apiKey: 'your-api-key',
+});
+
+// Database - fluent query builder
+const { data: users } = await vaif.db
+  .from('users')
+  .select('id, name, email')
+  .eq('active', true)
+  .order('created_at', { ascending: false })
+  .limit(10)
+  .execute();
+
+// Realtime - WebSocket subscriptions
+vaif.realtime.connect();
+vaif.realtime.channel('messages')
+  .on('postgres_changes', { event: 'INSERT', table: 'messages' }, (payload) => {
+    console.log('New message:', payload);
+  })
+  .subscribe();
+
+// Storage - file upload with CDN
+const { data } = await vaif.storage.from('avatars').upload('user.png', file);
+
+// Functions - edge function invocation
+const { data: result } = await vaif.functions.invoke('send-email', {
+  body: { to: 'user@example.com', subject: 'Hello' },
+});
+```
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| `vaif.db` | Database operations with fluent query builder |
+| `vaif.auth` | Authentication (email, OAuth, OTP, MFA) |
+| `vaif.realtime` | WebSocket subscriptions, channels, presence |
+| `vaif.storage` | File storage with CDN and image transforms |
+| `vaif.functions` | Edge function invocation |
+| `vaif.ai` | AI-powered code generation and chat |
+| `vaif.schema` | Database schema management and migrations |
+| `vaif.typegen` | TypeScript type generation from DB schema |
+| `vaif.projects` | Project management |
+| `vaif.apiKeys` | API key management |
+| `vaif.integrations` | Webhooks and event subscriptions |
+| `vaif.admin` | Platform admin endpoints |
+
+## Database
+
+### Query Builder
+
+```typescript
+interface User {
+  id: string;
+  email: string;
+  name: string;
+  active: boolean;
+  created_at: string;
+}
+
+// Select with filters
+const { data, error } = await vaif.db
+  .from<User>('users')
+  .select('id, name, email')
+  .eq('active', true)
+  .order('created_at', { ascending: false })
+  .limit(10)
+  .execute();
+
+// Get single record
+const { data: user, error } = await vaif.db
+  .from<User>('users')
+  .eq('id', 'user-123')
+  .single();
+
+// Get single or null
+const { data: user } = await vaif.db
+  .from<User>('users')
+  .eq('email', 'test@example.com')
+  .maybeSingle();
+
+// Insert
+const { data: newUser } = await vaif.db
+  .from<User>('users')
+  .insert({ email: 'new@example.com', name: 'New User', active: true })
+  .execute();
+
+// Upsert (insert or update on conflict)
+const { data } = await vaif.db
+  .from<User>('users')
+  .insert({ email: 'user@example.com', name: 'Updated' })
+  .onConflict('email')
+  .doUpdate({ name: 'Updated' })
+  .execute();
+
+// Update
+const { data: updated } = await vaif.db
+  .from<User>('users')
+  .update({ name: 'New Name' })
+  .eq('id', 'user-123')
+  .execute();
+
+// Delete
+await vaif.db.from('users').delete().eq('id', 'user-123').execute();
+```
+
+### Filters
+
+```typescript
+vaif.db.from('posts')
+  .eq('status', 'published')        // column = value
+  .neq('author_id', null)           // column != value
+  .gt('views', 100)                 // column > value
+  .gte('rating', 4.0)              // column >= value
+  .lt('price', 50)                  // column < value
+  .lte('stock', 10)                // column <= value
+  .like('title', '%TypeScript%')    // LIKE (case-sensitive)
+  .ilike('title', '%typescript%')   // ILIKE (case-insensitive)
+  .is('deleted_at', null)           // IS NULL
+  .in('status', ['draft', 'review']) // IN (...)
+  .contains('tags', ['js', 'ts'])   // @> (array contains)
+  .containedBy('tags', ['js', 'ts', 'go']) // <@ (contained by)
+  .overlaps('tags', ['js', 'python'])      // && (array overlap)
+  .textSearch('body', 'search query')       // Full-text search
+  .not.eq('role', 'admin')          // Negate any filter
+  .or('status.eq.draft,status.eq.review')   // OR conditions
+  .order('created_at', { ascending: false, nullsFirst: false })
+  .limit(20)
+  .offset(40)
+  .range(0, 9)                      // Shorthand for offset + limit
+  .count('exact')                   // Include total count
+  .execute();
+```
+
+### Raw SQL and RPC
+
+```typescript
+// Raw SQL (admin only)
+const { data } = await vaif.db.raw<User>(
+  'SELECT * FROM users WHERE created_at > $1',
+  ['2024-01-01']
+);
+
+// Stored procedure
+const { data } = await vaif.db.rpc('get_user_stats', { userId: '123' });
+```
+
+## Authentication
+
+```typescript
+// Sign up
+const { data, error } = await vaif.auth.signUp({
+  email: 'user@example.com',
+  password: 'secure-password',
+  data: { name: 'John' },
+});
+
+// Sign in with password
+const { data, error } = await vaif.auth.signInWithPassword({
+  email: 'user@example.com',
+  password: 'secure-password',
+});
+
+// Sign in with OAuth
+const { data } = await vaif.auth.signInWithOAuth({
+  provider: 'google',
+  redirectTo: 'https://myapp.com/callback',
+  scopes: 'email profile',
+});
+
+// Sign in with magic link / OTP
+await vaif.auth.signInWithOtp({
+  email: 'user@example.com',
+  redirectTo: 'https://myapp.com/verify',
+});
+
+// Verify OTP
+const { data } = await vaif.auth.verifyOtp({
+  email: 'user@example.com',
+  token: '123456',
+  type: 'magiclink',
+});
+
+// Get current user
+const { data: { user } } = await vaif.auth.getUser();
+
+// Listen to auth changes
+const { data: { subscription } } = vaif.auth.onAuthStateChange((event, session) => {
+  console.log('Auth event:', event, session);
+});
+
+// Sign out
+await vaif.auth.signOut();
+
+// Refresh session
+await vaif.auth.refreshSession();
+
+// Reset password
+await vaif.auth.resetPasswordForEmail({
+  email: 'user@example.com',
+  redirectTo: 'https://myapp.com/reset',
+});
+```
+
+## Realtime
+
+```typescript
+// Connect to realtime server
+vaif.realtime.connect();
+
+// Subscribe to database changes
+const channel = vaif.realtime.channel('my-channel')
+  .on('postgres_changes', {
+    event: 'INSERT',
+    schema: 'public',
+    table: 'messages',
+    filter: 'room_id=eq.123',
+  }, (payload) => {
+    console.log('New message:', payload.new);
+  })
+  .on('postgres_changes', {
+    event: 'UPDATE',
+    schema: 'public',
+    table: 'messages',
+  }, (payload) => {
+    console.log('Updated:', payload.new);
+  })
+  .subscribe();
+
+// Broadcast messages
+channel.broadcast('typing', { userId: 'user-123' });
+
+// Presence tracking
+channel.track({ userId: 'user-123', status: 'online' });
+const presenceState = channel.getPresenceState();
+
+channel.on('presence', { event: 'sync' }, (state) => {
+  console.log('Online users:', state);
+});
+
+// Cleanup
+channel.unsubscribe();
+vaif.realtime.removeChannel('my-channel');
+vaif.realtime.disconnect();
+```
+
+## Storage
+
+```typescript
+// Upload file
+const { data, error } = await vaif.storage
+  .from('avatars')
+  .upload('user-123/avatar.jpg', file, {
+    contentType: 'image/jpeg',
+    upsert: true,
+    cacheControl: '3600',
+    metadata: { userId: 'user-123' },
+  });
+
+// Download file
+const { data: blob } = await vaif.storage
+  .from('avatars')
+  .download('user-123/avatar.jpg');
+
+// Download with image transform
+const { data: thumbnail } = await vaif.storage
+  .from('avatars')
+  .download('user-123/avatar.jpg', {
+    transform: { width: 100, height: 100, resize: 'cover', format: 'webp', quality: 80 },
+  });
+
+// Get public URL
+const { data: { publicUrl } } = vaif.storage
+  .from('avatars')
+  .getPublicUrl('user-123/avatar.jpg');
+
+// Create signed URL (temporary access)
+const { data } = await vaif.storage
+  .from('private')
+  .createSignedUrl('document.pdf', { expiresIn: 3600 });
+
+// List files
+const { data: files } = await vaif.storage
+  .from('avatars')
+  .list('user-123/', { limit: 100, sortBy: { column: 'name', order: 'asc' } });
+
+// Move/copy/delete
+await vaif.storage.from('avatars').move('old-path.jpg', 'new-path.jpg');
+await vaif.storage.from('avatars').copy('source.jpg', 'dest.jpg');
+await vaif.storage.from('avatars').remove(['old-file.jpg', 'another.jpg']);
+
+// Bucket management
+const { data: buckets } = await vaif.storage.listBuckets();
+await vaif.storage.createBucket('documents', {
+  public: false,
+  fileSizeLimit: 10_000_000,
+  allowedMimeTypes: ['application/pdf', 'image/*'],
+});
+await vaif.storage.deleteBucket('old-bucket');
+```
+
+## Edge Functions
+
+```typescript
+// Invoke a function
+const { data, error } = await vaif.functions.invoke<{ sent: boolean }>('send-email', {
+  body: { to: 'user@example.com', subject: 'Hello' },
+  headers: { 'x-custom-header': 'value' },
+  timeout: 15000,
+});
+
+// Get function URL for direct use
+const url = vaif.functions.createUrl('send-email');
+
+// List deployed functions
+const { data: functions } = await vaif.functions.list();
+
+// Get function details
+const { data: fn } = await vaif.functions.get('send-email');
+```
+
+## AI Generation
+
+```typescript
+// Generate database schema from natural language
+const { data, error } = await vaif.ai.generateSchema({
+  prompt: 'Create a blog with posts, authors, and comments',
+  format: 'drizzle',
+  includeRelations: true,
+});
+
+// Generate edge function
+const { data } = await vaif.ai.generateFunction({
+  prompt: 'Create a function that sends welcome emails',
+  name: 'send-welcome-email',
+  runtime: 'edge',
+});
+
+// Generate API endpoint
+const { data } = await vaif.ai.generateEndpoint({
+  prompt: 'Get user profile with recent posts',
+  method: 'GET',
+  path: '/users/:id/profile',
+  requiresAuth: true,
+});
+
+// AI chat assistant
+const { data } = await vaif.ai.chat({
+  messages: [
+    { role: 'user', content: 'How do I add pagination to my posts query?' },
+  ],
+  context: { schema: mySchemaString },
+});
+
+// Streaming chat
+for await (const chunk of vaif.ai.chatStream({
+  messages: [{ role: 'user', content: 'Explain this schema' }],
+})) {
+  process.stdout.write(chunk);
+}
+
+// Code review
+const { data } = await vaif.ai.review(code, {
+  language: 'typescript',
+  focus: ['security', 'performance'],
+});
+
+// Generate SQL migration
+const { data } = await vaif.ai.generateMigration({
+  currentSchema: oldSchema,
+  targetSchema: newSchema,
+  database: 'postgresql',
+});
+
+// Check AI credits
+const { data: credits } = await vaif.ai.getCredits();
+console.log(`Balance: ${credits.balance} credits`);
+```
+
+## Configuration
+
+```typescript
+import { createClient } from '@vaiftechnologies/vaif-client';
+
+const vaif = createClient({
+  // Required
+  projectId: 'your-project-id',
+  apiKey: 'your-api-key',
+
+  // API endpoints
+  apiUrl: 'https://api.vaif.studio',           // Custom API URL
+  realtimeUrl: 'wss://realtime.vaif.studio',   // Custom WebSocket URL
+
+  // Request options
+  timeout: 30000,                               // Request timeout (ms)
+  headers: { 'x-custom': 'value' },            // Custom headers
+
+  // Auth
+  autoRefreshToken: true,                       // Auto-refresh JWT
+  persistSession: true,                         // Persist to storage
+  storage: customStorageAdapter,                // Custom storage
+
+  // Retry with exponential backoff
+  retry: {
+    maxRetries: 3,                              // Max retry attempts
+    retryDelay: 1000,                           // Initial delay (ms)
+    maxRetryDelay: 30000,                       // Max delay (ms)
+    backoffMultiplier: 2,                       // Exponential multiplier
+    retryOn: [429, 500, 502, 503, 504],        // Status codes to retry
+    retryOnNetworkError: true,                  // Retry on network errors
+  },
+
+  // Interceptors for observability
+  interceptors: {
+    onRequest: (ctx) => {
+      console.log(`${ctx.method} ${ctx.path} (attempt ${ctx.attempt})`);
+      return ctx; // optionally modify request
+    },
+    onResponse: (ctx) => {
+      console.log(`${ctx.status} in ${ctx.durationMs}ms`);
+    },
+    onError: (ctx) => {
+      console.error(`Error: ${ctx.error.message}`, ctx.willRetry ? '(retrying)' : '');
+    },
+  },
+
+  // Debug
+  debug: false,
+});
+```
+
+## Error Handling
+
+```typescript
+import {
+  VaifError,
+  VaifAuthError,
+  VaifValidationError,
+  VaifNetworkError,
+  VaifRateLimitError,
+  VaifNotFoundError,
+  VaifConflictError,
+  VaifTimeoutError,
+  isVaifError,
+} from '@vaiftechnologies/vaif-client';
+
+// All methods return { data, error } - check error first
+const { data, error } = await vaif.db.from('users').eq('id', '123').single();
+
+if (error) {
+  console.log('Error:', error.message, error.code);
+}
+
+// Or use error classes directly
+try {
+  // ... operations that throw
+} catch (err) {
+  if (err instanceof VaifAuthError) {
+    console.log('Auth error:', err.message);
+  } else if (err instanceof VaifValidationError) {
+    console.log('Validation:', err.fieldErrors);
+  } else if (err instanceof VaifRateLimitError) {
+    console.log(`Rate limited, retry after ${err.retryAfter}s`);
+  } else if (err instanceof VaifNotFoundError) {
+    console.log('Not found');
+  } else if (err instanceof VaifTimeoutError) {
+    console.log(`Timed out after ${err.timeoutMs}ms`);
+  } else if (err instanceof VaifNetworkError) {
+    console.log('Network error:', err.cause?.message);
+  } else if (isVaifError(err)) {
+    console.log('VAIF error:', err.code, err.statusCode, err.requestId);
+  }
+}
+```
+
+### Error Hierarchy
+
+```
+VaifError (base)
+  ├── VaifAuthError        (401/403)
+  ├── VaifValidationError  (400, with fieldErrors)
+  ├── VaifRateLimitError   (429, with retryAfter)
+  ├── VaifNotFoundError    (404)
+  ├── VaifConflictError    (409)
+  └── VaifNetworkError
+        └── VaifTimeoutError
+```
+
+## TypeScript
+
+The SDK is fully typed. Use generics for type-safe operations:
+
+```typescript
+interface Post {
+  id: string;
+  title: string;
+  content: string;
+  author_id: string;
+  published: boolean;
+}
+
+// Typed queries
+const { data } = await vaif.db.from<Post>('posts')
+  .select('id, title')
+  .eq('published', true)
+  .execute();
+// data is Post[]
+
+// Typed single
+const { data: post } = await vaif.db.from<Post>('posts')
+  .eq('id', '123')
+  .single();
+// post is Post
+
+// Typed functions
+const { data } = await vaif.functions.invoke<{ count: number }>('get-stats');
+// data is { count: number }
+```
+
+## Related Packages
+
+- [@vaiftech/client](https://www.npmjs.com/package/@vaiftech/client) - Monorepo client (internal)
+- [@vaiftech/auth](https://www.npmjs.com/package/@vaiftech/auth) - Standalone auth client
+- [@vaiftech/react](https://www.npmjs.com/package/@vaiftech/react) - React hooks
+- [@vaiftech/sdk-expo](https://www.npmjs.com/package/@vaiftech/sdk-expo) - React Native/Expo SDK
+- [vaif-client (PyPI)](https://pypi.org/project/vaif-client/) - Python SDK
+
+## License
+
+MIT