JavaScript SDK

import { VasBox } from '@vasbox/sdk';

// Initialize with API key
const vasbox = new VasBox(process.env.VASBOX_API_KEY);

// Or with additional options
const vasbox = new VasBox(process.env.VASBOX_API_KEY, {
    environment: 'sandbox', // or 'production'
    timeout: 30000,
    retry: {
        enabled: true,
        maxAttempts: 3,
    },
});

import { VasBox } from '@vasbox/sdk';

const vasbox = new VasBox(process.env.VASBOX_API_KEY);

// Create an invoice
const invoice = await vasbox.invoices.create({
    customer_id: 'cust_123',
    currency: 'USD',
    items: [
        {
            description: 'Software License',
            quantity: 1,
            unit_price: 299.00,
            tax_code: 'STD',
        },
    ],
    notes: 'Thank you for your business!',
});

console.log('Invoice ID:', invoice.id);
console.log('Invoice Number:', invoice.number);

// List invoices with filters
const invoices = await vasbox.invoices.list({
    status: 'draft',
    from: '2024-01-01',
    per_page: 50,
});

for (const inv of invoices.data) {
    console.log(`${inv.number}: ${inv.total}`);
}

// Get a specific invoice
const invoice = await vasbox.invoices.get('inv_abc123');

// Submit to ZIMRA
const result = await vasbox.invoices.submit('inv_abc123');
console.log('Fiscal Code:', result.fiscal_code);

import { VasBox } from '@vasbox/sdk';

const vasbox = new VasBox(process.env.VASBOX_API_KEY);

// Auto-pagination with async iterators
for await (const invoice of vasbox.invoices.listAll({ status: 'submitted' })) {
    console.log(invoice.number);
}

// Or collect all results
const allInvoices = [];
for await (const invoice of vasbox.invoices.listAll()) {
    allInvoices.push(invoice);
}

import { VasBox, Invoice, Customer, CreateInvoiceInput } from '@vasbox/sdk';

const vasbox = new VasBox(process.env.VASBOX_API_KEY!)

// Fully typed invoice creation
const invoiceData: CreateInvoiceInput = {
    customer_id: 'cust_123',
    currency: 'USD',
    items: [
        {
            description: 'Software License',
            quantity: 1,
            unit_price: 299.00,
            tax_code: 'STD',
        },
    ],
};

const invoice: Invoice = await vasbox.invoices.create(invoiceData);

// Type inference works automatically
const customers = await vasbox.customers.list({ search: 'acme' });
// customers.data is Customer[]

// Generic types for custom metadata
interface InvoiceMetadata {
    string;
    string;
}

const invoiceWithMeta = await vasbox.invoices.create<InvoiceMetadata>({
    customer_id: 'cust_123',
    items: [...],
    metadata: {
        order_id: 'ORD-123',
        department: 'Sales',
    },
});

import {
    VasBox,
    ValidationError,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
    ZimraError,
} from '@vasbox/sdk';

const vasbox = new VasBox(process.env.VASBOX_API_KEY);

try {
    const invoice = await vasbox.invoices.create({...});
} catch (error) {
    if (error instanceof ValidationError) {
        // Validation failed
        console.log('Validation errors:');
        for (const [field, messages] of Object.entries(error.details)) {
            console.log(`  ${field}: ${messages.join(', ')}`);
        }
    } else if (error instanceof AuthenticationError) {
        // Invalid API key
        console.log('Authentication failed:', error.message);
    } else if (error instanceof NotFoundError) {
        // Resource not found
        console.log('Not found:', error.message);
    } else if (error instanceof RateLimitError) {
        // Rate limit exceeded
        console.log('Rate limited. Retry after:', error.retryAfter, 'seconds');
        // Automatic retry is recommended
        await new Promise(r => setTimeout(r, error.retryAfter * 1000));
    } else if (error instanceof ZimraError) {
        // ZIMRA submission failed
        console.log('ZIMRA error:', error.zimraCode);
        console.log('Details:', error.zimraMessage);
    } else {
        // Other errors
        console.error('Error:', error.message);
    }
}