Caballo Client

Type-safe Deno/Node.js client for validating e-Invoices against EU standards using the Caballo API.

Table of Contents

• Description
  • Key Features
• Installation
  • Node.js
• Usage
• API Reference
  • CaballoClient
    • Configuration
    • Methods
    • Types
• Examples
• Development
• License

Description

Caballo Client is a modern TypeScript library for validating electronic invoices (e-Invoices) against European Union standards. It provides a simple and type-safe interface to interact with the Caballo validation API, supporting both XML and PDF e-Invoice formats.

Key Features

• Full TypeScript support with comprehensive types
• Zero dependencies, using standard Web APIs
• Support for both Deno and Node.js (ESM, Node 18+)
• Built-in validation for Factur-X/ZUGFeRD formats
• Efficient file handling with support for Uint8Array, Blob, and File inputs
• Clear error handling with detailed validation results

Installation

Node.js

npm install caballo-client

Usage

import { CaballoClient } from "caballo-client";

// Initialize client
const client = new CaballoClient({
  baseUrl: "https://api.example.com",
  timeout: 5000, // optional
});

// Validate XML
const xmlContent = await Deno.readFile("invoice.xml");
try {
  const result = await client.validateXml(xmlContent);
  console.log("XML Validation result:", result);
} catch (error) {
  console.error("Validation failed:", error.message);
}

// Validate PDF
const pdfContent = await Deno.readFile("invoice.pdf");
try {
  const result = await client.validatePdf(pdfContent);
  console.log("PDF Validation result:", result);
} catch (error) {
  console.error("Validation failed:", error.message);
}

API Reference

Caballo Client

Configuration

interface ClientConfig {
  baseUrl: string;    // Required: Base URL of the Caballo API
  timeout?: number;   // Optional: Timeout in milliseconds (default: 30000)
}

Methods

validateXml(content: FileContent): Promise<ValidationResult>

Validates an XML e-Invoice file.

validatePdf(content: FileContent): Promise<ValidationResult>

Validates a PDF e-Invoice file including its embedded XML and metadata.

Types

type FileContent = Uint8Array | Blob | File;

interface ValidationResult {
  valid: boolean;
  conformanceLevel?: string;
  structureErrors?: string[];
  pdfErrors?: string[];
}

Examples

See the examples directory for more usage examples.

Development

# Run tests
deno task test

# Format code
deno task fmt

# Run linter
deno task lint

# Build npm package
deno task build:npm

License

MIT License