Guru SaaS Web SDK

A comprehensive TypeScript SDK for the Guru SaaS platform, providing seamless integration with authentication, schema management, AI services, and notifications.

✨ Features

• 🔐 Complete Authentication - User management, RBAC, permissions
• 📋 Dynamic Schemas - Create and manage flexible data structures
• 🤖 AI-Powered - Schema generation and field enhancement
• 📧 Notifications - Email templates and delivery tracking
• 🔒 Type-Safe - Full TypeScript support with comprehensive types
• ⚡ Production Ready - 100% test coverage with real backend validation
• 🛠️ Developer Friendly - Intuitive API with excellent documentation

🚀 Quick Start

Installation

npm install @mindmakr/gs-websdk

Basic Usage

import { GuruSaaS } from '@mindmakr/gs-websdk';

// Production: Single base URL (with reverse proxy)
const client = new GuruSaaS({
  baseUrl: 'https://your-api-domain.com',
  debug: true
});

// OR Development: Individual service URLs
const devClient = new GuruSaaS({
  authUrl: 'http://localhost:4000',           // Auth Service
  globalDataUrl: 'http://localhost:5010',     // Global Data Service
  aiServiceUrl: 'http://localhost:4001',      // AI Service
  notificationUrl: 'http://localhost:5020',   // Notification Service
  debug: true
});

// Login
const { user, tokens } = await client.login('user@example.com', 'password');
console.log(`Welcome ${user.name}!`);

// Use services
const users = await client.auth.getUsers({ page: 1, limit: 10 });
const templates = await client.schema.getSchemaTemplates({ is_active: true });
const healthStatus = await client.ai.getHealthStatus();

🏗️ Core Services

🔐 Authentication Service

// User management
const users = await client.auth.getUsers();
const user = await client.auth.createUser({
  email: 'new@example.com',
  password: 'secure123',
  name: 'New User'
});

// Role-based access control
const roles = await client.auth.getRoles();
await client.auth.addRoleToUser(user.id, roleId);

// Permission management
const permissions = await client.auth.getPermissions();
const customRole = await client.auth.createRole({
  name: 'Content Editor',
  description: 'Can read and update content',
  tenant_id: 'tenant123',
  permissions: [1, 2, 3] // Permission IDs for schema_instance:read, schema_instance:update
});

📋 Schema Service

// Create schema template
const template = await client.schema.createSchemaTemplate({
  name: 'Customer Profile',
  code: 'customer_profile',
  schema_definition: {
    type: 'object',
    properties: {
      firstName: { type: 'string', title: 'First Name' },
      email: { type: 'string', format: 'email', title: 'Email' }
    }
  }
});

🤖 AI Service

// Get AI field suggestions
const suggestions = await client.ai.getFieldNameSuggestions({
  context: 'customer management',
  existing_fields: ['firstName', 'lastName']
});

📧 Notification Service

// Send email (only implemented functionality)
const result = await client.notification.sendEmail({
  to: 'user@example.com',
  subject: 'Welcome!',
  html: '<h1>Welcome to our platform!</h1>',
  text: 'Welcome to our platform!' // Optional plain text
});

console.log(result.message); // "Email sent successfully"

📚 Documentation

For Frontend Developers

• Developer Guide - Complete development guide
• Examples - React, Vue.js, and vanilla JS examples
• API Reference - Complete API documentation
• Integration Tests - Test documentation and examples

For DevOps Teams

• DevOps Guide - Build, test, and publish to npm

Reference Materials

• Schema Guide - Working with dynamic schemas
• Field Properties Guide - Field configuration

🧪 Testing

# Run all tests
npm test

# Run integration tests (requires backend services)
npm run test:integration

# Run specific integration test
npm run test:integration -- tests/integration/sdk-core-functionality.test.ts

# Generate coverage report
npm run test:coverage

Integration Tests

The SDK includes comprehensive integration tests that demonstrate real-world usage:

• SDK Core Functionality Test: Demonstrates authentication, user management, schema templates, roles, and permissions
• Task Management Workflow Test: Complete end-to-end workflow demonstrating custom role creation, permission assignment, and role-based access control
• Auth Service Test: Tests authentication flows and user management
• Schema Service Test: Tests schema template and instance operations

Task Management Workflow Test Features:

• Creates tenant and tenant admin user
• Creates custom roles with specific permissions (Task Manager: full CRUD, Developer: read/update only)
• Demonstrates permission enforcement (developers cannot create or delete schema instances)
• Tests schema template and instance operations with role-based restrictions
• Validates complete multi-user workflow with proper tenant isolation

Important Notes:

• Integration tests require backend services to be running
• User and tenant deletion is not supported by the backend for data integrity
• System tenant is a pseudo tenant and doesn't support schema instances
• Permission system uses generic schema_instance permissions (not template-specific)

Test Results: ✅ SDK Core Functionality: 13/13 passing | ✅ Task Management Workflow: 23/23 passing Documentation: See Integration Tests Guide for detailed results and examples

📦 NPM Publishing & Usage

Installation

# Install from npm
npm install @mindmakr/gs-websdk

# Or with yarn
yarn add @mindmakr/gs-websdk

# Or with pnpm
pnpm add @mindmakr/gs-websdk

CDN Usage

<script src="https://unpkg.com/@mindmakr/gs-websdk@latest/dist/index.js"></script>

Publishing (DevOps)

For build and release instructions, see our DevOps Guide.

Quick Release:

# Patch release (1.0.0 -> 1.0.1)
npm run release:patch

# Minor release (1.0.0 -> 1.1.0)
npm run release:minor

# Major release (1.0.0 -> 2.0.0)
npm run release:major

🤝 Contributing

We welcome contributions! Please see our Developer Guide for details.

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• GitHub Issues - Bug reports and feature requests
• GitHub Discussions - Questions and community support

Ready to get started? Install the SDK and check out our Developer Guide! 🚀