@mindmakr/gs-websdk
Version:
Web SDK for Guru SaaS System - Complete JavaScript/TypeScript SDK for building applications with dynamic schema management
1,940 lines (1,567 loc) • 40.7 kB
Markdown
# Guru SaaS Web SDK - API Reference
This document provides detailed API reference for all services and methods available in the Guru SaaS Web SDK.
## Table of Contents
- [Core Client](#core-client)
- [Authentication Service](#authentication-service)
- [Schema Service](#schema-service)
- [AI Service](#ai-service)
- [Notification Service](#notification-service)
- [Utility Functions](#utility-functions)
- [Types & Interfaces](#types--interfaces)
## Core Client
### GuruSaaSClient
The main client class that provides the foundation for all SDK operations.
#### Constructor
```typescript
new GuruSaaS(config?: SDKConfig)
```
**Parameters:**
- `config` (optional): SDK configuration object
**Example:**
```typescript
const client = new GuruSaaS({
baseUrl: 'https://api.example.com',
debug: true,
timeout: 30000
});
```
#### Methods
##### isAuthenticated()
Check if the user is currently authenticated.
```typescript
isAuthenticated(): boolean
```
##### getCurrentUser()
Get the current authenticated user.
```typescript
getCurrentUser(): User | null
```
##### getTokens()
Get current authentication tokens.
```typescript
getTokens(): AuthTokens | null
```
##### setTokens()
Set authentication tokens manually.
```typescript
setTokens(tokens: AuthTokens): void
```
##### clearAuth()
Clear all authentication data.
```typescript
clearAuth(): void
```
##### request()
Make an authenticated request to any service.
```typescript
request<T>(
method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH',
url: string,
data?: any,
config?: RequestConfig
): Promise<T>
```
---
## Authentication Service
### AuthService
Provides comprehensive authentication and authorization functionality.
#### OTP Authentication
##### requestOtp()
Request OTP for login verification.
```typescript
requestOtp(
email: string,
password: string,
config?: RequestConfig
): Promise<OtpResponse>
```
**Example:**
```typescript
const otpResponse = await client.auth.requestOtp('user@example.com', 'password');
console.log(`OTP sent to ${otpResponse.masked_email}`);
```
##### verifyOtp()
Verify OTP and complete login.
```typescript
verifyOtp(
otpToken: string,
otpCode: string,
rememberDevice?: boolean,
deviceName?: string,
config?: RequestConfig
): Promise<{ user: User; tokens: AuthTokens }>
```
**Example:**
```typescript
const { user, tokens } = await client.auth.verifyOtp(
otpToken,
'123456',
true,
'My Laptop'
);
```
##### refreshToken()
Refresh authentication token.
```typescript
refreshToken(refreshToken: string, config?: RequestConfig): Promise<AuthTokens>
```
##### logout()
Logout user and invalidate tokens.
```typescript
logout(config?: RequestConfig): Promise<{ message: string }>
```
#### Tenant Management
##### switchTenant()
Switch tenant context for the current user.
```typescript
switchTenant(tenantId: string, config?: RequestConfig): Promise<TenantSwitchResponse>
```
**Example:**
```typescript
const result = await client.auth.switchTenant('tenant-123');
console.log(`Switched to ${result.tenant_name}`);
```
#### User Management
##### getUsers()
Get users with pagination and filtering.
```typescript
getUsers(
pagination?: PaginationParams,
filters?: UserFilters,
config?: RequestConfig
): Promise<PaginatedResponse<User>>
```
**Parameters:**
- `pagination`: Page and limit options
- `filters`: Email, role, tenant_id, search filters
- `config`: Request configuration
**Example:**
```typescript
const users = await client.auth.getUsers(
{ page: 1, limit: 20 },
{ role: 'admin', tenant_id: 'my-tenant' }
);
```
##### getUserPermissions()
Get user permissions by user ID.
```typescript
getUserPermissions(userId: string, config?: RequestConfig): Promise<Permission[]>
```
**Example:**
```typescript
const permissions = await client.auth.getUserPermissions('user-123');
```
##### getUserById()
Get user by ID.
```typescript
getUserById(id: string, config?: RequestConfig): Promise<User>
```
##### createUser()
Create a new user.
```typescript
createUser(
userData: {
email: string;
password: string;
name?: string;
role?: string;
tenant_id?: string;
},
config?: RequestConfig
): Promise<User>
```
##### updateUser()
Update user information.
```typescript
updateUser(
id: string,
userData: Partial<User>,
config?: RequestConfig
): Promise<User>
```
**Note**: User deletion is not supported by the backend for data integrity. Users can be disabled by removing their roles instead.
#### Role Management
##### getRoles()
Get all roles for a tenant.
```typescript
getRoles(tenantId?: string, config?: RequestConfig): Promise<Role[]>
```
##### getRoleById()
Get role by ID with permissions.
```typescript
getRoleById(roleId: string, config?: RequestConfig): Promise<Role>
```
##### createRole()
Create a new role.
```typescript
createRole(
roleData: {
name: string;
description?: string;
tenant_id?: string;
permissions?: number[];
},
config?: RequestConfig
): Promise<Role>
```
##### updateRole()
Update role information.
```typescript
updateRole(
roleId: string,
roleData: { name?: string; description?: string },
config?: RequestConfig
): Promise<Role>
```
##### deleteRole()
Delete a role.
```typescript
deleteRole(roleId: string, config?: RequestConfig): Promise<void>
```
##### cloneRole()
Clone an existing role.
```typescript
cloneRole(
roleId: string,
data: { name: string; tenant_id?: string },
config?: RequestConfig
): Promise<Role>
```
#### Permission Management
##### getPermissions()
Get all available permissions.
```typescript
getPermissions(config?: RequestConfig): Promise<Permission[]>
```
##### assignPermissionToRole()
Assign permission to a role.
```typescript
assignPermissionToRole(
roleId: string,
permissionId: string,
config?: RequestConfig
): Promise<void>
```
##### revokePermissionFromRole()
Revoke permission from a role.
```typescript
revokePermissionFromRole(
roleId: string,
permissionId: string,
config?: RequestConfig
): Promise<void>
```
#### User-Role Management
##### getUserRoles()
Get roles assigned to a user.
```typescript
getUserRoles(userId: string, config?: RequestConfig): Promise<Role[]>
```
##### setUserRoles()
Set roles for a user (replaces all existing roles).
```typescript
setUserRoles(
userId: string,
roleIds: string[],
config?: RequestConfig
): Promise<void>
```
##### addRoleToUser()
Add a role to a user.
```typescript
addRoleToUser(
userId: string,
roleId: string,
config?: RequestConfig
): Promise<void>
```
##### removeRoleFromUser()
Remove a role from a user.
```typescript
removeRoleFromUser(
userId: string,
roleId: string,
config?: RequestConfig
): Promise<void>
```
#### Permission Checking
##### canAccessAdmin()
Check if current user can access admin endpoints.
```typescript
canAccessAdmin(config?: RequestConfig): Promise<boolean>
```
##### canCreateTenant()
Check if current user can create tenants.
```typescript
canCreateTenant(config?: RequestConfig): Promise<boolean>
```
##### checkPermission()
Check if current user has a specific permission.
```typescript
checkPermission(
resource: string,
action: string,
config?: RequestConfig
): Promise<boolean>
```
#### Admin Functions (Super Admin Only)
##### adminLogin()
Admin login for super admin users.
```typescript
adminLogin(
email: string,
password: string,
config?: RequestConfig
): Promise<{ user: User; tokens: AuthTokens }>
```
##### createAdminUser()
Create admin user (super admin only).
```typescript
createAdminUser(
userData: {
email: string;
password: string;
name?: string;
role?: 'super_admin' | 'tenant_admin';
},
config?: RequestConfig
): Promise<User>
```
##### updateAdminUser()
Update admin user (super admin only).
```typescript
updateAdminUser(
userId: string,
userData: {
email?: string;
name?: string;
role?: 'super_admin' | 'tenant_admin';
},
config?: RequestConfig
): Promise<User>
```
##### getJwtMetrics()
Get JWT metrics (super admin only).
```typescript
getJwtMetrics(config?: RequestConfig): Promise<JwtMetrics>
```
##### getJwtPerformanceMetrics()
Get JWT performance metrics (super admin only).
```typescript
getJwtPerformanceMetrics(config?: RequestConfig): Promise<JwtPerformanceMetrics>
```
#### Authentication Methods
##### login()
Login with email and password.
```typescript
login(email: string, password: string): Promise<{ user: User; tokens: AuthTokens }>
```
##### requestOTP()
Request OTP for email/password.
```typescript
requestOTP(
email: string,
password: string
): Promise<{ otp_token: string; masked_email: string }>
```
##### verifyOTP()
Verify OTP and complete login.
```typescript
verifyOTP(
otpToken: string,
otpCode: string,
options?: { rememberDevice?: boolean; deviceName?: string }
): Promise<{ user: User; tokens: AuthTokens }>
```
##### register()
Register a new user.
```typescript
register(userData: {
email: string;
password: string;
tenant_id: string;
name?: string;
}): Promise<User>
```
##### refreshToken()
Refresh access token.
```typescript
refreshToken(): Promise<AuthTokens>
```
##### logout()
Logout current user.
```typescript
logout(): Promise<void>
```
##### me()
Get current user information.
```typescript
me(): Promise<User>
```
---
## Schema Service
### SchemaService
Provides dynamic schema template and instance management functionality.
#### Schema Template Management
##### getSchemaTemplates()
Get schema templates with pagination and filtering.
```typescript
getSchemaTemplates(
filters?: SchemaFilters & PaginationParams,
config?: RequestConfig
): Promise<PaginatedResponse<SchemaTemplate>>
```
**Example:**
```typescript
const templates = await client.schema.getSchemaTemplates({
category: 'customer_management',
is_active: true,
search: 'customer',
page: 1,
limit: 20
});
```
##### getSchemaTemplateById()
Get schema template by ID.
```typescript
getSchemaTemplateById(id: number, config?: RequestConfig): Promise<SchemaTemplate>
```
##### getSchemaTemplateByCode()
Get schema template by unique code.
```typescript
getSchemaTemplateByCode(code: string, config?: RequestConfig): Promise<SchemaTemplate>
```
##### getSchemaTemplateByPath()
Get schema template by hierarchical path.
```typescript
getSchemaTemplateByPath(path: string, config?: RequestConfig): Promise<SchemaTemplate>
```
##### createSchemaTemplate()
Create a new schema template.
```typescript
createSchemaTemplate(
templateData: {
name: string;
code: string;
description?: string;
category: string;
schema_definition: Record<string, any>;
version?: string;
is_system?: boolean;
is_active?: boolean;
path?: string;
parent_path?: string;
},
config?: RequestConfig
): Promise<SchemaTemplate>
```
**Example:**
```typescript
const template = await client.schema.createSchemaTemplate({
name: 'Customer Profile',
code: 'customer_profile',
category: 'customer_management',
description: 'Comprehensive customer information form',
schema_definition: {
type: 'object',
title: 'Customer Profile',
properties: {
firstName: {
type: 'string',
title: 'First Name',
minLength: 1,
maxLength: 50
},
email: {
type: 'string',
format: 'email',
title: 'Email Address'
}
},
required: ['firstName', 'email']
}
});
```
##### updateSchemaTemplate()
Update an existing schema template.
```typescript
updateSchemaTemplate(
id: number,
templateData: {
name?: string;
description?: string | null;
category?: string;
schema_definition?: Record<string, any>;
version?: string;
is_active?: boolean;
path?: string;
parent_path?: string;
},
config?: RequestConfig
): Promise<SchemaTemplate>
```
##### deleteSchemaTemplate()
Delete a schema template.
```typescript
deleteSchemaTemplate(id: number, config?: RequestConfig): Promise<void>
```
##### cloneSchemaTemplate()
Clone an existing schema template.
```typescript
cloneSchemaTemplate(
id: number,
data: { code: string; name: string },
config?: RequestConfig
): Promise<SchemaTemplate>
```
##### getSchemaTemplateUsageStats()
Get usage statistics for a template.
```typescript
getSchemaTemplateUsageStats(id: number, config?: RequestConfig): Promise<UsageStats>
```
#### Path-Based Navigation
##### getSchemaTemplateChildren()
Get child templates for a parent path.
```typescript
getSchemaTemplateChildren(
parentPath: string,
config?: RequestConfig
): Promise<SchemaTemplate[]>
```
##### getVirtualHierarchy()
Get virtual hierarchy for template navigation.
```typescript
getVirtualHierarchy(config?: RequestConfig): Promise<VirtualHierarchyNode[]>
```
##### moveSchemaTemplate()
Move schema template to new path.
```typescript
moveSchemaTemplate(
id: number,
newPath: string,
config?: RequestConfig
): Promise<SchemaTemplate>
```
#### Template Composition
##### composeSchemaTemplate()
Get resolved/composed schema for a template.
```typescript
composeSchemaTemplate(
id: number,
config?: RequestConfig
): Promise<{ composed_schema: Record<string, any> }>
```
##### createComposedTemplate()
Create composed template from base template and rules.
```typescript
createComposedTemplate(
baseTemplateId: number,
compositionData: {
compositionRules: CompositionRules;
conflictResolution?: 'parent' | 'child' | 'merge';
mergeStrategy?: 'shallow' | 'deep';
validateOnly?: boolean;
generatePreview?: boolean;
},
config?: RequestConfig
): Promise<CompositionResponse>
```
##### getInheritanceChain()
Get inheritance chain for a template.
```typescript
getInheritanceChain(templateId: number, config?: RequestConfig): Promise<InheritanceChain>
```
#### Template Publishing
##### publishSchemaTemplate()
Publish a schema template.
```typescript
publishSchemaTemplate(
id: number,
expiresAt?: string,
config?: RequestConfig
): Promise<SchemaTemplate>
```
#### Enhanced Field Properties
##### getEnhancedFieldProperties()
Get enhanced field properties for a template.
```typescript
getEnhancedFieldProperties(
templateId: number,
config?: RequestConfig
): Promise<Record<string, any>>
```
##### updateFieldEnhancement()
Update field enhancement for a specific field.
```typescript
updateFieldEnhancement(
templateId: number,
fieldKey: string,
enhancement: Record<string, any>,
config?: RequestConfig
): Promise<Record<string, any>>
```
##### updateEnhancedTemplateProperties()
Update enhanced properties for entire template.
```typescript
updateEnhancedTemplateProperties(
templateId: number,
properties: Record<string, any>,
config?: RequestConfig
): Promise<SchemaTemplate>
```
##### validateFieldEnhancement()
Validate field enhancement configuration.
```typescript
validateFieldEnhancement(
enhancement: Record<string, any>,
config?: RequestConfig
): Promise<{ isValid: boolean; errors: string[]; warnings: string[] }>
```
#### Version Management
##### createSchemaTemplateVersion()
Create a new version of a template.
```typescript
createSchemaTemplateVersion(
id: number,
versionData: {
version_number: string;
schema_definition: Record<string, any>;
change_description?: string;
},
config?: RequestConfig
): Promise<{ version_id: number; template: SchemaTemplate }>
```
##### getSchemaTemplateVersionHistory()
Get version history for a template.
```typescript
getSchemaTemplateVersionHistory(
id: number,
config?: RequestConfig
): Promise<SchemaVersion[]>
```
##### getSchemaTemplateVersion()
Get specific version of a template.
```typescript
getSchemaTemplateVersion(
templateId: number,
versionId: number,
config?: RequestConfig
): Promise<SchemaVersionDetails>
```
##### createAdvancedSchemaTemplateVersion()
Create advanced version with metadata.
```typescript
createAdvancedSchemaTemplateVersion(
id: number,
versionData: AdvancedVersionData,
config?: RequestConfig
): Promise<{ version_id: number; template: SchemaTemplate }>
```
##### rollbackSchemaTemplateVersion()
Rollback to a previous version.
```typescript
rollbackSchemaTemplateVersion(
templateId: number,
targetVersionId: number,
rollbackReason?: string,
config?: RequestConfig
): Promise<{ version_id: number; template: SchemaTemplate }>
```
##### getVersionComparison()
Compare two template versions.
```typescript
getVersionComparison(
version1Id: number,
version2Id: number,
config?: RequestConfig
): Promise<VersionComparison>
```
#### Schema Instance Management
##### getSchemaInstances()
Get schema instances with advanced search capabilities.
**BREAKING CHANGE**: `userId` is now required for permission validation.
```typescript
getSchemaInstances(
filters?: SchemaInstanceFilters & PaginationParams & {
userId: string; // REQUIRED: User ID for permission validation
template_ids?: number[]; // Array of template IDs to search within
include_metadata?: boolean; // Include search metadata (default: true)
relevance_threshold?: number; // Minimum relevance score (0-1)
},
config?: RequestConfig
): Promise<PaginatedResponse<SchemaInstance & {
template_name?: string;
template_code?: string;
search_metadata?: {
matched_fields: string[];
relevance_score: number;
template_id: number;
permission_validated: boolean;
};
}> & {
search_summary?: {
total_templates_searched: number;
fields_searched: string[];
search_performance_ms: number;
permission_check_ms: number;
accessible_templates: number;
total_searchable_fields: number;
};
}>
```
**Features:**
- **Dynamic Field Discovery**: Automatically searches all string fields in schema definitions
- **Permission-Aware**: Only searches templates user has access to
- **Full-Text Search**: PostgreSQL full-text search with ranking and caching
- **Nested Field Support**: Searches nested objects (e.g., "general.displayName")
- **Performance Optimization**: Redis-based caching for sub-100ms response times
- **Search Analytics**: Performance tracking and optimization insights
**Example:**
```typescript
// Basic search
const results = await client.schema.getSchemaInstances({
search: 'john',
userId: 'user123',
page: 1,
limit: 20
});
// Advanced search with filters
const advancedResults = await client.schema.getSchemaInstances({
search: 'customer',
entity_type: 'user',
template_ids: [1, 2, 3],
include_metadata: true,
userId: 'user123'
});
// Access search metadata
console.log('Matched fields:', results.data[0]?.search_metadata?.matched_fields);
console.log('Search performance:', results.search_summary?.search_performance_ms + 'ms');
```
##### getSchemaInstanceById()
Get schema instance by ID.
```typescript
getSchemaInstanceById(
id: number,
tenantId?: string,
config?: RequestConfig
): Promise<SchemaInstance>
```
##### getSchemaInstanceByEntity()
Get schema instance by entity type and ID.
```typescript
getSchemaInstanceByEntity(
entityType: string,
entityId: number,
config?: RequestConfig
): Promise<SchemaInstance>
```
##### createSchemaInstance()
Create a new schema instance.
```typescript
createSchemaInstance(
instanceData: {
entity_type: string;
entity_id: number;
schema_template_id?: number | null;
instance_data?: Record<string, any>;
overrides?: Record<string, any>;
is_active?: boolean;
tenant_id?: string;
},
config?: RequestConfig
): Promise<SchemaInstance>
```
##### upsertSchemaInstance()
Create or update schema instance (upsert).
```typescript
upsertSchemaInstance(
entityType: string,
entityId: number,
instanceData: {
schema_template_id?: number | null;
instance_data?: Record<string, any>;
overrides?: Record<string, any>;
is_active?: boolean;
},
tenantId?: string,
config?: RequestConfig
): Promise<SchemaInstance>
```
##### deleteSchemaInstance()
Delete a schema instance.
```typescript
deleteSchemaInstance(
id: number,
tenantId?: string,
config?: RequestConfig
): Promise<void>
```
#### Category Management
##### getCategories()
Get schema categories.
```typescript
getCategories(
filters?: {
is_active?: boolean;
include_children?: boolean;
include_template_count?: boolean;
parent_id?: number;
},
config?: RequestConfig
): Promise<Category[]>
```
##### getCategoryById()
Get category by ID.
```typescript
getCategoryById(id: number, config?: RequestConfig): Promise<Category>
```
##### createCategory()
Create a new category.
```typescript
createCategory(
categoryData: {
code: string;
name: string;
description?: string;
parent_id?: number;
sort_order?: number;
is_active?: boolean;
},
config?: RequestConfig
): Promise<Category>
```
##### updateCategory()
Update category information.
```typescript
updateCategory(
id: number,
categoryData: {
name?: string;
description?: string;
parent_id?: number;
sort_order?: number;
is_active?: boolean;
},
config?: RequestConfig
): Promise<Category>
```
##### deleteCategory()
Delete a category.
```typescript
deleteCategory(id: number, config?: RequestConfig): Promise<void>
```
#### Performance Metrics
##### getSystemMetrics()
Get system performance metrics.
```typescript
getSystemMetrics(config?: RequestConfig): Promise<SystemMetrics>
```
**Returns:** System metrics including memory, CPU, database, and cache statistics.
##### getOperationMetrics()
Get operation-specific performance metrics.
```typescript
getOperationMetrics(operation: string, config?: RequestConfig): Promise<OperationMetrics>
```
**Parameters:**
- `operation`: Operation name to get metrics for
##### getCacheMetrics()
Get cache performance metrics.
```typescript
getCacheMetrics(config?: RequestConfig): Promise<CacheMetrics>
```
##### getPerformanceAlerts()
Get performance alerts.
```typescript
getPerformanceAlerts(config?: RequestConfig): Promise<PerformanceAlert[]>
```
##### invalidateCache()
Invalidate cache (admin only).
```typescript
invalidateCache(cacheKeys?: string[], config?: RequestConfig): Promise<CacheInvalidationResult>
```
##### resetMetrics()
Reset performance metrics (admin only).
```typescript
resetMetrics(config?: RequestConfig): Promise<MetricsResetResult>
```
---
## AI Service
### AIService
Provides AI-powered schema generation and field enhancement capabilities.
#### Field Enhancement
##### suggestFieldName()
Get AI-powered field name suggestions.
```typescript
suggestFieldName(
request: AIFieldNameRequest,
config?: RequestConfig
): Promise<AIFieldNameResponse>
```
**Example:**
```typescript
const suggestions = await client.ai.suggestFieldName({
fieldType: 'email',
businessContext: 'customer registration',
existingFields: ['firstName', 'lastName'],
userIntent: 'collect primary contact email'
});
```
##### suggestValidation()
Get AI-powered validation suggestions for a field.
```typescript
suggestValidation(
request: AIValidationRequest,
config?: RequestConfig
): Promise<AIValidationResponse>
```
##### suggestFieldType()
Get AI-powered field type suggestions.
```typescript
suggestFieldType(
request: AIFieldTypeRequest,
config?: RequestConfig
): Promise<AIFieldTypeResponse>
```
#### Schema Generation
##### generateSchema()
Generate complete schema based on business description.
```typescript
generateSchema(
request: AISchemaGenerationRequest,
config?: RequestConfig
): Promise<AISchemaGenerationResponse>
```
**Example:**
```typescript
const result = await client.ai.generateSchema({
businessDescription: 'Customer feedback form for restaurant service',
industry: 'hospitality',
formType: 'feedback',
requirements: [
'Must collect customer contact info',
'Need rating system for different aspects'
]
});
```
##### executeSchemaCreation()
Execute schema creation with AI assistance.
```typescript
executeSchemaCreation(
generatedSchema: Record<string, any>,
metadata: {
templateName: string;
templateCode: string;
category: string;
description?: string;
},
config?: RequestConfig
): Promise<SchemaCreationResult>
```
#### Context Analysis
##### analyzeContext()
Analyze business context and provide recommendations.
```typescript
analyzeContext(
request: AIContextAnalysisRequest,
config?: RequestConfig
): Promise<AIContextAnalysisResponse>
```
##### getSchemaKnowledge()
Get schema knowledge and insights.
```typescript
getSchemaKnowledge(
domain?: string,
templateType?: string,
config?: RequestConfig
): Promise<SchemaKnowledgeResponse>
```
#### Schema Editing
##### editSchema()
Edit existing schema with AI assistance.
```typescript
editSchema(
editRequest: {
templateId: number;
currentSchema: Record<string, any>;
editInstructions: string;
preserveData?: boolean;
businessContext?: string;
},
config?: RequestConfig
): Promise<SchemaEditResult>
```
#### Conversational AI
##### getConversations()
Get all conversations.
```typescript
getConversations(config?: RequestConfig): Promise<Conversation[]>
```
##### getConversation()
Get conversation by ID.
```typescript
getConversation(
conversationId: string,
config?: RequestConfig
): Promise<Conversation>
```
##### createConversation()
Create new conversation.
```typescript
createConversation(
conversationData: {
title?: string;
context?: ConversationContext;
},
config?: RequestConfig
): Promise<Conversation>
```
##### processConversation()
Process conversation message and get AI response.
```typescript
processConversation(
conversationData: {
conversationId?: string;
message: string;
context?: ConversationContext;
},
config?: RequestConfig
): Promise<ConversationProcessResult>
```
##### deleteConversation()
Delete conversation.
```typescript
deleteConversation(
conversationId: string,
config?: RequestConfig
): Promise<void>
```
##### executeFunction()
Execute AI function.
```typescript
executeFunction(
data: {
functionName: string;
parameters: Record<string, any>;
userId: string;
tenantId: string;
conversationId?: string;
requiresConfirmation?: boolean;
},
config?: RequestConfig
): Promise<{
success: boolean;
result?: any;
error?: string;
requiresConfirmation?: boolean;
confirmationMessage?: string;
}>
```
**Example:**
```typescript
const result = await client.ai.executeFunction({
functionName: 'create_schema_template',
parameters: {
name: 'Customer Form',
category: 'customer_management'
},
userId: 'user-123',
tenantId: 'tenant-456'
});
```
#### Context Enhancement
##### analyzeContext()
Analyze context for AI suggestions.
```typescript
analyzeContext(
data: {
context: string;
type?: string;
},
config?: RequestConfig
): Promise<{
success: boolean;
data: any;
}>
```
**Example:**
```typescript
const analysis = await client.ai.analyzeContext({
context: 'Customer registration form for e-commerce',
type: 'schema_design'
});
```
##### suggestFieldName()
Suggest field name based on context.
```typescript
suggestFieldName(
data: {
context: string;
existing_fields?: string[];
},
config?: RequestConfig
): Promise<{
success: boolean;
data: {
suggested_name: string;
};
}>
```
**Example:**
```typescript
const suggestion = await client.ai.suggestFieldName({
context: 'Field for customer email address',
existing_fields: ['name', 'phone', 'address']
});
console.log(suggestion.data.suggested_name); // 'email'
```
##### suggestValidation()
Suggest validation rules for a field.
```typescript
suggestValidation(
data: {
field_type: string;
context: string;
},
config?: RequestConfig
): Promise<{
success: boolean;
data: {
validation_rules: Record<string, any>;
};
}>
```
**Example:**
```typescript
const validation = await client.ai.suggestValidation({
field_type: 'email',
context: 'Customer email for notifications'
});
```
##### suggestFieldType()
Suggest field type based on context.
```typescript
suggestFieldType(
data: {
context: string;
field_name?: string;
},
config?: RequestConfig
): Promise<{
success: boolean;
data: {
suggested_type: string;
confidence?: number;
};
}>
```
**Example:**
```typescript
const typesuggestion = await client.ai.suggestFieldType({
context: 'Customer birth date',
field_name: 'birth_date'
});
```
##### suggestFields()
Suggest field enhancements for schema.
```typescript
suggestFields(
data: {
schema_context: string;
existing_fields?: any[];
requirements?: string;
},
config?: RequestConfig
): Promise<{
success: boolean;
data: {
suggested_fields: any[];
};
}>
```
**Note:** This endpoint may not be working according to api-status.md
**Example:**
```typescript
const fields = await client.ai.suggestFields({
schema_context: 'Customer management system',
requirements: 'Need fields for contact information and preferences'
});
```
##### executeFunctionCall()
Execute function call from AI response.
```typescript
executeFunctionCall(
functionCall: FunctionCall,
context?: Record<string, any>,
config?: RequestConfig
): Promise<FunctionCallResult>
```
#### Batch Operations
##### batchEnhanceFields()
Process multiple field enhancements in batch.
```typescript
batchEnhanceFields(
requests: BatchFieldEnhancementRequest[],
config?: RequestConfig
): Promise<BatchFieldEnhancementResult[]>
```
##### batchAnalyzeSchemas()
Analyze multiple schemas for optimization.
```typescript
batchAnalyzeSchemas(
templateIds: number[],
analysisType: 'optimization' | 'validation' | 'compliance' | 'user_experience',
config?: RequestConfig
): Promise<BatchSchemaAnalysisResult[]>
```
#### AI Capabilities
##### getCapabilities()
Get AI service capabilities and status.
```typescript
getCapabilities(config?: RequestConfig): Promise<AICapabilitiesResponse>
```
##### getHealthStatus()
Get AI model health status.
```typescript
getHealthStatus(config?: RequestConfig): Promise<AIHealthResponse>
```
---
## Notification Service
### NotificationService
Provides basic email notification functionality.
**⚠️ Important**: Only basic email sending is implemented. Advanced features like templates, bulk sending, analytics, and preferences are not available in the current backend.
#### Health Check
##### getHealth()
Get notification service health status.
```typescript
getHealth(config?: RequestConfig): Promise<{
status: string;
service: string;
timestamp?: string;
uptime?: number;
environment?: string;
}>
```
#### Email Notifications
##### sendEmail()
Send email notification.
```typescript
sendEmail(
notification: EmailNotification,
config?: RequestConfig
): Promise<{ message: string }>
```
**Example:**
```typescript
const result = await client.notification.sendEmail({
to: 'customer@example.com',
subject: 'Welcome to Our Service',
html: '<h1>Welcome!</h1><p>Thank you for joining us.</p>',
text: 'Welcome! Thank you for joining us.' // Optional plain text fallback
});
console.log(result.message); // "Email sent successfully"
```
**Parameters:**
- `to`: Email recipient(s) - string or array of strings
- `subject`: Email subject line
- `html`: HTML email content
- `text`: Optional plain text fallback
**Returns:**
- `Promise<{ message: string }>` - Success message from server
---
## Utility Functions
### Schema Helpers
#### generateUISchemaFromJSONSchema()
Generate UI schema from JSON schema for better form rendering.
```typescript
generateUISchemaFromJSONSchema(jsonSchema: Record<string, any>): Record<string, any>
```
#### createSchemaWithUISchema()
Create schema with UI schema information embedded.
```typescript
createSchemaWithUISchema(
jsonSchema: Record<string, any>,
uiSchema: Record<string, any>
): Record<string, any>
```
#### convertSchemaToFormConfig()
Convert schema template to a format suitable for form rendering.
```typescript
convertSchemaToFormConfig(template: SchemaTemplate): FormConfig
```
#### generateDefaultFormData()
Generate default form data from schema.
```typescript
generateDefaultFormData(schema: Record<string, any>): Record<string, any>
```
#### validateFormData()
Validate form data against schema.
```typescript
validateFormData(
formData: Record<string, any>,
schema: Record<string, any>
): ValidationResult
```
#### mergeSchemas()
Merge schemas (useful for composition).
```typescript
mergeSchemas(
baseSchema: Record<string, any>,
extendingSchema: Record<string, any>,
strategy?: 'override' | 'merge'
): Record<string, any>
```
#### cleanSchemaForStorage()
Clean schema by removing UI-specific properties for storage.
```typescript
cleanSchemaForStorage(schema: Record<string, any>): Record<string, any>
```
### Form Helpers
#### generateFormFields()
Generate form fields configuration from schema template.
```typescript
generateFormFields(template: SchemaTemplate): SchemaField[]
```
#### createFormConfig()
Create form configuration for rendering.
```typescript
createFormConfig(
template: SchemaTemplate,
instance?: SchemaInstance
): FormRenderConfig
```
#### transformFormDataForSubmission()
Transform form data for submission.
```typescript
transformFormDataForSubmission(
formData: Record<string, any>,
template: SchemaTemplate
): Record<string, any>
```
#### calculateFormCompletion()
Calculate form completion percentage.
```typescript
calculateFormCompletion(
formData: Record<string, any>,
template: SchemaTemplate
): FormCompletionResult
```
#### exportFormData()
Export form data in various formats.
```typescript
exportFormData(
formData: Record<string, any>,
template: SchemaTemplate,
format?: 'json' | 'csv' | 'xml'
): string
```
### Validation Helpers
#### validateForm()
Comprehensive form validation.
```typescript
validateForm(
formData: Record<string, any>,
template: SchemaTemplate,
options?: ValidationOptions
): ValidationResult
```
#### validateFieldDependencies()
Validate field dependencies and cross-field validation.
```typescript
validateFieldDependencies(
formData: Record<string, any>,
template: SchemaTemplate
): ValidationError[]
```
#### sanitizeFormData()
Sanitize form data (remove potentially harmful content).
```typescript
sanitizeFormData(
formData: Record<string, any>,
options?: SanitizationOptions
): Record<string, any>
```
---
## Types & Interfaces
### Core Types
```typescript
interface User {
id: string;
email: string;
role: string;
tenant_id?: string;
name?: string;
created_at: string;
updated_at: string;
last_login?: string;
permissions?: string[];
}
interface AuthTokens {
token: string;
refreshToken: string;
expiresIn: number;
tokenType: string;
}
interface SDKConfig {
baseUrl?: string;
authUrl?: string;
globalDataUrl?: string;
aiServiceUrl?: string;
notificationUrl?: string;
timeout?: number;
retryAttempts?: number;
debug?: boolean;
defaultTenant?: string;
autoRefreshToken?: boolean;
}
interface RequestConfig {
timeout?: number;
retries?: number;
headers?: Record<string, string>;
tenantId?: string;
}
interface PaginatedResponse<T> {
data: T[];
pagination: {
total: number;
page: number;
limit: number;
totalPages: number;
};
}
```
### Schema Types
```typescript
interface SchemaTemplate {
id: number;
name: string;
code: string;
description?: string;
category: string;
schema_definition: Record<string, any>;
version: string;
is_system: boolean;
is_active: boolean;
created_by?: string;
tenant_id?: string;
created_at: string;
updated_at: string;
path?: string;
parent_path?: string;
depth?: number;
base_template_id?: number;
composition_rules?: Record<string, any>;
enhanced_properties?: Record<string, any>;
status?: 'draft' | 'published' | 'archived';
published_at?: string;
published_by?: string;
expires_at?: string;
}
interface SchemaInstance {
id: number;
entity_type: string;
entity_id: number;
schema_template_id?: number;
instance_data: Record<string, any>;
overrides: Record<string, any>;
is_active: boolean;
tenant_id?: string;
created_at: string;
updated_at: string;
template?: {
name: string;
code: string;
schema_definition: Record<string, any>;
version: string;
category: string;
};
}
interface SchemaField {
id: string;
key: string;
type: string;
properties: Record<string, any>;
required: boolean;
order: number;
layout?: {
width?: 'quarter' | 'half' | 'three-quarter' | 'full';
height?: 'small' | 'medium' | 'large';
group?: string;
conditional?: {
field: string;
value: any;
operator: 'equals' | 'not_equals' | 'contains';
};
};
}
```
### AI Types
```typescript
interface AIFieldSuggestion {
name: string;
type: string;
title: Record<string, string>;
description: Record<string, string>;
confidence: number;
reasoning: string;
alternatives: string[];
validation: ValidationRule[];
enhancement: FieldEnhancement;
}
interface ValidationRule {
type: string;
value?: any;
message: Record<string, string>;
}
interface FieldEnhancement {
icon?: string;
placeholder?: Record<string, string>;
helpText?: Record<string, string>;
styling?: {
variant?: 'default' | 'outline' | 'ghost' | 'destructive';
size?: 'sm' | 'md' | 'lg';
className?: string;
};
validation?: ValidationRule[];
conditional?: {
field: string;
operator: string;
value: any;
};
}
```
### Notification Types
```typescript
// Real notification interface (matches actual implementation)
interface EmailNotification {
to: string | string[];
subject: string;
html: string;
text?: string;
}
// Response from sendEmail() method
interface EmailSendResult {
message: string;
}
```
### Error Types
```typescript
class SDKError extends Error {
public readonly code: string;
public readonly statusCode?: number;
public readonly details?: any;
}
class AuthenticationError extends SDKError {
constructor(message?: string, details?: any);
}
class PermissionError extends SDKError {
constructor(message?: string, details?: any);
}
class ValidationError extends SDKError {
constructor(message?: string, details?: any);
}
class NetworkError extends SDKError {
constructor(message?: string, details?: any);
}
```
---
This API reference provides comprehensive documentation for all available methods, parameters, and return types in the Guru SaaS Web SDK. For additional examples and best practices, refer to the main README.md file.