@sonex/sdk-server

Client SDK for Sonex - Intent-based API routing. Works like OpenAI/Claude npm packages - no database required.

Installation

npm install @sonex/sdk-server

Quick Start

// server.ts or app.ts (your server's starting file)
import { SonexClient, watch } from '@sonex/sdk-server';

// 1. Create a session
const client = new SonexClient({
  api_key: 'sonex_sk_...',
  auth_token: 'user-auth-token-from-your-backend'
});

const session = await client.createSession();

// 2. Watch intent file - MUST be called in your server's starting file
// Only requires API key - no auth_token needed
watch('sonex_sk_...');

Important: The watch() function must be called in your server's main entry file (e.g., server.ts, app.ts, index.ts) to detect file changes. It won't work if called in a module that's not actively running.

Features

• ✅ Session Management - Create and manage user sessions
• ✅ Intent File Watching - Auto-sync intents.json to Sonex API
• ✅ Zero Configuration - Works out of the box with your API key
• ✅ TypeScript Support - Full type definitions included
• ✅ No Database Required - Pure HTTP client, no dependencies

API Reference

SonexClient

Create and manage sessions with the Sonex API.

import { SonexClient } from '@sonex/sdk-server';

const client = new SonexClient({
  api_key: 'sonex_sk_abc123...',
  auth_token: 'user-backend-token',
});

// Create a session
const session = await client.createSession();

watch()

Watch intents.json and automatically sync changes to the Sonex API.

⚠️ Important: This function must be called in your server's starting file (e.g., server.ts, app.ts, index.ts) to actively monitor file changes.

// server.ts or app.ts
import { watch } from '@sonex/sdk-server';

// Only requires API key (string)
watch('sonex_sk_your_api_key_here');

// Or from environment variable
const apiKey = process.env.SONEX_API_KEY || 'sonex_sk_your_key_here';
watch(apiKey);

Features:

• Automatically detects file changes
• Debounces rapid changes
• Validates JSON before uploading
• Initial sync on startup
• Only requires API key - no auth_token needed

createSession()

Standalone function to create a session without instantiating a client.

import { createSession } from '@sonex/sdk-server';

const session = await createSession({
  api_key: 'sonex_sk_...',
  auth_token: 'user-token',
});

How It Works

This SDK is a lightweight HTTP client that communicates with your Sonex API server:

1. Session Creation - Makes HTTP calls to POST /api/session
2. Intent File Sync - Watches intents.json and uploads via POST /api/intentFile

Requirements

• Node.js >= 18.0.0
• Sonex API Key - Get from your Sonex dashboard
• Internet Connection - Connects to your Sonex API server

TypeScript Support

Full TypeScript definitions are included. No additional @types package needed.

import type { 
  SessionResponse, 
  SonexClientConfig,
  IntentWatchConfig 
} from '@sonex/sdk-server';

Complete Example

Here's a complete example showing how to use the "watch" import in your server's starting file:

// server.ts or app.ts
import express from 'express';
import { watch } from '@sonex/sdk-server';

const app = express();

// Your API key (from environment or config)
const apiKey = process.env.SONEX_API_KEY || 'sonex_sk_your_key_here';

// Start watching intent file - MUST be in starting file
// Monitors intents.json and auto-syncs changes to Sonex API
watch(apiKey);

// Your server routes...
app.get('/api/health', (req, res) => {
  res.json({ status: 'ok' });
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

Key Points:

• watch() only needs the API key (string)
• Must be called in your server's main file to detect changes

License

MIT