Imperio Utils — Node.js SDK

Official Node.js / TypeScript SDK for Imperio Utilities — the developer tools platform for B2B automation.

Zero dependencies. Uses native fetch (Node 18+).

Installation

npm install imperio-utils

Quick Start

Get your API key at imperioutils.com/enterprise.

import { ImperioClient } from 'imperio-utils';

const client = new ImperioClient({ apiKey: 'empire_live_your_key_here' });

Features

Secret Scanner — CI/CD ready

const result = await client.scanSecrets(sourceCode, 'app.ts');

console.log(result.risk_score);  // 'CLEAN' | 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL'
console.log(result.total);       // number of findings

for (const finding of result.findings) {
  console.log(finding.severity, finding.type, finding.line, finding.masked_value);
}

Values are always masked — safe to log to GitHub Actions or CI.

Italian Validators (batch, up to 500)

const result = await client.validateItalianBatch([
  { type: 'cf',   value: 'RSSMRA85T10A562S' },
  { type: 'piva', value: '12345678901' },
  { type: 'iban', value: 'IT60X0542811101000000123456' },
  { type: 'cap',  value: '00100' },
]);

console.log(`${result.valid_count} / ${result.total} valid`);

FatturaPA Parser

const xml = fs.readFileSync('fattura.xml', 'utf8');
const result = await client.parseFatturaPA(xml);

console.log(result.cedente_prestatore);      // seller
console.log(result.cessionario_committente); // buyer
result.fatture?.forEach(f => console.log(f));

GDPR Anonymization (batch)

const result = await client.anonymizeBatch(
  ['Mario Rossi, via Roma 1, [email protected]'],
  'standard' // or 'aggressive'
);
console.log(result.results[0].anonymized);
// '[NOME] [NOME], [INDIRIZZO], [EMAIL]'

AI Tools

// Extract structured data from invoice text
const invoice = await client.extractInvoiceAI(invoiceText, 'it');

// Analyze a contract
const analysis = await client.analyzeContract(contractText, 'it');

// Summarize
const summary = await client.summarize(text, 'bullets'); // 'brief' | 'detailed' | 'bullets'

// Compare PDFs
const diff = await client.comparePdfs(file1Blob, file2Blob);

GitHub Actions

- name: Scan for secrets
  run: |
    node -e "
    const { ImperioClient } = require('imperio-utils');
    const fs = require('fs');
    const client = new ImperioClient({ apiKey: process.env.IMPERIO_API_KEY });
    client.scanSecrets(fs.readFileSync('app.js', 'utf8'))
      .then(r => { if (r.critical > 0) process.exit(1); });
    "
  env:
    IMPERIO_API_KEY: ${{ secrets.IMPERIO_API_KEY }}

Error Handling

import { ImperioClient, AuthError, CreditError, RateLimitError } from 'imperio-utils';

try {
  const result = await client.scanSecrets(code);
} catch (e) {
  if (e instanceof AuthError)      console.error('Invalid API key');
  if (e instanceof CreditError)    console.error('Top up credits');
  if (e instanceof RateLimitError) console.error('Slow down');
}

TypeScript

Full type definitions included. No @types/ package needed.

import type { ScanResult, Finding, BatchValidateItem } from 'imperio-utils';

Links

• Documentation
• Get API Key
• GitHub
• Issues