Warranties Module

Relevant source files

The following files were used as context for generating this wiki page:

• src/app/(app)/products/page.tsx
• src/app/(app)/products/[id]/page.tsx
• src/components/ProductListClient.tsx
• PRODUCT.md
• GLOSSARY.md
• src/lib/chat/tools.ts
• ios-shell/www/app.js

The Warranties module manages household purchase coverage and end-of-life dates for physical assets. It provides a system to track manufacturer details, purchase history, and document evidence such as receipts and policy certificates. Unlike optional modules in Hearth, Warranties are an "always-on" core feature that surfaces upcoming expiration dates to prevent the loss of coverage.

Sources: PRODUCT.md:20-22, GLOSSARY.md:12-14

Core Concepts and Data Model

A Warranty represents the coverage an item has against faults. In the system, these are often referred to as "Products." A warranty is considered Lapsed once its end date passes. Warranties are distinct from Contracts; recurring billed coverage is treated as a Contract, while one-time purchase coverage is a Warranty.

Sources: GLOSSARY.md:12-20

Data Structure

Warranties track specific hardware and purchase metadata. The following table summarizes the primary fields used in the Product (Warranty) model:

Field	Description	Type
description	Short name of the item (e.g., "65-inch QLED TV")	String
manufacturer	The brand or company that made the item	String
model	Specific model name or number	String
vendor	The retailer where the item was purchased	String
serialNumber	Unique hardware identifier for the specific unit	String
barcode	Product UPC or EAN code	String
purchaseDate	The date the item was acquired	ISO Date
warrantyEndDate	The date the coverage expires	ISO Date
price	The amount paid for the item	Number
currency	3-letter currency code (e.g., AUD, USD)	String
reminderDaysBefore	Thresholds for notifications (default: "30,14,7,1")	String

Sources: src/lib/chat/tools.ts:327-340, ios-shell/www/app.js:106-125

Relationships

The Warranties module integrates with other household modules through specific foreign key relationships:

• Properties: A warranty can be linked to a specific property (e.g., a built-in appliance).
• Inventory: An inventory item can register its warranty against a Product record. The Inventory module provides a warrantyProductId field for this link.
• Documents: Multiple files (PDFs, images) can be attached to a single warranty record.

Sources: src/app/(app)/products/[id]/page.tsx:162-185, ios-shell/www/app.js:200-210, GLOSSARY.md:66-68

Lifecycle and States

Warranties follow a specific lifecycle from creation to expiration, governed by "Due" policies and extraction statuses.

Needs Review and Extraction

When a warranty is created via document upload, it enters a Needs Review state if fields were auto-filled by the AI/heuristic extraction pipeline. Reminders are held until a user reviews and saves the record, which constitutes confirmation.

Sources: GLOSSARY.md:112-115, ios-shell/www/app.js:633-636

Expiry and "Due" Logic

A warranty becomes Due when its end date is within the "due-soon window" (determined by the largest configured reminder threshold).

• Due Soon: Active coverage nearing expiration.
• Lapsed: A warranty whose end date has passed. Lapsed warranties are no longer considered "Due" and do not trigger reminders.

Sources: GLOSSARY.md:17-20, GLOSSARY.md:137-145

List Management and Filtering

The ProductListClient component handles the display and filtering of warranties. It utilizes a set of "chips" and search parameters to narrow the household-wide collection.

Filter Types

The system provides several standard filters for maintenance:

• Due soon: Coverage ending shortly.
• Lapsed: Coverage that has ended.
• Needs review: Records auto-filled but not yet confirmed.
• Missing key details: Records lacking an end date or both serial/barcode identifiers.
• Important: Records with starred documents.

Sources: src/components/ProductListClient.tsx:21-30, ios-shell/www/app.js:849-856

Search Capabilities

The search function queries across multiple fields simultaneously, including description, manufacturer, model, vendor, serialNumber, and barcode.

Sources: src/app/(app)/products/page.tsx:64-71, src/components/ProductListClient.tsx:109-115

Mobile and Standalone Implementation

Hearth includes a mobile shell that supports a Standalone Mode. In this mode, warranty data is stored in an encrypted native SQLite database on the device rather than a remote server.

Standalone Storage Schema

The mobile shell uses a specific SQL schema to mirror the server-side Prisma model.

CREATE TABLE IF NOT EXISTS products (
  id TEXT PRIMARY KEY,
  description TEXT NOT NULL,
  manufacturer TEXT,
  model TEXT,
  vendor TEXT,
  serial_number TEXT,
  barcode TEXT,
  purchase_date TEXT,
  warranty_end_date TEXT,
  price REAL,
  currency TEXT NOT NULL DEFAULT 'AUD',
  notes TEXT,
  reminder_days_before TEXT DEFAULT '30,14,7,1',
  extraction_pending INTEGER NOT NULL DEFAULT 0,
  extraction_confirmed_at TEXT,
  property_id TEXT,
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  deleted_at TEXT,
  version INTEGER NOT NULL DEFAULT 1
);

Sources: ios-shell/www/app.js:106-125

Local Reminders

In standalone mode, reminders are scheduled locally using the LocalNotifications plugin instead of the server's cron scheduler. The shell calculates notification dates based on the warranty_end_date and reminder_days_before thresholds.

Sources: ios-shell/www/app.js:770-800, ios-shell/www/app.js:933-958

AI Assistant Integration

The module provides tools for the Hearth AI Assistant to query and propose changes to warranty data. These tools are "guarded," meaning the AI validates input against Zod schemas but cannot write directly to the database without user confirmation.

Tool Name	Purpose
list_products	Returns a list of products filtered by a query string.
propose_create_product	Validates fields for a new warranty and returns a proposal for user approval.
propose_update_product	Validates changes to an existing warranty record.

Sources: src/lib/chat/tools.ts:251-260, src/lib/chat/tools.ts:400-440

The Warranties module serves as a critical component of the Hearth household system by centralizing purchase documentation and automating the monitoring of coverage expiration. Through its integration with the document extraction pipeline and the AI assistant, it reduces the friction of data entry while ensuring household assets remain protected.