124 lines
2.8 KiB
Markdown
124 lines
2.8 KiB
Markdown
# Caballo Client
|
|
|
|
Type-safe Deno/Node.js client for validating e-Invoices against EU standards using the Caballo API.
|
|
|
|
## Table of Contents
|
|
- [Description](#description)
|
|
- [Key Features](#key-features)
|
|
- [Installation](#installation)
|
|
- [Node.js](#nodejs)
|
|
- [Usage](#usage)
|
|
- [API Reference](#api-reference)
|
|
- [CaballoClient](#caballoclient)
|
|
- [Configuration](#configuration)
|
|
- [Methods](#methods)
|
|
- [Types](#types)
|
|
- [Examples](#examples)
|
|
- [Development](#development)
|
|
- [License](#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
|
|
```bash
|
|
npm install caballo-client
|
|
```
|
|
|
|
## Usage
|
|
```ts
|
|
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
|
|
```ts
|
|
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
|
|
|
|
```ts
|
|
type FileContent = Uint8Array | Blob | File;
|
|
|
|
interface ValidationResult {
|
|
valid: boolean;
|
|
conformanceLevel?: string;
|
|
structureErrors?: string[];
|
|
pdfErrors?: string[];
|
|
}
|
|
```
|
|
|
|
## Examples
|
|
See the [examples](./examples/) directory for more usage examples.
|
|
|
|
## Development
|
|
```bash
|
|
# 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](./LICENSE)
|
|
|