Artemis React Native Socket SDK

A headless WebSocket + auth + chat transport SDK for the Artemis platform, written in TypeScript for React Native. It contains no UI — only the connection, authentication, and messaging logic that a UI layer (such as the sibling ../UI SDK) builds on top of.

• Features: authenticated WebSocket sessions, streaming chat, persisted history, automatic reconnection with exponential backoff, and pending-message resend.
• Public surface: a single AgentSDK entry point (initialize, connect, sendMessage, getMessages, getWidgetConfig, event subscriptions).
• Zero native dependencies: relies only on the global WebSocket and fetch that React Native provides.

Architecture

The SDK is split into four focused modules. AgentSDK is the only public entry point; the other three are internal collaborators it orchestrates.

| Class | Responsibility | | ---------------- | --------------------------------------------------------- | | AgentSDK | Public API, wires the clients together, fans out events. | | TokenManager | Bootstraps/refreshes short-lived SDK session tokens. | | SessionManager | Opens the WebSocket, handles session_start, reconnects. | | ChatClient | Sends messages, parses streaming responses, loads history.|

AgentSDK

The orchestrator and public API. It parses/validates configuration, instantiates the three managers, and re-broadcasts their signals as two streams: on('event') for connection lifecycle and on('chat') for chat activity.

TokenManager

Owns authentication. It exchanges your api_key (or bootstrap_token) for a short-lived SDK session token via /api/v1/sdk/init, refreshes it before expiry through /api/v1/sdk/refresh, and exposes the server-provided widget config.

SessionManager

Owns the socket lifecycle. It requests a WebSocket ticket (/api/v1/sdk/ws-ticket, with a legacy subprotocol fallback), opens /ws/sdk, gates "connected" on the session_start handshake, and drives reconnection with exponential backoff.

ChatClient

Owns messaging. It sends outgoing messages, assembles streaming response frames (response_start / response_chunk / response_end), hydrates persisted history, replays unanswered messages after a reconnect, and keeps the local message store that getMessages() reads from.

Configuration

Configuration is supplied to initialize as a plain object. Keys are snake_case on input:

const config = {
  environment: 'dev',
  connection: {
    project_id: 'YOUR_PROJECT_ID',
    api_key: 'YOUR_API_KEY',
    endpoint: 'https://your-artemis-endpoint.example.com',
  },
  channel: {
    channel_id: 'YOUR_CHANNEL_ID',
    channel_name: 'RN Demo App',
  },
  websocket: {
    reconnection: {
      enabled: true,
      max_attempts: 5,
      base_delay_ms: 1000,
      max_delay_ms: 30000,
      exponential_backoff: true,
    },
  },
  chat: {
    enable_typing_indicator: true,
    enable_thoughts: false,
  },
  debug: { enabled: true, log_level: 'debug', log_websocket_messages: true },
};

Authentication requires either connection.api_key or connection.bootstrap_token (not both).

Usage

import { AgentSDK } from '@koredev/artemis-react-native-socket-sdk';

const sdk = await AgentSDK.initialize({ config });

// Connection lifecycle events
sdk.on('event', (event) => {
  switch (event.type) {
    case 'connected':
      console.log('connected', event.sessionId);
      break;
    case 'disconnected':
      console.log('disconnected', event.reason);
      break;
    case 'reconnecting':
      console.log(`reconnecting ${event.attempt}/${event.maxAttempts}`);
      break;
    case 'error':
      console.warn('sdk error', event.code, event.error);
      break;
  }
});

// Chat events (streaming, history, typing)
sdk.on('chat', (event) => {
  switch (event.type) {
    case 'messageStart':
    case 'messageChunk':
    case 'messageEnd':
    case 'messageReceived':
    case 'historyLoaded':
      setMessages(sdk.getMessages());
      break;
    case 'typingIndicator':
      setTyping(event.isTyping);
      break;
    case 'thought':
      console.log('thought', event.content);
      break;
    case 'chatError':
      console.warn('chat error', event.error);
      break;
  }
});

const sessionId = await sdk.connect();
await sdk.sendMessage('Hello!');

// Optional: attach data to every outgoing message for this session
sdk.updateCustomData({ plan: 'enterprise' });

// Teardown
await sdk.dispose();

Public API

| Member | Description | | ------------------------------------- | ------------------------------------------------- | | AgentSDK.initialize({ config, … }) | Parse/validate config and wire up clients. | | AgentSDK.createWithConfig(config) | Create from an already-parsed SDKConfiguration. | | connect() | Connect; resolves with the sessionId. | | disconnect() | Close the socket (no end_session). | | endSession() | Send end_session, clear custom data, close. | | isConnected() / getSessionId() | Connection status helpers. | | getWidgetConfig() | Server-provided widget theming config. | | sendMessage(text, opts?) | Send a message; resolves with the local id. | | getMessages() | Locally-stored messages. | | updateCustomData() / getCustomData() / clearCustomData() | Session-scoped custom data. | | clearHistory() | Clear the local message store. | | on('event' \| 'chat', handler) | Subscribe; returns an unsubscribe function. | | dispose() | Tear down and release all resources. |

Build

npm install
npm run build   # tsc -> dist/

Examples

• Headless smoke test — connect to the live runtime and send a message:

npm run smoke

• React Native app (Android + iOS) — a sample chat UI built on the SDK. The example/ folder is the app itself; see example/README.md for run instructions (cd example && npm install && npm run android / npm run ios).