@spaceinvoices/js-sdk

Official JavaScript/TypeScript SDK for the Space Invoices API.

Installation

npm install @spaceinvoices/js-sdk
# or
bun add @spaceinvoices/js-sdk

Usage

Lean SDK (Recommended)

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices({ accessToken: 'your-api-key' });

// List invoices for an entity
const invoices = await sdk.invoices.list({ entity_id: 'ent_123' });

// Create an invoice. SDK fields match the REST API's snake_case contract.
const invoice = await sdk.invoices.create(
  {
    is_draft: false,
    currency_code: 'EUR',
    date: '2024-01-15',
    items: [{ name: 'Service', quantity: 1, gross_price: 100, taxes: [] }]
  },
  {
    entity_id: 'ent_123',
    request_id: 'order_123:create-invoice'
  }
);

Individual API Modules

import { initSDK, invoices, customers } from '@spaceinvoices/js-sdk/sdk';

// Initialize once at app startup
initSDK({ accessToken: 'your-api-key' });

// Use individual modules anywhere
const result = await invoices.list();

Configuration Options

const sdk = new SpaceInvoices({
  accessToken: 'your-api-key',
  // Optional: custom API base URL
  basePath: 'https://eu.spaceinvoices.com',
  // Optional: callback for 401 responses
  onUnauthorized: (response) => {
    console.log('Token expired, refreshing...');
  }
});

Dynamic Token

const sdk = new SpaceInvoices({
  accessToken: async () => {
    // Fetch token from your auth system
    return await getAccessToken();
  }
});

Features

• Full TypeScript Support - Complete type definitions for all API methods
• Lean SDK Entry - Import from /sdk to exclude optional Zod schemas
• ESM & CJS - Works in Node.js, browsers, and modern bundlers
• Zod Schemas - Optional Zod schemas for form validation

Version 4

Version 4 removes deprecated compatibility type aliases and legacy generated client declarations. Use canonical generated types such as CreateInvoice, CreateCustomerBody, and InvoiceList. Request and response fields retain the API's snake_case names; the SDK does not expose camelCase field variants.

Upload and file metadata responses use secure_url and public_id. The former secureUrl and publicId fields remain as deprecated response aliases for API compatibility; new SDK integrations should use only the snake_case fields.

Zod Schemas

For form validation, import Zod schemas from the package root. This loads the complete generated schema catalog; applications that do not need runtime validation should use the lean /sdk entry shown above.

import { zod } from '@spaceinvoices/js-sdk';

// Validate invoice creation data
const result = zod.invoices.CreateInvoiceBody.safeParse(formData);
if (!result.success) {
  console.log(result.error.issues);
}

// Available schemas follow PascalCase naming:
// - zod.invoices.CreateInvoiceBody
// - zod.customers.CreateCustomerBody
// - zod.items.CreateItemBody
// - etc.

Documentation

• API Documentation

Development

# Generate SDK (deterministic by default from apps/api/openapi.json)
bun run generate

# Or generate from a live API explicitly
OPENAPI_TARGET=http://localhost:3000/openapi.json bun run generate

# If OpenAPI examples changed, refresh docs artifacts too
cd ../../apps/docs && bun run generate

# Build for distribution
bun run build

License

MIT