@normaai/sdk

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

npm install @normaai/sdk

Quickstart

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.

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>

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.

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.

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

Returns: Promise<SourceInfo[]>

client.usage()

Retrieve your current API usage and quota.

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

Returns: Promise<UsageInfo>

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.

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.

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

Documentation

Full API documentation, guides, and tutorials are available at docs.normaai.it.

License

MIT