npm package: @serovaai/sdk
Description: Official Serova SDK for Node.js - API client and AI agent tools
Author: Serova AI
Latest version: 0.2.0

# @serovaai/sdk

Official Serova SDK for Node.js - API client and AI agent tools.

## Installation

```bash
npm install @serovaai/sdk
# or
pnpm add @serovaai/sdk
# or
yarn add @serovaai/sdk
```

## Quick Start

```typescript
import { SerovaClient } from '@serovaai/sdk';

const client = new SerovaClient({
  apiKey: process.env.SEROVA_API_KEY!,
  defaultContextId: 'your-community-context-id',
});

// Search for recommendations
const results = await client.awareness.searchRecommendations({
  query: 'plumbers',
  limit: 10,
});

console.log(results.recommendations);
```

## Using with OpenAI Agents SDK

The SDK includes pre-built tool definitions for OpenAI's function calling:

```typescript
import { SerovaClient, allTools, createToolExecutor } from '@serovaai/sdk';
import OpenAI from 'openai';

const client = new SerovaClient({
  apiKey: process.env.SEROVA_API_KEY!,
  defaultContextId: process.env.SEROVA_CONTEXT_ID!,
});

const openai = new OpenAI();
const executor = createToolExecutor(client);

// Register Serova tools with your agent
const tools = allTools.map((t) => ({ type: 'function' as const, function: t }));

// Create a chat completion with tools
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Can you recommend a plumber?' }],
  tools,
});

// Handle tool calls
for (const toolCall of response.choices[0].message.tool_calls ?? []) {
  const result = await executor(
    toolCall.function.name,
    JSON.parse(toolCall.function.arguments)
  );
  console.log(result);
}
```

## Available Tools

| Tool Name | Description |
|-----------|-------------|
| `serova_get_recommendations` | Search for service recommendations |
| `serova_get_sentiment_stats` | Get community sentiment statistics |
| `serova_get_categories` | List available recommendation categories |

## API Reference

### `SerovaClient`

Main client for interacting with the Serova API.

```typescript
const client = new SerovaClient({
  apiKey: string;           // Required: Your API key
  baseUrl?: string;         // Optional: API base URL (default: https://api.serova.ai)
  defaultContextId?: string; // Optional: Default context for queries
  timeout?: number;         // Optional: Request timeout in ms (default: 30000)
});
```

### Awareness API

#### `client.awareness.searchRecommendations(query)`

Search for recommendations by query string.

```typescript
const results = await client.awareness.searchRecommendations({
  query: 'italian restaurants',
  limit: 10,
});
```

#### `client.awareness.getRecommendations(query)`

Get paginated recommendations with filters.

```typescript
const results = await client.awareness.getRecommendations({
  category: 'home services',
  sentiment: 'positive',
  limit: 20,
  offset: 0,
});
```

#### `client.awareness.getCategories()`

Get available recommendation categories.

```typescript
const categories = await client.awareness.getCategories();
// ['home services', 'food', 'healthcare', ...]
```

#### `client.awareness.getSentimentStats(query)`

Get sentiment statistics for a context.

```typescript
const stats = await client.awareness.getSentimentStats({
  startDate: '2024-01-01',
  endDate: '2024-12-31',
});
// { positive: 150, neutral: 80, negative: 20, total: 250 }
```

## License

MIT