@aui.io/aui-client

Official TypeScript/JavaScript SDK for AUI APIs - Provides REST and WebSocket support for intelligent agent communication.

🚀 Installation

npm install @aui.io/aui-client

⚡ Quick Start

import { ApolloClient, ApolloEnvironment } from '@aui.io/aui-client';

// Default: Uses Gcp environment
const client = new ApolloClient({
    networkApiKey: 'API_KEY_YOUR_KEY_HERE'
});

// Or explicitly choose an environment:
const gcpClient = new ApolloClient({
    environment: ApolloEnvironment.Gcp,
    networkApiKey: 'API_KEY_YOUR_KEY_HERE'
});

const azureClient = new ApolloClient({
    environment: ApolloEnvironment.Azure,
    networkApiKey: 'API_KEY_YOUR_KEY_HERE'
});

const awsClient = new ApolloClient({
    environment: ApolloEnvironment.Aws,
    networkApiKey: 'API_KEY_YOUR_KEY_HERE'
});

REST API - Create and Manage Tasks

// Create a new task
const taskResponse = await client.controllerApi.createTask({
    user_id: 'user123',
    task_origin_type: 'web-widget'  // Required: identifies the source of the task
});

console.log('Task ID:', taskResponse.id);
console.log('Welcome:', taskResponse.welcome_message);

// Get all messages for a task
const messages = await client.controllerApi.getTaskMessages(taskResponse.id);
console.log('Messages:', messages);

// Submit a message to an existing task
const messageResponse = await client.controllerApi.sendMessage({
    task_id: taskResponse.id,
    text: 'Looking for a microwave with at least 20 liters capacity',
    is_external_api: true
});

console.log('Agent response:', messageResponse.text);

// Get all tasks for a user
const userTasks = await client.controllerApi.listUserTasks({
    user_id: 'user123',
    page: 1,
    size: 10
});

console.log('Total tasks:', userTasks.total);

WebSocket - Real-time Agent Communication

// Connect to WebSocket with authentication headers
const socket = await client.apolloWsSession.connect({
    debug: false,
    reconnectAttempts: 3,
    headers: {
        'x-network-api-key': 'API_KEY_YOUR_KEY_HERE'
    }
});

// Listen for connection open
socket.on('open', () => {
    console.log('✅ Connected to agent');
    
    // Send a message
    socket.sendUserMessage({
        task_id: 'your-task-id',
        text: 'I need product recommendations for gaming laptops'
    });
});

// Handle streaming responses
socket.on('message', (message) => {
    // Streaming updates (partial responses)
    if (message.channel?.event_name === 'thread-message-text-content-updated') {
        console.log('Agent is typing:', message.data?.text);
    }
    
    // Final message with complete response
    if (message.id && message.text && message.sender) {
        console.log('Complete response:', message.text);
        
        // Handle product recommendations (if any)
        if (message.cards && message.cards.length > 0) {
            message.cards.forEach(card => {
                console.log(`${card.name} - ${card.id}`);
            });
        }
        
        // Follow-up suggestions
        if (message.followupSuggestions) {
            console.log('Suggestions:', message.followupSuggestions);
        }
    }
    
    // Error messages
    if (message.statusCode) {
        console.error('Agent error:', message.description);
    }
});

// Handle errors
socket.on('error', (error) => {
    console.error('WebSocket error:', error);
});

// Handle connection close
socket.on('close', (event) => {
    console.log('Connection closed:', event.code);
});

// Close connection when done
// socket.close();

📖 API Reference

Client Configuration

The ApolloClient constructor accepts the following options:

interface ApolloClient.Options {
    environment?: ApolloEnvironment;      // Use predefined environment (Gcp or Azure)
    
    // Authentication (required)
    networkApiKey: string;               // Your API key (x-network-api-key header)
    
    // Optional configurations
    headers?: Record<string, string>;    // Additional headers
    timeoutInSeconds?: number;           // Request timeout (default: 60)
    maxRetries?: number;                 // Max retry attempts (default: 2)
    fetch?: typeof fetch;                // Custom fetch implementation
}

Available Environments

The SDK supports multiple environments for both REST API and WebSocket connections:

import { ApolloEnvironment } from '@aui.io/aui-client';

// Gcp Environment (Default)
ApolloEnvironment.Gcp = {
    base: "https://api.aui.io/ia-controller",      // REST API
    wsUrl: "wss://api.aui.io"                       // WebSocket
}

// Azure Environment
ApolloEnvironment.Azure = {
    base: "https://azure-v2.aui.io/ia-controller", // REST API
    wsUrl: "wss://azure-v2.aui.io"                  // WebSocket
}

// AWS Environment
ApolloEnvironment.Aws = {
    base: "https://aws.aui.io/ia-controller",      // REST API
    wsUrl: "wss://aws.aui.io"                       // WebSocket
}

// Default (same as Gcp)
ApolloEnvironment.Default = {
    base: "https://api.aui.io/ia-controller",
    wsUrl: "wss://api.aui.io"
}

Usage Example:

import { ApolloClient, ApolloEnvironment } from '@aui.io/aui-client';

// Use Azure environment
const client = new ApolloClient({
    environment: ApolloEnvironment.Azure,
    networkApiKey: 'API_KEY_YOUR_KEY_HERE'
});

// Both REST and WebSocket will use Azure endpoints
const task = await client.controllerApi.createTask({...});
const socket = await client.apolloWsSession.connect({
    debug: false,
    reconnectAttempts: 3,
    headers: {
        'x-network-api-key': 'API_KEY_YOUR_KEY_HERE'
    }
});

REST API Methods

All methods are accessed via client.controllerApi.*

createTask(request) - Create Task

Create a new task for the agent.

const taskResponse = await client.controllerApi.createTask({
    user_id: string,              // Unique user identifier
    task_origin_type: string      // Required: origin type (e.g., 'web-widget', 'mobile-app', 'api')
});

// Returns: { id: string, user_id: string, title: string, welcome_message?: string }

Note: task_origin_type is required in v1.2.17+. Common values: 'web-widget', 'mobile-app', 'api', 'internal-tool'

getTask(taskId) - Get Task By ID

Retrieve a specific task by its ID.

const task = await client.controllerApi.getTask(taskId: string);

// Returns: { id: string, user_id: string, title: string, welcome_message?: string }

Example:

const task = await client.controllerApi.getTask('your-task-id');

console.log('Task ID:', task.id);
console.log('User ID:', task.user_id);
console.log('Title:', task.title);
if (task.welcome_message) {
    console.log('Welcome:', task.welcome_message);
}

getTaskMessages(taskId) - Get Task Messages

Retrieve all messages for a specific task.

const messages = await client.controllerApi.getTaskMessages(taskId: string);

// Returns: Message[] - Array of messages

sendMessage(request) - Send Message

Submit a new message to an existing task (non-streaming).

const messageResponse = await client.controllerApi.sendMessage({
    task_id: string,              // Task identifier
    text?: string,                // Message text (optional in v1.2.36+)
    is_external_api?: boolean,    // Optional: mark as external API call
    include_business_trace?: boolean, // Optional: include NLU/understanding + business decisions in trace_info (NEW in v1.2.37; replaces include_trace_info)
    include_context_trace?: boolean,  // Optional: include context section + call_integration decisions in trace_info (NEW in v1.2.37; replaces include_trace_info)
    context?: {                   // Optional: additional context
        url?: string,
        lead_details?: Record<string, any>,
        welcome_message?: string
    },
    agent_variables?: Record<string, unknown>,  // Optional: custom agent variables
    static_context?: Record<string, unknown>    // Optional: static context data (NEW in v1.2.36)
});

// Returns: Message - Complete agent response with optional product cards

New in v1.2.28: The agent_variables parameter allows you to pass custom context to the agent:

// Example: Send message with agent variables
const response = await client.controllerApi.sendMessage({
    task_id: 'your-task-id',
    text: 'What products do you recommend?',
    is_external_api: true,
    agent_variables: {
        context: 'User is interested in electric vehicles',
        user_preference: 'eco-friendly',
        budget: 'mid-range'
    }
});

listUserTasks(request) - List User Tasks

Retrieve all tasks for a specific user with pagination.

const tasksResponse = await client.controllerApi.listUserTasks({
    user_id: string,    // User identifier
    page?: number,      // Page number (optional, default: 1)
    size?: number       // Page size (optional, default: 10)
});

// Returns: { tasks: Task[], total: number, page: number, size: number }

getProductMetadata(link) - Get Product Metadata

Retrieve metadata for a product from a given URL/link.

const metadata = await client.controllerApi.getProductMetadata({
    link: string    // Product URL or link
});

// Returns: Record<string, any> - Product metadata object

getTraceInfo(taskId, messageId) - Get Trace Info (NEW)

Retrieve trace/debug information for a specific message. Useful for debugging agent responses and understanding the processing pipeline.

const traceInfo = await client.controllerApi.getTraceInfo('your-task-id', 'your-message-id');

// Returns: Record<string, any> - Trace information object

Example:

// First, send a message with trace info enabled.
// Note: `include_trace_info` was replaced in v1.2.39 by two granular flags.
const message = await client.controllerApi.sendMessage({
    task_id: 'your-task-id',
    text: 'What products do you recommend?',
    is_external_api: true,
    include_business_trace: true,
    include_context_trace: true
});

// Then retrieve the full trace info for that message
const traceInfo = await client.controllerApi.getTraceInfo('your-task-id', message.id);
console.log('Trace Info:', traceInfo);

getDirectFollowupSuggestions(request?) - Get Direct Followup Suggestions

Retrieve AI-generated followup suggestions. Accepts optional context and created_by parameters.

const response = await client.controllerApi.getDirectFollowupSuggestions({
    context?: Record<string, unknown>,  // Optional: context data (e.g., { task_id: 'xxx' })
    created_by?: string                 // Optional: user identifier
});

// Returns: DirectFollowupSuggestionsResponse
// {
//     suggestions?: string[],    // Array of suggested followup questions
//     metadata_id?: string       // Metadata ID for tracking/analytics
// }

Example:

const response = await client.controllerApi.getDirectFollowupSuggestions({
    context: { task_id: 'your-task-id' },
    created_by: 'user123'
});

console.log('Metadata ID:', response.metadata_id);
console.log('Suggested followups:');
response.suggestions?.forEach((suggestion, index) => {
    console.log(`${index + 1}. ${suggestion}`);
});

startTextConversation(request) - Start Text Conversation (NEW)

Start a phone-channel conversation (SMS or WhatsApp) with an initial outbound message.

The SDK creates a task on the AUI backend and then proxies to the third-party-auth service so the first message is delivered to the recipient over the chosen channel. Subsequent inbound replies from the user feed back into the same task and can be observed via the standard message / WebSocket APIs.

const response = await client.controllerApi.startTextConversation({
    phoneNumber: string,        // Recipient phone number in E.164 format (e.g., '+19999999999')
    channel: 'sms' | 'whatsapp',// Outbound channel
    message?: string            // Optional initial message to send (e.g., 'Hello!')
});

// Returns: TextConversationInitiateResponse
// {
//     status: boolean,                  // true on success
//     data: Record<string, string>,     // backend payload (e.g., task / message identifiers)
//     message: string,                  // human-readable status message
//     statusCode: number                // HTTP-style status code
// }

Parameters:

• phoneNumber (required) — Must include the country code in E.164 format. Example: +15551234567. Numbers without a country code are rejected by the upstream third-party-auth service.
• channel (required) — Either 'sms' or 'whatsapp'. Determines which provider sends the initial message.
• message (optional) — The first outbound message body. If omitted, the conversation is created but no initial message is sent.

Example:

const response = await client.controllerApi.startTextConversation({
    phoneNumber: '+19999999999',
    channel: 'sms',
    message: 'Hello!'
});

console.log('Status:     ', response.status);      // true
console.log('Status Code:', response.statusCode);  // e.g. 200
console.log('Message:    ', response.message);     // e.g. 'Conversation initiated'
console.log('Data:       ', response.data);        // e.g. { task_id: '...', ... }

ℹ️ Tip: During development you can default to a sandbox number with an env var, e.g. phoneNumber: process.env.TEST_PHONE_NUMBER ?? '+15551234567'. The placeholder +15551234567 is rejected by the upstream provider — use a real, reachable E.164 number to validate end-to-end delivery.

WebSocket API

All WebSocket methods are accessed via client.apolloWsSession.*

connect(args?) - Establish Connection

Connect to the WebSocket for real-time communication.

const socket = await client.apolloWsSession.connect({
    headers?: Record<string, string>,  // Additional headers
    debug?: boolean,                   // Enable debug mode (default: false)
    reconnectAttempts?: number         // Max reconnect attempts (default: 30)
});

Socket Events

Listen to events using socket.on(event, callback):

// Connection opened
socket.on('open', () => void);

// Message received from agent
socket.on('message', (message: Response) => void);

// Error occurred
socket.on('error', (error: Error) => void);

// Connection closed
socket.on('close', (event: CloseEvent) => void);

Message Types:

• streaming_update - Partial response while agent is thinking
• final_message - Complete response with optional product cards
• error - Error message from the agent

New in v0.6.0:

• Message fields: welcome_message, executed_workflows - Track workflow execution and welcome messages
• Card fields: category, query, sub_entities, self_review - Enhanced product card information with self-review scoring
• Product Metadata API: New endpoint to retrieve metadata from product URLs

Socket Methods

// Send a message to the agent
socket.sendUserMessage({
    task_id: string,  // Task identifier
    text: string      // Message text
});

// Close the connection
socket.close();

// Wait for connection to open (returns Promise)
await socket.waitForOpen();

// Check connection state
const state = socket.readyState;
// 0 = CONNECTING, 1 = OPEN, 2 = CLOSING, 3 = CLOSED

🎯 Common Use Cases

Complete Example: E-commerce Product Search

import { ApolloClient } from '@aui.io/aui-client';

const client = new ApolloClient({
    networkApiKey: 'API_KEY_YOUR_KEY_HERE'
});

async function searchProducts(userId: string, query: string) {
    // Step 1: Create a task
    const taskResponse = await client.controllerApi.createTask({
        user_id: userId,
        task_origin_type: 'web-widget'
    });
    
    const taskId = taskResponse.id;
    console.log('Created task:', taskId);
    
    // Step 2: Connect to WebSocket with authentication
    const socket = await client.apolloWsSession.connect({
        debug: false,
        reconnectAttempts: 3,
        headers: {
            'x-network-api-key': 'API_KEY_YOUR_KEY_HERE'
        }
    });
    
    // Step 3: Set up event handlers
    socket.on('open', () => {
        console.log('Connected! Sending query...');
        socket.sendUserMessage({
            task_id: taskId,
            text: query
        });
    });
    
    socket.on('message', (message) => {
        if (message.channel?.event_name === 'thread-message-text-content-updated') {
            // Show real-time updates
            console.log('Agent:', message.data?.text);
        }
        
        if (message.id && message.text && message.sender) {
            console.log('\n✅ Final Response:', message.text);
            
            // Display product recommendations
            if (message.cards && message.cards.length > 0) {
                console.log('\n🛍️ Product Recommendations:');
                message.cards.forEach((card, index) => {
                    console.log(`${index + 1}. ${card.name}`);
                    console.log(`   Product ID: ${card.id}`);
                    if (card.parameters && card.parameters.length > 0) {
                        console.log(`   Attributes: ${card.parameters.length}`);
                    }
                });
            }
            
            // Close connection after receiving final response
            socket.close();
        }
    });
    
    socket.on('error', (error) => {
        console.error('Error:', error.message);
    });
}

// Usage
searchProducts('user123', 'I need a gaming laptop under $1500');

REST API Only: Check Task Status

import { ApolloClient } from '@aui.io/aui-client';

const client = new ApolloClient({
    networkApiKey: 'API_KEY_YOUR_KEY_HERE'
});

async function getTaskHistory(userId: string) {
    // Get all tasks for a user
    const tasksResponse = await client.controllerApi.listUserTasks({
        user_id: userId,
        page: 1,
        size: 20
    });
    
    console.log(`Found ${tasksResponse.total} tasks`);
    
    // Get messages for the most recent task
    if (tasksResponse.tasks && tasksResponse.tasks.length > 0) {
        const latestTask = tasksResponse.tasks[0];
        const messages = await client.controllerApi.getTaskMessages(latestTask.id);
        
        console.log(`Task ${latestTask.id} has ${messages.length} messages`);
        messages.forEach(msg => {
            console.log(`[${msg.sender.type}]: ${msg.text}`);
        });
    }
}

getTaskHistory('user123');

Get Product Metadata

import { ApolloClient } from '@aui.io/aui-client';

const client = new ApolloClient({
    networkApiKey: 'API_KEY_YOUR_KEY_HERE'
});

async function fetchProductMetadata(productLink: string) {
    try {
        // Fetch metadata for a product
        const metadata = await client.controllerApi.getProductMetadata({
            link: productLink
        });
        
        console.log('Product Metadata:', metadata);
        
        // Metadata might include: name, price, description, images, etc.
        if (metadata) {
            console.log('Available fields:', Object.keys(metadata));
        }
        
        return metadata;
    } catch (error) {
        console.error('Error fetching product metadata:', error);
        throw error;
    }
}

// Example usage
fetchProductMetadata('https://www.example.com/product/12345');

Send Message with Agent Variables (NEW in v1.2.28)

import { ApolloClient } from '@aui.io/aui-client';

const client = new ApolloClient({
    networkApiKey: 'API_KEY_YOUR_KEY_HERE'
});

async function sendContextualMessage(taskId: string, message: string, userContext: Record<string, unknown>) {
    try {
        // Send a message with custom agent variables for contextual responses
        const response = await client.controllerApi.sendMessage({
            task_id: taskId,
            text: message,
            is_external_api: true,
            agent_variables: userContext
        });
        
        console.log('Agent Response:', response.text);
        
        // The agent will use the provided context to tailor its response
        if (response.cards && response.cards.length > 0) {
            console.log('Recommended products:', response.cards.length);
        }
        
        return response;
    } catch (error) {
        console.error('Error sending message:', error);
        throw error;
    }
}

// Example usage - provide context about user preferences
sendContextualMessage('task-123', 'What do you recommend?', {
    context: 'User is browsing electric vehicles',
    user_preference: 'eco-friendly',
    budget_range: '$30,000 - $50,000',
    location: 'California'
});

Get Trace Info (NEW)

import { ApolloClient } from '@aui.io/aui-client';

const client = new ApolloClient({
    networkApiKey: 'API_KEY_YOUR_KEY_HERE'
});

async function debugAgentResponse(taskId: string) {
    try {
        // Send a message with trace info enabled.
        // `include_trace_info` was replaced with the two flags below in v1.2.37.
        const message = await client.controllerApi.sendMessage({
            task_id: taskId,
            text: 'What products do you recommend?',
            is_external_api: true,
            include_business_trace: true,
            include_context_trace: true
        });

        console.log('Agent Response:', message.text);

        // Retrieve the full trace info for debugging
        const traceInfo = await client.controllerApi.getTraceInfo(taskId, message.id);
        console.log('Trace Info:', traceInfo);

        return traceInfo;
    } catch (error) {
        console.error('Error getting trace info:', error);
        throw error;
    }
}

debugAgentResponse('task-123');

Get Direct Followup Suggestions

import { ApolloClient } from '@aui.io/aui-client';

const client = new ApolloClient({
    networkApiKey: 'API_KEY_YOUR_KEY_HERE'
});

async function getSuggestedQuestions(taskId: string, userId: string) {
    try {
        // Get AI-generated followup suggestions with context and user info
        const response = await client.controllerApi.getDirectFollowupSuggestions({
            context: { task_id: taskId },
            created_by: userId
        });
        
        console.log('Metadata ID:', response.metadata_id);
        console.log('Suggested followup questions:');
        response.suggestions?.forEach((suggestion, index) => {
            console.log(`  ${index + 1}. ${suggestion}`);
        });
        
        return response;
    } catch (error) {
        console.error('Error getting suggestions:', error);
        throw error;
    }
}

// Example usage
getSuggestedQuestions('task-123', 'user-456');
// Output:
// Metadata ID: 69e4b4d4359671434fdff849
// Suggested followup questions:
//   1. "What colors are available?"
//   2. "Do you offer financing options?"
//   3. "Can I schedule a test drive?"

Start a Text Conversation - SMS / WhatsApp (NEW)

Reach a user over their phone channel (SMS or WhatsApp) with an initial outbound message. Internally, the SDK creates a task and dispatches the first message through Apollo's third-party-auth service — replies from the user thread back into the same task so you can keep using the existing message APIs and WebSocket events.

import { ApolloClient, Apollo } from '@aui.io/aui-client';

const client = new ApolloClient({
    networkApiKey: 'API_KEY_YOUR_KEY_HERE'
});

async function startTextConversation(
    phoneNumber: string,
    channel: 'sms' | 'whatsapp',
    message: string
) {
    try {
        const response: Apollo.TextConversationInitiateResponse =
            await client.controllerApi.startTextConversation({
                phoneNumber,   // E.164 format, e.g. '+19999999999'
                channel,       // 'sms' or 'whatsapp'
                message        // initial message body, e.g. 'Hello!'
            });

        console.log('✅ Conversation initiated');
        console.log('   Status:     ', response.status);
        console.log('   Status Code:', response.statusCode);
        console.log('   Message:    ', response.message);
        console.log('   Data:       ', response.data);

        return response;
    } catch (error: any) {
        console.error('❌ Error starting text conversation:', error.message);
        if (error.body) {
            console.error('   Body:', error.body);
        }
        throw error;
    }
}

// SMS
startTextConversation('+19999999999', 'sms', 'Hello!');

// WhatsApp
startTextConversation('+971501234567', 'whatsapp', 'Hi from AUI!');

UI mapping: This is the API behind the "Start Text Conversation" panel — phone number + channel selector (SMS / WhatsApp) + initial message — wired directly to client.controllerApi.startTextConversation({ phoneNumber, channel, message }).

Common errors:

| Symptom | Likely cause | Fix | |---------|--------------|-----| | 500 from upstream third-party-auth | Invalid or unreachable phone number (e.g., placeholder +15551234567) | Use a real E.164 number, including the country code | | 422 Unprocessable Entity | phoneNumber or channel missing / wrong shape | Ensure channel is exactly 'sms' or 'whatsapp' and phoneNumber starts with + | | 401 / 403 | Missing or invalid networkApiKey | Pass networkApiKey to ApolloClient (or the x-network-api-key header) |

🔧 Advanced Configuration

Custom Timeout and Retries

const client = new ApolloClient({
    networkApiKey: 'API_KEY_YOUR_KEY_HERE',
    timeoutInSeconds: 120,  // 2 minute timeout
    maxRetries: 5           // Retry up to 5 times
});

// Per-request overrides
const taskResponse = await client.controllerApi.createTask(
    { 
        user_id: 'user123',
        task_origin_type: 'web-widget'
    },
    {
        timeoutInSeconds: 30,  // Override for this request only
        maxRetries: 2
    }
);

WebSocket with Reconnection

const socket = await client.apolloWsSession.connect({
    debug: true,                // Enable debug logging
    reconnectAttempts: 50,      // Try to reconnect up to 50 times
    headers: {
        'x-network-api-key': 'API_KEY_YOUR_KEY_HERE'
    }
});

// The WebSocket will automatically attempt to reconnect on failure
socket.on('close', (event) => {
    console.log(`Connection closed with code ${event.code}`);
    // Socket will auto-reconnect unless you called socket.close()
});

Error Handling Best Practices

import { ApolloClient, UnprocessableEntityError, ApolloError } from '@aui.io/apollo-sdk';

const client = new ApolloClient({
    networkApiKey: 'API_KEY_YOUR_KEY_HERE'
});

try {
    const taskResponse = await client.controllerApi.createTask({
        user_id: 'user123',
        task_origin_type: 'web-widget'
    });
} catch (error) {
    if (error instanceof UnprocessableEntityError) {
        // Validation error (422)
        console.error('Validation failed:', error.body);
    } else if (error instanceof ApolloError) {
        // Other API errors
        console.error('API error:', error.statusCode, error.body);
    } else {
        // Network or other errors
        console.error('Unexpected error:', error);
    }
}

📦 TypeScript Support

This SDK is written in TypeScript and includes full type definitions. All types are automatically exported:

import { 
    ApolloClient,
    // Request types
    CreateExternalTaskRequest,
    SubmitExternalMessageRequest,
    UserMessagePayload,
    TextConversationInitiateRequest,
    // Response types
    CreateExternalTaskResponse,
    ExternalTaskMessage,
    ListExternalTasksResponse,
    StreamingUpdatePayload,
    FinalMessagePayload,
    ErrorMessagePayload,
    TextConversationInitiateResponse,
    // Error types
    ApolloError,
    UnprocessableEntityError
} from '@aui.io/apollo-sdk';

// All methods have full IntelliSense support
const client = new ApolloClient({
    networkApiKey: 'YOUR_KEY'
});

// TypeScript will autocomplete and type-check
const taskResponse = await client.controllerApi.createTask({ user_id: 'user123' });
taskResponse.id; // ✅ Fully typed

🐛 Troubleshooting

WebSocket Connection Issues

Problem: Connection fails with 1008 Policy Violation or authentication errors

Solution 1: Make sure you're using SDK version 1.1.7 or higher, which includes a fix for Node.js v21+ WebSocket compatibility:

npm install @aui.io/apollo-sdk@latest

Solution 2: If using an older SDK version, downgrade to Node.js v20:

# Check your Node version
node --version

# Switch to Node 20 if using nvm
nvm use 20

# Or install Node 20
nvm install 20

Solution 3: Verify your API key is being passed correctly:

const client = new ApolloClient({
    networkApiKey: 'API_KEY_YOUR_KEY_HERE'  // Make sure this is set
});

// Or pass it per-request
const socket = await client.apolloWsSession.connect({
    headers: {
        'x-network-api-key': 'API_KEY_YOUR_KEY_HERE'
    }
});

Authentication Errors (401/403)

Problem: Getting 401 Unauthorized or 403 Forbidden errors

Solution: Verify your API key:

const client = new ApolloClient({
    networkApiKey: 'API_KEY_YOUR_KEY_HERE'  // Double-check this value
});

// The key should start with "API_KEY_"
// Example: API_KEY_01K------

CORS Errors (Browser Only)

Problem: Getting CORS errors when using the SDK in a browser

Solution: The API must be configured to allow requests from your domain. Contact your API administrator to whitelist your origin.

TypeScript Errors

Problem: TypeScript compilation errors or missing type definitions

Solution: Ensure you're using TypeScript 4.0 or higher:

npm install --save-dev typescript@latest

📚 Examples

The examples/ directory contains ready-to-run code examples:

• Product Metadata API - examples/test-product-metadata.js
  • Fetch product information from URLs
  • Handle errors and edge cases
  • Extract and use metadata

Run examples:

export NETWORK_API_KEY="API_KEY_YOUR_KEY_HERE"
node examples/test-product-metadata.js

See the examples README for more details.

🔗 Resources

• GitHub Repository: aui-io/aui-client-typescript
• npm Package: @aui.io/aui-client
• API Documentation: Full API Reference
• Report Issues: GitHub Issues

📄 License

This SDK is proprietary software. Unauthorized copying or distribution is prohibited.

🤝 Support

For support, please contact your AUI representative or open an issue on GitHub.

Built with ❤️ by the AUI team