invoicing-sdk/README.md

Invoice SDK entry package for getting started quickly, including domain and application layers

# 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

### 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:

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

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