ai_licia Client

A TypeScript/JavaScript client library for interacting with with ai_licia AI Co-Host API, allowing you to send context data and trigger reactions from ai_licia in your Twitch stream.

Installation

npm install ai_licia-client

Configuration

You can configure the client using environment variables:

AI_LICIA_API_URL=https://api.getailicia.com/v1
AI_LICIA_API_KEY=your-api-key
AI_LICIA_CHANNEL=your-channel-name

Or you can provide them directly when initializing the client.

Usage

Basic Usage

import { AiliciaClient } from 'ai_licia-client';

// Create a new client
const client = new AiliciaClient(
  'your-api-key',    // Optional, will use environment variable if not provided
  'your-channel',    // Optional, will use environment variable if not provided
  'https://api.getailicia.com/v1'  // Optional, will use environment variable or the default if not provided
);

// Send contextual information to ai_licia (max 700 characters)
await client.sendEvent('Player health: 85%, Position: X:145 Y:230, Kills: 12');

// Trigger an immediate reaction from ai_licia (max 300 characters)
const response = await client.triggerGeneration('Player just defeated the final boss!');

// Listen to the live message stream
const messageStream = client.streamPublicChatMessages({
  roles: ['AI', 'Streamer'],
  onOpen: () => console.log('Listening to ai_licia and the streamer'),
  onMessage: (message) => console.log(`${message.role}: ${message.content}`),
  onError: (error) => console.error('Stream error', error),
  onClose: () => console.log('Stream closed')
});

// Stop streaming whenever you need to
messageStream.close();

// Fetch characters and rotate personas
const characters = await client.listCharacters();
const chillPersona = characters.find((c) => !c.isActive);
if (chillPersona) {
  await client.setActiveCharacter(chillPersona.id);
}

// Ask ai_licia to join chat (defaults to the configured channel)
await client.requestStreamJoin();

API Reference

AiliciaClient

The main class for interacting with the ai_licia API. (Official Documentation)

Constructor

new AiliciaClient(apiKey?: string, channelName?: string, baseUrl?: string)

Methods

sendEvent(content: string, ttl?: number): Promise<void>

Sends contextual information to ai_licia that will be stored in her memory and used for future interactions. This doesn't trigger an immediate response but enriches ai_licia's understanding of what's happening in your stream.

Use cases:

• Stream game state (health, position, inventory)
• Current music playing
• Chess board state in ASCII
• Player statistics, progress, or achievements
• Stream milestones
• Your setup state (lights colour, fan active or off, etc)

Parameters:

• content: The information to send (max 700 characters)
• ttl: (Optional) Time-to-live in seconds - how long this information stays relevant

// Examples
await client.sendEvent('Current song: "Never Gonna Give You Up" by Rick Astley');
await client.sendEvent(`Chess board: 
♜♞♝♛♚♝♞♜
♟♟♟♟♟♟♟♟
□■□■□■□■
■□■□■□■□
□■□■□■□■
■□■□■□■□
♙♙♙♙♙♙♙♙
♖♘♗♕♔♗♘♖
White turn
`);
await client.sendEvent('Player stats: Health: 75/100, Mana: 30/100, Position: Forest of Doom');

triggerGeneration(content: string): Promise<GenerationResponse>

Triggers ai_licia to generate an immediate response to a specific event or moment. This creates a one-off reaction from ai_licia that will appear in your stream.

Use cases:

• Player just defeated a boss
• Viewer redeemed channel points for ai_licia to roast them
• Plane crash in a simulator
• Reaching a milestone in-game
• Reaction to a funny/epic moment

Parameters:

• content: What ai_licia should react to (max 300 characters)

// Examples
await client.triggerGeneration('Player just pulled a legendary sword from the stone!');
await client.triggerGeneration('Viewer "GameMaster42" redeemed points for an ai_licia roast');
await client.triggerGeneration('Plane crashed into the mountain. Total damage: $2.5M');

streamPublicChatMessages(options: ChatMessageStreamOptions): ChatMessageStream

Connects to the public chat message stream (Server-Sent Events) so you can react to realtime chat data within your tooling.

Parameters:

• roles (optional): Filter the stream for specific roles ('Mod' | 'VIP' | 'AI' | 'Viewer' | 'Streamer')
• onMessage: Required callback invoked with the parsed PublicChatMessage
• onOpen, onError, onClose: Optional lifecycle callbacks

const stream = client.streamPublicChatMessages({
  roles: ['AI'],
  onOpen: () => console.log('Connected to ai_licia chat stream'),
  onMessage: (message) => {
    if (message.role === 'AI') {
      console.log(`ai_licia: ${message.content}`);
    }
  },
  onError: (error) => console.error('Stream error:', error.message),
  onClose: () => console.log('Stream closed')
});

// Later, when you want to disconnect:
stream.close();

listCharacters(): Promise<CharacterSummary[]>

Returns the list of personas linked to your account (id, name, description, isActive flag).

const characters = await client.listCharacters();
characters.forEach((character) =>
  console.log(`${character.name} - ${character.isActive ? 'active' : 'inactive'}`)
);

setActiveCharacter(characterId: string): Promise<void>

Switches the active persona for ai_licia.

await client.setActiveCharacter('char_123');

requestStreamJoin(channelName?: string): Promise<JoinChannelResponse>

Asks ai_licia to join chat immediately. Omitting channelName uses the one configured in the client.

const join = await client.requestStreamJoin();
if (!join.success) {
  console.warn('Join failed', join.message);
}

requestStreamLeave(channelName?: string): Promise<void>

Queues a leave request for ai_licia on the target channel.

await client.requestStreamLeave('backupChannel');

streamEventSub(auth: EventSubAuth, options?: EventSubStreamOptions): EventSubStream

Connects to the unified EventSub SSE stream (chat, AI, channel, system, moderation, character events) and returns an event-emitter style handle.

const eventStream = client.streamEventSub(
  { type: 'jwt', token: viewerJwt },
  {
    types: ['chat.message', 'ai.tts.generated'],
    autoReconnect: true,
    handlers: {
      'chat.message': (event) => {
        console.log(`[${event.payload.platform}] ${event.payload.username}: ${event.payload.message}`);
      }
    }
  }
);

eventStream
  .on('ai.tts.generated', (event) => {
    console.log(`New TTS clip at ${event.payload.ttsStreamUrl}`);
  })
  .onAny((event) => console.log(`Received ${event.type}`));

// Stop streaming
eventStream.close();

Notes:

• auth must be either { type: 'jwt', token: '...' } (frontend JWT) or { type: 'apiKey', key: '...' } (external clients).
• Browsers cannot set headers on native EventSource. Use the client method (fetch streaming) or an EventSource polyfill that supports headers. Do not put tokens in query strings.

Error Handling

The client throws descriptive errors when API calls fail. You can catch these errors to handle them gracefully:

try {
  await client.sendEvent('Player entered the final dungeon');
} catch (error) {
  console.error('Failed to send event:', error.message);
}

Common errors:

• Content length exceeding limits (700 chars for events, 300 chars for generations)
• API key authorization issues
• Rate limiting (too many requests)

Environment Setup

You can use environment variables with dotenv by creating a .env file:

AI_LICIA_API_KEY=your_api_key_here
AI_LICIA_CHANNEL=your_twitch_channel_name

Then in your code:

import { AiliciaClient } from 'ai_licia-client';
import dotenv from 'dotenv';

// Load environment variables
dotenv.config();

// Create client using environment variables
const client = new AiliciaClient();

// Now you can use client.sendEvent() and client.triggerGeneration()

Official Integrations & Partnerships

Are you a game developer, app creator, or platform looking to build a deeper integration with ai_licia? We welcome partnerships to create official, branded integrations that enhance the streaming experience!

Who Should Reach Out

• Game Studios: Create direct integrations that allow ai_licia to react to in-game events in real time
• App Developers: Integrate ai_licia into your streaming tools, bots, or community platforms
• Hardware Manufacturers: Connect physical devices, alerts, or hardware state to ai_licia
• Platform Creators: Build ai_licia capabilities into your streaming or content creation platform

Partnership Benefits

• Co-Marketing: Joint promotion of your integration to the ai_licia community
• Technical Support: Direct access to our development team
• API Enhancements: Potential for custom endpoints to support your specific needs
• Featured Integration: Highlighted placement in our documentation and website

Getting Started

To discuss partnership opportunities, join our Discord community and message in the #general channel.

We're particularly interested in integrations that create unique interactive experiences for streamers and their audience!

Need Help?

If you need help or have questions, please check the ai_licia documentation or visit our Discord community.

Development

Prerequisites

• Node.js (v14+)
• npm or yarn

Local Development

1. Clone the repo

   git clone [email protected]:novasquare-ailicia/ai_licia-core.git

2. Install dependencies

   cd ai_licia-core
   npm install

3. Build the package

   npm run build:client

Running Tests

npm test

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

Please check out the contributing guidelines for more information.

License

Distributed under the MIT License. See LICENSE for more information.

Related

• ai_licia-aitum - Aitum Custom Code integration for ai_licia