@superatomai/sdk-web

SuperAtom Web SDK - TypeScript SDK for browser-based WebSocket communication with the SuperAtom platform.

Features

• 🔌 WebSocket client with automatic reconnection and exponential backoff
• 🔒 Type-safe message validation using Zod v4
• 🎯 Request/response pattern with timeout support
• 📦 Bundle management with chunked transfer
• 🧩 Component registration and communication system
• 🔐 Authentication (login and token verification)
• 👥 User management (CRUD operations)
• 📊 Dashboard management (CRUD operations)
• 📈 Report management (CRUD operations)
• 🤖 AI component suggestions with text streaming support
• 💾 Data collection queries
• ⚡ Actions API for runtime operations
• 📝 UI logging support

Installation

pnpm add @superatomai/sdk-web

Quick Start

import { SuperatomClient, setup } from '@superatomai/sdk-web';

// 1. Create and connect client
const client = new SuperatomClient({
  userId: 'your-user-id',
  projectId: 'your-project-id',
  type: 'runtime', // Connection type (default: 'runtime')
  debug: true, // Enable debug logging
});

await client.connect();

// 2. Setup components (optional - for component rendering)
setup({
  MyComponent: MyReactComponent,
  AnotherComponent: AnotherReactComponent,
  mount: (Component, container, props) => {
    const root = createRoot(container);
    root.render(createElement(Component, props));
    return { unmount: () => root.unmount() };
  }
});

// 3. Authenticate (optional)
const loginResponse = await client.sendAuthLoginRequest(
  loginDataBase64, // Base64 encoded login data
  10000 // timeout in ms
);

// 4. Get AI component suggestions
const result = await client.sendUserPromptSuggestionsRequest(
  'show me a calendar component',
  5 // limit
);

API Reference

SuperatomClient

Main WebSocket client for communication.

Configuration

const client = new SuperatomClient({
  userId: string,                    // Required: User ID
  projectId: string,                 // Required: Project ID
  type?: string,                     // Default: 'runtime'
  baseUrl?: string,                  // Default: 'wss://ws.superatom.ai/websocket'
  maxReconnectAttempts?: number,     // Default: Infinity
  initialReconnectDelay?: number,    // Default: 1000ms
  maxReconnectDelay?: number,        // Default: 30000ms
  defaultTimeout?: number,           // Default: 30000ms
  debug?: boolean,                   // Default: false
});

Core Methods

// Connection management
await client.connect();                              // Returns Promise<void>
client.disconnect();
client.isConnected();                                // Returns boolean
await client.reconnectWithConfig(partialConfig);     // Reconnect with updated config

// Messaging
client.send(message);                                // Send message without waiting for response
await client.sendWithResponse(message, timeout);     // Send and wait for response
await client.ask(message, { timeout });              // Alias for sendWithResponse

// Event handlers
client.onMessage((message) => { ... });              // Returns unsubscribe function
client.onConnect(() => { ... });                     // Returns unsubscribe function
client.onDisconnect(() => { ... });                  // Returns unsubscribe function
client.onError((error) => { ... });                  // Returns unsubscribe function

Service Methods

Authentication

// Login with credentials
const loginResponse = await client.sendAuthLoginRequest(
  loginDataBase64,  // Base64 encoded: username + SHA-1 hashed password
  timeout          // Optional timeout in ms
);

// Verify authentication token
const verifyResponse = await client.sendAuthVerifyRequest(
  token,    // Base64 encoded auth token
  timeout   // Optional timeout in ms
);

User Management

// Create a new user
const result = await client.createUser(
  username,
  password,
  email?,      // Optional: User email
  fullname?,   // Optional: User full name
  role?,       // Optional: User role
  timeout?
);
// Returns: { success, username?, email?, fullname?, role?, message?, error? }

// Update an existing user
const result = await client.updateUser(
  username,
  {
    password?: string,   // Optional: New password
    email?: string,      // Optional: New email
    fullname?: string,   // Optional: New full name
    role?: string,       // Optional: New role
  },
  timeout?
);
// Returns: { success, username?, email?, fullname?, role?, message?, error? }

// Delete a user
const result = await client.deleteUser(username, timeout);
// Returns: { success, username?, email?, fullname?, role?, message?, error? }

// Get all users
const result = await client.getAllUsers(timeout);
// Returns: { success, users, count, error?, message? }
// User object: { username, email?, fullname?, role?, wsIds }

// Get a specific user
const result = await client.getUser(username, timeout);
// Returns: { success, user, error?, message? }
// User object: { username, email?, fullname?, role?, wsIds }

Dashboard Management

// Create a new dashboard
const result = await client.createDashboard(
  dashboardId,
  dashboardConfig,  // DSLRendererProps
  timeout
);

// Update an existing dashboard
const result = await client.updateDashboard(
  dashboardId,
  dashboardConfig,
  timeout
);

// Delete a dashboard
const result = await client.deleteDashboard(dashboardId, timeout);

// Get all dashboards
const result = await client.getAllDashboards(timeout);
// Returns: { success, dashboards, count, error?, message? }

// Get a specific dashboard
const result = await client.getDashboard(dashboardId, timeout);
// Returns: { success, dashboardId, dashboard, error?, message? }

Report Management

// Create a new report
const result = await client.createReport(
  reportId,
  reportConfig,  // ReportDSLRendererProps
  timeout
);

// Update an existing report
const result = await client.updateReport(
  reportId,
  reportConfig,
  timeout
);

// Delete a report
const result = await client.deleteReport(reportId, timeout);

// Get all reports
const result = await client.getAllReports(timeout);
// Returns: { success, reports, count, error?, message? }

// Get a specific report
const result = await client.getReport(reportId, timeout);
// Returns: { success, reportId, report, error?, message? }

User Prompts & AI Suggestions

// Send a user prompt request (component mode - default)
const response = await client.sendUserPromptRequest(
  prompt,
  threadId,
  uiBlockId,
  'component',  // responseMode: 'component' (default) or 'text'
  undefined,    // onStream callback (only used for text mode)
  timeout
);

// Send a user prompt request with text streaming
const response = await client.sendUserPromptRequest(
  prompt,
  threadId,
  uiBlockId,
  'text',       // responseMode: 'text' for streaming
  (chunk) => {  // onStream callback receives text chunks
    console.log('Stream chunk:', chunk);
  },
  timeout
);

// Get AI component suggestions
const result = await client.sendUserPromptSuggestionsRequest(
  'show me a form to collect user data',
  5,       // limit (default: 5)
  timeout  // optional timeout
);

Bundle & Data

// Request bundle with progress tracking
const bundle = await client.requestBundle({
  timeout: 60000,
  onProgress: (progress) => {
    console.log(`Download progress: ${progress}%`);
  }
});

// Query data collections
const result = await client.requestData({
  collection: 'users',
  operation: 'getMany',
  params: { limit: 10 },
  timeout: 10000
});
// Returns: { data?, error? }

Actions API

// Get available actions for the current context
const result = await client.getActions({
  SA_RUNTIME: {
    threadId: 'thread_123',
    uiBlockId: 'block_456'
  },
  timeout: 10000
});
// Returns: { success, data?, error? }

Component Management

// Send component list to server
await client.sendComponents([
  {
    id: 'comp_1',
    name: 'MyComponent',
    type: 'custom',
    description: 'A custom component',
    props: { /* ... */ }
  },
  // ... more components
]);

Component Setup

Register your components with SuperAtom for dynamic rendering.

import { setup } from '@superatomai/sdk-web';
import { createRoot } from 'react-dom/client';
import { createElement } from 'react';

setup({
  // Your components
  DemoCard: DemoCard,
  Calendar: Calendar,
  Form: ComplexForm,

  // Mount function (required)
  mount: (Component, container, props) => {
    const root = createRoot(container);
    root.render(createElement(Component, props));
    return { unmount: () => root.unmount() };
  }
});

Message Types

The SDK supports the following message types (all validated with Zod schemas):

Authentication

• AUTH_LOGIN_REQ / AUTH_LOGIN_RES - User login
• AUTH_VERIFY_REQ / AUTH_VERIFY_RES - Token verification

User Prompts & AI

• USER_PROMPT_REQ / USER_PROMPT_RES - User prompt processing
• USER_PROMPT_STREAM - Real-time text streaming from AI responses
• USER_PROMPT_SUGGESTIONS_REQ / USER_PROMPT_SUGGESTIONS_RES - Component suggestions

Bundle & Data

• BUNDLE_REQ / BUNDLE_CHUNK - Bundle transfer with chunking
• DATA_REQ / DATA_RES - Data collection queries

Management Operations

• USERS / USERS_RES - User CRUD operations
• DASHBOARDS / DASHBOARDS_RES - Dashboard CRUD operations
• REPORTS / REPORTS_RES - Report CRUD operations

Actions & Components

• ACTIONS / ACTIONS_RES - Runtime actions API
• COMPONENT_LIST_RES - Send component list to server

Logging

• UI_LOGS - UI logging messages

All message types are fully typed and validated using Zod v4 schemas.

USERS Schema

The USERS message type supports comprehensive user management with the following structure:

Request Payload (USERS):

{
  operation: 'create' | 'update' | 'delete' | 'getAll' | 'getOne',
  data?: {
    username?: string,        // Required for all operations except getAll
    email?: string,           // Optional: User email (validated)
    password?: string,        // Required for create, optional for update
    fullname?: string,        // Optional: User's full name
    role?: string,            // Optional: User's role
  }
}

Response Payload (USERS_RES):

{
  success: boolean,
  error?: string,
  data?: {
    username?: string,
    email?: string,
    fullname?: string,
    role?: string,
    message?: string,
    // For getAll operation
    users?: Array<{
      username: string,
      email?: string,
      fullname?: string,
      role?: string,
      wsIds: string[]
    }>,
    count?: number,
    // For getOne operation
    user?: {
      username: string,
      email?: string,
      fullname?: string,
      role?: string,
      wsIds: string[]
    }
  }
}

User Object Structure:

interface User {
  username: string;          // Required: Unique username
  email?: string;            // Optional: Validated email address
  fullname?: string;         // Optional: User's full name
  role?: string;             // Optional: User role (e.g., 'admin', 'editor', 'viewer')
  wsIds: string[];           // WebSocket connection IDs (in-memory only)
}

Type Safety

All messages are validated using Zod v4 schemas. The SDK exports comprehensive type definitions and schemas:

import {
  MessageSchema,
  DataRequestMessageSchema,
  AuthLoginRequestMessageSchema,
  UserPromptSuggestionsRequestMessageSchema,
  // ... and many more
} from '@superatomai/sdk-web';

// Validate any message
const validMessage = MessageSchema.parse(incomingData);

// Validate specific message types
const dataRequest = DataRequestMessageSchema.parse(requestData);

// TypeScript types are automatically inferred
import type {
  Message,
  DataRequestMessage,
  AuthLoginResponseMessage,
  Component,
  DSLRendererProps,
  ReportDSLRendererProps,
} from '@superatomai/sdk-web';

Examples

Complete React Integration

import { SuperatomClient, setup } from '@superatomai/sdk-web';
import { createRoot } from 'react-dom/client';
import { createElement } from 'react';
import MyComponent from './components/MyComponent';

// Initialize client
const client = new SuperatomClient({
  userId: 'user_123',
  projectId: 'project_456',
  type: 'runtime',
  debug: true,
});

// Setup components
setup({
  MyComponent,
  mount: (Component, container, props) => {
    const root = createRoot(container);
    root.render(createElement(Component, props));
    return { unmount: () => root.unmount() };
  }
});

// Connect and authenticate
await client.connect();

// Listen for messages
client.onMessage((message) => {
  console.log('Received:', message);
});

// Get component suggestions
async function handleUserQuery(query: string) {
  const result = await client.sendUserPromptSuggestionsRequest(query, 5);

  if (result?.payload?.data?.suggestions) {
    console.log('Suggestions:', result.payload.data.suggestions);
  }
}

User Management Example

import { SuperatomClient } from '@superatomai/sdk-web';

const client = new SuperatomClient({
  userId: 'admin_123',
  projectId: 'project_456',
});

await client.connect();

// Create a new user with all fields
const createResult = await client.createUser(
  'newuser',
  'password123',
  '[email protected]',     // email
  'John Doe',             // fullname
  'editor'                // role
);
if (createResult.success) {
  console.log('User created:', createResult.username);
  console.log('Email:', createResult.email);
  console.log('Full name:', createResult.fullname);
  console.log('Role:', createResult.role);
}

// Get all users
const usersResult = await client.getAllUsers();
if (usersResult.success && usersResult.users) {
  console.log(`Found ${usersResult.count} users`);
  usersResult.users.forEach(user => {
    console.log(`- ${user.username} (${user.email || 'no email'})`);
    console.log(`  Full name: ${user.fullname || 'N/A'}`);
    console.log(`  Role: ${user.role || 'N/A'}`);
    console.log(`  Connections: ${user.wsIds.length}`);
  });
}

// Update a user - change multiple fields
await client.updateUser('newuser', {
  password: 'newpassword456',
  email: '[email protected]',
  fullname: 'Jane Doe',
  role: 'admin'
});

// Update a user - change only specific fields
await client.updateUser('newuser', {
  role: 'viewer'  // Only update role
});

// Delete a user
await client.deleteUser('newuser');

Dashboard Management Example

import { SuperatomClient } from '@superatomai/sdk-web';
import type { DSLRendererProps } from '@superatomai/sdk-web';

const client = new SuperatomClient({
  userId: 'admin_123',
  projectId: 'project_456',
});

await client.connect();

// Create a dashboard
const dashboardConfig: DSLRendererProps = {
  // Your dashboard configuration
};

const result = await client.createDashboard(
  'dashboard_001',
  dashboardConfig
);

if (result.success) {
  console.log('Dashboard created:', result.dashboardId);
}

// Get all dashboards
const dashboards = await client.getAllDashboards();
if (dashboards.success && dashboards.dashboards) {
  console.log(`Total dashboards: ${dashboards.count}`);
}

// Get specific dashboard
const dashboard = await client.getDashboard('dashboard_001');
if (dashboard.success && dashboard.dashboard) {
  console.log('Dashboard config:', dashboard.dashboard);
}

Data Query Example

import { SuperatomClient } from '@superatomai/sdk-web';

const client = new SuperatomClient({
  userId: 'user_123',
  projectId: 'project_456',
});

await client.connect();

// Query data from a collection
const result = await client.requestData({
  collection: 'products',
  operation: 'getMany',
  params: {
    filter: { category: 'electronics' },
    limit: 20,
    offset: 0
  },
  timeout: 10000
});

if (!result.error && result.data) {
  console.log('Products:', result.data);
} else {
  console.error('Error:', result.error);
}

Text Streaming Example

import { SuperatomClient } from '@superatomai/sdk-web';

const client = new SuperatomClient({
  userId: 'user_123',
  projectId: 'project_456',
});

await client.connect();

// Use text streaming for real-time AI responses
let streamedText = '';

const response = await client.sendUserPromptRequest(
  'Explain how photosynthesis works',
  'thread_123',
  'block_456',
  'text',  // Enable text streaming mode
  (chunk) => {
    // Receive text chunks in real-time
    streamedText += chunk;
    console.log('Received chunk:', chunk);
    // Update UI with streaming text
    updateUIWithText(streamedText);
  },
  30000
);

console.log('Streaming complete. Final response:', response);

Actions API Example

import { SuperatomClient } from '@superatomai/sdk-web';

const client = new SuperatomClient({
  userId: 'user_123',
  projectId: 'project_456',
});

await client.connect();

// Get available actions for the current runtime context
const result = await client.getActions({
  SA_RUNTIME: {
    threadId: 'thread_123',
    uiBlockId: 'block_456'
  },
  timeout: 10000
});

if (result.success && result.data) {
  console.log('Available actions:', result.data);
} else {
  console.error('Error:', result.error);
}

// Send component list to server
await client.sendComponents([
  {
    id: 'my_component_1',
    name: 'DataTable',
    type: 'table',
    description: 'Display data in table format',
    props: {
      columns: ['name', 'email', 'status'],
      data: []
    }
  }
]);

Advanced Usage

Direct Service Access

All service functions can be imported and used directly for advanced use cases:

import { SuperatomClient, services } from '@superatomai/sdk-web';

const client = new SuperatomClient({ /* ... */ });

// Use service functions directly
const result = await services.requestData(client, {
  collection: 'users',
  operation: 'getMany',
  params: {},
  timeout: 10000
});

Event Unsubscription

All event handlers return an unsubscribe function:

const unsubscribe = client.onMessage((message) => {
  console.log('Message:', message);
});

// Later, when you want to stop listening
unsubscribe();

Reconnection with Updated Config

You can reconnect with updated configuration without creating a new client:

await client.reconnectWithConfig({
  userId: 'new_user_id',
  debug: true
});

License

MIT

Support

For issues and questions, please contact the SuperAtom team or refer to the SuperAtom platform documentation.