@baasix/sdk 0.1.6 → 0.1.8

package/README.md

@@ -807,24 +807,198 @@ const categories = await baasix.reports.distinct('products', 'category');
 
 ## Workflows
 
+### Basic Operations
+
+```typescript
+// List workflows
+const { data: workflows } = await baasix.workflows.find();
+
+// Get workflow by ID
+const workflow = await baasix.workflows.findOne('workflow-uuid');
+
+// Create workflow
+const newWorkflow = await baasix.workflows.create({
+  name: 'Order Processing',
+  trigger: { type: 'hook', config: { collection: 'orders', event: 'items.create.after' } },
+  nodes: [...],
+  edges: [...],
+  isActive: true
+});
+
+// Update workflow
+await baasix.workflows.update('workflow-uuid', { name: 'Updated Name' });
+
+// Delete workflow
+await baasix.workflows.delete('workflow-uuid');
+
+// Enable/Disable workflow
+await baasix.workflows.enable('workflow-uuid');
+await baasix.workflows.disable('workflow-uuid');
+
+// Duplicate workflow
+const copy = await baasix.workflows.duplicate('workflow-uuid', { name: 'Copy' });
+```
+
+### Execution
+
 ```typescript
 // Execute workflow
 const result = await baasix.workflows.execute('workflow-uuid', {
   orderId: 'order-123',
 });
 
+// Execute a specific node
+const nodeResult = await baasix.workflows.executeNode('workflow-uuid', 'node-id', {
+  inputData: 'value'
+});
+
+// Test workflow (without persisting)
+const testResult = await baasix.workflows.test('workflow-uuid', { testData: {} });
+
 // Get execution history
-const { data: executions } = await baasix.workflows.getExecutions('workflow-uuid');
+const { data: executions } = await baasix.workflows.getExecutions('workflow-uuid', {
+  limit: 50,
+  status: 'completed'
+});
+
+// Get specific execution
+const execution = await baasix.workflows.getExecution('workflow-uuid', 'execution-uuid');
+
+// Get execution logs
+const logs = await baasix.workflows.getExecutionLogs('workflow-uuid', 'execution-uuid');
+
+// Cancel running execution
+await baasix.workflows.cancelExecution('workflow-uuid', 'execution-uuid');
 
 // Subscribe to execution updates (requires realtime)
 const unsubscribe = baasix.realtime.subscribeToExecution(executionId, (update) => {
-  console.log('Execution progress:', update.progress, '%');
+  console.log('Progress:', update.progress, '%');
   if (update.status === 'complete') {
     console.log('Workflow finished!', update.result);
   }
 });
 ```
 
+### Statistics & Validation
+
+```typescript
+// Get workflow statistics
+const stats = await baasix.workflows.getStats('workflow-uuid');
+console.log(`Total: ${stats.totalExecutions}, Success Rate: ${stats.successRate}%`);
+
+// Validate workflow definition
+const validation = await baasix.workflows.validate({
+  name: 'My Workflow',
+  nodes: [...],
+  edges: [...]
+});
+if (!validation.valid) {
+  console.log('Errors:', validation.errors);
+}
+```
+
+### Export/Import
+
+```typescript
+// Export single workflow
+const exported = await baasix.workflows.export('workflow-uuid');
+
+// Export all workflows
+const allExported = await baasix.workflows.exportAll({
+  ids: ['wf-1', 'wf-2'], // Optional: specific workflows
+  includeInactive: true
+});
+
+// Preview import
+const preview = await baasix.workflows.importPreview(file);
+console.log('Will import:', preview.workflows.length);
+console.log('Conflicts:', preview.conflicts);
+
+// Import workflows
+const result = await baasix.workflows.import(file, { overwrite: true });
+console.log(`Imported: ${result.imported}, Skipped: ${result.skipped}`);
+```
+
+## Settings
+
+```typescript
+// Get all settings
+const settings = await baasix.settings.get();
+
+// Get a specific setting
+const appName = await baasix.settings.getKey('appName');
+
+// Update settings
+await baasix.settings.update({
+  appName: 'My Application',
+  theme: 'dark'
+});
+
+// Set a specific setting
+await baasix.settings.set('appName', 'New App Name');
+
+// Get settings by app URL (multi-tenant)
+const tenantSettings = await baasix.settings.getByAppUrl('https://myapp.example.com');
+
+// Get email branding
+const branding = await baasix.settings.getBranding();
+
+// Test email configuration (admin only)
+await baasix.settings.testEmail('admin@example.com');
+
+// Reload settings cache (admin only)
+await baasix.settings.reload();
+
+// Delete tenant settings (admin only)
+await baasix.settings.deleteTenant();
+```
+
+## Permissions
+
+```typescript
+// List all permissions
+const { data: permissions } = await baasix.permissions.find();
+
+// Get permissions for a role
+const { data: rolePerms } = await baasix.permissions.findByRole('role-uuid');
+
+// Get permissions for a collection
+const { data: collectionPerms } = await baasix.permissions.findByCollection('products');
+
+// Create permission
+const permission = await baasix.permissions.create({
+  role_Id: 'editor-role-uuid',
+  collection: 'posts',
+  action: 'update',
+  fields: ['title', 'content'],
+  conditions: { author_Id: { eq: '$CURRENT_USER' } }
+});
+
+// Create CRUD permissions for a collection
+await baasix.permissions.createCrudPermissions('role-uuid', 'products', {
+  create: { fields: ['name', 'price'] },
+  read: { fields: ['*'] },
+  update: { fields: ['name', 'price'] },
+  delete: false
+});
+
+// Update permission
+await baasix.permissions.update('permission-uuid', { fields: ['*'] });
+
+// Delete permission
+await baasix.permissions.delete('permission-uuid');
+
+// Reload permissions cache (admin only)
+await baasix.permissions.reloadCache();
+
+// Export all permissions
+const exported = await baasix.permissions.export();
+
+// Import permissions
+const result = await baasix.permissions.import(exportedData, { overwrite: true });
+console.log(`Imported: ${result.imported}`);
+```
+
 ## Realtime Subscriptions
 
 The SDK supports real-time data updates via WebSocket connections.
@@ -879,6 +1053,52 @@ const channel = baasix.realtime
 channel.unsubscribe();
 ```
 
+### Custom Rooms
+
+Custom rooms enable real-time communication between users for chat, games, or collaborative features. The **first user to join** a room becomes its creator. If the creator leaves temporarily, ownership transfers to the next member — but the **original creator automatically reclaims ownership** when they rejoin. If the room empties and is recreated, the next joiner becomes the new owner.
+
+```typescript
+// Join a room
+await baasix.realtime.joinRoom('game:lobby');
+
+// Get current members (you must be in the room)
+const members = await baasix.realtime.getRoomMembers('game:lobby');
+// [{ socketId: string, userId: string|number, isCreator: boolean }, ...]
+
+// Send a message to all room members
+await baasix.realtime.sendToRoom('game:lobby', 'chat', { text: 'Hello!' });
+
+// Listen for room messages
+const unsubscribe = baasix.realtime.onRoomMessage('game:lobby', 'chat', (data) => {
+  console.log(`${data.sender.userId}: ${data.payload.text}`);
+});
+
+// Listen for users joining / leaving
+baasix.realtime.onRoomUserJoined('game:lobby', (data) => {
+  console.log(`${data.userId} joined`);
+});
+baasix.realtime.onRoomUserLeft('game:lobby', (data) => {
+  console.log(`${data.userId} left`);
+});
+
+// Kick a user — only the room creator can do this
+await baasix.realtime.kickFromRoom('game:lobby', 'target-user-id');
+
+// Listen for being kicked out (fires only on the kicked user's socket)
+baasix.realtime.onKicked('game:lobby', ({ kickedBy }) => {
+  console.log(`You were kicked by user ${kickedBy}`);
+  // Room listeners are automatically cleaned up after a kick
+});
+
+// Listen for ownership changes (fires for all members when creator changes)
+baasix.realtime.onRoomCreatorChanged('game:lobby', ({ newCreatorUserId }) => {
+  console.log(`New room owner: ${newCreatorUserId}`);
+});
+
+// Leave the room
+await baasix.realtime.leaveRoom('game:lobby');
+```
+
 ### Connection Management
 
 ```typescript

package/dist/index.cjs

@@ -2584,6 +2584,37 @@ var PermissionsModule = class {
   async reloadCache() {
     await this.client.post("/permissions/reload");
   }
+  /**
+   * Export all permissions (admin only)
+   *
+   * @example
+   * ```typescript
+   * const exported = await baasix.permissions.export();
+   * // Save to file or transfer
+   * ```
+   */
+  async export() {
+    const response = await this.client.post("/permissions-export", {});
+    return response.data;
+  }
+  /**
+   * Import permissions from exported data (admin only)
+   *
+   * @example
+   * ```typescript
+   * const result = await baasix.permissions.import(exportedData, {
+   *   overwrite: true
+   * });
+   * console.log('Imported:', result.imported, 'permissions');
+   * ```
+   */
+  async import(data, options) {
+    const response = await this.client.post("/permissions-import", {
+      ...data,
+      ...options
+    });
+    return response.data;
+  }
 };
 
 // src/modules/settings.ts
@@ -2650,6 +2681,73 @@ var SettingsModule = class {
   async set(key, value) {
     return this.update({ [key]: value });
   }
+  /**
+   * Get settings by application URL (useful for multi-tenant apps)
+   *
+   * @example
+   * ```typescript
+   * const settings = await baasix.settings.getByAppUrl('https://myapp.example.com');
+   * ```
+   */
+  async getByAppUrl(appUrl) {
+    const response = await this.client.get(
+      "/settings/by-app-url",
+      { params: { appUrl } }
+    );
+    return response.data;
+  }
+  /**
+   * Get email branding settings for the current tenant
+   *
+   * @example
+   * ```typescript
+   * const branding = await baasix.settings.getBranding();
+   * console.log(branding.logo, branding.primaryColor);
+   * ```
+   */
+  async getBranding() {
+    const response = await this.client.get(
+      "/settings/branding"
+    );
+    return response.data;
+  }
+  /**
+   * Test email configuration by sending a test email
+   *
+   * @example
+   * ```typescript
+   * await baasix.settings.testEmail('admin@example.com');
+   * ```
+   */
+  async testEmail(to) {
+    const response = await this.client.post(
+      "/settings/test-email",
+      { to }
+    );
+    return response;
+  }
+  /**
+   * Reload settings cache (admin only)
+   *
+   * @example
+   * ```typescript
+   * await baasix.settings.reload();
+   * ```
+   */
+  async reload() {
+    await this.client.post("/settings/reload");
+  }
+  /**
+   * Delete tenant settings (admin only, multi-tenant)
+   *
+   * @example
+   * ```typescript
+   * await baasix.settings.deleteTenant();
+   * ```
+   */
+  async deleteTenant() {
+    await this.client.delete("/settings/tenant");
+  }
 };
 
 // src/modules/reports.ts
@@ -3027,6 +3125,159 @@ var WorkflowsModule = class {
       ...overrides
     });
   }
+  /**
+   * Execute a specific node in a workflow
+   *
+   * @example
+   * ```typescript
+   * const result = await baasix.workflows.executeNode(
+   *   'workflow-uuid',
+   *   'node-id',
+   *   { inputData: 'value' }
+   * );
+   * ```
+   */
+  async executeNode(workflowId, nodeId, triggerData) {
+    const response = await this.client.post(
+      `/workflows/${workflowId}/nodes/${nodeId}/execute`,
+      { triggerData }
+    );
+    return response.data;
+  }
+  /**
+   * Get execution logs for a specific execution
+   *
+   * @example
+   * ```typescript
+   * const logs = await baasix.workflows.getExecutionLogs(
+   *   'workflow-uuid',
+   *   'execution-uuid'
+   * );
+   * ```
+   */
+  async getExecutionLogs(workflowId, executionId) {
+    const response = await this.client.get(
+      `/workflows/${workflowId}/executions/${executionId}/logs`
+    );
+    return response.data;
+  }
+  /**
+   * Get workflow statistics
+   *
+   * @example
+   * ```typescript
+   * const stats = await baasix.workflows.getStats('workflow-uuid');
+   * console.log(stats.totalExecutions, stats.successRate);
+   * ```
+   */
+  async getStats(id) {
+    const response = await this.client.get(`/workflows/${id}/stats`);
+    return response.data;
+  }
+  /**
+   * Validate a workflow definition
+   *
+   * @example
+   * ```typescript
+   * const result = await baasix.workflows.validate({
+   *   name: 'My Workflow',
+   *   nodes: [...],
+   *   edges: [...]
+   * });
+   * if (result.valid) {
+   *   console.log('Workflow is valid');
+   * } else {
+   *   console.log('Errors:', result.errors);
+   * }
+   * ```
+   */
+  async validate(workflow) {
+    const response = await this.client.post(
+      "/workflows/validate",
+      workflow
+    );
+    return response;
+  }
+  /**
+   * Export a single workflow
+   *
+   * @example
+   * ```typescript
+   * const exported = await baasix.workflows.export('workflow-uuid');
+   * // Save to file or transfer
+   * ```
+   */
+  async export(id) {
+    const response = await this.client.get(
+      `/workflows/${id}/export`
+    );
+    return response.data;
+  }
+  /**
+   * Export multiple workflows
+   *
+   * @example
+   * ```typescript
+   * // Export all workflows
+   * const exported = await baasix.workflows.exportAll();
+   *
+   * // Export specific workflows
+   * const exported = await baasix.workflows.exportAll({
+   *   ids: ['workflow-1', 'workflow-2']
+   * });
+   * ```
+   */
+  async exportAll(options) {
+    const response = await this.client.post(
+      "/workflows/export",
+      options || {}
+    );
+    return response.data;
+  }
+  /**
+   * Preview workflow import without applying changes
+   *
+   * @example
+   * ```typescript
+   * const preview = await baasix.workflows.importPreview(file);
+   * console.log('Will import:', preview.workflows.length, 'workflows');
+   * console.log('Conflicts:', preview.conflicts);
+   * ```
+   */
+  async importPreview(file) {
+    const formData = new FormData();
+    if (file instanceof File) {
+      formData.append("file", file);
+    } else {
+      formData.append("file", file);
+    }
+    const response = await this.client.post("/workflows/import/preview", formData);
+    return response.data;
+  }
+  /**
+   * Import workflows from a file
+   *
+   * @example
+   * ```typescript
+   * const result = await baasix.workflows.import(file, {
+   *   overwrite: true
+   * });
+   * console.log('Imported:', result.imported, 'workflows');
+   * ```
+   */
+  async import(file, options) {
+    const formData = new FormData();
+    if (file instanceof File) {
+      formData.append("file", file);
+    } else {
+      formData.append("file", file);
+    }
+    if (options?.overwrite !== void 0) {
+      formData.append("overwrite", String(options.overwrite));
+    }
+    const response = await this.client.post("/workflows/import", formData);
+    return response.data;
+  }
 };
 
 // src/modules/realtime.ts
@@ -3042,6 +3293,8 @@ var RealtimeModule = class {
   roomCallbacks = /* @__PURE__ */ new Map();
   // room -> event -> callbacks
   roomUserCallbacks = /* @__PURE__ */ new Map();
+  kickCallbacks = /* @__PURE__ */ new Map();
+  creatorChangedCallbacks = /* @__PURE__ */ new Map();
   connectionCallbacks = /* @__PURE__ */ new Set();
   reconnecting = false;
   connectionPromise = null;
@@ -3171,6 +3424,27 @@ var RealtimeModule = class {
             }
           });
         });
+        this.socket.on("room:kicked", (data) => {
+          const callbacks = this.kickCallbacks.get(data.room);
+          callbacks?.forEach((cb) => {
+            try {
+              cb(data);
+            } catch (e) {
+              console.error("[Baasix Realtime] Error in room kicked callback:", e);
+            }
+          });
+          this.cleanupRoomListeners(data.room);
+        });
+        this.socket.on("room:creator:changed", (data) => {
+          const callbacks = this.creatorChangedCallbacks.get(data.room);
+          callbacks?.forEach((cb) => {
+            try {
+              cb(data);
+            } catch (e) {
+              console.error("[Baasix Realtime] Error in room creator changed callback:", e);
+            }
+          });
+        });
         this.socket.connect();
       } catch (error) {
         this.connectionPromise = null;
@@ -3200,6 +3474,8 @@ var RealtimeModule = class {
     this.workflowCallbacks.clear();
     this.roomCallbacks.clear();
     this.roomUserCallbacks.clear();
+    this.kickCallbacks.clear();
+    this.creatorChangedCallbacks.clear();
   }
   /**
    * Check if connected to the realtime server
@@ -3470,6 +3746,110 @@ var RealtimeModule = class {
       });
     });
   }
+  /**
+   * Get the list of users currently in a room.
+   * You must already be a member of the room to call this.
+   *
+   * @example
+   * ```typescript
+   * const members = await baasix.realtime.getRoomMembers('game:lobby');
+   * members.forEach(m => {
+   *   console.log(m.userId, m.isCreator ? '(owner)' : '');
+   * });
+   * ```
+   */
+  async getRoomMembers(roomName) {
+    if (!this.socket?.connected) {
+      throw new Error("Not connected. Call connect() first.");
+    }
+    return new Promise((resolve, reject) => {
+      this.socket.emit("room:members", { room: roomName }, (response) => {
+        if (response.status === "success") {
+          resolve(response.members);
+        } else {
+          reject(new Error(response.message || "Failed to get room members"));
+        }
+      });
+    });
+  }
+  /**
+   * Kick a user from a custom room. Only the room creator may call this.
+   *
+   * @example
+   * ```typescript
+   * await baasix.realtime.kickFromRoom('game:lobby', 'user-id-123');
+   * ```
+   */
+  async kickFromRoom(roomName, targetUserId) {
+    if (!this.socket?.connected) {
+      throw new Error("Not connected. Call connect() first.");
+    }
+    return new Promise((resolve, reject) => {
+      this.socket.emit(
+        "room:kick",
+        { room: roomName, userId: targetUserId },
+        (response) => {
+          if (response.status === "success") {
+            resolve();
+          } else {
+            reject(new Error(response.message || "Failed to kick user"));
+          }
+        }
+      );
+    });
+  }
+  /**
+   * Listen for being kicked from a room.
+   * The callback fires when the current user is removed by the room creator.
+   * Room listeners are automatically cleaned up after the kick.
+   *
+   * @example
+   * ```typescript
+   * baasix.realtime.onKicked('game:lobby', ({ kickedBy }) => {
+   *   console.log(`You were kicked by user ${kickedBy}`);
+   * });
+   * ```
+   */
+  onKicked(roomName, callback) {
+    if (!this.kickCallbacks.has(roomName)) {
+      this.kickCallbacks.set(roomName, /* @__PURE__ */ new Set());
+    }
+    this.kickCallbacks.get(roomName).add(callback);
+    return () => {
+      const callbacks = this.kickCallbacks.get(roomName);
+      if (callbacks) {
+        callbacks.delete(callback);
+        if (callbacks.size === 0) {
+          this.kickCallbacks.delete(roomName);
+        }
+      }
+    };
+  }
+  /**
+   * Listen for room ownership changes (e.g. when the creator leaves).
+   *
+   * @example
+   * ```typescript
+   * baasix.realtime.onRoomCreatorChanged('game:lobby', ({ newCreatorUserId }) => {
+   *   console.log(`New room owner: ${newCreatorUserId}`);
+   * });
+   * ```
+   */
+  onRoomCreatorChanged(roomName, callback) {
+    if (!this.creatorChangedCallbacks.has(roomName)) {
+      this.creatorChangedCallbacks.set(roomName, /* @__PURE__ */ new Set());
+    }
+    this.creatorChangedCallbacks.get(roomName).add(callback);
+    return () => {
+      const callbacks = this.creatorChangedCallbacks.get(roomName);
+      if (callbacks) {
+        callbacks.delete(callback);
+        if (callbacks.size === 0) {
+          this.creatorChangedCallbacks.delete(roomName);
+        }
+      }
+    };
+  }
   /**
    * Send a message to a room
    * 
@@ -3622,6 +4002,8 @@ var RealtimeModule = class {
   cleanupRoomListeners(roomName) {
     this.roomCallbacks.delete(roomName);
     this.roomUserCallbacks.delete(roomName);
+    this.kickCallbacks.delete(roomName);
+    this.creatorChangedCallbacks.delete(roomName);
   }
   // ===================
   // Channel (Room) API - Supabase-style