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

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

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

• InvoiceCreatedEvent: Emitted when a new invoice is created.
• InvoiceRequested: Emitted when an invoice is requested for an order.
• InvoicePdfGeneratedEvent: Emitted when a PDF for an invoice is generated.
• InvoiceValidationFailedEvent: Emitted when invoice validation fails.
• DomainEvent: The base interface for all domain events.

Note: For more details and future events, see the domain events directory.

Usage

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

# Build the package
npm run build

# Run tests
npm run test

# Watch mode for development
npm run dev