npm package: @normaai/sdk
Description: SDK JavaScript/TypeScript per NormaAI — Normativa italiana via API
Author: NormaAI
Latest version: 1.0.0

# @normaai/sdk

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

> Query Italian laws, regulations, and legal precedents from your code.

NormaAI provides a comprehensive, AI-powered knowledge base covering Italian legislation across five professional verticals. This SDK gives you type-safe access to the full NormaAI API from any JavaScript or TypeScript project.

## Installation

```bash
npm install @normaai/sdk
```

## Quickstart

```typescript
import { NormaAI } from "@normaai/sdk";

const client = new NormaAI({ apiKey: "nai_your_api_key" });

const result = await client.query(
  "Quali sono i termini per il licenziamento per giusta causa?",
  "lavoro"
);

console.log(result.answer);
console.log(result.sources);
```

## API Reference

### `new NormaAI(options)`

Create a new client instance.

| Option    | Type     | Required | Description                          |
|-----------|----------|----------|--------------------------------------|
| `apiKey`  | `string` | Yes      | Your NormaAI API key (`nai_...`)     |
| `baseUrl` | `string` | No       | Custom API base URL (for self-hosted)|

### `client.query(question, verticalId)`

Send a natural-language question to NormaAI and receive an AI-generated answer grounded in Italian legal sources.

```typescript
const result = await client.query(
  "Come si calcola il TFR?",
  "commercialista"
);
```

**Parameters:**

| Name         | Type     | Required | Description                              |
|--------------|----------|----------|------------------------------------------|
| `question`   | `string` | Yes      | Natural-language question in Italian      |
| `verticalId` | `string` | Yes      | One of the available vertical identifiers |

**Returns:** `Promise<QueryResult>`

```typescript
interface QueryResult {
  answer: string;
  sources: Source[];
  tokens_used: number;
  vertical_id: string;
  query_id: string;
}

interface Source {
  title: string;
  url: string | null;
  content: string;
  similarity: number;
}
```

### `client.verticals()`

List all available verticals.

```typescript
const verticals = await client.verticals();
// [{ id: "lavoro", name: "Diritto del Lavoro", doc_count: 6200 }, ...]
```

**Returns:** `Promise<Vertical[]>`

### `client.sources(verticalId)`

List indexed sources for a specific vertical.

```typescript
const sources = await client.sources("avvocato");
```

**Returns:** `Promise<SourceInfo[]>`

### `client.usage()`

Retrieve your current API usage and quota.

```typescript
const usage = await client.usage();
console.log(`${usage.queries_used} / ${usage.queries_limit} queries`);
```

**Returns:** `Promise<UsageInfo>`

```typescript
interface UsageInfo {
  queries_used: number;
  queries_limit: number;
  period_start: string;
  period_end: string;
  plan: string;
}
```

## Available Verticals

| Vertical ID      | Target Professionals          | Coverage                           |
|-------------------|-------------------------------|------------------------------------|
| `lavoro`          | Labour Consultants            | Employment law, payroll, contracts |
| `commercialista`  | Chartered Accountants         | Tax, corporate, accounting         |
| `avvocato`        | Lawyers                       | Civil, criminal, procedural law    |
| `ingegnere`       | Engineers / Surveyors         | Building codes, safety, permits    |
| `finanziario`     | Financial Advisors            | MiFID II, CONSOB, banking          |

## Error Handling

All methods throw `NormaAIError` on failure.

```typescript
import { NormaAI, NormaAIError } from "@normaai/sdk";

const client = new NormaAI({ apiKey: "nai_your_api_key" });

try {
  const result = await client.query("Domanda esempio", "lavoro");
} catch (error) {
  if (error instanceof NormaAIError) {
    console.error(`API error ${error.status}: ${error.message}`);
    // error.status  — HTTP status code
    // error.code    — Machine-readable error code (e.g. "rate_limit_exceeded")
    // error.message — Human-readable description
  }
}
```

## TypeScript

Full TypeScript definitions are included. No additional `@types/` package is required.

```typescript
import type { QueryResult, Vertical, UsageInfo } from "@normaai/sdk";
```

## Documentation

Full API documentation, guides, and tutorials are available at [docs.normaai.it](https://docs.normaai.it).

## License

MIT