Invoicing SDK

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

Installation

``bash
npm install invoicing-sdk
`

Quick Start

`typescript
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: "user@example.com",
});

const invoice = await sdk.createInvoice({
orderId: "order-123",
invoiceNumber: "INV-2025-001",
createdBy: "user@example.com",
});
`

API Reference

$3

#### 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 - 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 - Dependencies to validate

Throws: Error with details about missing dependencies

$3

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

$3

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

$3

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

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

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

$3

The SDK functions may throw domain-specific errors:

`typescript
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