npm package: @rightnow/sdk
Description: TypeScript SDK for RightNow AI — Arabic-first AI inference API
Author: RightNow AI
Latest version: 0.2.3

# rightnow

TypeScript / JavaScript SDK for [RightNow AI](https://rightnowai.co) — Arabic-first AI inference API.

- Chat completions (streaming + non-streaming)
- Embeddings
- Speech-to-text (Whisper)
- Text-to-speech
- Dialect detection
- Document processing (summarize, translate, extract, diacritize)

## Installation

```bash
npm install @rightnow/sdk
```

Requires **Node.js 18+** (uses native `fetch`).

## Quick Start

```typescript
import RightNow from '@rightnow/sdk';

const client = new RightNow({ apiKey: 'rn-...' });

// Chat
const response = await client.chat.completions.create({
  model: 'falcon-h1-arabic-7b',
  messages: [{ role: 'user', content: 'مرحبا' }],
});
console.log(response.choices[0].message.content);
```

## Streaming

```typescript
const stream = await client.chat.completions.create({
  model: 'falcon-h1-arabic-7b',
  messages: [{ role: 'user', content: 'اكتب قصة قصيرة' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}
```

## Embeddings

```typescript
const result = await client.embeddings.create({
  model: 'bge-m3-arabic',
  input: 'مرحبا بالعالم',
});
console.log(result.data[0].embedding.length); // 1024
```

## Audio

```typescript
import fs from 'fs';

// Speech-to-text
const transcription = await client.audio.transcriptions.create({
  file: fs.readFileSync('audio.wav'),
  model: 'whisper-v3-arabic',
});
console.log(transcription.text);

// Text-to-speech
const audio = await client.audio.speech.create({
  input: 'مرحبا بك',
  model: 'chatterbox-arabic',
});
fs.writeFileSync('output.mp3', Buffer.from(audio));
```

## Documents

```typescript
// Summarize
const summary = await client.documents.summarize({ text: '...' });

// Translate
const translated = await client.documents.translate({
  text: 'مرحبا',
  target_language: 'en',
});

// Extract entities
const entities = await client.documents.extract({
  text: 'أحمد يعمل في شركة أبل في الرياض',
  entities: ['person', 'organization', 'location'],
});

// Diacritize
const diacritized = await client.documents.diacritize({ text: 'كتب' });
```

## Dialect Detection

```typescript
const result = await client.dialects.detect({
  text: 'السلام عليكم ورحمة الله',
});
console.log(result.primary_dialect); // "MSA"
```

## Models

```typescript
const models = await client.models.list();
for (const model of models.data) {
  console.log(model.id);
}
```

## Configuration

```typescript
const client = new RightNow({
  apiKey: 'rn-...',               // or set RIGHTNOW_API_KEY env var
  baseURL: 'https://...',         // optional, defaults to production
  timeout: 300_000,               // optional, 5 min default
  maxRetries: 2,                  // optional
});
```

## Error Handling

```typescript
import { RightNowError, AuthenticationError, RateLimitError } from '@rightnow/sdk';

try {
  await client.chat.completions.create({ ... });
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (err instanceof RateLimitError) {
    console.error('Rate limited, retry later');
  } else if (err instanceof RightNowError) {
    console.error(err.status, err.message);
  }
}
```

## Available Models

| Model ID | Type | Description |
|----------|------|-------------|
| `falcon-h1-arabic-7b` | Chat | Best price/quality (default) |
| `falcon-h1-arabic-34b` | Chat | Complex reasoning |
| `jais-2-8b` | Chat | Strong dialect understanding |
| `allam-7b` | Chat | Saudi Arabic, MSA |
| `bge-m3-arabic` | Embeddings | 1024-dim, 8192 context |
| `whisper-v3-arabic` | STT | Arabic speech recognition |
| `chatterbox-arabic` | TTS | Arabic text-to-speech |

## License

MIT