npm package: @sonex/sdk-server
Description: Sonex SDK - Intent-based API routing
Author: Bharath
Latest version: 0.1.0

# @sonex/sdk-server

[![npm version](https://img.shields.io/npm/v/@sonex/sdk-server.svg)](https://www.npmjs.com/package/@sonex/sdk-server)
[![npm downloads](https://img.shields.io/npm/dm/@sonex/sdk-server.svg)](https://www.npmjs.com/package/@sonex/sdk-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

## Installation

```bash
npm install @sonex/sdk-server
```

## Quick Start

```typescript
// 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.

```typescript
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.

```typescript
// 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.

```typescript
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.

```typescript
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:

```typescript
// 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