integreat/docs/testing/behaviors/outgoing-invoice.md

Outgoing Invoice Behaviors

Overview

The Outgoing Invoice subsystem allows users to create and generate PDF invoices to send to customers. It provides a form-based workflow for specifying the client (sender), recipient details, invoice metadata (date, number, tax rate), and line items. Upon submission, the system calculates subtotals, applies tax, and invokes an AWS Lambda function (genpdf) to generate a downloadable PDF.

Routes & Pages

Route	Method	Handler	Purpose
GET /outgoing-invoice/new	GET	::new	Renders the new outgoing invoice form
POST /outgoing-invoice/new	POST	::new-submit	Validates form, generates PDF, shows download modal
GET /outgoing-invoice/line-item/new	GET	::new-line-item	Returns HTML for a new empty line item row (HTMX)

Behaviors

Unit Tests

• form-schema validates required fields: client, date, to, invoice-number, tax, to-address, line-items
• form-schema requires line-item description, unit-price, and quantity
• form-schema makes address street2 optional (nullable string)
• form-schema coerces line-items vector from form params
• form-schema applies strip decoder to street2 (trims whitespace, treats empty as nil)
• line-item renders a data-grid row with hidden db/id, description input, quantity money-input, unit-price money-input, and delete button
• line-item delete button uses Alpine.js to fade out and remove row after 500ms
• submit filters out line items with empty descriptions
• submit calculates line-item total as unit-price * quantity
• submit calculates subtotal as sum of all line-item totals
• submit calculates tax as subtotal * tax-rate (tax is a percentage, e.g., 10.0 = 10%)
• submit calculates total as subtotal + tax
• submit formats monetary values as $X,XXX.XX strings before sending to Lambda
• submit formats invoice date as normal-date string before sending to Lambda
• submit invokes genpdf Lambda with JSON payload
• submit extracts S3 URL from Lambda response and presents download link
• fmt-money formats nil as $0.00
• fmt-money formats large numbers with comma separators (e.g., $1,234.56)

Integration Tests

• GET /outgoing-invoice/new returns 200 with full form HTML for authenticated user
• Form includes client typeahead, invoice number input, date picker, line items grid, tax input, and recipient address fields
• Client typeahead fetches from :company-search endpoint
• Date input renders with normal-date formatted value
• Form POSTs to ::new-submit via HTMX
• POST /outgoing-invoice/new with valid data returns 200 with modal containing PDF download link
• POST /outgoing-invoice/new with invalid data returns form with validation errors
• Missing required fields (client, date, to, invoice-number) show validation errors
• Empty line items (no description) are filtered out before calculation
• GET /outgoing-invoice/line-item/new returns HTML for a new line item row
• New line item row can be appended to the line items grid via HTMX
• Multiple line items can be added and each calculates independently
• Form is wrapped with wrap-schema-decode using form-schema
• Form is wrapped with wrap-nested-form-params to handle nested form parameter keys
• Unauthenticated requests redirect to /login
• Request applies wrap-trim-client-ids and wrap-secure middleware

UI Test Behaviors (SSR)

Happy Path: Create and Generate Invoice

1. Authenticated user navigates to outgoing invoice new page
2. Page renders with breadcrumbs: Invoices > Outgoing > New
3. User selects a client from the typeahead ("From (client)")
4. User enters invoice number (e.g., "10000")
5. User selects/enters invoice date
6. User enters recipient name in "To" field
7. User fills in recipient address: street1, city, state, zip (street2 optional)
8. User adds line items: clicks "Add line", enters description, quantity, unit price
9. User adds multiple line items
10. User verifies or adjusts tax percentage (default 10.0)
11. User clicks "Generate" button
12. Server validates form, calculates totals, invokes PDF Lambda
13. Modal appears with message "Download your invoice" and link to S3 URL
14. User clicks link to download PDF

Add and Remove Line Items

1. User views new invoice form with one default empty line item
2. User clicks "Add line" button
3. HTMX fetches new line item row and appends it to the grid
4. User fills in the new line item
5. User clicks delete (X) button on a line item
6. Row fades out and removes itself via Alpine.js
7. Remaining line items retain their data

Validation Errors

1. User clicks "Generate" without filling required fields
2. Form POSTs and returns with validation error styling
3. Required fields show error indicators
4. User fills in missing fields and resubmits
5. Invoice generates successfully

Empty Line Items Handling

1. User adds multiple line items
2. User leaves some line item descriptions blank
3. User submits form
4. Server filters out empty line items
5. PDF generates with only populated line items
6. Subtotal and total reflect only populated items

Edge Cases

Form Validation

• Missing client: Typeahead shows error state; form cannot submit
• Missing date: Date input shows error state
• Missing recipient name: "To" field shows error state
• Missing invoice number: Invoice # field shows error state
• Invalid date format: Schema rejects; form redisplays with error
• Negative quantities: Money input may accept negatives; calculation handles them
• Zero unit price: Line item total is $0.00; included in subtotal
• Zero tax rate: Tax is $0.00; total equals subtotal
• Very large numbers: Monetary formatting uses commas; Lambda payload handles as string

Line Items

• All line items empty: Subtotal is 0.0, tax is 0.0, total is 0.0
• Single line item: Calculates correctly
• Many line items (50+): Grid scrolls; each item calculates independently
• Delete all line items: Grid empty; adding new row restores functionality
• Line item with only description: Filtered out (requires description + values)

PDF Generation

• Lambda invocation failure: Exception propagates; user sees error (no modal)
• Lambda returns invalid JSON: json/read-str may throw; error handling depends on catch logic
• S3 URL inaccessible: Link is presented but may 403/404 on click
• Very large invoice payload: Lambda payload size limits may apply

Permissions & Auth

• Unauthenticated user: Redirected to /login?redirect-to=/outgoing-invoice/new
• Session expired during form fill: HTMX POST returns hx-redirect to login
• User without client access: Client typeahead only shows accessible clients

Tax Calculation

• Tax as whole number (10): Treated as 10% (multiplied by 0.10)
• Tax with decimals (8.25): Treated as 8.25%
• Tax over 100%: Allowed by schema; mathematically valid but business-questionable
• Zero tax: Total equals subtotal exactly

Test Data Requirements

Users

• Authenticated user with access to at least one client
• Client with complete profile including address

Clients

• Client with :client/name and :client/address (street, city, state, zip)
• Multiple clients to test typeahead selection

Form Data

• Valid invoice number strings
• Valid dates in normal-date format
• Recipient names and addresses
• Line items with descriptions, quantities (numeric), unit prices (monetary)
• Tax rates (percentage values, e.g., 10.0 for 10%)

AWS Lambda Mock

• Mock genpdf Lambda invocation returning valid S3 URL
• Mock genpdf Lambda returning error

Dependencies

External Services

• AWS Lambda: genpdf function generates PDF from invoice data
• S3: Generated PDFs stored at data.prod.app.integreatconsult.com/<path>
• Datomic: Client lookup for typeahead, address data

Frontend Libraries

• HTMX: Form submission, line item row fetching
• Alpine.js: Line item row show/hide and removal animation
• Form cursor (auto-ap.ssr.form-cursor): Field state management, error binding

Middleware Stack

• wrap-secure: Requires authentication
• wrap-client-redirect-unauthenticated: Redirects unauthenticated users
• wrap-trim-client-ids: Trims client IDs from request
• wrap-schema-decode: Validates and decodes form data against form-schema
• wrap-nested-form-params: Parses nested form parameter structures

Related Subsystems

• Invoices: Outgoing invoices are linked from the main invoices page
• Company/Clients: Client typeahead depends on company search endpoint
• Company Search: Typeahead fetches from :company-search route