@insforge/sdk 1.0.3-refresh.1 → 1.0.5-dev.0

package/README.md

@@ -1,249 +1,259 @@
-# insforge-sdk-js
-
-[![npm version](https://img.shields.io/npm/v/@insforge/sdk.svg)](https://www.npmjs.com/package/@insforge/sdk)
-[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-
-Official TypeScript/JavaScript SDK for [InsForge](https://github.com/InsForge/InsForge) - A powerful, open-source Backend-as-a-Service (BaaS) platform.
-
-## Features
-
-- **Authentication** - Email/password, OAuth (Google, GitHub), session management
-- **Database** - Full PostgreSQL database access with PostgREST
-- **Storage** - File upload and management with S3-compatible storage
-- **Edge Functions** - Serverless function invocation
-- **AI Integration** - Built-in AI capabilities
-- **TypeScript** - Full TypeScript support with type definitions
-- **Automatic OAuth Handling** - Seamless OAuth callback detection
-
-## Installation
-
-```bash
-npm install @insforge/sdk
-```
-
-Or with yarn:
-
-```bash
-yarn add @insforge/sdk
-```
-
-## Quick Start
-
-### Initialize the Client
-
-```javascript
-import { createClient } from '@insforge/sdk';
-
-const insforge = createClient({
-  baseUrl: 'http://localhost:7130' // Your InsForge backend URL
-});
-```
-
-### Authentication
-
-```javascript
-// Sign up a new user
-const { data, error } = await insforge.auth.signUp({
-  email: 'user@example.com',
-  password: 'securePassword123',
-  name: 'John Doe' // optional
-});
-
-// Sign in with email/password
-const { data, error } = await insforge.auth.signInWithPassword({
-  email: 'user@example.com',
-  password: 'securePassword123'
-});
-
-// OAuth authentication (Google, GitHub)
-await insforge.auth.signInWithOAuth({
-  provider: 'google',
-  redirectTo: 'http://localhost:3000/dashboard'
-});
-
-// Get current user
-const { data: user } = await insforge.auth.getCurrentUser();
-
-// Sign out
-await insforge.auth.signOut();
-```
-
-### Database Operations
-
-```javascript
-// Insert data
-const { data, error } = await insforge.database
-  .from('posts')
-  .insert([
-    { title: 'My First Post', content: 'Hello World!' }
-  ]);
-
-// Query data
-const { data, error } = await insforge.database
-  .from('posts')
-  .select('*')
-  .eq('author_id', userId);
-
-// Update data
-const { data, error } = await insforge.database
-  .from('posts')
-  .update({ title: 'Updated Title' })
-  .eq('id', postId);
-
-// Delete data
-const { data, error } = await insforge.database
-  .from('posts')
-  .delete()
-  .eq('id', postId);
-```
-
-### File Storage
-
-```javascript
-// Upload a file
-const file = document.querySelector('input[type="file"]').files[0];
-const { data, error } = await insforge.storage
-  .from('avatars')
-  .upload(file);
-
-// Download a file
-const { data, error } = await insforge.storage
-  .from('avatars')
-  .download('user-avatar.png');
-
-// Delete a file
-const { data, error } = await insforge.storage
-  .from('avatars')
-  .remove(['user-avatar.png']);
-
-// List files
-const { data, error } = await insforge.storage
-  .from('avatars')
-  .list();
-```
-
-### Edge Functions
-
-```javascript
-// Invoke an edge function
-const { data, error } = await insforge.functions.invoke('my-function', {
-  body: { key: 'value' }
-});
-```
-
-### AI Integration
-
-```javascript
-// Generate text completion
-const { data, error } = await insforge.ai.completion({
-  model: 'gpt-3.5-turbo',
-  prompt: 'Write a hello world program'
-});
-
-// Analyze an image
-const { data, error } = await insforge.ai.vision({
-  imageUrl: 'https://example.com/image.jpg',
-  prompt: 'Describe this image'
-});
-```
-
-## Documentation
-
-For complete API reference and advanced usage, see:
-
-- **[SDK Reference](./SDK-REFERENCE.md)** - Complete API documentation
-- **[InsForge Main Repository](https://github.com/InsForge/InsForge)** - Backend platform and setup guides
-
-## Configuration
-
-The SDK supports the following configuration options:
-
-```javascript
-const insforge = createClient({
-  baseUrl: 'http://localhost:7130',  // Required: Your InsForge backend URL
-  storageStrategy: 'localStorage'     // Optional: 'localStorage' or 'memory' (default: 'localStorage')
-});
-```
-
-## TypeScript Support
-
-The SDK is written in TypeScript and provides full type definitions:
-
-```typescript
-import { createClient, InsForgeClient, User, Session } from '@insforge/sdk';
-
-const insforge: InsForgeClient = createClient({
-  baseUrl: 'http://localhost:7130'
-});
-
-// Type-safe API calls
-const response: { data: User | null; error: Error | null } =
-  await insforge.auth.getCurrentUser();
-```
-
-## Error Handling
-
-All SDK methods return a consistent response format:
-
-```javascript
-const { data, error } = await insforge.auth.signUp({...});
-
-if (error) {
-  console.error('Error:', error.message);
-  console.error('Status:', error.statusCode);
-} else {
-  console.log('Success:', data);
-}
-```
-
-## Browser Support
-
-The SDK works in all modern browsers that support:
-- ES6+ features
-- Fetch API
-- LocalStorage (for session management)
-
-For Node.js environments, ensure you're using Node.js 18 or higher.
-
-## Contributing
-
-We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.
-
-### Development Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/InsForge/insforge-sdk-js.git
-cd insforge-sdk-js
-
-# Install dependencies
-npm install
-
-# Build the SDK
-npm run build
-
-# Run tests
-npm test
-
-# Run integration tests
-npm run test:integration
-```
-
-## License
-
-This project is licensed under the Apache License 2.0 - see the [LICENSE](./LICENSE) file for details.
-
-## Community & Support
-
-- **GitHub Issues**: [Report bugs or request features](https://github.com/InsForge/insforge-sdk-js/issues)
-- **Documentation**: [https://docs.insforge.com](https://docs.insforge.com)
-- **Main Repository**: [InsForge Backend Platform](https://github.com/InsForge/InsForge)
-
-## Related Projects
-
-- **[InsForge](https://github.com/InsForge/InsForge)** - The main InsForge backend platform
-- **[InsForge MCP](https://github.com/InsForge/insforge-mcp)** - Model Context Protocol server for InsForge
-
----
-
-Built with ❤️ by the InsForge team
+# insforge-sdk-js
+
+[![npm version](https://img.shields.io/npm/v/@insforge/sdk.svg)](https://www.npmjs.com/package/@insforge/sdk)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+Official TypeScript/JavaScript SDK for [InsForge](https://github.com/InsForge/InsForge) - A powerful, open-source Backend-as-a-Service (BaaS) platform.
+
+## Features
+
+- **Authentication** - Email/password, OAuth (Google, GitHub), session management
+- **Database** - Full PostgreSQL database access with PostgREST
+- **Storage** - File upload and management with S3-compatible storage
+- **Edge Functions** - Serverless function invocation
+- **AI Integration** - Built-in AI capabilities
+- **TypeScript** - Full TypeScript support with type definitions
+- **Automatic OAuth Handling** - Seamless OAuth callback detection
+
+## Installation
+
+```bash
+npm install @insforge/sdk
+```
+
+Or with yarn:
+
+```bash
+yarn add @insforge/sdk
+```
+
+## Quick Start
+
+### Initialize the Client
+
+```javascript
+import { createClient } from '@insforge/sdk';
+
+const insforge = createClient({
+  baseUrl: 'http://localhost:7130' // Your InsForge backend URL
+});
+```
+
+### Authentication
+
+```javascript
+// Sign up a new user
+const { data, error } = await insforge.auth.signUp({
+  email: 'user@example.com',
+  password: 'securePassword123',
+  name: 'John Doe' // optional
+});
+
+// Sign in with email/password
+const { data, error } = await insforge.auth.signInWithPassword({
+  email: 'user@example.com',
+  password: 'securePassword123'
+});
+
+// OAuth authentication (Google, GitHub)
+await insforge.auth.signInWithOAuth({
+  provider: 'google',
+  redirectTo: 'http://localhost:3000/dashboard'
+});
+
+// Get current user
+const { data: user } = await insforge.auth.getCurrentUser();
+
+// Get any user's profile by ID (public endpoint)
+const { data: profile, error } = await insforge.auth.getProfile('user-id-here');
+
+// Update current user's profile (requires authentication)
+const { data: updatedProfile, error } = await insforge.auth.setProfile({
+  displayName: 'John Doe',
+  bio: 'Software developer',
+  avatarUrl: 'https://example.com/avatar.jpg'
+});
+
+// Sign out
+await insforge.auth.signOut();
+```
+
+### Database Operations
+
+```javascript
+// Insert data
+const { data, error } = await insforge.database
+  .from('posts')
+  .insert([
+    { title: 'My First Post', content: 'Hello World!' }
+  ]);
+
+// Query data
+const { data, error } = await insforge.database
+  .from('posts')
+  .select('*')
+  .eq('author_id', userId);
+
+// Update data
+const { data, error } = await insforge.database
+  .from('posts')
+  .update({ title: 'Updated Title' })
+  .eq('id', postId);
+
+// Delete data
+const { data, error } = await insforge.database
+  .from('posts')
+  .delete()
+  .eq('id', postId);
+```
+
+### File Storage
+
+```javascript
+// Upload a file
+const file = document.querySelector('input[type="file"]').files[0];
+const { data, error } = await insforge.storage
+  .from('avatars')
+  .upload(file);
+
+// Download a file
+const { data, error } = await insforge.storage
+  .from('avatars')
+  .download('user-avatar.png');
+
+// Delete a file
+const { data, error } = await insforge.storage
+  .from('avatars')
+  .remove(['user-avatar.png']);
+
+// List files
+const { data, error } = await insforge.storage
+  .from('avatars')
+  .list();
+```
+
+### Edge Functions
+
+```javascript
+// Invoke an edge function
+const { data, error } = await insforge.functions.invoke('my-function', {
+  body: { key: 'value' }
+});
+```
+
+### AI Integration
+
+```javascript
+// Generate text completion
+const { data, error } = await insforge.ai.completion({
+  model: 'gpt-3.5-turbo',
+  prompt: 'Write a hello world program'
+});
+
+// Analyze an image
+const { data, error } = await insforge.ai.vision({
+  imageUrl: 'https://example.com/image.jpg',
+  prompt: 'Describe this image'
+});
+```
+
+## Documentation
+
+For complete API reference and advanced usage, see:
+
+- **[SDK Reference](./SDK-REFERENCE.md)** - Complete API documentation
+- **[InsForge Main Repository](https://github.com/InsForge/InsForge)** - Backend platform and setup guides
+
+## Configuration
+
+The SDK supports the following configuration options:
+
+```javascript
+const insforge = createClient({
+  baseUrl: 'http://localhost:7130',  // Required: Your InsForge backend URL
+  storageStrategy: 'localStorage'     // Optional: 'localStorage' or 'memory' (default: 'localStorage')
+});
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides full type definitions:
+
+```typescript
+import { createClient, InsForgeClient, User, Session } from '@insforge/sdk';
+
+const insforge: InsForgeClient = createClient({
+  baseUrl: 'http://localhost:7130'
+});
+
+// Type-safe API calls
+const response: { data: User | null; error: Error | null } =
+  await insforge.auth.getCurrentUser();
+```
+
+## Error Handling
+
+All SDK methods return a consistent response format:
+
+```javascript
+const { data, error } = await insforge.auth.signUp({...});
+
+if (error) {
+  console.error('Error:', error.message);
+  console.error('Status:', error.statusCode);
+} else {
+  console.log('Success:', data);
+}
+```
+
+## Browser Support
+
+The SDK works in all modern browsers that support:
+- ES6+ features
+- Fetch API
+- LocalStorage (for session management)
+
+For Node.js environments, ensure you're using Node.js 18 or higher.
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/InsForge/insforge-sdk-js.git
+cd insforge-sdk-js
+
+# Install dependencies
+npm install
+
+# Build the SDK
+npm run build
+
+# Run tests
+npm test
+
+# Run integration tests
+npm run test:integration
+```
+
+## License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](./LICENSE) file for details.
+
+## Community & Support
+
+- **GitHub Issues**: [Report bugs or request features](https://github.com/InsForge/insforge-sdk-js/issues)
+- **Documentation**: [https://docs.insforge.com](https://docs.insforge.com)
+- **Main Repository**: [InsForge Backend Platform](https://github.com/InsForge/InsForge)
+
+## Related Projects
+
+- **[InsForge](https://github.com/InsForge/InsForge)** - The main InsForge backend platform
+- **[InsForge MCP](https://github.com/InsForge/insforge-mcp)** - Model Context Protocol server for InsForge
+
+---
+
+Built with ❤️ by the InsForge team

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { UserSchema, CreateUserRequest, CreateUserResponse, CreateSessionRequest, CreateSessionResponse, OAuthProvidersSchema, GetPublicAuthConfigResponse, UserIdSchema, EmailSchema, RoleSchema, SendVerificationEmailRequest, SendResetPasswordEmailRequest, ExchangeResetPasswordTokenRequest, VerifyEmailRequest, VerifyEmailResponse, StorageFileSchema, ListObjectsResponseSchema, ChatCompletionRequest, ImageGenerationRequest, SubscribeResponse, SocketMessage } from '@insforge/shared-schemas';
-export { AuthErrorResponse, CreateSessionRequest, CreateUserRequest, RealtimeErrorPayload, SocketMessage, SubscribeResponse, UserSchema } from '@insforge/shared-schemas';
+import { UserSchema, CreateUserRequest, CreateUserResponse, CreateSessionRequest, CreateSessionResponse, OAuthProvidersSchema, GetPublicAuthConfigResponse, GetProfileResponse, SendVerificationEmailRequest, SendResetPasswordEmailRequest, ExchangeResetPasswordTokenRequest, VerifyEmailRequest, VerifyEmailResponse, StorageFileSchema, ListObjectsResponseSchema, ChatCompletionRequest, ImageGenerationRequest, SubscribeResponse, SocketMessage, SendRawEmailRequest, SendEmailResponse } from '@insforge/shared-schemas';
+export { AuthErrorResponse, CreateSessionRequest, CreateUserRequest, RealtimeErrorPayload, SendRawEmailRequest as SendEmailOptions, SendEmailResponse, SocketMessage, SubscribeResponse, UserSchema } from '@insforge/shared-schemas';
 import * as _supabase_postgrest_js from '@supabase/postgrest-js';
 
 /**
@@ -162,29 +162,13 @@ declare class TokenManager {
  * Uses shared schemas for type safety
  */
 
-/**
- * Dynamic profile type - represents flexible profile data from database
- * Fields can vary based on database schema configuration.
- * All fields are converted from snake_case (database) to camelCase (API)
- */
-type ProfileData = Record<string, any> & {
-    id: string;
-    createdAt?: string;
-    updatedAt?: string;
-};
-/**
- * Dynamic profile update type - for updating profile fields
- * Supports any fields that exist in the profile table
- */
-type UpdateProfileData = Partial<Record<string, any>>;
 declare class Auth {
     private http;
     private tokenManager;
-    private database;
     constructor(http: HttpClient, tokenManager: TokenManager);
     /**
      * Automatically detect and handle OAuth callback parameters in the URL
-     * This runs on initialization to seamlessly complete the OAuth flow
+     * This runs after initialization to seamlessly complete the OAuth flow
      * Matches the backend's OAuth callback response (backend/src/api/routes/auth.ts:540-544)
      */
     private detectAuthCallback;
@@ -248,22 +232,17 @@ declare class Auth {
      */
     getCurrentUser(): Promise<{
         data: {
-            user: {
-                id: UserIdSchema;
-                email: EmailSchema;
-                role: RoleSchema;
-            };
-            profile: ProfileData | null;
+            user: UserSchema;
         } | null;
         error: any | null;
     }>;
     /**
      * Get any user's profile by ID
-     * Returns profile information from the users table (dynamic fields)
+     * Returns profile information from the users table
      */
     getProfile(userId: string): Promise<{
-        data: ProfileData | null;
-        error: any | null;
+        data: GetProfileResponse | null;
+        error: InsForgeError | null;
     }>;
     /**
      * Get the current session (only session data, no API call)
@@ -278,10 +257,11 @@ declare class Auth {
     /**
      * Set/Update the current user's profile
      * Updates profile information in the users table (supports any dynamic fields)
+     * Requires authentication
      */
-    setProfile(profile: UpdateProfileData): Promise<{
-        data: ProfileData | null;
-        error: any | null;
+    setProfile(profile: Record<string, unknown>): Promise<{
+        data: GetProfileResponse | null;
+        error: InsForgeError | null;
     }>;
     /**
      * Send email verification (code or link based on config)
@@ -678,7 +658,8 @@ declare class Realtime {
     private connectPromise;
     private subscribedChannels;
     private eventListeners;
-    constructor(baseUrl: string, tokenManager: TokenManager);
+    private anonKey?;
+    constructor(baseUrl: string, tokenManager: TokenManager, anonKey?: string);
     private notifyListeners;
     /**
      * Connect to the realtime server
@@ -761,6 +742,47 @@ declare class Realtime {
     getSubscribedChannels(): string[];
 }
 
+/**
+ * Emails client for sending custom emails
+ *
+ * @example
+ * ```typescript
+ * // Send a simple email
+ * const { data, error } = await client.emails.send({
+ *   to: 'user@example.com',
+ *   subject: 'Welcome!',
+ *   html: '<h1>Welcome to our platform</h1>'
+ * });
+ *
+ * if (error) {
+ *   console.error('Failed to send:', error.message);
+ *   return;
+ * }
+ * // Email sent successfully - data is {} (empty object)
+ *
+ * // Send to multiple recipients with CC
+ * const { data, error } = await client.emails.send({
+ *   to: ['user1@example.com', 'user2@example.com'],
+ *   cc: 'manager@example.com',
+ *   subject: 'Team Update',
+ *   html: '<p>Here is the latest update...</p>',
+ *   replyTo: 'support@example.com'
+ * });
+ * ```
+ */
+declare class Emails {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Send a custom HTML email
+     * @param options Email options including recipients, subject, and HTML content
+     */
+    send(options: SendRawEmailRequest): Promise<{
+        data: SendEmailResponse | null;
+        error: Error | null;
+    }>;
+}
+
 /**
  * Main InsForge SDK Client
  *
@@ -808,6 +830,7 @@ declare class InsForgeClient {
     readonly ai: AI;
     readonly functions: Functions;
     readonly realtime: Realtime;
+    readonly emails: Emails;
     constructor(config?: InsForgeConfig);
     /**
      * Get the underlying HTTP client for custom requests
@@ -829,4 +852,4 @@ declare class InsForgeClient {
 
 declare function createClient(config: InsForgeConfig): InsForgeClient;
 
-export { AI, type ApiError, Auth, type AuthSession, type InsForgeConfig as ClientOptions, type ConnectionState, Database, type EventCallback, type FunctionInvokeOptions, Functions, HttpClient, InsForgeClient, type InsForgeConfig, InsForgeError, type ProfileData, Realtime, Storage, StorageBucket, type StorageResponse, TokenManager, type TokenStorage, type UpdateProfileData, createClient, InsForgeClient as default };
+export { AI, type ApiError, Auth, type AuthSession, type InsForgeConfig as ClientOptions, type ConnectionState, Database, Emails, type EventCallback, type FunctionInvokeOptions, Functions, HttpClient, InsForgeClient, type InsForgeConfig, InsForgeError, Realtime, Storage, StorageBucket, type StorageResponse, TokenManager, type TokenStorage, createClient, InsForgeClient as default };