@iflytek-aichain/sdk

JavaScript/TypeScript client SDK for IIP Dispatch Protocol, mirroring the Python SDK implementation.

Installation

From npm (after publishing)

npm install @iflytek-aichain/sdk
# or
yarn add @iflytek-aichain/sdk

Local Development

npm install
npm run build

Build

Build the project to generate both CommonJS and ES module outputs:

npm run build

This will generate:

• dist/index.js - CommonJS entry point
• dist/index.esm.js - ES module entry point
• dist/index.d.ts - TypeScript type definitions

Publishing to npm

1. Prepare for Publishing

Before publishing, make sure:

1. Update version in package.json
2. Build the project: npm run build
3. Test locally (see Testing section below)

2. Publish to npm

# Login to npm (if not already logged in)
npm login

# Publish (will automatically run prepublishOnly script to build)
npm publish --access public

Note: The package name is @iflytek-aichain/sdk. If this is a scoped package, you may need to configure npm access.

3. Verify Installation

After publishing, test installation in a new project:

mkdir test-install
cd test-install
npm init -y
npm install @iflytek-aichain/sdk

Then create a test file:

const { AIChainClient } = require('@iflytek-aichain/sdk');
console.log('SDK imported successfully!');

Testing and Debugging

Running the Example

The project includes example files to test the SDK functionality:

# Set environment variables
export APP_ID="your_app_id"
export APP_KEY="your_app_key"
export HOST="localhost:8080"
export SN="test_sn_001"
export SCENE="main"

# Run CommonJS example
npm run example

# Or run ES module example
node examples/test-esm.mjs

Local Testing Without Publishing

To test the SDK locally without publishing to npm:

1. Build the project:

   npm run build

2. Use npm link (recommended):

   # In the SDK directory
   npm link
      
   # In your test project directory
   npm link @iflytek-aichain/sdk

3. Or use file path directly:

   // In your test project
   const { AIChainClient } = require('../iip-dispatch-client-sdk-js/dist/index.js');

Testing with Real Backend

1. Start your backend server (make sure it's running on the configured host)

2. Run the example:

   # Set your configuration
   export APP_ID="your_app_id"
   export APP_KEY="your_app_key"
   export HOST="localhost:8080"  # Your backend host
   export SN="test_sn_001"
      
   # Run the example
   npm run example

3. Monitor the output:

   • The example will connect to the server
   • Send test messages
   • Display received events
   • Show connection status

Debugging Tips

1. Enable debug mode:

   const client = new AIChainClient({
     // ... other options
     debug: true,
   });

2. Check connection state:

   console.log('Connection state:', client.getConnectionState());
   console.log('Connection info:', client.getConnectionInfo());

3. Listen to all events:

   client.on('*', (event, ...args) => {
     console.log('Event:', event, args);
   });

4. Handle errors:

   client.on('error', (code, message) => {
     console.error('Error:', code, message);
   });
      
   client.on('session.error', (error) => {
     console.error('Session error:', error);
   });

Usage

Import

// ES Module
import { AIChainClient } from '@iflytek-aichain/sdk';

// CommonJS
const { AIChainClient } = require('@iflytek-aichain/sdk');

Basic Example

import { AIChainClient, SessionConfig } from '@iflytek-aichain/sdk';

// Create client instance
const client = new AIChainClient({
  appId: 'your-app-id',
  appKey: 'your-app-key',
  host: 'your-host',
  sn: 'your-sn',
  scene: 'main',
  channel: 'real_time',
  autoReconnect: true,
  reconnectInterval: 1000,
  maxReconnectInterval: 30000,
  maxReconnectAttempts: 10,
});

// Register event listeners
client.on('session.created', (sid) => {
  console.log('Session created:', sid);
});

client.on('nlu.answer', (cid, result, last) => {
  console.log('NLU answer:', result.answer);
});

client.on('tts.audio', (cid, result, last) => {
  console.log('TTS audio received, index:', result.index, 'encoding:', result.audioEncoding);
  // result.data is base64 encoded audio string
});

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

const config: SessionConfig = {
  mode: 'full_duplex',
  simplifiedResponse: true,
  multiTurnEnabled: true,
  stt: {
    enable: true,
    language: 'auto', // Single language: 'zh', 'en', 'ja', etc. Multi-language: 'zh|en|ja' (supported by sttEngineId 3, 4, 5)
    audioConfig: {
      sampleRate: 16000,
      bitDepth: 16,
      channels: 1,
    },
  },
  nlu: {
    enable: true,
  },
  tts: {
    enable: true,
    textFilters: ['filter_markdown', 'filter_emoji'],
    voices: {
      zh: {
        voiceId: '4',
        speed: 5,
        pitch: 5,
        volume: 5,
        audioConfig: {
          audioEncoding: 'opus-wb',
          sampleRate: 16000,
          bitDepth: 16,
          channels: 1,
        },
      },
    },
  },
};

await client.setConfig(config);

// Send text message
await client.sendText('Hello, world!');

// Send audio stream
const audioData = new Uint8Array([...]); // Your audio data
await client.sendAudioStream(audioData, false); // isEnd = false for streaming
await client.sendAudioStream(audioData, true); // isEnd = true for final chunk

// Disconnect
await client.disconnect();

API Reference

AIChainClient

Main client class for connecting to IIP Dispatch service.

Constructor Options

• appId: Application ID
• appKey: Application key
• host: Server host
• sn: Serial number
• scene: Scene name (default: 'main')
• channel: Channel name (default: 'real_time')
• autoReconnect: Enable auto reconnect (default: true)
• reconnectInterval: Initial reconnect interval in ms (default: 1000)
• maxReconnectInterval: Maximum reconnect interval in ms (default: 30000)
• maxReconnectAttempts: Maximum reconnect attempts (default: 10)
• debug: Enable debug mode (default: false)

Methods

• connect(): Establish WebSocket connection
• disconnect(): Close connection
• reconnect(): Manual reconnection
• setConfig(config: SessionConfig): Send session configuration
• getConfig(): Get current session configuration
• beginSend(): Generate new CID for next conversation
• cancel(): Cancel current conversation
• sendText(text: string): Send text message
• sendTextStream(text: string, isEnd: boolean): Send text stream
• sendAudio(audioData: Uint8Array): Send single audio frame
• sendAudioStream(audioData: Uint8Array, isEnd: boolean): Send audio stream
• sendImage(imageData: string, extend?: Record<string, any>): Send image
• sendMsgs(items: Array<TextItem | ImageItem | AudioItem>): Send multiple items
• on(event: string, callback: EventCallback): Register event listener
• off(event: string, callback?: EventCallback): Remove event listener
• removeAllListeners(event?: string): Remove all listeners
• isConnected(): Check if connected
• getConnectionState(): Get connection state
• getConnectionInfo(): Get connection information

Events

• connecting: Emitted when connecting
• session.created: Emitted when session is created (sid)
• session.configed: Emitted when session is configured (sid, config)
• session.error: Emitted on session error (error)
• stt.result: Emitted on STT result (cid, result, last)
• nlu.answer: Emitted on NLU answer (cid, result, last)
• nlu.tool_selection: Emitted on tool selection (cid, result)
• nlu.tool_execution: Emitted on tool execution (cid, result)
• nlu.rag_retrieval: Emitted on RAG retrieval (cid, result)
• nlu.trace: Emitted on NLU trace (cid, result)
• tts.audio: Emitted on TTS audio (cid, result, last)
• welcome.answer: Emitted on welcome answer (cid, result)
• welcome.audio: Emitted on welcome audio (cid, result)
• event.interrupted: Emitted on interruption (cid)
• event.user_speech_started: Emitted when user speech starts (cid)
• event.user_speech_stopped: Emitted when user speech stops (cid)
• event.stt_revocation: Emitted when STT result should be revoked (cid)
• event.cid_end: Emitted when CID ends (cid, stats)
• pong: Emitted on pong response
• reconnecting: Emitted during reconnection (attempts, maxAttempts)
• close: Emitted on connection close (code, reason)
• error: Emitted on error (code, message)

License

ISC