Add TCO (total cost of ownership) reporting

api/internal/app/app.go

@@ -191,6 +191,17 @@ func App(
 	tenantApp.Get("/documents/download", documentsCtrl.DownloadDocument)
 	tenantApp.Delete("/documents/:id", documentsCtrl.DeleteDocument)
 
+	// Total cost of ownership reporting (operating costs from Glovebox
+	// documents + optional acquisition/depreciation settings per vehicle).
+	tcoSvc := service.NewTCOService(logger, pdb, fetchAPI, authProvider, vehicleSvc, attestSvc)
+	tcoCtrl := controllers.NewTCOController(logger, tcoSvc, vehicleSvc)
+	tenantApp.Get("/tco/settings", tcoCtrl.GetSettings)
+	tenantApp.Put("/tco/settings", tcoCtrl.PutSettings)
+	tenantApp.Get("/tco/summary", tcoCtrl.GetSummary)
+	tenantApp.Get("/tco/vehicle/:tokenId", tcoCtrl.GetVehicleDetail)
+	tenantApp.Get("/tco/export.csv", tcoCtrl.ExportCSV)
+	tenantApp.Put("/tco/vehicle/:tokenId/backfill/:documentId", tcoCtrl.BackfillAmount)
+
 	return app
 }
 

api/internal/controllers/documents.go

@@ -5,7 +5,6 @@ import (
 	"crypto/sha256"
 	"encoding/base64"
 	"encoding/hex"
-	"encoding/json"
 	"fmt"
 	"io"
 	"strconv"
@@ -223,28 +222,7 @@ func (d *DocumentsController) ListDocuments(c *fiber.Ctx) error {
 	}
 
 	// Build tombstoned-id set so we hide deleted docs.
-	tombstoned := map[string]struct{}{}
-	for _, e := range entries {
-		if e.Type != "dimo.tombstone" {
-			continue
-		}
-		// data: {voidsId, rawReferenceId?} — attest API renamed referenceId→voidsId;
-		// parse both so existing tombstones stored under the old name still work.
-		var d struct {
-			VoidsID        string `json:"voidsId"`
-			ReferenceID    string `json:"referenceId"`
-			RawReferenceID string `json:"rawReferenceId"`
-		}
-		_ = jsonUnmarshal(e.Data, &d)
-		if d.VoidsID != "" {
-			tombstoned[d.VoidsID] = struct{}{}
-		} else if d.ReferenceID != "" {
-			tombstoned[d.ReferenceID] = struct{}{}
-		}
-		if d.RawReferenceID != "" {
-			tombstoned[d.RawReferenceID] = struct{}{}
-		}
-	}
+	tombstoned := gateway.TombstonedIDs(entries)
 
 	// rawByHash: filehash -> raw ID, so we can include raw IDs alongside parsed
 	// (for delete path; download uses filehash directly).
@@ -366,14 +344,6 @@ func (d *DocumentsController) DeleteDocument(c *fiber.Ctx) error {
 	return c.JSON(result)
 }
 
-// jsonUnmarshal is a tiny wrapper that no-ops on nil input.
-func jsonUnmarshal(raw []byte, dst interface{}) error {
-	if len(raw) == 0 {
-		return nil
-	}
-	return json.Unmarshal(raw, dst)
-}
-
 func isAllowedMime(m string) bool {
 	switch m {
 	case "application/pdf", "image/jpeg", "image/png":

api/internal/controllers/tco.go

@@ -0,0 +1,206 @@
+// api/internal/controllers/tco.go
+package controllers
+
+import (
+	"fmt"
+	"strconv"
+
+	"github.com/DIMO-Network/fleet-lite-app/internal/service"
+	"github.com/gofiber/fiber/v2"
+	"github.com/rs/zerolog"
+)
+
+type TCOController struct {
+	logger     *zerolog.Logger
+	tcoSvc     *service.TCOService
+	vehicleSvc *service.VehicleService
+}
+
+func NewTCOController(logger *zerolog.Logger, tcoSvc *service.TCOService, vehicleSvc *service.VehicleService) *TCOController {
+	return &TCOController{logger: logger, tcoSvc: tcoSvc, vehicleSvc: vehicleSvc}
+}
+
+// vehicleInTenant reports whether the tokenID is one of the tenant's synced
+// vehicles — and, for limited members, inside their allowed groups.
+func (t *TCOController) vehicleInTenant(c *fiber.Ctx, tenantID string, tokenID int64) bool {
+	allowed, _ := GetAllowedGroups(c)
+	_, err := t.vehicleSvc.GetVehicle(c.Context(), tenantID, tokenID, allowed)
+	return err == nil
+}
+
+// GetSettings — GET /tco/settings?tokenId=N.
+func (t *TCOController) GetSettings(c *fiber.Ctx) error {
+	tenant, err := GetTenant(c)
+	if err != nil {
+		return fiber.NewError(fiber.StatusBadRequest, err.Error())
+	}
+	tokenID, err := strconv.ParseInt(c.Query("tokenId"), 10, 64)
+	if err != nil || tokenID == 0 {
+		return fiber.NewError(fiber.StatusBadRequest, "valid tokenId query param required")
+	}
+	if !t.vehicleInTenant(c, tenant.ID, tokenID) {
+		return fiber.NewError(fiber.StatusForbidden, "vehicle is not part of this tenant")
+	}
+	settings, err := t.tcoSvc.GetSettings(c.Context(), tenant.ID, tokenID)
+	if err != nil {
+		return fiber.NewError(fiber.StatusInternalServerError, "get tco settings: "+err.Error())
+	}
+	return c.JSON(settings)
+}
+
+// PutSettingsRequest is the body for PUT /tco/settings.
+type PutSettingsRequest struct {
+	TokenID         int64    `json:"tokenId"`
+	PurchasePrice   *float64 `json:"purchasePrice"`
+	PurchaseDate    *string  `json:"purchaseDate"`
+	UsefulLifeYears *int     `json:"usefulLifeYears"`
+	Currency        string   `json:"currency"`
+}
+
+// PutSettings — PUT /tco/settings.
+func (t *TCOController) PutSettings(c *fiber.Ctx) error {
+	tenant, err := GetTenant(c)
+	if err != nil {
+		return fiber.NewError(fiber.StatusBadRequest, err.Error())
+	}
+	var req PutSettingsRequest
+	if err := c.BodyParser(&req); err != nil {
+		return fiber.NewError(fiber.StatusBadRequest, "invalid request body: "+err.Error())
+	}
+	if req.TokenID == 0 {
+		return fiber.NewError(fiber.StatusBadRequest, "tokenId is required")
+	}
+	if !t.vehicleInTenant(c, tenant.ID, req.TokenID) {
+		return fiber.NewError(fiber.StatusForbidden, "vehicle is not part of this tenant")
+	}
+	currency := req.Currency
+	if currency == "" {
+		currency = "USD"
+	}
+	settings := service.TCOSettings{
+		VehicleTokenID:  req.TokenID,
+		PurchasePrice:   req.PurchasePrice,
+		PurchaseDate:    req.PurchaseDate,
+		UsefulLifeYears: req.UsefulLifeYears,
+		Currency:        currency,
+	}
+	if err := t.tcoSvc.UpsertSettings(c.Context(), tenant.ID, req.TokenID, settings); err != nil {
+		return fiber.NewError(fiber.StatusInternalServerError, "save tco settings: "+err.Error())
+	}
+	return c.JSON(settings)
+}
+
+// GetSummary — GET /tco/summary. Fleet-wide rollup.
+func (t *TCOController) GetSummary(c *fiber.Ctx) error {
+	tenant, err := GetTenant(c)
+	if err != nil {
+		return fiber.NewError(fiber.StatusBadRequest, err.Error())
+	}
+	allowed, _ := GetAllowedGroups(c)
+	summary, err := t.tcoSvc.FleetSummary(c.Context(), tenant, allowed)
+	if err != nil {
+		return fiber.NewError(fiber.StatusInternalServerError, "tco summary: "+err.Error())
+	}
+	return c.JSON(summary)
+}
+
+// GetVehicleDetail — GET /tco/vehicle/:tokenId.
+func (t *TCOController) GetVehicleDetail(c *fiber.Ctx) error {
+	tenant, err := GetTenant(c)
+	if err != nil {
+		return fiber.NewError(fiber.StatusBadRequest, err.Error())
+	}
+	tokenID, err := strconv.ParseInt(c.Params("tokenId"), 10, 64)
+	if err != nil || tokenID == 0 {
+		return fiber.NewError(fiber.StatusBadRequest, "valid tokenId path param required")
+	}
+	if !t.vehicleInTenant(c, tenant.ID, tokenID) {
+		return fiber.NewError(fiber.StatusForbidden, "vehicle is not part of this tenant")
+	}
+	allowed, _ := GetAllowedGroups(c)
+	summary, err := t.tcoSvc.VehicleSummary(c.Context(), tenant, tokenID, allowed)
+	if err != nil {
+		return fiber.NewError(fiber.StatusInternalServerError, "tco vehicle summary: "+err.Error())
+	}
+	return c.JSON(summary)
+}
+
+// BackfillAmountRequest is the body for PUT /tco/vehicle/:tokenId/backfill/:documentId.
+type BackfillAmountRequest struct {
+	Amount   float64 `json:"amount"`
+	Currency string  `json:"currency"`
+}
+
+// BackfillAmount — PUT /tco/vehicle/:tokenId/backfill/:documentId. Attaches a
+// dollar amount to a document that was uploaded without one, via a
+// cost-amendment CE (the original document is immutable and untouched).
+func (t *TCOController) BackfillAmount(c *fiber.Ctx) error {
+	tenant, err := GetTenant(c)
+	if err != nil {
+		return fiber.NewError(fiber.StatusBadRequest, err.Error())
+	}
+	tokenID, err := strconv.ParseInt(c.Params("tokenId"), 10, 64)
+	if err != nil || tokenID == 0 {
+		return fiber.NewError(fiber.StatusBadRequest, "valid tokenId path param required")
+	}
+	documentID := c.Params("documentId")
+	if documentID == "" {
+		return fiber.NewError(fiber.StatusBadRequest, "documentId path param required")
+	}
+	if !t.vehicleInTenant(c, tenant.ID, tokenID) {
+		return fiber.NewError(fiber.StatusForbidden, "vehicle is not part of this tenant")
+	}
+	var req BackfillAmountRequest
+	if err := c.BodyParser(&req); err != nil {
+		return fiber.NewError(fiber.StatusBadRequest, "invalid request body: "+err.Error())
+	}
+	if req.Amount <= 0 {
+		return fiber.NewError(fiber.StatusBadRequest, "amount must be greater than 0")
+	}
+	currency := req.Currency
+	if currency == "" {
+		currency = "USD"
+	}
+	amendmentID, err := t.tcoSvc.BackfillAmount(tenant, tokenID, documentID, req.Amount, currency)
+	if err != nil {
+		return fiber.NewError(fiber.StatusBadGateway, "backfill amount: "+err.Error())
+	}
+	return c.JSON(fiber.Map{"id": amendmentID})
+}
+
+// ExportCSV — GET /tco/export.csv (optionally ?tokenId=N for a single vehicle).
+func (t *TCOController) ExportCSV(c *fiber.Ctx) error {
+	tenant, err := GetTenant(c)
+	if err != nil {
+		return fiber.NewError(fiber.StatusBadRequest, err.Error())
+	}
+	var summaries []service.VehicleTCOSummary
+	filename := "tco-export.csv"
+	if q := c.Query("tokenId"); q != "" {
+		tokenID, err := strconv.ParseInt(q, 10, 64)
+		if err != nil || tokenID == 0 {
+			return fiber.NewError(fiber.StatusBadRequest, "invalid tokenId")
+		}
+		if !t.vehicleInTenant(c, tenant.ID, tokenID) {
+			return fiber.NewError(fiber.StatusForbidden, "vehicle is not part of this tenant")
+		}
+		allowed, _ := GetAllowedGroups(c)
+		summary, err := t.tcoSvc.VehicleSummary(c.Context(), tenant, tokenID, allowed)
+		if err != nil {
+			return fiber.NewError(fiber.StatusInternalServerError, "tco vehicle summary: "+err.Error())
+		}
+		summaries = []service.VehicleTCOSummary{*summary}
+		filename = fmt.Sprintf("tco-vehicle-%d.csv", tokenID)
+	} else {
+		allowed, _ := GetAllowedGroups(c)
+		fleet, err := t.tcoSvc.FleetSummary(c.Context(), tenant, allowed)
+		if err != nil {
+			return fiber.NewError(fiber.StatusInternalServerError, "tco summary: "+err.Error())
+		}
+		summaries = fleet.Vehicles
+	}
+	csvText := service.BuildCSV(summaries)
+	c.Set(fiber.HeaderContentType, "text/csv")
+	c.Set(fiber.HeaderContentDisposition, fmt.Sprintf(`attachment; filename="%s"`, filename))
+	return c.SendString(csvText)
+}

api/internal/db/migrations/20260710120000_vehicle_tco_settings.sql

@@ -0,0 +1,32 @@
+-- +goose Up
+-- +goose StatementBegin
+SELECT 'up SQL query';
+
+-- Optional per-vehicle acquisition/depreciation inputs for the TCO report.
+-- Scoped by tenant like vehicle_favorites. All purchase fields are nullable —
+-- a vehicle with no row (or nulls) just shows operating costs, no
+-- acquisition/depreciation line. See
+-- docs/superpowers/specs/2026-07-06-tco-reporting-design.md.
+CREATE TABLE IF NOT EXISTS vehicle_tco_settings (
+    tenant_id         UUID NOT NULL REFERENCES tenants (id) ON DELETE CASCADE,
+    token_id          BIGINT NOT NULL,
+    purchase_price    NUMERIC,
+    purchase_date     DATE,
+    useful_life_years INTEGER,
+    currency          TEXT NOT NULL DEFAULT 'USD',
+    created_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (tenant_id, token_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_vehicle_tco_settings_tenant_id ON vehicle_tco_settings (tenant_id);
+
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+SELECT 'down SQL query';
+
+DROP TABLE IF EXISTS vehicle_tco_settings;
+
+-- +goose StatementEnd