@invoicing-sdk/application/README.md

Application layer for the invoicing system including use cases, ports, and application services

# Invoicing SDK: Application Layer

Application layer for the invoicing system, containing use cases, ports, and application services.

## Overview

This package implements the application layer of the invoicing system following Domain-Driven Design (DDD) principles. It contains:

- **Use Cases**: Business workflows and application services
- **Ports**: Interface definitions for external dependencies
- **Commands and Queries**: Input/output contracts for use cases
- **Event Bus**: Interface and helpers to transport domain and application events

## Installation

```bash
npm install @invoicing-sdk/application
```

## Event Bus

The application layer provides a **type-safe Event Bus** for publishing and subscribing to domain events. This allows you to decouple event producers and consumers, and ensures compile-time safety for event types and handlers.

### Features

- **Type-safe**: Event types and handlers are strictly typed, reducing runtime errors.
- **Publish/Subscribe**: Publish domain events and subscribe to specific event types.
- **Pluggable**: Works with in-memory, RabbitMQ, Kafka, or custom event bus implementations.

### Usage Example

```typescript
import { type EventBus } from "@invoicing-sdk/application";
import { type InvoiceCreatedEvent } from "@invoicing-sdk/domain";

// Subscribe to an event
eventBus.subscribe<InvoiceCreatedEvent>(
  "InvoiceCreatedEvent", // <- this is fully type-safe - this name is the exact name as the event type
  async (event) => {
    // handle event
  }
);
```

Events are published by either the [`domain layer`](../domain) or by the application layer itself. The event bus is targeting Domain Events, but it will be targeting more dedicated application events in future versions.

### Available Domain Events

The following domain events are currently available (see [`@invoicing-sdk/domain`](../domain/README.md)):

- [`InvoiceCreatedEvent`](../domain/src/events/InvoiceEvents.ts): Emitted when a new invoice is created.
- [`InvoiceRequested`](../domain/src/events/InvoiceEvents.ts): Emitted when an invoice is requested for an order.
- [`InvoicePdfGeneratedEvent`](../domain/src/events/InvoiceEvents.ts): Emitted when a PDF for an invoice is generated.
- [`InvoiceValidationFailedEvent`](../domain/src/events/InvoiceEvents.ts): Emitted when invoice validation fails.
- [`DomainEvent`](../domain/src/types/shared.ts): The base interface for all domain events.

> **Note:** For more details and future events, see the [domain events directory](../domain/src/events/).

---

## Usage

```typescript
import {
  makeCreateInvoice,
  makeGetInvoice,
  makeListInvoices,
  makeRequestInvoice,
  type InvoiceRepository,
  type OrderRepository,
} from "@invoicing-sdk/application";

// Create use case instances with your repository implementations
const createInvoice = makeCreateInvoice({
  invoiceRepository: yourInvoiceRepository,
  orderRepository: yourOrderRepository,
  invoiceNumberValidator: yourValidator,
  pdfRenderer: yourPdfRenderer,
  germanLegalInfo: yourLegalInfo,
});

// Use the use case
const result = await createInvoice({
  orderId: "order-123",
  invoiceNumber: "INV-2024-001",
});
```

## Dependencies

- `@invoicing-sdk/domain`: Core domain logic and entities

## Architecture

This package follows the hexagonal architecture pattern where:

- **Use Cases** contain the application logic
- **Ports** define interfaces for external dependencies
- **Commands/Queries** define the input/output contracts

The application layer depends on the domain layer but is independent of infrastructure concerns.

## Development

```bash
# Build the package
npm run build

# Run tests
npm run test

# Watch mode for development
npm run dev
```