`@withpotter/invoice` — module reference

HTTP routes this module mounts, plus its internal use-cases, entities, and repositories. The exhaustive request/response contract is the engine’s OpenAPI document at /docs; the layered structure below follows the package internal architecture.

HTTP routes

Invoices `/invoices`

Method	Path	Auth	Description
`GET`	`/invoices`	Yes	List invoices with filters
`GET`	`/invoices/:id`	Yes	Get invoice by ID
`GET`	`/invoices/:id/pdf`	Yes	Download invoice as PDF
`GET`	`/invoices/number/:invoiceNumber`	—	Get invoice by number (public or dashboard)
`GET`	`/invoices/stats`	Yes	Get invoice statistics
`POST`	`/invoices`	Yes	Create a new invoice
`POST`	`/invoices/:id/cancel`	Yes	Cancel an invoice
`POST`	`/invoices/:id/pay`	—	Initialize online payment for an invoice (public)
`POST`	`/invoices/:id/payment`	Yes	Record a manual payment against an invoice
`POST`	`/invoices/:id/send`	Yes	Send invoice to customer via email
`POST`	`/invoices/number/:invoiceNumber/view`	—	Record that a customer viewed this invoice (public)
`PUT`	`/invoices/:id`	Yes	Update a draft invoice

Internals

Use-cases

Application operations. Each is a single-purpose class with one execute() method.

Use-case	Signature
`CancelInvoiceUseCase`	`execute(tenantId: string, id: string): Promise<InvoiceResponseDto>`
`CreateInvoiceUseCase`	`execute(tenantId: string, dto: CreateInvoiceDto): Promise<InvoiceResponseDto>`
`GenerateInvoicePdfUseCase`	`execute(tenantId: string, id: string): Promise<Buffer>`
`GetInvoiceByNumberUseCase`	`execute(tenantId: string, invoiceNumber: string): Promise<InvoiceResponseDto>`
`GetInvoiceStatsUseCase`	`execute(tenantId: string): Promise<InvoiceStatsResponseDto>`
`GetInvoiceUseCase`	`execute(tenantId: string, id: string): Promise<InvoiceResponseDto>`
`InitializeInvoicePaymentUseCase`	`execute(tenantId: string, input: InitializeInvoicePaymentInput): Promise<InitializeInvoicePaymentOutput>`
`ListInvoicesUseCase`	`execute(tenantId: string, query: InvoiceQueryDto): Promise<PaginatedInvoicesResponseDto>`
`MarkInvoiceViewedUseCase`	`execute(tenantId: string, invoiceNumber: string): Promise<InvoiceResponseDto>`
`RecordPaymentUseCase`	`execute(tenantId: string, id: string, dto: RecordPaymentDto): Promise<InvoiceResponseDto>`
`SendInvoiceUseCase`	`execute(tenantId: string, id: string): Promise<InvoiceResponseDto>`
`UpdateInvoiceUseCase`	`execute(tenantId: string, id: string, dto: UpdateInvoiceDto): Promise<InvoiceResponseDto>`

Entities

Sequelize models owned by this module.

`Invoice` — table `invoices`

Field	Type
`id`	`string`
`tenantId`	`string`
`tenant`	`Tenant`
`memberId`	`string \| null`
`member`	`Member`
`invoiceNumber`	`string`
`status`	`InvoiceStatus`
`customerEmail`	`string`
`customerName`	`string \| null`
`customerPhone`	`string \| null`
`customerAddress`	`InvoiceAddress \| null`
`subtotal`	`number`
`discountTotal`	`number`
`taxTotal`	`number`
`total`	`number`
`amountPaid`	`number`
`amountDue`	`number`
`currency`	`string`
`issueDate`	`string`
`dueDate`	`string`
`paidAt`	`Date \| null`
`sentAt`	`Date \| null`
`viewedAt`	`Date \| null`
`viewCount`	`number`
`cancelledAt`	`Date \| null`
`paymentReference`	`string \| null`
`paymentMethod`	`string \| null`
`paymentLink`	`string \| null`
`note`	`string \| null`
`internalNote`	`string \| null`
`terms`	`string \| null`
`metadata`	`Record<string, unknown> \| null`
`relatedType`	`string \| null`
`relatedId`	`string \| null`
`createdAt`	`Date`
`updatedAt`	`Date`
`items`	`InvoiceItem[]`
`id`	`string`
`invoiceId`	`string`
`invoice`	`Invoice`
`contentId`	`string \| null`
`title`	`string`
`description`	`string \| null`
`quantity`	`number`
`unitPrice`	`number`
`discount`	`number`
`tax`	`number`
`total`	`number`
`position`	`number`
`metadata`	`Record<string, unknown> \| null`
`createdAt`	`Date`
`updatedAt`	`Date`

Repositories

Data-access classes wrapping the entities.

`InvoiceRepository`

findById · findByInvoiceNumber · findByPaymentReference · findWithFilters · findByMember · create · createWithItems · update · updateStatus · markViewed · recordPayment · addItem · updateItem · removeItem · replaceItems · recalculateTotals · generateInvoiceNumber · countByStatus · getPaidRevenueInRange · markOverdueInvoices

Ports

DI contracts other modules bind adapters to.

InvoiceMailerTenantConfig, SendInvoiceEmailOptions, InvoiceMailerPort — token INVOICE_MAILER

Generated from the module’s source. Routes are relative to the engine root (default http://localhost:3001). For full request/response schemas use the live OpenAPI document.

invite-code location

@withpotter/invoice — module reference