From 5197cbebf1b2ae915a5b9aa49958b917510edf68 Mon Sep 17 00:00:00 2001
From: lorentz <lorentz@wulfconsulting.com>
Date: Fri, 10 Jul 2026 22:41:20 -0400
Subject: [PATCH] feat(12-01): add Pax8Invoice/Pax8InvoiceItem types

- Replace stale unused Pax8Order/Pax8OrderItem stubs with live-verified
  Pax8Invoice (header) and Pax8InvoiceItem (per-company line item) types
- Field shapes sourced from 12-RESEARCH.md live PAX8 API verification
---
 lib/types/pax8.ts | 43 ++++++++++++++++++++++++++++++++-----------
 1 file changed, 32 insertions(+), 11 deletions(-)

diff --git a/lib/types/pax8.ts b/lib/types/pax8.ts
index ca6c9de..f626ce6 100644
--- a/lib/types/pax8.ts
+++ b/lib/types/pax8.ts
@@ -62,28 +62,49 @@ export interface Pax8Product {
   // NOTE: the deprecated alternate-vendor-SKU field per PAX8's own schema is intentionally omitted.
 }
 
-// Modeled on PAX8's Invoice object (not the bare Order object, which lacks
-// pricing/status) — see 10-RESEARCH.md Pitfall 1.
-export interface Pax8Order {
+// Live-verified against PAX8's real /invoices response (12-RESEARCH.md
+// Pitfall 2) — the header is the partner's consolidated monthly bill.
+export interface Pax8Invoice {
   id: string;
-  companyId: string;
-  orderDate: string | null;
+  // Always null on the header for this single-tenant reseller account —
+  // per-company data lives on each invoice item (Pax8InvoiceItem), not here.
+  companyId: string | null;
+  invoiceDate: string | null;
   total: number | null;
   status: string | null;
   currencyCode: string | null;
   [key: string]: unknown; // escape hatch for fields not yet modeled
 }
 
-// Modeled on PAX8's Invoice Item object (not the bare LineItem object,
-// which lacks pricing) — see 10-RESEARCH.md Pitfall 1.
-export interface Pax8OrderItem {
+// Live-verified against PAX8's real /invoices response (12-RESEARCH.md
+// Pitfall 2) — the line item carries the actual per-company, per-period cost.
+export interface Pax8InvoiceItem {
   id: string;
-  orderId: string;
-  productId: string;
-  quantity: number;
+  type: string | null;
+  externalId: string | null;
+  companyId: string | null;
+  forCompanyId: string | null;
+  companyName: string | null;
+  startPeriod: string | null;
+  endPeriod: string | null;
+  quantity: number | null;
+  unitOfMeasure: string | null;
+  term: string | null;
+  sku: string | null;
+  description: string | null;
+  rateType: string | null;
+  chargeType: string | null;
   price: number | null;
   subTotal: number | null;
+  cost: number | null;
+  costTotal: number | null;
+  total: number | null;
+  amountDue: number | null;
+  productId: string | null;
+  productName: string | null;
+  vendorName: string | null;
   currencyCode: string | null;
+  subscriptionId: string | null;
   [key: string]: unknown; // escape hatch for fields not yet modeled
 }