Invoicing SDK

The main entry point for the invoicing system, providing a convenient API for creating and managing invoices.

Installation

npm install invoicing-sdk

Quick Start

import { createInvoicingSDK } from "invoicing-sdk";

// Set up your dependencies
const dependencies = {
  invoiceRepository: myInvoiceRepository,
  orderRepository: myOrderRepository,
  invoiceNumberValidator: myValidator,
  pdfRenderer: myPdfRenderer,
  invoiceNumberGenerator: myGenerator,
  legalInfo: myLegalInfo,
  shippingRateProvider: myShippingRates,
  shippingCostPolicy: myShippingPolicy,
};

// Create the SDK
const sdk = createInvoicingSDK(dependencies);

// Use the SDK
const invoiceDraft = await sdk.requestInvoice({
  orderId: "order-123",
  requestedBy: "[email protected]",
});

const invoice = await sdk.createInvoice({
  orderId: "order-123",
  invoiceNumber: "INV-2025-001",
  createdBy: "[email protected]",
});

API Reference

Main Functions

createInvoicingSDK(dependencies)

Creates a complete SDK instance with all use cases.

Parameters:

• dependencies: InvoicingSDKDependencies - All required dependencies

Returns: InvoicingSDK - Complete SDK with all use cases

createInvoicingSDKSafe(dependencies)

Safe version that validates dependencies before creating the SDK.

Parameters:

• dependencies: Partial<InvoicingSDKDependencies> - Dependencies to validate

Returns: InvoicingSDK - Complete SDK instance

Throws: Error if any required dependency is missing

validateSDKDependencies(dependencies)

Validates that all required dependencies are provided.

Parameters:

• dependencies: Partial<InvoicingSDKDependencies> - Dependencies to validate

Throws: Error with details about missing dependencies

Use Cases

The SDK provides the following use cases:

• requestInvoice - Create an invoice draft from an order
• createInvoice - Create and finalize an invoice with PDF generation
• listInvoices - List invoices with filtering and pagination
• getInvoice - Retrieve a single invoice by ID, number, or order ID

Types

The SDK re-exports all key types from the domain and application layers:

• Domain entities: Invoice, Money, CustomerInfo, etc.
• Value objects: OrderItem, InvoiceFinancials, ShippingCost
• Commands: RequestInvoiceCommand, CreateInvoiceCommand
• Queries: GetInvoiceQuery, ListInvoicesQuery
• Results: RequestInvoiceResult, CreateInvoiceResult, etc.
• Repositories: InvoiceRepository, OrderRepository

Dependencies

The SDK requires the following dependencies:

• invoiceRepository: InvoiceRepository - For invoice persistence
• orderRepository: OrderRepository - For order data access
• invoiceNumberValidator: InvoiceNumberValidator - For invoice number validation
• pdfRenderer: PDFRenderer - For PDF generation
• invoiceNumberGenerator: InvoiceNumberGenerator - For generating invoice numbers
• legalInfo: GermanLegalInfo - Legal information for invoices
• shippingRateProvider: ShippingRateProvider - Shipping rate calculation
• shippingCostPolicy: ShippingCostPolicy - Shipping cost policies

Advanced Usage

Individual Use Cases

If you only need specific functionality, you can create individual use cases:

import {
  makeRequestInvoice,
  makeCreateInvoice,
  createUseCases,
} from "invoicing-sdk";

const useCases = createUseCases({
  requestInvoice: makeRequestInvoice(requestDependencies),
  createInvoice: makeCreateInvoice(createDependencies),
});

Error Handling

The SDK functions may throw domain-specific errors:

import {
  OrderNotFoundError,
  InvoiceAlreadyExistsError,
  InvalidInvoiceNumberError,
} from "invoicing-sdk";

try {
  const invoice = await sdk.createInvoice(command);
} catch (error) {
  if (error instanceof OrderNotFoundError) {
    // Handle order not found
  } else if (error instanceof InvoiceAlreadyExistsError) {
    // Handle duplicate invoice
  }
}

License

MIT