@ixo/oracles-client-sdk

@ixo/oracles-client-sdk

Production-ready React SDK for building AI-powered applications with QiForge

Features

• Real-time Streaming - AI responses with optimized streaming
• Chat Management - Complete session and message management
• Custom UI Components - Extensible component system for rich interactions
• Voice & Video Calls - Encrypted live agent calls
• Memory Engine - Optional persistent context across sessions
• Payment Integration - Built-in oracle payment handling
• Type Safe - Full TypeScript support with comprehensive types

Installation

npm install @ixo/oracles-client-sdk
# or
pnpm add @ixo/oracles-client-sdk
# or
yarn add @ixo/oracles-client-sdk

Quick Start

import {
  OraclesProvider,
  useChat,
  useOracleSessions,
  renderMessageContent,
} from '@ixo/oracles-client-sdk';

function App() {
  return (
    <OraclesProvider
      initialWallet={{
        address: 'ixo1...',
        did: 'did:ixo:entity:...',
        matrix: { accessToken: 'syt_...' },
      }}
      transactSignX={async (messages, memo) => {
        // Handle blockchain transactions
        return undefined;
      }}
    >
      <ChatInterface />
    </OraclesProvider>
  );
}

function ChatInterface() {
  const oracleDid = 'did:ixo:entity:oracle-id';

  // Create or get session
  const { createSession, sessions } = useOracleSessions(oracleDid);
  const sessionId = sessions?.[0]?.sessionId;

  // Chat functionality
  const { messages, sendMessage, isSending } = useChat({
    oracleDid,
    sessionId: sessionId || '',
    onPaymentRequiredError: (claimIds) => {
      console.log('Payment required:', claimIds);
    },
  });

  return (
    <div className="chat-container">
      {/* Create session button */}
      <button onClick={() => createSession()}>New Chat</button>

      {/* Messages */}
      <div className="messages">
        {messages.map((msg) => (
          <div key={msg.id} className={msg.type}>
            {/* Render message content (handles text and components) */}
            {renderMessageContent(msg.content)}
          </div>
        ))}
      </div>

      {/* Input */}
      <form
        onSubmit={(e) => {
          e.preventDefault();
          const input = e.currentTarget.message;
          sendMessage(input.value);
          input.value = '';
        }}
      >
        <input name="message" placeholder="Ask anything..." />
        <button type="submit" disabled={isSending}>
          {isSending ? 'Sending...' : 'Send'}
        </button>
      </form>
    </div>
  );
}

📚 Documentation

• Usage Guide - Complete walkthrough with examples
• API Reference - Full API documentation
• Tool Calls & Browser Tools - Tool calls and browser-side tools
• Examples - Practical code examples
• Live Agent - Voice & video calls guide

Key Concepts

Message Rendering

The SDK stores messages as plain data (not React elements) for optimal performance. Use renderMessageContent to transform messages into UI:

import { renderMessageContent } from '@ixo/oracles-client-sdk';

// Handles strings, custom components, and mixed content
{
  messages.map((msg) => (
    <div key={msg.id}>{renderMessageContent(msg.content, uiComponents)}</div>
  ));
}

Custom UI Components

Register custom components for rich interactions:

const uiComponents = {
  WeatherWidget: (props) => (
    <div>
      <h3>Weather in {props.city}</h3>
      <p>{props.temperature}°C</p>
    </div>
  ),
  PriceChart: (props) => <Chart data={props.data} />,
};

const { messages } = useChat({
  oracleDid,
  sessionId,
  uiComponents, // Pass to useChat
  onPaymentRequiredError: () => {},
});

Real-time Streaming

Messages stream in real-time with optimized performance:

• RAF Batching: Uses requestAnimationFrame to batch multiple rapid updates into single render cycles, preventing UI stuttering during high-frequency streaming
• Efficient State Updates: Shallow copies only (no expensive deep cloning)
• Smooth Performance: Maintains 60fps streaming even at 100+ chunks/sec
• Memory Optimized: Metadata-based component storage reduces memory footprint

Voice & Video (Optional)

Live agent calls are lazy loaded to keep your bundle small:

// Import separately to avoid loading ~500KB unless needed
import { useLiveAgent } from '@ixo/oracles-client-sdk/live-agent';

🛠️ Core APIs

Hooks

• useChat - Real-time chat with streaming
• useOracleSessions - Session management
• useContractOracle - Payment and authorization
• useMemoryEngine - Matrix room management and memory engine setup
• useLiveAgent - Voice/video calls (separate bundle)

Components

• OraclesProvider - Required context provider
• renderMessageContent - Message renderer utility

Types

• IMessage - Message structure
• MessageContent - Content types (string | metadata | array)
• IComponentMetadata - Custom component metadata
• IChatSession - Session info

TypeScript Support

Fully typed with comprehensive interfaces:

import type {
  IMessage,
  MessageContent,
  IChatSession,
  UIComponentProps,
} from '@ixo/oracles-client-sdk';

📄 License

Licensed under the terms specified in License.txt

🔗 Links

• IXO Website
• Documentation
• Examples
• GitHub Repository

Built with ❤️ by the IXO team