npm package: @nimrobo/sdk-js
Description: Official Nimrobo JavaScript/TypeScript SDK for Node.js
Author: Nimrobo
Latest version: 0.1.0

# Nimrobo SDK for Node.js

Official JavaScript/TypeScript SDK for the [Nimrobo](https://nimroboai.com) API.

## Installation

```bash
npm install @nimrobo/sdk-js
```

## Quick Start

```typescript
import { NimroboClient } from '@nimrobo/sdk-js';

const client = new NimroboClient({
  apiKey: 'api_...',
});

// Get user profile
const profile = await client.user.getProfile();

// List projects
const { projects } = await client.projects.list();

// Create a project
const { project } = await client.projects.create({
  name: 'My Project',
  prompt: 'You are a helpful assistant...',
});
```

## Requirements

- Node.js >= 16.0.0

## Resources

### User

```typescript
// Get authenticated user profile
const profile = await client.user.getProfile();
```

### Projects

```typescript
// List all projects
const { projects } = await client.projects.list();

// Create a project
const { project } = await client.projects.create({
  name: 'Interview Bot',
  prompt: 'You are conducting a job interview...',
  description: 'Bot for candidate interviews',
  timeLimitMinutes: 30,
});

// Get a project
const { project } = await client.projects.get('project-id');

// Update a project
const { project } = await client.projects.update('project-id', {
  name: 'Updated Name',
  prompt: 'Updated prompt...',
});
```

### Project Links

```typescript
// List links for a project
const { links } = await client.projectLinks.list('project-id');

// Create links for a project
const { links } = await client.projectLinks.create('project-id', {
  labels: ['Candidate A', 'Candidate B'],
  expiryPreset: '1_week',
});

// Cancel a link
await client.projectLinks.cancel('link-id', 'project-id');
```

### Instant Links

```typescript
// List instant links
const { links } = await client.instantLinks.list();

// Create instant links
const { links } = await client.instantLinks.create({
  labels: ['Session 1'],
  expiryPreset: '1_day',
  prompt: 'You are a helpful assistant...',
});

// Update an instant link
await client.instantLinks.update('link-id', {
  label: 'Updated Label',
  prompt: 'Updated prompt...',
});
```

### Sessions

```typescript
// Get session status
const status = await client.sessions.getStatus({
  sessionId: 'session-id',
  type: 'project',
  projectId: 'project-id',
});

// Get session transcript
const { transcript } = await client.sessions.getTranscript({
  sessionId: 'session-id',
  type: 'project',
  projectId: 'project-id',
});

// Get session audio URL
const { audioUrl } = await client.sessions.getAudio({
  sessionId: 'session-id',
  type: 'project',
  projectId: 'project-id',
});

// Get evaluation results
const evaluation = await client.sessions.getEvaluation({
  sessionId: 'session-id',
  type: 'project',
  projectId: 'project-id',
});

// Get session summary
const summary = await client.sessions.getSummary({
  sessionId: 'session-id',
  projectId: 'project-id',
});
```

## Error Handling

The SDK throws typed errors for different failure scenarios:

```typescript
import { NimroboClient, NimroboError, NotFoundError, AuthenticationError } from '@nimrobo/sdk-js';

try {
  await client.projects.get('invalid-id');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Project not found');
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof NimroboError) {
    console.log(`API error: ${error.message} (status: ${error.status})`);
  }
}
```

### Error Types

| Error Class | Status Code | Description |
|-------------|-------------|-------------|
| `AuthenticationError` | 401 | Invalid or missing API key |
| `AuthorizationError` | 403 | Insufficient permissions |
| `NotFoundError` | 404 | Resource not found |
| `ValidationError` | 400/422 | Invalid request parameters |
| `RateLimitError` | 429 | Too many requests |
| `ServerError` | 5xx | Server-side error |
| `NetworkError` | - | Network connectivity issues |

## Types

All TypeScript types are exported from the package:

```typescript
import type {
  Project,
  ProjectLink,
  InstantLink,
  SessionStatusResponse,
  Evaluator,
  ExpiryPreset,
  LinkStatus,
} from '@nimrobo/sdk-js';
```

## Browser Usage

By default, the SDK prevents usage in browser environments to protect your API key. If you need to use it in a browser (not recommended for production), you can enable it:

```typescript
const client = new NimroboClient({
  apiKey: 'api_...',
  dangerouslyAllowBrowser: true,
});
```

**Warning:** Exposing your API key in client-side code allows anyone to use your key. For production applications, use a backend server to make API calls.

## License

Apache-2.0