@mindmakr/gs-websdk/README.md

Web SDK for Guru SaaS System - Complete JavaScript/TypeScript SDK for building applications with dynamic schema management

# Guru SaaS Web SDK

[![npm version](https://badge.fury.io/js/@mindmakr%2Fgs-websdk.svg)](https://badge.fury.io/js/@mindmakr%2Fgs-websdk)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![Tests](https://img.shields.io/badge/Tests-100%25%20Pass-green.svg)](#testing)

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

```bash
npm install @mindmakr/gs-websdk
```

### Basic Usage

```typescript
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
```typescript
// 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
```typescript
// 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
```typescript
// Get AI field suggestions
const suggestions = await client.ai.getFieldNameSuggestions({
  context: 'customer management',
  existing_fields: ['firstName', 'lastName']
});
```

### 📧 Notification Service
```typescript
// 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](./docs/DEVELOPER_GUIDE.md)** - Complete development guide
- **[Examples](./docs/EXAMPLES.md)** - React, Vue.js, and vanilla JS examples
- **[API Reference](./docs/API_REFERENCE.md)** - Complete API documentation
- **[Integration Tests](./docs/INTEGRATION_TESTS.md)** - Test documentation and examples

### For DevOps Teams
- **[DevOps Guide](./docs/DEVOPS_GUIDE.md)** - Build, test, and publish to npm

### Reference Materials
- **[Schema Guide](./docs/SCHEMA_GUIDE.md)** - Working with dynamic schemas
- **[Field Properties Guide](./docs/FIELD_PROPERTIES_GUIDE.md)** - Field configuration

## 🧪 Testing

```bash
# 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](./docs/INTEGRATION_TESTS.md) for detailed results and examples

## 📦 NPM Publishing & Usage

### Installation
```bash
# 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
```html
<script src="https://unpkg.com/@mindmakr/gs-websdk@latest/dist/index.js"></script>
```

### Publishing (DevOps)
For build and release instructions, see our [DevOps Guide](./docs/DEVOPS_GUIDE.md).

**Quick Release:**
```bash
# 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](./docs/DEVELOPER_GUIDE.md) for details.

## 📄 License

MIT License - see [LICENSE](../LICENSE) file for details.

## 🆘 Support

- **[GitHub Issues](https://github.com/mindmakr/guru-saas/issues)** - Bug reports and feature requests
- **[GitHub Discussions](https://github.com/mindmakr/guru-saas/discussions)** - Questions and community support

---

**Ready to get started?** Install the SDK and check out our [Developer Guide](./docs/DEVELOPER_GUIDE.md)! 🚀